@ultimat3/cli 23.0.0 → 24.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>;
 }
 
 /**
@@ -98,6 +133,8 @@ export function guardStep(
   env: Readonly<Record<string, string | undefined>> = Bun.env,
 ): 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[]>();
   const inherited = env[STEP_TAG_ENV];
   const value = inherited === undefined || inherited === '' ? tag : `${inherited} ${tag}`;
   return {
@@ -114,11 +151,35 @@ export function guardStep(
           durationMs: 0,
         };
       }
-      return runner(command, { ...options, env: { ...options.env, [STEP_TAG_ENV]: value } });
+      const run = runner(command, { ...options, env: { ...options.env, [STEP_TAG_ENV]: value } });
+      inFlight.set(run, command);
+      try {
+        return await run;
+      } finally {
+        inFlight.delete(run);
+      }
     },
-    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];
+      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.
+      const settled = await 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 };
+        }),
+      );
+      return { killed, inFlight: settled };
     },
   };
 }
@@ -162,19 +223,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 +261,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 +328,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'] : {})) {
@@ -184,6 +182,39 @@ 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,
@@ -246,6 +277,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);

package/src/verify-part-step.ts

@@ -0,0 +1,90 @@
+// One step of an `x verify --json` part, read against the shape `mergeStep` relies on. It was a
+// cast past `name` and `ok`: `findings: [null]` merged green, and a step with no `durationMs`
+// reached `Math.max` as `undefined` — a part a CI job hand-edited, or truncated, was believed.
+
+import type { Finding } from './output';
+import type { TestCounts } from './test-counts';
+
+export 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[];
+  };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isCount = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 0;
+
+/** What every finding is: code, cause and fix as strings. Optional fields ride along as written. */
+const isFinding = (value: unknown): value is Finding =>
+  isRecord(value) &&
+  typeof value['code'] === 'string' &&
+  typeof value['cause'] === 'string' &&
+  typeof value['fix'] === 'string';
+
+const isTests = (value: unknown): value is TestCounts =>
+  isRecord(value) &&
+  isCount(value['ran']) &&
+  isCount(value['skipped']) &&
+  (value['errors'] === undefined || isCount(value['errors']));
+
+const isShard = (value: unknown): value is NonNullable<PartStep['shard']> =>
+  isRecord(value) &&
+  isCount(value['index']) &&
+  isCount(value['total']) &&
+  typeof value['corpusHash'] === 'string' &&
+  Array.isArray(value['files']) &&
+  value['files'].every((file) => typeof file === 'string');
+
+/** The step, or the reason it is not one — phrased to follow "holds a step …". */
+export function readPartStep(raw: unknown): PartStep | string {
+  if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['ok'] !== 'boolean') {
+    return 'holds a step without a name and ok';
+  }
+  const name = raw['name'];
+  const durationMs = raw['durationMs'];
+  if (typeof durationMs !== 'number' || !Number.isFinite(durationMs) || durationMs < 0) {
+    return `holds step "${name}" without a durationMs in milliseconds`;
+  }
+  const findings = raw['findings'];
+  if (!Array.isArray(findings) || !findings.every(isFinding)) {
+    return `holds step "${name}" whose findings are not each a code, a cause and a fix`;
+  }
+  const { tests, shard, output, workers, skipped } = raw;
+  if (tests !== undefined && !isTests(tests)) {
+    return `holds step "${name}" whose tests are not counts`;
+  }
+  if (shard !== undefined && !isShard(shard)) {
+    return `holds step "${name}" whose shard is not an index, a total, a corpusHash and its files`;
+  }
+  if (output !== undefined && typeof output !== 'string') {
+    return `holds step "${name}" whose output is not text`;
+  }
+  if (workers !== undefined && !isCount(workers)) {
+    return `holds step "${name}" whose workers is not a count`;
+  }
+  return {
+    name,
+    ok: raw['ok'],
+    durationMs,
+    skipped: skipped === true,
+    findings,
+    ...(workers === undefined ? {} : { workers }),
+    ...(tests === undefined ? {} : { tests }),
+    ...(output === undefined ? {} : { output }),
+    ...(shard === undefined ? {} : { shard }),
+  };
+}

package/src/verify-run.ts

@@ -7,14 +7,22 @@ import type { CoverageMap } from './coverage-lcov';
 import { encodeCoverage } from './coverage-lcov';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue, StepResult } from './output';
-import { guardStep, raceDeadline, stepTimeoutFinding, stepTimeoutMs } from './verify-deadline';
+import type { StepGuard } from './verify-deadline';
+import { guardStep, raceDeadline, stepTimeoutMs } from './verify-deadline';
 import {
   floorRequires,
   readVerifyFloor,
   skippedSuiteFinding,
   vanishedSuiteFinding,
 } from './verify-floor';
-import type { CoverageNumbers, StepOutcome, VerifyContext, VerifyStep } from './verify-step';
+import { stalledOutput, stepTimeoutFinding } from './verify-stalled';
+import type {
+  CoverageNumbers,
+  StepOutcome,
+  VerifyContext,
+  VerifyStep,
+  VerifyStepName,
+} from './verify-step';
 import { GATE_COMMAND } from './verify-step';
 
 /**
@@ -172,7 +180,7 @@ export function verifySummary(input: {
  * `manifest` joined them 2026-09-23: it compares committed files against the code and writes
  * nothing, and at the repo root its host checks are ~20 whole-tree reads that sat alone at the end.
  */
-export const BESIDE_SERIAL_SUITES: ReadonlySet<string> = new Set([
+export const BESIDE_SERIAL_SUITES: ReadonlySet<VerifyStepName> = new Set<VerifyStepName>([
   'lint',
   'boundaries',
   'filesize',
@@ -182,7 +190,7 @@ export const BESIDE_SERIAL_SUITES: ReadonlySet<string> = new Set([
 ]);
 
 /** The consecutive run of steps the static group overlaps, in the order `VERIFY_STEP_NAMES` holds. */
-export const SERIAL_SUITES: readonly string[] = ['live', 'job', 'e2e', 'eval'];
+export const SERIAL_SUITES: readonly VerifyStepName[] = ['live', 'job', 'e2e', 'eval'];
 
 async function runStep(
   step: VerifyStep,
@@ -243,10 +251,7 @@ async function runStep(
     limit,
   );
   const outcome: StepOutcome = raced.timedOut
-    ? {
-        ok: false,
-        findings: [stepTimeoutFinding(step.name, limit, await guard.expire(), command)],
-      }
+    ? await expired(step.name, limit, guard, command)
     : raced.value;
   // A suite that executed nothing did not run, whatever its exit code says: `bun test` exits 0
   // over an all-skipped file, so the counts are the only channel that can tell the two apart.
@@ -282,6 +287,22 @@ async function runStep(
   };
 }
 
+/** The timed-out step's outcome: the finding naming what was in flight, over what it last printed. */
+async function expired(
+  step: VerifyStepName,
+  limit: number,
+  guard: StepGuard,
+  command: string,
+): Promise<StepOutcome> {
+  const expiry = await guard.expire();
+  const output = stalledOutput(expiry);
+  return {
+    ok: false,
+    findings: [stepTimeoutFinding(step, limit, expiry, command)],
+    ...(output === undefined ? {} : { output }),
+  };
+}
+
 function findingOf(error: unknown, step: string, command: string): Finding {
   // A step may throw anything, including an Error that fights being read: `instanceof` runs a
   // Proxy's `getPrototypeOf` trap and `.message` runs a getter, so a hostile throw would take the

package/src/verify-shard.ts

@@ -5,13 +5,24 @@
 // of the machine, the clock or the order a glob yielded — so job 3 of 8 is the same files on every
 // runner, and a failing shard reproduces locally with the same flags.
 
-import { renderFixShellArg } from '@ultimat3/core';
+import { renderFixShellArg, UltimateError } from '@ultimat3/core';
 import { CryptoHasher } from 'bun';
 import type { ShardFacts } from './output';
-import { VerifyShardInvalidError } from './verify-errors';
 import type { VerifyStepName } from './verify-step';
 import { GATE_COMMAND } from './verify-step';
 
+/** `x verify --shard` asked for a split the gate cannot make. */
+export class VerifyShardInvalidError extends UltimateError {
+  constructor(input: { reason: string; fix?: string; command?: string }) {
+    const command = input.command ?? GATE_COMMAND;
+    super({
+      code: 'X_VERIFY_SHARD_INVALID',
+      cause: `${command} --shard: ${input.reason}`,
+      fix: input.fix ?? `${command} --only unit --shard 1/4 --json`,
+    });
+  }
+}
+
 /** The steps a shard may split: the parallel suites. `live` and `e2e` are serial by design. */
 export const SHARDABLE_STEPS: readonly VerifyStepName[] = ['unit', 'contract', 'job'];