@ultimat3/cli 23.0.0 → 25.0.0

package/src/verify-deadline.ts

@@ -2,10 +2,9 @@
 // tag every process a step starts carries, and the kill that leaves none of them behind. A hung
 // step used to eat the whole CI job timeout and report nothing (#589); now it fails by name.
 
-import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { TEST_TYPES } from '@ultimat3/testing';
 import type { ExecResult, Runner } from './exec';
-import type { Finding } from './output';
+import { execOutput } from './exec';
 import type { VerifyStepName } from './verify-step';
 
 /** The `x.verify.json` key: `{ "stepTimeoutMs": { "unit": 900000 } }`. */
@@ -76,11 +75,47 @@ export const STEP_TAG_ENV = 'ULTIMATE_VERIFY_STEP';
 /** `bun test`-style "the command was stopped" exit, as `timeout(1)` reports it. */
 const EXPIRED_EXIT = 124;
 
+/** A process the kill found, as it was the moment before it died. */
+export interface KilledProcess {
+  readonly pid: number;
+  /** Its argv, clipped — a `bun test` coordinator's names every file of its batch. */
+  readonly command: string;
+}
+
+/** A child the step was still waiting on when it expired. */
+export interface InFlightRun {
+  readonly command: readonly string[];
+  /** Everything it had printed before the kill; absent when it did not settle after it. */
+  readonly output?: string;
+}
+
+/** What a step was doing when its deadline passed — `verify-stalled.ts` turns it into the finding. */
+export interface StepExpiry {
+  readonly killed: readonly KilledProcess[];
+  readonly inFlight: readonly InFlightRun[];
+}
+
+/** A killed child's pipes close with it; this is only the bound on a runner that is not `exec`. */
+const SETTLE_MS = 2_000;
+
+/**
+ * How a `bun test --parallel` worker is told from its coordinator: the flag bun starts each with
+ * (probed on 1.4.0). Killing the WORKERS first is what names the stuck file — the coordinator
+ * outlives them just long enough to print `✗ <file> (worker crashed: SIGKILL)` for whatever each
+ * was holding, in every reporter mode: plain, GitHub Actions' `::group::`, and the failures-only
+ * one an agent's shell switches on. A file's own header line cannot do it — bun prints that as
+ * results stream, so a file stuck in its third test has one.
+ */
+const isTestWorker = (command: string): boolean => command.includes(' --test-worker');
+
+/** How long a coordinator gets to say what its workers were holding before it is killed too. */
+const CRASH_REPORT_MS = 1_500;
+
 export interface StepGuard {
   /** `runner`, with every child tagged — and refusing to start one once the step has expired. */
   readonly runner: Runner;
-  /** Stop the step: no further child starts, and every tagged process is killed. Returns how many. */
-  expire(): Promise<number>;
+  /** Stop the step: no further child starts, every tagged process is killed, and what was in flight is told. */
+  expire(): Promise<StepExpiry>;
 }
 
 /**
@@ -91,13 +126,23 @@ export interface StepGuard {
  *
  * A nested gate (a test that runs `x verify`) appends its tag to the one it inherited, so the
  * outer step's kill still finds the inner step's children.
+ *
+ * Windows reads no process's environment, so there the tag finds nothing: every child's pid is
+ * recorded at spawn (`ExecOptions.onSpawn`) and `expire` tree-kills each one (`taskkillTree`).
  */
 export function guardStep(
   runner: Runner,
   tag: string,
   env: Readonly<Record<string, string | undefined>> = Bun.env,
+  platform: PlatformKill = {},
 ): StepGuard {
   let expired = false;
+  // Keyed by the promise itself: two batches of one step may run the very same argv.
+  const inFlight = new Map<Promise<ExecResult>, readonly string[]>();
+  // Every child's pid, recorded the moment it exists and dropped when its run settles (a settled
+  // pid may be reused). Windows reads no process's environment, so this is the step's only handle.
+  const spawned = new Map<number, readonly string[]>();
+  const windows = (platform.platform ?? process.platform) === 'win32';
   const inherited = env[STEP_TAG_ENV];
   const value = inherited === undefined || inherited === '' ? tag : `${inherited} ${tag}`;
   return {
@@ -114,15 +159,108 @@ export function guardStep(
           durationMs: 0,
         };
       }
-      return runner(command, { ...options, env: { ...options.env, [STEP_TAG_ENV]: value } });
+      let pid: number | undefined;
+      const run = runner(command, {
+        ...options,
+        env: { ...options.env, [STEP_TAG_ENV]: value },
+        onSpawn: (spawnedPid) => {
+          pid = spawnedPid;
+          spawned.set(spawnedPid, command);
+          options.onSpawn?.(spawnedPid);
+        },
+      });
+      inFlight.set(run, command);
+      try {
+        return await run;
+      } finally {
+        inFlight.delete(run);
+        if (pid !== undefined) spawned.delete(pid);
+      }
     },
-    async expire(): Promise<number> {
+    async expire(): Promise<StepExpiry> {
       expired = true;
-      return killTagged(tag);
+      // Before the kill: a killed child settles its runner call, which takes it off the map.
+      const waiting = [...inFlight];
+      if (windows) {
+        const killed = await killTrees(spawned, platform.killTree ?? taskkillTree);
+        return { killed, inFlight: await settleAll(waiting) };
+      }
+      const workers = await killTagged(tag, undefined, isTestWorker);
+      if (workers.length > 0) {
+        await raceDeadline(Promise.allSettled(waiting.map(([run]) => run)), CRASH_REPORT_MS);
+      }
+      const rest = await killTagged(tag);
+      const killed = [...workers, ...rest.filter((one) => workers.every((w) => w.pid !== one.pid))];
+      // After it: the kill closed the child's pipes, so its call now resolves with everything it
+      // had printed — for `bun test`, the crash line of each file a worker was holding.
+      return { killed, inFlight: await settleAll(waiting) };
     },
   };
 }
 
+/** What each child had printed, once the kill closed its pipes — or just its argv past `SETTLE_MS`. */
+function settleAll(
+  waiting: readonly (readonly [Promise<ExecResult>, readonly string[]])[],
+): Promise<readonly InFlightRun[]> {
+  return Promise.all(
+    waiting.map(async ([run, command]): Promise<InFlightRun> => {
+      const raced = await raceDeadline(run.then(execOutput), SETTLE_MS).catch(() => undefined);
+      return raced === undefined || raced.timedOut ? { command } : { command, output: raced.value };
+    }),
+  );
+}
+
+/** Kills `pid` and every process under it; answers whether it did. */
+export type KillTree = (pid: number) => Promise<boolean>;
+
+/** The platform a guard kills on, injectable so the Windows path runs on any host's tests. */
+export interface PlatformKill {
+  /** `process.platform` unless a test names one. */
+  readonly platform?: string;
+  /** Windows' tree kill. Absent is `taskkill /T /F /PID`. */
+  readonly killTree?: KillTree;
+}
+
+/**
+ * Windows: `taskkill /T /F` — the tree under the pid, forced. POSIX's tag sweep cannot run there
+ * (no process exposes its environment) and `process.kill` ends one process, leaving a
+ * `bun test --parallel` coordinator's workers behind. Bounded like `ps`, for the same reason.
+ */
+export async function taskkillTree(pid: number): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(['taskkill', '/T', '/F', '/PID', String(pid)], {
+      stdout: 'ignore',
+      stderr: 'ignore',
+      timeout: PS_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
+    });
+    return (await proc.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every recorded child, each with its tree, named by the argv it was started with. A child that
+ * already exited is not recorded — its run settled — so what is left is what was still running.
+ * A grandchild whose parent already exited is out of reach here: Windows keeps no tag to find it.
+ */
+export async function killTrees(
+  spawned: ReadonlyMap<number, readonly string[]>,
+  killTree: KillTree,
+): Promise<readonly KilledProcess[]> {
+  const killed: KilledProcess[] = [];
+  for (const [pid, command] of spawned) {
+    if (pid === process.pid || !(await killTree(pid))) continue;
+    const line = command.join(' ');
+    killed.push({
+      pid,
+      command: line.length > COMMAND_CHARS ? `${line.slice(0, COMMAND_CHARS)}…` : line,
+    });
+  }
+  return killed;
+}
+
 /** One process and the environment it was started with, as the platform reports it. */
 export interface ProcessEnviron {
   readonly pid: number;
@@ -162,19 +300,33 @@ async function procfsProcesses(): Promise<readonly ProcessEnviron[] | undefined>
   return out;
 }
 
+/** One `ps` listing; past this the sweep answers what it has rather than outliving the step. */
+const PS_TIMEOUT_MS = 10_000;
+
+const PS_LISTING: readonly string[] = ['ps', 'axeww', '-o', 'pid=,command='];
+
 /**
  * Elsewhere (macOS, BSD): `ps` in its BSD spelling — `e` prints each process's environment after
  * its command, `ww` never truncates it. The same spelling answers on Linux, which is where it is
  * tested; procfs is preferred there because it needs no process and no parsing.
  */
-export async function psProcesses(): Promise<readonly ProcessEnviron[]> {
+export async function psProcesses(
+  argv: readonly string[] = PS_LISTING,
+  timeoutMs: number = PS_TIMEOUT_MS,
+): Promise<readonly ProcessEnviron[]> {
   try {
-    const ps = Bun.spawn(['ps', 'axeww', '-o', 'pid=,command='], {
+    const ps = Bun.spawn([...argv], {
       stdout: 'pipe',
       stderr: 'ignore',
+      // The deadline's own sweep: a `ps` that hangs would hang the step it exists to end. SIGKILL,
+      // never the default SIGTERM, which a wedged child may ignore and so outlive the bound.
+      timeout: timeoutMs,
+      killSignal: 'SIGKILL',
     });
-    const text = await new Response(ps.stdout).text();
-    await ps.exited;
+    const [text, code] = await Promise.all([new Response(ps.stdout).text(), ps.exited]);
+    // A listing cut short by the timeout is NOT a smaller table: read as one, a tagged worker past
+    // the cut is "nothing left to kill". Unreadable, exactly like a `ps` that never ran.
+    if (code !== 0) return [];
     return text.split('\n').flatMap((line) => {
       const match = /^\s*(\d+)\s+(.*)$/.exec(line);
       return match === null ? [] : [{ pid: Number(match[1]), environ: match[2] ?? '' }];
@@ -186,26 +338,65 @@ export async function psProcesses(): Promise<readonly ProcessEnviron[]> {
 
 const SWEEPS = 5;
 
+const COMMAND_CHARS = 240;
+
+/**
+ * A process's argv, read BEFORE it is killed — afterwards there is nothing to read. procfs where
+ * there is one, `ps` otherwise; a process that is already gone is named by its pid alone.
+ */
+async function commandOf(pid: number): Promise<string> {
+  let text = await Bun.file(`/proc/${String(pid)}/cmdline`)
+    .text()
+    .catch(() => '');
+  if (text === '') {
+    try {
+      const ps = Bun.spawn(['ps', '-ww', '-o', 'command=', '-p', String(pid)], {
+        stdout: 'pipe',
+        stderr: 'ignore',
+        timeout: PS_TIMEOUT_MS,
+        killSignal: 'SIGKILL',
+      });
+      text = await new Response(ps.stdout).text();
+      await ps.exited;
+    } catch {
+      text = '';
+    }
+  }
+  const line = text.split('\0').join(' ').trim();
+  return line.length > COMMAND_CHARS ? `${line.slice(0, COMMAND_CHARS)}…` : line;
+}
+
 /**
  * SIGKILL every process carrying `tag`, and sweep again until a pass finds none: a worker can fork
  * between the listing and its own death. Never this process — a nested gate carries the outer tag.
+ * Returns the processes it killed, each with the command line it was running.
  */
 export async function killTagged(
   tag: string,
   /** The process table. Absent is this platform's: procfs where there is one, `ps` otherwise. */
   list: () => Promise<readonly ProcessEnviron[]> = async () =>
     (await procfsProcesses()) ?? (await psProcesses()),
-): Promise<number> {
-  const killed = new Set<number>();
+  /** Kill only the processes whose command line this accepts. Absent kills every tagged one. */
+  only?: (command: string) => boolean,
+): Promise<readonly KilledProcess[]> {
+  const killed = new Map<number, KilledProcess>();
+  // Read once per pid and BEFORE the first signal: a worker exits on its own the moment its
+  // coordinator dies, and one read between two kills would find it already gone.
+  const commands = new Map<number, string>();
   for (let sweep = 0; sweep < SWEEPS; sweep += 1) {
     const processes = await list();
-    const found = taggedPids(processes, tag).filter((pid) => pid !== process.pid);
+    const tagged = taggedPids(processes, tag).filter((pid) => pid !== process.pid);
+    for (const pid of tagged) {
+      if (!commands.has(pid)) commands.set(pid, await commandOf(pid));
+    }
+    const found =
+      only === undefined ? tagged : tagged.filter((pid) => only(commands.get(pid) ?? ''));
     const fresh = found.filter((pid) => !killed.has(pid));
     if (found.length === 0) break;
     for (const pid of found) {
       try {
         process.kill(pid, 'SIGKILL');
-        killed.add(pid);
+        if (!killed.has(pid)) killed.set(pid, { pid, command: commands.get(pid) ?? '' });
       } catch {
         // Already gone between the listing and the signal — which is the outcome wanted.
       }
@@ -214,26 +405,9 @@ export async function killTagged(
     if (fresh.length === 0) break;
     await Bun.sleep(20);
   }
-  return killed.size;
+  return [...killed.values()];
 }
 
-/**
- * A step that ran past its deadline, on that step's own line. `command` is the gate as it was
- * invoked here (`x verify`, or `bun run verify` at the framework root), so the fix runs where the
- * finding was raised.
- */
-export const stepTimeoutFinding = (
-  step: VerifyStepName,
-  ms: number,
-  killed: number,
-  command: string,
-): Finding => ({
-  code: 'X_VERIFY_STEP_TIMEOUT',
-  cause: `step "${step}" did not finish within its ${String(ms)} ms deadline, so it was stopped and ${String(killed)} process(es) it had started were killed`,
-  fix: `${command} --only ${step} --json   # reproduce it alone; if it legitimately needs longer, edit x.verify.json — add "${STEP_TIMEOUT_FIELD}": { "${step}": <milliseconds> }`,
-  docs: ERROR_DOCS_URL,
-});
-
 /** `work`, or `{ timedOut: true }` once `ms` passes. The abandoned promise is never unhandled. */
 export async function raceDeadline<T>(
   work: Promise<T>,

package/src/verify-merge.ts

@@ -16,7 +16,7 @@
 import { existsSync } from 'node:fs';
 // why: Bun ships no path-join primitive.
 import { join } from 'node:path';
-import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderThrowable, UltimateError } from '@ultimat3/core';
 import { APP_CONFIG_FILE } from './app-root';
 import { judgeCoverage } from './coverage-floor';
 import type { CoverageMap } from './coverage-lcov';
@@ -24,27 +24,29 @@ import { decodeCoverage, mergeCoverage } from './coverage-lcov';
 import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
 import type { TestCounts } from './test-counts';
-import { VerifyMergeInputError } from './verify-errors';
 import type { VerifyFloor } from './verify-floor';
 import { floorRequires, skippedSuiteFinding } from './verify-floor';
+import type { PartStep } from './verify-part-step';
+import { readPartStep } from './verify-part-step';
 import { verifySummary } from './verify-run';
+import { corpusHash } from './verify-shard';
 import { GATE_COMMAND, VERIFY_STEP_NAMES } from './verify-step';
 
-interface PartStep {
-  readonly name: string;
-  readonly ok: boolean;
-  readonly durationMs: number;
-  readonly skipped: boolean;
-  readonly findings: readonly Finding[];
-  readonly workers?: number;
-  readonly tests?: TestCounts;
-  readonly output?: string;
-  readonly shard?: {
-    readonly index: number;
-    readonly total: number;
-    readonly corpusHash: string;
-    readonly files: readonly string[];
-  };
+/**
+ * A part handed to `x verify merge` that is not an `x verify --json` document. `command` is the
+ * entry that raised it — `bun run verify` at the framework root, where `x verify` answers
+ * `X_NOT_IN_APP` — so the `fix:` runs where it was raised.
+ */
+export class VerifyMergeInputError extends UltimateError {
+  constructor(input: { file: string; reason: string; sourceError?: unknown; command?: string }) {
+    const command = input.command ?? GATE_COMMAND;
+    super({
+      code: 'X_VERIFY_MERGE_INPUT',
+      cause: `${command} merge: ${input.file} ${input.reason}`,
+      fix: `${command} --only unit --json > part.json   # one document per part, the last line of stdout`,
+      ...(input.sourceError === undefined ? {} : { sourceError: input.sourceError }),
+    });
+  }
 }
 
 export interface VerifyPart {
@@ -70,8 +72,9 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
 
 /**
- * The LAST non-empty line that parses: `bin/check --json` prints the build's document and then
- * the gate's, and a reader takes the last one.
+ * The LAST non-empty line, and only it: `bin/check --json` prints the build's document and then
+ * the gate's. Never "the last line that parses" — a part whose tail is not the gate's document is
+ * a truncated or appended upload, and falling back to an earlier line would believe it.
  */
 export function parsePart(file: string, text: string, command: string = GATE_COMMAND): VerifyPart {
   const lines = text
@@ -100,14 +103,9 @@ export function parsePart(file: string, text: string, command: string = GATE_COM
   const data = isRecord(doc['data']) ? doc['data'] : {};
   const steps: PartStep[] = [];
   for (const raw of doc['steps'] as unknown[]) {
-    if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['ok'] !== 'boolean') {
-      throw new VerifyMergeInputError({
-        file,
-        reason: 'holds a step without a name and ok',
-        command,
-      });
-    }
-    steps.push(raw as unknown as PartStep);
+    const step = readPartStep(raw);
+    if (typeof step === 'string') throw new VerifyMergeInputError({ file, reason: step, command });
+    steps.push(step);
   }
   const coverage = new Map<string, CoverageMap>();
   for (const [step, entry] of Object.entries(isRecord(data['coverage']) ? data['coverage'] : {})) {
@@ -134,15 +132,41 @@ export function parsePart(file: string, text: string, command: string = GATE_COM
 /** A gap finding, with a fix spelled for the entry that raised it. */
 type Gap = (cause: string, at?: string) => Finding;
 
-const gapFor =
-  (command: string): Gap =>
-  (cause, at) => ({
-    code: 'X_VERIFY_MERGE_INCOMPLETE',
-    cause,
-    fix: `${command} merge parts/*.json --json   # after every CI job uploaded its part`,
-    docs: ERROR_DOCS_URL,
-    ...(at === undefined ? {} : { at }),
-  });
+/**
+ * The gap kinds a merge can find. `present` is a document that arrived and disagrees with the
+ * others; `absent` is one that never arrived at all — GitHub failing to acquire a hosted runner
+ * leaves the job `cancelled` with no steps and no upload, and "missing shard 2/3" alone read as a
+ * shard that ran and died. The two are fixed differently: the first is debugged, the second re-run.
+ */
+interface Gaps {
+  readonly present: Gap;
+  readonly absent: Gap;
+}
+
+/** Said of every absent gap, so it can never be mistaken for a failure the part reported. */
+const NEVER_ARRIVED =
+  'its result never arrived — its CI job never ran or never uploaded (cancelled before a step, or no runner acquired); this is not a failure it reported';
+
+const gapsFor = (command: string): Gaps => {
+  const finding =
+    (fix: string): Gap =>
+    (cause, at) => ({
+      code: 'X_VERIFY_MERGE_INCOMPLETE',
+      cause,
+      fix,
+      docs: ERROR_DOCS_URL,
+      ...(at === undefined ? {} : { at }),
+    });
+  return {
+    present: finding(
+      `${command} merge parts/*.json --json   # after every CI job uploaded its part`,
+    ),
+    // The merge is still what proves the gate whole; what it waits on is a re-run, not a fix.
+    absent: finding(
+      `${command} merge parts/*.json --json   # after re-running the job that never reported: gh run rerun <run-id> --failed`,
+    ),
+  };
+};
 
 /** The step every part's coverage facts belong to. */
 const COVERED_STEP = 'unit';
@@ -184,20 +208,54 @@ const sumCounts = (steps: readonly PartStep[]): TestCounts | undefined => {
   };
 };
 
+/**
+ * The shards' `files` must PARTITION the corpus they all hashed: each file in exactly one shard,
+ * and the union hashing to `corpusHash`. Agreeing on the hash is not agreeing on the split — shard
+ * 1/2 round-robin beside 2/2 with `--timings` ran one file twice and another nowhere, green.
+ */
+function partitionGaps(
+  name: string,
+  sharded: readonly { readonly step: PartStep }[],
+  gap: Gap,
+): readonly Finding[] {
+  const counts = new Map<string, number>();
+  for (const entry of sharded) {
+    for (const file of entry.step.shard?.files ?? []) counts.set(file, (counts.get(file) ?? 0) + 1);
+  }
+  const twice = [...counts].filter(([, count]) => count > 1).map(([file]) => file);
+  const found: Finding[] = [];
+  if (twice.length > 0) {
+    found.push(gap(`step "${name}" ran ${twice.join(', ')} in more than one shard`, name));
+  }
+  // A list's fingerprint, not a credential: what the shards ran against what they all counted.
+  const ranCorpus = corpusHash([...counts.keys()]);
+  const countedCorpus = sharded[0]?.step.shard?.corpusHash;
+  if (ranCorpus !== countedCorpus) {
+    found.push(
+      gap(
+        `step "${name}"'s shards ran ${String(counts.size)} distinct file(s), which is not the corpus they hashed — some file ran in no shard; every shard must split one list the same way (all with --timings, or none)`,
+        name,
+      ),
+    );
+  }
+  return found;
+}
+
 /** One step's entries from every part, folded into one step result and its gaps. */
 function mergeStep(
   name: string,
   entries: readonly { readonly part: string; readonly step: PartStep }[],
   floor: VerifyFloor | undefined,
-  gap: Gap,
+  kinds: Gaps,
   rider: MergeRiders[string] | undefined,
 ): StepResult {
+  const gap = kinds.present;
   if (entries.length === 0) {
     return {
       name,
       ok: false,
       durationMs: 0,
-      findings: [gap(`step "${name}" is in no part — no CI job ran it`, name)],
+      findings: [kinds.absent(`step "${name}" is in no part: ${NEVER_ARRIVED}`, name)],
     };
   }
   const sharded = entries.filter((entry) => entry.step.shard !== undefined);
@@ -237,8 +295,8 @@ function mergeStep(
     const doubled = [...seen].filter(([, count]) => count > 1).map(([index]) => index);
     if (missing.length > 0) {
       gaps.push(
-        gap(
-          `step "${name}" is missing shard(s) ${missing.map((i) => `${String(i)}/${String(total)}`).join(', ')}`,
+        kinds.absent(
+          `step "${name}" is missing shard(s) ${missing.map((i) => `${String(i)}/${String(total)}`).join(', ')}: ${NEVER_ARRIVED}`,
           name,
         ),
       );
@@ -246,6 +304,8 @@ function mergeStep(
     if (doubled.length > 0) {
       gaps.push(gap(`step "${name}" has shard(s) ${doubled.join(', ')} more than once`, name));
     }
+    // Only over a complete, single-corpus set — any gap above already explains a partial union.
+    if (gaps.length === 0) gaps.push(...partitionGaps(name, sharded, gap));
   }
   const steps = entries.map((entry) => entry.step);
   const tests = sumCounts(steps);
@@ -262,6 +322,8 @@ function mergeStep(
       .map((step) => step.output as string),
     ...(rider?.output === undefined ? [] : [rider.output]),
   ].join('\n');
+  // Every part's advice, once each and in the order the parts reported it.
+  const warnings = [...new Set(steps.flatMap((step) => step.warnings ?? []))];
   const skipped =
     sharded.length > 0 ? nothingRan && !required : steps.every((step) => step.skipped);
   return {
@@ -276,6 +338,7 @@ function mergeStep(
     ...(skipped ? { skipped: true } : {}),
     findings,
     ...(output.length === 0 ? {} : { output }),
+    ...(warnings.length === 0 ? {} : { warnings }),
     ...(tests === undefined ? {} : { tests }),
   };
 }
@@ -287,11 +350,13 @@ export function mergeParts(
   declared: readonly string[] = VERIFY_STEP_NAMES,
   options: MergeOptions = {},
 ): CommandResult {
-  const gap = gapFor(options.command ?? GATE_COMMAND);
+  const kinds = gapsFor(options.command ?? GATE_COMMAND);
   const unknown = parts.flatMap((part) =>
     part.steps
       .filter((step) => !declared.includes(step.name))
-      .map((step) => gap(`${part.file} reports "${step.name}", which x verify does not run`)),
+      .map((step) =>
+        kinds.present(`${part.file} reports "${step.name}", which x verify does not run`),
+      ),
   );
   const steps = declared.map((name) =>
     mergeStep(
@@ -300,7 +365,7 @@ export function mergeParts(
         part.steps.filter((step) => step.name === name).map((step) => ({ part: part.file, step })),
       ),
       floor,
-      gap,
+      kinds,
       options.riders !== undefined && Object.hasOwn(options.riders, name)
         ? options.riders[name]
         : undefined,