Skip to content

fix(server): t3_thread_wait can wait out a thread's background tasks - #256

Merged
jayleaton merged 2 commits into
mainfrom
fix/thread-wait-background-tasks-20261116
Nov 16, 2026
Merged

jayleaton merged 2 commits into
mainfrom
fix/thread-wait-background-tasks-20261116

Conversation

@jayleaton

@jayleaton jayleaton commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

A thread can end its run with background tasks still running, such as a make box-ci it backgrounded. t3_thread_wait on that idle thread returned at once, even with untilDelegatedWorkSettled: true, so a Captain listener used up its rounds in seconds.

Summary

untilDelegatedWorkSettled waits only for delegated tasks and awaited background tasks. A task is awaited only if the agent marked it with t3_background_wait, which only Claude can do. Plain commands and monitors were left out on purpose, because a dev server must not hold a delegated result open. The reported thread is an OpenCode thread: its two box-ci runs were kind: "command" with no awaited, so the wait reported result_available immediately.

t3_thread_wait { threadId, untilBackgroundWorkEnds: true }
  run still active                 -> wait (as before)
  run ended, background tasks left -> keep waiting; return when
       none is left | a later run starts (the wake) | question/approval | timeout
  timeout with tasks left          -> timedOut: true, status: "completed",
                                      pendingBackgroundTaskCount: N
  • I added a new opt-in flag, untilBackgroundWorkEnds, instead of widening untilDelegatedWorkSettled. Remote delegation (RemoteDelegation.ts) and t3 thread (threadIsIdle) use untilDelegatedWorkSettled to mean "the result is ready". If it counted every background command, a child that left a dev server running would never deliver its result.
  • The wait reads the same pendingBackgroundTasks list that t3_thread_read returns. A wait that times out keeps today's shape: the run status shows the run ended, timedOut: true shows the thread isn't done, and pendingBackgroundTaskCount says why.
  • PeerForwarding passes the flag through to linked environments.
  • The Captain v2 listener (captain-event-loop, as rewritten in chore(agents): Captain preset follows approvals, continuations and post-merge cleanup #254) passes untilBackgroundWorkEnds: true in step A, so an idle child with running background work no longer ends the listener. Step D stays: the wait returns when a background task's completion starts a new run, and D's activeRunId check follows that run.

Evidence

The reported thread on the live install (main build), idle with two unawaited box-ci commands. This is before:

> t3_thread_wait {"threadId":"mcp-thread-v2-5bb9…","untilDelegatedWorkSettled":true,"timeoutMs":30000}
< immediately: {"runId":"…:ordinal:9","status":"completed","timedOut":false,
   "resultRun":{"runId":"…:ordinal:9","status":"completed"},"workState":"result_available"}

This branch's dev server, on a completed thread from a seeded copy with one unawaited command task added (sandbox data only). This is after:

> t3_thread_wait {"threadId":"mcp-thread-v2-38e0…","untilDelegatedWorkSettled":true,"timeoutMs":20000}
< after 0.0s: {"status":"completed","timedOut":false,"resultRun":{…},"workState":"result_available"}   # unchanged
> t3_thread_wait {"threadId":"mcp-thread-v2-38e0…","untilBackgroundWorkEnds":true,"timeoutMs":20000}
< after 20.0s: {"status":"completed","timedOut":true,"pendingBackgroundTaskCount":1}

New case in ThreadManagementService.test.ts: waitForThread can wait past an ended run for its background tasks. On main it fails with timedOut: false (expected true with pendingBackgroundTaskCount: 1). On this branch it passes, including the wake: the command ends, a new run starts, and the wait returns. vp run check:changed passes.

The tool-list budget (agentContextBudget.json) grows by 178 bytes for the new field; the agent-context-increase label accepts that. I didn't run a paid eval because this checkout has no eval API key. The change adds a parameter and doesn't rewrite existing guidance.

Thread status, t3_thread_read and the Agents view list the same tasks, but on purpose they treat only awaited tasks as "Working" (backgroundWorkHoldsCompletion). I left that unchanged.

Merge Danger

Door: two-way. The flag is opt-in, and a missing flag behaves exactly as before.

Blast Radius: narrow. Only callers that pass untilBackgroundWorkEnds change: the Captain listener template and any agent that opts in.

Opus 5.5 via Claude Code in Ada.

🤖 Generated with Claude Code

@github-actions github-actions Bot added vouch:trusted Author is trusted by repo permissions or the VOUCHED list. size:M labels Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

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 21.5 KiB 21.5 KiB 0 B (0.0%) 24.4 KiB ✅
Codex Live turn messages 1 1 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.9 KiB 21.9 KiB 0 B (0.0%) 24.4 KiB ✅
Claude Live turn messages 1 1 0 (0.0%) 8 ✅

Other scenarios

All 64 scenario measurements match main.

All 64 scenario measurements
Provider Scenario Metric Main baseline This PR Impact PR ceiling
Codex short turn resume WebSocket decoded 10.5 KiB 10.5 KiB 0 B (0.0%) 12.7 KiB ✅
Codex short turn resume WebSocket messages 2 2 0 (0.0%) 2 ✅
Codex long turn running, cold open HTTP decoded 281.7 KiB 281.7 KiB 0 B (0.0%) 302.7 KiB ✅
Codex long turn running, cold open rows 75 75 0 (0.0%) 75 ✅
Codex long turn running, history page HTTP decoded 92.4 KiB 92.4 KiB 0 B (0.0%) 107.4 KiB ✅
Codex long turn running, history page rows 75 75 0 (0.0%) 75 ✅
Codex long turn finished, cold open HTTP decoded 381.5 KiB 381.5 KiB 0 B (0.0%) 410.2 KiB ✅
Codex long turn finished, cold open rows 151 151 0 (0.0%) 151 ✅
Codex long turn finished, socket cold open WebSocket decoded 381.6 KiB 381.6 KiB 0 B (0.0%) 410.2 KiB ✅
Codex long turn finished, socket cold open WebSocket messages 2 2 0 (0.0%) 2 ✅
Codex long turn finished, socket cold open rows 151 151 0 (0.0%) 151 ✅
Codex long turn finished, work page HTTP decoded 186.2 KiB 186.2 KiB 0 B (0.0%) 200.2 KiB ✅
Codex long turn finished, work page rows 150 150 0 (0.0%) 150 ✅
Codex idle thread resume WebSocket decoded 65 B 65 B 0 B (0.0%) 200 B ✅
Codex idle thread resume WebSocket messages 1 1 0 (0.0%) 1 ✅
Codex fleet shell snapshot HTTP decoded 42.4 KiB 42.4 KiB 0 B (0.0%) 53.7 KiB ✅
Codex fleet shell snapshot rows 27 27 0 (0.0%) 27 ✅
Codex fleet shell subscribe WebSocket decoded 65 B 65 B 0 B (0.0%) 200 B ✅
Codex fleet shell subscribe WebSocket messages 1 1 0 (0.0%) 1 ✅
Codex fleet shell resume check HTTP decoded 18 B 18 B 0 B (0.0%) 100 B ✅
Codex fleet shell resume check rows 0 0 0 0 ✅
Codex stale shell reload HTTP decoded 42.4 KiB 42.4 KiB 0 B (0.0%) 53.7 KiB ✅
Codex stale shell reload rows 27 27 0 (0.0%) 27 ✅
Codex stale shell resume WebSocket decoded 140 B 140 B 0 B (0.0%) 400 B ✅
Codex stale shell resume WebSocket messages 2 2 0 (0.0%) 2 ✅
Codex stale todo list cold open HTTP decoded 72.4 KiB 72.4 KiB 0 B (0.0%) 83.0 KiB ✅
Codex stale todo list cold open rows 75 75 0 (0.0%) 75 ✅
Codex stale todo list cold open nodes 2 2 0 (0.0%) 4 ✅
Codex stale todo list cold open subagents 2 2 0 (0.0%) 4 ✅
Codex stale todo list cold open plans 1 1 0 (0.0%) 2 ✅
Codex stale todo list cold open providerTurns 1 1 0 (0.0%) 2 ✅
Codex stale todo list cold open checkpoints 1 1 0 (0.0%) 2 ✅
Claude short turn resume WebSocket decoded 10.6 KiB 10.6 KiB 0 B (0.0%) 12.7 KiB ✅
Claude short turn resume WebSocket messages 2 2 0 (0.0%) 2 ✅
Claude long turn running, cold open HTTP decoded 283.3 KiB 283.3 KiB 0 B (0.0%) 302.7 KiB ✅
Claude long turn running, cold open rows 75 75 0 (0.0%) 75 ✅
Claude long turn running, history page HTTP decoded 93.4 KiB 93.4 KiB 0 B (0.0%) 107.4 KiB ✅
Claude long turn running, history page rows 75 75 0 (0.0%) 75 ✅
Claude long turn finished, cold open HTTP decoded 384.2 KiB 384.2 KiB 0 B (0.0%) 410.2 KiB ✅
Claude long turn finished, cold open rows 151 151 0 (0.0%) 151 ✅
Claude long turn finished, socket cold open WebSocket decoded 384.3 KiB 384.3 KiB 0 B (0.0%) 410.2 KiB ✅
Claude long turn finished, socket cold open WebSocket messages 2 2 0 (0.0%) 2 ✅
Claude long turn finished, socket cold open rows 151 151 0 (0.0%) 151 ✅
Claude long turn finished, work page HTTP decoded 188.1 KiB 188.1 KiB 0 B (0.0%) 200.2 KiB ✅
Claude long turn finished, work page rows 150 150 0 (0.0%) 150 ✅
Claude idle thread resume WebSocket decoded 66 B 66 B 0 B (0.0%) 200 B ✅
Claude idle thread resume WebSocket messages 1 1 0 (0.0%) 1 ✅
Claude fleet shell snapshot HTTP decoded 43.0 KiB 43.0 KiB 0 B (0.0%) 53.7 KiB ✅
Claude fleet shell snapshot rows 27 27 0 (0.0%) 27 ✅
Claude fleet shell subscribe WebSocket decoded 66 B 66 B 0 B (0.0%) 200 B ✅
Claude fleet shell subscribe WebSocket messages 1 1 0 (0.0%) 1 ✅
Claude fleet shell resume check HTTP decoded 18 B 18 B 0 B (0.0%) 100 B ✅
Claude fleet shell resume check rows 0 0 0 0 ✅
Claude stale shell reload HTTP decoded 43.0 KiB 43.0 KiB 0 B (0.0%) 53.7 KiB ✅
Claude stale shell reload rows 27 27 0 (0.0%) 27 ✅
Claude stale shell resume WebSocket decoded 140 B 140 B 0 B (0.0%) 400 B ✅
Claude stale shell resume WebSocket messages 2 2 0 (0.0%) 2 ✅
Claude stale todo list cold open HTTP decoded 73.4 KiB 73.4 KiB 0 B (0.0%) 83.0 KiB ✅
Claude stale todo list cold open rows 75 75 0 (0.0%) 75 ✅
Claude stale todo list cold open nodes 2 2 0 (0.0%) 4 ✅
Claude stale todo list cold open subagents 2 2 0 (0.0%) 4 ✅
Claude stale todo list cold open plans 1 1 0 (0.0%) 2 ✅
Claude stale todo list cold open providerTurns 1 1 0 (0.0%) 2 ✅
Claude stale todo list cold open checkpoints 1 1 0 (0.0%) 2 ✅

Baseline: 605b8ff · PR result: 72190f0 · 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.

@jayleaton jayleaton added the agent-context-increase Approves a measured increase to the agent context budget label Nov 16, 2026
jayleaton and others added 2 commits November 16, 2026 12:12
…d tasks

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jayleaton
jayleaton force-pushed the fix/thread-wait-background-tasks-20261116 branch from 24eed72 to 72190f0 Compare November 16, 2026 04:13
@jayleaton
jayleaton marked this pull request as ready for review November 16, 2026 04:20
@jayleaton
jayleaton merged commit f274490 into main Nov 16, 2026
35 of 36 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-context-increase Approves a measured increase to the agent context budget size:M vouch:trusted Author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant