Fix worktree graveyard lifecycle

[TraderSamwise]

Summary

• preserve attached agent/service topology when graveyarding worktrees
• delete graveyarded checkouts directly instead of routing through active worktree listing
• block resurrection when the physical checkout is missing and document topology/git authority

Verification

• yarn vitest run src/multiplexer/persistence-methods.test.ts src/multiplexer/worktree-graveyard.test.ts src/runtime-core/topology-worktrees.test.ts src/multiplexer/dashboard-model.test.ts src/multiplexer/runtime-state.test.ts src/debug-state.test.ts src/metadata-server.test.ts app/lib/api.test.ts
• yarn typecheck
• yarn lint
• yarn build
• pre-push: yarn typecheck && yarn lint && yarn test

Summary by CodeRabbit

• Documentation

  • Clarified worktree graveyard behavior and lifecycle management requirements
  • Updated guidance on worktree resurrection and deletion procedures

• Bug Fixes

  • Enhanced validation to ensure checkout paths exist before resurrecting graveyarded worktrees
  • Improved service state cleanup during graveyard operations
  • Fixed graveyard cleanup to properly remove physical worktrees before clearing topology records

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e1651f38-612e-487b-9ab4-6a8c1a52de00

📥 Commits

Reviewing files that changed from the base of the PR and between 2a34f47 and 26e5629.

📒 Files selected for processing (8)

• docs/runtime-authority-dead-paths.md
• docs/runtime-core-hard-cut-roadmap.md
• docs/runtime-projection-contract.md
• src/debug-state.ts
• src/multiplexer/persistence-methods.test.ts
• src/multiplexer/persistence-methods.ts
• src/multiplexer/worktree-graveyard.test.ts
• src/multiplexer/worktree-graveyard.ts

---

📝 Walkthrough

Walkthrough

This PR integrates topology-aware state management into worktree graveyarding, resurrection, and deletion. Services are now persisted as "stopped" during graveyarding, resurrection validates checkout existence, and deletion removes physical git worktrees before clearing topology records. Documentation and tests are updated to reflect these changes.

Changes

Worktree Graveyarding Topology Integration

Layer / File(s)	Summary
Authority Documentation and Debug State docs/runtime-authority-dead-paths.md, docs/runtime-core-hard-cut-roadmap.md, docs/runtime-projection-contract.md, src/debug-state.ts	Documentation is updated to clarify that worktree lifecycle and graveyard visibility are managed by topology records, that resurrection requires existing checkouts, and that deletion must physically remove the git worktree via git worktree remove --force before clearing topology dependents. Debug state note for worktreeGraveyard is updated to reflect topology-gated resurrection.
Graveyard Entry Enrichment with Topology Session/Service Data src/multiplexer/worktree-graveyard.ts, src/multiplexer/worktree-graveyard.test.ts	listWorktreeGraveyardEntries() now populates agents and services fields by filtering topology session and service records by the graveyarded worktree path. New test verifies that graveyard listings include attached session and service entries with their ids and worktree paths.
Service Lifecycle Persistence during Graveyarding src/multiplexer/persistence-methods.ts	graveyardDesktopWorktree replaces detach/remove logic with stopWorktreeServicesForGraveyard, which kills service tmux windows, persists each service as stopped in topology via upsertTopologyService, and repopulates host.offlineServices instead of removing topology records.
Resurrection Validation and Deletion with Physical Git Worktree Handling src/multiplexer/persistence-methods.ts	resurrectGraveyardWorktree now validates the checkout path exists and throws if missing. deleteGraveyardWorktree blocks deletion of the main checkout and uses new removeGraveyardedDesktopWorktree / removeGitWorktreeCheckout helpers to physically remove the git worktree via git worktree remove --force before clearing topology dependents; non-existent checkouts are handled with state persistence.
Test Coverage for Graveyarding, Resurrection, and Deletion src/multiplexer/persistence-methods.test.ts	Tests verify topology session/service state transitions (offline/stopped status) during graveyarding, that services are stopped without deleting topology records, that resurrection fails when checkout is missing, that deletion properly handles git worktree removal failures, and that graveyarded worktrees are deleted with topology cleanup and service invalidation. New createSpawnChild() helper standardizes mocked subprocess EventEmitter behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• TraderSamwise/aimux#34: The src/debug-state.ts change updates the worktreeGraveyard debug-state source role descriptor introduced by PR #34; the debug-state authority and projection labeling are directly shared.
• TraderSamwise/aimux#32: The main PR's graveyard enrichment, resurrection, and deletion behavior changes in src/multiplexer/persistence-methods.ts and src/multiplexer/worktree-graveyard.ts directly extend the topology wiring for service and worktree lifecycle handling introduced in PR #32.

Poem

🐰 A worktree sleeps in the graveyard deep,
Its services stopped, their state we keep,
When resurrection calls and the path's still near,
We wake it up, loud and clear!
But if it's gone, we heed the call—
Remove the git, and clean it all. 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Fix worktree graveyard lifecycle' directly aligns with the PR's main objective to fix worktree graveyard behavior, addressing lifecycle preservation, deletion flow, and resurrection guards.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch phase/codex-runtime-next

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}