fix(server): Claude prompts no longer hang on a uuid the session already holds

[juliusmarminge]

Problem

A Claude thread can swallow a message: the run shows "Working" forever, nothing streams, and only Stop ends it.

Claude prompt uuids were a hash of the run attempt id, which is just the thread id and run ordinal. A dev server seeded from a copy of the database (migrate-dev-db) keeps those ids and the provider session binding, so it resumes the real ~/.claude transcript and writes prompts under the uuids the real server will use for its next runs. When the real server gets there, Claude finds the uuid already in its transcript and replies with a lone command_lifecycle completed: no queued, started, system/init or result. The adapter waits forever.

Seen on thread f9ac0fac: a dev instance had sent test prompts there as runs 17–20, and the user's real runs 17 and 19 were silently dropped (3h20m and 1h49m "Working", the second ending in a manual Stop). Each dropped prompt's uuid matched a transcript entry written four days earlier by the dev server.

Fix

• Fresh uuid per offer. Each prompt offer now gets a random UUIDv4 from the Effect Crypto service instead of claudePromptUuid(attemptId). Echo routing is unchanged: the same uuid is still stored on the turn context and matched against user_message_uuid. Replay already maps recorded prompt uuids to replayed ones by matched offer, so the recorder uses random uuids too.
• Backstop for a prompt Claude never runs. If Claude reports the pending prompt completed before ever reporting it started, the turn now fails with "Claude acknowledged the message but never started a turn for it." instead of hanging. The thread stays reusable, so the next message works. Across the local provider logs, every prompt that ran got queued → started (→ completed); completed with no started appears only for the dropped prompts.

The uuid change ports #16254 by @saphid onto current main. That PR now conflicts: main moved claudePromptUuid onto the Effect Crypto service since it was opened. This PR adds the backstop on top. #16254 can be closed in favor of this one.

Verification

• New test fails a prompt Claude completes without starting a turn for it: times out waiting for a terminal without the backstop, and passes with it.
• New test keeps a started prompt running until its result: a queued → started → completed sequence followed by the echoing result still completes normally, covering a CLI that reports completed before the turn's result.
• fix(server): Claude prompts no longer hang when a session outlives its database #16254's gives the same run attempt a fresh prompt uuid on every offer, and its migration of the echo-routing tests to read the offered uuid.
• vp test run on ClaudeAdapterV2.test.ts, ClaudeAutomaticDelivery, ClaudeReplayFixtures, OrchestratorReplayRecovery, OrchestratorReplayFixtures, OrchestratorReplayRestartBackgroundNote, ThreadMergeBack, and ThreadFork: 8 files, 310 tests passed.
• tsc --noEmit in apps/server is clean for these files. The ProviderSwitch.integration.test.ts errors are already present on main.

Made with Claude Opus 5.5 in Claude Code (running in T3 Code).

🤖 Generated with Claude Code

---

[macroscopeapp]

Approvability

Verdict: Approved at 54052c8

Macroscope's review found this PR approvable — This is a focused Claude adapter bug fix that replaces a known prompt hang with a reusable failure and uses fresh per-offer UUIDs to prevent transcript collisions. Normal prompt processing remains unchanged, with targeted regression tests covering both affected and successful lifecycle paths.

^{You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ The exact PR base did not have a successful artifact. Baseline uses the latest successful main measurement shown below.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	4.9 KiB	5.0 KiB	+23 B (+0.5%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	+23 B (+1.9%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.8 KiB	20.9 KiB	+41 B (+0.2%)	29.3 KiB	✅
Codex	Live turn messages	1	2	+1 (+100.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	−17 B (−0.3%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	−17 B (−1.4%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	0 B (0.0%)	29.3 KiB	✅
Claude	Live turn messages	2	2	0 (0.0%)	8	✅

Baseline: 250e052 · PR result: 54052c8 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: b8846656-dd7b-444d-9a8c-8bcf562931d2

📥 Commits

Reviewing files that changed from the base of the PR and between 41985b4 and 54052c8.

📒 Files selected for processing (3)

• apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
• apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.testkit.ts
• apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The Claude adapter now generates UUIDs for non-continuation prompts and tracks their lifecycle states. Tests use the UUIDs of offered prompts and cover UUID uniqueness, lifecycle failures, and successful completion.

Changes

Claude prompt flow

Layer / File(s)	Summary
Prompt UUID allocation and test framing apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts, apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.testkit.ts, apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts	Non-continuation prompts receive random UUIDs that the adapter validates. Replay recording generates UUIDs with Effect crypto. Wake tests stamp frames with the UUID of the offered prompt and check uniqueness across harnesses.
Prompt lifecycle handling apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts, apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts	The adapter records matching started lifecycle frames. A matching completed frame without a prior started frame fails the turn; a started prompt can complete when its result arrives.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Suggested reviewers: esthor

Merge Risk: ⚪ Minimal · up to 54052

The change is mergeable after normal checks; no concrete unresolved risk has been identified.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the server fix for Claude prompts that hang when the session already contains the UUID.
Description check	✅ Passed	The description provides a detailed problem statement, explains the UUID and lifecycle fixes, links the related pull request, and lists focused verification results. It uses “Fix” instead of the templ…
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.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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