@mjasnikovs/pi-task 0.26.0 → 0.28.0

package/dist/task/accept-debt.d.ts

@@ -6,6 +6,12 @@
  *     server entry point … the Hono server cannot be started"), so the terminal defect
  *     was FOUND and then erased by the very mechanism that found it. Persisted here so
  *     the final gate re-checks and surfaces it instead of letting it die with the revert.
+ *   - 'enforce-kept'   — the same enforce re-verify FAIL, but the failing check named
+ *     only files the ENFORCE COMMIT does not touch, so reverting that commit could not
+ *     possibly repair it (mx5 run 18 TASK_0024: a one-line paren removal in `Admin.tsx`
+ *     was reverted over a `MyListings.spec.tsx` CT failure it cannot reach, and the
+ *     final gate re-made the identical change 5 minutes later). The edits are KEPT and
+ *     the defect is recorded here — keeping the work must never mean losing the finding.
  *   - 'frozen-blocked' — a repo-health verify-FAIL whose only fix is an edit to a path
  *     THIS task's spec froze (mx5 run 12: `bun run lint` permanently red because the
  *     created files need a tsconfig registration every spec forbids). Cross-task
@@ -43,7 +49,7 @@
  *     (root-cause-repair.ts). Before this class existed the ledger recorded the same
  *     root cause twice and nothing ever scheduled a fix, so it survived ~24h.
  */
-export type DebtOrigin = 'accepted' | 'enforce-revert' | 'frozen-blocked' | 'cross-task-deletion' | 'yolo-accepted' | 'final-gate' | 'root-cause';
+export type DebtOrigin = 'accepted' | 'enforce-revert' | 'enforce-kept' | 'frozen-blocked' | 'cross-task-deletion' | 'yolo-accepted' | 'final-gate' | 'root-cause';
 /** One recorded defect: the task, why its VERIFY failed, and how it was recorded. */
 export interface AcceptDebt {
     taskId: string;
@@ -82,6 +88,14 @@ export declare function recordAcceptDebt(cwd: string, taskId: string, reason: st
  * rather than letting it die with the revert.
  */
 export declare function recordEnforceRevertDebt(cwd: string, taskId: string, reason: string): Promise<void>;
+/**
+ * Record an ENFORCE-KEPT debt (mx5 run 18 / nexttask 4): an enforce re-verify FAILED
+ * on a check whose named files are DISJOINT from the enforce commit's own diff, so
+ * the edits were kept — discarding them could not have repaired a failure they cannot
+ * reach. The defect is real and still in the shipped tree, so it is recorded with the
+ * same durability as an enforce-revert; only the disposition of the edits differs.
+ */
+export declare function recordEnforceKeptDebt(cwd: string, taskId: string, reason: string): Promise<void>;
 /**
  * Record a FROZEN-BLOCKED debt (mx5 run 12 / PROMPT 1 layer B): a repo-health FAIL
  * whose static findings can only be fixed by editing a path this task's spec froze —

package/dist/task/accept-debt.js

@@ -75,6 +75,7 @@ export function parseAcceptDebts(raw) {
             taskId: parts[0].trim(),
             reason: parts[1].trim(),
             ...((origin === 'enforce-revert'
+                || origin === 'enforce-kept'
                 || origin === 'frozen-blocked'
                 || origin === 'cross-task-deletion'
                 || origin === 'yolo-accepted'
@@ -147,6 +148,20 @@ export async function recordEnforceRevertDebt(cwd, taskId, reason) {
         origin: 'enforce-revert'
     });
 }
+/**
+ * Record an ENFORCE-KEPT debt (mx5 run 18 / nexttask 4): an enforce re-verify FAILED
+ * on a check whose named files are DISJOINT from the enforce commit's own diff, so
+ * the edits were kept — discarding them could not have repaired a failure they cannot
+ * reach. The defect is real and still in the shipped tree, so it is recorded with the
+ * same durability as an enforce-revert; only the disposition of the edits differs.
+ */
+export async function recordEnforceKeptDebt(cwd, taskId, reason) {
+    await appendDebt(cwd, {
+        taskId: taskId.trim(),
+        reason: normaliseReason(reason),
+        origin: 'enforce-kept'
+    });
+}
 /**
  * Record a FROZEN-BLOCKED debt (mx5 run 12 / PROMPT 1 layer B): a repo-health FAIL
  * whose static findings can only be fixed by editing a path this task's spec froze —
@@ -364,6 +379,9 @@ export function describeDebt(d) {
     if (d.origin === 'enforce-revert') {
         return 'enforce re-verify FAILED then the edits were reverted (defect indicts the ORIGINAL work, still shipped)';
     }
+    if (d.origin === 'enforce-kept') {
+        return 'enforce re-verify FAILED on a check the enforce diff cannot reach — the guideline edits were KEPT (reverting them could not fix it) and the defect indicts the ORIGINAL work, still shipped';
+    }
     if (d.origin === 'frozen-blocked') {
         return 'repo health blocked by a spec-frozen path (cross-task contradiction — no task may perform the fixing edit)';
     }

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

@@ -0,0 +1,128 @@
+/**
+ * enforce-attribution — decide whether an enforce-pass re-verify FAIL can possibly
+ * be the ENFORCE COMMIT's fault (mx5 run 18, nexttask 4).
+ *
+ * The failure class, measured. Run 18's TASK_0024 enforce commit `ee65661` was, in
+ * full, one line:
+ *
+ *     -  setApiError((usersData).error ?? 'Failed to load users')
+ *     +  setApiError(usersData.error ?? 'Failed to load users')
+ *
+ * The differential re-verify then FAILed on `MyListings.spec.tsx:186`, a Playwright
+ * CT file `Admin.tsx` cannot reach (CT bundles per story; the import graph never
+ * touches it), and the differential reverted the enforce commit anyway. The defect
+ * was real and PRE-EXISTING — `getByText('SOLD')` matched two elements because
+ * MOCK_LISTINGS already carries a sold row — and the final gate fixed it five
+ * minutes later, in the same commit that RE-MADE the identical paren change. Cost:
+ * one correct change destroyed, one permanent false verify-FAIL debt written
+ * against work that was fine, and the change re-made anyway.
+ *
+ * The mechanism was not broken; it was asked the wrong question. The root-cause
+ * channel (root-cause-repair.ts) attributed against `scope: 'committed'` — the
+ * TASK's own commit, which touched `MyListings.tsx` — concluded "this task touched
+ * the file", and fell through to the conservative revert. But at THIS seam the
+ * differential is deciding whether to discard the ENFORCE COMMIT. The causal
+ * question is therefore *"could the enforce diff have caused this?"*, never *"could
+ * the task have?"*: reverting the enforce commit can only ever repair damage the
+ * enforce commit did.
+ *
+ * So the filter here is mechanical and one-sided:
+ *
+ *   - the files the FAIL text NAMES are extracted (paths AND bare basenames — run
+ *     18's reason named `MyListings.spec.tsx:186`, which carries no separator and
+ *     is invisible to root-cause-repair.ts's path-token regex, a second reason
+ *     that incident could not be attributed);
+ *   - each is compared against the enforce commit's own file set, by path suffix
+ *     and by RELATED STEM (`Admin.tsx` ~ `Admin.spec.tsx` ~ `Admin.stories.tsx`),
+ *     so a regression in a touched file's own test still counts as overlap;
+ *   - DISJOINT ⇒ keep the edits and route the defect. Anything else — an unknown
+ *     enforce diff, a FAIL text naming no file at all, any overlap — reverts,
+ *     which is exactly the pre-existing behaviour. Never keep on ignorance.
+ *
+ * Keeping the edits must not mean losing the finding: the caller still records the
+ * debt and still queues the repair. Losing the finding was mx5 run 5's mistake.
+ *
+ * MEASURED COVERAGE, and it is the honest weakness of this filter. Live, 40 trials
+ * against the run-18 tree with a real verify child
+ * (`scripts/live-enforce-attribution-ab.ts`):
+ *
+ *   reachable arm (the enforce edit itself breaks `Admin.tsx`, ground truth REVERT)
+ *     20/20 FAILs named a resolvable file, 20/20 decided correctly — tsc prints the
+ *     path, so the regression case is fully covered.
+ *   disjoint arm (a deterministic failure in `MyListings.spec.tsx`, ground truth KEEP)
+ *     only 9/20 FAILs named a file at all. The other 11 named the UNIT — "The
+ *     MyListings component test \"edit link navigates…\" fails … expects 4 Edit links"
+ *     — with no path and no `.tsx` anywhere. Those 11 fall through to the revert.
+ *
+ * So this fires on roughly half of live disjoint failures and on the recorded run-18
+ * verdict (which did name `MyListings.spec.tsx:186`), and it was NEVER wrong: 29 of
+ * 29 extractable decisions matched ground truth across both arms. The arm-level
+ * verdict is still FAIL against the pre-registered ≥80%-extractable bar, and the
+ * shipped rule is deliberately the conservative half of that trade: a miss costs
+ * exactly the behaviour that shipped before, while a false KEEP would ship a real
+ * regression. A stem-widened extractor (accept a bare identifier matching a tracked
+ * file's stem) reaches 40/40 with 0 errors in the same data and is NOT wired — see
+ * VALIDATION-DEBT.md, it resolves prose nouns to files and its FP mode was never
+ * exercised.
+ */
+/**
+ * The comparable stem of a file name: the base name with its extension and any
+ * companion suffix removed, lowercased. `src/client/pages/Admin.tsx`,
+ * `Admin.spec.tsx` and `Admin.stories.tsx` all reduce to `admin`, which is what
+ * makes "the enforce diff broke that file's own test" count as an overlap rather
+ * than a disjoint (and therefore keepable) failure.
+ */
+export declare function fileStem(p: string): string;
+/**
+ * Every file a FAIL text names, de-duplicated, in first-seen order. Both shapes
+ * count: `src/server/routes/photos.ts` (path) and `MyListings.spec.tsx:186` (bare
+ * name plus a line number). An empty result is the signal that NOTHING can be
+ * attributed — the caller must then revert, never keep.
+ */
+export declare function extractFailingFiles(text: string): string[];
+/**
+ * Resolve a named file to a tracked repo path when the repo file list makes it
+ * unambiguous. `MyListings.spec.tsx` → `src/client/pages/MyListings.spec.tsx`, so
+ * the KEEP path can ask provenance about it and queue a real repair task. An
+ * ambiguous name (two tracked files share it) resolves to null: guessing which one
+ * the failure meant would put a wrong file in a repair task's title.
+ */
+export declare function resolveNamedFile(named: string, repoFiles: string[] | null): string | null;
+export interface EnforceAttributionInput {
+    /** The differential re-verify's FAIL reason, verbatim. */
+    failReason: string;
+    /**
+     * Repo-relative paths the ENFORCE COMMIT changed. `null` means unknown (git
+     * unavailable) and forces the pre-existing revert — inconclusive is never
+     * evidence for keeping a possible regression.
+     */
+    enforceTouched: string[] | null;
+    /** Tracked repo paths, for resolving bare file names. Optional; absent only
+     *  costs resolution, never changes the keep/revert verdict. */
+    repoFiles?: string[] | null;
+}
+/** Why the differential decided as it did — verbatim into the gate trail. */
+export type EnforceAttributionWhy = 'enforce-diff-unknown' | 'no-file-named' | 'named-file-in-enforce-diff' | 'disjoint-from-enforce-diff';
+export interface EnforceAttribution {
+    /** `keep` only on positive mechanical evidence that enforce cannot be at fault. */
+    verdict: 'keep' | 'revert';
+    why: EnforceAttributionWhy;
+    /** Files the FAIL text named (resolved to repo paths where unambiguous). */
+    named: string[];
+    /** The enforce commit's own file set, as compared against (for the trail). */
+    enforceDiff: string[];
+    /** On `revert`: the named file that overlaps the enforce diff. */
+    overlap?: {
+        named: string;
+        enforce: string;
+    };
+    /** On `keep`: the file to blame the defect on (the first named file). */
+    file?: string;
+}
+/**
+ * Could the ENFORCE COMMIT have caused this FAIL? `keep` iff the failure names at
+ * least one file and NO named file is the enforce diff's, or a companion of one.
+ * Every unknown returns `revert`, i.e. exactly the behaviour that shipped before
+ * this filter existed.
+ */
+export declare function attributeEnforceFailure(input: EnforceAttributionInput): EnforceAttribution;

package/dist/task/enforce-attribution.js

@@ -0,0 +1,213 @@
+/**
+ * enforce-attribution — decide whether an enforce-pass re-verify FAIL can possibly
+ * be the ENFORCE COMMIT's fault (mx5 run 18, nexttask 4).
+ *
+ * The failure class, measured. Run 18's TASK_0024 enforce commit `ee65661` was, in
+ * full, one line:
+ *
+ *     -  setApiError((usersData).error ?? 'Failed to load users')
+ *     +  setApiError(usersData.error ?? 'Failed to load users')
+ *
+ * The differential re-verify then FAILed on `MyListings.spec.tsx:186`, a Playwright
+ * CT file `Admin.tsx` cannot reach (CT bundles per story; the import graph never
+ * touches it), and the differential reverted the enforce commit anyway. The defect
+ * was real and PRE-EXISTING — `getByText('SOLD')` matched two elements because
+ * MOCK_LISTINGS already carries a sold row — and the final gate fixed it five
+ * minutes later, in the same commit that RE-MADE the identical paren change. Cost:
+ * one correct change destroyed, one permanent false verify-FAIL debt written
+ * against work that was fine, and the change re-made anyway.
+ *
+ * The mechanism was not broken; it was asked the wrong question. The root-cause
+ * channel (root-cause-repair.ts) attributed against `scope: 'committed'` — the
+ * TASK's own commit, which touched `MyListings.tsx` — concluded "this task touched
+ * the file", and fell through to the conservative revert. But at THIS seam the
+ * differential is deciding whether to discard the ENFORCE COMMIT. The causal
+ * question is therefore *"could the enforce diff have caused this?"*, never *"could
+ * the task have?"*: reverting the enforce commit can only ever repair damage the
+ * enforce commit did.
+ *
+ * So the filter here is mechanical and one-sided:
+ *
+ *   - the files the FAIL text NAMES are extracted (paths AND bare basenames — run
+ *     18's reason named `MyListings.spec.tsx:186`, which carries no separator and
+ *     is invisible to root-cause-repair.ts's path-token regex, a second reason
+ *     that incident could not be attributed);
+ *   - each is compared against the enforce commit's own file set, by path suffix
+ *     and by RELATED STEM (`Admin.tsx` ~ `Admin.spec.tsx` ~ `Admin.stories.tsx`),
+ *     so a regression in a touched file's own test still counts as overlap;
+ *   - DISJOINT ⇒ keep the edits and route the defect. Anything else — an unknown
+ *     enforce diff, a FAIL text naming no file at all, any overlap — reverts,
+ *     which is exactly the pre-existing behaviour. Never keep on ignorance.
+ *
+ * Keeping the edits must not mean losing the finding: the caller still records the
+ * debt and still queues the repair. Losing the finding was mx5 run 5's mistake.
+ *
+ * MEASURED COVERAGE, and it is the honest weakness of this filter. Live, 40 trials
+ * against the run-18 tree with a real verify child
+ * (`scripts/live-enforce-attribution-ab.ts`):
+ *
+ *   reachable arm (the enforce edit itself breaks `Admin.tsx`, ground truth REVERT)
+ *     20/20 FAILs named a resolvable file, 20/20 decided correctly — tsc prints the
+ *     path, so the regression case is fully covered.
+ *   disjoint arm (a deterministic failure in `MyListings.spec.tsx`, ground truth KEEP)
+ *     only 9/20 FAILs named a file at all. The other 11 named the UNIT — "The
+ *     MyListings component test \"edit link navigates…\" fails … expects 4 Edit links"
+ *     — with no path and no `.tsx` anywhere. Those 11 fall through to the revert.
+ *
+ * So this fires on roughly half of live disjoint failures and on the recorded run-18
+ * verdict (which did name `MyListings.spec.tsx:186`), and it was NEVER wrong: 29 of
+ * 29 extractable decisions matched ground truth across both arms. The arm-level
+ * verdict is still FAIL against the pre-registered ≥80%-extractable bar, and the
+ * shipped rule is deliberately the conservative half of that trade: a miss costs
+ * exactly the behaviour that shipped before, while a false KEEP would ship a real
+ * regression. A stem-widened extractor (accept a bare identifier matching a tracked
+ * file's stem) reaches 40/40 with 0 errors in the same data and is NOT wired — see
+ * VALIDATION-DEBT.md, it resolves prose nouns to files and its FP mode was never
+ * exercised.
+ */
+/** A path-like token: at least one separator, ending in a file name. */
+const PATH_TOKEN_RE = /(?:[\w.@~-]+\/)+[\w.@-]+\.\w+/g;
+/**
+ * A bare file name with a code-ish extension. Deliberately extension-gated: an
+ * ungated `\w+\.\w+` matches prose ("e.g.", "v1.2"), object access (`usersData.error`
+ * — which run 18's own enforce diff contains) and assertion chains
+ * (`toBeVisible()`), and every one of those would be a phantom "named file".
+ */
+const BARE_FILE_RE = /\b[\w@-]+(?:\.[\w@-]+)*\.(?:tsx?|jsx?|mtsx?|ctsx?|mjs|cjs|vue|svelte|astro|py|go|rs|rb|java|kt|kts|cs|php|swift|scala|c|h|cc|cpp|hpp|css|scss|sass|less|html?|json|jsonc|ya?ml|toml|sql|sh|bash|zsh|md|mdx|prisma|graphql|gql|proto|lock)\b/g;
+/** Line/column suffixes and decoration a reason wraps a file name in. */
+const TRAILING_POSITION_RE = /:(\d+)(?::(\d+))?$/;
+/** Suffixes that make a file a sibling of another (test/story/type companions). */
+const COMPANION_SUFFIXES = ['.spec', '.test', '.stories', '.story', '.d', '.min'];
+/** A pathological reason cannot make this scan unbounded. */
+const MAX_NAMED = 24;
+/** Strip `./`, leading slashes and surrounding whitespace. */
+function normalisePath(p) {
+    return p.replace(/^\.\//, '').replace(/^\/+/, '').trim();
+}
+/** The last path segment of a repo-relative path. */
+function basename(p) {
+    const i = p.lastIndexOf('/');
+    return i < 0 ? p : p.slice(i + 1);
+}
+/**
+ * The comparable stem of a file name: the base name with its extension and any
+ * companion suffix removed, lowercased. `src/client/pages/Admin.tsx`,
+ * `Admin.spec.tsx` and `Admin.stories.tsx` all reduce to `admin`, which is what
+ * makes "the enforce diff broke that file's own test" count as an overlap rather
+ * than a disjoint (and therefore keepable) failure.
+ */
+export function fileStem(p) {
+    let name = basename(normalisePath(p));
+    const dot = name.lastIndexOf('.');
+    if (dot > 0)
+        name = name.slice(0, dot);
+    for (const suffix of COMPANION_SUFFIXES) {
+        if (name.toLowerCase().endsWith(suffix)) {
+            name = name.slice(0, name.length - suffix.length);
+            break;
+        }
+    }
+    return name.toLowerCase();
+}
+/**
+ * Every file a FAIL text names, de-duplicated, in first-seen order. Both shapes
+ * count: `src/server/routes/photos.ts` (path) and `MyListings.spec.tsx:186` (bare
+ * name plus a line number). An empty result is the signal that NOTHING can be
+ * attributed — the caller must then revert, never keep.
+ */
+export function extractFailingFiles(text) {
+    if (text.trim().length === 0)
+        return [];
+    const out = [];
+    const seen = new Set();
+    const add = (raw) => {
+        const cleaned = normalisePath(raw.replace(TRAILING_POSITION_RE, ''));
+        if (cleaned.length === 0)
+            return;
+        const key = cleaned.toLowerCase();
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        if (out.length < MAX_NAMED)
+            out.push(cleaned);
+    };
+    // Paths first so `src/a/B.ts` is recorded as the path, not as the bare `B.ts`
+    // its own tail also matches.
+    const covered = [];
+    for (const m of text.matchAll(PATH_TOKEN_RE)) {
+        covered.push([m.index, m.index + m[0].length]);
+        add(withPosition(text, m.index + m[0].length, m[0]));
+    }
+    for (const m of text.matchAll(BARE_FILE_RE)) {
+        const start = m.index;
+        if (covered.some(([s, e]) => start >= s && start < e))
+            continue;
+        add(withPosition(text, start + m[0].length, m[0]));
+    }
+    return out;
+}
+/** Re-attach a `:line[:col]` suffix that follows a match, so it can be stripped
+ *  uniformly (and so `a.ts:1` and `a.ts` collapse to one named file). */
+function withPosition(text, end, token) {
+    const m = /^:\d+(?::\d+)?/.exec(text.slice(end));
+    return m ? token + m[0] : token;
+}
+/** Two repo-relative paths that denote the same file (suffix-compared). */
+function samePath(a, b) {
+    const x = normalisePath(a).toLowerCase();
+    const y = normalisePath(b).toLowerCase();
+    return x === y || x.endsWith(`/${y}`) || y.endsWith(`/${x}`);
+}
+/**
+ * Resolve a named file to a tracked repo path when the repo file list makes it
+ * unambiguous. `MyListings.spec.tsx` → `src/client/pages/MyListings.spec.tsx`, so
+ * the KEEP path can ask provenance about it and queue a real repair task. An
+ * ambiguous name (two tracked files share it) resolves to null: guessing which one
+ * the failure meant would put a wrong file in a repair task's title.
+ */
+export function resolveNamedFile(named, repoFiles) {
+    if (!repoFiles || repoFiles.length === 0)
+        return null;
+    const matches = repoFiles.filter(f => samePath(f, named));
+    if (matches.length === 1)
+        return normalisePath(matches[0]);
+    // Exact-path hit wins over the suffix fan-out (a repo may track both
+    // `a/x.ts` and `b/a/x.ts`).
+    const exact = repoFiles.filter(f => normalisePath(f).toLowerCase() === normalisePath(named).toLowerCase());
+    return exact.length === 1 ? normalisePath(exact[0]) : null;
+}
+/**
+ * Could the ENFORCE COMMIT have caused this FAIL? `keep` iff the failure names at
+ * least one file and NO named file is the enforce diff's, or a companion of one.
+ * Every unknown returns `revert`, i.e. exactly the behaviour that shipped before
+ * this filter existed.
+ */
+export function attributeEnforceFailure(input) {
+    const enforce = (input.enforceTouched ?? []).map(normalisePath).filter(f => f.length > 0);
+    if (input.enforceTouched === null || enforce.length === 0) {
+        return { verdict: 'revert', why: 'enforce-diff-unknown', named: [], enforceDiff: enforce };
+    }
+    const raw = extractFailingFiles(input.failReason);
+    const named = raw.map(n => resolveNamedFile(n, input.repoFiles ?? null) ?? n);
+    if (named.length === 0)
+        return { verdict: 'revert', why: 'no-file-named', named, enforceDiff: enforce };
+    for (const n of named) {
+        const hit = enforce.find(e => samePath(e, n) || fileStem(e) === fileStem(n));
+        if (hit) {
+            return {
+                verdict: 'revert',
+                why: 'named-file-in-enforce-diff',
+                named,
+                enforceDiff: enforce,
+                overlap: { named: n, enforce: hit }
+            };
+        }
+    }
+    return {
+        verdict: 'keep',
+        why: 'disjoint-from-enforce-diff',
+        named,
+        enforceDiff: enforce,
+        file: named[0]
+    };
+}

package/dist/task/final-gate.d.ts

@@ -305,7 +305,9 @@ export declare function preferredDeclaredPort(cwd: string): Promise<number | nul
  * needs no socket probe, so run 14's original true positive (a `--hot` runtime
  * pinning a crashed app) stays reportable wherever the tooling exists.
  *
- * Env-gap contract as everywhere: spawn error (ENOENT) or exit 127 → skip.
+ * Env-gap contract as everywhere: spawn error (ENOENT) or a command-not-found
+ * inside the chain (exit 127, or the runner's own wording where the platform
+ * reports it that way — see isCommandNotFound) → skip.
  */
 export declare function runBootCheck(cwd: string, [bin, args]: HealthCommand, graceMs?: number, opts?: {
     expectServer?: boolean;

package/dist/task/final-gate.js

@@ -55,7 +55,7 @@ import { readDeclaredScripts, missingDeclaredScripts, runnableDeclaredScripts }
 import { readEnvNotes, parseEnvNotes, isExcuseNote } from './env-notes.js';
 import { runRenderCheck } from './render-check.js';
 import { collectProjectEnv, pinnedLocalPort, runDeepRenderCheck } from './deep-render-check.js';
-import { resolveRunner, runnerEnv } from './runner-resolve.js';
+import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
 import { taskThatIntroduced } from './task-provenance.js';
 import { findDanglingArtifacts, danglingGateFailureText } from './artifact-closure.js';
 import { findMissingServeEntry, serveEntryGateFailureText } from './serve-entry.js';
@@ -693,7 +693,9 @@ function holderIsOurs(command, boot) {
  * needs no socket probe, so run 14's original true positive (a `--hot` runtime
  * pinning a crashed app) stays reportable wherever the tooling exists.
  *
- * Env-gap contract as everywhere: spawn error (ENOENT) or exit 127 → skip.
+ * Env-gap contract as everywhere: spawn error (ENOENT) or a command-not-found
+ * inside the chain (exit 127, or the runner's own wording where the platform
+ * reports it that way — see isCommandNotFound) → skip.
  */
 export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}) {
     const expectServer = (opts.expectServer ?? false) && process.platform !== 'win32';
@@ -881,7 +883,11 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
                 }
                 return settle({ outcome: 'pass' });
             }
-            if (status === 127 || (status === null && signal === null)) {
+            // Command-not-found inside the boot chain — 127 on a posix shell, or
+            // the runner's own wording where it isn't (Windows bun exits 1). Either
+            // way the boot never RAN, so it is an environment gap, not an app fault.
+            if (isCommandNotFound(status, `${out}\n${err}`)
+                || (status === null && signal === null)) {
                 return settle({ outcome: 'skip' });
             }
             const what = status !== null ? `exited ${status}` : `was killed by ${signal}`;
@@ -967,10 +973,12 @@ function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe) {
     });
     if (r.error)
         return { outcome: 'skip', spawnFailed: true };
-    if (r.status === null || r.status === 127)
+    if (r.status === null)
         return { outcome: 'skip', spawnFailed: false };
     if (r.status !== 0) {
         const output = `${r.stdout ?? ''}\n${r.stderr ?? ''}`;
+        if (isCommandNotFound(r.status, output))
+            return { outcome: 'skip', spawnFailed: false };
         if (ENV_GAP_OUTPUT_RE.test(output))
             return { outcome: 'skip', spawnFailed: false };
         if (extraGapRe?.test(output))

package/dist/task/gate-deps.js

@@ -22,7 +22,7 @@ import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
 import { readEnvNotes, appendEnvNotes } from './env-notes.js';
 import { readContracts } from './contracts.js';
-import { recordAcceptDebt, recordEnforceRevertDebt, recordFrozenBlockedDebt, recordCrossTaskDeletionDebt, recordYoloAcceptDebt, recordRootCauseDebt } from './accept-debt.js';
+import { recordAcceptDebt, recordEnforceKeptDebt, recordEnforceRevertDebt, recordFrozenBlockedDebt, recordCrossTaskDeletionDebt, recordYoloAcceptDebt, recordRootCauseDebt } from './accept-debt.js';
 import { recordRepairCandidate } from './root-cause-repair.js';
 import { runRepoHealthCheck } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels } from './final-gate.js';
@@ -400,6 +400,14 @@ export function buildGateDeps(params) {
                     // (a healthy endpoint reads as proof of life).
                     streamInactivityMs: getConfig().streamInactivityMs,
                     loop: { pathThreshold: Number.POSITIVE_INFINITY },
+                    // A discarded attempt is otherwise invisible here too: the
+                    // returned exitCode/text describe the FINAL attempt, so a
+                    // gate child that burned two attempts and its wall clock
+                    // reads exactly like one that ran clean.
+                    onRestart: rs => log(`=== ${kind} RESTART (attempt ${rs.attempt} discarded)`
+                        + ` reason=${rs.reason} wall=${rs.wallMs}ms`
+                        + (rs.detail ? ` — ${rs.detail}` : '')
+                        + ' ==='),
                     onLine: line => {
                         // `lastLine` feeds the LIVE status widget and is not
                         // logging — it stays outside the gate, or a quiet
@@ -469,6 +477,10 @@ export function buildGateDeps(params) {
         recordAcceptDebt: (cwd2, taskId, reason) => recordAcceptDebt(cwd2, taskId, reason),
         recordYoloAcceptDebt: (cwd2, taskId, reason) => recordYoloAcceptDebt(cwd2, taskId, reason),
         recordEnforceRevertDebt: (cwd2, taskId, reason) => recordEnforceRevertDebt(cwd2, taskId, reason),
+        // Same ledger, the KEPT disposition (mx5 run 18 / nexttask 4): the enforce
+        // re-verify FAILed on a check the enforce diff cannot reach, so the edits
+        // stayed and only the defect was recorded.
+        recordEnforceKeptDebt: (cwd2, taskId, reason) => recordEnforceKeptDebt(cwd2, taskId, reason),
         // Durable cross-task-contradiction ledger (PROMPT 1 layer B): a repo-health
         // FAIL whose only fix is an edit to a path this task's spec froze — recorded
         // when the gate loop routes it to the picker, re-checked by the final gate.
@@ -485,6 +497,23 @@ export function buildGateDeps(params) {
         recordRepairCandidate: (cwd2, candidate) => recordRepairCandidate(cwd2, candidate),
         // file → introducing task, the provenance half of the discriminator.
         introducedBy: (cwd2, rel) => Promise.resolve(taskThatIntroduced(cwd2, rel)),
+        // Tracked paths, used only to resolve a bare file name a FAIL text names
+        // (`MyListings.spec.tsx:186`) to its repo path. A git fault returns null,
+        // which costs resolution and nothing else.
+        repoFiles: async (cwd2) => {
+            try {
+                const r = await git(cwd2, ['ls-files'], signal);
+                if (r.exitCode !== 0)
+                    return null;
+                return r.stdout
+                    .split('\n')
+                    .map(l => l.trim())
+                    .filter(l => l.length > 0);
+            }
+            catch {
+                return null;
+            }
+        },
         // The authorship half: which files THIS task's work touched. `worktree` is
         // the pre-commit verify site (uncommitted changes); `committed` is the
         // post-commit enforce site, where the task snapshot and the ENFORCE commit
@@ -499,7 +528,18 @@ export function buildGateDeps(params) {
                     const c = parseTreeChanges(r.stdout);
                     return [...c.modified, ...c.added, ...c.deleted];
                 }
-                const r = await git(cwd2, ['log', '-n', '2', '--name-only', '--format=', 'HEAD'], signal);
+                // `enforce-commit` is HEAD ALONE — at the enforce differential HEAD is
+                // the ENFORCE commit, and that commit's own diff is the only file set
+                // that can answer "could reverting this repair the failure?" (mx5 run
+                // 18 / nexttask 4).
+                const r = await git(cwd2, [
+                    'log',
+                    '-n',
+                    scope === 'enforce-commit' ? '1' : '2',
+                    '--name-only',
+                    '--format=',
+                    'HEAD'
+                ], signal);
                 if (r.exitCode !== 0)
                     return null;
                 return r.stdout
@@ -586,6 +626,12 @@ export function buildGateDeps(params) {
                             // file (which IS this pass's job) never trips — only a
                             // literally-identical call repeated past threshold does.
                             loop: { pathThreshold: Number.POSITIVE_INFINITY },
+                            // Same reasoning as the gate child: without this a
+                            // discarded attempt leaves no trace anywhere.
+                            onRestart: rs => logEnforce(`=== enforce RESTART (attempt ${rs.attempt} discarded)`
+                                + ` reason=${rs.reason} wall=${rs.wallMs}ms`
+                                + (rs.detail ? ` — ${rs.detail}` : '')
+                                + ' ==='),
                             onLine: line => {
                                 // `lastLine` drives the live widget, not the trail.
                                 lastLine = line;