pi-antiloop 1.7.0 → 1.8.0

package/README.md

@@ -15,6 +15,7 @@
 - **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
@@ -141,6 +142,9 @@ 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
@@ -297,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
@@ -503,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 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-antiloop",
-  "version": "1.7.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. 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

@@ -62,6 +62,7 @@ async function showStatus(ctx: ExtensionCommandContext, rt: Runtime): Promise<vo
 		`  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)} · block ${yn(rt.config.detectBlockRepeats)} · outcome ${yn(rt.config.detectOutcomeLoops)}`,
 		`footer: interactive ${yn(rt.config.interactiveFooter)} · toggle: ${rt.config.toggleShortcut}`,
@@ -105,6 +106,7 @@ async function showConfigMenu(ctx: ExtensionCommandContext, rt: Runtime): Promis
 		{ 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" },
@@ -277,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

@@ -36,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

@@ -495,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;
@@ -543,6 +565,7 @@ export function detectLoops(state: AntiloopState, config: AntiloopConfig): LoopD
 	// 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;
@@ -596,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;
@@ -654,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];
@@ -802,6 +830,7 @@ 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,
@@ -1052,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/types.ts

@@ -109,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;