pi-anti-doom-loop 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to **pi-anti-doom-loop**.
+
+## [Unreleased]
+
+### Added
+
+- **Near-identical text cycle detection** — `checkText` now fires when near-identical assistant texts (token similarity ≥ 55%) accumulate to the text-repeat threshold within the sliding window, even when they are not identical and not consecutive. Catches a rotating set of rephrased commands ("Run the test." / "Run tests now." / "Let me run the test.") that never repeat verbatim. New block reason prefix: _"Assistant sent near-identical text N times within the last M messages"_.
+- **Token-cost awareness** — the detector estimates tokens burned on redundant repeats (~4 chars/token) and reports `~N tokens burned on repeats.` in tool-call block reasons; the cumulative wasted-token count appears in `/loopcheck` status.
+- **Time-windowed eviction** — optional `PI_ANTI_LOOP_TIME_WINDOW` (elapsed-time window in ms; default `0` = disabled, count-only) so slow chronic loops spread over a long session are caught.
+- **Failure-rate window** — optional `PI_ANTI_LOOP_FAIL_RATE` (0..1, default `0` = disabled) blocks a tool when its error share of in-window calls reaches the threshold, with `PI_ANTI_LOOP_FAIL_RATE_MIN` (default `3`) as the minimum-calls gate. Catches flaky retries interleaved with successes that never form a consecutive streak.
+- **Per-tool allowlist** — `PI_ANTI_LOOP_TOOLS_EXCLUDE` (comma-separated tool names) disables detection for those tools entirely: they never block and never enter the window.
+- **Richer `/loopcheck` diagnostics** — status now shows the current window contents (most-repeated recent calls and texts) and the wasted-token count, plus the fail-rate/time-window/exclude config when enabled.
+
+### Changed
+
+- **Same assistant text verbatim** now uses window semantics: it blocks on `3× within the last N messages` rather than strictly "in a row", consistent with the sliding-window repeat threshold.
+
+### Tests
+
+- Detection and regression coverage for the near-identical text cycle, token-cost reporting, time-windowed eviction, failure-rate window, per-tool exclusion, and the richer `/loopcheck` status.
+
+## [0.0.5] — 2026-08-05
+
+### Added
+
+- **`/loopcheck suspend` / `resume`** — escape hatch: pause detection until the next prompt when repetition is intentional (polling, retrying a deploy). No env restart needed.
+- **Session counters** — `steers`/`aborts` appear in `/loopcheck` status; session-scoped (survive per-prompt resets, reset on `/loopcheck reset` or new session).
+- Fixture for the live regex-repeat capture (`parameter\s+(\S+)\s+("` 3× in one message) — regression-covered via the within-message signal.
+- `CHANGELOG.md` ships in the tarball.
+
+### Tests
+
+- 72 → 75: suspend/resume lifecycle, session counters, regex-repeat fixture, `/loopcheck` subcommands.
+
+## [0.0.4] — 2026-08-05
+
+### Added
+
+- **Near-identical text detection** — token-set Jaccard similarity ≥ 0.55 on consecutive assistant messages counts as a loop streak. Catches rephrasing loops where the model changes one or two words per turn ("inspect the failing test" → "examine the failing assertion") that exact matching missed.
+- **Escalation ladder for text loops: steer → abort → bounded resume** — the first detection steers the agent mid-run (injects guidance, work continues); a persistent loop aborts the run and queues **one** fresh-resume directive (`followUp`) so work continues with a new approach; further looping aborts for real and hands control back. The auto-resume budget is session-scoped so a stuck model cannot cycle forever.
+- Detector now fires on every message while a loop condition holds; the controller turns the 1st into a steer, later ones into aborts.
+- Tests: 65 → 72 (token-similarity unit cases, near-identical streak + reset, steer→abort→resume ladder, budget persistence, adapter wiring, fuzz no-FP + injected-3× properties).
+
+## [0.0.3] — 2026-08-05
+
+### Added
+
+- **Within-message self-repetition detection** — a sentence repeating 3+ times inside ONE message (growing self-concatenation loops like "…X:…X:…X") now aborts/steers immediately. Liquid Antidoom's loop definition ("a section repeats at least N times").
+- Segmenter ignores chunks < 16 chars so pasted logs with repeated one-word lines never false-positive.
+- Fixtures for the production growing-loop capture (exact + spaced variants).
+
+### Fixed
+
+- Production gap: loops that grow by self-concatenation evaded both verbatim-streak (messages differ) and identical-call (args vary) detection. Now caught at the message itself.
+
+### Tests
+
+- 51 → 65: `repeatedSegment` unit cases, growing-pattern `checkText` cases, fixture controller paths, fuzz no-FP + injected-3× properties.
+
+## [0.0.2] — 2026-08-05
+
+### Added
+
+- **Full test suite** — Node's built-in `node:test`, no framework:
+  - unit (detector semantics, options clamping, helpers)
+  - fixtures (real doom-loop transcripts: CI-log loops, verbatim repeats; healthy sessions not flagged)
+  - fuzz (seeded: never throws, no false positives, injected loops always block)
+  - integration (controller + adapter driven through a fake `PiLike`)
+  - e2e (real subprocesses: detector self-check, version guard, tarball contents)
+- **`controller.ts`** — extracted all event logic into a pure, pi-free, testable module; `index.ts` became a thin structural adapter.
+- `npm test`, `engines >= 22.18`, `files` includes `scripts/`.
+
+### Fixed
+
+- Thresholds clamped to a minimum of 2 (a config of 1 would brick the agent — deepsec finding).
+- GitHub Actions pinned to commit SHAs (NPM_TOKEN in scope — deepsec finding).
+- Release job `concurrency` group (publish race / TOCTOU).
+- `npm publish --dry-run` preflight before the real publish.
+- Version guard requires the git tag `v$version` on the manual-dispatch path.
+
+### Changed
+
+- Leveraged `better-result` (detector decisions) and `effect` v4 (release guard).
+
+## [0.0.1] — 2026-08-05
+
+### Added
+
+- Initial release. Detects and breaks agent doom loops in pi:
+  - **identical (tool, args) repeated** 3× in the last 10 calls → block with an instructive reason
+  - **same tool failing** 3× consecutively → block with "stop retrying, fix the root cause"
+  - escalation: re-issuing a blocked call aborts the turn
+- `/loopcheck` command (status + reset).
+- Counters reset per user prompt (legit repeated tasks are never false positives).
+- GitHub Actions release workflow: quality gate → version bump guard → dry-run → publish, triggered by `v*` tags.
+- `pi-package` keyword + `pi` manifest for the pi.dev gallery.
+
+[0.0.5]: https://github.com/irfndi/pi-anti-doom-loop/compare/v0.0.4...v0.0.5
+[0.0.4]: https://github.com/irfndi/pi-anti-doom-loop/compare/v0.0.3...v0.0.4
+[0.0.2]: https://github.com/irfndi/pi-anti-doom-loop/compare/v0.0.1...v0.0.2
+[0.0.1]: https://github.com/irfndi/pi-anti-doom-loop/releases/tag/v0.0.1

package/README.md

@@ -15,13 +15,14 @@ pi install npm:pi-anti-doom-loop
 
 ## What it detects
 
-| Signal                           | Default                 | Blocked when                                                                             |
-| -------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------- |
-| Same `(tool, args)` repeated     | 3× in the last 10 calls | The pattern has repeated `3` times with no change                                        |
-| Same tool failing consecutively  | 3×                      | A tool errored `3` times in a row — stop retrying it blindly                             |
-| Same assistant text verbatim     | 3× in a row             | The model re-emitted identical text `3` times (text-only loops)                          |
-| Same sentence inside ONE message | 3×                      | A sentence repeats `3`+ times within a single message (growing self-concatenation loops) |
-| Near-identical text (rephrasing) | 3× in a row             | Consecutive messages share ≥55% tokens — the model is rephrasing the same step           |
+| Signal                                                  | Default                       | Blocked when                                                                                                                                         |
+| ------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Same `(tool, args)` repeated                            | 3× in the last 10 calls       | The pattern has repeated `3` times with no change                                                                                                    |
+| Same tool failing consecutively                         | 3×                            | A tool errored `3` times in a row — stop retrying it blindly                                                                                         |
+| Same assistant text verbatim                            | 3× within the last N messages | The model re-emitted identical text `3` times inside the sliding window                                                                              |
+| Same sentence inside ONE message                        | 3×                            | A sentence repeats `3`+ times within a single message (growing self-concatenation loops)                                                             |
+| Near-identical text (rephrasing)                        | 3× in a row                   | Consecutive messages share ≥55% tokens — the model is rephrasing the same step                                                                       |
+| Near-identical text cycle (rotating rephrased commands) | 3× within the last N messages | Near-identical assistant texts (≥55% token similarity) accumulate to the repeat threshold in the window, even when not identical and not consecutive |
 
 Blocks hand the model an instructive reason ("change your approach, use a
 different tool, or ask the user"). If the model ignores the block and re-issues
@@ -41,29 +42,42 @@ the same session is never a false positive.
 
 Environment variables, read at session/prompt start:
 
-| Variable                    | Default | Meaning                                            |
-| --------------------------- | ------- | -------------------------------------------------- |
-| `PI_ANTI_LOOP_REPEATS`      | `3`     | Identical-call block threshold                     |
-| `PI_ANTI_LOOP_FAILS`        | `3`     | Consecutive-failure block threshold                |
-| `PI_ANTI_LOOP_TEXT_REPEATS` | `3`     | Consecutive identical assistant texts before abort |
-| `PI_ANTI_LOOP_WINDOW`       | `10`    | How many recent calls/results are inspected        |
-| `PI_ANTI_LOOP_DISABLE`      | —       | Set to `1` to disable the extension entirely       |
+| Variable                     | Default | Meaning                                                                                                                                            |
+| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PI_ANTI_LOOP_REPEATS`       | `3`     | Identical-call block threshold                                                                                                                     |
+| `PI_ANTI_LOOP_FAILS`         | `3`     | Consecutive-failure block threshold                                                                                                                |
+| `PI_ANTI_LOOP_TEXT_REPEATS`  | `3`     | Window/cycle repeat threshold for identical and near-identical assistant texts                                                                     |
+| `PI_ANTI_LOOP_WINDOW`        | `10`    | How many recent calls/results are inspected                                                                                                        |
+| `PI_ANTI_LOOP_TIME_WINDOW`   | `0`     | Elapsed-time window in ms (`0` = disabled, count-only): evicts window entries older than this so slow chronic loops over a long session are caught |
+| `PI_ANTI_LOOP_FAIL_RATE`     | `0`     | Fail-rate block threshold `0..1` (`0` = disabled): block when a tool's error share of its in-window calls reaches this                             |
+| `PI_ANTI_LOOP_FAIL_RATE_MIN` | `3`     | Minimum calls before the fail-rate window can block                                                                                                |
+| `PI_ANTI_LOOP_TOOLS_EXCLUDE` | —       | Comma-separated tool names to disable detection for entirely (never block, never enter the window)                                                 |
+| `PI_ANTI_LOOP_DISABLE`       | —       | Set to `1` to disable the extension entirely                                                                                                       |
 
 ## Command
 
-- `/loopcheck` — show current thresholds and counters
+- `/loopcheck` — show thresholds, counters (steers/aborts this session), suspend state, the current window contents (most-repeated recent calls and texts), wasted-token count, and the fail-rate/time-window/exclude config when enabled
 - `/loopcheck reset` — clear counters
+- `/loopcheck suspend` — pause detection until the next prompt (escape hatch for intentional repetition)
+- `/loopcheck resume` — re-enable detection early
+
+## Token-cost awareness
+
+The detector estimates tokens burned on redundant repeats (~4 chars/token) and
+reports `"~N tokens burned on repeats."` in tool-call block reasons. The
+cumulative wasted-token count also appears in `/loopcheck` status, so you can
+see how much a loop actually cost before it was stopped.
 
 ## How it works
 
-Everything hooks into the `tool_call` / `tool_result` events; detection is a
-small sliding-window counter (see `extensions/detector.ts`) with no state kept
-between user prompts. Works with any model — cheap models just trigger it more
-often.
+Everything hooks into the `tool_call` / `tool_result` / `message_end` events;
+detection is a small sliding-window counter (see `extensions/detector.ts`) with
+per-session counters (steers/aborts) tracked in `extensions/controller.ts`.
+Works with any model — cheap models just trigger it more often.
 
 ## Development
 
-Requires Node 22.6+ (plain `node` runs the TS self-check).
+Requires Node 22.18+ (plain `node` runs the TS self-check).
 
 ```bash
 npm install

package/extensions/controller.ts

@@ -63,6 +63,10 @@ export interface AntiLoopController {
   onMessageEnd(role: string, content: unknown): TextLoopOutcome | null;
   /** Full reset (session start, user prompt, /loopcheck reset). */
   reset(): void;
+  /** Suspend detection until the next reset (escape hatch for intentional repetition). */
+  suspend(): void;
+  resume(): void;
+  isSuspended(): boolean;
   /** Human-readable status with thresholds + counters for /loopcheck. */
   status(): string;
 }
@@ -72,9 +76,13 @@ export function createController(opts: LoopOptions = readOptions()): AntiLoopCon
   const blockedIds = new Set<string>();
   let steered = false;
   let resumes = 0;
+  let steers = 0;
+  let aborts = 0;
+  let suspended = false;
 
   return {
     onToolCall(toolName, input, toolCallId) {
+      if (suspended) return null;
       const decision = detector.check(toolName, input);
       if (decision.isErr()) {
         detector.record(toolName, input);
@@ -96,6 +104,7 @@ export function createController(opts: LoopOptions = readOptions()): AntiLoopCon
     },
 
     onMessageEnd(role, content) {
+      if (suspended) return null;
       if (role !== "assistant") return null;
       const text = extractText(content);
       if (!text) return null;
@@ -105,12 +114,15 @@ export function createController(opts: LoopOptions = readOptions()): AntiLoopCon
       const reason = hit.value.reason;
       if (!steered) {
         steered = true;
+        steers++;
         return { reason, action: "steer", resume: false };
       }
       if (resumes < RESUME_BUDGET) {
         resumes++;
+        aborts++;
         return { reason, action: "abort", resume: true };
       }
+      aborts++;
       return { reason, action: "abort", resume: false };
     },
 
@@ -118,15 +130,34 @@ export function createController(opts: LoopOptions = readOptions()): AntiLoopCon
       detector = new LoopDetector(opts);
       blockedIds.clear();
       steered = false;
-      // resumes is intentionally NOT reset here: the auto-resume budget is
-      // session-scoped so a stuck model cannot cycle steer→abort forever.
+      suspended = false;
+      // resumes/steers/aborts are intentionally NOT reset here: they are
+      // session-scoped so a stuck model cannot cycle steer→abort forever and
+      // /loopcheck can report lifetime counters.
+    },
+
+    suspend() {
+      suspended = true;
+    },
+
+    resume() {
+      suspended = false;
+    },
+
+    isSuspended() {
+      return suspended;
     },
 
     status() {
       const o = detector.opts;
+      const s = suspended ? ", suspended" : "";
+      const rate = o.failRateThreshold > 0 ? `, failRate>=${o.failRateThreshold}` : "";
+      const time = o.timeWindowMs > 0 ? `, window ${o.timeWindowMs}ms` : "";
+      const excl = o.toolExclude.size ? `, exclude[${[...o.toolExclude].join(",")}]` : "";
       return (
         `anti-doom-loop: repeats>=${o.repeatThreshold}/window ${o.windowSize}, ` +
-        `fails>=${o.failThreshold}, text>=${o.textRepeatThreshold}. ${detector.summary()}`
+        `fails>=${o.failThreshold}, text>=${o.textRepeatThreshold}${rate}${time}${excl}. ` +
+        `${detector.diagnostics()} steers=${steers} aborts=${aborts}${s}`
       );
     },
   };

package/extensions/detector.ts

@@ -20,8 +20,21 @@ export interface LoopOptions {
   failThreshold: number;
   /** How many recent calls/results are inspected for repetition. */
   windowSize: number;
-  /** Consecutive verbatim assistant messages that trigger an abort. */
+  /** Verbatim/near-identical assistant-message repeats that trigger a block. */
   textRepeatThreshold: number;
+  /** Evict window entries older than this many ms (0 = count-only window). */
+  timeWindowMs: number;
+  /**
+   * Failure-rate threshold (0..1). When a tool's error share of its calls in
+   * the window is >= this (and it has >= failRateMinCalls calls), block. This
+   * catches flaky/ungrounded retries that are interleaved with successes and
+   * never form a consecutive streak. 0 = disabled.
+   */
+  failRateThreshold: number;
+  /** Minimum calls before the failure-rate signal applies. */
+  failRateMinCalls: number;
+  /** Tool names to skip detection for entirely (intentional repetition). */
+  toolExclude: Set<string>;
 }
 
 export const DEFAULT_OPTIONS: LoopOptions = {
@@ -29,6 +42,10 @@ export const DEFAULT_OPTIONS: LoopOptions = {
   failThreshold: 3,
   windowSize: 10,
   textRepeatThreshold: 3,
+  timeWindowMs: 0,
+  failRateThreshold: 0,
+  failRateMinCalls: 3,
+  toolExclude: new Set(),
 };
 
 export function readOptions(env: Record<string, string | undefined> = process.env): LoopOptions {
@@ -40,11 +57,23 @@ export function readOptions(env: Record<string, string | undefined> = process.en
     const n = Number(raw);
     return Number.isFinite(n) && n >= 2 ? n : fallback;
   };
+  const timeWindow = Number(env["PI_ANTI_LOOP_TIME_WINDOW"] ?? "0");
+  const failRate = Number(env["PI_ANTI_LOOP_FAIL_RATE"] ?? "0");
+  const toolExclude = new Set(
+    (env["PI_ANTI_LOOP_TOOLS_EXCLUDE"] ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
   return {
     repeatThreshold: num("PI_ANTI_LOOP_REPEATS", DEFAULT_OPTIONS.repeatThreshold),
     failThreshold: num("PI_ANTI_LOOP_FAILS", DEFAULT_OPTIONS.failThreshold),
     windowSize: num("PI_ANTI_LOOP_WINDOW", DEFAULT_OPTIONS.windowSize),
     textRepeatThreshold: num("PI_ANTI_LOOP_TEXT_REPEATS", DEFAULT_OPTIONS.textRepeatThreshold),
+    timeWindowMs: Number.isFinite(timeWindow) && timeWindow >= 0 ? timeWindow : 0,
+    failRateThreshold: Number.isFinite(failRate) ? Math.min(1, Math.max(0, failRate)) : 0,
+    failRateMinCalls: num("PI_ANTI_LOOP_FAIL_RATE_MIN", DEFAULT_OPTIONS.failRateMinCalls),
+    toolExclude,
   };
 }
 
@@ -77,25 +106,33 @@ export interface BlockDecision {
  */
 export class LoopDetector {
   readonly opts: LoopOptions;
-  private recentSigs: string[] = [];
-  private recentResults: { tool: string; error: boolean }[] = [];
+  private recentSigs: { sig: string; ts: number }[] = [];
+  private recentResults: { tool: string; error: boolean; ts: number }[] = [];
   private blockedBySig = new Map<string, number>();
+  private recentTexts: { text: string; ts: number }[] = [];
   private lastText: string | null = null;
   private textStreak = 0;
-  private textFired = false;
+  private wastedTokens = 0;
 
   constructor(opts: LoopOptions = DEFAULT_OPTIONS) {
     this.opts = opts;
   }
 
   check(toolName: string, input: unknown): Result<BlockDecision, undefined> {
+    if (this.opts.toolExclude.has(toolName)) {
+      // record() is a no-op for excluded tools, so nothing enters the window.
+      return Result.err(undefined);
+    }
+    this.evictSigs();
     const sig = signature(toolName, input);
-    const repeats = this.recentSigs.filter((s) => s === sig).length;
+    const repeats = this.recentSigs.filter((s) => s.sig === sig).length;
     const total = repeats + 1; // including this call
-    const fails = this.consecutiveFails(toolName);
+    const consecutiveFails = this.consecutiveFails(toolName);
+    const rate = this.failRate(toolName);
 
-    if (total < this.opts.repeatThreshold && fails < this.opts.failThreshold)
-      return Result.err(undefined);
+    // Rough cost accounting (feature B): every redundant repeat of an already
+    // present signature burns tokens with no new information.
+    if (repeats >= 1) this.wastedTokens += estimateTokens(stringify(input));
 
     const reasons: string[] = [];
     if (total >= this.opts.repeatThreshold) {
@@ -103,36 +140,49 @@ export class LoopDetector {
         `"${toolName}" was called with identical arguments ${total} times in the last ${this.opts.windowSize} tool calls with no change`,
       );
     }
-    if (fails >= this.opts.failThreshold) {
-      reasons.push(`"${toolName}" failed ${fails} consecutive times`);
+    if (consecutiveFails >= this.opts.failThreshold) {
+      reasons.push(`"${toolName}" failed ${consecutiveFails} consecutive times`);
     }
+    if (
+      this.opts.failRateThreshold > 0 &&
+      rate.calls >= this.opts.failRateMinCalls &&
+      rate.rate >= this.opts.failRateThreshold
+    ) {
+      reasons.push(
+        `"${toolName}" failed ${rate.errors} of ${rate.calls} calls in the window (${Math.round(rate.rate * 100)}%)`,
+      );
+    }
+
+    if (reasons.length === 0) return Result.err(undefined);
 
     const blockedCount = (this.blockedBySig.get(sig) ?? 0) + 1;
     this.blockedBySig.set(sig, blockedCount);
+    const cost = this.wastedTokens > 0 ? ` ~${this.wastedTokens} tokens burned on repeats.` : "";
 
     return Result.ok({
       reason:
         reasons.join("; ") +
+        cost +
         `. BLOCKED by anti-doom-loop — you appear to be looping. Change your approach, use a different tool, or ask the user.`,
       escalate: blockedCount > 1,
     });
   }
 
   record(toolName: string, input: unknown): void {
-    this.recentSigs.push(signature(toolName, input));
-    if (this.recentSigs.length > this.opts.windowSize) this.recentSigs.shift();
+    if (this.opts.toolExclude.has(toolName)) return;
+    this.recentSigs.push({ sig: signature(toolName, input), ts: Date.now() });
+    this.evictSigs();
   }
 
   recordResult(toolName: string, error: boolean): void {
-    this.recentResults.push({ tool: toolName, error });
-    if (this.recentResults.length > this.opts.windowSize) this.recentResults.shift();
+    this.recentResults.push({ tool: toolName, error, ts: Date.now() });
+    this.evictResults();
   }
 
   /**
-   * Consecutive verbatim assistant text (whitespace-normalized). Fires once
-   * per run when the streak reaches textRepeatThreshold, then stays silent
-   * until reset — message_end cannot return a block, so the caller aborts.
-   * $
+   * Consecutive verbatim/near-identical assistant text (whitespace-normalized).
+   * The controller turns the first detection into a steer, later ones into
+   * aborts. $
    * Detects the text-only loop shape (model re-emits the same sentence
    * forever, e.g. goal-function loops) that identical-tool-call detection
    * never sees. Liquid.ai's Antidoom mines loops as 'a section repeats at
@@ -156,6 +206,24 @@ export class LoopDetector {
       });
     }
 
+    // Cross-message window repeat (exact): the same text reappearing
+    // textRepeatThreshold times within the recent-text window. Catches text
+    // CYCLES that never form a 3-consecutive streak and are too short for
+    // repeatedSegment. Mirrors the tool-signature window in check().
+    const exactCount = this.recentTexts.filter((t) => t.text === norm).length + 1;
+    this.recentTexts.push({ text: norm, ts: Date.now() });
+    this.evictTexts();
+    if (this.recentTexts.filter((t) => t.text === norm).length >= 2) {
+      this.wastedTokens += estimateTokens(norm);
+    }
+    if (exactCount >= this.opts.textRepeatThreshold) {
+      return Result.ok({
+        reason:
+          `Assistant sent identical text ${exactCount} times within the last ${this.opts.windowSize} messages ` +
+          `("${truncate(norm, 80)}"). You appear to be in a loop.`,
+      });
+    }
+
     // Cross-message streak: consecutive assistant texts that are identical
     // OR near-identical (token-overlap similarity). Catches loops where the
     // model slightly rephrases each turn ("inspect the failing test" →
@@ -172,6 +240,23 @@ export class LoopDetector {
           `("${truncate(norm, 80)}"). You appear to be in a loop.`,
       });
     }
+
+    // Cross-message window repeat (near-identical): a rotating set of
+    // rephrased commands ("Run the test." / "Run tests now." / "Let me run
+    // the test.") that is never identical and never consecutive, so both the
+    // exact window check and the streak above miss it. Similar, non-identical
+    // texts accumulating to textRepeatThreshold within the window fire here.
+    const similarCount =
+      this.recentTexts.filter(
+        (t) => t.text !== norm && tokenSimilarity(norm, t.text) >= TEXT_SIMILARITY_THRESHOLD,
+      ).length + 1;
+    if (similarCount >= this.opts.textRepeatThreshold) {
+      return Result.ok({
+        reason:
+          `Assistant sent near-identical text ${similarCount} times within the last ${this.opts.windowSize} messages ` +
+          `("${truncate(norm, 80)}"). You appear to be in a loop.`,
+      });
+    }
     return Result.err(undefined);
   }
 
@@ -186,13 +271,80 @@ export class LoopDetector {
     return n;
   }
 
+  /** Error share of all in-window results for a tool. */
+  private failRate(toolName: string): { calls: number; errors: number; rate: number } {
+    let calls = 0;
+    let errors = 0;
+    for (const r of this.recentResults) {
+      if (r.tool !== toolName) continue;
+      calls++;
+      if (r.error) errors++;
+    }
+    return { calls, errors, rate: calls ? errors / calls : 0 };
+  }
+
+  private evictSigs(): void {
+    if (this.opts.timeWindowMs > 0) {
+      const cutoff = Date.now() - this.opts.timeWindowMs;
+      this.recentSigs = this.recentSigs.filter((s) => s.ts >= cutoff);
+    }
+    while (this.recentSigs.length > this.opts.windowSize) this.recentSigs.shift();
+  }
+
+  private evictResults(): void {
+    if (this.opts.timeWindowMs > 0) {
+      const cutoff = Date.now() - this.opts.timeWindowMs;
+      this.recentResults = this.recentResults.filter((r) => r.ts >= cutoff);
+    }
+    while (this.recentResults.length > this.opts.windowSize) this.recentResults.shift();
+  }
+
+  private evictTexts(): void {
+    if (this.opts.timeWindowMs > 0) {
+      const cutoff = Date.now() - this.opts.timeWindowMs;
+      this.recentTexts = this.recentTexts.filter((t) => t.ts >= cutoff);
+    }
+    while (this.recentTexts.length > this.opts.windowSize) this.recentTexts.shift();
+  }
+
+  /** Estimated tokens burned on redundant repeats (feature B). */
+  wastedTokensCount(): number {
+    return this.wastedTokens;
+  }
+
+  /** Human-readable window introspection for /loopcheck (feature F). */
+  diagnostics(): string {
+    const sigCounts = new Map<string, number>();
+    for (const s of this.recentSigs) sigCounts.set(s.sig, (sigCounts.get(s.sig) ?? 0) + 1);
+    const topSigs = [...sigCounts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 3)
+      .map(([s, n]) => `${truncate(s, 40)} x${n}`)
+      .join(", ");
+
+    const textCounts = new Map<string, number>();
+    for (const t of this.recentTexts) textCounts.set(t.text, (textCounts.get(t.text) ?? 0) + 1);
+    const topTexts = [...textCounts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 3)
+      .map(([s, n]) => `"${truncate(s, 24)}" x${n}`)
+      .join(", ");
+
+    return (
+      `calls[${this.recentSigs.length}] ${topSigs || "none"}; ` +
+      `texts[${this.recentTexts.length}] ${topTexts || "none"}; ` +
+      `wastedTokens=${this.wastedTokens}`
+    );
+  }
+
   reset(): void {
     this.recentSigs = [];
     this.recentResults = [];
     this.blockedBySig.clear();
+    this.recentTexts = [];
     this.lastText = null;
     this.textStreak = 0;
-    this.textFired = false;
+    this.wastedTokens = 0;
   }
 
   summary(): string {
@@ -218,6 +370,26 @@ export const MIN_REPEAT_CHUNK = 16;
 /** Jaccard similarity threshold for "near-identical" consecutive texts. */
 export const TEXT_SIMILARITY_THRESHOLD = 0.55;
 
+/** Stable string form of an arbitrary tool input (used for token estimation). */
+export function stringify(input: unknown): string {
+  if (typeof input === "string") return input;
+  try {
+    return JSON.stringify(input);
+  } catch {
+    return String(input);
+  }
+}
+
+/**
+ * Rough token estimate for cost accounting (feature B): ~4 chars per token,
+ * like the widely-used wc/4 rule. Purposely crude — it only needs to be
+ * monotonic so the same work always reports the same order of magnitude.
+ */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
 /**
  * Token-set Jaccard similarity of two texts (case/whitespace-insensitive).
  * Short tokens (< 3 chars: "a", "me", "to") are ignored to reduce noise.
@@ -271,6 +443,10 @@ if (import.meta.main) {
     failThreshold: 3,
     windowSize: 10,
     textRepeatThreshold: 3,
+    timeWindowMs: 0,
+    failRateThreshold: 0,
+    failRateMinCalls: 3,
+    toolExclude: new Set(),
   };
   const d: LoopDetector = new LoopDetector(opts);
 
@@ -330,7 +506,7 @@ if (import.meta.main) {
   const textHit = d.checkText("Now update buildProgram.");
   assert.ok(textHit.isOk(), "3rd identical text should fire");
   if (textHit.isOk()) {
-    assert.match(textHit.value.reason, /identical or near-identical text 3 times/);
+    assert.match(textHit.value.reason, /identical text 3 times within the last/);
   }
   assert.ok(
     d.checkText("Now update buildProgram.").isOk(),
@@ -345,23 +521,42 @@ if (import.meta.main) {
   const wsHit = d.checkText(" Read the region: ");
   assert.ok(wsHit.isOk(), "whitespace-normalized repeats should fire");
 
-  // 9. a different message breaks the streak (need 3 consecutive AFTER the break to fire)
+  // 9. window semantics: < textRepeatThreshold recurrences in the window do
+  //    NOT fire, even with other messages interleaved; the 3rd recurrence does.
   d.reset();
   d.checkText("A");
-  d.checkText("A");
-  d.checkText("B"); // breaks the streak
-  d.checkText("A");
-  assert.ok(d.checkText("A").isErr(), "only 2 consecutive As after the break must not fire");
-  const again = d.checkText("A");
-  assert.ok(again.isOk(), "3 consecutive As after the break fire");
+  d.checkText("B"); // different message
+  d.checkText("A"); // 2nd A in window
+  assert.ok(d.checkText("C").isErr(), "2 As in the window must not fire");
+  assert.ok(d.checkText("A").isOk(), "3rd A in the window fires");
 
   // 10. empty/blank text is ignored as a loop signal
   d.reset();
   d.checkText("");
   d.checkText("   ");
   assert.ok(d.checkText("").isErr(), "blank text must not fire");
-
-  // 11. threshold 1 is clamped away (would brick the agent)
+  // 11. text CYCLES: a small set of short near-identical commands rotating
+  //     ("Let me run. GO." / "Run. GO." / "GO.") never forms a consecutive
+  //     streak, but the same text reappears >= threshold within the window.
+  d.reset();
+  const cycle = [
+    "Let me run. GO.",
+    "Run. GO.",
+    "GO.",
+    "Run. GO.",
+    "GO.",
+    "Let me run. GO.",
+    "Run. GO.",
+    "GO.",
+    "Run. GO.",
+    "GO.",
+    "Let me run. GO.",
+  ];
+  let fired = false;
+  for (const m of cycle) if (d.checkText(m).isOk()) fired = true;
+  assert.ok(fired, "rotating near-identical cycle must fire");
+
+  // 12. threshold 1 is clamped away (would brick the agent)
   const clamped = readOptions({
     PI_ANTI_LOOP_REPEATS: "1",
     PI_ANTI_LOOP_FAILS: "0",

package/extensions/index.ts

@@ -73,7 +73,8 @@ export default function (pi: PiLike): void {
   pi.on("session_start", () => reset());
 
   // Fresh counters per user prompt: only the loop happening *right now* counts.
-  pi.on("before_agent_start", () => reset());
+  // Internal reset keeps session-scoped steers/aborts/resume budget.
+  pi.on("before_agent_start", () => controller.reset());
 
   pi.on("tool_call", (event: ToolCallEventLite, ctx: CtxLite) => {
     const outcome = controller.onToolCall(event.toolName, event.input, event.toolCallId);
@@ -118,11 +119,22 @@ export default function (pi: PiLike): void {
   pi.registerCommand("loopcheck", {
     description: "Anti-doom-loop status; `/loopcheck reset` clears counters",
     handler: async (args: string, ctx: CommandCtxLite) => {
-      if (args.trim().toLowerCase() === "reset") {
+      const arg = args.trim().toLowerCase();
+      if (arg === "reset") {
         reset();
         ctx.ui.notify("Anti-doom-loop: counters reset", "info");
         return;
       }
+      if (arg === "suspend") {
+        controller.suspend();
+        ctx.ui.notify("Anti-doom-loop: suspended until the next prompt", "info");
+        return;
+      }
+      if (arg === "resume") {
+        controller.resume();
+        ctx.ui.notify("Anti-doom-loop: resumed", "info");
+        return;
+      }
       ctx.ui.notify(controller.status(), "info");
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-anti-doom-loop",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Detect and break agent doom loops in pi: blocks identical repeated tool calls and blind retries before they burn tokens.",
   "keywords": [
     "anti-doom-loop",
@@ -17,7 +17,8 @@
   },
   "files": [
     "extensions",
-    "scripts"
+    "scripts",
+    "CHANGELOG.md"
   ],
   "type": "module",
   "main": "extensions/index.ts",
@@ -35,7 +36,8 @@
     "guard": "node scripts/guard-publish.ts",
     "lint": "oxlint --deny-warnings",
     "format": "oxfmt .",
-    "format:check": "oxfmt --check ."
+    "format:check": "oxfmt --check .",
+    "prepare": "effect-tsgo patch --no-typescript --oxlint"
   },
   "dependencies": {
     "better-result": "^3.0.0",
@@ -43,9 +45,11 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "@effect/tsgo": "^0.36.4",
     "@types/node": "^22.0.0",
     "oxfmt": "^0.62.0",
     "oxlint": "^1.77.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "typescript": "^5.6.0"
   },
   "peerDependencies": {

package/scripts/guard-publish.ts

@@ -63,8 +63,8 @@ const tagExists = (version: string): Effect.Effect<boolean> =>
         return false; // no git repo / git missing → treat as no tag
       }
     },
-    catch: () => new Error("git tag check failed"),
-  }).pipe(Effect.catch(() => Effect.succeed(false)));
+    catch: (): GuardError => ({ message: "git tag check failed" }),
+  }).pipe(Effect.orElseSucceed(() => false));
 /**
  * Latest published version on npm, or null when the package was never
  * published or the registry is unreachable (warn-only on network failure —
@@ -83,9 +83,9 @@ const fetchPublished = (name: string): Effect.Effect<string | null> =>
       console.warn(
         "GUARD WARN: could not reach the npm registry; skipping published-version check.",
       );
-      return new Error("registry unreachable");
+      return { message: "registry unreachable" };
     },
-  }).pipe(Effect.catch(() => Effect.succeed(null)));
+  }).pipe(Effect.orElseSucceed(() => null));
 
 const program: Effect.Effect<string, GuardError> = Effect.gen(function* () {
   const raw = yield* readManifest;
@@ -94,10 +94,10 @@ const program: Effect.Effect<string, GuardError> = Effect.gen(function* () {
   const expected = (process.argv[2] ?? "").replace(/^v/, ""); // tolerate "v0.0.1"
 
   if (!semverLike(local)) {
-    yield* fail(`GUARD FAIL: package.json version "${local}" is not a semver X.Y.Z.`);
+    return yield* fail(`GUARD FAIL: package.json version "${local}" is not a semver X.Y.Z.`);
   }
   if (expected && expected !== local) {
-    yield* fail(
+    return yield* fail(
       `GUARD FAIL: expected "${expected}" (tag/input) does not match package.json version "${local}". ` +
         `Bump package.json to ${expected}, or tag ${local}.`,
     );
@@ -105,7 +105,7 @@ const program: Effect.Effect<string, GuardError> = Effect.gen(function* () {
 
   const published = yield* fetchPublished(pkg.name);
   if (published === local) {
-    yield* fail(
+    return yield* fail(
       `GUARD FAIL: ${pkg.name}@${local} is already published on npm. ` +
         `Bump the version in package.json to cut a new release.`,
     );
@@ -115,7 +115,7 @@ const program: Effect.Effect<string, GuardError> = Effect.gen(function* () {
   // exist as a git tag — keeps the tag/manifest-sync invariant on both entry
   // points (clawpatch finding).
   if (expected && (yield* tagExists(expected)) === false) {
-    yield* fail(
+    return yield* fail(
       `GUARD FAIL: expected version "${expected}" has no matching git tag v${expected}. Tag it first.`,
     );
   }