@ultimat3/cli 29.4.0 → 30.1.0

package/src/cmd-repro.ts

@@ -0,0 +1,174 @@
+// `x repro <id>` — a production failure becomes a failing test. A dead job (its row, its steps) or
+// a captured 5xx (`x_failures`, when `failureCapture` is on) is read, `--write` puts the replay in
+// `repro/`, and `--verify` runs it: `{ reproduced, code, fingerprint }`. `--list` shows what is held.
+// CLI wiring only: the reads are `repro-bundle.ts`, the sources `repro-job.ts`/`repro-request.ts`.
+
+import { postgresErrorGroupsStore } from '@ultimat3/admin/error-groups';
+import { postgresFailureStore } from '@ultimat3/db';
+import { loadAppConfig } from './app-config-load';
+import { loadApp } from './app-load';
+import { requireAppRoot } from './app-root';
+import { reproSpec } from './cmd-repro-spec';
+import type { CliCommand, CommandContext } from './command';
+import { MissingPositionalError } from './errors';
+import { withJobDriver } from './jobs-driver';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { findingFrom } from './output';
+import { flagBool, flagString } from './parse';
+import type { ReproSubject } from './repro-bundle';
+import { resolveSubject, subjectFromFile } from './repro-bundle';
+import { ReproNotReproducedError } from './repro-errors';
+import { jobFingerprint } from './repro-job';
+import { reproFile, reproSource, verifyRepro, writeRepro } from './repro-write';
+
+/** What every answer carries, whichever kind: the code, the group, the build and what was masked. */
+function factsOf(subject: ReproSubject): {
+  code: string | null;
+  fingerprint: string | null;
+  build: string | null;
+  masked: readonly string[];
+} {
+  if (subject.kind === 'job') {
+    const { failure } = subject;
+    return {
+      code: failure.code,
+      fingerprint: jobFingerprint(failure),
+      build: null,
+      masked: failure.masked,
+    };
+  }
+  const { bundle } = subject;
+  return {
+    code: bundle.code,
+    fingerprint: bundle.fingerprint,
+    build: bundle.build,
+    masked: bundle.masked,
+  };
+}
+
+const summaryOf = (subject: ReproSubject): string =>
+  subject.kind === 'job'
+    ? msg('cli.repro.job', {
+        name: subject.failure.name,
+        id: subject.failure.jobId,
+        code: subject.failure.code ?? 'no code',
+        step: subject.failure.step ?? '(the body)',
+      })
+    : msg('cli.repro.request', {
+        primitive: subject.bundle.primitive,
+        name: subject.bundle.name,
+        code: subject.bundle.code,
+        fingerprint: subject.bundle.fingerprint,
+      });
+
+async function answer(
+  root: string,
+  ctx: CommandContext,
+  id: string,
+  subject: ReproSubject,
+): Promise<CommandResult> {
+  const facts = factsOf(subject);
+  const payload = (subject.kind === 'job'
+    ? subject.failure
+    : subject.bundle) as unknown as JsonValue;
+  const base = {
+    kind: subject.kind,
+    id,
+    code: facts.code,
+    fingerprint: facts.fingerprint,
+    build: facts.build,
+    masked: [...facts.masked],
+    [subject.kind === 'job' ? 'failure' : 'bundle']: payload,
+  };
+  const verify = flagBool(ctx.args, 'verify');
+  if (!verify && !flagBool(ctx.args, 'write')) {
+    return { ok: true, command: 'repro', summary: summaryOf(subject), data: base };
+  }
+  const file = reproFile(subject);
+  const runningBuild = ctx.env['BUILD_ID'] ?? null;
+  await writeRepro(root, file, await reproSource(root, subject, id, runningBuild), ctx.runner);
+  const lines = [msg('cli.repro.written', { file })];
+  if (!verify) {
+    return {
+      ok: true,
+      command: 'repro',
+      summary: summaryOf(subject),
+      lines,
+      data: { ...base, file },
+    };
+  }
+  const verdict = await verifyRepro(root, file, facts.code, ctx.runner, ctx.env);
+  const data = { ...base, file, reproduced: verdict.reproduced, got: verdict.got };
+  if (verdict.reproduced) {
+    lines.push(msg('cli.repro.reproduced', { file, code: facts.code ?? '' }));
+    return { ok: true, command: 'repro', summary: summaryOf(subject), lines, data };
+  }
+  lines.push(msg('cli.repro.notReproduced', { file, got: verdict.got ?? 'a pass' }));
+  const refusal = new ReproNotReproducedError({
+    id,
+    expected: facts.code ?? 'its original failure',
+    got: verdict.got,
+    masked: facts.masked,
+    file,
+    build: facts.build,
+  });
+  return {
+    ok: false,
+    command: 'repro',
+    summary: summaryOf(subject),
+    lines,
+    findings: [findingFrom(refusal)],
+    data,
+  };
+}
+
+/** The held bundles, each with its group's count and last sighting from `x_error_groups`. */
+async function list(ctx: CommandContext): Promise<CommandResult> {
+  const code = flagString(ctx.args, 'code');
+  const bundles = await postgresFailureStore().list(code === undefined ? {} : { code });
+  const groups = postgresErrorGroupsStore();
+  const rows: JsonValue[] = [];
+  for (const bundle of bundles) {
+    const group = await groups.get(bundle.fingerprint).catch(() => undefined);
+    rows.push({
+      ...bundle,
+      count: group?.count ?? null,
+      lastSeen: group?.lastSeen ?? null,
+      repro: `x repro ${bundle.id} --write --verify`,
+    });
+  }
+  return {
+    ok: true,
+    command: 'repro',
+    summary: msg('cli.repro.listed', { count: rows.length }),
+    lines: bundles.map(
+      (bundle) => `  ${bundle.at}  ${bundle.code.padEnd(28)} ${bundle.name}  ${bundle.id}`,
+    ),
+    data: { bundles: rows },
+  };
+}
+
+export const reproCommand: CliCommand = {
+  spec: reproSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('repro', ctx.cwd).dir;
+    const from = flagString(ctx.args, 'from');
+    const id = ctx.args.positionals[0];
+    if (from === undefined && id === undefined && !flagBool(ctx.args, 'list')) {
+      throw new MissingPositionalError({
+        command: 'repro',
+        positional: 'id',
+        example: 'x repro --list --json',
+      });
+    }
+    // The app's declarations are what mask a job's input and what a written test replays against.
+    await loadApp(root);
+    if (from !== undefined) return answer(root, ctx, id ?? from, await subjectFromFile(from));
+    const captureOn = (await loadAppConfig(root))?.failureCapture.enabled === true;
+    return withJobDriver(root, ctx, async (driver) => {
+      if (id === undefined) return list(ctx);
+      return answer(root, ctx, id, await resolveSubject(driver, id, captureOn));
+    });
+  },
+};

package/src/cmd-stop-spec.ts

@@ -0,0 +1,21 @@
+// `x stop`'s declaration, apart from its body: the parser, `x help` and the `errors` step read it
+// without loading `cmd-stop.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const stopSpec: CommandSpec = {
+  name: 'stop',
+  summary:
+    "stop this checkout's x dev — the pid its .x/dev.lock names, and nothing else — and return once x dev can boot again",
+  usage: 'x stop [--timeout 30s] [--json]',
+  requiresApp: true,
+  flags: [
+    {
+      name: 'timeout',
+      type: 'string',
+      // No `default:` — the default is the drain's own deadline plus margin, read at run time.
+      summary:
+        'how long to wait for the drain: 30s, 2m, PT1M (default: the drain deadline plus the release floor plus 5s)',
+    },
+  ],
+};

package/src/cmd-stop.ts

@@ -0,0 +1,166 @@
+// `x stop` — ends this checkout's `x dev`, and returns only once the next `x dev` can boot. The
+// lock is the whole authority: the pid `.x/dev.lock` names is the only process signalled, never
+// one found by port or by name, so agents sharing a box cannot end each other's servers.
+
+import { drainDeadlineMs, renderThrowable, stringField, UltimateError } from '@ultimat3/core';
+import { parseDuration } from '@ultimat3/time';
+import { requireAppRoot } from './app-root';
+import { stopSpec } from './cmd-stop-spec';
+import type { CliCommand, CommandContext } from './command';
+import { clearLock, isProcessAlive, liveDevLock, lockPath, parseLock, reusedPid } from './dev-lock';
+import { BadFlagError } from './errors';
+import { MIN_RELEASE_MS } from './hold';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagString } from './parse';
+import { resolveServices } from './runtime-bindings';
+
+/** How often the wait asks whether the pid has left. */
+const POLL_MS = 50;
+
+/** The child's own hard exit (`devHardExitMs`) plus margin, so its self-kill lands inside the wait. */
+export const defaultStopTimeoutMs = (): number => drainDeadlineMs() + MIN_RELEASE_MS + 5_000;
+
+/** The pid belongs to another user: SIGTERM is refused with EPERM, so nothing was stopped. */
+export class DevStopDeniedError extends UltimateError {
+  constructor(input: { readonly pid: number }) {
+    super({
+      code: 'X_DEV_STOP_DENIED',
+      cause: `x stop may not signal pid ${String(input.pid)}, the x dev this checkout's lock names: another user owns it (EPERM)`,
+      fix: `ps -o user= -p ${String(input.pid)}   # then, as that user: x stop --json`,
+      meta: { pid: input.pid },
+    });
+  }
+}
+
+/** The pid outlived the wait. Its lock stays: the process still holds the directory. */
+export class DevStopTimeoutError extends UltimateError {
+  constructor(input: { readonly pid: number; readonly waitedMs: number }) {
+    super({
+      code: 'X_DEV_STOP_TIMEOUT',
+      cause: `x stop sent SIGTERM to pid ${String(input.pid)}, the x dev this checkout's lock names, and it was still running ${String(input.waitedMs)}ms later — a drain past its deadline, or a process that ignores SIGTERM`,
+      // A hard kill leaves the lock behind, and `preflight` clears a lock whose pid is dead.
+      fix: `kill -9 ${String(input.pid)}   # then: x dev --json`,
+      meta: { pid: input.pid, waitedMs: input.waitedMs },
+    });
+  }
+}
+
+export type StopResult =
+  /** `stale`: the lock names a live pid that is not the process that wrote it (a reused pid). */
+  | { readonly stopped: false; readonly stale?: true }
+  | {
+      readonly stopped: true;
+      readonly pid: number;
+      readonly port: number;
+      readonly waitedMs: number;
+      /** False on Windows, where `kill` is TerminateProcess and no drain runs. */
+      readonly drained: boolean;
+    };
+
+export interface StopInput {
+  readonly stateDir: string;
+  readonly timeoutMs: number;
+  /** Test seams: the defaults are this process's platform, `process.kill` and signal 0. */
+  readonly platform?: NodeJS.Platform;
+  readonly kill?: (pid: number) => void;
+  readonly alive?: (pid: number) => boolean;
+}
+
+/** SIGTERM, with the one refusal a reader can act on coded; a pid already gone is no refusal. */
+function signal(pid: number, kill: (pid: number) => void): void {
+  try {
+    kill(pid);
+  } catch (error) {
+    // `stringField`, never a cast: the rule `dev-lock.ts`'s `isProcessAlive` states.
+    const code = stringField(error, 'code');
+    if (code === 'EPERM') throw new DevStopDeniedError({ pid });
+    if (code !== 'ESRCH') {
+      throw new UltimateError({
+        code: 'X_CLI_UNEXPECTED',
+        cause: `x stop could not signal pid ${String(pid)}: ${renderThrowable(error)}`,
+        fix: 'x doctor --json',
+      });
+    }
+  }
+}
+
+/** Whether the lock on disk still names `pid`: a drain removes it before the process exits. */
+const lockNames = async (stateDir: string, pid: number): Promise<boolean> => {
+  const file = Bun.file(lockPath(stateDir));
+  if (!(await file.exists())) return false;
+  return parseLock(await file.text())?.pid === pid;
+};
+
+/**
+ * Signal the lock's holder and wait for both facts the next boot reads: the pid gone and the lock
+ * no longer naming it. A dead pid whose lock survived was terminated without a drain (Windows, or a
+ * crash mid-drain), and its lock is cleared here so `x stop` returning means `x dev` boots.
+ * No live holder is not a failure: a stale lock is left for `preflight`, which owns that clear.
+ */
+export async function stopDev(input: StopInput): Promise<StopResult> {
+  const alive = input.alive ?? isProcessAlive;
+  const lock = liveDevLock(input.stateDir);
+  if (lock === undefined || !alive(lock.pid)) return { stopped: false };
+  // A pid alone is not the holder: a kill -9 leaves the lock and the kernel reuses the number.
+  // Nothing is signalled and nothing cleared; the next `x dev`'s preflight clears it (`reusedPid`).
+  if (await reusedPid(lock)) return { stopped: false, stale: true };
+  const windows = (input.platform ?? process.platform) === 'win32';
+  const started = performance.now();
+  signal(lock.pid, input.kill ?? ((pid: number) => process.kill(pid, 'SIGTERM')));
+  const waited = (): number => Math.round(performance.now() - started);
+  // The drain removes the lock BEFORE it stops the server (`cmd-dev.ts`), so a pid that is gone
+  // is a lock already cleared — unless no drain ran, which the clear below finishes.
+  while (alive(lock.pid)) {
+    if (waited() >= input.timeoutMs) {
+      throw new DevStopTimeoutError({ pid: lock.pid, waitedMs: waited() });
+    }
+    await Bun.sleep(POLL_MS);
+  }
+  if (await lockNames(input.stateDir, lock.pid)) clearLock(input.stateDir);
+  return { stopped: true, pid: lock.pid, port: lock.port, waitedMs: waited(), drained: !windows };
+}
+
+/** `--timeout` through `@ultimat3/time`'s grammar, the one a job's `timeout:` is read with. */
+function readTimeout(raw: string | undefined): number {
+  if (raw === undefined) return defaultStopTimeoutMs();
+  let ms = Number.NaN;
+  try {
+    ms = parseDuration(raw);
+  } catch {
+    // Refused below with the flag named.
+  }
+  if (ms > 0) return ms;
+  throw new BadFlagError({
+    flag: 'timeout',
+    command: 'stop',
+    reason: 'it is not a positive duration such as 30s, 2m or PT1M',
+    fix: 'x stop --timeout 30s --json',
+  });
+}
+
+export const stopCommand: CliCommand = {
+  spec: stopSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('stop', ctx.cwd).dir;
+    const timeoutMs = readTimeout(flagString(ctx.args, 'timeout'));
+    const { stateDir } = resolveServices(root, ctx.env);
+    const result = await stopDev({ stateDir, timeoutMs });
+    if (!result.stopped) {
+      const stale = result.stale === true;
+      return {
+        ok: true,
+        command: 'stop',
+        summary: msg(stale ? 'cli.stop.stale' : 'cli.stop.none'),
+        data: { stopped: false, ...(stale ? { stale: true } : {}) },
+      };
+    }
+    const params = { pid: result.pid, port: result.port, ms: result.waitedMs };
+    return {
+      ok: true,
+      command: 'stop',
+      summary: msg(result.drained ? 'cli.stop.stopped' : 'cli.stop.terminated', params),
+      data: { ...result },
+    };
+  },
+};

package/src/cmd-test-spec.ts

@@ -4,13 +4,19 @@
 import { TEST_TYPES } from '@ultimat3/testing/test-types';
 import { DEFAULT_BASE } from './affected';
 import type { CommandSpec } from './parse';
-import { SERIAL_TYPES, WORKER_BYTES, WORKER_CEILING, WORKER_FLOOR } from './test-workers';
+import {
+  BUDGET_RULE,
+  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] [--isolate] [--json] [-- <bun test flags>]`,
+  usage: `x test [${TEST_TYPES.join('|')}] [--filter path[,path…]] [--allow-empty] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--isolate] [--seed N] [--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 +26,7 @@ export const testSpec: CommandSpec = {
     {
       name: 'workers',
       type: 'string',
-      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 ')}`,
+      summary: `bun worker count (default: one per ${WORKER_BYTES / 2 ** 30} GiB of a ${BUDGET_RULE} 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',
@@ -48,13 +54,20 @@ export const testSpec: CommandSpec = {
     {
       name: 'affected',
       type: 'boolean',
-      summary: 'only the workspaces a diff touches, and everything that depends on one of them',
+      summary:
+        'only the tests a diff can break: in an app root, the test files whose import closure meets it (data.affected.tests says which and why); elsewhere, the workspaces it touches and everything depending on them',
     },
     {
       name: 'base',
       type: 'string',
       summary: `--affected: git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
     },
+    {
+      name: 'seed',
+      type: 'string',
+      summary:
+        'replay one simulateJobs seed — the N an X_JOB_SIM_INVARIANT names — in every file the run selects (ULTIMATE_JOB_SIM_SEED)',
+    },
     {
       name: 'dirty',
       type: 'boolean',

package/src/cmd-test.ts

@@ -3,21 +3,26 @@
 // spawned is test-shards.ts — this file only turns argv into their inputs, so a parsing bug can
 // never be read as a sharding one. `--affected` is the one narrowing decided here rather than
 // there, because it is a fact about a git diff and not about a path: what the diff touches is
-// `affected.ts`, and this file only maps that answer onto the paths discovery yields.
+// `affected.ts` (workspaces) and, in an app root, `affected-tests.ts` (import closure); this file
+// only maps that answer onto the paths discovery yields.
 
-import { TEST_TYPES } from '@ultimat3/testing';
+import { JOB_SIM_SEED_ENV, TEST_TYPES } from '@ultimat3/testing';
 import type { AffectedScope } from './affected';
 import { affectedScope, affectedScopeJson, DEFAULT_BASE, inScope } from './affected';
+import type { AppNarrowing } from './affected-tests';
+import { appTestScope, narrowToApp } from './affected-tests';
 import { testSpec } from './cmd-test-spec';
 import type { CliCommand, CommandContext } from './command';
 import { ok } from './command';
 import { BadFlagError, NoTestFilesError } from './errors';
+import type { Runner } from './exec';
 import { readIntFlag } from './flag-number';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
 import { quoteArg } from './shell-quote';
+import type { TestFile } from './test-select';
 import {
   discoverTests,
   missingSelection,
@@ -56,6 +61,29 @@ const readWorkers = (args: ParsedArgs): number | undefined =>
     example: 'x test --workers 1',
   });
 
+/**
+ * `--seed`: the one `simulateJobs` seed to replay, the number an `X_JOB_SIM_INVARIANT` printed. A
+ * seed is a uint32 (`seededRandom` reads `seed >>> 0`), so a larger one would replay another.
+ */
+const readSeed = (args: ParsedArgs): number | undefined =>
+  readIntFlag(args, {
+    name: 'seed',
+    command: 'test',
+    min: 0,
+    max: 2 ** 32 - 1,
+    example: 'x test job --seed 7',
+  });
+
+/**
+ * The runner every `bun test` child is spawned through, with the seed in its environment: the
+ * child's `simulateJobs` reads `ULTIMATE_JOB_SIM_SEED` and runs that seed alone.
+ */
+const seeded = (runner: Runner, seed: number | undefined): Runner =>
+  seed === undefined
+    ? runner
+    : (command, options) =>
+        runner(command, { ...options, env: { ...options.env, [JOB_SIM_SEED_ENV]: String(seed) } });
+
 /**
  * One positional, and it is the type. `x test contract live` used to run `contract` and drop
  * `live` on the floor, so a caller reading "contract passed" believed two suites had run. A path
@@ -106,14 +134,41 @@ const asObject = (value: JsonValue | undefined): Readonly<Record<string, JsonVal
     : {};
 
 /**
- * The scope, carried onto whatever the shards reported. `--json` is what an agent reads, and a
- * narrowed run that does not say what it narrowed to is indistinguishable from a full one.
+ * The scope as `--json` carries it: the workspace answer, plus — in an app root — which test files
+ * the import closure selected and why (`tests`). A narrowed run that does not say what it narrowed
+ * to is indistinguishable from a full one.
  */
-const withScope = (result: CommandResult, scope: AffectedScope): CommandResult => ({
+const scopeJson = (scope: AffectedScope, app: AppNarrowing<TestFile> | undefined): JsonValue =>
+  app === undefined
+    ? affectedScopeJson(scope)
+    : { ...asObject(affectedScopeJson(scope)), tests: app.json };
+
+/** The scope, carried onto whatever the shards reported. */
+const withScope = (result: CommandResult, scope: JsonValue): CommandResult => ({
   ...result,
-  data: { ...asObject(result.data), affected: affectedScopeJson(scope) },
+  data: { ...asObject(result.data), affected: scope },
 });
 
+/**
+ * In an app root the diff narrows by import closure — `selectTests`, the rule `x affected` reports
+ * as `data.tests` — since every slice shares the `apps/web` workspace. Outside one, by workspace.
+ */
+async function narrowAffected(
+  discovered: readonly TestFile[],
+  cwd: string,
+  scope: AffectedScope,
+): Promise<{ readonly files: readonly TestFile[]; readonly json: JsonValue }> {
+  const inApp = await appTestScope(cwd, scope.root, scope.plan.changed);
+  if (inApp === undefined) {
+    return {
+      files: discovered.filter((file) => inScope(file.path, scope.prefixes)),
+      json: scopeJson(scope, undefined),
+    };
+  }
+  const narrowed = narrowToApp(discovered, cwd, inApp);
+  return { files: narrowed.kept, json: scopeJson(scope, narrowed) };
+}
+
 /** The selection that matched nothing, as one phrase for `cli.test.empty`. */
 const describeSelection = (missing: { type?: string; filter?: string }): string =>
   [
@@ -130,6 +185,7 @@ export const testCommand: CliCommand = {
     const filter = flagString(ctx.args, 'filter');
     const filters = readFilters(filter);
     const sample = readSample(ctx.args);
+    const seed = readSeed(ctx.args);
     const scope = await readAffectedScope(ctx);
     const discovered = await discoverTests(ctx.cwd, filters, type);
     if (discovered.length === 0) {
@@ -146,11 +202,10 @@ export const testCommand: CliCommand = {
       }
       throw new NoTestFilesError({ root: ctx.cwd, ...missing });
     }
-    const selected =
-      scope === undefined
-        ? discovered
-        : discovered.filter((file) => inScope(file.path, scope.prefixes));
-    if (scope !== undefined && selected.length === 0) {
+    const narrowed =
+      scope === undefined ? undefined : await narrowAffected(discovered, ctx.cwd, scope);
+    const selected = narrowed === undefined ? discovered : narrowed.files;
+    if (scope !== undefined && narrowed !== undefined && selected.length === 0) {
       // Green, and it spawns nothing — a `.md`-only diff genuinely re-checks nothing, and failing
       // a build for editing a doc is the wrong answer. It never reads as "the suite passed": the
       // summary counts the files that ran (zero) and `data.affected` names the diff it asked about,
@@ -161,7 +216,7 @@ export const testCommand: CliCommand = {
         data: {
           ...(type === undefined ? {} : { type }),
           files: 0,
-          affected: affectedScopeJson(scope),
+          affected: narrowed.json,
         },
       });
     }
@@ -179,11 +234,12 @@ export const testCommand: CliCommand = {
     const workers = Math.max(1, Math.min(requested, ceiling));
     const result = await runShards({
       root: ctx.cwd,
-      runner: ctx.runner,
+      runner: seeded(ctx.runner, seed),
       env: ctx.env,
       files,
       workers,
       ...(isolate ? { isolate } : {}),
+      ...(seed === undefined ? {} : { seed }),
       // 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))),
@@ -200,7 +256,7 @@ export const testCommand: CliCommand = {
       // changes what a run measures, and the reproduce line carries it back out.
       ...(ctx.args.passthrough.length === 0 ? {} : { passthrough: ctx.args.passthrough }),
     });
-    return scope === undefined ? result : withScope(result, scope);
+    return narrowed === undefined ? result : withScope(result, narrowed.json);
   },
 };
 

package/src/cmd-upgrade-spec.ts

@@ -0,0 +1,26 @@
+// `x upgrade`'s declaration, apart from its body: the parser, `x help` and the `errors` step read it
+// without loading `cmd-upgrade.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const upgradeSpec: CommandSpec = {
+  name: 'upgrade',
+  summary:
+    'move every @ultimat3/* one major in lockstep, raise the Bun floor, install, gate — and name the section to read',
+  usage: 'x upgrade [--to <version>] [--dry-run] [--json]',
+  // The one command a repository with pins and no `app.config.ts` can still use: `upgrade-root.ts`
+  // finds its root, and its report says which check it could run.
+  flags: [
+    {
+      name: 'to',
+      type: 'string',
+      summary:
+        'an exact release inside the next major, or the higher version a mixed set was told to align to (default: the next major’s newest)',
+    },
+    {
+      name: 'dry-run',
+      type: 'boolean',
+      summary: 'report the pins, the Bun floor edits and the section; write nothing, run no gate',
+    },
+  ],
+};