fix: background agents stall the session — adopt the CLI's own turns and let background work outlive the turn

[saucam]

What was wrong

When the model used background agents, sessions stalled.
The model would end its turn with "I'll report when they land", and then nothing happened, sometimes for minutes and once for six hours, until the owner asked "is this done?".
That message was refused with "A tool approval is pending", naming no tool.
Then a wall of text appeared under "you".

The root cause, measured live against the real Claude CLI: when a background agent finishes, the CLI runs the main agent by itself.
codeoid had no turn open to receive that, so it dropped the whole turn: the reply, the tool calls, and any approval they needed.
That dropped approval is the invisible "A tool approval is pending".
The session's status then stuck, so codeoid's own wake-up never fired.
When the wake-up did eventually fire, it ran a second, duplicate turn about the same result.

Underneath all of it: the session treated every tool call, approval and sub-agent as belonging to the current turn, and background agents outlive the turn that started them.
So besides the stall, the end of each turn also auto-denied running background agents' approvals, marked their tools "cancelled", and revoked their identities.

What changes

• Turns the CLI starts on its own are adopted. They're consumed like any other turn, so their replies, tool cards and approval prompts render.
  A short note, "↻ Continuing after background work finished", explains a turn that has no prompt.
  They act and are audited as system:background, until the owner joins one.
• Background agents live past the turn. Their tool calls between turns show up, and their approvals are visible and answerable.
  They no longer leave the session stuck.
  A turn ending doesn't deny, cancel or revoke them.
  The rule applies at every boundary: turn exit, a mid-turn message, stall recovery, provider teardown, the CLI dying, and Stop.
  Cleanup happens when the CLI reports the background work has drained, or when the CLI dies.
• No duplicate wake-up. For Claude, codeoid's own wake-up is only a fallback, sent if the CLI hasn't continued within 20 seconds.
• Stop means stop. Mid-turn it ends the turn and leaves background agents running.
  With no turn running, it stops the background work through the SDK's stopTask.
• Your message is never refused because of a background agent's pending approval.
• The wake-up renders compactly as "N background tasks finished" in the web UI and the TUI, with the full text a click away.
  Digest text is escaped, so it can't forge task rows or end the block early.

Verification

• Live, real Claude CLI, sandbox daemon:
  • Background agent finishes: the CLI's own turn is adopted and its report renders.
    There's exactly one turn and the session ends idle.
  • With codeoid's wake-up disabled, the CLI's own turn still arrives. This is what confirmed the root cause: before the fix, every event of that turn was dropped.
  • The CLI's own turn asks to use Write: the approval card appears, approval writes the file, and the session ends idle.
    This is the exact failure from real sessions.
  • Stop while idle, with a background agent running: the agent is stopped before it finishes, the session ends idle, and nothing lingers.
• Tests: 52 new or changed, across the session, provider, TUI renderer, web and core.
  Every fix was mutation-checked: each test fails with its fix reverted.
  The suites pass: daemon bun test 2670 pass, 0 fail; web 573 pass; typecheck and lint clean.
• Audit: four rounds, each with a correctness reviewer and a security reviewer.
  Every round found something, and all of it was fixed in this branch, one commit per round.
  Round 4, the cap, came back ship-with-fixes and conditional GO. Its fixes were verified with tests, mutation checks and the live runs above, not a fifth round.
• Not run: the Highflame regression suite, because codeoid isn't in it.
  The live runs above stand in for it.

Known gaps / follow-ups

• No cap on chains of self-started turns in autonomous mode.
  codeoid's old wake-up had the same shape, and the turn budget already limits autonomous mode.
• A foreground sub-agent inside a stopped turn, while unrelated background work is live, isn't swept until the background work drains.
  Its approval is withdrawn once the CLI cancels the request.
  Telling foreground and background sub-agents apart precisely needs run_in_background tracking.
• setModel and rotate don't check whether the session is busy. A session:send holder can tear down mid-turn and deny pending approvals.
  This predates the branch.
• Duplicate approval audit rows (the approver's row and the gate's row).
  This predates the branch.
• A cosmetic mislabel when the owner's message races the CLI's own continuation.

For agents: where the code is

• src/daemon/providers/interface.ts:
  • SessionScopedEvent gains background_event (tool/sub-agent lifecycle arriving with no turn) and turn_started {run}.
  • TurnRun.bindGate.
  • SessionProvider.continuesAfterBackgroundWork and stopBackgroundTasks.
  • ToolApprovalFn takes an optional AbortSignal.
• src/daemon/providers/claude/index.ts:
  • #emit: when no queue is open, #adoptTurn (see opensAdoptedTurn); otherwise #handleUndeliverable routes lifecycle events to background_event.
  • #makeTurnRun is shared.
  • The loop's finally, rebuild and hard abort each announce an empty background_tasks.
  • The PreToolUse stand-in carries agent_id.
  • stopBackgroundTasks calls Query.stopTask.
• src/daemon/session.ts:
  • Turn-only statuses: #turnActive / #setTurnStatus / #settleBetweenTurns.
  • #adoptTurn binds a system:background gate and records a user turn for the harness input.
  • #reconcileWork / #denyPendingApprovals apply keepBackground at mid-turn and turn exit; teardown, stall and drain reconcile fully.
  • #backgroundToolMsgIds tags tool calls that carry an sdkAgentId or arrive between turns.
  • #revokeSubagent waits for the registration fence.
  • #watchdogPaused ignores background approvals and counts main-agent tools in flight.
  • Self-continuing providers: a fallback timer (#armBackgroundWakeFallback), cancelled by any turn start.
  • interrupt() stops background work when idle, and leaves tool cards to turn exit when a turn is in flight.
  • #withdrawOnAbort.
  • formatDigest.
• packages/core/src/background-wake.ts: the wake parser, shared by web and TUI.
• Rendering: web/src/components/transcript/MessageRow.tsx, src/tui/ansi/render-message.ts, src/tui/components/MessageRow.tsx.
• Tests: src/tests/session-background-agents.test.ts (new) and src/tests/tui-background-wake.test.tsx (new), plus additions to provider-claude, ansi-render-message, web MessageRow and core background-wake.
• Mock: src/daemon/providers/mock/session-provider.ts gains startOwnTurn, continuesAfterBackgroundWork, boundGates and stopBackgroundTasks.

🤖 Generated with Claude Code