feat: one recovery path — aimux repair reconciles stranded backend ids

[TraderSamwise]

Context (epic W3)

The investigation that started this work surfaced a sprawling, hierarchy-less command surface (~80 commands, ~23 flat at top level, four overlapping "fix my runtime" paths). The instinct was a noun-grouped restructure — but the documented agent verbs (spawn, stop, kill, fork, worktree …) are public and a mass rename is pure churn for users and scripts. So this epic delivers direction without churn: one obvious recovery command, no renames.

Change

aimux repair already rebuilds the tmux runtime. It now also runs a backend-id reconcile sweep: for every offline agent missing a durable backend session id, it discovers the id from the tool's on-disk session store (W2's discoverBackendSessionId) and backfills it into the topology.

• reconcileOfflineBackendSessionIds(projectRoot) — idempotent; only touches offline sessions that are missing an id and have a discoverable transcript; preserves offline status and all other fields (no binding, no status flip).
• repair prints (and --json emits) the recovered ids.

This operationalizes W0 (capture) + W2 (per-resume reconcile) into a single proactive action: run aimux repair once to recover agents whose backend id was lost to a crash before these fixes existed — including the claude-omdtnp session that started all this.

Why no renames

A separate, user-gated proposal will cover the broader noun-grouped hierarchy (agent …, project …, retiring the legacy host compat group). That's the high-churn part and deserves explicit sign-off on naming/compat rather than being forced autonomously. Nothing here breaks an existing command.

Verification

• yarn verify green: typecheck + lint clean, 1025/1025 tests.
• New backend-id-reconcile.test.ts: backfill-into-topology, already-has-id skip, no-transcript skip, and reconcile-twice idempotency.
• Independent implementation audit: PASS (offline-only scope, idempotency, field/status preservation, output wiring, exception safety).

Scope

Builds on W0 + W2 (merged). No write-layer (W1) or command-name changes.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Enhanced the repair command with session ID reconciliation, automatically recovering offline agent session mappings to their backend session IDs.
  • Repair command now displays a recovery report listing reconciled session mappings.
  • JSON output includes reconciliation results alongside existing repair data.

• Tests

  • Added test coverage for the new session reconciliation functionality.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 7, 2026 3:06am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1779dcbd-7110-49fc-9120-41c650489d49

📥 Commits

Reviewing files that changed from the base of the PR and between 43ace06 and 61b5c76.

📒 Files selected for processing (3)

• src/main.ts
• src/runtime-core/backend-id-reconcile.test.ts
• src/runtime-core/backend-id-reconcile.ts

---

📝 Walkthrough

Walkthrough

This PR adds offline backend session ID reconciliation. A new reconcileOfflineBackendSessionIds function discovers missing backend session IDs from on-disk transcripts, updates offline topology state, and returns reconciled mappings. Integration into the aimux repair command includes reconciliation results in JSON output and displays a recovery report of reconciled sessions.

Changes

Offline Backend Session ID Reconciliation

Layer / File(s)	Summary
Reconciliation contract and core logic src/runtime-core/backend-id-reconcile.ts	Exports BackendIdReconcileResult interface and reconcileOfflineBackendSessionIds function that scans offline sessions missing backendSessionId, discovers IDs from on-disk session store, upserts topology state, and returns reconciled { id, backendSessionId } mappings.
Reconciliation test suite src/runtime-core/backend-id-reconcile.test.ts	Vitest suite with isolated temp environments validates backfilling from transcripts, respecting already-present IDs, handling missing transcripts, and idempotency across multiple reconciliation runs.
CLI repair command integration src/main.ts	Integrates reconcileOfflineBackendSessionIds into the repair command by invoking reconciliation, merging results into JSON output, and printing a recovery report mapping reconciled offline agent sessions to backend session IDs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A rabbit hops through session trails,
Where offline maps to backend's tales.
Transcripts found, IDs now mend—
Repair command, reconcile, transcend! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% 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 clearly and concisely describes the primary change: extending aimux repair to reconcile/recover stranded backend session IDs for offline agents.
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 feat/cli-recovery-consolidation

---

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