fix: preserve task worktree identity on inventory refresh (#2980)

This commit is contained in:
Carlos Florêncio
2026-08-24 13:53:31 +00:00
committed by GitHub
parent 832734bb67
commit b69d2d9ca0
4 changed files with 309 additions and 6 deletions
@@ -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)
}
}
@@ -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
}
@@ -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.
@@ -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.