Skip to content

Hard cut services and worktrees to runtime topology#32

Merged
TraderSamwise merged 10 commits into
masterfrom
phase/service-worktree-hard-cut
May 26, 2026
Merged

Hard cut services and worktrees to runtime topology#32
TraderSamwise merged 10 commits into
masterfrom
phase/service-worktree-hard-cut

Conversation

@TraderSamwise

@TraderSamwise TraderSamwise commented May 26, 2026

Copy link
Copy Markdown
Owner

Summary

  • add runtime topology helpers for service and worktree lifecycle state
  • wire service lifecycle, worktree lifecycle, graveyard resurrect/delete, and CLI worktree surfaces through topology/project service paths
  • remove legacy worktree graveyard JSON authority and purge dependent topology sessions/services during worktree cleanup

Verification

  • yarn verify
  • yarn build
  • push hook verify: 85 files / 616 tests

Summary by CodeRabbit

  • New Features

    • Resurrect and delete archived worktrees via the metadata API; worktree listing prefers live daemon responses with a filtered local fallback.
    • Worktree create falls back to persisted topology and returns created path when offline.
  • Refactor

    • Graveyard and service state now drive worktree/service visibility from a shared runtime topology.
    • Service lifecycle and persistence moved into the topology layer; live-or-local endpoint resolution improved.
  • Tests

    • Expanded tests covering worktree lifecycle, graveyard actions, service state, and topology behaviors.

Review Change Stack

@coderabbitai

coderabbitai Bot commented May 26, 2026

Copy link
Copy Markdown

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: 4ab6c16e-017b-4f54-a70d-ad7e79b8b2df

📥 Commits

Reviewing files that changed from the base of the PR and between 2236e27 and 9baa888.

📒 Files selected for processing (1)
  • src/main.ts

📝 Walkthrough

Walkthrough

Migrates worktree graveyard and service lifecycle to a runtime topology store, adding topology worktree/service modules, preserving service node/binding state, and wiring topology-backed APIs into persistence, metadata-server, multiplexer services, CLI, and debug reporting.

Changes

Worktree and Service Lifecycle Management via Runtime Topology

Layer / File(s) Summary
Runtime Topology Worktree Types and Lifecycle
src/runtime-core/topology-worktrees.ts, src/runtime-core/topology-worktrees.test.ts
New types and APIs for worktree state/graveyard (upsert, move-to-graveyard, soft-delete, resurrect, remove) with tests validating lifecycle transitions.
Runtime Topology Service Types and Lifecycle
src/runtime-core/topology-services.ts, src/runtime-core/topology-services.test.ts
Adds RuntimeTopologyServiceState, conversions, and APIs to list/upsert/remove services and remove services by worktree; tests cover service lifecycle and node/binding management.
Session and Binding Preservation for Services
src/runtime-core/topology-sessions.ts, src/runtime-core/topology-sessions.test.ts
Preserves service-linked nodes/bindings when saving sessions and adds removeTopologySessionsForWorktree to remove sessions and related bindings/nodes/lifecycle ops.
Topology Store Graveyard Normalization
src/runtime-core/topology-store.ts, src/runtime-core/topology-store.test.ts
Relaxes graveyard pruning to retain entries by rigId only so graveyard rows referencing missing worktrees are kept.
Multiplexer Persistence: Worktree and Service Lifecycle
src/multiplexer/persistence-methods.ts, src/multiplexer/persistence-methods.test.ts, src/multiplexer/dashboard-model.ts
Implements topology-backed graveyard/resurrect/delete flows, detaches services, persists lifecycle transitions, updates create/remove to upsert topology states, and refreshes projections/metadata.
Multiplexer Service Lifecycle Integration
src/multiplexer/services.ts, src/multiplexer/runtime-state.ts, src/multiplexer/runtime-state.test.ts, src/multiplexer/services.test.ts
Converts between local ServiceState and topology shapes; persists create/stop/resume/remove via upsertTopologyService/removeTopologyService; loadOfflineServices prefers topology-sourced stopped/offline services; tests assert topology state.
Worktree Graveyard Source Migration to Topology
src/multiplexer/worktree-graveyard.ts, src/paths.ts
listWorktreeGraveyardEntries/Paths now source from topology functions; removed worktreeGraveyardPath and getWorktreeGraveyardPath() from public paths API.
Metadata Server Graveyard and Service Endpoints
src/metadata-server.ts, src/metadata-server.test.ts
Adds optional desktop.resurrectGraveyardWorktree handler and delegates graveyard POST endpoints to desktop handlers with 501 fallback; tests exercise resurrect/delete endpoints.
CLI Worktree Commands with Live Endpoints
src/main.ts
Refactors live-or-local helpers to early-fallback on endpoint resolution failures; adds listVisibleLocalWorktrees filtering out graveyard paths; prefers live /worktrees and /worktrees/create with local topology fallback that upserts created worktrees.
Debug State Extensions for Topology Services and Worktrees
src/debug-state.ts, src/debug-state.test.ts
Extends DebugStateReport.runtimeTopology to include services and worktrees; filterRuntimeTopology emits match entries for services/worktrees; buildDebugStateReport reads raw runtimeTopology for graveyard entries; tests updated and makePaths adds runtimeExchangePath.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

  • TraderSamwise/aimux#30: Adds runtime-exchange integration and expanded runtime-topology schema that this PR consumes for debug-state and topology exchange paths.
  • TraderSamwise/aimux#28: Earlier work replacing graveyard stubs; overlaps with implemented persistence-backed graveyard/resurrect/delete flows.
  • TraderSamwise/aimux#5: Related changes to debug-state target-resolution and reporting overlaps.

"🐰 From topology burrows I hop,
Graveyards mend and services stop—
Upserts hum and bindings play,
Worktrees wake to a brighter day,
I nibble bugs and bounce away."

🚥 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 'Hard cut services and worktrees to runtime topology' accurately and concisely describes the main objective of the changeset: migrating service and worktree lifecycle management to runtime topology instead of legacy JSON-based storage.
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/service-worktree-hard-cut

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/main.ts`:
- Around line 1600-1603: The calls to ensureDaemonProjectReady are preventing
the getLiveProjectServiceJsonOrLocal fallback from running for worktree
commands; modify the three spots (the call sites around prepareProjectContext →
ensureDaemonProjectReady → getLiveProjectServiceJsonOrLocal) so that
getLiveProjectServiceJsonOrLocal is invoked without preemptive
ensureDaemonProjectReady (or only call ensureDaemonProjectReady after checking
the live-vs-local result), specifically update the invocation sequences that
involve prepareProjectContext, ensureDaemonProjectReady, and
getLiveProjectServiceJsonOrLocal used by the worktree, worktree list, and
worktree create flows so the local-path fallback can execute when the daemon is
not ready.

In `@src/multiplexer/persistence-methods.ts`:
- Around line 747-753: The code currently sets the topology worktree state to
"removing" via upsertTopologyWorktree({path, name: path.split("/").pop() ??
path}, "removing") before running validations, which can leave stale "removing"
state if validation throws; move the upsertTopologyWorktree(...) call so it runs
only after all validation guards succeed, or wrap the validation+removal
sequence in a try/catch and on any failure call upsertTopologyWorktree(...) to
revert the state (e.g., clear or set back to the previous status) to ensure no
stale "removing" remains; apply the same change for the other occurrences of
upsertTopologyWorktree in the surrounding removal logic (the other similar call
sites mentioned).

In `@src/multiplexer/worktree-graveyard.ts`:
- Line 19: Replace the POSIX-only split call used to derive worktree names with
Node's cross-platform path basename: change the assignment of name (currently
"entry.name ?? entry.path.split(\"/\").pop() ?? entry.path") to use
path.basename(entry.path) (e.g., "entry.name ?? path.basename(entry.path) ??
entry.path"), and add the proper import for the path module (import path from
'path' or const path = require('path')) so entry.path is handled correctly on
Windows and POSIX.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 90efe6bd-523d-419e-90e9-b7d90756b7b5

📥 Commits

Reviewing files that changed from the base of the PR and between 92610b2 and cb4e547.

📒 Files selected for processing (22)
  • src/debug-state.test.ts
  • src/debug-state.ts
  • src/main.ts
  • src/metadata-server.test.ts
  • src/metadata-server.ts
  • src/multiplexer/dashboard-model.ts
  • src/multiplexer/persistence-methods.test.ts
  • src/multiplexer/persistence-methods.ts
  • src/multiplexer/runtime-state.test.ts
  • src/multiplexer/runtime-state.ts
  • src/multiplexer/services.test.ts
  • src/multiplexer/services.ts
  • src/multiplexer/worktree-graveyard.ts
  • src/paths.ts
  • src/runtime-core/topology-services.test.ts
  • src/runtime-core/topology-services.ts
  • src/runtime-core/topology-sessions.test.ts
  • src/runtime-core/topology-sessions.ts
  • src/runtime-core/topology-store.test.ts
  • src/runtime-core/topology-store.ts
  • src/runtime-core/topology-worktrees.test.ts
  • src/runtime-core/topology-worktrees.ts
💤 Files with no reviewable changes (1)
  • src/paths.ts

Comment thread src/main.ts
Comment thread src/multiplexer/persistence-methods.ts Outdated
Comment thread src/multiplexer/worktree-graveyard.ts Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/main.ts`:
- Around line 1599-1603: The fallback helper ensureDaemonProjectReadyForFallback
currently swallows all errors; update its catch to rethrow
ProjectServiceVersionError so it isn't suppressed: replace the empty catch with
catch (err) { if (err instanceof ProjectServiceVersionError) throw err; /*
otherwise ignore/allow fallback */ } and ensure ProjectServiceVersionError is
imported where ensureDaemonProjectReadyForFallback is defined so the instanceof
check works against the correct class.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9edf4669-88a6-419e-8d55-614ea76b88e1

📥 Commits

Reviewing files that changed from the base of the PR and between cb4e547 and 2236e27.

📒 Files selected for processing (3)
  • src/main.ts
  • src/multiplexer/persistence-methods.ts
  • src/multiplexer/worktree-graveyard.ts

Comment thread src/main.ts
@TraderSamwise
TraderSamwise merged commit a47e2d5 into master May 26, 2026
1 check passed
@TraderSamwise
TraderSamwise deleted the phase/service-worktree-hard-cut branch May 26, 2026 04:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant