fix: preserve task worktree identity on inventory refresh (#2980)
This commit is contained in:
+48
@@ -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.
|
||||
+103
@@ -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.
|
||||
Reference in New Issue
Block a user