@ultimat3/cli 24.0.0 → 25.1.0

package/src/trusted-hops.ts

@@ -0,0 +1,49 @@
+// How many proxies sit in front of this process, read from `TRUSTED_PROXY_HOPS`. Its own module
+// so both the web role (`role-start.ts`) and the sync node (`role-sync.ts`) read it without one
+// importing the other — `role-start` imports `role-sync`, and the reverse edge was a cycle.
+
+import { MAX_PROXY_HOPS } from '@ultimat3/http';
+import type { Env } from './runtime-bindings';
+import { TrustedProxyHopsInvalidError } from './trusted-hops-error';
+
+/**
+ * How many proxies is too many, and the number is **`@ultimat3/http`'s**, not this file's.
+ *
+ * `defineHttpConfig` screens the same setting — `assertFiniteCount('trustedProxyHops', …,
+ * MAX_PROXY_HOPS)` — and this screen used to say 16 where that one says 64, so one setting had two
+ * ceilings and a deployment behind 20 hops was accepted by the library and refused by the boot.
+ * Widened rather than narrowed: tightening the library would break a shipped public API, while
+ * this end only ever refused topologies http already supports.
+ *
+ * It was a duplicated literal until 2026-08-26, because `@ultimat3/http` did not export the
+ * constant. It does now, so this file IMPORTS it — a downward edge, tier 5 to tier 2 — and there is
+ * no second number left to drift. `runtime-overrides.test.ts` still probes both screens for the
+ * highest count each accepts, and it is kept rather than deleted: it compares BEHAVIOUR, so it also
+ * catches the two disagreeing for a reason a shared constant cannot fix, such as one side gaining a
+ * range check the other does not have.
+ */
+
+/**
+ * How many proxies append to `x-forwarded-for` between the client and this process, or `null`
+ * when nothing in front of it is trusted.
+ *
+ * Read from the environment and not from `app.config.ts`, for the reason `PORT` and `ROLE` are: it
+ * is a fact about the DEPLOYMENT — one image runs behind an ingress in one cluster and behind
+ * nothing on a laptop — and an app that hardcoded it would be wrong in one of the two. `x dev`
+ * sets neither and gets `trustProxy: false`, which is correct: there is no proxy.
+ *
+ * Without this seam a container behind an ingress reads `ctx.ip` as the ingress's own socket
+ * address on every request, so the rate limiter keys the entire fleet's anonymous traffic into ONE
+ * bucket and a single scanner 429s every real signup.
+ */
+export function trustedHopsFromEnv(env: Env): number | null {
+  const raw = env['TRUSTED_PROXY_HOPS']?.trim();
+  if (raw === undefined || raw === '') return null;
+  const hops = Number(raw);
+  // A malformed count is refused rather than defaulted: reading the header at the wrong index is
+  // trusting a value the client typed, which is the failure trusting a proxy exists to avoid.
+  if (!/^\d+$/.test(raw) || !Number.isInteger(hops) || hops < 1 || hops > MAX_PROXY_HOPS) {
+    throw new TrustedProxyHopsInvalidError({ value: raw });
+  }
+  return hops;
+}

package/src/unscanned-admin.ts

@@ -4,7 +4,7 @@
 // silently, which is how the reference app shipped an admin nobody could open.
 
 import { renderFixShellArg, stripComments } from '@ultimat3/core';
-import { describeRoutes } from '@ultimat3/render';
+import { describePages } from '@ultimat3/render';
 import { ADMIN_FILE } from './admin-registration';
 import type { Finding } from './output';
 import { hasPathSegment } from './path-segments';
@@ -17,7 +17,7 @@ const DECLARES = /\bdefineAdmin\(/;
 
 /** Any admin this process mounted — then every declaration was reached, wherever it sits. */
 export const adminMounted = (): boolean =>
-  describeRoutes().some((route) => route.mount?.by === 'defineAdmin');
+  describePages().some((route) => route.mount?.by === 'defineAdmin');
 
 /** Where the file belongs: its own name under the admin's home, `index.ts` as the declaration. */
 const homeOf = (file: string): string => {

package/src/verify-checks.ts

@@ -46,7 +46,7 @@ import type { VerifyStep } from './verify-step';
 import { fromExec, fromFindings, hostFindings } from './verify-step';
 import { TEST_STEPS } from './verify-tests';
 import { typecheckArgs } from './verify-typecheck';
-import { checkFileSizes, checkPackageShape, hasWorkspacePackages } from './workspace-checks';
+import { checkPackageShape, fileSizeReport, hasWorkspacePackages } from './workspace-checks';
 import { checkWorkspaceDependencies } from './workspace-graph';
 
 /** The one file that makes the `roadmap` step answerable, and therefore what `applies` reads. */
@@ -120,7 +120,17 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'filesize',
     summary: 'one file, one job',
-    run: async (ctx) => fromFindings(await checkFileSizes(ctx.root)),
+    // The band below the ceiling rides as warnings: listed in `--json` on a pass, never a failure.
+    run: async (ctx) => {
+      const { findings, warnings } = await fileSizeReport(ctx.root);
+      return {
+        ...fromFindings(findings),
+        warnings: warnings.map(
+          (warning) =>
+            `${warning.path}: ${warning.lines} lines, ${warning.ceiling - warning.lines} under the ${warning.ceiling} line ceiling — plan the split`,
+        ),
+      };
+    },
   },
   {
     name: 'package-shape',

package/src/verify-coverage-run.ts

@@ -14,6 +14,7 @@
 import { rm } from 'node:fs/promises';
 // why: Bun ships no path-join primitive.
 import { dirname, join } from 'node:path';
+import { ISOLATED_ENV } from '@ultimat3/testing';
 import type { CoverageMap } from './coverage-lcov';
 import { fileCoverageOf, mergeCoverage, parseLcov } from './coverage-lcov';
 import type { ExecResult, Runner } from './exec';
@@ -21,7 +22,7 @@ import { execOutput } from './exec';
 import { msg } from './messages';
 import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
-import { failureOf, ISOLATED_TEST_ENV } from './test-shards';
+import { failureOf } from './test-shards';
 import { SLOT_HELD_ENV } from './test-slots';
 import type { StepOutcome } from './verify-step';
 
@@ -113,7 +114,7 @@ export async function runCovered(options: CoveredRunOptions): Promise<CoveredRun
   const isolate = options.isolate === true;
   const overrides = {
     ...testEnvOverrides(options.root, options.env ?? Bun.env),
-    ...(isolate ? { [ISOLATED_TEST_ENV]: '1' } : {}),
+    ...(isolate ? { [ISOLATED_ENV]: '1' } : {}),
     ...(lease === undefined ? {} : { [SLOT_HELD_ENV]: '1' }),
   };
   const results = new Array<ExecResult>(slices.length);

package/src/verify-deadline.ts

@@ -126,15 +126,23 @@ export interface StepGuard {
  *
  * A nested gate (a test that runs `x verify`) appends its tag to the one it inherited, so the
  * outer step's kill still finds the inner step's children.
+ *
+ * Windows reads no process's environment, so there the tag finds nothing: every child's pid is
+ * recorded at spawn (`ExecOptions.onSpawn`) and `expire` tree-kills each one (`taskkillTree`).
  */
 export function guardStep(
   runner: Runner,
   tag: string,
   env: Readonly<Record<string, string | undefined>> = Bun.env,
+  platform: PlatformKill = {},
 ): StepGuard {
   let expired = false;
   // Keyed by the promise itself: two batches of one step may run the very same argv.
   const inFlight = new Map<Promise<ExecResult>, readonly string[]>();
+  // Every child's pid, recorded the moment it exists and dropped when its run settles (a settled
+  // pid may be reused). Windows reads no process's environment, so this is the step's only handle.
+  const spawned = new Map<number, readonly string[]>();
+  const windows = (platform.platform ?? process.platform) === 'win32';
   const inherited = env[STEP_TAG_ENV];
   const value = inherited === undefined || inherited === '' ? tag : `${inherited} ${tag}`;
   return {
@@ -151,18 +159,32 @@ export function guardStep(
           durationMs: 0,
         };
       }
-      const run = runner(command, { ...options, env: { ...options.env, [STEP_TAG_ENV]: value } });
+      let pid: number | undefined;
+      const run = runner(command, {
+        ...options,
+        env: { ...options.env, [STEP_TAG_ENV]: value },
+        onSpawn: (spawnedPid) => {
+          pid = spawnedPid;
+          spawned.set(spawnedPid, command);
+          options.onSpawn?.(spawnedPid);
+        },
+      });
       inFlight.set(run, command);
       try {
         return await run;
       } finally {
         inFlight.delete(run);
+        if (pid !== undefined) spawned.delete(pid);
       }
     },
     async expire(): Promise<StepExpiry> {
       expired = true;
       // Before the kill: a killed child settles its runner call, which takes it off the map.
       const waiting = [...inFlight];
+      if (windows) {
+        const killed = await killTrees(spawned, platform.killTree ?? taskkillTree);
+        return { killed, inFlight: await settleAll(waiting) };
+      }
       const workers = await killTagged(tag, undefined, isTestWorker);
       if (workers.length > 0) {
         await raceDeadline(Promise.allSettled(waiting.map(([run]) => run)), CRASH_REPORT_MS);
@@ -171,19 +193,74 @@ export function guardStep(
       const killed = [...workers, ...rest.filter((one) => workers.every((w) => w.pid !== one.pid))];
       // After it: the kill closed the child's pipes, so its call now resolves with everything it
       // had printed — for `bun test`, the crash line of each file a worker was holding.
-      const settled = await Promise.all(
-        waiting.map(async ([run, command]): Promise<InFlightRun> => {
-          const raced = await raceDeadline(run.then(execOutput), SETTLE_MS).catch(() => undefined);
-          return raced === undefined || raced.timedOut
-            ? { command }
-            : { command, output: raced.value };
-        }),
-      );
-      return { killed, inFlight: settled };
+      return { killed, inFlight: await settleAll(waiting) };
     },
   };
 }
 
+/** What each child had printed, once the kill closed its pipes — or just its argv past `SETTLE_MS`. */
+function settleAll(
+  waiting: readonly (readonly [Promise<ExecResult>, readonly string[]])[],
+): Promise<readonly InFlightRun[]> {
+  return Promise.all(
+    waiting.map(async ([run, command]): Promise<InFlightRun> => {
+      const raced = await raceDeadline(run.then(execOutput), SETTLE_MS).catch(() => undefined);
+      return raced === undefined || raced.timedOut ? { command } : { command, output: raced.value };
+    }),
+  );
+}
+
+/** Kills `pid` and every process under it; answers whether it did. */
+export type KillTree = (pid: number) => Promise<boolean>;
+
+/** The platform a guard kills on, injectable so the Windows path runs on any host's tests. */
+export interface PlatformKill {
+  /** `process.platform` unless a test names one. */
+  readonly platform?: string;
+  /** Windows' tree kill. Absent is `taskkill /T /F /PID`. */
+  readonly killTree?: KillTree;
+}
+
+/**
+ * Windows: `taskkill /T /F` — the tree under the pid, forced. POSIX's tag sweep cannot run there
+ * (no process exposes its environment) and `process.kill` ends one process, leaving a
+ * `bun test --parallel` coordinator's workers behind. Bounded like `ps`, for the same reason.
+ */
+export async function taskkillTree(pid: number): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(['taskkill', '/T', '/F', '/PID', String(pid)], {
+      stdout: 'ignore',
+      stderr: 'ignore',
+      timeout: PS_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
+    });
+    return (await proc.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every recorded child, each with its tree, named by the argv it was started with. A child that
+ * already exited is not recorded — its run settled — so what is left is what was still running.
+ * A grandchild whose parent already exited is out of reach here: Windows keeps no tag to find it.
+ */
+export async function killTrees(
+  spawned: ReadonlyMap<number, readonly string[]>,
+  killTree: KillTree,
+): Promise<readonly KilledProcess[]> {
+  const killed: KilledProcess[] = [];
+  for (const [pid, command] of spawned) {
+    if (pid === process.pid || !(await killTree(pid))) continue;
+    const line = command.join(' ');
+    killed.push({
+      pid,
+      command: line.length > COMMAND_CHARS ? `${line.slice(0, COMMAND_CHARS)}…` : line,
+    });
+  }
+  return killed;
+}
+
 /** One process and the environment it was started with, as the platform reports it. */
 export interface ProcessEnviron {
   readonly pid: number;

package/src/verify-merge.ts

@@ -132,15 +132,41 @@ export function parsePart(file: string, text: string, command: string = GATE_COM
 /** A gap finding, with a fix spelled for the entry that raised it. */
 type Gap = (cause: string, at?: string) => Finding;
 
-const gapFor =
-  (command: string): Gap =>
-  (cause, at) => ({
-    code: 'X_VERIFY_MERGE_INCOMPLETE',
-    cause,
-    fix: `${command} merge parts/*.json --json   # after every CI job uploaded its part`,
-    docs: ERROR_DOCS_URL,
-    ...(at === undefined ? {} : { at }),
-  });
+/**
+ * The gap kinds a merge can find. `present` is a document that arrived and disagrees with the
+ * others; `absent` is one that never arrived at all — GitHub failing to acquire a hosted runner
+ * leaves the job `cancelled` with no steps and no upload, and "missing shard 2/3" alone read as a
+ * shard that ran and died. The two are fixed differently: the first is debugged, the second re-run.
+ */
+interface Gaps {
+  readonly present: Gap;
+  readonly absent: Gap;
+}
+
+/** Said of every absent gap, so it can never be mistaken for a failure the part reported. */
+const NEVER_ARRIVED =
+  'its result never arrived — its CI job never ran or never uploaded (cancelled before a step, or no runner acquired); this is not a failure it reported';
+
+const gapsFor = (command: string): Gaps => {
+  const finding =
+    (fix: string): Gap =>
+    (cause, at) => ({
+      code: 'X_VERIFY_MERGE_INCOMPLETE',
+      cause,
+      fix,
+      docs: ERROR_DOCS_URL,
+      ...(at === undefined ? {} : { at }),
+    });
+  return {
+    present: finding(
+      `${command} merge parts/*.json --json   # after every CI job uploaded its part`,
+    ),
+    // The merge is still what proves the gate whole; what it waits on is a re-run, not a fix.
+    absent: finding(
+      `${command} merge parts/*.json --json   # after re-running the job that never reported: gh run rerun <run-id> --failed`,
+    ),
+  };
+};
 
 /** The step every part's coverage facts belong to. */
 const COVERED_STEP = 'unit';
@@ -220,15 +246,16 @@ function mergeStep(
   name: string,
   entries: readonly { readonly part: string; readonly step: PartStep }[],
   floor: VerifyFloor | undefined,
-  gap: Gap,
+  kinds: Gaps,
   rider: MergeRiders[string] | undefined,
 ): StepResult {
+  const gap = kinds.present;
   if (entries.length === 0) {
     return {
       name,
       ok: false,
       durationMs: 0,
-      findings: [gap(`step "${name}" is in no part — no CI job ran it`, name)],
+      findings: [kinds.absent(`step "${name}" is in no part: ${NEVER_ARRIVED}`, name)],
     };
   }
   const sharded = entries.filter((entry) => entry.step.shard !== undefined);
@@ -268,8 +295,8 @@ function mergeStep(
     const doubled = [...seen].filter(([, count]) => count > 1).map(([index]) => index);
     if (missing.length > 0) {
       gaps.push(
-        gap(
-          `step "${name}" is missing shard(s) ${missing.map((i) => `${String(i)}/${String(total)}`).join(', ')}`,
+        kinds.absent(
+          `step "${name}" is missing shard(s) ${missing.map((i) => `${String(i)}/${String(total)}`).join(', ')}: ${NEVER_ARRIVED}`,
           name,
         ),
       );
@@ -295,6 +322,8 @@ function mergeStep(
       .map((step) => step.output as string),
     ...(rider?.output === undefined ? [] : [rider.output]),
   ].join('\n');
+  // Every part's advice, once each and in the order the parts reported it.
+  const warnings = [...new Set(steps.flatMap((step) => step.warnings ?? []))];
   const skipped =
     sharded.length > 0 ? nothingRan && !required : steps.every((step) => step.skipped);
   return {
@@ -309,6 +338,7 @@ function mergeStep(
     ...(skipped ? { skipped: true } : {}),
     findings,
     ...(output.length === 0 ? {} : { output }),
+    ...(warnings.length === 0 ? {} : { warnings }),
     ...(tests === undefined ? {} : { tests }),
   };
 }
@@ -320,11 +350,13 @@ export function mergeParts(
   declared: readonly string[] = VERIFY_STEP_NAMES,
   options: MergeOptions = {},
 ): CommandResult {
-  const gap = gapFor(options.command ?? GATE_COMMAND);
+  const kinds = gapsFor(options.command ?? GATE_COMMAND);
   const unknown = parts.flatMap((part) =>
     part.steps
       .filter((step) => !declared.includes(step.name))
-      .map((step) => gap(`${part.file} reports "${step.name}", which x verify does not run`)),
+      .map((step) =>
+        kinds.present(`${part.file} reports "${step.name}", which x verify does not run`),
+      ),
   );
   const steps = declared.map((name) =>
     mergeStep(
@@ -333,7 +365,7 @@ export function mergeParts(
         part.steps.filter((step) => step.name === name).map((step) => ({ part: part.file, step })),
       ),
       floor,
-      gap,
+      kinds,
       options.riders !== undefined && Object.hasOwn(options.riders, name)
         ? options.riders[name]
         : undefined,

package/src/verify-part-step.ts

@@ -14,6 +14,7 @@ export interface PartStep {
   readonly workers?: number;
   readonly tests?: TestCounts;
   readonly output?: string;
+  readonly warnings?: readonly string[];
   readonly shard?: {
     readonly index: number;
     readonly total: number;
@@ -29,7 +30,7 @@ const isCount = (value: unknown): value is number =>
   typeof value === 'number' && Number.isInteger(value) && value >= 0;
 
 /** What every finding is: code, cause and fix as strings. Optional fields ride along as written. */
-const isFinding = (value: unknown): value is Finding =>
+export const isFinding = (value: unknown): value is Finding =>
   isRecord(value) &&
   typeof value['code'] === 'string' &&
   typeof value['cause'] === 'string' &&
@@ -41,6 +42,9 @@ const isTests = (value: unknown): value is TestCounts =>
   isCount(value['skipped']) &&
   (value['errors'] === undefined || isCount(value['errors']));
 
+const isTextList = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((line) => typeof line === 'string');
+
 const isShard = (value: unknown): value is NonNullable<PartStep['shard']> =>
   isRecord(value) &&
   isCount(value['index']) &&
@@ -63,7 +67,7 @@ export function readPartStep(raw: unknown): PartStep | string {
   if (!Array.isArray(findings) || !findings.every(isFinding)) {
     return `holds step "${name}" whose findings are not each a code, a cause and a fix`;
   }
-  const { tests, shard, output, workers, skipped } = raw;
+  const { tests, shard, output, workers, skipped, warnings } = raw;
   if (tests !== undefined && !isTests(tests)) {
     return `holds step "${name}" whose tests are not counts`;
   }
@@ -73,6 +77,9 @@ export function readPartStep(raw: unknown): PartStep | string {
   if (output !== undefined && typeof output !== 'string') {
     return `holds step "${name}" whose output is not text`;
   }
+  if (warnings !== undefined && !isTextList(warnings)) {
+    return `holds step "${name}" whose warnings are not a list of text`;
+  }
   if (workers !== undefined && !isCount(workers)) {
     return `holds step "${name}" whose workers is not a count`;
   }
@@ -85,6 +92,7 @@ export function readPartStep(raw: unknown): PartStep | string {
     ...(workers === undefined ? {} : { workers }),
     ...(tests === undefined ? {} : { tests }),
     ...(output === undefined ? {} : { output }),
+    ...(warnings === undefined ? {} : { warnings }),
     ...(shard === undefined ? {} : { shard }),
   };
 }

package/src/verify-role-load-probe.ts

@@ -3,11 +3,22 @@
 // those registered that the worker's process did not hold. Run by hand, it is the same answer.
 
 import { scanAppModules } from './app-load';
+import type { RelativeHost } from './posix-path';
+import { posixRelative } from './posix-path';
 import { scanBackground } from './role-load';
 import type { MissingRegistration } from './verify-role-load';
 import { PROBE_MARKER, registeredSince, registrations } from './verify-role-load';
 import { writeLine } from './write-line';
 
+/**
+ * The app-root-relative POSIX key a scanned module is held under — the form `scanBackground`'s
+ * `files` already are. A `${root}/` prefix strip matched nothing on Windows (`D:\…\app\apps\…`),
+ * so every module the worker DID import was blamed as missing. `host` is for a test only.
+ */
+export function moduleKey(root: string, absolute: string, host?: RelativeHost): string {
+  return posixRelative(root, absolute, host);
+}
+
 /**
  * What importing each module the worker load left out registered, by module — `[]` when the whole
  * scan reported a module that would not import. Exported so a test calls it in its own process;
@@ -31,12 +42,11 @@ export async function probeRoleLoad(root: string): Promise<readonly MissingRegis
 
   // The whole app, in the scan's own order. `include` is asked before each import, so the look it
   // takes is at what the PREVIOUS module added; a module the worker already imported adds nothing.
-  const prefix = root.endsWith('/') ? root : `${root}/`;
   const whole = await scanAppModules(root, {
     track: false,
     include: (absolute) => {
       attribute();
-      const file = absolute.startsWith(prefix) ? absolute.slice(prefix.length) : absolute;
+      const file = moduleKey(root, absolute);
       current = imported.has(file) ? undefined : file;
       return true;
     },

package/src/verify-role-load.ts

@@ -5,7 +5,7 @@
 // manifest; this is the build error for everything else a job reads by name.
 
 // why: Bun ships no path API; the fix names the import relative to the API index.
-import { dirname, join, relative } from 'node:path';
+import { dirname, join } from 'node:path';
 import { ERROR_DOCS_URL, registeredServiceNames, singleLine } from '@ultimat3/core';
 import { entityNames } from '@ultimat3/entity';
 import { catalogDeclarationCount } from '@ultimat3/i18n';
@@ -16,6 +16,8 @@ import { definedStorage } from '@ultimat3/storage';
 import { API_INDEX } from './app-root';
 import type { Runner } from './exec';
 import type { Finding } from './output';
+import type { RelativeHost } from './posix-path';
+import { posixRelative } from './posix-path';
 import { quoteArg } from './shell-quote';
 
 /** One thing a process registered, as a job would ask for it: by kind and by name. */
@@ -79,9 +81,12 @@ export function registeredSince(
   return after.filter((one) => !had.has(keyOf(one)));
 }
 
-/** The import the API index is missing, as it would be written there. */
-function specifierFor(module: string): string {
-  const from = relative(dirname(API_INDEX), module).replace(/\.[jt]sx?$/, '');
+/**
+ * The import the API index is missing, as it would be written there — POSIX on every host: a `\`
+ * pasted from a Windows run is an import no Linux teammate resolves. `host` is for a test only.
+ */
+export function specifierFor(module: string, host?: RelativeHost): string {
+  const from = posixRelative(dirname(API_INDEX), module, host).replace(/\.[jt]sx?$/, '');
   return from.startsWith('.') ? from : `./${from}`;
 }
 

package/src/verify-run.ts

@@ -277,6 +277,9 @@ async function runStep(
       skipped: nothingRan && !required,
       findings: [...outcome.findings, ...vanished],
       ...(outcome.output === undefined ? {} : { output: outcome.output }),
+      ...(outcome.warnings === undefined || outcome.warnings.length === 0
+        ? {}
+        : { warnings: outcome.warnings }),
       ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
       ...(outcome.widthReason === undefined ? {} : { widthReason: outcome.widthReason }),
       ...(outcome.shard === undefined ? {} : { shard: outcome.shard }),

package/src/verify-step.ts

@@ -135,6 +135,8 @@ export interface StepOutcome {
   readonly ok: boolean;
   readonly findings: readonly Finding[];
   readonly output?: string;
+  /** Advice that does not fail the step; carried on a pass too (`StepResult.warnings`). */
+  readonly warnings?: readonly string[];
   /**
    * Processes this step actually used. `1` is a step that ran serially, and a reader has to be
    * able to tell "serial because nothing could isolate it" from "parallel and fast" without

package/src/verify-test-run.ts

@@ -4,13 +4,14 @@
 
 // why: Bun ships no path-join primitive; the timings cache lives under the run's root.
 import { join } from 'node:path';
+import { ISOLATED_ENV } from '@ultimat3/testing';
 import type { Runner } 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';
-import { failureOf, ISOLATED_TEST_ENV, TEST_TIMINGS_FILE, testArgs } from './test-shards';
+import { failureOf, TEST_TIMINGS_FILE, testArgs } from './test-shards';
 import { BATCH_FILES_PER_WORKER, SHARED_BATCH_FILES_PER_WORKER } from './test-workers';
 import type { StepOutcome } from './verify-step';
 // Type-only, so nothing here evaluates verify-tests.ts and the two files cannot form a cycle.
@@ -53,7 +54,7 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
   const workers = Math.max(1, Math.min(Math.trunc(options.workers), files.length || 1));
   const envOverrides = {
     ...testEnvOverrides(options.root, options.env ?? Bun.env),
-    ...(options.isolate === true ? { [ISOLATED_TEST_ENV]: '1' } : {}),
+    ...(options.isolate === true ? { [ISOLATED_ENV]: '1' } : {}),
   };
   // 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.

package/src/verify-tests.ts

@@ -40,7 +40,6 @@ import { runParallel } from './verify-test-run';
  * and `@ultimat3/testing` is already a runtime dependency of this package.
  */
 export type { TestType } from '@ultimat3/testing';
-export { TEST_TYPES } from '@ultimat3/testing';
 
 type TypedTest = Exclude<TestType, 'unit'>;
 

package/src/worker-bundle.ts

@@ -7,7 +7,7 @@
 // why: Bun ships no path API; the entry is resolved to a file and named in the cause.
 import { dirname, join, relative } from 'node:path';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, json } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse } from '@ultimat3/http';
 import { FrameworkScriptBuildFailedError, type FrameworkScriptKind } from './errors';
 import { describeBuildError, graphHash, stripDebugId } from './island-identity';
 
@@ -198,7 +198,7 @@ function scriptRoute(
     handler: (request: UltimateRequest): Response => {
       const script = source();
       if (script === undefined || script.url !== request.pathname) {
-        return json(
+        return jsonResponse(
           {
             ok: false,
             error: {