@ultimat3/cli 22.6.1 → 22.7.0

package/src/cmd-dev.ts

@@ -13,8 +13,10 @@ import type { OverlayNotice, RequestContext } from '@ultimat3/http';
 import { asCtx } from '@ultimat3/http';
 import type { Manifest } from '@ultimat3/manifest';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { createIsrController } from '@ultimat3/render/server';
 import { loadSignInPath } from './app-auth';
 import { appManifest } from './app-manifest';
+import { enableReloadTracking } from './app-reload-graph';
 import { requireAppRoot } from './app-root';
 import { loadAppRuntime } from './app-runtime';
 import { devSpec } from './cmd-dev-spec';
@@ -128,6 +130,9 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // EVERY boot: a scratch server (`x shot`, `ui.shot`) boots here too, and without this a
   // fail-closed dev actor installs nothing — the picture is of a 401. Idempotent.
   declareDevEnvironment(options.env);
+  // Before the first scan: the watcher's rescans evict a saved module AND everything importing it,
+  // and that needs the import graph recorded as each module is first loaded (`app-reload-graph.ts`).
+  enableReloadTracking(true);
   // The declaration lands on `process.env`; the env this boot passes on must carry it too, or every
   // service resolved from `options.env` still reads no `ULTIMATE_ENV`.
   const env = needsDevEnvironmentDeclaration(options.env)
@@ -224,7 +229,11 @@ async function bootDev(
   };
   const panels = devPanels(dashboard).map((panel) => panel.key);
 
+  // `x dev`'s own, so a reload can empty it: an `isr` page's first render was otherwise served for
+  // its whole ttl after every save, whatever the modules behind it now said.
+  const isr = createIsrController({ buildId });
   const { routes, theme, errorStyles, mcpPath } = await devRouteTable({
+    isr,
     root: options.root,
     env: options.env,
     buildId,
@@ -283,6 +292,7 @@ async function bootDev(
       state.manifest = manifest;
       state.appFindings = findings;
       state.islands = islands;
+      for (const path of isr.store().paths()) isr.store().delete(path);
       state.reloads += 1;
       state.reloadFinding = undefined;
       options.onReload?.(file, Math.round(performance.now() - started));

package/src/cmd-test-spec.ts

@@ -4,13 +4,13 @@
 import { TEST_TYPES } from '@ultimat3/testing/test-types';
 import { DEFAULT_BASE } from './affected';
 import type { CommandSpec } from './parse';
-import { SERIAL_TYPES, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+import { SERIAL_TYPES, WORKER_BYTES, WORKER_CEILING, WORKER_FLOOR } from './test-workers';
 
 export const testSpec: CommandSpec = {
   name: 'test',
   summary:
     'run one test type — or the whole suite — across N workers, one isolated database per worker',
-  usage: `x test [${TEST_TYPES.join('|')}] [--filter path[,path…]] [--allow-empty] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--json] [-- <bun test flags>]`,
+  usage: `x test [${TEST_TYPES.join('|')}] [--filter path[,path…]] [--allow-empty] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--isolate] [--json] [-- <bun test flags>]`,
   positionalChoices: TEST_TYPES,
   // The one command that hands a tail to another tool — `bun test` — and the reason
   // `CommandSpec.passthrough` exists: `x test unit -- --coverage --bail` parsed both flags and
@@ -20,7 +20,13 @@ export const testSpec: CommandSpec = {
     {
       name: 'workers',
       type: 'string',
-      summary: `bun worker count (default: ${WORKER_OVERSUBSCRIBE}x CPUs rounded up, held to free memory, min ${WORKER_FLOOR}; max ${WORKER_CEILING}); clamped to the file count, and to 1 for ${SERIAL_TYPES.join(' and ')}`,
+      summary: `bun worker count (default: one per ${WORKER_BYTES / 2 ** 30} GiB of a min(4 GiB, max(2.75 GiB, 25% of RAM)) budget, at most one per core; ULTIMATE_TEST_MEMORY_BUDGET and ULTIMATE_TEST_MAX_WORKERS override, min ${WORKER_FLOOR}; max ${WORKER_CEILING}); clamped to the file count, and to 1 for ${SERIAL_TYPES.join(' and ')}`,
+    },
+    {
+      name: 'isolate',
+      type: 'boolean',
+      summary:
+        'a fresh global per test file (bun test --isolate) — off by default since 22.7; x.verify.json "isolate": true makes it the repo default',
     },
     {
       name: 'worker',

package/src/cmd-test.ts

@@ -26,7 +26,16 @@ import {
   sampleFiles,
 } from './test-select';
 import { runShards } from './test-shards';
-import { defaultWorkers, SERIAL_TYPES, WORKER_CEILING } from './test-workers';
+import { machineLease } from './test-slots';
+import type { WorkerPlan } from './test-workers';
+import {
+  availableCpus,
+  SERIAL_TYPES,
+  totalMemory,
+  WORKER_CEILING,
+  workerPlan,
+} from './test-workers';
+import { readVerifyFloor } from './verify-floor';
 import type { TestType } from './verify-tests';
 import { TEST_TYPES } from './verify-tests';
 
@@ -159,7 +168,12 @@ export const testCommand: CliCommand = {
       });
     }
     const files = sample === undefined ? selected : sampleFiles(selected, sample);
-    const requested = readIndex(ctx.args, 'workers', 1) ?? defaultWorkers();
+    const explicit = readIndex(ctx.args, 'workers', 1);
+    const plan =
+      explicit === undefined ? workerPlan(availableCpus(), totalMemory(), ctx.env) : undefined;
+    const requested = explicit ?? (plan as WorkerPlan).workers;
+    const floor = await readVerifyFloor(ctx.cwd);
+    const isolate = flagBool(ctx.args, 'isolate') || floor?.isolate === true;
     // The width a `--worker` index is judged against, and nothing else: which files really run one
     // at a time is `test-passes.ts`, off the FILES rather than off the positional. This line read
     // the positional alone until 2026-09 and the comment here claimed it made a serial type serial
@@ -183,6 +197,10 @@ export const testCommand: CliCommand = {
       env: ctx.env,
       files,
       workers,
+      ...(isolate ? { isolate } : {}),
+      // A default-width run leases its workers from the machine pool, so a second `x test` or
+      // gate on the same box runs narrower instead of doubling its memory.
+      ...(plan === undefined ? {} : withLease(machineLease(plan.workers, ctx.env))),
       ...(only === undefined ? {} : { only }),
       ...(filter === undefined ? {} : { filter }),
       ...(type === undefined ? {} : { type }),
@@ -201,3 +219,8 @@ export const testCommand: CliCommand = {
     return scope === undefined ? result : withScope(result, scope);
   },
 };
+
+const withLease = (
+  lease: ReturnType<typeof machineLease>,
+): { lease?: NonNullable<ReturnType<typeof machineLease>> } =>
+  lease === undefined ? {} : { lease };

package/src/cmd-verify-spec.ts

@@ -2,27 +2,57 @@
 // read it without loading `cmd-verify.ts`, which `registry.ts` imports only when the command runs.
 
 import type { CommandSpec } from './parse';
-import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+import { WORKER_BYTES, WORKER_CEILING, WORKER_FLOOR } from './test-workers';
+
+/** `run` is the gate (and what a bare `x verify` means); `merge` folds CI parts into its verdict. */
+export const VERIFY_SUBCOMMANDS = ['run', 'merge'] as const;
 
 export const verifySpec: CommandSpec = {
   name: 'verify',
   summary: 'the gate: typecheck, lint, boundaries, all tests, drift, contract, budgets',
-  usage: 'x verify [--only <step>[,<step>…]] [--workers N] [--json]',
+  usage:
+    'x verify [--only <step>[,<step>…] [--shard i/n [--timings file]]] [--workers N] [--isolate] [--json] · x verify merge <part.json…> [--json]',
   requiresApp: true,
-  // Two flags, and only one of them narrows. `--workers` changes how wide the test steps
-  // spread, never which steps run. `--only` runs the steps it names and says so in both renderers —
-  // never silently, which is the whole of what makes it safe to have.
+  subcommands: VERIFY_SUBCOMMANDS,
+  defaultSubcommand: 'run',
+  // `--workers` and `--isolate` change how the test steps run, never which steps run. `--only`
+  // runs the steps it names and says so in both renderers — never silently, which is the whole
+  // of what makes it safe to have. `--shard` narrows further, and only `merge` turns shards back
+  // into a gate verdict.
   flags: [
     {
       name: 'workers',
       type: 'string',
-      summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs rounded up, held to free memory; min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+      subcommands: ['run'],
+      summary: `test processes per parallel step (default: one per ${WORKER_BYTES / 2 ** 30} GiB of a min(4 GiB, max(2.75 GiB, 25% of RAM)) budget, at most one per core; ULTIMATE_TEST_MEMORY_BUDGET and ULTIMATE_TEST_MAX_WORKERS override; min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
     },
     {
       name: 'only',
       type: 'string',
+      subcommands: ['run'],
+      summary:
+        'run the named step(s), comma-separated, in one process — an iteration loop or one CI job, NOT A GATE RUN; the gate is this command with no flag, or `x verify merge` over every job',
+    },
+    {
+      name: 'shard',
+      type: 'string',
+      subcommands: ['run'],
+      summary:
+        'with --only unit|contract|job: run shard i of an n-way split of each step’s sorted file list (round-robin), for one CI job; `x verify merge` checks all n',
+    },
+    {
+      name: 'timings',
+      type: 'string',
+      subcommands: ['run'],
+      summary:
+        'with --shard: a bun --timings JSON ({ "path": ms }) — split greedy longest-first instead of round-robin',
+    },
+    {
+      name: 'isolate',
+      type: 'boolean',
+      subcommands: ['run'],
       summary:
-        'run the named step(s), comma-separated, in one process — an iteration loop, NOT A GATE RUN; the gate is this command with no flag',
+        'a fresh global per test file (bun test --isolate) — off by default since 22.7; x.verify.json "isolate": true makes it the repo default',
     },
   ],
 };

package/src/cmd-verify.ts

@@ -7,18 +7,26 @@
 // reader of either can take it for one. `--skip` stays refused — it would let a caller drop the
 // step that was going to fail and still read the output as a whole-tree verdict.
 
+// why: Bun ships no path-joining primitive: `join`/`isAbsolute` resolve a part path against the cwd.
+import { isAbsolute, join } from 'node:path';
 import { nearestName, renderFixShellArg } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import { verifySpec } from './cmd-verify-spec';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError } from './errors';
+import { BadFlagError, MissingPositionalError } from './errors';
 import { readIntFlag } from './flag-number';
-import type { CommandResult } from './output';
+import type { CommandResult, JsonValue } from './output';
 import type { ParsedArgs } from './parse';
-import { flagString } from './parse';
+import { flagBool, flagString } from './parse';
 import { WORKER_CEILING, WORKER_FLOOR } from './test-workers';
 import { VERIFY_STEPS } from './verify-checks';
+import { VerifyMergeInputError, VerifyShardInvalidError } from './verify-errors';
+import { readVerifyFloor } from './verify-floor';
+import type { VerifyPart } from './verify-merge';
+import { mergeParts, parsePart } from './verify-merge';
 import { runVerify } from './verify-run';
+import type { ShardSpec, Timings } from './verify-shard';
+import { assertShardable, parseShard, readTimings } from './verify-shard';
 import type { VerifyStepName } from './verify-step';
 import { VERIFY_STEP_NAMES } from './verify-step';
 
@@ -32,20 +40,88 @@ export const verifyCommand: CliCommand = {
   spec: verifySpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('verify', ctx.cwd).dir;
-    // Both readers before the run: an unrunnable flag must be refused in milliseconds, not after
+    if (ctx.args.subcommand === 'merge') return mergeCommand(root, ctx.args.positionals, ctx.cwd);
+    // Every reader before the run: an unrunnable flag must be refused in milliseconds, not after
     // `tsc -b` has spent fourteen seconds on a run the caller cannot use.
     const workers = readWorkers(ctx.args);
     const only = readOnlySteps(ctx.args);
-    return runVerify(VERIFY_STEPS, {
+    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 }),
     });
+    return shard === undefined ? result : withShardData(result, shard);
   },
 };
 
+/**
+ * `--shard i/n` (and `--timings`), validated before anything runs: only beside `--only`, and only
+ * over the parallel suites. `--timings` without `--shard` is refused rather than ignored.
+ */
+export async function readShard(
+  args: ParsedArgs,
+  only: readonly VerifyStepName[] | undefined,
+): Promise<(ShardSpec & { readonly timings?: Timings }) | undefined> {
+  const raw = flagString(args, 'shard');
+  const timingsPath = flagString(args, 'timings');
+  if (raw === undefined) {
+    if (timingsPath !== undefined) {
+      throw new VerifyShardInvalidError({
+        reason: '--timings balances a --shard split and does nothing without one',
+      });
+    }
+    return undefined;
+  }
+  const spec = parseShard(raw);
+  assertShardable(only);
+  if (timingsPath === undefined) return spec;
+  return { ...spec, timings: await readTimings(timingsPath) };
+}
+
+/** `data.shard`: which slice this part is, per step — what `x verify merge` reads back. */
+const withShardData = (result: CommandResult, shard: ShardSpec): CommandResult => {
+  const data = (result.data ?? {}) as Record<string, JsonValue>;
+  const steps: Record<string, JsonValue> = {};
+  for (const step of result.steps ?? []) {
+    if (step.shard === undefined) continue;
+    steps[step.name] = { corpusHash: step.shard.corpusHash, files: [...step.shard.files] };
+  }
+  return {
+    ...result,
+    data: { ...data, shard: { index: shard.index, total: shard.total, steps } },
+  };
+};
+
+async function mergeCommand(
+  root: string,
+  files: readonly string[],
+  cwd: string,
+): Promise<CommandResult> {
+  if (files.length === 0) {
+    throw new MissingPositionalError({
+      command: 'verify merge',
+      positional: 'part.json…',
+      example: 'x verify merge parts/*.json --json',
+    });
+  }
+  const parts: VerifyPart[] = [];
+  for (const file of files) {
+    const path = isAbsolute(file) ? file : join(cwd, file);
+    const handle = Bun.file(path);
+    if (!(await handle.exists())) {
+      throw new VerifyMergeInputError({ file, reason: 'does not exist' });
+    }
+    parts.push(parsePart(file, await handle.text()));
+  }
+  return mergeParts(parts, await readVerifyFloor(root));
+}
+
 /**
  * The steps `--only` names, or nothing: one step (`--only lint`) or a comma-separated list
  * (`--only typecheck,lint,boundaries`) run in ONE process, in the gate's declared order whatever

package/src/dev-route-table.ts

@@ -5,6 +5,7 @@
 import type { RealtimeConfig } from '@ultimat3/core';
 import type { RateLimitStore, Route } from '@ultimat3/http';
 import { describeRoutes } from '@ultimat3/render';
+import type { IsrController } from '@ultimat3/render/server';
 import type { Storage } from '@ultimat3/storage';
 import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
 import { mountAppMcp } from './app-mcp';
@@ -43,6 +44,11 @@ export interface DevRouteTableInput {
   readonly rateLimitStore?: RateLimitStore | undefined;
   /** `apps/<app>/runtime.ts`'s plain `routes`, mounted as the container mounts them. */
   readonly appRoutes?: readonly Route[] | undefined;
+  /**
+   * The ISR controller the page routes render through — `x dev`'s own, because a reload has to
+   * empty it: a stored render outlives the module that produced it.
+   */
+  readonly isr?: IsrController | undefined;
 }
 
 export interface DevRouteTable {
@@ -126,6 +132,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     ...pagePostRoutes(),
     ...appRoutes({
       buildId: input.buildId,
+      ...(input.isr === undefined ? {} : { isr: input.isr }),
       resolveIsland: (file) => input.islands().resolverFor(file),
       ...(sync.head === undefined ? {} : { sync: sync.head }),
       persisted: sync.persisted,

package/src/error-codes.ts

@@ -198,6 +198,10 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_FEATURE_UNKNOWN',
   'X_ROUTE_ASYNC_PAGE',
   'X_BUDGET_PARAMS_UNDECLARED',
+  'X_TEST_BUDGET_INVALID',
+  'X_VERIFY_SHARD_INVALID',
+  'X_VERIFY_MERGE_INCOMPLETE',
+  'X_VERIFY_MERGE_INPUT',
 ] as const;
 
 /**
@@ -345,6 +349,10 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ROUTE_ASYNC_PAGE: 'a route exports an async Page',
   X_BUDGET_PARAMS_UNDECLARED:
     'a dynamic route with a budget declares no prerender() paths to weigh it by',
+  X_TEST_BUDGET_INVALID: 'a test memory budget or worker cap env var does not parse',
+  X_VERIFY_SHARD_INVALID: 'x verify --shard was given a spec or a step list it cannot split',
+  X_VERIFY_MERGE_INCOMPLETE: 'x verify merge was handed parts that do not add up to the whole gate',
+  X_VERIFY_MERGE_INPUT: 'a part handed to x verify merge is not an x verify --json document',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/mcp-errors.ts

@@ -38,6 +38,11 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_ENV_MISSING: 'x env check --json',
   X_ENV_EXAMPLE_DRIFT: 'x env example --json',
   X_TEST_NO_FILES: 'x test --json   # from the repo root, or pass --cwd to it',
+  X_TEST_BUDGET_INVALID: 'ULTIMATE_TEST_MEMORY_BUDGET=3g x verify --json',
+  X_VERIFY_SHARD_INVALID: 'x verify --only unit --shard 1/4 --json',
+  X_VERIFY_MERGE_INCOMPLETE:
+    'x verify merge parts/*.json --json   # after every CI job uploaded its part',
+  X_VERIFY_MERGE_INPUT: 'x verify --only unit --json > part.json   # one document per part',
   X_TEST_SHARD_FAILED: 'x test --workers 1 --json',
   X_SCAFFOLD_PATH_ESCAPE: 'x g route posts --json   # a path with no ".." segment',
   X_GENERATE_JSON_INVALID:

package/src/messages.ts

@@ -265,6 +265,8 @@ const CATALOG = {
   'cli.test.affected.none': 'nothing is affected by {base}...HEAD — 0 test file(s) ran',
   'cli.test.empty': 'no test file matches {selection} — 0 test file(s) ran (--allow-empty)',
   'cli.test.pass': '{files} test file(s) on {workers} worker(s) passed in {ms}ms',
+  'cli.test.batch': '── batch {batch} of {batches} · {files} file(s) ──',
+  'cli.test.batches': ' · {batches} batches',
   'cli.test.sampled': 'sampled {kept} of {total} {type} file(s)',
   'cli.test.type.fail': '{type} — {failed} of {workers} shard(s) failed',
   'cli.test.type.pass': '{type} — {files} test file(s) on {workers} worker(s) passed in {ms}ms',
@@ -292,6 +294,7 @@ const CATALOG = {
   // included. Its own line and not `allSkipped` with a zero, because the repair differs — there is
   // 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}',
   'cli.verify.serial': 'serial',
   'cli.verify.workers': '{workers} workers',
   'cli.env.checked': '{count} declared variable(s), all present and valid',

package/src/output.ts

@@ -6,6 +6,16 @@ import { ERROR_DOCS_URL, renderThrowable, singleLine, stringField } from '@ultim
 import { msg } from './messages';
 import type { TestCounts } from './test-counts';
 
+/** One shard's share of one step's corpus — what `x verify merge` checks the parts against. */
+export interface ShardFacts {
+  readonly index: number;
+  readonly total: number;
+  /** sha256 of the step's WHOLE sorted file list: every shard of one split carries the same one. */
+  readonly corpusHash: string;
+  /** The files this shard ran. */
+  readonly files: readonly string[];
+}
+
 export interface Finding {
   readonly code: string;
   readonly cause: string;
@@ -31,6 +41,10 @@ export interface StepResult {
   readonly output?: string;
   /** Worker processes the step used; `1` means it ran serially. Absent for a non-test step. */
   readonly workers?: number;
+  /** Why the width is what it is — `4 workers (budget 4.0 GB)`. */
+  readonly widthReason?: string;
+  /** Under `x verify --shard`: this step's slice of its corpus. */
+  readonly shard?: ShardFacts;
   /**
    * What the step's suite executed. Absent for a step that spawned no test process, which is NOT
    * the same state as `{ ran: 0 }` — a step with no suite and a suite whose every test skipped
@@ -175,6 +189,7 @@ const mark = (step: StepResult): string => {
  */
 const width = (step: StepResult): string => {
   if (step.workers === undefined || step.skipped === true) return '';
+  if (step.widthReason !== undefined) return `  ${singleLine(step.widthReason)}`;
   return `  ${step.workers === 1 ? msg('cli.verify.serial') : msg('cli.verify.workers', { workers: step.workers })}`;
 };
 
@@ -227,6 +242,17 @@ export function renderJson(result: CommandResult): string {
     skipped: step.skipped === true,
     findings: step.findings,
     ...(step.workers === undefined ? {} : { workers: step.workers }),
+    ...(step.widthReason === undefined ? {} : { widthReason: step.widthReason }),
+    ...(step.shard === undefined
+      ? {}
+      : {
+          shard: {
+            index: step.shard.index,
+            total: step.shard.total,
+            corpusHash: step.shard.corpusHash,
+            files: [...step.shard.files],
+          },
+        }),
     // The counts the human line's `why()` renders, as numbers: a `--json` reader deciding whether
     // a skipped lane is missing a suite or missing a prerequisite needs the same fact CI's log has.
     ...(step.tests === undefined ? {} : { tests: step.tests }),

package/src/templates/scaffold-docs.ts

@@ -174,7 +174,9 @@ build_flags=""
 for arg in "$@"; do
   case "$arg" in --json|-j) build_flags="--json" ;; esac
 done
-bunx x build --target static $build_flags
+# \`--no-preflight\`: the build's own preflight is x verify's first six steps (typecheck, lint,
+# boundaries, filesize, package-shape, errors), and the gate below runs them anyway — once is enough.
+bunx x build --target static --no-preflight $build_flags
 exec bunx x verify "$@"
 `;
 

package/src/test-batches.ts

@@ -0,0 +1,145 @@
+// Spending one pass as a few `bun test --parallel=N` processes in sequence, not one. The width of
+// a pass is `test-workers.ts`'s to decide; how many files one set of N workers is allowed to chew
+// through before it is thrown away is this file's.
+//
+// WHY THERE IS MORE THAN ONE PROCESS, `As of 2026-09-27`. A `--parallel` worker is not freed file
+// by file: it keeps its heap for the life of the `bun test` process and it GROWS with every file it
+// is handed (JIT, module-resolution caches, PGlite heaps the collector has not yet returned). On
+// notificado.co's unit corpus (768 files, PGlite per file, 12-core box, Bun 1.4.0), whole-tree RSS
+// at 12 workers:
+//
+//   | form                                        | peak tree RSS | wall   |
+//   |---------------------------------------------|---------------|--------|
+//   | 1x `--parallel=12`, 768 files (~64/worker)  | 12.4-13.3 GB  | 134-158s |
+//   | 3x `--parallel=12`, 256 files (~21/worker)  | 10.8-11.4 GB  | 133-147s |
+//   | 6x `--parallel=12`, 128 files (~11/worker)  |  9.7 GB       | 166s   |
+//
+// (Wall is noisy — the box was shared, at load 30-40 — but batching at the same width never
+// measured slower than not batching outside one outlier run.)
+//
+// One process's footprint scales with the files each worker sees, so an unbatched run's peak is a
+// function of the CORPUS: every test file an app adds raises it, and nothing ever gives it back
+// until the run ends. A batch boundary gives all of it back. At `BATCH_FILES_PER_WORKER` files per
+// worker the peak is a function of the WIDTH alone — and the wall clock does not move, because a
+// worker restart costs a second against a batch of ~40s. Halving the batch again bought 1.5 GB for
+// 25% more wall, which is why the constant is not smaller.
+//
+// THE DEAL IS ROUND-ROBIN over the sorted list, so every batch gets a slice of every directory
+// (a slow directory is not one batch's tail) and the split is a pure function of the file list and
+// the width: `x test unit --workers N` reruns exactly the batches the failing run ran.
+
+import type { ExecResult, Runner } from './exec';
+import { execOutput } from './exec';
+import { msg } from './messages';
+import { SLOT_HELD_ENV } from './test-slots';
+import { BATCH_FILES_PER_WORKER } from './test-workers';
+
+/**
+ * The file groups one pass runs as, in order. One group — the list itself — whenever the list fits
+ * in `workers x BATCH_FILES_PER_WORKER`, which is every small selection and every `--filter`.
+ * Otherwise the fewest groups that fit, dealt round-robin so their sizes differ by at most one.
+ */
+export function testBatches(
+  files: readonly string[],
+  workers: number,
+  perWorker: number = BATCH_FILES_PER_WORKER,
+): readonly string[][] {
+  const sorted = [...files].sort();
+  const cap = Math.max(1, Math.trunc(workers)) * Math.max(1, Math.trunc(perWorker));
+  const count = Math.max(1, Math.ceil(sorted.length / cap));
+  const batches: string[][] = Array.from({ length: count }, () => []);
+  sorted.forEach((file, index) => {
+    batches[index % count]?.push(file);
+  });
+  return batches;
+}
+
+/** Every batch's own result, and what they add up to. */
+export interface BatchedRun {
+  /** One per batch, in order — `countsOf` reads each one's own Bun summary. */
+  readonly results: readonly ExecResult[];
+  /** The width each batch really ran at, after the machine lease. */
+  readonly widths: readonly number[];
+  readonly ok: boolean;
+  /** The first non-zero exit, or 0. */
+  readonly code: number;
+  /** Summed: the batches ran one after another. */
+  readonly durationMs: number;
+  /**
+   * Every batch's output, each under a line naming it when there was more than one. One batch is
+   * `execOutput` of it, byte for byte, so a small run reads exactly as it always has.
+   */
+  readonly output: string;
+}
+
+/**
+ * Run `batches` one after another — never `Promise.all`, which would put every batch's workers on
+ * the machine at once and undo the bound — and keep going after a red one, because the caller
+ * asked for the whole selection and a report that stops at the first failure hides the rest. The
+ * one exception is a caller that asked to stop (`stopOnFailure`, i.e. `-- --bail`).
+ */
+export async function runBatches(input: {
+  readonly runner: Runner;
+  readonly batches: readonly (readonly string[])[];
+  /** `width` is the batch's real worker count — the ask, narrowed by the machine lease. */
+  readonly argsFor: (files: readonly string[], width: number) => readonly string[];
+  /** The width each batch asks for; required with `lease`. */
+  readonly workers?: number;
+  /**
+   * Lease the batch's workers from the machine pool (`test-slots.ts`) before it starts, and give
+   * them back when it exits — so two runs on one box share its budget batch by batch.
+   */
+  readonly lease?: (want: number) => Promise<{ readonly count: number; release(): void }>;
+  readonly options: Parameters<Runner>[1];
+  /**
+   * Launch no further batch once one is red. Set for a caller-forwarded `--bail`: Bun stops a
+   * process at its threshold, and without this the next batch would start over from zero.
+   */
+  readonly stopOnFailure?: boolean;
+}): Promise<BatchedRun> {
+  const results: ExecResult[] = [];
+  const widths: number[] = [];
+  for (const files of input.batches) {
+    const want = Math.max(1, Math.min(input.workers ?? files.length, files.length));
+    const lease = input.lease === undefined ? undefined : await input.lease(want);
+    const width = Math.min(want, lease?.count ?? want);
+    let result: ExecResult;
+    try {
+      result = await input.runner(
+        input.argsFor(files, width),
+        lease === undefined
+          ? input.options
+          : { ...input.options, env: { ...input.options.env, [SLOT_HELD_ENV]: '1' } },
+      );
+    } finally {
+      lease?.release();
+    }
+    results.push(result);
+    widths.push(width);
+    if (!result.ok && input.stopOnFailure === true) break;
+  }
+  const first = results.find((result) => !result.ok);
+  const output =
+    results.length === 1
+      ? execOutput(results[0] as ExecResult)
+      : results
+          .map((result, index) =>
+            [
+              msg('cli.test.batch', {
+                batch: index + 1,
+                batches: results.length,
+                files: input.batches[index]?.length ?? 0,
+              }),
+              execOutput(result),
+            ].join('\n'),
+          )
+          .join('\n');
+  return {
+    results,
+    widths,
+    ok: first === undefined,
+    code: first?.code ?? 0,
+    durationMs: results.reduce((sum, result) => sum + result.durationMs, 0),
+    output,
+  };
+}