@ultimat3/cli 19.2.0 → 19.3.1

package/src/sw-artifacts.ts

@@ -50,15 +50,41 @@ export interface ServiceWorkerInput {
    * the offline fallback with no CSS is a page the visitor cannot read.
    */
   readonly styles: StyleBundle;
+  /**
+   * What the build RENDERED, keyed by the route path it was rendered for. Optional because only a
+   * static export has documents to hash: `x dev` and the container emit the worker at boot, where
+   * no page has been built yet, and `buildPrecacheManifest` falls back to the build id for a route
+   * this map does not name.
+   */
+  readonly documents?: ReadonlyMap<string, RenderedDocument>;
+}
+
+/**
+ * One rendered document, as the precache manifest needs it.
+ *
+ * `revision` is `contentHash(html)` — `@ultimat3/render`'s own, the function that already stamps
+ * an ETag — and never the build id. `precache.ts`' header states the rule and nothing kept it:
+ * `pwaRoutes` projected four of `PwaRoute`'s eight fields, so every route entry read
+ * `{"url":"/","revision":"build-aaa","bytes":0}` and two deploys of a byte-identical site
+ * re-fetched every precached document. The zero was the second half — `DEFAULT_PRECACHE_WARN_BYTES`
+ * is a 5 MB budget over a total that could not count one byte of HTML.
+ */
+export interface RenderedDocument {
+  readonly revision: string;
+  readonly bytes: number;
 }
 
 /**
  * The route table, as the service worker sees it. `api/` is dropped: an API response is a JSON
  * document whose freshness is the app's business, and precaching one serves a stale answer to a
- * client that had a network. Only the four fields `PwaRoute` reads cross — a descriptor carries
- * budgets and policy flags that a browser has no use for.
+ * client that had a network. Only the fields a browser can act on cross — a descriptor carries
+ * budgets and policy flags it has no use for — plus, for a route this build rendered, the content
+ * hash and the byte count of the document it produced.
  */
-const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
+const pwaRoutes = (
+  routes: readonly RouteDescriptor[],
+  documents: ReadonlyMap<string, RenderedDocument>,
+): readonly PwaRoute[] =>
   // `flatMap` rather than `filter().map()`: the filter's predicate does not narrow `surface` for
   // the map that follows it, and `PwaRoute` declares the two navigable surfaces only. A cast would
   // hide the day a fifth surface arrives.
@@ -66,6 +92,8 @@ const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
     // `shared/` is dropped with `api/`, and for a stronger reason: it is not a URL at all — the
     // surface exists so two routes can import one module, and a browser can never navigate to it.
     if (route.surface !== 'site' && route.surface !== 'app') return [];
+    // A `Map`, so a route path that happens to spell a prototype member cannot answer with one.
+    const document = documents.get(route.path);
     return [
       {
         path: route.path,
@@ -73,6 +101,10 @@ const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
         mode: route.mode,
         offline: route.offline,
         dynamic: route.dynamic,
+        // Absent rather than invented for a route no build rendered — an `ssr` page, or one this
+        // pass could not produce. `buildPrecacheManifest` then falls back to the build id, which
+        // is the honest answer when there are no bytes to hash.
+        ...(document === undefined ? {} : { revision: document.revision, bytes: document.bytes }),
       },
     ];
   });
@@ -128,14 +160,34 @@ export function serviceWorkerArtifacts(
   input: ServiceWorkerInput,
 ): ServiceWorkerArtifacts | undefined {
   const pwa = input.pwa;
-  if (pwa.offline.fallback === null) return undefined;
+  const head = serviceWorkerHead(pwa);
+  const fallback = pwa.offline.fallback;
+  // One predicate DECIDES — `serviceWorkerHead`, so a document can never name a script this
+  // function then declines to emit — and the `null` check is what NARROWS `fallback` below:
+  // TypeScript cannot learn a `string` from the other's answer, and a cast would hide the day the
+  // two stop agreeing.
+  if (head === undefined || fallback === null) return undefined;
+  const documents = input.documents ?? new Map<string, RenderedDocument>();
+  // The offline document is the one entry `buildPrecacheManifest` adds ITSELF, as
+  // `reason: 'fallback'`, ahead of every route — and `add()` keeps the first entry per url, so its
+  // revision is the one that decides. Without this pair it was the build id whatever the build
+  // knew, which re-downloaded the single page an offline navigation depends on on every deploy.
+  // Absent when this pass did not render the fallback (no route serves it — `x doctor` reports
+  // that as `X_PWA_NO_OFFLINE_FALLBACK`), and then `@ultimat3/pwa` falls back to the build id.
+  const fallbackDocument = documents.get(fallback);
   const output = generateServiceWorker(
-    pwaRoutes(input.routes),
+    pwaRoutes(input.routes, documents),
     {
       scope: SW_SCOPE,
       swPath: SERVICE_WORKER_PATH,
+      ...(fallbackDocument === undefined
+        ? {}
+        : {
+            offlineFallbackRevision: fallbackDocument.revision,
+            offlineFallbackBytes: fallbackDocument.bytes,
+          }),
       offline: {
-        fallback: pwa.offline.fallback,
+        fallback,
         ...(pwa.offline.image === null ? {} : { image: pwa.offline.image }),
         ...(pwa.offline.font === null ? {} : { font: pwa.offline.font }),
         neverCache: pwa.offline.neverCache,
@@ -148,7 +200,7 @@ export function serviceWorkerArtifacts(
   return {
     source: output.source,
     register: registerSource(),
-    head: `<script src="${SW_REGISTER_PATH}" defer></script>`,
+    head,
     precache: output.precache,
     // `output.warnings` IS `output.precache.warnings` — the generator returns the manifest's list
     // verbatim — so it is read once, not twice. The push line is this module's own, and it is the
@@ -160,6 +212,18 @@ export function serviceWorkerArtifacts(
   };
 }
 
+/**
+ * The one `<script src>` a document needs, or `undefined` for an app that gets no worker.
+ *
+ * Separate from `serviceWorkerArtifacts` because the two are wanted at different moments: a static
+ * export has to put this tag in every document it renders, and the WORKER cannot be emitted until
+ * those documents exist — its precache manifest is built from their content hashes. One predicate
+ * for both (`offline.fallback === null` is `generateServiceWorker`'s refusal, spent early), so a
+ * document can never name a script the export does not carry.
+ */
+export const serviceWorkerHead = (pwa: PwaArtifacts): string | undefined =>
+  pwa.offline.fallback === null ? undefined : `<script src="${SW_REGISTER_PATH}" defer></script>`;
+
 /**
  * `pwa.push: true` with nothing to sign a subscription with. There is no `pwa.vapid` config key
  * yet, so today this fires for EVERY app that sets the flag — deliberately: a switch that silently

package/src/templates/admin-page.ts

@@ -9,6 +9,7 @@ import { sortedImports } from './imports';
 import { catalogPath, resolveLocales } from './locales';
 import type { GeneratedFile } from './naming';
 import { camel, kebab, pascal } from './naming';
+import { LINE_WIDTH } from './wrap';
 
 /** Where an admin lives when the caller does not say. `x new` scaffolds this layout. */
 export const DEFAULT_ADMIN_PAGE_DIR = 'apps/admin/src/pages';
@@ -58,9 +59,45 @@ const catalogImport = (module: string | undefined): string =>
 const pageImports = (module: string | undefined): string =>
   sortedImports([
     `import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';`,
+    `import { definePermissions } from '@ultimat3/policy';`,
     catalogImport(module),
   ]);
 
+/**
+ * The page DECLARES the permission it requires, in both registries that decide about it.
+ *
+ * `x g admin:page ops` emitted `permissions: ['ops:read']` and nothing anywhere declared
+ * `ops:read`, so `assertPermission` threw X_PERMISSION_UNKNOWN on the first request that reached
+ * the page: a screen the generator built and no actor can open. Nothing catches it either — the
+ * gate's `policy` step reads `roleDefinitions()` and `routeEntries()`, and an admin page is
+ * neither a role nor a route, so `x verify` is green over it.
+ *
+ * Here rather than in a `policy.ts` beside it, because registration is a side effect of IMPORT and
+ * `pages:` already imports this module: a declaration in a file the admin does not import is a
+ * declaration that never runs. `declare module` is the type half — `can()`'s key type reads the
+ * registry, not the `definePermissions` call — and merging an identical member is what lets an app
+ * that already declares this permission keep its own declaration.
+ */
+const declarePermissions = (name: string, permission: string): string => {
+  const line = `export const ${camel(name)}PagePermissions = definePermissions(['${permission}']);`;
+  // Emitted PRE-formatted, because a template cannot run one: past 100 columns biome rewrites this
+  // call across four lines, and `x new zebra`-class names reach it (`emitted-contract.test.ts`
+  // varies both the length and the first letter for exactly this reason).
+  return line.length <= LINE_WIDTH
+    ? line
+    : `export const ${camel(name)}PagePermissions = definePermissions([\n  '${permission}',\n]);`;
+};
+
+const permissionDeclaration = (name: string, permission: string): string => `
+declare module '@ultimat3/policy' {
+  interface PermissionRegistry {
+    '${permission}': true;
+  }
+}
+
+${declarePermissions(name, permission)}
+`;
+
 /** `useT()` is per render, so the component binds it in its own body. */
 const translatorBinding = (module: string | undefined): string =>
   module === undefined ? '' : '\n  const t = useT();\n';
@@ -81,9 +118,12 @@ const pageSource = (
 // so the specifier is relative to wherever \`defineAdmin\` lives:
 //   import { ${declaration}Page } from './${name}';
 //   defineAdmin({ …, pages: […, ${declaration}Page] })
+//
+// The permission below is declared here AND has to be decided: an authz map built from a fixed
+// list must name '${permission}' too, or a declared permission is still denied for everyone.
 
 ${pageImports(module)}
-
+${permissionDeclaration(name, permission)}
 export function ${Name}Page(props: AdminPageProps) {${translatorBinding(module)}
   return (
     <section>
@@ -108,6 +148,7 @@ const pageTest = (name: string, permission: string): string => {
   const declaration = camel(name);
   return `// The ${name} admin page is guarded and owns no route of its own — the two facts that separate an
 // admin screen from a page, and the two an edit here is most likely to break.
+import { knownPermissions } from '@ultimat3/policy';
 import { expect, unitTest } from '@ultimat3/testing';
 import { ${declaration}Page } from './${name}';
 
@@ -119,6 +160,13 @@ unitTest('the ${name} admin page is rooted and guarded', () => {
   expect(${declaration}Page.permissions).toContain('${permission}');
 });
 
+// A \`permissions:\` entry no \`definePermissions()\` declares is X_PERMISSION_UNKNOWN on the first
+// request that reaches the page — a screen this generator built and nobody can open. Importing the
+// page above is what registers it, which is why the declaration lives in that file and not beside it.
+unitTest('the ${name} admin page declares its permission', () => {
+  expect(knownPermissions()).toContain('${permission}');
+});
+
 unitTest('the ${name} admin page declares no route of its own', () => {
   // \`pages:\` is the only way in. A \`config\` export here would be a route the frame never guards.
   expect('config' in ${declaration}Page).toBe(false);

package/src/templates/scaffold-container.ts

@@ -6,6 +6,7 @@
 // run-to-completion migrate step are conventions every container platform shares — a Heroku
 // buildpack, a Render blueprint or a fly.toml would be the primitive that never ships.
 
+import { SECRETS_KEY_FILE } from '@ultimat3/core';
 import type { GeneratedFile, NameSet } from './naming';
 import { helmFiles } from './scaffold-helm';
 
@@ -81,6 +82,12 @@ ENTRYPOINT ["bun", "apps/web/server.ts"]
  * tells the operator to create, in its own `env_file:` — nor `.env.development`, and both landed in
  * an image layer that `cache-to=mode=max` then pushes to a shared cache. Same four lines the
  * framework's own `docker/Dockerfile.dockerignore` carries, and for the same reason.
+ *
+ * The key file is interpolated from `SECRETS_KEY_FILE` rather than written out, because the
+ * constant is what `findMasterKey` reads: a rename would otherwise leave every app this generator
+ * has ever produced ignoring a filename nothing writes, which reads as a rule still in force.
+ * `scripts/image-contract.ts` holds every ignore file IN THIS TREE to the same line; a generated
+ * app's copy is this template's, and `scaffold-container.test.ts` is where it is judged.
  */
 const dockerignore = (): string => `**/.env
 **/.env.*
@@ -88,6 +95,11 @@ const dockerignore = (): string => `**/.env
 # Same shape, different file: an .npmrc carries a registry auth token, so any that exists in a
 # build context is somebody's local credential and has no business in a layer.
 **/.npmrc
+# Same shape, and this one is the key itself: ${SECRETS_KEY_FILE} decrypts the committed
+# secrets.enc.json beside it, and findMasterKey falls back to the file whenever
+# ULTIMATE_SECRETS_KEY is unset — so a baked copy boots the image on it and the platform's key is
+# never exercised.
+**/${SECRETS_KEY_FILE}
 
 node_modules
 **/node_modules

package/src/templates/scaffold-repo.ts

@@ -333,13 +333,18 @@ declare module '*.scss' {
 }
 `;
 
+// Build output is ROOT-ANCHORED, and that is not cosmetic: an unanchored `dist/` or `coverage/`
+// matches a directory of that name at ANY depth, so `apps/web/site/dist/page.tsx` — an app's own
+// `/dist` route, the directory IS the URL — was a file git refused to commit and `x dev` refused to
+// reload. `packages/*/dist/` keeps a workspace's build output ignored without reaching a surface.
 const gitignore = (): string => `node_modules/
 .x/
-dist/
+/dist/
+packages/*/dist/
 *.tsbuildinfo
 .env
 .env.*.local
-coverage/
+/coverage/
 playwright-report/
 test-results/
 `;

package/src/test-passes.ts

@@ -0,0 +1,79 @@
+// Which of a selection's files may share a worker pool, and which may not. `--parallel=N` is the
+// width of the WHOLE run, so a selection holding a `live` or an `e2e` file is more than one run —
+// this file decides how many, and `test-shards.ts` spends them.
+
+import type { TestFile } from './test-select';
+import type { TestType } from './verify-tests';
+import { ownerOf, SERIAL_TYPES } from './verify-tests';
+
+/** One `bun test` invocation: which files, how wide, and the type its reproduce line names. */
+export interface TestPass {
+  readonly files: readonly TestFile[];
+  readonly workers: number;
+  /**
+   * The type this pass is exactly the selection of, when it is one — so a failure's `fix:` names
+   * `x test live --workers 1` and reruns THESE files, not the whole corpus at this width.
+   */
+  readonly type?: TestType;
+}
+
+export interface PassInput {
+  readonly files: readonly TestFile[];
+  /** What the caller asked for, already bounded by `--workers`' own reader. */
+  readonly workers: number;
+  /** The positional, when there was one. A pass over one type keeps it; the split never adds one. */
+  readonly type?: TestType;
+  /** Set for a `--worker I` rerun, which is one process by construction. */
+  readonly shard?: number;
+}
+
+const widthFor = (files: readonly TestFile[], workers: number): number =>
+  Math.max(1, Math.min(Math.trunc(workers), files.length || 1));
+
+/**
+ * The passes one invocation becomes. One, for every selection that holds no serial file — which
+ * is every `x test unit`, every `--filter` over a feature's contract tests, and the whole corpus
+ * of an app that has neither.
+ *
+ * `live` and `e2e` are the exception, and `verify-tests.ts` owns both the list and the reasons: a
+ * logical replication slot is named at the Postgres CLUSTER level so a per-worker database does
+ * not isolate it, and `e2e` shares one `dist/` and one browser profile. `x verify` has routed them
+ * through `runSerial` since 2026-08 while `x test` clamped on the POSITIONAL alone — so a bare
+ * `x test --workers 8` ran the very files the gate runs one at a time, eight at a time, and only
+ * a real `TEST_DATABASE_URL` makes that visible.
+ *
+ * Each serial type is its own pass rather than one pass over both, because the pass's `type` is
+ * what its failure reproduces with: `x test live --workers 1` selects exactly the files that ran.
+ *
+ * A `--worker I` rerun is left whole: it is a single `bun test --isolate --shard=i/N` process, so
+ * nothing inside it runs beside anything else, and splitting it would make shard i of the rerun a
+ * different set of files from shard i of the run it reproduces.
+ */
+export function testPasses(input: PassInput): readonly TestPass[] {
+  const serialTypes = new Set<TestType>(SERIAL_TYPES);
+  if (input.shard !== undefined) {
+    return [
+      {
+        files: input.files,
+        workers: widthFor(input.files, input.workers),
+        ...(input.type === undefined ? {} : { type: input.type }),
+      },
+    ];
+  }
+  const shared = input.files.filter((file) => !serialTypes.has(ownerOf(file.path)));
+  const passes: TestPass[] = [];
+  // Cheapest first, and the widest first: the pool run is most of the corpus and most of the
+  // signal, and a serial suite that needs a database is the one a laptop is least likely to have.
+  if (shared.length > 0) {
+    passes.push({
+      files: shared,
+      workers: widthFor(shared, input.workers),
+      ...(input.type === undefined ? {} : { type: input.type }),
+    });
+  }
+  for (const type of SERIAL_TYPES) {
+    const files = input.files.filter((file) => ownerOf(file.path) === type);
+    if (files.length > 0) passes.push({ files, workers: 1, type });
+  }
+  return passes;
+}

package/src/test-shards.ts

@@ -40,6 +40,7 @@ import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue, StepResult } from './output';
 import { quoteArg } from './shell-quote';
+import { testPasses } from './test-passes';
 import type { TestFile } from './test-select';
 import type { TestType } from './verify-tests';
 
@@ -65,15 +66,26 @@ export function testArgs(input: {
   readonly workers: number;
   /** 0-based, matching `--worker`. Absent runs the whole selection across `workers` processes. */
   readonly shard?: number;
+  /**
+   * Everything after a bare `--`, handed to `bun test` verbatim and BEFORE the file list, which is
+   * where bun reads its flags. `ParsedArgs.passthrough` had no reader anywhere until 2026-09, so
+   * `x test unit -- --coverage --bail` parsed both flags, carried them through the command and
+   * dropped them on the floor — a run that reported exactly what a coverage run reports, with no
+   * coverage measured. `CommandSpec.passthrough` is what keeps the other commands from doing the
+   * same in silence: they refuse the `--` instead.
+   */
+  readonly passthrough?: readonly string[];
 }): readonly string[] {
   const files = [...input.files].sort();
+  const extra = input.passthrough ?? [];
   return input.shard === undefined
-    ? ['bun', 'test', `--parallel=${String(input.workers)}`, ...files]
+    ? ['bun', 'test', `--parallel=${String(input.workers)}`, ...extra, ...files]
     : [
         'bun',
         'test',
         '--isolate',
         `--shard=${String(input.shard + 1)}/${String(input.workers)}`,
+        ...extra,
         ...files,
       ];
 }
@@ -102,6 +114,8 @@ export interface ReproduceOptions {
   readonly affected?: AffectedSelection;
   /** 0-based, when reproducing ONE shard. Absent reproduces the whole selection. */
   readonly shard?: number;
+  /** What the caller put after `--`. It reaches `bun test`, so a rerun without it runs differently. */
+  readonly passthrough?: readonly string[];
 }
 
 /**
@@ -124,6 +138,11 @@ export function reproduceFor(options: ReproduceOptions): string {
     '--workers',
     String(options.workers),
     ...(options.shard === undefined ? [] : ['--worker', String(options.shard)]),
+    // Last, and after a `--` of its own, because that is where the caller typed it and where the
+    // parser will find it again. Quoted for `shell-quote.ts`'s reason: a reproduce line is pasted.
+    ...(options.passthrough === undefined || options.passthrough.length === 0
+      ? []
+      : ['--', ...options.passthrough.map(quoteArg)]),
   ].join(' ');
 }
 
@@ -144,16 +163,28 @@ export interface RunShardsOptions {
   readonly sample?: { readonly kept: number; readonly total: number };
   /** Passed straight to `reproduceFor`: see `ReproduceOptions.affected`. */
   readonly affected?: AffectedSelection;
+  /** Everything after the caller's `--`, forwarded to every pass and printed in the reproduce. */
+  readonly passthrough?: readonly string[];
 }
 
-/** The reproduction's inputs, resolved once: `workers` is the run's real width, not the ask. */
-const planOf = (options: RunShardsOptions, workers: number): ReproduceOptions => ({
-  workers,
+/**
+ * The reproduction's inputs for ONE pass: `workers` is that pass's real width, not the ask, and
+ * `type` is the pass's own when the split gave it one — `x test live --workers 1` reruns exactly
+ * the files that failed, where the whole invocation's flags would rerun the corpus around them.
+ */
+const planOf = (
+  options: RunShardsOptions,
+  pass: { readonly workers: number; readonly type?: TestType },
+): ReproduceOptions => ({
+  workers: pass.workers,
   ...(options.filter === undefined ? {} : { filter: options.filter }),
-  ...(options.type === undefined ? {} : { type: options.type }),
+  ...(pass.type === undefined ? {} : { type: pass.type }),
   ...(options.sample === undefined ? {} : { sample: options.sample.kept }),
   ...(options.affected === undefined ? {} : { affected: options.affected }),
   ...(options.only === undefined ? {} : { shard: options.only }),
+  ...(options.passthrough === undefined || options.passthrough.length === 0
+    ? {}
+    : { passthrough: options.passthrough }),
 });
 
 /**
@@ -173,68 +204,111 @@ export const failureOf = (code: number, files: number, plan: ReproduceOptions):
 });
 
 /**
- * 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.
+ * 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.
+ *
+ * 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
+ * stops at the first red step hides the rest of the answer.
  *
  * `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 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 passes = testPasses({
+    files: options.files,
+    workers: options.workers,
+    ...(options.type === undefined ? {} : { type: options.type }),
+    ...(only === undefined ? {} : { shard: only }),
+  });
   const started = performance.now();
-  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, 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`,
+  const steps: StepResult[] = [];
+  const spent: JsonValue[] = [];
+  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 }),
+      }),
+      {
+        cwd: options.root,
+        ...(only === undefined ? {} : { env: { ULTIMATE_TEST_WORKER: String(only) } }),
+      },
+    );
+    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`,
       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,
+      workers: pass.workers,
       findings: result.ok ? [] : [failureOf(result.code, files.length, plan)],
       output: execOutput(result),
-    },
-  ];
+    });
+    spent.push({
+      ...(pass.type === undefined ? {} : { type: pass.type }),
+      files: files.length,
+      workers: pass.workers,
+      ok: result.ok,
+      exitCode: result.code,
+      reproduce: reproduceFor(plan),
+    });
+    ok = ok && result.ok;
+    if (exitCode === 0) exitCode = result.code;
+  }
+  const durationMs = Math.round(performance.now() - started);
+  const fileCount = options.files.length;
+  // The width the RUN reached, which is the widest pass: a mixed selection whose serial half ran
+  // one at a time did not become a one-worker run, and reporting it as one would misname the
+  // reproduce a reader is handed.
+  const workers = Math.max(1, ...passes.map((pass) => pass.workers));
+  const plan = planOf(options, {
+    workers,
+    ...(options.type === undefined ? {} : { type: options.type }),
+  });
+  const type = options.type;
+  const typeParam = type === undefined ? {} : { type };
+  const sample = options.sample;
   const data: JsonValue = {
     ...typeParam,
     workers,
-    files: files.length,
+    files: fileCount,
     durationMs,
     ...(options.filter === undefined ? {} : { filter: options.filter }),
     ...(sample === undefined ? {} : { sample: { kept: sample.kept, total: sample.total } }),
     ...(only === undefined ? {} : { shard: only }),
-    ok: result.ok,
-    exitCode: result.code,
+    // 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 } : {}),
+    ok,
+    exitCode,
     reproduce: reproduceFor(plan),
   };
   return {
-    ok: result.ok,
+    ok,
     command: 'test',
-    summary: result.ok
+    summary: ok
       ? msg(type === undefined ? 'cli.test.pass' : 'cli.test.type.pass', {
           ...typeParam,
-          files: files.length,
+          files: fileCount,
           workers,
           ms: durationMs,
         })
       : msg(type === undefined ? 'cli.test.fail' : 'cli.test.type.fail', {
           ...typeParam,
-          failed: 1,
+          failed: steps.filter((step) => !step.ok).length,
           workers,
         }),
     steps,
@@ -242,6 +316,6 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
       ? {}
       : { lines: [msg('cli.test.sampled', { ...sample, type: type ?? 'all' })] }),
     data,
-    exitCode: result.ok ? 0 : 1,
+    exitCode: ok ? 0 : 1,
   };
 }

package/src/verify-checks.ts

@@ -80,7 +80,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'boundaries',
     summary: "surface, layer and package-tier imports, and the app's own guards",
-    // An app's `guards/` rides here rather than becoming an eighteenth step, for the reason the
+    // An app's `guards/` rides here rather than becoming a step of its own, for the reason the
     // seam already states: a host adds findings to a step, it can never add, remove, reorder or
     // skip one — so "green" keeps meaning exactly what it meant. This is the step whose host slot
     // already carries "rules this repo makes about itself that the framework cannot know" (the
@@ -106,7 +106,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     name: 'package-shape',
     summary: 'every package ships the same contract files',
     applies: (ctx) => hasWorkspacePackages(ctx.root),
-    // The dependency rule rides here rather than becoming a twentieth step because it is this
+    // The dependency rule rides here rather than becoming a step of its own because it is this
     // step's own question — what does a workspace owe the repo it lives in? — asked of the
     // manifest's `dependencies` instead of its `files`. It is deliberately NOT inside
     // `checkPackageShape`: `scripts/release.ts --check` calls that one to ask whether the tree is
@@ -155,7 +155,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     // Source, not database: the gate runs in CI with nothing listening, and the database half is
     // the post-migrate verification `runMigrations` performs where a connection is already open.
     //
-    // The destructive rail rides here rather than becoming an eighteenth step because it asks this
+    // The destructive rail rides here rather than becoming a step of its own because it asks this
     // step's own question — do the committed migrations still describe what the app is doing to its
     // schema? — off the same directory, in the same pass, with no database either.
     applies: async (ctx) => existsSync(join(ctx.root, APP_CONFIG_FILE)),
@@ -166,7 +166,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
         // The third rail, and the one the other two cannot see: a hand-written statement is
         // recorded by no snapshot and hashed by no source, so both halves above are green over SQL
         // a squash silently drops. Same directory, same reader, no database — this step's own
-        // question, which is why it is not an eighteenth step.
+        // question, which is why it is not a step of its own.
         ...(await checkUngeneratableMigrations(ctx.root)),
       ]),
   },
@@ -191,7 +191,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     name: 'budgets',
     summary:
       'per-route JS bytes and LCP, the global style layer every document carries, and the routes that boot nothing to receive their live rows',
-    // The global-style assertion rides here rather than becoming an eighteenth step, because this
+    // The global-style assertion rides here rather than becoming a step of its own, because this
     // step already asks the one question it asks: what does the document this build emits actually
     // contain? It is also the same app load — `appManifest` fills render's stylesheet registry on
     // its way through — so a separate step would pay for a second one to answer half a question.
@@ -295,7 +295,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     // once, and says so by finding nothing — but `AGENTS.md` is required of every repo the gate
     // runs in, so the step always has a question to answer and must never report as skipped.
     //
-    // `.env.example` joins this step rather than becoming an eighteenth: the question is the same
+    // `.env.example` joins this step rather than becoming one of its own: the question is the same
     // one — "does a committed, generated file still describe the code?" — and the step list is the
     // definition of shippable, so it grows only when a genuinely new question needs asking.
     //