@holmes-lab/holmes-kit 0.19.0 → 0.19.3

package/dist/holmes/mcp/maintenance-evidence.js

@@ -39,6 +39,8 @@ exports.artifactFrom = artifactFrom;
 exports.writeArtifact = writeArtifact;
 exports.readArtifacts = readArtifacts;
 exports.recordOutcome = recordOutcome;
+exports.openArtifacts = openArtifacts;
+exports.closeOpenArtifacts = closeOpenArtifacts;
 exports.computeCalibration = computeCalibration;
 // @implements A-SPEC-271
 // @implements A-SPEC-268
@@ -170,6 +172,17 @@ function readArtifacts(dir) {
 /**
  * Attach what actually happened to a prediction that was actually made. An unknown digest is
  * refused: inventing the prediction alongside the outcome would let the record score itself.
+ *
+ * @implements A-SPEC-578.6
+ * MERGES into any outcome already there. It used to REPLACE, and the defect was found by following
+ * this repository's own instruction: A-SPEC-578.4 made `test_run` attach the 12 files a slice
+ * actually changed, AGENTS.md then said "call maintenance_outcome yourself only to add a judged
+ * classification" — and that call left `actualFiles: []`. The documented workflow destroyed the
+ * data it existed to complete.
+ *
+ * Omission and erasure are DIFFERENT ACTS: a field left out keeps its value, a field given as an
+ * empty array is cleared. Without the second, a wrong record could never be corrected; without the
+ * first, completing a record destroys it.
  */
 function recordOutcome(dir, digest, outcome, recordedAt) {
     const file = path.join(dir, digestFilename(digest));
@@ -177,19 +190,73 @@ function recordOutcome(dir, digest, outcome, recordedAt) {
         throw new Error(`Refusing to record an outcome for an unknown analysis digest: ${digest}`);
     }
     const artifact = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const prev = artifact.outcome;
+    const merged = (given, before) => given === undefined ? (before ?? []) : sortedUnique(given);
+    const classification = outcome.actualClassification ?? prev?.actualClassification;
     const updated = {
         ...artifact,
         outcome: {
             recordedAt,
-            actualFiles: sortedUnique(outcome.actualFiles ?? []),
-            actualSymbols: sortedUnique(outcome.actualSymbols ?? []),
-            actualTests: sortedUnique(outcome.actualTests ?? []),
-            ...(outcome.actualClassification ? { actualClassification: outcome.actualClassification } : {}),
+            actualFiles: merged(outcome.actualFiles, prev?.actualFiles),
+            actualSymbols: merged(outcome.actualSymbols, prev?.actualSymbols),
+            actualTests: merged(outcome.actualTests, prev?.actualTests),
+            ...(classification ? { actualClassification: classification } : {}),
         },
     };
     writeAtomic(file, `${JSON.stringify(updated, null, 2)}\n`);
     return updated;
 }
+// @implements A-SPEC-578.4
+/**
+ * Predictions still waiting to be scored — the loop's missing second half.
+ *
+ * `since` bounds the window: an analysis recorded before the previous evidence run belonged to a
+ * previous slice, and attributing today's changes to it would be contamination rather than
+ * measurement. The boundary is EXCLUSIVE (`> since`) because the previous run already saw that
+ * instant.
+ */
+function openArtifacts(dir, since) {
+    const { artifacts } = readArtifacts(dir);
+    return artifacts.filter((a) => {
+        if (a.outcome !== undefined)
+            return false;
+        if (since === undefined)
+            return true;
+        const t = Date.parse(a.recordedAt);
+        const s = Date.parse(since);
+        return !Number.isFinite(t) || !Number.isFinite(s) ? true : t > s;
+    });
+}
+/**
+ * @implements A-SPEC-578.4
+ * Attach what a slice ACTUALLY touched to the predictions it made.
+ *
+ * Measured 2026-09-09: `maintenance_calibration` had reported `n:0, artifacts:0` since the loop was
+ * built, because `maintenance_analyze({persist:true})` is instructed (AGENTS.md step 3) while
+ * `maintenance_outcome` is instructed nowhere at all. The write path was healthy the whole time —
+ * one call produced an artifact immediately. What was missing was the call.
+ *
+ * TWO REFUSALS make this a measurement rather than a self-graded exam:
+ *  - `actualClassification` is never filled in. That is a judgement, and a loop that supplies its
+ *    own judgement scores itself; the bins stay `insufficient-data` and only the objective half —
+ *    file-level false positives and negatives — accrues.
+ *  - An empty change set closes nothing. Attributing "nothing changed" would turn every prediction
+ *    into a false positive: a measurement of nothing, recorded as a failure of everything.
+ */
+function closeOpenArtifacts(dir, actual, recordedAt, since) {
+    const files = Array.isArray(actual?.files) ? actual.files : [];
+    if (files.length === 0)
+        return { closed: [] };
+    const closed = [];
+    for (const a of openArtifacts(dir, since)) {
+        try {
+            recordOutcome(dir, a.digest, { actualFiles: files }, recordedAt);
+            closed.push(a.digest);
+        }
+        catch { /* an artifact we cannot write is not a reason to abandon the rest */ }
+    }
+    return { closed };
+}
 const BIN_EDGES = [0, 0.2, 0.4, 0.6, 0.8, 1];
 /**
  * Reliability bins plus a Brier score. `minSamples` is the honesty knob: below it a bin reports

package/dist/holmes/project/install-scripts-policy.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @implements A-SPEC-579
+ * npm 12 blocks dependency install scripts unless the ROOT package.json's `allowScripts` covers
+ * them ("Install commands silently skip lifecycle scripts for any dependency that does not have a
+ * matching entry" — npm docs, cli/v12/commands/npm-install-scripts). Measured 2026-09-09 on
+ * Windows (npm 12.0.1, Node 24.19.0): `npm ci` succeeded, nine install scripts were skipped, and
+ * better-sqlite3 had no binary — while the eight tree-sitter packages still loaded, because their
+ * `node-gyp-build` runtime loader finds `prebuilds/<platform>-<arch>` without the script ever
+ * running. So the minimum approval this repository needs is ONE package, pinned to the lockfile
+ * version so a dependency bump forces a fresh review.
+ *
+ * This module is the pure re-statement of that rule: no I/O, no process, no platform — the same
+ * verdict on every OS, shared by the test that pins package.json and by doctor (A-SPEC-580).
+ */
+/** Dependencies whose install script must actually RUN for the module to load. */
+export declare const NATIVE_INSTALL_SCRIPT_DEPS: readonly ["better-sqlite3"];
+/** Native dependencies that ship prebuilds and load with the script blocked (measured). */
+export declare const PREBUILT_NATIVE_DEPS: readonly ["tree-sitter", "tree-sitter-typescript", "tree-sitter-python", "tree-sitter-c-sharp", "tree-sitter-java", "tree-sitter-go", "tree-sitter-rust", "tree-sitter-cpp"];
+export type AllowScripts = Record<string, boolean>;
+export type Coverage = 'approved-pinned' | 'approved-unpinned' | 'denied' | 'uncovered';
+export interface LockLike {
+    packages?: Record<string, {
+        version?: string;
+        hasInstallScript?: boolean;
+    }>;
+}
+export type PolicyProblem = {
+    kind: 'reapproval-required';
+    name: string;
+    lockVersion: string;
+    approved: string[];
+    fix: string;
+} | {
+    kind: 'unpinned';
+    name: string;
+    fix: string;
+} | {
+    kind: 'denied';
+    name: string;
+    fix: string;
+} | {
+    kind: 'beyond-minimum';
+    key: string;
+    fix: string;
+} | {
+    kind: 'missing-from-lock';
+    name: string;
+};
+/** The exact command npm 12 documents for a pinned approval. */
+export declare function approveCommand(name: string, version: string, npmBin?: string): string;
+/**
+ * How `allowScripts` covers one package at one version, under npm 12's rules: a pinned `true`
+ * covers that version only, a bare `true` covers every version, and a `false` on either key is
+ * a denial that survives any approval (npm: deny "survives `approve --all`").
+ */
+export declare function allowScriptsCoverage(allow: AllowScripts | undefined, name: string, version: string): Coverage;
+/**
+ * What `npm install-scripts ls` would list: every lock entry with an install script that
+ * `allowScripts` does not approve. The root entry (`""`) is the project itself, never a dependency.
+ */
+export declare function blockedInstallScripts(lock: LockLike, allow: AllowScripts | undefined): {
+    name: string;
+    version: string;
+}[];
+/**
+ * This repository's policy, judged: every script-requiring dependency approved AND pinned to the
+ * lock version, and nothing else approved. Pure; never throws.
+ */
+export declare function policyVerdict(pkg: {
+    allowScripts?: AllowScripts;
+}, lock: LockLike, opts?: {
+    npmBin?: string;
+}): {
+    ok: boolean;
+    problems: PolicyProblem[];
+};

package/dist/holmes/project/install-scripts-policy.js

@@ -0,0 +1,131 @@
+"use strict";
+// @implements A-SPEC-579
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREBUILT_NATIVE_DEPS = exports.NATIVE_INSTALL_SCRIPT_DEPS = void 0;
+exports.approveCommand = approveCommand;
+exports.allowScriptsCoverage = allowScriptsCoverage;
+exports.blockedInstallScripts = blockedInstallScripts;
+exports.policyVerdict = policyVerdict;
+/**
+ * @implements A-SPEC-579
+ * npm 12 blocks dependency install scripts unless the ROOT package.json's `allowScripts` covers
+ * them ("Install commands silently skip lifecycle scripts for any dependency that does not have a
+ * matching entry" — npm docs, cli/v12/commands/npm-install-scripts). Measured 2026-09-09 on
+ * Windows (npm 12.0.1, Node 24.19.0): `npm ci` succeeded, nine install scripts were skipped, and
+ * better-sqlite3 had no binary — while the eight tree-sitter packages still loaded, because their
+ * `node-gyp-build` runtime loader finds `prebuilds/<platform>-<arch>` without the script ever
+ * running. So the minimum approval this repository needs is ONE package, pinned to the lockfile
+ * version so a dependency bump forces a fresh review.
+ *
+ * This module is the pure re-statement of that rule: no I/O, no process, no platform — the same
+ * verdict on every OS, shared by the test that pins package.json and by doctor (A-SPEC-580).
+ */
+/** Dependencies whose install script must actually RUN for the module to load. */
+exports.NATIVE_INSTALL_SCRIPT_DEPS = ['better-sqlite3'];
+/** Native dependencies that ship prebuilds and load with the script blocked (measured). */
+exports.PREBUILT_NATIVE_DEPS = [
+    'tree-sitter', 'tree-sitter-typescript', 'tree-sitter-python', 'tree-sitter-c-sharp',
+    'tree-sitter-java', 'tree-sitter-go', 'tree-sitter-rust', 'tree-sitter-cpp',
+];
+/** The exact command npm 12 documents for a pinned approval. */
+function approveCommand(name, version, npmBin = 'npm') {
+    return `${npmBin} install-scripts approve ${name}@${version}`;
+}
+/** Split an allowScripts key into its package name and optional pinned version (scopes kept). */
+function splitKey(key) {
+    const at = key.lastIndexOf('@');
+    if (at <= 0)
+        return { name: key }; // '@scope/pkg' or 'pkg'
+    return { name: key.slice(0, at), version: key.slice(at + 1) };
+}
+/**
+ * How `allowScripts` covers one package at one version, under npm 12's rules: a pinned `true`
+ * covers that version only, a bare `true` covers every version, and a `false` on either key is
+ * a denial that survives any approval (npm: deny "survives `approve --all`").
+ */
+function allowScriptsCoverage(allow, name, version) {
+    if (!allow)
+        return 'uncovered';
+    const pinned = allow[`${name}@${version}`];
+    const bare = allow[name];
+    if (pinned === false || bare === false)
+        return 'denied';
+    if (pinned === true)
+        return 'approved-pinned';
+    if (bare === true)
+        return 'approved-unpinned';
+    return 'uncovered';
+}
+/** The package name of a lockfile `packages` key: the segment after its LAST `node_modules/`. */
+function lockEntryName(key) {
+    const idx = key.lastIndexOf('node_modules/');
+    if (idx < 0)
+        return null;
+    const name = key.slice(idx + 'node_modules/'.length);
+    return name === '' ? null : name;
+}
+/**
+ * What `npm install-scripts ls` would list: every lock entry with an install script that
+ * `allowScripts` does not approve. The root entry (`""`) is the project itself, never a dependency.
+ */
+function blockedInstallScripts(lock, allow) {
+    const out = [];
+    for (const [key, entry] of Object.entries(lock.packages ?? {})) {
+        if (!entry?.hasInstallScript)
+            continue;
+        const name = lockEntryName(key);
+        if (name === null)
+            continue;
+        const version = entry.version ?? '';
+        const cov = allowScriptsCoverage(allow, name, version);
+        if (cov !== 'approved-pinned' && cov !== 'approved-unpinned')
+            out.push({ name, version });
+    }
+    return out;
+}
+/** The top-level lock version of a dependency (`node_modules/<name>`), if present. */
+function lockVersionOf(lock, name) {
+    return lock.packages?.[`node_modules/${name}`]?.version;
+}
+/**
+ * This repository's policy, judged: every script-requiring dependency approved AND pinned to the
+ * lock version, and nothing else approved. Pure; never throws.
+ */
+function policyVerdict(pkg, lock, opts) {
+    const npmBin = opts?.npmBin ?? 'npm';
+    const allow = pkg.allowScripts;
+    const problems = [];
+    for (const name of exports.NATIVE_INSTALL_SCRIPT_DEPS) {
+        const lockVersion = lockVersionOf(lock, name);
+        if (lockVersion === undefined) {
+            problems.push({ kind: 'missing-from-lock', name });
+            continue;
+        }
+        const fix = approveCommand(name, lockVersion, npmBin);
+        switch (allowScriptsCoverage(allow, name, lockVersion)) {
+            case 'approved-pinned': break;
+            case 'approved-unpinned':
+                problems.push({ kind: 'unpinned', name, fix });
+                break;
+            case 'denied':
+                problems.push({ kind: 'denied', name, fix });
+                break;
+            case 'uncovered': {
+                const approved = Object.entries(allow ?? {})
+                    .filter(([k, v]) => v === true && splitKey(k).name === name && splitKey(k).version !== undefined)
+                    .map(([k]) => splitKey(k).version);
+                problems.push({ kind: 'reapproval-required', name, lockVersion, approved, fix });
+                break;
+            }
+        }
+    }
+    const minimum = new Set(exports.NATIVE_INSTALL_SCRIPT_DEPS);
+    for (const [key, value] of Object.entries(allow ?? {})) {
+        if (value !== true)
+            continue; // a denial is never "beyond" the minimum
+        if (!minimum.has(splitKey(key).name)) {
+            problems.push({ kind: 'beyond-minimum', key, fix: `Remove "${key}" from allowScripts in package.json — it loads from its shipped prebuilds without an install script.` });
+        }
+    }
+    return { ok: problems.length === 0, problems };
+}

package/dist/holmes/project/npx-bin.d.ts

@@ -8,3 +8,9 @@
  * platform must never flip a POSIX hint to a Windows-only form.
  */
 export declare function npxBin(platform?: string): string;
+/**
+ * @implements A-SPEC-580
+ * The npm twin: the recovery commands doctor emits (`npm install-scripts approve`, `npm rebuild`)
+ * hit the same `.ps1` shim on Windows (measured 2026-09-09: npm.ps1 blocked, npm.cmd runs).
+ */
+export declare function npmBin(platform?: string): string;

package/dist/holmes/project/npx-bin.js

@@ -1,7 +1,9 @@
 "use strict";
 // @implements A-SPEC-542.1
+// @implements A-SPEC-580
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.npxBin = npxBin;
+exports.npmBin = npmBin;
 /**
  * @implements A-SPEC-542.1
  * The npx binary an OPERATOR can actually run on the platform this process runs on — which is the
@@ -14,3 +16,11 @@ exports.npxBin = npxBin;
 function npxBin(platform = process.platform) {
     return platform === 'win32' ? 'npx.cmd' : 'npx';
 }
+/**
+ * @implements A-SPEC-580
+ * The npm twin: the recovery commands doctor emits (`npm install-scripts approve`, `npm rebuild`)
+ * hit the same `.ps1` shim on Windows (measured 2026-09-09: npm.ps1 blocked, npm.cmd runs).
+ */
+function npmBin(platform = process.platform) {
+    return platform === 'win32' ? 'npm.cmd' : 'npm';
+}

package/dist/holmes/review/failed-test-names.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The names behind a red release gate.
+ *
+ * Measured 2026-09-10: `npm publish` refused with "스위트가 붉습니다" and nothing else, and finding
+ * out which test had failed cost two more full-suite runs. `test_run` learned to name its failures
+ * in REQ-577; the release gate had not. A gate that says "red" without saying what is a gate that
+ * makes the next person guess.
+ */
+/** How many names a refusal lists before it counts the rest. */
+export declare const FAILED_NAME_CAP = 10;
+/**
+ * Pull the failing test names out of a jest run's output.
+ *
+ * PURE, and forgiving: output it cannot read yields an empty list so the caller keeps its existing
+ * refusal rather than replacing a working message with an empty one. Jest prints the summary block
+ * twice on some configurations, so names are de-duplicated — the same failure listed twice is one
+ * failure.
+ */
+export declare function failedTestNames(output: string): string[];

package/dist/holmes/review/failed-test-names.js

@@ -0,0 +1,43 @@
+"use strict";
+// @implements A-SPEC-582.1
+/**
+ * The names behind a red release gate.
+ *
+ * Measured 2026-09-10: `npm publish` refused with "스위트가 붉습니다" and nothing else, and finding
+ * out which test had failed cost two more full-suite runs. `test_run` learned to name its failures
+ * in REQ-577; the release gate had not. A gate that says "red" without saying what is a gate that
+ * makes the next person guess.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAILED_NAME_CAP = void 0;
+exports.failedTestNames = failedTestNames;
+/** How many names a refusal lists before it counts the rest. */
+exports.FAILED_NAME_CAP = 10;
+/** Jest's summary marks each failure with `● <suite> › <test>`. */
+const SUMMARY_LINE = /^\s*●\s+(.+?)\s*$/;
+/**
+ * Pull the failing test names out of a jest run's output.
+ *
+ * PURE, and forgiving: output it cannot read yields an empty list so the caller keeps its existing
+ * refusal rather than replacing a working message with an empty one. Jest prints the summary block
+ * twice on some configurations, so names are de-duplicated — the same failure listed twice is one
+ * failure.
+ */
+function failedTestNames(output) {
+    const seen = [];
+    for (const line of String(output ?? '').split('\n')) {
+        const m = SUMMARY_LINE.exec(line);
+        if (m === null)
+            continue;
+        const name = m[1];
+        // A `●` line that is not a test name (jest uses the bullet for Console blocks too).
+        if (name === '' || name === 'Console' || !name.includes('›'))
+            continue;
+        if (!seen.includes(name))
+            seen.push(name);
+    }
+    if (seen.length <= exports.FAILED_NAME_CAP)
+        return seen;
+    const rest = seen.length - exports.FAILED_NAME_CAP;
+    return [...seen.slice(0, exports.FAILED_NAME_CAP), `… and ${rest} more`];
+}

package/dist/holmes/review/run-replay.d.ts

@@ -1,6 +1,23 @@
 import { evaluationMetrics, impactMetrics, ceilingMetrics } from './evaluation-metrics';
 import { type ReplayCorpus } from './replay-corpus';
 import { type PprArmConfig } from '../assoc/assoc-arm';
+/** One case, scored by both arms. Measurement only — never read by a pin. */
+export interface PairedRow {
+    commit: string;
+    uncited: boolean;
+    productRecall10: number;
+    baselineRecall10: number;
+    truth: number;
+}
+/**
+ * @implements A-SPEC-578.7
+ * The paired differences on the UNCITED axis, ready for `pairedPower`.
+ *
+ * Filtering here rather than while measuring is deliberate: observation records every case, and the
+ * axis is chosen at analysis time. A harness that only recorded what it currently cares about could
+ * never answer a question asked later.
+ */
+export declare function uncitedDiffs(rows: readonly PairedRow[]): number[];
 export interface ReplayResult {
     corpus: string;
     cases: number;
@@ -231,6 +248,12 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
         /** @implements A-SPEC-567.2 — present only when judgementBundle was asked. */
         judgementBundle?: import('./judgement-bundle').JudgementBundle;
     }) => void;
+    /**
+     * @implements A-SPEC-578.7 — the power arm: one row per case, both arms scored, so the caller
+     * can compute an MDE with `pairedPower`. Same idiom as `caseDump` — a callback, never a change
+     * to `ReplayResult`, so a pin cannot move because a measurement was asked for.
+     */
+    pairedDump?: (row: PairedRow) => void;
     /** @implements A-SPEC-487 — 2-pass semantic injection for the dump only, never the pins. */
     productSemantic?: {
         embedBatch: (texts: string[], kind: 'query' | 'doc') => Promise<number[][]>;

package/dist/holmes/review/run-replay.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.uncitedDiffs = uncitedDiffs;
 exports.runReplay = runReplay;
 exports.semanticCaseRanking = semanticCaseRanking;
 // @implements A-SPEC-346
@@ -41,6 +42,7 @@ exports.semanticCaseRanking = semanticCaseRanking;
 // @implements A-SPEC-349
 // @implements A-SPEC-378
 // @implements A-SPEC-402
+const baseline_arm_1 = require("./baseline-arm");
 const fs = __importStar(require("node:fs"));
 const node_child_process_1 = require("node:child_process");
 const os = __importStar(require("node:os"));
@@ -79,6 +81,17 @@ const dense_retrieval_1 = require("./dense-retrieval");
 const explore_1 = require("../assoc/explore");
 const temporal_prior_1 = require("./temporal-prior");
 const commit_text_1 = require("./commit-text");
+/**
+ * @implements A-SPEC-578.7
+ * The paired differences on the UNCITED axis, ready for `pairedPower`.
+ *
+ * Filtering here rather than while measuring is deliberate: observation records every case, and the
+ * axis is chosen at analysis time. A harness that only recorded what it currently cares about could
+ * never answer a question asked later.
+ */
+function uncitedDiffs(rows) {
+    return rows.filter((r) => r.uncited).map((r) => r.productRecall10 - r.baselineRecall10);
+}
 /**
  * Run the point-in-time replay against ANY corpus.
  *
@@ -258,6 +271,23 @@ async function runReplay(corpus, limit, opts = {}) {
                     return Object.keys(defUse).length === 0 ? firstPass : analyzeWith(defUse);
                 })();
                 const ranked = result.candidates.map((x) => x.file);
+                // @implements A-SPEC-578.7 — the power arm. Both recalls come from what already exists:
+                // the product's from `ranked` (never recomputed — recomputing is how a benchmark ends up
+                // scoring a pipeline the product does not ship, measured once already in A-SPEC-573.3),
+                // the baseline's from `rankBaseline`, the no-graph floor built in A-SPEC-356 and never
+                // called until now. The `uncited` predicate is the PRODUCT'S — `citationsIn` — so the axis
+                // is defined the same way here and there.
+                if (opts.pairedDump !== undefined && c.files.length > 0) {
+                    const truth = new Set(c.files);
+                    const recallOf = (files) => files.slice(0, 10).filter((f) => truth.has(f)).length / truth.size;
+                    opts.pairedDump({
+                        commit: c.commit,
+                        uncited: (0, localize_1.citationsIn)(c.subject, new Set(specs.map((sp) => sp.id))).cited.length === 0,
+                        productRecall10: recallOf(ranked),
+                        baselineRecall10: recallOf((0, baseline_arm_1.rankBaseline)(c.subject, scanned, 10).map((h) => h.file)),
+                        truth: truth.size,
+                    });
+                }
                 // @implements A-SPEC-469 — the union scores what a caller actually RECEIVES as the impact
                 // answer, and that surface is now the graded rankedImpact (the closure stays gate-facing).
                 const impacted = (result.impacts?.rankedImpact ?? []).map((r) => r.file);

package/dist/holmes/review/test-runner.d.ts

@@ -190,6 +190,18 @@ export declare function runGo(files: string[], mode: TestRunPlan['mode'], cwd: s
  * gate that ran part of its scope has verified less than it reports.
  */
 export declare function runTestScope(scope: TestScope, cwd: string): TestRunResult;
+/**
+ * The last few lines of a runner's output, bounded by SIZE as well as by line count.
+ *
+ * A line budget is only a size budget while the lines are short, and jest `--json` breaks that
+ * assumption completely: it emits one line. Measured 2026-09-02 — a GREEN `test_run` returned
+ * 1,432,092 characters, of which this field was 1,421,327 (99.2%) across "6 lines" whose longest
+ * was 1,420,959. The usefulness was inverted: a red run gave six clean lines of stderr summary,
+ * and a green run gave the whole document.
+ *
+ * The END is what survives a cut. A runner's conclusion is always at the bottom.
+ */
+export declare const TAIL_MAX_CHARS = 4000;
 export declare function tailOf(s: string, opts?: number | {
     lines?: number;
     maxChars?: number;
@@ -204,4 +216,19 @@ export declare function tailOf(s: string, opts?: number | {
  * Returns null on anything it cannot read, and the caller falls back to the truncated original:
  * a failed summary must not turn partial information into none.
  */
+/**
+ * What failed, by name — the red counterpart to `summarizeJestJson`.
+ *
+ * Measured 2026-09-09: a red `test_run` reported "1 failed" three times running and never said
+ * which test. The failing file had to be recovered from the outcome ledger's A-SPEC list, because
+ * the red path's tail is the tail of a JSON DOCUMENT — bytes, not a name. Counts tell you a run
+ * went red; only a name tells you what to look at.
+ *
+ * The payload is located by the SAME rule `summarizeJestJson` uses (the first `{`), because a suite
+ * that logs anything prints it before the JSON — this repository's does — and two rules for one
+ * string is how the two quietly disagree.
+ *
+ * Only the FIRST line of a failure message: one failure, one look. The rest is in the file.
+ */
+export declare function failedTestSummary(stdout: string, limit?: number): string | null;
 export declare function summarizeJestJson(stdout: string): string | null;

package/dist/holmes/review/test-runner.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAIL_MAX_CHARS = void 0;
 exports.planTestRun = planTestRun;
 exports.ecosystemOf = ecosystemOf;
 exports.parseGoTestJson = parseGoTestJson;
@@ -49,6 +50,7 @@ exports.runDotnet = runDotnet;
 exports.runGo = runGo;
 exports.runTestScope = runTestScope;
 exports.tailOf = tailOf;
+exports.failedTestSummary = failedTestSummary;
 exports.summarizeJestJson = summarizeJestJson;
 // @implements A-SPEC-102.1
 const node_child_process_1 = require("node:child_process");
@@ -304,7 +306,11 @@ function runJest(files, mode, cwd) {
         const err = e;
         // A failing suite still emits --json on stdout, so execution evidence — and the red/green outcome
         // classification (A-SPEC-534.1) — survives a red run.
-        return { passed: false, tail: tailOf(`${err.stdout ?? ''}\n${err.stderr ?? err.message ?? ''}`), executed: parseExecutedCounts(err.stdout ?? '', cwd), outcomes: classifyJestOutcomes(err.stdout ?? '', cwd) };
+        // @implements A-SPEC-577.1 — the names first, then jest's own summary from stderr. Without the
+        // first half this tail was the tail of a JSON document: it said how many failed and never which.
+        const named = failedTestSummary(err.stdout ?? '');
+        const tail = tailOf(`${named === null ? (err.stdout ?? '') : named}\n${err.stderr ?? err.message ?? ''}`, { lines: named === null ? 6 : 40 });
+        return { passed: false, tail, executed: parseExecutedCounts(err.stdout ?? '', cwd), outcomes: classifyJestOutcomes(err.stdout ?? '', cwd) };
     }
 }
 /**
@@ -703,11 +709,11 @@ function runTestScope(scope, cwd) {
  *
  * The END is what survives a cut. A runner's conclusion is always at the bottom.
  */
-const TAIL_MAX_CHARS = 4000;
+exports.TAIL_MAX_CHARS = 4000;
 function tailOf(s, opts = {}) {
     // The numeric spelling is the one the go adapter uses (`tailOf(err.stderr, 2)`); keeping it means
     // this change cannot silently alter a caller that only ever wanted fewer lines.
-    const { lines = 6, maxChars = TAIL_MAX_CHARS } = typeof opts === 'number' ? { lines: opts } : opts;
+    const { lines = 6, maxChars = exports.TAIL_MAX_CHARS } = typeof opts === 'number' ? { lines: opts } : opts;
     const picked = s.trim().split('\n').slice(-lines).join('\n');
     if (picked.length <= maxChars)
         return picked;
@@ -725,6 +731,56 @@ function tailOf(s, opts = {}) {
  * Returns null on anything it cannot read, and the caller falls back to the truncated original:
  * a failed summary must not turn partial information into none.
  */
+// @implements A-SPEC-577.1
+/**
+ * What failed, by name — the red counterpart to `summarizeJestJson`.
+ *
+ * Measured 2026-09-09: a red `test_run` reported "1 failed" three times running and never said
+ * which test. The failing file had to be recovered from the outcome ledger's A-SPEC list, because
+ * the red path's tail is the tail of a JSON DOCUMENT — bytes, not a name. Counts tell you a run
+ * went red; only a name tells you what to look at.
+ *
+ * The payload is located by the SAME rule `summarizeJestJson` uses (the first `{`), because a suite
+ * that logs anything prints it before the JSON — this repository's does — and two rules for one
+ * string is how the two quietly disagree.
+ *
+ * Only the FIRST line of a failure message: one failure, one look. The rest is in the file.
+ */
+function failedTestSummary(stdout, limit = 5) {
+    const start = stdout.indexOf('{');
+    if (start < 0)
+        return null;
+    let j;
+    try {
+        j = JSON.parse(stdout.slice(start));
+    }
+    catch {
+        return null;
+    }
+    if (j === null || typeof j !== 'object' || !Array.isArray(j.testResults))
+        return null;
+    const failures = [];
+    for (const file of j.testResults) {
+        const base = typeof file?.name === 'string' ? file.name.split(/[\\/]/).pop() ?? file.name : '(unknown file)';
+        for (const a of Array.isArray(file?.assertionResults) ? file.assertionResults : []) {
+            if (a?.status !== 'failed')
+                continue;
+            const msg = Array.isArray(a.failureMessages) ? a.failureMessages.find((m) => typeof m === 'string' && m.trim() !== '') : undefined;
+            failures.push({
+                where: `${base} \u203a ${String(a.title ?? '(untitled)')}`,
+                first: typeof msg === 'string' ? (msg.trim().split('\n')[0] ?? '') : '',
+            });
+        }
+    }
+    if (failures.length === 0)
+        return null;
+    const shown = failures.slice(0, Math.max(0, limit));
+    const lines = shown.flatMap((f) => (f.first === '' ? [f.where] : [f.where, `    ${f.first}`]));
+    const rest = failures.length - shown.length;
+    if (rest > 0)
+        lines.push(`    \u2026 \uc678 ${rest}\uac74`);
+    return lines.join('\n');
+}
 function summarizeJestJson(stdout) {
     // The payload is not the whole of stdout. A suite that logs anything prints it BEFORE the JSON,
     // and this repository's own suite does: measured, the first live run after this function landed