@mjasnikovs/pi-task 0.38.15 → 0.38.17

package/dist/task/child-runner.d.ts

@@ -7,6 +7,11 @@
  */
 import { type SpawnFn, type ContextSnapshot, type ToolCall, type LoopHit } from '../shared/child-process.js';
 import type { DebugLine } from './debug-log.js';
+import type { RunWorkerInput, RunWorkerResult } from '../workers/pi-worker-core.js';
+import type { docsRaw, docsFocused } from '../workers/docs-core.js';
+import type { fetchRaw, fetchFocused } from '../workers/fetch-core.js';
+import type { npmVersionLookup } from '../workers/npm-version.js';
+import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
 export declare const LOOP_WINDOW = 20;
 export declare const LOOP_THRESHOLD = 5;
 export declare const MAX_LOOP_RESTARTS = 2;
@@ -139,6 +144,38 @@ interface PhaseDeps {
      * the rungs. This seam is for callers to whom the child is a premise.
      */
     runChild?: (name: string, tools: string, prompt: string) => Promise<string>;
+    /**
+     * Run ONE research worker. Absent (production) → the real `runWorker`.
+     *
+     * Every decision `runSpec` makes — the three Research retry gates, the
+     * fatal/runaway/empty classification, the marker choice, `postProcess` — is a
+     * pure function of the returned `RunWorkerResult`, but reaching any of them
+     * otherwise requires driving a fake process that emits JSON events.
+     *
+     * `label` is the worker's name — the same one `recordWorker` trails — because
+     * a substitute must answer differently per worker, and the only alternative
+     * is matching a marker sentence inside the prompt. Same reason `runChild`
+     * takes a name.
+     */
+    runWorker?: (label: string, input: RunWorkerInput) => Promise<RunWorkerResult>;
+    /** The project file inventory handed to every research worker's header. */
+    getFileInventory?: (cwd: string, signal?: AbortSignal) => Promise<string>;
+    /** RAW docs lookup — the research phase's EXTERNAL CONTEXT variant. */
+    docsRaw?: typeof docsRaw;
+    /** RAW url fetch — the research phase's EXTERNAL CONTEXT variant. */
+    fetchRaw?: typeof fetchRaw;
+    /** Live npm version lookup for the research phase's named deps. */
+    npmVersionLookup?: typeof npmVersionLookup;
+    /** FOCUSED docs lookup — the grill auto-answer's variant. */
+    docsFocused?: typeof docsFocused;
+    /** FOCUSED url fetch — the grill auto-answer's variant. */
+    fetchFocused?: typeof fetchFocused;
+    /**
+     * Live web search. ONE field, not two: the research phase and the auto-answer
+     * differ in the doc/url worker VARIANT (raw vs focused) and in POLICY, never
+     * in how they search — the two dep bags declared it identically.
+     */
+    searchFn?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
 }
 export type { PhaseDeps };
 /**
@@ -165,7 +202,7 @@ export type { PhaseDeps };
  * All three are checked BEFORE the triage ladder: we killed the child, so its
  * exit status describes our SIGTERM and says nothing about its verdict.
  */
-export declare function runPhaseChild(deps: PhaseDeps, name: string, tools: string, prompt: string): Promise<string>;
+export declare function runPhaseChild(deps: PhaseDeps, name: string, tools: string, prompt: string, opts?: PhaseChildOptions): Promise<string>;
 export declare function formatLoopHint(hit: LoopHit): string;
 /**
  * Terminal hint for the degrade attempt: the model has thrashed through the whole
@@ -178,11 +215,19 @@ export declare function formatLoopHint(hit: LoopHit): string;
 export declare function formatDegradeHint(hit: LoopHit): string;
 export declare function prependHint(hint: string | null, prompt: string): string;
 /**
- * Run a phase child with loop detection. On a detected loop, kill and re-spawn
- * with a hint that names the offending call. Cap at MAX_LOOP_RESTARTS restarts;
- * the (MAX_LOOP_RESTARTS+1)th loop throws LoopExhaustedError.
+ * The two things a phase child can disagree about. Everything else — the loop
+ * and stall detectors, the wall clock, the loop trail, the triage ladder and its
+ * budget — is the one loop's, because the two wrappers that used to differ
+ * disagreed on nothing else that was ever observable.
  */
-export interface LoopGuardOptions {
+export interface PhaseChildOptions {
+    /**
+     * The wrapper's own word in the debug log for "we are going round again".
+     * An option rather than one word because it is the single externally visible
+     * difference between the two loops this collapsed, and the debug trail of a
+     * real run is read by a human who knows which phases restart and which retry.
+     */
+    verb?: 'retry' | 'restart';
     /**
      * When the strike budget is exhausted by loops, do NOT fail the phase. Run
      * ONE final attempt with NO tools and a terminal hint ordering the model to
@@ -194,7 +239,6 @@ export interface LoopGuardOptions {
      */
     degradeOnExhaustion?: boolean;
 }
-export declare function runPhaseWithLoopGuard(deps: PhaseDeps, name: string, tools: string, buildPrompt: (loopHint: string | null) => string, opts?: LoopGuardOptions): Promise<string>;
 /**
  * Run a child up to twice; the second attempt gets `emphasized=true` to escalate
  * the prompt. On success, return the validator's value; on two failures, throw

package/dist/task/child-runner.js

@@ -229,18 +229,18 @@ onToolResult) {
  * tool call. Callers own the loop, the prompt and the hint; this owns the
  * verdict, so a fix to any rung lands in every caller at once.
  *
- * `attempt` is the caller's 0-based counter (its attempt/strike), `budget` the
- * matching restart allowance (MAX_LEAK_RETRIES for runPhaseChild's leak budget,
- * MAX_LOOP_RESTARTS for runPhaseWithLoopGuard's strike budget) — so both run
- * `budget + 1` attempts in total before a rung gives up and throws.
+ * `attempt` is the caller's 0-based counter, `budget` the matching restart
+ * allowance (MAX_LEAK_RETRIES, which is also MAX_LOOP_RESTARTS — the loop and
+ * leak budgets were separate constants at the same value and are shared by one
+ * loop now) — so a phase runs `budget + 1` attempts before a rung gives up.
  *
- * `verb` names the caller's restart in the debug log ("retry" for runPhaseChild,
- * "restart" for runPhaseWithLoopGuard). It is the only externally visible thing
- * that differs between the two, and the only way to tell from a debug log which
- * wrapper produced a given line — so it is passed in rather than hardcoded.
+ * `verb` names the restart in the debug log ("retry" by default, "restart" for
+ * refine and grill-gen). It is the only externally visible thing that differed
+ * between the two loops this collapsed, and the only way to tell from a debug
+ * log which phase produced a line — so it is passed in rather than hardcoded.
  *
- * A loop kill (`r.loopHit`) is NOT handled here: only runPhaseWithLoopGuard
- * detects loops, and it must consume the hit before calling this.
+ * A loop kill (`r.loopHit`) is NOT handled here: the caller detects loops and
+ * must consume the hit before calling this.
  */
 async function triageChildResult(deps, name, r, attempt, budget, verb) {
     if (r.exitCode !== 0) {
@@ -303,13 +303,17 @@ async function triageChildResult(deps, name, r, attempt, budget, verb) {
  * All three are checked BEFORE the triage ladder: we killed the child, so its
  * exit status describes our SIGTERM and says nothing about its verdict.
  */
-export async function runPhaseChild(deps, name, tools, prompt) {
+export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
     if (deps.runChild)
         return await deps.runChild(name, tools, prompt);
+    const verb = opts.verb ?? 'retry';
     let hint = null;
     const loopHistory = [];
     const budgetMs = deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS;
     for (let attempt = 0; attempt <= MAX_LEAK_RETRIES; attempt++) {
+        // A cancel between attempts must not buy another spawn.
+        if (deps.signal.aborted)
+            throw new Error(USER_CANCELLED);
         const detector = new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD);
         const stall = new StallDetector();
         const clock = phaseTimeout(deps.signal, budgetMs);
@@ -327,13 +331,23 @@ export async function runPhaseChild(deps, name, tools, prompt) {
         if (deps.signal.aborted)
             throw new Error(USER_CANCELLED);
         if (r.loopHit) {
+            const isLastStrike = attempt === MAX_LEAK_RETRIES;
             loopHistory.push(r.loopHit);
-            if (attempt === MAX_LEAK_RETRIES)
+            await appendLoopEvent(deps.cwd, deps.taskId, name, r.loopHit, attempt + 1, isLastStrike ?
+                opts.degradeOnExhaustion ?
+                    'degraded — no-tools final attempt'
+                    : 'phase failed'
+                : 'restarted with hint');
+            if (isLastStrike) {
+                if (opts.degradeOnExhaustion) {
+                    return await runDegradedFinalAttempt(deps, name, prompt, r.loopHit, loopHistory);
+                }
                 throw new LoopExhaustedError(name, loopHistory);
+            }
             deps.logDebug?.(r.loopHit.stall ?
                 `${name}: stalled (${r.loopHit.stall}) on ${r.loopHit.call.name} — `
-                    + `retry ${attempt + 1}/${MAX_LEAK_RETRIES}`
-                : `${name}: looped on ${r.loopHit.call.name} — retry ${attempt + 1}/${MAX_LEAK_RETRIES}`);
+                    + `${verb} ${attempt + 1}/${MAX_LEAK_RETRIES}`
+                : `${name}: looped on ${r.loopHit.call.name} — ${verb} ${attempt + 1}/${MAX_LEAK_RETRIES}`);
             hint = r.loopHit.stall ? formatStallHint(r.loopHit.stall) : formatLoopHint(r.loopHit);
             continue;
         }
@@ -342,11 +356,11 @@ export async function runPhaseChild(deps, name, tools, prompt) {
                 throw new PhaseTimeoutError(name, budgetMs, MAX_LEAK_RETRIES + 1);
             }
             deps.logDebug?.(`${name}: exceeded its ${Math.round(budgetMs / 1000)}s budget — `
-                + `retry ${attempt + 1}/${MAX_LEAK_RETRIES}`);
+                + `${verb} ${attempt + 1}/${MAX_LEAK_RETRIES}`);
             hint = PHASE_TIMEOUT_HINT;
             continue;
         }
-        const step = await triageChildResult(deps, name, r, attempt, MAX_LEAK_RETRIES, 'retry');
+        const step = await triageChildResult(deps, name, r, attempt, MAX_LEAK_RETRIES, verb);
         if (step.done)
             return step.text;
         if (step.hint !== undefined)
@@ -381,63 +395,28 @@ export function formatDegradeHint(hit) {
 export function prependHint(hint, prompt) {
     return hint === null ? prompt : `${hint}\n\n${prompt}`;
 }
+/**
+ * Append one line to the task file's `loop events` section.
+ *
+ * Best-effort by contract: it runs for EVERY phase child now that there is one
+ * loop, and the six sites that used to reach the un-trailed wrapper do not all
+ * own a task file on disk (a scripted harness, a bare unit deps bag). A trail
+ * that cannot be written must cost the phase nothing — the loop kill itself is
+ * already reported through the debug log and the thrown LoopExhaustedError.
+ */
 async function appendLoopEvent(cwd, taskId, phase, hit, strike, outcome) {
     const ts = new Date().toISOString();
     const argsStr = JSON.stringify(hit.call.args);
     const line = `- ${ts}  ${phase}  strike ${strike}/${MAX_LOOP_RESTARTS + 1}  `
         + `${hit.call.name}(${argsStr}) ×${hit.count} in last ${hit.windowSize} calls  → ${outcome}`;
-    const existing = (await readSection(cwd, taskId, 'loop events')) ?? '';
-    const next = existing ? `${existing}\n${line}` : line;
-    await setTaskSection(cwd, taskId, 'loop events', next);
-}
-export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt, opts = {}) {
-    // The substitute stands in for the whole guarded run, so it is handed the
-    // prompt the first strike would have used (no loop hint in flight yet).
-    if (deps.runChild)
-        return await deps.runChild(name, tools, buildPrompt(null));
-    const loopHistory = [];
-    // Carries the correction hint (loop OR leaked-tool-call) into the next strike.
-    let nextHint = null;
-    for (let strike = 0; strike <= MAX_LOOP_RESTARTS; strike++) {
-        if (deps.signal.aborted)
-            throw new Error(USER_CANCELLED);
-        const detector = new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD);
-        const stall = new StallDetector();
-        const prompt = buildPrompt(nextHint);
-        const r = await runChild(deps.cwd, tools, prompt, deps.signal, deps.onChildOutput, snapshot => {
-            stall.noteContext(snapshot.contextWindow);
-            deps.onContextUsage?.(snapshot);
-        }, call => detector.record(call) ?? stall.record(call), deps.spawn, undefined, (text, isError) => stall.noteResult(text, isError));
-        if (deps.signal.aborted)
-            throw new Error(USER_CANCELLED);
-        if (r.loopHit) {
-            const isLastStrike = strike === MAX_LOOP_RESTARTS;
-            loopHistory.push(r.loopHit);
-            const lastOutcome = opts.degradeOnExhaustion ? 'degraded — no-tools final attempt' : 'phase failed';
-            await appendLoopEvent(deps.cwd, deps.taskId, name, r.loopHit, strike + 1, isLastStrike ? lastOutcome : 'restarted with hint');
-            if (isLastStrike) {
-                if (opts.degradeOnExhaustion) {
-                    return await runDegradedFinalAttempt(deps, name, buildPrompt, r.loopHit, loopHistory);
-                }
-                throw new LoopExhaustedError(name, loopHistory);
-            }
-            nextHint =
-                r.loopHit.stall ? formatStallHint(r.loopHit.stall) : formatLoopHint(r.loopHit);
-            continue;
-        }
-        // Everything past the loop kill is the shared ladder: exit code, model
-        // error (connection-class restarts within the strike budget), empty
-        // completion, leaked tool call. The strike budget is shared with the
-        // loop restarts above — MAX_LOOP_RESTARTS+1 attempts across all causes.
-        const step = await triageChildResult(deps, name, r, strike, MAX_LOOP_RESTARTS, 'restart');
-        if (step.done)
-            return step.text;
-        // Only a leak produces a new correction hint; the other rungs have
-        // nothing to correct and leave any loop hint already in flight alone.
-        if (step.hint !== undefined)
-            nextHint = step.hint;
+    try {
+        const existing = (await readSection(cwd, taskId, 'loop events')) ?? '';
+        const next = existing ? `${existing}\n${line}` : line;
+        await setTaskSection(cwd, taskId, 'loop events', next);
+    }
+    catch {
+        /* best-effort: a trail is never worth failing a phase for */
     }
-    throw new LoopExhaustedError(name, loopHistory);
 }
 /**
  * Final degrade attempt after the loop budget is spent: re-spawn the child with
@@ -448,10 +427,10 @@ export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt, opts
  * to the original LoopExhaustedError so the phase still fails honestly when even
  * the degrade produces nothing.
  */
-async function runDegradedFinalAttempt(deps, name, buildPrompt, hit, loopHistory) {
+async function runDegradedFinalAttempt(deps, name, prompt, hit, loopHistory) {
     deps.logDebug?.(`${name}: loop budget exhausted — degrading to a no-tools final attempt`);
     const r = await runChild(deps.cwd, '', // --no-tools: the model cannot read/grep/list, only answer
-    buildPrompt(formatDegradeHint(hit)), deps.signal, deps.onChildOutput, deps.onContextUsage, undefined, deps.spawn);
+    prependHint(formatDegradeHint(hit), prompt), deps.signal, deps.onChildOutput, deps.onContextUsage, undefined, deps.spawn);
     if (r.exitCode !== 0 || r.modelError || r.text.trim().length === 0) {
         throw new LoopExhaustedError(name, loopHistory);
     }

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

@@ -45,18 +45,41 @@ export interface CommandSpec {
     args: string[];
     timeoutMs: number;
     /**
-     * Replaces the child's environment wholesale. Passed explicitly because bun's
-     * spawnSync resolves the binary against a startup snapshot of the environment
+     * Replaces the child's environment wholesale. Passed explicitly because a
+     * spawn resolves the binary against a startup snapshot of the environment
      * rather than the live `process.env`.
      */
     env?: Record<string, string | undefined>;
+    /** The caller's cancel. Kills the child; the run reads as `status: null`. */
+    signal?: AbortSignal;
 }
 /**
  * The injectable half. The gate takes one of these so its tests can script
  * verdicts instead of paying process-spawn cost for every classification case.
+ *
+ * ASYNC by contract. It was `(spec) => CommandRun`, so the only implementation
+ * could be `spawnSync`, and the run-end gate blocked the event loop end to end:
+ * repo-health under a 600s cap, then every lockfile/test/build/launch command
+ * under a 900s cap, then every ACCEPT-debt re-run under a 300s cap, with no
+ * loader able to paint through any of it. That freeze is MEASURED — 0 of 686
+ * expected 100ms ticks fired during a 69s run — and `repo-health-check.ts`'s own
+ * doc comment already told gate callers not to do it, while `final-gate.ts`'s
+ * repo-health call did exactly that.
+ */
+export type CommandRunner = (spec: CommandSpec) => Promise<CommandRun>;
+/**
+ * The real runner: one bounded child, output collected, never rejects.
+ *
+ * A kill — by the wall clock or by the caller's cancel — reads as `status: null`,
+ * which the gap ladder already treats as "nothing was observed".
+ *
+ * THE RUN SETTLES ON THE CHILD, NOT ON THE PIPE. `close` fires only once every
+ * stdio pipe has reached EOF, and a backgrounded grandchild INHERITS stdout: a
+ * seed script that starts a daemon, a build that leaves a watcher, a launch
+ * script. Waiting for `close` there is waiting for the grandchild, which no
+ * timeout can reach — SIGKILL goes to the direct child and the inherited pipe
+ * survives it. So `exit` settles the run, and the deadline settles it itself.
  */
-export type CommandRunner = (spec: CommandSpec) => CommandRun;
-/** The real runner. */
 export declare const spawnCommand: CommandRunner;
 /**
  * A non-zero exit whose output shows an EXTERNAL runtime dependency is missing, not
@@ -94,6 +117,26 @@ export type CommandVerdict =
 };
 /** Last ~`limit` chars of the command's combined output, one line, for the reason. */
 export declare function outputTail(stdout: string, stderr: string, limit?: number): string;
+/**
+ * Which gap rows may be claimed by a command's OUTPUT rather than by the fact
+ * that it never ran. Only these can be WRONG about a command that did run, which
+ * is why they are the ones a caller opts into.
+ */
+export interface ClassifyOptions {
+    /**
+     * May this command's output claim a MISSING BROWSER/RUNTIME?
+     *
+     * True by default: the row exists for the gate's TEST commands, where a
+     * Playwright suite on a box with no browsers is an environment gap.
+     *
+     * False for the static ladder. `ENV_GAP_OUTPUT_RE` matches ordinary English
+     * — `browsers are not installed`, `wasn't installed` — and repo-health runs
+     * lint and typecheck only, which have no browsers to miss. A real lint report
+     * that happens to quote that wording would otherwise SKIP the static check
+     * and tell the gate the repo is healthy.
+     */
+    runtimeGap?: boolean;
+}
 /**
  * Decide what one finished command proved. Pure — no spawning, no filesystem, no
  * clock — so every case is stateable as a literal.
@@ -101,7 +144,7 @@ export declare function outputTail(stdout: string, stderr: string, limit?: numbe
  * `gapPatterns` are the EXTRA output shapes this particular command may treat as
  * an environment gap (see INFRA_GAP_OUTPUT_RE). Empty for an ordinary check.
  */
-export declare function classifyCommandRun(run: CommandRun, gapPatterns?: readonly RegExp[]): CommandVerdict;
+export declare function classifyCommandRun(run: CommandRun, gapPatterns?: readonly RegExp[], opts?: ClassifyOptions): CommandVerdict;
 /**
  * How a re-run of ONE recorded VERIFY command line ended.
  *   pass — it ran and exited 0. The ONLY outcome that may close a debt.
@@ -137,4 +180,4 @@ export type VerifyRerunOutcome = {
  */
 export declare function runVerifyCommandLine(cwd: string, line: string, timeoutMs: number, extraGapRe?: RegExp, 
 /** The spawner. Injected so a re-run's outcome can be tested without one. */
-run?: CommandRunner): VerifyRerunOutcome;
+run?: CommandRunner, signal?: AbortSignal): Promise<VerifyRerunOutcome>;

package/dist/task/command-run.js

@@ -27,24 +27,156 @@
  * carried nine injectable probes for the gate's boot half while its command half
  * had none.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { isCommandNotFound, resolveRunner, runnerEnv } from './runner-resolve.js';
-/** The real runner. */
-export const spawnCommand = spec => {
-    const r = spawnSync(spec.bin, spec.args, {
+/**
+ * How much of ONE stream may be held in the HOST process, and how it is split.
+ *
+ * `spawnSync` bounded this at its 1 MB default `maxBuffer`. The async runner had
+ * no bound at all: two strings grew in the TUI's own process for as long as a
+ * command under the 900s cap kept talking.
+ *
+ * BOTH ENDS are kept, because both are read. `isCommandNotFound` and the two gap
+ * regexes match wording a runner prints FIRST; `outputTail` and every failure
+ * reason take the LAST 400 characters. A single-ended cap loses one of them.
+ */
+const OUTPUT_HEAD_CAP = 256 * 1024;
+const OUTPUT_TAIL_CAP = 768 * 1024;
+/** One stream, bounded, keeping its head and its tail with the middle elided. */
+class BoundedOutput {
+    head = '';
+    tail = '';
+    total = 0;
+    push(chunk) {
+        this.total += chunk.length;
+        let rest = chunk;
+        if (this.head.length < OUTPUT_HEAD_CAP) {
+            const room = OUTPUT_HEAD_CAP - this.head.length;
+            this.head += rest.slice(0, room);
+            rest = rest.slice(room);
+        }
+        if (rest.length === 0)
+            return;
+        this.tail = (this.tail + rest).slice(-OUTPUT_TAIL_CAP);
+    }
+    toString() {
+        const elided = this.total - this.head.length - this.tail.length;
+        return elided > 0 ?
+            `${this.head}\n…[${elided} characters elided]…\n${this.tail}`
+            : this.head + this.tail;
+    }
+}
+/**
+ * After the child EXITS, how long its pipes may still deliver buffered data
+ * before the run is reported. Not a wait for the pipes to CLOSE — that is the
+ * bug below — just the turn or two the reader needs to hand over what it has.
+ */
+const DRAIN_MS = 50;
+/**
+ * The real runner: one bounded child, output collected, never rejects.
+ *
+ * A kill — by the wall clock or by the caller's cancel — reads as `status: null`,
+ * which the gap ladder already treats as "nothing was observed".
+ *
+ * THE RUN SETTLES ON THE CHILD, NOT ON THE PIPE. `close` fires only once every
+ * stdio pipe has reached EOF, and a backgrounded grandchild INHERITS stdout: a
+ * seed script that starts a daemon, a build that leaves a watcher, a launch
+ * script. Waiting for `close` there is waiting for the grandchild, which no
+ * timeout can reach — SIGKILL goes to the direct child and the inherited pipe
+ * survives it. So `exit` settles the run, and the deadline settles it itself.
+ */
+export const spawnCommand = spec => new Promise(resolve => {
+    const out = new BoundedOutput();
+    const err = new BoundedOutput();
+    let settled = false;
+    let exitStatus = null;
+    let exited = false;
+    let endedStreams = 0;
+    let drain;
+    const child = spawn(spec.bin, spec.args, {
         cwd: spec.cwd,
-        encoding: 'utf8',
-        timeout: spec.timeoutMs,
+        // stdin CLOSED. `spawnSync` gave the child none; the default `spawn`
+        // stdio is a live pipe nobody ever ends, so a check that reads stdin —
+        // a `cat`-style pipeline, a tool that prompts, a pager — blocked until
+        // the kill timer: 600s for repo-health, 900s for a gate command.
+        stdio: ['ignore', 'pipe', 'pipe'],
         ...(spec.env ? { env: spec.env } : {})
     });
-    return {
-        failedToStart: r.error !== undefined && r.error !== null,
-        ...(r.error ? { failureMessage: r.error.message } : {}),
-        status: r.status,
-        stdout: r.stdout ?? '',
-        stderr: r.stderr ?? ''
+    const done = (status, failure) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        clearTimeout(drain);
+        spec.signal?.removeEventListener('abort', killAndSettle);
+        resolve({
+            failedToStart: failure !== undefined,
+            ...(failure === undefined ? {} : { failureMessage: failure }),
+            status,
+            stdout: out.toString(),
+            stderr: err.toString()
+        });
+    };
+    const expectedStreams = (child.stdout ? 1 : 0) + (child.stderr ? 1 : 0);
+    const settleIfDrained = () => {
+        if (exited && endedStreams >= expectedStreams)
+            done(exitStatus);
+    };
+    const kill = () => {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    };
+    /**
+     * The deadline and the cancel both END the run. The kill only reaches the
+     * direct child, so this cannot wait to observe its effect — it kills, gives
+     * the pipes one drain, and reports `status: null` regardless.
+     */
+    const killAndSettle = () => {
+        kill();
+        clearTimeout(drain);
+        drain = setTimeout(() => done(null), DRAIN_MS);
     };
-};
+    // NOT unref'd. With `spawnSync`'s own `timeout` gone this timer is the only
+    // bound left on every gate command, repo-health command and ACCEPT-debt
+    // re-run — and an unref'd timer is MEASURED in this repo never to fire at
+    // all on Windows (0/20s), which would leave all of them unbounded. It is
+    // cleared the moment the run settles, so it holds the loop open only while
+    // a command the caller is awaiting anyway is still running.
+    const timer = setTimeout(killAndSettle, spec.timeoutMs);
+    if (spec.signal) {
+        if (spec.signal.aborted)
+            killAndSettle();
+        else
+            spec.signal.addEventListener('abort', killAndSettle, { once: true });
+    }
+    child.stdout?.on('data', (d) => out.push(d.toString()));
+    child.stderr?.on('data', (d) => err.push(d.toString()));
+    child.stdout?.on('end', () => {
+        endedStreams++;
+        settleIfDrained();
+    });
+    child.stderr?.on('end', () => {
+        endedStreams++;
+        settleIfDrained();
+    });
+    child.on('error', (e) => done(null, e.message));
+    child.on('exit', (code) => {
+        exited = true;
+        exitStatus = code;
+        // Both ends of the same question: settle now if the pipes are already
+        // at EOF, otherwise settle after one short drain rather than waiting on
+        // whoever else is holding them.
+        settleIfDrained();
+        if (!settled) {
+            clearTimeout(drain);
+            drain = setTimeout(() => done(exitStatus), DRAIN_MS);
+        }
+    });
+});
 /**
  * A non-zero exit whose output shows an EXTERNAL runtime dependency is missing, not
  * a code fault: a browser suite (Playwright/Cypress) whose browser binaries or system
@@ -116,14 +248,17 @@ export function outputTail(stdout, stderr, limit = 400) {
  * `gapPatterns` are the EXTRA output shapes this particular command may treat as
  * an environment gap (see INFRA_GAP_OUTPUT_RE). Empty for an ordinary check.
  */
-export function classifyCommandRun(run, gapPatterns = []) {
+export function classifyCommandRun(run, gapPatterns = [], opts = {}) {
     // A clean exit is a pass before any gap shape is consulted: gap patterns
     // describe output, and passing output can legitimately mention a database or
     // a browser.
     if (!run.failedToStart && run.status === 0)
         return { outcome: 'pass' };
     const output = `${run.stdout}\n${run.stderr}`;
+    const runtimeGap = opts.runtimeGap ?? true;
     for (const rule of GAP_RULES) {
+        if (rule.id === 'missing-runtime' && !runtimeGap)
+            continue;
         if (rule.applies(run, output, gapPatterns)) {
             return { outcome: 'gap', gap: rule.id, detail: rule.detail(run) };
         }
@@ -160,19 +295,20 @@ function leadingBin(line) {
  * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the
  * debt exactly as open as it was.
  */
-export function runVerifyCommandLine(cwd, line, timeoutMs, extraGapRe, 
+export async function runVerifyCommandLine(cwd, line, timeoutMs, extraGapRe, 
 /** The spawner. Injected so a re-run's outcome can be tested without one. */
-run = spawnCommand) {
+run = spawnCommand, signal) {
     const bin = leadingBin(line);
     const runner = bin === null ? null : resolveRunner(bin);
     // A VERIFY line is a SHELL line, not an argv — env prefixes, `&&` and
     // redirects are all ordinary there — so the runner spawns `sh -c`.
-    const verdict = classifyCommandRun(run({
+    const verdict = classifyCommandRun(await run({
         cwd,
         bin: 'sh',
         args: ['-c', line],
         timeoutMs,
-        env: runner ? runnerEnv(runner) : { ...process.env }
+        env: runner ? runnerEnv(runner) : { ...process.env },
+        ...(signal === undefined ? {} : { signal })
     }), 
     // Infrastructure counts as a gap on EVERY debt re-run, not only on
     // request: an unreachable database cannot tell us whether the code is

package/dist/task/coverage-loop.d.ts

@@ -139,3 +139,14 @@ export interface ScoredPlan {
      */
     judgeMissing: string[];
 }
+/**
+ * Normalise a missing-area string for cross-round identity — lowercased alnum
+ * words, punctuation and quote-wrapping collapsed. Used only to tell whether an
+ * adopted plan introduced a NEW gap versus re-surfacing the same one (the bonus
+ * round); intentionally coarse, so trivial rewording of the same area does not
+ * read as new and buy an extra round.
+ *
+ * Lives here rather than in `auto-orchestrator.ts` because its only consumer is
+ * `CoverageLedger.consider`, which is the adoption rule this file owns.
+ */
+export declare function normMissingArea(s: string): string;

package/dist/task/coverage-loop.js

@@ -290,3 +290,19 @@ export function decideAdoption(current, retry, hasRequirements) {
     }
     return { adopt: true, reason: 'count floor met, no coverage regression', dropped: [] };
 }
+/**
+ * Normalise a missing-area string for cross-round identity — lowercased alnum
+ * words, punctuation and quote-wrapping collapsed. Used only to tell whether an
+ * adopted plan introduced a NEW gap versus re-surfacing the same one (the bonus
+ * round); intentionally coarse, so trivial rewording of the same area does not
+ * read as new and buy an extra round.
+ *
+ * Lives here rather than in `auto-orchestrator.ts` because its only consumer is
+ * `CoverageLedger.consider`, which is the adoption rule this file owns.
+ */
+export function normMissingArea(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+}

package/dist/task/external-context.d.ts

@@ -19,12 +19,16 @@
  * {@link ExternalContextLookups} — an adapter, expressible only since the
  * focused-extractor seam landed.
  */
-import { docsRaw } from '../workers/docs-core.js';
-import { fetchRaw } from '../workers/fetch-core.js';
-import { npmVersionLookup, type NpmVersionInfo } from '../workers/npm-version.js';
+import { type NpmVersionInfo } from '../workers/npm-version.js';
 import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
 import type { PhaseDeps } from './child-runner.js';
-type GatherDeps = Pick<PhaseDeps, 'cwd' | 'signal' | 'recordSubStep'>;
+/**
+ * What assembling the block needs off the phase's deps: where it runs, when to
+ * stop, where to trail a sub-step — and, for the research binding, the four
+ * lookup seams. They are fields on `PhaseDeps` (not a second bag) because the
+ * bag was a trailing parameter no production caller could reach.
+ */
+type GatherDeps = Pick<PhaseDeps, 'cwd' | 'signal' | 'recordSubStep' | 'docsRaw' | 'fetchRaw' | 'npmVersionLookup' | 'searchFn'>;
 /** What a target lookup contributes to the block. */
 export interface ExternalTargetResult {
     /** Emitted as an `### npm:` block ahead of every body. Absent for url targets. */
@@ -89,13 +93,6 @@ export interface ExternalContextPolicy {
  * is nothing to enrich (no targets, or every lookup failed).
  */
 export declare function buildExternalContext(source: string, deps: GatherDeps, lookups: ExternalContextLookups, policy?: ExternalContextPolicy): Promise<string>;
-/** Injectable workers so enrichment is testable without spawning real lookups. */
-export interface ExternalContextDeps {
-    docsRaw?: typeof docsRaw;
-    fetchRaw?: typeof fetchRaw;
-    searchFn?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
-    npmVersionLookup?: typeof npmVersionLookup;
-}
 /**
  * The RESEARCH-phase binding: raw workers, no caps, live versions for every
  * named dep, truncated bodies, timed, and short-circuited when there is nothing
@@ -103,5 +100,5 @@ export interface ExternalContextDeps {
  *
  * Returns the `EXTERNAL CONTEXT\n…\n\n` block for the refined spec, or `''`.
  */
-export declare function gatherExternalContext(refined: string, deps: GatherDeps, researchDeps?: ExternalContextDeps): Promise<string>;
+export declare function gatherExternalContext(refined: string, deps: GatherDeps): Promise<string>;
 export {};