@mjasnikovs/pi-task 0.18.27 → 0.18.28

package/dist/config/config.d.ts

@@ -43,16 +43,20 @@ export interface PiTaskConfig {
      */
     extensionWhitelist: string[];
     /**
-     * Wall-clock ceiling (ms) on a SINGLE tool execution in the MAIN session
-     * before the command watchdog cancels it and reminds the model to set its
-     * own timeout. Local models routinely run a command that never returns
+     * Wall-clock ceiling (ms) on a SINGLE tool execution before the command
+     * watchdog steps in. Local models routinely run a command that never returns
      * (e.g. `godot --headless` with no timeout, a dev server, a hung test) and
      * the run wedges until the user manually aborts. pi's bash tool has an
      * OPTIONAL timeout with NO default (bash.js), so a command the model didn't
-     * bound runs forever; this is the missing default, enforced from the host
-     * side via ctx.abort() (which kills the tool's whole process tree) plus an
-     * auto-reminder turn. Tool-agnostic: it arms on any tool execution, though
-     * in practice only bash runs long enough to trip it. 0 = off.
+     * bound runs forever; this is the missing default.
+     *
+     * ONE knob, TWO surfaces (shared/command-watchdog.ts): in the MAIN session
+     * the overrun call is cancelled via ctx.abort() (kills the tool's whole
+     * process tree) plus an auto-reminder turn; in the verify/fix GATE children
+     * (gate-deps.ts) the child is killed and re-spawned with a hint, the ceiling
+     * halving on repeat hangs. 0 = off — which unguards BOTH surfaces, gates
+     * included. Tool-agnostic: it arms on any tool execution, though in practice
+     * only bash runs long enough to trip it.
      * DEFAULT 15 min: long enough for a real build/test suite, short enough that
      * a true hang doesn't cost half an hour of dead time.
      */

package/dist/config/register.js

@@ -102,7 +102,9 @@ const ITEMS = [
         description: 'Cancel a single command that runs longer than this and remind the model to set '
             + 'its own timeout. Catches a local model that runs a command which never returns '
             + '(hung build, dev server, no-timeout check) so the run stops itself instead of '
-            + 'waiting for a manual abort. off disables it',
+            + 'waiting for a manual abort. One knob for both surfaces: the main session AND '
+            + 'the verify/fix gate children. off disables it everywhere — gates can then hang '
+            + 'unbounded',
         // Display human labels; the stored config value stays the ms number.
         values: COMMAND_TIMEOUT_OPTIONS.map(o => o.label)
     }

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

@@ -58,6 +58,13 @@ export interface ChildResult {
 export interface ToolCall {
     name: string;
     args: unknown;
+    /**
+     * pi's id for this tool call, carried on both `tool_execution_start` and
+     * `tool_execution_end` so a caller can pair them (the command watchdog arms
+     * on start and disarms on the matching end). Optional because the loop
+     * detector — the other consumer — keys on name+args and never needs it.
+     */
+    toolCallId?: string;
 }
 export interface LoopHit {
     call: ToolCall;
@@ -100,6 +107,7 @@ export interface RunChildJsonEventsOptions {
         name: string;
         isError: boolean;
         text: string;
+        toolCallId?: string;
     }) => void;
     onFirstByte?: () => void;
     /**

package/dist/shared/child-process.js

@@ -150,12 +150,13 @@ export class JsonEventSink {
         }
         if (t === 'tool_execution_start') {
             const tn = typeof evt.toolName === 'string' ? evt.toolName : 'tool';
+            const id = typeof evt.toolCallId === 'string' ? evt.toolCallId : undefined;
             if (opts.onLine) {
                 const detail = summarizeToolArgs(tn, evt.args);
                 opts.onLine(detail ? `${tn}: ${detail}` : tn);
             }
             if (opts.onToolCall) {
-                const hit = opts.onToolCall({ name: tn, args: evt.args });
+                const hit = opts.onToolCall({ name: tn, args: evt.args, toolCallId: id });
                 if (hit)
                     this.onLoopKill();
             }
@@ -163,9 +164,10 @@ export class JsonEventSink {
         }
         if (t === 'tool_execution_end' && opts.onToolResult) {
             const tn = typeof evt.toolName === 'string' ? evt.toolName : 'tool';
+            const id = typeof evt.toolCallId === 'string' ? evt.toolCallId : undefined;
             const res = evt.result;
             const text = toolResultText(res?.content);
-            opts.onToolResult({ name: tn, isError: evt.isError === true, text });
+            opts.onToolResult({ name: tn, isError: evt.isError === true, text, toolCallId: id });
         }
     }
 }

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

@@ -0,0 +1,95 @@
+/**
+ * Command watchdog — the per-tool-call wall-clock machine, shared by both
+ * surfaces that can run a command which never returns.
+ *
+ * WHY THIS LIVES IN shared/: pi's bash tool takes an OPTIONAL `timeout` with NO
+ * default (pi-coding-agent core/tools/bash.js), so ANY command the model didn't
+ * bound runs forever. That is true in two places, and they are disjoint:
+ *
+ *   MAIN SESSION — the implementation turn, handed off via sendUserMessage
+ *                  (task/orchestrator.ts). Guarded by registerCommandWatchdog
+ *                  in task/command-watchdog.ts.
+ *   CHILD pi     — the verify / lint-fix / recommend / final-fix gate children
+ *                  (task/gate-deps.ts). Children are spawned `--no-extensions`
+ *                  (CHILD_BASE_ARGS), so the host's extension-event watchdog
+ *                  cannot see them at all. Guarded inside runWorker.
+ *
+ * Neither registration can cover the other's surface, so both exist — but the
+ * TIMER STATE MACHINE is identical, and lives here once. What differs is only
+ * the `onFire` side effect, which each adapter supplies:
+ *
+ *   main session — ctx.abort() cancels just that tool call and the session
+ *                  survives to receive a follow-up reminder turn.
+ *   child        — there is no per-tool cancellation channel into a child, so
+ *                  the whole child is killed and re-spawned with
+ *                  {@link commandTimeoutHint} prepended. Coarser by necessity:
+ *                  the child's accumulated context is lost.
+ */
+/** Opaque timer handle — a real `setTimeout` return in production, anything the
+ *  test's fake scheduler hands back under test. */
+export type TimerHandle = unknown;
+export interface WatchdogDeps {
+    /**
+     * The ceiling in ms, read PER command-start. How live that read is depends
+     * on the adapter: the main session passes a config read, so a /task-config
+     * change takes effect on the next command with no reload; the child adapter
+     * passes a constant frozen per attempt (the halved ceiling), so there a
+     * config change lands at the next attempt/gate, not the next command.
+     * 0 (or any non-positive value) means the watchdog is off and never arms.
+     */
+    getTimeoutMs: () => number;
+    schedule: (fn: () => void, ms: number) => TimerHandle;
+    cancel: (handle: TimerHandle) => void;
+    /** Invoked when a command overruns: each adapter aborts/kills here. */
+    onFire: (toolCallId: string, toolName: string, timeoutMs: number) => void;
+}
+/**
+ * MAIN-SESSION reminder, delivered as a follow-up turn after ctx.abort() has
+ * cancelled the offending tool call. The session is still alive and remembers
+ * the call, so this addresses it in the second person, present tense.
+ */
+export declare function reminderMessage(toolName: string, timeoutMs: number): string;
+/**
+ * CHILD restart hint, prepended to the prompt of a re-spawned gate child. The
+ * killed child is GONE — this one never saw the command — so it is framed as
+ * "your previous attempt" and names the command, which the fresh child would
+ * otherwise have no way to know it must avoid repeating unbounded.
+ *
+ * `editsMayPersist` — set for a write-capable child (edit/write tools, or bash,
+ * whose commands have side effects). Nothing reverts the working tree between
+ * attempts, so telling such a child its previous attempt was "discarded" is
+ * false: partial edits and command side effects survive the kill, and a fresh
+ * child that believes it starts clean may re-apply them or misread the tree.
+ * Only the CONVERSATION is gone; the hint must say so precisely.
+ *
+ * Replaces the generic worker-timeout hint for this case: that one blames
+ * "exploring too long", which is the wrong diagnosis for a hung command and
+ * never mentions the timeout parameter.
+ */
+export declare function commandTimeoutHint(toolName: string, timeoutMs: number, opts?: {
+    commandDetail?: string;
+    editsMayPersist?: boolean;
+}): string;
+export declare class CommandWatchdog {
+    private readonly deps;
+    /** Armed timers, keyed by the tool call they guard. Tool executions are
+     *  sequential, so this holds at most one entry in normal operation, but the
+     *  map keeps it correct even if pi ever overlaps two calls. */
+    private readonly active;
+    constructor(deps: WatchdogDeps);
+    /** Arm a timer for a starting tool. No-op when the watchdog is off. */
+    onStart(toolCallId: string, toolName: string): void;
+    /** Disarm the timer for a finished tool. */
+    onEnd(toolCallId: string): void;
+    /** Cancel every armed timer — a turn-end / session-shutdown / child-exit
+     *  safety net so no stray timer can fire into a later, unrelated command. */
+    clearAll(): void;
+    private disarm;
+    private fire;
+}
+/**
+ * Real-clock schedule/cancel, unref'd so a pending watchdog timer can never
+ * itself keep the process alive on exit. Shared by both adapters; tests
+ * substitute a fake scheduler instead.
+ */
+export declare const realTimerDeps: Pick<WatchdogDeps, 'schedule' | 'cancel'>;

package/dist/shared/command-watchdog.js

@@ -0,0 +1,150 @@
+/**
+ * Command watchdog — the per-tool-call wall-clock machine, shared by both
+ * surfaces that can run a command which never returns.
+ *
+ * WHY THIS LIVES IN shared/: pi's bash tool takes an OPTIONAL `timeout` with NO
+ * default (pi-coding-agent core/tools/bash.js), so ANY command the model didn't
+ * bound runs forever. That is true in two places, and they are disjoint:
+ *
+ *   MAIN SESSION — the implementation turn, handed off via sendUserMessage
+ *                  (task/orchestrator.ts). Guarded by registerCommandWatchdog
+ *                  in task/command-watchdog.ts.
+ *   CHILD pi     — the verify / lint-fix / recommend / final-fix gate children
+ *                  (task/gate-deps.ts). Children are spawned `--no-extensions`
+ *                  (CHILD_BASE_ARGS), so the host's extension-event watchdog
+ *                  cannot see them at all. Guarded inside runWorker.
+ *
+ * Neither registration can cover the other's surface, so both exist — but the
+ * TIMER STATE MACHINE is identical, and lives here once. What differs is only
+ * the `onFire` side effect, which each adapter supplies:
+ *
+ *   main session — ctx.abort() cancels just that tool call and the session
+ *                  survives to receive a follow-up reminder turn.
+ *   child        — there is no per-tool cancellation channel into a child, so
+ *                  the whole child is killed and re-spawned with
+ *                  {@link commandTimeoutHint} prepended. Coarser by necessity:
+ *                  the child's accumulated context is lost.
+ */
+/** Whole minutes, floored at 1, for the human-facing ceiling in both messages. */
+function minutes(timeoutMs) {
+    const mins = Math.max(1, Math.round(timeoutMs / 60_000));
+    return `${mins} minute${mins === 1 ? '' : 's'}`;
+}
+/**
+ * The core correction, shared by both adapters' messages. Two jobs, both
+ * learned from live runs: stop the model reporting a killed command as a
+ * success, and name the ONE mechanism that prevents a repeat (the bash tool's
+ * own `timeout` parameter) rather than leaving "be faster" as the takeaway.
+ */
+function correction() {
+    return (`The command was killed before it finished and produced NO result, so do not `
+        + `report it as completed or successful, and do not claim that anything it would `
+        + `have started (a server, build, or process) is now running. `
+        + `If it was a genuinely long-running command, you MUST re-run it with an explicit `
+        + `timeout — set the bash tool's \`timeout\` parameter (in seconds) so it cannot hang `
+        + `again — or break it into smaller steps. Do NOT simply retry the same unbounded command.`);
+}
+/**
+ * MAIN-SESSION reminder, delivered as a follow-up turn after ctx.abort() has
+ * cancelled the offending tool call. The session is still alive and remembers
+ * the call, so this addresses it in the second person, present tense.
+ */
+export function reminderMessage(toolName, timeoutMs) {
+    return (`[SYSTEM] Your \`${toolName}\` call ran longer than ${minutes(timeoutMs)} `
+        + `and was automatically cancelled — it looked stuck. `
+        + correction());
+}
+/**
+ * CHILD restart hint, prepended to the prompt of a re-spawned gate child. The
+ * killed child is GONE — this one never saw the command — so it is framed as
+ * "your previous attempt" and names the command, which the fresh child would
+ * otherwise have no way to know it must avoid repeating unbounded.
+ *
+ * `editsMayPersist` — set for a write-capable child (edit/write tools, or bash,
+ * whose commands have side effects). Nothing reverts the working tree between
+ * attempts, so telling such a child its previous attempt was "discarded" is
+ * false: partial edits and command side effects survive the kill, and a fresh
+ * child that believes it starts clean may re-apply them or misread the tree.
+ * Only the CONVERSATION is gone; the hint must say so precisely.
+ *
+ * Replaces the generic worker-timeout hint for this case: that one blames
+ * "exploring too long", which is the wrong diagnosis for a hung command and
+ * never mentions the timeout parameter.
+ */
+export function commandTimeoutHint(toolName, timeoutMs, opts) {
+    const what = opts?.commandDetail ? ` (${opts.commandDetail})` : '';
+    const aftermath = opts?.editsMayPersist ?
+        `killed and that attempt's conversation was discarded — you are starting over, `
+            + `BUT any file edits or command side effects it made before the kill are still `
+            + `in the working tree. Check the current state of files before assuming they `
+            + `are untouched or re-applying changes. `
+        : `killed and that attempt was discarded — you are seeing this task again from `
+            + `the start. `;
+    return (`[SYSTEM NOTE: Your previous attempt ran a \`${toolName}\` command${what} that had not `
+        + `returned after ${minutes(timeoutMs)}, so it was `
+        + aftermath
+        + correction()
+        + `]`);
+}
+export class CommandWatchdog {
+    deps;
+    /** Armed timers, keyed by the tool call they guard. Tool executions are
+     *  sequential, so this holds at most one entry in normal operation, but the
+     *  map keeps it correct even if pi ever overlaps two calls. */
+    active = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Arm a timer for a starting tool. No-op when the watchdog is off. */
+    onStart(toolCallId, toolName) {
+        const ms = this.deps.getTimeoutMs();
+        if (!(ms > 0))
+            return;
+        // A duplicate start for the same id must not leak the previous timer.
+        this.disarm(toolCallId);
+        const handle = this.deps.schedule(() => this.fire(toolCallId, toolName, ms), ms);
+        this.active.set(toolCallId, handle);
+    }
+    /** Disarm the timer for a finished tool. */
+    onEnd(toolCallId) {
+        this.disarm(toolCallId);
+    }
+    /** Cancel every armed timer — a turn-end / session-shutdown / child-exit
+     *  safety net so no stray timer can fire into a later, unrelated command. */
+    clearAll() {
+        for (const handle of this.active.values())
+            this.deps.cancel(handle);
+        this.active.clear();
+    }
+    disarm(toolCallId) {
+        const handle = this.active.get(toolCallId);
+        if (handle !== undefined) {
+            this.deps.cancel(handle);
+            this.active.delete(toolCallId);
+        }
+    }
+    fire(toolCallId, toolName, ms) {
+        // If the tool ended in the same tick the timer fired, its entry is gone
+        // already — never abort a command that has just finished cleanly.
+        if (!this.active.has(toolCallId))
+            return;
+        this.active.delete(toolCallId);
+        this.deps.onFire(toolCallId, toolName, ms);
+    }
+}
+/**
+ * Real-clock schedule/cancel, unref'd so a pending watchdog timer can never
+ * itself keep the process alive on exit. Shared by both adapters; tests
+ * substitute a fake scheduler instead.
+ */
+export const realTimerDeps = {
+    schedule: (fn, ms) => {
+        const handle = setTimeout(fn, ms);
+        if (typeof handle.unref === 'function') {
+            ;
+            handle.unref();
+        }
+        return handle;
+    },
+    cancel: handle => clearTimeout(handle)
+};

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

@@ -1,7 +1,6 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 /**
- * Command watchdog — cancels a single tool execution that overruns the
- * configured ceiling and reminds the model to bound its own commands.
+ * MAIN-SESSION adapter for the command watchdog.
  *
  * WHY: a local model in the MAIN session routinely runs a command that never
  * returns — `godot --headless --check-only` with no timeout, a dev server, a
@@ -17,48 +16,15 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
  * what happened so it retries with a timeout instead of hanging again.
  *
  * Tool-agnostic: it arms on ANY tool, honouring "any command can run forever",
- * though in practice only bash runs long enough to trip it. The pure timer
- * state lives in {@link CommandWatchdog}; all side effects (abort, reminder,
- * per-call ctx lookup) live in the registration's `onFire`, so the machine is
- * unit-testable without a real pi session.
- */
-/** Opaque timer handle — a real `setTimeout` return in production, anything the
- *  test's fake scheduler hands back under test. */
-export type TimerHandle = unknown;
-export interface WatchdogDeps {
-    /**
-     * The ceiling in ms, read PER command-start so a /task-config change takes
-     * effect on the next command with no reload. 0 (or any non-positive value)
-     * means the watchdog is off and never arms.
-     */
-    getTimeoutMs: () => number;
-    schedule: (fn: () => void, ms: number) => TimerHandle;
-    cancel: (handle: TimerHandle) => void;
-    /** Invoked when a command overruns: the registration aborts + reminds here. */
-    onFire: (toolCallId: string, toolName: string, timeoutMs: number) => void;
-}
-/**
- * The reminder delivered to the model after its command is cancelled. Kept pure
- * and exported so a test can assert its shape without driving the whole session.
+ * though in practice only bash runs long enough to trip it.
+ *
+ * SCOPE — this covers the main session ONLY, which is where the implementation
+ * turn runs (orchestrator hands the spec off via sendUserMessage). Gate
+ * children are spawned `--no-extensions`, so no host extension exists inside
+ * them; their equivalent guard lives in runWorker (workers/pi-worker-core.ts)
+ * and shares the same machine from shared/command-watchdog.ts.
  */
-export declare function reminderMessage(toolName: string, timeoutMs: number): string;
-export declare class CommandWatchdog {
-    private readonly deps;
-    /** Armed timers, keyed by the tool call they guard. Tool executions are
-     *  sequential, so this holds at most one entry in normal operation, but the
-     *  map keeps it correct even if pi ever overlaps two calls. */
-    private readonly active;
-    constructor(deps: WatchdogDeps);
-    /** Arm a timer for a starting tool. No-op when the watchdog is off. */
-    onStart(toolCallId: string, toolName: string): void;
-    /** Disarm the timer for a finished tool. */
-    onEnd(toolCallId: string): void;
-    /** Cancel every armed timer — a turn-end / session-shutdown safety net so no
-     *  stray timer can fire into a later, unrelated command. */
-    clearAll(): void;
-    private disarm;
-    private fire;
-}
+export { CommandWatchdog, commandTimeoutHint, realTimerDeps, reminderMessage, type TimerHandle, type WatchdogDeps } from '../shared/command-watchdog.js';
 /**
  * Wire the watchdog into the main session. Only ever active in the host session
  * (children run `--no-extensions`), which is exactly where the observed hangs

package/dist/task/command-watchdog.js

@@ -1,68 +1,33 @@
 import { getConfig } from '../config/config.js';
+import { CommandWatchdog, realTimerDeps, reminderMessage } from '../shared/command-watchdog.js';
 /**
- * The reminder delivered to the model after its command is cancelled. Kept pure
- * and exported so a test can assert its shape without driving the whole session.
+ * MAIN-SESSION adapter for the command watchdog.
+ *
+ * WHY: a local model in the MAIN session routinely runs a command that never
+ * returns — `godot --headless --check-only` with no timeout, a dev server, a
+ * hung test — and the run wedges until the user manually aborts and tells the
+ * model to add a timeout. pi's bash tool takes an OPTIONAL `timeout` with NO
+ * default (see pi-coding-agent tools/bash.js), so any command the model didn't
+ * bound runs forever. This supplies the missing default from the host side.
+ *
+ * HOW: arm a wall-clock timer on `tool_execution_start`, disarm it on
+ * `tool_execution_end`. If it elapses, `ctx.abort()` cancels the in-flight
+ * operation — which fires the tool's AbortSignal, and pi's bash executor kills
+ * the whole process tree on abort — then a follow-up user turn tells the model
+ * what happened so it retries with a timeout instead of hanging again.
+ *
+ * Tool-agnostic: it arms on ANY tool, honouring "any command can run forever",
+ * though in practice only bash runs long enough to trip it.
+ *
+ * SCOPE — this covers the main session ONLY, which is where the implementation
+ * turn runs (orchestrator hands the spec off via sendUserMessage). Gate
+ * children are spawned `--no-extensions`, so no host extension exists inside
+ * them; their equivalent guard lives in runWorker (workers/pi-worker-core.ts)
+ * and shares the same machine from shared/command-watchdog.ts.
  */
-export function reminderMessage(toolName, timeoutMs) {
-    const mins = Math.max(1, Math.round(timeoutMs / 60_000));
-    return (`[SYSTEM] Your \`${toolName}\` call ran longer than ${mins} minute`
-        + `${mins === 1 ? '' : 's'} and was automatically cancelled — it looked stuck. `
-        // Anti-fabrication: a live run showed the model react to the cancel by
-        // reporting the killed command as succeeded ("the server is now running").
-        // State plainly that it produced nothing so the model can't claim success.
-        + `The command was killed before it finished and produced NO result, so do not `
-        + `report it as completed or successful, and do not claim that anything it would `
-        + `have started (a server, build, or process) is now running. `
-        + `If it was a genuinely long-running command, you MUST re-run it with an explicit `
-        + `timeout — set the bash tool's \`timeout\` parameter (in seconds) so it cannot hang `
-        + `again — or break it into smaller steps. Do NOT simply retry the same unbounded command.`);
-}
-export class CommandWatchdog {
-    deps;
-    /** Armed timers, keyed by the tool call they guard. Tool executions are
-     *  sequential, so this holds at most one entry in normal operation, but the
-     *  map keeps it correct even if pi ever overlaps two calls. */
-    active = new Map();
-    constructor(deps) {
-        this.deps = deps;
-    }
-    /** Arm a timer for a starting tool. No-op when the watchdog is off. */
-    onStart(toolCallId, toolName) {
-        const ms = this.deps.getTimeoutMs();
-        if (!(ms > 0))
-            return;
-        // A duplicate start for the same id must not leak the previous timer.
-        this.disarm(toolCallId);
-        const handle = this.deps.schedule(() => this.fire(toolCallId, toolName, ms), ms);
-        this.active.set(toolCallId, handle);
-    }
-    /** Disarm the timer for a finished tool. */
-    onEnd(toolCallId) {
-        this.disarm(toolCallId);
-    }
-    /** Cancel every armed timer — a turn-end / session-shutdown safety net so no
-     *  stray timer can fire into a later, unrelated command. */
-    clearAll() {
-        for (const handle of this.active.values())
-            this.deps.cancel(handle);
-        this.active.clear();
-    }
-    disarm(toolCallId) {
-        const handle = this.active.get(toolCallId);
-        if (handle !== undefined) {
-            this.deps.cancel(handle);
-            this.active.delete(toolCallId);
-        }
-    }
-    fire(toolCallId, toolName, ms) {
-        // If the tool ended in the same tick the timer fired, its entry is gone
-        // already — never abort a command that has just finished cleanly.
-        if (!this.active.has(toolCallId))
-            return;
-        this.active.delete(toolCallId);
-        this.deps.onFire(toolCallId, toolName, ms);
-    }
-}
+// Re-exported so existing importers (and the machine's own tests) keep their
+// entry point while the implementation lives in shared/.
+export { CommandWatchdog, commandTimeoutHint, realTimerDeps, reminderMessage } from '../shared/command-watchdog.js';
 /**
  * Wire the watchdog into the main session. Only ever active in the host session
  * (children run `--no-extensions`), which is exactly where the observed hangs
@@ -75,16 +40,7 @@ export function registerCommandWatchdog(pi) {
     const ctxByCall = new Map();
     const watchdog = new CommandWatchdog({
         getTimeoutMs: () => getConfig().requestTimeoutMs,
-        schedule: (fn, ms) => {
-            const handle = setTimeout(fn, ms);
-            // Don't let a pending watchdog timer keep the process alive on exit.
-            if (typeof handle.unref === 'function') {
-                ;
-                handle.unref();
-            }
-            return handle;
-        },
-        cancel: handle => clearTimeout(handle),
+        ...realTimerDeps,
         onFire: (toolCallId, toolName, timeoutMs) => {
             const ctx = ctxByCall.get(toolCallId);
             ctxByCall.delete(toolCallId);

package/dist/task/enforce-guidelines.d.ts

@@ -90,6 +90,10 @@ export interface EnforceChildResult {
     loopHit?: unknown;
     leakedToolCall?: unknown;
     stalled?: boolean;
+    commandTimedOut?: {
+        toolName: string;
+        timeoutMs: number;
+    };
 }
 /**
  * Map the enforcement child's runWorker result to a fatal error message, or null

package/dist/task/enforce-guidelines.js

@@ -224,6 +224,15 @@ export function classifyEnforceChildFailure(r) {
     if (r.stalled) {
         return 'model server unreachable — the child produced no output and the model endpoint did not respond';
     }
+    // Same rule, same reason: the command watchdog's kill sets `aborted` too, so
+    // a child killed for a command that never returned would otherwise report as
+    // a user cancel. Its text is truncated mid-run — the verdict in it is partial
+    // and must never be parsed as a real one.
+    if (r.commandTimedOut) {
+        const mins = Math.max(1, Math.round(r.commandTimedOut.timeoutMs / 60_000));
+        return (`child ran a \`${r.commandTimedOut.toolName}\` command that had not returned after `
+            + `${mins} minute${mins === 1 ? '' : 's'} and was killed — it never bounded the command`);
+    }
     if (r.timedOut)
         return 'enforcement child timed out';
     if (r.loopHit)

package/dist/task/gate-deps.js

@@ -263,6 +263,15 @@ export function buildGateDeps(params) {
                     signal: sig,
                     tools,
                     timeoutMs: 0,
+                    // The gate child runs to completion (timeoutMs 0), but a
+                    // single command inside it must still be bounded: pi's bash
+                    // tool has no default timeout, so a `bun run dev` / hung
+                    // check the model forgot to bound wedges the gate forever.
+                    // The stall guard cannot see it — a reachable model endpoint
+                    // reads as proof of life while the command blocks. Same
+                    // ceiling the main session uses, so one /task-config knob
+                    // covers implementation and gates alike.
+                    commandTimeoutMs: getConfig().requestTimeoutMs,
                     loop: { pathThreshold: Number.POSITIVE_INFINITY },
                     onLine: line => {
                         lastLine = line;
@@ -404,6 +413,11 @@ export function buildGateDeps(params) {
                             signal: sig,
                             tools,
                             timeoutMs: 0, // no wall-clock timeout — run to completion
+                            // …but still bound any SINGLE command (see makeGateChild).
+                            // enforce is read,edit today, so nothing here can hang on
+                            // bash — wired anyway so a future tool grant can't quietly
+                            // re-open the hole.
+                            commandTimeoutMs: getConfig().requestTimeoutMs,
                             // 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/workers/pi-worker-core.d.ts

@@ -17,6 +17,7 @@ export interface RunWorkerInput {
         name: string;
         isError: boolean;
         text: string;
+        toolCallId?: string;
     }) => void;
     /**
      * Called for each context_usage snapshot the child emits (same `--mode json`
@@ -31,6 +32,26 @@ export interface RunWorkerInput {
      * own) — for a pass that must be allowed to finish however long it takes.
      */
     timeoutMs?: number;
+    /**
+     * PER-TOOL-CALL wall-clock ceiling in ms — the child-side half of the command
+     * watchdog (see shared/command-watchdog.ts). Arms on each tool_execution_start
+     * and disarms on the matching end; on overrun the child is killed and, within
+     * the shared restart budget, re-spawned with commandTimeoutHint.
+     *
+     * WHY SEPARATE FROM `timeoutMs`: that one bounds the whole worker and is
+     * deliberately 0 (unbounded) for gate children, which must run to completion.
+     * Neither it nor the stall guard can catch a hung command — the stall guard
+     * treats a reachable model endpoint as proof of life, which it is, even while
+     * a `bun run dev` the model forgot to bound blocks the child forever.
+     *
+     * This is the ceiling for the FIRST attempt; each HANG-caused restart halves
+     * it (see commandCeilingForAttempt — loop-caused restarts don't count), so a
+     * model that ignores the hint cannot spend the full ceiling again on every
+     * retry.
+     *
+     * 0 / omitted = off, so every existing caller is unchanged.
+     */
+    commandTimeoutMs?: number;
     /**
      * Per-worker loop-detector tuning. Defaults to the read-only research/impl
      * guard (LOOP_WINDOW / LOOP_THRESHOLD, path threshold = exact threshold). An
@@ -96,5 +117,39 @@ export interface RunWorkerResult {
      * aborted too, and mislabeling this as a user cancel hides a dead backend.
      */
     stalled?: boolean;
+    /**
+     * Set when the command watchdog killed the worker's FINAL attempt: one tool
+     * call outran `commandTimeoutMs` (a command the model never bounded). Like
+     * loopHit/timedOut the text is partial — treat as a failure. Names the tool
+     * so the caller's trail says which call hung rather than just "aborted".
+     *
+     * Check BEFORE `aborted`, same reasoning as `stalled`: the kill aborts too.
+     */
+    commandTimedOut?: {
+        toolName: string;
+        timeoutMs: number;
+    };
 }
+/**
+ * The per-command ceiling for attempt N, halving each time a hang recurs.
+ *
+ * The first attempt gets the full configured ceiling — a genuinely slow build or
+ * test suite deserves it. But every hang-caused restart carries
+ * commandTimeoutHint, which tells the model in as many words to bound its
+ * command; a SECOND hang means it ignored an explicit instruction, and a third
+ * means it ignored it twice. Giving a non-complying child the full ceiling again
+ * would put the worst case at 3 × 15 min = 45 minutes of dead time, resting
+ * entirely on the model obeying prose. Halving bounds it at ~26 min while
+ * costing a complying child nothing.
+ *
+ * `priorHangs` counts watchdog kills specifically, NOT total restarts — the
+ * restart budget is shared with loop kills, and a child restarted for LOOPING
+ * never received the bound-your-command hint, so its first hang still deserves
+ * the full ceiling. Only a hang after a hang is defiance.
+ *
+ * Floored at 30s so repeated halving cannot shrink the ceiling to something no
+ * real command could finish inside — but never ABOVE the configured ceiling
+ * itself, or a caller asking for 10s would silently get 30.
+ */
+export declare function commandCeilingForAttempt(baseMs: number, priorHangs: number): number;
 export declare function runWorker(input: RunWorkerInput): Promise<RunWorkerResult>;

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

@@ -1,5 +1,6 @@
 import { getPiInvocation } from '../shared/pi-invocation.js';
 import { runChildDefault } from '../shared/child-process.js';
+import { CommandWatchdog, commandTimeoutHint, realTimerDeps } from '../shared/command-watchdog.js';
 import { childBaseArgs } from '../shared/child-extensions.js';
 import { LoopDetector } from '../task/loop-detector.js';
 import { LOOP_WINDOW, LOOP_THRESHOLD, MAX_LOOP_RESTARTS, formatLoopHint } from '../task/child-runner.js';
@@ -32,7 +33,12 @@ const RESEARCH_WORKER_TIMEOUT_MS = 240_000;
  * alive) just gets probed and waits on.
  */
 const STALL_AFTER_MS = 180_000;
-/** Restart hint after a wall-clock timeout — distinct from the loop hint. */
+/**
+ * Restart hint after a WHOLE-WORKER wall-clock timeout — distinct from both the
+ * loop hint and the per-command hint. This one diagnoses over-exploration, which
+ * is what the whole-worker cap actually catches. A single hung COMMAND is a
+ * different fault with a different fix, and gets commandTimeoutHint instead.
+ */
 const WORKER_TIMEOUT_HINT = '[SYSTEM NOTE: Your previous attempt ran out of time before answering — you '
     + 'were exploring too long. Be decisive: do the minimum reads/greps needed, '
     + 'then write your answer now. Do not re-explore ground you have already covered.]';
@@ -69,6 +75,85 @@ function workerTimeout(external, ms) {
         }
     };
 }
+/**
+ * The per-command ceiling for attempt N, halving each time a hang recurs.
+ *
+ * The first attempt gets the full configured ceiling — a genuinely slow build or
+ * test suite deserves it. But every hang-caused restart carries
+ * commandTimeoutHint, which tells the model in as many words to bound its
+ * command; a SECOND hang means it ignored an explicit instruction, and a third
+ * means it ignored it twice. Giving a non-complying child the full ceiling again
+ * would put the worst case at 3 × 15 min = 45 minutes of dead time, resting
+ * entirely on the model obeying prose. Halving bounds it at ~26 min while
+ * costing a complying child nothing.
+ *
+ * `priorHangs` counts watchdog kills specifically, NOT total restarts — the
+ * restart budget is shared with loop kills, and a child restarted for LOOPING
+ * never received the bound-your-command hint, so its first hang still deserves
+ * the full ceiling. Only a hang after a hang is defiance.
+ *
+ * Floored at 30s so repeated halving cannot shrink the ceiling to something no
+ * real command could finish inside — but never ABOVE the configured ceiling
+ * itself, or a caller asking for 10s would silently get 30.
+ */
+export function commandCeilingForAttempt(baseMs, priorHangs) {
+    if (!(baseMs > 0))
+        return 0;
+    const floor = Math.min(baseMs, 30_000);
+    return Math.max(floor, Math.round(baseMs / 2 ** priorHangs));
+}
+/**
+ * Build the child-side command watchdog for ONE attempt: a per-tool-call timer
+ * machine (shared with the main session) whose `onFire` aborts `signal`, which
+ * runChild turns into a process-GROUP kill — reaping the hung command itself,
+ * not just the pi child holding it.
+ *
+ * LIMIT: the group kill only reaches processes still IN the group. A hung
+ * command that detached a daemon (setsid/nohup dev server) leaves it running —
+ * the fresh attempt can then hit a port the dead attempt's escapee still holds
+ * (the run-9 orphan-dev-server → false-EADDRINUSE shape). No cheap fix from
+ * here; the restart hint's "check current state" line is the mitigation.
+ *
+ * Returns null when the watchdog is off, so the caller keeps the plain timeout
+ * signal and no per-call bookkeeping happens at all.
+ */
+function commandWatch(timeoutMs) {
+    if (!(timeoutMs > 0))
+        return null;
+    const ctrl = new AbortController();
+    // pi's toolCallId pairs start↔end. When it is absent (a fake stream in a
+    // test, an older pi), fall back to one shared slot: tool executions in a
+    // child are sequential, so a single slot is still correctly paired.
+    const key = (id) => id ?? 'anon';
+    const details = new Map();
+    let killed;
+    const watchdog = new CommandWatchdog({
+        getTimeoutMs: () => timeoutMs,
+        ...realTimerDeps,
+        onFire: (toolCallId, toolName, ms) => {
+            killed = {
+                toolName,
+                timeoutMs: ms,
+                ...(details.has(toolCallId) ? { detail: details.get(toolCallId) } : {})
+            };
+            ctrl.abort();
+        }
+    });
+    return {
+        onStart: call => {
+            const id = key(call.toolCallId);
+            const args = call.args;
+            if (typeof args?.command === 'string') {
+                details.set(id, args.command.slice(0, 120));
+            }
+            watchdog.onStart(id, call.name);
+        },
+        onEnd: id => watchdog.onEnd(key(id)),
+        killed: () => killed,
+        signal: ctrl.signal,
+        clear: () => watchdog.clearAll()
+    };
+}
 export async function runWorker(input) {
     const tools = input.tools ?? DEFAULT_TOOLS;
     const baseArgs = [...childBaseArgs(input.extensions ?? []), '--mode', 'json', '--tools', tools];
@@ -79,6 +164,10 @@ export async function runWorker(input) {
     // hint up to MAX_LOOP_RESTARTS times before we give up. Leaked tool calls
     // keep their own MAX_LEAK_RETRIES budget below — a different failure mode.
     let restarts = 0;
+    // Watchdog kills specifically — drives the ceiling halving. Kept apart from
+    // `restarts` (the shared budget) so a loop-caused restart doesn't shorten
+    // the rope of a child that has never hung (see commandCeilingForAttempt).
+    let hangKills = 0;
     let leakRetries = 0;
     for (;;) {
         const prompt = hint === null ? input.prompt : `${hint}\n\n${input.prompt}`;
@@ -101,9 +190,13 @@ export async function runWorker(input) {
         // caller couldn't distinguish from a crash.
         let loopHit;
         const timeout = workerTimeout(input.signal, timeoutMs);
+        // Per-tool-call watchdog for this attempt (null when off). Its abort is
+        // OR'd with the worker timeout / external cancel into the child's signal.
+        const cmdWatch = commandWatch(commandCeilingForAttempt(input.commandTimeoutMs ?? 0, hangKills));
+        const childSignal = cmdWatch ? AbortSignal.any([timeout.signal, cmdWatch.signal]) : timeout.signal;
         let result;
         try {
-            result = await runChildDefault(invocation, input.cwd, timeout.signal, {
+            result = await runChildDefault(invocation, input.cwd, childSignal, {
                 mode: 'json-events',
                 ...(input.stall === false ?
                     {}
@@ -116,6 +209,7 @@ export async function runWorker(input) {
                     }),
                 onFirstByte: () => (tFirstByte = Date.now()),
                 onToolCall: call => {
+                    cmdWatch?.onStart(call);
                     if (!loopDetector)
                         return null;
                     const hit = loopDetector.record(call);
@@ -124,18 +218,28 @@ export async function runWorker(input) {
                     return hit;
                 },
                 onLine: input.onLine,
-                onToolResult: input.onToolResult,
+                // Always wired when the watchdog is on — the sink only emits
+                // tool_execution_end if a handler exists, and without it every
+                // timer would stay armed and fire on a finished command.
+                onToolResult: cmdWatch ?
+                    r => {
+                        cmdWatch.onEnd(r.toolCallId);
+                        input.onToolResult?.(r);
+                    }
+                    : input.onToolResult,
                 onContextUsage: input.onContextUsage
             }, input.spawn);
         }
         finally {
             timeout.cleanup();
+            cmdWatch?.clear();
         }
         const tEnd = Date.now();
         const waitMs = tFirstByte === null ? tEnd - tStart : tFirstByte - tStart;
         const workMs = tFirstByte === null ? 0 : tEnd - tFirstByte;
         const text = result.text ?? '';
         const timedOut = timeout.timedOut();
+        const commandKill = cmdWatch?.killed();
         // 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.
@@ -144,6 +248,23 @@ export async function runWorker(input) {
             restarts++;
             continue;
         }
+        // A hung COMMAND is restartable too, on the same budget, but checked
+        // before the whole-worker timeout because its hint is the specific one:
+        // bound the command. (The two can't be confused — a watchdog kill leaves
+        // timeout.timedOut() false, since that flag tracks only its own timer.)
+        if (commandKill && !loopHit && restarts < MAX_LOOP_RESTARTS) {
+            hint = commandTimeoutHint(commandKill.toolName, commandKill.timeoutMs, {
+                commandDetail: commandKill.detail,
+                // Nothing reverts the tree between attempts, so a child that can
+                // mutate it (edit/write, or bash side effects) must not be told
+                // its previous attempt left no trace. Same capability test the
+                // gate logger uses — decided by tools, not by phase.
+                editsMayPersist: /\b(?:edit|bash|write)\b/.test(tools)
+            });
+            restarts++;
+            hangKills++;
+            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.
@@ -171,7 +292,15 @@ export async function runWorker(input) {
             ...(leaked ? { leakedToolCall: leaked } : {}),
             ...(loopHit ? { loopHit } : {}),
             ...(timedOut ? { timedOut: true } : {}),
-            ...(result.stalled ? { stalled: true } : {})
+            ...(result.stalled ? { stalled: true } : {}),
+            ...(commandKill ?
+                {
+                    commandTimedOut: {
+                        toolName: commandKill.toolName,
+                        timeoutMs: commandKill.timeoutMs
+                    }
+                }
+                : {})
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.27",
+    "version": "0.18.28",
     "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",