@mjasnikovs/pi-task 0.18.26 → 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/api-synthesis.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Anti-synthesis guard for grill/clarify auto-answers (mx5 run-13 Bug A).
+ *
+ * The grill auto-answer channel invented `Bun.mkdirSync` (does not exist) while
+ * the task's own research APIS section carried the correct list (Bun.build,
+ * Bun.spawn). Nothing cross-checked the answer against it, so the invention was
+ * promoted into the task's title, requirements, acceptance criteria AND VERIFY
+ * block, and the implementer shipped a fake ambient declare to compile it.
+ *
+ * Lever: the same verbatim-substring anti-synthesis check as the F3 contract
+ * registry. Extract API-shaped identifiers (`Namespace.member`) from the answer;
+ * an identifier is SYNTHESIZED when
+ *   (a) the full identifier appears nowhere in the research (APIS/docs/context
+ *       sections, verbatim substring, case-sensitive) and nowhere in the
+ *       question itself, AND
+ *   (b) the research DOES mention that namespace's API surface (`Bun.` appears
+ *       somewhere) — i.e. research claims coverage of the namespace, so a
+ *       member absent from it is suspicious rather than merely uncovered.
+ * Gate (b) is the step-aside rule: when research never mentions the namespace
+ * at all (React.StrictMode in a task whose research covered no React API), the
+ * check is INCONCLUSIVE and must not fire — the guard may only cost time,
+ * never work. Same for the clarify-triage seam, whose research slot is a stub:
+ * no namespace coverage ⇒ no findings ⇒ guard inert by construction.
+ *
+ * Caller contract (phaseAutoAnswer): findings ⇒ re-ask ONCE with the research
+ * API lines injected (belt); a re-asked answer that still carries a flagged
+ * identifier is surfaced to the user as UNKNOWN instead of being promoted.
+ */
+export interface SynthesizedApiFinding {
+    /** The full flagged identifier, e.g. "Bun.mkdirSync". */
+    identifier: string;
+    /** Its namespace, e.g. "Bun" — research mentions `Bun.` but not this member. */
+    namespace: string;
+}
+/** All API-shaped identifiers in a text, deduped, first-seen order. */
+export declare function extractApiIdentifiers(text: string): string[];
+/**
+ * The synthesized identifiers in an auto-answer: API-shaped, absent from the
+ * research and the question, in a namespace the research claims to cover.
+ * Verbatim-substring membership — never a model judgement.
+ */
+export declare function findSynthesizedApis(answer: string, question: string, research: string): SynthesizedApiFinding[];
+/**
+ * Re-ask hint (SYSTEM NOTE shape, mirrors GRILL_AUTO_FORMAT_HINT): names the
+ * unverified identifiers, injects the research lines that ARE verified for
+ * those namespaces, and demands an answer grounded in them — or UNKNOWN.
+ */
+export declare function synthesizedApiReaskHint(findings: SynthesizedApiFinding[], research: string): string;

package/dist/task/api-synthesis.js

@@ -0,0 +1,155 @@
+/**
+ * Anti-synthesis guard for grill/clarify auto-answers (mx5 run-13 Bug A).
+ *
+ * The grill auto-answer channel invented `Bun.mkdirSync` (does not exist) while
+ * the task's own research APIS section carried the correct list (Bun.build,
+ * Bun.spawn). Nothing cross-checked the answer against it, so the invention was
+ * promoted into the task's title, requirements, acceptance criteria AND VERIFY
+ * block, and the implementer shipped a fake ambient declare to compile it.
+ *
+ * Lever: the same verbatim-substring anti-synthesis check as the F3 contract
+ * registry. Extract API-shaped identifiers (`Namespace.member`) from the answer;
+ * an identifier is SYNTHESIZED when
+ *   (a) the full identifier appears nowhere in the research (APIS/docs/context
+ *       sections, verbatim substring, case-sensitive) and nowhere in the
+ *       question itself, AND
+ *   (b) the research DOES mention that namespace's API surface (`Bun.` appears
+ *       somewhere) — i.e. research claims coverage of the namespace, so a
+ *       member absent from it is suspicious rather than merely uncovered.
+ * Gate (b) is the step-aside rule: when research never mentions the namespace
+ * at all (React.StrictMode in a task whose research covered no React API), the
+ * check is INCONCLUSIVE and must not fire — the guard may only cost time,
+ * never work. Same for the clarify-triage seam, whose research slot is a stub:
+ * no namespace coverage ⇒ no findings ⇒ guard inert by construction.
+ *
+ * Caller contract (phaseAutoAnswer): findings ⇒ re-ask ONCE with the research
+ * API lines injected (belt); a re-asked answer that still carries a flagged
+ * identifier is surfaced to the user as UNKNOWN instead of being promoted.
+ */
+/**
+ * `Namespace.member` where the namespace starts uppercase (Bun, React, Deno —
+ * the global/imported-namespace API shape; run-13's TP is exactly this) and
+ * both sides are ≥2 chars (kills "U.S.", "e.G" prose shapes). Member may start
+ * either case: `Bun.mkdirSync` and `React.StrictMode` are both API-shaped.
+ */
+const API_IDENT_RE = /\b([A-Z][A-Za-z0-9_$]+)\.([A-Za-z_$][A-Za-z0-9_$]+)\b/g;
+/**
+ * Member names that make the match a file name, domain, or version-ish token
+ * rather than an API (Node.js, App.tsx, README.md, Fly.io, Express.com). All
+ * lowercase-compared, so `INDEX.HTML` is excluded too.
+ */
+const NON_API_MEMBERS = new Set([
+    'js',
+    'ts',
+    'jsx',
+    'tsx',
+    'mjs',
+    'cjs',
+    'mts',
+    'cts',
+    'json',
+    'jsonc',
+    'md',
+    'html',
+    'htm',
+    'css',
+    'scss',
+    'less',
+    'svg',
+    'png',
+    'jpg',
+    'jpeg',
+    'gif',
+    'ico',
+    'txt',
+    'yml',
+    'yaml',
+    'toml',
+    'lock',
+    'map',
+    'env',
+    'sh',
+    'sql',
+    'db',
+    'sqlite',
+    'wasm',
+    'node',
+    'exe',
+    'com',
+    'org',
+    'net',
+    'io',
+    'dev',
+    'app',
+    'ai',
+    'co',
+    'gg'
+]);
+/** All API-shaped identifiers in a text, deduped, first-seen order. */
+export function extractApiIdentifiers(text) {
+    const out = [];
+    const seen = new Set();
+    for (const m of text.matchAll(API_IDENT_RE)) {
+        const [full, , member] = m;
+        if (NON_API_MEMBERS.has(member.toLowerCase()))
+            continue;
+        if (seen.has(full))
+            continue;
+        seen.add(full);
+        out.push(full);
+    }
+    return out;
+}
+/**
+ * The synthesized identifiers in an auto-answer: API-shaped, absent from the
+ * research and the question, in a namespace the research claims to cover.
+ * Verbatim-substring membership — never a model judgement.
+ */
+export function findSynthesizedApis(answer, question, research) {
+    const out = [];
+    for (const identifier of extractApiIdentifiers(answer)) {
+        if (research.includes(identifier) || question.includes(identifier))
+            continue;
+        const namespace = identifier.slice(0, identifier.indexOf('.'));
+        // Step-aside gate: research must claim this namespace's API surface.
+        if (!research.includes(`${namespace}.`))
+            continue;
+        out.push({ identifier, namespace });
+    }
+    return out;
+}
+/** Research lines that mention any flagged namespace — the verified API list to inject. */
+function verifiedApiLines(findings, research) {
+    const namespaces = new Set(findings.map(f => f.namespace));
+    const lines = [];
+    for (const line of research.split('\n')) {
+        const t = line.trim();
+        if (t.length === 0)
+            continue;
+        for (const ns of namespaces) {
+            if (t.includes(`${ns}.`)) {
+                lines.push(t);
+                break;
+            }
+        }
+    }
+    return lines.slice(0, 20);
+}
+/**
+ * Re-ask hint (SYSTEM NOTE shape, mirrors GRILL_AUTO_FORMAT_HINT): names the
+ * unverified identifiers, injects the research lines that ARE verified for
+ * those namespaces, and demands an answer grounded in them — or UNKNOWN.
+ */
+export function synthesizedApiReaskHint(findings, research) {
+    const flagged = findings.map(f => `\`${f.identifier}\``).join(', ');
+    const verified = verifiedApiLines(findings, research);
+    return (`[SYSTEM NOTE: Your previous answer named ${flagged} — NOT present in this task's `
+        + 'verified research API list, so it may not exist (a plausible-looking invented API '
+        + 'poisons the whole task: it gets promoted into requirements and VERIFY, and the '
+        + 'implementation fakes type declarations to compile it). The VERIFIED research lines '
+        + 'for that namespace are:\n'
+        + verified.map(l => `  ${l}`).join('\n')
+        + '\nAnswer again using ONLY APIs from the research or the question. If the behavior '
+        + 'needs an API the research does not list, do NOT invent one — describe the behavior '
+        + 'without naming a concrete API, or tag UNKNOWN.]');
+}

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