@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/child-runner.js

@@ -9,41 +9,37 @@ import { spawn } from 'node:child_process';
 import { getPiInvocation } from '../shared/pi-invocation.js';
 import { runChild as runChildUnified } from '../shared/child-process.js';
 import { childBaseArgs } from '../shared/child-extensions.js';
-import { LoopDetector } from './loop-detector.js';
+import { LoopDetector, MAX_LOOP_RESTARTS } from './loop-detector.js';
 import { StallDetector, formatStallHint } from './stall-detector.js';
 import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 import { readSection, setTaskSection } from './task-io.js';
 import { streamStallCause } from '../shared/stream-watchdog.js';
+import { commandCeilingForAttempt, commandTimeoutHint, commandWatch } from '../shared/command-watchdog.js';
+import { discoverModelEndpoints, probeModelEndpoints } from '../shared/model-endpoint.js';
+// VALUE import, and it is only safe because worker-profiles.ts reads its loop
+// constants from loop-detector.ts. Point those back at this file and the graph
+// closes into a TDZ ReferenceError that no compile step catches.
+import { workerPolicy } from '../workers/worker-profiles.js';
 import { getConfig } from '../config/config.js';
 import { groupThinkingArgs } from '../config/reasoning-args.js';
 import { reasoningGroupForChild } from '../config/reasoning.js';
-// ─── Loop detection constants ────────────────────────────────────────────────
-// Defined here (not in phases.ts) to avoid a circular dependency:
-//   phases.ts → child-runner.ts → phases.ts
-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 ──────────────────────────────────────────────
 /**
  * Optional wall-clock bound on ONE spawn of a phase child. DEFAULT: OFF.
  *
- * It used to default to 600_000, sized against measured HEALTHY planning
- * children on one local 27B backend (decompose 89s, whole plan phase 321s) on
- * the reasoning that ten minutes was a 3-6x margin over honest work.
+ * WHY OFF, AND NOT A NUMBER. A wall clock on a model child measures the
+ * MODEL'S SPEED, not its health. The same planning child that answers well in
+ * seconds on one backend takes many minutes on another, or on the same backend
+ * with thinking turned on — so any cap generous enough to be safe is too loose
+ * to catch anything, and any cap tight enough to catch a runaway kills healthy
+ * work. Assume a model that emits one token per second and the number has no
+ * defensible value at all.
  *
- * That premise was measured and is false. Replaying ONE captured auto-decompose
- * request against the same backend with reasoning ON, n=10, everything else
- * byte-identical (2026-08-17): all ten answered correctly with 26-42 titles, and
- * every one took 610-927s. The cap would have killed 10 out of 10 GOOD runs and
- * then failed the phase with PhaseTimeoutError. The number was not measuring the
- * pathology, it was measuring one model's speed on one day.
- *
- * The runaway it was there to catch — a decompose child that ran 16m23s at
- * 117,370 of a 120,064-token window, forward-paging past the loop detector — is
- * now caught by StallDetector (stall-detector.ts), which bounds NON-PROGRESS and
- * CONTEXT CHURN instead of elapsed seconds. Both of those are properties of the
- * pathology, so neither has to be re-tuned for a slower model or a bigger repo.
+ * The runaway it was there to catch — a child forward-paging through its whole
+ * context window, past the loop detector, never going to return — is caught by
+ * StallDetector (stall-detector.ts) instead. That bounds NON-PROGRESS and
+ * CONTEXT CHURN, both properties of the pathology itself, so neither has to be
+ * re-tuned for a slower model or a bigger repo.
  *
  * The value and the plumbing stay for a caller that genuinely wants a hard stop
  * (tests inject a short one), but nothing sets it in production. Pass
@@ -108,6 +104,75 @@ export class PhaseTimeoutError extends Error {
         this.name = 'PhaseTimeoutError';
     }
 }
+/**
+ * The terminal error for a guard kill, or null when the child was not killed.
+ *
+ * Both spawn paths must ask. A kill reports `exitCode: 0` (child-process.ts uses
+ * `code ?? 0`, and a signal gives null), so a path that tests the exit code
+ * instead returns the truncated text as the phase's answer.
+ */
+export function guardKillError(name, r, opts = {}) {
+    if (r.commandKill)
+        return new CommandTimeoutError(name, r.commandKill);
+    // A dead-backend verdict is only trusted once every attempt has produced it.
+    // `discoverModelEndpoints` reads EVERY provider in models.json, not the one
+    // this child's model uses, so a stopped local server can condemn a run against
+    // a healthy cloud backend. The asymmetry settles it: a backend that really is
+    // down costs three 5s probes, a wrong verdict costs the whole run.
+    if (r.stalled)
+        return opts.finalAttempt === false ? null : new BackendDownError(name);
+    return null;
+}
+/**
+ * The dead-backend probe killed a phase child on its LAST attempt.
+ *
+ * Reaching this means every attempt found no endpoint answering, not one. The
+ * single-probe verdict is not trusted on its own: `discoverModelEndpoints` reads
+ * every provider in models.json rather than the one this child's model uses, so a
+ * stopped local server can condemn a run against a healthy cloud backend. Three
+ * failed probes cost ~15s; one wrong verdict costs the run.
+ */
+export class BackendDownError extends Error {
+    childName;
+    constructor(childName) {
+        super(`${childName} child killed: no output for the stall window and the model `
+            + `endpoint did not answer a probe`);
+        this.childName = childName;
+        this.name = 'BackendDownError';
+    }
+}
+/**
+ * A phase child spent every attempt on a command that never returned. Its own
+ * class because the fix is in the SPEC, not the model's exploration: a VERIFY
+ * block naming an unbounded `dev` command re-hangs every attempt.
+ */
+export class CommandTimeoutError extends Error {
+    childName;
+    kill;
+    constructor(childName, kill) {
+        super(`${childName} child ran \`${kill.toolName}\``
+            + `${kill.detail ? ` (${kill.detail})` : ''} past its `
+            + `${Math.round(kill.timeoutMs / 1000)}s ceiling on every attempt`);
+        this.childName = childName;
+        this.kill = kill;
+        this.name = 'CommandTimeoutError';
+    }
+}
+/**
+ * Causes a best-effort `catch` must NOT absorb.
+ *
+ * A phase child that merely answered badly should degrade — that is what those
+ * catches are for. These two are different in kind: the run is over either way,
+ * and swallowing them ships a half-built spec while every later phase dies
+ * against the same dead backend, or turns a user's ESC into silent progress.
+ * `failure-classifier.ts` has a verdict for both; a catch that eats them makes it
+ * unreachable.
+ */
+export function isFatalChildCause(e) {
+    if (e instanceof BackendDownError)
+        return true;
+    return e instanceof Error && e.message === USER_CANCELLED;
+}
 // ─── Connection-error retry ──────────────────────────────────────────────────
 /**
  * A connection-class model error is transient: a single dropped fetch to a live
@@ -123,9 +188,54 @@ export class PhaseTimeoutError extends Error {
  * provider 5xx that names a real fault) still fails fast: re-spawning against
  * the same request won't fix it, so burning the budget only delays the report.
  */
-const CONNECTION_ERROR_RE = /\b(?:connection error|connection (?:lost|closed|reset|refused|aborted)|econnreset|econnrefused|econnaborted|epipe|etimedout|enetunreach|enetdown|eai_again|socket hang up|fetch failed|network (?:error|timeout)|premature close|request timed out|terminated|unreachable)\b/i;
+/**
+ * Transport-level failures worth another attempt.
+ *
+ * SCOPE, and it is deliberate: connection classes only. pi's own
+ * `isRetryableAssistantError` (@earendil-works/pi-ai, `dist/utils/retry.js`) also
+ * retries the provider-LOAD family — `429`, `5xx`, `rate limit`, `overloaded` —
+ * which `does NOT match real, non-transient faults` in child-runner.test.ts
+ * explicitly rejects. That disagreement is real and OPEN; it is not settled here,
+ * because this backoff starts at 500ms and a 429 answered that fast is a retry
+ * storm, not a recovery.
+ *
+ * MEASURED against pi before widening: the transport entries added here — a bare
+ * `timed out`, `getaddrinfo ENOTFOUND`, `upstream connect`, `reset before
+ * headers`, a truncated Anthropic stream and a closed websocket — were all
+ * MISSES. Every one is a REMOTE-provider failure, which is why a local llama.cpp
+ * setup never surfaced the gap. The errno spellings are pi-task's own: a child
+ * reports them through stderr, and pi never sees them.
+ *
+ * pi's bare `timeout` is deliberately NOT reproduced. It matched a provider 400
+ * that merely echoed a `timeout` field back, turning a fail-fast into a full
+ * retry budget, and it caught nothing the `timed out` spellings above miss.
+ */
+const CONNECTION_ERROR_RE = /\b(?:connection error|connection (?:lost|closed|reset|refused|aborted)|econnreset|econnrefused|econnaborted|epipe|etimedout|enetunreach|enetdown|eai_again|socket hang up|socket connection was closed|fetch failed|network (?:error|timeout)|premature close|terminated|unreachable|getaddrinfo|enotfound|upstream.?connect|reset before headers|timed? out|ended without|stream ended before message_stop|websocket.?(?:closed|error))\b/i;
+/**
+ * Provider LOAD, which is transient in a different way: the server is up and
+ * saying "not now". pi retries all of these; 53f0488 did not, but its own message
+ * names only "context overflow, bad request, auth" as the fail-fast set — a
+ * throttle was never argued for, it just rode along in a list written for a LOCAL
+ * server, where none of these can occur.
+ *
+ * Words carry no trailing \b (`overloaded_error` joins on `_`, which is a word
+ * character); the bare status codes carry one, or `500` matches inside `15000`.
+ */
+const PROVIDER_LOAD_RE = /(?:overloaded|rate.?limit|too many requests|service.?unavailable|server.?error|internal.?error|provider.?returned.?error)|\b(?:429|500|502|503|504|524)\b/i;
+/**
+ * Account facts, not liveness: a budget does not refill on a retry. Checked FIRST,
+ * because these arrive worded as a throttle — `429 GoUsageLimitError` is a
+ * subscription limit, not a queue.
+ */
+const NON_RETRYABLE_RE = /\b(?:insufficient_quota|quota exceeded|out of budget|billing|usage limit reached|available balance|GoUsageLimitError|FreeUsageLimitError)\b/i;
+/**
+ * Retry budget is three attempts at 500ms/1s/2s — three requests over 3.5s, which
+ * is not a storm even against a throttle. pi's own ladder is three at 2s/4s/8s.
+ */
 export function isConnectionError(cause) {
-    return CONNECTION_ERROR_RE.test(cause);
+    if (NON_RETRYABLE_RE.test(cause))
+        return false;
+    return CONNECTION_ERROR_RE.test(cause) || PROVIDER_LOAD_RE.test(cause);
 }
 /** Exponential backoff before a connection-error retry: 500ms, 1s, 2s, …, so a
  *  brief saturation window can drain before we re-issue the request. */
@@ -145,8 +255,8 @@ thinking = []) {
     // `--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,
-    // and every phase fails with "X child produced no output". Was silently
-    // dropped in the 4e34f96 split-refactor; do not remove again.
+    // and every phase fails with "X child produced no output". A refactor has
+    // dropped it once already; do not remove it again.
     //
     // An empty `tools` string means "no tools at all" — emit `--no-tools`
     // instead of `--tools ''` (which pi would reject). Used by pure-judgment
@@ -154,8 +264,9 @@ thinking = []) {
     // hand them, never spend time reading the repo.
     //
     // 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`).
+    // runChild below / getPiInvocation), so a large inlined-design prompt cannot
+    // exceed the OS argv ceiling — which fails the spawn outright rather than
+    // truncating (`E2BIG` on this platform).
     //
     // `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
@@ -167,30 +278,75 @@ thinking = []) {
 // Sentinel error thrown when the user dismisses a grill-me dialog.
 // Defined here (not in failure-classifier.ts) to avoid circular dependency.
 export const USER_CANCELLED = '__user_cancelled__';
-export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawn: spawnFn, extensions, onToolResult, contextWindow, thinking }) {
+/**
+ * The `phase` row of WORKER_PROFILES, resolved with this machine's config.
+ *
+ * Read here rather than at module load so a /task-config change reaches the next
+ * child, the same contract childBaseArgs already keeps. Both spawn paths in this
+ * file go through it, so the degraded final attempt cannot drift from the ordinary
+ * one — the mislabel class runDegradedFinalAttempt's own comment warns about.
+ */
+export function phasePolicy() {
+    return workerPolicy('phase', {
+        commandTimeoutMs: getConfig().requestTimeoutMs,
+        streamInactivityMs: getConfig().streamInactivityMs
+    });
+}
+export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawn: spawnFn, extensions, onToolResult, contextWindow, thinking, commandCeilingMs }) {
     const invocation = getPiInvocation(childArgs(tools, extensions, thinking), prompt);
     let loopHit;
-    const result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, signal, {
-        mode: 'json-events',
-        // A hung model stream reports nothing at all, so without this the
-        // phase child waits forever (mx5 run 14: ~2.9h of dead air). The kill
-        // is reported below as a connection-class cause, which routes it into
-        // the retry/backoff path this file already has for a LOUD disconnect.
-        streamInactivityMs: getConfig().streamInactivityMs,
-        onLine,
-        onContextUsage,
-        ...(contextWindow && contextWindow > 0 ? { contextWindow } : {}),
-        onToolResult: onToolResult ? r => onToolResult(r.text, r.isError) : undefined,
-        onToolCall: call => {
-            if (!onToolCall)
-                return null;
-            const hit = onToolCall(call);
-            if (hit && !loopHit) {
-                loopHit = hit;
+    const guards = phasePolicy().guards;
+    // Null when the user set the ceiling to `off`. Why a phase child needs this at
+    // all is the `phase` row's `why` in worker-profiles.ts.
+    const cmdWatch = commandWatch(commandCeilingMs ?? guards['command-timeout']);
+    const childSignal = cmdWatch ? AbortSignal.any([signal, cmdWatch.signal]) : signal;
+    let result;
+    try {
+        result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, childSignal, {
+            mode: 'json-events',
+            // A hung model stream reports nothing at all, so without this the
+            // phase child waits forever. The kill
+            // is reported below as a connection-class cause, which routes it into
+            // the retry/backoff path this file already has for a LOUD disconnect.
+            streamInactivityMs: guards['stream-stall'],
+            ...(guards.stalled === false ?
+                {}
+                : {
+                    stall: {
+                        afterMs: guards.stalled.afterMs,
+                        probe: guards.stalled.probe
+                            ?? (() => probeModelEndpoints(discoverModelEndpoints()))
+                    }
+                }),
+            onLine,
+            onContextUsage,
+            ...(contextWindow && contextWindow > 0 ? { contextWindow } : {}),
+            // ALWAYS wired, never conditional on the caller wanting results:
+            // the sink emits a tool-execution-end only when a handler exists,
+            // and without that end the command watchdog's timer is never
+            // disarmed — every healthy tool call would then look hung.
+            onToolResult: r => {
+                cmdWatch?.onEnd(r.toolCallId);
+                onToolResult?.(r.text, r.isError);
+            },
+            onToolCall: call => {
+                // Before the detectors: a call they let through still needs its
+                // clock started.
+                cmdWatch?.onStart(call);
+                if (!onToolCall)
+                    return null;
+                const hit = onToolCall(call);
+                if (hit && !loopHit) {
+                    loopHit = hit;
+                }
+                return hit; // propagate to unified runner so it can kill
             }
-            return hit; // propagate to unified runner so it can kill
-        }
-    });
+        });
+    }
+    finally {
+        cmdWatch?.clear();
+    }
+    const commandKill = cmdWatch?.killed();
     // Use `||` (not `??`) so an empty string from json-events mode falls
     // back to raw stdout. Without this, a child that exits 0 but emits no
     // assistant text (e.g. model API error swallowed in json mode) always
@@ -204,14 +360,16 @@ export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUs
         ?? (result.streamStalled ? streamStallCause(result.streamStalled.idleMs) : undefined);
     return {
         text,
-        // WE killed this child, so its exit status describes our own SIGTERM, not
-        // the child's verdict. Report 0 and let `modelError` carry the cause —
-        // otherwise the wrappers' `exitCode !== 0` guard throws a bare "child
-        // failed" before the connection-error retry ever gets to look.
-        exitCode: result.streamStalled ? 0 : result.exitCode,
+        // WE killed this child, so its exit status is our own SIGTERM. Report 0
+        // and let the named cause carry it. EVERY guard kill must be listed: one
+        // omitted here arrives as exit 0 with partial text, and triageChildResult
+        // returns it as a successful answer.
+        exitCode: result.streamStalled || result.stalled || commandKill ? 0 : result.exitCode,
         stderr: result.stderr.trim(),
         loopHit,
         modelError,
+        ...(commandKill ? { commandKill } : {}),
+        ...(result.stalled ? { stalled: true } : {}),
         // A tool call the model wrote as text (wrong dialect) never executed and
         // sailed past the structured-event guards above; flag it so the wrappers
         // can re-prompt instead of accepting the unexecuted call. Only meaningful
@@ -226,9 +384,8 @@ export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUs
  * verdict, so a fix to any rung lands in every caller at once.
  *
  * `attempt` is the caller's 0-based counter, `budget` the matching restart
- * allowance (MAX_LEAK_RETRIES, which is also MAX_LOOP_RESTARTS — the loop and
- * leak budgets were separate constants at the same value and are shared by one
- * loop now) — so a phase runs `budget + 1` attempts before a rung gives up.
+ * allowance — MAX_LEAK_RETRIES and MAX_LOOP_RESTARTS are both 2, and one loop
+ * spends the pair — so a phase runs `budget + 1` attempts before a rung gives up.
  *
  * `verb` names the restart in the debug log ("retry" by default, "restart" for
  * refine and grill-gen). It is the only externally visible thing that differed
@@ -240,7 +397,11 @@ export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUs
  */
 async function triageChildResult(deps, name, r, attempt, budget, verb) {
     if (r.exitCode !== 0) {
-        throw new Error(`${name} child failed: ${r.stderr || '(no stderr)'}`);
+        // The exit code is the only signal when stderr is empty, and pi exits
+        // silently on several paths (143 = SIGTERM/loop-kill, 137 = SIGKILL/OOM).
+        // Dropping it left "(no stderr)" as the whole diagnosis.
+        const why = r.stderr || `no stderr, exit ${r.exitCode}`;
+        throw new Error(`${name} child failed: ${why}`);
     }
     if (r.modelError) {
         // The model/provider failed (pi exited 0 with a stopReason "error"
@@ -286,16 +447,16 @@ async function triageChildResult(deps, name, r, attempt, budget, verb) {
  *
  * THREE 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 none:
+ * contract-extract), and an unguarded planning child can burn a whole run:
  *   • a LoopDetector, so an identical repeated tool call is killed and
  *     re-prompted instead of being allowed to fill the context window;
  *   • a StallDetector, the backstop for the varied-args thrash the loop
- *     detector's short window cannot see — the shape that actually cost us a
- *     16-minute decompose child that was never going to return. It bounds
+ *     detector's short window cannot see — a child that keeps calling tools with
+ *     different arguments, learns nothing, and is never going to return. It bounds
  *     consecutive no-new-ground calls and total context churn, NOT elapsed time;
- *   • PHASE_CHILD_TIMEOUT_MS, a hard wall clock, OFF by default because the
- *     measured healthy range (610-927s for a reasoning-on decompose) overlaps
- *     any value that would catch the pathology. See its comment.
+ *   • PHASE_CHILD_TIMEOUT_MS, a hard wall clock, OFF by default: a healthy
+ *     reasoning-on planning child and a runaway one occupy the same range of
+ *     elapsed times, so no threshold separates them. See its comment.
  * All three are checked BEFORE the triage ladder: we killed the child, so its
  * exit status describes our SIGTERM and says nothing about its verdict.
  */
@@ -345,17 +506,29 @@ export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
     let hint = null;
     const loopHistory = [];
     const budgetMs = deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS;
+    // From the `phase` row, not from literals here, so the table is the one place
+    // that answers "how may this child die". The row resolves to the same
+    // DEFAULT_LOOP_DETECTOR / DEFAULT_LOOP_PROGRESS this file used to hard-code.
+    const loopGuard = phasePolicy().guards.loop;
+    // Watchdog kills, NOT total strikes: a loop restart never saw the
+    // bound-your-command hint. Without the halving, three attempts at the default
+    // ceiling cost 45 minutes and nothing else bounds this path.
+    let hangKills = 0;
     for (let attempt = 0; attempt <= MAX_LEAK_RETRIES; attempt++) {
         // A cancel between attempts must not buy another spawn.
         if (deps.signal.aborted)
             throw new Error(USER_CANCELLED);
-        const detector = new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD);
-        const stall = new StallDetector();
-        // Arm the churn rule BEFORE the first tool call. The window used to reach
-        // the detector only through a context snapshot, and pi's stream never
-        // carries one, so it was always 0 and rule 2 never fired (issue #16). The
-        // parent knows the value at spawn time — say it then, not later.
-        stall.noteContext(deps.contextWindow ?? 0);
+        const detector = loopGuard.detector === false ?
+            null
+            : new LoopDetector(loopGuard.detector.window, loopGuard.detector.threshold, loopGuard.detector.pathThreshold);
+        const stall = loopGuard.progress === false ?
+            null
+            : new StallDetector(loopGuard.progress.limit, loopGuard.progress.churnFactor);
+        // Arm the churn rule BEFORE the first tool call. pi's stream carries no
+        // context WINDOW, so a detector that waited to be told one would sit at 0,
+        // and the churn rule returns false on a non-positive window. The parent
+        // knows the value at spawn time — say it then, not later.
+        stall?.noteContext(deps.contextWindow ?? 0);
         const clock = phaseTimeout(deps.signal, budgetMs);
         let r;
         try {
@@ -365,14 +538,16 @@ export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
                 signal: clock.signal,
                 thinking,
                 onContextUsage: snapshot => {
-                    // Real window or nothing: noteContext ignores 0, and until
-                    // deps.contextWindow existed 0 was all it ever saw, which
-                    // left the churn rule permanently disarmed (issue #16).
-                    stall.noteContext(snapshot.contextWindow);
+                    // Real window or nothing: `noteContext` ignores 0, which is
+                    // why the parent's value must be supplied at spawn — a
+                    // stream that only ever reports 0 leaves the churn rule
+                    // permanently disarmed.
+                    stall?.noteContext(snapshot.contextWindow);
                     deps.onContextUsage?.(snapshot);
                 },
-                onToolCall: call => detector.record(call) ?? stall.record(call),
-                onToolResult: (text, isError) => stall.noteResult(text, isError)
+                commandCeilingMs: commandCeilingForAttempt(phasePolicy().guards['command-timeout'], hangKills),
+                onToolCall: call => detector?.record(call) ?? stall?.record(call) ?? null,
+                onToolResult: (text, isError) => stall?.noteResult(text, isError)
             }));
         }
         finally {
@@ -402,6 +577,36 @@ export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
             hint = r.loopHit.stall ? formatStallHint(r.loopHit.stall) : formatLoopHint(r.loopHit);
             continue;
         }
+        // Ordered after the loop rule and before the clock, matching RESTART_ORDER
+        // (worker-kill.ts): the loop hint names the offending call and is the more
+        // specific thing to tell a re-spawn, and a watchdog kill leaves the phase
+        // clock's own flag false, so the two cannot be confused.
+        if (r.commandKill) {
+            hangKills++;
+            if (attempt === MAX_LEAK_RETRIES) {
+                throw new CommandTimeoutError(name, r.commandKill);
+            }
+            deps.logDebug?.(`${name}: ${r.commandKill.toolName} outran `
+                + `${Math.round(r.commandKill.timeoutMs / 1000)}s — `
+                + `${verb} ${attempt + 1}/${MAX_LEAK_RETRIES}`);
+            // Tracks the TOOLS, not the phase: verify-tooling holds `read,bash`,
+            // and a half-written node_modules survives the kill.
+            hint = commandTimeoutHint(r.commandKill.toolName, r.commandKill.timeoutMs, {
+                ...(r.commandKill.detail ? { commandDetail: r.commandKill.detail } : {}),
+                editsMayPersist: /\b(?:bash|edit|write)\b/.test(tools)
+            });
+            continue;
+        }
+        // A dead-backend kill spends a strike like the others; guardKillError says
+        // when the verdict has been earned.
+        const killed = guardKillError(name, r, { finalAttempt: attempt === MAX_LEAK_RETRIES });
+        if (killed)
+            throw killed;
+        if (r.stalled) {
+            deps.logDebug?.(`${name}: no output for the stall window and no endpoint answered — `
+                + `${verb} ${attempt + 1}/${MAX_LEAK_RETRIES}`);
+            continue;
+        }
         if (clock.timedOut()) {
             if (attempt === MAX_LEAK_RETRIES) {
                 throw new PhaseTimeoutError(name, budgetMs, MAX_LEAK_RETRIES + 1);
@@ -450,8 +655,8 @@ export function prependHint(hint, prompt) {
  * Append one line to the task file's `loop events` section.
  *
  * Best-effort by contract: it runs for EVERY phase child now that there is one
- * loop, and the six sites that used to reach the un-trailed wrapper do not all
- * own a task file on disk (a scripted harness, a bare unit deps bag). A trail
+ * loop, and not every caller owns a task file on disk (a scripted harness, a
+ * bare unit deps bag). A trail
  * that cannot be written must cost the phase nothing — the loop kill itself is
  * already reported through the debug log and the thrown LoopExhaustedError.
  */
@@ -480,11 +685,9 @@ async function appendLoopEvent(cwd, taskId, phase, hit, strike, outcome) {
  */
 async function runDegradedFinalAttempt(deps, name, prompt, hit, loopHistory) {
     deps.logDebug?.(`${name}: loop budget exhausted — degrading to a no-tools final attempt`);
-    // BEHAVIOUR DELTA. This attempt now runs under the same wall clock as the
-    // strikes that led here. It used to pass `deps.signal` raw — one of the
-    // three drifts that came of reaching past bare `undefined`s to the later
-    // positionals — so the one attempt made after a loop budget was spent was
-    // also the one attempt that could hang forever.
+    // This attempt runs under the same wall clock as the strikes that led here.
+    // Passing `deps.signal` raw instead would make the one attempt taken after a
+    // loop budget is spent the one attempt that can hang forever.
     const clock = phaseTimeout(deps.signal, deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS);
     let r;
     try {
@@ -501,12 +704,17 @@ async function runDegradedFinalAttempt(deps, name, prompt, hit, loopHistory) {
     finally {
         clock.cleanup();
     }
+    // BEFORE the exit-code test, not inside it: a guard kill reports exit 0, so
+    // asking afterwards would already have returned the truncated text as this
+    // phase's deliverable.
+    const killed = guardKillError(name, r);
+    if (killed)
+        throw killed;
     if (r.exitCode !== 0 || r.modelError || r.text.trim().length === 0) {
-        // A wall-clock kill is NOT a loop. The clock above is new here, and
-        // without this check a degrade that outran its budget was reported as
-        // "loop budget exhausted", carrying a loop history that did not cause it
-        // — the same mislabel class the worker-kill roster exists to prevent, on
-        // the very path that clock was added to guard.
+        // A wall-clock kill is NOT a loop. Without this check a child that outran
+        // its budget is reported as "loop budget exhausted", carrying a loop
+        // history that did not cause it — the same mislabel class the worker-kill
+        // roster exists to prevent, on the very path the clock guards.
         if (clock.timedOut()) {
             throw new PhaseTimeoutError(name, deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS, 1);
         }

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

@@ -2,21 +2,22 @@
  * ChildStatus — the live status of the child pi currently running under a
  * status loader: its latest output line and its context usage.
  *
- * Four sites used to keep this state by hand — `let lastLine; let contextUsage;`
+ * Without it each spawn site keeps this state by hand — `let lastLine; let contextUsage;`
  * plus two callbacks (`onChildOutput` writes the line, `onContextUsage` folds a
  * snapshot through `resolveContextUsage` with the parent window), a reset before
- * every child, and a loader whose every tick read both — in `/task-auto`'s
- * planning `runChild`, `/task-plan`'s `child`, `buildGateDeps` (an accessor box
- * handed to `makeGateChild`), and the single-task `TaskRunner`. The first three
- * are one ritual and are now this class; the fourth stays where it is (see
- * `orchestrator.ts`: its state is the whole-run `WidgetState`, shared by
- * reference with `PhaseContext` and written by the phases themselves).
+ * every child, and a loader whose every tick reads both.
+ *
+ * Three sites share that ritual and are now this class: `/task-auto`'s planning
+ * `runChild`, `buildGateDeps`, and `/task-plan` — one `new ChildStatus` each, and
+ * no others. The single-task `TaskRunner` deliberately stays where it is: its
+ * state is the whole-run `WidgetState`, shared by reference with `PhaseContext`
+ * and written by the phases themselves (see `orchestrator.ts`).
  *
  * `track` is the loader ritual: reset, raise the loader reading this status on
  * every tick, run, always stop. The status OUTLIVES a track — `buildGateDeps`
  * shares one across every gate child, and the verify gate raises its own
- * gate-wide loader over a child that renders none (`frame: null`), so both must
- * see the same object.
+ * gate-wide loader over a child that renders none (`frame: null`, reached when
+ * `deps.loader === false` in gate-child), so both must see the same object.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { ContextSnapshot } from '../shared/child-process.js';
@@ -55,12 +56,17 @@ export declare class ChildStatus {
     };
     /**
      * Run `run` under the loader: reset, raise a loader whose every tick is
-     * `frame()` plus the live line and gauge, and stop it in a `finally` — a
-     * throwing child must not leave the widget up. `frame` wins on a clash, which
-     * is how the verify gate shows its deterministic-stage label until the child
-     * has a line of its own. `frame: null` renders NO loader (the caller already
-     * has one reading this status) but still resets, so the previous child's
-     * trailer is cleared either way.
+     * `frame()` spread OVER the live line and gauge, and stop it in a `finally`.
+     * All four behaviours were run against a fake loader:
+     *   - the reset lands first, so the previous child's line never reaches the
+     *     new loader's first tick;
+     *   - `frame` wins on a clash, because it is spread last — which is how the
+     *     verify gate shows its deterministic-stage label until the child has a
+     *     line of its own;
+     *   - `frame: null` raises NO loader at all (the caller already has one
+     *     reading this status) but still resets;
+     *   - a child that THROWS still stops the loader, so a failure never leaves
+     *     the widget up.
      */
     track<T>(ctx: ExtensionCommandContext, frame: (() => AutoLoaderState) | null, run: () => Promise<T>): Promise<T>;
 }
@@ -98,6 +104,7 @@ export declare function runPlanningChild(opts: {
 }): Promise<string>;
 /**
  * Wire a `ChildStatus` as a phase child's stream callbacks — plus the window the
- * child must be TOLD, since pi's event stream never reports one (issue #16).
+ * child must be TOLD, since pi's `--mode json` stream reports token counts but no
+ * context window.
  */
 export declare function statusCallbacks(status: ChildStatus): Pick<PhaseDeps, 'onChildOutput' | 'onContextUsage' | 'contextWindow'>;