@ultimat3/cli 22.15.0 → 24.0.0

package/src/verify-run.ts

@@ -3,15 +3,27 @@
 // command: what a run means — never bail early, count what actually ran — belongs to neither.
 
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import type { CoverageMap } from './coverage-lcov';
+import { encodeCoverage } from './coverage-lcov';
 import { msg } from './messages';
-import type { CommandResult, Finding, StepResult } from './output';
+import type { CommandResult, Finding, JsonValue, StepResult } from './output';
+import type { StepGuard } from './verify-deadline';
+import { guardStep, raceDeadline, stepTimeoutMs } from './verify-deadline';
 import {
   floorRequires,
   readVerifyFloor,
   skippedSuiteFinding,
   vanishedSuiteFinding,
 } from './verify-floor';
-import type { 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';
 
 /**
  * Run every step, never bailing early: an agent fixing three things at once needs all
@@ -30,6 +42,30 @@ export async function runVerify(
   const only = onlyList(ctx.only);
   const selected = only === undefined ? steps : steps.filter((step) => only.includes(step.name));
   const byName = new Map<string, StepResult>();
+  // Per step: the numbers a judged run measured, or — under `--shard`, which cannot judge — the
+  // `facts` its slice covered, for `x verify merge` to fold.
+  const coverage = new Map<string, JsonValue>();
+  // One per run: a step's tag is `<step>@<run>`, so two gates on one machine never kill each
+  // other's children.
+  const runId = crypto.randomUUID().slice(0, 8);
+  const run = async (step: VerifyStep, stepCtx: VerifyContext): Promise<void> => {
+    const ran = await runStep(step, stepCtx, floor, runId);
+    byName.set(step.name, ran.result);
+    if (ran.coverage !== undefined) {
+      coverage.set(step.name, { facts: encodeCoverage(ran.coverage) });
+    } else if (ran.measured !== undefined) {
+      const { lines, funcs, files } = ran.measured;
+      coverage.set(step.name, { lines, funcs, files });
+    }
+    // Told as it finishes, never at the end: the caller streams it, so a cancelled job's log
+    // ends on the last step that finished (#589). A progress line is not the verdict: a listener
+    // that throws — stderr closed under it — must not take the gate down with it.
+    try {
+      ctx.onStep?.(ran.result);
+    } catch {
+      // Nothing to report it on; the document on stdout still carries the step.
+    }
+  };
   const began = performance.now();
   // The static steps wait for the serial suites and then run BESIDE them — only when `live` is in
   // the list, so a one-step run (`--only`) and a list with no serial suite keep today's order.
@@ -51,16 +87,12 @@ export async function runVerify(
   for (const step of selected) {
     if (beside.includes(step)) continue;
     if (step.name === SERIAL_SUITES[0]) {
-      pending = Promise.all(
-        beside.map(async (other) => {
-          byName.set(other.name, await runStep(other, base, floor));
-        }),
-      ).then(() => undefined);
+      pending = Promise.all(beside.map((other) => run(other, base))).then(() => undefined);
     } else if (!SERIAL_SUITES.includes(step.name)) {
       await join();
     }
     const inWindow = pending !== undefined && SERIAL_SUITES.includes(step.name);
-    byName.set(step.name, await runStep(step, inWindow ? shared : base, floor));
+    await run(step, inWindow ? shared : base);
   }
   await join();
   // Reported in the declared order, whatever order the steps finished in: the table, `--json` and
@@ -98,6 +130,7 @@ export async function runVerify(
       // summary line to learn that this run checked one thing.
       // `only` is always the LIST, in declared order — one name is a list of one.
       ...(only === undefined ? {} : { notAGateRun: true, only: [...only] }),
+      ...(coverage.size === 0 ? {} : { coverage: Object.fromEntries(coverage) }),
     },
     // The step's own status: one step, so `failedSteps` is that step and nothing else.
     exitCode: failedSteps.length === 0 ? 0 : 1,
@@ -147,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',
@@ -157,20 +190,33 @@ 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,
   ctx: VerifyContext,
   floor: Awaited<ReturnType<typeof readVerifyFloor>>,
-): Promise<StepResult> {
+  runId: string,
+): Promise<{
+  readonly result: StepResult;
+  readonly coverage?: CoverageMap;
+  readonly measured?: CoverageNumbers;
+}> {
+  const command = ctx.command ?? GATE_COMMAND;
   // Inside the step's own failure, like a throwing `run`: an `applies` that threw escaped every
   // catch and aborted the whole gate, which is the one outcome `runVerify` exists to prevent.
   let applies: boolean;
   try {
     applies = step.applies === undefined ? true : await step.applies(ctx);
   } catch (error) {
-    return { name: step.name, ok: false, durationMs: 0, findings: [findingOf(error, step.name)] };
+    return {
+      result: {
+        name: step.name,
+        ok: false,
+        durationMs: 0,
+        findings: [findingOf(error, step.name, command)],
+      },
+    };
   }
   if (!applies) {
     // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
@@ -180,20 +226,33 @@ async function runStep(
     // the summary, `data.failed`, and the reference-app gate's own red list.
     const required = floorRequires(floor, step.name);
     return {
-      name: step.name,
-      ok: !required,
-      durationMs: 0,
-      skipped: !required,
-      findings: required ? [vanishedSuiteFinding(step.name)] : [],
+      result: {
+        name: step.name,
+        ok: !required,
+        durationMs: 0,
+        skipped: !required,
+        findings: required ? [vanishedSuiteFinding(step.name, command)] : [],
+      },
     };
   }
   const started = performance.now();
-  const outcome = await step.run(ctx).catch(
-    (error: unknown): StepOutcome => ({
-      ok: false,
-      findings: [findingOf(error, step.name)],
-    }),
+  // The deadline: a step that hangs fails BY NAME and its processes are killed, instead of eating
+  // the CI job's whole timeout and leaving a log that says nothing (#589). The step runs on a
+  // guarded runner, so everything it starts carries its tag — that is what the kill finds.
+  const limit = stepTimeoutMs(step.name, ctx.stepTimeoutMs, floor?.stepTimeoutMs);
+  const guard = guardStep(ctx.runner, `${step.name}@${runId}`);
+  const raced = await raceDeadline(
+    step.run({ ...ctx, runner: guard.runner }).catch(
+      (error: unknown): StepOutcome => ({
+        ok: false,
+        findings: [findingOf(error, step.name, command)],
+      }),
+    ),
+    limit,
   );
+  const outcome: StepOutcome = raced.timedOut
+    ? 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.
   // ONE definition of "nothing ran", read twice, because the floor decides which of the two
@@ -208,23 +267,43 @@ async function runStep(
   // step's own findings so `data.failed`, the counts and every gate reading this table carry it.
   const vanished = nothingRan && required ? [skippedSuiteFinding(step.name, tests.skipped)] : [];
   return {
-    name: step.name,
-    ok: outcome.ok && vanished.length === 0,
-    durationMs: Math.round(performance.now() - started),
-    // Without a floor to require it, a suite that ran nothing is a SKIP and not a pass (#434):
-    // the `e2e` step printed `✓ e2e 46ms` over its one skipped test, which is the one thing a
-    // step table may never do — a reader cannot tell a lane that ran from a lane that did not.
-    skipped: nothingRan && !required,
-    findings: [...outcome.findings, ...vanished],
-    ...(outcome.output === undefined ? {} : { output: outcome.output }),
-    ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
-    ...(outcome.widthReason === undefined ? {} : { widthReason: outcome.widthReason }),
-    ...(outcome.shard === undefined ? {} : { shard: outcome.shard }),
-    ...(tests === undefined ? {} : { tests }),
+    result: {
+      name: step.name,
+      ok: outcome.ok && vanished.length === 0,
+      durationMs: Math.round(performance.now() - started),
+      // Without a floor to require it, a suite that ran nothing is a SKIP and not a pass (#434):
+      // the `e2e` step printed `✓ e2e 46ms` over its one skipped test, which is the one thing a
+      // step table may never do — a reader cannot tell a lane that ran from a lane that did not.
+      skipped: nothingRan && !required,
+      findings: [...outcome.findings, ...vanished],
+      ...(outcome.output === undefined ? {} : { output: outcome.output }),
+      ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
+      ...(outcome.widthReason === undefined ? {} : { widthReason: outcome.widthReason }),
+      ...(outcome.shard === undefined ? {} : { shard: outcome.shard }),
+      ...(tests === undefined ? {} : { tests }),
+    },
+    ...(outcome.coverage === undefined ? {} : { coverage: outcome.coverage }),
+    ...(outcome.measured === undefined ? {} : { measured: outcome.measured }),
+  };
+}
+
+/** 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): Finding {
+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
   // gate's own report down with it — the one message that may never be lost.
@@ -232,7 +311,7 @@ function findingOf(error: unknown, step: string): Finding {
   return {
     code: 'X_VERIFY_FAILED',
     cause: `step "${step}" threw: ${cause}`,
-    fix: 'x verify --json',
+    fix: `${command} --json`,
     docs: ERROR_DOCS_URL,
   };
 }

package/src/verify-shard.ts

@@ -5,11 +5,23 @@
 // 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'];
@@ -20,18 +32,22 @@ export interface ShardSpec {
   readonly total: number;
 }
 
-/** `3/8` → `{ index: 3, total: 8 }`, refused unless `1 <= i <= n`. */
-export function parseShard(raw: string): ShardSpec {
+/**
+ * `3/8` → `{ index: 3, total: 8 }`, refused unless `1 <= i <= n`. `command` is the gate as the
+ * caller was invoked, so the refusal's fix runs where it was raised.
+ */
+export function parseShard(raw: string, command: string = GATE_COMMAND): ShardSpec {
   const match = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(raw);
   const index = match === null ? Number.NaN : Number(match[1]);
   const total = match === null ? Number.NaN : Number(match[2]);
   if (!Number.isSafeInteger(index) || !Number.isSafeInteger(total) || total < 1 || index < 1) {
-    throw new VerifyShardInvalidError({ reason: `"${raw}" is not i/n (e.g. 2/4)` });
+    throw new VerifyShardInvalidError({ reason: `"${raw}" is not i/n (e.g. 2/4)`, command });
   }
   if (index > total) {
     throw new VerifyShardInvalidError({
       reason: `shard ${String(index)} does not exist in a ${String(total)}-way split (1..${String(total)})`,
-      fix: `x verify --only unit --shard ${renderFixShellArg(`${String(total)}/${String(total)}`, '<i/n>')} --json`,
+      fix: `${command} --only unit --shard ${renderFixShellArg(`${String(total)}/${String(total)}`, '<i/n>')} --json`,
+      command,
     });
   }
   return { index, total };
@@ -41,11 +57,14 @@ export function parseShard(raw: string): ShardSpec {
  * The steps a shard run may name: every one must be shardable. Refused with the step named, and a
  * fix that keeps the shardable ones — `live`/`e2e` belong in a job of their own.
  */
-export function assertShardable(only: readonly VerifyStepName[] | undefined): void {
+export function assertShardable(
+  only: readonly VerifyStepName[] | undefined,
+  command: string = GATE_COMMAND,
+): void {
   if (only === undefined || only.length === 0) {
     throw new VerifyShardInvalidError({
       reason: 'a shard is one slice of ONE parallel step and needs --only to name it',
-      fix: 'x verify --only unit --shard 1/4 --json',
+      command,
     });
   }
   const refused = only.filter((step) => !SHARDABLE_STEPS.includes(step));
@@ -57,8 +76,9 @@ export function assertShardable(only: readonly VerifyStepName[] | undefined): vo
       } in a job of its own without --shard`,
       fix:
         kept.length === 0
-          ? `x verify --only ${renderFixShellArg(refused.join(','), '<step,step>')} --json`
-          : `x verify --only ${renderFixShellArg(kept.join(','), '<step,step>')} --shard 1/4 --json`,
+          ? `${command} --only ${renderFixShellArg(refused.join(','), '<step,step>')} --json`
+          : `${command} --only ${renderFixShellArg(kept.join(','), '<step,step>')} --shard 1/4 --json`,
+      command,
     });
   }
 }
@@ -116,12 +136,13 @@ export function shardFiles(
 }
 
 /** A timings file, or a refusal naming it — a CI job must not silently fall back to round-robin. */
-export async function readTimings(path: string): Promise<Timings> {
+export async function readTimings(path: string, command: string = GATE_COMMAND): Promise<Timings> {
   const file = Bun.file(path);
   if (!(await file.exists())) {
     throw new VerifyShardInvalidError({
       reason: `--timings ${path} does not exist`,
       fix: 'bun test --timings=timings.json --update-timings   # writes it, then commit or cache it',
+      command,
     });
   }
   let parsed: unknown;
@@ -139,6 +160,7 @@ export async function readTimings(path: string): Promise<Timings> {
     throw new VerifyShardInvalidError({
       reason: `--timings ${path} is not a JSON object of { "path": ms }`,
       fix: 'bun test --timings=timings.json --update-timings',
+      command,
     });
   }
   return parsed as Timings;

package/src/verify-stalled.ts

@@ -0,0 +1,152 @@
+// What a step was doing when its deadline passed, as the `X_VERIFY_STEP_TIMEOUT` finding. A hung
+// test file used to cost eight minutes and report "2 process(es) were killed" — nothing a reader
+// could run. The finding now names the file bun says a killed worker held, and its `fix:` runs it.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+import type { InFlightRun, StepExpiry } from './verify-deadline';
+import { STEP_TIMEOUT_FIELD } from './verify-deadline';
+import type { VerifyStepName } from './verify-step';
+
+/**
+ * One `bun test` the step was waiting on, read against what it printed as it was stopped. A `type`,
+ * like the meta that carries it: an interface is not assignable to `Finding.meta`'s JSON record.
+ */
+export type StalledRun = {
+  /** The argv without its file list: `bun test --parallel=3`. */
+  readonly command: string;
+  /** Files the run was handed; 0 for a serial run, which selects by filter. */
+  readonly files: number;
+  /** `--parallel`'s width, and 1 for a serial run. */
+  readonly workers: number;
+  /** The files that were still running, as bun named them. Empty when it named none. */
+  readonly stuck: readonly string[];
+};
+
+/** `X_VERIFY_STEP_TIMEOUT`'s `meta`. A `type`: an interface is not assignable to `Finding.meta`. */
+export type StepTimeoutMeta = {
+  readonly step: string;
+  readonly deadlineMs: number;
+  readonly killed: readonly { readonly pid: number; readonly command: string }[];
+  readonly inFlight: readonly StalledRun[];
+};
+
+/**
+ * What a `--parallel` coordinator prints for the file a killed worker was holding. The guard kills
+ * the workers first for exactly this line (`verify-deadline.ts`); it is bun's own statement of
+ * what was in flight, and it is printed in every reporter mode.
+ */
+const CRASHED = /^\s*✗ (.+) \(worker crashed: SIG[A-Z0-9]+\)$/;
+
+/** Bun's per-file header — `::group::`-prefixed on GitHub Actions. A serial run prints it at START. */
+const FILE_LINE = /^(?:::group::)?(\S.*\.test\.[cm]?[jt]sx?):$/;
+
+const PARALLEL = '--parallel=';
+
+const bare = (path: string): string => (path.startsWith('./') ? path.slice(2) : path);
+
+/**
+ * A parallel run names its stuck files itself, one crash line per killed worker. A serial run has
+ * no worker to kill: it prints a file's header when the file STARTS, so the stuck file is the last
+ * one printed — unless a `(fail)` follows it, which is also all a failures-only reporter ever
+ * prints, and then nothing is claimed.
+ */
+export function stalledRun(run: InFlightRun): StalledRun | undefined {
+  const [program, verb, ...rest] = run.command;
+  if (program !== 'bun' || verb !== 'test' || run.output === undefined) return undefined;
+  const lines = run.output.split('\n').map((line) => line.trimEnd());
+  const width = rest.find((arg) => arg.startsWith(PARALLEL));
+  const flags = rest.filter((arg) => arg.startsWith('--') && !arg.startsWith('--timings'));
+  const command = ['bun', 'test', ...flags].join(' ');
+  if (width === undefined) {
+    const last = lines.findLastIndex((line) => FILE_LINE.test(line));
+    const started = last < 0 ? undefined : FILE_LINE.exec(lines[last] ?? '')?.[1];
+    const failed = lines.slice(last + 1).some((line) => line.startsWith('(fail)'));
+    return {
+      command,
+      files: 0,
+      workers: 1,
+      stuck: started === undefined || failed ? [] : [started],
+    };
+  }
+  const files = rest.filter((arg) => !arg.startsWith('--'));
+  const crashed = lines.flatMap((line) => {
+    const path = CRASHED.exec(line)?.[1];
+    // As the caller handed it in, so the `fix:` reruns the very argument the run was given.
+    return path === undefined ? [] : [files.find((file) => bare(file) === bare(path)) ?? path];
+  });
+  return {
+    command,
+    files: files.length,
+    workers: Math.max(1, Number(width.slice(PARALLEL.length)) || 1),
+    stuck: [...new Set(crashed)],
+  };
+}
+
+/** How many paths a `cause:` spells out — the rest are in `meta`. */
+const NAMED_IN_CAUSE = 5;
+
+const OUTPUT_TAIL_CHARS = 4_000;
+
+/** The last thing each killed run printed: what a reader of a red step looks at first. */
+export function stalledOutput(expiry: StepExpiry): string | undefined {
+  const text = expiry.inFlight
+    .flatMap((run) => (run.output === undefined || run.output === '' ? [] : [run.output]))
+    .join('\n');
+  if (text === '') return undefined;
+  return text.length > OUTPUT_TAIL_CHARS ? `…${text.slice(-OUTPUT_TAIL_CHARS)}` : text;
+}
+
+const inFlightClause = (runs: readonly StalledRun[], expiry: StepExpiry): string => {
+  const files = runs.flatMap((run) => run.stuck);
+  const named = runs.find((run) => run.stuck.length > 0);
+  if (named !== undefined) {
+    const shown = files.slice(0, NAMED_IN_CAUSE).join(', ');
+    const more = files.length > NAMED_IN_CAUSE ? `, +${String(files.length - NAMED_IN_CAUSE)}` : '';
+    return `; still running when it was stopped: ${shown}${more} (${named.command})`;
+  }
+  const waiting = expiry.inFlight[0];
+  if (waiting === undefined) return '';
+  return runs[0] === undefined
+    ? `; it was waiting on: ${waiting.command.slice(0, 4).join(' ')}`
+    : `; its running "${runs[0].command}" named no file still in flight, so the run itself did not exit`;
+};
+
+/**
+ * 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. With a stuck file named, the fix runs THAT file; the step's own rerun and
+ * the `stepTimeoutMs` edit ride behind it.
+ */
+export const stepTimeoutFinding = (
+  step: VerifyStepName,
+  ms: number,
+  expiry: StepExpiry,
+  command: string,
+): Finding => {
+  const runs = expiry.inFlight.flatMap((run) => stalledRun(run) ?? []);
+  const stuck = runs.flatMap((run) => run.stuck);
+  const rerun = `${command} --only ${step} --json`;
+  const longer = `if it legitimately needs longer, edit x.verify.json — add "${STEP_TIMEOUT_FIELD}": { "${step}": <milliseconds> }`;
+  // Each path through `quoteArg`, one argv word apiece: a test file's name is data from the disk,
+  // and this line is pasted into a shell.
+  const alone = ['bun', 'test', ...stuck.map(quoteArg)].join(' ');
+  const meta: StepTimeoutMeta = {
+    step,
+    deadlineMs: ms,
+    killed: expiry.killed.map((one) => ({ pid: one.pid, command: one.command })),
+    inFlight: runs,
+  };
+  return {
+    code: 'X_VERIFY_STEP_TIMEOUT',
+    cause: `step "${step}" did not finish within its ${String(ms)} ms deadline, so it was stopped and ${String(expiry.killed.length)} process(es) it had started were killed${inFlightClause(runs, expiry)}`,
+    fix:
+      stuck.length > 0
+        ? `${alone}   # what had not finished, alone; the whole step: ${rerun}; ${longer}`
+        : `${rerun}   # reproduce it alone; ${longer}`,
+    docs: ERROR_DOCS_URL,
+    ...(stuck[0] === undefined ? {} : { at: stuck[0] }),
+    meta,
+  };
+};

package/src/verify-step.ts

@@ -3,10 +3,12 @@
 // implementation can live beside the code it checks without importing the list.
 
 import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { CoverageMap } from './coverage-lcov';
 import type { ExecResult, Runner } from './exec';
 import { execOutput } from './exec';
-import type { Finding, ShardFacts } from './output';
+import type { Finding, ShardFacts, StepResult } from './output';
 import type { TestCounts } from './test-counts';
+import type { StepTimeouts } from './verify-deadline';
 
 /**
  * Every step of the gate, in cost order — cheapest and most informative first, and never a check
@@ -106,8 +108,29 @@ export interface VerifyContext {
    * name is accepted for the callers that narrow to one (`scripts/verify.ts`).
    */
   readonly only?: VerifyStepName | readonly VerifyStepName[];
+  /**
+   * Per-step deadlines in milliseconds that beat `x.verify.json`'s `stepTimeoutMs`, which beat the
+   * step class's declared number (`verify-deadline.ts`). A step past its deadline fails by name
+   * with `X_VERIFY_STEP_TIMEOUT` and every process it started is killed.
+   */
+  readonly stepTimeoutMs?: StepTimeouts;
+  /**
+   * Called as each step finishes, in the order they finish. `--json` prints nothing until the run
+   * ends, so a job cancelled mid-run left no trace of where it hung (#589): the command streams
+   * one line per step to stderr through this, and stdout stays the single document.
+   */
+  readonly onStep?: (step: StepResult) => void;
+  /**
+   * The gate as it was invoked HERE, for a `fix:` that has to run where it was raised: `x verify`
+   * when absent, `bun run verify` from the framework root's own entry — where `x verify` answers
+   * `X_NOT_IN_APP`.
+   */
+  readonly command?: string;
 }
 
+/** `ctx.command`'s default: the binary and the command, as an app types it. */
+export const GATE_COMMAND = 'x verify';
+
 export interface StepOutcome {
   readonly ok: boolean;
   readonly findings: readonly Finding[];
@@ -128,6 +151,24 @@ export interface StepOutcome {
    * NOT the same as a suite that ran nothing, which is a number the ratchet acts on.
    */
   readonly tests?: TestCounts;
+  /**
+   * What the `unit` suite covered of the app's own tree, when this run did NOT judge it: a
+   * `--shard` slice cannot hold a floor, so it hands its facts to `x verify merge`, which folds
+   * every shard's and judges once.
+   */
+  readonly coverage?: CoverageMap;
+  /**
+   * What the `unit` suite covered of the app's own tree when this run DID judge it. `--json` drops
+   * a green step's `output`, so the numbers ride in `data.coverage` where a reader can find them.
+   */
+  readonly measured?: CoverageNumbers;
+}
+
+/** The two percentages a judged run measured, and the source files they are over. */
+export interface CoverageNumbers {
+  readonly lines: number;
+  readonly funcs: number;
+  readonly files: number;
 }
 
 export interface VerifyStep {