fix: reconcile backend id only from an unambiguous transcript dir

[TraderSamwise]

Found in production

Running the W3 aimux repair on a real project surfaced a mis-binding the W2 audit had flagged as a theoretical risk — and it was real. Offline sessions without a worktreePath fell back to the main-repo transcript directory, which accumulates many transcripts from agents that ran there over time. The "most recently active" tie-break then bound several offline sessions to the same id (the latest main-repo transcript):

claude-lpppvo -> dd3fd726…   # main-repo transcript, not lpppvo's
claude-ywwo1g -> dd3fd726…   # same id again — duplicate

The original resume path deliberately refused to guess; the discovery heuristic broke that guarantee.

Fix

Bind only when the worktree's transcript directory holds exactly one candidate. Absent / empty / multi-transcript directories refuse (null). This:

• keeps every correct single-transcript recovery (the per-worktree agents, including the claude-omdtnp that started this work),
• eliminates duplicate/wrong bindings by construction (a multi-transcript dir never binds),
• restores the original "exact id only, never guess" safety.

Disambiguating a multi-transcript dir by session createdAt is noted as a future enhancement.

Verification

• yarn verify green: typecheck + lint clean, 1027/1027 tests.
• Flipped the discovery test ("several transcripts → null") and added a reconcile-level test locking "ambiguous dir → not bound, no backendSessionId written".

Follow-up to #100 / #101.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Enhanced backend session discovery to safely handle ambiguous scenarios by returning null when multiple transcript files exist, instead of arbitrarily selecting one.

• Tests

  • Updated and added test coverage to verify correct behavior when multiple transcript files are present.

[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:31am

[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: b7528d46-73ec-4a40-adbf-2fa189daf01f

📥 Commits

Reviewing files that changed from the base of the PR and between e42d687 and b20dc13.

📒 Files selected for processing (3)

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

---

📝 Walkthrough

Walkthrough

The PR refactors transcript discovery to refuse ambiguity instead of guessing: discoverClaudeBackendSessionId now returns null when zero or multiple UUID-named .jsonl files exist in the worktree directory, rather than selecting by modification time. Tests for both discovery and reconciliation are updated accordingly.

Changes

Backend session discovery refactoring

Layer / File(s)	Summary
Discovery strategy and imports src/backend-session-discovery.ts	The statSync import is removed; the discovery logic now enumerates .jsonl filenames and returns the UUID only when exactly one valid candidate exists, otherwise null. Documentation is clarified to describe this strict matching behavior.
Discovery unit test update src/backend-session-discovery.test.ts	The ambiguity test case is updated to assert null return when multiple UUID transcripts are present, instead of expecting selection of the most recently modified transcript.
Reconciliation test for ambiguous transcripts src/runtime-core/backend-id-reconcile.test.ts	A new test verifies that reconcileOfflineBackendSessionIds does not bind backendSessionId when the worktree directory contains multiple UUID-named transcript files, leaving the offline session's backendSessionId undefined.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• TraderSamwise/aimux#100: The main PR refactors discoverClaudeBackendSessionId to refuse when multiple UUID transcripts exist; this PR's implementation previously picked the most-recently modified transcript—direct behavioral conflict in the same discovery logic.
• TraderSamwise/aimux#101: Both PRs involve reconcileOfflineBackendSessionIds backfilling backendSessionId from on-disk transcript discovery; the main PR's change to return null for ambiguous candidates directly affects the reconciler added in PR #101.

Poem

🐇 When multiple transcripts confuse the way,
We wisely choose to not guess today.
One UUID shines, or none at all—
Ambiguity answered by honest refusal's call. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 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 summarizes the main change: reconciling backend IDs only when the transcript directory is unambiguous, not from multiple candidates.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 fix/backend-discovery-unambiguous-only

---

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