@ultimat3/cli 27.12.0 → 27.13.0

package/CLAUDE.md

@@ -45,7 +45,7 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `verify-checks.ts` / `verify-step.ts` / `verify-run.ts` | the step list, the outcome shape, the run order (`BESIDE_SERIAL_SUITES`) |
 | `verify-floor.ts` | `x.verify.json`: a floor step that ran zero tests is `X_VERIFY_SUITE_VANISHED` |
 | `coverage-floor.ts` / `coverage-lcov.ts` / `coverage-source.ts` / `verify-coverage-run.ts` | an APP's `unit` step holds `coverage` in `x.verify.json` over its whole source tree. The suite runs as fixed slices, one plain `bun test` each — never `--parallel --coverage`, whose merge moves with the core count. `coverage-lcov.ts` is the ONE lcov reader; `scripts/coverage-gate.ts` reads through it. A shard defers to `verify-merge.ts` (`coverageRiders`), which also holds the shards' `files` to a partition of the corpus they hashed and reads each part step through `verify-part-step.ts`; `doctor-coverage.ts` lists the excludes |
-| `verify-deadline.ts` / `verify-stalled.ts` / `verify-progress.ts` | a step past its deadline is `X_VERIFY_STEP_TIMEOUT`: its children carry `ULTIMATE_VERIFY_STEP` and are killed by that tag; the finding names the test file `bun test` had not finished (`at`, `meta.inFlight`) and its `fix:` runs that file; `--json` streams a line per finished step to stderr. A `fix:` names `ctx.command` — `bun run verify` at the framework root |
+| `verify-deadline.ts` / `verify-stalled.ts` / `verify-progress.ts` | a step past its deadline is `X_VERIFY_STEP_TIMEOUT`: its children carry `ULTIMATE_VERIFY_STEP` and are killed by that tag; the finding names the test file `bun test` had not finished (`at`, `meta.inFlight`) and its `fix:` runs that file; any render streams step lines + a heartbeat to stderr. A `fix:` names `ctx.command` — `bun run verify` at the framework root |
 | `load-findings.ts` | module-load failures are reported once, by `manifest`; other steps point there |
 | `boundary-findings.ts` / `app-boundaries.ts` / `boundary-cuts.ts` | surface + layer rules; a finding's `fix:` is the concrete cut |
 | `app-transport.ts` / `browser-transport.ts` / `transport-calls.ts` / `import-closure.ts` / `server-barrels.ts` | `boundaries`, built in: one browser transport. `app-transport.ts` reuses the files `readAppSources` read (no second walk), resolves through the app's tsconfig `paths` and workspace manifests, reads the app's own `packages/*` lazily, and STOPS at `node_modules`. `browser-transport.ts` is the pure rule — `scripts/browser-transport.ts` calls the same function with this repo's seam FILES. Never a `guards/` file: an app must not be able to delete it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.12.0",
+  "version": "27.13.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.12.0",
-    "@ultimat3/admin": "27.12.0",
-    "@ultimat3/ai": "27.12.0",
-    "@ultimat3/auth": "27.12.0",
-    "@ultimat3/cache": "27.12.0",
-    "@ultimat3/core": "27.12.0",
-    "@ultimat3/db": "27.12.0",
-    "@ultimat3/entity": "27.12.0",
-    "@ultimat3/flags": "27.12.0",
-    "@ultimat3/http": "27.12.0",
-    "@ultimat3/i18n": "27.12.0",
-    "@ultimat3/jobs": "27.12.0",
-    "@ultimat3/mail": "27.12.0",
-    "@ultimat3/manifest": "27.12.0",
-    "@ultimat3/mcp": "27.12.0",
-    "@ultimat3/money": "27.12.0",
-    "@ultimat3/notify": "27.12.0",
-    "@ultimat3/policy": "27.12.0",
-    "@ultimat3/pwa": "27.12.0",
-    "@ultimat3/query": "27.12.0",
-    "@ultimat3/realtime": "27.12.0",
-    "@ultimat3/render": "27.12.0",
-    "@ultimat3/schema": "27.12.0",
-    "@ultimat3/seo": "27.12.0",
-    "@ultimat3/storage": "27.12.0",
-    "@ultimat3/testing": "27.12.0",
-    "@ultimat3/time": "27.12.0",
+    "@ultimat3/action": "27.13.0",
+    "@ultimat3/admin": "27.13.0",
+    "@ultimat3/ai": "27.13.0",
+    "@ultimat3/auth": "27.13.0",
+    "@ultimat3/cache": "27.13.0",
+    "@ultimat3/core": "27.13.0",
+    "@ultimat3/db": "27.13.0",
+    "@ultimat3/entity": "27.13.0",
+    "@ultimat3/flags": "27.13.0",
+    "@ultimat3/http": "27.13.0",
+    "@ultimat3/i18n": "27.13.0",
+    "@ultimat3/jobs": "27.13.0",
+    "@ultimat3/mail": "27.13.0",
+    "@ultimat3/manifest": "27.13.0",
+    "@ultimat3/mcp": "27.13.0",
+    "@ultimat3/money": "27.13.0",
+    "@ultimat3/notify": "27.13.0",
+    "@ultimat3/policy": "27.13.0",
+    "@ultimat3/pwa": "27.13.0",
+    "@ultimat3/query": "27.13.0",
+    "@ultimat3/realtime": "27.13.0",
+    "@ultimat3/render": "27.13.0",
+    "@ultimat3/schema": "27.13.0",
+    "@ultimat3/seo": "27.13.0",
+    "@ultimat3/storage": "27.13.0",
+    "@ultimat3/testing": "27.13.0",
+    "@ultimat3/time": "27.13.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/cmd-build.ts

@@ -26,6 +26,7 @@ import {
   renderStaticReport,
   staticReportData,
 } from './static-report';
+import { measurePace } from './verify-pace';
 import type { VerifyStepName } from './verify-step';
 
 /**
@@ -385,7 +386,12 @@ export const buildCommand: CliCommand = {
       const verifySteps = (await import('./cmd-verify')).VERIFY_STEPS.filter((step) =>
         PREFLIGHT_STEPS.includes(step.name),
       );
-      const verifyResult = await runVerify(verifySteps, { root, runner: ctx.runner, env: ctx.env });
+      const verifyResult = await runVerify(verifySteps, {
+        root,
+        runner: ctx.runner,
+        env: ctx.env,
+        pace: measurePace(),
+      });
       if (!verifyResult.ok) {
         return preflightResult(verifyResult);
       }

package/src/cmd-verify.ts

@@ -23,7 +23,8 @@ import { VERIFY_STEPS } from './verify-checks';
 import { readVerifyFloor } from './verify-floor';
 import type { VerifyPart } from './verify-merge';
 import { coverageRiders, mergeParts, parsePart, VerifyMergeInputError } from './verify-merge';
-import { stepStream } from './verify-progress';
+import { measurePace } from './verify-pace';
+import { withVerifyProgress } from './verify-progress';
 import { runVerify } from './verify-run';
 import type { ShardSpec, Timings } from './verify-shard';
 import { assertShardable, parseShard, readTimings, VerifyShardInvalidError } from './verify-shard';
@@ -48,18 +49,22 @@ export const verifyCommand: CliCommand = {
     const only = readOnlySteps(ctx.args);
     const shard = await readShard(ctx.args, only);
     const isolate = flagBool(ctx.args, 'isolate') ? true : undefined;
-    const result = await runVerify(VERIFY_STEPS, {
-      root,
-      runner: ctx.runner,
-      env: ctx.env,
-      ...(workers === undefined ? {} : { workers }),
-      ...(only === undefined ? {} : { only }),
-      ...(shard === undefined ? {} : { shard }),
-      ...(isolate === undefined ? {} : { isolate }),
-      // `--json` prints one document when the run ends; a line per finished step on stderr is
-      // what a cancelled CI job's log ends on (#589). stdout stays the single document.
-      ...stepStream(ctx.args.json, writeErrorLine),
-    });
+    // Either render prints its verdict only when the run ends; the progress on stderr — a line per
+    // finished step, a heartbeat while one runs — is what a cancelled job's log ends on (#589) and
+    // what keeps a silence-killing harness from killing a healthy gate. stdout stays the document.
+    const result = await withVerifyProgress(writeErrorLine, (progress) =>
+      runVerify(VERIFY_STEPS, {
+        root,
+        runner: ctx.runner,
+        env: ctx.env,
+        pace: measurePace(),
+        ...(workers === undefined ? {} : { workers }),
+        ...(only === undefined ? {} : { only }),
+        ...(shard === undefined ? {} : { shard }),
+        ...(isolate === undefined ? {} : { isolate }),
+        ...progress,
+      }),
+    );
     return shard === undefined ? result : withShardData(result, shard);
   },
 };

package/src/mcp-host.ts

@@ -55,6 +55,7 @@ import { resolveServices } from './runtime-bindings';
 import type { RunningServices } from './runtime-services';
 import { startServices } from './runtime-services';
 import { testEnvOverrides } from './test-dotenv';
+import { measurePace } from './verify-pace';
 
 export interface DevHostInput {
   readonly root: string;
@@ -317,7 +318,7 @@ function capabilities(
       // The one safe autofix this repo actually has. Anything more would be the gate rewriting
       // code it was asked to judge.
       if (fix) await runner(['bunx', 'biome', 'check', '--write', '.'], { cwd: root });
-      const result = await runVerify(VERIFY_STEPS, { root, runner });
+      const result = await runVerify(VERIFY_STEPS, { root, runner, pace: measurePace() });
       return {
         ok: result.ok,
         steps: (result.steps ?? []).map((step): VerifyStep => {

package/src/messages.ts

@@ -337,6 +337,9 @@ const CATALOG = {
   // no skipped test to read a reason off, so the files the step selected hold no test.
   'cli.verify.ranNothing': 'found no test to run in the file(s) it selected',
   'cli.verify.merged': 'merged {parts} part(s) — {summary}',
+  // The heartbeat `verify-progress.ts` writes while a step is still running: `{steps}` is
+  // `unit (12m 3s), live (4m 0s)`, each step with the time since it started.
+  'cli.verify.stillRunning': 'still running: {steps}',
   // The `unit` step's own measurement, in `output`: what the suite covered of the app's whole
   // source tree, beside the floor it was held to. A shard says it measured a slice instead.
   'cli.verify.coverage':

package/src/verify-coverage-run.ts

@@ -24,6 +24,8 @@ import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
 import { failureOf } from './test-shards';
 import { SLOT_HELD_ENV } from './test-slots';
+import type { MachinePace } from './verify-pace';
+import { defaultTimeoutArgs, paceEnv } from './verify-pace';
 import type { StepOutcome } from './verify-step';
 
 /**
@@ -83,6 +85,8 @@ export interface CoveredRunOptions {
   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;
+  /** The machine's pace (`verify-pace.ts`): each test's default and declared deadline stretch by it. */
+  readonly pace?: MachinePace;
 }
 
 export interface CoveredRun extends StepOutcome {
@@ -95,10 +99,12 @@ export const coveredArgs = (
   files: readonly string[],
   dir: string,
   isolate: boolean,
+  pace?: MachinePace,
 ): readonly string[] => [
   'bun',
   'test',
   ...(isolate ? ['--isolate'] : []),
+  ...defaultTimeoutArgs(pace),
   '--coverage',
   '--coverage-reporter=lcov',
   `--coverage-dir=${dir}`,
@@ -116,6 +122,7 @@ export async function runCovered(options: CoveredRunOptions): Promise<CoveredRun
     ...testEnvOverrides(options.root, options.env ?? Bun.env),
     ...(isolate ? { [ISOLATED_ENV]: '1' } : {}),
     ...(lease === undefined ? {} : { [SLOT_HELD_ENV]: '1' }),
+    ...paceEnv(options.pace),
   };
   const results = new Array<ExecResult>(slices.length);
   let next = 0;
@@ -125,7 +132,12 @@ export async function runCovered(options: CoveredRunOptions): Promise<CoveredRun
       const index = next;
       next += 1;
       results[index] = await options.runner(
-        coveredArgs(slices[index] as readonly string[], join(base, String(index)), isolate),
+        coveredArgs(
+          slices[index] as readonly string[],
+          join(base, String(index)),
+          isolate,
+          options.pace,
+        ),
         { cwd: options.root, env: { ...overrides, ULTIMATE_TEST_WORKER: String(slot) } },
       );
     }

package/src/verify-deadline.ts

@@ -10,12 +10,16 @@ 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. */
+/**
+ * A check step — the compiler, biome, an in-process scan. Five minutes at a 4-core CI runner's
+ * pace; a slower machine runs it under this times its own (`stepDeadline`, `verify-pace.ts`).
+ */
 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.
+ * Stretched on a slower machine the same way as the check number.
  */
 export const SUITE_STEP_TIMEOUT_MS = 480_000;
 
@@ -26,16 +30,27 @@ export const defaultStepTimeoutMs = (step: string): number =>
 
 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 = (
+/**
+ * The deadline a step runs under. `pace` is set when it is the step class's declared number
+ * stretched to this machine (`verify-pace.ts`), so the finding past it can say so.
+ */
+export type StepDeadline = { readonly ms: number; readonly pace?: number };
+
+/**
+ * The caller's override, then the floor file's — each a number someone wrote down for this repo,
+ * taken as written — then the step class's declared number at this machine's pace `factor`.
+ */
+export const stepDeadline = (
   step: VerifyStepName,
-  ...overrides: readonly (StepTimeouts | undefined)[]
-): number => {
+  overrides: readonly (StepTimeouts | undefined)[],
+  factor: number,
+): StepDeadline => {
   for (const table of overrides) {
     const ms = table !== undefined && Object.hasOwn(table, step) ? table[step] : undefined;
-    if (ms !== undefined) return ms;
+    if (ms !== undefined) return { ms };
   }
-  return defaultStepTimeoutMs(step);
+  const declared = defaultStepTimeoutMs(step);
+  return factor === 1 ? { ms: declared } : { ms: Math.round(declared * factor), pace: factor };
 };
 
 /**

package/src/verify-pace.ts

@@ -0,0 +1,120 @@
+// How much slower this machine runs the gate than the one its declared numbers were measured on.
+// Every deadline the gate declares — a step's (`verify-deadline.ts`), Bun's 5 s per test, a test's
+// own — was set against a 4-core CI runner, and on a 2-core 1.8 GHz box the same honest work runs
+// five to seven times longer: the gate failed there on the deadlines, never on the code. Measured
+// once per gate, before any step runs, and applied to every one of those numbers.
+
+import { TEST_PACE_ENV } from '@ultimat3/testing';
+import { availableCpus } from './test-workers';
+
+/**
+ * The width the declared deadlines were measured at: a GitHub-hosted `ubuntu-latest` runner on a
+ * public repository has 4 cores, and the `unit` deadline's "~3 minutes" is on one.
+ */
+export const REFERENCE_CPUS = 4;
+
+/**
+ * What `probeWork` takes on that runner, the median of `PROBE_RUNS`: the SLOWEST of the five gate
+ * parts' readings, so the runner's own spread reads as pace 1 and its deadlines stay the declared
+ * ones. MEASURED on GitHub's `ubuntu-latest`, `As of 2026-10-19`: 31, 32, 32, 34, 35 ms (`ci` run
+ * 39208102081, each part's `data.pace.probeMs`). An idle 3.1 GHz Haswell core reads 65-90 ms.
+ */
+export const REFERENCE_PROBE_MS = 35;
+
+/** Rows the probe allocates, round-trips through JSON and sorts: ~25 ms a run on the reference. */
+export const PROBE_ROWS = 30_000;
+
+/** Timed runs after one untimed warm-up, so the JIT is not what gets measured. */
+export const PROBE_RUNS = 5;
+
+/** The machine's pace, and the two readings it was computed from — `--json` carries all three. */
+export type MachinePace = {
+  /** Every declared deadline is multiplied by this. Never below 1: a fast machine keeps the number. */
+  readonly factor: number;
+  readonly cpus: number;
+  /** The probe's median, in milliseconds. */
+  readonly probeMs: number;
+};
+
+/** Pace 1: the numbers as declared. What a caller that measured nothing runs at. */
+export const DECLARED_PACE: MachinePace = {
+  factor: 1,
+  cpus: REFERENCE_CPUS,
+  probeMs: REFERENCE_PROBE_MS,
+};
+
+/**
+ * Fewer cores than the reference is a proportionally longer parallel step, and a slower core is a
+ * proportionally longer everything: the two multiply. Each is held at 1 from below, so a wide or
+ * fast machine is never handed a TIGHTER deadline than the one declared. Two decimals: the number
+ * is printed, and `ULTIMATE_TEST_PACE` carries it to every test run.
+ */
+export function paceOf(cpus: number, probeMs: number): MachinePace {
+  const width = Math.max(1, REFERENCE_CPUS / Math.max(1, cpus));
+  const speed = Math.max(1, probeMs / REFERENCE_PROBE_MS);
+  return { factor: Math.round(width * speed * 100) / 100, cpus, probeMs };
+}
+
+/** A declared deadline at this pace. */
+export const pacedMs = (ms: number, pace: MachinePace): number => Math.round(ms * pace.factor);
+
+/**
+ * Fixed single-threaded work of the kind the gate does — allocate, serialize, parse, sort, scan
+ * strings — so a slower core, and a core shared with whatever else the box runs, both read slower.
+ * The result is folded into the return value so the work cannot be optimized away.
+ */
+export function probeWork(): number {
+  const rows = Array.from({ length: PROBE_ROWS }, (_, i) => ({
+    id: `row-${String((i * 7919) % PROBE_ROWS)}`,
+    n: i,
+    tags: [i % 3, i % 5],
+  }));
+  const back = JSON.parse(JSON.stringify(rows)) as typeof rows;
+  back.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return back
+    .map((row) => row.id)
+    .join('\n')
+    .split('\n')
+    .filter((line) => line.endsWith('7')).length;
+}
+
+const median = (values: readonly number[]): number => {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)] ?? 0;
+};
+
+/** The probe's median over `PROBE_RUNS`, in whole milliseconds. */
+export function probeMs(work: () => number = probeWork): number {
+  work();
+  const runs = Array.from({ length: PROBE_RUNS }, () => {
+    const started = performance.now();
+    work();
+    return performance.now() - started;
+  });
+  return Math.round(median(runs));
+}
+
+/** This machine, now: what an entry point (`x verify`, `x build`, the MCP host) hands the gate. */
+export const measurePace = (): MachinePace => paceOf(availableCpus(), probeMs());
+
+/** Bun's own per-test default: what every test and hook without a number of its own runs under. */
+export const BUN_TEST_TIMEOUT_MS = 5_000;
+
+/**
+ * `--timeout` for a test run at this pace, so a test with no number of its own — and every
+ * `beforeEach` booting an embedded Postgres — gets Bun's 5 s stretched like everything else. None
+ * at pace 1 or unmeasured: Bun's default already is the number, and the argv stays the one a
+ * developer types.
+ */
+export const defaultTimeoutArgs = (pace: MachinePace | undefined): readonly string[] =>
+  pace === undefined || pace.factor === 1
+    ? []
+    : [`--timeout=${String(pacedMs(BUN_TEST_TIMEOUT_MS, pace))}`];
+
+/**
+ * What a test run started at this pace is told, so its own declared deadlines stretch with it
+ * (`@ultimat3/testing`'s `paced`). Set at 1 too, whenever a pace was measured: a gate nested in a
+ * test must not inherit the outer run's pace as its own. Nothing when none was measured.
+ */
+export const paceEnv = (pace: MachinePace | undefined): Readonly<Record<string, string>> =>
+  pace === undefined ? {} : { [TEST_PACE_ENV]: String(pace.factor) };

package/src/verify-progress.ts

@@ -1,8 +1,31 @@
-// One finished gate step as one line of JSON, for stderr. `x verify --json` prints its document
-// when the run ENDS, so a job cancelled mid-run used to leave a log with nothing in it (#589):
-// the last of these lines is the last step that finished, and the hung one is whichever is next.
+// What the gate writes to stderr WHILE it runs, in every render mode: a line per finished step and
+// a heartbeat naming the steps still running. Both entries print their verdict only at the end, so
+// a run killed mid-way left nothing (#589), and a harness that kills on SILENCE killed a healthy one.
 
+import type { Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+import { msg } from './messages';
 import type { StepResult } from './output';
+import type { VerifyStepName } from './verify-step';
+
+/**
+ * How often the heartbeat names the steps still running. Bounded by the silence budget of the
+ * harness that runs the gate, not by cost: an agent runner or CI job that kills a process after
+ * 30 minutes with no new output byte killed green gates that finished seconds past it, and one
+ * step on a slow 2-core box can outlast that window on its own, so a line per finished step is
+ * not enough. A minute is far inside any silence window a harness sets.
+ */
+export const HEARTBEAT_MS = 60_000;
+
+/** A repeating timer that returns its own stop — injected so a test advances time, never sleeps. */
+export type Every = (tick: () => void, intervalMs: number) => () => void;
+
+/** Unref'd: a heartbeat must never be the thing that keeps a finished gate's process alive. */
+const unrefInterval: Every = (tick, intervalMs) => {
+  const timer = setInterval(tick, intervalMs);
+  timer.unref();
+  return () => clearInterval(timer);
+};
 
 /** `{"step":"lint","ok":true,"ms":21987}` — plus `"skipped":true` for a step that did not apply. */
 export const stepLine = (step: StepResult): string =>
@@ -13,13 +36,63 @@ export const stepLine = (step: StepResult): string =>
     ...(step.skipped === true ? { skipped: true } : {}),
   });
 
+/** `12m 3s`, `45s`: a person reading a CI log, not a parser — the step lines carry exact ms. */
+export const elapsedLabel = (ms: number): string => {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  return minutes === 0 ? `${seconds}s` : `${minutes}m ${seconds % 60}s`;
+};
+
+/** `still running: unit (12m 3s), live (4m 0s)` — each step with the time since IT started. */
+export const heartbeatLine = (running: ReadonlyMap<string, number>, now: number): string =>
+  msg('cli.verify.stillRunning', {
+    steps: [...running].map(([name, began]) => `${name} (${elapsedLabel(now - began)})`).join(', '),
+  });
+
+/** The two `VerifyContext` listeners a progress run hands the gate. */
+export interface VerifyProgressHooks {
+  readonly onStepStart: (name: VerifyStepName) => void;
+  readonly onStep: (step: StepResult) => void;
+}
+
+export interface VerifyProgressOptions {
+  readonly clock?: Clock;
+  readonly every?: Every;
+}
+
 /**
- * The `onStep` a `--json` run streams through, or nothing: the human render needs no second
- * channel. One function for both entries (`x verify`, and `bun run verify` at the framework
- * root), so the two cannot print different lines.
+ * Run the gate with progress on `write` (stderr), the heartbeat stopped however `run` ends. One
+ * function for both entries (`x verify`, and `bun run verify` at the framework root), so the two
+ * cannot print different lines; stdout is untouched, so `--json` stays one document there.
  */
-export const stepStream = (
-  json: boolean,
+export async function withVerifyProgress<T>(
   write: (line: string) => void,
-): { readonly onStep?: (step: StepResult) => void } =>
-  json ? { onStep: (step) => write(stepLine(step)) } : {};
+  run: (hooks: VerifyProgressHooks) => Promise<T>,
+  options: VerifyProgressOptions = {},
+): Promise<T> {
+  const clock = options.clock ?? systemClock;
+  const running = new Map<string, number>();
+  const stop = (options.every ?? unrefInterval)(() => {
+    if (running.size === 0) return;
+    // Inside a timer callback a throw is an uncaught exception: stderr closed under the gate must
+    // not take the run down with it. The verdict still reaches stdout.
+    try {
+      write(heartbeatLine(running, clock.monotonic()));
+    } catch {
+      // Nowhere left to say it.
+    }
+  }, HEARTBEAT_MS);
+  try {
+    return await run({
+      onStepStart: (name) => {
+        running.set(name, clock.monotonic());
+      },
+      onStep: (step) => {
+        running.delete(step.name);
+        write(stepLine(step));
+      },
+    });
+  } finally {
+    stop();
+  }
+}

package/src/verify-run.ts

@@ -7,8 +7,8 @@ import type { CoverageMap } from './coverage-lcov';
 import { encodeCoverage } from './coverage-lcov';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue, StepResult } from './output';
-import type { StepGuard } from './verify-deadline';
-import { guardStep, raceDeadline, stepTimeoutMs } from './verify-deadline';
+import type { StepDeadline, StepGuard } from './verify-deadline';
+import { guardStep, raceDeadline, stepDeadline } from './verify-deadline';
 import {
   floorRequires,
   readVerifyFloor,
@@ -49,6 +49,12 @@ export async function runVerify(
   // other's children.
   const runId = crypto.randomUUID().slice(0, 8);
   const run = async (step: VerifyStep, stepCtx: VerifyContext): Promise<void> => {
+    // A progress listener, like `onStep` below: one that throws must not take the gate down.
+    try {
+      ctx.onStepStart?.(step.name);
+    } catch {
+      // The step still runs; its line still reaches `onStep` and the document.
+    }
     const ran = await runStep(step, stepCtx, floor, runId);
     byName.set(step.name, ran.result);
     if (ran.coverage !== undefined) {
@@ -131,6 +137,9 @@ export async function runVerify(
       // `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 machine the deadlines were stretched for, when the entry point measured one: a step
+      // that timed out at ×1 and one that timed out at ×6 are different findings.
+      ...(ctx.pace === undefined ? {} : { pace: { ...ctx.pace } }),
     },
     // The step's own status: one step, so `failedSteps` is that step and nothing else.
     exitCode: failedSteps.length === 0 ? 0 : 1,
@@ -239,7 +248,11 @@ async function runStep(
   // 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 deadline = stepDeadline(
+    step.name,
+    [ctx.stepTimeoutMs, floor?.stepTimeoutMs],
+    ctx.pace?.factor ?? 1,
+  );
   const guard = guardStep(ctx.runner, `${step.name}@${runId}`);
   const raced = await raceDeadline(
     step.run({ ...ctx, runner: guard.runner }).catch(
@@ -248,10 +261,10 @@ async function runStep(
         findings: [findingOf(error, step.name, command)],
       }),
     ),
-    limit,
+    deadline.ms,
   );
   const outcome: StepOutcome = raced.timedOut
-    ? await expired(step.name, limit, guard, command)
+    ? await expired(step.name, deadline, 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.
@@ -293,7 +306,7 @@ 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,
+  deadline: StepDeadline,
   guard: StepGuard,
   command: string,
 ): Promise<StepOutcome> {
@@ -301,7 +314,7 @@ async function expired(
   const output = stalledOutput(expiry);
   return {
     ok: false,
-    findings: [stepTimeoutFinding(step, limit, expiry, command)],
+    findings: [stepTimeoutFinding(step, deadline, expiry, command)],
     ...(output === undefined ? {} : { output }),
   };
 }

package/src/verify-stalled.ts

@@ -5,7 +5,7 @@
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Finding } from './output';
 import { quoteArg } from './shell-quote';
-import type { InFlightRun, StepExpiry, StepProgress } from './verify-deadline';
+import type { InFlightRun, StepDeadline, StepExpiry, StepProgress } from './verify-deadline';
 import { STEP_TIMEOUT_FIELD } from './verify-deadline';
 import type { VerifyStepName } from './verify-step';
 
@@ -30,6 +30,8 @@ export type StalledRun = {
 export type StepTimeoutMeta = {
   readonly step: string;
   readonly deadlineMs: number;
+  /** Set when `deadlineMs` is the declared number stretched to this machine (`verify-pace.ts`). */
+  readonly pace?: number;
   readonly killed: readonly { readonly pid: number; readonly command: string }[];
   readonly inFlight: readonly StalledRun[];
   /** The runs that had finished before the deadline — the step's progress. */
@@ -147,6 +149,12 @@ const inFlightClause = (runs: readonly StalledRun[], expiry: StepExpiry): string
     : `; its running "${runs[0].command}" named no file still in flight, so the run itself did not exit${waiting.runningMs === undefined ? '' : ` after ${seconds(waiting.runningMs)} s`}`;
 };
 
+/** Said only when the deadline was stretched: a reader comparing it with the declared one asks. */
+const pacedClause = (deadline: StepDeadline): string =>
+  deadline.pace === undefined
+    ? ''
+    : ` (the declared ${String(Math.round(deadline.ms / deadline.pace))} ms at this machine's pace, ×${String(deadline.pace)})`;
+
 /**
  * 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
@@ -155,10 +163,11 @@ const inFlightClause = (runs: readonly StalledRun[], expiry: StepExpiry): string
  */
 export const stepTimeoutFinding = (
   step: VerifyStepName,
-  ms: number,
+  deadline: StepDeadline,
   expiry: StepExpiry,
   command: string,
 ): Finding => {
+  const ms = deadline.ms;
   const runs = expiry.inFlight.flatMap((run) => stalledRun(run) ?? []);
   const stuck = runs.flatMap((run) => run.stuck);
   const rerun = `${command} --only ${step} --json`;
@@ -169,6 +178,7 @@ export const stepTimeoutFinding = (
   const meta: StepTimeoutMeta = {
     step,
     deadlineMs: ms,
+    ...(deadline.pace === undefined ? {} : { pace: deadline.pace }),
     killed: expiry.killed.map((one) => ({ pid: one.pid, command: one.command })),
     inFlight: runs,
     finished: expiry.finished ?? { runs: 0, slowestMs: 0 },
@@ -176,7 +186,7 @@ export const stepTimeoutFinding = (
   const wider = `${command} --only ${step} --workers <n> --json`;
   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)}`,
+    cause: `step "${step}" did not finish within its ${String(ms)} ms deadline${pacedClause(deadline)}, so it was stopped and ${String(expiry.killed.length)} process(es) it had started were killed${inFlightClause(runs, expiry)}`,
     fix: outgrewDeadline(runs, expiry)
       ? `${wider}   # it outgrew its deadline at this width, so run it wider; or raise the deadline in x.verify.json — add "${STEP_TIMEOUT_FIELD}": { "${step}": <milliseconds> } above the ${String(ms)} it was given`
       : stuck.length > 0

package/src/verify-step.ts

@@ -9,6 +9,7 @@ import { execOutput } from './exec';
 import type { Finding, ShardFacts, StepResult } from './output';
 import type { TestCounts } from './test-counts';
 import type { StepTimeouts } from './verify-deadline';
+import type { MachinePace } from './verify-pace';
 
 /**
  * Every step of the gate, in cost order — cheapest and most informative first, and never a check
@@ -114,12 +115,25 @@ export interface VerifyContext {
    * with `X_VERIFY_STEP_TIMEOUT` and every process it started is killed.
    */
   readonly stepTimeoutMs?: StepTimeouts;
+  /**
+   * How much slower this machine runs than the 4-core runner the declared deadlines were measured
+   * on (`verify-pace.ts`): each step class's deadline, Bun's per-test default and a test's own
+   * declared timeout (`ULTIMATE_TEST_PACE`) are multiplied by it. Measured by the entry point —
+   * `x verify`, `x build`, the MCP host, the framework root's `scripts/verify.ts` — once, before
+   * any step. Absent is the numbers as declared.
+   */
+  readonly pace?: MachinePace;
   /**
    * 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;
+  /**
+   * Called as each step starts. The heartbeat (`verify-progress.ts`) names the steps between this
+   * and `onStep`: one step can run longer than a harness's silence budget on its own.
+   */
+  readonly onStepStart?: (name: VerifyStepName) => 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

package/src/verify-test-run.ts

@@ -14,6 +14,8 @@ import { tidyBeforeTestRun } from './test-housekeeping';
 import type { TestFile } from './test-select';
 import { failureOf, TEST_TIMINGS_FILE, testArgs } from './test-shards';
 import { BATCH_FILES_PER_WORKER, SHARED_BATCH_FILES_PER_WORKER } from './test-workers';
+import type { MachinePace } from './verify-pace';
+import { defaultTimeoutArgs, paceEnv } from './verify-pace';
 import type { StepOutcome } from './verify-step';
 // Type-only, so nothing here evaluates verify-tests.ts and the two files cannot form a cycle.
 import type { TestType } from './verify-tests';
@@ -34,6 +36,8 @@ export interface ParallelRunOptions {
   readonly widthReason?: string;
   /** The machine-pool lease (`test-slots.ts`), for a default-width run. */
   readonly lease?: (want: number) => Promise<{ readonly count: number; release(): void }>;
+  /** The machine's pace (`verify-pace.ts`): each test's default and declared deadline stretch by it. */
+  readonly pace?: MachinePace;
 }
 
 /**
@@ -56,6 +60,7 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
   const envOverrides = {
     ...testEnvOverrides(options.root, options.env ?? Bun.env),
     ...(options.isolate === true ? { [ISOLATED_ENV]: '1' } : {}),
+    ...paceEnv(options.pace),
   };
   // Batched exactly as `x test` batches the same selection at the same width, so the gate's
   // `fix:` line — `x test <type> --workers N` — reruns the very processes that failed.
@@ -77,6 +82,7 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
         workers: width,
         isolate: options.isolate === true,
         timings: join(options.root, TEST_TIMINGS_FILE),
+        passthrough: defaultTimeoutArgs(options.pace),
       }),
     options: {
       cwd: options.root,

package/src/verify-tests.ts

@@ -27,6 +27,8 @@ import { availableCpus, SERIAL_TYPES, totalMemory, workerPlan } from './test-wor
 import { runCovered } from './verify-coverage-run';
 import { withE2eApp } from './verify-e2e';
 import { readVerifyFloor } from './verify-floor';
+import type { MachinePace } from './verify-pace';
+import { DECLARED_PACE, defaultTimeoutArgs, pacedMs, paceEnv } from './verify-pace';
 import { shardFiles } from './verify-shard';
 import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 import { fromExec, fromFindings } from './verify-step';
@@ -153,18 +155,24 @@ export const typeFiltersOf = (type: Exclude<TestType, 'unit'>): readonly string[
  */
 export const E2E_TEST_TIMEOUT_MS = 60_000;
 
-/** Unit is everything the typed suites do not claim, so no test can fall between two steps. */
-export const testStepCommand = (type: TestType): readonly string[] =>
+/**
+ * Unit is everything the typed suites do not claim, so no test can fall between two steps. Each
+ * per-test default is read at the machine's `pace` (`verify-pace.ts`).
+ */
+export const testStepCommand = (type: TestType, pace?: MachinePace): readonly string[] =>
   type === 'unit'
     ? [
         'bun',
         'test',
+        ...defaultTimeoutArgs(pace),
         ...ignoreFlags([...NEVER_A_TEST, '**/e2e/**', `**/*.${TYPED_SUFFIXES}.test.*`]),
       ]
     : [
         'bun',
         'test',
-        ...(type === 'e2e' ? [`--timeout=${String(E2E_TEST_TIMEOUT_MS)}`] : []),
+        ...(type === 'e2e'
+          ? [`--timeout=${String(pacedMs(E2E_TEST_TIMEOUT_MS, pace ?? DECLARED_PACE))}`]
+          : defaultTimeoutArgs(pace)),
         ...ignoreFlags([...NEVER_A_TEST, ...disownedBy(type)]),
         ...typeFiltersOf(type),
       ];
@@ -193,8 +201,8 @@ const filesFor = async (root: string, type: TestType): Promise<readonly TestFile
 export const resetTestDiscovery = (): void => discovered.clear();
 
 const runSerial = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome> => {
-  const command = testStepCommand(type);
-  const envOverrides = testEnvOverrides(ctx.root, ctx.env ?? Bun.env);
+  const command = testStepCommand(type, ctx.pace);
+  const envOverrides = { ...testEnvOverrides(ctx.root, ctx.env ?? Bun.env), ...paceEnv(ctx.pace) };
   const exec = (e2e: { command: readonly string[]; env: typeof envOverrides }) =>
     ctx.runner(e2e.command, {
       cwd: ctx.root,
@@ -259,6 +267,7 @@ const runType = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome>
       widthReason,
       shard,
       lease,
+      pace: ctx.pace,
     });
   }
   const outcome = await runParallel({
@@ -271,6 +280,7 @@ const runType = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome>
     widthReason,
     ...(lease === undefined ? {} : { lease }),
     ...(ctx.env === undefined ? {} : { env: ctx.env }),
+    ...(ctx.pace === undefined ? {} : { pace: ctx.pace }),
   });
   return shard === undefined ? outcome : { ...outcome, shard };
 };
@@ -294,6 +304,7 @@ const coveredUnit = async (
     readonly widthReason: string;
     readonly shard: ReturnType<typeof shardFiles> | undefined;
     readonly lease: ReturnType<typeof machineLease> | undefined;
+    readonly pace: MachinePace | undefined;
   },
 ): Promise<StepOutcome> => {
   const { coverage, ...outcome } = await runCovered({
@@ -305,6 +316,7 @@ const coveredUnit = async (
     widthReason: run.widthReason,
     ...(run.lease === undefined ? {} : { lease: run.lease }),
     ...(ctx.env === undefined ? {} : { env: ctx.env }),
+    ...(run.pace === undefined ? {} : { pace: run.pace }),
   });
   if (!outcome.ok) return run.shard === undefined ? outcome : { ...outcome, shard: run.shard };
   if (run.shard !== undefined) {