@miller-tech/uap 1.210.5 → 1.210.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.210.5",
+  "version": "1.210.6",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "start": "node dist/bin/cli.js",
     "test": "vitest",
     "test:ci": "vitest run",
-    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_live_deliver_kill tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_gate_evidence tools.agents.tests.test_repeat_call_guard tools.agents.tests.test_gate_integrity tools.agents.tests.test_gate_failclosed_indirection tools.agents.tests.test_expert_review_pr_scope tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_write_complexity tools.agents.tests.test_fastpath_config tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_non_stream_resp_log tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core tools.agents.tests.test_models_context_window tools.agents.tests.test_thinking_template_kwargs",
+    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_live_deliver_kill tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_gate_evidence tools.agents.tests.test_repeat_call_guard tools.agents.tests.test_gate_integrity tools.agents.tests.test_gate_failclosed_indirection tools.agents.tests.test_expert_review_pr_scope tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_write_complexity tools.agents.tests.test_fastpath_config tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_non_stream_resp_log tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core tools.agents.tests.test_models_context_window tools.agents.tests.test_thinking_template_kwargs tools.agents.tests.test_cycle_break_wait_poll",
     "test:coverage": "vitest --coverage",
     "bench": "vitest --config vitest.bench.config.ts",
     "lint": "eslint src --ext .ts",

package/tools/agents/scripts/anthropic_proxy.py

@@ -396,6 +396,14 @@ PROXY_STUCK_API_THRESHOLD = int(os.environ.get("PROXY_STUCK_API_THRESHOLD", "3")
 # strategy, so this fires on the fingerprint alone, independent of outcome.
 # PROXY_REPEAT_CALL_THRESHOLD=0 disables.
 PROXY_REPEAT_CALL_THRESHOLD = int(os.environ.get("PROXY_REPEAT_CALL_THRESHOLD", "4"))
+# How many CONSECUTIVE wait/poll turns stay exempt from the loop guards before
+# the guards resume. The exemption is call-side and outcome-blind — a poll of a
+# healthy run and a poll of a wedged one are byte-identical from here — so
+# without a cap a dead job polled forever would be bounded only by the client's
+# own timeout. At the 45s follow interval this is ~30 minutes of waiting before
+# the proxy insists on a checkpoint, comfortably longer than a normal build turn
+# and far shorter than a stuck mission. 0 disables the cap.
+PROXY_WAIT_POLL_MAX_STREAK = int(os.environ.get("PROXY_WAIT_POLL_MAX_STREAK", "40"))
 # Marker so the injected directive can address a SUCCEEDING loop correctly
 # rather than telling the model to stop retrying "a failing action".
 _REPEAT_CALL_REASON = "identical tool call"
@@ -729,6 +737,18 @@ _READ_ONLY_TOOL_CLASS = frozenset({
 # open-ended set of tools (Bash, WebFetch, Agent, ...) that cannot be
 # enumerated, but "the agent produced a write" is a small, stable signal.
 # Names are matched case-insensitively (callers lower() before lookup).
+# Every wire name `deliver` arrives under. Tool names reach this proxy verbatim
+# from the client, prefixed with the MCP server's CONFIG KEY — and this repo
+# ships two: `.mcp.json`/`opencode.json` register it as `uap-router`, while
+# `uap setup` (setup-mcp-router.ts, for Claude/Factory/VSCode/Cursor) registers
+# it as `router`. Enumerating only one of them silently exempts half the fleet,
+# which is why this is ONE constant rather than three hand-maintained lists.
+_DELIVER_TOOL_NAMES = frozenset({
+    "deliver",
+    "uap-router_deliver", "uap-router__deliver", "mcp__uap-router__deliver",
+    "router_deliver", "mcp__router__deliver",
+})
+
 _WRITE_TOOL_CLASS = frozenset({
     "write", "edit", "multiedit", "notebookedit",
     "str_replace", "str_replace_editor", "str_replace_based_edit_tool",
@@ -746,7 +766,13 @@ _WRITE_TOOL_CLASS = frozenset({
     # and (b) the recon-convergence restore loop re-injects `deliver` when
     # narrowing dropped it, so a gated "route through deliver" directive is
     # actually satisfiable.
-    "deliver",
+    #
+    # The PREFIXED forms matter as much as the bare one: the wire name is
+    # `uap-router_deliver`, so with only "deliver" here the no-write streak kept
+    # climbing through a healthy delivery and recon-convergence escalated
+    # mid-wait — stripping reads and demanding "write your deliverable now"
+    # while the deliverable was being written by the run it was waiting on.
+    *_DELIVER_TOOL_NAMES,
 })
 
 # Open-ended exploration tools the agent uses to make a DIFFERENT move once a
@@ -763,6 +789,60 @@ _EXPLORATION_ESCAPE_TOOLS = frozenset({
     "agent", "task", "dispatch_agent",
 })
 
+# NEVER strip these either, for the same reason and a sharper one: they BLOCK on
+# a long-running job and return "still running" when their wait budget expires,
+# so the correct agent behaviour is to call them again. That is a WAIT, not a
+# spin — but it is indistinguishable from one by fingerprint, since every poll
+# carries identical arguments.
+#
+# Observed live 2026-08-17: an agent following a healthy `deliver` run (heartbeat
+# 8s old, checkpoint advancing) polled it as designed. The cycle-breaker read the
+# repeats as a loop, excluded the deliver tool, and the agent — now unable to
+# observe the work it was waiting on — fell through to Bash and cycled on THAT
+# instead. Median turn spacing collapsed from the 45s poll interval to 5s. The
+# loop the breaker "found" was the one it created.
+#
+# Stripping the tool cannot help here: unlike a cycling Bash, there is no
+# different argument to vary toward. The job is simply not finished yet.
+_WAIT_POLL_TOOLS = frozenset(
+    n.strip().lower()
+    for n in os.environ.get(
+        "PROXY_WAIT_POLL_TOOLS",
+        ",".join(sorted(_DELIVER_TOOL_NAMES | {"await_run", "wait"})),
+    ).split(",")
+    if n.strip()
+)
+
+
+def _fingerprint_tool_names(fingerprint: str) -> set:
+    """Tool names inside a tool-call fingerprint.
+
+    Fingerprints are "name" or "name:arghash", joined by "|" for a multi-call
+    turn — the same shape the cycle path already unpacks when it builds
+    cycling_tool_names.
+    """
+    names = set()
+    for part in (fingerprint or "").split("|"):
+        part = part.strip()
+        if part:
+            names.add(part.split(":")[0].lower())
+    return names
+
+
+def _spinning_cycling_names(cycling_tool_names) -> list:
+    """The cycling names that are genuinely spinning — wait/poll tools removed."""
+    return [n for n in (cycling_tool_names or []) if str(n).lower() not in _WAIT_POLL_TOOLS]
+
+
+def _is_wait_poll_only(names) -> bool:
+    """True when EVERY name given is a wait/poll tool (and there is at least one).
+
+    Deliberately all-not-any: a turn that calls `deliver` alongside a genuinely
+    spinning tool is still a spin, and must stay breakable.
+    """
+    lowered = {str(n).lower() for n in names if str(n).strip()}
+    return bool(lowered) and lowered <= _WAIT_POLL_TOOLS
+
 
 def _narrow_tools_for_cycle_break(tools, cycling_tool_names, session_banned_tools):
     """Drop cycling + session-banned tools from the toolset, expanding to the
@@ -788,8 +868,10 @@ def _narrow_tools_for_cycle_break(tools, cycling_tool_names, session_banned_tool
         cycling_exclude |= read_only_lower
     # Never let the cycling path narrow away the exploration escape hatch — that
     # is exactly the filesystem-exploration capability the cycle-break is trying
-    # to redirect the agent toward.
+    # to redirect the agent toward. Wait/poll tools are spared for the stronger
+    # reason that their repeats are not a loop at all (see _WAIT_POLL_TOOLS).
     cycling_exclude -= _EXPLORATION_ESCAPE_TOOLS
+    cycling_exclude -= _WAIT_POLL_TOOLS
     exclude_set = cycling_exclude | banned_lower
 
     def _name(t):
@@ -824,6 +906,11 @@ def _should_auto_ban(name, cycle_count, ban_at):
     """
     if name.lower() in _EXPLORATION_ESCAPE_TOOLS:
         return False
+    # A wait/poll tool accrues cycle counts fastest of all — every poll of a
+    # long job looks identical — so without this it is the FIRST tool banned,
+    # permanently, for doing exactly what it is for.
+    if name.lower() in _WAIT_POLL_TOOLS:
+        return False
     return cycle_count >= ban_at
 
 PROXY_GUARDRAIL_RETRY = os.environ.get("PROXY_GUARDRAIL_RETRY", "on").lower() not in {
@@ -1784,6 +1871,9 @@ class SessionMonitor:
     tool_state_forced_budget_remaining: int = 0
     tool_state_auto_budget_remaining: int = 0
     tool_state_stagnation_streak: int = 0
+    # Consecutive turns whose tool calls were ALL wait/poll tools. Bounds the
+    # loop-guard exemption so a wedged job cannot be polled forever.
+    wait_poll_streak: int = 0
     tool_state_transitions: int = 0
     tool_state_review_cycles: int = 0
     tool_state_unproductive_exhaustion_streak: int = 0
@@ -1974,6 +2064,12 @@ class SessionMonitor:
             and self.coordination_repeat_streak >= PROXY_COORDINATION_EARLY_BAN
         ):
             for n in coord_names:
+                # This path adds to session_banned_tools directly, bypassing
+                # _should_auto_ban — and an explicit ban IS honoured even for
+                # exempt tools, so a wait/poll tool reaching here would be
+                # stripped for the rest of the session.
+                if n.lower() in _WAIT_POLL_TOOLS:
+                    continue
                 if n not in self.session_banned_tools:
                     self.session_banned_tools.add(n)
                     logger.warning(
@@ -2054,6 +2150,20 @@ class SessionMonitor:
         else:
             self.rate_limited_api_streak = 0
 
+    def wait_poll_exempt(self) -> bool:
+        """True when this turn is a bounded wait on a long-running job.
+
+        Bounded: `wait_poll_streak` is capped by PROXY_WAIT_POLL_MAX_STREAK, so
+        a wedged job — indistinguishable from a healthy one at the call site —
+        eventually falls back under the normal guards.
+        """
+        last_fp = self.tool_call_history[-1] if self.tool_call_history else ""
+        if not _is_wait_poll_only(_fingerprint_tool_names(last_fp)):
+            return False
+        if PROXY_WAIT_POLL_MAX_STREAK <= 0:
+            return True
+        return self.wait_poll_streak <= PROXY_WAIT_POLL_MAX_STREAK
+
     def should_force_stuck_break(self) -> tuple[bool, str]:
         """True + reason when a terminal break should be forced this turn."""
         if not PROXY_STUCK_BREAK:
@@ -2069,7 +2179,16 @@ class SessionMonitor:
         if PROXY_REPEAT_CALL_THRESHOLD > 0:
             looping, count = self.detect_tool_loop(window=PROXY_REPEAT_CALL_THRESHOLD)
             if looping and count >= PROXY_REPEAT_CALL_THRESHOLD:
-                return True, f"{_REPEAT_CALL_REASON} x{count}"
+                # ...unless the repeated call is a WAIT. This branch is
+                # outcome-blind by design (see above), which is right for a
+                # `git diff --stat` loop and wrong for a tool that blocks on a
+                # long job and returns "still running": every poll is identical
+                # by construction, so this fires ~4 polls in — earlier than the
+                # cycle path — and tells the agent "you already have that
+                # output, do NOT repeat it" while the job is still running.
+                # The wait is bounded by the job, not by the agent.
+                if not self.wait_poll_exempt():
+                    return True, f"{_REPEAT_CALL_REASON} x{count}"
         return False, ""
 
     def note_deferral_signal(self, text: str, had_tool_call: bool) -> None:
@@ -5414,6 +5533,26 @@ def _update_tool_state_stagnation(
     repeated = latest_tool_fingerprint == monitor.last_tool_fingerprint
     recently_seen = latest_tool_fingerprint in monitor.tool_call_history[-4:-1]
 
+    # THE choke point for the wait/poll exemption. This signal is keyed on
+    # repeats alone — `repeated` above is a fingerprint comparison — and a poll
+    # of a long job repeats by construction, while its "still running" reply is
+    # a tool_result, so the only reset guard never fires either. Left unchecked
+    # the streak climbs one per poll straight through a healthy wait and the
+    # state machine enters review, accrues review cycles, and force-finalizes
+    # with "wrap up ... what is blocking further progress" — mid-build.
+    #
+    # Exempting HERE rather than at each consumer covers the stagnation
+    # finalize, the review-cycle limit and the phase flip in one place.
+    if _is_wait_poll_only(_fingerprint_tool_names(latest_tool_fingerprint)):
+        monitor.wait_poll_streak += 1
+        if PROXY_WAIT_POLL_MAX_STREAK <= 0 or monitor.wait_poll_streak <= PROXY_WAIT_POLL_MAX_STREAK:
+            monitor.last_tool_fingerprint = latest_tool_fingerprint
+            return
+        # Past the cap the guards resume: a wedged job looks exactly like a
+        # healthy one from here, so the exemption must not be unbounded.
+    else:
+        monitor.wait_poll_streak = 0
+
     if repeated or recently_seen:
         monitor.tool_state_stagnation_streak += 1
     else:
@@ -5576,6 +5715,24 @@ def _resolve_state_machine_tool_choice(
         # kept as a strong signal (read target repeated 3+ times). Low-repeat
         # cycles detected by detect_tool_cycle get filtered here.
         cycle_trip = cycle_looping and cycle_repeat >= PROXY_CYCLE_TRIGGER_REPEAT
+        # A cycle made up ENTIRELY of wait/poll calls is a wait, not a spin.
+        # Letting it trip still costs the session even with the tool exempted
+        # from narrowing: entering review increments tool_state_review_cycles,
+        # and at PROXY_TOOL_STATE_REVIEW_CYCLE_LIMIT the machine forces a
+        # finalize turn telling the agent to "wrap up" — mid-wait.
+        #
+        # Judged over the SAME window the detector used: a shorter slice lets an
+        # A/B oscillation between a wait tool and a real one be suppressed
+        # whenever the last turns happen to be waits. And only `cycle_trip` is
+        # cleared, never `cycle_looping` — that flag also carries the
+        # duplicate-read-target signal, which is not fingerprint-derived, and
+        # clearing it flips a downstream branch into counting the turn as
+        # unproductive (arming a different finalize).
+        _cycle_window = max(2, PROXY_TOOL_STATE_CYCLE_WINDOW)
+        if cycle_trip and _is_wait_poll_only(
+            _fingerprint_tool_names("|".join(monitor.tool_call_history[-_cycle_window:]))
+        ):
+            cycle_trip = False
         if cycle_trip or stagnating:
             reason = "cycle_detected" if cycle_looping else "stagnation"
             monitor.set_tool_turn_phase("review", reason=reason)
@@ -5635,7 +5792,15 @@ def _resolve_state_machine_tool_choice(
 
         if monitor.tool_state_forced_budget_remaining <= 0:
             monitor.set_tool_turn_phase("review", reason="forced_budget_exhausted")
-            if cycle_looping or stagnating:
+            if monitor.wait_poll_exempt():
+                # A bounded wait is neither a cycle nor an unproductive burn:
+                # both arms below lead to a forced finalize (review-cycle limit
+                # at 3, unproductive-exhaustion at 2), and reaching either
+                # mid-wait tells the agent to wrap up a job that is still
+                # running. Bounded by PROXY_WAIT_POLL_MAX_STREAK, so a wedged
+                # run falls back into normal accounting.
+                monitor.tool_state_unproductive_exhaustion_streak = 0
+            elif cycle_looping or stagnating:
                 monitor.tool_state_review_cycles += 1
                 monitor.tool_state_unproductive_exhaustion_streak = 0
             else:
@@ -6986,9 +7151,16 @@ def build_openai_request(
             if (
                 monitor.tool_turn_phase == "review"
                 and state_reason in {"cycle_detected", "stagnation"}
-                and monitor.cycling_tool_names
+                # A hint naming ONLY wait/poll tools would read "stop calling
+                # deliver, produce your final answer now" while the job it is
+                # waiting on is still running — an instruction to abandon the
+                # wait and claim a result the agent does not have yet. Hint on
+                # the genuinely-spinning tools, or say nothing.
+                and _spinning_cycling_names(monitor.cycling_tool_names)
             ):
-                cycling_names = ", ".join(monitor.cycling_tool_names)
+                cycling_names = ", ".join(
+                    _spinning_cycling_names(monitor.cycling_tool_names)
+                )
                 cycles = monitor.tool_state_review_cycles
                 if cycles <= 1:
                     cycle_hint = (
@@ -7030,8 +7202,12 @@ def build_openai_request(
                 )
                 if narrowed:
                     openai_body["tools"] = narrowed
-                    # Only log on first activation or phase transitions to reduce noise
-                    if state_reason in {"cycle_detected", "stagnation"}:
+                    # Only log on first activation or phase transitions to reduce noise.
+                    # `len(narrowed) < original_count` keeps an exempt-only cycle
+                    # from logging "narrowed tools from 5 to 5", which reads as a
+                    # cycle-break having happened when nothing was excluded —
+                    # exactly the line that would mislead triage of this incident.
+                    if state_reason in {"cycle_detected", "stagnation"} and len(narrowed) < original_count:
                         logger.warning(
                             "CYCLE BREAK: narrowed tools from %d to %d (excluded %s, read_only_class=%s)",
                             original_count,

package/tools/agents/tests/test_cycle_break_wait_poll.py

@@ -0,0 +1,293 @@
+"""A tool that BLOCKS on a long job must not be loop-broken for repeating.
+
+Incident (2026-08-17): an agent was following a healthy `deliver` run — heartbeat
+8s old, run checkpoint advancing, genuinely compiling a Rust crate. `deliver` in
+follow mode blocks up to its wait budget and returns "still running", so the
+correct behaviour is to call it again; every poll therefore carries identical
+arguments and an identical fingerprint.
+
+Three separate guards read those repeats as a spin:
+
+  1. should_force_stuck_break  — fires FIRST, at 4 identical calls, judged on
+     the fingerprint alone, and injects "STOP ... do NOT repeat it".
+  2. the cycle path            — enters review, increments review cycles, and
+     at the review-cycle limit forces a "wrap up" finalize turn.
+  3. cycle-break narrowing     — excluded the deliver tool outright, after which
+     the agent could no longer observe the work it was waiting on and fell
+     through to Bash, cycling on THAT instead. Median turn spacing collapsed
+     from the 45s poll interval to 5s.
+
+Unlike a cycling Bash ("vary the command"), there is no different argument to
+vary toward: the job is simply not finished yet. The wait is bounded by the job.
+"""
+import importlib.util
+import os
+import unittest
+from pathlib import Path
+
+proxy_path = Path(__file__).resolve().parents[1] / "scripts" / "anthropic_proxy.py"
+
+
+def load_proxy(wait_tools=None):
+    # Explicit, so a project .uap/proxy.env cannot inject PROXY_WAIT_POLL_TOOLS
+    # and silently invalidate the default-list assertions when this module is
+    # run directly rather than through the npm script.
+    os.environ["UAP_PROXY_ENV_AUTOLOAD"] = "0"
+    if wait_tools is None:
+        os.environ.pop("PROXY_WAIT_POLL_TOOLS", None)
+    else:
+        os.environ["PROXY_WAIT_POLL_TOOLS"] = wait_tools
+    spec = importlib.util.spec_from_file_location("anthropic_proxy_waitpoll", proxy_path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def tool(name):
+    return {"type": "function", "function": {"name": name, "parameters": {}}}
+
+
+# The toolset from the live incident, trimmed to the relevant members.
+TOOLS = [tool(n) for n in ("uap-router_deliver", "bash", "read", "edit", "glob")]
+
+
+_PRIOR_AUTOLOAD = os.environ.get("UAP_PROXY_ENV_AUTOLOAD")
+
+
+def tearDownModule():
+    # Restore rather than leak into any module loaded later in this process —
+    # cross-test env leakage from files like this one has caused
+    # order-dependent failures before.
+    if _PRIOR_AUTOLOAD is None:
+        os.environ.pop("UAP_PROXY_ENV_AUTOLOAD", None)
+    else:
+        os.environ["UAP_PROXY_ENV_AUTOLOAD"] = _PRIOR_AUTOLOAD
+
+
+class _Base(unittest.TestCase):
+    def tearDown(self):
+        os.environ.pop("PROXY_WAIT_POLL_TOOLS", None)
+
+    @staticmethod
+    def _names(tools):
+        return [t["function"]["name"] for t in tools]
+
+
+class WaitPollNotNarrowedTest(_Base):
+    def test_the_polled_tool_survives_the_cycle_break(self):
+        ap = load_proxy()
+        narrowed, _ = ap._narrow_tools_for_cycle_break(TOOLS, ["uap-router_deliver"], [])
+        self.assertIn("uap-router_deliver", self._names(narrowed))
+
+    def test_a_genuinely_spinning_tool_is_still_narrowed(self):
+        ap = load_proxy()
+        narrowed, _ = ap._narrow_tools_for_cycle_break(TOOLS, ["edit"], [])
+        self.assertNotIn("edit", self._names(narrowed))
+
+    def test_matching_is_exact_not_substring(self):
+        # A tool whose name merely CONTAINS an exempt name must still be
+        # narrowed — otherwise the exemption silently widens to anything
+        # someone names "deliver_report".
+        ap = load_proxy()
+        tools = [tool("deliver_report"), tool("bash"), tool("edit")]
+        narrowed, _ = ap._narrow_tools_for_cycle_break(tools, ["deliver_report"], [])
+        self.assertNotIn("deliver_report", self._names(narrowed))
+
+    def test_the_polled_tool_is_never_auto_banned(self):
+        ap = load_proxy()
+        self.assertFalse(ap._should_auto_ban("uap-router_deliver", cycle_count=99, ban_at=3))
+        self.assertTrue(ap._should_auto_ban("edit", cycle_count=99, ban_at=3))
+
+    def test_an_explicit_session_ban_is_still_honoured(self):
+        ap = load_proxy()
+        narrowed, _ = ap._narrow_tools_for_cycle_break(TOOLS, [], ["uap-router_deliver"])
+        self.assertNotIn("uap-router_deliver", self._names(narrowed))
+
+    def test_the_set_is_configurable(self):
+        ap = load_proxy(wait_tools="my_wait_tool")
+        self.assertIn("my_wait_tool", ap._WAIT_POLL_TOOLS)
+        narrowed, _ = ap._narrow_tools_for_cycle_break(
+            [tool("my_wait_tool"), tool("edit")], ["my_wait_tool"], []
+        )
+        self.assertIn("my_wait_tool", self._names(narrowed))
+
+    def test_matching_is_case_insensitive(self):
+        ap = load_proxy()
+        narrowed, _ = ap._narrow_tools_for_cycle_break(
+            [tool("UAP-Router_Deliver"), tool("edit")], ["UAP-Router_Deliver"], []
+        )
+        self.assertIn("UAP-Router_Deliver", self._names(narrowed))
+
+    def test_exploration_hatch_still_exempt(self):
+        ap = load_proxy()
+        narrowed, _ = ap._narrow_tools_for_cycle_break(TOOLS, ["bash"], [])
+        self.assertIn("bash", self._names(narrowed))
+
+
+class DeliverWireNamesTest(_Base):
+    def test_both_mcp_config_keys_are_covered(self):
+        # Names arrive prefixed with the MCP server's CONFIG KEY, and this repo
+        # ships two: `uap-router` (.mcp.json / opencode.json) and `router`
+        # (setup-mcp-router.ts, used by `uap setup`). Covering one exempts only
+        # half the fleet.
+        ap = load_proxy()
+        for name in ("uap-router_deliver", "mcp__uap-router__deliver",
+                     "router_deliver", "mcp__router__deliver", "deliver"):
+            self.assertIn(name, ap._WAIT_POLL_TOOLS, name)
+
+    def test_deliver_counts_as_a_write_under_every_wire_name(self):
+        # _WRITE_TOOL_CLASS with only the bare name let the no-write streak
+        # climb through a healthy delivery, escalating recon-convergence
+        # mid-wait ("write your deliverable now") while the deliverable was
+        # being written by the run being waited on.
+        ap = load_proxy()
+        for name in ap._DELIVER_TOOL_NAMES:
+            self.assertIn(name, ap._WRITE_TOOL_CLASS, name)
+
+    def test_wait_poll_and_write_classes_deliberately_overlap(self):
+        # Other tool classes in this module are pairwise disjoint; this pair is
+        # not, and the intent is pinned here rather than left implicit.
+        ap = load_proxy()
+        self.assertTrue(ap._WAIT_POLL_TOOLS & ap._WRITE_TOOL_CLASS)
+
+
+class StuckBreakTest(_Base):
+    """The guard that fires FIRST — 4 identical calls, outcome-blind."""
+
+    @staticmethod
+    def _monitor(ap, history):
+        m = ap.SessionMonitor(context_window=131072)
+        m.tool_call_history = list(history)
+        return m
+
+    def test_a_healthy_poll_does_not_force_a_stuck_break(self):
+        ap = load_proxy()
+        m = self._monitor(ap, ["uap-router_deliver:abc"] * 8)
+        forced, reason = m.should_force_stuck_break()
+        self.assertFalse(forced, reason)
+
+    def test_a_genuinely_repeated_call_still_forces_a_break(self):
+        # The 44-turn `git diff --stat` loop this guard exists for.
+        ap = load_proxy()
+        m = self._monitor(ap, ["bash:diffstat"] * 8)
+        forced, _ = m.should_force_stuck_break()
+        self.assertTrue(forced)
+
+    def test_a_wait_mixed_with_a_spin_still_breaks(self):
+        # all-not-any: a turn calling deliver alongside a spinning tool is
+        # still a spin and must stay breakable.
+        ap = load_proxy()
+        m = self._monitor(ap, ["uap-router_deliver:abc|bash:x"] * 8)
+        forced, _ = m.should_force_stuck_break()
+        self.assertTrue(forced)
+
+
+class StateMachineEndToEndTest(_Base):
+    """Drive real polls through the state machine — the test that catches the
+    guard the helper-level tests miss.
+
+    The first cut of this fix exempted narrowing, the stuck-break and the cycle
+    trip, and STILL force-finalized a healthy wait: the stagnation signal is
+    keyed on repeats (`latest_fingerprint == last_fingerprint`) and its only
+    reset needs a turn WITHOUT a tool_result, which a poll always has. It
+    climbed one per poll, entered review at 9, and hit the review-cycle limit at
+    16 with "wrap up ... what is blocking further progress" — mid-build.
+    """
+
+    FP = "uap-router_deliver:abc"
+
+    @staticmethod
+    def _poll(ap, monitor, fingerprint, msgs):
+        """One agent turn: record the call, then run the state machine.
+
+        `msgs` GROWS across turns. A constant-length message list reads as a
+        compaction boundary ("message count collapsed"), which resets all
+        anti-spin state every turn and would make this harness silently prove
+        nothing.
+        """
+        monitor.record_tool_calls(["deliver"], fingerprint=fingerprint)
+        ap._update_tool_state_stagnation(
+            monitor, latest_tool_fingerprint=fingerprint, last_user_has_tool_result=True
+        )
+        msgs.append({"role": "assistant", "content": "calling"})
+        msgs.append({"role": "user", "content": "STILL RUNNING"})
+        body = {"messages": list(msgs), "tools": [tool("uap-router_deliver")]}
+        # A poll always carries the previous poll's "still running" tool_result,
+        # which is precisely why the stagnation reset never fires for it.
+        return ap._resolve_state_machine_tool_choice(
+            body, monitor, has_tool_results=True, last_user_has_tool_result=True
+        )
+
+    def test_a_healthy_wait_is_never_force_finalized(self):
+        ap = load_proxy()
+        m = ap.SessionMonitor(context_window=131072)
+        msgs = [{"role": "user", "content": "start"}]
+        for i in range(30):
+            self._poll(ap, m, self.FP, msgs)
+            self.assertNotEqual(
+                m.tool_turn_phase, "finalize",
+                f"forced a finalize on poll {i + 1} of a healthy wait",
+            )
+        self.assertEqual(m.tool_state_stagnation_streak, 0)
+        self.assertEqual(m.tool_state_review_cycles, 0)
+
+    def test_a_wedged_job_is_still_bounded(self):
+        # The exemption is call-side and outcome-blind, so it MUST be capped:
+        # a dead run polled forever would otherwise be bounded only by the
+        # client's own timeout.
+        ap = load_proxy()
+        ap.PROXY_WAIT_POLL_MAX_STREAK = 5
+        m = ap.SessionMonitor(context_window=131072)
+        msgs = [{"role": "user", "content": "start"}]
+        for _ in range(40):
+            self._poll(ap, m, self.FP, msgs)
+        self.assertGreater(
+            m.tool_state_stagnation_streak, 0,
+            "past the cap the normal guards must resume",
+        )
+
+    def test_a_real_spin_still_stagnates(self):
+        ap = load_proxy()
+        m = ap.SessionMonitor(context_window=131072)
+        msgs = [{"role": "user", "content": "start"}]
+        for _ in range(10):
+            self._poll(ap, m, "bash:samecmd", msgs)
+        self.assertGreater(m.tool_state_stagnation_streak, 0)
+
+    def test_the_streak_resets_when_the_agent_does_something_else(self):
+        ap = load_proxy()
+        m = ap.SessionMonitor(context_window=131072)
+        msgs = [{"role": "user", "content": "start"}]
+        for _ in range(5):
+            self._poll(ap, m, self.FP, msgs)
+        self.assertEqual(m.wait_poll_streak, 5)
+        self._poll(ap, m, "edit:file", msgs)
+        self.assertEqual(m.wait_poll_streak, 0)
+
+
+class HelperTest(_Base):
+    def test_fingerprint_names_are_unpacked(self):
+        ap = load_proxy()
+        self.assertEqual(
+            ap._fingerprint_tool_names("uap-router_deliver:abc123|bash:def"),
+            {"uap-router_deliver", "bash"},
+        )
+
+    def test_is_wait_poll_only_requires_all(self):
+        ap = load_proxy()
+        self.assertTrue(ap._is_wait_poll_only({"uap-router_deliver"}))
+        self.assertFalse(ap._is_wait_poll_only({"uap-router_deliver", "bash"}))
+        self.assertFalse(ap._is_wait_poll_only(set()))
+
+    def test_hint_names_drop_wait_tools_but_keep_spinners(self):
+        # The load-bearing mixed case: the hint must still fire, naming only
+        # the tool that is actually spinning.
+        ap = load_proxy()
+        self.assertEqual(
+            ap._spinning_cycling_names(["uap-router_deliver", "read"]), ["read"]
+        )
+        self.assertEqual(ap._spinning_cycling_names(["uap-router_deliver"]), [])
+
+
+if __name__ == "__main__":
+    unittest.main()