@ultimat3/cli 22.15.0 → 23.0.0

package/src/verify-coverage-run.ts

@@ -0,0 +1,190 @@
+// An app's `unit` step, run so its coverage can be read: the suite as a pool of plain `bun test`
+// processes over fixed slices, each writing its own lcov, folded by `coverage-lcov.ts`'s rule.
+//
+// NOT `bun test --parallel` with `--coverage` added, which is the obvious form and was measured
+// first (2026-10-01, Bun 1.4.0, `examples/dummy`, 53 unit files): Bun's own cross-worker merge is
+// a union, so the SAME tree read 59.9% of lines at four workers, 65.0% at two and 65.5% in one
+// process. A floor that moves with the core count is not a floor. Per-process lcov folded here
+// read 65.90% at 2, 4 and 8 processes.
+//
+// It costs nothing measurable: four slice processes took 9.7 s against 12.4 s for `--parallel=4`
+// over the same files, on a loaded 12-core box.
+
+// why: Bun ships no recursive delete and no path-join primitive; the lcov parts live under `.x/`.
+import { rm } from 'node:fs/promises';
+// why: Bun ships no path-join primitive.
+import { dirname, join } from 'node:path';
+import type { CoverageMap } from './coverage-lcov';
+import { fileCoverageOf, mergeCoverage, parseLcov } from './coverage-lcov';
+import type { ExecResult, Runner } from './exec';
+import { execOutput } from './exec';
+import { msg } from './messages';
+import { countsOf } from './test-counts';
+import { testEnvOverrides } from './test-dotenv';
+import { failureOf, ISOLATED_TEST_ENV } from './test-shards';
+import { SLOT_HELD_ENV } from './test-slots';
+import type { StepOutcome } from './verify-step';
+
+/**
+ * Test files per process. Small enough that a process is thrown away before its heap grows with
+ * the corpus (`test-batches.ts`), large enough that the ~0.3 s a process costs to start is noise.
+ */
+export const COVERAGE_SLICE_FILES = 16;
+
+/** Where a run's lcov parts are written, under the app root — removed when the run has read them. */
+export const COVERAGE_DIR = '.x/coverage';
+
+/**
+ * The slices one run is spent as: a pure function of the sorted file list, never of the machine,
+ * so the measured number is the same on a laptop and on a runner. A directory's tests stay in one
+ * slice — function coverage is the best one process reached (`mergeFileCoverage`), and the tests
+ * that cover a file sit beside it — and only a directory larger than the cap is cut.
+ */
+export function coverageSlices(
+  files: readonly string[],
+  cap: number = COVERAGE_SLICE_FILES,
+): readonly (readonly string[])[] {
+  const byDir = new Map<string, string[]>();
+  for (const file of [...new Set(files)].sort()) {
+    const dir = dirname(file);
+    const list = byDir.get(dir) ?? [];
+    list.push(file);
+    byDir.set(dir, list);
+  }
+  const slices: string[][] = [];
+  let open: string[] = [];
+  const close = (): void => {
+    if (open.length > 0) slices.push(open);
+    open = [];
+  };
+  for (const group of byDir.values()) {
+    if (group.length > cap) {
+      close();
+      for (let at = 0; at < group.length; at += cap) slices.push(group.slice(at, at + cap));
+    } else {
+      if (open.length + group.length > cap) close();
+      open.push(...group);
+    }
+  }
+  close();
+  return slices;
+}
+
+export interface CoveredRunOptions {
+  readonly root: string;
+  readonly runner: Runner;
+  /** Paths relative to `root`. */
+  readonly files: readonly string[];
+  readonly workers: number;
+  readonly isolate?: boolean;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly widthReason?: string;
+  readonly lease?: (want: number) => Promise<{ readonly count: number; release(): void }>;
+  /** Test files per process. Absent is `COVERAGE_SLICE_FILES`; a test cuts smaller. */
+  readonly sliceFiles?: number;
+}
+
+export interface CoveredRun extends StepOutcome {
+  /** Every file any slice loaded, by the path Bun wrote — relative to `root`. */
+  readonly coverage: CoverageMap;
+}
+
+/** One slice's argv. An explicit file list, never a re-glob, for `testArgs`' reason. */
+export const coveredArgs = (
+  files: readonly string[],
+  dir: string,
+  isolate: boolean,
+): readonly string[] => [
+  'bun',
+  'test',
+  ...(isolate ? ['--isolate'] : []),
+  '--coverage',
+  '--coverage-reporter=lcov',
+  `--coverage-dir=${dir}`,
+  ...files,
+];
+
+export async function runCovered(options: CoveredRunOptions): Promise<CoveredRun> {
+  const slices = coverageSlices(options.files, options.sliceFiles);
+  const want = Math.max(1, Math.min(Math.trunc(options.workers), slices.length));
+  const lease = want > 1 ? await options.lease?.(want) : undefined;
+  const width = Math.min(want, lease?.count ?? want);
+  const base = join(options.root, COVERAGE_DIR, `unit-${String(process.pid)}`);
+  const isolate = options.isolate === true;
+  const overrides = {
+    ...testEnvOverrides(options.root, options.env ?? Bun.env),
+    ...(isolate ? { [ISOLATED_TEST_ENV]: '1' } : {}),
+    ...(lease === undefined ? {} : { [SLOT_HELD_ENV]: '1' }),
+  };
+  const results = new Array<ExecResult>(slices.length);
+  let next = 0;
+  // Each pool worker names its own numbered test database, as `--parallel`'s workers do.
+  const worker = async (slot: number): Promise<void> => {
+    while (next < slices.length) {
+      const index = next;
+      next += 1;
+      results[index] = await options.runner(
+        coveredArgs(slices[index] as readonly string[], join(base, String(index)), isolate),
+        { cwd: options.root, env: { ...overrides, ULTIMATE_TEST_WORKER: String(slot) } },
+      );
+    }
+  };
+  let maps: CoverageMap[];
+  try {
+    await Promise.all(Array.from({ length: width }, (_, slot) => worker(slot)));
+    maps = await Promise.all(slices.map((_, index) => readPart(join(base, String(index)))));
+  } finally {
+    lease?.release();
+    await rm(base, { recursive: true, force: true });
+  }
+  const failed = results.filter((result) => !result.ok);
+  const first = failed[0];
+  const output = results
+    .map((result, index) =>
+      result.ok
+        ? undefined
+        : [
+            msg('cli.test.batch', {
+              batch: index + 1,
+              batches: results.length,
+              files: slices[index]?.length ?? 0,
+            }),
+            execOutput(result),
+          ].join('\n'),
+    )
+    .filter((text) => text !== undefined)
+    .join('\n');
+  return {
+    ok: first === undefined,
+    findings:
+      first === undefined
+        ? []
+        : [
+            failureOf(first.code, options.files.length, {
+              workers: width,
+              type: 'unit',
+              ...(isolate ? { isolate: true } : {}),
+            }),
+          ],
+    workers: width,
+    ...(options.widthReason === undefined ? {} : { widthReason: options.widthReason }),
+    tests: countsOf(results),
+    ...(first === undefined ? {} : { output }),
+    coverage: mergeCoverage(maps),
+  };
+}
+
+/**
+ * One slice's lcov as a map, kept to the app's own tree: a slice loads a thousand framework files
+ * for every hundred of the app's, and none of those is what the floor measures. No file is no
+ * coverage — the slice died before writing it, and its exit code already says so.
+ */
+async function readPart(dir: string): Promise<CoverageMap> {
+  const file = Bun.file(join(dir, 'lcov.info'));
+  if (!(await file.exists())) return {};
+  return Object.fromEntries(
+    parseLcov(await file.text())
+      .filter((record) => /^(?:apps|packages)\//.test(record.file))
+      .map((record) => [record.file, fileCoverageOf(record)]),
+  );
+}

package/src/verify-deadline.ts

@@ -0,0 +1,256 @@
+// A gate step's deadline: the declared number per step class, the `x.verify.json` override, the
+// 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 type { VerifyStepName } from './verify-step';
+
+/** The `x.verify.json` key: `{ "stepTimeoutMs": { "unit": 900000 } }`. */
+export const STEP_TIMEOUT_FIELD = 'stepTimeoutMs';
+
+/** A check step — the compiler, biome, an in-process scan. Five minutes. */
+export const CHECK_STEP_TIMEOUT_MS = 300_000;
+
+/**
+ * A test suite. Eight minutes: under the ten a CI job is commonly given, so the step names itself
+ * before the runner cancels the job — the framework's own `unit` step is ~3 on a 4-core runner.
+ */
+export const SUITE_STEP_TIMEOUT_MS = 480_000;
+
+const SUITE_STEPS: readonly string[] = TEST_TYPES;
+
+export const defaultStepTimeoutMs = (step: string): number =>
+  SUITE_STEPS.includes(step) ? SUITE_STEP_TIMEOUT_MS : CHECK_STEP_TIMEOUT_MS;
+
+export type StepTimeouts = Readonly<Partial<Record<VerifyStepName, number>>>;
+
+/** The caller's override, then the floor file's, then the step class's declared number. */
+export const stepTimeoutMs = (
+  step: VerifyStepName,
+  ...overrides: readonly (StepTimeouts | undefined)[]
+): number => {
+  for (const table of overrides) {
+    const ms = table !== undefined && Object.hasOwn(table, step) ? table[step] : undefined;
+    if (ms !== undefined) return ms;
+  }
+  return defaultStepTimeoutMs(step);
+};
+
+/**
+ * `stepTimeoutMs` out of `x.verify.json`, or the reasons it is not one. A value that is not a
+ * positive whole number is refused, never read as "no deadline": a typo that removed the deadline
+ * is the hang this file exists to end.
+ */
+export function readStepTimeouts(
+  payload: Record<string, unknown> | undefined,
+  declared: readonly string[],
+): { timeouts?: StepTimeouts; problems: readonly string[] } {
+  const raw = payload?.[STEP_TIMEOUT_FIELD];
+  if (raw === undefined) return { problems: [] };
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return { problems: [`"${STEP_TIMEOUT_FIELD}" is not an object of { "<step>": milliseconds }`] };
+  }
+  const problems: string[] = [];
+  const timeouts = new Map<string, number>();
+  for (const [step, ms] of Object.entries(raw)) {
+    if (!declared.includes(step)) {
+      problems.push(`"${STEP_TIMEOUT_FIELD}" names ${step}, which x verify does not run`);
+    } else if (typeof ms !== 'number' || !Number.isSafeInteger(ms) || ms <= 0) {
+      problems.push(
+        `"${STEP_TIMEOUT_FIELD}" gives ${step} ${JSON.stringify(ms)}, which is not a positive whole number of milliseconds`,
+      );
+    } else timeouts.set(step, ms);
+  }
+  return {
+    ...(timeouts.size === 0 ? {} : { timeouts: Object.fromEntries(timeouts) as StepTimeouts }),
+    problems,
+  };
+}
+
+/** Carried by every process a step starts, and inherited by everything those start in turn. */
+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;
+
+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>;
+}
+
+/**
+ * The step's own view of the subprocess boundary. The tag is an ENVIRONMENT variable rather than a
+ * pid list or a process group because it is the one mark a grandchild keeps after its parent dies:
+ * `bun test --parallel` workers, `bunx`'s child and an e2e browser are all re-parented to init the
+ * moment the process this file started exits, and a walk down the ppid chain loses them there.
+ *
+ * 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.
+ */
+export function guardStep(
+  runner: Runner,
+  tag: string,
+  env: Readonly<Record<string, string | undefined>> = Bun.env,
+): StepGuard {
+  let expired = false;
+  const inherited = env[STEP_TAG_ENV];
+  const value = inherited === undefined || inherited === '' ? tag : `${inherited} ${tag}`;
+  return {
+    runner: async (command, options): Promise<ExecResult> => {
+      // The step's own code keeps running after its deadline — a batch loop moves on to the next
+      // batch when the killed one returns — and a child started then would outlive the gate.
+      if (expired) {
+        return {
+          command,
+          code: EXPIRED_EXIT,
+          ok: false,
+          stdout: '',
+          stderr: 'not started: the step is past its deadline',
+          durationMs: 0,
+        };
+      }
+      return runner(command, { ...options, env: { ...options.env, [STEP_TAG_ENV]: value } });
+    },
+    async expire(): Promise<number> {
+      expired = true;
+      return killTagged(tag);
+    },
+  };
+}
+
+/** One process and the environment it was started with, as the platform reports it. */
+export interface ProcessEnviron {
+  readonly pid: number;
+  /** Whatever text holds `NAME=value` pairs — NUL-separated on Linux, space-separated from `ps`. */
+  readonly environ: string;
+}
+
+/** The pids whose environment carries `tag` as one word of `STEP_TAG_ENV`'s value. */
+export function taggedPids(processes: readonly ProcessEnviron[], tag: string): readonly number[] {
+  const marker = `${STEP_TAG_ENV}=`;
+  const pids: number[] = [];
+  for (const one of processes) {
+    for (const pair of one.environ.split('\0')) {
+      const at = pair.indexOf(marker);
+      if (at < 0) continue;
+      // From `ps`, the pair is one line of space-separated pairs: the value runs to the next
+      // ` NAME=`, and a tag never holds `=`.
+      const value = pair.slice(at + marker.length).split(/ (?=[A-Za-z_][A-Za-z0-9_]*=)/)[0] ?? '';
+      if (value.split(' ').includes(tag)) pids.push(one.pid);
+    }
+  }
+  return pids;
+}
+
+/** Linux: every process's start-time environment is a file. Unreadable ones are not ours. */
+async function procfsProcesses(): Promise<readonly ProcessEnviron[] | undefined> {
+  if (!(await Bun.file('/proc/self/environ').exists())) return undefined;
+  const out: ProcessEnviron[] = [];
+  for await (const entry of new Bun.Glob('[0-9]*').scan({ cwd: '/proc', onlyFiles: false })) {
+    const pid = Number(entry);
+    if (!Number.isSafeInteger(pid)) continue;
+    const environ = await Bun.file(`/proc/${entry}/environ`)
+      .text()
+      .catch(() => undefined);
+    if (environ !== undefined) out.push({ pid, environ });
+  }
+  return out;
+}
+
+/**
+ * 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[]> {
+  try {
+    const ps = Bun.spawn(['ps', 'axeww', '-o', 'pid=,command='], {
+      stdout: 'pipe',
+      stderr: 'ignore',
+    });
+    const text = await new Response(ps.stdout).text();
+    await ps.exited;
+    return text.split('\n').flatMap((line) => {
+      const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+      return match === null ? [] : [{ pid: Number(match[1]), environ: match[2] ?? '' }];
+    });
+  } catch {
+    return [];
+  }
+}
+
+const SWEEPS = 5;
+
+/**
+ * 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.
+ */
+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>();
+  for (let sweep = 0; sweep < SWEEPS; sweep += 1) {
+    const processes = await list();
+    const found = taggedPids(processes, tag).filter((pid) => pid !== process.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);
+      } catch {
+        // Already gone between the listing and the signal — which is the outcome wanted.
+      }
+    }
+    // A killed process stays listed until it is reaped; nothing NEW on a pass means it is done.
+    if (fresh.length === 0) break;
+    await Bun.sleep(20);
+  }
+  return killed.size;
+}
+
+/**
+ * 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>,
+  ms: number,
+): Promise<{ readonly timedOut: false; readonly value: T } | { readonly timedOut: true }> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<{ readonly timedOut: true }>((resolve) => {
+    timer = setTimeout(() => resolve({ timedOut: true }), ms);
+  });
+  try {
+    const raced = await Promise.race([
+      work.then((value) => ({ timedOut: false as const, value })),
+      expired,
+    ]);
+    if (raced.timedOut) work.catch(() => undefined);
+    return raced;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/verify-errors.ts

@@ -25,24 +25,33 @@ export class TestBudgetInvalidError extends UltimateError {
   }
 }
 
+/**
+ * The gate as an app types it. A refusal raised from another entry — `bun run verify` at the
+ * framework root, where `x verify` answers `X_NOT_IN_APP` — passes its own spelling, so the
+ * `fix:` runs where it was raised.
+ */
+const GATE = 'x verify';
+
 /** `x verify --shard` asked for a split the gate cannot make. */
 export class VerifyShardInvalidError extends UltimateError {
-  constructor(input: { reason: string; fix?: string }) {
+  constructor(input: { reason: string; fix?: string; command?: string }) {
+    const command = input.command ?? GATE;
     super({
       code: 'X_VERIFY_SHARD_INVALID',
-      cause: `x verify --shard: ${input.reason}`,
-      fix: input.fix ?? 'x verify --only unit --shard 1/4 --json',
+      cause: `${command} --shard: ${input.reason}`,
+      fix: input.fix ?? `${command} --only unit --shard 1/4 --json`,
     });
   }
 }
 
 /** A part handed to `x verify merge` that is not an `x verify --json` document. */
 export class VerifyMergeInputError extends UltimateError {
-  constructor(input: { file: string; reason: string; sourceError?: unknown }) {
+  constructor(input: { file: string; reason: string; sourceError?: unknown; command?: string }) {
+    const command = input.command ?? GATE;
     super({
       code: 'X_VERIFY_MERGE_INPUT',
-      cause: `x verify merge: ${input.file} ${input.reason}`,
-      fix: 'x verify --only <step> --json > part.json   # one document per part, the last line of stdout',
+      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 }),
     });
   }

package/src/verify-floor.ts

@@ -9,8 +9,12 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { AGENTS_MD_MAX_BYTES } from '@ultimat3/manifest';
+import type { CoverageFloor } from './coverage-floor';
+import { COVERAGE_FIELD, readCoverageFloor } from './coverage-floor';
 import type { Finding } from './output';
-import { VERIFY_STEP_NAMES } from './verify-step';
+import type { StepTimeouts } from './verify-deadline';
+import { readStepTimeouts, STEP_TIMEOUT_FIELD } from './verify-deadline';
+import { GATE_COMMAND, VERIFY_STEP_NAMES } from './verify-step';
 
 /** Hand-written and committed, beside the generated `x.manifest.json` the same gate reads. */
 export const VERIFY_FLOOR_FILE = 'x.verify.json';
@@ -48,6 +52,16 @@ export interface VerifyFloor {
    * says `true` here once, in the file that configures the gate, and `x test`/`x verify` honour it.
    */
   readonly isolate?: boolean;
+  /**
+   * A step's own deadline in milliseconds, beating its class's declared number
+   * (`verify-deadline.ts`). A step past it is `X_VERIFY_STEP_TIMEOUT`, by name.
+   */
+  readonly stepTimeoutMs?: StepTimeouts;
+  /**
+   * The coverage the `unit` step must hold, of the app's whole source tree (`coverage-floor.ts`).
+   * Absent in an app is `X_COVERAGE_FLOOR_UNSTATED`: no app is held to a number it did not write.
+   */
+  readonly coverage?: CoverageFloor;
   /** Why part of the file is not a floor. The `manifest` step reports these; nothing swallows them. */
   readonly problems: readonly string[];
 }
@@ -147,18 +161,27 @@ export function parseVerifyFloor(
   const budget = readBudget(record);
   const typecheckBin = readTypecheckBin(record);
   const isolate = readIsolate(record);
+  const timeouts = readStepTimeouts(record, declared);
+  const coverage = readCoverageFloor(record);
+  const rest = {
+    ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
+    ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
+    ...(isolate.isolate === undefined ? {} : { isolate: isolate.isolate }),
+    ...(timeouts.timeouts === undefined ? {} : { stepTimeoutMs: timeouts.timeouts }),
+    ...(coverage.coverage === undefined ? {} : { coverage: coverage.coverage }),
+  };
   const steps = record?.['steps'];
   if (!Array.isArray(steps)) {
     return {
       steps: [],
-      ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
-      ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
-      ...(isolate.isolate === undefined ? {} : { isolate: isolate.isolate }),
+      ...rest,
       problems: [
         'it has no "steps" array of step names',
         ...budget.problems,
         ...typecheckBin.problems,
         ...isolate.problems,
+        ...timeouts.problems,
+        ...coverage.problems,
       ],
     };
   }
@@ -166,9 +189,7 @@ export function parseVerifyFloor(
   const unknown = named.filter((step) => !declared.includes(step));
   return {
     steps: named.filter((step) => declared.includes(step)),
-    ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
-    ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
-    ...(isolate.isolate === undefined ? {} : { isolate: isolate.isolate }),
+    ...rest,
     problems: [
       ...isolate.problems,
       ...(named.length === steps.length ? [] : ['"steps" holds an entry that is not a string']),
@@ -177,6 +198,8 @@ export function parseVerifyFloor(
         ? []
         : [`"steps" names ${unknown.join(', ')}, which x verify does not run`]),
       ...budget.problems,
+      ...timeouts.problems,
+      ...coverage.problems,
     ],
   };
 }
@@ -206,10 +229,10 @@ export const floorRequires = (floor: VerifyFloor | undefined, step: string): boo
  * command that rewrites the floor is the gate editing its own ratchet, which is the false green the
  * floor exists to close — so the run that proves the step is back is what this offers to repeat.
  */
-export const vanishedSuiteFinding = (step: string): Finding => ({
+export const vanishedSuiteFinding = (step: string, command: string = GATE_COMMAND): Finding => ({
   code: 'X_VERIFY_SUITE_VANISHED',
   cause: `${VERIFY_FLOOR_FILE} requires the ${step} step and this run found nothing for it to check`,
-  fix: `x verify --json   # restore the ${step} suite, or drop "${step}" from ${VERIFY_FLOOR_FILE} in the commit that says why`,
+  fix: `${command} --json   # restore the ${step} suite, or drop "${step}" from ${VERIFY_FLOOR_FILE} in the commit that says why`,
   docs: ERROR_DOCS_URL,
   at: VERIFY_FLOOR_FILE,
 });
@@ -262,5 +285,9 @@ const fixFor = (problem: string): string => {
     return `x verify --json   # then set "${BUDGET_FIELD}" in ${VERIFY_FLOOR_FILE} to a positive whole number of bytes, or drop the key for the ${AGENTS_MD_MAX_BYTES}B default`;
   if (problem.includes(`"${TYPECHECK_BIN_FIELD}"`))
     return `x verify --json   # then set "${TYPECHECK_BIN_FIELD}" in ${VERIFY_FLOOR_FILE} to a non-empty binary name, or drop the key to run tsc`;
+  if (problem.includes(`"${STEP_TIMEOUT_FIELD}"`))
+    return `x verify --json   # then write "${STEP_TIMEOUT_FIELD}" in ${VERIFY_FLOOR_FILE} as { "unit": 900000 } — a step it runs, a whole number of milliseconds`;
+  if (problem.includes(`"${COVERAGE_FIELD}`))
+    return `x verify --only unit --json   # then write "${COVERAGE_FIELD}" in ${VERIFY_FLOOR_FILE} as { "lines": 95, "funcs": 95 }, every "exclude" entry as { "glob": "…", "why": "…" }`;
   return `x verify --json   # then write ${VERIFY_FLOOR_FILE} as {"steps":["unit","contract"]}, naming only steps it ran`;
 };