@mjasnikovs/pi-task 0.38.32 → 0.39.1

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

@@ -1,204 +1,66 @@
 /**
- * Child process runner for the pi-task orchestrator.
+ * The phase children's adapter over the one attempt loop.
  *
- * Thin wrapper layer over the unified `runChild` in `shared/child-process.ts`.
- * Provides JSON event-stream parsing, loop detection, and context-usage tracking
- * for phase-level child pi invocations.
- */
-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';
+ * `runWorker` (workers/pi-worker-core.ts) owns every guard a model child runs
+ * under and every restart it may be granted; the `phase` row of WORKER_PROFILES
+ * says which. What is left here is what a PHASE child is that a research worker
+ * is not: it is named, its name picks its group, its failure is THROWN as a
+ * typed error the pipeline switches on, and its loop kills leave a trail in the
+ * task file. Nothing here re-decides how a child may die.
+ */
+import { type RunWorkerInput, type RunWorkerResult } from '../workers/pi-worker-core.js';
+import { type WorkerFailure } from '../workers/worker-failure.js';
+import type { SpawnFn, ContextSnapshot, LoopHit } from '../shared/child-process.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 USER_CANCELLED = "__user_cancelled__";
 /**
- * Optional wall-clock bound on ONE spawn of a phase child. DEFAULT: OFF.
- *
- * WHY OFF, AND NOT A NUMBER. A wall clock on a model child measures the
- * MODEL'S SPEED, not its health. The same planning child that answers well in
- * seconds on one backend takes many minutes on another, or on the same backend
- * with thinking turned on — so any cap generous enough to be safe is too loose
- * to catch anything, and any cap tight enough to catch a runaway kills healthy
- * work. Assume a model that emits one token per second and the number has no
- * defensible value at all.
- *
- * The runaway it was there to catch — a child forward-paging through its whole
- * context window, past the loop detector, never going to return — is caught by
- * StallDetector (stall-detector.ts) instead. That bounds NON-PROGRESS and
- * CONTEXT CHURN, both properties of the pathology itself, so neither has to be
- * re-tuned for a slower model or a bigger repo.
- *
- * The value and the plumbing stay for a caller that genuinely wants a hard stop
- * (tests inject a short one), but nothing sets it in production. Pass
- * `timeoutMs` explicitly to arm it.
- */
-export 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
- * job WORKER_TIMEOUT_HINT does for research workers.
- */
-export declare const PHASE_TIMEOUT_HINT: string;
-/** Thrown when a phase child spends its whole restart budget hitting the cap. */
-export declare class PhaseTimeoutError extends Error {
-    readonly childName: string;
-    readonly budgetMs: number;
-    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.
+ * Why a phase child did not answer.
  *
- * 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 worker roster's kills, plus the two outcomes `worker-failure.ts`
+ * deliberately leaves to the consumer: a reported model error, and an empty
+ * answer. For a phase child both ARE failures, so they join the union here.
+ * `loop` carries how many strikes it took, which is what the notice reports.
+ */
+export type ChildFailure = Exclude<WorkerFailure, {
+    kind: 'loop';
+}> | {
+    kind: 'loop';
+    hit: LoopHit;
+    strikes: number;
+} | {
+    kind: 'model-error';
+    cause: string;
+} | {
+    kind: 'empty-answer';
+};
 /**
- * The dead-backend probe killed a phase child on its LAST attempt.
+ * ONE error class for every way a phase child fails, carrying the cause as data.
  *
- * Reaching this means every attempt found no endpoint answering, not one. The
- * single-probe verdict is not trusted on its own, because one sample cannot tell
- * a dead server from a blip. Three failed probes cost ~15s; one wrong verdict
- * costs the run.
+ * Six classes plus a string sentinel used to say the same nine things, and
+ * `classifyFailure` rebuilt the ladder by `instanceof` and then fell through
+ * to sniffing the message — the tell that the vocabulary was leaking. A catch
+ * site asks `isFatalChildCause`; the notice switches on `failure.kind`.
  */
-export 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);
+export declare class ChildFailureError extends Error {
+    readonly phase: string;
+    readonly failure: ChildFailure;
+    readonly stderr: string;
+    constructor(phase: string, failure: ChildFailure, stderr?: string);
 }
 /**
  * Causes a best-effort `catch` must NOT absorb.
  *
  * A phase child that merely answered badly should degrade — that is what those
- * catches are for. These two are different in kind: the run is over either way,
- * and swallowing them ships a half-built spec while every later phase dies
- * against the same dead backend, or turns a user's ESC into silent progress.
- * `failure-classifier.ts` has a verdict for both; a catch that eats them makes it
- * unreachable.
+ * catches are for. A dead backend and a user cancel are different in kind: the
+ * run is over either way, and swallowing them ships a half-built spec while
+ * every later phase dies against the same dead server, or turns an ESC into
+ * silent progress. Which kills are fatal is the roster's column, not a list here.
  */
 export 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. */
-export declare function connectionRetryBackoffMs(attempt: number): number;
-export interface PhaseRunResult {
-    text: string;
-    exitCode: number;
-    stderr: string;
-    loopHit?: LoopHit;
-    /** Set when the assistant text contains an unexecuted, leaked tool call. */
-    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[], 
-/**
- * This child's group fragment: `--model` then `--thinking`, either half
- * possibly absent. Resolved by the CALLER, never here — both are properties
- * of the child's ROLE, and this function is handed tools and extensions, not
- * a name. Omitted ⇒ byte-identical argv to the version before group profiles.
- *
- * ONE field rather than a `model` beside a `thinking`, because nothing may
- * compose the two halves by hand: `groupChildArgs` is the only producer, so a
- * doubled `--thinking` is unreachable rather than merely unlikely.
- */
-groupArgs?: readonly string[]): string[];
-export declare const USER_CANCELLED = "__user_cancelled__";
-/**
- * Run a child pi process with JSON event-stream output, loop detection, and
- * context-usage tracking. This is the typed convenience wrapper used by
- * phase-level code.
- */
-/**
- * One child-pi invocation, as a value.
- *
- * 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;
-    /** `''` means `--no-tools`. See childArgs. */
-    tools: string;
-    prompt: string;
-    signal: AbortSignal;
-    onLine?: (line: string) => void;
-    onContextUsage?: (snapshot: ContextSnapshot) => void;
-    onToolCall?: (call: ToolCall) => LoopHit | null;
-    spawn?: SpawnFn;
-    /** Internal `-e` extension paths for in-run guards (see childArgs). */
-    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;
-    /**
-     * 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;
-    /**
-     * The resolved argv fragment for this child's group — `--model` then
-     * `--thinking` — or `[]`/omitted to inherit both defaults as before.
-     */
-    groupArgs?: 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;
-}
-/**
- * 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, groupArgs, commandCeilingMs }: ChildRun): Promise<PhaseRunResult>;
 export interface PhaseDeps {
     cwd: string;
     taskId: string;
@@ -206,14 +68,13 @@ export interface PhaseDeps {
     onChildOutput?: (line: string) => void;
     onContextUsage?: (snapshot: ContextSnapshot) => void;
     /**
-     * The parent session's context window in tokens, handed down to every child.
+     * The parent session's context window in tokens, handed down to every child
+     * whose group resolved no window of its own.
      *
      * 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.
+     * return false`. Absent = unknown, and both consumers degrade.
      */
     contextWindow?: number;
     /**
@@ -235,10 +96,9 @@ export interface PhaseDeps {
      */
     childExtensions?: readonly string[];
     /**
-     * Wall-clock budget for ONE spawn of this child, in ms. Defaults to
-     * PHASE_CHILD_TIMEOUT_MS; `0` disables the cap. Mirrors runWorker's
-     * `timeoutMs` input, which is the same backstop one layer down
-     * (workers/pi-worker-core.ts). Tests inject a short budget.
+     * Wall-clock budget for ONE spawn of this child, in ms — the `phase`
+     * profile's `worker-timeout` row. Nothing sets it in production; the row
+     * says why. Tests inject a short budget.
      */
     timeoutMs?: number;
     /**
@@ -256,9 +116,9 @@ export interface PhaseDeps {
     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.
+     * child goes through. Absent (production) → the real loop runs, with every
+     * guard the `phase` profile names. 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. Discarded before it reaches
@@ -266,8 +126,8 @@ export interface PhaseDeps {
      * 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.
+     * `spawn` stays: the loop's OWN tests 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>;
     /**
@@ -316,29 +176,27 @@ export interface PhaseDeps {
  */
 export type PhaseSeams = Omit<PhaseDeps, 'cwd' | 'taskId' | 'signal' | 'onChildOutput' | 'onContextUsage' | 'contextWindow' | 'recordSubStep'>;
 /**
- * Run a child pi and return its assistant text. Throws if exit code != 0.
- *
- * If the child leaks a tool call as plain text (wrong dialect — never executed),
- * re-prompt with a correction hint up to MAX_LEAK_RETRIES times; if it keeps
- * leaking, throw LeakedToolCallError rather than returning the unexecuted call.
- * Empty completions and connection-class model errors share that same budget —
- * see triageChildResult, which decides every one of those cases.
- *
- * THREE RUNAWAY GUARDS ride the same budget, because this is the runner every
- * /task-auto planning child goes through (clarify, decompose, coverage,
- * contract-extract), and an unguarded planning child can burn a whole run:
- *   • a LoopDetector, so an identical repeated tool call is killed and
- *     re-prompted instead of being allowed to fill the context window;
- *   • a StallDetector, the backstop for the varied-args thrash the loop
- *     detector's short window cannot see — a child that keeps calling tools with
- *     different arguments, learns nothing, and is never going to return. It bounds
- *     consecutive no-new-ground calls and total context churn, NOT elapsed time;
- *   • PHASE_CHILD_TIMEOUT_MS, a hard wall clock, OFF by default: a healthy
- *     reasoning-on planning child and a runaway one occupy the same range of
- *     elapsed times, so no threshold separates them. See its comment.
- * All three are checked BEFORE the triage ladder: we killed the child, so its
- * exit status describes our SIGTERM and says nothing about its verdict.
+ * The two things a phase child can disagree about. Everything else — the
+ * guards, the budgets, the loop trail — is the one loop's and the `phase` row's.
  */
+export interface PhaseChildOptions {
+    /**
+     * The wrapper's own word in the debug log for "we are going round again".
+     * The debug trail of a real run is read by a human who knows which phases
+     * restart and which retry.
+     */
+    verb?: 'retry' | 'restart';
+    /**
+     * When the strike budget is exhausted by loops, do NOT fail the phase. Run
+     * ONE final attempt with NO tools and a terminal hint ordering the model to
+     * emit its output from what it already has. Only safe for phases whose
+     * deliverable is a pure text rewrite that never strictly required a read
+     * (refine) — a hard-fail there kills the whole /task-auto run for a model
+     * that simply over-explored. Research/location phases must NOT enable this:
+     * their output depends on real reads, so a no-tools fallback would fabricate.
+     */
+    degradeOnExhaustion?: boolean;
+}
 /**
  * The group fragment for a named child, or `[]` when the name is unmapped.
  *
@@ -350,42 +208,13 @@ export type PhaseSeams = Omit<PhaseDeps, 'cwd' | 'taskId' | 'signal' | 'onChildO
  */
 export declare function groupArgsForChild(name: string): string[];
 export declare function runPhaseChild(deps: PhaseDeps, name: string, tools: string, prompt: string, opts?: PhaseChildOptions): Promise<string>;
-export declare function formatLoopHint(hit: LoopHit): string;
 /**
  * Terminal hint for the degrade attempt: the model has thrashed through the whole
  * strike budget re-reading files without converging, so we strip its tools and
- * order it to emit the deliverable NOW from what it already has. Used only by
- * read-only analysis phases (refine) whose output is a text rewrite that never
- * strictly required a successful read — far better to ship a best-effort spec
- * than to hard-fail the whole /task-auto run. See countRevisits / LoopExhausted.
+ * order it to emit the deliverable NOW from what it already has.
  */
 export declare function formatDegradeHint(hit: LoopHit): string;
 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. These two are the only differences observable from
- * outside it.
- */
-export interface PhaseChildOptions {
-    /**
-     * The wrapper's own word in the debug log for "we are going round again".
-     * An option rather than one word because it is the single externally visible
-     * difference between the two loops this collapsed, and the debug trail of a
-     * real run is read by a human who knows which phases restart and which retry.
-     */
-    verb?: 'retry' | 'restart';
-    /**
-     * When the strike budget is exhausted by loops, do NOT fail the phase. Run
-     * ONE final attempt with NO tools and a terminal hint ordering the model to
-     * emit its output from what it already has. Only safe for phases whose
-     * deliverable is a pure text rewrite that never strictly required a read
-     * (refine) — a hard-fail there kills the whole /task-auto run for a model
-     * that simply over-explored. Research/location phases must NOT enable this:
-     * their output depends on real reads, so a no-tools fallback would fabricate.
-     */
-    degradeOnExhaustion?: boolean;
-}
 /**
  * Run a child up to twice; the second attempt gets `emphasized=true` to escalate
  * the prompt. On success, return the validator's value; on two failures, throw
@@ -398,34 +227,3 @@ export declare function runWithEmphasisRetry<T>(deps: PhaseDeps, name: string, t
     ok: false;
     problem: string;
 }, onFail: (problem: string) => Error): Promise<T>;
-export declare class LoopExhaustedError extends Error {
-    readonly phase: string;
-    readonly history: LoopHit[];
-    constructor(phase: string, history: LoopHit[]);
-}
-/**
- * Thrown when a phase child's final turn failed with stopReason "error" — the
- * model/provider died (local model disconnect, fetch failed, socket hang up,
- * provider 5xx) after pi exhausted its own internal retries. pi reports this as
- * an agent_end with empty assistant text, which would otherwise surface as the
- * misleading "produced no output"; this names the real cause instead.
- *
- * Fail-fast: not retried at the pi-task layer. pi already retried the retryable
- * cases; re-spawning a fresh child against the same dead endpoint only burns
- * time and buries the real error. Restart the model/provider, then resume.
- */
-export declare class ModelError extends Error {
-    readonly phase: string;
-    readonly cause: string;
-    constructor(phase: string, cause: string);
-}
-/**
- * Thrown when a phase child repeatedly wrote a tool call as plain text (a markup
- * dialect pi's harness didn't parse) instead of invoking it. The call never ran,
- * so the phase output is untrustworthy — fail loudly rather than check it off.
- */
-export declare class LeakedToolCallError extends Error {
-    readonly phase: string;
-    readonly marker: string;
-    constructor(phase: string, marker: string);
-}