fix(server): Claude background-task wakes start when the queue is held#17885

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Preserve Stop holds for provider wakes.

A Claude wake can be offered after Stop. Stop holds queued runs that already exist, but this provider wake bypasses queueHeld. When the interrupted run becomes terminal, nextQueuedRun can select and start the wake. Apply the provider-wake exemption only to restart-recovery holds, not to a queue held by Stop.

✅ Addressed in commit 637b569

[claude-opus-5-5] RESPONDING ON BEHALF OF TANNER

Fixed in 637b569646. A provider wake skips the inherited hold only when Stop has not reached the active run, so a wake that queues after Stop waits with Stop's hold. The new BackgroundWorkStop integration test covers that window. The exemption still applies to the provider-failure hold as well as the restart hold. A message that reaches an idle thread already starts past either hold on main, so a wake that lands mid-run now behaves the same way.

@fireboltdude1357 Thanks for the fix and the clarification. The supplied code confirms that a provider wake inherits the queue hold when Stop has reached the active run.

The provider-failure exemption remains intentional. My recommendation to restrict the exemption to restart holds was too narrow.

If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!

✅ Review thread resolved.

You are interacting with an AI system.

[minor] A provider wake dispatched after Stop now starts past the queue Stop held · logic

Stop holds only the runs that are queued when it commits (holdStoppedThread). Before this change, a later wake picked up that hold because a held run already sat in the queue. Now a provider wake (createdBy: "agent", creationSource: "provider") never gets queueHeld, and nextQueuedRun skips held runs. So a wake dispatched between Stop's commit and the stopped run's terminal event starts when that run ends, with no queue.resume, while the user's held messages stay held.

When it breaks: The thread has a queued user message Q. Claude's turn for run A ends in the adapter, but the orchestrator hasn't ingested A's terminal event yet, so A still shows as running. The user presses Stop, which commits and holds Q. A background-task notification then makes the CLI start a wake turn. ClaudeAdapterV2 offers a continuation, and ProviderContinuationService dispatches W as a provider queue_after_active message. W isn't held. When A's terminal event lands, startNextQueuedRun skips the held Q and starts W. On the base commit, W would have inherited Q's hold.

Evidence (level 3: traced the failing path): - Orchestrator.ts:4980-5001: isProviderWake skips the inherited queueHeld with no check for whether the thread was stopped. The only other check before this, at 4553-4581, covers restartContinuationOfRunId; nothing in message.dispatch calls stopReachedRun for provider wakes.

• Orchestrator.ts:8735-8766 (holdStoppedThread): Stop sets queueHeld only on runs that are queued at commit time. It has no lasting "stopped" state that a later dispatch would read.
• Orchestrator.ts:614 (nextQueuedRun) and 1276-1305 (startNextQueuedRun): after this change, held runs are skipped instead of blocking the queue, so the unheld W starts once A is terminal.
• ProviderContinuationService.ts:155-179: the Claude wake is dispatched with createdBy: "agent" and creationSource: "provider". Claude's offer (ClaudeAdapterV2.ts:5669) has no dispatchIfCurrent, so nothing re-checks the request before dispatch.
• ClaudeAdapterV2.ts:5902-6003: a wake is buffered or offered only when the adapter has no active turn. So the trigger needs the window where the adapter has finished A and the orchestrator hasn't ingested it. The PR says this window is where wakes usually arrive.
• ProviderTurnControlService.ts:201-225 and ClaudeAdapterV2.ts:7817-7843: if Stop's interrupt reaches the adapter before W starts, it closes the CLI and clears the wake buffer, so W settles as an empty run (7752-7758). If W starts first, the interrupt targets A's turn and fails with "not the active turn" (7850-7854), so the wake turn keeps running after Stop.
• Base (dacd2cb649) Orchestrator.ts message.dispatch: every queued run inherited the hold when a held run existed, and startNextQueuedRun returned early while any run was held. In this exact case W stayed held until the user resumed.
• Mitigation: a thread with no queued messages at Stop time never held such a wake, before or after this change. The gap itself is old, but this change opens it for threads whose queue Stop actually held.
• I could not run code here because Bash was denied, so this is a step-by-step trace.

Suggested fix: Keep the provider-wake exemption only when no Stop has reached the thread's current work. For example, find the active or latest executed run and check stopReachedRun on it. If Stop reached it, let the wake inherit the hold (or drop it):

_{Raised by bugs-sol + boundary-sol; verified by claude-opus-5-5. Finding r1-1.}

[claude-opus-5-5] RESPONDING ON BEHALF OF TANNER

Fixed in 637b569646. A provider wake now skips the inherited hold only when Stop has not reached the active run (stopReachedRun on activeRun). A wake that queues after Stop waits with the held queue, as it did before this PR. The new test "Stop holds a provider wake that queues before the stopped turn ends" in BackgroundWorkStop.integration.test.ts dispatches Stop while a turn is still running, then a provider wake. It fails on e059b62 (expected undefined to be true) and passes now.

The same check covers r1-2, the Codex background-command continuation dispatched in that Stop window. I kept the Codex offer as it is. Marking it message_text would change how clients label those messages, which is a separate change. Outside Stop, a held queue only catches a wake that arrives while a run is active. A wake that reaches an idle thread already starts past held messages on main, so a Codex wake skipping a restart hold matches what main does at idle.

[major] Restrict the queue-hold bypass to Claude buffered wakes · logic

The bypass also matches Codex background-command continuations, allowing them to start while the queue remains held. Codex sends these continuations as fresh prompts, so the Claude justification that the CLI already runs the wake turn does not apply.

When it breaks: Startup recovery holds a Codex queued message. During a subsequent active run, a settled background command finishes and offers a continuation. If the active run completes successfully without Stop, the continuation starts while the older user message remains held.

Evidence (level 3: traced the failing path): CodexAdapterV2.ts:5909-5916 retains completed turns with background work; :2063-2070 resolves their late events; :4790-4832 offers a continuation without delivery. ProviderContinuationService.ts:155-173 dispatches it as queue_after_active with createdBy=agent and creationSource=provider. Orchestrator.ts:4876-4883 queues it, and :4987-5004 omits queueHeld because the only additional guard checks Stop. ProjectionStore.ts:4685-4693 permits an unheld queued run beside held runs; Orchestrator.ts:611-614 selects it, and :1872-1875 schedules provider-turn.start. CodexAdapterV2.ts:6625-6631 converts its message into input, :3158-3168 includes the detail text, and :6209 sends turn/start. Base Orchestrator.ts:4988-4992 inherited the hold for this same request. This is a source-traced failure path; execution was unavailable because this checkout has no node_modules.

Suggested fix: Require the queued adapter's driver to be Claude in wakeSkipsHold, preserving the existing Stop guard. Add a focused Codex continuation test asserting that it inherits queueHeld and stays queued after the active run completes.

_{Raised by sweep-opus; verified by gpt-6.1-sol. Finding r2-1.}

[claude-opus-5-5] RESPONDING ON BEHALF OF TANNER

Fixed in 865e04d81f, at the source instead of with a driver check in the orchestrator. Codex was the only adapter that offered a "provider" wake without adopting a turn it had already started. Claude, Muse, ACP, OpenCode and pi all attach to a running turn. Codex now offers its background-command continuation with delivery: "message_text", which matches what it does: it starts a new turn from that text. ProviderContinuationService therefore dispatches it as creationSource: "server", and it inherits the hold as it did on main. The existing Codex adapter test now asserts the delivery. One visible side effect: the Codex wake message's attribution row reads T3 Code instead of the agent. That is accurate, since T3 Code writes that text.

🟠 High orchestration-v2/Orchestrator.ts:689

When all queued runs are held, queue.resume rejects a valid resume for a queued message targeting provider B with “Continue the limited thread,” even when B is allowed by usageLimitHoldsQueue. This filter makes nextQueuedRun return undefined, so resume validation checks the thread’s provider instead of the queued run’s provider; validate explicit resumes using delivery order including held runs while retaining this filter for automatic scheduling.

External image Major · Data Integrity & Integration · Quick win

Keep provider wakes held while worktree setup is unresolved.

If worktree setup fails and a later client message starts a run, worktreeSetupUnresolved keeps the earlier queue held. A provider wake during that run still satisfies wakeSkipsHold. After the run completes, startNextQueuedRun can start the wake without the missing worktree. Exclude worktreeSetupUnresolved from the hold bypass so the wake remains held with the queue. As per coding guidelines, “Connection modes. Local, remote/relay, and tunnel behave differently. Multi-device and multi-environment cases are real.”

Source: Coding guidelines