202 lines
9.0 KiB
Markdown
202 lines
9.0 KiB
Markdown
---
|
|
created: 2026-09-09
|
|
status: done
|
|
requirements:
|
|
- REQ-TASKS-RUNTIME-CLEANUP-001
|
|
system_design:
|
|
- ../../specs/tasks/system-design/runtime-cleanup.md
|
|
- ../../specs/tasks/system-design/runtime-cleanup-preparation.md
|
|
legacy_specs: []
|
|
---
|
|
|
|
# Implementation Plan: Missing Worktree Cleanup Preparation
|
|
|
|
## Overview
|
|
|
|
[Issue #3531](https://github.com/kdlbs/kandev/issues/3531) reports blocked task
|
|
archive and deletion after external worktree removal. The issue is assigned to
|
|
`carlosflorencio`.
|
|
|
|
One sequential work order corrects preparation and proves the complete task
|
|
lifecycle. The implementation and validation are complete. The investigation used revision
|
|
`ecd3efc01b819615e1eb3219d774dfb0e3a44cfd`.
|
|
|
|
The [preparation design](../../specs/tasks/system-design/runtime-cleanup-preparation.md)
|
|
defines the missing-resource boundary. The task system owns cleanup preparation and
|
|
the durable resource snapshot. Workspace ownership and deletion safeguards
|
|
remain governed by the existing design and ADRs.
|
|
|
|
## Confirmed root cause
|
|
|
|
`CaptureCleanupHeadOIDs` already checks the worktree path with `os.Stat`.
|
|
For an absent directory, it resolves `refs/heads/<branch>^{commit}` from the
|
|
parent repository. If the branch is also absent, Git exits 128.
|
|
`captureWorktreeCleanupHeadOIDs` propagates the error through
|
|
`PrepareTaskResourceCleanupWithOptions` before task mutation.
|
|
|
|
Preparation reserves a `prepared` cleanup job before identity capture. The
|
|
capture error prevents replacement of its placeholder snapshot. This explains
|
|
the reported `prepared` jobs with zero worker attempts.
|
|
|
|
The current failure does not require Git to run inside the missing directory.
|
|
The fallback branch lookup alone reproduces the reported error.
|
|
|
|
## Reproduction evidence
|
|
|
|
A temporary test used the real task service, SQLite repository, worktree
|
|
manager, and disposable Git repositories. It created an active worktree row,
|
|
removed the checkout through Git, and retained the database inventory.
|
|
|
|
Command, from `apps/backend`:
|
|
|
|
```bash
|
|
rtk go test -tags fts5 ./internal/task/service -run '^TestRepro3531_PrepareMissingWorktree$' -count=1 -v
|
|
```
|
|
|
|
- `branch_present` passed preparation after directory removal.
|
|
- `branch_absent` failed after removal of the local branch as well.
|
|
- The failure contained `capture worktree cleanup identities` and `exit status 128`.
|
|
- A second diagnostic proved that `CleanupWorktrees` already accepts the fully
|
|
absent resource without a captured commit identity.
|
|
|
|
A separate Git probe established these results on Git 2.47.3:
|
|
|
|
| Probe result | Exit | Combined output |
|
|
| --- | --- | --- |
|
|
| Exact branch present | 0 | Ref name, object ID, and `commit` |
|
|
| Exact branch absent | 0 | Empty |
|
|
| Broken ref | 0 | Warning text |
|
|
| Ref points to missing object | 128 | Fatal diagnostic |
|
|
|
|
The probe used `for-each-ref` with
|
|
`--format=%(refname)%00%(objectname)%00%(objecttype)` and the full branch ref.
|
|
Its four diagnostic cases passed. A quiet `show-ref --verify` probe returned
|
|
the same exit code for a missing ref and a broken ref, so it is unsuitable here.
|
|
|
|
Temporary tests and their fixture data were removed after diagnosis. No user
|
|
instance or database was modified. The permanent regression must first fail
|
|
against unchanged production code during implementation.
|
|
|
|
## Scope
|
|
|
|
### In scope
|
|
|
|
- Preparation for absent worktrees with either surviving or absent branches.
|
|
- Complete snapshots for tasks with healthy and absent repository worktrees.
|
|
- Direct and cascade archive/delete through the real services and cleanup worker.
|
|
- Error classification and existing ownership, branch, and path safeguards.
|
|
|
|
### Out of scope
|
|
|
|
- Recreating missing worktrees or recovering externally deleted commits.
|
|
- Automatic database repair, schema changes, or removal of historical jobs.
|
|
- Relaxing cleanup audits or treating generic Git errors as absence.
|
|
- New UI controls, translations, runtime flags, or executor behavior.
|
|
|
|
## Technical approach
|
|
|
|
The correction belongs in
|
|
`apps/backend/internal/worktree/manager_cleanup.go:CaptureCleanupHeadOIDs`,
|
|
with strict ref and object-ID parsing in the adjacent
|
|
`manager_cleanup_capture.go` helper file.
|
|
Use the existing `cleanupPathPresent` classification for physical paths.
|
|
Keep existing handling for incomplete legacy inventory metadata.
|
|
|
|
For absent paths with a recorded branch, use a bounded exact-ref probe through
|
|
`runBoundedGitInspect`. The structured `for-each-ref` form above supports old
|
|
Git versions without the newer `show-ref --exists` option.
|
|
Git patterns can include descendant refs. Compare the returned full ref name
|
|
exactly, as specified in the [Git documentation](https://git-scm.com/docs/git-for-each-ref).
|
|
|
|
Parse only complete records with a nonempty object ID and object type `commit`.
|
|
Reject unexpected output, including warnings on stderr combined by the runner.
|
|
A successful response without the exact ref establishes absence.
|
|
An exact branch result supplies its immutable commit identity.
|
|
An absent branch omits only its identity-map entry and emits a bounded warning
|
|
with the task/worktree IDs and the absence reason.
|
|
|
|
At execution, snapshot worktrees use the identity-aware batch cleanup path. The
|
|
task-environment teardown path skips those same worktree IDs so its legacy
|
|
ID-only destroyer cannot adopt a checkout that reappeared after preparation.
|
|
The worker keeps such a replacement retryable when no immutable identity is
|
|
available.
|
|
|
|
Do not use `Manager.branchExists` to establish absence in preparation.
|
|
That helper currently maps generic command failures to `false` outside timeout
|
|
handling. Changing its wider behavior is outside this repair.
|
|
|
|
Keep the full `Worktrees` snapshot and the existing service error propagation.
|
|
`manager_cleanup_audit.go` remains the authority for destructive worker actions.
|
|
No early row deletion, broad Git prune, or new cleanup status is required.
|
|
|
|
Related decisions:
|
|
|
|
- [Fail-closed cleanup](../../decisions/0009-fail-closed-gc-semantics.md).
|
|
- [Task-owned worktree lifetime](../../decisions/2026-08-08-task-owned-worktree-lifetime.md).
|
|
|
|
This repair applies those boundaries without a new architectural decision.
|
|
|
|
## Tests
|
|
|
|
| Acceptance criteria | Permanent evidence |
|
|
| --- | --- |
|
|
| .9, .13 | `manager_cleanup_capture_test.go`: `TestCaptureCleanupHeadOIDs_MissingWorktree` |
|
|
| .9, .12 | `manager_cleanup_capture_test.go`: `TestCaptureCleanupHeadOIDs_FailsClosed` |
|
|
| .6, .13 | `resource_cleanup_missing_worktree_test.go`: `TestPrepareTaskResourceCleanup_MissingWorktree` |
|
|
| .6, .7, .9, .13 | Same file: `TestTaskLifecycleCleanup_MissingWorktree` |
|
|
| .9, .13 | Same file: `TestTaskLifecycleCleanup_MissingWorktree_ReplacementBranchStaysRetryable` |
|
|
|
|
All criterion suffixes refer to `AC-TASKS-RUNTIME-CLEANUP-001`.
|
|
The work order defines the case matrix, worker assertions, and exact commands.
|
|
New test files avoid the existing oversized `resource_cleanup_jobs_test.go`.
|
|
|
|
## E2E tests
|
|
|
|
The backend integration matrix reproduces the missing-resource defect through
|
|
real lifecycle services and durable cleanup. Existing browser flows provide
|
|
end-to-end evidence for unchanged controls:
|
|
|
|
- `tests/kanban/card-menu-delete-archive.spec.ts`, project `chromium`: archive
|
|
and delete remove the card. Maps to .13 with the backend matrix.
|
|
- `tests/task/mobile-archive-task-redirect.spec.ts`, project `mobile-chrome`:
|
|
cascade archive preserves usable navigation. Maps to .13 with the backend matrix.
|
|
|
|
These browser tests are smoke coverage, not independent reproductions of the
|
|
missing-worktree state. No new layout or touch behavior requires a mobile design.
|
|
|
|
## Work orders
|
|
|
|
- [done] [Task 01: Recover cleanup preparation for absent worktrees](task-01-recover-preparation.md)
|
|
|
|
## Verification results
|
|
|
|
Diagnosis: real service reproduction failed as expected, with the surviving-branch
|
|
control passing. Existing execution accepted the fully absent resource.
|
|
The structured-ref diagnostic passed all four cases.
|
|
|
|
Design validation passed: `lint-spec-files.py --all`, all 30 specification-linter
|
|
tests, and `git diff --check`.
|
|
|
|
Implementation and its regression/E2E checks are complete. The manager capture
|
|
matrix and lifecycle regressions pass in normal and race-enabled runs. The
|
|
existing browser smoke flows pass with 5 Chromium tests and 1 mobile-Chromium
|
|
test. The changed-code Go lint reports 0 issues; the specification linter and
|
|
diff check also pass.
|
|
|
|
## Documentation impact
|
|
|
|
Internal requirements and design describe the preparation contract explicitly.
|
|
Public docs need no change during this design turn. The repair adds no operator
|
|
action or public interface, and restores the existing cleanup intent.
|
|
|
|
## Risks
|
|
|
|
- Treating a warning or generic Git failure as absence can hide damaged metadata.
|
|
- Dropping the worktree snapshot entry can lose registration and row cleanup.
|
|
- A directory or branch can reappear between preparation and execution.
|
|
Existing worker identity audits must remain active.
|
|
- Stale registrations without verifiable identity remain retryable by design.
|
|
- Historical prepared-job reconciliation remains unchanged.
|
|
- The WSL host was not reproduced. The same failure reproduced on Linux through
|
|
the platform-independent Go/Git path.
|