@mjasnikovs/pi-task 0.18.37 → 0.18.38

package/README.md

@@ -65,7 +65,7 @@ A whole plan — `/task-auto` splits it into an ordered task list and runs each
 | `/task-auto <feature>` | Plan a feature into a task list and run each title through `/task` in order (resumable). |
 | `/task-auto-resume` | Resume the active `/task-auto` run at the next unfinished task. |
 | `/task-auto-cancel` | Stop the `/task-auto` loop after the current task (still resumable). |
-| `/task-config` | Toggle pi-task settings in an editor dialog: remote server, compress reasoning, auto-commit, orientation, verify work, enforce guidelines, command timeout, and the extension whitelist for child sessions. |
+| `/task-config` | Toggle pi-task settings in an editor dialog: remote server, compress reasoning, auto-commit, orientation, verify work, enforce guidelines, command timeout, stream watchdog, and the extension whitelist for child sessions. |
 | `/remote` | Show the QR code & URLs for the web view (`/remote stop` to stop). Answer grill questions, start tasks, and watch progress from your phone. |
 
 ## The pipeline
@@ -180,6 +180,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | **research cache** | on | Cache docs/search/fetch worker results for the duration of one `/task-auto` run so sibling tasks re-asking the same package/URL + query reuse the first pipeline's digest instead of re-fetching. Per-run isolated, external-only (project-source `.` lookups excluded), success-only. |
 | **search provider** | Exa | Engine behind `pi-worker-search` and freshness/enrichment checks. **Exa** (default) and **DuckDuckGo** need no API key; **Brave** requires `BRAVE_SEARCH_API_KEY`. |
 | **command timeout** | 15 min | Wall-clock ceiling on a **single** tool execution. Local models routinely run a command that never returns (a hung build, a dev server, a check with no timeout) and the run wedges until you abort by hand — pi's bash tool has an optional timeout with no default, so this is the missing one. One knob, two surfaces: in the main session the overrun call is cancelled (killing the tool's whole process tree) plus a reminder turn; in the verify/fix gate children the child is killed and re-spawned with a hint, halving the ceiling on repeat hangs. Choices: 5/10/15/30 min or **off** — off unguards both surfaces, gates included. |
+| **stream watchdog** | 10 min | Inactivity ceiling on the **model stream**. A hung or silently-dropped stream throws nothing at all, so neither the connection-error retry (it needs a reported error) nor the **command timeout** (tool calls only) nor the dead-backend stall guard (a reachable endpoint reads as proof of life) can see it — an mx5 run lost ~2.9h to three of them while the model server stayed healthy. Measured as time since the **last stream event of any kind**, so a slow model emitting one token every 30s is never touched, and it pauses while a tool runs. On expiry the main session aborts the turn (through the same channel the command watchdog uses) and posts a resume reminder; a child is killed and routed into the existing connection-error retry. Choices: 5/10/20/30 min or **off**. Keep it generous on local backends — prompt processing on a large context legitimately emits nothing for minutes. |
 | **yolo mode** | off | **Unattended runs.** Wherever pi-task would stop and ask, it takes the option already marked RECOMMENDED, stamps the artifact `(YOLO)` so an audit can tell a machine decided, and shows no prompt at all — clarify/grill answers, the verify-FAIL picker (auto-**Accept**, recorded as a yolo debt), and the final-gate picker (autofix while the budget lasts, then leave the run FAILED). A question with no recommendation is **skipped**, never invented. For throwaway/test projects nobody is watching; a real run should decide these itself. |
 | **extension whitelist** | empty | Host `pi` extensions to load into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. `/task-config` enumerates the currently installed extensions as individual `ext: …` toggles; the list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |
 

package/dist/config/config.d.ts

@@ -61,6 +61,26 @@ export interface PiTaskConfig {
      * a true hang doesn't cost half an hour of dead time.
      */
     requestTimeoutMs: number;
+    /**
+     * Inactivity ceiling (ms) on the MODEL STREAM before the stream watchdog
+     * aborts the request (shared/stream-watchdog.ts). A hung or silently-dropped
+     * stream throws nothing, so neither the connection-error retry (needs a
+     * reported error) nor the command watchdog (covers tool calls only) nor the
+     * child stall guard (a reachable endpoint is proof of life) can see it — mx5
+     * run 14 lost ~2.9h to three such hangs while the model server stayed healthy.
+     *
+     * Measured as time since the LAST stream event of any kind, so a slow model
+     * emitting one token every 30s is never touched; only total silence counts.
+     * Suspended while a tool executes — that window is the command watchdog's.
+     *
+     * ONE knob, TWO surfaces: the MAIN session aborts the turn through the same
+     * plumbing the command watchdog uses and posts a resume reminder; a CHILD is
+     * killed and its result routed into the EXISTING connection-error retry.
+     * 0 = off, on both surfaces.
+     * DEFAULT 10 min: local prompt processing on a 32k context legitimately emits
+     * nothing for minutes, so a 60-120s ceiling would kill healthy long prompts.
+     */
+    streamInactivityMs: number;
     /**
      * UNATTENDED AUTO-PICK (see task/yolo.ts): wherever pi-task would stop and ask,
      * take the option it already marks RECOMMENDED, stamp the artifact `(YOLO)` so
@@ -91,6 +111,18 @@ export declare const COMMAND_TIMEOUT_OPTIONS: ReadonlyArray<{
  * one of the offered choices so the watchdog never arms on a nonsense value.
  */
 export declare function sanitizeRequestTimeoutMs(value: unknown): number;
+/**
+ * The stream-watchdog choices offered by /task-config, in cycle order. Every
+ * option is minutes, not seconds: the failure this guards costs hours, and the
+ * legitimate silence it must tolerate (local prompt processing) is minutes.
+ */
+export declare const STREAM_INACTIVITY_OPTIONS: ReadonlyArray<{
+    label: string;
+    ms: number;
+}>;
+/** Same pinning as {@link sanitizeRequestTimeoutMs}: a hand-edited value that is
+ *  not one of the offered choices falls back to the default. */
+export declare function sanitizeStreamInactivityMs(value: unknown): number;
 /**
  * A hand-edited config can hold anything; keep only string entries so a stray
  * object/number can't reach the child argv as `-e [object Object]`.

package/dist/config/config.js

@@ -3,6 +3,7 @@ import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { isSearchProvider } from '../workers/search-types.js';
+import { DEFAULT_STREAM_INACTIVITY_MS } from '../shared/stream-watchdog.js';
 /**
  * The command-watchdog timeout choices offered by /task-config, newest-first in
  * the cycle order the picker shows. The stored config value is the ms number;
@@ -25,6 +26,25 @@ export function sanitizeRequestTimeoutMs(value) {
         value
         : DEFAULT_REQUEST_TIMEOUT_MS;
 }
+/**
+ * The stream-watchdog choices offered by /task-config, in cycle order. Every
+ * option is minutes, not seconds: the failure this guards costs hours, and the
+ * legitimate silence it must tolerate (local prompt processing) is minutes.
+ */
+export const STREAM_INACTIVITY_OPTIONS = [
+    { label: '5 min', ms: 5 * 60_000 },
+    { label: '10 min', ms: DEFAULT_STREAM_INACTIVITY_MS },
+    { label: '20 min', ms: 20 * 60_000 },
+    { label: '30 min', ms: 30 * 60_000 },
+    { label: 'off', ms: 0 }
+];
+/** Same pinning as {@link sanitizeRequestTimeoutMs}: a hand-edited value that is
+ *  not one of the offered choices falls back to the default. */
+export function sanitizeStreamInactivityMs(value) {
+    return STREAM_INACTIVITY_OPTIONS.some(o => o.ms === value) ?
+        value
+        : DEFAULT_STREAM_INACTIVITY_MS;
+}
 const DEFAULTS = {
     remote: true,
     compressReasoning: true,
@@ -39,6 +59,7 @@ const DEFAULTS = {
     searchProvider: 'exa',
     extensionWhitelist: [],
     requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
+    streamInactivityMs: DEFAULT_STREAM_INACTIVITY_MS,
     // OFF: auto-answering is for unattended throwaway runs only.
     yoloMode: false
 };
@@ -69,6 +90,7 @@ if (!G.loaded) {
             delete parsed.searchProvider;
         parsed.extensionWhitelist = sanitizeExtensionWhitelist(parsed.extensionWhitelist);
         parsed.requestTimeoutMs = sanitizeRequestTimeoutMs(parsed.requestTimeoutMs);
+        parsed.streamInactivityMs = sanitizeStreamInactivityMs(parsed.streamInactivityMs);
         // A hand-edited `"yoloMode": "false"` is a truthy string — it must not
         // silently switch a watched run into unattended auto-pick. Only a real
         // boolean counts; anything else falls back to the OFF default.

package/dist/config/register.js

@@ -1,7 +1,7 @@
 import { SettingsList, visibleWidth } from '@earendil-works/pi-tui';
 import { registerBridgeCommand } from '../remote/bridge.js';
 import { SEARCH_PROVIDERS, SEARCH_PROVIDER_LABELS, providerForLabel } from '../workers/search-types.js';
-import { COMMAND_TIMEOUT_OPTIONS, getConfig, saveConfig } from './config.js';
+import { COMMAND_TIMEOUT_OPTIONS, getConfig, saveConfig, STREAM_INACTIVITY_OPTIONS } from './config.js';
 import { listInstalledExtensions } from './extension-list.js';
 const CONFIG_TITLE = 'pi-task settings';
 /**
@@ -108,6 +108,19 @@ const ITEMS = [
         // Display human labels; the stored config value stays the ms number.
         values: COMMAND_TIMEOUT_OPTIONS.map(o => o.label)
     },
+    {
+        id: 'streamInactivityMs',
+        label: 'stream watchdog',
+        description: 'Abort and retry a model request whose stream goes SILENT for this long — a hung '
+            + 'or dropped stream reports no error at all, so nothing else catches it (mx5 run '
+            + '14 lost ~2.9h to three of them while the model server stayed healthy). Counts '
+            + 'time since the last stream event of any kind, so a slow model that keeps '
+            + 'emitting tokens is never touched, and it pauses while a tool runs. Keep it '
+            + 'generous on local backends: prompt processing on a large context legitimately '
+            + 'emits nothing for minutes. off disables it on both the main session and children',
+        // Display human labels; the stored config value stays the ms number.
+        values: STREAM_INACTIVITY_OPTIONS.map(o => o.label)
+    },
     {
         id: 'yoloMode',
         label: 'yolo mode',
@@ -123,12 +136,18 @@ const ITEMS = [
 function timeoutLabel(ms) {
     return COMMAND_TIMEOUT_OPTIONS.find(o => o.ms === ms)?.label ?? `${ms}ms`;
 }
+/** Human label for the stored stream-inactivity ms (falls back to the raw ms). */
+function streamTimeoutLabel(ms) {
+    return STREAM_INACTIVITY_OPTIONS.find(o => o.ms === ms)?.label ?? `${ms}ms`;
+}
 /** What /task-config shows for a setting's current value. */
 function displayValue(cfg, id, isEnum) {
     if (id === 'searchProvider')
         return SEARCH_PROVIDER_LABELS[cfg.searchProvider];
     if (id === 'requestTimeoutMs')
         return timeoutLabel(cfg.requestTimeoutMs);
+    if (id === 'streamInactivityMs')
+        return streamTimeoutLabel(cfg.streamInactivityMs);
     if (isEnum)
         return String(cfg[id]);
     return cfg[id] ? 'on' : 'off';
@@ -206,6 +225,11 @@ async function handleTaskConfig(_args, ctx) {
                 if (opt)
                     cfg.requestTimeoutMs = opt.ms;
             }
+            else if (id === 'streamInactivityMs') {
+                const opt = STREAM_INACTIVITY_OPTIONS.find(o => o.label === newValue);
+                if (opt)
+                    cfg.streamInactivityMs = opt.ms;
+            }
             else {
                 ;
                 cfg[id] = newValue === 'on';

package/dist/index.js

@@ -5,6 +5,7 @@ import { registerWorkers } from './workers/index.js';
 import { registerRemote } from './remote/register.js';
 import { registerThinkingCompression } from './thinking/compress.js';
 import { registerCommandWatchdog } from './task/command-watchdog.js';
+import { registerStreamWatchdog } from './task/stream-watchdog.js';
 export default function (pi) {
     registerConfig(pi);
     registerTask(pi);
@@ -13,4 +14,5 @@ export default function (pi) {
     registerRemote(pi);
     registerThinkingCompression(pi);
     registerCommandWatchdog(pi);
+    registerStreamWatchdog(pi);
 }

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

@@ -54,6 +54,17 @@ export interface ChildResult {
      * 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 —
+     * the run-14 hangs had 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;
@@ -124,6 +135,15 @@ export interface RunChildJsonEventsOptions {
         afterMs: number;
         probe: () => Promise<boolean>;
     };
+    /**
+     * Stream-inactivity ceiling in ms (shared/stream-watchdog.ts). Unlike `stall`
+     * this asks NOTHING of the backend: a stream that has produced no bytes for
+     * this long is dead whether or not the server answers a health probe, which
+     * is exactly the run-14 shape (server Up(healthy), stream silent for hours).
+     * Any stdout/stderr chunk resets it, so a slow model emitting one token every
+     * 30s is never killed. 0 / omitted = off.
+     */
+    streamInactivityMs?: number;
 }
 export type RunChildOptions = RunChildTextOptions | RunChildJsonEventsOptions;
 /**

package/dist/shared/child-process.js

@@ -1,4 +1,5 @@
 import { spawn as defaultSpawn, spawnSync as spawnSyncDefault } from 'node:child_process';
+import { realStreamTimerDeps, StreamWatchdog } from './stream-watchdog.js';
 /** Grace period between SIGTERM and SIGKILL (ms). */
 export const KILL_GRACE_MS = 5000;
 /** Base flags shared by all child pi invocations. */
@@ -248,7 +249,43 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                     reapGroup('SIGKILL');
             }, KILL_GRACE_MS);
         };
-        const sink = opts?.mode === 'json-events' ? new JsonEventSink(opts, killProc) : null;
+        // Stream watchdog (json-events children only): a silent stream is killed
+        // even when the backend is healthy — the case the probe-based stall guard
+        // 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();
+                }
+            })
+            : null;
+        streamWatch?.start();
+        // The sink sees the child's parsed events; tool start/end are what tell
+        // the watchdog to pause and resume. Wrapping the caller's handlers keeps
+        // that wiring invisible to callers — and onToolResult must be present for
+        // the sink to emit tool_execution_end at all, so it is always supplied
+        // when the watchdog is on.
+        const sinkOpts = opts?.mode !== 'json-events' ? null
+            : streamWatch ?
+                {
+                    ...opts,
+                    onToolCall: call => {
+                        streamWatch.suspend();
+                        return opts.onToolCall ? opts.onToolCall(call) : null;
+                    },
+                    onToolResult: r => {
+                        streamWatch.resume();
+                        opts.onToolResult?.(r);
+                    }
+                }
+                : 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.
@@ -283,6 +320,7 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         let firstByteFired = false;
         proc.stdout?.on('data', (d) => {
             lastActivity = Date.now();
+            streamWatch?.note();
             if (!firstByteFired) {
                 firstByteFired = true;
                 opts?.onFirstByte?.();
@@ -297,11 +335,13 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         });
         proc.stderr?.on('data', (d) => {
             lastActivity = Date.now();
+            streamWatch?.note();
             stderr += d.toString();
         });
         proc.on('close', (code) => {
             if (stallTimer)
                 clearInterval(stallTimer);
+            streamWatch?.stop();
             // The child has exited, but anything it backgrounded (a dev server) may
             // still hold its process group and a port — reap the group so the next
             // gate's boot check does not collide with our own orphan. Best-effort:
@@ -320,12 +360,16 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                 aborted,
                 text,
                 modelError: sink?.modelError,
-                ...(stalled ? { stalled: true } : {})
+                ...(stalled ? { stalled: true } : {}),
+                ...(streamStalledIdleMs !== undefined ?
+                    { streamStalled: { idleMs: streamStalledIdleMs } }
+                    : {})
             });
         });
         proc.on('error', () => {
             if (stallTimer)
                 clearInterval(stallTimer);
+            streamWatch?.stop();
             resolve({ stdout, stderr, exitCode: 1, aborted });
         });
         if (signal) {

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

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * DEFAULT_STREAM_INACTIVITY_MS.
+ *
+ * TWO SURFACES, one machine (same split as command-watchdog.ts):
+ *   MAIN SESSION — task/stream-watchdog.ts arms it from pi's extension events and
+ *                  fires ctx.abort() through the SAME abort plumbing the command
+ *                  watchdog uses (noteWatchdogAbort → steerUntilDone), so there is
+ *                  exactly one abort channel, not two racing ones.
+ *   CHILDREN     — shared/child-process.ts arms it on the child's stdout/stderr
+ *                  chunks; a fire kills the child and the result carries
+ *                  `streamStalled`, which child-runner turns into a
+ *                  connection-class cause so the EXISTING retry/backoff path
+ *                  handles it (re-spawn from the last durable prompt, never a
+ *                  blind re-send of a half-executed turn).
+ */
+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.
+ */
+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.
+ */
+export declare function pollIntervalMs(timeoutMs: number): number;
+export interface StreamWatchdogDeps {
+    /** The inactivity ceiling in ms, read when the watchdog arms. 0 (or any
+     *  non-positive value) means the watchdog is off and never arms. */
+    getTimeoutMs: () => number;
+    now: () => number;
+    schedule: (fn: () => void, ms: number) => TimerHandle;
+    cancel: (handle: TimerHandle) => void;
+    /** Invoked once per arming when the stream has been silent for the ceiling. */
+    onFire: (idleMs: number, timeoutMs: number) => void;
+}
+export declare class StreamWatchdog {
+    private readonly deps;
+    private timer;
+    private lastEvent;
+    private armedMs;
+    /** True while a TOOL is executing: the model stream is legitimately idle then,
+     *  and that window belongs to the command watchdog, not to this one. Without
+     *  this, a 10-minute build would look identical to a hung stream. */
+    private suspended;
+    private fired;
+    constructor(deps: StreamWatchdogDeps);
+    /** Begin watching a model request. No-op when the watchdog is off or already armed. */
+    start(): void;
+    /** Any stream event of any kind: resets the idle clock. */
+    note(): void;
+    /** A tool started executing — pause the idle clock until it ends. */
+    suspend(): void;
+    /** A tool finished — the stream is expected to resume; restart the clock. */
+    resume(): void;
+    /** Stop watching (turn/agent/session end, or child exit). Safe to call twice. */
+    stop(): void;
+    /** @internal Exposed for the poll callback and tests. */
+    check(): void;
+}
+/**
+ * Real-clock poll deps, unref'd so a pending watchdog poll can never itself keep
+ * the process alive on exit. `schedule` returns a repeating interval — the
+ * machine cancels it on stop/fire.
+ */
+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.
+ */
+export declare function streamStallCause(idleMs: number): string;
+/**
+ * MAIN-SESSION reminder, delivered as a follow-up turn after ctx.abort() ended the
+ * hung turn. Carries the shared WATCHDOG_CANCEL_MARKER so steerUntilDone
+ * recognises it as a watchdog recovery rather than a human ESC (see
+ * task/command-watchdog.ts) — one marker, one abort channel.
+ *
+ * Idempotent resume, not a re-send: the aborted turn's tool calls and their
+ * results are already in the transcript, so the model is told to CONTINUE from
+ * what is recorded. Re-issuing the turn wholesale would re-run tool calls that
+ * already ran.
+ */
+export declare function streamStallReminder(idleMs: number, marker: string): string;
+/**
+ * CHILD restart hint for a re-spawned worker whose previous attempt was killed by
+ * the stream watchdog. The killed child is gone and never saw an error, so this
+ * states plainly what happened and, unlike the command-timeout hint, does NOT
+ * blame the model: a hung stream is an infrastructure fault, and telling the model
+ * to "be faster" would teach it to truncate its work for no reason.
+ */
+export declare function streamStallHint(idleMs: number): string;

package/dist/shared/stream-watchdog.js

@@ -0,0 +1,182 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * DEFAULT_STREAM_INACTIVITY_MS.
+ *
+ * TWO SURFACES, one machine (same split as command-watchdog.ts):
+ *   MAIN SESSION — task/stream-watchdog.ts arms it from pi's extension events and
+ *                  fires ctx.abort() through the SAME abort plumbing the command
+ *                  watchdog uses (noteWatchdogAbort → steerUntilDone), so there is
+ *                  exactly one abort channel, not two racing ones.
+ *   CHILDREN     — shared/child-process.ts arms it on the child's stdout/stderr
+ *                  chunks; a fire kills the child and the result carries
+ *                  `streamStalled`, which child-runner turns into a
+ *                  connection-class cause so the EXISTING retry/backoff path
+ *                  handles it (re-spawn from the last durable prompt, never a
+ *                  blind re-send of a half-executed turn).
+ */
+/**
+ * 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.
+ */
+export const DEFAULT_STREAM_INACTIVITY_MS = 10 * 60_000;
+/** Whole minutes, floored at 1, for the human-facing window in every message. */
+function minutes(ms) {
+    const mins = Math.max(1, Math.round(ms / 60_000));
+    return `${mins} minute${mins === 1 ? '' : 's'}`;
+}
+/**
+ * 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.
+ */
+export function pollIntervalMs(timeoutMs) {
+    return Math.max(50, Math.min(Math.floor(timeoutMs / 4), 30_000));
+}
+export class StreamWatchdog {
+    deps;
+    timer;
+    lastEvent = 0;
+    armedMs = 0;
+    /** True while a TOOL is executing: the model stream is legitimately idle then,
+     *  and that window belongs to the command watchdog, not to this one. Without
+     *  this, a 10-minute build would look identical to a hung stream. */
+    suspended = false;
+    fired = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Begin watching a model request. No-op when the watchdog is off or already armed. */
+    start() {
+        if (this.timer !== undefined) {
+            // Already watching — a new request inside the same agent loop just
+            // counts as activity rather than restarting the machine.
+            this.note();
+            return;
+        }
+        const ms = this.deps.getTimeoutMs();
+        if (!(ms > 0))
+            return;
+        this.armedMs = ms;
+        this.fired = false;
+        this.suspended = false;
+        this.lastEvent = this.deps.now();
+        this.timer = this.deps.schedule(() => this.check(), pollIntervalMs(ms));
+    }
+    /** Any stream event of any kind: resets the idle clock. */
+    note() {
+        this.lastEvent = this.deps.now();
+    }
+    /** A tool started executing — pause the idle clock until it ends. */
+    suspend() {
+        this.suspended = true;
+    }
+    /** A tool finished — the stream is expected to resume; restart the clock. */
+    resume() {
+        this.suspended = false;
+        this.note();
+    }
+    /** Stop watching (turn/agent/session end, or child exit). Safe to call twice. */
+    stop() {
+        if (this.timer !== undefined)
+            this.deps.cancel(this.timer);
+        this.timer = undefined;
+        this.suspended = false;
+    }
+    /** @internal Exposed for the poll callback and tests. */
+    check() {
+        if (this.timer === undefined || this.fired || this.suspended)
+            return;
+        const idle = this.deps.now() - this.lastEvent;
+        if (idle < this.armedMs)
+            return;
+        this.fired = true;
+        const armed = this.armedMs;
+        this.stop();
+        this.deps.onFire(idle, armed);
+    }
+}
+/**
+ * Real-clock poll deps, unref'd so a pending watchdog poll can never itself keep
+ * the process alive on exit. `schedule` returns a repeating interval — the
+ * machine cancels it on stop/fire.
+ */
+export const realStreamTimerDeps = {
+    now: () => Date.now(),
+    schedule: (fn, ms) => {
+        const handle = setInterval(fn, ms);
+        if (typeof handle.unref === 'function') {
+            ;
+            handle.unref();
+        }
+        return handle;
+    },
+    cancel: handle => clearInterval(handle)
+};
+/**
+ * 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.
+ */
+export function streamStallCause(idleMs) {
+    return (`model stream inactivity: no stream events for ${minutes(idleMs)} — `
+        + `connection lost (aborted by pi-task's stream watchdog; the provider `
+        + `reported no error)`);
+}
+/**
+ * MAIN-SESSION reminder, delivered as a follow-up turn after ctx.abort() ended the
+ * hung turn. Carries the shared WATCHDOG_CANCEL_MARKER so steerUntilDone
+ * recognises it as a watchdog recovery rather than a human ESC (see
+ * task/command-watchdog.ts) — one marker, one abort channel.
+ *
+ * Idempotent resume, not a re-send: the aborted turn's tool calls and their
+ * results are already in the transcript, so the model is told to CONTINUE from
+ * what is recorded. Re-issuing the turn wholesale would re-run tool calls that
+ * already ran.
+ */
+export function streamStallReminder(idleMs, marker) {
+    return (`[SYSTEM] The model stream produced no events for ${minutes(idleMs)} — the response `
+        + `appeared to hang, so the turn ${marker} `
+        + `Nothing was reported as failed and no error was raised: the stream simply went `
+        + `silent, so any work the turn had ALREADY completed (tool calls and their results) `
+        + `is still recorded above and must NOT be repeated. Continue from that recorded `
+        + `state: re-read anything you are unsure about, then carry on with the remaining `
+        + `work. Do not restart the task from the beginning.`);
+}
+/**
+ * CHILD restart hint for a re-spawned worker whose previous attempt was killed by
+ * the stream watchdog. The killed child is gone and never saw an error, so this
+ * states plainly what happened and, unlike the command-timeout hint, does NOT
+ * blame the model: a hung stream is an infrastructure fault, and telling the model
+ * to "be faster" would teach it to truncate its work for no reason.
+ */
+export function streamStallHint(idleMs) {
+    return (`[SYSTEM NOTE: Your previous attempt was aborted because the model stream stopped `
+        + `producing output for ${minutes(idleMs)} — an infrastructure hang, not a mistake `
+        + `you made. That attempt's conversation is gone, but any file edits or command side `
+        + `effects it made are still in the working tree, so check the current state before `
+        + `assuming files are untouched. Redo the work from here.]`);
+}

package/dist/task/child-runner.js

@@ -12,6 +12,8 @@ import { childBaseArgs } from '../shared/child-extensions.js';
 import { LoopDetector } from './loop-detector.js';
 import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 import { readSection, setTaskSection } from './task-io.js';
+import { streamStallCause } from '../shared/stream-watchdog.js';
+import { getConfig } from '../config/config.js';
 // ─── Loop detection constants ────────────────────────────────────────────────
 // Defined here (not in phases.ts) to avoid a circular dependency:
 //   phases.ts → child-runner.ts → phases.ts
@@ -77,6 +79,11 @@ export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsag
     let loopHit;
     const result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, signal, {
         mode: 'json-events',
+        // A hung model stream reports nothing at all, so without this the
+        // phase child waits forever (mx5 run 14: ~2.9h of dead air). The kill
+        // is reported below as a connection-class cause, which routes it into
+        // the retry/backoff path this file already has for a LOUD disconnect.
+        streamInactivityMs: getConfig().streamInactivityMs,
         onLine,
         onContextUsage,
         onToolCall: call => {
@@ -95,12 +102,21 @@ export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsag
     // fails with the unhelpful "X child produced no output" — the raw
     // stdout/stderr that might contain the real error is discarded.
     const text = result.text || result.stdout.trim();
+    // The stream watchdog's kill leaves no provider error to report (that is the
+    // whole failure mode), so name it here rather than letting it surface as the
+    // meaningless "produced no output". Never overwrite a real reported cause.
+    const modelError = result.modelError
+        ?? (result.streamStalled ? streamStallCause(result.streamStalled.idleMs) : undefined);
     return {
         text,
-        exitCode: result.exitCode,
+        // WE killed this child, so its exit status describes our own SIGTERM, not
+        // the child's verdict. Report 0 and let `modelError` carry the cause —
+        // otherwise the wrappers' `exitCode !== 0` guard throws a bare "child
+        // failed" before the connection-error retry ever gets to look.
+        exitCode: result.streamStalled ? 0 : result.exitCode,
         stderr: result.stderr.trim(),
         loopHit,
-        modelError: result.modelError,
+        modelError,
         // A tool call the model wrote as text (wrong dialect) never executed and
         // sailed past the structured-event guards above; flag it so the wrappers
         // can re-prompt instead of accepting the unexecuted call. Only meaningful

package/dist/task/gate-deps.js

@@ -391,6 +391,11 @@ export function buildGateDeps(params) {
                     // ceiling the main session uses, so one /task-config knob
                     // covers implementation and gates alike.
                     commandTimeoutMs: getConfig().requestTimeoutMs,
+                    // Same reasoning one level up: a gate child with no
+                    // wall-clock cap also needs the HUNG-STREAM bound, which
+                    // the probe-based stall guard structurally cannot supply
+                    // (a healthy endpoint reads as proof of life).
+                    streamInactivityMs: getConfig().streamInactivityMs,
                     loop: { pathThreshold: Number.POSITIVE_INFINITY },
                     onLine: line => {
                         lastLine = line;
@@ -538,6 +543,9 @@ export function buildGateDeps(params) {
                             // bash — wired anyway so a future tool grant can't quietly
                             // re-open the hole.
                             commandTimeoutMs: getConfig().requestTimeoutMs,
+                            // Unbounded wall clock here too — the hung-stream
+                            // bound is the only thing that ends a dead stream.
+                            streamInactivityMs: getConfig().streamInactivityMs,
                             // Exact-match loop guard only: pathThreshold Infinity
                             // disables the path-revisit heuristic, so revisiting one
                             // file (which IS this pass's job) never trips — only a

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

@@ -0,0 +1,32 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/**
+ * MAIN-SESSION adapter for the model-stream watchdog.
+ *
+ * WHY (mx5 run 14): three implementation turns died mid-turn — the session jsonl's
+ * last record is an ordinary assistant message, then silence forever, while the
+ * model container stayed Up(healthy). No error is ever thrown for this shape, so
+ * the connection-error retry (which needs a reported ModelError) cannot fire and
+ * the command watchdog, which only covers tool executions, never arms. The run sat
+ * dead for ~2.9h across the three until a human restarted it.
+ *
+ * HOW: pi's extension events ARE the stream. Any of them — a token delta, a
+ * thinking delta, a tool-call delta, the provider's response headers — resets the
+ * idle clock; only total silence for the configured window fires. On fire the turn
+ * is aborted and a follow-up user turn tells the model to CONTINUE from the
+ * transcript (its completed tool calls and results are already recorded, so a
+ * blind re-send would re-run them).
+ *
+ * ONE ABORT CHANNEL: the fire path goes through the command watchdog's existing
+ * {@link noteWatchdogAbort} flag and its WATCHDOG_CANCEL_MARKER, so
+ * steerUntilDone's already-fixed abort/steer race (b543d15) covers this watchdog
+ * too instead of racing a second, parallel abort mechanism.
+ *
+ * SUSPENDED DURING TOOLS: while a tool executes the model stream is legitimately
+ * idle — a 12-minute build emits nothing. That window belongs to the command
+ * watchdog (requestTimeoutMs); this one pauses between tool_execution_start and
+ * tool_execution_end so the two can never double-fire on the same silence.
+ *
+ * SCOPE: main session only. Children run `--no-extensions`, so their equivalent
+ * guard lives in runChild (shared/child-process.ts) and shares the same machine.
+ */
+export declare function registerStreamWatchdog(pi: ExtensionAPI): void;

package/dist/task/stream-watchdog.js

@@ -0,0 +1,90 @@
+import { getConfig } from '../config/config.js';
+import { realStreamTimerDeps, StreamWatchdog, streamStallReminder } from '../shared/stream-watchdog.js';
+import { noteWatchdogAbort, WATCHDOG_CANCEL_MARKER } from './command-watchdog.js';
+/**
+ * MAIN-SESSION adapter for the model-stream watchdog.
+ *
+ * WHY (mx5 run 14): three implementation turns died mid-turn — the session jsonl's
+ * last record is an ordinary assistant message, then silence forever, while the
+ * model container stayed Up(healthy). No error is ever thrown for this shape, so
+ * the connection-error retry (which needs a reported ModelError) cannot fire and
+ * the command watchdog, which only covers tool executions, never arms. The run sat
+ * dead for ~2.9h across the three until a human restarted it.
+ *
+ * HOW: pi's extension events ARE the stream. Any of them — a token delta, a
+ * thinking delta, a tool-call delta, the provider's response headers — resets the
+ * idle clock; only total silence for the configured window fires. On fire the turn
+ * is aborted and a follow-up user turn tells the model to CONTINUE from the
+ * transcript (its completed tool calls and results are already recorded, so a
+ * blind re-send would re-run them).
+ *
+ * ONE ABORT CHANNEL: the fire path goes through the command watchdog's existing
+ * {@link noteWatchdogAbort} flag and its WATCHDOG_CANCEL_MARKER, so
+ * steerUntilDone's already-fixed abort/steer race (b543d15) covers this watchdog
+ * too instead of racing a second, parallel abort mechanism.
+ *
+ * SUSPENDED DURING TOOLS: while a tool executes the model stream is legitimately
+ * idle — a 12-minute build emits nothing. That window belongs to the command
+ * watchdog (requestTimeoutMs); this one pauses between tool_execution_start and
+ * tool_execution_end so the two can never double-fire on the same silence.
+ *
+ * SCOPE: main session only. Children run `--no-extensions`, so their equivalent
+ * guard lives in runChild (shared/child-process.ts) and shares the same machine.
+ */
+export function registerStreamWatchdog(pi) {
+    // The ctx whose abort() ends the in-flight turn, refreshed on every event so
+    // the fire (which happens outside any handler) aborts the CURRENT operation.
+    let liveCtx;
+    const watchdog = new StreamWatchdog({
+        getTimeoutMs: () => getConfig().streamInactivityMs,
+        ...realStreamTimerDeps,
+        onFire: idleMs => {
+            const ctx = liveCtx;
+            liveCtx = undefined;
+            // Flag BEFORE the abort, exactly as the command watchdog does: the
+            // steer loop can otherwise observe the 'aborted' turn first and show
+            // a steering prompt to an empty room, wedging an unattended run.
+            if (ctx) {
+                noteWatchdogAbort();
+                ctx.abort();
+            }
+            pi.sendUserMessage(streamStallReminder(idleMs, WATCHDOG_CANCEL_MARKER), {
+                deliverAs: 'followUp'
+            });
+        }
+    });
+    // Any event proves the stream is alive. `arm` also (re)starts the machine, so
+    // a request that begins after a previous turn ended is watched again without
+    // needing a single canonical "request started" event.
+    const arm = (ctx) => {
+        if (ctx)
+            liveCtx = ctx;
+        watchdog.start();
+        watchdog.note();
+    };
+    pi.on('before_provider_request', (_e, ctx) => arm(ctx));
+    pi.on('after_provider_response', (_e, ctx) => arm(ctx));
+    pi.on('turn_start', (_e, ctx) => arm(ctx));
+    pi.on('message_start', (_e, ctx) => arm(ctx));
+    pi.on('message_update', (_e, ctx) => arm(ctx));
+    pi.on('message_end', (_e, ctx) => arm(ctx));
+    pi.on('tool_execution_start', (_e, ctx) => {
+        liveCtx = ctx;
+        watchdog.suspend();
+    });
+    pi.on('tool_execution_update', (_e, ctx) => {
+        liveCtx = ctx;
+    });
+    pi.on('tool_execution_end', (_e, ctx) => {
+        liveCtx = ctx;
+        watchdog.resume();
+    });
+    // Nothing is streaming between agent loops; stop so no timer can fire into an
+    // idle session (which would abort nothing and post a reminder to no one).
+    const stop = () => {
+        watchdog.stop();
+        liveCtx = undefined;
+    };
+    pi.on('agent_end', stop);
+    pi.on('session_shutdown', stop);
+}

package/dist/workers/pi-worker-core.d.ts

@@ -74,6 +74,16 @@ export interface RunWorkerInput {
         afterMs?: number;
         probe?: () => Promise<boolean>;
     } | false;
+    /**
+     * Stream-inactivity ceiling in ms (shared/stream-watchdog.ts). The stall guard
+     * above cannot catch a HUNG stream on a HEALTHY backend — it reads a reachable
+     * endpoint as proof of life, which is exactly what run 14's three hangs looked
+     * like. This one asks nothing of the backend: no output for this long (with
+     * tool executions excluded) ⇒ kill and restart the attempt with
+     * {@link streamStallHint}, inside the same shared restart budget.
+     * 0 / omitted = off.
+     */
+    streamInactivityMs?: number;
 }
 export interface RunWorkerResult {
     text: string;
@@ -129,6 +139,16 @@ export interface RunWorkerResult {
         toolName: string;
         timeoutMs: number;
     };
+    /**
+     * Set when the stream watchdog killed the worker's FINAL attempt: the model
+     * stream produced nothing for the configured window while no tool was running.
+     * Like loopHit/timedOut the text is partial — treat as a failure, and check it
+     * BEFORE `aborted` (the kill aborts too), or a hung backend is mislabeled a
+     * user cancel.
+     */
+    streamStalled?: {
+        idleMs: number;
+    };
 }
 /**
  * The per-command ceiling for attempt N, halving each time a hang recurs.

package/dist/workers/pi-worker-core.js

@@ -6,6 +6,7 @@ import { LoopDetector } from '../task/loop-detector.js';
 import { LOOP_WINDOW, LOOP_THRESHOLD, MAX_LOOP_RESTARTS, formatLoopHint } from '../task/child-runner.js';
 import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 import { discoverModelEndpoints, probeModelEndpoints } from '../shared/model-endpoint.js';
+import { streamStallHint } from '../shared/stream-watchdog.js';
 // `--mode json` makes pi emit structured events as they happen instead of
 // buffering the assistant text and flushing on exit. That matters for the
 // wait/work timing split: in text mode the first stdout chunk only arrives at
@@ -207,6 +208,9 @@ export async function runWorker(input) {
                                 ?? (() => probeModelEndpoints(discoverModelEndpoints()))
                         }
                     }),
+                ...(input.streamInactivityMs ?
+                    { streamInactivityMs: input.streamInactivityMs }
+                    : {}),
                 onFirstByte: () => (tFirstByte = Date.now()),
                 onToolCall: call => {
                     cmdWatch?.onStart(call);
@@ -240,6 +244,7 @@ export async function runWorker(input) {
         const text = result.text ?? '';
         const timedOut = timeout.timedOut();
         const commandKill = cmdWatch?.killed();
+        const streamStalled = result.streamStalled;
         // A loop-kill gets the same restart-with-hint treatment every other phase
         // already gets (runPhaseWithLoopGuard) — name the offending call so the
         // re-spawn avoids it. Bounded by the shared restart budget.
@@ -265,6 +270,14 @@ export async function runWorker(input) {
             hangKills++;
             continue;
         }
+        // A hung model stream is restartable on the same budget. Checked before
+        // the wall-clock timeout because it is the more specific diagnosis (and
+        // its hint does not blame the model: nothing it did caused the hang).
+        if (streamStalled && !loopHit && restarts < MAX_LOOP_RESTARTS) {
+            hint = streamStallHint(streamStalled.idleMs);
+            restarts++;
+            continue;
+        }
         // A wall-clock timeout (the backstop for varied thrash the exact-match
         // detector misses) is also restartable, sharing the same budget. Skip when
         // a loop also tripped — the loop hint above is more specific.
@@ -293,6 +306,7 @@ export async function runWorker(input) {
             ...(loopHit ? { loopHit } : {}),
             ...(timedOut ? { timedOut: true } : {}),
             ...(result.stalled ? { stalled: true } : {}),
+            ...(streamStalled ? { streamStalled } : {}),
             ...(commandKill ?
                 {
                     commandTimedOut: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.37",
+    "version": "0.18.38",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",