kandev/docs/plans/executor-transition-workspace-validation/plan.md

spec, created, status

spec	created	status
docs/specs/tasks/system-design/additional-session-workspace-reuse.md	2026-08-29	in_progress

Implementation Plan: Executor Transition Workspace Validation

Overview

Make executor transitions select a workspace owned by the requested executor and fail closed before execution creation when a repo-backed workspace is missing, non-Git, path-mismatched, or not backed by complete canonical inventory. Preserve existing tasks and all filesystem evidence.

Confirmed root cause

• reuseExistingEnvironment returns early when env.ExecutorType differs from req.ExecutorType, so old runtime handles are not copied.
• That return does not change the durable environment/session selection or invalidate the old workspace_path.
• ensureWorkspaceExecutionLocked later accepts any non-empty WorkspaceInfo.WorkspacePath and creates an execution without proving a repo-backed path is the selected Git checkout.
• The observed v0.92.1 runtime consequently skipped worktree-environment reuse, created a local execution at the removed legacy task path, and launched the agent with has_worktree=false.

Invariants

• Keep the existing task, repository, session history, and canonical repository.
• Do not delete, move, reset, clean, checkout, or rewrite the stale path.
• Do not use a session path or cached change projection as workspace authority.
• Do not start an agent until the selected environment passes admission.
• Do not add a second workspace ledger or database table.

Implementation waves

1. task-01-fail-closed-stale-workspace — implementation and focused verification pass; isolated runtime rebind remains

Verification

cd apps/backend && go test ./internal/orchestrator/executor -run 'Test.*Executor.*Mismatch|Test.*Workspace.*Reuse|Test.*Executor.*Transition'
cd apps/backend && go test ./internal/agent/runtime/lifecycle -run 'Test.*Workspace.*Execution|Test.*Workspace.*Ready'
python3 scripts/lint-spec-files.py --all

Risks

• Treating every missing path as an executor transition could break legitimate first materialization; validation must be tied to repo-backed selected environments and launch phase.
• Host Git inspection is not valid for remote executors; their existing executor-owned inventory remains the authority.
• A defense-in-depth lifecycle guard must not convert repository-less tasks or quick chats into false failures.

Implementation receipt

Implemented locally on 2026-08-29. The patch clears stale session workspace authority on executor transition, rebinds the single durable environment only after a successful target-executor launch, removes stale backend-specific runtime/worktree projections, and validates repo-backed host paths before both launch preparation and cold execution creation.

Passing verification:

• Full internal/orchestrator/executor package.
• Focused lifecycle local-preparer, workspace-admission, and workspace-execution tests.
• Focused task-service workspace-info tests.
• Backend make build, including macOS and Linux agentctl binaries and Kandev.
• Full specification lint and git diff --check.

The full lifecycle package retains four failures reproduced unchanged on the clean v0.92.1 base: three stale-worktree error-classification expectations on the external-volume layout and one macOS Unix-socket path-length failure. They are not introduced by this implementation. Runtime rebind against an isolated data/config root remains required before this plan can be marked complete.