@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/shared/model-endpoint.js

@@ -2,18 +2,18 @@
  * model-endpoint — discovery + reachability probe for the model backend(s) a
  * child pi process talks to.
  *
- * The failure this serves (mx5 run 7, validated): the model server went down
- * mid-gate-child and the child hung MUTE for 64 minutes — pi's own
- * connection-error handling only fires when a request FAILS, not when the
- * backend freezes and the open request simply never answers. The stall guard in
- * runChild uses this module to tell the two apart: no output could be honest
- * long work (prompt processing emits nothing for minutes), so only "no output
- * AND the endpoint does not answer" is treated as a dead backend.
+ * The failure this serves: the model server dies mid-child and the child hangs
+ * mute. pi's own connection-error handling cannot help, because it runs from a
+ * catch — a request that FAILS reaches it, a request that simply never answers
+ * does not. The stall guard in runChild uses this module to tell the two apart:
+ * silence alone could be honest long work, since prompt processing emits nothing
+ * while it runs, so only "no output AND the endpoint does not answer" counts as
+ * a dead backend.
  *
- * Discovery is generic: the custom providers pi itself is configured with
- * (models.json `providers.*.baseUrl`), no provider or server names hardcoded.
- * No discoverable endpoint → nothing to probe → the guard NEVER kills (a child
- * on a backend we cannot see must get the benefit of the doubt).
+ * Discovery is generic — the custom providers pi is configured with, read from
+ * models.json `providers.*.baseUrl`, with no provider or server name hardcoded.
+ * No discoverable endpoint means nothing to probe, and the guard then NEVER
+ * kills: a child on a backend we cannot see gets the benefit of the doubt.
  */
 import * as fs from 'node:fs';
 import * as os from 'node:os';
@@ -34,9 +34,13 @@ export function discoverModelEndpoints(agentDir = path.join(os.homedir(), '.pi',
     }
 }
 /**
- * true → at least one endpoint ANSWERED (any HTTP status counts — a 404 still
- * proves the server is alive); false → every probe was refused or hung past the
- * timeout. An empty list is true: nothing to probe means never kill.
+ * true → at least one endpoint ANSWERED. Any HTTP status counts, because the
+ * question is liveness, not correctness: probing a path that 404s still returns
+ * true, while a closed port returns false. Both confirmed against a live server.
+ * An empty list is true — nothing to probe means never kill.
+ *
+ * `models` is joined RELATIVELY here, and deliberately: it lives under the
+ * OpenAI-compatible prefix a baseUrl already carries. Contrast `/props` below.
  */
 export async function probeModelEndpoints(urls, timeoutMs = 5_000) {
     if (urls.length === 0)
@@ -59,14 +63,22 @@ export async function probeModelEndpoints(urls, timeoutMs = 5_000) {
  * answer worth having" — not a llama.cpp server, unreachable, or a body in a
  * shape this does not recognise.
  *
- * `null` is a first-class result, not an error: every non-llama.cpp backend
- * returns it, and the caller must degrade to the models.json view rather than
- * warn about a server it could not read. Never throws.
+ * `null` is a first-class result, not an error: a backend that does not serve
+ * this shape returns it, and the caller must degrade to the models.json view
+ * rather than warn about a server it could not read. Never throws — a closed
+ * port answers `null`, confirmed.
+ *
+ * The LEADING SLASH in `/props` is load-bearing, because `/props` lives at the
+ * server ROOT while a configured baseUrl carries an OpenAI-compatible prefix.
+ * How a relative `'props'` resolves depends on whether that prefix ends in a
+ * slash, which is not something this can rely on:
+ *
+ *     new URL('props',  'http://host/v1')   →  /props
+ *     new URL('props',  'http://host/v1/')  →  /v1/props     ← 404
+ *     new URL('/props', either)             →  /props
  *
- * The LEADING SLASH in `/props` is load-bearing. A configured baseUrl normally
- * ends in `/v1` (llama-server's OpenAI-compatible prefix) while `/props` lives at
- * the server root, so a relative `'props'` would resolve to `/v1/props` and 404 —
- * which this would report as `null`, i.e. as a silent loss of the better signal.
+ * A 404 would come back from here as `null`, silently losing the better signal.
+ * The absolute form is right for both.
  */
 export async function probeChatTemplateCaps(baseUrl, timeoutMs = 2_000) {
     try {

package/dist/shared/pi-invocation.d.ts

@@ -1,11 +1,14 @@
 /** Pick the right way to re-invoke pi: prefer the current pi script under the
- *  current node/bun runtime; fall back to the `pi` shim on PATH. Mirrors the
- *  pattern from pi-coding-agent's official subagent example.
+ *  current node/bun runtime; fall back to the `pi` shim on PATH. This mirrors
+ *  pi's own subagent example, which ships a function of the same name and the
+ *  same three-step shape in `examples/extensions/subagent/index.ts`. What is
+ *  added here is the `PI_BIN` override, the `/$bunfs/root/` guard, and `stdin`.
  *
  *  `stdin`, when given, is the prompt to feed the child over stdin instead of as
  *  an argv element — pi reads its prompt from stdin when no positional message
- *  is passed, which keeps a large prompt off the length-limited command line
- *  (see runChild / GitHub issue #1). It is threaded through unchanged. */
+ *  is passed, which keeps a large prompt off the argv ceiling that would
+ *  otherwise fail the spawn outright (see runChild). It is threaded through
+ *  unchanged: every branch below returns it as given. */
 export declare function getPiInvocation(args: string[], stdin?: string): {
     command: string;
     args: string[];

package/dist/shared/pi-invocation.js

@@ -1,17 +1,22 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 /** Pick the right way to re-invoke pi: prefer the current pi script under the
- *  current node/bun runtime; fall back to the `pi` shim on PATH. Mirrors the
- *  pattern from pi-coding-agent's official subagent example.
+ *  current node/bun runtime; fall back to the `pi` shim on PATH. This mirrors
+ *  pi's own subagent example, which ships a function of the same name and the
+ *  same three-step shape in `examples/extensions/subagent/index.ts`. What is
+ *  added here is the `PI_BIN` override, the `/$bunfs/root/` guard, and `stdin`.
  *
  *  `stdin`, when given, is the prompt to feed the child over stdin instead of as
  *  an argv element — pi reads its prompt from stdin when no positional message
- *  is passed, which keeps a large prompt off the length-limited command line
- *  (see runChild / GitHub issue #1). It is threaded through unchanged. */
+ *  is passed, which keeps a large prompt off the argv ceiling that would
+ *  otherwise fail the spawn outright (see runChild). It is threaded through
+ *  unchanged: every branch below returns it as given. */
 export function getPiInvocation(args, stdin) {
-    // Test/dev override: point at a specific pi binary directly. Bypasses the
-    // re-invoke-current-script heuristic, which goes wrong under `bun test`
-    // (currentScript is the .test.ts file, not a pi entrypoint).
+    // Test/dev override: point at a specific pi binary directly. It bypasses the
+    // re-invoke-current-script heuristic below, which goes wrong under the test
+    // runner — confirmed by printing it from inside a test, where `process.argv[1]`
+    // is the `.test.ts` file itself. Without this the child would be the runtime
+    // re-running a test file, not pi.
     if (process.env.PI_BIN) {
         return { command: process.env.PI_BIN, args, stdin };
     }

package/dist/shared/pkg-version.d.ts

@@ -1,8 +1,16 @@
 /**
- * The installed pi-task version, read from package.json at runtime so nothing
- * has to be regenerated on release. Two levels up holds for both src/<dir>
- * (tests) and dist/<dir> (build), since tsc preserves the layout under rootDir.
- * Falls back to '0.0.0' rather than throwing: every caller here is cosmetic
- * (a User-Agent, a title bar) and none is worth failing over.
+ * The installed pi-task version, read from package.json on every call so no
+ * build step has to bake it in and nothing needs regenerating on release.
+ *
+ * Two levels up is right for BOTH trees: `src/<dir>/../..` and `dist/<dir>/../..`
+ * each land on the package root, because tsconfig.build.json sets
+ * `rootDir: "src"` and tsc therefore reproduces the directory layout under dist.
+ * Called from each, both answer the version package.json declares.
+ *
+ * There are two ways to reach the '0.0.0' fallback and neither throws: an absent
+ * or unreadable package.json is caught, and a `version` that is not a string
+ * fails the typeof guard. Both were run. Throwing would be wrong for what the
+ * two callers do with it — one builds a fetch User-Agent, the other the title on
+ * the /task-config settings box. Neither is worth failing a session over.
  */
 export declare function readPkgVersion(): string;

package/dist/shared/pkg-version.js

@@ -2,11 +2,19 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 /**
- * The installed pi-task version, read from package.json at runtime so nothing
- * has to be regenerated on release. Two levels up holds for both src/<dir>
- * (tests) and dist/<dir> (build), since tsc preserves the layout under rootDir.
- * Falls back to '0.0.0' rather than throwing: every caller here is cosmetic
- * (a User-Agent, a title bar) and none is worth failing over.
+ * The installed pi-task version, read from package.json on every call so no
+ * build step has to bake it in and nothing needs regenerating on release.
+ *
+ * Two levels up is right for BOTH trees: `src/<dir>/../..` and `dist/<dir>/../..`
+ * each land on the package root, because tsconfig.build.json sets
+ * `rootDir: "src"` and tsc therefore reproduces the directory layout under dist.
+ * Called from each, both answer the version package.json declares.
+ *
+ * There are two ways to reach the '0.0.0' fallback and neither throws: an absent
+ * or unreadable package.json is caught, and a `version` that is not a string
+ * fails the typeof guard. Both were run. Throwing would be wrong for what the
+ * two callers do with it — one builds a fetch User-Agent, the other the title on
+ * the /task-config settings box. Neither is worth failing a session over.
  */
 export function readPkgVersion() {
     try {

package/dist/shared/reasoning-capability.d.ts

@@ -3,31 +3,38 @@
  *
  * WHY A LOCAL COPY OF PI'S CLAMP
  * ------------------------------
- * pi never reports that it ignored or downgraded a level. Measured live against
- * this machine's llama-server, with a proxy capturing the request body:
+ * pi does not report that it ignored or downgraded a level. Captured on the wire,
+ * with a logging proxy between pi and the model server. All three runs completed
+ * normally and printed no warning of any kind:
  *
  *   1. a model with `reasoning: false` + `--thinking medium`
- *        → the body carries NO reasoning field at all. No error, no warning.
- *   2. `thinkingLevelMap: {off: null, ...}` + `--thinking off`
- *        → silently clamped UP to `medium`. Thinking stays on.
+ *        → the request body carries NO reasoning field and no
+ *          `chat_template_kwargs`. The level is erased, not refused.
+ *   2. `thinkingLevelMap: {off: null, …}` + `--thinking off`
+ *        → thinking STAYS ON: the body arrives with
+ *          `chat_template_kwargs.enable_thinking: true`. The clamp walks UP one
+ *          rung at a time, so `off` lands on `minimal` — not on `medium`.
  *   3. `--thinking low` where `low: null`
- *        → silently clamped to `medium`.
+ *        → `medium` on the wire.
  *
  * All three are the same arithmetic, and it is pure: `getSupportedThinkingLevels`
- * / `clampThinkingLevel` in @earendil-works/pi-ai's models module. Reproducing it
+ * / `clampThinkingLevel` in @earendil-works/pi-ai's `models.js`. Reproducing it
  * lets one predicate — `clampToModel(m, wanted) !== wanted` — catch all three
  * host-side, before a single request is sent.
  *
  * Reimplemented rather than imported because `@earendil-works/pi-ai` is neither a
- * dependency nor a peerDependency of pi-task: it is present only because
- * pi-coding-agent hoists it, so importing it would take a hard dependency on a
- * transitive package to get twenty lines of arithmetic. SOURCE OF TRUTH is that
- * module; `reasoning-capability.test.ts` is where a change upstream shows up.
+ * dependency, a devDependency nor a peerDependency of pi-task — it is in none of
+ * the three, and sits in node_modules only because pi-coding-agent depends on it.
+ * Importing it would take a hard dependency on a transitive package for twenty
+ * lines of arithmetic. SOURCE OF TRUTH is that module, and what follows is
+ * line-for-line identical to it, ladder included. Nothing here imports pi-ai, so
+ * an upstream change will not fail a test — the two have to be re-compared.
  */
 import { type ReasoningGroup, type GroupSetting } from '../config/reasoning.js';
 /**
- * pi's own level ladder, in order. The order is the whole algorithm: an
- * unsupported level is resolved by walking UP first, then down.
+ * pi's own level ladder, in order — the same seven names, in the same sequence,
+ * as `EXTENDED_THINKING_LEVELS` in pi-ai's models.js. The order IS the algorithm:
+ * an unsupported level is resolved by walking UP first, then down.
  */
 export declare const THINKING_LADDER: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 export type LadderLevel = (typeof THINKING_LADDER)[number];
@@ -48,9 +55,11 @@ export interface ReasoningModelFacts {
  *    1: the knob is not rejected, it is erased.
  *  - a MISSING map entry means "supported" for the standard levels but
  *    "unsupported" for `xhigh` / `max`, which are opt-in and must be declared.
- *    This is why config/reasoning.ts does not offer those two: a model with no
- *    map at all would receive the raw string, and Qwen3.8's chat template
- *    answers an unknown effort with HTTP 500 rather than a clamp.
+ *    This is why config/reasoning.ts offers neither: without a map the raw
+ *    string reaches the server, and a chat template that does not know the level
+ *    fails rather than clamping. Confirmed against a live server — an effort
+ *    string its template does not handle comes back HTTP 500, raised from inside
+ *    the template itself, while one it does handle returns 200.
  */
 export declare function supportedThinkingLevels(model: ReasoningModelFacts): LadderLevel[];
 /**
@@ -69,15 +78,17 @@ export interface ReasoningMismatch {
 /**
  * Every group whose setting the model will silently change.
  *
- * `inherit` groups are skipped entirely, and that is what keeps a default
- * install permanently quiet: with the shipped all-`inherit` table this returns
- * an empty array for every model, including one with no reasoning at all.
+ * `inherit` groups are skipped entirely, because an inherited group asks for
+ * nothing. That is not the same as a quiet default: the shipped table is mostly
+ * DECIDED, with a single cell left on `inherit`, so a default install is not
+ * silent. Run against a `reasoning: false` model it reports a mismatch for every
+ * group whose level that model cannot honour.
  *
  * It reports mismatches in BOTH directions, which is wider than "warn when
- * reasoning is on but unsupported". The failure actually captured on this
- * machine is the mirror of that — `off` clamped UP to `medium`, so a user who
- * turned thinking off still pays for it — and it is the same comparison. Warning
- * about one direction while staying silent about the other would ship this
- * feature with its own measured failure mode unreported.
+ * reasoning is on but unsupported". The mirror case is the one captured on the
+ * wire — `off` clamped UP with `enable_thinking: true` still going out, so a
+ * user who turned thinking off still pays for it — and it is the same
+ * comparison. Warning about one direction while staying silent about the other
+ * would ship this feature unable to see its own failure mode.
  */
 export declare function reasoningMismatches(model: ReasoningModelFacts | undefined, levels: Readonly<Record<ReasoningGroup, GroupSetting>>): ReasoningMismatch[];

package/dist/shared/reasoning-capability.js

@@ -3,31 +3,38 @@
  *
  * WHY A LOCAL COPY OF PI'S CLAMP
  * ------------------------------
- * pi never reports that it ignored or downgraded a level. Measured live against
- * this machine's llama-server, with a proxy capturing the request body:
+ * pi does not report that it ignored or downgraded a level. Captured on the wire,
+ * with a logging proxy between pi and the model server. All three runs completed
+ * normally and printed no warning of any kind:
  *
  *   1. a model with `reasoning: false` + `--thinking medium`
- *        → the body carries NO reasoning field at all. No error, no warning.
- *   2. `thinkingLevelMap: {off: null, ...}` + `--thinking off`
- *        → silently clamped UP to `medium`. Thinking stays on.
+ *        → the request body carries NO reasoning field and no
+ *          `chat_template_kwargs`. The level is erased, not refused.
+ *   2. `thinkingLevelMap: {off: null, …}` + `--thinking off`
+ *        → thinking STAYS ON: the body arrives with
+ *          `chat_template_kwargs.enable_thinking: true`. The clamp walks UP one
+ *          rung at a time, so `off` lands on `minimal` — not on `medium`.
  *   3. `--thinking low` where `low: null`
- *        → silently clamped to `medium`.
+ *        → `medium` on the wire.
  *
  * All three are the same arithmetic, and it is pure: `getSupportedThinkingLevels`
- * / `clampThinkingLevel` in @earendil-works/pi-ai's models module. Reproducing it
+ * / `clampThinkingLevel` in @earendil-works/pi-ai's `models.js`. Reproducing it
  * lets one predicate — `clampToModel(m, wanted) !== wanted` — catch all three
  * host-side, before a single request is sent.
  *
  * Reimplemented rather than imported because `@earendil-works/pi-ai` is neither a
- * dependency nor a peerDependency of pi-task: it is present only because
- * pi-coding-agent hoists it, so importing it would take a hard dependency on a
- * transitive package to get twenty lines of arithmetic. SOURCE OF TRUTH is that
- * module; `reasoning-capability.test.ts` is where a change upstream shows up.
+ * dependency, a devDependency nor a peerDependency of pi-task — it is in none of
+ * the three, and sits in node_modules only because pi-coding-agent depends on it.
+ * Importing it would take a hard dependency on a transitive package for twenty
+ * lines of arithmetic. SOURCE OF TRUTH is that module, and what follows is
+ * line-for-line identical to it, ladder included. Nothing here imports pi-ai, so
+ * an upstream change will not fail a test — the two have to be re-compared.
  */
 import { REASONING_GROUPS } from '../config/reasoning.js';
 /**
- * pi's own level ladder, in order. The order is the whole algorithm: an
- * unsupported level is resolved by walking UP first, then down.
+ * pi's own level ladder, in order — the same seven names, in the same sequence,
+ * as `EXTENDED_THINKING_LEVELS` in pi-ai's models.js. The order IS the algorithm:
+ * an unsupported level is resolved by walking UP first, then down.
  */
 export const THINKING_LADDER = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
 /**
@@ -38,9 +45,11 @@ export const THINKING_LADDER = ['off', 'minimal', 'low', 'medium', 'high', 'xhig
  *    1: the knob is not rejected, it is erased.
  *  - a MISSING map entry means "supported" for the standard levels but
  *    "unsupported" for `xhigh` / `max`, which are opt-in and must be declared.
- *    This is why config/reasoning.ts does not offer those two: a model with no
- *    map at all would receive the raw string, and Qwen3.8's chat template
- *    answers an unknown effort with HTTP 500 rather than a clamp.
+ *    This is why config/reasoning.ts offers neither: without a map the raw
+ *    string reaches the server, and a chat template that does not know the level
+ *    fails rather than clamping. Confirmed against a live server — an effort
+ *    string its template does not handle comes back HTTP 500, raised from inside
+ *    the template itself, while one it does handle returns 200.
  */
 export function supportedThinkingLevels(model) {
     if (!model.reasoning)
@@ -80,16 +89,18 @@ export function clampToModel(model, level) {
 /**
  * Every group whose setting the model will silently change.
  *
- * `inherit` groups are skipped entirely, and that is what keeps a default
- * install permanently quiet: with the shipped all-`inherit` table this returns
- * an empty array for every model, including one with no reasoning at all.
+ * `inherit` groups are skipped entirely, because an inherited group asks for
+ * nothing. That is not the same as a quiet default: the shipped table is mostly
+ * DECIDED, with a single cell left on `inherit`, so a default install is not
+ * silent. Run against a `reasoning: false` model it reports a mismatch for every
+ * group whose level that model cannot honour.
  *
  * It reports mismatches in BOTH directions, which is wider than "warn when
- * reasoning is on but unsupported". The failure actually captured on this
- * machine is the mirror of that — `off` clamped UP to `medium`, so a user who
- * turned thinking off still pays for it — and it is the same comparison. Warning
- * about one direction while staying silent about the other would ship this
- * feature with its own measured failure mode unreported.
+ * reasoning is on but unsupported". The mirror case is the one captured on the
+ * wire — `off` clamped UP with `enable_thinking: true` still going out, so a
+ * user who turned thinking off still pays for it — and it is the same
+ * comparison. Warning about one direction while staying silent about the other
+ * would ship this feature unable to see its own failure mode.
  */
 export function reasoningMismatches(model, levels) {
     // No model resolved yet (session still starting, or none selected): say

package/dist/shared/stream-watchdog.d.ts

@@ -2,25 +2,30 @@
  * Model-stream watchdog — the inactivity machine for a stream that goes SILENT
  * without erroring.
  *
- * WHY (mx5 run 14): three main-session implementation turns died mid-turn — the
- * session jsonl's last event is an ordinary assistant message, then nothing,
- * forever, while the model server stayed Up(healthy) the whole time. A hung or
- * silently-dropped stream throws NOTHING, so:
- *   - the connection-error retry (child-runner.ts) never fires: it needs a
- *     thrown/reported ModelError,
- *   - the command watchdog never fires: it only covers TOOL executions,
- *   - the child stall guard never fires: it treats a reachable endpoint as proof
- *     of life, which it is — the endpoint was fine, the stream was not.
- * Cost in run 14: ~2.9h of dead air awaiting manual restarts.
+ * WHY: a turn can die mid-stream — the last thing recorded is an ordinary
+ * assistant message, then nothing, while the model server stays healthy. A hung
+ * or silently-dropped stream throws NOTHING, so none of the three guards that
+ * already exist can see it:
+ *   - the connection-error retry never fires. child-runner reaches it only
+ *     inside `if (r.modelError)`, and a silent hang reports no error at all.
+ *   - the command watchdog never fires: it arms per tool call and covers only
+ *     TOOL executions.
+ *   - the child stall guard never fires: it kills only when a probe finds the
+ *     endpoint UNREACHABLE, and here the endpoint answers fine. The stream is
+ *     what died, not the server.
  *
- * WHAT THIS MEASURES: time since the LAST stream event of ANY kind — text token,
- * tool-call delta, thinking delta, provider response header. NOT wall-clock, and
- * NOT "time to first token". One token every 30s is a working local model and
- * must never be killed; zero events for the whole window is a hang.
+ * WHAT THIS MEASURES: time since the last sign of life, NOT wall-clock and NOT
+ * time-to-first-token. What counts as a sign differs by surface — for the main
+ * session it is any of six pi events (`before_provider_request`,
+ * `after_provider_response`, `turn_start`, `message_start`, `message_update`,
+ * `message_end`), with every text, thinking and tool-call delta arriving as
+ * `message_update`; for a child it is any stdout or stderr CHUNK. A slow model
+ * that emits something occasionally is working and must never be killed. Zero
+ * for the whole window is a hang.
  *
- * WHY THE DEFAULT IS GENEROUS: on a local llama-server a 32k-context prompt can
- * spend many minutes in prompt processing emitting nothing at all. A 60-120s
- * ceiling would kill every long prompt on local hardware. See
+ * WHY THE DEFAULT IS GENEROUS: prompt processing legitimately emits nothing
+ * while it runs, so a tight ceiling would kill honest long prompts. This guard
+ * exists to bound dead air, not to police slowness. See
  * DEFAULT_STREAM_INACTIVITY_MS.
  *
  * TWO SURFACES, one machine (same split as command-watchdog.ts):
@@ -38,15 +43,19 @@
 import type { TimerHandle } from './command-watchdog.js';
 export type { TimerHandle };
 /**
- * Default inactivity ceiling: 10 minutes. Chosen from the constraint that a local
- * model's first token can legitimately be many minutes away — the guard exists to
- * turn hours of dead air into minutes, not to police slowness.
+ * Default inactivity ceiling. Sized by the constraint that a local model's first
+ * token can legitimately be a long way off, so the number has to clear honest
+ * prompt processing rather than sit close to it.
  */
 export declare const DEFAULT_STREAM_INACTIVITY_MS: number;
 /**
- * How often the machine checks the idle clock. A poll (rather than re-arming a
- * timeout on every token) keeps cost O(1) per window instead of O(1) per token —
- * a streaming turn emits thousands of events. Same idiom as the child stall guard.
+ * How often the machine checks the idle clock. A poll, rather than re-arming a
+ * timeout on every token, keeps the cost per window constant instead of per
+ * event — and "thousands of events" is not a figure of speech: one captured turn
+ * emitted over two thousand, nearly all of them `message_update`.
+ *
+ * A quarter of the window, clamped: never tighter than 50ms, never looser than
+ * 30s. The child stall guard polls with the same shape and its own divisor.
  */
 export declare function pollIntervalMs(timeoutMs: number): number;
 export interface StreamWatchdogDeps {
@@ -69,12 +78,14 @@ export declare class StreamWatchdog {
      * legitimately idle, and that window belongs to the command watchdog, not to
      * this one — without it a 10-minute build looks identical to a hung stream.
      *
-     * A SET, not a boolean: pi runs a tool batch in parallel (agent-loop.js
-     * `executeToolCallsParallel` emits every tool_execution_start up front, then one
-     * end per call as each settles, and answers an immediate call inline while an
-     * earlier one is still running). A boolean would be cleared by the FIRST end and
-     * leave the still-running sibling — the long build — exposed to a false fire.
-     * Same per-toolCallId idiom the command watchdog uses.
+     * A SET, not a boolean, and pi's own loop is why. `executeToolCallsParallel`
+     * in agent-loop.js emits EVERY `tool_execution_start` up front, before any
+     * call is prepared; a call that prepares "immediate" gets its end emitted
+     * inline right there, while the rest are deferred as closures and settle
+     * through a `Promise.all`. So an end can arrive while earlier siblings are
+     * still running. A boolean would be cleared by that first end and leave the
+     * long build exposed to a false fire. Same per-toolCallId idiom the command
+     * watchdog uses.
      */
     private readonly active;
     /** Nesting depth for callers that cannot supply an id, counted so an unkeyed
@@ -107,27 +118,32 @@ export declare class StreamWatchdog {
  * cancels it on stop/fire, and runChild's cleanup() stops the watchdog on every
  * settle path (close, error, abort), so it cannot outlive the child it watches.
  *
- * The poll is REF'd, deliberately. It used to be unref'd, on the reasoning that a
- * pending watchdog poll should never keep the process alive at exit — but under
- * Bun on WINDOWS an unref'd timer does not fire at all once nothing ref'd is
- * pending. Measured on a windows-latest runner (bun 1.3.14): an unref'd interval
- * with nothing else pending never fired in 20s, while the identical ref'd one
- * fired at 101ms; on linux both fire at 100ms.
+ * The poll is REF'd, deliberately. Unref'd reads better — a pending watchdog poll
+ * should never keep the process alive at exit — but an unref'd timer is only
+ * guaranteed to fire while something ref'd is still pending, and that guarantee
+ * is not the platform-independent thing it looks like.
+ *
+ * Measured here, on both runtimes: with nothing else pending an unref'd timer
+ * never fires at all, the process just exits; with a spawned child holding its
+ * stdout and stderr pipes open it fires on schedule throughout. A silent child
+ * is the SECOND case — its pipes are still ref'd work — so on this platform the
+ * unref would not have broken the child guard. The reason to keep it ref'd is
+ * that this machine also runs in the main session, where no such handle is
+ * guaranteed, and the failure mode is silent: a watchdog that never fires looks
+ * exactly like a stream that never hung.
  *
- * That state — no ref'd work outstanding — is EXACTLY the state this watchdog
- * exists to police: a child whose model stream has gone silent. So the unref
- * disabled the guard precisely when it was needed, and every stream-stall
- * integration test hung forever on windows (CI runs 30476786365, 30477802633,
- * 30478455402 — it hangs at v0.24.1 too, so this predates that release).
  * A poll that can delay exit by one interval is the cheaper failure.
  */
 export declare const realStreamTimerDeps: Pick<StreamWatchdogDeps, 'now' | 'schedule' | 'cancel'>;
 /**
  * The cause string a CHILD's stream stall is reported as. Phrased so
- * {@link isConnectionError} (child-runner.ts) matches it — the whole point is to
- * route a silent hang into the retry path that already exists for a LOUD
- * connection failure, rather than inventing a second one. Honest about who
- * killed it: pi-task aborted the request, the provider did not report anything.
+ * {@link isConnectionError} (child-runner.ts) matches it — checked by running the
+ * round-trip, and it does. The whole point is to route a silent hang into the
+ * retry path that already exists for a LOUD connection failure rather than
+ * inventing a second one, so the phrase "connection lost" is load-bearing, not
+ * decoration: reword it past that predicate and stream stalls stop retrying.
+ * Honest about who killed it, too — pi-task aborted the request, the provider
+ * reported nothing.
  */
 export declare function streamStallCause(idleMs: number): string;
 /**