@mjasnikovs/pi-task 0.38.22 → 0.38.24

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

@@ -81,32 +81,49 @@ export declare const USER_CANCELLED = "__user_cancelled__";
  * context-usage tracking. This is the typed convenience wrapper used by
  * phase-level code.
  */
-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[], 
 /**
- * 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 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.
- */
-contextWindow?: number, 
-/**
- * The resolved `['--thinking', level]` fragment for this child's reasoning
- * group, or `[]`/omitted to inherit the session default as before.
+ * One child-pi invocation, as a value.
  *
- * A 13th trailing positional is not pretty. It is how `contextWindow` (the
- * 12th) was added, and an options-bag refactor of this signature is a
- * separate change from wiring one flag — doing both at once would put a
- * behaviour change inside a mechanical one. DEBT: convert to an options bag.
+ * 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.
  */
-thinking?: readonly string[]): Promise<PhaseRunResult>;
-interface PhaseDeps {
+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 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.
+     */
+    contextWindow?: number;
+    /**
+     * The resolved `['--thinking', level]` fragment for this child's reasoning
+     * group, or `[]`/omitted to inherit the session default as before.
+     */
+    thinking?: readonly string[];
+}
+export declare function runChild({ cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawn: spawnFn, extensions, onToolResult, contextWindow, thinking }: ChildRun): Promise<PhaseRunResult>;
+export interface PhaseDeps {
     cwd: string;
     taskId: string;
     signal: AbortSignal;
@@ -211,7 +228,55 @@ interface PhaseDeps {
      */
     searchFn?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
 }
-export type { 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
+ * 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.
+ */
+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 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;
+ *   • 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.
+ */
+/**
+ * The `--thinking` fragment for a named child, or `[]` when the name is unmapped.
+ *
+ * An unmapped name INHERITS rather than throwing: a child that reaches the model
+ * with today's argv is always safe, and aborting a user's task over a missing
+ * table row would be a worse failure than the one it reports. The guard that
+ * makes the table complete is `reasoning-groups.test.ts`, which fails the BUILD —
+ * where someone can actually fix it.
+ */
+export declare function thinkingForChild(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;
 /**

package/dist/task/child-runner.js

@@ -16,7 +16,7 @@ import { readSection, setTaskSection } from './task-io.js';
 import { streamStallCause } from '../shared/stream-watchdog.js';
 import { getConfig } from '../config/config.js';
 import { groupThinkingArgs } from '../config/reasoning-args.js';
-import { reasoningGroupForChild } from './reasoning-groups.js';
+import { reasoningGroupForChild } from '../config/reasoning.js';
 // ─── Loop detection constants ────────────────────────────────────────────────
 // Defined here (not in phases.ts) to avoid a circular dependency:
 //   phases.ts → child-runner.ts → phases.ts
@@ -167,37 +167,7 @@ thinking = []) {
 // Sentinel error thrown when the user dismisses a grill-me dialog.
 // Defined here (not in failure-classifier.ts) to avoid circular dependency.
 export const USER_CANCELLED = '__user_cancelled__';
-// ─── Core child runner (JSON event-stream mode) ─────────────────────────────
-/**
- * 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.
- */
-export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawnFn, 
-/** Internal `-e` extension paths for in-run guards (see childArgs). */
-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, 
-/**
- * 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.
- */
-contextWindow, 
-/**
- * The resolved `['--thinking', level]` fragment for this child's reasoning
- * group, or `[]`/omitted to inherit the session default as before.
- *
- * A 13th trailing positional is not pretty. It is how `contextWindow` (the
- * 12th) was added, and an options-bag refactor of this signature is a
- * separate change from wiring one flag — doing both at once would put a
- * behaviour change inside a mechanical one. DEBT: convert to an options bag.
- */
-thinking) {
+export async function runChild({ cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawn: spawnFn, extensions, onToolResult, contextWindow, thinking }) {
     const invocation = getPiInvocation(childArgs(tools, extensions, thinking), prompt);
     let loopHit;
     const result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, signal, {
@@ -338,10 +308,30 @@ async function triageChildResult(deps, name, r, attempt, budget, verb) {
  * makes the table complete is `reasoning-groups.test.ts`, which fails the BUILD —
  * where someone can actually fix it.
  */
-function thinkingForChild(name) {
+export function thinkingForChild(name) {
     const group = reasoningGroupForChild(name);
     return group ? groupThinkingArgs(group) : [];
 }
+/**
+ * What a PHASE child's invocation carries, said once.
+ *
+ * Both callers of `runChild` in this file are phase children — the strike
+ * attempts and the no-tools degrade that rescues them — and everything they
+ * disagree about is in `over`. Anything not there is the same by construction,
+ * which is what the degrade's own comment ("the degrade changes the TOOLS, not
+ * the role") claimed while three bare `undefined`s quietly made it false.
+ */
+function phaseChildRun(deps, over) {
+    return {
+        cwd: deps.cwd,
+        onLine: deps.onChildOutput,
+        onContextUsage: deps.onContextUsage,
+        spawn: deps.spawn,
+        extensions: deps.childExtensions,
+        contextWindow: deps.contextWindow,
+        ...over
+    };
+}
 export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
     if (deps.runChild)
         return await deps.runChild(name, tools, prompt);
@@ -369,13 +359,21 @@ export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
         const clock = phaseTimeout(deps.signal, budgetMs);
         let r;
         try {
-            r = await runChild(deps.cwd, tools, prependHint(hint, prompt), clock.signal, deps.onChildOutput, 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).
-                stall.noteContext(snapshot.contextWindow);
-                deps.onContextUsage?.(snapshot);
-            }, call => detector.record(call) ?? stall.record(call), deps.spawn, deps.childExtensions, (text, isError) => stall.noteResult(text, isError), deps.contextWindow, thinking);
+            r = await runChild(phaseChildRun(deps, {
+                tools,
+                prompt: prependHint(hint, prompt),
+                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).
+                    stall.noteContext(snapshot.contextWindow);
+                    deps.onContextUsage?.(snapshot);
+                },
+                onToolCall: call => detector.record(call) ?? stall.record(call),
+                onToolResult: (text, isError) => stall.noteResult(text, isError)
+            }));
         }
         finally {
             clock.cleanup();
@@ -482,13 +480,36 @@ 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`);
-    const r = await runChild(deps.cwd, '', // --no-tools: the model cannot read/grep/list, only answer
-    prependHint(formatDegradeHint(hit), prompt), deps.signal, deps.onChildOutput, deps.onContextUsage, undefined, deps.spawn, undefined, undefined, deps.contextWindow, 
-    // Same group as the attempts that led here. The degrade changes the
-    // TOOLS, not the role — running it at a different thinking level would
-    // make the fallback a different experiment from the thing it rescues.
-    thinkingForChild(name));
+    // 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.
+    const clock = phaseTimeout(deps.signal, deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS);
+    let r;
+    try {
+        r = await runChild(phaseChildRun(deps, {
+            tools: '', // --no-tools: the model cannot read/grep/list, only answer
+            prompt: prependHint(formatDegradeHint(hit), prompt),
+            signal: clock.signal,
+            // Same group as the attempts that led here. The degrade changes the
+            // TOOLS, not the role — running it at a different thinking level would
+            // make the fallback a different experiment from the thing it rescues.
+            thinking: thinkingForChild(name)
+        }));
+    }
+    finally {
+        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.
+        if (clock.timedOut()) {
+            throw new PhaseTimeoutError(name, deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS, 1);
+        }
         throw new LoopExhaustedError(name, loopHistory);
     }
     return r.text;

package/dist/task/orchestrator.d.ts

@@ -19,10 +19,9 @@ import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-c
 import { type WidgetState } from './widget.js';
 import { type RunTaskFn } from './gate-deps.js';
 import { type GateDeps } from './task-gates.js';
-import { type PhaseDeps } from './child-runner.js';
+import { type PhaseSeams } from './child-runner.js';
 import { type ThinkingControl } from './implementation-thinking.js';
 import { type RunEnd } from './run-end.js';
-import type { SpawnFn } from '../shared/child-process.js';
 import { type SuperviseOptions } from './implementation-turn.js';
 /**
  * Everything one TaskRunner needs, as one object. The runner is the shared core
@@ -38,25 +37,20 @@ export interface TaskRunnerOptions {
     resumeId?: string;
     /** Deliver the finished spec to the main session. Absent → nothing is sent. */
     sendSpec?: (spec: string) => Promise<void>;
-    /** Test seam: spawn function forwarded into `PhaseDeps.spawn`. Keep for tests
-     *  that drive the Error-triage ladder or a real process. */
-    spawnFn?: SpawnFn;
     /**
-     * Test seam: `PhaseDeps.runChild(name, tools, prompt)`. Present → every phase
-     * child is answered by name, with none of the ladder's guards. Use this when
-     * the child is a premise of the test, not its subject.
-     */
-    runChild?: PhaseDeps['runChild'];
-    /**
-     * Test seam: `PhaseDeps.runWorker(label, input)`. Present → every research
-     * worker is answered BY NAME, so the three Research retry gates and the
-     * fatal/runaway/empty classification are reachable from a runner-driven test
-     * without matching a marker sentence inside the prompt.
+     * Every injectable phase seam, in one field (`PhaseSeams`, child-runner.ts).
+     *
+     * `spawn` drives the Error-triage ladder or a real process. `runChild(name,
+     * tools, prompt)` answers every phase child BY NAME, with none of the
+     * ladder's guards — use it when the child is a premise of the test, not its
+     * subject. `runWorker(label, input)` answers every research worker by name,
+     * so the three Research retry gates are reachable without matching a marker
+     * sentence inside a prompt. The EXTERNAL CONTEXT lookups and the file
+     * inventory each default to the real implementation when absent. `timeoutMs`,
+     * `sleepFor`, `childExtensions` and `logDebug` are seams too, and were
+     * unreachable from here until this became one field.
      */
-    runWorker?: PhaseDeps['runWorker'];
-    /** Test seam: the four EXTERNAL CONTEXT lookups plus the file inventory. Each
-     *  defaults to the real implementation when absent. */
-    lookups?: Pick<PhaseDeps, 'getFileInventory' | 'docsRaw' | 'fetchRaw' | 'npmVersionLookup' | 'docsFocused' | 'fetchFocused' | 'searchFn'>;
+    seams?: PhaseSeams;
     /** Called with the resolved task id once its file exists, before any phase
      *  work. Lets callers record the id (e.g. stamp the /task-auto entry) so an
      *  interrupted run can be resumed instead of restarted. */
@@ -147,7 +141,7 @@ export declare class TaskRunner {
      */
     private _specForDelivery;
 }
-export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId' | 'spawnFn' | 'runChild' | 'runWorker' | 'lookups' | 'onStart' | 'planContext' | 'fixInstruction'> {
+export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId' | 'seams' | 'onStart' | 'planContext' | 'fixInstruction'> {
     /** Await the session going idle after the spec is delivered, so the caller
      *  blocks until the agent has implemented it. Default false. */
     waitForImplementation?: boolean;

package/dist/task/orchestrator.js

@@ -126,10 +126,7 @@ export class TaskRunner {
             cwd,
             taskId: '',
             signal: this._abort.signal,
-            spawn: opts.spawnFn,
-            runChild: opts.runChild,
-            runWorker: opts.runWorker,
-            ...opts.lookups,
+            ...opts.seams,
             // Deliberately NOT a ChildStatus (child-status.ts): the phase widget's
             // state is the whole-run WidgetState — task id, phase, label — shared by
             // reference with PhaseContext and written by the phases themselves
@@ -231,7 +228,10 @@ export class TaskRunner {
         const debugLogPath = path.join(tasksDir(cwd), `${id}-debug.log`);
         // Left UNSET at level `off`, so the ~39 `logDebug?.(…)` sites downstream
         // short-circuit before they format a string and the file is never created.
-        this._deps.logDebug = gateDebugWriter((msg) => {
+        // A caller-supplied `logDebug` seam WINS: it is the only way to observe
+        // the ~39 trail decisions from a runner-driven test, and production never
+        // sets one, so the file writer is unaffected.
+        this._deps.logDebug ??= gateDebugWriter((msg) => {
             const line = `${new Date().toISOString()} ${msg}\n`;
             fsp.appendFile(debugLogPath, line).catch(() => {
                 /* ignore */
@@ -480,10 +480,7 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                         release();
                     }
                 },
-                spawnFn: opts.spawnFn,
-                runChild: opts.runChild,
-                runWorker: opts.runWorker,
-                lookups: opts.lookups,
+                seams: opts.seams,
                 onStart: opts.onStart,
                 planContext: opts.planContext,
                 fixInstruction: opts.fixInstruction,
@@ -536,6 +533,12 @@ export const gateRunTask = (c, cwd, t, opts) => runSingleTask(c, cwd, t, {
     onStart: opts?.onStart,
     planContext: opts?.planContext,
     fixInstruction: opts?.fixInstruction
+    // NO `seams` here, deliberately. Threading them would need a field on
+    // `GateParams` and another on `GateDeps`, and nothing — production or
+    // test — would set either: the gate is reached through two orchestrators
+    // that build their params from a task file. An unused field on a seam
+    // roster is the `WorkerOutcome.reason` shape (written twelve times, read
+    // by nothing), so this stays unplumbed until a test actually needs it.
 });
 /**
  * Demote a task file to a resumable state after a gate (or its implementation)

package/dist/task/phases.d.ts

@@ -123,6 +123,22 @@ export declare function resolveOwnedFreezeForThisTask(deps: PhaseDeps, spec: str
 export declare function claimOwnedFreezeForThisTask(deps: PhaseDeps, refined: string): Promise<void>;
 export declare const phaseRefine: (deps: PhaseDeps, raw: string, planContext?: string) => Promise<string>;
 export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): Promise<string>;
+/**
+ * The worker channels the APIS research worker is given.
+ *
+ * `pi-worker-search` + `pi-worker-fetch` ride along only when the configured
+ * engine is usable (a keyless engine always is; brave needs its key). A tool
+ * without a key just errors, and a weak model burns calls on it — while search
+ * being ABSENT was structural in the other direction: three consecutive audited
+ * runs made 0 search calls because the child literally did not have the tool.
+ *
+ * Both halves of "given a channel" — the tools string and the `-e` path — come
+ * from the same rows, so they cannot disagree.
+ */
+export declare function apisWorkerChannels(): {
+    tools: string;
+    extensions: string[];
+};
 /**
  * Is live web search configured for this process? The keyless providers (exa,
  * ddg) always are; only brave needs its API key.
@@ -156,29 +172,6 @@ export declare const SINGLE_READ_EXTENSION_PATH: string;
  * mentions; the rest are unchanged or only lightly trimmed.
  */
 export declare function scopedToolingGoal(refined: string): string;
-/**
- * Build a degraded section body for a runaway worker: a one-line marker naming
- * the failure (so downstream phases and a human reading the task file know this
- * section is incomplete) followed by whatever partial answer the worker streamed
- * before it was killed. The marker is always present even when there is no
- * partial text, so an empty degrade is never mistaken for a real finding.
- */
-export declare function degradedSectionBody(name: string, reason: string, partial: string): string;
-/**
- * The body written for a research section the worker confirmed has no entries.
- *
- * Three states have to stay distinguishable to anyone — human or later phase —
- * reading a research section, so each carries its own marker:
- *   `(none — …)`     the worker RAN and answered "nothing applies" (this)
- *   `(degraded: …)`  the worker was killed mid-answer, text may be partial
- *                    (degradedSectionBody)
- *   section absent   the worker never got that far — the phase threw
- *
- * Naming the worker inside the marker keeps it true after assembly, where the
- * section headings are all that separate the four workers' output.
- */
-export declare function emptySectionBody(name: string): string;
-export declare function isBareNoneAnswer(text: string): boolean;
 export declare function phaseResearch(deps: PhaseDeps, refined: string): Promise<string>;
 export declare function phaseAutoAnswer(deps: PhaseDeps, refined: string, research: string, question: string): Promise<AutoAnswer>;
 export declare function phaseGrill(deps: PhaseDeps, ctx: ExtensionCommandContext, widgetState: WidgetState, refined: string, research: string): Promise<string>;