Files
kandev/docs/specs/tasks/requirements/additional-session-workspace-reuse.md
T
2026-09-04 13:49:06 +00:00

7.9 KiB

status, system, created, updated, owners
status system created updated owners
draft tasks 2026-08-19 2026-08-30
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.

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.