@mjasnikovs/pi-task 0.39.0 → 0.39.2

package/dist/task/child-runner.js

@@ -1,470 +1,92 @@
 /**
- * Child process runner for the pi-task orchestrator.
+ * The phase children's adapter over the one attempt loop.
  *
- * Thin wrapper layer over the unified `runChild` in `shared/child-process.ts`.
- * Provides JSON event-stream parsing, loop detection, and context-usage tracking
- * for phase-level child pi invocations.
+ * `runWorker` (workers/pi-worker-core.ts) owns every guard a model child runs
+ * under and every restart it may be granted; the `phase` row of WORKER_PROFILES
+ * says which. What is left here is what a PHASE child is that a research worker
+ * is not: it is named, its name picks its group, its failure is THROWN as a
+ * typed error the pipeline switches on, and its loop kills leave a trail in the
+ * task file. Nothing here re-decides how a child may die.
  */
-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, 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 { runWorker } from '../workers/pi-worker-core.js';
+import { classifyWorkerFailure } from '../workers/worker-failure.js';
+import { isFatalKill } from '../workers/worker-kill.js';
+import { MAX_LOOP_RESTARTS } from './loop-detector.js';
+import { 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 { childModelEndpoints, probeModelEndpoints } from '../shared/model-endpoint.js';
-import { modelSpecFromArgs } from '../config/group-models.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 { groupChildArgs, groupWindow } from '../config/group-args.js';
 import { groupForChild } from '../config/groups.js';
-// ─── Phase-child wall-clock cap ──────────────────────────────────────────────
-/**
- * Optional wall-clock bound on ONE spawn of a phase child. DEFAULT: OFF.
- *
- * 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.
- *
- * 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
- * `timeoutMs` explicitly to arm it.
- */
-export const PHASE_CHILD_TIMEOUT_MS = 0;
-/**
- * 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';
-    }
-}
-/**
- * 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.
-    // The probe now asks about this child's own endpoint rather than ORing over
-    // every provider, so it is exact — but it is still one network call at one
-    // instant, and a blip is indistinguishable from a death in a single sample.
-    // 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;
-}
+// Sentinel error thrown when the user dismisses a grill-me dialog or cancels a
+// run. Defined here (not in failure-classifier.ts) to avoid a circular dependency.
+export const USER_CANCELLED = '__user_cancelled__';
 /**
- * The dead-backend probe killed a phase child on its LAST attempt.
+ * ONE error class for every way a phase child fails, carrying the cause as data.
  *
- * Reaching this means every attempt found no endpoint answering, not one. The
- * single-probe verdict is not trusted on its own, because one sample cannot tell
- * a dead server from a blip. Three failed probes cost ~15s; one wrong verdict
- * costs the run.
+ * Six classes plus a string sentinel used to say the same nine things, and
+ * `classifyFailure` rebuilt the ladder by `instanceof` and then fell through
+ * to sniffing the message — the tell that the vocabulary was leaking. A catch
+ * site asks `isFatalChildCause`; the notice switches on `failure.kind`.
  */
-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';
+export class ChildFailureError extends Error {
+    phase;
+    failure;
+    stderr;
+    constructor(phase, failure, stderr = '') {
+        super(describeChildFailure(phase, failure, stderr));
+        this.phase = phase;
+        this.failure = failure;
+        this.stderr = stderr;
+        this.name = 'ChildFailureError';
     }
 }
-/**
- * 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';
+function describeChildFailure(phase, f, stderr) {
+    switch (f.kind) {
+        case 'stalled':
+            return (`${phase} child killed: no output for the stall window and the model `
+                + `endpoint did not answer a probe`);
+        case 'command-timeout':
+            return (`${phase} child ran \`${f.toolName}\``
+                + `${f.detail ? ` (${f.detail})` : ''} past its `
+                + `${Math.round(f.timeoutMs / 1000)}s ceiling on every attempt`);
+        case 'stream-stall':
+            return `${phase} child: model error — ${streamStallCause(f.idleMs)}`;
+        case 'worker-timeout':
+            return (`${phase} child ran out of time on every attempt — it never stopped `
+                + `working long enough to answer`);
+        case 'loop':
+            return `loop detected ${f.strikes} times in ${phase}`;
+        case 'leaked-tool-call':
+            return (`${phase} child wrote a tool call as text instead of invoking it `
+                + `(${f.text.trim()}) — it never ran`);
+        case 'aborted':
+            return `${phase} child aborted`;
+        case 'exit':
+            // The exit code is the only signal when stderr is empty, and pi exits
+            // silently on several paths (143 = SIGTERM, 137 = SIGKILL/OOM).
+            return `${phase} child failed: ${stderr || `no stderr, exit ${f.code}`}`;
+        case 'model-error':
+            return `${phase} child: model error — ${f.cause}`;
+        case 'empty-answer':
+            return `${phase} child produced no output${stderr ? ' — stderr: ' + stderr : ''}`;
     }
 }
 /**
  * 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.
+ * catches are for. A dead backend and a user cancel 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 server, or turns an ESC into
+ * silent progress. Which kills are fatal is the roster's column, not a list here.
  */
 export function isFatalChildCause(e) {
-    if (e instanceof BackendDownError)
-        return true;
+    if (e instanceof ChildFailureError)
+        return isFatalKill(e.failure.kind);
     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
- * endpoint, not a repeatable mistake. On a local single-slot server (e.g.
- * llama-server with `--parallel 1`) pi-task's own concurrent fan-out can briefly
- * saturate the slot, and one request fails to connect even though the model is
- * up and the next request succeeds. pi already retries internally, but those
- * retries don't always absorb it on a saturated local server — and pi-task's
- * fail-fast then kills the whole task (and, under /task-auto, the whole run) for
- * a single blip. We retry these within the existing strike/leak budget.
- *
- * A NON-connection model error (bad request, context-length overflow, auth,
- * 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.
- */
-/**
- * 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) {
-    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. */
-export function connectionRetryBackoffMs(attempt) {
-    return 500 * 2 ** attempt;
-}
-const defaultSleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-// ─── Spawn helpers ───────────────────────────────────────────────────────────
-export function childArgs(tools, extensions = [], 
-/**
- * This child's group fragment: `--model` then `--thinking`, either half
- * possibly absent. Resolved by the CALLER, never here — both are properties
- * of the child's ROLE, and this function is handed tools and extensions, not
- * a name. Omitted ⇒ byte-identical argv to the version before group profiles.
- *
- * ONE field rather than a `model` beside a `thinking`, because nothing may
- * compose the two halves by hand: `groupChildArgs` is the only producer, so a
- * doubled `--thinking` is unreachable rather than merely unlikely.
- */
-groupArgs = []) {
-    // `--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". 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
-    // phases like critique-triage that should reason only over the text we
-    // 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 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
-    // one — the guards all hang off pi's `tool_call` hook.
-    const toolFlags = tools === '' ? ['--no-tools'] : ['--tools', tools];
-    const internal = tools === '' ? [] : extensions;
-    return [...childBaseArgs(internal), ...groupArgs, '--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.
-export const USER_CANCELLED = '__user_cancelled__';
-/**
- * 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, groupArgs, commandCeilingMs }) {
-    const invocation = getPiInvocation(childArgs(tools, extensions, groupArgs), prompt);
-    let loopHit;
-    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(childModelEndpoints(modelSpecFromArgs(groupArgs ?? []))))
-                    }
-                }),
-            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
-            }
-        });
-    }
-    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
-    // fails with the unhelpful "X child produced no output" — the raw
-    // stdout/stderr that might contain the real error is discarded.
-    const text = result.text || result.stdout.trim();
-    // The stream watchdog's kill leaves no provider error to report (that is the
-    // whole failure mode), so name it here rather than letting it surface as the
-    // meaningless "produced no output". Never overwrite a real reported cause.
-    const modelError = result.modelError
-        ?? (result.streamStalled ? streamStallCause(result.streamStalled.idleMs) : undefined);
-    return {
-        text,
-        // 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
-        // when the run otherwise succeeded — a loop kill truncates text mid-stream.
-        leakedToolCall: loopHit ? undefined : (detectLeakedToolCall(text) ?? undefined)
-    };
-}
-/**
- * The error-triage ladder both phase wrappers run over a finished child, in
- * this fixed order: non-zero exit → model error → empty completion → leaked
- * tool call. Callers own the loop, the prompt and the hint; this owns the
- * 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 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
- * between the two loops this collapsed, and the only way to tell from a debug
- * log which phase produced a line — so it is passed in rather than hardcoded.
- *
- * A loop kill (`r.loopHit`) is NOT handled here: the caller detects loops and
- * must consume the hit before calling this.
- */
-async function triageChildResult(deps, name, r, attempt, budget, verb) {
-    if (r.exitCode !== 0) {
-        // 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"
-        // turn). A connection-class cause is transient — re-spawn within the
-        // caller's budget after a backoff; anything else fails fast (pi already
-        // retried, and re-spawning won't fix a real fault).
-        if (isConnectionError(r.modelError) && attempt < budget) {
-            deps.logDebug?.(`${name}: connection error "${r.modelError}" — ${verb} `
-                + `${attempt + 1}/${budget}`);
-            await (deps.sleepFor ?? defaultSleep)(connectionRetryBackoffMs(attempt));
-            return { done: false };
-        }
-        throw new ModelError(name, r.modelError);
-    }
-    if (r.text.trim().length === 0) {
-        // An empty completion (exit 0, no assistant text, no stderr) is almost
-        // always transient — a model/API error swallowed inside --mode json,
-        // not a repeatable mistake — so re-spawn rather than fail the phase.
-        // There's nothing to correct, so we carry no hint (and leave any hint
-        // the caller already has alone). Shares the caller's budget: budget+1
-        // attempts, then surface the error.
-        if (attempt === budget) {
-            throw new Error(`${name} child produced no output${r.stderr ? ' — stderr: ' + r.stderr : ''}`);
-        }
-        return { done: false };
-    }
-    if (r.leakedToolCall) {
-        if (attempt === budget) {
-            throw new LeakedToolCallError(name, r.leakedToolCall);
-        }
-        return { done: false, hint: leakedToolCallHint(r.leakedToolCall) };
-    }
-    return { done: true, text: r.text };
-}
-/**
- * Run a child pi and return its assistant text. Throws if exit code != 0.
- *
- * If the child leaks a tool call as plain text (wrong dialect — never executed),
- * re-prompt with a correction hint up to MAX_LEAK_RETRIES times; if it keeps
- * 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.
- *
- * 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 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 — 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: 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.
- */
+// ─── The adapter ─────────────────────────────────────────────────────────────
 /**
  * The group fragment for a named child, or `[]` when the name is unmapped.
  *
@@ -478,15 +100,6 @@ export function groupArgsForChild(name) {
     const group = groupForChild(name);
     return group ? groupChildArgs(group) : [];
 }
-/**
- * What a PHASE child's invocation carries, said once.
- *
- * Both callers of `runChild` in this file are phase children — the strike
- * attempts and the no-tools degrade that rescues them — and everything they
- * disagree about is in `over`. Anything not there is the same by construction,
- * which is what the degrade's own comment ("the degrade changes the TOOLS, not
- * the role") claimed while three bare `undefined`s quietly made it false.
- */
 /**
  * The context window a child of this group runs against.
  *
@@ -497,175 +110,119 @@ export function groupArgsForChild(name) {
 function childContextWindow(deps, group) {
     return (group === undefined ? undefined : groupWindow(group)) ?? deps.contextWindow;
 }
-function phaseChildRun(deps, 
-/** This child's group, for the window. Undefined ⇒ the run's own window. */
-group, over) {
-    return {
-        cwd: deps.cwd,
-        onLine: deps.onChildOutput,
-        onContextUsage: deps.onContextUsage,
-        spawn: deps.spawn,
-        extensions: deps.childExtensions,
-        // The GROUP's window when this session resolved one, else the run's.
-        // Too small a window makes the churn rule fire early and kill a healthy
-        // child, so an unresolved group keeps the parent's number.
-        contextWindow: (group === undefined ? undefined : groupWindow(group)) ?? deps.contextWindow,
-        ...over
-    };
-}
 export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
     if (deps.runChild)
         return await deps.runChild(name, tools, prompt);
-    // Resolved ONCE per call, not per attempt: a /task-config change landing
-    // between a loop-kill and its retry would otherwise make the two attempts
-    // different experiments, and the retry exists to repeat the first one with a
-    // hint. An unmapped name inherits, which is today's argv — the build-time
-    // guard for that is config/groups.test.ts, not a throw in a user's run.
-    const groupArgs = groupArgsForChild(name);
-    const group = groupForChild(name);
+    if (deps.signal.aborted)
+        throw new Error(USER_CANCELLED);
     const verb = opts.verb ?? 'retry';
-    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 = 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.
-        //
-        // The SAME number the child is handed below. Arming it from the run's
-        // window while the child runs on a bigger model's would judge the child
-        // against a window it does not have, for exactly the stretch before the
-        // first `context_usage` event corrects it — which is the stretch this
-        // line exists to cover.
-        stall?.noteContext(childContextWindow(deps, group) ?? 0);
-        const clock = phaseTimeout(deps.signal, budgetMs);
-        let r;
-        try {
-            r = await runChild(phaseChildRun(deps, group, {
-                tools,
-                prompt: prependHint(hint, prompt),
-                signal: clock.signal,
-                groupArgs,
-                onContextUsage: snapshot => {
-                    // 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);
-                },
-                commandCeilingMs: commandCeilingForAttempt(phasePolicy().guards['command-timeout'], hangKills),
-                onToolCall: call => detector?.record(call) ?? stall?.record(call) ?? null,
-                onToolResult: (text, isError) => stall?.noteResult(text, isError)
-            }));
-        }
-        finally {
-            clock.cleanup();
-        }
-        // A user cancel must not be mistaken for any of the guards.
-        if (deps.signal.aborted)
-            throw new Error(USER_CANCELLED);
-        if (r.loopHit) {
-            const isLastStrike = attempt === MAX_LEAK_RETRIES;
-            loopHistory.push(r.loopHit);
-            await appendLoopEvent(deps.cwd, deps.taskId, name, r.loopHit, attempt + 1, isLastStrike ?
-                opts.degradeOnExhaustion ?
-                    'degraded — no-tools final attempt'
-                    : 'phase failed'
-                : 'restarted with hint');
-            if (isLastStrike) {
-                if (opts.degradeOnExhaustion) {
-                    return await runDegradedFinalAttempt(deps, name, prompt, r.loopHit, loopHistory);
-                }
-                throw new LoopExhaustedError(name, loopHistory);
-            }
-            deps.logDebug?.(r.loopHit.stall ?
-                `${name}: stalled (${r.loopHit.stall}) on ${r.loopHit.call.name} — `
-                    + `${verb} ${attempt + 1}/${MAX_LEAK_RETRIES}`
-                : `${name}: looped on ${r.loopHit.call.name} — ${verb} ${attempt + 1}/${MAX_LEAK_RETRIES}`);
-            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);
-            }
-            deps.logDebug?.(`${name}: exceeded its ${Math.round(budgetMs / 1000)}s budget — `
-                + `${verb} ${attempt + 1}/${MAX_LEAK_RETRIES}`);
-            hint = PHASE_TIMEOUT_HINT;
-            continue;
+    const cfg = getConfig();
+    // Leak retries draw on their own budget, so `r.attempt` (one counter across
+    // every reason) would print 3/2 on a leak after two loop kills.
+    const spent = { leak: 0, shared: 0 };
+    const result = await runWorker({
+        prompt,
+        cwd: deps.cwd,
+        signal: deps.signal,
+        spawn: deps.spawn,
+        tools,
+        extensions: deps.childExtensions,
+        onLine: deps.onChildOutput,
+        onContextUsage: deps.onContextUsage,
+        contextWindow: childContextWindow(deps, groupForChild(name)) ?? 'unknown',
+        profile: 'phase',
+        policyInputs: {
+            commandTimeoutMs: cfg.requestTimeoutMs,
+            streamInactivityMs: cfg.streamInactivityMs,
+            timeoutMs: deps.timeoutMs
+        },
+        sleepFor: deps.sleepFor,
+        // Resolved ONCE per call, not per attempt: a /task-config change landing
+        // between a loop-kill and its retry would otherwise make the two attempts
+        // different experiments, and the retry exists to repeat the first one.
+        groupArgs: groupArgsForChild(name),
+        // The degrade changes the TOOLS, not the role: it runs on the same model
+        // at the same level as the attempts it rescues, or it is a different
+        // experiment from the thing it stands in for.
+        rescue: opts.degradeOnExhaustion ? { tools: '', hint: formatDegradeHint } : undefined,
+        onRestart: r => {
+            deps.logDebug?.(r.rescue ?
+                `${name}: loop budget exhausted — degrading to a no-tools final attempt`
+                : `${name}: ${describeRestart(r)} — ${verb} ${describeBudget(r, spent)}`);
         }
-        const step = await triageChildResult(deps, name, r, attempt, MAX_LEAK_RETRIES, verb);
-        if (step.done)
-            return step.text;
-        if (step.hint !== undefined)
-            hint = step.hint;
+    });
+    await appendLoopEvents(deps.cwd, deps.taskId, name, result);
+    // A user cancel must not be mistaken for any of the guards.
+    if (deps.signal.aborted)
+        throw new Error(USER_CANCELLED);
+    const failure = phaseFailure(result);
+    if (failure)
+        throw new ChildFailureError(name, failure, result.stderr);
+    return result.text;
+}
+/** `n/budget` for the budget this restart spent, counted by the caller. */
+function describeBudget(r, spent) {
+    if (r.reason === 'leaked-tool-call')
+        return `${++spent.leak}/${MAX_LEAK_RETRIES}`;
+    return `${++spent.shared}/${MAX_LOOP_RESTARTS}`;
+}
+/** The debug-log line for one discarded attempt. */
+function describeRestart(r) {
+    switch (r.reason) {
+        case 'loop':
+            return r.loopHit?.stall ?
+                `stalled (${r.loopHit.stall}) on ${r.loopHit.call.name}`
+                : `looped on ${r.loopHit?.call.name ?? r.detail}`;
+        case 'command-timeout':
+            return `${r.detail} outran its ceiling`;
+        case 'stream-stall':
+            return `model stream inactivity (${r.detail})`;
+        case 'stalled':
+            return r.detail ?? 'stalled';
+        case 'worker-timeout':
+            return `exceeded its budget (${r.detail})`;
+        case 'connection-error':
+            return `connection error "${r.detail}"`;
+        case 'leaked-tool-call':
+            return 'wrote a tool call as text';
+        case 'empty-answer':
+            return 'empty completion';
     }
-    // Unreachable: the loop returns clean text or throws on the final leak.
-    throw new LeakedToolCallError(name, '(unknown)');
 }
-export function formatLoopHint(hit) {
-    const argsStr = JSON.stringify(hit.call.args);
-    return (`[SYSTEM NOTE: Your prior attempt called ${hit.call.name}(${argsStr}) `
-        + `${hit.count} times in the last ${hit.windowSize} tool calls — you appeared to be `
-        + `stuck in a loop. Avoid repeating that exact call; if you've already seen its result, `
-        + `work from memory or pick a different angle.]`);
+/**
+ * What the pipeline is told about a finished phase child, or `undefined` for an
+ * answer.
+ *
+ * The roster's kills come first, through the one ladder every consumer uses.
+ * Then the two consumer-policy outcomes: a rescue that produced nothing is
+ * reported as the loop it stood in for — a wall-clock or watchdog kill on the
+ * rescue is still that kill, but "the no-tools attempt said nothing" is not a
+ * new fact about the child, it is the loop budget being spent.
+ */
+function phaseFailure(r) {
+    // Strikes the BUDGET saw. The rescue is outside it: a no-tools child cannot
+    // loop, and one that somehow did is still the budget's exhaustion, not a
+    // fourth strike.
+    const loopStrikes = r.restarts.filter(x => x.reason === 'loop').length + (r.loopHit && !r.rescued ? 1 : 0);
+    const kill = classifyWorkerFailure(r);
+    if (kill)
+        return kill.kind === 'loop' ? { ...kill, strikes: loopStrikes } : kill;
+    const answered = r.modelError === undefined && r.text.trim().length > 0;
+    if (answered)
+        return undefined;
+    if (r.rescued) {
+        const hit = r.restarts.findLast(x => x.loopHit !== undefined)?.loopHit;
+        if (hit)
+            return { kind: 'loop', hit, strikes: loopStrikes };
+    }
+    if (r.modelError !== undefined)
+        return { kind: 'model-error', cause: r.modelError };
+    return { kind: 'empty-answer' };
 }
 /**
  * Terminal hint for the degrade attempt: the model has thrashed through the whole
  * strike budget re-reading files without converging, so we strip its tools and
- * order it to emit the deliverable NOW from what it already has. Used only by
- * read-only analysis phases (refine) whose output is a text rewrite that never
- * strictly required a successful read — far better to ship a best-effort spec
- * than to hard-fail the whole /task-auto run. See countRevisits / LoopExhausted.
+ * order it to emit the deliverable NOW from what it already has.
  */
 export function formatDegradeHint(hit) {
     return (`[SYSTEM NOTE: You called ${hit.call.name}(${JSON.stringify(hit.call.args)}) `
@@ -679,77 +236,34 @@ export function prependHint(hint, prompt) {
     return hint === null ? prompt : `${hint}\n\n${prompt}`;
 }
 /**
- * Append one line to the task file's `loop events` section.
+ * Append one line per loop kill 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 not every caller owns a task file on disk (a scripted harness, a
- * bare unit deps bag). A trail
+ * Best-effort by contract: it runs for EVERY phase child, 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.
+ * already reported through the debug log and the thrown error.
  */
-async function appendLoopEvent(cwd, taskId, phase, hit, strike, outcome) {
-    const ts = new Date().toISOString();
-    const argsStr = JSON.stringify(hit.call.args);
-    const line = `- ${ts}  ${phase}  strike ${strike}/${MAX_LOOP_RESTARTS + 1}  `
-        + `${hit.call.name}(${argsStr}) ×${hit.count} in last ${hit.windowSize} calls  → ${outcome}`;
+async function appendLoopEvents(cwd, taskId, phase, r) {
+    const line = (hit, strike, outcome) => `- ${new Date().toISOString()}  ${phase}  strike ${strike}/${MAX_LOOP_RESTARTS + 1}  `
+        + `${hit.call.name}(${JSON.stringify(hit.call.args)}) ×${hit.count} in last `
+        + `${hit.windowSize} calls  → ${outcome}`;
+    const lines = r.restarts.flatMap(x => x.loopHit ?
+        [
+            line(x.loopHit, x.attempt, x.rescue ? 'degraded — no-tools final attempt' : 'restarted with hint')
+        ]
+        : []);
+    if (r.loopHit)
+        lines.push(line(r.loopHit, r.attempts, 'phase failed'));
+    if (lines.length === 0)
+        return;
     try {
         const existing = (await readSection(cwd, taskId, 'loop events')) ?? '';
-        const next = existing ? `${existing}\n${line}` : line;
-        await setTaskSection(cwd, taskId, 'loop events', next);
+        await setTaskSection(cwd, taskId, 'loop events', [existing, ...lines].filter(Boolean).join('\n'));
     }
     catch {
         /* best-effort: a trail is never worth failing a phase for */
     }
 }
-/**
- * Final degrade attempt after the loop budget is spent: re-spawn the child with
- * NO tools and a terminal hint, so a model that thrashed re-reading files is
- * forced to emit its deliverable from what it already has. With no tools there
- * are no tool calls, so no loop can recur — the only failure modes left are a
- * dead turn (non-zero exit, model error) or empty output, any of which fall back
- * to the original LoopExhaustedError so the phase still fails honestly when even
- * the degrade produces nothing.
- */
-async function runDegradedFinalAttempt(deps, name, prompt, hit, loopHistory) {
-    deps.logDebug?.(`${name}: loop budget exhausted — degrading to a no-tools final attempt`);
-    // 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 {
-        r = await runChild(phaseChildRun(deps, groupForChild(name), {
-            tools: '', // --no-tools: the model cannot read/grep/list, only answer
-            prompt: prependHint(formatDegradeHint(hit), prompt),
-            signal: clock.signal,
-            // Same group as the attempts that led here. The degrade changes the
-            // TOOLS, not the role — running it on a different model, or at a
-            // different thinking level, would make the fallback a different
-            // experiment from the thing it rescues.
-            groupArgs: groupArgsForChild(name)
-        }));
-    }
-    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. 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);
-        }
-        throw new LoopExhaustedError(name, loopHistory);
-    }
-    return r.text;
-}
 /**
  * Run a child up to twice; the second attempt gets `emphasized=true` to escalate
  * the prompt. On success, return the validator's value; on two failures, throw
@@ -766,53 +280,3 @@ export async function runWithEmphasisRetry(deps, name, tools, build, validate, o
     }
     throw onFail(lastProblem);
 }
-// ─── LoopExhaustedError ──────────────────────────────────────────────────────
-export class LoopExhaustedError extends Error {
-    phase;
-    history;
-    constructor(phase, history) {
-        super(`loop detected ${history.length} times in ${phase}`);
-        this.phase = phase;
-        this.history = history;
-        this.name = 'LoopExhaustedError';
-    }
-}
-// ─── ModelError ──────────────────────────────────────────────────────────────
-/**
- * Thrown when a phase child's final turn failed with stopReason "error" — the
- * model/provider died (local model disconnect, fetch failed, socket hang up,
- * provider 5xx) after pi exhausted its own internal retries. pi reports this as
- * an agent_end with empty assistant text, which would otherwise surface as the
- * misleading "produced no output"; this names the real cause instead.
- *
- * Fail-fast: not retried at the pi-task layer. pi already retried the retryable
- * cases; re-spawning a fresh child against the same dead endpoint only burns
- * time and buries the real error. Restart the model/provider, then resume.
- */
-export class ModelError extends Error {
-    phase;
-    cause;
-    constructor(phase, cause) {
-        super(`${phase} child: model error — ${cause}`);
-        this.phase = phase;
-        this.cause = cause;
-        this.name = 'ModelError';
-    }
-}
-// ─── LeakedToolCallError ─────────────────────────────────────────────────────
-/**
- * Thrown when a phase child repeatedly wrote a tool call as plain text (a markup
- * dialect pi's harness didn't parse) instead of invoking it. The call never ran,
- * so the phase output is untrustworthy — fail loudly rather than check it off.
- */
-export class LeakedToolCallError extends Error {
-    phase;
-    marker;
-    constructor(phase, marker) {
-        super(`${phase} child wrote a tool call as text instead of invoking it `
-            + `(${marker.trim()}) — it never ran`);
-        this.phase = phase;
-        this.marker = marker;
-        this.name = 'LeakedToolCallError';
-    }
-}