@mjasnikovs/pi-task 0.38.29 → 0.38.31

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

@@ -6,34 +6,30 @@
  * for phase-level child pi invocations.
  */
 import { type SpawnFn, type ContextSnapshot, type ToolCall, type LoopHit } from '../shared/child-process.js';
+import { type CommandKill } from '../shared/command-watchdog.js';
+import { type WorkerGuardPolicy } from '../workers/worker-profiles.js';
 import type { DebugLine } from './debug-log.js';
 import type { RunWorkerInput, RunWorkerResult } from '../workers/pi-worker-core.js';
 import type { docsRaw, docsFocused } from '../workers/docs-core.js';
 import type { fetchRaw, fetchFocused } from '../workers/fetch-core.js';
 import type { npmVersionLookup } from '../workers/npm-version.js';
 import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
-export declare const LOOP_WINDOW = 20;
-export declare const LOOP_THRESHOLD = 5;
-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
@@ -53,6 +49,54 @@ export declare class PhaseTimeoutError extends Error {
     readonly attempts: number;
     constructor(childName: string, budgetMs: number, attempts: number);
 }
+/**
+ * The terminal error for a guard kill, or null when the child was not killed.
+ *
+ * Both spawn paths must ask. A kill reports `exitCode: 0` (child-process.ts uses
+ * `code ?? 0`, and a signal gives null), so a path that tests the exit code
+ * instead returns the truncated text as the phase's answer.
+ */
+export declare function guardKillError(name: string, r: PhaseRunResult, opts?: {
+    finalAttempt?: boolean;
+}): Error | null;
+/**
+ * The dead-backend probe killed a phase child on its LAST attempt.
+ *
+ * Reaching this means every attempt found no endpoint answering, not one. The
+ * single-probe verdict is not trusted on its own: `discoverModelEndpoints` reads
+ * every provider in models.json rather than the one this child's model uses, so a
+ * stopped local server can condemn a run against a healthy cloud backend. Three
+ * failed probes cost ~15s; one wrong verdict costs the run.
+ */
+export declare class BackendDownError extends Error {
+    readonly childName: string;
+    constructor(childName: string);
+}
+/**
+ * A phase child spent every attempt on a command that never returned. Its own
+ * class because the fix is in the SPEC, not the model's exploration: a VERIFY
+ * block naming an unbounded `dev` command re-hangs every attempt.
+ */
+export declare class CommandTimeoutError extends Error {
+    readonly childName: string;
+    readonly kill: CommandKill;
+    constructor(childName: string, kill: CommandKill);
+}
+/**
+ * Causes a best-effort `catch` must NOT absorb.
+ *
+ * A phase child that merely answered badly should degrade — that is what those
+ * catches are for. These two are different in kind: the run is over either way,
+ * and swallowing them ships a half-built spec while every later phase dies
+ * against the same dead backend, or turns a user's ESC into silent progress.
+ * `failure-classifier.ts` has a verdict for both; a catch that eats them makes it
+ * unreachable.
+ */
+export declare function isFatalChildCause(e: unknown): boolean;
+/**
+ * Retry budget is three attempts at 500ms/1s/2s — three requests over 3.5s, which
+ * is not a storm even against a throttle. pi's own ladder is three at 2s/4s/8s.
+ */
 export declare function isConnectionError(cause: string): boolean;
 /** Exponential backoff before a connection-error retry: 500ms, 1s, 2s, …, so a
  *  brief saturation window can drain before we re-issue the request. */
@@ -66,6 +110,18 @@ export interface PhaseRunResult {
     leakedToolCall?: string;
     /** Set when the child's final turn failed with stopReason "error" (model/provider failure). */
     modelError?: string;
+    /**
+     * Set when the per-command watchdog killed the child: one tool call outran
+     * `requestTimeoutMs`. RESTARTABLE (worker-kill.ts) — a hung command is a
+     * mistake the next attempt can be told not to repeat.
+     */
+    commandKill?: CommandKill;
+    /**
+     * Set when the dead-backend probe killed the child: no output for the stall
+     * window AND the model endpoint unreachable. NOT restartable (worker-kill.ts):
+     * re-spawning against a backend that is down buys nothing.
+     */
+    stalled?: boolean;
 }
 export declare function childArgs(tools: string, extensions?: readonly string[], 
 /**
@@ -84,13 +140,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 +167,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;
     /**
@@ -121,8 +179,23 @@ export interface ChildRun {
      * group, or `[]`/omitted to inherit the session default as before.
      */
     thinking?: readonly string[];
+    /**
+     * This attempt's per-command ceiling, already halved for prior hangs by the
+     * caller's strike loop. Omitted -> the `phase` row's full configured ceiling,
+     * which is the right value for a single-attempt caller.
+     */
+    commandCeilingMs?: number;
 }
-export declare function runChild({ cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawn: spawnFn, extensions, onToolResult, contextWindow, thinking }: ChildRun): Promise<PhaseRunResult>;
+/**
+ * The `phase` row of WORKER_PROFILES, resolved with this machine's config.
+ *
+ * Read here rather than at module load so a /task-config change reaches the next
+ * child, the same contract childBaseArgs already keeps. Both spawn paths in this
+ * file go through it, so the degraded final attempt cannot drift from the ordinary
+ * one — the mislabel class runDegradedFinalAttempt's own comment warns about.
+ */
+export declare function phasePolicy(): WorkerGuardPolicy;
+export declare function runChild({ cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawn: spawnFn, extensions, onToolResult, contextWindow, thinking, commandCeilingMs }: ChildRun): Promise<PhaseRunResult>;
 export interface PhaseDeps {
     cwd: string;
     taskId: string;
@@ -132,12 +205,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 +258,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 +304,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 +323,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 +361,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 {
     /**