@mjasnikovs/pi-task 0.18.26 → 0.18.28

package/dist/task/command-watchdog.js

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

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

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

package/dist/task/enforce-guidelines.js

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

package/dist/task/gate-deps.js

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

package/dist/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/dist/workers/pi-worker-core.d.ts

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