fix(orchestrator): grade a forced-kill timeout instead of discarding it

[joeysbase]

Summary

A structural timeout used to discard the agent's work. TaskTimeoutError / TurnTimeoutError set a status and threw the trajectory away, so a task that timed out but had already satisfied its success criteria was reported TIMEOUT. Both handlers now grade what the agent produced and finalize SUCCESS (plain, error_message cleared) when the criteria pass.

Three things ride along, each needed to make that safe:

• Antigravity's poll loop is rebounded. A poll cycle's cost is bimodal — against a backgrounded job the connection is idle and receive_steps() returns immediately (5s/cycle); against a wedged connection every re-drain burns the full 30s per-step timeout. One bound can't cover both, so _MAX_BACKGROUND_POLLS (120 × 5s = 600s) sizes the cheap mode and a new _MAX_BACKGROUND_POLL_WALL_SECONDS sizes the wedged one.
• A real TurnTimeoutError on the "nothing settled" exit, instead of silently finalizing as an ordinary COMPLETED turn — that's what gives the orchestrator's grading path a chance to run.
• CE022 generalized to a (file, function, cap) table, since this change adds two # noqa: PLR0915 sites.

Behavior change worth flagging to consumers

FinalStatus.TIMEOUT no longer means "every timed-out run". A timed-out task whose criteria pass now finalizes SUCCESS, so anything reading TIMEOUT as a proxy for "hit the wall" (dashboards, error-rate rollups) will see a shift. CLAUDE.md, docs/agents/HARNESS_PARITY.md and docs/agents/ANTIGRAVITY.md are updated to say so.

Safety properties of the grading pass

• Commits the fallback status before its first await and only ever upgrades to SUCCESS, so a BaseException mid-grade can't leave the row at the constructor default.
• Quiesces the agent first. On a TurnTimeoutError nothing has torn the harness down yet — Antigravity's kill_sync() is intent-only and _cleanup() runs later in run()'s finally — so without this the criteria could read a sandbox a backgrounded build was still writing.
• Wall-clock bounded (60s), never raises, and honors the same FIRED-ONLY early-stop gate as a normal run.
• Re-grades rather than reusing a stale snapshot. The simulation loop rewrites success_criteria_results every turn under check_criteria: every_turn, so a non-empty list alone doesn't mean the grade covers the trajectory; a _graded_iteration_count stamp gates the shortcut.

Known limitation (not fixed here)

With a configured turn_timeout, the poll deadline is 0.8 × turn_timeout measured from turn start (it has to be turn-anchored to win its race with the watchdog). At the repo default turn_timeout: 300 that's 240s — below the 300s worst backgrounded job on record. Raising it is a defaults change rather than a constants change, so it's asserted explicitly in test_background_poll_budget_still_covers_the_worst_observed_backgrounded_job: changing the default deliberately trips the test.

Testing

make verify — 4149 passed, coverage 91.68%; make lint — 340 passed.

One pre-existing failure remains, unrelated to this branch: test_effective_model_prefers_config_then_default asserts _effective_model() falls through to _DEFAULT_MODEL, which fails on any machine whose .env sets ANTIGRAVITY_MODEL (pydantic-settings reads .env). It passes in CI, which has no .env.

New coverage includes the forced-kill grading matrix (pass → SUCCESS, fail → TIMEOUT, already-graded shortcut, stale-snapshot re-grade, 60s budget expiry, CancelledError mid-grade, agent quiesce + quiesce failure), both branches of the FIRED-ONLY gate, and the poll-budget bounds.

Review

Two rounds of multi-model review (three Opus reviewers each; the multi MCP server was unavailable, so this used the documented fallback). Round 2 reviewed round 1's fixes and found three High issues in those fixes — a grading/live-agent race, a poll budget that could be zero, and a lost TIMEOUT classification under BaseException — all fixed here.

🤖 Generated with Claude Code