@miller-tech/uap 2.16.6 → 2.19.5

package/tools/agents/scripts/anthropic_proxy.py

@@ -64,6 +64,37 @@ Configuration (Environment Variables)
                                     conversation pruning activates (0.0-1.0)
                                     Default: 0.85
 
+    PROXY_PRUNE_SPIRAL_STREAK       Consecutive above-threshold prunes with a
+                                    RISING post-prune floor required before the
+                                    prune circuit breaker fires. A tool-heavy
+                                    client's fixed overhead (system + tool
+                                    schemas) can sit above the threshold
+                                    permanently; a flat floor is NOT a death
+                                    spiral. Default: 3
+
+    PROXY_PRUNE_SPIRAL_EPSILON      Minimum post-prune utilization rise
+                                    (fraction of window, e.g. 0.01 = 1 point)
+                                    for a prune to count toward the spiral
+                                    streak. Default: 0.01
+
+    PROXY_FINAL_ANSWER_CHARS         Content reaching this many characters
+                                    is a legitimate final answer: the
+                                    unexpected-end-turn retry is skipped
+                                    and the client's loop ends naturally,
+                                    a `required` tool turn returning such
+                                    content is exempt from the
+                                    required_tool_miss streak, retries, and
+                                    forced-tool dampener, and the
+                                    recon-convergence no-write streak does
+                                    not advance on it (a finished model's
+                                    summary is a completion, not a miss).
+                                    Content matching the deferral
+                                    phrases stays retried even when long —
+                                    a capitulation is not a final answer.
+                                    Env alias: PROXY_END_TURN_FINAL_CHARS
+                                    (deprecated spelling, same knob).
+                                    0 = always retry. Default: 800
+
 Usage
 -----
     # Basic usage (connects to llama.cpp on default port):
@@ -299,6 +330,54 @@ PROXY_CONTEXT_WINDOW = int(os.environ.get("PROXY_CONTEXT_WINDOW", "0"))
 PROXY_CONTEXT_PRUNE_THRESHOLD = float(
     os.environ.get("PROXY_CONTEXT_PRUNE_THRESHOLD", "0.85")
 )
+# Prune circuit-breaker floor-trend discrimination (2026-09-30): a tool-heavy
+# client's FIXED overhead (system prompt + tool schemas — observed live:
+# opencode's 99 tools ≈ 66k est tokens in a 114,688-token window) can sit
+# permanently ABOVE PROXY_CONTEXT_PRUNE_THRESHOLD (0.42 in production), so
+# post-prune utilization can never get below the threshold no matter how many
+# messages are dropped. The breaker's old condition — "3+ consecutive prunes
+# and still above threshold" — read that permanent flat floor as a death
+# spiral and force-finalized healthy ~44% sessions every few turns (observed
+# live: 8 breaker fires in 10 minutes, each one ending the client's turn; the
+# operator symptom was "the client keeps stopping"). A REAL death spiral shows
+# a RISING post-prune floor turn over turn; a fixed-overhead floor is flat.
+# The breaker now fires only after PROXY_PRUNE_SPIRAL_STREAK consecutive
+# above-threshold prunes whose post-prune utilization rose by more than
+# PROXY_PRUNE_SPIRAL_EPSILON (fraction of the window). Slow sub-epsilon
+# spirals do not trip this breaker; they escalate to the >=90% critical
+# prune and the catastrophic raw-ctx finalize backstops instead.
+PROXY_PRUNE_SPIRAL_STREAK = int(
+    os.environ.get("PROXY_PRUNE_SPIRAL_STREAK", "3")
+)
+PROXY_PRUNE_SPIRAL_EPSILON = float(
+    os.environ.get("PROXY_PRUNE_SPIRAL_EPSILON", "0.01")
+)
+# Substantive-final-answer exemption for the unexpected-end-turn retry
+# (2026-10-03): the retry exists for thinking-runaway stalls — an end_turn
+# with EMPTY or near-empty content mid-loop (reproduced 2026-09-17: 5917
+# reasoning chars, finish=length, 0 tool_calls). It had NO completion signal,
+# so a model that GENUINELY finished and wrote its final answer was also
+# "unexpected": the retry coerced it back into a tool call, and a finished
+# model under coercion emits a degenerate no-op call (observed live
+# 2026-10-03 01:00-03:00: "Task complete — recap delivered and one concrete
+# defect fixed", 2211 chars, followed by 96 retry cycles each producing the
+# identical `git status` no-op — two hours of churn the operator saw as
+# "keeps stopping or looping"). Content reaching this many characters is a
+# legitimate final answer: let the client's loop end. The runaway case has
+# empty content, so the threshold separates the two classes cleanly. The
+# threshold now gates a family of exemptions — the end-turn retry, the
+# stream-path malformed-streak counter, the required-tool-miss classification
+# (2026-10-03 13:24-13:40 incident), and the recon-convergence no-write streak
+# — hence the rename from PROXY_END_TURN_FINAL_CHARS (still accepted as a
+# deprecated env alias). 0 restores the old always-retry behavior.
+PROXY_FINAL_ANSWER_CHARS = int(
+    os.environ.get("PROXY_FINAL_ANSWER_CHARS")
+    or os.environ.get("PROXY_END_TURN_FINAL_CHARS")
+    or "800"
+)
+# Deprecated alias (2026-10-03): existing env files and older tooling still
+# use the end-turn spelling; both knobs control the same threshold.
+PROXY_END_TURN_FINAL_CHARS = PROXY_FINAL_ANSWER_CHARS
 # Verbatim decision compaction (uplift 1.2): when context pressure triggers a
 # prune, first try per-tool-call keep/truncate/drop decisions that keep all
 # retained content VERBATIM; fall back to the lossy breadcrumb pruner only
@@ -1748,6 +1827,21 @@ try:
     )
 except ValueError:
     PROXY_STREAM_HEARTBEAT_SECS = 0.0
+# Journal progress cadence for the same buffered wait. The heartbeat keeps the
+# CLIENT alive; this keeps the OPERATOR alive: a no-tool streaming turn served
+# via the guarded path (confidence-escalation buffering, tools-stripped breaker
+# turns, forced non-stream) can generate for minutes with zero journal output —
+# live 2026-10-04, opencode's client-side compaction summary (msgs=1, tools=0,
+# stream=True) buffered 11,099 output tokens over 281 s: the proxy looked idle,
+# the client looked hung, and nothing in the log distinguished a bug from a
+# long generation until the RESP line finally landed. One INFO line per this
+# many seconds of waiting. 0 disables.
+try:
+    PROXY_GUARDED_WAIT_LOG_SECS = float(
+        os.environ.get("PROXY_GUARDED_WAIT_LOG_SECS", "60")
+    )
+except ValueError:
+    PROXY_GUARDED_WAIT_LOG_SECS = 60.0
 PROXY_FORCED_TOOL_DAMPENER = os.environ.get(
     "PROXY_FORCED_TOOL_DAMPENER", "on"
 ).lower() not in {
@@ -2410,6 +2504,14 @@ class SessionMonitor:
     pre_prune_input_tokens: int = 0
     prune_count: int = 0  # How many times pruning was triggered
     overflow_count: int = 0  # How many context overflow errors caught
+    # Prune circuit-breaker floor trend (2026-09-30): consecutive
+    # above-threshold prunes whose post-prune utilization ROSE (a real death
+    # spiral regrows faster than the pruner can cut), and the last post-prune
+    # utilization seen, to compute the delta. A flat floor is fixed overhead,
+    # not a spiral — see _prune_breaker_should_fire.
+    prune_spiral_streak: int = 0
+    last_post_prune_util: float = -1.0
+    prune_floor_logged: bool = False  # one-shot "floor is flat" operator notice
     # Monotonic: # of oldest middle msgs pruned (B3). Only meaningful for
     # legacy lossy-path turns — a successful verbatim compaction (uplift 1.2)
     # re-indexes the middle non-contiguously and RESETS this to 0, since a
@@ -2457,7 +2559,7 @@ class SessionMonitor:
     session_id: str = ""  # owning session id (set by get_session_monitor)
     mandate_deliver_fires: int = 0  # monotonic count of forced deliver-routings (mandate)
     mandate_deliver_active: bool = False  # THIS turn is pinned to deliver (beats recon convergence)
-    tool_starvation_streak: int = 0  # Consecutive forced turns with no tool_calls produced
+    tool_starvation_streak: int = 0  # breaker FIRES since the last compaction reset (not per turn)
     last_request_msg_count: int = 0  # Message count of the previous request (compaction-boundary detection)
     malformed_tool_streak: int = 0  # consecutive malformed pseudo tool payloads
     invalid_tool_call_streak: int = 0  # consecutive invalid tool arg payloads
@@ -2494,6 +2596,15 @@ class SessionMonitor:
     # back into a structured tool_use, which would continue the very loop the
     # breaker is ending. Reset to False at the start of every request.
     suppress_text_tool_extraction: bool = False
+    # Bounded snippet of the most recent tool_result text seen in the request.
+    # Feeds the STUCK-BREAK repeat-call directive so the model is SHOWN the
+    # unchanged output instead of only being told it "already has" it — live
+    # 2026-09-29, a model re-ran `uap memory query "plane workspace slug pay2u"`
+    # 7 times ignoring the directive, because a "No results" output is not an
+    # answer a weak model recognises as final; it believes the missing value
+    # must exist and keeps re-asking. Quoting the output makes the futility
+    # concrete. Refreshed on every request from the conversation.
+    last_tool_result_snippet: str = ""
     # Tool-turn count at which the TURN-COUNT FINALIZE BREAKER last fired. The
     # count is derived from the (only-growing) conversation, so without this the
     # breaker would re-fire on EVERY turn once the ceiling is first crossed —
@@ -3029,6 +3140,61 @@ class SessionMonitor:
         """Highest current streak among malformed/invalid tool outputs."""
         return max(self.malformed_tool_streak, self.invalid_tool_call_streak)
 
+    def reset_forcing_loop(self) -> None:
+        """Reset the forcing-loop family to a clean per-turn baseline.
+
+        2026-10-04 follow-up to the starvation-breaker fix (PR #830): the
+        membership of this family lives HERE, not in four hand-maintained
+        reset blocks (fresh user text, no-tool-result conversations, the
+        compaction boundary, the contamination hard reset). Members and why:
+
+          consecutive_forced_count, no_progress_streak -- the forcing loop
+          is PER-TURN state; a stale count crossing a fresh user text
+          false-fired the TOOL STARVATION BREAKER ~once per user turn for
+          hours (fixed 2026-10-04).
+
+        Deliberately NOT members (each with its own lifecycle):
+          consecutive_no_write_turns -- PER-TASK state (recon exploration
+          streak), reset at the same four boundary sites INLINE, not here:
+          it is not forcing-loop state, and an ack-shaped fresh text must
+          not clear it (see the fresh_user_text branch). Its four reset
+          sites and rationale are documented at those sites.
+          malformed/invalid/required_tool_miss streaks -- output QUALITY is
+          cross-turn evidence; a new user message says nothing about the
+          model's tool-call formatting.
+          forced_auto_cooldown_turns -- the dampener is a REMEDY for the
+          quality streaks, and quality is cross-turn, so the cooldown
+          carries across mid-episode user acks ("keep going" must not cut
+          the recovery window short). It also cannot re-arm right after a
+          reset: activation needs consecutive_forced_count >= min_forced,
+          which the reset just zeroed. It clears only at a brand-new
+          conversation (the n_msgs <= 1 block) and the emergency
+          contamination reset.
+          deferral_streak -- the capitulation loop it breaks SPANS user
+          acks (model asks for more cycles, user says yes, model asks
+          again), so a per-turn reset would make that breaker unreachable
+          in exactly its true-positive case.
+          tool_starvation_streak -- per-EPOCH session telemetry: counts
+          breaker fires since the last compaction reset (the compaction
+          boundary clears it), not per-turn severity.
+          recon_hard_fires -- monotonic session counter, never reset.
+          catastrophic_ctx_streak -- consecutive-turn utilization streak;
+          resets the moment utilization drops below the finalize ratio,
+          so it is per-turn-consecutive, not monotonic.
+
+        Two more semantic classes reset the member pair INLINE by design,
+        and a grep for "consecutive_forced_count = 0" will find them:
+        consequence/consume-on-fire clears (breaker fire, dampener
+        release, finalize paths, analysis routing) zero the pair after an
+        ACTION was taken, which is a different event from a boundary reset.
+        And the four boundary call sites here are gated behind
+        PROXY_TOOL_STATE_MACHINE (pre-existing posture, unchanged): with
+        the state machine off, the consumers still run and the stale-state
+        false-fire class returns.
+        """
+        self.consecutive_forced_count = 0
+        self.no_progress_streak = 0
+
     def consume_forced_auto_turn(self) -> bool:
         """Consume one dampener turn that temporarily sets tool_choice=auto."""
         if self.forced_auto_cooldown_turns <= 0:
@@ -3520,6 +3686,39 @@ def _prune_overhead_tokens(anthropic_body: dict) -> int:
     return int(overhead_tokens * 1.5)  # Safety factor for template overhead
 
 
+def _prune_breaker_should_fire(post_util: float, monitor) -> bool:
+    """Death-spiral discriminator for the prune circuit breaker (2026-09-30).
+
+    Called once per request AFTER all prune passes, with the post-prune
+    utilization. Updates the monitor's floor-trend streak and returns whether
+    the breaker should fire.
+
+    Why trend, not just "still above threshold": a tool-heavy client's fixed
+    overhead (system + tool schemas; observed: ~66k est tokens of a 114,688
+    window against a 42% threshold) puts the post-prune floor PERMANENTLY
+    above the threshold. The old breaker condition (3+ consecutive prunes and
+    still above threshold) fired every few turns on that flat floor, forcing
+    finalize on healthy ~44% sessions — the operator-visible "the client
+    keeps stopping". A real death spiral (auto-compact transcript regrowth,
+    exploding tool results) shows a post-prune floor that RISES turn over turn
+    even as the pruner cuts; only that counts. Flat or falling floors reset
+    the streak.
+    """
+    prev = monitor.last_post_prune_util
+    monitor.last_post_prune_util = post_util
+    if post_util < PROXY_CONTEXT_PRUNE_THRESHOLD:
+        # Back under the threshold (real headroom recovered): reset the trend.
+        monitor.prune_spiral_streak = 0
+        return False
+    if prev >= 0 and post_util > prev + PROXY_PRUNE_SPIRAL_EPSILON:
+        monitor.prune_spiral_streak += 1
+    else:
+        # Flat (within epsilon), falling, or the first observation above the
+        # threshold: not spiral evidence.
+        monitor.prune_spiral_streak = 0
+    return monitor.prune_spiral_streak >= PROXY_PRUNE_SPIRAL_STREAK
+
+
 def _truncate_oversized_message_content(messages: list, budget_tokens: int) -> bool:
     """Truncate the largest message content in-place until the total fits
     budget_tokens. Used when message-DROPPING cannot reduce below the window —
@@ -6828,10 +7027,35 @@ def _resolve_state_machine_tool_choice(
     if latest_user_text and not last_user_has_tool_result:
         monitor.tool_call_history = []
         monitor.reset_doubling()
+        # 2026-10-04 fix (recurring false TOOL STARVATION BREAKER, fired ~once
+        # per user turn for hours): the forcing loop is PER-TURN state. The
+        # family membership and each member's lifecycle live in
+        # SessionMonitor.reset_forcing_loop -- reset there, never here.
+        monitor.reset_forcing_loop()
+        # The recon exploration streak is PER-TASK, not per-turn (added
+        # 2026-10-04 with the reset_forcing_loop extraction): the previous
+        # task's read-forever streak is not evidence about the NEW
+        # deliverable, and a stale streak fired the recon convergence
+        # directive on the new task's first request -- the same
+        # stale-state-crossing-a-boundary class as the breaker fix above.
+        # Agent-driven resends carry tool_results and cannot reach this
+        # branch, so genuine same-task recon loops keep counting. One
+        # accepted trade-off: a MID-TASK human ack ("ok", "standing by")
+        # also lands here and would clear a same-task streak — so the
+        # existing _is_no_task_user_text classifier gates the reset: only
+        # fresh text that plausibly starts NEW work clears the streak.
+        # Reviewer P3 (security, 2026-10-04): without the gate, a model
+        # could end each threshold-1 turn soliciting an ack and keep the
+        # convergence directive unreachable forever.
+        if not _is_no_task_user_text(latest_user_text):
+            monitor.consecutive_no_write_turns = 0
         if n_msgs <= 1:
+            # Brand-new conversation only. forced_auto_cooldown_turns is
+            # sticky across mid-episode acks on purpose (see
+            # reset_forcing_loop's docstring) but a 1-message request is a
+            # fresh conversation surface, where the old cooldown describes
+            # a model state that no longer applies.
             monitor.forced_auto_cooldown_turns = 0
-            monitor.consecutive_forced_count = 0
-            monitor.no_progress_streak = 0
             monitor.malformed_tool_streak = 0
             monitor.invalid_tool_call_streak = 0
             monitor.required_tool_miss_streak = 0
@@ -6861,10 +7085,24 @@ def _resolve_state_machine_tool_choice(
         if not has_tool_results:
             monitor.tool_call_history = []
             monitor.reset_doubling()
+            # Same per-turn reset as fresh_user_text (see the 2026-10-04 fix
+            # there, and SessionMonitor.reset_forcing_loop for the family
+            # membership): a conversation with no tool results cannot host a
+            # MID-LOOP starvation episode -- genuine ones resend with
+            # tool_results and never reach this branch -- so a stale forcing
+            # count from a prior turn carries no signal here, only the
+            # false-fire. The recon streak resets under the same ack gate as
+            # fresh_user_text (latest_user_text is empty in most
+            # no-tool-result conversations, and an empty text is not an ack,
+            # so the gate usually passes here). Output-quality streaks stay
+            # sticky under the n_msgs guard.
+            monitor.reset_forcing_loop()
+            if not _is_no_task_user_text(latest_user_text):
+                monitor.consecutive_no_write_turns = 0
             if n_msgs <= 1:
+                # Brand-new conversation only (see the fresh_user_text
+                # branch for why the cooldown is otherwise sticky).
                 monitor.forced_auto_cooldown_turns = 0
-                monitor.consecutive_forced_count = 0
-                monitor.no_progress_streak = 0
                 monitor.malformed_tool_streak = 0
                 monitor.invalid_tool_call_streak = 0
                 monitor.required_tool_miss_streak = 0
@@ -7265,15 +7503,27 @@ def _maybe_inject_stuck_break(openai_body: dict, monitor: "SessionMonitor") -> N
     if reason.startswith(_REPEAT_CALL_REASON):
         # The call SUCCEEDS every time, so "stop retrying a failing action" and
         # the switch-channel advice would both be nonsense here. Name the real
-        # problem: the answer is already in hand and re-asking cannot change it.
+        # problem: the answer is already in hand and re-asking cannot change
+        # it. QUOTE the actual output — live 2026-09-29, "You already have that
+        # output" was ignored 7 times on a `uap memory query` returning "No
+        # results": the model does not recognise an empty result as an answer,
+        # so the directive must show it that the output IS the output.
+        snippet = (monitor.last_tool_result_snippet or "").strip()
+        quoted = (
+            f' It returns EXACTLY this every time: "{snippet[:300]}"' if snippet else ""
+        )
         directive = (
             "\n\nSTOP — you have issued the same tool call with the same "
             "arguments " + reason.rsplit("x", 1)[-1] + " times in a row. It "
             "SUCCEEDED each time and the result will not change by asking again. "
-            "You already have that output. Do NOT repeat it. Either take the "
-            "NEXT concrete action using what it told you, or — if you genuinely "
-            "cannot proceed — state the single blocking question in one sentence "
-            "and stop. Answer in plain text now if the work is done."
+            "You already have that output." + quoted + " Do NOT repeat it — "
+            "re-asking cannot produce new information, and an empty or "
+            "'no results' output IS this source's final answer. Either take the "
+            "NEXT concrete action using what it told you (proceeding WITHOUT "
+            "the missing information and stating your assumption if necessary), "
+            "or — if you genuinely cannot proceed — state the single blocking "
+            "question in one sentence and stop. Answer in plain text now if "
+            "the work is done."
         )
     else:
         directive = (
@@ -8636,7 +8886,7 @@ def build_openai_request(
             monitor.no_progress_streak = 0
             monitor.reset_tool_turn_state(reason="tool_starvation_breaker")
             logger.warning(
-                "TOOL STARVATION BREAKER: stripped tools after %d forced turns with no tool output (starvation_streak=%d)",
+                "TOOL STARVATION BREAKER: stripped tools after %d forced turns with no tool output (starvation_streak=%d; the streak counts fires since the last compaction reset, not per-turn severity)",
                 PROXY_TOOL_STARVATION_THRESHOLD,
                 monitor.tool_starvation_streak,
             )
@@ -9093,16 +9343,21 @@ def _record_last_assistant_tool_calls(
                     _latest_err = any(_flags)
                 break
     monitor.note_tool_result_error(_latest_tr, _latest_err)
+    # Bounded raw snippet of the same result, for the STUCK-BREAK repeat-call
+    # directive (see SessionMonitor.last_tool_result_snippet).
+    monitor.last_tool_result_snippet = (_latest_tr or "")[:400]
     _seed_tool_history_from_request(monitor, messages)
     tool_fingerprints = []
     tool_targets: dict[str, str] = {}
     assistant_had_text = False  # Fix B: did the last assistant turn emit prose?
+    assistant_prose = ""  # raw text of that prose, for the completion gate
     for msg in reversed(messages):
         if msg.get("role") != "assistant":
             continue
         content = msg.get("content")
         if isinstance(content, str) and content.strip():
             assistant_had_text = True
+            assistant_prose = content
         if isinstance(content, list):
             for block in content:
                 if (
@@ -9111,6 +9366,11 @@ def _record_last_assistant_tool_calls(
                     and str(block.get("text", "")).strip()
                 ):
                     assistant_had_text = True
+                    # Accumulate, never overwrite: a completion split across
+                    # several sub-threshold text blocks is still one
+                    # completion (parity with _final_answer_content_exempt's
+                    # own list handling, which joins text parts).
+                    assistant_prose += str(block.get("text", ""))
                 if isinstance(block, dict) and block.get("type") == "tool_use":
                     tool_fingerprints.append(_tool_call_fingerprint(block))
                     # Extract target key for read-only dedup (Option 3)
@@ -9141,8 +9401,12 @@ def _record_last_assistant_tool_calls(
     # Fix B: no tool call in the last assistant turn. A plain-text turn is still
     # a non-write turn, so advance the recon-convergence streak (previously it
     # only moved on tool turns, freezing the counter through prose-only stalls).
-    # Guard on real prose so an empty/absent assistant turn never inflates it.
-    if assistant_had_text:
+    # Guard on real prose so an empty/absent assistant turn never inflates it —
+    # EXCEPT a substantive final answer (architect follow-up 2026-10-03): a
+    # finished model's completion is not a stall signal, and counting it was
+    # the last site in the false-positive family that treats a completion as a
+    # miss. Same gate as the end-turn and required-miss exemptions.
+    if assistant_had_text and not _final_answer_content_exempt(assistant_prose):
         monitor.note_no_tool_turn()
     monitor.note_doubling_signal(
         "", _latest_tr, msg_count=len(messages), result_error=_latest_err
@@ -9150,6 +9414,77 @@ def _record_last_assistant_tool_calls(
     return ""
 
 
+def _final_answer_content_exempt(content) -> bool:
+    """True when an end_turn's content is a substantive final answer.
+
+    Shared by the unexpected-end-turn classifier (skip the retry so the
+    client's loop ends naturally), the stream-path malformed_tool_streak
+    counter (a legitimate completion must not feed the forced-tool dampener
+    via the `end_turn + long text` branch), and the required-tool-miss
+    classifier (a finished model's summary is a completion, not a miss).
+    2026-10-03.
+    """
+    if PROXY_FINAL_ANSWER_CHARS <= 0:
+        return False
+    if not isinstance(content, str):
+        # OpenAI content-parts list: count only the text parts, never the
+        # repr of the list (which would always exceed the threshold). A
+        # part whose "text" is not a str is skipped, not joined — a
+        # malformed backend payload must not abort the turn with a
+        # TypeError mid-classification.
+        if not isinstance(content, list):
+            return False
+        content = " ".join(
+            part.get("text", "")
+            for part in content
+            if isinstance(part, dict)
+            and isinstance(part.get("text", ""), str)
+        )
+    if len(content.strip()) < PROXY_FINAL_ANSWER_CHARS:
+        return False
+    # BUT a LONG DEFERRAL is not a final answer: a model that wrote 800+ chars
+    # of "I need more cycles before acting" is stalling, not finishing, and
+    # must still be herded back to work. The deferral regex already exists
+    # (and already accepts its false-positive risk on no-tool turns), so the
+    # exemption is gated on it rather than on new vocabulary.
+    return not _DEFERRAL_PHRASE_RE.search(content)
+
+
+def _required_tool_miss_exempt(openai_resp: dict) -> bool:
+    """True when a required tool turn returned no tool calls but the response
+    is a substantive final answer, not a miss.
+
+    Same false-positive family as the unexpected-end-turn retry (mechanism #3)
+    and the garbled-args classifier (mechanism #4), observed live
+    2026-10-03 13:24-13:40: the tool state machine had forced
+    tool_choice=required for 32 consecutive turns; the model had FINISHED the
+    task (session summaries, "234 tests passing") and kept emitting exactly
+    that. Each summary was counted as required_tool_miss, retries demanded a
+    tool call, the streak fed the contamination breaker (3 resets), and the
+    forced-finalize branch — which clears malformed/invalid streaks but did
+    not clear required_tool_miss_streak — re-fired finalize on EVERY
+    subsequent request (contamination_resets 3→6, ~4 min of GPU burn) until
+    the client gave up. A finished model must be allowed to hand its summary
+    to the client: the loop ends naturally, exactly as with the end-turn
+    exemption.
+    """
+    if _openai_has_tool_calls(openai_resp):
+        return False
+    # A response truncated by max_tokens did not FINISH — its length says
+    # nothing about intent, and the truncation paths (truncated_tool_args
+    # downgrade, empty-max-tokens recovery) own that class. Mirrors
+    # _is_unexpected_end_turn, which only accepts stop/end_turn finishes.
+    choice, _ = _extract_openai_choice(openai_resp)
+    if (choice.get("finish_reason") or "").lower() == "length":
+        return False
+    # Pass the RAW content (not _openai_message_text, whose str() fallback
+    # would stringify a list-parts content to its repr and defeat
+    # _final_answer_content_exempt's count-only-text-parts guard — a 400-char
+    # list payload measured as a 700-char repr). Mirrors _is_unexpected_end_turn.
+    _, message = _extract_openai_choice(openai_resp)
+    return _final_answer_content_exempt(message.get("content", ""))
+
+
 def _is_unexpected_end_turn(openai_resp: dict, anthropic_body: dict) -> bool:
     choices = openai_resp.get("choices") or []
     if not choices:
@@ -9167,6 +9502,16 @@ def _is_unexpected_end_turn(openai_resp: dict, anthropic_body: dict) -> bool:
     if "tools" not in anthropic_body:
         return False
 
+    # Substantive-final-answer exemption (2026-10-03): an end_turn that CARRIES
+    # a real final answer is the agentic loop's natural end, not a stall. The
+    # thinking-runaway this retry exists for produces empty content, so content
+    # length separates the classes. Without this, a finished model gets coerced
+    # back into a degenerate no-op tool call every turn (observed live:
+    # "Task complete ... Summary:" 2211 chars -> 96 retry cycles of the
+    # identical `git status` no-op over two hours).
+    if _final_answer_content_exempt(msg.get("content", "")):
+        return False
+
     has_tool_results = _conversation_has_tool_results(anthropic_body)
 
     return has_tool_results or _last_assistant_was_text_only(anthropic_body)
@@ -10056,16 +10401,14 @@ def _is_garbled_tool_arguments(arguments_str: str) -> bool:
     """Detect garbled/degenerate tool call arguments.
 
     Returns True if the arguments string shows signs of degenerate generation:
-    - Runaway closing braces (}}}}})
-    - Repetitive digit patterns (000000, 398859738398859738)
-    - Extremely long digit strings
-    - Unbalanced braces suggesting truncated/corrupt JSON
+    - Repetitive digit patterns (000000, 398859738398859738) and long digit
+      runs (degenerate CONTENT, meaningful even inside valid JSON values)
+    - Structural corruption — runaway closing braces (}}}}}) and unbalanced
+      braces — only when the payload does not parse as JSON
     """
     if not arguments_str or arguments_str == "{}":
         return False
 
-    if _GARBLED_RUNAWAY_BRACES_RE.search(arguments_str):
-        return True
     if _GARBLED_REPETITIVE_DIGITS_RE.search(arguments_str):
         return True
     if _GARBLED_ZEROS_RE.search(arguments_str):
@@ -10073,11 +10416,31 @@ def _is_garbled_tool_arguments(arguments_str: str) -> bool:
     if _GARBLED_LONG_DIGITS_RE.search(arguments_str):
         return True
 
-    # Check brace balance — more than 2 unmatched braces suggests corruption
-    open_count = arguments_str.count("{")
-    close_count = arguments_str.count("}")
-    if abs(open_count - close_count) > 2:
-        return True
+    # Structural checks — ONLY meaningful for a payload that does not parse
+    # as JSON: a clean json.loads proves the arguments are not truncated, and
+    # braces inside JSON string VALUES are payload content, not structure.
+    # edit/write tool args legitimately carry partial code excerpts with
+    # unbalanced braces (observed live 2026-10-03: a Rust tail snippet with
+    # 3 closing braces and no opening braces in oldString tripped the raw
+    # balance check on a perfectly valid payload; the reject-retry loop that
+    # followed burned three session-contamination resets and a forced
+    # finalize mid-task). Runaway `}}}}}` gets the same gate: four or more
+    # consecutive closing braces are common inside minified JS/JSON string
+    # values, while the classic degenerate form (runaway closers appended
+    # after the JSON) does not parse and is still caught here.
+    try:
+        json.loads(arguments_str)
+    except (ValueError, TypeError, RecursionError):
+        # Unparseable: brace imbalance and runaway closers are genuine
+        # truncation/corruption signals here. RecursionError covers deeply
+        # nested degenerate input (the exact artifact family this classifier
+        # absorbs) that the C scanner rejects without raising ValueError.
+        if _GARBLED_RUNAWAY_BRACES_RE.search(arguments_str):
+            return True
+        open_count = arguments_str.count("{")
+        close_count = arguments_str.count("}")
+        if abs(open_count - close_count) > 2:
+            return True
 
     return False
 
@@ -10349,6 +10712,11 @@ class ToolResponseIssue:
     kind: str = ""
     reason: str = ""
     retry_hint: str = ""
+    # True when the response was exempted from required_tool_miss by the
+    # substantive-completion gate — set by _classify_tool_response_issue so
+    # the streak/dampener/retry sites read ONE evaluation instead of re-running
+    # the gate and risking site drift (2026-10-03, code-review follow-up).
+    exempt: bool = False
 
     def has_issue(self) -> bool:
         return bool(self.kind)
@@ -11171,6 +11539,14 @@ def _classify_tool_response_issue(
     has_tool_calls = _openai_has_tool_calls(openai_resp)
     if not has_tool_calls:
         if required_tool_choice:
+            # Substantive-final-answer exemption (2026-10-03): a required turn
+            # that carries a real completion is the loop's natural end, not a
+            # miss — see _required_tool_miss_exempt. Passing it through lets
+            # the client finish instead of retrying the model into the
+            # contamination breaker. exempt=True carries the single evaluation
+            # to the streak/dampener/retry sites.
+            if _required_tool_miss_exempt(openai_resp):
+                return ToolResponseIssue(exempt=True)
             return ToolResponseIssue(
                 kind="required_tool_miss",
                 reason="required tool turn returned no tool calls",
@@ -11924,16 +12300,24 @@ async def _apply_malformed_tool_guardrail(
 
     required_tool_choice = openai_body.get("tool_choice") == "required"
     has_tool_calls = _openai_has_tool_calls(working_resp)
-    if required_tool_choice and not has_tool_calls:
-        monitor.required_tool_miss_streak += 1
 
     issue = _classify_tool_response_issue(
         working_resp,
         anthropic_body,
         required_tool_choice=required_tool_choice,
     )
+    # The streak and dampener gates read issue.exempt — the ONE evaluation of
+    # the substantive-completion gate, done inside classification. Re-running
+    # the gate at each site risks evaluation drift, which is how this
+    # false-positive family propagates (one site fixed, another missed).
+    if required_tool_choice and not has_tool_calls and not issue.exempt:
+        monitor.required_tool_miss_streak += 1
+
     if not issue.has_issue():
-        if required_tool_choice and not has_tool_calls:
+        # A substantive completion is exempt from the miss classification, so
+        # it must not activate the forced-tool dampener either: relaxing
+        # tool_choice for a finished model is at best noise.
+        if required_tool_choice and not has_tool_calls and not issue.exempt:
             monitor.maybe_activate_forced_tool_dampener("required_tool_miss")
         if has_tool_calls:
             monitor.malformed_tool_streak = 0
@@ -12075,14 +12459,20 @@ async def _apply_malformed_tool_guardrail(
 
         retry_has_tool_calls = _openai_has_tool_calls(retry_working)
         retry_required = retry_body.get("tool_choice") == "required"
-        if retry_required and not retry_has_tool_calls:
-            monitor.required_tool_miss_streak += 1
-
         retry_issue = _classify_tool_response_issue(
             retry_working,
             anthropic_body,
             required_tool_choice=retry_required,
         )
+        # Same substantive-completion exemption as the primary path, read from
+        # the single classification evaluation (retry_issue.exempt) — a retry
+        # that produced a real final answer is not a miss.
+        if (
+            retry_required
+            and not retry_has_tool_calls
+            and not retry_issue.exempt
+        ):
+            monitor.required_tool_miss_streak += 1
 
         if not retry_issue.has_issue():
             # 2026-05-12: Fix #2 — do NOT reset malformed/invalid/miss streaks
@@ -12341,6 +12731,13 @@ def _maybe_apply_session_contamination_breaker(
         monitor.contamination_resets += 1
         monitor.malformed_tool_streak = 0
         monitor.invalid_tool_call_streak = 0
+        # 2026-10-03: the finalize branch cleared the malformed/invalid streaks
+        # but NOT required_tool_miss_streak — and that very streak is a
+        # should_reset trigger, so once condemned, EVERY subsequent request
+        # re-forced finalize (observed: contamination_resets 3→6, four
+        # finalize turns in a row, each burning a full generation). Clear it
+        # so finalize fires ONCE per contamination episode.
+        monitor.required_tool_miss_streak = 0
         # Remove tools to force text-only response
         updated = dict(anthropic_body)
         updated.pop("tools", None)
@@ -12454,12 +12851,21 @@ def _maybe_apply_session_contamination_breaker(
     forced_before = monitor.consecutive_forced_count
     required_miss_before = monitor.required_tool_miss_streak
     monitor.contamination_resets += 1
+    # Emergency tier: the conversation itself is rewritten, so BOTH the
+    # forcing-loop family (via its one policy point) and the output-quality
+    # streaks clear -- the n_msgs stickiness that protects quality streaks
+    # at ordinary turn boundaries does not apply to a hard reset. The
+    # dampener cooldown clears with them: the model state it was remedying
+    # belonged to the collapsed transcript.
+    monitor.reset_forcing_loop()
+    monitor.forced_auto_cooldown_turns = 0
     monitor.malformed_tool_streak = 0
     monitor.invalid_tool_call_streak = 0
     monitor.required_tool_miss_streak = 0
-    monitor.no_progress_streak = 0
-    monitor.consecutive_forced_count = 0
-    monitor.forced_auto_cooldown_turns = 0
+    # The recon streak belongs to the collapsed transcript (per-TASK state,
+    # reset at turn boundaries since 2026-10-04); the rewritten conversation
+    # is a fresh task surface.
+    monitor.consecutive_no_write_turns = 0
     monitor.reset_tool_turn_state(reason=f"contamination_guardrail_reset_{log_reason}")
     if attractor_detected:
         logger.warning(
@@ -13208,6 +13614,12 @@ async def _heartbeat_then_buffered(produce_coro, model: str, input_tokens: int =
     interval = PROXY_STREAM_HEARTBEAT_SECS if PROXY_STREAM_HEARTBEAT_SECS > 0 else 15.0
     thinking_heartbeat = PROXY_STREAM_THINKING_DELTAS and PROXY_PREFILL_HEARTBEAT_SECS > 0
     hb_thinking_open = False
+    # Operator-visible progress for the same wait the client heartbeats mask
+    # (2026-10-04 incident: a 281 s buffered compaction summary left the
+    # journal silent from REQ to RESP, reading as a hung proxy). One INFO line
+    # per PROXY_GUARDED_WAIT_LOG_SECS boundary crossed, never more.
+    waited_secs = 0.0
+    last_wait_log_boundary = 0
     task = asyncio.ensure_future(produce_coro)
     try:
         while True:
@@ -13217,6 +13629,17 @@ async def _heartbeat_then_buffered(produce_coro, model: str, input_tokens: int =
                 produced = await asyncio.wait_for(asyncio.shield(task), timeout=interval)
                 break
             except asyncio.TimeoutError:
+                waited_secs += interval
+                if PROXY_GUARDED_WAIT_LOG_SECS > 0:
+                    boundary = int(waited_secs // PROXY_GUARDED_WAIT_LOG_SECS)
+                    if boundary > last_wait_log_boundary:
+                        last_wait_log_boundary = boundary
+                        logger.info(
+                            "GUARDED-BUFFER WAIT: buffered non-stream turn still "
+                            "generating after %ds (model=%s input_tokens=%d) — "
+                            "client is receiving heartbeats, not hung",
+                            int(waited_secs), model, input_tokens,
+                        )
                 if thinking_heartbeat:
                     if not hb_thinking_open:
                         hb_thinking_open = True
@@ -13918,7 +14341,14 @@ async def stream_anthropic_response(
         and not tool_calls_by_index
         and (
             finish_reason == "max_tokens"
-            or (finish_reason == "end_turn" and len(accumulated_text) > 512)
+            or (
+                finish_reason == "end_turn"
+                and len(accumulated_text) > 512
+                # A substantive final answer is a completion, not a malformed
+                # payload: don't feed it to the forced-tool dampener (the
+                # same exemption the unexpected-end-turn retry uses).
+                and not _final_answer_content_exempt(accumulated_text)
+            )
         )
     ):
         monitor.malformed_tool_streak += 1
@@ -14401,10 +14831,23 @@ async def messages(request: Request):
     prev_msg_count = getattr(monitor, "last_request_msg_count", 0)
     if prev_msg_count >= 8 and n_messages <= prev_msg_count // 2:
         monitor.reset_tool_turn_state(reason="compaction_boundary")
-        monitor.consecutive_forced_count = 0
-        monitor.no_progress_streak = 0
+        # The forcing-loop family via its one policy point (2026-10-04
+        # extraction). forced_auto_cooldown_turns deliberately does NOT
+        # clear here -- the dampener remedies cross-turn output quality,
+        # which survives a compaction (see reset_forcing_loop's
+        # docstring). Test coverage note: this site is inline in the
+        # request handler and unreachable from the build_openai_request
+        # test seam, so its wiring is inspection-verified -- the method
+        # it calls IS pinned by test_reset_forcing_loop_membership_is_exact.
+        monitor.reset_forcing_loop()
         monitor.tool_starvation_streak = 0
         monitor.consecutive_no_write_turns = 0
+        # Prune-breaker floor trend too (2026-09-30, reviewer P2-1): a stale
+        # pre-compaction floor baseline must not contribute a phantom "rise"
+        # to the fresh epoch — the exact breaker false-positive class
+        # _prune_breaker_should_fire exists to prevent.
+        monitor.prune_spiral_streak = 0
+        monitor.last_post_prune_util = -1.0
         logger.info(
             "COMPACTION BOUNDARY: message count collapsed %d -> %d; reset "
             "tool-turn/anti-spin state for the fresh epoch",
@@ -14503,18 +14946,42 @@ async def messages(request: Request):
                     n_messages,
                     post_util * 100,
                 )
-            # Option 2: Circuit breaker — if 3+ consecutive prunes and still above,
-            # force finalize (drop tools, let model wrap up)
-            if monitor.prune_count >= 3 and post_util >= PROXY_CONTEXT_PRUNE_THRESHOLD:
+            # Option 2: Circuit breaker — fires only on a RISING post-prune
+            # floor (_prune_breaker_should_fire, 2026-09-30). The old "3+
+            # consecutive prunes and still above threshold" condition fired
+            # every few turns on tool-heavy clients whose fixed system+tools
+            # overhead alone exceeds the threshold (observed live: 66k est
+            # tokens of a 114,688 window at a 42% threshold), force-finalizing
+            # healthy ~44% sessions.
+            if _prune_breaker_should_fire(post_util, monitor):
                 logger.error(
-                    "PRUNE CIRCUIT BREAKER: %d consecutive prunes, still at %.1f%%. "
-                    "Forcing finalize to prevent death spiral.",
-                    monitor.prune_count,
+                    "PRUNE CIRCUIT BREAKER: post-prune floor rising for %d consecutive prunes "
+                    "(now %.1f%%, threshold %.1f%%). Forcing finalize to prevent death spiral.",
+                    monitor.prune_spiral_streak,
                     post_util * 100,
+                    PROXY_CONTEXT_PRUNE_THRESHOLD * 100,
                 )
                 monitor.set_tool_turn_phase("finalize", reason="prune_circuit_breaker")
                 monitor.tool_state_auto_budget_remaining = 1
                 monitor.reset_completion_recovery()
+            elif (
+                post_util >= PROXY_CONTEXT_PRUNE_THRESHOLD
+                and monitor.prune_spiral_streak == 0
+                and not monitor.prune_floor_logged
+            ):
+                # Above threshold with a FLAT floor (no rise this turn): fixed
+                # overhead, not a spiral. Tell the operator ONCE per session —
+                # the per-turn prune above still logs its own warning lines.
+                monitor.prune_floor_logged = True
+                logger.warning(
+                    "Post-prune utilization %.1f%% stays above the %.1f%% threshold "
+                    "with a FLAT floor — fixed system+tools overhead, not a death "
+                    "spiral; circuit breaker held. Consider raising "
+                    "PROXY_CONTEXT_PRUNE_THRESHOLD above the overhead floor for "
+                    "this client.",
+                    post_util * 100,
+                    PROXY_CONTEXT_PRUNE_THRESHOLD * 100,
+                )
 
     # Whether this upstream accepts chat_template_kwargs decides what
     # _set_thinking is allowed to write, so it must be answered BEFORE the body
@@ -14563,6 +15030,13 @@ async def messages(request: Request):
     use_guarded_non_stream = _should_buffer_turn(is_stream, body, openai_body, monitor)
     if use_guarded_non_stream:
         async def _produce_guarded():
+            # Covers the full buffered lifetime including any concurrency-queue
+            # wait: from the first upstream attempt to the served response.
+            # Reported in the "served ... (buffered %ds)" log line below so a
+            # long buffered turn is legible after the fact (2026-10-04: a
+            # client-compaction summary buffered 281 s and the only end-line
+            # evidence was the RESP timestamp).
+            t_guarded = time.monotonic()
             strict_body = dict(openai_body)
             strict_body["stream"] = False
 
@@ -14789,15 +15263,18 @@ async def messages(request: Request):
             )
             if PROXY_FORCE_NON_STREAM:
                 logger.info(
-                    "FORCED NON-STREAM: served stream response via guarded non-stream path"
+                    "FORCED NON-STREAM: served stream response via guarded non-stream path (buffered %ds)",
+                    int(time.monotonic() - t_guarded),
                 )
             elif PROXY_MALFORMED_TOOL_STREAM_STRICT and _has_tool_definitions(body):
                 logger.info(
-                    "STRICT STREAM GUARDRAIL: served stream response via guarded non-stream path"
+                    "STRICT STREAM GUARDRAIL: served stream response via guarded non-stream path (buffered %ds)",
+                    int(time.monotonic() - t_guarded),
                 )
             else:
                 logger.info(
-                    "REQUIRED TOOL STREAM GUARDRAIL: served stream response via guarded non-stream path"
+                    "REQUIRED TOOL STREAM GUARDRAIL: served stream response via guarded non-stream path (buffered %ds)",
+                    int(time.monotonic() - t_guarded),
                 )
 
             anthropic_resp = await _maybe_apply_recipe(anthropic_resp, body, openai_body, client)