@mjasnikovs/pi-task 0.18.25 → 0.18.27

package/dist/config/config.d.ts

@@ -42,7 +42,36 @@ export interface PiTaskConfig {
      * /task-config, which enumerates the currently installed extensions.
      */
     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
+     * (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.
+     * 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.
+     */
+    requestTimeoutMs: number;
 }
+/**
+ * The command-watchdog timeout choices offered by /task-config, newest-first in
+ * the cycle order the picker shows. The stored config value is the ms number;
+ * the label is display-only (mirrors the searchProvider label/value split).
+ */
+export declare const COMMAND_TIMEOUT_OPTIONS: ReadonlyArray<{
+    label: string;
+    ms: number;
+}>;
+/**
+ * A hand-edited or stale config could carry any number (or a string); pin it to
+ * one of the offered choices so the watchdog never arms on a nonsense value.
+ */
+export declare function sanitizeRequestTimeoutMs(value: unknown): number;
 /**
  * A hand-edited config can hold anything; keep only string entries so a stray
  * object/number can't reach the child argv as `-e [object Object]`.

package/dist/config/config.js

@@ -3,6 +3,28 @@ import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { isSearchProvider } from '../workers/search-types.js';
+/**
+ * The command-watchdog timeout choices offered by /task-config, newest-first in
+ * the cycle order the picker shows. The stored config value is the ms number;
+ * the label is display-only (mirrors the searchProvider label/value split).
+ */
+export const COMMAND_TIMEOUT_OPTIONS = [
+    { label: '5 min', ms: 5 * 60_000 },
+    { label: '10 min', ms: 10 * 60_000 },
+    { label: '15 min', ms: 15 * 60_000 },
+    { label: '30 min', ms: 30 * 60_000 },
+    { label: 'off', ms: 0 }
+];
+const DEFAULT_REQUEST_TIMEOUT_MS = 15 * 60_000;
+/**
+ * A hand-edited or stale config could carry any number (or a string); pin it to
+ * one of the offered choices so the watchdog never arms on a nonsense value.
+ */
+export function sanitizeRequestTimeoutMs(value) {
+    return COMMAND_TIMEOUT_OPTIONS.some(o => o.ms === value) ?
+        value
+        : DEFAULT_REQUEST_TIMEOUT_MS;
+}
 const DEFAULTS = {
     remote: true,
     compressReasoning: true,
@@ -15,7 +37,8 @@ const DEFAULTS = {
     // 3/3, 0 collisions; ~14.5s of repeated docs lookups collapse to 0ms on a hit).
     researchCache: true,
     searchProvider: 'exa',
-    extensionWhitelist: []
+    extensionWhitelist: [],
+    requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS
 };
 /**
  * A hand-edited config can hold anything; keep only string entries so a stray
@@ -43,6 +66,7 @@ if (!G.loaded) {
         if (!isSearchProvider(parsed.searchProvider))
             delete parsed.searchProvider;
         parsed.extensionWhitelist = sanitizeExtensionWhitelist(parsed.extensionWhitelist);
+        parsed.requestTimeoutMs = sanitizeRequestTimeoutMs(parsed.requestTimeoutMs);
         G.config = { ...DEFAULTS, ...parsed };
     }
     catch {

package/dist/config/register.js

@@ -1,7 +1,7 @@
 import { SettingsList, visibleWidth } from '@earendil-works/pi-tui';
 import { registerBridgeCommand } from '../remote/bridge.js';
 import { SEARCH_PROVIDERS, SEARCH_PROVIDER_LABELS, providerForLabel } from '../workers/search-types.js';
-import { getConfig, saveConfig } from './config.js';
+import { COMMAND_TIMEOUT_OPTIONS, getConfig, saveConfig } from './config.js';
 import { listInstalledExtensions } from './extension-list.js';
 const CONFIG_TITLE = 'pi-task settings';
 /**
@@ -95,12 +95,28 @@ const ITEMS = [
         description: 'Engine behind web search (pi-worker-search + freshness checks). Exa and DuckDuckGo need no API key; Brave needs BRAVE_SEARCH_API_KEY',
         // Display full engine names; the stored config value stays the short id.
         values: SEARCH_PROVIDERS.map(p => SEARCH_PROVIDER_LABELS[p])
+    },
+    {
+        id: 'requestTimeoutMs',
+        label: 'command timeout',
+        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',
+        // Display human labels; the stored config value stays the ms number.
+        values: COMMAND_TIMEOUT_OPTIONS.map(o => o.label)
     }
 ];
+/** Human label for the stored command-timeout ms (falls back to the raw ms). */
+function timeoutLabel(ms) {
+    return COMMAND_TIMEOUT_OPTIONS.find(o => o.ms === ms)?.label ?? `${ms}ms`;
+}
 /** What /task-config shows for a setting's current value. */
 function displayValue(cfg, id, isEnum) {
     if (id === 'searchProvider')
         return SEARCH_PROVIDER_LABELS[cfg.searchProvider];
+    if (id === 'requestTimeoutMs')
+        return timeoutLabel(cfg.requestTimeoutMs);
     if (isEnum)
         return String(cfg[id]);
     return cfg[id] ? 'on' : 'off';
@@ -173,6 +189,11 @@ async function handleTaskConfig(_args, ctx) {
                 if (provider)
                     cfg.searchProvider = provider;
             }
+            else if (id === 'requestTimeoutMs') {
+                const opt = COMMAND_TIMEOUT_OPTIONS.find(o => o.label === newValue);
+                if (opt)
+                    cfg.requestTimeoutMs = opt.ms;
+            }
             else {
                 ;
                 cfg[id] = newValue === 'on';
@@ -185,7 +206,7 @@ async function handleTaskConfig(_args, ctx) {
 export function registerConfig(pi) {
     registerBridgeCommand(pi, 'task-config', {
         description: 'Configure pi-task settings (remote, compress reasoning, auto-commit, orientation, '
-            + 'enforce guidelines, extension whitelist for child sessions).',
+            + 'enforce guidelines, command timeout, extension whitelist for child sessions).',
         handler: handleTaskConfig
     });
 }

package/dist/index.js

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

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

@@ -0,0 +1,67 @@
+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.
+ *
+ * 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. 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.
+ */
+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;
+}
+/**
+ * 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
+ * happen.
+ */
+export declare function registerCommandWatchdog(pi: ExtensionAPI): void;

package/dist/task/command-watchdog.js

@@ -0,0 +1,114 @@
+import { getConfig } from '../config/config.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.
+ */
+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);
+    }
+}
+/**
+ * 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
+ * happen.
+ */
+export function registerCommandWatchdog(pi) {
+    // The ctx that owns each in-flight tool's AbortSignal, captured per start so
+    // the timer callback (which fires outside the event handler) aborts the
+    // right operation.
+    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),
+        onFire: (toolCallId, toolName, timeoutMs) => {
+            const ctx = ctxByCall.get(toolCallId);
+            ctxByCall.delete(toolCallId);
+            // Cancel the stuck command (kills the tool's whole process tree via
+            // the turn's AbortSignal), then start a fresh turn telling the model
+            // to bound its next attempt.
+            ctx?.abort();
+            pi.sendUserMessage(reminderMessage(toolName, timeoutMs), { deliverAs: 'followUp' });
+        }
+    });
+    pi.on('tool_execution_start', (event, ctx) => {
+        ctxByCall.set(event.toolCallId, ctx);
+        watchdog.onStart(event.toolCallId, event.toolName);
+    });
+    pi.on('tool_execution_end', event => {
+        ctxByCall.delete(event.toolCallId);
+        watchdog.onEnd(event.toolCallId);
+    });
+    // Safety net: nothing should outlive its turn, but if a start ever lacks a
+    // matching end, clear on turn/session teardown so no timer fires stale.
+    const reset = () => {
+        watchdog.clearAll();
+        ctxByCall.clear();
+    };
+    pi.on('turn_end', reset);
+    pi.on('session_shutdown', reset);
+}

package/dist/task/final-gate.js

@@ -383,6 +383,12 @@ export function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}) {
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env }
         });
+        // Best-effort cleanup only: killGroup below can silently fail to reap the
+        // process (platform/sandbox-specific — observed on a GH Actions Linux
+        // runner where the group-kill did not take, hanging the whole `bun test
+        // --isolate` run on the leaked child's piped stdio). unref() so a child
+        // we already tried to kill can never itself keep this process alive.
+        child.unref();
         let out = '';
         let err = '';
         let listenerSeen = false;

package/dist/task/phases.js

@@ -30,6 +30,8 @@ import { findSkipEscapes, skipEscapeDefectText } from './skip-escape.js';
 import { findSynthesizedWiring, wiringProbeText, readReferencedDocs } from './wiring-claims.js';
 import { findAbsenceConflicts, absenceProbeText, siblingTitlesFromPlanContext } from './verify-reconcile.js';
 import { findFrozenPathConflicts, frozenConflictProbeText } from './frozen-conflict.js';
+import { findSynthesizedApis, synthesizedApiReaskHint } from './api-synthesis.js';
+import { findGrepOnlyVerify, grepOnlyVerifyDefectText, GREP_THEATER_RETRY_HINT } from './verify-quality.js';
 import { existsSync } from 'node:fs';
 import { readContracts, buildContractsBlock, buildContractsVerifyBlock } from './contracts.js';
 import { readRequirements, buildRequirementsBlock } from './requirements.js';
@@ -633,7 +635,43 @@ export async function phaseAutoAnswer(deps, refined, research, question, autoDep
             // otherwise a preamble line leaks out as the recommended answer.
             text = await runPhaseChild(deps, 'grill-auto', 'read', prependHint(GRILL_AUTO_FORMAT_HINT, basePrompt));
         }
-        const parsed = parseAutoAnswer(text);
+        let parsed = parseAutoAnswer(text);
+        // Anti-synthesis guard (mx5 run 13, Bug A): the auto-answer invented
+        // `Bun.mkdirSync` while research's APIS section carried the correct list,
+        // and the invention was promoted into requirements + VERIFY. Deterministic
+        // verbatim-substring check: an API-shaped identifier in the answer that is
+        // absent from the research AND the question, in a namespace the research
+        // claims to cover, triggers ONE re-ask with the verified research lines
+        // injected. Still synthesizing after the re-ask ⇒ surface to the user as a
+        // recommendation instead of silently promoting it (costs time, never work).
+        if (parsed.kind === 'answered') {
+            const synth = findSynthesizedApis(parsed.text, question, research);
+            if (synth.length > 0) {
+                deps.logDebug?.('grill-auto: unverified API identifier(s) in answer — '
+                    + synth.map(f => f.identifier).join(', ')
+                    + ' — re-asking with the research API list injected');
+                let reasked = null;
+                try {
+                    const text2 = await runPhaseChild(deps, 'grill-auto', 'read', prependHint(synthesizedApiReaskHint(synth, research), basePrompt));
+                    if (autoAnswerHasTag(text2))
+                        reasked = parseAutoAnswer(text2);
+                }
+                catch {
+                    reasked = null;
+                }
+                if (reasked === null
+                    || (reasked.kind === 'answered'
+                        && findSynthesizedApis(reasked.text, question, research).length > 0)) {
+                    const still = reasked ?? parsed;
+                    const suggested = still.kind === 'answered' ? still.text : parsed.text;
+                    deps.logDebug?.('grill-auto: answer still carries an unverified API — surfacing to user');
+                    parsed = { kind: 'unknown', suggested, raw: still.raw };
+                }
+                else {
+                    parsed = reasked;
+                }
+            }
+        }
         // Surviving-unknown routing: an integration / build-wiring unknown whose
         // wrong guess is a structural landmine must NOT be silently auto-answered.
         // We first try to ground it from fetched docs (the enrichment fan-out
@@ -866,6 +904,17 @@ export async function phaseCritique(deps, spec, refined, qa, planContext, resear
         deps.logDebug?.('unsatisfiable freeze/requires-edit pair flagged in spec: '
             + frozenConflicts.map(c => c.path).join(' | '));
     }
+    // DETERMINISTIC grep-theater probe (mx5 run 13, Bug B): a VERIFY block that
+    // grep-asserts the SOURCE of a runnable deliverable while every command in
+    // the block is static inspection — the build script "verified" by three
+    // greps that was never run, shipping broken for 14 tasks. Forced into the
+    // rewrite like the skip-escape finding: VERIFY must EXECUTE the artifact
+    // and assert an observable outcome of that run.
+    const grepOnly = findGrepOnlyVerify(spec);
+    const grepOnlyProbe = grepOnly.length > 0 ? grepOnlyVerifyDefectText(grepOnly) : null;
+    if (grepOnlyProbe) {
+        deps.logDebug?.('grep-theater VERIFY flagged in spec: ' + grepOnly.map(f => f.target).join(' | '));
+    }
     let triageDefects = null;
     if (parseVerifyBlock(spec) !== null) {
         const tTriage = Date.now();
@@ -883,14 +932,15 @@ export async function phaseCritique(deps, spec, refined, qa, planContext, resear
         deps.recordSubStep?.('triage', Date.now() - tTriage);
         if (verdict !== null) {
             // A deterministic skip-escape, synthesized-wiring, plan-contradiction,
-            // or unsatisfiable-pair finding overrides a CLEAN triage: the draft must
+            // unsatisfiable-pair, or grep-theater finding overrides a CLEAN triage: the draft must
             // be rewritten to resolve it even if the model judged the rest clean
             // (the model does not self-discover any of them reliably).
             if (isCritiqueClean(verdict)) {
                 if (skipDefects === null
                     && wiringProbe === null
                     && absenceProbe === null
-                    && frozenProbe === null) {
+                    && frozenProbe === null
+                    && grepOnlyProbe === null) {
                     return spec;
                 }
             }
@@ -900,22 +950,39 @@ export async function phaseCritique(deps, spec, refined, qa, planContext, resear
         }
     }
     // Merge the deterministic skip-escape + synthesized-wiring + plan-contradiction
-    // + unsatisfiable-pair defects with any triage defects for the rewrite (all are
-    // forced FOCUS items).
-    const rewriteDefects = [skipDefects, wiringProbe, absenceProbe, frozenProbe, triageDefects]
+    // + unsatisfiable-pair + grep-theater defects with any triage defects for the
+    // rewrite (all are forced FOCUS items).
+    const rewriteDefects = [skipDefects, wiringProbe, absenceProbe, frozenProbe, grepOnlyProbe, triageDefects]
         .filter(Boolean)
         .join('\n\n') || null;
     const tRewrite = Date.now();
     try {
-        return await runWithEmphasisRetry(deps, 'critique', 'read', problem => CRITIQUE_PROMPT(spec, refined, qa, problem !== null, rewriteDefects, contractsBlock), text => {
+        return await runWithEmphasisRetry(deps, 'critique', 'read', problem => {
+            const base = CRITIQUE_PROMPT(spec, refined, qa, problem === 'no_verify_block', rewriteDefects, contractsBlock);
+            // Theater retry gets a targeted hint (the generic emphasis line
+            // says "previous attempt had no VERIFY block", which is wrong
+            // here — it had one, it just never ran the deliverable).
+            return problem === 'verify_grep_theater' ?
+                prependHint(GREP_THEATER_RETRY_HINT, base)
+                : base;
+        }, text => {
             // The rewrite (thinking on) sometimes prepends narration before
             // GOAL; the prompt forbids it but this validator only checks for
             // a VERIFY block. Strip it so the delivered spec starts at GOAL.
             const stripped = stripSpecPreamble(text);
-            return parseVerifyBlock(stripped) ?
-                { ok: true, value: stripped }
-                : { ok: false, problem: 'no_verify_block' };
-        }, () => new Error('no_verify_block'));
+            if (parseVerifyBlock(stripped) === null) {
+                return { ok: false, problem: 'no_verify_block' };
+            }
+            // Detector-backed closure on the grep-theater defect: when the
+            // draft was flagged, the rewrite must actually resolve it (live
+            // A/B: 1/5 rewrites ignored the injected defect and re-shipped
+            // the grep-only block). One emphasis retry with a targeted hint;
+            // a second miss falls back to the draft in critiqueWithFallback.
+            if (grepOnlyProbe !== null && findGrepOnlyVerify(stripped).length > 0) {
+                return { ok: false, problem: 'verify_grep_theater' };
+            }
+            return { ok: true, value: stripped };
+        }, problem => new Error(problem));
     }
     finally {
         deps.recordSubStep?.('rewrite', Date.now() - tRewrite);
@@ -928,7 +995,7 @@ export async function critiqueWithFallback(d, p) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        if (msg !== 'no_verify_block')
+        if (msg !== 'no_verify_block' && msg !== 'verify_grep_theater')
             throw err;
         // Fall back to the compose draft — but only if it actually carries a
         // runnable VERIFY block. Critique reaches its rewrite path precisely
@@ -937,9 +1004,14 @@ export async function critiqueWithFallback(d, p) {
         // handoff gate rejects and resume can't heal. Compose now enforces a
         // parseable VERIFY, so this should hold; keep the guard so a regression
         // fails the run cleanly instead of shipping a broken spec.
+        // (verify_grep_theater: both rewrite attempts kept a grep-only VERIFY;
+        // the draft carries the same defect but is the validated-shape fallback
+        // — deliver it rather than fail the run. The guard costs time, never work.)
         if (parseVerifyBlock(p.spec) === null)
             throw err;
-        p.ctx.ui.notify("Critique couldn't produce a VERIFY block — using compose draft. Edit the spec manually if needed.", 'warning');
+        p.ctx.ui.notify(msg === 'verify_grep_theater' ?
+            'Critique rewrite kept a grep-only VERIFY — using compose draft. Consider adding a command that RUNS the deliverable.'
+            : "Critique couldn't produce a VERIFY block — using compose draft. Edit the spec manually if needed.", 'warning');
         return p.spec;
     }
 }

package/dist/task/prompts.js

@@ -231,6 +231,8 @@ LIVE-DATA RULE:
 - No npm block + question is about latest/current version → tag UNKNOWN (training data goes stale).
 - VERSION-PIN questions ("pin to X.y vs latest", "which major version") are costly-to-reverse build-shaping choices: unless the spec or an "### npm:" block already settles it (then ANSWER that value), tag UNKNOWN and surface it. NEVER auto-answer a downgrade to an OLDER major "to avoid breaking changes" from memory — that reasoning is exactly the stale-training-data trap. If an "### npm:" block shows a newer major than your instinct, that block is the live latest; do not silently pin an older major the live data and spec never asked for.
 
+API-GROUNDING RULE: never name a concrete API (\`Namespace.member\`, an imported function, a runtime builtin) that appears in neither the research notes nor the question. The research APIS list was verified against the installed types; an API you remember but the research does not list may simply not exist, and an invented one poisons the whole task downstream. If the behavior you recommend needs an API the research does not list, describe the behavior without naming an API, or tag UNKNOWN.
+
 TRIAGE — run these checks IN ORDER first. The REVERSIBILITY TEST below applies ONLY to a question that survives all checks as a genuine preference.
 
 1. ALREADY-DECIDED CHECK — scan the refined task and research for a value, shape, response body, schema, route, or requirement that ALREADY determines the answer. If one does, this is a fact, not a preference. Emit "ANSWER: <value taken from that source>". If your instinct or a "nicer" alternative contradicts that source, the SOURCE WINS — never override a stated contract with a preferred default. (E.g. a stated response shape { items, total, page, pageSize } already answers a pagination question — page/offset — you may NOT answer "cursor".)
@@ -323,6 +325,7 @@ VERIFY must exercise the surface area the task actually touches. Draw VERIFY com
 - TypeScript / JavaScript source changes → MUST include the project's typecheck, lint, and test commands when those scripts exist in TOOLING. Include build only if the change could affect the build output.
 - Python / Go / Rust / other source changes → MUST include the language's standard verification from TOOLING (e.g. \`pytest\`, \`go test ./...\`, \`cargo test\`) plus lint/typecheck if configured.
 - Config / infra-only changes with no executable verification → state that explicitly with a single command that re-reads or validates the config (e.g. \`docker compose config\`, \`nginx -t\`, \`yamllint file.yml\`). Never leave VERIFY with only \`true\` or \`echo ok\`.
+- Runnable deliverables (a build script, server, CLI, seed/migrate script) → VERIFY must EXECUTE the artifact and assert an observable outcome of that run (exit code, a file the run produces, a served response). A grep on the artifact's SOURCE proves nothing about behavior and is never sufficient on its own.
 
 When this task is one step of a larger plan: sibling steps' deliverables may already exist in the tree and more will land after this task. NEVER write a VERIFY check that fails because sibling work exists (e.g. "file X must not exist" when another step owns X). The plan context forbids you from BUILDING other steps' work — it does not make their work absent. Verify what THIS task adds or changes.
 

package/dist/task/verify-quality.d.ts

@@ -0,0 +1,26 @@
+export interface GrepOnlyVerifyFinding {
+    /** The runnable source file being grep-asserted, e.g. "build.ts". */
+    target: string;
+    /** The VERIFY lines that inspect it, verbatim. */
+    lines: string[];
+}
+/**
+ * Scan a composed spec's VERIFY block: all-static block that grep/cat-asserts
+ * runnable source ⇒ one finding per inspected file. Empty when the block
+ * contains any execution command, has no VERIFY block, or inspects no runnable
+ * source (doc/config-only tasks).
+ */
+export declare function findGrepOnlyVerify(spec: string): GrepOnlyVerifyFinding[];
+/**
+ * Retry hint when the critique rewrite KEPT the grep-theater block it was told
+ * to fix (live A/B: 1/5 rewrites ignored the injected defect). Prepended to the
+ * second rewrite attempt; the defect block naming the exact files is still in
+ * the prompt body.
+ */
+export declare const GREP_THEATER_RETRY_HINT: string;
+/**
+ * Render the findings as a defect block for the critique rewrite: VERIFY must
+ * EXECUTE the runnable deliverable and assert an observable outcome of THAT
+ * run, not grep its source.
+ */
+export declare function grepOnlyVerifyDefectText(findings: GrepOnlyVerifyFinding[]): string;

package/dist/task/verify-quality.js

@@ -0,0 +1,182 @@
+/**
+ * Grep-theater VERIFY detector (mx5 run-13 Bug B), compose-critique side.
+ *
+ * TASK_0018's VERIFY block "verified" a build script with tsc + three greps on
+ * build.ts's SOURCE — it never ran `bun build.ts`. The greps asserted the
+ * hallucinated `Bun.mkdirSync` line was present, so a broken build shipped
+ * green and stayed broken for 14 tasks. Grep-on-source is not verification of
+ * a runnable deliverable; only executing the artifact is.
+ *
+ * Deterministic shape (findSkipEscapes → critique-rewrite pattern): a finding
+ * fires when the VERIFY block (a) grep/cat-asserts the SOURCE of a runnable
+ * file (.ts/.js/.sh — a build script, server, CLI entry) and (b) contains NO
+ * execution command at all — every command is static inspection (grep, test,
+ * ls, cat, tsc --noEmit, eslint, prettier). Any real execution anywhere in the
+ * block (bun/node/npm run/test, curl, ./script) means the deliverable-runs
+ * question is at worst partially covered, and we step aside — the guard may
+ * only cost time, never work, so recall is floored at the unambiguous
+ * all-static case rather than chasing which command exercises which file.
+ */
+import { parseVerifyBlock } from './spec-validation.js';
+/** Commands that only inspect — they never execute the shipped artifact. */
+const STATIC_HEADS = new Set([
+    'grep',
+    'rg',
+    'cat',
+    'ls',
+    'test',
+    '[',
+    '[[',
+    'find',
+    'wc',
+    'head',
+    'tail',
+    'diff',
+    'stat',
+    'echo',
+    'printf',
+    'true',
+    'false',
+    'cd',
+    'pwd',
+    'which',
+    'command',
+    'file',
+    'jq',
+    'sed',
+    'awk',
+    'sort',
+    'uniq',
+    'cut',
+    'tr',
+    'sleep',
+    'exit',
+    // static-analysis tools: they read source, they don't run the deliverable
+    'tsc',
+    'eslint',
+    'prettier',
+    'biome'
+]);
+/** A bare (unquoted) path token ending in a runnable-source extension. */
+const RUNNABLE_SRC_RE = /^[\w@./-]+\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|sh)$/;
+/** Heads whose file arguments count as "inspecting the source of". */
+const INSPECT_HEADS = new Set(['grep', 'rg', 'cat', 'head', 'tail', 'wc']);
+/**
+ * Shell-control noise that precedes (or IS) a segment without being a command:
+ * `if grep -q x f; then` splits into an `if`-prefixed segment plus bare `then`;
+ * `… || { echo FAIL; exit 1; }` yields `{ echo …` and `}` segments. Treating
+ * these as unknown heads would count them as execution and silently blind the
+ * detector on exactly the incident shape (run-13's VERIFY used all of them).
+ */
+const CONTROL_PREFIX = new Set(['if', 'elif', 'while', 'until', 'then', 'else', 'do', '!']);
+const CONTROL_ONLY = new Set(['}', ')', 'fi', 'done', 'esac']);
+/**
+ * The effective head of one pipeline segment: shell-control prefixes, leading
+ * `(`/`{`, VAR=val prefixes and `timeout N` are skipped; `bunx`/`npx` resolve
+ * to the tool they invoke (so `bunx tsc --noEmit` is static).
+ * `bun`/`npm`/`yarn`/`pnpm`/`node` stay as themselves — whatever they run (a
+ * script, a test suite, a file) is execution.
+ */
+function segmentHead(segment) {
+    const tokens = segment.split(/\s+/).filter(t => t.length > 0);
+    let i = 0;
+    while (i < tokens.length) {
+        const t = tokens[i].replace(/^[({!]+/, '');
+        if (t.length === 0 || CONTROL_PREFIX.has(t)) {
+            i++;
+            continue;
+        }
+        tokens[i] = t;
+        break;
+    }
+    if (i >= tokens.length || CONTROL_ONLY.has(tokens[i]))
+        return null;
+    while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]))
+        i++;
+    if (i < tokens.length && tokens[i] === 'timeout') {
+        i++;
+        if (i < tokens.length && /^\d/.test(tokens[i]))
+            i++;
+    }
+    if (i >= tokens.length)
+        return null;
+    let head = tokens[i];
+    if (head === 'bunx' || head === 'npx') {
+        i++;
+        while (i < tokens.length && tokens[i].startsWith('-'))
+            i++;
+        if (i >= tokens.length)
+            return null;
+        head = tokens[i];
+    }
+    return { head, args: tokens.slice(i + 1) };
+}
+/**
+ * Scan a composed spec's VERIFY block: all-static block that grep/cat-asserts
+ * runnable source ⇒ one finding per inspected file. Empty when the block
+ * contains any execution command, has no VERIFY block, or inspects no runnable
+ * source (doc/config-only tasks).
+ */
+export function findGrepOnlyVerify(spec) {
+    const cmds = parseVerifyBlock(spec);
+    if (!cmds)
+        return [];
+    const inspected = new Map();
+    for (const { raw } of cmds) {
+        // Split into pipeline segments; quotes are rare in VERIFY one-liners and
+        // a mis-split only risks a MISSED finding (a quoted `&&` making a fake
+        // segment whose head is unknown ⇒ counted as execution ⇒ step aside).
+        for (const segment of raw.split(/&&|\|\||;|\|/)) {
+            const s = segmentHead(segment);
+            if (s === null)
+                continue;
+            if (!STATIC_HEADS.has(s.head))
+                return []; // real execution — step aside
+            if (!INSPECT_HEADS.has(s.head))
+                continue;
+            for (const arg of s.args) {
+                if (arg.startsWith('-') || arg.startsWith("'") || arg.startsWith('"'))
+                    continue;
+                if (!RUNNABLE_SRC_RE.test(arg))
+                    continue;
+                const lines = inspected.get(arg) ?? [];
+                if (!lines.includes(raw))
+                    lines.push(raw);
+                inspected.set(arg, lines);
+            }
+        }
+    }
+    return [...inspected.entries()].map(([target, lines]) => ({ target, lines }));
+}
+/**
+ * Retry hint when the critique rewrite KEPT the grep-theater block it was told
+ * to fix (live A/B: 1/5 rewrites ignored the injected defect). Prepended to the
+ * second rewrite attempt; the defect block naming the exact files is still in
+ * the prompt body.
+ */
+export const GREP_THEATER_RETRY_HINT = '[SYSTEM NOTE: Your previous rewrite still shipped a VERIFY block whose only signal '
+    + 'on the runnable deliverable is grep-on-source — every command is static inspection '
+    + '(grep/cat/test/tsc) and the artifact is never run. This exact shape shipped a broken '
+    + 'build that stayed broken for 14 tasks. The rewritten VERIFY MUST execute the '
+    + 'deliverable (e.g. `bun <script>.ts`, `bun run <script>`, start it and curl it) and '
+    + 'assert an observable outcome of that run (exit code, a file the run produces, a '
+    + 'served response). Keep greps only as additions to the run, never as the only signal.]';
+/**
+ * Render the findings as a defect block for the critique rewrite: VERIFY must
+ * EXECUTE the runnable deliverable and assert an observable outcome of THAT
+ * run, not grep its source.
+ */
+export function grepOnlyVerifyDefectText(findings) {
+    return [
+        'GREP-THEATER VERIFY — every command in the VERIFY block is static inspection',
+        '(grep/cat/test/tsc), yet the deliverable includes runnable source. Grep-asserting',
+        'that a source file CONTAINS some text proves nothing about behavior (run-13: a',
+        'build script "verified" by greps shipped broken and stayed broken for 14 tasks',
+        'because `bun build.ts` was never run). Rewrite the VERIFY block so it EXECUTES the',
+        'runnable deliverable and asserts an OBSERVABLE OUTCOME of that run — exit code,',
+        'a produced file (`rm -rf dist && bun run build && test -f dist/…`), a served',
+        'response (`curl -sf http://…`). Keep static checks only as ADDITIONS to the run,',
+        'never as the sole signal. Runnable files currently only grep/cat-inspected:',
+        ...findings.map((f, i) => `  ${i + 1}. ${f.target} — via: ${f.lines.join(' ; ')}`)
+    ].join('\n');
+}

package/package.json

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