kandev/docs/specs/tasks/requirements/additional-session-workspace-reuse.md

status, system, created, updated, owners

status	system	created	updated	owners
active	tasks	2026-08-19	2026-09-22	kandev

Additional Session Workspace Reuse Requirements

Overview

Additional sessions must use the task's existing workspace. They must not materialize a second worktree or change the files that the first session owns.

Requirements

REQ-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001: Additional Session Workspace Reuse

Intent: Let additional sessions attach to a validated task workspace while preserving independent session runtime state.

Acceptance criteria

• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.1: An additional session shall attach only to a ready canonical environment with a complete, validated repository inventory.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.2: Attach-only preparation shall not create, recreate, clone, fetch, pull, checkout, reset, or otherwise modify the shared workspace.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.3: Each attached session shall receive independent execution identity and runtime state.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.4: Unsafe or unsupported reuse shall fail with a typed, recoverable API error without creating a session or replacement workspace.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.5: Desktop and mobile workspace views shall show one current Git status for sessions that share a task environment. A response from a non-canonical workspace or an older observation shall not replace that status.

REQ-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-002: Canonical Workspace Identity Continuity

Intent: Keep the task's effective workspace identity stable when Kandev reconstructs or resumes its runtime.

Acceptance criteria

• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-002.1: When Kandev recovers or resumes a task with a ready canonical environment, the persisted and projected workspace path shall remain the materialized workspace used by the recovered runtime.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-002.2: When the task reloads after recovery, Files and later attached sessions shall resolve the same canonical workspace; the repository's source checkout shall not replace it.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-002.3: When no materialized or recovered runtime workspace exists, a legacy repository-backed session can continue to use its source checkout as a compatibility fallback.

REQ-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-003: Executor Transition Workspace Validation

Intent: Prevent a session launched with a different executor type from starting in a stale workspace retained by the previous executor.

Acceptance criteria

• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-003.1: When the requested executor type differs from the canonical task environment executor type, the launch shall not reuse that environment's workspace path, repository inventory, execution identity, or runtime handles.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-003.2: A repo-backed launch may become ready only after its selected environment has a complete canonical repository inventory and every selected local workspace path resolves to the expected Git repository checkout.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-003.3: A missing, non-Git, path-mismatched, or executor-mismatched workspace shall fail before agent process startup with a typed, recoverable error; it shall not expose the invalid workspace as ready or as the task's current change projection.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-003.4: Rejecting an invalid workspace shall not delete, move, reset, clean, checkout, or otherwise modify the stale path, the canonical repository, or either environment inventory.

REQ-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-004: Concurrent Session Workspace Visibility

Intent: Keep sanctioned concurrent writing on a shared task workspace observable, without introducing a task-wide writer lock.

User story: As an operator, I want Kandev to record when an agent starts in a task workspace that another session is already working in, so that I can recognize a shared-workspace conflict instead of discovering it later as corrupted files.

Acceptance criteria

• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-004.1: When a launch or a resume starts an agent process for a session whose task already holds another session in a working state, the system shall record that co-residency before the agent process starts.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-004.2: A co-residency record shall be an operational counter and a structured log entry only. It shall not refuse, defer, delay, or otherwise change the admission outcome.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-004.3: When the sibling session read fails, the system shall record a skipped observation with its reason rather than reporting an absence of co-residency.
• AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-004.4: Recorded labels shall be a closed set of admission site and skip reason. No task, session, workspace path, branch, or repository identifier shall be a label value.

Migrated source detail

Why

An additional session belongs to an existing task workspace. Treating it as a new worktree materialization can collide with the branch already checked out by the task and can hide or modify uncommitted work from the new agent.

What

• task_environments owns the workspace. task_environment_repos is the sole physical worktree inventory; sessions only reference task_environment_id.
• The first eligible launch may materialize a workspace. Every later session attaches to the ready canonical environment and its exact repository/branch inventory.
• Attach-only preparation does not create, recreate, clone, fetch, pull, checkout, reset, run repository setup, configure contribution state, or copy files. It preserves both tracked and untracked working-tree changes.
• Multiple agents may write the shared workspace concurrently. This does not imply a task-wide writer lock or a filesystem read-only capability.
• A session name, review state, or reviewer profile does not grant a special filesystem mode. Workspace-only restore/view may attach without launching an additional mutating agent.

Workspace state matrix

Mode	Canonical environment	Result
new_workspace	none	Elect one initial materializer.
new_workspace	creating	Return recoverable workspace_preparing; do not create a session or workspace.
new_workspace	ready and complete	Attach with reuse_required.
inherit_parent	parent/group ready and complete	Attach to that environment.
inherit_parent	missing or unsafe	Return a reuse error; never create a child environment.
shared_group	none	Atomically elect one group materializer.
shared_group	creating	Return recoverable workspace_preparing.
shared_group	ready and complete	Attach to the group environment.

An executor-type transition is not an attach. It must select or materialize an environment owned by the requested executor before a session can start. A persisted session or environment workspace path from the previous executor is diagnostic evidence only and is never a fallback launch directory.

An incomplete, failed, deleted, path-mismatched, branch-mismatched, or duplicate repository slot is workspace_reuse_unsafe. An executor that cannot create an independent session runtime against the validated environment returns workspace_reuse_unsupported.

Executor boundary

The environment contributes only stable workspace handles. A new session always gets independent execution identity: agentctl/process and ACP state for host execution; agentctl instance for Docker; session directory, PID, port and forward for SSH; and corresponding per-session runtime state for Sprites. Sibling PreviousExecutionID data is never a workspace identity.

API failure contract

spawn_session_kandev maps typed workspace state errors to CONFLICT with a stable reason, recoverable boolean, and bounded retry guidance. It never includes a path, branch, secret, token, or executor credential in those details. Its successful response shape and profile precedence do not change; an optional session name remains best effort after a successful launch.

Scenarios

• A named or unnamed additional session sees the same uncommitted tracked and untracked files as the task's first session.
• A late status response from a sibling session does not clear or replace the current task-environment status in desktop or mobile workspace views.
• Git worktree inventory, HEAD, index, branch and status remain unchanged by an additional launch.
• A terminal primary or zero-session task can reuse its retained ready environment.
• A preparing or unsafe environment fails before lifecycle preparation and does not silently repair or replace the workspace.
• Every current repository/branch slot must have exactly one active canonical row before an attach-only launch begins.

Out of scope

• Preventing concurrent agents from editing the same file.
• A trusted filesystem read-only agent mode.
• Automatic workspace repair, reset, branch switching, or replacement during session spawn.
• Reconstructing a missing physical worktree from filesystem guesses.