@mjasnikovs/pi-task 0.38.15 → 0.38.16

package/dist/task/boot-probe.js

@@ -23,10 +23,11 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as net from 'node:net';
 import * as path from 'node:path';
+import { runRenderCheck } from './render-check.js';
 import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
 import { outputTail } from './command-run.js';
 import { packageScripts, makeHasTarget } from './launch-manifest.js';
-import { collectProjectEnv, pinnedLocalPort } from './deep-render-check.js';
+import { collectProjectEnv, pinnedLocalPort, runDeepRenderCheck } from './deep-render-check.js';
 /** Leading `FOO=bar` env assignments and `sudo`/`exec` wrappers carry no verb. */
 function commandTokens(member) {
     const t = member.trim().split(/\s+/).filter(Boolean);
@@ -791,7 +792,11 @@ export function bootSkipVerdict(args) {
  * the caller emit the harness diagnosis. Never reaps a process we cannot attribute
  * to ourselves.
  */
-export async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps, expectServer) {
+export async function recoverOrphanPort(cwd, boot, first, 
+/** One options object, not four trailing positionals — `bootGraceMs` and a
+ *  boolean sat adjacent and swapped without a type error. */
+opts) {
+    const { graceMs: bootGraceMs, deps, expectServer } = opts;
     if (first.port === null)
         return first;
     const holder = (deps.findPortHolder ?? defaultFindPortHolder)(first.port);
@@ -804,3 +809,94 @@ export async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps, exp
     await new Promise(r => setTimeout(r, 1_500));
     return runBootCheck(cwd, boot, bootGraceMs, { expectServer, deps });
 }
+export async function runBootSection(cwd, opts = {}) {
+    const boot = discoverBootCommand(cwd);
+    const expectServer = detectsServedApp(cwd, opts.planText);
+    const warnings = [];
+    if (!boot) {
+        // Nothing to boot — but if the reason is that the project's only launch
+        // script was REJECTED as not-a-launch (2A), that is not the same thing as a
+        // project with no launch surface, and it must not degrade into silence.
+        const rejected = rejectedLaunchScript(cwd);
+        if (rejected && expectServer) {
+            return {
+                observed: false,
+                warnings,
+                unobservedNote: `boot check: this project's only launch script (\`${rejected.name}\`) is not a `
+                    + `launch — ${rejected.reason} — so nothing was started and the app was never `
+                    + 'observed to run.'
+            };
+        }
+        return { observed: false, warnings };
+    }
+    const label = `${boot[0]} ${boot[1].join(' ')}`;
+    // Render check (mx5 runs 8/11): for a served app, load the live page in a
+    // headless browser and judge the RENDERED DOM — curl can't run JS, so a
+    // blank-mount app passed every prior "renders" check. runRenderCheck
+    // env-gap-SKIPs when no browser exists, so a box without one never gets a
+    // false FAIL.
+    //
+    // Authenticated deep-render check (mx5 run 17): the page above renders, so now
+    // sign in with the account the project's own dotenv declares (the same
+    // ADMIN_PHONE/ADMIN_PASSWORD the launch contract's seed step consumes) and
+    // require the session to actually work. WEB-ONLY by construction — it hangs off
+    // the served-app branch and never runs for C++, Godot, CLI or library projects.
+    // It may only FAIL when the SERVER authenticated us; no browser, no
+    // credentials, an undrivable form or rejected credentials all skip as env gaps.
+    const deps = {
+        ...opts.deps,
+        renderProbe: opts.deps?.renderProbe ?? runRenderCheck,
+        deepRenderProbe: opts.deps?.deepRenderProbe ?? (url => runDeepRenderCheck(url, cwd)),
+        preferredPort: opts.deps?.preferredPort ?? (() => preferredDeclaredPort(cwd))
+    };
+    let b = await runBootCheck(cwd, boot, opts.graceMs, { expectServer, deps });
+    if (b.outcome === 'orphan-port') {
+        b = await recoverOrphanPort(cwd, boot, b, {
+            ...(opts.graceMs === undefined ? {} : { graceMs: opts.graceMs }),
+            deps,
+            expectServer
+        });
+    }
+    const verdict = {
+        attempted: boot[0],
+        observed: b.outcome !== 'skip',
+        warnings,
+        ...(b.outcome === 'skip' && b.spawnFailed ? { spawnFailedBin: boot[0] } : {})
+    };
+    const unobserved = bootSkipVerdict({ label, skipped: b.outcome === 'skip', expectServer });
+    if (unobserved !== null)
+        verdict.unobservedNote = unobserved;
+    if (b.outcome === 'fail') {
+        // OBSERVED (nexttask 19A). Every path that produces `fail` here is a probe
+        // that looked: the render judge saw an empty body, the deep session saw the
+        // authenticated half dead, the enumerator saw no listener, or the launch
+        // command itself exited non-zero. The one condition that means "we could not
+        // look" — no ss/netstat/lsof, mx5 run 14 — returns PASS stamped UNOBSERVED
+        // and never reaches here.
+        verdict.failure = { detail: `boot check: \`${label}\` ${b.detail}`, rank: 0, observed: true };
+    }
+    else if (b.outcome === 'orphan-port') {
+        // Could not clear the port. Distinct HARNESS diagnosis, never a bare app
+        // FAIL: name the port and (when known) the process squatting on it. The
+        // holder lookup reads the SAME deps the boot ran under — it used to be a
+        // second reach into `BootDeps` from the gate, one layer away from the run.
+        const holder = b.port !== null ? (deps.findPortHolder ?? defaultFindPortHolder)(b.port) : null;
+        const who = holder ? ` — held by an orphaned process (pid ${holder.pid}: ${holder.command})`
+            : b.port !== null ? ` — port ${b.port} is held by another process`
+                : '';
+        verdict.failure = {
+            detail: `boot check: \`${label}\` could not bind: orphaned process / port already in `
+                + `use${who} (harness condition, not an app fault)`,
+            rank: 0,
+            observed: false
+        };
+    }
+    else if (b.outcome === 'pass') {
+        verdict.ranLabel = label;
+        // A listener that served, but whose page could not be OBSERVED to render
+        // (no browser, undeterminable port) → UNOBSERVED warning, not a silent pass.
+        if (b.renderNote)
+            warnings.push(b.renderNote);
+    }
+    return verdict;
+}

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>;