pi-antiloop 1.6.1 → 1.8.0

package/README.md

@@ -6,15 +6,16 @@
 
 # Antiloop — Loop Detection and Break for pi
 
-**Antiloop watches every assistant message, tool call and thinking block, and forces the model out of reasoning loops before they eat your context and your patience.** Six simultaneous detection strategies (text similarity, tool-call sequences, thinking content, structural openings, degenerate repetition, no-progress outcome runs) find loops that humans miss — and progressive intervention (warning → force break → abort) tells the model to take a different approach, without you having to babysit it.
+**Antiloop watches every assistant message, tool call and thinking block, and forces the model out of reasoning loops before they eat your context and your patience.** Seven simultaneous detection strategies (text similarity, tool-call sequences, thinking content, structural openings, degenerate repetition, block/narration repetition, no-progress outcome runs) find loops that humans miss — and progressive intervention (warning → force break → abort) tells the model to take a different approach, without you having to babysit it.
 
 ---
 
 ## Features
 
-- **Six detection strategies** — text repetition (trigram Jaccard + Levenshtein), tool-call sequences (name + near-identical arguments + same outcome — result-aware, so retries that make progress don't false-positive), thinking blocks, structural opening-phrase patterns, **degenerate repetition** (a single message/call stuck repeating one word hundreds of times — the `noguerol ×5145` meltdown — caught at `message_end` with no repeated peer needed, and degenerate bash commands blocked before they execute), and **no-progress outcome runs** (the NFS `test A…QQQ` class: dozens of near-identical re-runs of the same experiment, every one ending in the *same failing outcome* — args mutate so tool-loop can't see it; the repeated failure signature can)
+- **Seven detection strategies** — text repetition (trigram Jaccard + Levenshtein), tool-call sequences (name + near-identical arguments + same outcome — result-aware, so retries that make progress don't false-positive), thinking blocks, structural opening-phrase patterns, **degenerate repetition** (a single message/call stuck repeating one word hundreds of times — the `noguerol ×5145` meltdown — caught at `message_end` with no repeated peer needed, and degenerate bash commands blocked before they execute), **block repetition** (ONE message replaying whole sentences/phrases — the narration loop: `Let me start by checking the environment…` ×5 — same `message_end` timing and strong turn weight), and **no-progress outcome runs** (the NFS `test A…QQQ` class: dozens of near-identical re-runs of the same experiment, every one ending in the *same failing outcome* — args mutate so tool-loop can't see it; the repeated failure signature can)
 - **Stays alive in long sessions** — tracked messages carry a monotonic sequence number, so trimming the sliding window can never make the dedupe guard skip later messages (a bug that silently blinded antiloop after ~15 tracked messages)
 - **Task-stream recognition (batch work)** — when another extension (e.g. `punched` appending lines to pi.md, or `plan` adding tasks) makes the model call the *same* tool many times with *different* content, antiloop recognizes it as N distinct tasks of one type and stays silent — no warning, no force break. A genuine loop (the *same* call repeated verbatim) is still caught
+- **Snapshot/read-only tool exemption** — a coordinator closing N agents that already finished calls `trimegisto_harvest` once per agent and gets the *same* settled board every time; identical reads of a status snapshot are an idempotent serial close, not a loop, so `snapshotTools` (configurable) is exempt from tool-loop and no-progress detection — real `bash` loops next to it are still caught
 - **Progressive intervention** — `warning` reminds the model to vary its approach; `force break` steers a real break message into the running agent before its next LLM call; `abort` stops the run entirely
 - **Configurable thresholds** — independent dials for similarity cutoff, warning/force-break/abort counts, detection window, and which strategies are on
 - **Sliding window** — only the last N messages are compared, so detection is O(N) in the window size, not in the full session
@@ -100,12 +101,14 @@ Detection strategies:
   Tool loops: ✅
   Thinking loops: ✅
   Degenerate: ✅
+  Block repetition: ✅
   Outcome (no-progress): ✅
 
 Recent detections:
   [text] Text similarity 85% with message 3 (2m ago)
   [tool] repeated 3x: bash (5m ago)
   [degenerate] bash command: degenerate repetition — "noguerol" ×5145 (5m ago)
+  [block] message text: block repetition — 100% of 450 tokens replay repeated 5-word phrases (5m ago)
   [outcome] no progress: 9 near-identical bash attempts with the same failing outcome (5m ago)
 ```
 
@@ -129,7 +132,9 @@ Grouped interactive menu showing the current value in each option:
 - **🔁 call repeats** — `1 / 2 / 3` — how many times the same call must repeat before it flags (default 2)
 - **🧾 result similarity** — `95 / 80 / 60%` — how similar captured results must be to count as the *same outcome*; a repeated command that starts producing a different result is progress, not a loop (default 80%)
 - **🌀 degenerate run** — `8 / 16 / 24 / 48` — identical words in a row inside ONE message/call before it counts as stuck generation (default 16; the `noguerol ×5145` class)
-- **⛔ block degenerate bash** — on/off — refuse a degenerate bash command before it executes, feeding the reason back to the model (default on)
+- **🔁 block repetition** — on/off — detect ONE message replaying whole sentences/phrases (the narration loop: `Let me start by checking the environment…` ×5) with no repeated peer needed
+- **🔁 block share** — `70 / 85 / 95%` — share of replayed 5-word phrases in one message before it counts as a replay (default 85%)
+- **⛔ block repetitive bash** — on/off — refuse a degenerate or replayed bash command before it executes, feeding the reason back to the model (default on)
 - **📉 no-progress after** — `4 / 6 / 8 / 12` — same failing outcome repeated this many times (near-identical args) before flagging (default 8; the NFS `test A…QQQ` class)
 
 **📋 Task streams** — batch work (punched_log, plan_manager, …) is N tasks of one type, not a loop
@@ -137,11 +142,15 @@ Grouped interactive menu showing the current value in each option:
 - **📋 stream min calls** — `2 / 3 / 4 / 5` — same-tool calls required before a batch is recognized (default 3)
 - **📋 twin threshold** — `99 / 95 / 90%` — calls more similar than this count as the *same task* repeated; one twin invalidates the batch and normal detection resumes (default 99%)
 
+**📡 Snapshot tools** — read-only status boards (trimegisto_harvest, …) read serially are not a loop
+- **📡 snapshot tools** — `trimegisto_harvest` / off — repeated identical reads of a settled board stay silent all the way through (default on; add any other status/poll tool in `antiloop.json`)
+
 **🔍 Detectors**
 - **📝 text** — on/off — detect repeated text messages
 - **🔧 tools** — on/off — detect repeated tool calls
 - **🧠 thinking** — on/off — detect repeated internal reasoning
 - **🌀 degenerate** — on/off — detect one message stuck repeating a single word/token (no repeated peer needed)
+- **🔁 block** — on/off — detect one message replaying whole sentences/phrases (narration loop, no repeated peer needed)
 - **📉 outcome** — on/off — detect many near-identical attempts all ending in the same failing outcome (no progress)
 
 **🧹 reset state** — clear all counters and history
@@ -175,6 +184,9 @@ degenerate legit cmd      → ok (exp ok) ✅
 degenerate interleaved    → flag (noguerol ×150) (exp flag — freq/share clause) ✅
 degenerate glued token    → flag (noguerol ×300) (exp flag — perfect power) ✅
 degenerate turn weight    → degenerate 2, text 1 (exp 2, 1) ✅
+block S0 narration loop  → block (message text: 100% of 450 tokens replay repeated 5-word phrases) ✅   ← v1.7: ONE message replaying sentences, no peer
+block 3 cycles / 2 cycles→ flag (100%) / no (exp flag / no — needs ≥3 repeats) ✅
+block legit prose/logs   → ok (exp ok) ✅
 outcome fires on 9th      → outcome (9 near-identical bash attempts, same failing outcome) ✅   ← v1.6.1: NFS test-A…QQQ class
 outcome needs 8 prior     → silent (exp silent at 5 attempts) ✅
 outcome converging sweep  → silent (exp silent — outcomes differ = progress) ✅
@@ -186,7 +198,7 @@ outcome identical OKs     → silent (exp silent — success repeats ≠ loop)
 
 ### Detection pipeline
 
-After every assistant `message_end` event, antiloop extracts the new content (text, thinking, tool calls — including their ids) and pushes it onto a sliding window of the last `detectionWindow + 5` messages. Detection itself runs at `turn_end`, once the tool results are known: results are fingerprinted and attached to the tracked calls, then the active detection strategies run against the window. The one exception is the **degenerate** strategy: a single stuck message needs no peer and no tool result, so it is evaluated right at `message_end` — the only point before the message's own tool calls execute — and degenerate `bash` calls are also blocked at the `tool_call` hook.
+After every assistant `message_end` event, antiloop extracts the new content (text, thinking, tool calls — including their ids) and pushes it onto a sliding window of the last `detectionWindow + 5` messages. Detection itself runs at `turn_end`, once the tool results are known: results are fingerprinted and attached to the tracked calls, then the active detection strategies run against the window. The exceptions are the **intra-message** strategies — **degenerate** and **block**. A single stuck message needs no peer and no tool result, so both are evaluated right at `message_end` — the only point before the message's own tool calls execute — and repetitive `bash` calls are also blocked at the `tool_call` hook.
 
 | Strategy | What it compares | Algorithm |
 |----------|------------------|-----------|
@@ -195,10 +207,11 @@ After every assistant `message_end` event, antiloop extracts the new content (te
 | Thinking | Internal reasoning/thinking blocks | Same as text |
 | Structural | First 10 words of each message | Opening-phrase similarity ≥ 90% across ≥ 3 messages |
 | Degenerate | One single message/call (no peer needed) | Run-length + frequency of identical words inside the payload: ≥ `degenerateMaxRun` (default 16) consecutive identical words, or one word ≥ `degenerateMaxFreq`× at ≥ `degenerateMaxShare` of all tokens; plus a perfect-power check for glued no-space tokens. Scanned at `message_end` — before the tool calls execute — and on every `bash` `tool_call` (blocking gate) |
+| Block | One single message (no peer needed) | Sliding `blockNgram`-word n-grams over the normalized payload: a payload of ≥ `blockMinTokens` (120) words is a replay when ≥ `blockRepeatShare` (default 85%) of the n-gram positions recur AND the most repeated n-gram appears ≥ `blockMinRepeats` (3) times. Catches a message replaying whole sentences/phrases — the narration loop (`Let me start by checking the environment…` ×5) that every cross-message detector misses because there is no peer. Scanned at `message_end` and on every `bash` `tool_call` (blocking gate) |
 | Outcome | Single tool calls across the window, after the last user input | ≥ `outcomeMinRepeats` (default 8) PRIOR attempts with args ≥ `outcomeArgSimilarity` (0.85) similar AND the same *failing* outcome (failure signatures compared at ≥ `outcomeSigThreshold`, 0.7; identical OK results never count — they're the norm for batches). Catches mutated re-run loops the tool detector can't see (labels/permutations change every turn) |
 | Task stream | Same tool, many calls | When a tool appears ≥ `taskStreamMinCalls` times (default 3) in the window and *no two* calls are near-identical (`taskStreamTwinThreshold`, default 99%), the tool is an active batch: N different tasks of one type (e.g. `punched_log` appends, `plan_manager` task adds). Those calls are exempt from tool-loop detection, and text/thinking/structural patterns that only involve those batch messages are suppressed too. If even one call pair is a twin (the same task repeated), the tool is *not* a stream and detection proceeds normally |
 
-Each detected pair becomes a `LoopDetection { type, similarity, messageIndices, description }` and the consecutive counter increases (a degenerate turn counts `degenerateTurnWeight`, default 2 — warning on first sight).
+Each detected pair becomes a `LoopDetection { type, similarity, messageIndices, description }` and the consecutive counter increases (a degenerate or block turn counts `degenerateTurnWeight`, default 2 — warning on first sight).
 
 ### Intervention levels
 
@@ -211,7 +224,7 @@ Each detected pair becomes a `LoopDetection { type, similarity, messageIndices,
 
 The level never de-escalates during an active loop; user input decays the consecutive counter naturally so a fresh prompt can break the cycle.
 
-**Degenerate turns are handled earlier than the ladder:** the meltdown is detected at `message_end` (the same moment the text/tool-call payload is complete, *before* pi preflights and executes its tools). A single degenerate turn already adds `degenerateTurnWeight` (2) consecutive points → warning on first sight; the second consecutive meltdown → force break steer; after the steer, further degenerate output counts against `ignoredSteerLimit` → hard stop. Degenerate `bash` calls are additionally refused by the `tool_call` gate (`blockDegenerateBash`) — the command never runs, and the block reason is fed back to the model as the tool error so it can still change approach.
+**Degenerate and block turns are handled earlier than the ladder:** they are detected at `message_end` (the same moment the text/tool-call payload is complete, *before* pi preflights and executes its tools). A single such turn already adds `degenerateTurnWeight` (2) consecutive points → warning on first sight; the second consecutive one → force break steer; after the steer, further degenerate/blocked output counts against `ignoredSteerLimit` → hard stop. Repetitive `bash` calls are additionally refused by the `tool_call` gate (`blockDegenerateBash`) — the command never runs, and the block reason is fed back to the model as the tool error so it can still change approach.
 
 ### Similarity scoring
 
@@ -252,6 +265,7 @@ If the same command produced a *different* outcome, the pair is progress:
 
 Results only veto; they never trigger on their own, and calls without a
 captured result fall back to argument matching alone.
+```
 
 ### Task streams: N tasks of one type ≠ a loop
 
@@ -287,6 +301,27 @@ size needed before recognition), `taskStreamTwinThreshold` (how similar args
 must be to count as *the same task* — lower it to treat near-duplicate
 entries as loops again).
 
+### Snapshot tools: the serial close of settled agents ≠ a loop
+
+A coordinator that closes N agents which have already finished calls the
+snapshot tool once per agent. When the agents are all settled, every one of
+those calls returns the **same** serialized board — same arguments (`{}`),
+same result. To the tool detector that is indistinguishable from a verbatim
+loop: `same args + same outcome` repeated N times, so it force-broke a run
+that was simply collecting finished results.
+
+Re-reading a state snapshot is an *idempotent read*, not a stuck generation,
+so tools listed in `snapshotTools` (default `["trimegisto_harvest"]`) are
+exempt from tool-loop **and** no-progress outcome detection. The exemption is
+deliberately narrow:
+
+- it only applies when *every* call in the message is a snapshot tool — a
+  real `bash` loop re-run alongside a harvest is still flagged;
+- it is name-based and configurable, so `antiloop.json` can list any other
+  status/poll tool (`"snapshotTools": ["trimegisto_harvest", "my_status"]`);
+- clearing it (`"snapshotTools": []` or **📡 off**) restores normal detection,
+  where the very same 5× harvest payload is a genuine verbatim tool loop.
+
 ### Degenerate repetition: ONE message stuck on a word ≠ a reasoning loop
 
 All strategies above need at least two similar messages — they detect a model
@@ -333,6 +368,49 @@ sweeps that motivated the tool-loop threshold). Only `bash` gets the blocking
 gate — writing a repetitive *file* (e.g. a user-requested padding fixture) is
 alerted and escalated, not refused.
 
+### Block repetition: ONE message replaying its own sentences
+
+The degenerate detector catches a single *word* repeated hundreds of times.
+There is a second intra-message failure mode, just as obvious to a human and
+invisible to every cross-message detector: **the model replays whole
+sentences/phrases inside one generation**. Real case (a coding session's S0
+scaffold): ONE assistant message cycled ~5 times through
+
+> Let me start by checking the environment and the current state of the
+> repository, then set up a plan for the S0 slice and begin building.
+> I'll run several independent checks in parallel.
+> Let me begin the S0 development. First, reconnaissance of the environment
+> and current repo state.
+
+…never emitting a tool call. Text/tool/thinking/structural detection all
+compare *across* messages and had nothing to compare against; the degenerate
+scan only watches for one word repeated, and no single word repeated 16×.
+
+Antiloop v1.7 detects **block repetition** on the message itself:
+
+- the payload is read as a stream of lowercase alphanumeric words;
+- a sliding window of `blockNgram` (default 5) words is built over it;
+- if at least `blockRepeatShare` (default **85%**) of those n-gram positions
+  recur somewhere else, the most repeated n-gram appears at least
+  `blockMinRepeats` (default 3) times, and the payload has at least
+  `blockMinTokens` (default 120) words, the generation is replaying itself.
+
+The thresholds are deliberately far apart from normal content: ordinary
+prose — even long, structured documents — scores ≤ 11% coverage, while 3+
+replays of a narration block reach 98–100%. Templated payloads with evolving
+data (log lines, generated code) are not flagged because their n-grams carry
+the varying digits and differ. A single restatement (2 cycles) does not trip
+it — one echo is a summary, three are stuck generation.
+
+Because the signal is conclusive it is handled like the degenerate one:
+caught at `message_end` (before the message's tools execute), weighted
+`degenerateTurnWeight` (2) so the first occurrence warns, and a replayed
+`bash` command is refused by the same `blockDegenerateBash` gate. After a
+force-break steer, another replayed block escalates to the hard stop.
+
+Tunables: `detectBlockRepeats`, `blockRepeatShare` (lower = earlier),
+`blockMinRepeats`, `blockNgram`, `blockMinTokens`.
+
 ### No-progress outcome runs: mutated re-runs, same wall
 
 A subtler meltdown than the degenerate one: the model re-runs the SAME
@@ -372,7 +450,6 @@ real session this fires at `test MM` (warn) → `NN` (steer) → `PP` (abort)
 
 Tunables: `detectOutcomeLoops`, `outcomeMinRepeats` (lower = earlier cutoff),
 `outcomeArgSimilarity`, `outcomeSigThreshold`.
-```
 
 ### Sliding window
 
@@ -399,6 +476,11 @@ Persisted as JSON at `~/.pi/agent/antiloop.json`:
   "degenerateMaxShare": 0.4,
   "degenerateTurnWeight": 2,
   "blockDegenerateBash": true,
+  "detectBlockRepeats": true,
+  "blockMinTokens": 120,
+  "blockNgram": 5,
+  "blockMinRepeats": 3,
+  "blockRepeatShare": 0.85,
   "detectOutcomeLoops": true,
   "outcomeMinRepeats": 8,
   "outcomeArgSimilarity": 0.85,
@@ -433,7 +515,12 @@ Persisted as JSON at `~/.pi/agent/antiloop.json`:
 | `degenerateMaxFreq` | `60` | One word's total occurrences (with `degenerateMaxShare` of the payload) that flags interleaved meltdowns |
 | `degenerateMaxShare` | `0.4` | Frequency share (freq/total tokens) required together with `degenerateMaxFreq` |
 | `degenerateTurnWeight` | `2` | Consecutive-detection points added by one degenerate turn (2 = warning on first sight) |
-| `blockDegenerateBash` | `true` | Block a degenerate `bash` command in the `tool_call` hook before it executes; the reason is fed back to the model as the tool error |
+| `blockDegenerateBash` | `true` | Block a degenerate or block-repetition `bash` command in the `tool_call` hook before it executes; the reason is fed back to the model as the tool error |
+| `detectBlockRepeats` | `true` | Detect intra-message block/narration repetition — ONE message replaying whole sentences/phrases (the `Let me start by checking the environment…` ×5 class). Needs no repeated peer; scanned at `message_end` and on every bash `tool_call` |
+| `blockMinTokens` | `120` | Minimum normalized words in a payload before it is scanned for block repetition (shorter payloads aren't conclusive) |
+| `blockNgram` | `5` | Word window of the n-grams whose recurrence is measured |
+| `blockMinRepeats` | `3` | The most repeated n-gram must occur at least this many times to flag |
+| `blockRepeatShare` | `0.85` | Share of n-gram positions that must recur for the payload to count as a replay |
 | `detectOutcomeLoops` | `true` | No-progress outcome runs: ≥ `outcomeMinRepeats` near-identical attempts (args ≥ `outcomeArgSimilarity`) all ending in the *same failing outcome* — the NFS `test A…QQQ` class |
 | `outcomeMinRepeats` | `8` | Prior same-failure attempts (inside the window, after the last user input) required before the outcome detector fires |
 | `outcomeArgSimilarity` | `0.85` | How similar args must be to count as the *same experiment reshuffled* (mutations of labels/permutations stay under it — distinct tasks don't) |
@@ -441,6 +528,7 @@ Persisted as JSON at `~/.pi/agent/antiloop.json`:
 | `detectTaskStreams` | `true` | Recognize homogeneous batch work (same tool called with distinct content — e.g. punched/plan/obsidian extensions) and stay silent; see [task streams](#task-streams-n-tasks-of-one-type--a-loop) |
 | `taskStreamMinCalls` | `3` | Same-tool calls required inside the window before a task stream is recognized |
 | `taskStreamTwinThreshold` | `0.99` | Arguments this similar (or identical) count as *the same task* — a twin invalidates the stream and re-enables normal loop detection |
+| `snapshotTools` | `["trimegisto_harvest"]` | Read-only snapshot/status tools: repeated identical reads (the serial close of N settled agents) never count as a tool loop or no-progress run. Add any other status/poll tool by name |
 | `detectTextLoops` | `true` | Detect full-text repetition |
 | `detectToolLoops` | `true` | Detect tool-call sequence + argument repetition |
 | `detectThinkingLoops` | `true` | Detect repeated thinking/reasoning content |
@@ -460,7 +548,8 @@ Persisted as JSON at `~/.pi/agent/antiloop.json`:
 6. **Let user input clear state** — each user message decays the consecutive counter by 2, so a fresh prompt naturally resets without `/antiloop reset`.
 7. **Degenerate detector needs no tuning for most setups** — a run of ≥ 16 identical words (or one word ≥ 40% of a ≥ 50-token payload) inside a single message is conclusive stuck generation; the 46 KB `noguerol ×5145` SSH-wordlist meltdown is caught on first sight (warning), its bash never executes (`blockDegenerateBash`), and a second consecutive meltdown gets the force-break steer. If a model legitimately writes repetitive payloads, raise `degenerateMaxRun` / `degenerateMaxFreq` via `/antiloop config` — don't disable the detector.
 8. **Outcome detector catches mutated re-run loops** — a model that re-issues the same experiment with cosmetic changes (labels, permutations) while every attempt fails identically gets a warning after `outcomeMinRepeats` (8) same-failure attempts, a steer on the next, and a hard stop shortly after. Converging sweeps, evolving failures and repeated successes stay silent by design. Lower `outcomeMinRepeats` if you want earlier cutoffs.
-9. **`/antiloop test`** — runs the real detection engine (text + tool-call + task-stream + degenerate + outcome regression cases) to verify calibration after any change.
+9. **Block detector catches narration loops** — a single message replaying whole sentences (the `Let me start by checking the environment…` ×5 class) warns on first sight and escalates like a meltdown. It only fires when ≥ 85% of the message's 5-word phrases recur, so ordinary prose and templated logs/code stay silent. Raise `blockRepeatShare` (or `blockMinRepeats`) if you ever see a false positive.
+10. **`/antiloop test`** — runs the real detection engine (text + tool-call + task-stream + degenerate + block + outcome regression cases) to verify calibration after any change.
 
 ## Architecture
 
@@ -485,10 +574,10 @@ Modular extension with zero external dependencies (only pi's bundled `@earendil-
 
 - **Levenshtein + trigram Jaccard** hybrid — small texts use edit distance, large texts use n-gram overlap (each is O(N) in text length)
 - **Sliding window** — only the last `detectionWindow` messages participate, capping memory at O(W × message_size)
-- **Early bail** — short messages and empty tool calls skip similarity computation entirely; the degenerate scan is a single linear tokenization pass
+- **Early bail** — short messages and empty tool calls skip similarity computation entirely; the degenerate and block scans are single linear passes
 - **TUI integration** — uses `ctx.ui.select` for the config menu and the log viewer; `ctx.ui.notify` for state notifications; `ctx.ui.setStatus` + a custom `ctx.ui.setFooter` component for the persistent footer indicator, live level info, and the `esc+a` keyboard toggle (`ctx.ui.onTerminalInput`, never consumes input)
-- **Hooks** — `message_end` (track messages + tool call ids with a monotonic sequence so the sliding-window trim can never collide turn indices, and pre-handle degenerate meltdowns — the message is complete but its tools haven't executed yet), `tool_call` (block degenerate `bash` commands before they run), `turn_end` (attach result fingerprints with failure signatures, detect — including no-progress outcome runs — and intervene: steer the force break / abort the run), `input` (decay on real user messages only), `session_start` (load config + install footer + reset), `session_shutdown` (restore built-in footer)
-- **Intervention runs on the turn loop, not on user prompts** — escalation is decided at `turn_end` (and at `message_end` for the self-contained degenerate signal), the break is steered into the running agent before its next LLM call, and the guaranteed hard stop aborts the run (`ctx.abort`, fire-and-forget — never awaited, so the hook can't deadlock). No custom-role messages are injected into the conversation at any level (steering a real user message + aborting are the only levers; custom-role injections were removed because a model can stall on an unexpected injected message)
+- **Hooks** — `message_end` (track messages + tool call ids with a monotonic sequence so the sliding-window trim can never collide turn indices, and pre-handle degenerate/block repetition — the message is complete but its tools haven't executed yet), `tool_call` (block degenerate or replayed `bash` commands before they run), `turn_end` (attach result fingerprints with failure signatures, detect — including no-progress outcome runs — and intervene: steer the force break / abort the run), `input` (decay on real user messages only), `session_start` (load config + install footer + reset), `session_shutdown` (restore built-in footer)
+- **Intervention runs on the turn loop, not on user prompts** — escalation is decided at `turn_end` (and at `message_end` for the self-contained intra-message signals), the break is steered into the running agent before its next LLM call, and the guaranteed hard stop aborts the run (`ctx.abort`, fire-and-forget — never awaited, so the hook can't deadlock). No custom-role messages are injected into the conversation at any level (steering a real user message + aborting are the only levers; custom-role injections were removed because a model can stall on an unexpected injected message)
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-antiloop",
-  "version": "1.6.1",
-  "description": "Antiloop: detect reasoning loops and force a break (warn → force → abort) across text, tool, thinking, structural, degenerate-repetition, and no-progress outcome patterns. Degenerate (one message stuck repeating a word hundreds of times — noguerol ×5145) is caught at message_end and its bash blocked before executing. No-progress (the NFS test-A…QQQ class: ~90 mutated re-runs of the same experiment, every one failing identically) fires when the same failing outcome repeats ≥ outcomeMinRepeats times with near-identical args. Fixes antiloop going blind mid-session: tracked messages use a monotonic sequence so the trim of the sliding window can never collide turn indices. The force break is delivered mid-run (steer before the next LLM call) and if the model ignores it antiloop aborts the run — an autonomous tool loop always terminates. Result-aware tool-loop detection keeps sequential bash and converging sweeps quiet; task-stream recognition keeps punched/plan batch work quiet.",
+  "version": "1.8.0",
+  "description": "Antiloop: detect reasoning loops and force a break (warn → force → abort) across text, tool, thinking, structural, degenerate-repetition, block/narration-repetition, and no-progress outcome patterns. Degenerate (one message stuck repeating a word hundreds of times — noguerol ×5145) is caught at message_end and its bash blocked before executing. Block (ONE message replaying whole sentences/phrases — the 'Let me start by checking the environment…' ×5 narration loop, invisible to every cross-message detector because there is no peer) fires on the first such message with the same strong turn weight and blocks a replayed bash command. No-progress (the NFS test-A…QQQ class: ~90 mutated re-runs of the same experiment, every one failing identically) fires when the same failing outcome repeats ≥ outcomeMinRepeats times with near-identical args. Snapshot tools (trimegisto_harvest) are exempt: a coordinator closing N settled agents re-reads the SAME board serially, which is an idempotent read, not a loop — so isVerbatimRepeat never fires on it. Fixes antiloop going blind mid-session: tracked messages use a monotonic sequence so the trim of the sliding window can never collide turn indices. The force break is delivered mid-run (steer before the next LLM call) and if the model ignores it antiloop aborts the run — an autonomous tool loop always terminates. Result-aware tool-loop detection keeps sequential bash and converging sweeps quiet; task-stream recognition keeps punched/plan batch work quiet.",
   "keywords": [
     "pi-package",
     "antiloop",

package/src/commands.ts

@@ -59,10 +59,12 @@ async function showStatus(ctx: ExtensionCommandContext, rt: Runtime): Promise<vo
 		`  tool sim: ${(rt.config.toolSimilarityThreshold * 100).toFixed(0)}%  tool repeat: ${rt.config.minToolRepeatCount}+ prior`,
 		`  result sim: ${(rt.config.resultSimilarityThreshold * 100).toFixed(0)}%  (same cmd + diff outcome = no loop)`,
 		`  degenerate: run ≥ ${rt.config.degenerateMaxRun} same word · freq ≥ ${rt.config.degenerateMaxFreq} @ ${(rt.config.degenerateMaxShare * 100).toFixed(0)}% (≥ ${rt.config.degenerateMinTokens} tokens) · weight ${rt.config.degenerateTurnWeight} · block bash ${yn(rt.config.blockDegenerateBash)}`,
+		`  block repeats: ${yn(rt.config.detectBlockRepeats)} (≥ ${(rt.config.blockRepeatShare * 100).toFixed(0)}% of ≥ ${rt.config.blockMinTokens} tokens replay ${rt.config.blockNgram}-grams ×${rt.config.blockMinRepeats}+)`,
 		`  outcome: same failing result ≥ ${rt.config.outcomeMinRepeats} attempts (args ≥ ${(rt.config.outcomeArgSimilarity * 100).toFixed(0)}% sim, sig ≥ ${(rt.config.outcomeSigThreshold * 100).toFixed(0)}%)`,
 		`  task streams: ${yn(rt.config.detectTaskStreams)} (min ${rt.config.taskStreamMinCalls} calls, twins ≥ ${(rt.config.taskStreamTwinThreshold * 100).toFixed(0)}%)`,
+		`  snapshot tools: ${rt.config.snapshotTools?.length ? rt.config.snapshotTools.join(", ") : "off"} (repeated reads are not a loop)`,
 		"",
-		`detectors: text ${yn(rt.config.detectTextLoops)} · tool ${yn(rt.config.detectToolLoops)} · think ${yn(rt.config.detectThinkingLoops)} · degenerate ${yn(rt.config.detectDegenerate)} · outcome ${yn(rt.config.detectOutcomeLoops)}`,
+		`detectors: text ${yn(rt.config.detectTextLoops)} · tool ${yn(rt.config.detectToolLoops)} · think ${yn(rt.config.detectThinkingLoops)} · degenerate ${yn(rt.config.detectDegenerate)} · block ${yn(rt.config.detectBlockRepeats)} · outcome ${yn(rt.config.detectOutcomeLoops)}`,
 		`footer: interactive ${yn(rt.config.interactiveFooter)} · toggle: ${rt.config.toggleShortcut}`,
 	];
 	if (rt.state.activeTaskStreams.length) {
@@ -95,13 +97,16 @@ async function showConfigMenu(ctx: ExtensionCommandContext, rt: Runtime): Promis
 		{ value: "resultSim" as const, label: `🧾 result similarity: ${(c.resultSimilarityThreshold * 100).toFixed(0)}%`, description: "same command + different result = progress, not a loop" },
 		// ── 🌀 Degenerate (intra-message meltdown) ───────────────────────
 		{ value: "degRun" as const, label: `🌀 degenerate run: ≥ ${c.degenerateMaxRun}`, description: "identical words in a row inside ONE message/call before it counts as stuck generation (noguerol ×5145 class)" },
-		{ value: "degBlock" as const, label: `⛔ block degenerate bash: ${yn(c.blockDegenerateBash)}`, description: "stop a degenerate command before it executes (default on)" },
+		{ value: "blk" as const, label: `🔁 block repetition: ${yn(c.detectBlockRepeats)}`, description: "ONE message replaying whole sentences/phrases (the narration loop: 'Let me start by checking…' ×5)" },
+		{ value: "blkShare" as const, label: `🔁 block share: ≥ ${(c.blockRepeatShare * 100).toFixed(0)}%`, description: "share of replayed 5-word phrases in one message before it counts as a replay" },
+		{ value: "degBlock" as const, label: `⛔ block repetitive bash: ${yn(c.blockDegenerateBash)}`, description: "stop a degenerate or replayed command before it executes (default on)" },
 		// ── 📉 Outcome (no-progress) ────────────────────────────────
 		{ value: "outcomeMin" as const, label: `📉 no-progress after: ${c.outcomeMinRepeats}`, description: "same failing outcome repeated this many times (mutated args ≥ 85% similar) before flagging — the NFS test-A…QQQ class" },
 		// ── 📋 Task streams ─────────────────────────────────────────
 		{ value: "streams" as const, label: `📋 task streams: ${yn(c.detectTaskStreams)}`, description: "batch work (punched_log / plan_manager / …) is not a loop" },
 		{ value: "streamMin" as const, label: `📋 stream min calls: ${c.taskStreamMinCalls}`, description: "calls of the same tool before a batch is recognized" },
 		{ value: "streamTwin" as const, label: `📋 twin threshold: ${(c.taskStreamTwinThreshold * 100).toFixed(0)}%`, description: "calls more similar than this = the same task repeated, not a batch" },
+		{ value: "snapshot" as const, label: `📡 snapshot tools: ${c.snapshotTools?.length ? c.snapshotTools.join(", ") : "off"}`, description: "read-only status tools (trimegisto_harvest): re-reading settled agents serially is not a loop" },
 		// ── 🔍 Detectors ────────────────────────────────────────────
 		{ value: "text" as const, label: `📝 text: ${yn(c.detectTextLoops)}`, description: "detect repeated text messages" },
 		{ value: "tool" as const, label: `🔧 tools: ${yn(c.detectToolLoops)}`, description: "detect repeated tool calls" },
@@ -227,9 +232,21 @@ async function showConfigMenu(ctx: ExtensionCommandContext, rt: Runtime): Promis
 			if (v !== undefined) { c.degenerateMaxRun = v; saveConfig(c); ctx.ui.notify(`degenerate run: ≥ ${v}`, "info"); }
 			break;
 		}
+		case "blk":
+			c.detectBlockRepeats = !c.detectBlockRepeats; saveConfig(c);
+			ctx.ui.notify(`block repetition: ${yn(c.detectBlockRepeats)}`, "info"); break;
+		case "blkShare": {
+			const v = await selectFrom(ctx, "🔁 block repetition share (replayed 5-gram positions in ONE message)", [
+				{ value: 0.7, label: "⚡ 70% (sensitive)" },
+				{ value: 0.85, label: "🎯 85% (default)" },
+				{ value: 0.95, label: "🐢 95% (only near-total replays)" },
+			]);
+			if (v !== undefined) { c.blockRepeatShare = v; saveConfig(c); ctx.ui.notify(`block share: ${(v * 100).toFixed(0)}%`, "info"); }
+			break;
+		}
 		case "degBlock":
 			c.blockDegenerateBash = !c.blockDegenerateBash; saveConfig(c);
-			ctx.ui.notify(`block degenerate bash: ${yn(c.blockDegenerateBash)}`, "info"); break;
+			ctx.ui.notify(`block repetitive bash: ${yn(c.blockDegenerateBash)}`, "info"); break;
 		case "outcomeMin": {
 			const v = await selectFrom(ctx, "📉 no-progress threshold (same failing outcome, near-identical args)", [
 				{ value: 4, label: "⚡ 4 (sensitive — long experiment series get cut early)" },
@@ -262,6 +279,18 @@ async function showConfigMenu(ctx: ExtensionCommandContext, rt: Runtime): Promis
 			if (v !== undefined) { c.taskStreamTwinThreshold = v; saveConfig(c); ctx.ui.notify(`twin threshold: ${(v * 100).toFixed(0)}%`, "info"); }
 			break;
 		}
+		case "snapshot": {
+			const v = await selectFrom(ctx, "📡 snapshot / read-only tools (repeated identical reads are never a loop)", [
+				{ value: "default" as const, label: "🎯 trimegisto_harvest (default)", description: "serial close of settled agents: same args + same snapshot ×N stays silent" },
+				{ value: "off" as const, label: "🚫 off", description: "treat every tool identically (harvest can loop-flag again)" },
+			]);
+			if (v !== undefined) {
+				c.snapshotTools = v === "off" ? [] : ["trimegisto_harvest"];
+				saveConfig(c);
+				ctx.ui.notify(`snapshot tools: ${c.snapshotTools.length ? c.snapshotTools.join(", ") : "off"}`, "info");
+			}
+			break;
+		}
 		case "ignoredBreak": {
 			const v = await selectFrom(ctx, "🛑 stop after ignored break (identical repeats after the force break)", [
 				{ value: 1, label: "⚡ 1 (sensitive — one identical repeat after the break stops the run)" },

package/src/config.ts

@@ -24,6 +24,11 @@ export const DEFAULT_CONFIG: AntiloopConfig = {
 	degenerateMaxShare: 0.4,
 	degenerateTurnWeight: 2,
 	blockDegenerateBash: true,
+	detectBlockRepeats: true,
+	blockMinTokens: 120,
+	blockNgram: 5,
+	blockMinRepeats: 3,
+	blockRepeatShare: 0.85,
 	detectOutcomeLoops: true,
 	outcomeMinRepeats: 8,
 	outcomeArgSimilarity: 0.85,
@@ -31,6 +36,7 @@ export const DEFAULT_CONFIG: AntiloopConfig = {
 	detectTaskStreams: true,
 	taskStreamMinCalls: 3,
 	taskStreamTwinThreshold: 0.99,
+	snapshotTools: ["trimegisto_harvest"],
 	detectToolLoops: true,
 	detectThinkingLoops: true,
 	detectTextLoops: true,

package/src/detect.ts

@@ -185,12 +185,124 @@ export function degenerateDescription(hit: DegenerateHit): string {
 	return `${hit.where}: degenerate repetition — "${hit.token}" ×${hit.freq} (${share}% of ${hit.total} tokens, longest run ${hit.maxRun})`;
 }
 
+// ---------------------------------------------------------------------------
+// Intra-message BLOCK repetition (v1.7).
+//
+// The "narration loop" class (verified against a real coding session: ONE
+// assistant message replaying ~5 near-verbatim cycles of "Let me start by
+// checking the environment and the current state of the repository… / I'll run
+// several independent checks in parallel. / Let me begin the S0 development…").
+// Every pre-existing detector stayed silent: text/tool/thinking/structural all
+// compare ACROSS messages (the model produced one message, no peer), and the
+// degenerate detector only watches ONE word repeated hundreds of times, not a
+// whole sentence/paragraph replayed. The signal here is phrase-level: a sliding
+// window of blockNgram-word n-grams over the normalized payload; if almost ALL
+// of those n-grams recur and the most frequent one recurs ≥ blockMinRepeats
+// times, the generation is replaying itself instead of advancing.
+//
+// Deliberately conservative: only a payload where ≥ blockRepeatShare (default
+// 85%) of 5-gram positions repeat qualifies. Ordinary prose — even long,
+// structured docs — sits far below (README/pi.md paragraphs: ≤ 0.11), while
+// 3+ replays of a narration block reach 0.98–1.0. Repeat-linked code/log lines
+// that share a template are NOT flagged because their n-grams carry the varying
+// digits and differ.
+// ---------------------------------------------------------------------------
+
+/** Recursive n-gram coverage of one payload. */
+export interface BlockRepeatInfo {
+	/** Recurring n-gram positions / total n-gram positions (0..1). */
+	ratio: number;
+	/** Occurrences of the MOST repeated n-gram. */
+	repeats: number;
+	/** Total normalized words in the payload. */
+	tokens: number;
+	/** The n used (words per window). */
+	ngram: number;
+	/** The most repeated n-gram, for the description. */
+	sample: string;
+}
+
+export interface BlockRepeatHit extends BlockRepeatInfo {
+	where: string;
+}
+
+/**
+ * Detect phrase/block-level self-repetition inside ONE payload. Returns the
+ * coverage ratio with the most repeated n-gram, or undefined for normal text.
+ *
+ * Reads the payload as a stream of lowercase alphanumeric words (code symbols
+ * and punctuation are separators, so stored-JSON escaping cannot glue tokens).
+ * Coverage counts an n-gram position as repeated when the SAME n-word sequence
+ * (digits included, so templated lines with varying numbers do not count)
+ * occurs somewhere else in the payload.
+ */
+export function findRepetitiveBlock(text: string, config: AntiloopConfig): BlockRepeatInfo | undefined {
+	const words = String(text).toLowerCase().match(/[\p{L}\p{N}]+/gu);
+	if (!words) return undefined;
+	const total = words.length;
+	if (total < config.blockMinTokens) return undefined;
+	const n = Math.max(2, config.blockNgram);
+	const minRepeats = Math.max(2, config.blockMinRepeats);
+	if (total < n * minRepeats) return undefined;
+
+	const counts = new Map<string, number>();
+	const grams: string[] = [];
+	for (let i = 0; i + n <= total; i++) {
+		const g = words.slice(i, i + n).join(" ");
+		grams.push(g);
+		counts.set(g, (counts.get(g) ?? 0) + 1);
+	}
+	if (!grams.length) return undefined;
+
+	let covered = 0;
+	let topKey = "";
+	let top = 0;
+	for (const g of grams) {
+		const c = counts.get(g)!;
+		if (c > top) {
+			top = c;
+			topKey = g;
+		}
+		if (c >= 2) covered++;
+	}
+	// At least one n-word phrase must recur blockMinRepeats times (a single
+	// echo is a restatement, not a replay) and the recurrence must dominate.
+	if (top < minRepeats) return undefined;
+	const ratio = covered / grams.length;
+	if (ratio < config.blockRepeatShare) return undefined;
+	return { ratio, repeats: top, tokens: total, ngram: n, sample: topKey };
+}
+
+/** Scan one assistant message (text + each tool-call argument) for a replay. */
+export function scanMessageBlock(
+	content: string,
+	toolCalls: TrackedToolCall[] | undefined,
+	config: AntiloopConfig,
+): BlockRepeatHit | undefined {
+	if (!config.detectBlockRepeats) return undefined;
+	if (content && content.length) {
+		const b = findRepetitiveBlock(content, config);
+		if (b) return { ...b, where: "message text" };
+	}
+	for (const tc of toolCalls ?? []) {
+		if (!tc.args) continue;
+		const b = findRepetitiveBlock(tc.args, config);
+		if (b) return { ...b, where: tc.name === "bash" ? "bash command" : `args(${tc.name})` };
+	}
+	return undefined;
+}
+
+export function blockRepeatDescription(hit: BlockRepeatHit): string {
+	const pct = Math.round(hit.ratio * 100);
+	return `${hit.where}: block repetition — ${pct}% of ${hit.tokens} tokens replay repeated ${hit.ngram}-word phrases ("${hit.sample}" ×${hit.repeats})`;
+}
+
 /** Consecutive-detection weight of a detection turn. The strong
  * self-contained signals (degenerate meltdown, proven no-progress outcome run)
  * add degenerateTurnWeight (default 2) points so the FIRST one already reaches
  * the warning level and escalation is fast on repeat. */
 export function detectionTurnWeight(detections: LoopDetection[], config: AntiloopConfig): number {
-	const strong = detections.some((d) => d.type === "degenerate" || d.type === "outcome");
+	const strong = detections.some((d) => d.type === "degenerate" || d.type === "block" || d.type === "outcome");
 	return strong ? Math.max(1, config.degenerateTurnWeight) : 1;
 }
 
@@ -383,6 +495,28 @@ export function detectTaskStreams(
 	return streams;
 }
 
+// ---------------------------------------------------------------------------
+// Snapshot / read-only tools (v1.8).
+//
+// A coordinator closing N agents that already finished calls the snapshot tool
+// once per agent and gets the SAME serialized board every time (all settled).
+// Same args + same result looks exactly like a verbatim tool loop to the
+// detector, but re-reading a state snapshot is an idempotent read — the serial
+// close of finished work, not a stuck generation. Tools listed in
+// config.snapshotTools (default: trimegisto_harvest) are therefore exempt from
+// tool-loop and outcome detection. Any other status/poll tool can be added.
+// ---------------------------------------------------------------------------
+
+/** Set of tool names whose repeated identical reads must never count as a loop. */
+function snapshotToolSet(config: AntiloopConfig): Set<string> {
+	return new Set((config.snapshotTools ?? []).map((n) => n.trim()).filter(Boolean));
+}
+
+/** True when every call in the set is a snapshot/status read. */
+function allSnapshotCalls(calls: TrackedToolCall[] | undefined, snapshots: Set<string>): boolean {
+	return !!calls && calls.length > 0 && calls.every((c) => snapshots.has(c.name));
+}
+
 export function detectLoops(state: AntiloopState, config: AntiloopConfig): LoopDetection[] {
 	const out: LoopDetection[] = [];
 	const msgs = state.recentMessages;
@@ -391,9 +525,10 @@ export function detectLoops(state: AntiloopState, config: AntiloopConfig): LoopD
 	const win = msgs.slice(start);
 	const now = Date.now();
 
-	// Intra-message degenerate repetition fires on a SINGLE pathological message
-	// (no peer needed) and is independent of the task-stream batch gate: a
-	// meltdown is a meltdown even mid-batch.
+	// Intra-message repetition fires on a SINGLE pathological message (no peer
+	// needed) and is independent of the task-stream batch gate: a meltdown is a
+	// meltdown even mid-batch. Two flavors: degenerate (one word ×hundreds) and
+	// block (whole sentences/phrases replayed — the narration-loop class).
 	if (config.detectDegenerate) {
 		const last = win[win.length - 1];
 		const hit = scanMessageDegenerate(last.content, last.toolCalls, config);
@@ -408,12 +543,29 @@ export function detectLoops(state: AntiloopState, config: AntiloopConfig): LoopD
 		}
 	}
 
+	if (config.detectBlockRepeats) {
+		const last = win[win.length - 1];
+		const hit = scanMessageBlock(last.content, last.toolCalls, config);
+		if (hit) {
+			out.push({
+				type: "block",
+				// 0.99 => isVerbatimRepeat(): after a force break, a replayed block
+				// is the model ignoring the break and escalates to the hard stop.
+				similarity: 0.99,
+				messageIndices: [msgs.length - 1],
+				description: blockRepeatDescription(hit),
+				timestamp: now,
+			});
+		}
+	}
+
 	// Task-stream gate: if the window is a homogeneous batch (same extension
 	// tool called with DISTINCT content ≥ taskStreamMinCalls times), that tool
 	// is exempt from tool-loop detection, and text/thinking/structural
 	// detections that only involve batch messages are suppressed too — the
 	// model is doing N different tasks of the same type, not looping.
 	const streams = detectTaskStreams(win, config);
+	const snapshots = snapshotToolSet(config);
 	const batchAt = new Set<number>();
 	win.forEach((m, idx) => {
 		const calls = m.toolCalls;
@@ -467,7 +619,10 @@ export function detectLoops(state: AntiloopState, config: AntiloopConfig): LoopD
 		const lastCalls = last.toolCalls;
 		// A message whose calls are all task-stream tools is batch work — skip
 		// it entirely (the stream gate already proved the calls are distinct).
-		if (lastCalls && lastCalls.length && !batchAt.has(msgs.length - 1)) {
+		// Snapshot/status tools (trimegisto_harvest…) are also skipped: repeated
+		// identical reads of a settled board are the serial close of finished
+		// agents, not a loop.
+		if (lastCalls && lastCalls.length && !batchAt.has(msgs.length - 1) && !allSnapshotCalls(lastCalls, snapshots)) {
 			const matched: number[] = [];
 			for (let i = 0; i < win.length - 1; i++) {
 				const prev = win[i].toolCalls;
@@ -525,7 +680,9 @@ export function detectLoops(state: AntiloopState, config: AntiloopConfig): LoopD
 			// produce the SAME OK outcome every call — they must never count. And
 			// batch messages must NOT be skipped here: a "bash ×N stream" with
 			// identical failures is exactly the no-progress loop to catch.
-			if (lc.result && isFailResult(lc.result)) {
+			// Snapshot/status reads are excluded outright: an identical harvest
+			// snapshot is a state read, not a repeated failing experiment.
+			if (lc.result && isFailResult(lc.result) && !snapshots.has(lc.name)) {
 				let matches = 0;
 				for (let i = 0; i < win.length - 1; i++) {
 					const m = win[i];
@@ -673,8 +830,10 @@ export function runSelfTest(): string[] {
 		detectTextLoops: true, notifyOnDetection: true, maxHistoryEntries: 100,
 		detectionWindow: 10, interactiveFooter: true, toggleShortcut: "esc+a",
 		detectTaskStreams: true, taskStreamMinCalls: 3, taskStreamTwinThreshold: 0.99,
+		snapshotTools: ["trimegisto_harvest"],
 		detectDegenerate: true, degenerateMinTokens: 50, degenerateMaxRun: 16,
 		degenerateMaxFreq: 60, degenerateMaxShare: 0.4, degenerateTurnWeight: 2, blockDegenerateBash: true,
+		detectBlockRepeats: true, blockMinTokens: 120, blockNgram: 5, blockMinRepeats: 3, blockRepeatShare: 0.85,
 		detectOutcomeLoops: true, outcomeMinRepeats: 8, outcomeArgSimilarity: 0.85, outcomeSigThreshold: 0.7,
 	};
 	const asState = (recentMessages: TrackedMessage[]): AntiloopState =>
@@ -782,6 +941,56 @@ export function runSelfTest(): string[] {
 	const wTxt = detectionTurnWeight(dl("text", 0.8), tcfg);
 	out.push(`degenerate turn weight    → degenerate ${wDeg}, text ${wTxt} (exp 2, 1) ${wDeg === 2 && wTxt === 1 ? "✅" : "❌"}`);
 
+	// --- v1.7: intra-message BLOCK repetition (narration loops) ---
+	// Regression: a real coding session where ONE assistant message replayed the
+	// same ~5 sentences in a loop ("Let me start by checking the environment…" /
+	// "I'll run several independent checks in parallel." / "Let me begin the S0
+	// development…"). Cross-message text/tool/thinking detectors need a peer and
+	// stayed silent; the degenerate scan only watches a single word. The block
+	// detector must fire on the message itself.
+	const NARRV = [
+		"Let me start by checking the environment and the current state of the repository, then set up a plan for the S0 slice and begin building.",
+		"I'll run several independent checks in parallel.",
+		"Let me begin the S0 development. First, reconnaissance of the environment and current repo state.",
+		"Let me check what's available in the environment (node, package managers, network, postgres) and the current repo state, then set up the S0 plan and start building the monorepo scaffold.",
+		"I'll run a batch of independent environment checks first.",
+	];
+	const cycles = (k: number): string => {
+		let s = "";
+		for (let i = 0; i < k; i++) for (const v of NARRV) s += v + "\n\n";
+		return s;
+	};
+	const s0Det = detectLoops(asState([mk(cycles(5))]), tcfg);
+	const s0Hit = s0Det.find((d) => d.type === "block");
+	out.push(`block S0 narration loop  → ${s0Hit ? `block (${s0Hit.description})` : "no"} (exp block — was the miss) ${s0Hit ? "✅" : "❌"}`);
+	out.push(`block turn weight        → ${detectionTurnWeight(s0Det, tcfg)} (exp 2 — warn on first sight) ${detectionTurnWeight(s0Det, tcfg) === 2 ? "✅" : "❌"}`);
+	out.push(`block post-steer = ignored→ ${isVerbatimRepeat(s0Det) ? "yes" : "no"} (exp yes — replayed block after the break) ${isVerbatimRepeat(s0Det) ? "✅" : "❌"}`);
+
+	// 3 replay cycles still flag; a single restatement (2 cycles, top-gram ×2)
+	// does not — one echo is a summary, not stuck generation.
+	const c3 = findRepetitiveBlock(cycles(3), tcfg);
+	const c2 = findRepetitiveBlock(cycles(2), tcfg);
+	out.push(`block 3 cycles / 2 cycles→ ${c3 ? `flag (${Math.round(c3.ratio * 100)}%)` : "no"} / ${c2 ? "flag" : "no"} (exp flag / no — needs ≥3 repeats) ${c3 && !c2 ? "✅" : "❌"}`);
+
+	// Ordinary prose and templated (but evolving) payloads must stay silent:
+	// long docs score ≤ 0.11 coverage; templated logs/code carry varying digits
+	// so their 5-grams differ.
+	const prose =
+		"The extension watches every assistant message and tool call to decide whether the model is making progress. " +
+		"It stores a short window of recent turns, fingerprints tool results and compares them with earlier attempts. " +
+		"When a pattern repeats it escalates from a quiet warning to a forced change of approach and finally aborts. " +
+		"Configuration lives in a small json file next to the agent directory and every threshold can be tuned at runtime. " +
+		"The default values were chosen against real sessions so ordinary work never triggers a false positive. " +
+		"Detectors are independent: disabling one leaves the others active and the footer keeps the user informed. " +
+		"A clean turn cools the counter down so a recovered model is given room to finish the task. " +
+		"Everything is written in plain typescript with no runtime dependencies beyond the host package. " +
+		"New strategies should be measured against the recorded payloads before they are enabled by default. " +
+		"The goal is simple: catch a stuck model early and keep the context useful for the real work.";
+	const logLines = [...Array(30)].map((_, i) => `2026-09-24T10:${String(i).padStart(2, "0")}:00Z INFO worker ${i} processed job ${1000 + i} in ${i * 3}ms status ok`).join("\n");
+	const proseHit = findRepetitiveBlock(prose, tcfg);
+	const logHit = findRepetitiveBlock(logLines, tcfg);
+	out.push(`block legit prose/logs   → ${proseHit || logHit ? "flag" : "ok"} (exp ok) ${!proseHit && !logHit ? "✅" : "❌"}`);
+
 	// --- v1.6.1: no-progress outcome runs (mutated re-runs, same outcome) ---
 	// Regression: the NFS session — ~90 mutated re-runs of the SAME experiment
 	// (ssh exportfs/mount, labels test A…test QQQ, targets alternating Javi /
@@ -872,5 +1081,32 @@ export function runSelfTest(): string[] {
 	out.push(`outcome identical OKs     → ${okDet.some((d) => d.type === "outcome") ? "outcome" : "silent"} (exp silent — success repeats ≠ loop) ${!okDet.some((d) => d.type === "outcome") ? "✅" : "❌"}`);
 	out.push(`isFailResult gate         → err| → ${isFailResult("err|boom") ? "fail" : "ok"}, rc32 → ${isFailResult("ok|rc32 denied") ? "fail" : "ok"}, rc0/ok → ${isFailResult("ok|rc 0 12 passed") ? "fail" : "ok"} (exp fail, fail, ok) ${isFailResult("err|boom") && isFailResult("ok|rc32 denied") && !isFailResult("ok|rc 0 12 passed") ? "✅" : "❌"}`);
 
+	// --- v1.8: snapshot/read-only tools are idempotent reads, not loops ---
+	// Regression (real session /home/j 2026-09-23T21:35): a coordinator closed
+	// N agents that had ALREADY settled by calling trimegisto_harvest five times
+	// with `{}`; every call returned the SAME 2.3 KB cumulative snapshot (all
+	// agents done). Same args + same result ×5 → the tool detector force-broke
+	// the run. Re-reading a settled state board is the serial close of finished
+	// agents, not a stuck generation: with the snapshot exemption it is silent.
+	const harvestSnap = resultFingerprint(
+		[{
+			type: "text",
+			text:
+				"## Trimegisto harvest (instant snapshot)\n\n### ✅ t0a [Active] — done (101s)\nTask: Explora el sistema en busca de LM Studio y sus runtimes.\n\n```\n# Informe: LM Studio en el sistema\n...\n```\n*10 turns, ↑32825 ↓2429*\n\n_All agents settled._",
+		}],
+		false,
+	)!;
+	const harvestMsgs = [0, 1, 2, 3, 4].map(() =>
+		mk("", [{ name: "trimegisto_harvest", args: "{}", result: harvestSnap }]),
+	);
+	const snapDet = detectLoops(asState(harvestMsgs), tcfg);
+	out.push(`snapshot harvest ×5       → ${snapDet.length ? snapDet.map((d) => d.type).join(",") : "silent"} (exp silent — serial close of settled agents) ${snapDet.length === 0 ? "✅" : "❌"}`);
+
+	// Guard: the exemption is what silences it — the SAME payload with
+	// snapshotTools off is a genuine verbatim tool loop.
+	const noSnapCfg: AntiloopConfig = { ...tcfg, snapshotTools: [] };
+	const snapLoud = detectLoops(asState(harvestMsgs), noSnapCfg);
+	out.push(`snapshot off = loop       → ${snapLoud.some((d) => d.type === "tool") ? "tool" : "no"} (exp tool — normal tools still loop) ${snapLoud.some((d) => d.type === "tool") ? "✅" : "❌"}`);
+
 	return out;
 }

package/src/index.ts

@@ -24,6 +24,13 @@
  * hook (blockDegenerateBash). One degenerate turn counts degenerateTurnWeight
  * (2) consecutive points: warning on first sight, force-break steer on the
  * second consecutive meltdown, hard stop shortly after if it keeps repeating.
+ *
+ * v1.7 adds the intra-message BLOCK detector for the narration-loop class:
+ * ONE message that replays whole sentences/phrases ("Let me start by checking
+ * the environment…" ×5), which every cross-message detector misses because
+ * there is no peer message and the degenerate scan only watches single words.
+ * Same message_end timing and strong turn weight; the bash gate refuses a
+ * command that is itself a replayed block.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -285,29 +292,55 @@ export default function antiloopExtension(pi: ExtensionAPI) {
 			state.recentMessages = state.recentMessages.slice(-(config.detectionWindow + 5));
 		}
 
-		// v1.6 — degenerate meltdowns are handled HERE, at message_end, because
-		// turn_end only fires after tool execution (too late to stop the 46 KB
-		// "noguerol ×5000" bash from running) and an aborted generation may never
-		// reach turn_end at all. The signal is self-contained (one pathological
-		// payload, no peer message) so the full escalation ladder runs right now;
-		// the turn-guard makes the later turn_end pass skip this message and no
-		// detection is double-counted.
-		if (!config.detectDegenerate) return;
-		const { scanMessageDegenerate, degenerateDescription, nextLevel, isVerbatimRepeat } = await import("./detect.ts");
-		const hit = scanMessageDegenerate(content, toolCalls, config);
-		if (!hit) return;
+		// v1.6/v1.7 — intra-message repetition is handled HERE, at message_end,
+		// because turn_end only fires after tool execution (too late to stop the
+		// 46 KB "noguerol ×5000" bash from running) and an aborted generation may
+		// never reach turn_end at all. The signal is self-contained (one
+		// pathological payload, no peer message) so the full escalation ladder runs
+		// right now; the turn-guard makes the later turn_end pass skip this message
+		// and no detection is double-counted. Two flavors: degenerate (one word
+		// ×hundreds) and block (whole sentences/phrases replayed — the narration
+		// loop class where every cross-message detector is blind).
+		if (!config.detectDegenerate && !config.detectBlockRepeats) return;
+		const {
+			scanMessageDegenerate,
+			degenerateDescription,
+			scanMessageBlock,
+			blockRepeatDescription,
+			nextLevel,
+			isVerbatimRepeat,
+		} = await import("./detect.ts");
+		let det: LoopDetection | undefined;
+		if (config.detectDegenerate) {
+			const degHit = scanMessageDegenerate(content, toolCalls, config);
+			if (degHit) {
+				det = {
+					type: "degenerate",
+					similarity: 1,
+					messageIndices: [state.recentMessages.length - 1],
+					description: degenerateDescription(degHit),
+					timestamp: Date.now(),
+				};
+			}
+		}
+		if (!det && config.detectBlockRepeats) {
+			const blkHit = scanMessageBlock(content, toolCalls, config);
+			if (blkHit) {
+				det = {
+					type: "block",
+					similarity: 0.99,
+					messageIndices: [state.recentMessages.length - 1],
+					description: blockRepeatDescription(blkHit),
+					timestamp: Date.now(),
+				};
+			}
+		}
+		if (!det) return;
 		const tracked = state.recentMessages[state.recentMessages.length - 1];
 		if (tracked) state.lastDetectedTurnIndex = tracked.turnIndex;
 		const prevLevel = state.currentLevel;
 		state.consecutiveDetections += Math.max(1, config.degenerateTurnWeight);
 		state.totalDetections++;
-		const det: LoopDetection = {
-			type: "degenerate",
-			similarity: 1,
-			messageIndices: [state.recentMessages.length - 1],
-			description: degenerateDescription(hit),
-			timestamp: Date.now(),
-		};
 		state.detections.push(det);
 		if (state.detections.length > config.maxHistoryEntries) {
 			state.detections = state.detections.slice(-config.maxHistoryEntries);
@@ -331,13 +364,13 @@ export default function antiloopExtension(pi: ExtensionAPI) {
 					ctx.ui.notify(`antiloop: force break — ${det.description}`, "error");
 				}
 			} else if (isVerbatimRepeat([det])) {
-				// The model produced degenerate output AGAIN after the break message:
-				// count it; once the ignore limit is hit the run is cut for good.
+				// The model produced the same intra-message repetition AGAIN after the
+				// break message: count it; once the ignore limit is hit, cut the run.
 				state.ignoredSteerCount++;
 				if (state.ignoredSteerCount >= config.ignoredSteerLimit) {
 					hardStop(
 						ctx,
-						`antiloop: abort — degenerate output repeated ${state.ignoredSteerCount}× after the force break — run stopped; provide new instructions`,
+						`antiloop: abort — repetitive output repeated ${state.ignoredSteerCount}× after the force break — run stopped; provide new instructions`,
 					);
 				}
 			}
@@ -379,15 +412,28 @@ export default function antiloopExtension(pi: ExtensionAPI) {
 	 * sees why the command was refused and can change approach.
 	 */
 	pi.on("tool_call", async (event, ctx) => {
-		if (!config.enabled || !config.detectDegenerate || !config.blockDegenerateBash) return;
+		if (!config.enabled || !config.blockDegenerateBash) return;
 		if (!isToolCallEventType("bash", event)) return;
-		const { findDegenerateRepetition, degenerateDescription } = await import("./detect.ts");
-		const hit = findDegenerateRepetition(event.input.command ?? "", config);
-		if (!hit) return;
-		return {
-			block: true,
-			reason: `[antiloop] blocked: ${degenerateDescription({ ...hit, where: "bash command" })} — this is stuck generation, not a real command. Do NOT retry it: stop and take one small, concrete step instead.`,
-		};
+		const command = event.input.command ?? "";
+		const { findDegenerateRepetition, findRepetitiveBlock, degenerateDescription, blockRepeatDescription } = await import("./detect.ts");
+		if (config.detectDegenerate) {
+			const hit = findDegenerateRepetition(command, config);
+			if (hit) {
+				return {
+					block: true,
+					reason: `[antiloop] blocked: ${degenerateDescription({ ...hit, where: "bash command" })} — this is stuck generation, not a real command. Do NOT retry it: stop and take one small, concrete step instead.`,
+				};
+			}
+		}
+		if (config.detectBlockRepeats) {
+			const blk = findRepetitiveBlock(command, config);
+			if (blk) {
+				return {
+					block: true,
+					reason: `[antiloop] blocked: ${blockRepeatDescription({ ...blk, where: "bash command" })} — this is stuck generation, not a real command. Do NOT retry it: stop and take one small, concrete step instead.`,
+				};
+			}
+		}
 	});
 
 	pi.on("turn_end", async (event, ctx) => {

package/src/types.ts

@@ -34,8 +34,30 @@ export interface AntiloopConfig {
 	degenerateMaxShare: number;
 	/** How many consecutive-detection points ONE degenerate turn adds (2 = warn on first sight). */
 	degenerateTurnWeight: number;
-	/** Block a bash tool call whose command shows degenerate repetition BEFORE it executes. */
+	/** Block a bash tool call whose command shows degenerate OR block repetition BEFORE it executes. */
 	blockDegenerateBash: boolean;
+	/**
+	 * Intra-message BLOCK repetition (v1.7): the "narration loop" class where ONE
+	 * assistant message keeps replaying the same sentences/phrases (the real S0
+	 * coding session: ~5 near-verbatim cycles of "Let me start by checking the
+	 * environment…" inside a SINGLE generation, which every cross-message detector
+	 * misses because it produced only one message and the degenerate detector only
+	 * watches for ONE word repeated hundreds of times). A sliding window of
+	 * blockNgram-word n-grams over the normalized payload is built; when at least
+	 * blockRepeatShare of those positions recur, one n-gram appears at least
+	 * blockMinRepeats times and the payload has at least blockMinTokens words, the
+	 * message is a replay. Fires at message_end (before the message's tools run)
+	 * with the same strong turn weight as the degenerate detector.
+	 */
+	detectBlockRepeats: boolean;
+	/** Minimum normalized words in a payload before it is scanned for block repetition. */
+	blockMinTokens: number;
+	/** Word window of the n-grams whose recurrence is measured (default 5). */
+	blockNgram: number;
+	/** The MOST repeated n-gram must occur at least this many times to flag. */
+	blockMinRepeats: number;
+	/** Share of n-gram positions that must recur for the payload to count as a replay. */
+	blockRepeatShare: number;
 	/**
 	 * No-progress outcome runs (v1.6.1): a model that keeps re-running the SAME
 	 * experiment with cosmetic mutations (labels/permutations) while the outcome
@@ -87,6 +109,18 @@ export interface AntiloopConfig {
 	detectTaskStreams: boolean;
 	taskStreamMinCalls: number;
 	taskStreamTwinThreshold: number;
+	/**
+	 * Read-only snapshot/status tools (default: ["trimegisto_harvest"]). These
+	 * return a view of changing state (a list of agents, a queue, a dashboard).
+	 * Calling one again with the SAME arguments is an idempotent read — most
+	 * strikingly when a coordinator closes N agents that already settled and the
+	 * serialized snapshot is byte-identical every time. That is the serial close
+	 * of finished agents, not a reasoning loop, so repeated calls to a snapshot
+	 * tool never count as a tool loop (nor as a no-progress outcome run). Names
+	 * are matched exactly against the tool name; add any other status/poll tool
+	 * here to keep antiloop quiet while it is read repeatedly.
+	 */
+	snapshotTools: string[];
 	detectToolLoops: boolean;
 	detectThinkingLoops: boolean;
 	detectTextLoops: boolean;
@@ -106,7 +140,7 @@ export interface AntiloopConfig {
 	toggleShortcut: string;
 }
 
-export type LoopKind = "text" | "tool" | "thinking" | "structural" | "degenerate" | "outcome";
+export type LoopKind = "text" | "tool" | "thinking" | "structural" | "degenerate" | "block" | "outcome";
 
 export interface LoopDetection {
 	type: LoopKind;