Repository navigation
Codex Desktop: completed subagents can remain as hidden resident blockers and prevent later spawns #34518
Description
Summary
In Codex Desktop, after the root agent spawns three direct subagents and their tasks appear to be completed, a later spawn_agent can fail with:
collab spawn failed: agent thread limit reached
The user-facing problem is that a subagent shown as completed can still be a non-evictable resident because of hidden pending mailbox state. The UI and the generic error do not identify the blocking agent or provide a recovery action.
Environment
- Product: Codex Desktop
- Platform: Windows
- Date reproduced: 2026-07-21
- App/CLI version: not exposed to the isolated test thread, so I cannot report it reliably
- Observed collaboration capacity: root plus three direct subagent resident slots
- No files or configuration were changed during the reproduction
Original user-facing symptom
- Ask the root agent to delegate work to three subagents.
- Let the delegated tasks finish.
- Continue the same Codex task and ask it to delegate another task.
- The later spawn fails or delegation is unavailable even though the earlier subagents appear completed.
From the UI, this looks like completed subagents failed to release their capacity.
Controlled reproduction
I ran two isolated Codex tasks to separate ordinary completion from hidden mailbox state.
Baseline: ordinary completed agents
- Spawn direct subagents A, B, and C with clean history.
- Let all three return
A_OK,B_OK, andC_OKand reachcompleted. - Spawn a new direct subagent D.
Result: D's spawn_agent returned successfully without a noticeable wait, and D completed with D_OK.
This shows that ordinary completed agents alone were reclaimable in this runtime.
Pending-mailbox variant
- In a fresh isolated task, spawn A and let it complete with
A_OK. - Send
STATUS_PROBEto completed A using queue-onlysend_message. It does not trigger a new turn. - Spawn E and F with tasks that remain active for about 45 seconds.
- While E and F are active, attempt to spawn G.
The G spawn fails immediately with the exact output:
collab spawn failed: agent thread limit reached
At that point only E and F are actively running. A is completed, but it has the pending queue-only mailbox item. The controlled difference from the successful baseline is the hidden pending mailbox on A.
I then used followup_task on A; A consumed the queued work and returned A_DRAINED. E and F also completed. A subsequent retry could not be emitted because the isolated test task encountered a separate tool-routing failure, so this report does not claim that the recovery path was independently verified.
Actual behavior
- A completed subagent can remain resident and block admission.
- The completed status does not expose pending mailbox state.
AgentLimitReacheddoes not distinguish active concurrency exhaustion from residency pressure.- The user cannot see which completed agent is blocking eviction or how to recover.
- Raising the thread limit would only make the problem less frequent.
Expected behavior
At least one of the following should occur:
- Reject queue-only
send_messageto an already completed agent and direct the caller tofollowup_task. - Automatically trigger a follow-up turn when queue-only mail crosses the completion boundary.
- Persist the mailbox independently so the completed resident can be evicted.
- Expose a close/drain action for completed agents.
- Make
AgentLimitReachedreportmax,active,residents, and anypending_mailbox_blockers. - Show in the Desktop UI when a completed subagent still counts toward capacity.
Related issues
- MultiAgentV2: queue-only message to a completed agent pins a residency slot #32353 documents the pending-mailbox residency mechanism at the app-server level.
- Completed subagents continue to count against thread limit #22779 covers older completed/open-thread quota accounting.
- MultiAgentV2 spawn_agent can hang indefinitely while evicting a terminal resident thread #33777 covers a separate MultiAgentV2 hang while evicting a terminal resident.
This report is filed separately to track the Codex Desktop user-facing symptom: agents appear completed, but hidden residency state prevents later delegation with no diagnostic or recovery hint.
Additional evidence
Independent reproduction comment on #32353:
No local paths, task/thread IDs, account information, or private logs are included.
Activity
slobodaapl commentedon Jul 26, 2026
Can confirm it also happens in CLI; root agent tries to spawn agents; after they're done, they're no longer visible to the root agent, and thus if it tries to spawn another past the limit, it errors out on agent cap being reached, but it cannot close old ones as it cannot see them.
pomazanbohdan commentedon Aug 18, 2026
Additional Windows Desktop reproduction (26.814.5167.0; CLI/runtime 0.148.0-alpha.15):
task_complete/final_answer, but the parent persisted all 7 spawn edges as open; the parent recorded started/interacted activity without a terminal/completed edge transition.context_compactedevents, one already-completed child reappeared aspending_init. With that hidden resident plus two genuinely running reviewers, a third reviewer failed withcollab spawn failed: agent thread limit reached.codex_core::tools::router,core/src/tools/router.rs:231. All 7 child rollouts later completed while all 7 parent edges remained open.This indicates a completion-to-residency/edge-release gap, with compaction/rehydration reviving a stale resident handle. A regression test should compare child terminal state with parent edge closure and ensure completed/
pending_initresidents do not consume spawn capacity.pomazanbohdan commentedon Aug 23, 2026
Follow-up cluster note: the same boundary affects both capacity and presentation—terminal children can retain open parent edges/residency, then rehydrate as Active after reload. The safe invariant is rollout terminal state plus live-process absence, not UI Active or thread_spawn_edges.status=open; see #39694 and #37042.
iendeavor123 commentedon Sep 30, 2026
Additional Codex Desktop observation (2026-09-30, macOS)
Codex Desktop
26.928.20755, build12246. In a long-running task, the runtime advertised 11 concurrency slots including the root, matching the session's initial[agents] max_concurrent_threads_per_session = 10setting.Observed sequence:
agent thread limit reached.list_agentssnapshot shows the root and one worker running, eight workerscompleted, and onepending_init. Active work is well below the expected ten-worker concurrency limit.The on-disk agent cap was subsequently changed from 10 to 20. The active runtime still advertises 11 slots; this report does not claim the change was live-reloaded or tested in a new session.
Expected: replacement admission while fewer than ten workers are active, or an actionable error explaining which non-active thread/state prevents admission. Actual: a generic limit error despite only one running worker.
This corroborates the Desktop symptom. It is an observed production sequence, not a controlled deterministic reproducer: we have not inspected internal mailbox/residency state and cannot establish whether pending mail, the
pending_initentry, or another lifecycle condition caused this occurrence. No forced cleanup/restart was performed to diagnose it.iendeavor123 commentedon Oct 1, 2026
Update (Sep 30, 2026): I tested a fresh Codex task with the current config ([agents].max_concurrent_threads_per_session = 20). It advertised a 20-thread per-session limit and ran 10 workers simultaneously alongside the root; all completed a 60-second hold. This confirms fresh-session capacity with this config. It does not establish why replacement spawns failed in the original long-lived session or prove completed-thread retention was the cause; see the original observation at #34518 (comment).