@mjasnikovs/pi-task 0.38.6 → 0.38.8

package/dist/task/auto-orchestrator.js

@@ -25,7 +25,7 @@ import { requestCancel, resetCancel, isCancelRequested, cancelCheckpoint } from
 import { armCancelListener, disarmCancelListener } from './cancel-input.js';
 import { beginRun, endRun } from './mid-run-input.js';
 import { reportDroppedInput } from './dropped-input.js';
-import { refineExistingFilesBlock } from './phases.js';
+import { refineExistingFilesBlock, SINGLE_READ_EXTENSION_PATH } from './phases.js';
 import { SessionUI, registerBridgeCommand, publishLifecycleNotice } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { startAutoLoader } from './widget.js';
@@ -1079,6 +1079,13 @@ function defaultDeps(ctx, cwd, signal, title) {
         cwd,
         taskId: '',
         signal,
+        // IN-RUN thrash guard for the planning children (mx5-n 2026-08-14: a
+        // decompose child re-read DESIGN/marketplace.html until it filled a
+        // 120k window, and ran 16m23s without returning). Every planning child
+        // gets its source doc INLINED in its prompt, so a second read of a file
+        // it has already opened can only be thrash — which makes the read-once
+        // block safe here in a way it is not for a phase that must explore.
+        childExtensions: [SINGLE_READ_EXTENSION_PATH],
         onChildOutput: (line) => {
             lastLine = line;
         },

package/dist/task/child-runner.d.ts

@@ -10,6 +10,40 @@ import type { DebugLine } from './debug-log.js';
 export declare const LOOP_WINDOW = 20;
 export declare const LOOP_THRESHOLD = 5;
 export declare const MAX_LOOP_RESTARTS = 2;
+/**
+ * Hard wall-clock bound on ONE spawn of a phase child.
+ *
+ * The loop detector above only sees IDENTICAL repeated calls; a child that
+ * re-reads the same design file at varying offsets slips past it and, with pi
+ * compacting its context whenever the window fills, never exits on its own.
+ * mx5-n 2026-08-14 is the observed case: a decompose child ran 16m23s at
+ * 117,370 of a 120,064-token window, adding ~56k tokens of tool output per
+ * minute, and had to be killed by hand. `streamInactivityMs` cannot catch it —
+ * that guard fires on SILENCE and this child was the opposite of silent.
+ *
+ * Sized against measured HEALTHY planning children on the same local 27B
+ * backend, which is the slowest thing we run: requirement extraction 54s,
+ * artifact closure 47s, decompose 89s (22 titles), coverage 17s, and a whole
+ * plan phase (clarify + two extractions + decompose) 321s end to end. Ten
+ * minutes is 3-6x the slowest of those and well under the runaway, so it ends
+ * the pathology without ever trimming honest work. Deliberately far above
+ * RESEARCH_WORKER_TIMEOUT_MS (240s): a research worker answers one question,
+ * a planning child reasons over the whole design doc.
+ */
+export declare const PHASE_CHILD_TIMEOUT_MS = 600000;
+/**
+ * Restart hint after a phase child burns its whole wall-clock budget. It
+ * diagnoses over-exploration, which is what the cap actually catches — the same
+ * job WORKER_TIMEOUT_HINT does for research workers.
+ */
+export declare const PHASE_TIMEOUT_HINT: string;
+/** Thrown when a phase child spends its whole restart budget hitting the cap. */
+export declare class PhaseTimeoutError extends Error {
+    readonly childName: string;
+    readonly budgetMs: number;
+    readonly attempts: number;
+    constructor(childName: string, budgetMs: number, attempts: number);
+}
 export declare function isConnectionError(cause: string): boolean;
 /** Exponential backoff before a connection-error retry: 500ms, 1s, 2s, …, so a
  *  brief saturation window can drain before we re-issue the request. */
@@ -24,14 +58,16 @@ export interface PhaseRunResult {
     /** Set when the child's final turn failed with stopReason "error" (model/provider failure). */
     modelError?: string;
 }
-export declare function childArgs(tools: string): string[];
+export declare function childArgs(tools: string, extensions?: readonly string[]): string[];
 export declare const USER_CANCELLED = "__user_cancelled__";
 /**
  * Run a child pi process with JSON event-stream output, loop detection, and
  * context-usage tracking. This is the typed convenience wrapper used by
  * phase-level code.
  */
-export declare function runChild(cwd: string, tools: string, prompt: string, signal: AbortSignal, onLine?: (line: string) => void, onContextUsage?: (snapshot: ContextSnapshot) => void, onToolCall?: (call: ToolCall) => LoopHit | null, spawnFn?: SpawnFn): Promise<PhaseRunResult>;
+export declare function runChild(cwd: string, tools: string, prompt: string, signal: AbortSignal, onLine?: (line: string) => void, onContextUsage?: (snapshot: ContextSnapshot) => void, onToolCall?: (call: ToolCall) => LoopHit | null, spawnFn?: SpawnFn, 
+/** Internal `-e` extension paths for in-run guards (see childArgs). */
+extensions?: readonly string[]): Promise<PhaseRunResult>;
 interface PhaseDeps {
     cwd: string;
     taskId: string;
@@ -45,6 +81,24 @@ interface PhaseDeps {
      */
     recordSubStep?: (label: string, ms: number) => void;
     spawn?: SpawnFn;
+    /**
+     * Internal `-e` extension paths loaded into this child for IN-RUN guards.
+     *
+     * The point of a guard that runs inside the child is that it does not have
+     * to kill it: pi turns a `tool_call` handler's `{block, reason}` into an
+     * error tool result, so the model reads the reason as its own tool output
+     * and continues with its context intact. The host's only alternative is to
+     * kill and re-spawn from nothing, which just re-runs a model that
+     * deterministically re-thrashes (workers/single-read-guard.ts).
+     */
+    childExtensions?: readonly string[];
+    /**
+     * Wall-clock budget for ONE spawn of this child, in ms. Defaults to
+     * PHASE_CHILD_TIMEOUT_MS; `0` disables the cap. Mirrors runWorker's
+     * `timeoutMs` input, which is the same backstop one layer down
+     * (workers/pi-worker-core.ts). Tests inject a short budget.
+     */
+    timeoutMs?: number;
     /**
      * Write a timestamped line to the per-task debug log. Fire-and-forget, and
      * UNSET entirely when the trail is off — so a caller must keep the `?.` and
@@ -68,6 +122,17 @@ export type { PhaseDeps };
  * leaking, throw LeakedToolCallError rather than returning the unexecuted call.
  * Empty completions and connection-class model errors share that same budget —
  * see triageChildResult, which decides every one of those cases.
+ *
+ * TWO RUNAWAY GUARDS ride the same budget, because this is the runner every
+ * /task-auto planning child goes through (clarify, decompose, coverage,
+ * contract-extract) and until mx5-n 2026-08-14 it had neither:
+ *   • a LoopDetector, so an identical repeated tool call is killed and
+ *     re-prompted instead of being allowed to fill the context window;
+ *   • PHASE_CHILD_TIMEOUT_MS, the backstop for the varied-args thrash the
+ *     detector cannot see — the shape that actually cost us a 16-minute
+ *     decompose child that was never going to return.
+ * Both are checked BEFORE the triage ladder: we killed the child, so its exit
+ * status describes our SIGTERM and says nothing about its verdict.
  */
 export declare function runPhaseChild(deps: PhaseDeps, name: string, tools: string, prompt: string): Promise<string>;
 export declare function formatLoopHint(hit: LoopHit): string;

package/dist/task/child-runner.js

@@ -21,6 +21,86 @@ export const LOOP_WINDOW = 20;
 export const LOOP_THRESHOLD = 5;
 export const MAX_LOOP_RESTARTS = 2; // 3 strikes total (initial attempt + 2 restarts)
 // MAX_LEAK_RETRIES lives in shared/leaked-tool-call.ts (imported above).
+// ─── Phase-child wall-clock cap ──────────────────────────────────────────────
+/**
+ * Hard wall-clock bound on ONE spawn of a phase child.
+ *
+ * The loop detector above only sees IDENTICAL repeated calls; a child that
+ * re-reads the same design file at varying offsets slips past it and, with pi
+ * compacting its context whenever the window fills, never exits on its own.
+ * mx5-n 2026-08-14 is the observed case: a decompose child ran 16m23s at
+ * 117,370 of a 120,064-token window, adding ~56k tokens of tool output per
+ * minute, and had to be killed by hand. `streamInactivityMs` cannot catch it —
+ * that guard fires on SILENCE and this child was the opposite of silent.
+ *
+ * Sized against measured HEALTHY planning children on the same local 27B
+ * backend, which is the slowest thing we run: requirement extraction 54s,
+ * artifact closure 47s, decompose 89s (22 titles), coverage 17s, and a whole
+ * plan phase (clarify + two extractions + decompose) 321s end to end. Ten
+ * minutes is 3-6x the slowest of those and well under the runaway, so it ends
+ * the pathology without ever trimming honest work. Deliberately far above
+ * RESEARCH_WORKER_TIMEOUT_MS (240s): a research worker answers one question,
+ * a planning child reasons over the whole design doc.
+ */
+export const PHASE_CHILD_TIMEOUT_MS = 600_000;
+/**
+ * Restart hint after a phase child burns its whole wall-clock budget. It
+ * diagnoses over-exploration, which is what the cap actually catches — the same
+ * job WORKER_TIMEOUT_HINT does for research workers.
+ */
+export const PHASE_TIMEOUT_HINT = '[SYSTEM NOTE: Your previous attempt ran out of time before answering — you '
+    + 'were re-reading source material you had already seen. Read each file AT '
+    + 'MOST ONCE, then write your answer from what you have. Do not re-open a '
+    + 'file you have already read.]';
+/**
+ * Combine the caller's abort signal with a wall-clock timer into one signal,
+ * keeping the two causes apart: `timedOut()` is true only when the timer fired,
+ * never when the user cancelled — so a cap can restart the child while a cancel
+ * still ends the run. `ms <= 0` disables the timer entirely.
+ *
+ * (workers/pi-worker-core.ts has the same shape for research workers. It is not
+ * shared because that module imports FROM this one; a common home for it would
+ * be worth it if a third caller ever appears.)
+ */
+function phaseTimeout(external, ms) {
+    const ctrl = new AbortController();
+    let firedByTimer = false;
+    const armed = ms > 0 && Number.isFinite(ms);
+    const timer = armed ?
+        setTimeout(() => {
+            firedByTimer = true;
+            ctrl.abort();
+        }, ms)
+        : undefined;
+    const onExternal = () => ctrl.abort();
+    if (external.aborted)
+        ctrl.abort();
+    else
+        external.addEventListener('abort', onExternal, { once: true });
+    return {
+        signal: ctrl.signal,
+        timedOut: () => firedByTimer,
+        cleanup: () => {
+            if (timer)
+                clearTimeout(timer);
+            external.removeEventListener('abort', onExternal);
+        }
+    };
+}
+/** Thrown when a phase child spends its whole restart budget hitting the cap. */
+export class PhaseTimeoutError extends Error {
+    childName;
+    budgetMs;
+    attempts;
+    constructor(childName, budgetMs, attempts) {
+        super(`${childName} child exceeded its ${Math.round(budgetMs / 1000)}s budget on all `
+            + `${attempts} attempt(s) — it never stopped working long enough to answer`);
+        this.childName = childName;
+        this.budgetMs = budgetMs;
+        this.attempts = attempts;
+        this.name = 'PhaseTimeoutError';
+    }
+}
 // ─── Connection-error retry ──────────────────────────────────────────────────
 /**
  * A connection-class model error is transient: a single dropped fetch to a live
@@ -47,7 +127,7 @@ export function connectionRetryBackoffMs(attempt) {
 }
 const defaultSleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 // ─── Spawn helpers ───────────────────────────────────────────────────────────
-export function childArgs(tools) {
+export function childArgs(tools, extensions = []) {
     // `--mode json` puts the child into the structured event stream the
     // unified runner parses in `mode: 'json-events'`. Without it the child
     // emits plain text, every line fails JSON.parse, finalText stays empty,
@@ -62,8 +142,13 @@ export function childArgs(tools) {
     // The prompt is NOT an argv element: it goes to the child over stdin (see
     // runChild below / getPiInvocation), so a large inlined-design prompt can't
     // overflow the OS command-line limit (Windows `spawn ENAMETOOLONG`).
+    //
+    // `extensions` are internal `-e` loads for in-run guards (the caller supplies
+    // the path). A no-tools child cannot make a tool call, so it never carries
+    // one — the guards all hang off pi's `tool_call` hook.
     const toolFlags = tools === '' ? ['--no-tools'] : ['--tools', tools];
-    return [...childBaseArgs(), '--mode', 'json', ...toolFlags];
+    const internal = tools === '' ? [] : extensions;
+    return [...childBaseArgs(internal), '--mode', 'json', ...toolFlags];
 }
 // Sentinel error thrown when the user dismisses a grill-me dialog.
 // Defined here (not in failure-classifier.ts) to avoid circular dependency.
@@ -74,8 +159,10 @@ export const USER_CANCELLED = '__user_cancelled__';
  * context-usage tracking. This is the typed convenience wrapper used by
  * phase-level code.
  */
-export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawnFn) {
-    const invocation = getPiInvocation(childArgs(tools), prompt);
+export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawnFn, 
+/** Internal `-e` extension paths for in-run guards (see childArgs). */
+extensions) {
+    const invocation = getPiInvocation(childArgs(tools, extensions), prompt);
     let loopHit;
     const result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, signal, {
         mode: 'json-events',
@@ -188,11 +275,52 @@ async function triageChildResult(deps, name, r, attempt, budget, verb) {
  * leaking, throw LeakedToolCallError rather than returning the unexecuted call.
  * Empty completions and connection-class model errors share that same budget —
  * see triageChildResult, which decides every one of those cases.
+ *
+ * TWO RUNAWAY GUARDS ride the same budget, because this is the runner every
+ * /task-auto planning child goes through (clarify, decompose, coverage,
+ * contract-extract) and until mx5-n 2026-08-14 it had neither:
+ *   • a LoopDetector, so an identical repeated tool call is killed and
+ *     re-prompted instead of being allowed to fill the context window;
+ *   • PHASE_CHILD_TIMEOUT_MS, the backstop for the varied-args thrash the
+ *     detector cannot see — the shape that actually cost us a 16-minute
+ *     decompose child that was never going to return.
+ * Both are checked BEFORE the triage ladder: we killed the child, so its exit
+ * status describes our SIGTERM and says nothing about its verdict.
  */
 export async function runPhaseChild(deps, name, tools, prompt) {
     let hint = null;
+    const loopHistory = [];
+    const budgetMs = deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS;
     for (let attempt = 0; attempt <= MAX_LEAK_RETRIES; attempt++) {
-        const r = await runChild(deps.cwd, tools, prependHint(hint, prompt), deps.signal, deps.onChildOutput, deps.onContextUsage, undefined, deps.spawn);
+        const detector = new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD);
+        const clock = phaseTimeout(deps.signal, budgetMs);
+        let r;
+        try {
+            r = await runChild(deps.cwd, tools, prependHint(hint, prompt), clock.signal, deps.onChildOutput, deps.onContextUsage, call => detector.record(call), deps.spawn, deps.childExtensions);
+        }
+        finally {
+            clock.cleanup();
+        }
+        // A user cancel must not be mistaken for either guard.
+        if (deps.signal.aborted)
+            throw new Error(USER_CANCELLED);
+        if (r.loopHit) {
+            loopHistory.push(r.loopHit);
+            if (attempt === MAX_LEAK_RETRIES)
+                throw new LoopExhaustedError(name, loopHistory);
+            deps.logDebug?.(`${name}: looped on ${r.loopHit.call.name} — retry ${attempt + 1}/${MAX_LEAK_RETRIES}`);
+            hint = formatLoopHint(r.loopHit);
+            continue;
+        }
+        if (clock.timedOut()) {
+            if (attempt === MAX_LEAK_RETRIES) {
+                throw new PhaseTimeoutError(name, budgetMs, MAX_LEAK_RETRIES + 1);
+            }
+            deps.logDebug?.(`${name}: exceeded its ${Math.round(budgetMs / 1000)}s budget — `
+                + `retry ${attempt + 1}/${MAX_LEAK_RETRIES}`);
+            hint = PHASE_TIMEOUT_HINT;
+            continue;
+        }
         const step = await triageChildResult(deps, name, r, attempt, MAX_LEAK_RETRIES, 'retry');
         if (step.done)
             return step.text;

package/dist/task/phases.d.ts

@@ -111,6 +111,15 @@ export declare function searchConfigured(getEnv?: (k: string) => string | undefi
 /** Extra prompt block for the APIS worker when search is available — trigger-framed
  *  (the validated shape for getting a local model to actually reach for search). */
 export declare const RESEARCH_SEARCH_HINT: string;
+/**
+ * In-process guards loaded into the TOOLING worker only: block a re-read of any
+ * file already read, and block any byte-identical grep/find/ls repeat, feeding
+ * the model "you already have this, answer now" instead of letting it re-run.
+ * TOOLING reads each file once and never needs an identical search twice in any
+ * healthy recorded run, so neither rule has a legitimate false positive here.
+ * See single-read-guard.ts.
+ */
+export declare const SINGLE_READ_EXTENSION_PATH: 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

package/dist/task/phases.js

@@ -332,7 +332,7 @@ export const RESEARCH_SEARCH_HINT = '\n\nLIVE WEB — use pi-worker-search for e
  * healthy recorded run, so neither rule has a legitimate false positive here.
  * See single-read-guard.ts.
  */
-const SINGLE_READ_EXTENSION_PATH = fileURLToPath(new URL('../workers/single-read-extension.js', import.meta.url));
+export const SINGLE_READ_EXTENSION_PATH = fileURLToPath(new URL('../workers/single-read-extension.js', import.meta.url));
 /**
  * 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,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.38.6",
+    "version": "0.38.8",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",