fix(server): held queued wakes no longer keep delegated tasks running

[juliusmarminge]

Problem

A delegated child thread's queued runs (for example pull request watch wakes) get held for the user when the child is stopped, the server restarts, or the provider fails. Those held runs were still counted as active work. As a result:

• delegatedTaskProgress kept the task in working, so the parent's subagent row stayed running with no result.
• Startup subagent-results recovery (TS predicate and SQL) skipped the child, so a restart did not repair it either.
• task_status reported hasPendingChildRuns: true for turns that only the user can resume.

There was a second ordering bug in handleTerminalRun. It finalized the child's task before startNextQueuedRun held the queue after a provider failure. Finalization still saw a deliverable queued wake, returned working, and nothing finalized the task again until the next restart.

Before: a stopped or failed child with a held wake leaves the parent task stuck "running" indefinitely.
After: the task settles with the cancelled or failed run as its result, and the held wake stays held for the user to resume or discard.

Fix

• A queued run with queueHeld === true no longer counts as owed work in delegatedTaskProgress, needsRecovery, the recovery SQL (queueHeld IS 1, so missing or NULL is treated as unheld), and hasPendingChildRuns. The task_status tool description now says so.
• handleTerminalRun makes the queue decision first and finalizes afterwards. A failure in the queue step is logged and no longer skips finalization. Locks are still taken sequentially, never nested, so lock order is unchanged.

The scope was authorized by a maintainer and stays inside the server's subagent lifecycle. There are no contract, client, or provider-adapter changes.

Verification

The proof is deterministic tests. Screenshots don't apply because no UI changed.

• With the new tests in place and the source change reverted, 5 tests fail:
  • settles a cancelled child whose held wakes wait behind it
  • settles a child whose provider failure holds its queued wakes (times out: the task stays running)
  • recovers terminal subagent results until their cross-thread transfer exists
  • waits for nested work and retains the report across monitor acknowledgements
  • the MCP toolkit hasPendingChildRuns case
• With the fix, 11 related suites pass, 185/185 tests: delegated delivery, subagent projection, projection recovery and store, the MCP toolkit, restart continuation, thread stop, background work stop, runtimeLayer, provider runtime recovery, and run completion reads.
• tsc --noEmit in apps/server is clean. Lint on the touched files is clean apart from one existing unused-variable warning that this change doesn't touch.
• An independent review approved the fix and contributed the ordering correction.
• Both failure modes were reproduced from a read-only snapshot of real data. Those records are private and not attached.

The fix only reaches existing stuck tasks after the host runs this build and startup recovery runs.

Done by Claude Opus 5.5 in T3 Code (Claude Code harness).

🤖 Generated with Claude Code

---

[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: bb5a7be5-e94a-4320-8e48-166e887d7875

📥 Commits

Reviewing files that changed from the base of the PR and between d720210 and ac10d11.

📒 Files selected for processing (9)

• apps/server/src/mcp/OrchestratorMcpService.ts
• apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts
• apps/server/src/mcp/toolkits/orchestrator/tools.ts
• apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts
• apps/server/src/orchestration-v2/Orchestrator.ts
• apps/server/src/orchestration-v2/ProjectionRecovery.test.ts
• apps/server/src/orchestration-v2/ProjectionStore.ts
• apps/server/src/orchestration-v2/SubagentProjection.test.ts
• apps/server/src/orchestration-v2/SubagentProjection.ts

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

---

📝 Walkthrough

Walkthrough

The change excludes queued child runs marked queueHeld from pending-work and recovery calculations. For run.updated events, delegated completion delivery now runs before queued-run startup, whose failures are logged and swallowed.

Changes

Held queued child run handling

Layer / File(s)	Summary
Pending child work classification apps/server/src/orchestration-v2/SubagentProjection.ts, apps/server/src/orchestration-v2/SubagentProjection.test.ts, apps/server/src/mcp/OrchestratorMcpService.ts, apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts, apps/server/src/mcp/toolkits/orchestrator/tools.ts	Progress and MCP pending-run checks exclude queued runs marked queueHeld. Tests cover held and unheld queued runs. The task status description documents that held turns wait for the user and do not count as pending child runs.
Subagent recovery selection apps/server/src/orchestration-v2/ProjectionStore.ts, apps/server/src/orchestration-v2/ProjectionRecovery.test.ts	Recovery checks use the latest unheld run. Tests cover recovery behavior for held, deliverable-queued, and other child states.
Terminal run completion delivery apps/server/src/orchestration-v2/Orchestrator.ts, apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts	run.updated handling finalizes delegated completion delivery before attempting queued-run startup. Startup failures are logged and swallowed. Tests cover restart recovery when held queued runs remain.

Priority: ➖ Normal

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

Change: Bug fix

Possibly related PRs

• pingdotgg/t3code#15170: Introduced delegated-task reconciliation and terminal handling in the same paths affected by this change.

Suggested reviewers: maria-rcks, t3dotgg

Merge Risk: ⚪ Minimal · up to ac10d

This change stops held queued runs from keeping delegated tasks in the running state. No merge-blocking risk was identified.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary fix: held queued wakes no longer keep delegated tasks running.
Description check	✅ Passed	The description includes the required Problem, Change, Scope and approval, and Verification sections. It explains the affected behavior, implementation, authorization, tests, type-checking, lint statu…
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.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	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	0 B (0.0%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.9 KiB	20.9 KiB	0 B (0.0%)	29.3 KiB	✅
Codex	Live turn messages	2	2	0 (0.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	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	0 B (0.0%)	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: d720210 · PR result: ac10d11 · 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.

[macroscopeapp]

Approvability

Verdict: Approved at ac10d11

Macroscope's review found this PR approvable — This is a focused server-side bug fix that prevents user-held queued wakes from falsely keeping delegated tasks active and ensures provider-failure finalization occurs in the correct order. The runtime edits are narrow, consistent across status and recovery paths, and accompanied by targeted regression coverage.

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