@mjasnikovs/pi-task 0.38.11 → 0.38.13

package/dist/task/auto-orchestrator.js

@@ -20,16 +20,13 @@ import { drainRepairQueue, mergeRepairCandidates, planHasRepairFor, parseRepairT
 import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath, tasksDir } from './task-io.js';
 import { readTextFile } from '../shared/fs-text.js';
 import { findPhantomImports, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
-import { runPhaseChild, prependHint, USER_CANCELLED } from './child-runner.js';
+import { prependHint, USER_CANCELLED } from './child-runner.js';
 import { requestCancel, resetCancel, isCancelRequested, cancelCheckpoint } from './cancel-points.js';
-import { armCancelListener, disarmCancelListener } from './cancel-input.js';
-import { beginRun, endRun } from './mid-run-input.js';
-import { reportDroppedInput } from './dropped-input.js';
+import { withRun, announceTerminal } from './run-bracket.js';
 import { refineExistingFilesBlock, SINGLE_READ_EXTENSION_PATH } from './phases.js';
 import { SessionUI, registerBridgeCommand, publishLifecycleNotice } from '../remote/bridge.js';
-import { pushNotify } from '../remote/push.js';
-import { startAutoLoader } from './widget.js';
-import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
+import { getParentContextWindow } from './context-usage.js';
+import { ChildStatus, runPlanningChild, statusCallbacks } from './child-status.js';
 import { buildGateDeps, collectTreeChanges } from './gate-deps.js';
 import { runGatesForTask } from './task-gates.js';
 import { runFinalGateStage } from './run-final-gate.js';
@@ -1126,12 +1123,11 @@ const AUTO_PLAN_STEPS = {
 };
 const AUTO_PLAN_STEP_TOTAL = 2;
 function defaultDeps(ctx, cwd, signal, title) {
-    // Captured by the planning loader's getState so the widget mirrors the child's
-    // latest output line and context usage, exactly like the single-task phase
-    // widget. (The gate children manage their own loaders inside buildGateDeps.)
-    let lastLine;
-    let contextUsage;
+    // The planning loader mirrors the child's latest output line and context
+    // usage, exactly like the single-task phase widget. (The gate children have
+    // their own ChildStatus inside buildGateDeps.)
     const parentContextWindow = getParentContextWindow(ctx);
+    const status = new ChildStatus({ parentContextWindow });
     const phaseDeps = {
         cwd,
         taskId: '',
@@ -1143,41 +1139,31 @@ function defaultDeps(ctx, cwd, signal, title) {
         // it has already opened can only be thrash — which makes the read-once
         // block safe here in a way it is not for a phase that must explore.
         childExtensions: [SINGLE_READ_EXTENSION_PATH],
-        onChildOutput: (line) => {
-            lastLine = line;
-        },
-        onContextUsage: snapshot => {
-            contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
-        }
+        ...statusCallbacks(status)
     };
     return {
         // Planning-only seam. The shared gate surface (runTask/commit/verify/
         // enforce/recommend/revert) comes from buildGateDeps below — identical to
         // what /task builds, so both commands gate the same way.
-        runChild: async (name, tools, prompt) => {
-            // Planning children are slow LLM calls with no UI of their own; show
-            // the same status block as /task so this never goes silent until the
-            // drill dialog.
-            lastLine = undefined;
-            contextUsage = undefined;
-            const startedAt = Date.now();
-            const { step, stepNum } = AUTO_PLAN_STEPS[name] ?? { step: name, stepNum: 1 };
-            const stopLoader = startAutoLoader(ctx, () => ({
+        //
+        // Planning children are slow LLM calls with no UI of their own; the
+        // shared loader shows the same status block as /task so this never goes
+        // silent until the drill dialog.
+        runChild: (name, tools, prompt) => runPlanningChild({
+            ctx,
+            status,
+            phaseDeps,
+            name,
+            tools,
+            prompt,
+            loader: {
                 title,
-                step,
-                stepNum,
-                stepTotal: AUTO_PLAN_STEP_TOTAL,
-                startedAt,
-                lastLine,
-                contextUsage
-            }));
-            try {
-                return await runPhaseChild(phaseDeps, name, tools, prompt);
+                step: n => ({
+                    ...(AUTO_PLAN_STEPS[n] ?? { step: n, stepNum: 1 }),
+                    stepTotal: AUTO_PLAN_STEP_TOTAL
+                })
             }
-            finally {
-                stopLoader();
-            }
-        },
+        }),
         ...buildGateDeps({ signal, parentContextWindow, runTask: gateRunTask }),
         // Loop-level repo integrity + run-end gate glue (see AutoDeps docs).
         unmergedPaths: cwd2 => gitUnmergedPaths(cwd2, signal),
@@ -1213,12 +1199,7 @@ export function requestAutoCancel() {
  * runSingleTask without notifyFinish, so they stay silent).
  */
 function announceDone(ctx, msg, level) {
-    ctx.ui.notify(msg, level);
-    // ctx.ui.notify is terminal-only and pushNotify is a backgrounded-device web
-    // push — neither shows up in a remote viewer that's watching live. Mirror it
-    // into the session view too (errors become a persistent red bubble).
-    publishLifecycleNotice(msg, level);
-    void pushNotify('Task finished', msg, 'pi-end').catch(() => { });
+    announceTerminal(ctx, msg, level);
 }
 export async function runAutoLoop(ctx, cwd, id, deps) {
     resetCancel();
@@ -1461,46 +1442,45 @@ async function handleTaskAuto(args, ctx) {
         return;
     }
     autoRunning = true;
-    beginRun(); // the whole loop owns the session, not just the task inside it
-    // Take delivery of a typed /task-auto-cancel for the WHOLE run, planning
-    // included — planning is children too, so the host is not streaming and the
-    // ordinary command path cannot reach us.
-    armTerminalCancel(ctx);
+    // The whole loop owns the session, not just the task inside it — and the
+    // bracket takes delivery of a typed /task-auto-cancel for the WHOLE run,
+    // planning included: planning is children too, so the host is not streaming
+    // and the ordinary command path cannot reach us.
     try {
-        // Stamp a fresh per-run research-cache id (F10) BEFORE planning so enrichment and
-        // every task's research phase share one run's cache; disabled ⇒ clears any token a
-        // prior run left, so nothing is cached.
-        configureResearchRun(getConfig().researchCache);
-        const abort = new AbortController();
-        const deps = defaultDeps(ctx, cwd, abort.signal, deriveTitle(raw));
-        let id;
-        try {
-            id = await planAuto(ctx, cwd, raw, deps);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (msg === USER_CANCELLED) {
+        await withRun(ctx, { onCancel: terminalCancel }, async () => {
+            // Stamp a fresh per-run research-cache id (F10) BEFORE planning so enrichment and
+            // every task's research phase share one run's cache; disabled ⇒ clears any token a
+            // prior run left, so nothing is cached.
+            configureResearchRun(getConfig().researchCache);
+            const abort = new AbortController();
+            const deps = defaultDeps(ctx, cwd, abort.signal, deriveTitle(raw));
+            let id;
+            try {
+                id = await planAuto(ctx, cwd, raw, deps);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg === USER_CANCELLED) {
+                    announceDone(ctx, '/task-auto cancelled.', 'warning');
+                    return;
+                }
+                announceDone(ctx, `/task-auto planning failed: ${msg}`, 'error');
+                return;
+            }
+            if (!id)
+                return;
+            // Check for a cancel that was requested during the planning phase before the
+            // loop resets the flag.
+            if (isCancelRequested()) {
+                resetCancel();
                 announceDone(ctx, '/task-auto cancelled.', 'warning');
                 return;
             }
-            announceDone(ctx, `/task-auto planning failed: ${msg}`, 'error');
-            return;
-        }
-        if (!id)
-            return;
-        // Check for a cancel that was requested during the planning phase before the
-        // loop resets the flag.
-        if (isCancelRequested()) {
-            resetCancel();
-            announceDone(ctx, '/task-auto cancelled.', 'warning');
-            return;
-        }
-        await runAutoLoop(ctx, cwd, id, deps);
+            await runAutoLoop(ctx, cwd, id, deps);
+        });
     }
     finally {
         autoRunning = false;
-        reportDroppedInput(endRun(), ctx);
-        disarmCancelListener();
     }
 }
 async function handleTaskAutoResume(args, ctx) {
@@ -1529,28 +1509,27 @@ async function handleTaskAutoResume(args, ctx) {
     const id = candidate.id;
     await updateTaskFrontMatter(cwd, id, { state: 'in_progress' });
     autoRunning = true;
-    beginRun(); // the whole loop owns the session, not just the task inside it
-    armTerminalCancel(ctx);
+    // The whole loop owns the session, not just the task inside it.
     try {
-        // Reuse the interrupted run's research-cache id, dropping only the entries whose
-        // own package moved version (F10). mx5 run 13 resumed three times and each
-        // resume's fresh id discarded a working 201-entry cache; run 14 then showed a
-        // whole-file freshness gate can never hold on a greenfield run that installs
-        // packages as it goes, so invalidation is per entry. See resumeResearchRun.
-        const research = await resumeResearchRun(cwd, getConfig().researchCache);
-        if (research.reused) {
-            logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies), `
-                + `dropped ${research.dropped} stale`);
-        }
-        const abort = new AbortController();
-        // Resume only runs the loop (runTask); no planning children, so the loader
-        // title is unused here — pass the id for clarity if that ever changes.
-        await runAutoLoop(ctx, cwd, id, defaultDeps(ctx, cwd, abort.signal, id));
+        await withRun(ctx, { onCancel: terminalCancel }, async () => {
+            // Reuse the interrupted run's research-cache id, dropping only the entries whose
+            // own package moved version (F10). mx5 run 13 resumed three times and each
+            // resume's fresh id discarded a working 201-entry cache; run 14 then showed a
+            // whole-file freshness gate can never hold on a greenfield run that installs
+            // packages as it goes, so invalidation is per entry. See resumeResearchRun.
+            const research = await resumeResearchRun(cwd, getConfig().researchCache);
+            if (research.reused) {
+                logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies), `
+                    + `dropped ${research.dropped} stale`);
+            }
+            const abort = new AbortController();
+            // Resume only runs the loop (runTask); no planning children, so the loader
+            // title is unused here — pass the id for clarity if that ever changes.
+            await runAutoLoop(ctx, cwd, id, defaultDeps(ctx, cwd, abort.signal, id));
+        });
     }
     finally {
         autoRunning = false;
-        reportDroppedInput(endRun(), ctx);
-        disarmCancelListener();
     }
 }
 // eslint-disable-next-line @typescript-eslint/require-await
@@ -1571,24 +1550,22 @@ async function handleTaskAutoCancel(_args, ctx) {
 const CANCEL_ACK = 'Stopping /task-auto at the next safe checkpoint…';
 /**
  * Deliver a /task-auto-cancel typed in the terminal while a run owns the main
- * loop. `armCancelListener` watches raw stdin, so it works during the spec
- * phases and the gates — the windows where pi would otherwise queue the line
- * until after the run (see cancel-input.ts). The remote path is unaffected:
- * dispatchRemoteLine invokes the handler directly.
+ * loop — the run bracket's `onCancel`. The armed listener watches raw stdin, so
+ * it works during the spec phases and the gates — the windows where pi would
+ * otherwise queue the line until after the run (see cancel-input.ts). The
+ * remote path is unaffected: dispatchRemoteLine invokes the handler directly.
  */
-function armTerminalCancel(ctx) {
-    armCancelListener(ctx, live => {
-        requestAutoCancel();
-        // `live` is the ctx the listener is currently installed on — the captured
-        // one is stale the moment a task replaces the session.
-        try {
-            live.ui.notify(CANCEL_ACK, 'warning');
-        }
-        catch {
-            /* the acknowledgement must never break the cancel itself */
-        }
-        publishLifecycleNotice(CANCEL_ACK, 'warning');
-    });
+function terminalCancel(live) {
+    requestAutoCancel();
+    // `live` is the ctx the listener is currently installed on — the captured
+    // one is stale the moment a task replaces the session.
+    try {
+        live.ui.notify(CANCEL_ACK, 'warning');
+    }
+    catch {
+        /* the acknowledgement must never break the cancel itself */
+    }
+    publishLifecycleNotice(CANCEL_ACK, 'warning');
 }
 // ─── Registration ────────────────────────────────────────────────────────────
 export function registerTaskAuto(pi) {

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;
@@ -140,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,16 +288,20 @@ 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)
@@ -295,23 +311,30 @@ export async function runPhaseChild(deps, name, tools, prompt) {
     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()) {
@@ -379,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) {
@@ -394,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'>;