plumbbob 0.8.13 → 0.8.17

package/node_modules/checkride/dist/orchestrator.js

@@ -7,16 +7,20 @@
  * diagnostics — agents read the per-tool JSON directly.
  */
 import { spawn } from 'node:child_process';
-import { mkdir } from 'node:fs/promises';
+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, fingerprint, loadBaseline, ratchet, writeBaseline, } from './baseline/index.js';
+import { applyBaseline, BASELINE_FILE, baselinesEqual, countBaselineKeys, fallowVerdict, fingerprint, loadBaseline, ratchet, 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 { checkSmoke } from './smoke.js';
+import { checkSnippets } from './snippets.js';
 /**
  * Port of the interim `select_checks`: only/skip/opt-in selection by slot name.
  * An opt-in slot runs when `--all`/`--include` names it, or when it was
@@ -37,6 +41,25 @@ export function selectChecks(resolved, flags) {
         return true;
     });
 }
+/**
+ * Reject unknown slot names in `--only`/`--skip`/`--include`. A typo like
+ * `--only lints` used to 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.
+ */
+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));
+        if (unknown.length === 0)
+            continue;
+        const named = unknown.map((n) => `'${n}'`).join(', ');
+        const noun = unknown.length > 1 ? 'slots' : 'slot';
+        throw new Error(`unknown ${noun} ${named} in --${flag}. Valid slots: ${[...valid].join(', ')}.`);
+    }
+}
 /** Append an adapter's `changedArgs` under `--changed` (otherwise base args). */
 export function runtimeArgs(adapter, changed) {
     if (changed && adapter.changedArgs)
@@ -51,22 +74,112 @@ export function runtimeArgs(adapter, changed) {
  * disables the cap.
  */
 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
+ * oversubscribing every core is worse than a conservative cap; one reserved
+ * core keeps the machine responsive. Override with `--concurrency`.
+ */
+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.
+    }
+}
+/**
+ * Process groups of checks currently in flight: pid → a promise that settles
+ * when that child's `close` fires. `spawnCheck` registers each spawn and
+ * unregisters it on close; `killLiveChecks` walks the registry to reap
+ * everything when the CLI takes a fatal signal.
+ */
+const liveChecks = new Map();
+/**
+ * One-way interrupt latch. Between `killLiveChecks` reaping the registry and
+ * the CLI re-raising the fatal signal, the still-running `runChecks` loop gets
+ * control back (the killed check's outcome resolves) and would spawn the next
+ * check — a fresh detached process group that outlives the dying CLI as
+ * exactly the orphan the cleanup exists to prevent. Once latched, `spawnCheck`
+ * starts nothing new.
+ */
+let interrupted = false;
+/**
+ * Reap every in-flight check before the process dies: SIGTERM each live
+ * process group (grandchildren included — see `killGroup`), escalate to
+ * SIGKILL after `KILL_GRACE_SECONDS` for a group that won't die politely, and
+ * resolve once every group has closed or been SIGKILLed. The CLI's
+ * SIGINT/SIGTERM handlers await this and then re-raise — cleanup first, the
+ * signal's default exit semantics after.
+ */
+export async function killLiveChecks() {
+    interrupted = true;
+    await Promise.all([...liveChecks.entries()].map(async ([pid, closed]) => {
+        killGroup(pid, 'SIGTERM');
+        let escalate = null;
+        const grace = new Promise((resolve) => {
+            escalate = setTimeout(() => {
+                killGroup(pid, 'SIGKILL');
+                resolve();
+            }, KILL_GRACE_SECONDS * 1000);
+        });
+        await Promise.race([closed, grace]);
+        if (escalate !== null)
+            clearTimeout(escalate);
+    }));
+}
 /**
  * Spawn one check. A falsy or non-positive `timeoutSec` means no cap (the
- * default cap is applied by the runner, not here). When it fires, the child
- * gets SIGTERM, then SIGKILL after a short grace, and a failed outcome carries
- * a `"timed out after Ns"` note so the slot is recorded failed with its
- * elapsed duration (both timers are always cleared on `close`).
+ * default cap is applied by the runner, not here). When it fires, the check's
+ * whole process group gets SIGTERM, then SIGKILL after a short grace (see
+ * `killGroup` — `detached` + group signal so grandchildren die too), and a
+ * failed outcome carries a `"timed out after Ns"` note so the slot is recorded
+ * failed with its elapsed duration (both timers are always cleared on `close`).
+ * Output is captured with an explicit UTF-8 decoder so a multibyte character
+ * split across two read chunks survives intact rather than decoding to U+FFFD.
+ * Every spawn is registered in `liveChecks` until it closes, so a fatal signal
+ * can reap the lot (`killLiveChecks`); after that interrupt, no new check
+ * starts.
  */
 function spawnCheck(command, args, cwd, timeoutSec) {
     return new Promise((resolveOutcome) => {
+        // Post-interrupt, the process is about to die by the re-raised signal —
+        // starting another detached group here would orphan it (see `interrupted`).
+        if (interrupted) {
+            resolveOutcome({ ok: false, exit_code: -1, stdout: '', stderr: 'interrupted before start\n' });
+            return;
+        }
         const proc = spawn(command, args, {
             cwd,
+            detached: true,
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
         });
+        let resolveClosed = null;
+        if (proc.pid !== undefined) {
+            liveChecks.set(proc.pid, new Promise((resolve) => { resolveClosed = resolve; }));
+        }
+        const unregister = () => {
+            if (proc.pid !== undefined)
+                liveChecks.delete(proc.pid);
+            resolveClosed?.();
+        };
         let stdout = '';
         let stderr = '';
         let timedOut = false;
@@ -74,8 +187,8 @@ function spawnCheck(command, args, cwd, timeoutSec) {
         const timer = timeoutSec && timeoutSec > 0
             ? setTimeout(() => {
                 timedOut = true;
-                proc.kill('SIGTERM');
-                killTimer = setTimeout(() => { proc.kill('SIGKILL'); }, KILL_GRACE_SECONDS * 1000);
+                killGroup(proc.pid, 'SIGTERM');
+                killTimer = setTimeout(() => { killGroup(proc.pid, 'SIGKILL'); }, KILL_GRACE_SECONDS * 1000);
             }, timeoutSec * 1000)
             : null;
         const clearTimers = () => {
@@ -84,14 +197,21 @@ function spawnCheck(command, args, cwd, timeoutSec) {
             if (killTimer)
                 clearTimeout(killTimer);
         };
-        proc.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
-        proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        // A decoded string stream (not raw Buffers): the internal StringDecoder holds
+        // a partial multibyte sequence until the continuation bytes arrive, so `+=`
+        // never concatenates a half-decoded character.
+        proc.stdout.setEncoding('utf8');
+        proc.stderr.setEncoding('utf8');
+        proc.stdout.on('data', (chunk) => { stdout += chunk; });
+        proc.stderr.on('data', (chunk) => { stderr += chunk; });
         proc.on('error', (err) => {
             clearTimers();
+            unregister();
             resolveOutcome({ ok: false, exit_code: -1, stdout: '', stderr: `Failed to spawn: ${err.message}` });
         });
         proc.on('close', (code) => {
             clearTimers();
+            unregister();
             if (timedOut) {
                 const note = `timed out after ${timeoutSec}s`;
                 resolveOutcome({ ok: false, exit_code: -1, stdout, stderr: stderr ? `${stderr}\n${note}` : `${note}\n` });
@@ -108,6 +228,24 @@ const defaultRunner = (resolved, ctx) => {
     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 });
+    }
     const { command, args } = translateExec(adapter.command, runtimeArgs(adapter, ctx.changed), ctx.pm);
     return spawnCheck(command, args, ctx.cwd, timeout);
 };
@@ -129,6 +267,26 @@ async function persistOutput(cwd, adapter, outcome) {
     if (outcome.stderr.trim())
         await writeFileAtomic(join(dir, `${adapter.slot}.stderr.txt`), outcome.stderr);
 }
+/**
+ * Remove a slot's prior `.check/` artifacts before it re-runs, so a later clean
+ * run that emits nothing — or a different stream/form than last time — can't leave
+ * 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).
+ * Runs *before* the check so this run's own tool-written artifacts survive.
+ */
+async function clearSlotOutputs(cwd, adapter) {
+    const dir = join(cwd, '.check');
+    const names = new Set([
+        `${adapter.slot}.stdout.txt`,
+        `${adapter.slot}.stderr.txt`,
+        `${adapter.slot}.json`,
+    ]);
+    if (adapter.outputFile)
+        names.add(adapter.outputFile);
+    await Promise.all([...names].map((f) => rm(join(dir, f), { force: true })));
+}
 function writeLine(out, line) {
     out.write(`${line}\n`);
 }
@@ -151,13 +309,19 @@ function skippedEntry(resolved) {
         output_file: resolved.adapter?.outputFile ?? null,
     };
 }
-function buildSummary(checks) {
+/**
+ * `total_duration_ms` is the wall-clock span of the whole execution phase (D7),
+ * 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).
+ */
+function buildSummary(checks, totalDurationMs) {
     return {
         schema_version: SCHEMA_VERSION,
         timestamp: new Date().toISOString(),
         ok: checks.every((c) => c.ok),
         checks_run: checks.filter((c) => !c.skipped).length,
-        total_duration_ms: checks.reduce((sum, c) => sum + c.duration_ms, 0),
+        total_duration_ms: totalDurationMs,
         checks,
     };
 }
@@ -188,138 +352,330 @@ function warnVacuous(stderr, checks, adapters) {
     writeLine(stderr, '  Run `checkride doctor` for per-slot detail, or add a custom check to');
     writeLine(stderr, '  checkride.config.json. Gates should run with --strict (exit 2 on zero checks).');
 }
-/** Run the selected checks against `cwd`, persist output, write the summary. */
-export async function runChecks(options) {
+/**
+ * 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).
+ */
+export function resolveCommonOptions(options) {
     const cwd = options.cwd ?? process.cwd();
-    const slots = options.slots ?? SLOTS;
-    const adapters = options.adapters ?? ADAPTERS;
-    const config = options.config !== undefined ? options.config : loadConfig(cwd);
-    const stderr = options.stderr ?? process.stderr;
-    const stdout = options.stdout ?? process.stdout;
-    const runner = options.runner ?? defaultRunner;
-    const json = options.json ?? false;
-    const bail = options.bail ?? false;
-    const changed = options.changed ?? false;
-    const timeout = config?.timeout;
-    const pm = options.pm ?? detectPackageManager({ cwd });
-    const baseline = options.baseline !== undefined ? options.baseline : loadBaseline(cwd);
-    await mkdir(join(cwd, '.check'), { recursive: true });
-    const resolved = resolveChecks({ slots, adapters, config, cwd });
-    const selected = selectChecks(resolved, options);
+    return {
+        cwd,
+        slots: options.slots ?? SLOTS,
+        adapters: options.adapters ?? ADAPTERS,
+        config: options.config !== undefined ? options.config : loadConfig(cwd),
+        stdout: options.stdout ?? process.stdout,
+        stderr: options.stderr ?? process.stderr,
+    };
+}
+/** Apply every run default: the common options plus runner, flags, PM, and baseline. */
+function resolveRunContext(options) {
+    const common = resolveCommonOptions(options);
+    return {
+        ...common,
+        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),
+        concurrency: Math.max(1, Math.floor(options.concurrency ?? defaultConcurrency())),
+    };
+}
+/**
+ * Baseline-aware verdict for one slot's outcome. fallow slots derive pass/fail
+ * from the parsed report (its exit code doesn't reliably gate); everything else
+ * masks the adapter's fingerprint. `observed` is non-null only when the run's
+ * findings could be read — the ratchet must never prune from an unreadable run.
+ */
+function maskOutcome(adapter, outcome, baseline, slot) {
+    if (adapter.gate === 'fallow') {
+        const v = fallowVerdict(outcome.stdout, baseline ? (baseline.slots[slot] ?? []) : null);
+        return { ok: v.ok, baselined: v.baselined, newKeys: v.newKeys, reason: v.reason, observed: v.observed ? v.findings : null };
+    }
+    const current = baseline ? fingerprint(adapter.name, outcome.stdout) : null;
+    if (baseline && current !== null) {
+        const adj = applyBaseline(current, baseline.slots[slot] ?? [], outcome.ok);
+        return { ok: adj.ok, baselined: adj.baselined, newKeys: adj.newKeys, reason: null, observed: current };
+    }
+    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, `\nRunning ${selected.length} check(s)...\n`);
-    const checks = [];
-    const runs = [];
-    // Per-slot current fingerprints for slots actually observed this run, and
-    // whether `--bail` cut the loop short — both feed the ratchet's full-run gate.
-    const observed = new Map();
-    let brokeEarly = false;
-    for (const r of selected) {
-        // 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).
-        const unavailable = r.adapter && !isAvailableUnder(r.adapter.command, r.adapter.args, pm);
-        if (r.skip || !r.adapter || unavailable) {
-            const entry = skippedEntry(unavailable ? { ...r, skip: `'${r.adapter?.command} ${r.adapter?.args[0]}' is unavailable under ${pm}` } : r);
-            checks.push(entry);
-            if (!json)
-                writeLine(stderr, `  ○ ${entry.name.padEnd(8)}      skip  ${entry.reason ?? ''}`);
-            continue;
-        }
-        const adapter = r.adapter;
-        if (!json)
-            writeLine(stderr, `  ▸ ${r.slot}  ${adapter.description}`);
-        const start = performance.now();
-        const outcome = await runner(r, { cwd, changed, pm, ...(timeout !== undefined ? { timeout } : {}) });
-        const duration_ms = Math.round(performance.now() - start);
-        runs.push({ slot: r.slot, adapter, outcome });
-        await persistOutput(cwd, adapter, outcome);
-        // Baseline-aware: subtract this slot's grandfathered diagnostics. Masking is
-        // always on (even under a partial run); only the ratchet below is gated. The
-        // raw `.check/<slot>.json` is already persisted untouched — masking changes
-        // the pass/fail verdict, never the authoritative output.
-        let ok = outcome.ok;
-        let baselined = 0;
-        let newKeys = [];
-        const current = baseline ? fingerprint(adapter.name, outcome.stdout) : null;
-        if (baseline && current !== null) {
-            observed.set(r.slot, current);
-            const adj = applyBaseline(current, baseline.slots[r.slot] ?? [], outcome.ok);
-            ({ ok, baselined, newKeys } = adj);
-        }
-        const entry = {
-            name: r.slot,
-            adapter: adapter.name,
-            description: adapter.description,
-            ok,
-            exit_code: outcome.exit_code,
-            duration_ms,
-            output_file: adapter.outputFile,
-            ...(baselined > 0 ? { baselined } : {}),
-        };
-        checks.push(entry);
-        if (!json) {
-            writeLine(stderr, formatStatusLine(entry));
-            if (baselined > 0)
-                writeLine(stderr, `           ${baselined} baselined (grandfathered)`);
-            if (!ok && newKeys.length > 0) {
-                writeLine(stderr, `           ${newKeys.length} new, not in baseline:`);
-                for (const k of newKeys)
-                    writeLine(stderr, `             ${k}`);
-            }
-        }
-        if (!ok && bail) {
-            brokeEarly = true;
-            break;
+        writeLine(stderr, `  ○ ${entry.name.padEnd(8)}      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));
+    if (mask.baselined > 0)
+        writeLine(stderr, `           ${mask.baselined} baselined (grandfathered)`);
+    if (!entry.ok && mask.reason)
+        writeLine(stderr, `           ${mask.reason}`);
+    if (!entry.ok && mask.newKeys.length > 0) {
+        writeLine(stderr, `           ${mask.newKeys.length} new, not in baseline:`);
+        for (const k of mask.newKeys)
+            writeLine(stderr, `             ${k}`);
+    }
+}
+/** Run one active check: clear stale output, run it, persist, and mask against the baseline. */
+async function runOneCheck(r, adapter, ctx) {
+    if (!ctx.json)
+        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.
+    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);
+    // 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.
+    const mask = maskOutcome(adapter, outcome, ctx.baseline, r.slot);
+    const entry = {
+        name: r.slot,
+        adapter: adapter.name,
+        description: adapter.description,
+        ok: mask.ok,
+        exit_code: outcome.exit_code,
+        duration_ms,
+        output_file: adapter.outputFile,
+        ...(mask.baselined > 0 ? { baselined: mask.baselined } : {}),
+    };
+    return { entry, run: { slot: r.slot, adapter, outcome }, mask };
+}
+/**
+ * Run one selected check to a {@link CheckResult} — the concurrency-safe core
+ * 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).
+ */
+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).
+    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 };
+    }
+    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 };
+}
+/** Fold one result into the report accumulators, in call order. */
+function collect(res, acc) {
+    acc.checks.push(res.entry);
+    if (res.run)
+        acc.runs.push(res.run);
+    if (res.observed)
+        acc.observed.set(res.observed.slot, res.observed.fp);
+}
+/** A fresh, empty {@link Execution}. */
+function emptyExecution(brokeEarly = false) {
+    return { checks: [], runs: [], observed: new Map(), 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
+ * 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.
+ */
+const SINGLE_RANK = 2;
+function scheduleGroup(order) {
+    if (order === 'first')
+        return { rank: 0, line: 0 };
+    if (order === 'single')
+        return { rank: SINGLE_RANK, line: 0 };
+    if (order === 'last')
+        return { rank: 3, line: 0 };
+    return { rank: 1, line: typeof order === 'number' ? order : 0 };
+}
+/**
+ * Split the already-sorted `selected` into execution waves: the `'first'` group,
+ * each distinct numeric value, and the `'last'` group each become one concurrent
+ * wave, with a barrier between waves; every `'single'` is its own wave so it runs
+ * with nothing else in flight. Adjacent items share a wave only when their (rank,
+ * line) match and neither is a single.
+ */
+function partitionWaves(items) {
+    const waves = [];
+    let current = [];
+    let prev = null;
+    for (const item of items) {
+        const g = scheduleGroup(item.r.order ?? 'any');
+        const sameWave = prev !== null && prev.rank === g.rank && prev.line === g.line && g.rank !== SINGLE_RANK;
+        if (!sameWave && current.length > 0) {
+            waves.push(current);
+            current = [];
         }
+        current.push(item);
+        prev = g;
     }
-    // Ratchet: on a fully-observed run, prune grandfathered diagnostics now fixed.
-    // A partial run (`--only`/`--skip`/`--changed`) or an early `--bail` break can't
-    // see every slot's full output, so it never prunes — an unobserved diagnostic
-    // must not be mistaken for a fixed one and dropped (a1). Masking still applied
-    // above; only the rewrite is withheld.
-    if (baseline) {
-        const restricted = (options.only ?? null) !== null || (options.skip?.length ?? 0) > 0 || changed || brokeEarly;
-        if (!restricted) {
-            const pruned = ratchet(baseline, observed);
-            if (!baselinesEqual(baseline, pruned)) {
-                await writeBaseline(cwd, pruned);
-                if (!json) {
-                    writeLine(stderr, `\nbaseline: ratcheted ${BASELINE_FILE} to ${countBaselineKeys(pruned)} grandfathered diagnostic(s)`);
-                }
-            }
+    if (current.length > 0)
+        waves.push(current);
+    return waves;
+}
+/**
+ * Run `items` through a pool `width` workers wide: each worker pulls the next
+ * item until the queue drains, so at most `width` run at once. Concurrency is the
+ * worker count; each worker still processes its own items one at a time. `width`
+ * is clamped to at least 1 and never exceeds the item count.
+ */
+async function runPool(items, width, worker) {
+    if (items.length === 0)
+        return;
+    let next = 0;
+    const runWorker = async () => {
+        while (next < items.length) {
+            const item = items[next];
+            next += 1;
+            if (item === undefined)
+                continue;
+            // oxlint-disable-next-line no-await-in-loop -- a worker processes its items in sequence; concurrency is the `width` workers running this loop at once.
+            await worker(item);
         }
+    };
+    const workers = Array.from({ length: Math.max(1, Math.min(width, items.length)) }, () => runWorker());
+    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
+ * 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.
+ */
+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).
+        const res = await runSelectedCheck(r, ctx);
+        collect(res, acc);
+        if (res.run && !res.entry.ok)
+            return { ...acc, brokeEarly: true };
+    }
+    return acc;
+}
+/**
+ * The wave scheduler (D1): 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
+ * 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.
+        await runPool(wave, ctx.concurrency, async ({ r, i }) => { results[i] = await runSelectedCheck(r, ctx); });
+    }
+    const acc = emptyExecution();
+    for (const res of results)
+        if (res)
+            collect(res, acc);
+    return acc;
+}
+/**
+ * Run the selected checks, collecting rows, raw runs, observed fingerprints, and
+ * `--bail` state. `--bail` takes the flat sequential path; every other run waves
+ * on the effective `order` through a bounded pool.
+ */
+function executeChecks(selected, ctx) {
+    return ctx.bail ? executeBail(selected, ctx) : executeWaves(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).
+ */
+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). */
+async function maybeRatchet(cwd, baseline, observed, restricted, json, stderr) {
+    if (!baseline || restricted)
+        return;
+    const pruned = ratchet(baseline, observed);
+    if (baselinesEqual(baseline, pruned))
+        return;
+    await writeBaseline(cwd, pruned);
+    if (!json) {
+        writeLine(stderr, `\nbaseline: ratcheted ${BASELINE_FILE} to ${countBaselineKeys(pruned)} grandfathered diagnostic(s)`);
+    }
+}
+/** 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)
+        warnVacuous(stderr, checks, adapters);
+    writeLine(stderr, '');
+    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`);
+    writeLine(stderr, 'report: .check/summary.json');
+    if (digestWritten)
+        writeLine(stderr, 'digest: .check/digest.md');
+    writeLine(stderr, '');
+}
+/**
+ * The 0/1/2 exit taxonomy. `--strict` turns a vacuous green (zero checks) into a
+ * harness error (exit 2) — a gate must not report "done" on a repo where nothing
+ * was checked.
+ */
+function computeExitCode(summary, strict, json, stderr) {
+    if (strict && summary.checks_run === 0) {
+        if (!json)
+            writeLine(stderr, '--strict: zero checks ran, exiting 2.\n');
+        return 2;
+    }
+    return summary.ok ? 0 : 1;
+}
+/** 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 });
+    // 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 });
+    const selected = selectChecks(resolved, options);
+    if (!ctx.json)
+        writeLine(ctx.stderr, `\nRunning ${selected.length} check(s)...\n`);
+    // `--bail` is fail-fast sequential (D6); 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).');
     }
-    const summary = buildSummary(checks);
-    await writeFileAtomic(join(cwd, '.check', 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`);
+    // `total_duration_ms` is wall-clock of the execution phase (D7), 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 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
     // untouched — the digest only reads them.
-    const digestWritten = (options.digest ?? false) ? await writeDigest(cwd, runs, checks) : false;
-    if (json) {
-        stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+    const digestWritten = (options.digest ?? false) ? await writeDigest(ctx.cwd, runs, checks) : false;
+    if (ctx.json) {
+        ctx.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
     }
     else {
-        if (summary.checks_run === 0)
-            warnVacuous(stderr, checks, adapters);
-        writeLine(stderr, '');
-        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`);
-        writeLine(stderr, 'report: .check/summary.json');
-        if (digestWritten)
-            writeLine(stderr, 'digest: .check/digest.md');
-        writeLine(stderr, '');
-    }
-    // `--strict` turns a vacuous green into a harness error: exit 2, never 0 —
-    // a gate must not report "done" on a repo where nothing was checked.
-    let exitCode = summary.ok ? 0 : 1;
-    if ((options.strict ?? false) && summary.checks_run === 0) {
-        exitCode = 2;
-        if (!json)
-            writeLine(stderr, '--strict: zero checks ran, exiting 2.\n');
+        reportSummary(ctx.stderr, summary, checks, ctx.adapters, digestWritten);
     }
+    const exitCode = computeExitCode(summary, options.strict ?? false, ctx.json, ctx.stderr);
     return { ok: summary.ok, summary, exitCode, runs };
 }
 function spawnInherit(command, args, cwd) {
@@ -329,16 +685,27 @@ function spawnInherit(command, args, cwd) {
         proc.on('close', (code) => { resolveOutcome({ ok: code === 0, exit_code: code ?? -1 }); });
     });
 }
-const defaultFixRunner = (adapter, ctx) => spawnInherit(adapter.command, adapter.fixArgs ?? [], ctx.cwd);
+/**
+ * The command `checkride fix` spawns for one adapter under `pm` — the fix
+ * path's counterpart to `defaultRunner`'s `translateExec` call, so a fix runs
+ * on the same binary the run path does (a canonical `pnpm exec oxlint --fix`
+ * becomes `npx oxlint --fix` under npm). Non-`pnpm exec` fix commands, and
+ * everything under pnpm, pass through unchanged.
+ */
+export function fixInvocation(adapter, pm) {
+    return translateExec(adapter.command, adapter.fixArgs ?? [], pm);
+}
+const defaultFixRunner = (adapter, ctx) => {
+    const { command, args } = fixInvocation(adapter, ctx.pm);
+    return spawnInherit(command, args, ctx.cwd);
+};
 /** Run every active adapter's `fixArgs` (`checkride fix`). */
 export async function runFix(options) {
-    const cwd = options.cwd ?? process.cwd();
-    const slots = options.slots ?? SLOTS;
-    const adapters = options.adapters ?? ADAPTERS;
-    const config = options.config !== undefined ? options.config : loadConfig(cwd);
-    const stderr = options.stderr ?? process.stderr;
+    const { cwd, slots, adapters, config, stderr } = resolveCommonOptions(options);
     const fixRunner = options.fixRunner ?? defaultFixRunner;
+    const pm = options.pm ?? detectPackageManager({ cwd });
     const resolved = resolveChecks({ slots, adapters, config, cwd });
+    validateSelection(resolved, options);
     const fixable = selectChecks(resolved, options).filter((r) => r.adapter?.fixArgs);
     if (fixable.length === 0) {
         writeLine(stderr, 'checkride fix: no active adapters expose a fix command.');
@@ -351,7 +718,8 @@ export async function runFix(options) {
         if (!adapter)
             continue;
         writeLine(stderr, `  ▸ fix ${r.slot.padEnd(8)} (${adapter.name})`);
-        const outcome = await fixRunner(adapter, { cwd });
+        // 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.
+        const outcome = await fixRunner(adapter, { cwd, pm });
         ran.push(adapter.name);
         writeLine(stderr, outcome.ok ? `  ✔ ${r.slot}` : `  ✘ ${r.slot} (exit ${outcome.exit_code})`);
         if (!outcome.ok)