@miller-tech/uap 2.21.3 → 2.36.1

package/tools/agents/scripts/toolcall_path_normalizer.py

@@ -12,7 +12,10 @@ path to the nearest path the model already used correctly earlier in the
 conversation — filesystem-free, and the proxy is in the request path.
 
 Pure functions; gated by PROXY_TOOLCALL_PATH_NORMALIZE in the proxy. Mirrors the
-TS reference at src/self-harness/middleware/path-normalizer.ts.
+TS reference at src/self-harness/middleware/path-normalizer.ts (the filename-snap
+normalize only). Containment -- contain_tool_uses / contain_to_workdir,
+including the container-exec exemption -- is proxy-side Python ONLY, with no
+TS counterpart; a TS parity sync must not treat containment as mirrored.
 See docs/design/SELF_HARNESS.md §4 (P2).
 """
 
@@ -25,6 +28,39 @@ _PATH_ARG_KEYS = ("file_path", "path", "filePath", "notebook_path")
 # Absolute paths a tool call might target. Used to scan/rewrite Bash commands.
 _ABS_PATH_RE = re.compile(r"/(?:home|root|Users|tmp|var|opt|srv|mnt)/[A-Za-z0-9._\-/]+")
 
+# Container-exec contexts: docker exec (incl. 'docker compose exec' -- the
+# docker word already prefixes it), podman exec, nerdctl exec, kubectl exec.
+# Paths at-or-after this boundary belong to ANOTHER filesystem -- the
+# container's, not the host's -- so the host-workdir heuristic cannot reason
+# about them. Containing them manufactures a guaranteed failure: observed
+# 2026-10-18, an 11-hour loop where every
+# "docker exec p37koral bash -lc 'cat /tmp/e2e/...log'" had its container
+# path snapped onto the host workdir (/tmp/p37/e2e/...), which cannot exist
+# inside the container, so the command failed no matter what the model
+# varied. The exemption is fail-safe: an un-rewritten path that IS garbled
+# errors loudly inside the container, and the loop guards steer on it.
+#
+# Scope decisions, pinned by tests in test_path_containment.py -- do not
+# "tighten" without re-reading the incident:
+#   * the boundary is the END of the exec word (engine flags before the
+#     subcommand, e.g. kubectl --kubeconfig=/host.conf, are host-side);
+#   * the exemption extends to the END OF THE COMMAND, never the next
+#     separator -- quoted exec payloads (bash -lc 'cat /a; cat /b') carry
+#     separators a regex cannot scope, so per-segment scoping would
+#     reintroduce the incident class;
+#   * {0,1000} bounds the lazy scan (a capped-out match simply fails and
+#     paths stay contained -- fail-safe);
+#   * known residual shapes, accepted as fail-loud for now: env-assignment
+#     BEFORE the boundary (LOG=/x docker exec ...), backslash
+#     line-continuation between engine word and exec, docker cp / docker
+#     run dest-side paths, multi-line spellings. Broaden only on incident
+#     evidence (candidates: nsenter/chroot/unshare/lxc, docker cp / kubectl
+#     cp dest side).
+_CONTAINER_EXEC_RE = re.compile(
+    r"\b(?:docker|podman|nerdctl|kubectl)\b[^\n;&|]{0,1000}?\bexec\b",
+    re.IGNORECASE,
+)
+
 
 def _squash(s: str) -> str:
     return re.sub(r"[^a-z0-9]", "", s.lower())
@@ -276,7 +312,16 @@ def contain_tool_uses(tool_uses, workdir: str):
                     corrections.append((tu_id, key, v, nv, reason))
         cmd = inp.get("command")
         if isinstance(cmd, str) and "/" in cmd:
+            exec_m = _CONTAINER_EXEC_RE.search(cmd)
+            # Boundary = END of the exec word: engine flags BEFORE the
+            # subcommand are host-side and stay contained; everything from
+            # the subcommand on is container-side (see _CONTAINER_EXEC_RE).
+            exec_at = exec_m.end() if exec_m else None
             def _sub(m):
+                # At-or-after a container-exec boundary the token is a
+                # container-FS path: exempt (see _CONTAINER_EXEC_RE).
+                if exec_at is not None and m.start() >= exec_at:
+                    return m.group(0)
                 nv, changed, _ = contain_to_workdir(m.group(0), workdir)
                 return nv if changed else m.group(0)
             new_cmd = _ABS_PATH_RE.sub(_sub, cmd)

package/tools/agents/tests/test_anthropic_proxy_streaming.py

@@ -4306,15 +4306,32 @@ class TestGarbledArgsRetry(unittest.TestCase):
     """Tests for garbled tool arguments triggering retry via _validate_tool_call_arguments."""
 
     def test_garbled_runaway_braces_triggers_retry(self):
-        """Garbled brace imbalance should return an invalid_tool_args issue."""
-        # Valid JSON but with extreme brace imbalance in string value
-        garbled_args = '{"todos": "}}}}}}}}}}}}}"}'
+        """Unparseable runaway braces should return an invalid_tool_args issue.
+
+        Valid JSON with braces inside a string VALUE must NOT be flagged: a
+        live payload (2026-10-03) carried a Rust code excerpt with unmatched
+        closing braces in oldString, and the raw balance check burned three
+        session-contamination resets on a perfectly valid payload before the
+        check was gated behind JSON-parse failure.
+        """
+        # Truncated payload: the JSON closes, then runaway closers follow —
+        # unparseable. The JSON step catches it BEFORE the garbled classifier,
+        # so the issue names the syntax error (still invalid_tool_args, still
+        # retried) rather than "garbled".
+        garbled_args = '{"todos": "cut mid-generation"}}}}}}}'
         issue = proxy._validate_tool_call_arguments(
             "TodoWrite", garbled_args, {}, {"TodoWrite"}
         )
         self.assertTrue(issue.has_issue())
         self.assertEqual(issue.kind, "invalid_tool_args")
-        self.assertIn("garbled", issue.reason)
+        self.assertIn("invalid JSON arguments", issue.reason)
+        # Valid JSON, runaway braces as payload CONTENT (a code excerpt) —
+        # not an issue.
+        excerpt_args = '{"todos": "}}}}}}}}}}}}}"}'
+        issue = proxy._validate_tool_call_arguments(
+            "TodoWrite", excerpt_args, {}, {"TodoWrite"}
+        )
+        self.assertFalse(issue.has_issue())
 
     def test_garbled_repetitive_digits_triggers_retry(self):
         """Repetitive digit patterns should return an invalid_tool_args issue."""
@@ -4632,9 +4649,15 @@ class TestRetryGarbledImprovements(unittest.TestCase):
 
     def test_garbled_args_excerpt_in_issue(self):
         """_is_garbled_tool_arguments detects garbled content for logging."""
-        # Garbled pattern: runaway braces
-        garbled = '{"pattern": "test}}}}}}}}}}}}}}"}'
+        # Garbled pattern: runaway braces on an UNPARSEABLE payload
+        # (truncated JSON + trailing closers)
+        garbled = '{"pattern": "test"}}}}}}}}}}}}}}'
         self.assertTrue(proxy._is_garbled_tool_arguments(garbled))
+        # Valid JSON with runaway braces as string CONTENT (a code excerpt) —
+        # must NOT be flagged (live 2026-10-03: valid Rust excerpt, three
+        # wasted contamination resets)
+        excerpt = '{"pattern": "test}}}}}}}}}}}}}}"}'
+        self.assertFalse(proxy._is_garbled_tool_arguments(excerpt))
         # Clean pattern
         clean = '{"pattern": "hello", "path": "/src"}'
         self.assertFalse(proxy._is_garbled_tool_arguments(clean))

package/tools/agents/tests/test_doubling_break.py

@@ -30,6 +30,9 @@ proxy = _load_proxy_module()
 FAIL = "Error: rate limit exceeded for url"
 FAIL_OTHER = "TypeError: cannot read properties of undefined"
 OK = "all files written successfully"
+# Content-free wrapper: names no failure, so no signature can anchor on it --
+# the unnameable identical-call shape _declares_failure_shape now owns here.
+WRAPPER_ONLY = "error: command failed (exit code: 1)"
 
 
 class TestDoublingStreakAccounting(unittest.TestCase):
@@ -116,6 +119,39 @@ class TestDoublingStreakAccounting(unittest.TestCase):
         mon.note_doubling_signal("Bash:abcd1234", body)
         self.assertEqual(mon.doubling_streak, 2)
 
+    def test_unnameable_content_free_failure_still_counts(self):
+        # Architect review 2026-10-18: an identical call failing with ONLY a
+        # content-free wrapper forms NO signature, so before
+        # _declares_failure_shape no guard owned this shape at all.
+        mon = proxy.SessionMonitor()
+        mon.note_doubling_signal("Bash:abcd1234", WRAPPER_ONLY)
+        mon.note_doubling_signal("Bash:abcd1234", WRAPPER_ONLY)
+        self.assertEqual(mon.doubling_streak, 2)
+
+    def test_bare_traceback_header_failure_still_counts(self):
+        mon = proxy.SessionMonitor()
+        mon.note_doubling_signal(
+            "Bash:abcd1234", "Traceback (most recent call last):"
+        )
+        mon.note_doubling_signal(
+            "Bash:abcd1234", "Traceback (most recent call last):"
+        )
+        self.assertEqual(mon.doubling_streak, 2)
+
+    def test_pure_output_with_no_failure_declaration_does_not_count(self):
+        # The declaration shapes are failure-specific: bare output text is
+        # not one, so a healthy identical call still resets the streak.
+        mon = proxy.SessionMonitor()
+        mon.note_doubling_signal("Bash:abcd1234", FAIL)
+        mon.note_doubling_signal("Bash:abcd1234", "Compiling main.c")
+        self.assertEqual(mon.doubling_streak, 0)
+
+    def test_zero_exit_code_is_success_not_failure(self):
+        mon = proxy.SessionMonitor()
+        mon.note_doubling_signal("Bash:abcd1234", "exit code 0")
+        mon.note_doubling_signal("Bash:abcd1234", "exit code 0")
+        self.assertEqual(mon.doubling_streak, 0)
+
     def test_reset_doubling_clears_state(self):
         mon = proxy.SessionMonitor()
         mon.note_doubling_signal("Bash:abcd1234", FAIL)
@@ -145,7 +181,16 @@ class TestDoublingInjection(unittest.TestCase):
         body = _body()
         proxy._maybe_inject_doubling_break(body, mon)
         self.assertEqual(mon.doubling_break_fires, 1)
-        self.assertIn("PIVOT", body["messages"][0]["content"])
+        # Tail placement (the salience position LOCKSTEP/ERROR-LOOP forced):
+        # the directive rides the transcript tail as a user-role turn, never a
+        # system-top append -- the 2026-10-07 ledger shows system-top
+        # directives ignored twice en route to a hard stop.
+        tail = body["messages"][-1]
+        self.assertEqual(tail["role"], "user")
+        self.assertIn("PIVOT", tail["content"])
+        # the system prompt is untouched -- no system-0 mangling
+        self.assertEqual(body["messages"][0]["role"], "system")
+        self.assertEqual(body["messages"][0]["content"], "base")
         # Advisory: never touches tool_choice (unlike deferral-break).
         self.assertEqual(body["tool_choice"], "auto")
 
@@ -181,12 +226,26 @@ class TestDoublingInjection(unittest.TestCase):
         proxy._maybe_inject_doubling_break(body, mon)
         self.assertEqual(mon.doubling_break_fires, 0)
 
-    def test_inserts_system_message_when_absent(self):
+    def test_appends_tail_directive_and_keeps_trailing_prefill_last(self):
+        # No system message exists to append to, and a trailing assistant
+        # message is a client prefill (a continuation contract): the directive
+        # goes in front of it, never after -- same contract as LOCKSTEP.
         mon = _saturated_monitor()
-        body = {"tools": [], "messages": [{"role": "user", "content": "hi"}]}
+        body = {
+            "tools": [],
+            "messages": [
+                {"role": "user", "content": "hi"},
+                {"role": "assistant", "content": "the plan is "},
+            ],
+        }
         proxy._maybe_inject_doubling_break(body, mon)
-        self.assertEqual(body["messages"][0]["role"], "system")
-        self.assertIn("PIVOT", body["messages"][0]["content"])
+        prefill = body["messages"][-1]
+        directive = body["messages"][-2]
+        self.assertEqual(prefill["role"], "assistant")
+        self.assertEqual(prefill["content"], "the plan is ")  # untouched
+        self.assertEqual(directive["role"], "user")
+        self.assertIn("PIVOT", directive["content"])
+        self.assertEqual(body["messages"][0]["content"], "hi")
 
 
 class TestRecordingWiring(unittest.TestCase):

package/tools/agents/tests/test_error_loop_break.py

@@ -68,10 +68,16 @@ class InjectionTests(unittest.TestCase):
             self.m.note_tool_result_error("SyntaxError: already declared\n at x:1")
         body = {"messages": [{"role": "user", "content": "go"}], "tool_choice": "required"}
         proxy._maybe_inject_error_loop_break(body, self.m)
-        sysmsg = body["messages"][0]
-        self.assertEqual(sysmsg["role"], "system")
-        self.assertIn("SAME failure", sysmsg["content"])
-        self.assertIn("re-read", sysmsg["content"].lower())
+        # Tail user-role turn (the salient placement LOCKSTEP forced; the
+        # 2026-09-24 opencode+qwen log shows system-top directives ignored 3x
+        # en route to every hard stop), not a system-top append.
+        tail = body["messages"][-1]
+        self.assertEqual(tail["role"], "user")
+        self.assertIn("SAME failure", tail["content"])
+        self.assertIn("re-read", tail["content"].lower())
+        # the original messages are untouched -- no system-0 mangling
+        self.assertEqual(body["messages"][0]["role"], "user")
+        self.assertEqual(body["messages"][0]["content"], "go")
         # advisory: does NOT release tool_choice
         self.assertEqual(body["tool_choice"], "required")
         self.assertEqual(self.m.error_loop_fires, 1)

package/tools/agents/tests/test_error_loop_ignores_correctives.py

@@ -46,7 +46,14 @@ def _load_signature():
     _error_signature, rather than cherry-picking names. The previous version
     exec'd a hardcoded list of regexes, so adding a helper to the proxy left the
     test raising NameError against its own source -- the loader had to be edited
-    in lockstep with any new dependency."""
+    in lockstep with any new dependency.
+
+    Placement contract (review condition 2026-10-18): every constant and
+    helper _error_signature/_error_signature_for_result touches must live
+    INSIDE this slice -- between _ERROR_LINE_RE and the first "# ---" section
+    marker after them. A helper that drifts below the marker raises NameError
+    here on the next run; the fix is to move it back into the region, never
+    to cherry-pick names into ns."""
     src = PROXY.read_text()
     ns = {"re": re}
     start = src.index("_ERROR_LINE_RE = re.compile(")
@@ -241,7 +248,11 @@ class TestTheFlagIsActuallyWiredThrough(unittest.TestCase):
     def test_the_request_handler_passes_the_is_error_flag(self):
         src = PROXY.read_text()
         assert "_latest_err" in src, "the handler no longer computes the is_error flag"
-        assert re.search(r"note_tool_result_error\(\s*_latest_tr\s*,\s*_latest_err\s*\)", src), (
+        assert re.search(
+            r"note_tool_result_error\(\s*_latest_tr\s*,\s*_latest_err\s*,\s*"
+            r"tool_names=_latest_tr_tools\s*\)",
+            src,
+        ), (
             "note_tool_result_error is called without the is_error flag — reading a file that "
             "contains the word 'Exception' will manufacture a failure streak again"
         )

package/tools/agents/tests/test_lockstep_escalation.py

@@ -118,16 +118,152 @@ class LadderTests(LockstepKnobGuard):
         _drive_lockstep(m, proxy.PROXY_LOCKSTEP_PIVOT_AT)
         body = self._body()
         proxy._maybe_lockstep_escalate(body, m)
-        sysmsg = body["messages"][0]
-        self.assertEqual(sysmsg["role"], "system")
-        self.assertIn("LOOP-ESCALATE", sysmsg["content"])
-        self.assertIn("different approaches", sysmsg["content"])
+        # Salient placement: the directive rides the transcript TAIL as a
+        # user-role turn, not the system-prompt top (2026-10-07 ledger: both
+        # system-top directives were ignored en route to a hard stop).
+        tail = body["messages"][-1]
+        self.assertEqual(tail["role"], "user")
+        self.assertIn("LOOP-ESCALATE", tail["content"])
+        self.assertIn("different approaches", tail["content"])
+        # unknown error class stays generic: no invented fix line
+        self.assertNotIn("KNOWN FIX", tail["content"])
+        # the quoted error text is untrusted; both guards carry the caveat
+        self.assertIn("untrusted tool output", tail["content"])
         self.assertEqual(m.lockstep_fires, 1)
         # advisory: tool_choice untouched
         self.assertEqual(body["tool_choice"], "auto")
         recs = self._records()
         self.assertEqual([r["outcome"] for r in recs], ["pivot"])
 
+    def _drive_signature(self, monitor, signature, n):
+        """Drive the trackers with a specific error signature, the way a real
+        loop with that error feeds them every turn. result_error=True mirrors
+        the is_error flag: without it, keyword-free text (e.g. the client
+        cancel marker) never extracts a signature at all."""
+        for i in range(n):
+            monitor.note_tool_result_error(signature, result_error=True)
+            monitor.note_doubling_signal(
+                FP, signature, msg_count=100 + i, result_error=True
+            )
+
+    def test_pivot_carries_known_fix_for_missing_skill(self):
+        m = proxy.SessionMonitor()
+        sig = 'skill "uap-router__react" not found. available skills: adapt, animate'
+        self._drive_signature(m, sig, proxy.PROXY_LOCKSTEP_PIVOT_AT)
+        body = self._body()
+        proxy._maybe_lockstep_escalate(body, m)
+        tail = body["messages"][-1]
+        self.assertIn("KNOWN FIX", tail["content"])
+        self.assertIn("does not exist", tail["content"])
+        self.assertIn("available-skills list", tail["content"])
+
+    def test_pivot_carries_known_fix_for_invalid_status(self):
+        m = proxy.SessionMonitor()
+        sig = "error: todo item #: status must be pending, in_progress, or completed"
+        self._drive_signature(m, sig, proxy.PROXY_LOCKSTEP_PIVOT_AT)
+        body = self._body()
+        proxy._maybe_lockstep_escalate(body, m)
+        tail = body["messages"][-1]
+        self.assertIn("KNOWN FIX", tail["content"])
+        self.assertIn("pending, in_progress, completed", tail["content"])
+
+    def test_pivot_carries_known_fix_for_interrupted_call(self):
+        m = proxy.SessionMonitor()
+        sig = "[tool execution was interrupted]"
+        self._drive_signature(m, sig, proxy.PROXY_LOCKSTEP_PIVOT_AT)
+        body = self._body()
+        proxy._maybe_lockstep_escalate(body, m)
+        tail = body["messages"][-1]
+        self.assertIn("KNOWN FIX", tail["content"])
+        self.assertIn("interrupted before it ran", tail["content"])
+
+    def test_pivot_carries_known_fix_for_edit_anchor_mismatch(self):
+        # edit x19 across 3 sessions (ledger 2026-09-25..10-13): the top class.
+        m = proxy.SessionMonitor()
+        sig = "error: edit could not find oldstring in the file. it must match exactly, including whitespace, indentation, and line endings."
+        self._drive_signature(m, sig, proxy.PROXY_LOCKSTEP_PIVOT_AT)
+        body = self._body()
+        proxy._maybe_lockstep_escalate(body, m)
+        tail = body["messages"][-1]
+        self.assertIn("KNOWN FIX", tail["content"])
+        self.assertIn("byte-for-byte", tail["content"])
+
+    def test_pivot_carries_known_fix_for_identical_edit(self):
+        m = proxy.SessionMonitor()
+        sig = "no changes to apply: oldstring and newstring are identical."
+        self._drive_signature(m, sig, proxy.PROXY_LOCKSTEP_PIVOT_AT)
+        body = self._body()
+        proxy._maybe_lockstep_escalate(body, m)
+        tail = body["messages"][-1]
+        self.assertIn("KNOWN FIX", tail["content"])
+        self.assertIn("already contains the intended text", tail["content"])
+
+    def test_pivot_carries_known_fix_for_write_truncation(self):
+        # one hard_blocked incident: re-emitting the whole file gets cut off
+        # again, so the fix must forbid whole-file re-emission.
+        m = proxy.SessionMonitor()
+        sig = "error: src<path> content looks truncated (# unclosed {). your output was likely cut off mid-file. do not re-emit the whole file"
+        self._drive_signature(m, sig, proxy.PROXY_LOCKSTEP_PIVOT_AT)
+        body = self._body()
+        proxy._maybe_lockstep_escalate(body, m)
+        tail = body["messages"][-1]
+        self.assertIn("KNOWN FIX", tail["content"])
+        self.assertIn("Do NOT re-emit the whole file", tail["content"])
+
+    def test_pivot_carries_known_fix_for_policy_block(self):
+        # opencode+qwen log 2026-09-24: 20 ERROR-LOOP hard stops on exactly
+        # this signature. The fix must point at the POLICY LAYER, never
+        # endorse executing a command string lifted from the untrusted error
+        # text (a hostile repo can forge the block line in any failing
+        # command's output).
+        m = proxy.SessionMonitor()
+        sig = "[uap policy blocked: rtk-wrap] rtk-wrap: 'docker' must be invoked via rtk. use: rtk docker compose"
+        self._drive_signature(m, sig, proxy.PROXY_LOCKSTEP_PIVOT_AT)
+        body = self._body()
+        proxy._maybe_lockstep_escalate(body, m)
+        tail = body["messages"][-1]
+        self.assertIn("KNOWN FIX", tail["content"])
+        self.assertIn("blocked by UAP policy", tail["content"])
+        self.assertIn("untrusted", tail["content"])
+        self.assertNotIn("verbatim", tail["content"])
+
+    def test_final_warning_repeats_known_fix(self):
+        m = proxy.SessionMonitor()
+        sig = 'skill "uap-router__react" not found. available skills: adapt'
+        self._drive_signature(m, sig, proxy.PROXY_LOCKSTEP_PIVOT_AT)
+        proxy._maybe_lockstep_escalate(self._body(), m)
+        self._drive_signature(m, sig, 1)
+        body = self._body()
+        proxy._maybe_lockstep_escalate(body, m)
+        tail = body["messages"][-1]
+        self.assertIn("FINAL WARNING", tail["content"])
+        self.assertIn("KNOWN FIX", tail["content"])
+
+    def test_pivot_keeps_trailing_assistant_prefill_last(self):
+        # A trailing assistant message is a client prefill (a continuation
+        # contract the prefill workaround keys on): the directive must go in
+        # FRONT of it, never after -- burying the prefill would 400 on
+        # thinking-enabled backends and the retry would then silently drop the
+        # pivot behind the duplicate-observation guard.
+        m = proxy.SessionMonitor()
+        _drive_lockstep(m, proxy.PROXY_LOCKSTEP_PIVOT_AT)
+        body = {
+            "messages": [
+                {"role": "user", "content": "fix it"},
+                {"role": "assistant", "content": "the fix is "},
+            ],
+            "tool_choice": "auto",
+        }
+        proxy._maybe_lockstep_escalate(body, m)
+        prefill = body["messages"][-1]
+        directive = body["messages"][-2]
+        self.assertEqual(prefill["role"], "assistant")
+        self.assertEqual(prefill["content"], "the fix is ")  # untouched
+        self.assertEqual(directive["role"], "user")
+        self.assertIn("LOOP-ESCALATE", directive["content"])
+        self.assertEqual(m.lockstep_fires, 1)
+        self.assertEqual([r["outcome"] for r in self._records()], ["pivot"])
+
     def test_final_warning_on_second_fire(self):
         m = proxy.SessionMonitor()
         _drive_lockstep(m, proxy.PROXY_LOCKSTEP_PIVOT_AT)
@@ -135,7 +271,7 @@ class LadderTests(LockstepKnobGuard):
         _drive_lockstep(m, 1)
         body = self._body()
         proxy._maybe_lockstep_escalate(body, m)
-        self.assertIn("FINAL WARNING", body["messages"][0]["content"])
+        self.assertIn("FINAL WARNING", body["messages"][-1]["content"])
         self.assertEqual(m.lockstep_fires, 2)
         self.assertEqual(
             [r["outcome"] for r in self._records()], ["pivot", "final_warning"]
@@ -231,8 +367,8 @@ class LadderTests(LockstepKnobGuard):
             m.note_doubling_signal(fp_b, "Error: EACCES", msg_count=1000 + i, result_error=True)
         body = self._body()
         proxy._maybe_lockstep_escalate(body, m)
-        self.assertIn("LOOP-ESCALATE", body["messages"][0]["content"])
-        self.assertNotIn("FINAL WARNING", body["messages"][0]["content"])
+        self.assertIn("LOOP-ESCALATE", body["messages"][-1]["content"])
+        self.assertNotIn("FINAL WARNING", body["messages"][-1]["content"])
         self.assertEqual(m.lockstep_fires, 1)
         self.assertEqual(
             [r["outcome"] for r in self._records()],
@@ -264,6 +400,138 @@ class YieldTests(LockstepKnobGuard):
         self.assertEqual(m.error_loop_fires, 1)
 
 
+class ErrorLoopDirectiveTests(LockstepKnobGuard):
+    """ERROR-LOOP's directive moved from system-top to the tail user turn (the
+    same salience fix the 2026-10-07 ledger forced for LOCKSTEP) and carries a
+    class-specific KNOWN FIX when the data has one. The opencode+qwen log
+    (2026-09-24) shows 20 ERROR-LOOP hard stops where 3 injected system-top
+    directives were ignored en route to each stop -- the generic re-read advice
+    is not merely useless for those classes, it is wrong."""
+
+    def _body(self):
+        return {
+            "messages": [
+                {"role": "user", "content": "fix it"},
+                {"role": "assistant", "content": "editing"},
+                {"role": "tool", "content": "err"},
+            ],
+            "tool_choice": "auto",
+        }
+
+    def _drive_error_loop(self, monitor, signature):
+        # varied edits, same error: error streak builds, doubling streak stays
+        # 0, so lockstep never arms and ERROR-LOOP owns the shape.
+        for _ in range(proxy.PROXY_ERROR_LOOP_THRESHOLD):
+            monitor.note_tool_result_error(signature, result_error=True)
+        self.assertFalse(proxy._lockstep_active(monitor))
+
+    def test_directive_at_tail_not_system_top(self):
+        m = proxy.SessionMonitor()
+        sig = "error: edit could not find oldstring in the file. it must match exactly"
+        self._drive_error_loop(m, sig)
+        body = self._body()
+        proxy._maybe_inject_error_loop_break(body, m)
+        tail = body["messages"][-1]
+        self.assertEqual(tail["role"], "user")  # tail user turn, not system-top
+        self.assertIn("STOP", tail["content"])
+        self.assertIn("could not find oldstring", tail["content"])
+        # the original messages are untouched -- no system-0 mangling
+        self.assertEqual(body["messages"][0]["role"], "user")
+        self.assertEqual(body["messages"][0]["content"], "fix it")
+        self.assertEqual(m.error_loop_fires, 1)
+
+    def test_directive_before_trailing_assistant_prefill(self):
+        # Same prefill contract as LOCKSTEP: a trailing assistant message is
+        # a continuation contract; the directive goes in front of it, never
+        # after (burying the prefill would 400 on thinking-enabled backends).
+        m = proxy.SessionMonitor()
+        sig = "error: edit could not find oldstring in the file. it must match exactly"
+        self._drive_error_loop(m, sig)
+        body = {
+            "messages": [
+                {"role": "user", "content": "fix it"},
+                {"role": "assistant", "content": "the fix is "},
+            ],
+            "tool_choice": "auto",
+        }
+        proxy._maybe_inject_error_loop_break(body, m)
+        prefill = body["messages"][-1]
+        directive = body["messages"][-2]
+        self.assertEqual(prefill["role"], "assistant")
+        self.assertEqual(prefill["content"], "the fix is ")  # untouched
+        self.assertEqual(directive["role"], "user")
+        self.assertIn("STOP", directive["content"])
+
+    def test_known_fix_replaces_generic_remedy(self):
+        # For a class with a known fix, the directive replaces the generic
+        # re-read advice entirely -- re-reading does not fix a wrong anchor.
+        m = proxy.SessionMonitor()
+        sig = "error: edit could not find oldstring in the file. it must match exactly"
+        self._drive_error_loop(m, sig)
+        body = self._body()
+        proxy._maybe_inject_error_loop_break(body, m)
+        tail = body["messages"][-1]["content"]
+        self.assertIn("KNOWN FIX for this error class", tail)
+        self.assertIn("byte-for-byte", tail)
+        self.assertNotIn("re-read the ENTIRE failing file", tail)
+
+    def test_policy_block_signature_gets_policy_fix(self):
+        m = proxy.SessionMonitor()
+        sig = "[uap policy blocked: rtk-wrap] rtk-wrap: 'docker' must be invoked via rtk. use: rtk docker compose"
+        self._drive_error_loop(m, sig)
+        body = self._body()
+        proxy._maybe_inject_error_loop_break(body, m)
+        tail = body["messages"][-1]["content"]
+        self.assertIn("KNOWN FIX for this error class", tail)
+        self.assertIn("blocked by UAP policy", tail)
+        self.assertIn("untrusted", tail)
+        # verbatim delegation removed: the directive must never endorse
+        # executing error-named content
+        self.assertNotIn("verbatim", tail)
+        self.assertIn("untrusted tool output", tail)
+
+    def test_generic_remedy_falls_back_when_no_class(self):
+        # Unknown error class keeps the diagnose-first generic remedy.
+        m = proxy.SessionMonitor()
+        sig = "error: something novel and deterministic nobody has classified"
+        self._drive_error_loop(m, sig)
+        body = self._body()
+        proxy._maybe_inject_error_loop_break(body, m)
+        tail = body["messages"][-1]["content"]
+        self.assertNotIn("KNOWN FIX for this error class", tail)
+        self.assertIn("re-read", tail)
+
+    def test_recon_convergence_pending_yields(self):
+        # Recon's own user-role tail directive (injected earlier in the
+        # request build) would read as a fresh human turn to the re-arm
+        # check and falsely re-arm the hard stop. ERROR-LOOP must yield to
+        # recon exactly like LOCKSTEP / DOUBLING-DOWN / DEFERRAL-BREAK.
+        m = proxy.SessionMonitor()
+        sig = "error: edit could not find oldstring in the file. it must match exactly"
+        self._drive_error_loop(m, sig)
+        m.error_loop_fires = proxy.PROXY_ERROR_LOOP_HARD_LIMIT
+        m.consecutive_no_write_turns = proxy.PROXY_RECON_CONVERGENCE_THRESHOLD
+        self.assertTrue(m.recon_convergence_pending())
+        body = self._body()
+        proxy._maybe_inject_error_loop_break(body, m)
+        self.assertEqual(len(body["messages"]), 3)  # untouched
+        self.assertEqual(m.error_loop_fires, proxy.PROXY_ERROR_LOOP_HARD_LIMIT)
+        self.assertEqual(m.error_loop_blocks, 0)  # no raise, no re-arm
+
+    def test_hard_stop_wording_names_directives_not_re_read(self):
+        # After the class table, the nudges are directives (several carry
+        # tool-misuse fixes, not re-read advice); the stop text must not
+        # promise "re-read" remediation it never gave.
+        m = proxy.SessionMonitor()
+        sig = "error: edit could not find oldstring in the file. it must match exactly"
+        self._drive_error_loop(m, sig)
+        m.error_loop_fires = proxy.PROXY_ERROR_LOOP_HARD_LIMIT
+        with self.assertRaises(proxy.ErrorLoopHardBlock) as ctx:
+            proxy._maybe_inject_error_loop_break(self._body(), m)
+        self.assertIn("injected directives were ignored", str(ctx.exception))
+        self.assertNotIn("re-read directives", str(ctx.exception))
+
+
 class IncidentRecordTests(LockstepKnobGuard):
     def test_record_shape_and_arg_redaction(self):
         m = proxy.SessionMonitor()
@@ -281,8 +549,11 @@ class IncidentRecordTests(LockstepKnobGuard):
         self.assertTrue(rec["fingerprint"])
         self.assertNotIn(FP, json.dumps(rec))  # raw args never persisted
         self.assertNotIn("ssh host", json.dumps(rec))
-        # the persisted signature is the normalized one (literals stripped)
-        self.assertIn("traceback", rec["error_signature"])
+        # the persisted signature is the normalized DECISIVE line (literals
+        # stripped). The content-free traceback header no longer anchors a
+        # streak -- ledger 2026-09-25 -- so the ledger record names the real
+        # error the session was hard-stopped over.
+        self.assertEqual(rec["error_signature"], "keyerror: 'x'")
 
     def test_ledger_disabled_by_empty_path(self):
         proxy.UAP_LOOP_INCIDENTS = ""