pi-anti-doom-loop 0.0.5 → 0.0.7

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to **pi-anti-doom-loop**.
 
+## [0.0.7] — 2026-08-13
+
+### Changed
+
+- **Effect 4.0 RC** — upgraded `effect` from `^4.0.0-beta.103` to `^4.0.0-rc.108`.
+- **Anti-slop lint hardening** — vendored an opinionated Oxlint rule set (`tools/oxlint/anti-slop/`) and enabled it in `oxlint.config.ts`; resolved all 23 findings by introducing a JSON-safe `ToolInput` domain type decoded at the pi boundary, replacing `unknown` parameters, `typeof` checks, `Record<string, unknown>`, and value widening.
+
+## [0.0.6] — 2026-08-12
+
+### 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
@@ -78,7 +104,10 @@ All notable changes to **pi-anti-doom-loop**.
 - 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.7]: https://github.com/irfndi/pi-anti-doom-loop/compare/v0.0.6...v0.0.7
+[0.0.6]: https://github.com/irfndi/pi-anti-doom-loop/compare/v0.0.5...v0.0.6
 [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.3]: https://github.com/irfndi/pi-anti-doom-loop/compare/v0.0.2...v0.0.3
 [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,21 +42,32 @@ 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 thresholds, counters (steers/aborts this session), suspend state
+- `/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` / `message_end` events;
@@ -65,7 +77,7 @@ 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

@@ -13,7 +13,7 @@
  * a fresh session (new controller) starts over.
  */
 import { LoopDetector, readOptions } from "./detector.ts";
-import type { LoopOptions } from "./detector.ts";
+import type { LoopOptions, ToolInput } from "./detector.ts";
 
 /** Minimal shapes of the pi events the controller consumes (structural). */
 export interface ToolCallEventLite {
@@ -37,6 +37,15 @@ export interface CommandCtxLite {
   ui: { notify(message: string, level: string): void };
 }
 
+/** One content block of an assistant message; only text blocks carry text. */
+export interface MessageContentBlock {
+  readonly type: string;
+  readonly text?: string;
+}
+
+/** The list of content blocks of an assistant message. */
+export type MessageContent = readonly MessageContentBlock[];
+
 export interface ToolCallOutcome {
   block: true;
   reason: string;
@@ -56,11 +65,11 @@ export const RESUME_BUDGET = 1;
 
 export interface AntiLoopController {
   /** Returns a block decision for a tool call, or null to let it run. */
-  onToolCall(toolName: string, input: unknown, toolCallId: string): ToolCallOutcome | null;
+  onToolCall(toolName: string, input: ToolInput, toolCallId: string): ToolCallOutcome | null;
   /** Record a finished tool result (blocked calls' results are ignored). */
   onToolResult(toolName: string, toolCallId: string, isError: boolean): void;
   /** Detect assistant-text loops; returns a steer/abort decision or null. */
-  onMessageEnd(role: string, content: unknown): TextLoopOutcome | null;
+  onMessageEnd(role: string, content: MessageContent): TextLoopOutcome | null;
   /** Full reset (session start, user prompt, /loopcheck reset). */
   reset(): void;
   /** Suspend detection until the next reset (escape hatch for intentional repetition). */
@@ -151,23 +160,19 @@ export function createController(opts: LoopOptions = readOptions()): AntiLoopCon
     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()} ` +
-        `steers=${steers} aborts=${aborts}${s}`
+        `fails>=${o.failThreshold}, text>=${o.textRepeatThreshold}${rate}${time}${excl}. ` +
+        `${detector.diagnostics()} steers=${steers} aborts=${aborts}${s}`
       );
     },
   };
 }
 
 /** Join the text content blocks of an assistant message. */
-export function extractText(content: unknown): string {
-  if (!Array.isArray(content)) return "";
-  return content
-    .map((c) =>
-      typeof c === "object" && c !== null && c.type === "text" && typeof c.text === "string"
-        ? c.text
-        : "",
-    )
-    .join(" ");
+export function extractText(content: MessageContent): string {
+  return content.map((c) => (c.type === "text" ? (c.text ?? "") : "")).join(" ");
 }

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,26 +57,52 @@ 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,
   };
 }
 
+/**
+ * A JSON-safe tool-call argument value. Tool inputs arrive from the pi event
+ * loop as untyped data; they are decoded into this domain type at the I/O
+ * boundary (see index.ts) before the detector fingerprints them.
+ */
+export type ToolInput =
+  | null
+  | boolean
+  | number
+  | string
+  | ToolInput[]
+  | { readonly [key: string]: ToolInput };
+
 /** Keys sorted recursively so {a:1,b:2} and {b:2,a:1} share a signature. */
-export function canonical(input: unknown): string {
-  if (input === null || typeof input !== "object") return JSON.stringify(input);
+export function canonical(input: ToolInput): string {
   if (Array.isArray(input)) return `[${input.map(canonical).join(",")}]`;
-  const obj = input as Record<string, unknown>;
-  return `{${Object.keys(obj)
-    .sort()
-    .map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`)
-    .join(",")}}`;
+  if (input instanceof Object) {
+    return `{${Object.keys(input)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonical(input[k])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(input) ?? "";
 }
 
-export function signature(toolName: string, input: unknown): string {
+export function signature(toolName: string, input: ToolInput): string {
   return `${toolName}:${canonical(input)}`;
 }
 
@@ -77,25 +120,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> {
+  check(toolName: string, input: ToolInput): 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 +154,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();
+  record(toolName: string, input: ToolInput): void {
+    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 +220,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 +254,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 +285,80 @@ export class LoopDetector {
     return n;
   }
 
+  /** Error share of all in-window results for a tool. */
+  private failRate(toolName: string) {
+    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 +384,21 @@ 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 a tool input (used for token estimation). */
+export function stringify(input: ToolInput): string {
+  return JSON.stringify(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 +452,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 +515,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 +530,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

@@ -31,11 +31,12 @@ import {
   type AntiLoopController,
   type CommandCtxLite,
   type CtxLite,
+  type MessageContent,
   type MessageEndEventLite,
   type ToolCallEventLite,
   type ToolResultEventLite,
 } from "./controller.ts";
-import { readOptions } from "./detector.ts";
+import { readOptions, type ToolInput } from "./detector.ts";
 
 /** The subset of pi's ExtensionAPI this extension uses (structural). */
 export interface PiLike {
@@ -77,7 +78,13 @@ export default function (pi: PiLike): void {
   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);
+    // The pi event delivers untyped tool arguments; decode them into the
+    // ToolInput domain type at this I/O boundary before the controller sees them.
+    const outcome = controller.onToolCall(
+      event.toolName,
+      event.input as ToolInput,
+      event.toolCallId,
+    );
     if (outcome === null) return;
     if (outcome.escalate) {
       ctx.ui.notify("Anti-doom-loop: identical call blocked again — aborting turn", "error");
@@ -94,7 +101,11 @@ export default function (pi: PiLike): void {
   // tool calls) never reach tool_call. Steer first, abort as escalation,
   // then a bounded auto-resume so the work continues.
   pi.on("message_end", (event: MessageEndEventLite, ctx: CtxLite) => {
-    const outcome = controller.onMessageEnd(event.message.role, event.message.content);
+    // Decode the untyped message content into MessageContent at this boundary.
+    const outcome = controller.onMessageEnd(
+      event.message.role,
+      event.message.content as MessageContent,
+    );
     if (outcome === null) return;
 
     if (outcome.action === "steer") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-anti-doom-loop",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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",
@@ -36,17 +36,21 @@
     "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",
-    "effect": "^4.0.0-beta.103"
+    "effect": "^4.0.0-rc.108"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "@effect/tsgo": "^0.36.4",
+    "@oxlint/plugins": "^1.77.0",
     "@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.`,
     );
   }