@ultimat3/cli 22.6.0 → 22.6.2

package/package.json

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

package/src/api-registration.ts

@@ -3,13 +3,11 @@
 // nothing lists keeps the positional `anonymous-job-2` that `job()` minted, on the queue row, in
 // `x.manifest.json` and in every dead-letter trace — under a green gate (plan 101 slice 11 b).
 
+import { API_INDEX } from './app-root';
 import { containedPath } from './generate-write';
 import { camel } from './templates/naming';
 import { wrapList } from './templates/wrap';
 
-/** The one file `defineApi` is called from in a scaffolded app. */
-export const API_INDEX = 'apps/web/api/index.ts';
-
 /** One module to import as a namespace and list under a `defineApi` key. */
 export interface ApiEntry {
   readonly key: 'jobs' | 'tasks';

package/src/app-load.ts

@@ -5,7 +5,7 @@
 
 // Bun ships no `Bun.*` path API: `relative`/`sep` turn an absolute scan hit into the app-root-
 // relative POSIX path every finding and every manifest fact is keyed by.
-import { join, relative, sep } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
 import { listActions, registerActions } from '@ultimat3/action';
 import { describeEntities } from '@ultimat3/entity';
 import { localeConfig } from '@ultimat3/i18n';
@@ -28,7 +28,7 @@ import {
 // accident one refactor away from compiling every app's `.tsx` to `React.createElement`. The named
 // import is a value import, so the side effect holds without the bare line it replaced.
 import { setStylesheetRoot } from '@ultimat3/render/server';
-import { APP_CONFIG_FILE } from './app-root';
+import { API_INDEX, APP_CONFIG_FILE } from './app-root';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';
@@ -116,11 +116,17 @@ export function resetAppLoad(): void {
 }
 
 /**
- * Every module path the app globs match, SORTED. `Bun.Glob` answers in directory order, which is
- * the filesystem's — ext4 hashes names with a per-filesystem seed — so two pods of one image
- * imported the app in two orders, registered its stylesheets in two orders, and served two
- * different `/styles/<hash>.css` for one page (notificado.co, 22.3.2). Import order is the
- * stylesheet cascade's order, so it must be the same everywhere.
+ * Every module path the app globs match, SORTED — with the API index first. `Bun.Glob` answers in
+ * directory order, which is the filesystem's — ext4 hashes names with a per-filesystem seed — so
+ * two pods of one image imported the app in two orders, registered its stylesheets in two orders,
+ * and served two different `/styles/<hash>.css` for one page (notificado.co, 22.3.2). Import order
+ * is the stylesheet cascade's order, so it must be the same everywhere.
+ *
+ * The API index leads because `defineApi({ http: { pathStyle } })` is what every action URL is
+ * derived under: sorted, `apps/admin/**` evaluated before it, and a module-level
+ * `derivePath('signOut').path` there captured the default style's `/api/outs/sign` — a form
+ * posting to a URL no route served (notificado.co, 22.6.0). Anything still evaluated before the
+ * declaration (the index's own imports) is refused at it, `X_ACTION_PATH_DERIVED_EARLY`.
  */
 export async function appModulePaths(root: string): Promise<readonly string[]> {
   // Pattern by pattern, as before — only the order WITHIN a pattern was the filesystem's.
@@ -134,7 +140,9 @@ export async function appModulePaths(root: string): Promise<readonly string[]> {
     }
     found.push(...matched.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)));
   }
-  return found;
+  // Resolved, like the glob's own answers: `loadApp('.')` is a legal call.
+  const index = resolve(root, API_INDEX);
+  return found.includes(index) ? [index, ...found.filter((path) => path !== index)] : found;
 }
 
 export async function loadApp(root: string): Promise<LoadedApp> {

package/src/app-root.ts

@@ -6,6 +6,12 @@ import { dirname, join, resolve } from 'node:path';
 import { BunVersionError, NotInAppError } from './errors';
 
 export const APP_CONFIG_FILE = 'app.config.ts';
+
+/**
+ * The one file `defineApi` is called from in a scaffolded app — here, beside the config file, so
+ * the module scan can import it first without pulling the generators into the serve graph.
+ */
+export const API_INDEX = 'apps/web/api/index.ts';
 export const MANIFEST_FILE = 'x.manifest.json';
 /**
  * The floor the shipped `x` enforces, and it must not sit below what `x` EMITS. It said `1.3.0`

package/src/cmd-test-spec.ts

@@ -4,7 +4,14 @@
 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 {
+  MEMORY_SHARE,
+  SERIAL_TYPES,
+  WORKER_BYTES,
+  WORKER_CEILING,
+  WORKER_FLOOR,
+  WORKER_OVERSUBSCRIBE,
+} from './test-workers';
 
 export const testSpec: CommandSpec = {
   name: 'test',
@@ -20,7 +27,7 @@ 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: ${WORKER_OVERSUBSCRIBE}x CPUs rounded up, held to ${MEMORY_SHARE * 100}% of free memory at ${WORKER_BYTES / 2 ** 30} GiB a worker, min ${WORKER_FLOOR}; max ${WORKER_CEILING}); clamped to the file count, and to 1 for ${SERIAL_TYPES.join(' and ')}`,
     },
     {
       name: 'worker',

package/src/cmd-verify-spec.ts

@@ -2,7 +2,13 @@
 // 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 {
+  MEMORY_SHARE,
+  WORKER_BYTES,
+  WORKER_CEILING,
+  WORKER_FLOOR,
+  WORKER_OVERSUBSCRIBE,
+} from './test-workers';
 
 export const verifySpec: CommandSpec = {
   name: 'verify',
@@ -16,7 +22,7 @@ export const verifySpec: CommandSpec = {
     {
       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})`,
+      summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs rounded up, held to ${MEMORY_SHARE * 100}% of free memory at ${WORKER_BYTES / 2 ** 30} GiB a worker; min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
     },
     {
       name: 'only',

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',

package/src/test-batches.ts

@@ -0,0 +1,114 @@
+// 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 { 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): readonly string[][] {
+  const sorted = [...files].sort();
+  const cap = Math.max(1, Math.trunc(workers)) * BATCH_FILES_PER_WORKER;
+  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[];
+  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[])[];
+  readonly argsFor: (files: readonly string[]) => readonly string[];
+  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[] = [];
+  for (const files of input.batches) {
+    const result = await input.runner(input.argsFor(files), input.options);
+    results.push(result);
+    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,
+    ok: first === undefined,
+    code: first?.code ?? 0,
+    durationMs: results.reduce((sum, result) => sum + result.durationMs, 0),
+    output,
+  };
+}

package/src/test-shards.ts

@@ -2,6 +2,11 @@
 // 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 PER BATCH, N WORKERS. Until 2026-09-27 it was one process for the whole selection;
+// a worker's heap grows with every file it runs, so that process's peak grew with the corpus, and
+// `test-batches.ts` now spends each pass as a few `--parallel=N` processes in sequence — the
+// measurement is its header. Everything below still holds inside a batch.
+//
 // 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
@@ -39,7 +44,6 @@
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { AffectedSelection } from './affected';
 import type { Runner } from './exec';
-import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue, StepResult } from './output';
 import { quoteArg } from './shell-quote';
@@ -48,6 +52,7 @@ import { testEnvOverrides } from './test-dotenv';
 /** `@ultimat3/testing`'s `ISOLATED_ENV`, restated: `cli → testing` is a runtime edge, kept to fixtures. */
 export const ISOLATED_TEST_ENV = 'ULTIMATE_TEST_ISOLATED';
 
+import { runBatches, testBatches } from './test-batches';
 import { testPasses } from './test-passes';
 import type { TestFile } from './test-select';
 import type { TestType } from './verify-tests';
@@ -219,10 +224,10 @@ export const failureOf = (code: number, files: number, plan: ReproduceOptions):
 });
 
 /**
- * ONE `bun test` PER PASS, and one pass unless the selection mixes serial files with the rest —
- * `test-passes.ts` decides that, and this spends it. Bun owns the pool inside a pass 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.
+ * ONE `bun test` PER BATCH, a pass being as many batches as `test-batches.ts` cuts it into, and
+ * one pass unless the selection mixes serial files with the rest — `test-passes.ts` decides that,
+ * and this spends it. Bun owns the pool inside a batch 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.
  *
  * Sequential, never `Promise.all`: the whole point of a serial pass is that nothing runs beside
  * it. And every pass runs even after one fails — the caller asked for a suite, and a report that
@@ -241,6 +246,9 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
     // Every run this spawns is isolated (`--parallel` or `--isolate`) unless the caller opted out.
     ...((options.passthrough ?? []).includes('--no-isolate') ? {} : { [ISOLATED_TEST_ENV]: '1' }),
   };
+  const passthrough = options.passthrough ?? [];
+  const watching = passthrough.includes('--watch');
+  const bailing = passthrough.some((arg) => arg === '--bail' || arg.startsWith('--bail='));
   const passes = testPasses({
     files: options.files,
     workers: options.workers,
@@ -250,18 +258,28 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
   const started = performance.now();
   const steps: StepResult[] = [];
   const spent: JsonValue[] = [];
+  let batchCount = 0;
   let ok = true;
   let exitCode = 0;
   for (const pass of passes) {
     const files = pass.files.map((file) => file.path);
-    const result = await options.runner(
-      testArgs({
-        files,
-        workers: pass.workers,
-        ...(only === undefined ? {} : { shard: only }),
-        ...(options.passthrough === undefined ? {} : { passthrough: options.passthrough }),
-      }),
-      {
+    // A `--worker` rerun is one process over one shard and is never split: shard i of the rerun
+    // must be the same files as shard i of the run it reproduces. Nor is `-- --watch`, which never
+    // exits, so a second batch would never start. Every other pass is spent in `test-batches.ts`'
+    // batches, one `bun test` after another.
+    const batches = only === undefined && !watching ? testBatches(files, pass.workers) : [files];
+    const result = await runBatches({
+      runner: options.runner,
+      batches,
+      stopOnFailure: bailing,
+      argsFor: (batch) =>
+        testArgs({
+          files: batch,
+          workers: Math.min(pass.workers, batch.length),
+          ...(only === undefined ? {} : { shard: only }),
+          ...(options.passthrough === undefined ? {} : { passthrough: options.passthrough }),
+        }),
+      options: {
         cwd: options.root,
         ...(Object.keys(envOverrides).length === 0 && only === undefined
           ? {}
@@ -272,24 +290,28 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
               },
             }),
       },
-    );
+    });
+    batchCount += batches.length;
     const plan = planOf(options, pass);
     const label =
       only === undefined ? `${pass.workers} worker(s)` : `shard ${only} of ${pass.workers}`;
     steps.push({
-      name: `${pass.type === undefined ? label : `${pass.type} · ${label}`} · ${files.length} files`,
+      name: `${pass.type === undefined ? label : `${pass.type} · ${label}`} · ${files.length} files${
+        batches.length > 1 ? msg('cli.test.batches', { batches: batches.length }) : ''
+      }`,
       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: pass.workers,
       findings: result.ok ? [] : [failureOf(result.code, files.length, plan)],
-      output: execOutput(result),
+      output: result.output,
     });
     spent.push({
       ...(pass.type === undefined ? {} : { type: pass.type }),
       files: files.length,
       workers: pass.workers,
+      ...(batches.length > 1 ? { batches: batches.length } : {}),
       ok: result.ok,
       exitCode: result.code,
       reproduce: reproduceFor(plan),
@@ -321,6 +343,8 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
     // Only when the split made more than one, so a single-pass run's JSON is byte-identical to
     // what it has always been — and a mixed one can never be read as if it were a single run.
     ...(spent.length > 1 ? { passes: spent } : {}),
+    // Only when some pass was split, for the same reason: an unbatched run's JSON is unchanged.
+    ...(batchCount > spent.length ? { batches: batchCount } : {}),
     ok,
     exitCode,
     reproduce: reproduceFor(plan),

package/src/test-workers.ts

@@ -35,11 +35,11 @@ export function availableCpus(): number {
  *
  * The bound is memory, not cores. A worker is a whole Bun process with the framework's module
  * graph loaded and — in the typed suites — its own cloned Postgres or an in-process PGlite. Until
- * 22.3 that was a FIXED ceiling of 8, which held a 12-core box to 8 workers with 30 GB free: the
- * notificado.co `unit` step (381 files) sat at 51s on 8 workers against a 90s gate budget. The
- * ceiling is now what the machine can actually hold — `os.freemem()` (MemAvailable on Linux, so
- * reclaimable page cache counts as free) divided by `WORKER_BYTES` — which still binds on a small
- * CI runner and on a loaded laptop, the two places an unbounded count would swap.
+ * 22.3 that was a FIXED ceiling of 8, which held a 12-core box to 8 workers with 30 GB free. The
+ * ceiling is now what the machine can actually hold — `MEMORY_SHARE` of `os.freemem()`
+ * (MemAvailable on Linux, so reclaimable page cache counts as free) divided by `WORKER_BYTES` —
+ * which binds on a small CI runner, on a loaded laptop and on a box shared with other sessions,
+ * the places an unbounded count swaps or, with no swap, is OOM-killed.
  *
  * The floor of 2 keeps a 1-core box sharding rather than silently reverting to serial.
  */
@@ -49,22 +49,44 @@ export const WORKER_OVERSUBSCRIBE = 1.5;
 export const WORKER_FLOOR = 2;
 
 /**
- * What one test worker is budgeted at, for the memory bound above. MEASURED — peak RSS of the whole
- * `x test unit` process tree on the notificado.co corpus (381 files, PGlite per worker), 12-core
- * box, `As of 2026-09-25`:
+ * What one test worker is budgeted at, for the memory bound above. MEASURED — whole-tree RSS of
+ * `x test unit` on the notificado.co corpus (768 files, PGlite per file), 12-core box, Bun 1.4.0,
+ * `As of 2026-09-27`, batched by `BATCH_FILES_PER_WORKER`:
  *
- *   | workers | peak tree RSS |
- *   |---------|---------------|
- *   | 8       | 20.7 GB       |
- *   | 12      | 22.5 GB       |
- *   | 16      | 24.3 GB       |
+ *   | workers | batches | peak tree RSS | largest single worker |
+ *   |---------|---------|---------------|-----------------------|
+ *   | 12      | 3       | 10.8-11.4 GB  | 1.38-1.41 GB          |
+ *   | 14      | 3       | 12.2 GB       | 1.39 GB               |
+ *   | 18      | 2       | 15.9 GB       | 1.47 GB               |
  *
- * The MARGINAL worker costs ~0.45 GB (the slope); the ~17 GB intercept is the corpus itself —
- * every file's module graph and database, retained per worker — and does not shrink with fewer
- * workers, so it is not this bound's to budget. The constant is the slope doubled and rounded to a
- * power of two, because free memory is read once, before a single worker has started.
+ * Unbatched, the same box at 22.6.1's default of 18 workers peaked at 17.1-18.2 GB, and the same
+ * run's wall clock was 132-167s against 152-163s for this default (14 workers, 3 batches) — within
+ * the noise of a box at load 30-40.
+ *
+ * The constant is the LARGEST single worker rounded up, not the average (~0.88 GB), so the bound
+ * holds even on the run where every worker peaks at the same moment. The 2026-09-25 figure it
+ * replaces (1 GiB, from a "~0.45 GB slope over a ~17 GB intercept") budgeted the slope and waved
+ * the intercept away as "the corpus"; that intercept was per-worker growth over an unbatched run,
+ * and an 18-worker default on 35 GB free took a 45 GB box with no swap down (2026-09-27).
+ */
+export const WORKER_BYTES = 1.5 * 1024 * 1024 * 1024;
+
+/**
+ * The share of available memory a default-width run may plan to use. Never all of it, because free
+ * memory is read ONCE, before a single worker has started, and a dev box is never only running the
+ * tests: a type-checker, an editor's language server, another agent's gate all grow after that
+ * read. A run that plans on every free byte is one neighbour away from the OOM killer. 0.6 and not
+ * less because the plan is made at the LARGEST worker's peak: measured, the whole tree peaks at
+ * ~0.9 GB a worker, so the real peak lands near 35-40% of what was available at the start.
+ */
+export const MEMORY_SHARE = 0.6;
+
+/**
+ * Files each worker is handed before its `bun test` process is thrown away and a fresh one takes
+ * the next batch (`test-batches.ts`, which carries the measurement). What makes the peak a function
+ * of the width rather than of the corpus.
  */
-export const WORKER_BYTES = 1024 * 1024 * 1024;
+export const BATCH_FILES_PER_WORKER = 24;
 
 /**
  * The most `--workers` accepts, on either command. Not a default and not a memory rule — a sanity
@@ -77,7 +99,8 @@ export const WORKER_CEILING = 64;
 export const availableMemory = (): number => freemem();
 
 /**
- * `ceil(cpus x 1.5)`, held to what free memory can carry and never below the floor. The file-count
+ * `ceil(cpus x 1.5)`, held to `MEMORY_SHARE` of free memory at `WORKER_BYTES` a worker, and never
+ * below the floor. The file-count
  * clamp is `test-passes.ts`'s (every pass is clamped to its own file list), because only the
  * caller knows the selection.
  */
@@ -86,7 +109,7 @@ export const defaultWorkers = (
   freeBytes: number = availableMemory(),
 ): number => {
   const byCpu = Math.ceil(available * WORKER_OVERSUBSCRIBE);
-  const byMemory = Math.floor(freeBytes / WORKER_BYTES);
+  const byMemory = Math.floor((freeBytes * MEMORY_SHARE) / WORKER_BYTES);
   return Math.max(WORKER_FLOOR, Math.min(byCpu, byMemory, WORKER_CEILING));
 };
 

package/src/verify-test-run.ts

@@ -3,8 +3,8 @@
 // is never a race, and a race is never a selection bug.
 
 import type { Runner } from './exec';
-import { execOutput } from './exec';
 import type { Finding } from './output';
+import { runBatches, testBatches } from './test-batches';
 import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
 import type { TestFile } from './test-select';
@@ -26,7 +26,8 @@ export interface ParallelRunOptions {
 }
 
 /**
- * ONE `bun test --parallel=N`, not N processes this file spawns and packs itself.
+ * `bun test --parallel=N` per batch (`test-batches.ts`), 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
@@ -42,9 +43,17 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
   const files = options.files.map((file) => file.path);
   const workers = Math.max(1, Math.min(Math.trunc(options.workers), files.length || 1));
   const envOverrides = testEnvOverrides(options.root, options.env ?? Bun.env);
-  const result = await options.runner(testArgs({ files, workers }), {
-    cwd: options.root,
-    ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
+  // 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.
+  const batches = testBatches(files, workers);
+  const result = await runBatches({
+    runner: options.runner,
+    batches,
+    argsFor: (batch) => testArgs({ files: batch, workers: Math.min(workers, batch.length) }),
+    options: {
+      cwd: options.root,
+      ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
+    },
   });
   // `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
@@ -56,9 +65,11 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
     ok: findings.length === 0,
     findings,
     workers,
-    tests: countsOf([result]),
+    // Per batch: each process printed its own summary, and one parse of the joined text would
+    // read only the last one.
+    tests: countsOf(result.results),
     // 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) }),
+    ...(result.ok ? {} : { output: result.output }),
   };
 }