@mjasnikovs/pi-task 0.18.36 → 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/accept-debt.d.ts

@@ -22,8 +22,15 @@
  *     deletion ships in the next commit. Recorded so the final gate re-checks it:
  *     resolved iff the named file is back in the tree (a later task restored it),
  *     otherwise surfaced.
+ *   - 'final-gate' — the final integration gate DEMOTED one of its own checks to
+ *     UNOBSERVED (mx5 run 14): two fix attempts that both changed the tree and
+ *     re-ran the gate produced a byte-identical ranked-first failure, so the check
+ *     is unfalsifiable in this environment (run 14: the boot probe needed `ss` or
+ *     `lsof` and the sandbox had neither) and no further attempt can move it. The
+ *     run is allowed to converge on the REMAINING checks, carrying this one here
+ *     so the next run's gate re-checks and re-surfaces it rather than losing it.
  */
-export type DebtOrigin = 'accepted' | 'enforce-revert' | 'frozen-blocked' | 'cross-task-deletion' | 'yolo-accepted';
+export type DebtOrigin = 'accepted' | 'enforce-revert' | 'frozen-blocked' | 'cross-task-deletion' | 'yolo-accepted' | 'final-gate';
 /** One recorded defect: the task, why its VERIFY failed, and how it was recorded. */
 export interface AcceptDebt {
     taskId: string;
@@ -89,6 +96,15 @@ export declare function recordCrossTaskDeletionDebt(cwd: string, taskId: string,
  * reading only the artifacts can never read it as "a human decided this".
  */
 export declare function recordYoloAcceptDebt(cwd: string, taskId: string, reason: string): Promise<void>;
+/**
+ * Record a FINAL-GATE UNOBSERVED debt (mx5 run 14): the final gate demoted one of its
+ * OWN checks after two tree-changing fix attempts returned an identical ranked-first
+ * failure — unfalsifiable in this environment, so the gate stopped paying for it and
+ * converged on the remaining checks. Durable so the NEXT run's gate re-checks it: it
+ * is model-/environment-judged, so the re-check surfaces it (never auto-closes it).
+ * The taskId is the run's parent id — the demotion is a run-level decision.
+ */
+export declare function recordFinalGateUnobservedDebt(cwd: string, taskId: string, reason: string): Promise<void>;
 /**
  * The deleted path a cross-task-deletion debt names (the fixed shape
  * recordCrossTaskDeletionDebt writes). Null on any other reason text — an