Agent Runner Timeout Enforcement#

The runner enforces five independent, layered time-based limits on every agent run to prevent wedged runs from holding sandboxes, mounts, and sockets indefinitely — and to avoid prematurely killing legitimate long-lived connections during human-in-the-loop (HITL) approval workflows. 1

All limits are implemented in run-limits.ts and wired into sandbox_agent.ts. The long-poll ACP transport layer is handled separately in acp-fetch.ts.

Timeout Layers#

Five distinct limits cover different failure modes 1:

Idle clamping safety: If AGENTA_RUNNER_RUN_IDLE_TIMEOUT_MS is configured at or above the total deadline, the runner automatically clamps idle to half the total and logs a warning — a misconfigured environment never breaks every run in the process. 1

How Limits Are Enforced#

All four run-scoped limits (total, idle, TTFB, per-tool-call) are managed by the RunLimitsHandle returned by createRunLimits(). When any limit trips, it fires a deadlineAbort controller that is merged with the caller's existing signal via AbortSignal.any() — the run aborts exactly as a client disconnect would, reusing the existing finally cleanup path with no new teardown logic. 1

Key wiring in sandbox_agent.ts:

• Progress tracking — The emit callback is wrapped with runLimits.wrapEmit(emit) so every harness event (message deltas, tool results, usage, etc.) resets the idle and TTFB timers. 1
• Per-tool-call tracking — noteToolCallStart(id) starts the timer on tool_call ACP updates; noteToolCallEnd(id) clears it on completed/failed status. 1
• Pause exemption — When the pause signal resolves (a turn parks for HITL input), runLimits.notePaused() freezes all timers permanently. The pause controller owns the turn's end from that point — run-limit deadlines must never reap a turn waiting on human input. 1
• Cleanup — runLimits.dispose() is called unconditionally in the finally block, marking the instance inert so no late ACP event can re-arm a timer after teardown. 1

ACP Long-Poll Timeout (HITL Keep-Alive)#

A separate problem existed before PR #4848: undici's default headersTimeout (~5 min) was killing parked ACP connections while a human deliberated on a tool approval, causing UND_ERR_HEADERS_TIMEOUT to abort the paused turn. 2

acp-fetch.ts solves this by routing all ACP HTTP through a custom undici Agent (createAcpDispatcher) scoped exclusively to ACP traffic — other HTTP clients retain their safe defaults. 2

Original defaults in PR #4848: both headersTimeout and bodyTimeout set to 0 (disabled). In PR #5148, these were changed to 60 minutes to provide an explicit backstop without interfering with legitimate HITL waits — intentionally wider than the 45-minute total deadline so they never fire first during a normal run. 1 2

keepAliveTimeout and keepAliveMaxTimeout are both set to 600,000 ms (10 min) to prevent connection pooling from closing the socket mid-park. 2

HITL Approval Parking#

When a tool requires human approval and no stored decision exists, the runner returns a park outcome (introduced in PR #4848) instead of deny, which skips sending a respondPermission reply to the harness entirely. 2 This prevents the previous bug where the deny reply's "User refused permission" error clobbered the approval prompt on the same tool_call_id. The turn ends with the tool pending; the next turn's stored decision resolves it.

This is runner-internal only — no wire protocol change to /run. 2

Key Source Files#