@ultimat3/cli 16.0.0 → 18.0.0

package/src/templates/naming.ts

@@ -79,6 +79,17 @@ export const plural = (input: string): string => {
 
 export const titleKey = (input: string): string => `app.${kebab(input)}.title`;
 
+/**
+ * A human title from a slug: `ledger-demo` -> `Ledger Demo`. Its one caller is the scaffolded
+ * `pwa.name`, which is what a browser shows a person in the install prompt — `app.name` is a slug
+ * by `NAME_RE` and `pascal` would offer to install `LedgerDemo`. Not a `NameSet` member: every
+ * other field there names a code identifier, and this one is prose.
+ */
+export const titleCase = (input: string): string =>
+  words(input)
+    .map((word) => `${word[0]?.toUpperCase() ?? ''}${word.slice(1)}`)
+    .join(' ');
+
 export interface NameSet {
   readonly raw: string;
   readonly kebab: string;

package/src/templates/scaffold-repo.ts

@@ -8,6 +8,7 @@ import { ENV_EXAMPLE_PATH } from '@ultimat3/core';
 import { VERIFY_FLOOR_FILE } from '../verify-floor';
 import type { VerifyStepName } from '../verify-step';
 import type { GeneratedFile, NameSet } from './naming';
+import { titleCase } from './naming';
 import { dbPackageFiles } from './scaffold-db-package';
 import { docsFiles } from './scaffold-docs';
 import { domainPackageFiles } from './scaffold-domain-package';
@@ -180,7 +181,19 @@ export const config = defineConfig({
   jobs: { queues: ['${app.kebab}-default'], concurrency: 4 },
   // In-process transport by default; set urlEnv and transport: 'nats' to scale past one node.
   realtime: { enabled: true, transport: 'memory' },
-  pwa: { enabled: true, offline: 'runtime' },
+  // \`name\` and \`colors\` are what an install prompt shows and what a browser paints the splash
+  // with before any stylesheet has loaded — the four values the framework cannot derive, so
+  // \`defineConfig\` refuses \`pwa.enabled: true\` without them. Raw hex is legal here and nowhere
+  // else in an app.
+  pwa: {
+    enabled: true,
+    offline: 'runtime',
+    name: '${titleCase(app.raw)}',
+    colors: {
+      light: { themeColor: '#1b1f3b', backgroundColor: '#ffffff' },
+      dark: { themeColor: '#1b1f3b', backgroundColor: '#0b0d1a' },
+    },
+  },
   ai: { mcp: { expose: true, path: '/mcp' } },
 });
 `;

package/src/test-shards.ts

@@ -1,7 +1,37 @@
-// Spending the selected test files: the LPT plan that balances them across worker processes, the
-// argv each child gets, and the command that reproduces one shard exactly. Split out of
-// cmd-test.ts because a printed reproduction is only true if it carries every input to the split —
-// that rule is this file's, and argv parsing is that one's.
+// Spending the selected test files: the argv one `bun test` run gets, and the command that
+// reproduces it exactly. Split out of cmd-test.ts because a printed reproduction is only true if
+// it carries every input to the run — that rule is this file's, and argv parsing is that one's.
+//
+// ONE PROCESS, N WORKERS, `As of 2026-08-27`. This file used to pack the files into N bins itself
+// (largest-first greedy over file SIZE) and `Promise.all` one `bun test` per bin. Bun 1.4 runs the
+// pool itself — `--parallel=N`, which starts each file on the next free worker — so the packer is
+// deleted rather than improved.
+//
+// THE PACKER WAS NOT COSTING TIME, AND THAT IS THE FINDING. Four interleaved runs of each form,
+// one machine, the same 1296-file unit corpus, 8 workers:
+//
+//   8x `bun test --isolate`, hand-packed   58.2s  60.0s  65.0s  66.5s
+//   1x `bun test --parallel=8`             54.5s  57.8s  61.7s  64.5s
+//
+// Within noise of each other, because both are already work-bound. `--update-timings` measures the
+// corpus at 436.7s of file time, so eight workers cannot beat 54.6s however the files are dealt,
+// and the slowest single file is 20.5s — far under that floor, so no one file sets it either. A
+// greedy pack of 1296 small items lands near-optimal by accident, which is why bytes being a poor
+// proxy for time never showed up as a wall. The change buys the DELETION, not the seconds: this
+// file's packer and its `Shard` type gone, one process instead of eight, and Bun's own summary
+// instead of eight merged ones (issue #342).
+//
+// `--timings` IS REFUSED FOR THE SAME REASON. Bun will start the slowest files first from a
+// recorded timings file, but there is at most the ~5s between the measured 59.8s median and the
+// 54.6s floor in it — against a committed JSON that goes stale on every test edit and that nothing
+// in the gate would notice had gone stale.
+//
+// TWO THINGS THE OLD SPLIT OWNED AND BUN NOW OWNS. `--parallel` implies `--isolate`, so the
+// per-FILE module registry that made an arbitrary partition safe at all is unchanged. And the
+// per-WORKER database survives untouched: `@ultimat3/testing`'s `workerId` already read
+// `BUN_TEST_WORKER_ID` as its second key, which is exactly what Bun sets, 1..N, one per real
+// process (probed on 1.4.0). `ULTIMATE_TEST_WORKER` stays the first key and is what `--worker`
+// still sets, so a single-shard rerun keeps naming its own database.
 
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { AffectedSelection } from './affected';
@@ -11,82 +41,75 @@ import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue, StepResult } from './output';
 import { quoteArg } from './shell-quote';
 import type { TestFile } from './test-select';
-import { bySizeThenPath } from './test-select';
 import type { TestType } from './verify-tests';
 
-export interface Shard {
-  readonly index: number;
-  readonly files: readonly string[];
-  readonly bytes: number;
-}
-
 /**
- * Largest-first greedy bin packing (LPT). Deterministic — the total order is (size desc, path asc),
- * so the filesystem's scan order never reaches the assignment and a CI failure on worker 3 is the
- * same worker 3 locally. Balanced — every file lands in the currently emptiest bin, which bounds a
- * bin at average + largest file; round-robin or hashing can pile every slow file onto one worker.
- * The inner scan is O(files × workers), and workers is a core count, so a heap would only add
- * allocation.
+ * The argv for one run. An explicit file list, never a re-glob: discovery already decided which
+ * files belong to this type, and a child that globs again can pick up a file the selection removed.
+ *
+ * `--parallel=N` for the whole selection, `--shard=i+1/N` for one slice of it. The shard form is
+ * `--worker`'s, and it carries `--isolate` in its own right — only `--parallel` implies it, and a
+ * partition without a fresh module registry per file is the failure mode this whole design exists
+ * to remove: measured on this repo, an 8-way split turned 0 failures into 36, every one
+ * `X_PERMISSION_UNKNOWN` in `@ultimat3/query` because the `packages/cli` file that had been
+ * declaring `feed:read` for it landed elsewhere. Half a dozen registries here are process-global by
+ * design — the permission set, the roles, the entity/action/query tables, the error-code titles,
+ * the fixture bag — and a serial `bun test` only passes because glob order happens to put every
+ * declaring file before every file that reads what it left behind.
+ *
+ * Bun's shard partition is round-robin over the list it is given, so the sorted list this hands it
+ * makes `--shard=2/8` the same 1/8 on CI and on a laptop (probed on 1.4.0).
  */
-export function planShards(files: readonly TestFile[], workers: number): readonly Shard[] {
-  const count = Math.max(1, Math.min(Math.trunc(workers), files.length));
-  const loads = new Array<number>(count).fill(0);
-  const buckets: string[][] = Array.from({ length: count }, () => []);
-  for (const file of [...files].sort(bySizeThenPath)) {
-    let target = 0;
-    for (let i = 1; i < count; i += 1) if ((loads[i] ?? 0) < (loads[target] ?? 0)) target = i;
-    buckets[target]?.push(file.path);
-    loads[target] = (loads[target] ?? 0) + file.bytes;
-  }
-  return buckets.map((paths, index) => ({
-    index,
-    files: [...paths].sort(),
-    bytes: loads[index] ?? 0,
-  }));
+export function testArgs(input: {
+  readonly files: readonly string[];
+  readonly workers: number;
+  /** 0-based, matching `--worker`. Absent runs the whole selection across `workers` processes. */
+  readonly shard?: number;
+}): readonly string[] {
+  const files = [...input.files].sort();
+  return input.shard === undefined
+    ? ['bun', 'test', `--parallel=${String(input.workers)}`, ...files]
+    : [
+        'bun',
+        'test',
+        '--isolate',
+        `--shard=${String(input.shard + 1)}/${String(input.workers)}`,
+        ...files,
+      ];
 }
 
 /**
- * Explicit file list, so the child never re-globs and can never pick up another shard's files.
- *
- * `--isolate` is what makes an arbitrary partition safe, and it is not optional. Half a dozen
- * registries in this framework are process-global by design — the permission set, the roles, the
- * entity/action/query tables, the error-code titles, the fixture bag — and a serial `bun test`
- * only passes because glob order happens to put every declaring file before every file that reads
- * what it left behind. Re-partition the same files and that accident is gone: measured on this
- * repo, an 8-way split turned 0 failures into 36, all of them `X_PERMISSION_UNKNOWN` in
- * `@ultimat3/query` because the `packages/cli` file that had been declaring `feed:read` for it
- * landed in another shard. A fresh module registry per FILE removes the channel entirely, so the
- * split can be any split. The database is isolated per WORKER, not per file — one cloned template
- * per process, which is `ULTIMATE_TEST_WORKER` below.
+ * The files an argv selects, flags stripped. `bun test` takes its file list positionally, so this
+ * is the inverse of `testArgs` and the one thing a test asserting "what did the child get?" needs
+ * — the flag COUNT is not fixed (`--parallel=N` is one token, a shard run carries two more), and a
+ * test slicing a hardcoded prefix length reads a flag as a filename the day that changes.
  */
-export const SHARD_COMMAND_PREFIX = ['bun', 'test', '--isolate'] as const;
-
-export const shardArgs = (shard: Shard): readonly string[] => [
-  ...SHARD_COMMAND_PREFIX,
-  ...shard.files,
-];
+export const filesIn = (command: readonly string[]): readonly string[] =>
+  command.slice(2).filter((arg) => !arg.startsWith('--'));
 
 export interface ReproduceOptions {
-  /** The *effective* worker count: `planShards` clamps to the file count, and the split follows. */
+  /** The *effective* worker count: the run clamps it to the file count, and the rerun follows. */
   readonly workers: number;
   readonly filter?: string;
   readonly type?: TestType;
   /** Files `--sample` kept, so the rerun samples the same corpus instead of the whole type. */
   readonly sample?: number;
   /**
-   * The `--affected` narrowing, when there was one. The fourth input to the split and the one most
-   * easily forgotten: `--affected` decides which files exist to shard at all, so a rerun without it
-   * re-splits the WHOLE corpus and its shard 2 is a different shard 2.
+   * The `--affected` narrowing, when there was one. The input most easily forgotten: `--affected`
+   * decides which files exist to run at all, so a rerun without it selects the WHOLE corpus and
+   * its shard 2 is a different shard 2.
    */
   readonly affected?: AffectedSelection;
+  /** 0-based, when reproducing ONE shard. Absent reproduces the whole selection. */
+  readonly shard?: number;
 }
 
 /**
- * Every input to the split, printed back. The type, `--filter` and `--affected` decide which files
- * exist to shard, `--sample` decides how many of them survive, `--workers` decides the bins — drop
- * any one and the command still runs, over a different file set, which reproduces nothing.
+ * Every input to the run, printed back. The type, `--filter` and `--affected` decide which files
+ * exist, `--sample` decides how many of them survive, `--workers` decides the width — drop any one
+ * and the command still runs, over a different file set, which reproduces nothing.
  */
-export function reproduceFor(shard: Shard, options: ReproduceOptions): string {
+export function reproduceFor(options: ReproduceOptions): string {
   return [
     'x test',
     ...(options.type === undefined ? [] : [quoteArg(options.type)]),
@@ -100,8 +123,7 @@ export function reproduceFor(shard: Shard, options: ReproduceOptions): string {
     ...(options.affected?.dirty === true ? ['--dirty'] : []),
     '--workers',
     String(options.workers),
-    '--worker',
-    String(shard.index),
+    ...(options.shard === undefined ? [] : ['--worker', String(options.shard)]),
   ].join(' ');
 }
 
@@ -110,104 +132,116 @@ export interface RunShardsOptions {
   readonly runner: Runner;
   readonly files: readonly TestFile[];
   readonly workers: number;
-  /** Run exactly one shard of the same split, not a one-worker run of everything. */
+  /** Run exactly one shard of the same N-way split, not a one-worker run of everything. */
   readonly only?: number;
   readonly filter?: string;
   readonly type?: TestType;
   /**
    * Set when `--sample` narrowed `files`: `kept` is what survived, `total` what discovery found.
-   * `kept` is carried rather than counted from the shards that ran, because `--worker N` runs one
-   * shard of the sample and would otherwise report that shard's size as the corpus.
+   * `kept` is carried rather than counted from what ran, because `--worker N` runs one shard of the
+   * sample and would otherwise report that shard's size as the corpus.
    */
   readonly sample?: { readonly kept: number; readonly total: number };
   /** Passed straight to `reproduceFor`: see `ReproduceOptions.affected`. */
   readonly affected?: AffectedSelection;
 }
 
-/** The reproduction's inputs, resolved once: `workers` is the split's real width, not the ask. */
+/** The reproduction's inputs, resolved once: `workers` is the run's real width, not the ask. */
 const planOf = (options: RunShardsOptions, workers: number): ReproduceOptions => ({
   workers,
   ...(options.filter === undefined ? {} : { filter: options.filter }),
   ...(options.type === undefined ? {} : { type: options.type }),
   ...(options.sample === undefined ? {} : { sample: options.sample.kept }),
   ...(options.affected === undefined ? {} : { affected: options.affected }),
+  ...(options.only === undefined ? {} : { shard: options.only }),
 });
 
-const failureOf = (shard: Shard, code: number, plan: ReproduceOptions): Finding => ({
-  code: 'X_TEST_SHARD_FAILED',
-  cause: `shard ${shard.index} of ${plan.workers} exited ${code} (${shard.files.length} file(s))`,
-  fix: reproduceFor(shard, plan),
+/**
+ * `X_TEST_SHARD_FAILED` for a `--worker` run and `X_TEST_FAILED` for a whole one, because the two
+ * name different reruns: a shard is reproduced by naming it, and a full run by rerunning it. Both
+ * codes already exist and both are already documented — a third would be a new name for a failed
+ * `bun test`.
+ */
+export const failureOf = (code: number, files: number, plan: ReproduceOptions): Finding => ({
+  code: plan.shard === undefined ? 'X_TEST_FAILED' : 'X_TEST_SHARD_FAILED',
+  cause:
+    plan.shard === undefined
+      ? `${plan.type ?? 'test'} run exited ${code} across ${plan.workers} worker(s) (${files} file(s))`
+      : `shard ${plan.shard} of ${plan.workers} exited ${code} (${files} file(s))`,
+  fix: reproduceFor(plan),
   docs: ERROR_DOCS_URL,
 });
 
+/**
+ * ONE `bun test`, not one per worker. Bun owns the pool and hands each free worker the next file,
+ * so nothing here decides which file runs where — see this file's header for what that measured.
+ *
+ * `ULTIMATE_TEST_WORKER` is still set for a `--worker` rerun and only then: that run is one
+ * process, so naming its database is this file's to do. A `--parallel` run has N of them and Bun
+ * numbers each with `BUN_TEST_WORKER_ID`, which `@ultimat3/testing`'s `workerId` already reads.
+ */
 export async function runShards(options: RunShardsOptions): Promise<CommandResult> {
-  const shards = planShards(options.files, options.workers);
+  const files = options.files.map((file) => file.path);
+  const workers = Math.max(1, Math.min(Math.trunc(options.workers), files.length || 1));
   const only = options.only;
-  const chosen = only === undefined ? shards : shards.filter((shard) => shard.index === only);
   const started = performance.now();
-  // All shards at once: wall-clock is the whole point, and each one owns a separate database.
-  const runs = await Promise.all(
-    chosen.map(async (shard) => ({
-      shard,
-      result: await options.runner(shardArgs(shard), {
-        cwd: options.root,
-        env: { ULTIMATE_TEST_WORKER: String(shard.index) },
-      }),
-    })),
+  const result = await options.runner(
+    testArgs({ files, workers, ...(only === undefined ? {} : { shard: only }) }),
+    {
+      cwd: options.root,
+      ...(only === undefined ? {} : { env: { ULTIMATE_TEST_WORKER: String(only) } }),
+    },
   );
   const durationMs = Math.round(performance.now() - started);
-  const plan = planOf(options, shards.length);
-  const steps: readonly StepResult[] = runs.map(({ shard, result }) => ({
-    name: `shard ${shard.index} · ${shard.files.length} files`,
-    ok: result.ok,
-    durationMs: result.durationMs,
-    findings: result.ok ? [] : [failureOf(shard, result.code, plan)],
-    output: execOutput(result),
-  }));
-  const failed = runs.filter((run) => !run.result.ok).map((run) => run.shard.index);
-  const fileCount = chosen.reduce((total, shard) => total + shard.files.length, 0);
+  const plan = planOf({ ...options, workers }, workers);
   const type = options.type;
   const typeParam = type === undefined ? {} : { type };
   const sample = options.sample;
+  const label = only === undefined ? `${workers} worker(s)` : `shard ${only} of ${workers}`;
+  const steps: readonly StepResult[] = [
+    {
+      name: `${label} · ${files.length} files`,
+      ok: result.ok,
+      durationMs: result.durationMs,
+      // `output.ts` documents this field as absent for a NON-test step, so omitting it here made
+      // `renderJson` describe the test step as one — recoverable only by parsing `name`.
+      workers,
+      findings: result.ok ? [] : [failureOf(result.code, files.length, plan)],
+      output: execOutput(result),
+    },
+  ];
   const data: JsonValue = {
     ...typeParam,
-    workers: shards.length,
-    files: fileCount,
+    workers,
+    files: files.length,
     durationMs,
     ...(options.filter === undefined ? {} : { filter: options.filter }),
     ...(sample === undefined ? {} : { sample: { kept: sample.kept, total: sample.total } }),
-    shards: runs.map(({ shard, result }) => ({
-      index: shard.index,
-      files: shard.files.length,
-      bytes: shard.bytes,
-      ok: result.ok,
-      exitCode: result.code,
-      durationMs: result.durationMs,
-      reproduce: reproduceFor(shard, plan),
-    })),
-    failed,
+    ...(only === undefined ? {} : { shard: only }),
+    ok: result.ok,
+    exitCode: result.code,
+    reproduce: reproduceFor(plan),
   };
   return {
-    ok: failed.length === 0,
+    ok: result.ok,
     command: 'test',
-    summary:
-      failed.length === 0
-        ? msg(type === undefined ? 'cli.test.pass' : 'cli.test.type.pass', {
-            ...typeParam,
-            files: fileCount,
-            workers: chosen.length,
-            ms: durationMs,
-          })
-        : msg(type === undefined ? 'cli.test.fail' : 'cli.test.type.fail', {
-            ...typeParam,
-            failed: failed.length,
-            workers: chosen.length,
-          }),
+    summary: result.ok
+      ? msg(type === undefined ? 'cli.test.pass' : 'cli.test.type.pass', {
+          ...typeParam,
+          files: files.length,
+          workers,
+          ms: durationMs,
+        })
+      : msg(type === undefined ? 'cli.test.fail' : 'cli.test.type.fail', {
+          ...typeParam,
+          failed: 1,
+          workers,
+        }),
     steps,
     ...(sample === undefined
       ? {}
       : { lines: [msg('cli.test.sampled', { ...sample, type: type ?? 'all' })] }),
     data,
-    exitCode: failed.length === 0 ? 0 : 1,
+    exitCode: result.ok ? 0 : 1,
   };
 }

package/src/ts-scan.ts

@@ -106,7 +106,12 @@ function endOfRegex(text: string, from: number): number {
  * reading one as an opening quote desyncs every literal after it.
  */
 function blankRegions(text: string, strings: boolean): string {
-  const out = [...text];
+  // `split('')` and NOT `[...text]`: the spread yields one element per CODE POINT while every
+  // index below runs over UTF-16 units (`text.length`, `text[i]`). One astral character — an emoji
+  // in a fixture, `piñata 🎉` — and `out` is shorter than `text`, so every write past it lands a
+  // slot early and the returned mask no longer aligns with the input. Measured: 22 files in this
+  // tree desynced, shipped source included, and eight rules read this mask.
+  const out = text.split('');
   const blank = (from: number, to: number): void => {
     for (let n = from; n < to; n += 1) if (out[n] !== '\n') out[n] = ' ';
   };

package/src/verify-test-run.ts

@@ -1,15 +1,13 @@
-// Running one test type across N worker processes and reporting it as one gate step. Split from
-// verify-tests.ts because that file owns which files belong to a type and this one owns what
-// happens to them once selected — a wrong file list is never a race, and a race is never a
-// selection bug.
+// Running one test type as one gate step. Split from verify-tests.ts because that file owns which
+// files belong to a type and this one owns what happens to them once selected — a wrong file list
+// is never a race, and a race is never a selection bug.
 
-import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
 import type { Finding } from './output';
 import { countsOf } from './test-counts';
 import type { TestFile } from './test-select';
-import { planShards, reproduceFor, shardArgs } from './test-shards';
+import { failureOf, testArgs } from './test-shards';
 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';
@@ -18,55 +16,42 @@ export interface ParallelRunOptions {
   readonly root: string;
   readonly runner: Runner;
   readonly files: readonly TestFile[];
-  /** The ask. `planShards` clamps it to the file count, and the report carries what it became. */
+  /** The ask. Clamped to the file count, and the report carries what it became. */
   readonly workers: number;
-  /** Carried into the `fix:` so a failed shard reproduces as `x test <type> --workers N …`. */
+  /** Carried into the `fix:` so a failure reproduces as `x test <type> --workers N`. */
   readonly type: TestType;
 }
 
 /**
- * The whole point is wall-clock, so every shard starts at once. Two things make that safe and
- * neither is optional: `shardArgs` gives each FILE its own module registry (`--isolate`), and
- * `ULTIMATE_TEST_WORKER` gives each PROCESS its own database — `@ultimat3/testing`'s
- * `acquireWorkerDatabase` reads exactly that variable first and clones the migrated template into
- * `…_w<index>`. Rails' numbered test databases, with Postgres doing the copy.
+ * ONE `bun test --parallel=N`, not N processes this file spawns and packs itself.
+ *
+ * Two things make an arbitrary partition safe here and neither is optional. `--parallel` implies
+ * `--isolate`, so every FILE gets a fresh module registry — half a dozen registries in this
+ * framework are process-global by design, and a serial run only passes because glob order happens
+ * to put every declaring file before every file that reads what it left behind (measured: a bare
+ * `bun test packages/` is 282 failures, the same corpus under `--isolate` is 0). And the database
+ * is per WORKER: `@ultimat3/testing`'s `workerId` reads `BUN_TEST_WORKER_ID`, which Bun sets 1..N,
+ * one per real process — so the numbered test databases keep working with nothing threaded here.
+ *
+ * `test-shards.ts`'s header carries what replacing the hand-written packer measured.
  */
 export async function runParallel(options: ParallelRunOptions): Promise<StepOutcome> {
-  const shards = planShards(options.files, options.workers);
-  const runs = await Promise.all(
-    shards.map(async (shard) => ({
-      shard,
-      result: await options.runner(shardArgs(shard), {
-        cwd: options.root,
-        env: { ULTIMATE_TEST_WORKER: String(shard.index) },
-      }),
-    })),
-  );
-  const findings: Finding[] = [];
-  for (const { shard, result } of runs) {
-    if (result.ok) continue;
-    findings.push({
-      code: 'X_TEST_SHARD_FAILED',
-      cause: `${options.type} shard ${shard.index} of ${shards.length} exited ${result.code} (${shard.files.length} file(s))`,
-      // The reproduction has to name every input to the split, or it reruns a different file set:
-      // `reproduceFor` is the one place that rule lives, shared with `x test`.
-      fix: reproduceFor(shard, { workers: shards.length, type: options.type }),
-      docs: ERROR_DOCS_URL,
-    });
-  }
-  // Only the failing shards' output: a green 8-way split would otherwise print eight summaries,
-  // and the reader of a red gate needs the assertion diff, not the seven runs that passed.
-  const output = runs
-    .filter((run) => !run.result.ok)
-    .map((run) => `— shard ${run.shard.index}\n${execOutput(run.result)}`)
-    .join('\n');
+  const files = options.files.map((file) => file.path);
+  const workers = Math.max(1, Math.min(Math.trunc(options.workers), files.length || 1));
+  const result = await options.runner(testArgs({ files, workers }), { cwd: options.root });
+  // `failureOf` is `x test`'s own, imported rather than restated: the two paths report the SAME
+  // failed `bun test`, so a second literal here is two `cause:` strings and two `fix:` lines free
+  // to drift — and the one that drifts is the gate's, which is the one an agent reads first.
+  const findings: readonly Finding[] = result.ok
+    ? []
+    : [failureOf(result.code, files.length, { workers, type: options.type })];
   return {
     ok: findings.length === 0,
     findings,
-    workers: shards.length,
-    // Every shard's summary, including the green ones whose output is dropped above: the counts
-    // are how the ratchet tells a suite that passed from a suite that skipped itself to nothing.
-    tests: countsOf(runs.map((run) => run.result)),
-    ...(output === '' ? {} : { output }),
+    workers,
+    tests: countsOf([result]),
+    // Only on failure: a green run's summary is already the step table's, and the reader of a red
+    // gate needs the assertion diff.
+    ...(result.ok ? {} : { output: execOutput(result) }),
   };
 }