@mjasnikovs/pi-task 0.13.20 → 0.13.22

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.d.ts

@@ -40,6 +40,22 @@ export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): P
 export interface PhaseResearchDeps extends ExternalContextDeps {
     getFileInventory?: (cwd: string, signal?: AbortSignal) => Promise<string>;
 }
+/**
+ * The TOOLING worker only needs to know which verification commands the task
+ * cares about — never the per-file edit list. Big refined prompts embed a long
+ * bulleted "fix these files" checklist *inside* the GOAL block; handing that to
+ * a weak local model drags it into reading/grepping source it doesn't need and
+ * it loops (TASK_0017: read(sql-adapter.ts) ×5 → loop-kill → fails the phase).
+ * So scope TOOLING's view to the GOAL prose, truncated at the first bullet.
+ *
+ * Fallbacks, in order: no bare `GOAL` header (free-form refined) → the whole
+ * refined unchanged; a GOAL block with no bullets → the full GOAL block. The
+ * GOAL boundary is the next bare ALL-CAPS header (CONSTRAINTS, KNOWN-UNKNOWNS,
+ * …) or end of text. Verified against every recorded refined prompt: the
+ * bullet-heavy failure case drops 3319→329 chars with zero source-file
+ * mentions; the rest are unchanged or only lightly trimmed.
+ */
+export declare function scopedToolingGoal(refined: string): string;
 export declare function phaseResearch(deps: PhaseDeps, refined: string, researchDeps?: PhaseResearchDeps): Promise<string>;
 export interface PhaseAutoAnswerDeps {
     docsFocused?: typeof docsFocused;

package/dist/task/phases.js

@@ -12,7 +12,7 @@ import { getFileInventory } from './file-inventory.js';
 import { formatServiceBlock, formatFreshnessSkippedBlock } from './service-blocks.js';
 import { gatherExternalContext } from './external-context.js';
 import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, MAX_GRILL_QUESTIONS, appendNoThink } from './prompts.js';
-import { setTaskSection, updateTaskFrontMatter } from './task-io.js';
+import { readSection, removeTaskSection, setTaskSection, updateTaskFrontMatter } from './task-io.js';
 import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js';
 import { isDuplicateQuestion, MAX_DUP_STRIKES, DUP_REPROMPT_HINT } from './question-dedup.js';
 import { parseGrillQuestions, parseAutoAnswer, autoAnswerHasTag, parseVerifyToolingOutput, deriveTitle } from './parsers.js';
@@ -79,6 +79,68 @@ 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;
+/**
+ * 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,
+ * instead of re-running all four from scratch when one of them fails — the
+ * expensive case (e.g. 3 healthy workers thrown away because the 4th looped).
+ */
+function researchWorkerCacheHeading(section) {
+    return `research worker ${section}`;
+}
+/**
+ * The TOOLING worker only needs to know which verification commands the task
+ * cares about — never the per-file edit list. Big refined prompts embed a long
+ * bulleted "fix these files" checklist *inside* the GOAL block; handing that to
+ * a weak local model drags it into reading/grepping source it doesn't need and
+ * it loops (TASK_0017: read(sql-adapter.ts) ×5 → loop-kill → fails the phase).
+ * So scope TOOLING's view to the GOAL prose, truncated at the first bullet.
+ *
+ * Fallbacks, in order: no bare `GOAL` header (free-form refined) → the whole
+ * refined unchanged; a GOAL block with no bullets → the full GOAL block. The
+ * GOAL boundary is the next bare ALL-CAPS header (CONSTRAINTS, KNOWN-UNKNOWNS,
+ * …) or end of text. Verified against every recorded refined prompt: the
+ * bullet-heavy failure case drops 3319→329 chars with zero source-file
+ * mentions; the rest are unchanged or only lightly trimmed.
+ */
+export function scopedToolingGoal(refined) {
+    const m = /^GOAL[ \t]*\n([\s\S]*?)(?=\n[A-Z][A-Z][A-Z -]*[ \t]*\n|$(?![\s\S]))/m.exec(refined);
+    if (!m)
+        return refined;
+    const goal = m[1].trim();
+    const firstBullet = goal.search(/\n[ \t]*[-*]\s/);
+    return firstBullet === -1 ? goal : goal.slice(0, firstBullet).trim();
+}
+/**
+ * Throw a descriptive error if a research worker's result is not trustworthy
+ * output, so only good output is ever cached and assembled. Precedence mirrors
+ * the original inline checks: loop/timeout exhaustion first (a loop-kill is a
+ * SIGTERM/exit 143 OR a clean exit 0 with partial text, so exitCode alone is
+ * ambiguous — the worker already burned its MAX_LOOP_RESTARTS restarts before
+ * setting these), then exit code, empty output, and finally a leaked
+ * (never-executed) tool call.
+ */
+function assertResearchWorkerOk(name, result) {
+    if (result.loopHit) {
+        const argsStr = JSON.stringify(result.loopHit.call.args);
+        throw new Error(`Research ${name} worker stuck in a loop — called `
+            + `${result.loopHit.call.name}(${argsStr}) ×${result.loopHit.count} in the last `
+            + `${result.loopHit.windowSize} calls and still looped after restarts`);
+    }
+    if (result.timedOut) {
+        throw new Error(`Research ${name} worker timed out after restarts`);
+    }
+    if (result.exitCode !== 0) {
+        throw new Error(`Research ${name} worker failed (exit ${result.exitCode}): ${result.stderr.slice(-500)}`);
+    }
+    if (result.text.trim().length === 0) {
+        throw new Error(`Research ${name} worker produced no output`);
+    }
+    if (result.leakedToolCall) {
+        throw new Error(`Research ${name} worker wrote a tool call as text instead of invoking it `
+            + `(${result.leakedToolCall.trim()}) — it never ran`);
+    }
+}
 export async function phaseResearch(deps, refined, researchDeps = {}) {
     const fileInventoryFn = researchDeps.getFileInventory ?? getFileInventory;
     const externalContext = await gatherExternalContext(refined, deps, researchDeps);
@@ -152,11 +214,27 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         {
             section: 'TOOLING',
             label: 'worker:tooling',
-            prompt: appendNoThink(promptHeader + RESEARCH_TOOLING_PROMPT(refined))
+            // 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)))
         }
     ];
-    const workerResults = [];
+    // Run workers one at a time, persisting each worker's validated output the
+    // moment it succeeds. On a resume, a worker whose cached output is already on
+    // disk is skipped — so when one worker fails and the phase is re-run, the
+    // others don't burn minutes regenerating work that was already good. Each
+    // worker is validated inline (not in a second pass) so a failure throws
+    // before later workers run, and only trustworthy text is ever cached.
+    const sections = [];
     for (const spec of workerSpecs) {
+        const cacheHeading = researchWorkerCacheHeading(spec.section);
+        const cached = (await readSection(deps.cwd, deps.taskId, cacheHeading)) ?? '';
+        if (cached.trim().length > 0) {
+            deps.logDebug?.(`${spec.label}: cached — skipping re-run`);
+            updateProgress();
+            sections.push({ name: spec.section, text: cached.trim() });
+            continue;
+        }
         deps.logDebug?.(`${spec.label}: start`);
         const r = await recordWorker(spec.label, runWorker({
             prompt: spec.prompt,
@@ -174,39 +252,20 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             + (r.stderr ? ` stderr=${r.stderr.slice(0, 300)}` : '')
             + (r.leakedToolCall ? ` leaked=${r.leakedToolCall.trim().slice(0, 80)}` : ''));
         updateProgress();
-        workerResults.push(r);
+        // Throws (failing the phase) on a loop/timeout/exit/empty/leak — so the
+        // workers that already succeeded above stay cached for the resume.
+        assertResearchWorkerOk(spec.section, r);
+        await setTaskSection(deps.cwd, deps.taskId, cacheHeading, r.text);
+        sections.push({ name: spec.section, text: r.text.trim() });
     }
-    // Validate + assemble by mapping spec.section over the results, so adding or
-    // reordering a worker is a single edit to workerSpecs (the result order
-    // mirrors workerSpecs order — the loop above pushes in sequence).
-    const sections = workerSpecs.map((spec, i) => ({ name: spec.section, result: workerResults[i] }));
-    for (const { name, result } of sections) {
-        // Loop/timeout exhaustion is checked before the generic exit-code branch:
-        // a loop-kill arrives as a SIGTERM (exit 143) AND sometimes as a clean
-        // exit 0 with partial text, so keying off exitCode alone would either give
-        // a useless "exit 143" message or silently accept truncated output. The
-        // worker already burned its MAX_LOOP_RESTARTS restarts before setting these.
-        if (result.loopHit) {
-            const argsStr = JSON.stringify(result.loopHit.call.args);
-            throw new Error(`Research ${name} worker stuck in a loop — called `
-                + `${result.loopHit.call.name}(${argsStr}) ×${result.loopHit.count} in the last `
-                + `${result.loopHit.windowSize} calls and still looped after restarts`);
-        }
-        if (result.timedOut) {
-            throw new Error(`Research ${name} worker timed out after restarts`);
-        }
-        if (result.exitCode !== 0) {
-            throw new Error(`Research ${name} worker failed (exit ${result.exitCode}): ${result.stderr.slice(-500)}`);
-        }
-        if (result.text.trim().length === 0) {
-            throw new Error(`Research ${name} worker produced no output`);
-        }
-        if (result.leakedToolCall) {
-            throw new Error(`Research ${name} worker wrote a tool call as text instead of invoking it `
-                + `(${result.leakedToolCall.trim()}) — it never ran`);
-        }
+    // All workers succeeded — the assembled output below becomes the canonical
+    // 'research' section (written by the orchestrator). The per-worker caches
+    // exist only to survive a mid-phase failure, so drop them now to avoid
+    // carrying every section twice in the task file.
+    for (const spec of workerSpecs) {
+        await removeTaskSection(deps.cwd, deps.taskId, researchWorkerCacheHeading(spec.section));
     }
-    return sections.map(({ name, result }) => `${name}\n${result.text}`).join('\n\n');
+    return sections.map(({ name, text }) => `${name}\n${text}`).join('\n\n');
 }
 export async function phaseAutoAnswer(deps, refined, research, question, autoDeps = {}) {
     const docsFocusedFn = autoDeps.docsFocused ?? docsFocused;

package/dist/task/task-io.d.ts

@@ -17,3 +17,5 @@ export declare function writeTaskFile(cwd: string, fm: TaskFrontMatter, body: st
 export declare function updateTaskFrontMatter(cwd: string, id: string, patch: Partial<TaskFrontMatter>): Promise<void>;
 export declare function readSection(cwd: string, id: string, heading: string): Promise<string | null>;
 export declare function setTaskSection(cwd: string, id: string, heading: string, content: string): Promise<void>;
+/** Remove a section (heading + body) if present; a no-op when it's absent. */
+export declare function removeTaskSection(cwd: string, id: string, heading: string): Promise<void>;

package/dist/task/task-io.js

@@ -76,3 +76,12 @@ export async function setTaskSection(cwd, id, heading, content) {
     }
     await writeTaskFile(cwd, { ...frontMatter, updated_at: new Date().toISOString() }, next);
 }
+/** Remove a section (heading + body) if present; a no-op when it's absent. */
+export async function removeTaskSection(cwd, id, heading) {
+    const { frontMatter, body } = await readTaskFile(cwd, id);
+    const re = sectionRegex(heading);
+    if (!re.test(body))
+        return;
+    const next = body.replace(re, '');
+    await writeTaskFile(cwd, { ...frontMatter, updated_at: new Date().toISOString() }, next);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.13.20",
+    "version": "0.13.22",
     "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",