@mjasnikovs/pi-task 0.28.3 → 0.29.1

package/README.md

@@ -184,6 +184,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | **stuck reply retry** | 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. |
 | **debug logs** | events | How much of a run is written to `.pi-tasks/*-debug.log`. **`events`** keeps decisions and guard actions — which phase ran, why a worker was retried, what the git-state guard restored, what a write-capable child changed on disk, why a gate returned FAIL — a few lines per task. **`full`** adds every line the child model emitted and every tool result; that's ~85% of the bytes (a real 247 KB `verify-debug.log` is 1315 lines, 521 of them tool dumps) and is what you want while actively debugging. **`off`** writes nothing. Nothing in pi-task ever reads these files back, so the setting cannot change how a run behaves — only whether you can explain it afterwards, and a log not written can't be recovered later. |
+| **watch: …** | all on | One toggle per tool in the live session, deciding whether **command timeout** applies to it. The list is discovered from `pi.getAllTools()` when the menu opens — built-ins first, then each extension's tools with the owning entry-point path in the description — so nothing is typed by hand and an uninstalled tool just stops being listed. Turn one **off** only for a tool that already owns a longer bounded, cancellable contract of its own (the guard exists because pi's `bash` has an optional timeout with *no* default — that reasoning doesn't transfer to a tool that has one). Two things to know before you do: a genuine hang in an unwatched tool is caught by nothing, since **stuck reply retry** is paused for the whole time any tool runs; and an unwatched tool is still killed as collateral if a *watched* sibling in the same turn overruns, because pi runs sibling tool calls concurrently and the abort ends the whole turn. Stored as exemptions, so the default and every tool pi-task has never seen stay guarded. |
 | **ext: …** | all off | One toggle per installed host `pi` extension, loading it 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. Children also inherit the extension's tools and hooks, so only enable ones you trust. The list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |
 
 ## Configuration

package/dist/config/config.d.ts

@@ -61,6 +61,22 @@ export interface PiTaskConfig {
      * a true hang doesn't cost half an hour of dead time.
      */
     requestTimeoutMs: number;
+    /**
+     * Tools the generic command watchdog must NOT arm on, by exact name — for
+     * tools that own a stronger, domain-specific timeout and cancellation
+     * contract of their own and would otherwise be aborted mid-transaction at
+     * the generic ceiling. `bash` and every unlisted tool stay guarded.
+     *
+     * Stored as the EXEMPTIONS, not the guarded set, so the default (`[]`) and
+     * every tool pi-task has never seen are guarded — a new or renamed tool can
+     * never silently lose its watchdog.
+     *
+     * Populated from `/task-config`'s `watch:` rows, which are discovered from
+     * the live session via `pi.getAllTools()` (see config/tool-list.ts), so the
+     * names here are pi's own and never hand-typed. A stale entry left behind by
+     * an uninstalled tool matches nothing and is harmless.
+     */
+    commandTimeoutExemptTools: string[];
     /**
      * Inactivity ceiling (ms) on the MODEL STREAM before the stream watchdog
      * aborts the request (shared/stream-watchdog.ts). A hung or silently-dropped
@@ -148,6 +164,8 @@ 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;
+/** Keep only exact, unique Pi tool names from an advanced config override. */
+export declare function sanitizeCommandTimeoutExemptTools(value: unknown): string[];
 /**
  * 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

package/dist/config/config.js

@@ -43,6 +43,23 @@ export function sanitizeRequestTimeoutMs(value) {
         value
         : DEFAULT_REQUEST_TIMEOUT_MS;
 }
+/** Keep only exact, unique Pi tool names from an advanced config override. */
+export function sanitizeCommandTimeoutExemptTools(value) {
+    if (!Array.isArray(value))
+        return [];
+    const result = [];
+    const seen = new Set();
+    for (const item of value) {
+        if (typeof item !== 'string')
+            continue;
+        const name = item.trim();
+        if (!/^[A-Za-z0-9_][A-Za-z0-9_.:-]*$/.test(name) || seen.has(name))
+            continue;
+        seen.add(name);
+        result.push(name);
+    }
+    return result;
+}
 /**
  * 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
@@ -76,6 +93,7 @@ const DEFAULTS = {
     searchProvider: 'exa',
     extensionWhitelist: [],
     requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
+    commandTimeoutExemptTools: [],
     streamInactivityMs: DEFAULT_STREAM_INACTIVITY_MS,
     // OFF: auto-answering is for unattended throwaway runs only.
     yoloMode: false,
@@ -110,6 +128,7 @@ if (!G.loaded) {
             delete parsed.searchProvider;
         parsed.extensionWhitelist = sanitizeExtensionWhitelist(parsed.extensionWhitelist);
         parsed.requestTimeoutMs = sanitizeRequestTimeoutMs(parsed.requestTimeoutMs);
+        parsed.commandTimeoutExemptTools = sanitizeCommandTimeoutExemptTools(parsed.commandTimeoutExemptTools);
         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

package/dist/config/register.d.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-c
 import type { Component } from '@earendil-works/pi-tui';
 import { type PiTaskConfig } from './config.js';
 import { type InstalledExtension } from './extension-list.js';
+import { type GuardableTool } from './tool-list.js';
 type Theme = ExtensionCommandContext['ui']['theme'];
 /**
  * Frames a child component (the settings list) in a rounded border with a title
@@ -46,6 +47,15 @@ export declare function extensionItems(extensions: InstalledExtension[], whiteli
 }[];
 /** Apply an extension toggle to the config's whitelist (idempotent both ways). */
 export declare function applyExtensionToggle(whitelist: readonly string[], entryPath: string, on: boolean): string[];
+export declare function toolItems(tools: readonly GuardableTool[], exempt: readonly string[]): {
+    id: string;
+    label: string;
+    description: string;
+    currentValue: string;
+    values: string[];
+}[];
+/** Apply a per-tool watchdog toggle to the exemption list (idempotent both ways). */
+export declare function applyToolToggle(exempt: readonly string[], toolName: string, watched: boolean): string[];
 /**
  * Tallest body the settings list can render, so {@link BorderedBox} can pad
  * every frame to it and hold the border still. Mirrors SettingsList's own
@@ -68,6 +78,6 @@ export type PanelItem = {
  */
 export declare function createSettingsPanel(items: PanelItem[], theme: Theme, onChange: (id: string, newValue: string) => void, onCancel: () => void): BorderedBox;
 /** The full settings row list for the current config, in menu order. */
-export declare function panelItems(cfg: PiTaskConfig, installed: InstalledExtension[]): PanelItem[];
+export declare function panelItems(cfg: PiTaskConfig, installed: InstalledExtension[], tools?: readonly GuardableTool[]): PanelItem[];
 export declare function registerConfig(pi: ExtensionAPI): void;
 export {};

package/dist/config/register.js

@@ -4,6 +4,7 @@ import { readPkgVersion } from '../shared/pkg-version.js';
 import { SEARCH_PROVIDERS, SEARCH_PROVIDER_LABELS, providerForLabel } from '../workers/search-types.js';
 import { COMMAND_TIMEOUT_OPTIONS, DEBUG_LOG_OPTIONS, getConfig, sanitizeDebugLogs, saveConfig, STREAM_INACTIVITY_OPTIONS } from './config.js';
 import { listInstalledExtensions } from './extension-list.js';
+import { listGuardableTools } from './tool-list.js';
 // Version in the title so a bug report or screenshot says which build it came
 // from without anyone having to go look it up.
 const CONFIG_TITLE = `pi-task ${readPkgVersion()} settings`;
@@ -215,6 +216,35 @@ export function applyExtensionToggle(whitelist, entryPath, on) {
     const rest = whitelist.filter(p => p !== entryPath);
     return on ? [...rest, entryPath] : rest;
 }
+/**
+ * One /task-config toggle per tool in the live session, so the command watchdog
+ * can be turned off for a single tool without unguarding `bash` with it.
+ *
+ * The list is DISCOVERED (see tool-list.ts), never typed: the id carries the
+ * exact tool name pi reports, which is the same string the watchdog matches on.
+ * A tool that is uninstalled simply stops being listed, and a stale name left in
+ * the config matches nothing.
+ */
+const TOOL_ID_PREFIX = 'tool:';
+export function toolItems(tools, exempt) {
+    return tools.map(t => ({
+        id: TOOL_ID_PREFIX + t.name,
+        label: `watch: ${t.name}`,
+        description: `Apply the command timeout to this tool. Leave it on unless the tool runs its own `
+            + `bounded, cancellable work for longer than the timeout — turning it off means a `
+            + `genuine hang in this tool will never be caught, and nothing else is watching `
+            + `while a tool runs. ${t.origin}`,
+        // Stored inverted: the config records the EXEMPTIONS, so an empty list
+        // (and any tool pi-task has never heard of) stays guarded by default.
+        currentValue: exempt.includes(t.name) ? 'off' : 'on',
+        values: ['on', 'off']
+    }));
+}
+/** Apply a per-tool watchdog toggle to the exemption list (idempotent both ways). */
+export function applyToolToggle(exempt, toolName, watched) {
+    const rest = exempt.filter(n => n !== toolName);
+    return watched ? rest : [...rest, toolName];
+}
 /** Overlay width; the list gets `- 4` of it, the description `- 4` again. */
 const OVERLAY_WIDTH = 68;
 /** Settings rows shown at once before the list scrolls. */
@@ -259,7 +289,7 @@ export function createSettingsPanel(items, theme, onChange, onCancel) {
     return new BorderedBox(list, CONFIG_TITLE, s => theme.fg('borderMuted', s), s => theme.fg('accent', theme.bold(s)), settingsBodyHeight(items.map(i => i.description), MAX_VISIBLE, OVERLAY_WIDTH - 8));
 }
 /** The full settings row list for the current config, in menu order. */
-export function panelItems(cfg, installed) {
+export function panelItems(cfg, installed, tools = []) {
     return [
         ...ITEMS.map(({ id, label, description, values }) => ({
             id: id,
@@ -268,17 +298,30 @@ export function panelItems(cfg, installed) {
             currentValue: displayValue(cfg, id, Boolean(values)),
             values: values ?? ['on', 'off']
         })),
+        ...toolItems(tools, cfg.commandTimeoutExemptTools),
         ...extensionItems(installed, cfg.extensionWhitelist)
     ];
 }
-async function handleTaskConfig(_args, ctx) {
-    const cfg = { ...getConfig(), extensionWhitelist: [...getConfig().extensionWhitelist] };
+async function handleTaskConfig(_args, ctx, getTools = () => []) {
+    const cfg = {
+        ...getConfig(),
+        extensionWhitelist: [...getConfig().extensionWhitelist],
+        commandTimeoutExemptTools: [...getConfig().commandTimeoutExemptTools]
+    };
     // Enumerated live at open so an installed extension appears and an
     // uninstalled one vanishes without pi-task doing any bookkeeping. A failed
     // enumeration only costs the extension toggles, never the whole menu.
     const installed = await listInstalledExtensions({ cwd: ctx.cwd }).catch(() => []);
+    // Same contract for tools, and for the same reason — plus one pi-specific
+    // one: getAllTools() throws until the extension runtime is initialized, so
+    // it can only be read here, when the menu opens, never at registration.
+    const tools = getTools();
     if (ctx.mode !== 'tui') {
         const lines = ITEMS.map(({ id, label, values }) => `${label.padEnd(22)} ${displayValue(cfg, id, Boolean(values))}`);
+        for (const t of tools) {
+            const state = cfg.commandTimeoutExemptTools.includes(t.name) ? 'off' : 'on';
+            lines.push(`${('watch: ' + t.name).padEnd(22)} ${state}`);
+        }
         for (const e of installed) {
             const state = cfg.extensionWhitelist.includes(e.path) ? 'on' : 'off';
             lines.push(`${('ext: ' + e.label).padEnd(22)} ${state}`);
@@ -286,10 +329,13 @@ async function handleTaskConfig(_args, ctx) {
         ctx.ui.notify(lines.join('  |  '), 'info');
         return;
     }
-    await ctx.ui.custom((_tui, theme, _kb, done) => createSettingsPanel(panelItems(cfg, installed), theme, (id, newValue) => {
+    await ctx.ui.custom((_tui, theme, _kb, done) => createSettingsPanel(panelItems(cfg, installed, tools), theme, (id, newValue) => {
         if (id.startsWith(EXT_ID_PREFIX)) {
             cfg.extensionWhitelist = applyExtensionToggle(cfg.extensionWhitelist, id.slice(EXT_ID_PREFIX.length), newValue === 'on');
         }
+        else if (id.startsWith(TOOL_ID_PREFIX)) {
+            cfg.commandTimeoutExemptTools = applyToolToggle(cfg.commandTimeoutExemptTools, id.slice(TOOL_ID_PREFIX.length), newValue === 'on');
+        }
         else if (id === 'searchProvider') {
             const provider = providerForLabel(newValue);
             if (provider)
@@ -321,7 +367,11 @@ async function handleTaskConfig(_args, ctx) {
 export function registerConfig(pi) {
     registerBridgeCommand(pi, 'task-config', {
         description: 'Configure pi-task settings (remote control, auto-commit, verify work, enforce '
-            + 'guidelines, research, timeouts, extensions for helper sessions).',
-        handler: handleTaskConfig
+            + 'guidelines, research, timeouts, per-tool command watchdog, extensions for helper '
+            + 'sessions).',
+        // `pi` is closed over rather than taken from ctx: ExtensionCommandContext
+        // has no tool accessor, and the read must happen inside the handler
+        // anyway (getAllTools throws until the runtime is initialized).
+        handler: (args, ctx) => handleTaskConfig(args, ctx, () => listGuardableTools(pi))
     });
 }

package/dist/config/tool-list.d.ts

@@ -0,0 +1,50 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/**
+ * The tools /task-config offers a command-watchdog toggle for, discovered from
+ * the live session rather than named by hand.
+ *
+ * WHY DISCOVERY AND NOT A HAND-EDITED NAME LIST: the watchdog arms on ANY tool
+ * (see task/command-watchdog.ts), which is correct for `bash` — pi's bash takes
+ * an OPTIONAL `timeout` with no default, so an unbounded command runs forever —
+ * but wrong for an extension tool that already owns a longer, bounded contract
+ * of its own. Those tools get aborted mid-transaction at the generic ceiling.
+ * The operator has to be able to say "not this one", and the only identity that
+ * survives a rename or an uninstall is the one pi itself reports.
+ *
+ * MEASURED against pi 0.83.0 (`pi.getAllTools()`), not assumed:
+ *   - built-ins report `source: "builtin"`, `path: "<builtin:bash>"`
+ *   - extension tools report the extension's real entry-point path — the SAME
+ *     identity `extensionWhitelist` keys on (see extension-list.ts)
+ *   - `getAllTools()` THROWS during extension loading ("Extension runtime not
+ *     initialized"); it is only callable from `session_start` onward, which is
+ *     why this is read when the menu opens and never at registration.
+ *   - `getActiveTools()` is a strict SUBSET (4 of 7 built-ins in a plain
+ *     session), so it is the wrong source: a tool the model isn't currently
+ *     offered is still a tool the watchdog would arm on if it ran.
+ */
+export interface GuardableTool {
+    /** Exact tool name — the watchdog's key, and what the config stores. */
+    name: string;
+    /** Provenance shown in the menu, e.g. "built in" or "npm:pi-fable". */
+    origin: string;
+}
+/**
+ * Every tool in the live session, built-ins first and each extension's tools in
+ * registration order after them, so the menu reads owner-by-owner.
+ *
+ * Pure over the ToolInfo list so the ordering and labelling are unit-testable
+ * without a running pi; {@link listGuardableTools} supplies the live one.
+ */
+export declare function toGuardableTools(tools: readonly {
+    name: string;
+    sourceInfo: {
+        source: string;
+        path: string;
+    };
+}[]): GuardableTool[];
+/**
+ * The live tool list, or `[]` if pi cannot answer. Enumeration failing must cost
+ * only the per-tool rows, never the whole settings menu — the same contract
+ * listInstalledExtensions() has in the command handler.
+ */
+export declare function listGuardableTools(pi: ExtensionAPI): GuardableTool[];

package/dist/config/tool-list.js

@@ -0,0 +1,53 @@
+/** `source` values pi reports for its own tools rather than an extension's. */
+const BUILTIN_SOURCE = 'builtin';
+/**
+ * Human provenance for a tool's source metadata. `source` is pi's own word for
+ * where the owner came from ("builtin", "npm:...", "auto", "cli"); the two
+ * discovery-shaped values are spelled out because "auto" tells the operator
+ * nothing about which extension they are about to unguard.
+ */
+function toolOrigin(source, path) {
+    if (source === BUILTIN_SOURCE)
+        return 'built in';
+    if (source === 'auto')
+        return `discovered (${path})`;
+    if (source === 'cli')
+        return `-e flag (${path})`;
+    return `${source} (${path})`;
+}
+/**
+ * Every tool in the live session, built-ins first and each extension's tools in
+ * registration order after them, so the menu reads owner-by-owner.
+ *
+ * Pure over the ToolInfo list so the ordering and labelling are unit-testable
+ * without a running pi; {@link listGuardableTools} supplies the live one.
+ */
+export function toGuardableTools(tools) {
+    const builtins = [];
+    const rest = [];
+    const seen = new Set();
+    for (const t of tools) {
+        // A duplicate name cannot be told apart by the watchdog (it only ever
+        // sees `toolName`), so a second registration must not add a second row
+        // that silently toggles the first one's guard.
+        if (seen.has(t.name))
+            continue;
+        seen.add(t.name);
+        const entry = { name: t.name, origin: toolOrigin(t.sourceInfo.source, t.sourceInfo.path) };
+        (t.sourceInfo.source === BUILTIN_SOURCE ? builtins : rest).push(entry);
+    }
+    return [...builtins, ...rest];
+}
+/**
+ * The live tool list, or `[]` if pi cannot answer. Enumeration failing must cost
+ * only the per-tool rows, never the whole settings menu — the same contract
+ * listInstalledExtensions() has in the command handler.
+ */
+export function listGuardableTools(pi) {
+    try {
+        return toGuardableTools(pi.getAllTools());
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -18,8 +18,15 @@
  * 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.
+ *   main session — ctx.abort() ends the whole agent operation, not just the one
+ *                  tool call (pi types it "Abort the current agent operation"),
+ *                  and pi runs sibling tool calls CONCURRENTLY by default. So an
+ *                  overrun kills every tool in flight in that turn — including
+ *                  one exempted via commandTimeoutExemptTools, which only stops
+ *                  a timer being armed FOR that tool, not its being collateral
+ *                  when a guarded sibling trips. There is no per-call
+ *                  cancellation channel to do better with. The session itself
+ *                  survives to receive the 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:
@@ -38,6 +45,8 @@ export interface WatchdogDeps {
      * 0 (or any non-positive value) means the watchdog is off and never arms.
      */
     getTimeoutMs: () => number;
+    /** Optional exact policy for tools with their own bounded execution contract. */
+    shouldWatch?: (toolName: string) => boolean;
     schedule: (fn: () => void, ms: number) => TimerHandle;
     cancel: (handle: TimerHandle) => void;
     /** Invoked when a command overruns: each adapter aborts/kills here. */

package/dist/shared/command-watchdog.js

@@ -18,8 +18,15 @@
  * 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.
+ *   main session — ctx.abort() ends the whole agent operation, not just the one
+ *                  tool call (pi types it "Abort the current agent operation"),
+ *                  and pi runs sibling tool calls CONCURRENTLY by default. So an
+ *                  overrun kills every tool in flight in that turn — including
+ *                  one exempted via commandTimeoutExemptTools, which only stops
+ *                  a timer being armed FOR that tool, not its being collateral
+ *                  when a guarded sibling trips. There is no per-call
+ *                  cancellation channel to do better with. The session itself
+ *                  survives to receive the 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:
@@ -105,11 +112,14 @@ export class CommandWatchdog {
     }
     /** Arm a timer for a starting tool. No-op when the watchdog is off. */
     onStart(toolCallId, toolName) {
+        // Disarm first so a live policy/config change cannot leave a timer from
+        // a duplicate start armed after the tool becomes exempt or watchdog-off.
+        this.disarm(toolCallId);
+        if (this.deps.shouldWatch?.(toolName) === false)
+            return;
         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);
     }

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

@@ -15,8 +15,11 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
  * 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.
+ * Tool-agnostic by default: it arms on every tool except exact names listed in
+ * `commandTimeoutExemptTools`, which /task-config fills from the live tool list
+ * (config/tool-list.ts). Exemptions are for tools that already own a bounded
+ * timeout and cancellation contract — the guard's whole justification is that
+ * pi's bash has NO default timeout, which says nothing about a tool that does.
  *
  * SCOPE — this covers the main session ONLY, which is where the implementation
  * turn runs (orchestrator hands the spec off via sendUserMessage). Gate

package/dist/task/command-watchdog.js

@@ -16,8 +16,11 @@ import { CommandWatchdog, realTimerDeps, reminderMessage } from '../shared/comma
  * 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.
+ * Tool-agnostic by default: it arms on every tool except exact names listed in
+ * `commandTimeoutExemptTools`, which /task-config fills from the live tool list
+ * (config/tool-list.ts). Exemptions are for tools that already own a bounded
+ * timeout and cancellation contract — the guard's whole justification is that
+ * pi's bash has NO default timeout, which says nothing about a tool that does.
  *
  * SCOPE — this covers the main session ONLY, which is where the implementation
  * turn runs (orchestrator hands the spec off via sendUserMessage). Gate
@@ -64,6 +67,7 @@ export function registerCommandWatchdog(pi) {
     const ctxByCall = new Map();
     const watchdog = new CommandWatchdog({
         getTimeoutMs: () => getConfig().requestTimeoutMs,
+        shouldWatch: toolName => !getConfig().commandTimeoutExemptTools.includes(toolName),
         ...realTimerDeps,
         onFire: (toolCallId, toolName, timeoutMs) => {
             const ctx = ctxByCall.get(toolCallId);

package/dist/workers/docs-core.js

@@ -106,9 +106,24 @@ export async function runAutoInstall(spawn, packageName, signal, versionRange) {
     // `shell: false` in runChild, so a `^`/`~`/space in the range stays a single
     // literal arg — no glob/expansion risk from `<pkg>@<range>`.
     const target = versionRange ? `${packageName}@${versionRange}` : packageName;
+    // `--ignore-scripts` is not optional here. The package NAME is model-chosen —
+    // it comes out of a worker's question, or out of a `/// <reference types="X" />`
+    // line in someone else's declaration file — so a hallucinated or typosquatted
+    // name would otherwise run its preinstall/postinstall as the user. This cache
+    // has already run install hooks for `node`, `argon2`, `onnxruntime-node` and
+    // `sharp`, next to fetched names like `app.ts`, `pkg.json` and `tsconfig.json`.
+    // Nothing is lost: the docs worker only ever READS `.d.ts` files and the README
+    // out of the installed tree, and those ship in the tarball.
     const result = await runChild(spawn, {
         command: 'npm',
-        args: ['install', '--no-audit', '--no-fund', '--loglevel=error', target]
+        args: [
+            'install',
+            '--ignore-scripts',
+            '--no-audit',
+            '--no-fund',
+            '--loglevel=error',
+            target
+        ]
     }, installDir, signal, { mode: 'text', discardStdout: true });
     return { success: result.exitCode === 0 && !result.aborted, installDir, stderr: result.stderr };
 }

package/dist/workers/docs-resolve.d.ts

@@ -30,9 +30,27 @@ export declare function resolvePackage(moduleName: string, cwd: string): Resolve
 export declare function typesPackageName(moduleName: string): string | null;
 /** True if the package ships at least one declaration file. */
 export declare function hasTypeFiles(root: string): boolean;
+/**
+ * Count declarations in a declaration file's text, ignoring comments, blank
+ * lines, and the pointer lines a redirect stub is made of (`/// <reference .. />`
+ * and `export * from "X"`).
+ *
+ * This is the discriminator `detectTypesRedirect` needs: a redirect stub is a
+ * file with essentially nothing in it but the pointer, while an API surface that
+ * merely *declares an ambient dependency* on another types package (the
+ * `sharp` -> `/// <reference types="node" />` shape) carries its own
+ * declarations. Counting `.d.ts` FILES cannot tell those apart — sharp ships one
+ * 1971-line file and `@types/bun` ships one 1-line file, and both count as 1.
+ *
+ * Deliberately lexical, not a TypeScript parse: this runs in the shipped worker,
+ * which has no compiler dependency. Over-counting is the safe direction (a
+ * declaration found ⇒ not a stub ⇒ keep the package's own types).
+ */
+export declare function countEntryDeclarations(content: string): number;
 /** When a package is a pure pointer to another types package — a single-file
  *  `/// <reference types="X" />` (the `@types/bun -> bun-types` shape) or a lone
  *  `export * from "X"` re-export — return the target package name. Returns null
- *  for packages that ship their own declarations (more than one .d.ts file, or a
- *  local `/// <reference path=... />` aggregator entry). */
+ *  for packages that ship their own declarations (more than one .d.ts file, a
+ *  local `/// <reference path=... />` aggregator entry, or an entry file that
+ *  declares anything of its own). */
 export declare function detectTypesRedirect(pkg: ResolvedPackage): string | null;

package/dist/workers/docs-resolve.js

@@ -223,11 +223,55 @@ function isBareSpecifier(spec) {
 }
 const REFERENCE_TYPES_RE = /\/\/\/\s*<reference\s+types=["']([^"']+)["']\s*\/>/;
 const REEXPORT_ALL_RE = /^\s*export\s+(?:type\s+)?\*\s+from\s+["']([^"']+)["'];?\s*$/m;
+const BLOCK_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
+const DECLARATION_RE = /^\s*(?:export\s+(?:default\s+)?)?(?:declare\s+)?(?:abstract\s+|async\s+)?(?:interface|type|class|function|const|let|var|namespace|module|enum)\b/;
+/**
+ * Count declarations in a declaration file's text, ignoring comments, blank
+ * lines, and the pointer lines a redirect stub is made of (`/// <reference .. />`
+ * and `export * from "X"`).
+ *
+ * This is the discriminator `detectTypesRedirect` needs: a redirect stub is a
+ * file with essentially nothing in it but the pointer, while an API surface that
+ * merely *declares an ambient dependency* on another types package (the
+ * `sharp` -> `/// <reference types="node" />` shape) carries its own
+ * declarations. Counting `.d.ts` FILES cannot tell those apart — sharp ships one
+ * 1971-line file and `@types/bun` ships one 1-line file, and both count as 1.
+ *
+ * Deliberately lexical, not a TypeScript parse: this runs in the shipped worker,
+ * which has no compiler dependency. Over-counting is the safe direction (a
+ * declaration found ⇒ not a stub ⇒ keep the package's own types).
+ */
+export function countEntryDeclarations(content) {
+    const stripped = content.replace(BLOCK_COMMENT_RE, '');
+    let n = 0;
+    for (const raw of stripped.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('//'))
+            continue;
+        if (REEXPORT_ALL_RE.test(line))
+            continue;
+        if (DECLARATION_RE.test(line))
+            n++;
+    }
+    return n;
+}
+/** The package a declaration file points at: a triple-slash `<reference types>`
+ *  or a whole-module `export * from`. Null when the file points nowhere. */
+function pointerTarget(content) {
+    const ref = REFERENCE_TYPES_RE.exec(content);
+    if (ref && isBareSpecifier(ref[1]))
+        return parentPackageName(ref[1]);
+    const rex = REEXPORT_ALL_RE.exec(content);
+    if (rex && isBareSpecifier(rex[1]))
+        return parentPackageName(rex[1]);
+    return null;
+}
 /** When a package is a pure pointer to another types package — a single-file
  *  `/// <reference types="X" />` (the `@types/bun -> bun-types` shape) or a lone
  *  `export * from "X"` re-export — return the target package name. Returns null
- *  for packages that ship their own declarations (more than one .d.ts file, or a
- *  local `/// <reference path=... />` aggregator entry). */
+ *  for packages that ship their own declarations (more than one .d.ts file, a
+ *  local `/// <reference path=... />` aggregator entry, or an entry file that
+ *  declares anything of its own). */
 export function detectTypesRedirect(pkg) {
     // A package that ships multiple declaration files is an aggregator, not a
     // redirect stub — use its own types.
@@ -247,11 +291,16 @@ export function detectTypesRedirect(pkg) {
     // declarations (e.g. bun-types) — not a redirect to another package.
     if (/\/\/\/\s*<reference\s+path=/.test(content))
         return null;
-    const ref = REFERENCE_TYPES_RE.exec(content);
-    if (ref && isBareSpecifier(ref[1]))
-        return parentPackageName(ref[1]);
-    const rex = REEXPORT_ALL_RE.exec(content);
-    if (rex && isBareSpecifier(rex[1]))
-        return parentPackageName(rex[1]);
-    return null;
+    const target = pointerTarget(content);
+    if (!target)
+        return null;
+    // A pointer line is not a redirect when the file it sits in also declares an
+    // API. `/// <reference types="node" />` in a package like sharp is an AMBIENT
+    // DEPENDENCY declaration — "my types need node's" — not "my types ARE node's";
+    // following it answered every sharp question out of @types/node (tty.d.ts,
+    // zlib.d.ts) while sharp's own 1971-line surface sat one file away. The .d.ts
+    // FILE count cannot see this: sharp ships one file and so does @types/bun.
+    if (countEntryDeclarations(content) > 0)
+        return null;
+    return target;
 }

package/package.json

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