@mjasnikovs/pi-task 0.38.6 → 0.38.7

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. */
@@ -45,6 +79,13 @@ interface PhaseDeps {
      */
     recordSubStep?: (label: string, ms: number) => void;
     spawn?: SpawnFn;
+    /**
+     * 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 +109,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
@@ -188,11 +268,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);
+        }
+        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/package.json

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