@mjasnikovs/pi-task 0.13.21 → 0.13.23

package/dist/task/loop-detector.d.ts

@@ -1,12 +1,17 @@
 /**
  * Pure-logic loop detector for pi-task sub-agent phases.
  *
- * Watches a ring buffer of recent tool-call keys. When the same
- * `(toolName, stable-stringified args)` key appears `threshold` times
- * within the last `window` events, returns a LoopHit so the caller can
- * kill the child and re-spawn with a hint.
+ * Watches a ring buffer of recent tool calls and trips on two thrash patterns:
  *
- * No I/O. No imports from index.ts. Trivially unit-testable.
+ *   1. EXACT repeats — the same `(toolName, stable-stringified args)` key appears
+ *      `threshold` times within the last `window` events.
+ *   2. PATH revisits — the same primary file path is re-targeted `pathThreshold`
+ *      times within the window WITHOUT the read offset advancing, which the exact
+ *      key misses when `offset/limit` vary call-to-call. Strictly-forward paging
+ *      never trips (see countRevisits).
+ *
+ * Either pattern returns a LoopHit so the caller can kill the child and re-spawn
+ * with a hint. No I/O. No imports from index.ts. Trivially unit-testable.
  */
 export interface ToolCall {
     name: string;
@@ -22,11 +27,29 @@ export interface LoopHit {
  * Arrays preserve their order (positional). undefined / primitives passthrough.
  */
 export declare function stableStringify(value: unknown): string;
+/**
+ * The primary file path a tool call targets, mirroring summarizeToolArgs' field
+ * precedence. Returns null when the call names no path (e.g. bash, or a grep
+ * with only a pattern) so such calls never participate in path detection.
+ */
+export declare function primaryPath(args: unknown): string | null;
 export declare class LoopDetector {
     private readonly window;
     private readonly threshold;
+    /** Revisits of one path needed to trip; defaults to the exact threshold. */
+    private readonly pathThreshold;
     private readonly buf;
-    constructor(window?: number, threshold?: number);
-    /** Record a tool call. Returns LoopHit if the threshold is breached, else null. */
+    constructor(window?: number, threshold?: number, 
+    /** Revisits of one path needed to trip; defaults to the exact threshold. */
+    pathThreshold?: number);
+    /** Record a tool call. Returns LoopHit if either threshold is breached, else null. */
     record(call: ToolCall): LoopHit | null;
+    /**
+     * Count same-path calls in the window that are "revisits" — accesses whose
+     * offset does not advance past the furthest offset already seen for that
+     * path. Linear paging (strictly increasing offsets) yields zero revisits and
+     * never trips; repeated whole-file re-reads (offset 0 each time), backward
+     * jumps, and path-targeting greps (offset 0) accumulate.
+     */
+    private countRevisits;
 }

package/dist/task/loop-detector.js

@@ -1,12 +1,17 @@
 /**
  * Pure-logic loop detector for pi-task sub-agent phases.
  *
- * Watches a ring buffer of recent tool-call keys. When the same
- * `(toolName, stable-stringified args)` key appears `threshold` times
- * within the last `window` events, returns a LoopHit so the caller can
- * kill the child and re-spawn with a hint.
+ * Watches a ring buffer of recent tool calls and trips on two thrash patterns:
  *
- * No I/O. No imports from index.ts. Trivially unit-testable.
+ *   1. EXACT repeats — the same `(toolName, stable-stringified args)` key appears
+ *      `threshold` times within the last `window` events.
+ *   2. PATH revisits — the same primary file path is re-targeted `pathThreshold`
+ *      times within the window WITHOUT the read offset advancing, which the exact
+ *      key misses when `offset/limit` vary call-to-call. Strictly-forward paging
+ *      never trips (see countRevisits).
+ *
+ * Either pattern returns a LoopHit so the caller can kill the child and re-spawn
+ * with a hint. No I/O. No imports from index.ts. Trivially unit-testable.
  */
 /**
  * JSON.stringify with sorted object keys so {a:1,b:2} and {b:2,a:1} hash equal.
@@ -23,24 +28,86 @@ export function stableStringify(value) {
         return sorted;
     });
 }
+/**
+ * The primary file path a tool call targets, mirroring summarizeToolArgs' field
+ * precedence. Returns null when the call names no path (e.g. bash, or a grep
+ * with only a pattern) so such calls never participate in path detection.
+ */
+export function primaryPath(args) {
+    if (!args || typeof args !== 'object')
+        return null;
+    const a = args;
+    if (typeof a.file_path === 'string')
+        return a.file_path;
+    if (typeof a.path === 'string')
+        return a.path;
+    if (typeof a.filePath === 'string')
+        return a.filePath;
+    return null;
+}
+/** Numeric read offset (0 when absent/non-numeric) — drives progress vs revisit. */
+function readOffset(args) {
+    if (!args || typeof args !== 'object')
+        return 0;
+    const o = args.offset;
+    return typeof o === 'number' && Number.isFinite(o) ? o : 0;
+}
 export class LoopDetector {
     window;
     threshold;
+    pathThreshold;
     buf = [];
-    constructor(window = 20, threshold = 5) {
+    constructor(window = 20, threshold = 5, 
+    /** Revisits of one path needed to trip; defaults to the exact threshold. */
+    pathThreshold = threshold) {
         this.window = window;
         this.threshold = threshold;
+        this.pathThreshold = pathThreshold;
     }
-    /** Record a tool call. Returns LoopHit if the threshold is breached, else null. */
+    /** Record a tool call. Returns LoopHit if either threshold is breached, else null. */
     record(call) {
         const key = `${call.name}\x00${stableStringify(call.args)}`;
-        this.buf.push(key);
+        this.buf.push({ key, path: primaryPath(call.args), offset: readOffset(call.args) });
         if (this.buf.length > this.window)
             this.buf.shift();
-        let count = 0;
-        for (const k of this.buf)
-            if (k === key)
-                count++;
-        return count >= this.threshold ? { call, count, windowSize: this.buf.length } : null;
+        // 1. Exact-match loop: identical (name, args) repeated past threshold.
+        let exact = 0;
+        for (const e of this.buf)
+            if (e.key === key)
+                exact++;
+        if (exact >= this.threshold)
+            return { call, count: exact, windowSize: this.buf.length };
+        // 2. Path-aware loop: the same file re-targeted without forward progress.
+        // Caught here precisely because varied offset/limit make the exact key
+        // miss it (TASK_0017: auth.ts read/grepped ~12× with changing args until
+        // the wall-clock timeout, never tripping the exact detector).
+        const path = this.buf[this.buf.length - 1].path;
+        if (path !== null) {
+            const revisits = this.countRevisits(path);
+            if (revisits >= this.pathThreshold) {
+                return { call, count: revisits, windowSize: this.buf.length };
+            }
+        }
+        return null;
+    }
+    /**
+     * Count same-path calls in the window that are "revisits" — accesses whose
+     * offset does not advance past the furthest offset already seen for that
+     * path. Linear paging (strictly increasing offsets) yields zero revisits and
+     * never trips; repeated whole-file re-reads (offset 0 each time), backward
+     * jumps, and path-targeting greps (offset 0) accumulate.
+     */
+    countRevisits(path) {
+        let maxOffset = -1;
+        let revisits = 0;
+        for (const e of this.buf) {
+            if (e.path !== path)
+                continue;
+            if (e.offset > maxOffset)
+                maxOffset = e.offset; // progress: new ground
+            else
+                revisits++; // revisit: already-covered ground
+        }
+        return revisits;
     }
 }

package/dist/task/phases.js

@@ -79,6 +79,15 @@ export async function phaseVerifyTooling(deps, research) {
     return replaceToolingWithVerified(research, parsed.verified);
 }
 const DOCS_EXTENSION_PATH = new URL('../workers/docs-extension.js', import.meta.url).pathname;
+/**
+ * In-process guard loaded into the TOOLING worker only: blocks a second read of
+ * any file it already read, feeding the model "you already read this, answer
+ * now" instead of letting it re-read. TOOLING reads each file exactly once in
+ * every healthy recorded run; re-reading is purely the thrash signature, so a
+ * read-once rule has no legitimate false positive here. See single-read-guard.ts.
+ */
+const SINGLE_READ_EXTENSION_PATH = new URL('../workers/single-read-extension.js', import.meta.url)
+    .pathname;
 /**
  * Task-file heading under which a research worker's validated output is cached.
  * A resumed research phase reads these to skip workers that already succeeded,
@@ -216,7 +225,10 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             label: 'worker:tooling',
             // Scope to the goal prose only — not the per-file edit checklist that
             // makes a weak model spelunk source and loop. See scopedToolingGoal.
-            prompt: appendNoThink(promptHeader + RESEARCH_TOOLING_PROMPT(scopedToolingGoal(refined)))
+            prompt: appendNoThink(promptHeader + RESEARCH_TOOLING_PROMPT(scopedToolingGoal(refined))),
+            // Block re-reads in-process so a weak model that wants to re-read the
+            // same file is told to answer from what it has instead of looping.
+            extensions: [SINGLE_READ_EXTENSION_PATH]
         }
     ];
     // Run workers one at a time, persisting each worker's validated output the

package/dist/workers/single-read-extension.d.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/**
+ * Loaded via `-e` into the TOOLING research worker only. Blocks a second read of
+ * any file the worker has already read this run, returning a reason the model
+ * receives as an error tool result (agent-loop: block → createErrorToolResult).
+ * The worker then continues from what it has instead of re-reading. See
+ * SingleReadGuard for why this is scoped to TOOLING.
+ */
+export default function (pi: ExtensionAPI): void;

package/dist/workers/single-read-extension.js

@@ -0,0 +1,20 @@
+import { resolve } from 'node:path';
+import { SingleReadGuard } from './single-read-guard.js';
+/**
+ * Loaded via `-e` into the TOOLING research worker only. Blocks a second read of
+ * any file the worker has already read this run, returning a reason the model
+ * receives as an error tool result (agent-loop: block → createErrorToolResult).
+ * The worker then continues from what it has instead of re-reading. See
+ * SingleReadGuard for why this is scoped to TOOLING.
+ */
+export default function (pi) {
+    const guard = new SingleReadGuard();
+    pi.on('tool_call', event => {
+        if (event.toolName !== 'read')
+            return;
+        const path = event.input.path;
+        if (typeof path !== 'string')
+            return;
+        return guard.check(resolve(process.cwd(), path)) ?? undefined;
+    });
+}

package/dist/workers/single-read-guard.d.ts

@@ -0,0 +1,30 @@
+/**
+ * In-process "read each file once" guard for the TOOLING research worker.
+ *
+ * Validated against every recorded mx5 run: a healthy TOOLING worker reads each
+ * file exactly once (max same-file reads = 1 across 7 tasks). The failure case
+ * (TASK_0017) re-read the same file up to 50× — the model already had the answer
+ * (package.json) but kept oscillating read→write-fragment→read until it looped.
+ *
+ * Rather than detect-and-kill (which only restarts a model that re-thrashes), we
+ * deny the re-read *inside the run*: the extension wiring returns this guard's
+ * block result from a `tool_call` handler, so pi feeds `reason` back to the model
+ * as an error tool result and the worker continues without the re-read. No kill,
+ * no restart. Pure logic, no I/O — the extension does path resolution.
+ */
+export interface ReadBlock {
+    block: true;
+    reason: string;
+}
+/** The error text the model receives in place of the re-read's contents. */
+export declare function singleReadReason(path: string): string;
+export declare class SingleReadGuard {
+    private readonly seen;
+    /**
+     * Record a read of `resolvedPath`. Returns a ReadBlock the first time a path
+     * is seen a second time (and every time after), else null on the first read.
+     * Callers pass an already-resolved/normalized path so `a.ts` and `./a.ts`
+     * dedupe to one entry.
+     */
+    check(resolvedPath: string): ReadBlock | null;
+}

package/dist/workers/single-read-guard.js

@@ -0,0 +1,36 @@
+/**
+ * In-process "read each file once" guard for the TOOLING research worker.
+ *
+ * Validated against every recorded mx5 run: a healthy TOOLING worker reads each
+ * file exactly once (max same-file reads = 1 across 7 tasks). The failure case
+ * (TASK_0017) re-read the same file up to 50× — the model already had the answer
+ * (package.json) but kept oscillating read→write-fragment→read until it looped.
+ *
+ * Rather than detect-and-kill (which only restarts a model that re-thrashes), we
+ * deny the re-read *inside the run*: the extension wiring returns this guard's
+ * block result from a `tool_call` handler, so pi feeds `reason` back to the model
+ * as an error tool result and the worker continues without the re-read. No kill,
+ * no restart. Pure logic, no I/O — the extension does path resolution.
+ */
+/** The error text the model receives in place of the re-read's contents. */
+export function singleReadReason(path) {
+    return (`You already read ${path} earlier in this run — its contents are in your context. `
+        + `Re-reading the same file is blocked. Do not read it again: use what you have already `
+        + `gathered and write your final answer now.`);
+}
+export class SingleReadGuard {
+    seen = new Set();
+    /**
+     * Record a read of `resolvedPath`. Returns a ReadBlock the first time a path
+     * is seen a second time (and every time after), else null on the first read.
+     * Callers pass an already-resolved/normalized path so `a.ts` and `./a.ts`
+     * dedupe to one entry.
+     */
+    check(resolvedPath) {
+        if (this.seen.has(resolvedPath)) {
+            return { block: true, reason: singleReadReason(resolvedPath) };
+        }
+        this.seen.add(resolvedPath);
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.13.21",
+    "version": "0.13.23",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",