feat(agent): stuck/runaway guard + surface the failure behind a max_turns cap (ABCA-662)

[isadeks]

Stacked on #599 (base pr/error-classifier-hardening). The classifier changes reference ErrorClass introduced in #599, so review/merge #599 first; I'll rebase onto main once #599 lands.

What

Backports the agent-side stuck-guard subsystem from linear-vercel, plus a modest max-turns diagnostic.

1. feat(agent): stuck/runaway guard — new StuckGuard (agent/src/stuck_guard.py) that records tool results via the PostToolUse hook and detects a repeating-failing-command loop (the ABCA-483 spin).
2. fix: stuck-guard advisory-only — drop the hard bail; keep a one-time steer (preserves the K10 "no false kill" stance).
3. fix(agent): catch loop-of-variations early (ABCA-662) — a signature-agnostic trailing window (last 6 tool outcomes): when ≥5 share a byte-identical failure fingerprint across different commands, steer the agent once, mid-run.
4. max-turns terminal copy — when a max_turns cap coincides with a failure-dominated trailing window, the pipeline appends a neutral observation to the reason (last tool calls repeated: \git push` → invalid credentials`). The failure stays classified as the plain "Exceeded max turns": it surfaces what was observed and lets the reader decide — it does not re-title the run or claim more turns wouldn't help (the last 6 calls can't distinguish a hard blocker from a long task that hit a recoverable snag at the tail). The mid-run steer to the agent still coaches assertively — that's advice to the agent, not a classification of the outcome.

Conflict resolution (keep-both / partial)

• hooks.py — 4 add-vs-add interleaves with main's feat(agent): observable blocker signal + bounded self-remediation for environmental faults #251 egress-denial detection: kept both the #251 progress/egress path and the new stuck_guard recording in post_tool_use_hook.
• pipeline.py — the incoming hunk carried context from a not-included commit (8035b71, ENOSPC/OOM build_infra_failed, which depends on the unmerged feat(linear): parent/sub-issue orchestration with dependency-aware child tasks #247 build subsystem). Dropped that context; kept only the ABCA-662 stuck-summary enrichment. Verified build_infra_failed is referenced nowhere.

Test

• agent: ty clean, ruff check + ruff format --check clean, 1212 tests pass (coverage 80.83%; stuck_guard.py 89%).
• cdk: compile clean, 124 suites / 2274 tests pass, eslint --fix no mutations.

[scottschreckengaust]

Review — Principal Architect (Stack B: agent error handling, PR 2/2 · stacked on #599)

Base verified against fresh origin PR head (diffed vs #599's branch pr/error-classifier-hardening). All mandatory agents run (table below).

Verdict: Approve (with nits)

Excellent stuck/runaway-guard work. The StuckGuard catches two distinct spin shapes — a per-signature identical-failure streak (ABCA-483) and the signature-agnostic trailing-window loop-of-variations (ABCA-662: the agent retries a failing git push every which way, each getting "invalid credentials", so no single command streak grows but the window is failure-dominated). It's advisory-only by deliberate design — a false nudge costs one comment; the max_turns cap is the real backstop — and the K10 reasoning (do NOT digit-blur fingerprints, so a healthy iterate-and-fix loop with a different failing test each run reads as progress and never trips) is a subtle, correct call. Cleanly stacked on #599's ErrorClass.

Verified myself: _LAST_STUCK_SUMMARY module-global is correctly reset per-task (reset_stuck_summary() at run_task top, before hooks run — mirrors the existing blocker-latch pattern), the deferred from hooks import … is intentional (avoids a circular import, matches the pre-existing convention), and the max_turns copy stays neutral (appends an observation, makes no causal claim about whether more turns would help) — a mature UX decision.

Non-blocking suggestions / nits

• N3 (crit-8 test seam) — The max_turns reason-enrichment chain is tested only at its two pure endpoints: stuck_guard.recent_failure_summary() (unit) and the classifier consuming a hand-built string. The wiring between them is unverified — neither the pipeline.py:477 append (if err and "error_max_turns" in err: … last_stuck_summary()) nor the hooks.py:1465 latch-write is exercised end-to-end. Add a TestResolveOverallTaskStatus case monkeypatching hooks.last_stuck_summary (assert append on max_turns, no-append on a non-max_turns error, no double-append), and one driving _stuck_guard_between_turns_hook/stop_hook then asserting last_stuck_summary() — including the load-bearing "recovered → clears to None" behavior the comment claims.
• N4 (crit-6 boundary) — The window-steer boundary is untested at exactly WINDOW_FAIL_THRESHOLD (5/6): the tests straddle it at 6 (steers) and 4 (doesn't) but skip the ==5 >= edge where an off-by-one would hide. Also add "window not full" (5 identical failures in a length-5 window → no steer, since _dominant_window_failure requires a full window). Two ~3-line tests; WINDOW_FAIL_THRESHOLD isn't even imported into the test file, so nothing currently pins the constant's boundary semantics.
• N5 (cosmetic) — record_tool_result calls _looks_failed(tool_response) twice (window bookkeeping + streak); results are identical, could hoist to one call. And the window-steer's double-nudge guard keys on _last_failing_sig, so a per-signature steer + a window steer can both fire for one broad spin — benign (advisory; _window_steered still caps window steers at one).

Tests & CI

• CI: all green (title, CodeQL ×3, dead-code advisory, secrets/deps/actions, build (agentcore)); MERGEABLE.
• Coverage: stuck-guard core detection and hook integration are genuinely well-covered — the test_post_tool_use_record_error_never_blocks_screening (a guard raise must not break the fail-open screening path), test_stop_hook_steers_not_bails (advisory-only contract), test_iterating_agent_same_command_DIFFERENT_failures_never_steers (K10 false-positive guard), and the neutral-wording recent_failure_summary assertions are all high-value, behavior-not-implementation tests. Gaps are the integration seams → N3/N4.
• Bootstrap synth-coverage: N/A (Python agent code + a small classifier copy tweak; no CDK construct/stack/resource change).

Review agents run (Stage 3 — mandatory)

Agent	Ran?	Outcome
code-reviewer	✅	No blocking defects; stuck-guard streak/window logic, per-task reset, and deferred imports all verified correct.
silent-failure-hunter	✅	The three advisory swallow-paths are all appropriate fail-open: PostToolUse record_tool_result swallow can't mask screening (runs before/independent of the scanner); the between-turns swallow only disables an advisory nudge, never a safety behavior; _looks_failed unknown→success is the correct bias for an additive guard (a miss costs nothing — max_turns is the floor). No silent-failure defects.
pr-test-analyzer	✅	Core detection well-covered; integration-seam gaps → N3, boundary → N4.
type-design-analyzer	⏭️ omitted	StuckAction/_SigState are simple dataclasses; no complex invariant to analyze.
comment-analyzer	⏭️ omitted	Comment accuracy spot-checked by hand + the other agents; the neutral-observation wording is correct and well-documented.
/security-review	⏭️ omitted	No IAM/Cedar/network/secrets change; the guard previews untrusted repo output but truncates (_CMD_PREVIEW_LEN) and never executes it.

Human heuristics

• Proportionality — ✅ Deliberately minimal (advisory, no kill); matches the ABCA-483/662 incidents.
• Coherence — ✅ Mirrors existing conventions (dedup set, per-task reset, between-turns hook ordering with the cancel<stuck<nudge invariant).
• Clarity — ✅ Exemplary "why" comments, especially the K10 don't-blur-digits rationale and the neutral-observation design.
• Appropriateness — ✅ The "surface what was observed, make no causal claim" max_turns copy is a notably mature UX call.

Governance

Branch pr/agent-stuck-guard carries no issue number (ADR-003) — same item as #599; attach an approved issue + conforming branch before merge. Code is approve-ready.

Bottom line: approve-ready. N3/N4 are worthwhile follow-up tests (the integration seams and the exact window boundary), not blockers. The advisory-only design and K10 false-positive avoidance are high quality. Merge after #599 lands (stacked).

_{🤖 Generated with Claude Code}

[isadeks]

Follow-up on the N3/N4 nits — since this merged into the Stack B base branch (pr/error-classifier-hardening, #599) before I added the tests, I put them on #599 (commit 6b7cd3f) so they ride to main when #599 merges:

• N3 (crit-8 wiring seam): TestMaxTurnsStuckEnrichment in test_pipeline_outcomes.py — drives the _resolve_overall_task_status max_turns append itself (monkeypatching hooks.last_stuck_summary): appends on error_max_turns, does NOT append on a non-max_turns error, unchanged when the summary is None, and no double-append.
• N4 (crit-6 boundary): two tests in test_stuck_guard.py — steers at exactly WINDOW_FAIL_THRESHOLD (5/6 in a full window) and does NOT steer when the window isn't full yet (5 fails / length-5 history). Imports WINDOW/WINDOW_FAIL_THRESHOLD so the boundary semantics are pinned.
• N5 (cosmetic): left as-is — the double _looks_failed call and per-sig+window double-nudge are benign/advisory as you noted; not worth source churn on merged code.

All green (50 tests across the two files, ruff clean).