@mjasnikovs/pi-task 0.39.0 → 0.39.2

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-4320%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-4118%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -244,7 +244,7 @@ them checked in.
 
 ```sh
 bun install
-bun run test       # 4321 tests across 242 files
+bun run test       # 4119 tests across 227 files
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```

package/dist/config/group-args.d.ts

@@ -1,21 +1,33 @@
 /**
- * The live-config bridge for per-group child settings: group in, argv fragment out.
+ * The live-config bridge for per-group child settings: group in, argv fragment
+ * out — plus the session's model snapshot, which the argv needs and which only a
+ * session_start with a `ctx` can produce.
  *
  * Separate from reasoning.ts and group-models.ts because those must take no
  * import with a runtime side effect — see their headers. The `getConfig()` read
  * lives here instead: this file imports them and nothing in config/ imports it
  * back, so the graph stays a tree.
  *
- * Read PER CALL, never cached at module scope, so a /task-config change lands on
- * the next child without a restart. Same contract `childBaseArgs` keeps.
+ * Config is read PER CALL, never cached at module scope, so a /task-config
+ * change lands on the next child without a restart. Same contract
+ * `childBaseArgs` keeps. The snapshot is the one deliberate exception, and it is
+ * a snapshot of the REGISTRY, not of config.
  */
 import { type PiTaskConfig } from './config.js';
 import type { ChildGroup } from './groups.js';
-export declare function setUnusableSpecs(specs: Iterable<string>): void;
-export declare function isSpecUsable(spec: string): boolean;
-export declare function setGroupWindows(windows: Readonly<Partial<Record<ChildGroup, number>>>): void;
-/** The group's own window, or `undefined` for "caller keeps its fallback". */
+import type { GroupModelSnapshot } from '../shared/model-resolve.js';
+export declare function setGroupModels(snapshot: Readonly<Partial<Record<ChildGroup, GroupModelSnapshot>>>): void;
+/**
+ * The group's own window, or `undefined` for "caller keeps its fallback".
+ *
+ * The number drives `StallDetector`'s churn rule, where the two error directions
+ * are NOT symmetric: too large fires late (degraded, and the no-new-ground rule
+ * still covers it), too small fires early and KILLS A HEALTHY CHILD. So an
+ * absent answer means "use the parent's", never a guess.
+ */
 export declare function groupWindow(group: ChildGroup): number | undefined;
+export declare function setModelEndpoints(endpoints: ReadonlyMap<string, string>): void;
+export declare function modelEndpoint(spec: string): string | undefined;
 /**
  * The `['--model', spec]` fragment for a group, or `[]` for `inherit` and for a
  * spec this session proved unresolvable.
@@ -26,14 +38,17 @@ export declare function groupWindow(group: ChildGroup): number | undefined;
  * `reasoning: true` onto it, inherits the provider's default baseUrl and answers
  * at exit 0. Dropping the flag runs the same child the user got last week and
  * says so out loud; passing it runs a model nobody chose and says nothing.
+ *
+ * The verdict applies to the spec it was proven on: a cell changed since
+ * session_start is emitted, and pi decides.
  */
 export declare function groupModelArgs(group: ChildGroup, cfg?: PiTaskConfig): string[];
 /**
  * The `['--thinking', level]` fragment for a group, or `[]` when the group is
  * `inherit` and the child should keep falling back to settings.json.
  *
- * Still exported on its own: the host-session turn (implementation-hold.ts) and
- * the settings UI (register.ts) need the level rather than a whole fragment.
+ * Exported for its own tests only: the per-call config read is a contract on
+ * each half, and only the half on its own can assert it.
  */
 export declare function groupThinkingArgs(group: ChildGroup, cfg?: PiTaskConfig): string[];
 /**

package/dist/config/group-args.js

@@ -1,22 +1,26 @@
 /**
- * The live-config bridge for per-group child settings: group in, argv fragment out.
+ * The live-config bridge for per-group child settings: group in, argv fragment
+ * out — plus the session's model snapshot, which the argv needs and which only a
+ * session_start with a `ctx` can produce.
  *
  * Separate from reasoning.ts and group-models.ts because those must take no
  * import with a runtime side effect — see their headers. The `getConfig()` read
  * lives here instead: this file imports them and nothing in config/ imports it
  * back, so the graph stays a tree.
  *
- * Read PER CALL, never cached at module scope, so a /task-config change lands on
- * the next child without a restart. Same contract `childBaseArgs` keeps.
+ * Config is read PER CALL, never cached at module scope, so a /task-config
+ * change lands on the next child without a restart. Same contract
+ * `childBaseArgs` keeps. The snapshot is the one deliberate exception, and it is
+ * a snapshot of the REGISTRY, not of config.
  */
 import { getConfig } from './config.js';
 import { MODEL_INHERIT, modelArgs } from './group-models.js';
 import { resolveReasoning, thinkingArgs } from './reasoning.js';
 /**
- * Specs this session has proven a child cannot resolve.
+ * What this session resolved each group's model cell to.
  *
- * WHY A SESSION-SCOPED SET AND NOT A LOOKUP
- * -----------------------------------------
+ * WHY A SESSION-SCOPED SNAPSHOT AND NOT A LOOKUP
+ * ----------------------------------------------
  * The honest question is "can a `--no-extensions` child resolve this spec?", and
  * only `ctx.modelRegistry` can answer it. Five of the six argv producers have no
  * `ctx` — `pi-worker`, `pi-worker-docs`, `docs-core`, `fetch-core` and
@@ -26,41 +30,43 @@ import { resolveReasoning, thinkingArgs } from './reasoning.js';
  * this project does not depend on pi-ai.
  *
  * So it is answered ONCE, at session_start, where ctx exists and every task is
- * still in the future, and the verdict is left here.
+ * still in the future, and the whole verdict is left here — usability and the
+ * context window from ONE walk, so the argv and the churn rule can never
+ * disagree about which model a group runs on.
  *
  * EMPTY MEANS EMIT. A host that never fires session_start therefore behaves
  * exactly as it does today — the failure direction is "pi decides", never "we
  * silently dropped a flag nobody checked".
  */
-let unusableSpecs = new Set();
-export function setUnusableSpecs(specs) {
-    unusableSpecs = new Set(specs);
-}
-export function isSpecUsable(spec) {
-    return !unusableSpecs.has(spec);
+let groupModels = {};
+export function setGroupModels(snapshot) {
+    groupModels = { ...snapshot };
 }
 /**
- * The context window of each group's model, resolved in the SAME session pass
- * that filled {@link setUnusableSpecs}.
- *
- * It lives here for the same reason that set does — `child-runner` and the
- * workers have no `ctx`, so they cannot ask a registry — and it is filled by the
- * same walk, so the two can never disagree about which model a group runs on.
+ * The group's own window, or `undefined` for "caller keeps its fallback".
  *
  * The number drives `StallDetector`'s churn rule, where the two error directions
  * are NOT symmetric: too large fires late (degraded, and the no-new-ground rule
  * still covers it), too small fires early and KILLS A HEALTHY CHILD. So an
  * absent answer means "use the parent's", never a guess.
  */
-let groupWindows = {};
-export function setGroupWindows(windows) {
-    groupWindows = { ...windows };
-}
-/** The group's own window, or `undefined` for "caller keeps its fallback". */
 export function groupWindow(group) {
-    const w = groupWindows[group];
+    const w = groupModels[group]?.contextWindow;
     return w !== undefined && w > 0 ? w : undefined;
 }
+/**
+ * `spec → baseUrl` for every model the session can use, from the same
+ * session_start pass. Read by the dead-backend probe (shared/model-endpoint.ts),
+ * which runs where no `ctx` exists. Empty until a session starts, and the probe
+ * reads "no url" as "cannot see this server, so never kill".
+ */
+let modelEndpoints = new Map();
+export function setModelEndpoints(endpoints) {
+    modelEndpoints = new Map(endpoints);
+}
+export function modelEndpoint(spec) {
+    return modelEndpoints.get(spec);
+}
 /**
  * The `['--model', spec]` fragment for a group, or `[]` for `inherit` and for a
  * spec this session proved unresolvable.
@@ -71,19 +77,23 @@ export function groupWindow(group) {
  * `reasoning: true` onto it, inherits the provider's default baseUrl and answers
  * at exit 0. Dropping the flag runs the same child the user got last week and
  * says so out loud; passing it runs a model nobody chose and says nothing.
+ *
+ * The verdict applies to the spec it was proven on: a cell changed since
+ * session_start is emitted, and pi decides.
  */
 export function groupModelArgs(group, cfg) {
     const spec = (cfg ?? getConfig()).groupModels[group];
     if (spec === undefined || spec === MODEL_INHERIT)
         return [];
-    return isSpecUsable(spec) ? modelArgs(spec) : [];
+    const proven = groupModels[group];
+    return proven?.spec === spec && !proven.usable ? [] : modelArgs(spec);
 }
 /**
  * The `['--thinking', level]` fragment for a group, or `[]` when the group is
  * `inherit` and the child should keep falling back to settings.json.
  *
- * Still exported on its own: the host-session turn (implementation-hold.ts) and
- * the settings UI (register.ts) need the level rather than a whole fragment.
+ * Exported for its own tests only: the per-call config read is a contract on
+ * each half, and only the half on its own can assert it.
  */
 export function groupThinkingArgs(group, cfg) {
     // The default is evaluated HERE, per call. Hoisting the read to module scope

package/dist/config/register.d.ts

@@ -178,15 +178,6 @@ export interface ModelCatalog {
 }
 /** No registry reachable. Every row still renders; nothing narrows. */
 export declare const EMPTY_CATALOG: ModelCatalog;
-/**
- * The levels a row may offer, given the model that row's group will run on.
- *
- * The INTERSECTION with `REASONING_SETTINGS`, not `supportedThinkingLevels`
- * directly: that returns the whole ladder including `xhigh` and `max`, which
- * this menu excludes on purpose (see reasoning.ts) because pi's own UI may not
- * offer them. A model declaring `xhigh` must not smuggle it in here.
- */
-export declare function offeredLevels(facts: ReasoningModelFacts | undefined): GroupSetting[];
 /**
  * `level · provider/id`, the one string a step row shows and accepts.
  *

package/dist/config/register.js

@@ -1,6 +1,7 @@
 import { getKeybindings, SettingsList, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
-import { clampToModel, supportedThinkingLevels } from '../shared/reasoning-capability.js';
-import { MODEL_INHERIT, splitSpec } from './group-models.js';
+import { effectiveSetting, offeredLevels } from '../shared/reasoning-capability.js';
+import { resolveModel, specOf } from '../shared/model-resolve.js';
+import { MODEL_INHERIT } from './group-models.js';
 import { PairPicker } from './option-picker.js';
 import { registerBridgeCommand } from '../remote/bridge.js';
 import { readPkgVersion } from '../shared/pkg-version.js';
@@ -382,20 +383,6 @@ export function stepRowLabel(group) {
 }
 /** No registry reachable. Every row still renders; nothing narrows. */
 export const EMPTY_CATALOG = { specs: [], facts: () => undefined };
-/**
- * The levels a row may offer, given the model that row's group will run on.
- *
- * The INTERSECTION with `REASONING_SETTINGS`, not `supportedThinkingLevels`
- * directly: that returns the whole ladder including `xhigh` and `max`, which
- * this menu excludes on purpose (see reasoning.ts) because pi's own UI may not
- * offer them. A model declaring `xhigh` must not smuggle it in here.
- */
-export function offeredLevels(facts) {
-    if (facts === undefined)
-        return [...REASONING_SETTINGS];
-    const supported = supportedThinkingLevels(facts);
-    return REASONING_SETTINGS.filter(s => s === 'inherit' || supported.includes(s));
-}
 /** The separator between a step row's two halves. */
 const PAIR_SEP = ' \u00b7 ';
 /**
@@ -498,19 +485,10 @@ function stepPicker(group, cfg, catalog) {
         ],
         second: spec => {
             const facts = catalog.facts(spec);
-            const offered = offeredLevels(facts);
             const wanted = resolveReasoning(group, cfg);
-            const clamped = facts === undefined || wanted === 'inherit' ?
-                wanted
-                : clampToModel(facts, wanted);
-            // Back inside the menu's own vocabulary. `clampToModel` walks UP
-            // first and knows the whole ladder, so a model declaring `xhigh`
-            // can land on a level `offeredLevels` deliberately excludes — and
-            // then stage two would open on `inherit` with the explanation
-            // attached to no row at all.
-            const runs = offered.includes(clamped) ? clamped : (offered.at(-1) ?? 'inherit');
+            const runs = effectiveSetting(facts, wanted);
             return {
-                options: offered.map(level => ({
+                options: offeredLevels(facts).map(level => ({
                     value: level,
                     label: level,
                     ...(level === runs && runs !== wanted ?
@@ -551,10 +529,7 @@ export function applyStepValue(cfg, group, chosen, catalog) {
         return;
     }
     cfg.groupModels = { ...cfg.groupModels, [group]: pair.spec };
-    const facts = catalog.facts(pair.spec);
-    const level = facts === undefined || pair.level === 'inherit' ?
-        pair.level
-        : clampToModel(facts, pair.level);
+    const level = effectiveSetting(catalog.facts(pair.spec), pair.level);
     // Only when it MOVES something: `applyReasoningLevel` flips the whole table
     // to `custom`, and picking a pair the config already runs must not do that
     // as a side effect.
@@ -831,47 +806,27 @@ function liveCatalog(ctx) {
     // registry that cannot answer must cost the model rows, never the menu.
     // Every row below still renders; `EMPTY_CATALOG` offers only `inherit` and
     // narrows nothing, which is exactly the pre-feature panel.
-    let registry;
     let available;
-    let fromExtension;
     try {
-        registry = ctx.modelRegistry;
-        available = registry.getAvailable();
-        fromExtension = new Set(registry.getRegisteredProviderIds());
+        available = ctx.modelRegistry.getAvailable();
     }
     catch {
         return EMPTY_CATALOG;
     }
     return {
-        specs: available.map(m => `${m.provider}/${m.id}`),
-        note: spec => {
-            const parts = splitSpec(spec);
-            return parts && fromExtension.has(parts.provider) ?
-                'provider comes from an extension — whitelist it under child extensions, '
-                    + "or this group's children exit 1"
-                : undefined;
-        },
-        facts: spec => {
-            // `inherit` means the session's own model, which is what a child
-            // resolves today. Its facts are what the thinking row must narrow to.
-            if (spec === MODEL_INHERIT)
-                return ctx.model;
-            const parts = splitSpec(spec);
-            return parts ? registry.find(parts.provider, parts.id) : undefined;
-        }
+        specs: available.map(specOf),
+        note: spec => resolveModel(ctx, spec)?.fromExtension ?
+            'provider comes from an extension — whitelist it under child extensions, '
+                + "or this group's children exit 1"
+            : undefined,
+        facts: spec => resolveModel(ctx, spec)
     };
 }
 async function handleTaskConfig(_args, ctx, getTools = () => []) {
-    const cfg = {
-        ...getConfig(),
-        extensionWhitelist: [...getConfig().extensionWhitelist],
-        commandTimeoutExemptTools: [...getConfig().commandTimeoutExemptTools],
-        // Copied for the same reason as the two arrays above: the panel mutates
-        // its own draft, and sharing the live object would apply half-made
-        // choices to running children before the user finished choosing.
-        reasoningLevels: { ...getConfig().reasoningLevels },
-        groupModels: { ...getConfig().groupModels }
-    };
+    // A deep copy: the panel mutates its own draft, and sharing the live object
+    // would apply half-made choices to running children before the user
+    // finished choosing.
+    const cfg = structuredClone(getConfig());
     // Enumerated live at open so an installed extension appears and an
     // uninstalled one vanishes without pi-task doing any bookkeeping. A failed
     // enumeration only costs the extension toggles, never the whole menu.

package/dist/shared/child-process.d.ts

@@ -1,4 +1,6 @@
 import type { EventEmitter } from 'node:events';
+import type { CommandKillReason } from './command-watchdog.js';
+import type { LoopHit } from '../task/loop-detector.js';
 /** Grace period between SIGTERM and SIGKILL (ms). */
 export declare const KILL_GRACE_MS = 5000;
 /** Base flags shared by all child pi invocations. */
@@ -36,11 +38,41 @@ export type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
      *  model children (json-events); plumbing stays in-group. */
     detached?: boolean;
 }) => ProcLike;
+/**
+ * Why runChild killed the child. Five sources converge on one kill path, and
+ * each names itself here rather than in its own flag — so a consumer reads ONE
+ * field, and a sixth source is one more member, not a fourth boolean that every
+ * consumer has to remember to test before `aborted`.
+ *
+ * `aborted` is the caller's signal with no cause attached: a user cancel, or a
+ * wall clock that aborts without saying so. `command-timeout` also arrives
+ * through the signal, but the watchdog aborts WITH its kill as the reason
+ * (command-watchdog.ts), which is how it stays a member here instead of an
+ * out-of-band query.
+ */
+export type ChildKill = {
+    by: 'aborted';
+} | {
+    by: 'loop';
+    hit: LoopHit;
+} | {
+    by: 'stream-stall';
+    idleMs: number;
+} | {
+    by: 'stalled';
+} | CommandKillReason;
 export interface ChildResult {
     stdout: string;
     stderr: string;
     exitCode: number;
+    /** true exactly when `kill` is set. Kept as a flag for the text-mode callers. */
     aborted: boolean;
+    /**
+     * Set when WE ended the child. Its exit status then describes our SIGTERM
+     * and says nothing about the child's verdict, so a consumer must read this
+     * before the exit code.
+     */
+    kill?: ChildKill;
     /** Extracted assistant text (only populated in json-events mode). */
     text?: string;
     /**
@@ -51,24 +83,6 @@ export interface ChildResult {
      * Only populated in json-events mode.
      */
     modelError?: string;
-    /**
-     * true when the stall guard killed the child: no output for the stall
-     * window AND the model endpoint probe found the backend unreachable.
-     * Callers must check this BEFORE `aborted` — the kill sets aborted too,
-     * and without the flag it would mislabel as a user cancel.
-     */
-    stalled?: boolean;
-    /**
-     * true when the STREAM watchdog killed the child: no output at all for the
-     * configured inactivity window, regardless of whether the backend answers a
-     * probe. Distinct from `stalled`, which requires an UNREACHABLE endpoint —
-     * these hangs have a perfectly healthy server and a dead stream, so the
-     * probe path could never fire. Callers must check this BEFORE `aborted`
-     * (the kill sets aborted too) and route it into the connection-error retry.
-     */
-    streamStalled?: {
-        idleMs: number;
-    };
 }
 export interface ToolCall {
     name: string;
@@ -83,19 +97,7 @@ export interface ToolCall {
      */
     toolCallId?: string;
 }
-export interface LoopHit {
-    call: ToolCall;
-    count: number;
-    windowSize: number;
-    /**
-     * Set when the kill came from the whole-run StallDetector rather than the
-     * short-window LoopDetector, naming which of its two rules tripped
-     * (task/stall-detector.ts). Absent for an ordinary loop hit. Carried here so
-     * a stall rides the kill/restart plumbing the loop hit already has instead of
-     * needing a second channel.
-     */
-    stall?: 'no-new-ground' | 'context-churn';
-}
+export type { LoopHit } from '../task/loop-detector.js';
 export interface ContextSnapshot {
     tokens: number;
     contextWindow: number;
@@ -215,7 +217,7 @@ export declare class JsonEventSink {
     private buf;
     constructor(opts: RunChildJsonEventsOptions, 
     /** Invoked when onToolCall reports a loop hit — runChild kills the child. */
-    onLoopKill: () => void);
+    onLoopKill: (hit: LoopHit) => void);
     /** Feed a raw stdout chunk: parse every complete line, buffer the partial tail. */
     feed(chunk: string): void;
     /** Flush a trailing event that wasn't newline-terminated (call on close). */

package/dist/shared/child-process.js

@@ -1,5 +1,6 @@
 import { spawn as defaultSpawn, spawnSync as spawnSyncDefault } from 'node:child_process';
 import { realStreamTimerDeps, StreamWatchdog } from './stream-watchdog.js';
+import { realStallTimerDeps, StallProbe } from './stall-probe.js';
 import { workerChannel } from '../workers/worker-channels.js';
 /** Grace period between SIGTERM and SIGKILL (ms). */
 export const KILL_GRACE_MS = 5000;
@@ -12,6 +13,11 @@ export const CHILD_BASE_ARGS = [
     '--no-context-files',
     '--no-session'
 ];
+/** The cause a signal was aborted with, when its owner attached one. */
+function abortCause(reason) {
+    const tagged = reason;
+    return tagged?.by === 'command-timeout' ? reason : { by: 'aborted' };
+}
 // ─── JSON event-stream sink ──────────────────────────────────────────────────
 /**
  * Parses a child's `--mode json` event stream into assistant text plus side
@@ -179,7 +185,7 @@ export class JsonEventSink {
             if (opts.onToolCall) {
                 const hit = opts.onToolCall({ name: tn, args: evt.args, toolCallId: id });
                 if (hit)
-                    this.onLoopKill();
+                    this.onLoopKill(hit);
             }
             return;
         }
@@ -208,7 +214,7 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
     return new Promise(resolve => {
         let stdout = '';
         let stderr = '';
-        let aborted = false;
+        let kill;
         const discardStdout = opts?.mode === 'text' && opts.discardStdout === true;
         // Deliver the prompt on stdin, not argv. A large prompt — an inlined design
         // doc, say — exceeds the OS argv ceiling and the spawn fails outright rather
@@ -253,12 +259,13 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                 // group already gone
             }
         };
-        // One kill path, shared by user-abort and loop-kill: SIGTERM, then SIGKILL
-        // after a grace period if the child ignored the term. For a group-owning
-        // (model) child, ALSO sweep the group so anything it backgrounded dies with
-        // it — proc.kill hits only the leader, reapGroup the grandchildren.
-        const killProc = () => {
-            aborted = true;
+        // One kill path for every source: SIGTERM, then SIGKILL after a grace
+        // period if the child ignored the term. For a group-owning (model) child,
+        // ALSO sweep the group so anything it backgrounded dies with it —
+        // proc.kill hits only the leader, reapGroup the grandchildren. The FIRST
+        // cause wins: a stall kill's SIGTERM can trip the abort path behind it.
+        const killProc = (cause) => {
+            kill ??= cause;
             proc.kill('SIGTERM');
             if (ownGroup)
                 reapGroup('SIGTERM');
@@ -274,15 +281,11 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         // below structurally cannot catch. Suspended for the duration of a tool
         // call: a 12-minute build legitimately emits nothing, and that window is
         // the COMMAND watchdog's to police, not this one's.
-        let streamStalledIdleMs;
         const streamWatch = opts?.mode === 'json-events' && (opts.streamInactivityMs ?? 0) > 0 ?
             new StreamWatchdog({
                 getTimeoutMs: () => opts.streamInactivityMs,
                 ...realStreamTimerDeps,
-                onFire: idleMs => {
-                    streamStalledIdleMs = idleMs;
-                    killProc();
-                }
+                onFire: idleMs => killProc({ by: 'stream-stall', idleMs })
             })
             : null;
         streamWatch?.start();
@@ -307,41 +310,21 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                     }
                 }
                 : opts;
-        const sink = sinkOpts ? new JsonEventSink(sinkOpts, killProc) : null;
-        // Dead-backend stall guard (json-events children only; see the option
-        // docs). Any output resets the window; a reachable probe also resets it
-        // so the next probe is a full window away, not every tick.
+        const sink = sinkOpts ? new JsonEventSink(sinkOpts, hit => killProc({ by: 'loop', hit })) : null;
+        // Dead-backend stall guard (json-events children only; see the option docs).
         const stall = opts?.mode === 'json-events' ? opts.stall : undefined;
-        let lastActivity = Date.now();
-        let stalled = false;
-        let probing = false;
-        const stallTimer = stall ?
-            setInterval(() => {
-                if (probing || Date.now() - lastActivity < stall.afterMs)
-                    return;
-                probing = true;
-                stall
-                    .probe()
-                    .then(reachable => {
-                    probing = false;
-                    if (reachable || stalled) {
-                        lastActivity = Date.now();
-                        return;
-                    }
-                    stalled = true;
-                    killProc();
-                })
-                    .catch(() => {
-                    // A probe that itself crashed proves nothing —
-                    // benefit of the doubt, keep waiting.
-                    probing = false;
-                    lastActivity = Date.now();
-                });
-            }, Math.max(50, Math.min(stall.afterMs / 2, 15_000)))
-            : undefined;
+        const stallProbe = stall ?
+            new StallProbe({
+                afterMs: stall.afterMs,
+                probe: stall.probe,
+                ...realStallTimerDeps,
+                onDead: () => killProc({ by: 'stalled' })
+            })
+            : null;
+        stallProbe?.start();
         let firstByteFired = false;
         proc.stdout?.on('data', (d) => {
-            lastActivity = Date.now();
+            stallProbe?.note();
             streamWatch?.note();
             if (!firstByteFired) {
                 firstByteFired = true;
@@ -378,10 +361,11 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         // research-worker slices the TAIL of stderr in two places and the HEAD in a
         // third, and child-runner feeds the whole string into its failure message.
         proc.stderr?.on('data', (d) => {
-            lastActivity = Date.now();
+            stallProbe?.note();
             streamWatch?.note();
             stderr += d.toString();
         });
+        const onAbort = () => killProc(abortCause(signal?.reason));
         // One idempotent settle path for close/error/abort. Detaching the abort
         // listener here is the point. `{once: true}` fires-and-removes on an ACTUAL
         // abort and at no other time, so a child that finishes normally leaves its
@@ -394,10 +378,9 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         // the caller's callbacks close over.
         let settled = false;
         const cleanup = () => {
-            if (stallTimer)
-                clearInterval(stallTimer);
+            stallProbe?.stop();
             streamWatch?.stop();
-            signal?.removeEventListener('abort', killProc);
+            signal?.removeEventListener('abort', onAbort);
         };
         const settle = (result) => {
             cleanup();
@@ -422,23 +405,26 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                 stdout,
                 stderr,
                 exitCode: code ?? 0,
-                aborted,
+                aborted: kill !== undefined,
+                ...(kill ? { kill } : {}),
                 text,
-                modelError: sink?.modelError,
-                ...(stalled ? { stalled: true } : {}),
-                ...(streamStalledIdleMs !== undefined ?
-                    { streamStalled: { idleMs: streamStalledIdleMs } }
-                    : {})
+                modelError: sink?.modelError
             });
         });
         proc.once('error', () => {
-            settle({ stdout, stderr, exitCode: 1, aborted });
+            settle({
+                stdout,
+                stderr,
+                exitCode: 1,
+                aborted: kill !== undefined,
+                ...(kill ? { kill } : {})
+            });
         });
         if (signal) {
             if (signal.aborted)
-                killProc();
+                onAbort();
             else
-                signal.addEventListener('abort', killProc, { once: true });
+                signal.addEventListener('abort', onAbort, { once: true });
         }
     });
 }