Files
kandev/docs/plans/preserve-task-worktree-inventory/plan.md
T

148 lines
6.4 KiB
Markdown

---
created: 2026-08-24
status: done
requirements:
- REQ-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001
- REQ-TASKS-RUNTIME-CLEANUP-001
system_design:
- ../../specs/tasks/system-design/runtime-cleanup.md
legacy_specs: []
---
# Implementation Plan: Preserve Task Worktree Inventory
## Overview
Prevent an inventory-only launch projection from erasing the canonical physical
worktree identity stored in `task_environment_repos`. The repair starts with a
focused executor regression test, then changes the existing-row merge so only a
concrete worktree result can replace physical worktree fields. This preserves
restart recovery and the Changes panel's branch-diff source without changing any
HTTP, WebSocket, or frontend contract.
The confirmed live-instance failure is:
1. A workspace-only execution reuses the task's correct worktree.
2. Agent promotion returns repository inventory without a concrete
`WorktreeID`.
3. `persistTaskEnvironmentRepos` matches the canonical row by repository and
branch identity.
4. `refreshTaskEnvironmentRepo` copies blank `worktree_id`, `worktree_path`, and
`worktree_branch` fields over the existing physical identity.
5. After restart, workspace recovery cannot resolve `session.Worktrees`, falls
back to the seed repository, and reports an empty diff even though the linked
PR worktree remains intact.
This violates
`AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.1`,
`AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.2`, and the accepted ownership
rule in
[ADR-2026-08-08-task-owned-worktree-lifetime](../../decisions/2026-08-08-task-owned-worktree-lifetime.md):
`task_environment_repos` is the sole physical-worktree source of truth and only
task lifecycle operations may remove that identity.
## Scope
### In scope
- Preserve a valid canonical worktree ID, path, and branch when a launch update
carries repository inventory but no concrete physical worktree.
- Continue replacing stale physical fields when a successful launch carries a
non-empty concrete `WorktreeID`.
- Add focused regression coverage for both preservation and concrete refresh.
- Run the existing workspace-info projection test that proves restart recovery
reads the persisted worktree identity.
### Out of scope
- Frontend rendering or Changes-panel state changes.
- New database columns, migrations, compatibility readers, or automatic
filesystem discovery.
- Automatic repair of rows already corrupted by the regression. The accepted
ownership ADR requires missing or ambiguous inventory to fail closed rather
than silently select or create another physical owner; live-data repair needs
a separately authorized, exact operational action.
- PR association or comparison-target behavior; its `no_match` result is a
downstream symptom of the lost workspace identity.
## Technical approach
### Existing-row merge
Update `refreshTaskEnvironmentRepo` and its refresh predicate in
`apps/backend/internal/orchestrator/executor/executor_execute.go` so an incoming
row without `WorktreeID` is treated as inventory-only. Such a row may update
non-physical inventory metadata such as position and error state, but it cannot
clear or replace an existing physical worktree tuple.
When the incoming row contains `WorktreeID`, retain the current concrete-refresh
behavior and update `worktree_id`, `worktree_path`, and `worktree_branch`
together. Explicit cleanup and environment-reset paths remain the only owners
that remove physical identity.
### Regression boundary
Add the regression in the dedicated
`apps/backend/internal/orchestrator/executor/executor_environment_repo_persistence_test.go`
file because the existing persistence test files already exceed the backend's
effective test-file lint limit. Seed an active canonical row with a concrete
worktree, pass the inventory-only shape produced by `environmentReposForLaunch`,
and assert the stored physical tuple is unchanged. Keep the existing
concrete-refresh test green to prove the repair does not freeze stale worktree
data.
Use the existing
`TestGetWorkspaceInfoForSession_ProjectsPersistedWorktreeIdentity` service test
as downstream recovery evidence: when the canonical row remains intact,
workspace recovery selects the task worktree instead of the repository snapshot.
## Tests
- `AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.1`: a canonical repository
row remains complete after an inventory-only promotion update.
- `AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.2`: promotion does not replace
or rematerialize the existing physical workspace.
- `AC-TASKS-RUNTIME-CLEANUP-001.2`: a non-lifecycle session operation does not
discard the task-owned worktree identity.
The new test is
`TestPersistTaskEnvironmentRepos_PreservesPhysicalWorktreeOnInventoryOnlyRefresh`
in `executor_environment_repo_persistence_test.go`. It failed before the
correction because the current merge blanked all three physical fields.
## E2E tests
No new Playwright test is planned. The UI consumes the backend's live git-status
projection and did not fail in the captured frontend diagnostics. The defect is
the durable backend worktree tuple, and the focused persistence plus workspace
projection tests exercise the boundary that determines the Changes source after
restart.
## Work orders
- [x] [Task 01: Preserve physical worktree identity](task-01-preserve-physical-worktree-identity.md)
## Verification results
- RED confirmed with the new regression before the production change: the
inventory-only refresh cleared the stored physical worktree tuple.
- `go test ./internal/orchestrator/executor -run
'TestPersistTaskEnvironmentRepos_(PreservesPhysicalWorktreeOnInventoryOnlyRefresh|RefreshesExistingRows|MigratesLegacyFlatRowToBranchIdentity)$'`
passed.
- `go test ./internal/task/service -run
'^TestGetWorkspaceInfoForSession_ProjectsPersistedWorktreeIdentity$'` passed.
- `go test ./internal/orchestrator/executor ./internal/task/service` passed
(1,710 tests across both packages).
## Risks
- Treating every blank incoming field as destructive would reproduce the bug;
`WorktreeID` must remain the discriminator between inventory-only and concrete
physical updates.
- Preserving fields must not block a later successful recreate from replacing a
stale worktree tuple; the existing concrete-refresh regression remains part of
the required check.
- Already-corrupted environments remain unsafe until explicitly repaired or
reset. This package prevents further corruption but does not guess ownership
from filesystem state.