feat(runtime): stop a turn on the clock as well as the step count

[mangit955]

Implements #60 (already closed). ADR committed alongside the code at docs/adr/0001-wall-clock-budget-for-the-agent-loop.md.

Why

The loop has only ever measured its budget in iterations while the harness enforces a wall clock. make-mips-interpreter was killed by its own 200th iteration at 406s of an 1800s budget, mid-work, with exception_info: null proving Harbor's timeout never fired. Across the five-task config every trial spent 2–23% of the time it was given.

What

• runtime/deadline.ts — module singleton in the shape of runtime/sandbox/registry.ts. WALL_RESERVE_SEC = 60 held back so the last step, the final answer and the session write land before the harness kills the process. The clock is injectable, which is how elapsed time is tested without stubbing Date globally.
• runtime/loop.ts — BudgetExhaustedError base with IterationBudgetExhaustedError and a new WallBudgetExhaustedError as siblings; WOOPCODE_MAX_WALL_SEC read once per turn; the deadline checked at the top of an iteration, inside the try, so it takes the same onError-then-rethrow path.
• The wind-down is unified. Remaining time ÷ the turn's own measured wall-per-iteration gives a step count, so one message and one flag serve both budgets.
• commands/agent.tsx — one instanceof BudgetExhaustedError in place of two, so both budgets exit 2. A distinct code would be booked as an exception by any harness not yet updated to know it.

onBudgetExhausted is deliberately not consulted for the deadline: the step ceiling can afford to ask because iterations do not tick while a human thinks, and a clock does.

Behaviour change

The wind-down flag replaces an equality test that silently never fired when the ceiling was below five steps — the turns with least room were the ones told nothing. A two-step budget is now announced at its first step. iterationBudget.test.ts was updated to assert the new behaviour.

Verification

• bun run verify --all — 4 gates passed (docs lint, docs surface, type check, tests).
• bun run replay:baseline — byte-identical before and after, across all ten fixtures and the corpus totals. Expected: this decides when a turn stops, not what the prompt carries.
• Six mutations applied, confirmed present in the file, run red, then restored: the deadline throw (3 fail), clearDeadline in finally (1), the wind-down reset (1), the wall term in stepsRemaining (3), the reserve subtraction (11), the clamp floor (1). The first disarm test survived its mutation and was rewritten to assert remainingMs() directly.
• Reverse-order sweep and each affected file in isolation, both green.

Not checked: a live Harbor run, a live provider, interactive TUI input.

Deferred, and load-bearing

This makes the failure fixable, not fixed. Both of these are needed before it stops happening:

• Clamp tool timeouts to the remaining wall budget #61 — nothing clamps tool timeouts yet, so the deadline is advisory for a command already running. run_terminal's 300s default is 40% of overfull-hbox's budget.
• Wire the wall budget through Harbor, and correct CLAUDE.md #62 — nothing sets the variable in agent.py or job.yaml, so no benchmark run gets a wall budget. CLAUDE.md's contradictory "Wall clock is the binding budget, not iterations" line is Wire the wall budget through Harbor, and correct CLAUDE.md #62's to correct.

Two things a reviewer should weigh

Both were raised in review and left as the ADR decided them, rather than redesigned here:

1. WOOPCODE_MAX_WALL_SEC in a .env would break the TUI. Bun auto-loads .env, the deadline anchors to process start, and the interactive path skips onBudgetExhausted — so after the budget elapses every turn throws before its first request, with no checkpoint. The ADR's reasoning rests on "the interactive path will not have the variable set," which the code does not enforce.
2. meanStepMs is a whole-turn mean and the warning flag is permanent. One slow step can tell the model to wrap up while plenty of budget remains, and it is never taken back. It nudges rather than ends the turn.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
woop-code	Ready	Preview	Aug 30, 2026 3:53am