plumbbob 0.9.3 → 0.10.0

package/node_modules/checkride/dist/orchestrator.js

@@ -1,5 +1,5 @@
 /**
- * Orchestrator — behavior-ported from the interim `scripts/check.mjs`.
+ * The check orchestrator.
  *
  * Resolves slots to adapters, selects which to run (flags), spawns each command
  * (or runs a built-in), captures raw output to `.check/`, and writes the
@@ -7,22 +7,26 @@
  * diagnostics — agents read the per-tool JSON directly.
  */
 import { spawn } from 'node:child_process';
+import { readdirSync } from 'node:fs';
 import { mkdir, rm } from 'node:fs/promises';
 import { cpus } from 'node:os';
 import { join } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { ADAPTERS, SCHEMA_VERSION, SLOTS } from './adapters.js';
 import { writeFileAtomic } from './atomic.js';
-import { applyBaseline, BASELINE_FILE, baselinesEqual, countBaselineKeys, fallowVerdict, fingerprint, loadBaseline, ratchet, writeBaseline, } from './baseline/index.js';
+import { applyBaseline, BASELINE_FILE, baselinesEqual, countBaselineKeys, fallowVerdict, fingerprint, historicalHint, ratchet, readBaselineStatus, writeBaseline, } from './baseline/index.js';
 import { loadConfig, resolveChecks } from './config.js';
 import { writeDigest } from './digest/index.js';
 import { checkLinks } from './links.js';
 import { checkPack } from './pack.js';
-import { detectPackageManager, isAvailableUnder, translateExec } from './pm/index.js';
+import { detectPackageManager, execTool, execUsesGlobalCache, installCommand, isAvailableUnder, resolveSlotTool, translateExec, } from './pm/index.js';
+import { KILL_GRACE_SECONDS, killGroup } from './proc.js';
+import { checkSecurity } from './security.js';
 import { checkSmoke } from './smoke.js';
 import { checkSnippets } from './snippets.js';
+import { parseToolJson } from './tool-json.js';
 /**
- * Port of the interim `select_checks`: only/skip/opt-in selection by slot name.
+ * Only/skip/opt-in selection by slot name.
  * An opt-in slot runs when `--all`/`--include` names it, or when it was
  * explicitly configured in `checks` (`r.explicit`) — naming a slot is opting in.
  */
@@ -42,17 +46,30 @@ export function selectChecks(resolved, flags) {
     });
 }
 /**
- * Reject unknown slot names in `--only`/`--skip`/`--include`. A typo like
- * `--only lints` used to slip through `selectChecks` as a filter that matched
+ * Reject bad slot selections in `--only`/`--skip`/`--include`. A typo like
+ * `--only lints` would otherwise slip through `selectChecks` as a filter that matched
  * nothing, silently disabling the gate — the worst kind of vacuous green in a
  * definition-of-done check. It is a usage error instead (thrown here, surfaced
  * as exit 2 at the CLI). The valid set is every resolved slot: the catalogue
  * slots plus any config custom-check names.
+ *
+ * A *present but empty* list is rejected for the same reason. `[]` is truthy,
+ * so `selectChecks` reads it as "match nothing" rather than "no filter", and an
+ * empty `only` selects zero checks. The CLI already rejects `--only ,` when it
+ * parses (see `parseList`); this covers the programmatic API, where a caller can
+ * hand `runChecks` an array it computed. `selectChecks` itself is left alone —
+ * it is exported public surface, and the error belongs before it runs.
  */
 function validateSelection(resolved, flags) {
     const valid = new Set(resolved.map((r) => r.slot));
     for (const flag of ['only', 'skip', 'include']) {
-        const unknown = (flags[flag] ?? []).filter((name) => !valid.has(name));
+        const names = flags[flag];
+        if (names === undefined || names === null)
+            continue;
+        if (names.length === 0) {
+            throw new Error(`--${flag} was given an empty list, which selects nothing. Valid slots: ${[...valid].join(', ')}.`);
+        }
+        const unknown = names.filter((name) => !valid.has(name));
         if (unknown.length === 0)
             continue;
         const named = unknown.map((n) => `'${n}'`).join(', ');
@@ -76,33 +93,18 @@ export function runtimeArgs(adapter, changed) {
 export const DEFAULT_TIMEOUT_SECONDS = 600;
 /**
  * Default pool width for a wave (equal-`order` group): `min(4, max(1, cores −
- * 1))` (D5). Heavy checks (test, mutation, build) parallelize internally, so
+ * reserve))`. Heavy checks (test, mutation, build) parallelize internally, so
  * oversubscribing every core is worse than a conservative cap; one reserved
- * core keeps the machine responsive. Override with `--concurrency`.
+ * core keeps the machine responsive — for the human at it. A hosted CI runner
+ * has no such human, and a standard GitHub-hosted runner reports 2 CPUs, so
+ * reserving one there collapsed the pool to 1 and wave scheduling silently
+ * degenerated to fully sequential — on exactly the machine class the docs say
+ * to gate on. Every CI provider sets `CI`, so no core is reserved there.
+ * Override with `--concurrency`; `--bail` stays fail-fast sequential.
  */
-function defaultConcurrency() {
-    return Math.min(4, Math.max(1, cpus().length - 1));
-}
-/** Grace between SIGTERM and SIGKILL when a timed-out check won't die politely. */
-const KILL_GRACE_SECONDS = 5;
-/**
- * Signal a spawned check's whole process group. The check is spawned
- * `detached`, so it leads its own group and a negated-pid `kill` reaches every
- * descendant — a wrapper's grandchildren included — not just the direct child.
- * That is the difference between a timed-out `sh -c 'slow-tool …'` leaving its
- * real worker orphaned and alive versus taking the whole tree down. ESRCH is
- * swallowed: the group racing to exit on its own before we signal is success,
- * not an error (and `pid` is absent only when the spawn itself failed).
- */
-function killGroup(pid, signal) {
-    if (pid === undefined)
-        return;
-    try {
-        process.kill(-pid, signal);
-    }
-    catch {
-        // Group already gone (raced with a clean exit) — nothing left to kill.
-    }
+export function defaultConcurrency(env = process.env, cores = cpus().length) {
+    const reserve = env['CI'] ? 0 : 1;
+    return Math.min(4, Math.max(1, cores - reserve));
 }
 /**
  * Process groups of checks currently in flight: pid → a promise that settles
@@ -221,51 +223,164 @@ function spawnCheck(command, args, cwd, timeoutSec) {
         });
     });
 }
+/**
+ * Dispatch a built-in check, or `null` when the adapter spawns a real tool.
+ * Every built-in that runs a subprocess goes through `spawnCheck`, so its
+ * child registers in `liveChecks` and inherits the timeout + reaping like any
+ * other check. `security` alone runs the adapter's own args — its
+ * `--audit-level` doubles as the threshold the evaluator enforces, since
+ * pnpm's JSON-mode exit code ignores the level. The snippets pair shares one
+ * execution path, differing only in mode.
+ */
+function runBuiltin(adapter, ctx, timeout) {
+    const base = { cwd: ctx.cwd, spawn: spawnCheck, timeoutSec: timeout };
+    switch (adapter.builtin) {
+        case 'pack':
+            return checkPack({ ...base, pm: ctx.pm });
+        case 'smoke':
+            return checkSmoke(base);
+        case 'security':
+            return checkSecurity({ ...base, command: adapter.command, args: runtimeArgs(adapter, ctx.changed) });
+        case 'snippets':
+            return checkSnippets({ ...base, mode: 'src', pm: ctx.pm });
+        case 'snippets-dist':
+            return checkSnippets({ ...base, mode: 'dist', pm: ctx.pm });
+        default:
+            return null;
+    }
+}
+/**
+ * Refuse a slot whose tool this repo never declared, rather than letting the
+ * launcher's per-user cache decide the verdict.
+ *
+ * `--no-install` stops `npx`/`bunx` fetching a missing tool, but both still run
+ * a copy cached from some earlier, unrelated invocation — so the same commit
+ * passes on a machine that happens to hold one and fails on a clean checkout,
+ * which is the CI runner. A gate whose result depends on that is not reporting
+ * on the code. Resolving the binary in the local tree first moves the failure
+ * to every machine equally, and to the one place it is cheap to fix.
+ *
+ * Scoped to the launchers that *have* such a cache ({@link
+ * execUsesGlobalCache}): `pnpm exec` and `yarn` resolve from the project tree
+ * already, and pre-flighting Yarn PnP — which has no `node_modules/.bin` — would
+ * report every tool missing. `null` means the check may spawn.
+ */
+export function missingToolOutcome(slot, adapter, args, ctx) {
+    if (!execUsesGlobalCache(ctx.pm))
+        return null;
+    const tool = execTool(adapter.command, args);
+    if (!tool || resolveSlotTool(ctx.cwd, tool))
+        return null;
+    const stderr = [
+        `checkride: the \`${slot}\` slot needs \`${tool}\`, which is not installed in this project.`,
+        '',
+        `  looked for: node_modules/.bin/${tool} (from ${ctx.cwd} up to the repo root)`,
+        '',
+        'checkride never fetches a tool mid-run, and a launcher cache can still supply',
+        "one this repo never declared — so a tool that isn't a dependency here would",
+        'pass on your machine and fail on a clean checkout. Declare it instead:',
+        '',
+        `  ${installCommand(ctx.pm, tool)}`,
+        '',
+    ].join('\n');
+    // Exit 1, not -1. Nothing spawned, so there is no real status to report — but
+    // -1 is reserved for a spawn failure or timeout, which `triage` discounts as
+    // "a harness problem, not a finding" (see `docs/plugin.md`). An undeclared
+    // tool is the opposite: the finding the run exists to surface, and the one
+    // the reader has to act on. Reporting it as -1 would tell them to ignore it.
+    return { ok: false, exit_code: 1, stdout: '', stderr };
+}
+/**
+ * Fail the `prose` check when its configured `exemplars` directory is missing
+ * or holds no files, rather than letting the tool pass while the anchor texts
+ * rot away.
+ *
+ * The exemplars are the repo's hand-written voice reference: the AGENTS.md
+ * stanza tells writing sessions to imitate them, so a config that names a
+ * directory that no longer exists (renamed, deleted, never created) would leave
+ * that instruction aimed at nothing while the check stayed green. Presence is
+ * the whole assertion — checkride never scores prose against the exemplars;
+ * that read belongs to a human. `null` means the check may spawn.
+ */
+export function missingExemplarsOutcome(adapter, cwd) {
+    const dir = adapter.exemplars;
+    if (dir === undefined)
+        return null;
+    let state = 'does not exist';
+    try {
+        const files = readdirSync(join(cwd, dir), { withFileTypes: true }).filter((e) => e.isFile() && !e.name.startsWith('.'));
+        state = files.length > 0 ? null : 'has no files in it';
+    }
+    catch (error) {
+        // Unreadable reads as missing. A file sitting at the path is named for what
+        // it is — "does not exist" would send the reader hunting a typo that isn't
+        // there.
+        if (error instanceof Error && 'code' in error && error.code === 'ENOTDIR')
+            state = 'is a file, not a directory';
+    }
+    if (state === null)
+        return null;
+    const stderr = [
+        `checkride: the \`prose\` slot names \`${dir}\` as its voice exemplars, and that path ${state}.`,
+        '',
+        'Exemplars are hand-written prose the agent contract points writing sessions at',
+        'as the voice to imitate, so a config naming an empty directory aims that',
+        'instruction at nothing. Write a few short samples of prose in your own voice',
+        'there (or fix the `exemplars` path in checkride.config.json), then re-run.',
+        '',
+    ].join('\n');
+    // Exit 1 for the same reason as missingToolOutcome above: nothing spawned,
+    // but this is the finding the run exists to surface, not a harness problem.
+    return { ok: false, exit_code: 1, stdout: '', stderr };
+}
 const defaultRunner = (resolved, ctx) => {
     const adapter = resolved.adapter;
     if (!adapter)
         return Promise.resolve({ ok: true, exit_code: 0, stdout: '', stderr: '' });
-    if (adapter.builtin === 'links')
-        return checkLinks(ctx.cwd);
-    const timeout = adapter.timeout ?? ctx.timeout ?? DEFAULT_TIMEOUT_SECONDS;
-    // The pack built-in spawns its own subprocess (the PM's pack dry-run) through
-    // `spawnCheck`, so its child registers in `liveChecks` and inherits the
-    // timeout + reaping like every other check (D16/C6).
-    if (adapter.builtin === 'pack')
-        return checkPack({ cwd: ctx.cwd, pm: ctx.pm, spawn: spawnCheck, timeoutSec: timeout });
-    // The smoke built-in spawns a `node` probe of the built package through
-    // `spawnCheck`, so that child registers in `liveChecks` and inherits the
-    // timeout + reaping like every other check (D9/D16/C6).
-    if (adapter.builtin === 'smoke')
-        return checkSmoke({ cwd: ctx.cwd, spawn: spawnCheck, timeoutSec: timeout });
-    // The snippets built-ins spawn `<pm> exec tsc` through `spawnCheck` (D16/C6);
-    // the two adapters share one execution path, differing only in mode (D12).
-    if (adapter.builtin === 'snippets') {
-        return checkSnippets({ cwd: ctx.cwd, mode: 'src', pm: ctx.pm, spawn: spawnCheck, timeoutSec: timeout });
-    }
-    if (adapter.builtin === 'snippets-dist') {
-        return checkSnippets({ cwd: ctx.cwd, mode: 'dist', pm: ctx.pm, spawn: spawnCheck, timeoutSec: timeout });
+    if (adapter.builtin === 'links') {
+        return checkLinks(ctx.cwd, { exclude: adapter.exclude, allowlist: adapter.allowlist });
     }
-    const { command, args } = translateExec(adapter.command, runtimeArgs(adapter, ctx.changed), ctx.pm);
+    const timeout = adapter.timeout ?? ctx.timeout ?? DEFAULT_TIMEOUT_SECONDS;
+    const builtin = runBuiltin(adapter, ctx, timeout);
+    if (builtin)
+        return builtin;
+    const missingExemplars = missingExemplarsOutcome(adapter, ctx.cwd);
+    if (missingExemplars)
+        return Promise.resolve(missingExemplars);
+    const declared = runtimeArgs(adapter, ctx.changed);
+    const missing = missingToolOutcome(resolved.slot, adapter, declared, ctx);
+    if (missing)
+        return Promise.resolve(missing);
+    const { command, args } = translateExec(adapter.command, declared, ctx.pm);
     return spawnCheck(command, args, ctx.cwd, timeout);
 };
-/** Persist raw output atomically: JSON to `.check/<outputFile>`, else stdout/stderr text. */
+/**
+ * Persist raw output atomically: JSON to `.check/<outputFile>`, else
+ * stdout/stderr text.
+ *
+ * Returns the JSON file it wrote, or `null` when it fell through to text — the
+ * summary's `output_file` is that return value, never the adapter's
+ * *declaration*. A slot that declares an `outputFile` does not always produce
+ * one (the tool printed a warning first, crashed, or emitted plain text this
+ * run), and naming a file that was never written sends every consumer to an
+ * ENOENT while the real bytes sit in `<slot>.stdout.txt` beside it.
+ */
 async function persistOutput(cwd, adapter, outcome) {
     const dir = join(cwd, '.check');
     if (adapter.outputFile && outcome.stdout.trim()) {
-        try {
-            JSON.parse(outcome.stdout);
-            await writeFileAtomic(join(dir, adapter.outputFile), outcome.stdout);
-            return;
-        }
-        catch {
-            // Not JSON after all; fall through to raw text.
+        // Tolerates a launcher preamble ahead of the JSON; writes the tool's own
+        // bytes from the first JSON character on, so the artifact actually parses.
+        const parsed = parseToolJson(outcome.stdout);
+        if (parsed) {
+            await writeFileAtomic(join(dir, adapter.outputFile), parsed.text);
+            return adapter.outputFile;
         }
     }
     if (outcome.stdout.trim())
         await writeFileAtomic(join(dir, `${adapter.slot}.stdout.txt`), outcome.stdout);
     if (outcome.stderr.trim())
         await writeFileAtomic(join(dir, `${adapter.slot}.stderr.txt`), outcome.stderr);
+    return null;
 }
 /**
  * Remove a slot's prior `.check/` artifacts before it re-runs, so a later clean
@@ -273,7 +388,7 @@ async function persistOutput(cwd, adapter, outcome) {
  * the previous run's output lingering as authoritative. Covers everything
  * `persistOutput` writes (`<slot>.stdout.txt`, `<slot>.stderr.txt`, the adapter's
  * JSON `outputFile`) plus the conventional `<slot>.json` a tool may write itself
- * (e.g. vitest's `--outputFile=.check/test.json`, where `outputFile` is null).
+ * (for example vitest's `--outputFile=.check/test.json`, where `outputFile` is null).
  * Runs *before* the check so this run's own tool-written artifacts survive.
  */
 async function clearSlotOutputs(cwd, adapter) {
@@ -290,9 +405,18 @@ async function clearSlotOutputs(cwd, adapter) {
 function writeLine(out, line) {
     out.write(`${line}\n`);
 }
-function formatStatusLine(check) {
+/**
+ * Width of the slot-name column, measured from the names this run will print
+ * (never below the historical 8). A fixed 8 was sized for catalogue slots, and
+ * a config custom check — `typecheck-tests` is 15 — pushed the duration and
+ * description columns right on its row alone.
+ */
+function nameWidth(selected) {
+    return selected.reduce((n, r) => Math.max(n, r.slot.length), 8);
+}
+function formatStatusLine(check, width) {
     const mark = check.ok ? '✔' : '✘';
-    const name = check.name.padEnd(8);
+    const name = check.name.padEnd(width);
     const duration = `${check.duration_ms}ms`.padStart(8);
     return `  ${mark} ${name} ${duration}  ${check.description}`;
 }
@@ -306,14 +430,16 @@ function skippedEntry(resolved) {
         reason: resolved.skip ?? 'skipped',
         exit_code: null,
         duration_ms: 0,
-        output_file: resolved.adapter?.outputFile ?? null,
+        // A skipped check ran nothing and wrote nothing; naming its adapter's
+        // declared output file would point at whatever an earlier run left there.
+        output_file: null,
     };
 }
 /**
- * `total_duration_ms` is the wall-clock span of the whole execution phase (D7),
+ * `total_duration_ms` is the wall-clock span of the whole execution phase,
  * not the sum of per-check durations — under concurrency those diverge, and
- * wall-clock is what the field honestly means. It equals the old sum whenever
- * execution is sequential (one check in flight at a time).
+ * wall-clock is what the field honestly means. It equals the per-check sum
+ * whenever execution is sequential (one check in flight at a time).
  */
 function buildSummary(checks, totalDurationMs) {
     return {
@@ -335,8 +461,8 @@ function enableHint(slot, adapters) {
 }
 /**
  * The first-party vacuous-green signal: "green because nothing ran" must be
- * unmissable, not something only a consumer that hand-rolled the check (as
- * plumbbob's gate did) can distinguish from "green because everything passed".
+ * unmissable, not something only a consumer that hand-rolls its own check can
+ * distinguish from "green because everything passed".
  * Names why each slot sat out and what would enable it.
  */
 function warnVacuous(stderr, checks, adapters) {
@@ -354,9 +480,8 @@ function warnVacuous(stderr, checks, adapters) {
 }
 /**
  * Apply the defaults every command shares: cwd, the slot/adapter catalogues, the
- * config (loaded from `cwd` unless injected), and the two streams. Extracted so
- * `runChecks`/`runFix`/`runDoctor` resolve this identical block one way (it was
- * copy-pasted across all three).
+ * config (loaded from `cwd` unless injected), and the two streams, so
+ * `runChecks`/`runFix`/`runDoctor` resolve this identical block one way.
  */
 export function resolveCommonOptions(options) {
     const cwd = options.cwd ?? process.cwd();
@@ -369,18 +494,36 @@ export function resolveCommonOptions(options) {
         stderr: options.stderr ?? process.stderr,
     };
 }
-/** Apply every run default: the common options plus runner, flags, PM, and baseline. */
+/**
+ * Apply every run default: the common options plus runner, flags, PM, and
+ * baseline. `nameWidth` is a placeholder here — the selection it measures is
+ * not known until after `selectChecks`, so `runChecks` narrows it then.
+ */
+/**
+ * The baseline a run masks with: the option override, or the committed file.
+ * An injected baseline bypasses the file, so its state carries no file
+ * diagnosis — it is classified by presence alone.
+ */
+function resolveBaselineRead(options, cwd) {
+    if (options.baseline !== undefined) {
+        return { baseline: options.baseline, state: options.baseline === null ? 'absent' : 'ok' };
+    }
+    return readBaselineStatus(cwd);
+}
 function resolveRunContext(options) {
     const common = resolveCommonOptions(options);
+    const read = resolveBaselineRead(options, common.cwd);
     return {
         ...common,
+        nameWidth: 8,
         runner: options.runner ?? defaultRunner,
         json: options.json ?? false,
         bail: options.bail ?? false,
         changed: options.changed ?? false,
         timeout: common.config?.timeout,
         pm: options.pm ?? detectPackageManager({ cwd: common.cwd }),
-        baseline: options.baseline !== undefined ? options.baseline : loadBaseline(common.cwd),
+        baseline: read.baseline,
+        baselineState: read.state,
         concurrency: Math.max(1, Math.floor(options.concurrency ?? defaultConcurrency())),
     };
 }
@@ -403,15 +546,15 @@ function maskOutcome(adapter, outcome, baseline, slot) {
     return { ok: outcome.ok, baselined: 0, newKeys: [], reason: null, observed: null };
 }
 /** Build (and print) the skipped-entry row for a slot that won't run this pass. */
-function handleSkip(r, unavailable, pm, json, stderr) {
-    const entry = skippedEntry(unavailable ? { ...r, skip: `'${r.adapter?.command} ${r.adapter?.args[0]}' is unavailable under ${pm}` } : r);
-    if (!json)
-        writeLine(stderr, `  ○ ${entry.name.padEnd(8)}      skip  ${entry.reason ?? ''}`);
+function handleSkip(r, unavailable, ctx) {
+    const entry = skippedEntry(unavailable ? { ...r, skip: `'${r.adapter?.command} ${r.adapter?.args[0]}' is unavailable under ${ctx.pm}` } : r);
+    if (!ctx.json)
+        writeLine(ctx.stderr, `  ○ ${entry.name.padEnd(ctx.nameWidth)}      skip  ${entry.reason ?? ''}`);
     return entry;
 }
 /** Print one check's status line, its baselined count, and any new (non-grandfathered) findings. */
-function reportCheckResult(stderr, entry, mask) {
-    writeLine(stderr, formatStatusLine(entry));
+function reportCheckResult(stderr, entry, mask, width) {
+    writeLine(stderr, formatStatusLine(entry, width));
     if (mask.baselined > 0)
         writeLine(stderr, `           ${mask.baselined} baselined (grandfathered)`);
     if (!entry.ok && mask.reason)
@@ -428,12 +571,12 @@ async function runOneCheck(r, adapter, ctx) {
         writeLine(ctx.stderr, `  ▸ ${r.slot}  ${adapter.description}`);
     // Wipe this slot's stale `.check/` artifacts before it runs, so a leaner re-run
     // can't leave last run's output behind as authoritative — and so any artifact
-    // the tool writes during *this* run (e.g. `test.json`) survives.
+    // the tool writes during *this* run (for example `test.json`) survives.
     await clearSlotOutputs(ctx.cwd, adapter);
     const start = performance.now();
     const outcome = await ctx.runner(r, { cwd: ctx.cwd, changed: ctx.changed, pm: ctx.pm, ...(ctx.timeout !== undefined ? { timeout: ctx.timeout } : {}) });
     const duration_ms = Math.round(performance.now() - start);
-    await persistOutput(ctx.cwd, adapter, outcome);
+    const outputFile = await persistOutput(ctx.cwd, adapter, outcome);
     // Masking is always on (even under a partial run); only the ratchet is gated.
     // The raw `.check/<slot>.json` is persisted untouched — masking changes the
     // pass/fail verdict, never the authoritative output.
@@ -445,7 +588,7 @@ async function runOneCheck(r, adapter, ctx) {
         ok: mask.ok,
         exit_code: outcome.exit_code,
         duration_ms,
-        output_file: adapter.outputFile,
+        output_file: outputFile,
         ...(mask.baselined > 0 ? { baselined: mask.baselined } : {}),
     };
     return { entry, run: { slot: r.slot, adapter, outcome }, mask };
@@ -455,19 +598,19 @@ async function runOneCheck(r, adapter, ctx) {
  * shared by the sequential (`--bail`) and wave paths. A skipped/unavailable slot
  * records a skip row and runs nothing; an active one runs, prints its status
  * line, and reports its fingerprint for the ratchet. It mutates no shared state,
- * so N of these can be in flight at once (C6).
+ * so N of these can be in flight at once.
  */
 async function runSelectedCheck(r, ctx) {
-    // Skip when unresolved, or when the adapter can't run under this PM — e.g.
-    // `pnpm audit` (the `security` slot) is unavailable off pnpm (b5).
+    // Skip when unresolved, or when the adapter can't run under this PM — for
+    // example `pnpm audit` (the `security` slot) is unavailable off pnpm.
     const unavailable = Boolean(r.adapter && !isAvailableUnder(r.adapter.command, r.adapter.args, ctx.pm));
     if (r.skip || !r.adapter || unavailable) {
-        return { entry: handleSkip(r, unavailable, ctx.pm, ctx.json, ctx.stderr), run: null, observed: null };
+        return { entry: handleSkip(r, unavailable, ctx), run: null, observed: null, newKeys: [] };
     }
     const { entry, run, mask } = await runOneCheck(r, r.adapter, ctx);
     if (!ctx.json)
-        reportCheckResult(ctx.stderr, entry, mask);
-    return { entry, run, observed: mask.observed !== null ? { slot: r.slot, fp: mask.observed } : null };
+        reportCheckResult(ctx.stderr, entry, mask, ctx.nameWidth);
+    return { entry, run, observed: mask.observed !== null ? { slot: r.slot, fp: mask.observed } : null, newKeys: mask.newKeys };
 }
 /** Fold one result into the report accumulators, in call order. */
 function collect(res, acc) {
@@ -476,15 +619,16 @@ function collect(res, acc) {
         acc.runs.push(res.run);
     if (res.observed)
         acc.observed.set(res.observed.slot, res.observed.fp);
+    acc.newKeys.push(...res.newKeys);
 }
 /** A fresh, empty {@link Execution}. */
 function emptyExecution(brokeEarly = false) {
-    return { checks: [], runs: [], observed: new Map(), brokeEarly };
+    return { checks: [], runs: [], observed: new Map(), newKeys: [], brokeEarly };
 }
 /**
- * Scheduling coordinates for a check on D1's line: the group `rank` (firsts 0, the
- * numeric line 1, singles 2, lasts 3) and its position on the numeric line
- * (`'any'`/`'middle'` sit at 0 — v1's conservative placement). This must agree
+ * Scheduling coordinates for a check on the order line: the group `rank` (firsts 0,
+ * the numeric line 1, singles 2, lasts 3) and its position on the numeric line
+ * (`'any'`/`'middle'` sit at 0 — the conservative placement). This must agree
  * with `config.ts`'s group sort, which already put `selected` in exactly this
  * sequence; here it only re-derives the wave *boundaries* the sort collapsed.
  */
@@ -547,16 +691,16 @@ async function runPool(items, width, worker) {
     await Promise.all(workers);
 }
 /**
- * `--bail`: the flat sequential path (D6). Checks run one at a time in D1's group
- * order and the run stops at the first *executed* failure — fail-fast is
+ * `--bail`: the flat sequential path. Checks run one at a time in group order
+ * and the run stops at the first *executed* failure — fail-fast is
  * incompatible with already-launched concurrent work, so `--concurrency` is moot
  * here (the caller notes it if one was passed). For the default set (all `'any'`)
- * this is exactly today's cheapest-first order.
+ * this is exactly the cheapest-first order.
  */
 async function executeBail(selected, ctx) {
     const acc = emptyExecution();
     for (const r of selected) {
-        // oxlint-disable-next-line no-await-in-loop -- --bail is fail-fast: checks run one at a time so the run can stop at the first failure (D6).
+        // oxlint-disable-next-line no-await-in-loop -- --bail is fail-fast: checks run one at a time so the run can stop at the first failure.
         const res = await runSelectedCheck(r, ctx);
         collect(res, acc);
         if (res.run && !res.entry.ok)
@@ -565,17 +709,17 @@ async function executeBail(selected, ctx) {
     return acc;
 }
 /**
- * The wave scheduler (D1): run each wave's members concurrently through the pool,
+ * The wave scheduler: run each wave's members concurrently through the pool,
  * with a barrier between waves. Results are placed by their `selected` index and
  * assembled in that order afterwards, so the report is deterministic regardless
- * of which check finishes first (D7). Every selected check runs — there is no
+ * of which check finishes first. Every selected check runs — there is no
  * early stop off the `--bail` path.
  */
 async function executeWaves(selected, ctx) {
     const indexed = selected.map((r, i) => ({ r, i }));
     const results = Array.from({ length: selected.length });
     for (const wave of partitionWaves(indexed)) {
-        // oxlint-disable-next-line no-await-in-loop -- the between-values barrier (D1): a wave runs to completion before the next distinct order value begins.
+        // oxlint-disable-next-line no-await-in-loop -- the between-values barrier: a wave runs to completion before the next distinct order value begins.
         await runPool(wave, ctx.concurrency, async ({ r, i }) => { results[i] = await runSelectedCheck(r, ctx); });
     }
     const acc = emptyExecution();
@@ -595,12 +739,12 @@ function executeChecks(selected, ctx) {
 /**
  * Whether this run saw less than the full pipeline — an `--only`/`--skip`/
  * `--changed` filter or an early `--bail` break. The ratchet is gated off for
- * these: an unobserved diagnostic must not be mistaken for a fixed one (a1).
+ * these: an unobserved diagnostic must not be mistaken for a fixed one.
  */
 function isPartialRun(options, changed, brokeEarly) {
     return (options.only ?? null) !== null || (options.skip?.length ?? 0) > 0 || changed || brokeEarly;
 }
-/** On a fully-observed run, prune grandfathered diagnostics now fixed (shrink-only, atomic). */
+/** On a fully observed run, prune grandfathered diagnostics now fixed (shrink-only, atomic). */
 async function maybeRatchet(cwd, baseline, observed, restricted, json, stderr) {
     if (!baseline || restricted)
         return;
@@ -612,6 +756,26 @@ async function maybeRatchet(cwd, baseline, observed, restricted, json, stderr) {
         writeLine(stderr, `\nbaseline: ratcheted ${BASELINE_FILE} to ${countBaselineKeys(pruned)} grandfathered diagnostic(s)`);
     }
 }
+/**
+ * How much of the selection actually ran, said only when it was not all of it.
+ *
+ * `✔ all checks passed` is a true sentence about the checks that ran and a
+ * misleading one about the repo, and the gap is invisible at exactly the moment
+ * it matters most: a repo that configures almost nothing reports the same
+ * confident green as one that configures everything. `--strict` does not catch
+ * this, and cannot — its floor is *zero* checks, which a slot like `links` that
+ * needs no tool keeps a repo off by itself.
+ *
+ * Only skipped slots are counted here. The per-slot `○ … skip <reason>` lines
+ * are already on screen above; this is the one line someone scrolled past them
+ * to read.
+ */
+function coverage(summary, checks) {
+    const skipped = checks.length - summary.checks_run;
+    if (skipped <= 0)
+        return '';
+    return ` — only ${summary.checks_run} of ${checks.length} checks ran, ${skipped} skipped`;
+}
 /** Print the human run summary: the vacuous-green warning, the status line, and artifact paths. */
 function reportSummary(stderr, summary, checks, adapters, digestWritten) {
     if (summary.checks_run === 0)
@@ -620,7 +784,8 @@ function reportSummary(stderr, summary, checks, adapters, digestWritten) {
     const status = summary.checks_run === 0
         ? '⚠ no checks ran'
         : summary.ok ? '✔ all checks passed' : '✘ one or more checks failed';
-    writeLine(stderr, `${status} in ${summary.total_duration_ms}ms`);
+    const ran = summary.checks_run === 0 ? '' : coverage(summary, checks);
+    writeLine(stderr, `${status} in ${summary.total_duration_ms}ms${ran}`);
     writeLine(stderr, 'report: .check/summary.json');
     if (digestWritten)
         writeLine(stderr, 'digest: .check/digest.md');
@@ -639,34 +804,60 @@ function computeExitCode(summary, strict, json, stderr) {
     }
     return summary.ok ? 0 : 1;
 }
+/**
+ * On a red run, the best-effort recover hint: when the run's new-not-in-baseline
+ * findings were grandfathered in a recent committed baseline, one stderr line
+ * says so. The difference between "a wall of new debt" and "a merge dropped
+ * baseline entries" is a diagnosis the run output alone cannot make — and this
+ * is the moment someone is actually reading it. Strictly bounded and silent on
+ * any failure (see {@link historicalHint}); a hint must never slow or break a run.
+ */
+async function maybeRecoverHint(ctx, ok, newKeys) {
+    if (ok || newKeys.length === 0)
+        return;
+    const hint = await historicalHint(ctx.cwd, newKeys);
+    if (hint === null)
+        return;
+    writeLine(ctx.stderr, `hint: ${hint.matched} of ${hint.total} new finding(s) were grandfathered until ${hint.shortSha} — a merge may have dropped baseline entries; see \`checkride recover\`\n`);
+}
 /** Run the selected checks against `cwd`, persist output, write the summary. */
 export async function runChecks(options) {
-    const ctx = resolveRunContext(options);
-    const resolved = resolveChecks({ slots: ctx.slots, adapters: ctx.adapters, config: ctx.config, cwd: ctx.cwd });
+    // Clear the interrupt latch. On the CLI path this is a no-op — the process
+    // re-raises the signal and dies — but `runChecks` is exported, and a
+    // long-lived programmatic consumer that took one SIGINT would otherwise have
+    // every later run silently spawn nothing (`spawnCheck` starts nothing while
+    // latched). A new call necessarily follows the previous one's return, so
+    // there is no in-flight run for this to un-latch.
+    interrupted = false;
+    const base = resolveRunContext(options);
+    const resolved = resolveChecks({ slots: base.slots, adapters: base.adapters, config: base.config, cwd: base.cwd });
     // A usage error before any side effect: no `.check/` dir, no run, exit 2.
     validateSelection(resolved, options);
-    await mkdir(join(ctx.cwd, '.check'), { recursive: true });
+    await mkdir(join(base.cwd, '.check'), { recursive: true });
     const selected = selectChecks(resolved, options);
+    // The status-line column is sized once the selection is known, so a long
+    // custom-check name widens the column instead of overflowing it.
+    const ctx = { ...base, nameWidth: nameWidth(selected) };
     if (!ctx.json)
         writeLine(ctx.stderr, `\nRunning ${selected.length} check(s)...\n`);
-    // `--bail` is fail-fast sequential (D6); a `--concurrency > 1` passed alongside
+    // `--bail` is fail-fast sequential; a `--concurrency > 1` passed alongside
     // is safe but moot, so say so once — not a usage error, the run just goes slow.
     if (ctx.bail && (options.concurrency ?? 0) > 1 && !ctx.json) {
         writeLine(ctx.stderr, '--concurrency ignored under --bail (fail-fast runs sequentially).');
     }
-    // `total_duration_ms` is wall-clock of the execution phase (D7), so measure
+    // `total_duration_ms` is wall-clock of the execution phase, so measure
     // around it rather than summing per-check durations (which diverge under
     // concurrency). The report array is assembled in `selected` order, not
     // completion order, so it stays byte-reproducible regardless of interleaving.
     const startedAt = performance.now();
-    const { checks, runs, observed, brokeEarly } = await executeChecks(selected, ctx);
+    const { checks, runs, observed, newKeys, brokeEarly } = await executeChecks(selected, ctx);
     const totalDurationMs = Math.round(performance.now() - startedAt);
     await maybeRatchet(ctx.cwd, ctx.baseline, observed, isPartialRun(options, ctx.changed, brokeEarly), ctx.json, ctx.stderr);
     const summary = buildSummary(checks, totalDurationMs);
     await writeFileAtomic(join(ctx.cwd, '.check', 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`);
     // `--digest`: write (or, on green, clear) the token-bounded failure excerpt.
     // A file beside summary.json, never a stdout stream, so the machine-output
-    // split holds (C5). Raw `.check/<slot>.json` files are already persisted and
+    // split holds. Raw `.check/<slot>.json` files are already persisted and
     // untouched — the digest only reads them.
     const digestWritten = (options.digest ?? false) ? await writeDigest(ctx.cwd, runs, checks) : false;
     if (ctx.json) {
@@ -674,6 +865,13 @@ export async function runChecks(options) {
     }
     else {
         reportSummary(ctx.stderr, summary, checks, ctx.adapters, digestWritten);
+        // A mangled committed baseline (a botched merge, usually) masks nothing, so
+        // every grandfathered finding above reported red — say so where the person
+        // reading the wall of red will actually look, right under the summary.
+        if (ctx.baselineState === 'unparseable') {
+            writeLine(ctx.stderr, `baseline: ${BASELINE_FILE} is present but unparseable — possibly a botched merge; grandfathered findings report red. See \`checkride recover\`.\n`);
+        }
+        await maybeRecoverHint(ctx, summary.ok, newKeys);
     }
     const exitCode = computeExitCode(summary, options.strict ?? false, ctx.json, ctx.stderr);
     return { ok: summary.ok, summary, exitCode, runs };
@@ -712,13 +910,14 @@ export async function runFix(options) {
         return { ok: true, exitCode: 0, ran: [] };
     }
     const ran = [];
+    const width = nameWidth(fixable);
     let ok = true;
     for (const r of fixable) {
         const adapter = r.adapter;
         if (!adapter)
             continue;
-        writeLine(stderr, `  ▸ fix ${r.slot.padEnd(8)} (${adapter.name})`);
-        // oxlint-disable-next-line no-await-in-loop -- fixers mutate the working tree; running them sequentially prevents two (e.g. oxlint --fix and prettier --write) racing on the same files.
+        writeLine(stderr, `  ▸ fix ${r.slot.padEnd(width)} (${adapter.name})`);
+        // oxlint-disable-next-line no-await-in-loop -- fixers mutate the working tree; running them sequentially prevents two (for example oxlint --fix and prettier --write) racing on the same files.
         const outcome = await fixRunner(adapter, { cwd, pm });
         ran.push(adapter.name);
         writeLine(stderr, outcome.ok ? `  ✔ ${r.slot}` : `  ✘ ${r.slot} (exit ${outcome.exit_code})`);