@mjasnikovs/pi-task 0.38.28 → 0.38.30

package/dist/task/cancel-points.js

@@ -3,24 +3,30 @@
  *
  * A cancel is a *request*, never a kill. It is honoured only where the on-disk
  * state is durable and /task-auto-resume provably continues from it. Killing a
- * child mid-phase would also stop the run (the abort signal already reaches
- * every child's process group) but throws away that phase's work and can leave
- * a half-written tree — so the flag is polled at boundaries instead.
+ * child mid-phase would also stop the run — the abort signal reaches every
+ * child's process group — but it throws away that phase's work and can leave a
+ * half-written tree, so the flag is polled at boundaries instead.
  *
- * The checkpoint set, and why each one is safe:
+ * The checkpoint set is exactly these four, one call site each:
  *
- *   loop-top       the previous task is checked off + committed and the next one
- *                  has not started. The original (and until now the ONLY) point.
- *   pre-task       after the pre-task checkpoint commit, before the runner is
- *                  constructed: tree committed, no inner id stamped yet, so the
- *                  entry is simply still unchecked and a resume restarts it.
- *   phase:<name>   inside the runner's phase loop, after setTaskSection +
- *                  postCommitPhase have persisted the phase output and
- *                  front-matter `phase` names the NEXT phase. This is exactly
- *                  the state /task-resume already resumes from (PHASE_INDEX
- *                  skip-forward), so a cancel here costs nothing.
- *   pre-final-gate every task is checked off and committed; the whole-repo gate
- *                  has not started. A resume re-enters the same branch.
+ *   loop-top       (auto-orchestrator) the previous task is checked off and
+ *                  committed and the next one has not started.
+ *   pre-task       (auto-orchestrator) after the pre-task checkpoint commit,
+ *                  before the runner is constructed: tree committed, no inner id
+ *                  stamped yet, so the entry is simply still unchecked and a
+ *                  resume restarts it.
+ *   phase:<name>   (orchestrator, inside the phase loop) after setTaskSection and
+ *                  postCommitPhase have persisted this phase's output. Front-matter
+ *                  `phase` still names the phase that JUST FINISHED, not the next
+ *                  one: `advance()` writes it at the TOP of each iteration and
+ *                  nothing moves it afterwards — postCommitPhase writes only
+ *                  `title` and `label`. Since the resume skip rule is
+ *                  `idx < resumeIdx`, a resume therefore RE-ENTERS this phase and
+ *                  runs it again. Nothing is lost, because its section is already
+ *                  on disk; the cost is repeating one phase, not zero.
+ *   pre-final-gate (run-final-gate) every task is checked off and committed; the
+ *                  whole-repo gate has not started. A resume re-enters the same
+ *                  branch.
  *
  * DELIBERATELY NOT checkpoints — stopping here is not safe:
  *   - mid implementation turn: uncommitted, half-applied edits. The user's ESC
@@ -31,7 +37,8 @@
  */
 let requested = false;
 /** Checkpoints actually reached since the last reset, in order. Instrumentation
- *  for the A/B harness and the unit tests — never read by the loop itself. */
+ *  only: `checkpointsCrossed` and `resetCheckpointTrail` have no caller anywhere
+ *  in src/ — every consumer is a test. */
 const crossed = [];
 export function requestCancel() {
     requested = true;
@@ -51,7 +58,7 @@ export function isCancelRequested() {
 export function resetCancel() {
     requested = false;
 }
-/** Drop the recorded checkpoint trail (A/B + tests). */
+/** Drop the recorded checkpoint trail. */
 export function resetCheckpointTrail() {
     crossed.length = 0;
 }
@@ -64,14 +71,15 @@ export function resetCheckpointTrail() {
  */
 export function cancelCheckpoint(where) {
     crossed.push(where);
-    // A/B ONLY (scripts/cancel-latency-ab.ts): reproduce the pre-checkpoint
-    // behaviour — the flag was observed at the loop top and nowhere else — so the
-    // two arms differ in exactly the thing under test and share every other path.
+    // CANCEL_AB_ARM=baseline collapses the checkpoint set back to loop-top alone,
+    // so the two arms differ in exactly one thing. Nothing in src/ ever sets it;
+    // the only writer in the tree is cancel-points.test.ts, which uses it to pin
+    // that the extra checkpoints — and only they — are what the flag gates.
     if (process.env.CANCEL_AB_ARM === 'baseline' && where !== 'loop-top')
         return false;
     return requested;
 }
-/** Checkpoints crossed since the last reset (A/B + tests). */
+/** Checkpoints crossed since the last reset. */
 export function checkpointsCrossed() {
     return crossed;
 }

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

@@ -18,22 +18,19 @@ export declare const MAX_LOOP_RESTARTS = 2;
 /**
  * Optional wall-clock bound on ONE spawn of a phase child. DEFAULT: OFF.
  *
- * It used to default to 600_000, sized against measured HEALTHY planning
- * children on one local 27B backend (decompose 89s, whole plan phase 321s) on
- * the reasoning that ten minutes was a 3-6x margin over honest work.
+ * WHY OFF, AND NOT A NUMBER. A wall clock on a model child measures the
+ * MODEL'S SPEED, not its health. The same planning child that answers well in
+ * seconds on one backend takes many minutes on another, or on the same backend
+ * with thinking turned on — so any cap generous enough to be safe is too loose
+ * to catch anything, and any cap tight enough to catch a runaway kills healthy
+ * work. Assume a model that emits one token per second and the number has no
+ * defensible value at all.
  *
- * That premise was measured and is false. Replaying ONE captured auto-decompose
- * request against the same backend with reasoning ON, n=10, everything else
- * byte-identical (2026-08-17): all ten answered correctly with 26-42 titles, and
- * every one took 610-927s. The cap would have killed 10 out of 10 GOOD runs and
- * then failed the phase with PhaseTimeoutError. The number was not measuring the
- * pathology, it was measuring one model's speed on one day.
- *
- * The runaway it was there to catch — a decompose child that ran 16m23s at
- * 117,370 of a 120,064-token window, forward-paging past the loop detector — is
- * now caught by StallDetector (stall-detector.ts), which bounds NON-PROGRESS and
- * CONTEXT CHURN instead of elapsed seconds. Both of those are properties of the
- * pathology, so neither has to be re-tuned for a slower model or a bigger repo.
+ * The runaway it was there to catch — a child forward-paging through its whole
+ * context window, past the loop detector, never going to return — is caught by
+ * StallDetector (stall-detector.ts) instead. That bounds NON-PROGRESS and
+ * CONTEXT CHURN, both properties of the pathology itself, so neither has to be
+ * re-tuned for a slower model or a bigger repo.
  *
  * The value and the plumbing stay for a caller that genuinely wants a hard stop
  * (tests inject a short one), but nothing sets it in production. Pass
@@ -84,13 +81,13 @@ export declare const USER_CANCELLED = "__user_cancelled__";
 /**
  * One child-pi invocation, as a value.
  *
- * WHY A RECORD. This was thirteen ordered positionals, and the thirteenth
- * carried its own DEBT note saying so. Two production callers reached it, and
- * they had already drifted: the degrade attempt wrote three bare `undefined`s to
- * reach the later slots and passed the RAW signal, so it escaped the wall clock
- * its own strike siblings run under — the same defect class this file already
- * recorded for `runAutoInstall` and for the deleted `runPhaseWithLoopGuard`.
- * Adjacent optionals of the same type can no longer swap without a type error.
+ * WHY A RECORD RATHER THAN POSITIONALS. With this many optional parameters of
+ * the same type, a caller reaching a late one must write bare `undefined`s to get
+ * there, and one that miscounts silently lands the wrong value in the wrong slot.
+ * The failure that shape produces here is a child spawned with the RAW signal
+ * instead of the wall-clocked one, escaping a guard its siblings run under, with
+ * nothing to catch it. Named fields make adjacent optionals of the same type
+ * impossible to swap without a type error.
  */
 export interface ChildRun {
     cwd: string;
@@ -111,9 +108,11 @@ export interface ChildRun {
      */
     onToolResult?: (text: string, isError: boolean) => void;
     /**
-     * The child's context window in tokens. Nothing in pi's event stream reports
-     * one (issue #16), so the parent hands its own down — children carry no `-m`
-     * and resolve the same default model. 0 / omitted = unknown, as before.
+     * The child's context window in tokens. Nothing in pi's `--mode json` stream
+     * reports one — a real capture carries token counts and a model id, but no key
+     * naming a window — so the parent hands its own down. Children carry no `-m`
+     * (CHILD_BASE_ARGS) and resolve the same default model, which is what makes
+     * the parent's window the honest value. 0 or omitted = unknown.
      */
     contextWindow?: number;
     /**
@@ -132,12 +131,12 @@ export interface PhaseDeps {
     /**
      * The parent session's context window in tokens, handed down to every child.
      *
-     * pi's `--mode json` stream reports token counts but no window (issue #16),
-     * so without this the gauge shows a bare number and — worse — the
-     * StallDetector's CONTEXT CHURN rule, which is gated on a positive window,
-     * can never fire. Children are spawned without `-m` (CHILD_BASE_ARGS) and so
-     * run the parent's own default model; its window is the honest value.
-     * Absent = unknown, and both consumers degrade exactly as they did before.
+     * pi's `--mode json` stream reports token counts but no window, so without
+     * this the gauge shows a bare number and — worse — the StallDetector's CONTEXT
+     * CHURN rule can never fire: it opens with `if (this.contextWindow <= 0)
+     * return false`. Children are spawned without `-m` (CHILD_BASE_ARGS) and so
+     * run the parent's own default model, which is what makes its window the
+     * honest value. Absent = unknown, and both consumers degrade.
      */
     contextWindow?: number;
     /**
@@ -185,11 +184,10 @@ export interface PhaseDeps {
      * 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.
+     * branches on and what a test wants to assert. Discarded before it reaches
+     * the only injectable boundary (`spawn`), a phase test has to reconstruct it
+     * by matching prompt PROSE against prompts.ts — which makes prompt copy
+     * load-bearing test infrastructure in a codebase that rewords prompts.
      *
      * `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.
@@ -232,13 +230,10 @@ export interface PhaseDeps {
  * The subset of `PhaseDeps` a CALLER may supply — every injectable seam, derived
  * by naming what the runner owns instead of by listing what it does not.
  *
- * `TaskRunnerOptions` used to declare `spawnFn`, `runChild`, `runWorker` and a
- * seven-name `Pick` called `lookups` separately; `RunSingleTaskOptions` re-picked
- * all four, `runSingleTask` re-forwarded each by name, and the constructor spread
- * them back together. Four coordinated edits, none of which failed to compile if
- * you skipped one — the exact indictment this codebase already recorded against
- * `ConfigItem`. Four seams (`timeoutMs`, `sleepFor`, `childExtensions`,
- * `logDebug`) had in fact been left behind, so a runner-driven test of the
+ * Declaring the seams separately on `TaskRunnerOptions`, re-picking them on
+ * `RunSingleTaskOptions`, re-forwarding each by name and spreading them back
+ * together is four coordinated edits, none of which fails to compile if you skip
+ * one. Seams get left behind that way, and a runner-driven test of the
  * connection-error rung really slept and the debug trail could not be asserted at
  * all. Derived by `Omit`, a NEW seam field joins this with no second edit.
  */
@@ -254,16 +249,16 @@ export type PhaseSeams = Omit<PhaseDeps, 'cwd' | 'taskId' | 'signal' | 'onChildO
  *
  * THREE RUNAWAY GUARDS ride the same budget, because this is the runner every
  * /task-auto planning child goes through (clarify, decompose, coverage,
- * contract-extract) and until mx5-n 2026-08-14 it had none:
+ * contract-extract), and an unguarded planning child can burn a whole run:
  *   • a LoopDetector, so an identical repeated tool call is killed and
  *     re-prompted instead of being allowed to fill the context window;
  *   • a StallDetector, the backstop for the varied-args thrash the loop
- *     detector's short window cannot see — the shape that actually cost us a
- *     16-minute decompose child that was never going to return. It bounds
+ *     detector's short window cannot see — a child that keeps calling tools with
+ *     different arguments, learns nothing, and is never going to return. It bounds
  *     consecutive no-new-ground calls and total context churn, NOT elapsed time;
- *   • PHASE_CHILD_TIMEOUT_MS, a hard wall clock, OFF by default because the
- *     measured healthy range (610-927s for a reasoning-on decompose) overlaps
- *     any value that would catch the pathology. See its comment.
+ *   • PHASE_CHILD_TIMEOUT_MS, a hard wall clock, OFF by default: a healthy
+ *     reasoning-on planning child and a runaway one occupy the same range of
+ *     elapsed times, so no threshold separates them. See its comment.
  * All three are checked BEFORE the triage ladder: we killed the child, so its
  * exit status describes our SIGTERM and says nothing about its verdict.
  */
@@ -292,8 +287,8 @@ export declare function prependHint(hint: string | null, prompt: string): string
 /**
  * The two things a phase child can disagree about. Everything else — the loop
  * and stall detectors, the wall clock, the loop trail, the triage ladder and its
- * budget — is the one loop's, because the two wrappers that used to differ
- * disagreed on nothing else that was ever observable.
+ * budget — is the one loop's. These two are the only differences observable from
+ * outside it.
  */
 export interface PhaseChildOptions {
     /**

package/dist/task/child-runner.js

@@ -28,22 +28,19 @@ export const MAX_LOOP_RESTARTS = 2; // 3 strikes total (initial attempt + 2 rest
 /**
  * Optional wall-clock bound on ONE spawn of a phase child. DEFAULT: OFF.
  *
- * It used to default to 600_000, sized against measured HEALTHY planning
- * children on one local 27B backend (decompose 89s, whole plan phase 321s) on
- * the reasoning that ten minutes was a 3-6x margin over honest work.
+ * WHY OFF, AND NOT A NUMBER. A wall clock on a model child measures the
+ * MODEL'S SPEED, not its health. The same planning child that answers well in
+ * seconds on one backend takes many minutes on another, or on the same backend
+ * with thinking turned on — so any cap generous enough to be safe is too loose
+ * to catch anything, and any cap tight enough to catch a runaway kills healthy
+ * work. Assume a model that emits one token per second and the number has no
+ * defensible value at all.
  *
- * That premise was measured and is false. Replaying ONE captured auto-decompose
- * request against the same backend with reasoning ON, n=10, everything else
- * byte-identical (2026-08-17): all ten answered correctly with 26-42 titles, and
- * every one took 610-927s. The cap would have killed 10 out of 10 GOOD runs and
- * then failed the phase with PhaseTimeoutError. The number was not measuring the
- * pathology, it was measuring one model's speed on one day.
- *
- * The runaway it was there to catch — a decompose child that ran 16m23s at
- * 117,370 of a 120,064-token window, forward-paging past the loop detector — is
- * now caught by StallDetector (stall-detector.ts), which bounds NON-PROGRESS and
- * CONTEXT CHURN instead of elapsed seconds. Both of those are properties of the
- * pathology, so neither has to be re-tuned for a slower model or a bigger repo.
+ * The runaway it was there to catch — a child forward-paging through its whole
+ * context window, past the loop detector, never going to return — is caught by
+ * StallDetector (stall-detector.ts) instead. That bounds NON-PROGRESS and
+ * CONTEXT CHURN, both properties of the pathology itself, so neither has to be
+ * re-tuned for a slower model or a bigger repo.
  *
  * The value and the plumbing stay for a caller that genuinely wants a hard stop
  * (tests inject a short one), but nothing sets it in production. Pass
@@ -145,8 +142,8 @@ thinking = []) {
     // `--mode json` puts the child into the structured event stream the
     // unified runner parses in `mode: 'json-events'`. Without it the child
     // emits plain text, every line fails JSON.parse, finalText stays empty,
-    // and every phase fails with "X child produced no output". Was silently
-    // dropped in the 4e34f96 split-refactor; do not remove again.
+    // and every phase fails with "X child produced no output". A refactor has
+    // dropped it once already; do not remove it again.
     //
     // An empty `tools` string means "no tools at all" — emit `--no-tools`
     // instead of `--tools ''` (which pi would reject). Used by pure-judgment
@@ -154,8 +151,9 @@ thinking = []) {
     // hand them, never spend time reading the repo.
     //
     // The prompt is NOT an argv element: it goes to the child over stdin (see
-    // runChild below / getPiInvocation), so a large inlined-design prompt can't
-    // overflow the OS command-line limit (Windows `spawn ENAMETOOLONG`).
+    // runChild below / getPiInvocation), so a large inlined-design prompt cannot
+    // exceed the OS argv ceiling — which fails the spawn outright rather than
+    // truncating (`E2BIG` on this platform).
     //
     // `extensions` are internal `-e` loads for in-run guards (the caller supplies
     // the path). A no-tools child cannot make a tool call, so it never carries
@@ -173,7 +171,7 @@ export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUs
     const result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, signal, {
         mode: 'json-events',
         // A hung model stream reports nothing at all, so without this the
-        // phase child waits forever (mx5 run 14: ~2.9h of dead air). The kill
+        // 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: getConfig().streamInactivityMs,
@@ -226,9 +224,8 @@ export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUs
  * verdict, so a fix to any rung lands in every caller at once.
  *
  * `attempt` is the caller's 0-based counter, `budget` the matching restart
- * allowance (MAX_LEAK_RETRIES, which is also MAX_LOOP_RESTARTS — the loop and
- * leak budgets were separate constants at the same value and are shared by one
- * loop now) — so a phase runs `budget + 1` attempts before a rung gives up.
+ * allowance — MAX_LEAK_RETRIES and MAX_LOOP_RESTARTS are both 2, and one loop
+ * spends the pair — so a phase runs `budget + 1` attempts before a rung gives up.
  *
  * `verb` names the restart in the debug log ("retry" by default, "restart" for
  * refine and grill-gen). It is the only externally visible thing that differed
@@ -240,7 +237,11 @@ export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUs
  */
 async function triageChildResult(deps, name, r, attempt, budget, verb) {
     if (r.exitCode !== 0) {
-        throw new Error(`${name} child failed: ${r.stderr || '(no stderr)'}`);
+        // The exit code is the only signal when stderr is empty, and pi exits
+        // silently on several paths (143 = SIGTERM/loop-kill, 137 = SIGKILL/OOM).
+        // Dropping it left "(no stderr)" as the whole diagnosis.
+        const why = r.stderr || `no stderr, exit ${r.exitCode}`;
+        throw new Error(`${name} child failed: ${why}`);
     }
     if (r.modelError) {
         // The model/provider failed (pi exited 0 with a stopReason "error"
@@ -286,16 +287,16 @@ async function triageChildResult(deps, name, r, attempt, budget, verb) {
  *
  * THREE RUNAWAY GUARDS ride the same budget, because this is the runner every
  * /task-auto planning child goes through (clarify, decompose, coverage,
- * contract-extract) and until mx5-n 2026-08-14 it had none:
+ * contract-extract), and an unguarded planning child can burn a whole run:
  *   • a LoopDetector, so an identical repeated tool call is killed and
  *     re-prompted instead of being allowed to fill the context window;
  *   • a StallDetector, the backstop for the varied-args thrash the loop
- *     detector's short window cannot see — the shape that actually cost us a
- *     16-minute decompose child that was never going to return. It bounds
+ *     detector's short window cannot see — a child that keeps calling tools with
+ *     different arguments, learns nothing, and is never going to return. It bounds
  *     consecutive no-new-ground calls and total context churn, NOT elapsed time;
- *   • PHASE_CHILD_TIMEOUT_MS, a hard wall clock, OFF by default because the
- *     measured healthy range (610-927s for a reasoning-on decompose) overlaps
- *     any value that would catch the pathology. See its comment.
+ *   • PHASE_CHILD_TIMEOUT_MS, a hard wall clock, OFF by default: a healthy
+ *     reasoning-on planning child and a runaway one occupy the same range of
+ *     elapsed times, so no threshold separates them. See its comment.
  * All three are checked BEFORE the triage ladder: we killed the child, so its
  * exit status describes our SIGTERM and says nothing about its verdict.
  */
@@ -351,10 +352,10 @@ export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
             throw new Error(USER_CANCELLED);
         const detector = new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD);
         const stall = new StallDetector();
-        // Arm the churn rule BEFORE the first tool call. The window used to reach
-        // the detector only through a context snapshot, and pi's stream never
-        // carries one, so it was always 0 and rule 2 never fired (issue #16). The
-        // parent knows the value at spawn time — say it then, not later.
+        // Arm the churn rule BEFORE the first tool call. pi's stream carries no
+        // context WINDOW, so a detector that waited to be told one would sit at 0,
+        // and the churn rule returns false on a non-positive window. The parent
+        // knows the value at spawn time — say it then, not later.
         stall.noteContext(deps.contextWindow ?? 0);
         const clock = phaseTimeout(deps.signal, budgetMs);
         let r;
@@ -365,9 +366,10 @@ export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
                 signal: clock.signal,
                 thinking,
                 onContextUsage: snapshot => {
-                    // Real window or nothing: noteContext ignores 0, and until
-                    // deps.contextWindow existed 0 was all it ever saw, which
-                    // left the churn rule permanently disarmed (issue #16).
+                    // 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);
                 },
@@ -450,8 +452,8 @@ export function prependHint(hint, prompt) {
  * Append one line to the task file's `loop events` section.
  *
  * Best-effort by contract: it runs for EVERY phase child now that there is one
- * loop, and the six sites that used to reach the un-trailed wrapper do not all
- * own a task file on disk (a scripted harness, a bare unit deps bag). A trail
+ * loop, and not every caller owns a task file on disk (a scripted harness, a
+ * bare unit deps bag). A trail
  * that cannot be written must cost the phase nothing — the loop kill itself is
  * already reported through the debug log and the thrown LoopExhaustedError.
  */
@@ -480,11 +482,9 @@ async function appendLoopEvent(cwd, taskId, phase, hit, strike, outcome) {
  */
 async function runDegradedFinalAttempt(deps, name, prompt, hit, loopHistory) {
     deps.logDebug?.(`${name}: loop budget exhausted — degrading to a no-tools final attempt`);
-    // BEHAVIOUR DELTA. This attempt now runs under the same wall clock as the
-    // strikes that led here. It used to pass `deps.signal` raw — one of the
-    // three drifts that came of reaching past bare `undefined`s to the later
-    // positionals — so the one attempt made after a loop budget was spent was
-    // also the one attempt that could hang forever.
+    // This attempt runs under the same wall clock as the strikes that led here.
+    // Passing `deps.signal` raw instead would make the one attempt taken after a
+    // loop budget is spent the one attempt that can hang forever.
     const clock = phaseTimeout(deps.signal, deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS);
     let r;
     try {
@@ -502,11 +502,10 @@ async function runDegradedFinalAttempt(deps, name, prompt, hit, loopHistory) {
         clock.cleanup();
     }
     if (r.exitCode !== 0 || r.modelError || r.text.trim().length === 0) {
-        // A wall-clock kill is NOT a loop. The clock above is new here, and
-        // without this check a degrade that outran its budget was reported as
-        // "loop budget exhausted", carrying a loop history that did not cause it
-        // — the same mislabel class the worker-kill roster exists to prevent, on
-        // the very path that clock was added to guard.
+        // A wall-clock kill is NOT a loop. Without this check a child that outran
+        // its budget is reported as "loop budget exhausted", carrying a loop
+        // history that did not cause it — the same mislabel class the worker-kill
+        // roster exists to prevent, on the very path the clock guards.
         if (clock.timedOut()) {
             throw new PhaseTimeoutError(name, deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS, 1);
         }

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

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

package/dist/task/child-status.js

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

package/dist/task/clamp-output.js

@@ -1,11 +1,18 @@
 /**
  * clamp-output — the ONE trail-side ceiling for captured tool output.
  *
- * `appendGateRecord` flattens newlines to spaces, so the gate trail stays one line
- * per entry; this caps the volume, because a wedged tool can emit megabytes.
- * Extracted from task-gates.ts so every probe that carries evidence into a failure
- * detail clamps the SAME way: a second clamp with a second ceiling is how two
- * trails start disagreeing about what was captured.
+ * `appendGateRecord` already collapses every run of whitespace-around-newline
+ * into a single space, so each trail entry is one line. What it does NOT do is
+ * bound the LENGTH, which is this. A wedged tool has no upper limit on what it
+ * prints, and the trail is a task file a human reads.
+ *
+ * Both probes that carry tool output into a failure detail — the render check and
+ * the gate's own command records — call THIS function, so the two trails cannot
+ * start disagreeing about what was captured. A second clamp with a second ceiling
+ * is exactly how that happens.
+ *
+ * At the boundary: 1200 characters pass through untouched, 1201 or more come back
+ * clamped to 1200 plus a single ellipsis.
  */
 const TRAIL_OUTPUT_MAX_CHARS = 1200;
 export function clampOutput(output) {