WaleWangPW
81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
---
|
|
spec: docs/specs/tasks/system-design/additional-session-workspace-reuse.md
|
|
created: 2026-08-29
|
|
status: 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](task-01-fail-closed-stale-workspace.md) — implementation and focused verification pass; isolated runtime rebind remains
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
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.
|