Add coherent aimux restart flow

[TraderSamwise]

Summary

• add runtime coherence inventory via aimux doctor versions
• add top-level aimux restart to restart daemon/services and reload existing dashboards without killing agent tmux windows
• route stale control-plane repair and aimux daemon restart through the coherent restart path
• update docs for the new repair/restart model

Verification

• yarn typecheck
• yarn lint
• yarn test
• yarn build
• built CLI smoke checks for restart, doctor versions, and restart --help

Summary by CodeRabbit

Release Notes

• New Features

  • Added aimux restart command to coherently restart the local control plane with optional project scoping.
  • Added aimux doctor versions command to inspect daemon/project/dashboard version coherence.
  • Extended CLI with task lifecycle, handoff, review, thread, and host-level operations.

• Documentation

  • Restructured architecture documentation to clarify daemon, per-project service, and tmux runtime layers.
  • Updated runtime lifecycle guidance with clearer restart/recovery workflows.
  • Refined feature and API descriptions to reflect API-first control plane model.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 20, 2026 11:19am

[coderabbitai]

Warning

Review limit reached

@TraderSamwise, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 25 minutes and 16 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 14254561-fe06-47f5-811d-3a8f940fea0e

📥 Commits

Reviewing files that changed from the base of the PR and between 573de32 and e95bff7.

📒 Files selected for processing (6)

• src/daemon.ts
• src/main.ts
• src/runtime-coherence.test.ts
• src/runtime-coherence.ts
• src/runtime-restart.test.ts
• src/runtime-restart.ts

📝 Walkthrough

Walkthrough

Adds two new TypeScript modules—runtime-coherence.ts and runtime-restart.ts—implementing runtime coherence reporting and control-plane restart orchestration. Wires aimux restart (with --project scoping), a compatibility aimux daemon restart alias, and aimux doctor versions into src/main.ts. Updates all documentation (AGENTS.md, README.md, docs/current-architecture.md, docs/runtime-lifecycle.md) to reflect the new four-layer control-plane architecture.

Changes

Runtime Coherence, Restart, and CLI

Layer / File(s)	Summary
Runtime coherence types, report builder, and renderer src/runtime-coherence.ts, src/runtime-coherence.test.ts	Exports status/source union types and report interfaces; buildRuntimeCoherenceReport collects known projects from daemon state and tmux sessions, calls each project's /health endpoint with a 1000ms timeout, enumerates dashboard windows, and computes per-project and summary statuses; renderRuntimeCoherenceReport formats the result as text. Tests cover version-mismatch detection and unreachable-service handling.
Runtime restart orchestration, result types, and renderer src/runtime-restart.ts, src/runtime-restart.test.ts	Defines RuntimeRestartStepStatus, per-project and overall result interfaces, and a dependency-injectable options type; restartAimuxControlPlane orchestrates coherence reporting → daemon stop/start → per-project service ensure → dashboard reload with forceReload: true; renderRuntimeRestartResult formats the outcome string. Tests cover default and project-scoped restart scenarios.
CLI command wiring src/main.ts	Adds imports for new coherence/restart helpers; reworks restartStaleControlPlane to delegate to restartAimuxControlPlane; registers top-level aimux restart (--project, --json); replaces aimux daemon restart body with a compatibility alias; and adds aimux doctor versions backed by buildRuntimeCoherenceReport.
Architecture, lifecycle, and agent documentation AGENTS.md, README.md, docs/current-architecture.md, docs/runtime-lifecycle.md	AGENTS.md gains a Runtime Architecture section and extended CLI command list; README.md rewrites the Features, Architecture, API, recovery, and Task Delegation sections around the four-layer model; docs/current-architecture.md replaces the three-layer description with the four-layer model, dashboard model, tmux control helpers, and state-split rules; docs/runtime-lifecycle.md overhauled restart/recovery guidance and recovery order.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI as aimux restart / doctor versions
  participant restartAimuxControlPlane
  participant buildRuntimeCoherenceReport
  participant TmuxRuntimeManager
  participant ProjectService as per-project /health
  participant DaemonControl as stop/ensureDaemon

  User->>CLI: aimux restart [--project path]
  CLI->>restartAimuxControlPlane: call({projectRoot?})
  restartAimuxControlPlane->>buildRuntimeCoherenceReport: collect daemon state + tmux sessions
  buildRuntimeCoherenceReport->>TmuxRuntimeManager: list sessions/windows
  buildRuntimeCoherenceReport->>ProjectService: GET /health (1000ms timeout) per project
  ProjectService-->>buildRuntimeCoherenceReport: serviceInfo or error
  buildRuntimeCoherenceReport-->>restartAimuxControlPlane: RuntimeCoherenceReport
  restartAimuxControlPlane->>DaemonControl: stopDaemon → ensureDaemonRunning
  loop each target project
    restartAimuxControlPlane->>ProjectService: ensureProjectService
    restartAimuxControlPlane->>TmuxRuntimeManager: resolveDashboardTarget(forceReload:true)
  end
  restartAimuxControlPlane-->>CLI: RuntimeRestartResult
  CLI->>User: renderRuntimeRestartResult or JSON

  Note over User,CLI: aimux doctor versions
  User->>CLI: aimux doctor versions
  CLI->>buildRuntimeCoherenceReport: build report only
  buildRuntimeCoherenceReport-->>CLI: RuntimeCoherenceReport
  CLI->>User: renderRuntimeCoherenceReport or JSON

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐇 Hop, hop, the daemon wakes anew,
A coherence report checks what's stale or true,
aimux restart tidies each project in line,
doctor versions ensures every stamp is in rhyme,
The control plane hums — four layers, all fine! 🎉

🚥 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 'Add coherent aimux restart flow' directly and specifically describes the main change: introducing a new coherent restart mechanism for the aimux CLI tool.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/coherent-restart

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/runtime-coherence.test.ts (1)

50-132: ⚡ Quick win

Add a runtime-owner mismatch regression test.

Current coverage validates service/build-stamp drift, but not TMUX_RUNTIME_OWNER_OPTION drift. Add a case where session runtime owner differs from expected and assert dashboard/project status become mismatch / needs-restart.

🤖 Prompt for 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.

In `@src/runtime-coherence.test.ts` around lines 50 - 132, Add a third test case
within the "runtime coherence report" describe block that validates runtime
owner mismatch detection. The test should call buildRuntimeCoherenceReport with
getRuntimeOwnerId returning one owner value (e.g., "owner-new") and
getProjectServiceManifest returning a serviceInfo object with a different
runtimeOwner value (e.g., "owner-old"). Assert that the resulting report shows
dashboard and project status as "mismatch" and needsRestart count increases
appropriately, similar to the existing test structure for buildStamp mismatches.

🤖 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/runtime-coherence.ts`:
- Around line 225-228: The status evaluation in the ternary operator that checks
"ok" versus "mismatch" is missing validation of the runtimeOwner variable
(captured on line 212) against input.expectedRuntimeOwner. Add a check for
runtimeOwner equality to the condition alongside the existing checks for alive,
buildStamp, and owner to ensure the dashboard coherence evaluation properly
validates the runtime owner. Apply the same fix to the similar status assignment
at lines 374-375.

---

Nitpick comments:
In `@src/runtime-coherence.test.ts`:
- Around line 50-132: Add a third test case within the "runtime coherence
report" describe block that validates runtime owner mismatch detection. The test
should call buildRuntimeCoherenceReport with getRuntimeOwnerId returning one
owner value (e.g., "owner-new") and getProjectServiceManifest returning a
serviceInfo object with a different runtimeOwner value (e.g., "owner-old").
Assert that the resulting report shows dashboard and project status as
"mismatch" and needsRestart count increases appropriately, similar to the
existing test structure for buildStamp mismatches.

🪄 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

Run ID: 83fbf534-8c40-484f-b31f-c17f6454baa0

📥 Commits

Reviewing files that changed from the base of the PR and between 790eb6e and 573de32.

📒 Files selected for processing (9)

• AGENTS.md
• README.md
• docs/current-architecture.md
• docs/runtime-lifecycle.md
• src/main.ts
• src/runtime-coherence.test.ts
• src/runtime-coherence.ts
• src/runtime-restart.test.ts
• src/runtime-restart.ts

[TraderSamwise]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.