test: cover the max_turns-enrichment wiring seam + window-steer boundary (#600 N3/N4)

Follow-up coverage from the #600 review (feature approved as-is; tests only):

- N3 (crit-8 wiring seam): the max_turns reason-enrichment was tested only at
  its two pure endpoints (stuck_guard.recent_failure_summary + the classifier on
  a hand-built string) — the append in _resolve_overall_task_status that joins
  them was unverified. Add TestMaxTurnsStuckEnrichment (monkeypatching
  hooks.last_stuck_summary): appends on error_max_turns, does NOT append on a
  non-max_turns error, leaves the reason unchanged when there's no summary, and
  does not double-append when the summary is already present.
- N4 (crit-6 boundary): the window-steer was tested at 6/6 (steers) and 4/6
  (doesn't) but not at the exact WINDOW_FAIL_THRESHOLD `>=` edge. Add
  test_window_steers_at_exactly_the_threshold (5/6 same-fingerprint fails in a
  full window → steers) and test_no_steer_when_window_not_yet_full (5 fails in a
  length-5 history → no steer, since _dominant_window_failure requires a full
  window). Imports WINDOW/WINDOW_FAIL_THRESHOLD so the constants' boundary
  semantics are now pinned.

Full agent suite green (1218); ruff format + check clean.

Author: isadeks

agent/tests/test_pipeline_outcomes.py

@@ -161,3 +161,61 @@ def test_zero_turns_attempted_round_trips(self):
         # Zero is treated the same as None (falsy) so we don't clamp it to a
         # negative / nonsensical value.
         assert _compute_turns_completed("error_max_turns", 0, max_turns=10) == 0
+
+
+class TestMaxTurnsStuckEnrichment:
+    """N3 wiring seam (#600): _resolve_overall_task_status enriches a max_turns
+    reason with the stuck-guard summary (hooks.last_stuck_summary). Previously
+    tested only at its two pure endpoints; this drives the append itself."""
+
+    def test_max_turns_appends_stuck_summary(self, monkeypatch):
+        import hooks
+
+        summary = "last tool calls repeated: git push — invalid credentials"
+        monkeypatch.setattr(hooks, "last_stuck_summary", lambda: summary)
+        ar = AgentResult(
+            status="error_max_turns",
+            error="Agent session error (subtype=error_max_turns)",
+        )
+        _, err = _resolve_overall_task_status(ar, build_ok=False, pr_url=None)
+        assert err is not None
+        assert "error_max_turns" in err
+        assert summary in err
+
+    def test_non_max_turns_error_is_not_enriched(self, monkeypatch):
+        # A generic failure must NOT pull in the stuck summary — only max_turns.
+        import hooks
+
+        monkeypatch.setattr(hooks, "last_stuck_summary", lambda: "last tool calls repeated: X")
+        ar = AgentResult(status="error", error="receive_response() failed: boom")
+        _, err = _resolve_overall_task_status(ar, build_ok=False, pr_url=None)
+        assert err is not None
+        assert "last tool calls repeated" not in err
+
+    def test_max_turns_with_no_stuck_summary_left_unchanged(self, monkeypatch):
+        # A task that used its turns productively (window not failure-dominated →
+        # summary None) leaves the max_turns reason unchanged.
+        import hooks
+
+        monkeypatch.setattr(hooks, "last_stuck_summary", lambda: None)
+        ar = AgentResult(
+            status="error_max_turns",
+            error="Agent session error (subtype=error_max_turns)",
+        )
+        _, err = _resolve_overall_task_status(ar, build_ok=False, pr_url=None)
+        assert err == "Agent session error (subtype=error_max_turns)"
+
+    def test_stuck_summary_not_double_appended(self, monkeypatch):
+        # Idempotent: if the summary is already in the reason (e.g. a durable
+        # re-resolution of the same result), it must not be appended twice.
+        import hooks
+
+        summary = "last tool calls repeated: git push — invalid credentials"
+        monkeypatch.setattr(hooks, "last_stuck_summary", lambda: summary)
+        ar = AgentResult(
+            status="error_max_turns",
+            error=f"Agent session error (subtype=error_max_turns) — {summary}",
+        )
+        _, err = _resolve_overall_task_status(ar, build_ok=False, pr_url=None)
+        assert err is not None
+        assert err.count(summary) == 1

agent/tests/test_stuck_guard.py

@@ -4,6 +4,8 @@
 
 from stuck_guard import (
     STEER_THRESHOLD,
+    WINDOW,
+    WINDOW_FAIL_THRESHOLD,
     StuckGuard,
     _looks_failed,
     _signature,
@@ -222,3 +224,27 @@ def test_healthy_iteration_below_window_threshold_no_steer(self):
             g.record_tool_result("Bash", {"command": f"cmd {i}"}, out)
         assert g.evaluate().kind == "none"
         assert g.recent_failure_summary() is None
+
+    def test_window_steers_at_exactly_the_threshold(self):
+        # N4 boundary: exactly WINDOW_FAIL_THRESHOLD (5) same-fingerprint failures
+        # in a FULL window of WINDOW (6) — the `>=` edge where an off-by-one would
+        # hide. One OK dilutes the window to 5/6 fails, still == the threshold.
+        assert WINDOW == 6 and WINDOW_FAIL_THRESHOLD == 5  # pin the constants
+        g = StuckGuard()
+        outcomes = [OK, _ERR, _ERR, _ERR, _ERR, _ERR]  # 5 same-fp fails / full 6
+        for i, out in enumerate(outcomes):
+            g.record_tool_result("Bash", {"command": f"push {i}"}, out)
+        action = g.evaluate()
+        assert action.kind == "steer"
+        assert action.signature == "__window__"
+        assert g.recent_failure_summary() is not None
+
+    def test_no_steer_when_window_not_yet_full(self):
+        # N4 boundary: WINDOW_FAIL_THRESHOLD failures but the window has fewer than
+        # WINDOW entries — _dominant_window_failure requires a FULL window, so 5
+        # identical failures in a length-5 history must NOT steer yet.
+        g = StuckGuard()
+        for i in range(WINDOW_FAIL_THRESHOLD):  # 5 fails, window not yet at 6
+            g.record_tool_result("Bash", {"command": f"push {i}"}, _ERR)
+        assert g.evaluate().kind == "none"
+        assert g.recent_failure_summary() is None