@mjasnikovs/pi-task 0.26.0 → 0.28.0

package/dist/task/phases.js

@@ -10,6 +10,7 @@ import { runWorker } from '../workers/pi-worker-core.js';
 import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
 import { search as defaultSearch } from '../workers/search-core.js';
 import { extractEnrichTargets } from './enrichment.js';
+import { fanoutTimeoutPolicy, workerCarryForward, workerProgressCeilingMs, projectDocsBudget, projectDocsBudgetNotice } from './research-fanout-budget.js';
 import { isIntegrationUnknown } from './unknown-routing.js';
 import { extractUserDirectives, preserveDirectivesBlock, enforceDirectives } from './user-directives.js';
 import { demoteUnsourcedAttributions } from './context-attribution.js';
@@ -560,6 +561,13 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     // the pattern nexxtasks exists to prevent. To re-run the experiment, restore the block
     // this comment replaces — see the git history of this file and the PROMPT 4 entry in
     // nexxtasks.txt RESULTS.
+    // nexttask 5B fan-out bounds. Both read their env ONCE per research phase, so
+    // every worker in a run sees the same policy and a harness cannot half-apply
+    // an arm; both are null in the shipped configuration.
+    const fanoutBudget = projectDocsBudget();
+    const fanoutTimeout = fanoutTimeoutPolicy();
+    const carryForward = workerCarryForward();
+    const progressCeilingMs = workerProgressCeilingMs();
     let doneCount = 0;
     const updateProgress = () => {
         doneCount++;
@@ -572,9 +580,18 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     // per-worker measurement — waitMs the worker's own cold-start, workMs its
     // generation+tool-call cost. Under the opt-in parallel mode the numbers are
     // wall-clock-relative (queueing shows up in waitMs).
+    //
+    // Restarted attempts get their OWN row. Without one the widget contradicts
+    // itself: mx5 run 18 printed `workers 722.2s` over a longest member reading
+    // `worker:apis work 239.3s`, because wait/work describe the final attempt
+    // while the phase clock counts all three. The discarded time is the whole
+    // gap, so naming it is what closes the widget.
     const recordWorker = (label, p) => p.then(r => {
         deps.recordSubStep?.(`${label} wait`, r.waitMs);
         deps.recordSubStep?.(`${label} work`, r.workMs);
+        if (r.attempts > 1) {
+            deps.recordSubStep?.(`${label} discarded (${r.attempts - 1} restart${r.attempts > 2 ? 's' : ''})`, Math.max(0, r.totalWallMs - r.waitMs - r.workMs));
+        }
         return r;
     });
     // Run the four workers ONE AT A TIME. Settled by an A/B on the local
@@ -617,9 +634,15 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             prompt: prior => appendNoThink(orientation.block
                 + promptHeader
                 + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined)
-                + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')),
+                + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')
+                // 5B CAP arm — empty unless PI_TASK_PROJECT_DOCS_BUDGET is
+                // set. The tool-side half lives in pi-worker-docs.ts; a
+                // budget enforced without being announced would just read
+                // to the worker as a broken tool.
+                + (fanoutBudget === null ? '' : projectDocsBudgetNotice(fanoutBudget))),
             tools: 'read,grep,find,ls,pi-worker-docs'
                 + (searchConfigured() ? ',pi-worker-search,pi-worker-fetch' : ''),
+            fanoutBounded: true,
             extensions: [
                 DOCS_EXTENSION_PATH,
                 ...(searchConfigured() ? [SEARCH_EXTENSION_PATH] : [])
@@ -738,6 +761,32 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             spawn: deps.spawn,
             ...(spec.tools ? { tools: spec.tools } : {}),
             ...(spec.extensions ? { extensions: spec.extensions } : {}),
+            // 5B SCALE arm — null unless both env vars are set. Only the
+            // docs-capable worker can fan out, so only it can be scaled.
+            ...(spec.fanoutBounded && fanoutTimeout ? { fanoutTimeout } : {}),
+            // 5B RESCUE arm — off unless its env vars are set. Applies to
+            // EVERY research worker, not just the docs-capable one: any
+            // worker that gets killed loses its work the same way.
+            ...(carryForward ? { carryForward: true } : {}),
+            ...(progressCeilingMs !== null ?
+                { progressTimeoutCeilingMs: progressCeilingMs }
+                : {}),
+            // One line per DISCARDED attempt. The `done` line below reports
+            // the final attempt only, so a worker that timed out twice at
+            // 240s and then answered used to log exactly like a clean one —
+            // 8 minutes of burned compute recoverable only by subtracting
+            // its own wait+work from the start/done timestamps.
+            onCarryForward: ci => {
+                deps.logDebug?.(`${spec.label}: CARRY-FORWARD injected into attempt ${ci.attempt}`
+                    + ` (${ci.chars} chars onto a ${ci.promptCharsBefore}-char prompt)`);
+            },
+            onRestart: rs => {
+                deps.logDebug?.(`${spec.label}: RESTART (attempt ${rs.attempt} discarded)`
+                    + ` reason=${rs.reason} wall=${rs.wallMs}ms`
+                    + ` wait=${rs.waitMs}ms work=${rs.workMs}ms`
+                    + (rs.detail ? ` — ${rs.detail}` : ''));
+                deps.onChildOutput?.(`${spec.label}: restart (${rs.reason})`);
+            },
             onLine: line => {
                 // The one 'stream' site in this file: raw research-worker
                 // output. Every other logDebug here records a decision.
@@ -838,6 +887,18 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             }
         }
         deps.logDebug?.(`${spec.label}: done exit=${r.exitCode} wait=${r.waitMs}ms work=${r.workMs}ms`
+            // attempts/total are the pair that makes wait+work honest: they are
+            // the FINAL attempt's split, and only `total` sees the discarded ones.
+            + ` attempts=${r.attempts} total=${r.totalWallMs}ms`
+            + (r.restarts.length > 0 ?
+                ` restarts=[${r.restarts.map(x => x.reason).join(',')}]`
+                : '')
+            // Attribution for the RESCUE arm: a run with zero restarts was
+            // never killed (the progress deadline did it), while a run that
+            // restarted and salvaged was killed but kept its work. Without
+            // this the two are indistinguishable in the logs, and "0
+            // timeouts" cannot be traced to the half that earned it.
+            + (r.salvagedFromDiscardedAttempt ? ' salvaged=1' : '')
             + (r.stderr ? ` stderr=${r.stderr.slice(0, 300)}` : '')
             + (r.leakedToolCall ? ` leaked=${r.leakedToolCall.trim().slice(0, 80)}` : ''));
         updateProgress();

package/dist/task/repo-health-check.js

@@ -32,7 +32,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
-import { resolveRunner, runnerEnv } from './runner-resolve.js';
+import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
 /** How much of a failing command's output to keep — bounded so a wedged tool that
  *  spews megabytes cannot bloat the trail. stderr leads (a crash trace lives there). */
 const HEALTH_OUTPUT_MAX_LINES = 40;
@@ -142,10 +142,12 @@ export function runRepoHealthCheck(cwd, timeoutMs = 600_000) {
         // Tool missing (ENOENT) or killed by timeout → cannot conclude; skip it.
         if (r.error || r.status === null)
             continue;
-        // Exit 127 = "command not found" INSIDE the script chain (e.g. `bun run lint`
-        // before node_modules exists — seen live failing TASK_0001's first verify).
-        // Same environment gap as ENOENT, just surfaced through the runner's shell.
-        if (r.status === 127)
+        // "Command not found" INSIDE the script chain (e.g. `bun run lint` before
+        // node_modules exists — seen live failing TASK_0001's first verify). Same
+        // environment gap as ENOENT, just surfaced through the runner's shell —
+        // as exit 127 where a posix shell ran it, else by the runner's own wording
+        // (Windows bun reports the miss itself and exits 1).
+        if (isCommandNotFound(r.status, `${r.stdout ?? ''}\n${r.stderr ?? ''}`))
             continue;
         if (r.status !== 0) {
             return {

package/dist/task/research-fanout-budget.d.ts

@@ -0,0 +1,121 @@
+/**
+ * nexttask 5B — the two candidate bounds on worker:apis's project-source fan-out.
+ *
+ * ⚠ NOT WIRED. Both levers here are OFF unless their env var is set, so the
+ * shipped path is bit-for-bit what it was. They exist so
+ * `scripts/live-research-fanout-budget-ab.ts` can run them against the shipped
+ * baseline in the SAME build — the alternative (dist surgery) measures a patched
+ * copy of the code and not the code. Nothing may read these outside that harness
+ * until it reports PASS; a lever wired on argument rather than measurement is the
+ * failure mode nexttasks exists to prevent.
+ *
+ * THE FAULT THEY TARGET (mx5 run 18, measured — scripts/research-restart-baserate.ts):
+ * `worker:apis` fans out `pi-worker-docs(module: ".")` project-source lookups, each
+ * of which spawns its own summarising child, and the per-worker wall-clock cap is
+ * 240s. Pearson r(project lookups, worker wall clock) = 0.909 over 24 tasks. 0-4
+ * lookups never timed out; every worker at >=46 lookups burned the FULL restart
+ * budget — 3 attempts, 720s, two of them discarded whole. The 240s ceiling and a
+ * 46-call fan-out are jointly unsatisfiable, so the timeout is not a backstop
+ * there, it is the guaranteed outcome.
+ *
+ * TWO WAYS TO MAKE THEM SATISFIABLE, and the A/B — not this comment — decides:
+ *
+ *   CAP     bound the fan-out to fit the ceiling. Told to the worker upfront
+ *           (projectDocsBudgetNotice) and enforced in the tool
+ *           (projectDocsBudgetExhausted), because run 18 shows the prompt alone
+ *           does not bind: the same worker is ALREADY told "be decisive" by
+ *           WORKER_TIMEOUT_HINT on every restart.
+ *   SCALE   bound the ceiling to fit the fan-out: each project-source lookup
+ *           pushes the deadline out, up to a hard ceiling, so a worker that is
+ *           making progress is not killed for making progress.
+ *
+ * The risk each carries, and why the A/B's quality invariant is load-bearing: CAP
+ * can produce a faster worker that ships a THINNER APIS section, which is a
+ * regression wearing a win's clothes (memory/apis-contract-stage2-failed.md: a
+ * lever moved behaviour 20/20 while fabricating 15% of it). SCALE can simply
+ * spend the extra time and still time out, buying nothing.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * BOTH OF THE ABOVE ANSWER THE WRONG QUESTION. Kept for the record and for the
+ * A/B's other arms, but they are not the fix.
+ *
+ * They argue about how long a worker may run. The actual defect is what happens
+ * when it runs out: the attempt is killed and everything it produced is THROWN
+ * AWAY, and the re-spawn is given a hint but no findings — so it re-reads the
+ * same files against the same clock and dies in the same place. That is why
+ * every worker at >=46 lookups burned the FULL budget rather than converging.
+ * The r=0.909 correlation measures the amnesia, not an over-long task.
+ *
+ * Judged against "the worker must return its work", CAP makes the worker read
+ * LESS — lowering the requirement so the metric goes green — and SCALE is a
+ * per-file constant that dies on one big file, and, being wall-clock, makes
+ * answer quality a function of the user's hardware: the same task on a slower
+ * local model loses its work and degrades. No constant fixes that.
+ *
+ *   RESCUE  (pi-worker-core.ts) carry the killed attempt's findings into the
+ *           next one and never return less than the best attempt produced, so a
+ *           restart CONVERGES instead of repeating; and deadline on lack of
+ *           PROGRESS rather than elapsed time, so "slow" and "stuck" stop being
+ *           the same verdict. Being stuck is already detected separately and
+ *           correctly by the output-stall probe (STALL_AFTER_MS), which resets
+ *           on progress and only kills when the model endpoint is unreachable.
+ *
+ * Its risk is its own, and the same quality invariant catches it: a half-written
+ * entry replayed under "work already done" is exactly how a fabrication gets
+ * laundered into a final answer. Hence the carry is framed as unverified, and
+ * ungrounded-symbol and anti-synthesis counts gate the arm.
+ */
+/** Max project-source (`module: "."`) docs lookups per worker ATTEMPT. Unset = no cap. */
+export declare const PROJECT_DOCS_BUDGET_ENV = "PI_TASK_PROJECT_DOCS_BUDGET";
+/** Deadline extension granted per project-source lookup, in ms. Unset = no extension. */
+export declare const FANOUT_TIMEOUT_PER_LOOKUP_ENV = "PI_TASK_FANOUT_TIMEOUT_PER_LOOKUP_MS";
+/** Hard ceiling the extensions may never push the deadline past, in ms. */
+export declare const FANOUT_TIMEOUT_CEILING_ENV = "PI_TASK_FANOUT_TIMEOUT_CEILING_MS";
+/** RESCUE: carry a killed attempt's findings into the re-spawn, and salvage its output. `1` = on. */
+export declare const WORKER_CARRY_FORWARD_ENV = "PI_TASK_WORKER_CARRY_FORWARD";
+/** RESCUE: deadline on lack of progress instead of elapsed time. Value = absolute ceiling, ms. */
+export declare const WORKER_PROGRESS_CEILING_ENV = "PI_TASK_WORKER_PROGRESS_CEILING_MS";
+type Env = (key: string) => string | undefined;
+/**
+ * The CAP arm's budget, or null when the lever is off (the shipped default).
+ * A non-numeric or non-positive value is off too: a typo'd env var must not
+ * silently cap the worker at 0 lookups.
+ */
+export declare function projectDocsBudget(env?: Env): number | null;
+/**
+ * The SCALE arm's policy, or null when off. Both halves are required: an
+ * extension with no ceiling is an unbounded worker, which is the one thing the
+ * 240s cap exists to prevent.
+ */
+export declare function fanoutTimeoutPolicy(env?: Env): {
+    perLookupMs: number;
+    ceilingMs: number;
+} | null;
+/**
+ * The RESCUE arm's two halves, or nulls when off.
+ *
+ * Separated because they are independent claims and the A/B should be able to
+ * attribute a win: RESCUE_CARRY says a restart should keep what the killed
+ * attempt found, RESCUE_PROGRESS_CEILING says a worker should be killed for
+ * going quiet rather than for taking a while. Either can pay off without the
+ * other, and either can fabricate or hang without the other.
+ */
+export declare function workerCarryForward(env?: Env): boolean;
+/**
+ * The absolute backstop for the progress-based deadline, or null when off.
+ * Required rather than defaulted: a progress deadline with no ceiling is an
+ * unbounded worker, which is the one thing the fixed cap exists to prevent.
+ */
+export declare function workerProgressCeilingMs(env?: Env): number | null;
+/**
+ * The upfront half of the CAP arm, appended to the APIS worker's prompt.
+ *
+ * Upfront and NUMERIC on purpose. The worker cannot ration a budget it learns
+ * about only when it is spent, and "be decisive" — which it already receives on
+ * every timeout restart — is exactly the unquantified version that run 18 shows
+ * it ignoring until the third attempt.
+ */
+export declare function projectDocsBudgetNotice(budget: number): string;
+/** The enforcement half: what the tool returns once the budget is spent. */
+export declare function projectDocsBudgetExhausted(budget: number): string;
+export {};

package/dist/task/research-fanout-budget.js

@@ -0,0 +1,148 @@
+/**
+ * nexttask 5B — the two candidate bounds on worker:apis's project-source fan-out.
+ *
+ * ⚠ NOT WIRED. Both levers here are OFF unless their env var is set, so the
+ * shipped path is bit-for-bit what it was. They exist so
+ * `scripts/live-research-fanout-budget-ab.ts` can run them against the shipped
+ * baseline in the SAME build — the alternative (dist surgery) measures a patched
+ * copy of the code and not the code. Nothing may read these outside that harness
+ * until it reports PASS; a lever wired on argument rather than measurement is the
+ * failure mode nexttasks exists to prevent.
+ *
+ * THE FAULT THEY TARGET (mx5 run 18, measured — scripts/research-restart-baserate.ts):
+ * `worker:apis` fans out `pi-worker-docs(module: ".")` project-source lookups, each
+ * of which spawns its own summarising child, and the per-worker wall-clock cap is
+ * 240s. Pearson r(project lookups, worker wall clock) = 0.909 over 24 tasks. 0-4
+ * lookups never timed out; every worker at >=46 lookups burned the FULL restart
+ * budget — 3 attempts, 720s, two of them discarded whole. The 240s ceiling and a
+ * 46-call fan-out are jointly unsatisfiable, so the timeout is not a backstop
+ * there, it is the guaranteed outcome.
+ *
+ * TWO WAYS TO MAKE THEM SATISFIABLE, and the A/B — not this comment — decides:
+ *
+ *   CAP     bound the fan-out to fit the ceiling. Told to the worker upfront
+ *           (projectDocsBudgetNotice) and enforced in the tool
+ *           (projectDocsBudgetExhausted), because run 18 shows the prompt alone
+ *           does not bind: the same worker is ALREADY told "be decisive" by
+ *           WORKER_TIMEOUT_HINT on every restart.
+ *   SCALE   bound the ceiling to fit the fan-out: each project-source lookup
+ *           pushes the deadline out, up to a hard ceiling, so a worker that is
+ *           making progress is not killed for making progress.
+ *
+ * The risk each carries, and why the A/B's quality invariant is load-bearing: CAP
+ * can produce a faster worker that ships a THINNER APIS section, which is a
+ * regression wearing a win's clothes (memory/apis-contract-stage2-failed.md: a
+ * lever moved behaviour 20/20 while fabricating 15% of it). SCALE can simply
+ * spend the extra time and still time out, buying nothing.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * BOTH OF THE ABOVE ANSWER THE WRONG QUESTION. Kept for the record and for the
+ * A/B's other arms, but they are not the fix.
+ *
+ * They argue about how long a worker may run. The actual defect is what happens
+ * when it runs out: the attempt is killed and everything it produced is THROWN
+ * AWAY, and the re-spawn is given a hint but no findings — so it re-reads the
+ * same files against the same clock and dies in the same place. That is why
+ * every worker at >=46 lookups burned the FULL budget rather than converging.
+ * The r=0.909 correlation measures the amnesia, not an over-long task.
+ *
+ * Judged against "the worker must return its work", CAP makes the worker read
+ * LESS — lowering the requirement so the metric goes green — and SCALE is a
+ * per-file constant that dies on one big file, and, being wall-clock, makes
+ * answer quality a function of the user's hardware: the same task on a slower
+ * local model loses its work and degrades. No constant fixes that.
+ *
+ *   RESCUE  (pi-worker-core.ts) carry the killed attempt's findings into the
+ *           next one and never return less than the best attempt produced, so a
+ *           restart CONVERGES instead of repeating; and deadline on lack of
+ *           PROGRESS rather than elapsed time, so "slow" and "stuck" stop being
+ *           the same verdict. Being stuck is already detected separately and
+ *           correctly by the output-stall probe (STALL_AFTER_MS), which resets
+ *           on progress and only kills when the model endpoint is unreachable.
+ *
+ * Its risk is its own, and the same quality invariant catches it: a half-written
+ * entry replayed under "work already done" is exactly how a fabrication gets
+ * laundered into a final answer. Hence the carry is framed as unverified, and
+ * ungrounded-symbol and anti-synthesis counts gate the arm.
+ */
+/** Max project-source (`module: "."`) docs lookups per worker ATTEMPT. Unset = no cap. */
+export const PROJECT_DOCS_BUDGET_ENV = 'PI_TASK_PROJECT_DOCS_BUDGET';
+/** Deadline extension granted per project-source lookup, in ms. Unset = no extension. */
+export const FANOUT_TIMEOUT_PER_LOOKUP_ENV = 'PI_TASK_FANOUT_TIMEOUT_PER_LOOKUP_MS';
+/** Hard ceiling the extensions may never push the deadline past, in ms. */
+export const FANOUT_TIMEOUT_CEILING_ENV = 'PI_TASK_FANOUT_TIMEOUT_CEILING_MS';
+/** RESCUE: carry a killed attempt's findings into the re-spawn, and salvage its output. `1` = on. */
+export const WORKER_CARRY_FORWARD_ENV = 'PI_TASK_WORKER_CARRY_FORWARD';
+/** RESCUE: deadline on lack of progress instead of elapsed time. Value = absolute ceiling, ms. */
+export const WORKER_PROGRESS_CEILING_ENV = 'PI_TASK_WORKER_PROGRESS_CEILING_MS';
+const defaultEnv = key => process.env[key];
+function positiveInt(raw) {
+    if (raw === undefined)
+        return null;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+/**
+ * The CAP arm's budget, or null when the lever is off (the shipped default).
+ * A non-numeric or non-positive value is off too: a typo'd env var must not
+ * silently cap the worker at 0 lookups.
+ */
+export function projectDocsBudget(env = defaultEnv) {
+    return positiveInt(env(PROJECT_DOCS_BUDGET_ENV));
+}
+/**
+ * The SCALE arm's policy, or null when off. Both halves are required: an
+ * extension with no ceiling is an unbounded worker, which is the one thing the
+ * 240s cap exists to prevent.
+ */
+export function fanoutTimeoutPolicy(env = defaultEnv) {
+    const perLookupMs = positiveInt(env(FANOUT_TIMEOUT_PER_LOOKUP_ENV));
+    const ceilingMs = positiveInt(env(FANOUT_TIMEOUT_CEILING_ENV));
+    return perLookupMs !== null && ceilingMs !== null ? { perLookupMs, ceilingMs } : null;
+}
+/**
+ * The RESCUE arm's two halves, or nulls when off.
+ *
+ * Separated because they are independent claims and the A/B should be able to
+ * attribute a win: RESCUE_CARRY says a restart should keep what the killed
+ * attempt found, RESCUE_PROGRESS_CEILING says a worker should be killed for
+ * going quiet rather than for taking a while. Either can pay off without the
+ * other, and either can fabricate or hang without the other.
+ */
+export function workerCarryForward(env = defaultEnv) {
+    return env(WORKER_CARRY_FORWARD_ENV) === '1';
+}
+/**
+ * The absolute backstop for the progress-based deadline, or null when off.
+ * Required rather than defaulted: a progress deadline with no ceiling is an
+ * unbounded worker, which is the one thing the fixed cap exists to prevent.
+ */
+export function workerProgressCeilingMs(env = defaultEnv) {
+    return positiveInt(env(WORKER_PROGRESS_CEILING_ENV));
+}
+/**
+ * The upfront half of the CAP arm, appended to the APIS worker's prompt.
+ *
+ * Upfront and NUMERIC on purpose. The worker cannot ration a budget it learns
+ * about only when it is spent, and "be decisive" — which it already receives on
+ * every timeout restart — is exactly the unquantified version that run 18 shows
+ * it ignoring until the third attempt.
+ */
+export function projectDocsBudgetNotice(budget) {
+    return (`\n\nLOOKUP BUDGET: you may make at most ${budget} project-source `
+        + '`pi-worker-docs` calls (module: ".") in this attempt. They are the most '
+        + 'expensive thing you can do — each one runs a separate model pass — and '
+        + 'past the budget the tool returns nothing at all. Spend them only on '
+        + 'symbols you will actually list in APIS, batch related questions about '
+        + 'one file into a single call, and read a file directly with `read` when '
+        + 'you just need to see it. When the budget runs out, write your answer '
+        + 'from what you already have.');
+}
+/** The enforcement half: what the tool returns once the budget is spent. */
+export function projectDocsBudgetExhausted(budget) {
+    return (`PROJECT LOOKUP BUDGET SPENT — you have used all ${budget} project-source `
+        + 'docs lookups for this attempt and no further ones will run. Do NOT retry '
+        + 'this call or rephrase it; it will return this same message. Use `read` or '
+        + '`grep` if you must see one more file, then write your answer now from what '
+        + 'you already retrieved.');
+}

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

@@ -20,6 +20,31 @@ export declare function resolveRunner(bin: string, opts?: {
     probe?: (bin: string) => boolean;
     env?: NodeJS.ProcessEnv;
 }): ResolvedRunner;
+/**
+ * Output shapes a RUNNER emits when the command inside a script chain does not
+ * exist, on platforms where that is not reported as exit 127.
+ *
+ * 127 is a POSIX-SHELL convention: on Linux/macOS bun hands the script to
+ * /bin/sh, the shell prints `…: command not found` and exits 127, and the whole
+ * env-gap contract keys off that number. On Windows there is no such shell —
+ * bun runs the script in its own built-in shell, which reports the miss itself
+ * (`bun: command not found: X`) and exits **1**, indistinguishable by status
+ * alone from a real code fault. cmd.exe (9009) and PowerShell have their own
+ * wording. Recognising the shape restores one env-gap contract on all three.
+ *
+ * Deliberately narrow: only wordings a RUNNER/SHELL produces, never the bare
+ * phrase. A suite that prints "command not found" inside a failing assertion is
+ * a real FAIL and must stay one — the posix shape already travels as 127.
+ */
+export declare const COMMAND_NOT_FOUND_OUTPUT_RE: RegExp;
+/**
+ * Did this command fail because the thing it tried to run does not exist here,
+ * rather than because the code is wrong? Exit 127 (POSIX shell) or 9009
+ * (cmd.exe) say so outright; anything else needs the runner's own wording (see
+ * COMMAND_NOT_FOUND_OUTPUT_RE) — a Windows `bun run dev` on a missing binary
+ * exits 1. Callers treat a true here as an environment gap → skip, never FAIL.
+ */
+export declare function isCommandNotFound(status: number | null, output?: string): boolean;
 /**
  * The env a spawn site should pass so the resolved runner's script chain can
  * re-invoke it: base env with the runner's directory prepended to PATH. With no

package/dist/task/runner-resolve.js

@@ -83,6 +83,37 @@ export function resolveRunner(bin, opts = {}) {
     cache.set(bin, resolved);
     return resolved;
 }
+/**
+ * Output shapes a RUNNER emits when the command inside a script chain does not
+ * exist, on platforms where that is not reported as exit 127.
+ *
+ * 127 is a POSIX-SHELL convention: on Linux/macOS bun hands the script to
+ * /bin/sh, the shell prints `…: command not found` and exits 127, and the whole
+ * env-gap contract keys off that number. On Windows there is no such shell —
+ * bun runs the script in its own built-in shell, which reports the miss itself
+ * (`bun: command not found: X`) and exits **1**, indistinguishable by status
+ * alone from a real code fault. cmd.exe (9009) and PowerShell have their own
+ * wording. Recognising the shape restores one env-gap contract on all three.
+ *
+ * Deliberately narrow: only wordings a RUNNER/SHELL produces, never the bare
+ * phrase. A suite that prints "command not found" inside a failing assertion is
+ * a real FAIL and must stay one — the posix shape already travels as 127.
+ */
+export const COMMAND_NOT_FOUND_OUTPUT_RE = /\b(?:bun|npm|pnpm|yarn|node|deno): command not found:|is not recognized as an internal or external command|is not recognized as the name of a cmdlet/i;
+/**
+ * Did this command fail because the thing it tried to run does not exist here,
+ * rather than because the code is wrong? Exit 127 (POSIX shell) or 9009
+ * (cmd.exe) say so outright; anything else needs the runner's own wording (see
+ * COMMAND_NOT_FOUND_OUTPUT_RE) — a Windows `bun run dev` on a missing binary
+ * exits 1. Callers treat a true here as an environment gap → skip, never FAIL.
+ */
+export function isCommandNotFound(status, output = '') {
+    if (status === 127 || status === 9009)
+        return true;
+    if (status === null || status === 0)
+        return false;
+    return COMMAND_NOT_FOUND_OUTPUT_RE.test(output);
+}
 /**
  * The env a spawn site should pass so the resolved runner's script chain can
  * re-invoke it: base env with the runner's directory prepended to PATH. With no

package/dist/task/task-gates.d.ts

@@ -170,6 +170,13 @@ export interface GateDeps {
      * so the final gate must re-check and surface it. Best-effort; absent in tests.
      */
     recordRootCauseDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
+    /**
+     * Record a durable ENFORCE-KEPT debt (mx5 run 18 / nexttask 4): the enforce
+     * re-verify FAILED but the failing check names only files the ENFORCE COMMIT
+     * does not touch, so the edits were KEPT. The defect is still real and still in
+     * the shipped tree — keeping the work must not lose the finding.
+     */
+    recordEnforceKeptDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
     /**
      * Queue a scoped repair task for a root-caused defect. The gate DETECTS the
      * cause; only the /task-auto loop may mutate the plan, so the two are decoupled
@@ -184,12 +191,22 @@ export interface GateDeps {
      * this task's own fault, and only a file it never touched can be somebody
      * else's pre-existing bug. `worktree` = uncommitted changes (the pre-commit
      * verify site); `committed` = the files the task snapshot + the ENFORCE commit
-     * changed (the post-commit enforce site). `null` means UNKNOWN (git
-     * unavailable) and stands the whole channel down — inconclusive is never
-     * evidence, so an unreadable tree can only cost a repair task, never spawn a
-     * wrong one or wrongly keep a regression.
+     * changed (the post-commit enforce site); `enforce-commit` = the ENFORCE COMMIT
+     * ALONE, which is the only correct authorship question at the enforce
+     * differential (mx5 run 18 / nexttask 4 — that differential decides whether to
+     * discard the enforce commit, so what the TASK touched is irrelevant to it).
+     * `null` means UNKNOWN (git unavailable) and stands the whole channel down —
+     * inconclusive is never evidence, so an unreadable tree can only cost a repair
+     * task, never spawn a wrong one or wrongly keep a regression.
+     */
+    touchedFiles?: (cwd: string, scope: 'worktree' | 'committed' | 'enforce-commit') => Promise<string[] | null>;
+    /**
+     * Every path git tracks in the repo — used ONLY to resolve a bare file name a
+     * FAIL text names (`MyListings.spec.tsx:186`) to its repo path, so the defect
+     * can be attributed and a repair queued for it. Absent/null costs resolution,
+     * never changes a keep/revert verdict.
      */
-    touchedFiles?: (cwd: string, scope: 'worktree' | 'committed') => Promise<string[] | null>;
+    repoFiles?: (cwd: string) => Promise<string[] | null>;
     /** The task whose commit INTRODUCED a file (task-provenance.ts). Null for a
      *  file predating the run or any git error → unknown provenance. */
     introducedBy?: (cwd: string, rel: string) => Promise<string | null>;

package/dist/task/task-gates.js

@@ -1,7 +1,8 @@
 import { resolutionOptions, classifyResolutionAnswer } from './verify-resolution.js';
 import { SessionUI } from '../remote/bridge.js';
 import { isYoloMode, yoloVerifyResolution, YOLO_STAMP } from './yolo.js';
-import { findRepairCandidate } from './root-cause-repair.js';
+import { extractFailingCommand, findRepairCandidate, summariseDefect } from './root-cause-repair.js';
+import { attributeEnforceFailure } from './enforce-attribution.js';
 /**
  * How many times a verify FAIL may be auto-fixed UNATTENDED (the research
  * recommended AUTOFIX, so pi re-runs the impl turn without prompting) before the
@@ -455,8 +456,8 @@ export async function runGatesForTask(ctxIn, deps, p) {
                 const afterReason = after.reason ?? 'enforce re-verify failed';
                 // PRE-EXISTING-CAUSE KEEP PATH (mx5 run 14 item 5b). Both of run
                 // 14's enforce-reverts were this shape: the re-verify FAILed on
-                // TASK_0007's `test/teardown.ts` TRUNCATE bug — a file neither the
-                // task's work nor the enforce pass touched — and the differential
+                // TASK_0007's `test/teardown.ts` TRUNCATE bug — a file the enforce
+                // pass never touched — and the differential
                 // reverted enforce's edits anyway, destroying good work over a fault
                 // it did not cause AND leaving the actual cause unscheduled. When the
                 // FAIL is attributed to another task's untouched file, KEEP the edits
@@ -464,16 +465,82 @@ export async function runGatesForTask(ctxIn, deps, p) {
                 // unknown (git unavailable, no provenance, this task touched the file,
                 // an environment-blamed FAIL) falls through to the revert below —
                 // the conservative pre-existing behavior.
-                const rootCause = after.ok ? null : await routeRootCause(afterReason, '', 'committed');
+                //
+                // The scope is `enforce-commit`, NOT the task's own commit (mx5 run
+                // 18 / nexttask 4). This differential decides whether to discard the
+                // ENFORCE COMMIT, so the causal question is "could the enforce diff
+                // have caused this?" — asking what the TASK touched answers a
+                // question nobody at this seam is asking, and in run 18 it answered
+                // it in a way that destroyed a correct one-line change.
+                const rootCause = after.ok ? null : await routeRootCause(afterReason, '', 'enforce-commit');
+                // ATTRIBUTION PRE-FILTER (mx5 run 18 / nexttask 4). The root-cause
+                // channel above needs a blame CUE, a path-separator token and known
+                // provenance; run 18's FAIL text carried none of the three (it named
+                // a bare `MyListings.spec.tsx:186`), so it fell straight through to
+                // the revert. This filter asks only the mechanical question: does the
+                // failing check name any file the ENFORCE COMMIT touched? Disjoint =>
+                // the revert cannot repair the failure, so keep the edits and route
+                // the defect. Unknown diff, or a FAIL naming no file at all, still
+                // reverts — never keep on ignorance.
+                const attribution = !after.ok && !rootCause ?
+                    attributeEnforceFailure({
+                        failReason: afterReason,
+                        enforceTouched: (await deps.touchedFiles?.(p.cwd, 'enforce-commit')) ?? null,
+                        repoFiles: (await deps.repoFiles?.(p.cwd)) ?? null
+                    })
+                    : null;
                 if (!after.ok && rootCause) {
                     await rec(`enforce: re-verify FAILED (${afterReason.slice(0, 200)}) but the failure is attributed to a PRE-EXISTING defect in \`${rootCause.file}\` `
-                        + `(${rootCause.owner}'s file, untouched by this task and by the enforce pass) — edits KEPT, not reverted; repair task queued`);
+                        + `(${rootCause.owner}'s file, untouched by the ENFORCE COMMIT whose fate this differential decides) — edits KEPT, not reverted; repair task queued`);
                     active.ui.notify(`${p.tag}: guideline fixes on "${p.title}" re-verified red on a pre-existing defect in ${rootCause.file} (${rootCause.owner}'s file) — keeping the fixes, queued a repair task.`, 'warning');
                 }
+                else if (!after.ok && attribution?.verdict === 'keep') {
+                    // KEEP, mechanically justified: every file the failing check named
+                    // is outside the enforce diff (and outside its companions — a
+                    // touched file's own spec/story counts as inside). Discarding the
+                    // enforce commit could not repair this, and in run 18 doing so
+                    // cost a correct change that the final gate then re-made.
+                    await rec(`enforce: re-verify FAILED (${afterReason.slice(0, 200)}) but the failing check names only \`${attribution.named.join(', ')}\`, `
+                        + `which the ENFORCE COMMIT does not touch (its diff: ${attribution.enforceDiff.join(', ') || '—'}) — `
+                        + 'reverting it could not repair this, so the edits are KEPT and the defect is recorded as durable debt');
+                    // Keeping the edits must NOT lose the finding — that was mx5 run
+                    // 5's mistake. Same durability as the revert path; only the
+                    // disposition of the edits differs.
+                    await deps.recordEnforceKeptDebt?.(p.cwd, p.taskId, afterReason);
+                    // …and, when the named file is somebody else's committed work,
+                    // queue the scoped repair so something actually FIXES it.
+                    if (attribution.file && deps.introducedBy && deps.recordRepairCandidate) {
+                        try {
+                            const owner = await deps.introducedBy(p.cwd, attribution.file);
+                            const verifyCommand = extractFailingCommand(afterReason);
+                            if (owner && owner !== p.taskId) {
+                                await deps.recordRepairCandidate(p.cwd, {
+                                    file: attribution.file,
+                                    owner,
+                                    defect: summariseDefect(afterReason, attribution.file),
+                                    blamedTask: p.taskId,
+                                    ...(verifyCommand ? { verifyCommand } : {})
+                                });
+                                await rec(`root-cause: \`${attribution.file}\` is ${owner}'s file — scoped repair task queued`);
+                            }
+                        }
+                        catch {
+                            // queueing a repair must never break the gate sequence
+                        }
+                    }
+                    active.ui.notify(`${p.tag}: guideline fixes on "${p.title}" re-verified red on ${attribution.file ?? 'a file'} — outside the enforce diff, so keeping the fixes and recording the defect.`, 'warning');
+                }
                 else if (!after.ok) {
                     if (deps.revert)
                         await deps.revert(p.cwd);
-                    await rec(`enforce: fixes committed but re-verify FAILED (${(after.reason ?? 'now fails').slice(0, 200)}) — ${deps.revert ? 'REVERTED' : 'left in place (no revert available)'}`);
+                    await rec(`enforce: fixes committed but re-verify FAILED (${(after.reason ?? 'now fails').slice(0, 200)}) — ${deps.revert ? 'REVERTED' : 'left in place (no revert available)'}`
+                        // Why the attribution filter did NOT save the edits, so a
+                        // revert is explainable from the trail alone.
+                        + (attribution ?
+                            ` [attribution: ${attribution.why}${attribution.overlap ?
+                                ` — the check names \`${attribution.overlap.named}\`, the enforce diff touches \`${attribution.overlap.enforce}\``
+                                : ''}]`
+                            : ''));
                     // Persist the FAIL as a durable defect (mx5 run 10 item 3). The
                     // revert restores the tree the ORIGINAL verify already blessed, so
                     // this re-verify caught a defect that verify's earlier PASS missed —