Hard cut agent lifecycle to topology

[TraderSamwise]

Summary

• route agent spawn/stop/kill/resurrection through the topology-backed lifecycle adapter
• preserve graveyard/offline topology state across runtime shutdown and resume reconciliation
• fail closed when a non-owner runtime tries to mutate a live topology agent
• add GUI graveyard resurrection support

Verification

• yarn verify
• yarn build
• yarn --cwd app typecheck
• yarn --cwd app eslint 'app/(main)/(tabs)/(dashboard)/graveyard.tsx' lib/api.ts

Note: full app lint still has unrelated existing prettier/hook warnings in other app files.

Summary by CodeRabbit

• New Features
  • Resurrect graveyard agents to offline status from the dashboard (UI button) and via CLI commands.
• Chores
  • Improved session lifecycle reconciliation and daemon-first service calls with local fallbacks to support resurrection flows.
• Documentation
  • Updated roadmap notes about lifecycle routing and resurrection behavior.
• Tests
  • Added/updated tests covering resurrection, lifecycle reconciliation, and dashboard behaviors.

[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: fc4c720a-18a5-45be-885a-c8ee9f066530

📥 Commits

Reviewing files that changed from the base of the PR and between 709eefd and d8359fe.

📒 Files selected for processing (1)

• src/main.ts

---

📝 Walkthrough

Walkthrough

Implements end-to-end graveyard resurrection: frontend button + API client, MetadataServer HTTP handlers, multiplexer lifecycle implementations, persistence resurrection into offline topology, session-exit preservation, session reconciliation before resume/restore, and CLI remote-first wiring.

Changes

Graveyard Resurrection Feature

Layer / File(s)	Summary
Frontend Graveyard Resurrection UI & API app/app/(main)/(tabs)/(dashboard)/graveyard.tsx, app/lib/api.ts	Endpoint-keyed graveyardState, guarded listing fetch, resurrect(entry) flow with busy/error handling and desktop refresh; resurrectGraveyardAgent POSTs to /graveyard/resurrect.
Metadata Server HTTP Endpoints src/metadata-server.ts, src/metadata-server.test.ts	Implements /graveyard/resurrect and /agents/teammates/resurrect: validate input, check desktop.resurrectGraveyard, call resurrection, trigger onChange, return 200 payloads; tests updated to expect success/failure semantics.
Multiplexer Dashboard Tail Methods & Tests src/multiplexer/dashboard-tail-methods.ts, src/multiplexer/dashboard-tail-methods.test.ts	Replaces disabled stubs with concrete lifecycle methods (spawn/fork/createTeammate/stopAgent/sendAgentToGraveyard/migrate/rename), topology-state transitions, offline cache handling, runtime kills, ownership checks, and comprehensive tests.
Persistence Resurrection & Session Launch src/multiplexer/persistence-methods.ts, src/multiplexer/persistence-methods.test.ts, src/multiplexer/session-launch.ts, src/multiplexer/session-launch.test.ts	Implements resurrection via resurrectTopologySession, upserts restored session into offlineSessions with status: "offline", triggers refresh hooks, and reconciles topology before resume/restore; tests updated/added.
Session Exit Handling & Graveyard Preservation src/multiplexer/session-runtime-core.ts, src/multiplexer/session-runtime-core.test.ts	Adds graveyardAfterStop tracking to avoid re-adding graveyarded live sessions to offline cache on exit and clears marker sets during cleanup.
Supporting Contracts & Wiring src/dashboard/session-actions.ts, src/multiplexer/dashboard-ops.ts, src/multiplexer/agent-io-methods.ts, src/multiplexer/archives.ts, src/multiplexer/dashboard-model.ts, docs/runtime-core-hard-cut-roadmap.md	Allows async stopSessionToOffline, wires stop-to-offline to host.stopAgent, delegates interruptAgent to runtime-core implementation, calls remote resurrect in dashboard mode for archives, adds reconcile helper and lifecycle resurrectGraveyard handler, and updates roadmap note.
CLI Remote-First Operations src/main.ts	aimux stop/kill/graveyard send/resurrect now prefer daemon HTTP endpoints (postLiveProjectServiceJsonOrLocal) while falling back to local Multiplexer implementations.

Sequence Diagram

sequenceDiagram
  participant UI as GraveyardScreen
  participant Client as resurrectGraveyardAgent
  participant Server as MetadataServer
  participant Multiplexer as dashboardTailMethods
  participant Persistence as resurrectTopologySession
  UI->>Client: POST /graveyard/resurrect {sessionId}
  Client->>Server: forward request
  Server->>Multiplexer: host.resurrectGraveyardSession(sessionId)
  Multiplexer->>Persistence: resurrectTopologySession(sessionId)
  Persistence-->>Multiplexer: {sessionId,status:"offline"}
  Multiplexer->>Server: notify change
  Server->>Client: 200 {ok:true, sessionId, status:"offline"}
  Client->>UI: success -> update UI, kickDesktopStateRefresh

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• TraderSamwise/aimux#28: Directly related to re-enabling /graveyard/resurrect and removing prior hard-disable behavior.

🐰 From graveyard dust a tiny hop,

I press the button — sessions stop to drop;
A POST, a server, threads reconnect,
Topology hums, the dashboard shows respect;
A rabbit cheers: restored and whole again.

🚥 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 agent lifecycle to topology' accurately describes the main objective of this pull request: routing agent lifecycle operations (spawn, stop, kill, resurrection) through a topology-backed lifecycle adapter rather than the previous runtime-core approach.
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/agent-lifecycle-hard-cut

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

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

[coderabbitai]

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 2461-2464: The command is calling
Multiplexer.resurrectGraveyardSession(...) directly (via prepareProjectContext
and new Multiplexer()) instead of using the daemon/ project service call path
used by sibling lifecycle commands; update the graveyard resurrect flow to call
the project service API (the same daemon-ready project service helper used
elsewhere) and only fall back to local Multiplexer.resurrectGraveyardSession
when the service is unavailable, preserving existing behavior for opts.json
output and the identical case at the other occurrence around
resurrectGraveyardSession at the later location; locate usages of
prepareProjectContext, Multiplexer, and resurrectGraveyardSession to implement
the service-first, local-fallback routing.

🪄 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: e726d820-18ff-4b2a-b65b-4a9a5cc298d3

📥 Commits

Reviewing files that changed from the base of the PR and between af56595 and 709eefd.

📒 Files selected for processing (21)

• app/app/(main)/(tabs)/(dashboard)/graveyard.tsx
• app/lib/api.ts
• docs/runtime-core-hard-cut-roadmap.md
• src/dashboard/session-actions.ts
• src/main.ts
• src/metadata-server.test.ts
• src/metadata-server.ts
• src/multiplexer/agent-io-methods.ts
• src/multiplexer/archives.ts
• src/multiplexer/dashboard-model.ts
• src/multiplexer/dashboard-ops.ts
• src/multiplexer/dashboard-tail-methods.test.ts
• src/multiplexer/dashboard-tail-methods.ts
• src/multiplexer/persistence-methods.test.ts
• src/multiplexer/persistence-methods.ts
• src/multiplexer/session-launch.test.ts
• src/multiplexer/session-launch.ts
• src/multiplexer/session-runtime-core.test.ts
• src/multiplexer/session-runtime-core.ts
• src/runtime-core/index.test.ts
• src/runtime-core/index.ts

💤 Files with no reviewable changes (2)

• src/runtime-core/index.ts
• src/runtime-core/index.test.ts