diff --git a/apps/backend/internal/orchestrator/executor/executor_environment_repo_persistence_test.go b/apps/backend/internal/orchestrator/executor/executor_environment_repo_persistence_test.go new file mode 100644 index 0000000000..0fe0501e06 --- /dev/null +++ b/apps/backend/internal/orchestrator/executor/executor_environment_repo_persistence_test.go @@ -0,0 +1,48 @@ +package executor + +import ( + "context" + "testing" + + "github.com/kandev/kandev/internal/task/models" +) + +// @covers AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.1 +// @covers AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.2 +// @covers AC-TASKS-RUNTIME-CLEANUP-001.2 +func TestPersistTaskEnvironmentRepos_PreservesPhysicalWorktreeOnInventoryOnlyRefresh(t *testing.T) { + repo := newMockRepository() + exec := newTestExecutor(t, &mockAgentManager{}, repo) + const envID = "env-inventory-only" + repo.taskEnvironmentRepos[envID] = []*models.TaskEnvironmentRepo{ + { + ID: "env-inventory-only-repo-main", + TaskEnvironmentID: envID, + RepositoryID: "repo-kandev", + BranchSlug: "main", + WorktreeID: "wt-existing", + WorktreePath: "/tasks/task-1/repo", + WorktreeBranch: "feature/task-1", + Position: 4, + ErrorMessage: "stale inventory error", + }, + } + + repos := environmentReposForLaunch( + &LaunchAgentRequest{ + RepositoryID: "repo-kandev", + RepositoryPath: "/source/kandev", + BranchIdentitySlug: "main", + }, + &LaunchAgentResponse{WorkspacePath: "/source/kandev"}, + ) + exec.persistTaskEnvironmentRepos(context.Background(), envID, repos) + + row := repo.taskEnvironmentRepos[envID][0] + if row.WorktreeID != "wt-existing" || row.WorktreePath != "/tasks/task-1/repo" || row.WorktreeBranch != "feature/task-1" { + t.Fatalf("inventory-only refresh changed physical worktree: %+v", row) + } + if row.Position != 0 || row.ErrorMessage != "" { + t.Fatalf("inventory-only refresh did not update inventory metadata: position=%d error=%q", row.Position, row.ErrorMessage) + } +} diff --git a/apps/backend/internal/orchestrator/executor/executor_execute.go b/apps/backend/internal/orchestrator/executor/executor_execute.go index bd1a933e85..6a4dcfb1f3 100644 --- a/apps/backend/internal/orchestrator/executor/executor_execute.go +++ b/apps/backend/internal/orchestrator/executor/executor_execute.go @@ -2468,9 +2468,13 @@ func (e *Executor) refreshTaskEnvironmentRepo(ctx context.Context, row, w *model return } row.BranchSlug = w.BranchSlug - row.WorktreeID = w.WorktreeID - row.WorktreePath = w.WorktreePath - row.WorktreeBranch = w.WorktreeBranch + // Concrete launch results populate the physical tuple together; inventory-only + // rows have no WorktreeID and must not replace it. + if w.WorktreeID != "" { + row.WorktreeID = w.WorktreeID + row.WorktreePath = w.WorktreePath + row.WorktreeBranch = w.WorktreeBranch + } row.Position = position row.ErrorMessage = w.ErrorMessage if err := e.repo.UpdateTaskEnvironmentRepo(ctx, row); err != nil { @@ -2484,9 +2488,10 @@ func (e *Executor) refreshTaskEnvironmentRepo(ctx context.Context, row, w *model func taskEnvironmentRepoNeedsRefresh(row, w *models.TaskEnvironmentRepo, position int) bool { return row.BranchSlug != w.BranchSlug || - row.WorktreeID != w.WorktreeID || - row.WorktreePath != w.WorktreePath || - row.WorktreeBranch != w.WorktreeBranch || + (w.WorktreeID != "" && + (row.WorktreeID != w.WorktreeID || + row.WorktreePath != w.WorktreePath || + row.WorktreeBranch != w.WorktreeBranch)) || row.Position != position || row.ErrorMessage != w.ErrorMessage } diff --git a/docs/plans/preserve-task-worktree-inventory/plan.md b/docs/plans/preserve-task-worktree-inventory/plan.md new file mode 100644 index 0000000000..edad8a7d84 --- /dev/null +++ b/docs/plans/preserve-task-worktree-inventory/plan.md @@ -0,0 +1,147 @@ +--- +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. diff --git a/docs/plans/preserve-task-worktree-inventory/task-01-preserve-physical-worktree-identity.md b/docs/plans/preserve-task-worktree-inventory/task-01-preserve-physical-worktree-identity.md new file mode 100644 index 0000000000..4cec5249dd --- /dev/null +++ b/docs/plans/preserve-task-worktree-inventory/task-01-preserve-physical-worktree-identity.md @@ -0,0 +1,103 @@ +--- +id: "01-preserve-physical-worktree-identity" +title: "Preserve physical worktree identity" +status: done +wave: 1 +depends_on: [] +plan: "plan.md" +requirements: + - REQ-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001 + - REQ-TASKS-RUNTIME-CLEANUP-001 +acceptance_criteria: + - AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.1 + - AC-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001.2 + - AC-TASKS-RUNTIME-CLEANUP-001.2 +system_design: + - ../../specs/tasks/system-design/runtime-cleanup.md +--- + +# Task 01: Preserve Physical Worktree Identity + +## Summary + +Make repository-inventory persistence merge-aware: an inventory-only launch +update must preserve the task environment's concrete worktree tuple, while a +new concrete worktree result must still replace stale values. Prove the repair +with a failing executor regression test before changing production code. + +## In scope + +- Add + `TestPersistTaskEnvironmentRepos_PreservesPhysicalWorktreeOnInventoryOnlyRefresh` + in a dedicated executor persistence test file because the existing test files + already exceed the backend's effective test-file lint limit. +- Change the existing-row merge and refresh predicate in + `executor_execute.go` so a missing incoming `WorktreeID` cannot clear a valid + physical worktree tuple. +- Preserve existing concrete-refresh and legacy-flat-row migration behavior. +- Run the downstream workspace-info projection test. + +## Out of scope + +- Frontend or WebSocket changes. +- Database schema changes or migrations. +- Automatic repair of already-empty canonical rows. +- Live-instance database mutation. +- PR comparison-target changes. + +## Acceptance + +- An inventory-only projection for an existing repository/branch row leaves its + `worktree_id`, `worktree_path`, and `worktree_branch` unchanged. +- A projection with a concrete non-empty `WorktreeID` continues to replace all + three physical worktree fields. +- Workspace-info recovery continues to project a retained canonical worktree + path for the session after the persistence update. + +## Verification + +```bash +cd apps/backend && go test ./internal/orchestrator/executor -run 'TestPersistTaskEnvironmentRepos_(PreservesPhysicalWorktreeOnInventoryOnlyRefresh|RefreshesExistingRows|MigratesLegacyFlatRowToBranchIdentity)$' +cd apps/backend && go test ./internal/task/service -run '^TestGetWorkspaceInfoForSession_ProjectsPersistedWorktreeIdentity$' +cd apps/backend && go test ./internal/orchestrator/executor ./internal/task/service +``` + +The first command must fail on the new preservation assertion before production +code changes and pass afterward. + +## Files likely touched + +- `apps/backend/internal/orchestrator/executor/executor_execute.go` +- `apps/backend/internal/orchestrator/executor/executor_environment_repo_persistence_test.go` +- `docs/plans/preserve-task-worktree-inventory/plan.md` +- `docs/plans/preserve-task-worktree-inventory/task-01-preserve-physical-worktree-identity.md` + +## Dependencies + +None. + +## Risks + +- The merge must use concrete worktree identity, not path presence alone, so + remote inventory rows cannot be misclassified as physical worktrees. + +## Parallelism + +`sequential` + +## Inputs + +- `REQ-TASKS-ADDITIONAL-SESSION-WORKSPACE-REUSE-001`, especially AC `.1` and + `.2`. +- `REQ-TASKS-RUNTIME-CLEANUP-001`, especially AC `.2`. +- `docs/specs/tasks/system-design/runtime-cleanup.md`, section + `task_environments and task_environment_repos`. +- `docs/decisions/2026-08-08-task-owned-worktree-lifetime.md`. +- Existing concrete-refresh tests in `executor_multi_repo_test.go`. + +## Results + +Implemented and verified. The regression failed before the production change, +then passed after inventory-only rows stopped replacing the physical worktree +tuple. The concrete-refresh and legacy-flat-row tests, the downstream +workspace-info projection test, and both full executor/service packages pass.