@mjasnikovs/pi-task 0.38.2 → 0.38.3

package/dist/task/auto-orchestrator.js

@@ -45,6 +45,8 @@ import { granularityFloor, granularitySplitHint, isPlanShapeQuestion, isTooCoars
 import { mandatesTestsInSameChange, rewriteBatchTestPlan } from './batch-test-task.js';
 import { REQUIREMENT_EXTRACT_PROMPT, COVERAGE_MAP_PROMPT, parseRequirementLines, keepGroundedRequirements, capRequirements, writeOwnedRequirements, enumerateObligationPassages, uncoveredPassages, extractionRetryHint, parseCoverageMap, accountCoverage, isCrossCuttingRequirement, appendCarriedRequirements, buildRequirementsLedger } from './requirements.js';
 import { decideAdoption, groundedCoverage } from './coverage-loop.js';
+import { buildOptionCards, resolveAnswer } from './question-dialog.js';
+import { TERMINAL_OUTCOMES, formatAt, formatWhy } from './terminal-outcome.js';
 import { findSpecDanglingArtifacts, titlesCoverArtifact, danglingMissingText, danglingCarryText } from './artifact-closure.js';
 import { LAUNCH_EXTRACT_PROMPT, enumerateScriptCandidates, parseScriptLines, keepGroundedScripts, appendDeclaredScripts } from './launch-contract.js';
 // Hard ceiling on clarify questions per feature. The loop is open-ended (it stops
@@ -556,11 +558,6 @@ export async function planAuto(ctx, cwd, feature, deps) {
         }
         const plainSuggested = suggested === undefined ? undefined : stripInlineMarkdown(suggested);
         const plainAlt = alt === undefined ? undefined : stripInlineMarkdown(alt);
-        // Identical to /task's grill dialog: a recommendation (or A/B fork)
-        // becomes the boxed picker locally — each answer in its own bounding box,
-        // the recommended one tinted green; an open question shows the bare text
-        // prompt. No verbose "Recommended:" / "press Enter to accept" scaffolding.
-        const twoOption = plainSuggested !== undefined && plainAlt !== undefined;
         // YOLO: take the recommended option (index 0 / the green card) without ever
         // building the prompt. Clarify has no anti-synthesis channel — it runs before
         // any research — so the only step-aside here is a question that carries no
@@ -575,17 +572,22 @@ export async function planAuto(ctx, cwd, feature, deps) {
                 + `A${answers.length + 1}: ${auto} ${YOLO_STAMP}`);
             continue;
         }
-        const options = twoOption ?
-            [
-                {
-                    label: `A: ${renderInlineMarkdown(suggested, theme)}`,
-                    value: plainSuggested
-                },
-                { label: `B: ${renderInlineMarkdown(alt, theme)}`, value: plainAlt }
-            ]
-            : plainSuggested !== undefined ?
-                [{ label: renderInlineMarkdown(suggested, theme), value: plainSuggested }]
-                : undefined;
+        // The picker cards and the reply mapping are shared with /task's grill
+        // phase and the plan session (question-dialog.ts) — all three used to
+        // write them out, and had drifted.
+        const pending = {
+            plain: plainQ,
+            shown: shownQ,
+            ...(plainSuggested !== undefined && {
+                suggested: plainSuggested,
+                shownSuggested: renderInlineMarkdown(suggested, theme)
+            }),
+            ...(plainAlt !== undefined && {
+                alt: plainAlt,
+                shownAlt: renderInlineMarkdown(alt, theme)
+            })
+        };
+        const options = buildOptionCards(pending);
         const a = await ui.ask({
             localTitle: shownQ,
             displayQuestion: shownQ,
@@ -599,31 +601,15 @@ export async function planAuto(ctx, cwd, feature, deps) {
             announceDone(ctx, '/task-auto cancelled.', 'warning');
             return null;
         }
-        const typed = a.trim();
-        // The local picker resolves to the chosen option's full value, but a
-        // remote user (or the picker's free-text fallback) may still type a bare
-        // "A"/"B" — map those back to the option's full text. Mirrors phaseGrill.
-        let answer;
-        if (typed.length === 0 && plainSuggested) {
-            answer = `${plainSuggested} (accepted recommendation)`;
-        }
-        else if (typed.length === 0) {
-            answer = '(skipped)';
-        }
-        else if (twoOption && /^a[.)]?$/i.test(typed)) {
-            answer = plainSuggested;
-        }
-        else if (twoOption && /^b[.)]?$/i.test(typed)) {
-            answer = plainAlt;
-        }
-        else if (!twoOption && plainSuggested !== undefined && typed === plainSuggested) {
-            // Single recommendation accepted by picking its (green) card in the
-            // boxed picker — same provenance as an empty-submit accept.
-            answer = `${plainSuggested} (accepted recommendation)`;
-        }
-        else {
-            answer = typed;
-        }
+        const resolved = resolveAnswer(pending, a);
+        // Clarify's transcript records PROVENANCE; grill's deliberately does not,
+        // because grill's is fed back verbatim into the next grill-gen prompt. That
+        // is now the only difference between the two dialogs, and it is one line.
+        // An accept covers both routes to it: submitting empty, and pressing the
+        // single green card.
+        const answer = resolved.source === 'accepted' ?
+            `${resolved.answer} (accepted recommendation)`
+            : resolved.answer;
         answers.push(`Q${answers.length + 1}: ${plainQ}\nA${answers.length + 1}: ${answer}`);
     }
     if (answers.length === 0) {
@@ -821,9 +807,11 @@ export async function planAuto(ctx, cwd, feature, deps) {
     const hasRequirements = reqEntries.length > 0;
     // `best` is both the plan the next round reprompts FROM and the plan that
     // ships — kept identical because adoption is monotone (see coverage-loop.ts).
+    //
+    // It is also the ONLY handle on the accounting. There used to be a second,
+    // `let accounting`, carried alongside — see the ScoredPlan doc comment for the
+    // requirement-to-wrong-task bug that cost us.
     let best = await scorePlan(planTitles);
-    // The carried accounting (cross-cutting + unowned) for the plan that ships.
-    let accounting = best.accounting;
     let round = 0;
     // #2: the round cap can be lifted ONCE. An adoption is a fresh whole-plan roll,
     // so the plan that gets adopted can expose an uncovered area the pre-adoption
@@ -873,8 +861,12 @@ export async function planAuto(ctx, cwd, feature, deps) {
             // every round, so there is no trustworthy "grew"/"new" signal to gate on.
             const priorCovered = best.plan.covered.size;
             const priorMissing = new Set(best.plan.missing.map(normMissingArea));
+            // The WHOLE scored plan is adopted, titles and accounting together.
+            // This used to be two assignments, and the second one kept the OLD
+            // plan's accounting whenever the new plan's coverage-map child faulted
+            // (`cand.accounting ?? accounting`) — binding requirements to titles
+            // they were never mapped against. See the ScoredPlan doc comment.
             best = cand;
-            accounting = cand.accounting ?? accounting;
             logPlanDebug(cwd, `decompose retry ADOPTED — ${decision.reason}`);
             if (!bonusRoundUsed
                 && round >= roundCap
@@ -926,8 +918,8 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // exactly the class that, having no carrier, was warned-about then dropped (mx5
     // 2026-07-16, §10 test-infra). Carried independent of `accounting` so a mapping
     // fault (accounting === null) can't strand them either.
-    const carriedCrossCutting = accounting?.crossCutting ?? [];
-    const carriedUnmapped = accounting?.unmapped ?? [];
+    const carriedCrossCutting = best.accounting?.crossCutting ?? [];
+    const carriedUnmapped = best.accounting?.unmapped ?? [];
     const carriedJudge = best.judgeMissing;
     // Dangling artifacts still unclaimed by any title of the SHIPPING plan are a
     // fourth channel: the producing obligation travels verbatim into every task
@@ -959,16 +951,17 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // not a substring of the doc and is dropped, so a fabricated contract — exactly
     // the F3 bug — can never enter the registry. Best-effort: any fault here is
     // swallowed (the registry is a sharpener, never a planning blocker).
-    try {
-        const contractRaw = await deps.runChild('contract-extract', '', CONTRACT_EXTRACT_PROMPT(featureForModel, planTitles));
-        const grounded = keepGroundedContracts(parseContractLines(contractRaw), featureForModel);
-        logPlanDebug(cwd, `contract extraction: ${grounded.length} grounded contract(s) kept`
-            + ` from ${parseContractLines(contractRaw).length} emitted`);
-        await appendContracts(cwd, grounded);
-    }
-    catch {
-        // best-effort registry
-    }
+    await runGroundedExtraction({
+        cwd,
+        runChild: deps.runChild,
+        child: 'contract-extract',
+        noun: 'contract',
+        label: 'contract extraction',
+        prompt: CONTRACT_EXTRACT_PROMPT(featureForModel, planTitles),
+        parse: parseContractLines,
+        ground: emitted => keepGroundedContracts(emitted, featureForModel),
+        append: appendContracts
+    });
     // Launch contract (mx5 run 10 item 4): extract the package/build SCRIPTS the design
     // declares the project must expose (`migrate`/`seed` fell through decompose and
     // shipped missing, unchecked). Each emitted name is re-grounded against the design
@@ -979,16 +972,17 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // far from the design's summary list (`test:ct` in §2 vs §9's five) can't be
     // missed by a weak model's recall — the child classifies, it no longer recalls.
     // Best-effort.
-    try {
-        const scriptRaw = await deps.runChild('launch-extract', '', LAUNCH_EXTRACT_PROMPT(featureForModel, enumerateScriptCandidates(featureForModel)));
-        const grounded = keepGroundedScripts(parseScriptLines(scriptRaw), featureForModel);
-        logPlanDebug(cwd, `launch-contract extraction: ${grounded.length} grounded script(s) kept`
-            + ` from ${parseScriptLines(scriptRaw).length} emitted`);
-        await appendDeclaredScripts(cwd, grounded);
-    }
-    catch {
-        // best-effort artifact
-    }
+    await runGroundedExtraction({
+        cwd,
+        runChild: deps.runChild,
+        child: 'launch-extract',
+        noun: 'script',
+        label: 'launch-contract extraction',
+        prompt: LAUNCH_EXTRACT_PROMPT(featureForModel, enumerateScriptCandidates(featureForModel)),
+        parse: parseScriptLines,
+        ground: emitted => keepGroundedScripts(emitted, featureForModel),
+        append: appendDeclaredScripts
+    });
     // Thread the feature's spec doc(s) into every title so each per-task
     // pipeline — which only ever sees its title — reads the real spec instead of
     // a lossy one-line paraphrase of it.
@@ -1004,8 +998,8 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // §9's "serves `/api` + static `dist/`" out of its spec with nothing to stop
     // it). Inert until the owned-requirements injection is wired into the phase
     // prompts; recorded regardless so the plan's mapping is auditable per run.
-    if (accounting && accounting.mapped.length > 0) {
-        await writeOwnedRequirements(cwd, accounting.mapped
+    if (best.accounting && best.accounting.mapped.length > 0) {
+        await writeOwnedRequirements(cwd, best.accounting.mapped
             .filter(m => m.task >= 1 && m.task <= titles.length)
             .map(m => ({ quote: m.req.quote, anchor: m.req.anchor, title: titles[m.task - 1] })));
     }
@@ -1022,16 +1016,50 @@ export async function planAuto(ctx, cwd, feature, deps) {
     };
     // Durable, user-visible coverage record (goal A(c)): what was carried and what
     // stayed unowned lives in the plan file itself, not only in a transient toast.
-    const coverageNote = accounting === null ? '' : ([
-        `${reqEntries.length} grounded requirement(s): ${accounting.mapped.length} task-mapped, `
-            + `${accounting.crossCutting.length} cross-cutting (carried into every task via `
-            + `.pi-tasks/requirements.md), ${accounting.unmapped.length} unowned`,
-        ...accounting.crossCutting.map(e => `- carried: "${e.quote}"`),
-        ...accounting.unmapped.map(e => `- UNOWNED (no task covers this): "${e.quote}"`)
+    const shipped = best.accounting;
+    const coverageNote = shipped === null ? '' : ([
+        `${reqEntries.length} grounded requirement(s): ${shipped.mapped.length} task-mapped, `
+            + `${shipped.crossCutting.length} cross-cutting (carried into every task via `
+            + `.pi-tasks/requirements.md), ${shipped.unmapped.length} unowned`,
+        ...shipped.crossCutting.map(e => `- carried: "${e.quote}"`),
+        ...shipped.unmapped.map(e => `- UNOWNED (no task covers this): "${e.quote}"`)
     ].join('\n'));
     await writeTaskFile(cwd, fm, buildAutoBody(feature, clarifications, titles, coverageNote));
     return id;
 }
+/**
+ * One best-effort, HOST-GROUNDED extraction: ask a child to emit lines, drop
+ * every line the design does not literally contain, log the kept/emitted split,
+ * and append what survives to a run-level artifact.
+ *
+ * The grounding step is the reason this shape exists rather than a plain child
+ * call. A child asked for interface facts will paraphrase and occasionally invent
+ * them (mx5 run 8, F3), and an invented fact in a run-level registry is read as
+ * authoritative by every downstream refine/compose/verify. So nothing the child
+ * says is trusted: `ground` re-checks each emitted line against the design text
+ * host-side, and only substrings survive.
+ *
+ * Best-effort by contract. These artifacts SHARPEN planning; none of them gates
+ * it, so a fault here is swallowed rather than failing a run that is otherwise
+ * fine — which is why the whole body sits in one `catch {}`.
+ *
+ * The two call sites (contracts, launch scripts) were byte-identical apart from
+ * the four values this row carries, and the contracts copy parsed its child's
+ * output twice — once for the artifact and once for the log count — because the
+ * duplication made the second parse easy to miss.
+ */
+async function runGroundedExtraction(row) {
+    try {
+        const emitted = row.parse(await row.runChild(row.child, '', row.prompt));
+        const grounded = row.ground(emitted);
+        logPlanDebug(row.cwd, `${row.label}: ${grounded.length} grounded ${row.noun}(s) kept`
+            + ` from ${emitted.length} emitted`);
+        await row.append(row.cwd, grounded);
+    }
+    catch {
+        // best-effort artifact — never a planning blocker
+    }
+}
 /** The two feature-level planning children, shown as steps in the loader. */
 const AUTO_PLAN_STEPS = {
     'auto-clarify': { step: 'clarify', stepNum: 1 },
@@ -1303,26 +1331,23 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 onVerified: () => checkOffTask(cwd, id, next.index, res.taskId, next.title)
             });
             active = gate.ctx;
-            if (gate.kind === 'paused') {
-                await markResumable(cwd, res.taskId);
-                await updateTaskFrontMatter(cwd, id, { state: 'failed' });
-                announceDone(active, `${id} paused at "${next.title}" — verification failed and you dismissed the choice; resume with /task-auto-resume.`, 'warning');
-                return;
-            }
-            if (gate.kind === 'session-cancelled') {
-                announceDone(active, `${id} paused — could not start a session for autofix. Run /task-auto-resume to retry.`, 'warning');
-                return;
-            }
-            if (gate.kind === 'interrupted') {
-                await markResumable(cwd, res.taskId);
-                announceDone(active, `${id} paused at "${next.title}" — resume with /task-auto-resume.`, 'warning');
-                return;
-            }
-            if (gate.kind === 'failed') {
-                await markResumable(cwd, res.taskId);
-                await updateTaskFrontMatter(cwd, id, { state: 'failed' });
-                const why = gate.reason ? ` — ${gate.reason.slice(0, 160)}` : '';
-                announceDone(active, `${id} stopped at "${next.title}"${why} — fix and run /task-auto-resume.`, 'error');
+            // Every terminal gate outcome — what to demote, what to fail, what to
+            // say — comes from TERMINAL_OUTCOMES, shared verbatim with /task's
+            // loop. `done` alone is not terminal here: it falls through to the
+            // next task.
+            if (gate.kind !== 'done') {
+                const outcome = TERMINAL_OUTCOMES[gate.kind];
+                if (outcome.markResumable)
+                    await markResumable(cwd, res.taskId);
+                if (outcome.failParent) {
+                    await updateTaskFrontMatter(cwd, id, { state: 'failed' });
+                }
+                announceDone(active, outcome.message({
+                    tag: id,
+                    at: formatAt(next.title),
+                    why: formatWhy(gate.kind === 'failed' ? gate.reason : undefined),
+                    resumeCmd: '/task-auto-resume'
+                }), outcome.level);
                 return;
             }
             // ROOT-CAUSE REPAIR (mx5 run 14 item 5): the gate may have attributed a

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

@@ -0,0 +1,104 @@
+/**
+ * command-run — running a project command under the gate's ENV-GAP CONTRACT, and
+ * the single statement of what each way of ending means.
+ *
+ * The contract: a command that never ran tells you nothing about the code. A
+ * missing runner, a 127 inside the script chain, a browser binary that was never
+ * installed, a database that is not up on this box, a timeout — all of these are
+ * facts about the ENVIRONMENT, and none of them may fail a gate or close a debt.
+ * Only a command that demonstrably ran and exited non-zero for a reason of its
+ * own is a failure, and only exit 0 is a pass.
+ *
+ * Why a module. That ladder was written three times inside final-gate.ts —
+ * `runGateCommand`, `runVerifyCommandLine`, `rerunDebtVerifyCommand` — in the
+ * same order with different labels, and the copies had already drifted (the
+ * infrastructure pattern applied unconditionally in one and only on request in
+ * another). repo-health-check.ts had solved exactly this shape years earlier:
+ * `classifyHealthRun` is pure over a value, extracted so its sync and async
+ * runners "cannot drift apart". The gate never adopted it.
+ *
+ * The second half is the seam. Classification is now pure over a `CommandRun`
+ * value, and SPAWNING is a `CommandRunner` the caller injects. That is what lets
+ * the gate's tests state a case as `{status: 1, stdout: "…"}` instead of writing
+ * a real `node -e` child, creating a temp directory for it, and — for the three
+ * cases only reachable that way — shadowing a binary on `process.env.PATH` and
+ * resetting a module-level cache, which made those tests order-sensitive and
+ * needed a Windows carve-out. Note the asymmetry this closes: `BootDeps` already
+ * carried nine injectable probes for the gate's boot half while its command half
+ * had none.
+ */
+/** What one finished command looks like, stripped of how it was spawned. */
+export interface CommandRun {
+    /** The runner binary itself never started (ENOENT, no POSIX shell). */
+    failedToStart: boolean;
+    /** Why it could not start — only meaningful with `failedToStart`. */
+    failureMessage?: string;
+    /** Exit status, or null when the child was killed (timeout or signal). */
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Everything a runner needs to spawn one command. */
+export interface CommandSpec {
+    cwd: string;
+    bin: string;
+    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
+     * rather than the live `process.env`.
+     */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * 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.
+ */
+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
+ * a code fault: a browser suite (Playwright/Cypress) whose browser binaries or system
+ * libraries were never installed here (mx5 run 10 item 2: `test:ct` must run in the
+ * gate, but on a box with no Playwright browsers it is an environment gap, not a FAIL).
+ * These exit non-zero (not 127), so they need output-shape recognition to skip.
+ */
+export declare const ENV_GAP_OUTPUT_RE: RegExp;
+/**
+ * A non-zero exit whose output shows the EXTERNAL INFRASTRUCTURE a launch script
+ * talks to is absent HERE — a database/daemon that is not running or not
+ * installed — rather than a fault in the script itself.
+ *
+ * NOT applied by default, and that is deliberate: a migrate/seed against no DB is
+ * an environment gap on this box, but the same wording out of a `test` run is a
+ * real failure the suite must own. Callers opt in per command by passing it in
+ * `gapPatterns`, which is why that parameter exists rather than a boolean.
+ */
+export declare const INFRA_GAP_OUTPUT_RE: RegExp;
+/** Which way a command failed to tell us anything. */
+export type CommandGapId = 'spawn-failed' | 'killed' | 'command-not-found' | 'missing-runtime' | 'infrastructure';
+export type CommandVerdict = 
+/** Nothing was observed. Never fails a gate, never closes a debt. */
+{
+    outcome: 'gap';
+    gap: CommandGapId;
+    detail: string;
+} | {
+    outcome: 'pass';
+} | {
+    outcome: 'fail';
+    status: number;
+    tail: string;
+};
+/** 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;
+/**
+ * Decide what one finished command proved. Pure — no spawning, no filesystem, no
+ * clock — so every case is stateable as a literal.
+ *
+ * `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;

package/dist/task/command-run.js

@@ -0,0 +1,138 @@
+/**
+ * command-run — running a project command under the gate's ENV-GAP CONTRACT, and
+ * the single statement of what each way of ending means.
+ *
+ * The contract: a command that never ran tells you nothing about the code. A
+ * missing runner, a 127 inside the script chain, a browser binary that was never
+ * installed, a database that is not up on this box, a timeout — all of these are
+ * facts about the ENVIRONMENT, and none of them may fail a gate or close a debt.
+ * Only a command that demonstrably ran and exited non-zero for a reason of its
+ * own is a failure, and only exit 0 is a pass.
+ *
+ * Why a module. That ladder was written three times inside final-gate.ts —
+ * `runGateCommand`, `runVerifyCommandLine`, `rerunDebtVerifyCommand` — in the
+ * same order with different labels, and the copies had already drifted (the
+ * infrastructure pattern applied unconditionally in one and only on request in
+ * another). repo-health-check.ts had solved exactly this shape years earlier:
+ * `classifyHealthRun` is pure over a value, extracted so its sync and async
+ * runners "cannot drift apart". The gate never adopted it.
+ *
+ * The second half is the seam. Classification is now pure over a `CommandRun`
+ * value, and SPAWNING is a `CommandRunner` the caller injects. That is what lets
+ * the gate's tests state a case as `{status: 1, stdout: "…"}` instead of writing
+ * a real `node -e` child, creating a temp directory for it, and — for the three
+ * cases only reachable that way — shadowing a binary on `process.env.PATH` and
+ * resetting a module-level cache, which made those tests order-sensitive and
+ * needed a Windows carve-out. Note the asymmetry this closes: `BootDeps` already
+ * carried nine injectable probes for the gate's boot half while its command half
+ * had none.
+ */
+import { spawnSync } from 'node:child_process';
+import { isCommandNotFound } from './runner-resolve.js';
+/** The real runner. */
+export const spawnCommand = spec => {
+    const r = spawnSync(spec.bin, spec.args, {
+        cwd: spec.cwd,
+        encoding: 'utf8',
+        timeout: spec.timeoutMs,
+        ...(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 ?? ''
+    };
+};
+/**
+ * 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
+ * libraries were never installed here (mx5 run 10 item 2: `test:ct` must run in the
+ * gate, but on a box with no Playwright browsers it is an environment gap, not a FAIL).
+ * These exit non-zero (not 127), so they need output-shape recognition to skip.
+ */
+export const ENV_GAP_OUTPUT_RE = /Executable doesn't exist|playwright install|browserType\.\w+: Executable|(?:wasn't|weren't) installed|Host system is missing dependencies|No usable sandbox|Cypress verification|Cypress executable (?:not found|was not found)|browser(?:s)? (?:is|are)? ?not installed/i;
+/**
+ * A non-zero exit whose output shows the EXTERNAL INFRASTRUCTURE a launch script
+ * talks to is absent HERE — a database/daemon that is not running or not
+ * installed — rather than a fault in the script itself.
+ *
+ * NOT applied by default, and that is deliberate: a migrate/seed against no DB is
+ * an environment gap on this box, but the same wording out of a `test` run is a
+ * real failure the suite must own. Callers opt in per command by passing it in
+ * `gapPatterns`, which is why that parameter exists rather than a boolean.
+ */
+export const INFRA_GAP_OUTPUT_RE = /ECONNREFUSED|connection refused|ENOTFOUND|EAI_AGAIN|is the server running|could not connect|cannot connect to the docker daemon|connect: connection|no such host/i;
+/**
+ * The gap ladder, in order. FIRST MATCH WINS.
+ *
+ * `spawn-failed` is first and is kept distinguishable from every other row by its
+ * id: a tool-level gap (127 inside the chain, a missing browser, a timeout) means
+ * the runner demonstrably RAN, and only genuine spawn failures feed the gate's
+ * full-blindness guard (mx5 run 16 — see observabilityGapFailure).
+ */
+const GAP_RULES = [
+    {
+        id: 'spawn-failed',
+        detail: run => run.failureMessage ?
+            `runner did not spawn (${run.failureMessage})`
+            : 'runner did not spawn',
+        applies: run => run.failedToStart
+    },
+    {
+        id: 'killed',
+        detail: () => 'killed (timeout or signal)',
+        applies: run => run.status === null
+    },
+    {
+        id: 'command-not-found',
+        detail: () => 'command not found (127)',
+        applies: (run, output) => isCommandNotFound(run.status, output)
+    },
+    {
+        id: 'missing-runtime',
+        detail: () => 'missing browser/runtime',
+        applies: (_run, output) => ENV_GAP_OUTPUT_RE.test(output)
+    },
+    {
+        id: 'infrastructure',
+        detail: () => 'external infrastructure unreachable',
+        applies: (_run, output, gapPatterns) => gapPatterns.some(re => re.test(output))
+    }
+];
+/** Last ~`limit` chars of the command's combined output, one line, for the reason. */
+export function outputTail(stdout, stderr, limit = 400) {
+    const combined = `${stdout}\n${stderr}`.trim();
+    if (combined.length === 0)
+        return '';
+    const tail = combined.slice(-limit).replace(/\s+/g, ' ').trim();
+    return combined.length > limit ? `…${tail}` : tail;
+}
+/**
+ * Decide what one finished command proved. Pure — no spawning, no filesystem, no
+ * clock — so every case is stateable as a literal.
+ *
+ * `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 = []) {
+    // 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}`;
+    for (const rule of GAP_RULES) {
+        if (rule.applies(run, output, gapPatterns)) {
+            return { outcome: 'gap', gap: rule.id, detail: rule.detail(run) };
+        }
+    }
+    // Only reachable with a real non-zero status: `failedToStart` and a null
+    // status are both gap rows above.
+    return {
+        outcome: 'fail',
+        status: run.status ?? -1,
+        tail: outputTail(run.stdout, run.stderr)
+    };
+}

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

@@ -25,6 +25,7 @@
  * docs task all flow through the same integers.
  */
 /** A scored plan candidate — the minimum the adoption rule needs. */
+import type { CoverageAccounting } from './requirements.js';
 export interface CoveragePlan {
     titles: string[];
     /**
@@ -94,3 +95,47 @@ export interface AdoptionDecision {
  *      the no-requirements path also ships the best, not the last.
  */
 export declare function decideAdoption(current: CoveragePlan, retry: CoveragePlan, hasRequirements: boolean): AdoptionDecision;
+/**
+ * One scored plan: its titles, and every judgement made ABOUT those titles.
+ *
+ * The whole point of this type is that it is indivisible. `accounting.mapped[i].task`
+ * is a 1-BASED INDEX INTO `plan.titles` — it means nothing except against the exact
+ * title list the coverage-map child was prompted with. Hold the two apart and the
+ * index silently addresses the wrong plan.
+ *
+ * That is not hypothetical. The coverage loop used to keep `best` (the scored plan)
+ * and a separate `let accounting`, updated on adoption as
+ * `accounting = cand.accounting ?? accounting`. `cand.accounting` is null whenever
+ * the coverage-map child throws or its output fails to parse — a fault that is
+ * SWALLOWED, while `decideAdoption` still adopts, because the monotonic guard runs
+ * on the grounded covered-set and not on the accounting. So: round 1 maps
+ * requirement #3 to task 2 of plan A; round 2 is adopted but its coverage-map child
+ * returns nothing; `planTitles` becomes plan B's while `accounting` stays plan A's;
+ * and `writeOwnedRequirements` binds requirement #3 to plan B's title #2 — a
+ * different task. The bounds filter at the write site only checks `1..titles.length`,
+ * so nothing catches it. Downstream, `ownedForTitle` force-appends that obligation
+ * into the wrong task's CONSTRAINTS and the final gate reports it unclaimed.
+ *
+ * Keeping accounting INSIDE the scored plan makes that state unrepresentable rather
+ * than merely fixed: adopting a plan is one assignment, so titles and accounting
+ * cannot come from different rounds. If you find yourself lifting `accounting` back
+ * out into its own variable, this is the bug you are re-introducing.
+ */
+export interface ScoredPlan {
+    plan: CoveragePlan;
+    /**
+     * The per-requirement map for `plan.titles`, or null when the mapping child
+     * faulted. Null means "no accounting for THIS plan" — never "reuse the last
+     * plan's". A round that loses its accounting loses it; the judge-missing
+     * channel below is carried independently so nothing is stranded.
+     */
+    accounting: CoverageAccounting | null;
+    suspect: boolean;
+    /**
+     * The holistic-judge missing areas alone (NOT the quoted unmapped entries,
+     * which the grounded accounting already carries). This is the belt-only
+     * channel — areas requirement-extraction never captured, so nothing durable
+     * sees them unless carried explicitly at exhaustion.
+     */
+    judgeMissing: string[];
+}