@mjasnikovs/pi-task 0.38.10 → 0.38.12

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

@@ -11,26 +11,30 @@ 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.
+ * Optional wall-clock bound on ONE spawn of a phase child. DEFAULT: OFF.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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 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 declare const PHASE_CHILD_TIMEOUT_MS = 600000;
+export declare 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
@@ -67,7 +71,13 @@ export declare const USER_CANCELLED = "__user_cancelled__";
  */
 export declare function runChild(cwd: string, tools: string, prompt: string, signal: AbortSignal, onLine?: (line: string) => void, onContextUsage?: (snapshot: ContextSnapshot) => void, onToolCall?: (call: ToolCall) => LoopHit | null, spawnFn?: SpawnFn, 
 /** Internal `-e` extension paths for in-run guards (see childArgs). */
-extensions?: readonly string[]): Promise<PhaseRunResult>;
+extensions?: readonly string[], 
+/**
+ * Every finished tool call's result text. The StallDetector's churn rule
+ * needs the size of what actually entered the child's context, which the
+ * CALL alone does not carry (task/stall-detector.ts).
+ */
+onToolResult?: (text: string, isError: boolean) => void): Promise<PhaseRunResult>;
 interface PhaseDeps {
     cwd: string;
     taskId: string;
@@ -112,6 +122,23 @@ interface PhaseDeps {
     /** Injectable delay for connection-error backoff; defaults to a real timer.
      *  Tests override it with a no-op so retries don't actually sleep. */
     sleepFor?: (ms: number) => Promise<void>;
+    /**
+     * Run ONE named Child pi and return its assistant text — the seam every phase
+     * child goes through. Absent (production) → the real wrappers run, with the
+     * loop detector, the wall-clock budget and the Error-triage ladder. Present →
+     * the substitute answers directly and NONE of those guards run.
+     *
+     * The child's NAME is the first parameter because the name is what a caller
+     * branches on and what a test wants to assert. It used to be discarded before
+     * reaching the only injectable boundary (`spawn`), so a phase test had to
+     * reconstruct it by matching prompt PROSE against prompts.ts — which made
+     * prompt copy load-bearing test infrastructure in a codebase whose practice is
+     * rewording prompts and A/B-ing them.
+     *
+     * `spawn` stays: the ladder's OWN tests must drive a real process to exercise
+     * the rungs. This seam is for callers to whom the child is a premise.
+     */
+    runChild?: (name: string, tools: string, prompt: string) => Promise<string>;
 }
 export type { PhaseDeps };
 /**
@@ -123,16 +150,20 @@ export type { PhaseDeps };
  * 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
+ * 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 neither:
+ * contract-extract) and until mx5-n 2026-08-14 it had none:
  *   • 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.
+ *   • 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
+ *     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.
+ * 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.
  */
 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

@@ -10,6 +10,7 @@ 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 { 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';
@@ -23,26 +24,30 @@ export const MAX_LOOP_RESTARTS = 2; // 3 strikes total (initial attempt + 2 rest
 // 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.
+ * Optional wall-clock bound on ONE spawn of a phase child. DEFAULT: OFF.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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 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 = 600_000;
+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
@@ -161,7 +166,13 @@ export const USER_CANCELLED = '__user_cancelled__';
  */
 export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawnFn, 
 /** Internal `-e` extension paths for in-run guards (see childArgs). */
-extensions) {
+extensions, 
+/**
+ * Every finished tool call's result text. The StallDetector's churn rule
+ * needs the size of what actually entered the child's context, which the
+ * CALL alone does not carry (task/stall-detector.ts).
+ */
+onToolResult) {
     const invocation = getPiInvocation(childArgs(tools, extensions), prompt);
     let loopHit;
     const result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, signal, {
@@ -173,6 +184,7 @@ extensions) {
         streamInactivityMs: getConfig().streamInactivityMs,
         onLine,
         onContextUsage,
+        onToolResult: onToolResult ? r => onToolResult(r.text, r.isError) : undefined,
         onToolCall: call => {
             if (!onToolCall)
                 return null;
@@ -276,40 +288,53 @@ async function triageChildResult(deps, name, r, attempt, budget, verb) {
  * 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
+ * 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 neither:
+ * contract-extract) and until mx5-n 2026-08-14 it had none:
  *   • 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.
+ *   • 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
+ *     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.
+ * 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.
  */
 export async function runPhaseChild(deps, name, tools, prompt) {
+    if (deps.runChild)
+        return await deps.runChild(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 detector = new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD);
+        const stall = new StallDetector();
         const clock = phaseTimeout(deps.signal, budgetMs);
         let r;
         try {
-            r = await runChild(deps.cwd, tools, prependHint(hint, prompt), clock.signal, deps.onChildOutput, deps.onContextUsage, call => detector.record(call), deps.spawn, deps.childExtensions);
+            r = await runChild(deps.cwd, tools, prependHint(hint, prompt), clock.signal, deps.onChildOutput, snapshot => {
+                stall.noteContext(snapshot.contextWindow);
+                deps.onContextUsage?.(snapshot);
+            }, call => detector.record(call) ?? stall.record(call), deps.spawn, deps.childExtensions, (text, isError) => stall.noteResult(text, isError));
         }
         finally {
             clock.cleanup();
         }
-        // A user cancel must not be mistaken for either guard.
+        // A user cancel must not be mistaken for any of the guards.
         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);
+            deps.logDebug?.(r.loopHit.stall ?
+                `${name}: stalled (${r.loopHit.stall}) on ${r.loopHit.call.name} — `
+                    + `retry ${attempt + 1}/${MAX_LEAK_RETRIES}`
+                : `${name}: looped on ${r.loopHit.call.name} — retry ${attempt + 1}/${MAX_LEAK_RETRIES}`);
+            hint = r.loopHit.stall ? formatStallHint(r.loopHit.stall) : formatLoopHint(r.loopHit);
             continue;
         }
         if (clock.timedOut()) {
@@ -366,6 +391,10 @@ async function appendLoopEvent(cwd, taskId, phase, hit, strike, outcome) {
     await setTaskSection(cwd, taskId, 'loop events', next);
 }
 export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt, opts = {}) {
+    // The substitute stands in for the whole guarded run, so it is handed the
+    // prompt the first strike would have used (no loop hint in flight yet).
+    if (deps.runChild)
+        return await deps.runChild(name, tools, buildPrompt(null));
     const loopHistory = [];
     // Carries the correction hint (loop OR leaked-tool-call) into the next strike.
     let nextHint = null;
@@ -373,8 +402,12 @@ export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt, opts
         if (deps.signal.aborted)
             throw new Error(USER_CANCELLED);
         const detector = new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD);
+        const stall = new StallDetector();
         const prompt = buildPrompt(nextHint);
-        const r = await runChild(deps.cwd, tools, prompt, deps.signal, deps.onChildOutput, deps.onContextUsage, call => detector.record(call), deps.spawn);
+        const r = await runChild(deps.cwd, tools, prompt, deps.signal, deps.onChildOutput, snapshot => {
+            stall.noteContext(snapshot.contextWindow);
+            deps.onContextUsage?.(snapshot);
+        }, call => detector.record(call) ?? stall.record(call), deps.spawn, undefined, (text, isError) => stall.noteResult(text, isError));
         if (deps.signal.aborted)
             throw new Error(USER_CANCELLED);
         if (r.loopHit) {
@@ -388,7 +421,8 @@ export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt, opts
                 }
                 throw new LoopExhaustedError(name, loopHistory);
             }
-            nextHint = formatLoopHint(r.loopHit);
+            nextHint =
+                r.loopHit.stall ? formatStallHint(r.loopHit.stall) : formatLoopHint(r.loopHit);
             continue;
         }
         // Everything past the loop kill is the shared ladder: exit code, model

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

@@ -0,0 +1,95 @@
+/**
+ * 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;`
+ * 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).
+ *
+ * `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.
+ */
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type { ContextSnapshot } from '../shared/child-process.js';
+import { type PhaseDeps } from './child-runner.js';
+import { type AutoLoaderState } from './widget.js';
+export interface ChildStatusDeps {
+    /** The parent session's window — the last fallback for the context gauge. */
+    parentContextWindow: number;
+    /** Raise a loader. Defaults to the real `startAutoLoader`; a test injects a fake. */
+    startLoader?: (ctx: ExtensionCommandContext, getState: () => AutoLoaderState | null) => () => void;
+}
+export declare class ChildStatus {
+    private _lastLine;
+    private _contextUsage;
+    private readonly _parentContextWindow;
+    private readonly _startLoader;
+    constructor(deps: ChildStatusDeps);
+    /** The child's latest stream line. Bind as `onChildOutput` / `onLine`. */
+    onLine(line: string): void;
+    /**
+     * Fold a raw context_usage snapshot into the gauge: the child's own window,
+     * else the last known one, else the parent's (`resolveContextUsage`).
+     */
+    onContextUsage(snapshot: ContextSnapshot): void;
+    /** Forget the previous child, so its trailer never sits under the next one's block. */
+    reset(): void;
+    /** The two live fields, as a loader frame reads them. */
+    snapshot(): {
+        lastLine?: string;
+        contextUsage?: ContextSnapshot;
+    };
+    /**
+     * 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.
+     */
+    track<T>(ctx: ExtensionCommandContext, frame: (() => AutoLoaderState) | null, run: () => Promise<T>): Promise<T>;
+}
+/** What a planning child's loader shows: the head-line command, the title, the step. */
+export interface PlanningChildLoader {
+    /** Head-line command. Omit for the loader's default (`/task-auto`). */
+    command?: string;
+    title: string;
+    /**
+     * The step for THIS child. Read on every tick, because /task-plan renames the
+     * step while a child runs (`setStatus`), and /task-auto numbers its steps.
+     */
+    step: (name: string) => {
+        step: string;
+        stepNum: number;
+        stepTotal: number;
+    };
+}
+/**
+ * Run one planning child — a phase child (`runPhaseChild`, with its Error-triage
+ * ladder) whose only UI is the shared status loader. Both `/task-auto`'s
+ * planning `runChild` and `/task-plan`'s `child` are adapters over this: what
+ * they disagree on is the phase deps (task id, read-once extension, debug log),
+ * the tool set, and the loader's labelling — all parameters here. What
+ * `/task-plan` adds around it (the read-only tree diff) stays its own.
+ */
+export declare function runPlanningChild(opts: {
+    ctx: ExtensionCommandContext;
+    status: ChildStatus;
+    phaseDeps: PhaseDeps;
+    name: string;
+    tools: string;
+    prompt: string;
+    loader: PlanningChildLoader;
+}): Promise<string>;
+/** Wire a `ChildStatus` as a phase child's stream callbacks. */
+export declare function statusCallbacks(status: ChildStatus): Pick<PhaseDeps, 'onChildOutput' | 'onContextUsage'>;

package/dist/task/child-status.js

@@ -0,0 +1,99 @@
+/**
+ * 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;`
+ * 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).
+ *
+ * `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.
+ */
+import { runPhaseChild } from './child-runner.js';
+import { resolveContextUsage } from './context-usage.js';
+import { startAutoLoader } from './widget.js';
+export class ChildStatus {
+    _lastLine;
+    _contextUsage;
+    _parentContextWindow;
+    _startLoader;
+    constructor(deps) {
+        this._parentContextWindow = deps.parentContextWindow;
+        this._startLoader = deps.startLoader ?? startAutoLoader;
+    }
+    /** The child's latest stream line. Bind as `onChildOutput` / `onLine`. */
+    onLine(line) {
+        this._lastLine = line;
+    }
+    /**
+     * Fold a raw context_usage snapshot into the gauge: the child's own window,
+     * else the last known one, else the parent's (`resolveContextUsage`).
+     */
+    onContextUsage(snapshot) {
+        this._contextUsage = resolveContextUsage(snapshot, this._contextUsage, this._parentContextWindow);
+    }
+    /** Forget the previous child, so its trailer never sits under the next one's block. */
+    reset() {
+        this._lastLine = undefined;
+        this._contextUsage = undefined;
+    }
+    /** The two live fields, as a loader frame reads them. */
+    snapshot() {
+        return { lastLine: this._lastLine, contextUsage: this._contextUsage };
+    }
+    /**
+     * 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.
+     */
+    async track(ctx, frame, run) {
+        this.reset();
+        const stop = frame === null ?
+            () => { }
+            : this._startLoader(ctx, () => ({ ...this.snapshot(), ...frame() }));
+        try {
+            return await run();
+        }
+        finally {
+            stop();
+        }
+    }
+}
+/**
+ * Run one planning child — a phase child (`runPhaseChild`, with its Error-triage
+ * ladder) whose only UI is the shared status loader. Both `/task-auto`'s
+ * planning `runChild` and `/task-plan`'s `child` are adapters over this: what
+ * they disagree on is the phase deps (task id, read-once extension, debug log),
+ * the tool set, and the loader's labelling — all parameters here. What
+ * `/task-plan` adds around it (the read-only tree diff) stays its own.
+ */
+export async function runPlanningChild(opts) {
+    const { ctx, status, phaseDeps, name, tools, prompt, loader } = opts;
+    const startedAt = Date.now();
+    return status.track(ctx, () => ({
+        ...(loader.command === undefined ? {} : { command: loader.command }),
+        title: loader.title,
+        ...loader.step(name),
+        startedAt
+    }), () => runPhaseChild(phaseDeps, name, tools, prompt));
+}
+/** Wire a `ChildStatus` as a phase child's stream callbacks. */
+export function statusCallbacks(status) {
+    return {
+        onChildOutput: line => status.onLine(line),
+        onContextUsage: snapshot => status.onContextUsage(snapshot)
+    };
+}

package/dist/task/command-run.d.ts

@@ -102,3 +102,39 @@ export declare function outputTail(stdout: string, stderr: string, limit?: numbe
  * an environment gap (see INFRA_GAP_OUTPUT_RE). Empty for an ordinary check.
  */
 export declare function classifyCommandRun(run: CommandRun, gapPatterns?: readonly RegExp[]): CommandVerdict;
+/**
+ * How a re-run of ONE recorded VERIFY command line ended.
+ *   pass — it ran and exited 0. The ONLY outcome that may close a debt.
+ *   fail — it ran and exited non-zero for a real reason. Debt stays open.
+ *   gap  — nothing was observed: the shell/runner never spawned, 127 inside the
+ *          chain, a timeout, a missing browser, or absent external infrastructure.
+ *          INCONCLUSIVE, so the debt stays open (surface, never re-hide).
+ */
+export type VerifyRerunOutcome = {
+    outcome: 'pass';
+} | {
+    outcome: 'fail';
+    status: number;
+    tail: string;
+} | {
+    outcome: 'gap';
+    detail: string;
+};
+/**
+ * Re-run one VERIFY-block command line (nexttask 5) under the gate's existing
+ * env-gap contract, so a debt whose reason NAMES that command can be closed by the
+ * command itself rather than by a judgement about it.
+ *
+ * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: run 19's
+ * is `AGENT=1 bun test test/listings.test.ts`, and env prefixes, `&&` and redirects
+ * are all ordinary there. The leading command word is still resolved through
+ * runner-resolve so a login-shell-stripped PATH cannot make every re-run look like a
+ * gap (mx5 run 16's blindness, one level down).
+ *
+ * The asymmetry is the point: only exit 0 is conclusive. Every other ending — real
+ * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the
+ * debt exactly as open as it was.
+ */
+export declare function runVerifyCommandLine(cwd: string, line: string, timeoutMs: number, extraGapRe?: RegExp, 
+/** The spawner. Injected so a re-run's outcome can be tested without one. */
+run?: CommandRunner): VerifyRerunOutcome;

package/dist/task/command-run.js

@@ -28,7 +28,7 @@
  * had none.
  */
 import { spawnSync } from 'node:child_process';
-import { isCommandNotFound } from './runner-resolve.js';
+import { isCommandNotFound, resolveRunner, runnerEnv } from './runner-resolve.js';
 /** The real runner. */
 export const spawnCommand = spec => {
     const r = spawnSync(spec.bin, spec.args, {
@@ -136,3 +136,50 @@ export function classifyCommandRun(run, gapPatterns = []) {
         tail: outputTail(run.stdout, run.stderr)
     };
 }
+/** The command word of a shell line, past any leading `VAR=value` assignments. */
+function leadingBin(line) {
+    for (const tok of line.trim().split(/\s+/)) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tok))
+            continue;
+        return tok;
+    }
+    return null;
+}
+/**
+ * Re-run one VERIFY-block command line (nexttask 5) under the gate's existing
+ * env-gap contract, so a debt whose reason NAMES that command can be closed by the
+ * command itself rather than by a judgement about it.
+ *
+ * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: run 19's
+ * is `AGENT=1 bun test test/listings.test.ts`, and env prefixes, `&&` and redirects
+ * are all ordinary there. The leading command word is still resolved through
+ * runner-resolve so a login-shell-stripped PATH cannot make every re-run look like a
+ * gap (mx5 run 16's blindness, one level down).
+ *
+ * The asymmetry is the point: only exit 0 is conclusive. Every other ending — real
+ * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the
+ * debt exactly as open as it was.
+ */
+export function runVerifyCommandLine(cwd, line, timeoutMs, extraGapRe, 
+/** The spawner. Injected so a re-run's outcome can be tested without one. */
+run = spawnCommand) {
+    const bin = leadingBin(line);
+    const runner = bin === null ? null : resolveRunner(bin);
+    // A VERIFY line is a SHELL line, not an argv — env prefixes, `&&` and
+    // redirects are all ordinary there — so the runner spawns `sh -c`.
+    const verdict = classifyCommandRun(run({
+        cwd,
+        bin: 'sh',
+        args: ['-c', line],
+        timeoutMs,
+        env: runner ? runnerEnv(runner) : { ...process.env }
+    }), 
+    // Infrastructure counts as a gap on EVERY debt re-run, not only on
+    // request: an unreachable database cannot tell us whether the code is
+    // fixed, and the asymmetry below means an inconclusive re-run simply
+    // leaves the debt as open as it was.
+    extraGapRe ? [INFRA_GAP_OUTPUT_RE, extraGapRe] : [INFRA_GAP_OUTPUT_RE]);
+    if (verdict.outcome === 'gap')
+        return { outcome: 'gap', detail: verdict.detail };
+    return verdict;
+}

package/dist/task/command-watchdog.js

@@ -34,7 +34,7 @@ export { CommandWatchdog, commandTimeoutHint, realTimerDeps, reminderMessage, WA
 /**
  * One-shot marker: the most recent turn abort was issued BY THE WATCHDOG, not by
  * a human ESC. Both end the assistant turn with stopReason 'aborted' — the only
- * signal steerUntilDone's wasInterrupted() can read — so without this flag the
+ * signal steerUntilDone's classifyTurnEnd() can read — so without this flag the
  * steer loop can win the race against the watchdog's queued follow-up turn and
  * show a steering prompt to an empty room (wedging an unattended run).
  *

package/dist/task/context-usage.d.ts

@@ -1,7 +1,8 @@
 /**
- * Context-usage resolution — shared by the single-task widget (TaskRunner) and
- * the /task-auto planning loader (defaultDeps), which both mirror a child's
- * context_usage events into a display snapshot with identical math.
+ * Context-usage resolution — the one piece of math every child-status mirror
+ * shares. `ChildStatus` (child-status.ts) folds it into its `onContextUsage` for
+ * the planning and gate children; the single-task widget (TaskRunner) calls it
+ * directly, because its state is the whole-run `WidgetState`, not one child's.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { ContextSnapshot } from '../shared/child-process.js';

package/dist/task/context-usage.js

@@ -1,7 +1,8 @@
 /**
- * Context-usage resolution — shared by the single-task widget (TaskRunner) and
- * the /task-auto planning loader (defaultDeps), which both mirror a child's
- * context_usage events into a display snapshot with identical math.
+ * Context-usage resolution — the one piece of math every child-status mirror
+ * shares. `ChildStatus` (child-status.ts) folds it into its `onContextUsage` for
+ * the planning and gate children; the single-task widget (TaskRunner) calls it
+ * directly, because its state is the whole-run `WidgetState`, not one child's.
  */
 /** The parent session's context window, or 0 when the model doesn't expose it. */
 export function getParentContextWindow(ctx) {