@ultimat3/cli 24.0.0 → 25.1.0

package/src/dev-supervisor.ts

@@ -5,17 +5,23 @@
 // of logging "reloaded" over stale code, and this loop boots a fresh one on the same port. Every
 // other save stays the in-process reload it was — a restart is paid only where nothing else works.
 
-// why: Bun has no path API; the restart line names files relative to the app root.
-import { relative } from 'node:path';
-import { drain } from '@ultimat3/core';
 import type { StalePin } from './app-reload-graph';
 import { devSpec } from './cmd-dev-spec';
-import type { DevChildGone } from './dev-child-watch';
-import { DEV_SUPERVISOR_PID_ENV, startDevChildWatch, supervisorPid } from './dev-child-watch';
+import type { DevChildGone, DevDrainMessage } from './dev-child-watch';
+import {
+  DEV_SUPERVISOR_PID_ENV,
+  devHardExitMs,
+  startDevChildWatch,
+  supervisorPid,
+} from './dev-child-watch';
 import { devPortFor } from './dev-port';
+import { type RetiringWorker, retireThenDrain } from './dev-restart-retire';
+import { PORT_RANGE } from './flag-number';
 import { msg } from './messages';
 import type { Finding } from './output';
 import { parseArgs } from './parse';
+import { posixRelative } from './posix-path';
+import { writeErrorLine } from './write-line';
 
 /** Set on the child: it serves, and a pinned save makes it exit for a restart. */
 export const DEV_CHILD_ENV = 'ULTIMATE_DEV_CHILD';
@@ -48,12 +54,43 @@ export function devSupervision(
   }
 }
 
-/** A port nothing holds right now, asked of the OS — what `--port 0` is pinned to. */
-export function freeDevPort(): number {
+/** A port the OS hands out for `0`, released at once — the candidate `freeDevPort` checks. */
+const kernelPort = (): number => {
   const probe = Bun.serve({ port: 0, fetch: () => new Response() });
   const port = probe.port ?? 0;
   probe.stop(true);
   return port;
+};
+
+/** Whether `port` can be bound right now: `Bun.serve` refusing it is the answer, not an error. */
+const portBindable = (port: number): boolean => {
+  try {
+    Bun.serve({ port, fetch: () => new Response() }).stop(true);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Kernel candidates tried for a free PAIR before the last one is handed back unchecked. */
+const PAIR_ATTEMPTS = 16;
+
+/**
+ * A port whose PAIR nothing holds right now — what `--port 0` is pinned to. `x dev` binds the web
+ * role on `port` and the sync role on `port + 1` (`syncPortFor`), so a port the kernel says is
+ * free proves nothing about its neighbour: asking for one alone failed the boot `X_PORT_IN_USE`
+ * on a busy box whenever the neighbour was taken (`cmd-dev-orphan.live.test.ts`, 2026-10-07).
+ */
+export function freeDevPort(
+  pick: () => number = kernelPort,
+  bindable: (port: number) => boolean = portBindable,
+): number {
+  let port = 0;
+  for (let attempt = 0; attempt < PAIR_ATTEMPTS; attempt += 1) {
+    port = pick();
+    if (port > 0 && port < PORT_RANGE.max && bindable(port + 1)) return port;
+  }
+  return port;
 }
 
 /** `argv` with every `--port` removed and `--port <port>` appended. */
@@ -75,6 +112,35 @@ function withPort(argv: readonly string[], port: number): readonly string[] {
 export interface DevChild {
   readonly exited: Promise<number>;
   kill(signal: 'SIGINT' | 'SIGTERM'): void;
+  /** The IPC channel; absent or closed, `stopChild` falls back to the signal. */
+  send?(message: DevDrainMessage): void;
+}
+
+/**
+ * Asks the child to drain: a `drain` message over IPC, on every platform — on Windows
+ * `kill('SIGTERM')` is TerminateProcess, which skips the drain and leaves the embedded database
+ * unclean. The signal only when there is no channel to ask over (it closed, or a test's child) —
+ * or once `afterMs` has passed with the child still running: one still booting has no listener
+ * yet and drops the message, and a stop that never lands is a supervisor waiting forever.
+ */
+export function stopChild(
+  child: DevChild,
+  signal: 'SIGINT' | 'SIGTERM',
+  afterMs: number = devHardExitMs(),
+): void {
+  if (child.send !== undefined) {
+    try {
+      child.send({ type: 'x-dev-drain', signal });
+      const fallback = setTimeout(() => child.kill(signal), afterMs);
+      // Never what keeps this process alive: awaiting the child's exit is.
+      fallback.unref();
+      void child.exited.then(() => clearTimeout(fallback));
+      return;
+    } catch {
+      // The channel closed under us: the child is exiting or gone, and the signal is all that's left.
+    }
+  }
+  child.kill(signal);
 }
 
 export interface SuperviseDevInput {
@@ -91,16 +157,23 @@ const spawnInherited = (
   command: readonly string[],
   env: Record<string, string | undefined>,
 ): DevChild =>
-  Bun.spawn([...command], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit', env });
+  Bun.spawn([...command], {
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+    env,
+    // The channel `stopChild` drains over; the child sends nothing back.
+    ipc: () => undefined,
+  });
 
 /**
  * Runs children until one exits with anything but `DEV_RESTART_EXIT_CODE`, and answers that code.
- * SIGINT and SIGTERM are forwarded — a terminal's Ctrl-C reaches the child on its own too, and its
- * drain is idempotent — and once one arrived no child is started again: a Ctrl-C during a restart
- * is a stop, never a respawn.
+ * SIGINT and SIGTERM are forwarded as a `drain` message (`stopChild`) — a terminal's Ctrl-C reaches
+ * the child on its own too, and its drain is idempotent — and once one arrived no child is started
+ * again: a Ctrl-C during a restart is a stop, never a respawn.
  *
  * Every other way out stops the child too: an uncaught error or a `process.exit` here reaches the
- * `exit` listener, which SIGTERMs a child still running. The one way no listener sees is a SIGKILL
+ * `exit` listener, which asks a child still running to drain. The one way no listener sees is a SIGKILL
  * of this process — the child's own watch (`dev-child-watch.ts`) answers that, from its side, off
  * the pid this loop hands it.
  */
@@ -111,12 +184,12 @@ export async function superviseDev(input: SuperviseDevInput): Promise<number> {
   let stopping = false;
   const forward = (signal: 'SIGINT' | 'SIGTERM') => (): void => {
     stopping = true;
-    child?.kill(signal);
+    if (child !== undefined) stopChild(child, signal);
   };
   const onInt = forward('SIGINT');
   const onTerm = forward('SIGTERM');
   const onExit = (): void => {
-    if (running) child?.kill('SIGTERM');
+    if (running && child !== undefined) stopChild(child, 'SIGTERM');
   };
   process.on('SIGINT', onInt);
   process.on('SIGTERM', onTerm);
@@ -145,8 +218,8 @@ export function restartReason(root: string, pins: readonly StalePin[]): string {
   return pins
     .map(({ changed, pinned }) =>
       changed === pinned
-        ? relative(root, pinned)
-        : `${relative(root, changed)} under ${relative(root, pinned)}`,
+        ? posixRelative(root, pinned)
+        : `${posixRelative(root, changed)} under ${posixRelative(root, pinned)}`,
     )
     .join(', ');
 }
@@ -158,7 +231,7 @@ export function restartFinding(root: string, pins: readonly StalePin[]): Finding
     code: 'X_DEV_RESTART_REQUIRED',
     cause: `${restartReason(root, pins)} — a module that defines a primitive still holds the code before the save, and re-importing it would register a second definition`,
     fix: 'restart x dev (a supervised `x dev` restarts itself; an embedded startDev() passes onRestart)',
-    at: first === undefined ? '' : relative(root, first.pinned),
+    at: first === undefined ? '' : posixRelative(root, first.pinned),
   };
 }
 
@@ -166,12 +239,20 @@ export function restartFinding(root: string, pins: readonly StalePin[]): Finding
 export interface ChildRestart {
   readonly options: { readonly onRestart?: (pins: readonly StalePin[]) => void };
   readonly exit: (code: number) => void;
+  /**
+   * The worker this child booted, handed over once `startDev` returns: a restart retires it before
+   * the drain, so a save never cancels a running job (`dev-restart-retire.ts`). `null` for a child
+   * running no worker role.
+   */
+  readonly adopt: (worker: RetiringWorker | null) => void;
 }
 
 /**
  * Only a supervised child restarts: it says why on stderr (fd 1 may be `--json`'s one document),
- * starts core's drain — the hold then releases the lock, the port and the embedded database — and
- * exits `DEV_RESTART_EXIT_CODE` once released. Anything else keeps the finding on `/_x`.
+ * retires its worker — every running job finishes, none is claimed — then starts core's drain (the
+ * hold then releases the lock, the port and the embedded database) and exits
+ * `DEV_RESTART_EXIT_CODE` once released. One restart per child however many saves land while it
+ * waits. Anything else keeps the finding on `/_x`.
  *
  * A child its supervisor named (`DEV_SUPERVISOR_PID_ENV`) also watches for that supervisor's death
  * and its app root's, and stops on either — exit 1 for a root that is gone, which the supervisor,
@@ -181,9 +262,14 @@ export function childRestart(
   root: string,
   env: Readonly<Record<string, string | undefined>>,
   watch: typeof startDevChildWatch = startDevChildWatch,
+  retire: (worker: RetiringWorker | null) => Promise<void> = retireThenDrain,
 ): ChildRestart {
-  if (env[DEV_CHILD_ENV] !== '1') return { options: {}, exit: () => undefined };
+  if (env[DEV_CHILD_ENV] !== '1') {
+    return { options: {}, exit: () => undefined, adopt: () => undefined };
+  }
   let leaving: 'restart' | DevChildGone | undefined;
+  let worker: RetiringWorker | null = null;
+  let restarting = false;
   const watched =
     supervisorPid(env) === undefined
       ? undefined
@@ -193,12 +279,18 @@ export function childRestart(
   return {
     options: {
       onRestart: (pins) => {
-        process.stderr.write(`${msg('cli.dev.restart', { reason: restartReason(root, pins) })}\n`);
+        writeErrorLine(msg('cli.dev.restart', { reason: restartReason(root, pins) }));
         leaving ??= 'restart';
         watched?.stopping(DEV_RESTART_EXIT_CODE);
-        void drain('restart');
+        if (restarting) return;
+        restarting = true;
+        // Never rejects: a failed retire is logged and the drain still runs (`retireThenDrain`).
+        void retire(worker);
       },
     },
+    adopt: (booted) => {
+      worker = booted;
+    },
     exit: () => {
       if (leaving === 'restart') process.exit(DEV_RESTART_EXIT_CODE);
       if (leaving === 'root') process.exit(1);

package/src/dev-traces.ts

@@ -127,49 +127,82 @@ function toTrace(root: ReadableSpan, spans: readonly ReadableSpan[]): RequestTra
 
 /**
  * Spans end innermost-first, so a trace is only whole once its root arrives — which is also the
- * moment the request finished. Grouping by trace id and reporting only groups that have an HTTP
- * root is what keeps a half-finished request, and a job's spans, out of a panel about requests.
+ * moment the request finished. Until then it is OPEN: unclassified, because the span that says
+ * "request" or "background" is the last one to end. A trace whose root arrives and is NOT a
+ * request's is forgotten the moment it ends; one whose root IS a request's is RETAINED.
+ *
+ * Two maps, two quotas, because only retained requests are what the limit promises to keep. One
+ * shared buffer let an open trace evict a retained request: at limit 1, a worker's `job.poll`
+ * ended its `db.update` first, that provisional trace took the only slot, and discarding
+ * `job.poll` a moment later could not bring the request back.
  */
 export function createTraceRecorder(options: { limit?: number } = {}): TraceRecorder {
-  // `byTrace.size > NaN` is false on every pass, so an unchecked limit does not widen the buffer —
+  // `buffer.size > NaN` is false on every pass, so an unchecked limit does not widen the buffer —
   // it deletes the eviction loop, and a dev session then holds every span of every request it has
   // ever seen. At least 1: a recorder that retains nothing is what `/_x/timeline` reads.
   const limit = finiteCount('createTraceRecorder', 'limit', options.limit ?? DEFAULT_LIMIT, 1);
-  // Insertion-ordered: the oldest trace id is the first key, which is the one eviction drops.
-  const byTrace = new Map<string, ReadableSpan[]>();
+  // Insertion-ordered, both: the oldest trace id is the first key, which is the one eviction drops.
+  const retained = new Map<string, ReadableSpan[]>();
+  // Bounded too, by the same figure but separately: a root that never ends (a span leaked by app
+  // code) would otherwise hold its children forever. Overflowing it costs an in-flight trace its
+  // early spans, never a finished request.
+  const open = new Map<string, ReadableSpan[]>();
+
+  const admit = (buffer: Map<string, ReadableSpan[]>, traceId: string, spans: ReadableSpan[]) => {
+    buffer.set(traceId, spans);
+    // Bounded by TRACE, not by span: dropping half a request would leave a flame with holes.
+    // The cost is stated rather than capped — one trace's span array has no bound of its own, so
+    // a request issuing 50k statements holds 50k `ReadableSpan`s until it is evicted. That is a
+    // dev-only recorder (`serve.ts` installs none), and a per-trace cap would silently produce
+    // the holed flame this bound exists to prevent.
+    while (buffer.size > limit) {
+      const oldest = buffer.keys().next();
+      if (oldest.done === true) break;
+      buffer.delete(oldest.value);
+    }
+  };
 
   const record = (span: ReadableSpan): void => {
     const traceId = span.context.traceId;
-    const spans = byTrace.get(traceId);
-    if (spans === undefined) {
-      byTrace.set(traceId, [span]);
-      // Bounded by TRACE, not by span: dropping half a request would leave a flame with holes.
-      // The cost is stated rather than capped — one trace's span array has no bound of its own, so
-      // a request issuing 50k statements holds 50k `ReadableSpan`s until it is evicted. That is a
-      // dev-only recorder (`serve.ts` installs none), and a per-trace cap would silently produce
-      // the holed flame this bound exists to prevent.
-      while (byTrace.size > limit) {
-        const oldest = byTrace.keys().next();
-        if (oldest.done === true) break;
-        byTrace.delete(oldest.value);
-      }
+    // Late spans of a request already retained (work it handed off under its own trace id) join it.
+    const kept = retained.get(traceId);
+    if (kept !== undefined) {
+      kept.push(span);
+      return;
+    }
+    // Taken out and put back last: an open trace still receiving spans is never the oldest key,
+    // so the open bound evicts the trace that went quiet, not the one mid-flight.
+    const spans = open.get(traceId) ?? [];
+    open.delete(traceId);
+    // A request's root: the trace is classified and complete, so it moves into the quota.
+    if (isHttpRoot(span)) {
+      spans.push(span);
+      admit(retained, traceId, spans);
       return;
     }
+    // A root that is not a request's — no parent, no HTTP facts — ends its trace, and the trace is
+    // a scheduler tick or a worker's job: not the panel's to show. Dropped here, not filtered at
+    // read time, because idle background roles minting a few per second would otherwise churn
+    // the buffers for nothing.
+    if (span.parentSpanId === undefined) return;
     spans.push(span);
+    if (spans.length === 1) admit(open, traceId, spans);
+    else open.set(traceId, spans);
   };
 
   return {
     exporter: { export: record },
     traces(): readonly RequestTrace[] {
       const traces: RequestTrace[] = [];
-      for (const spans of byTrace.values()) {
+      for (const spans of retained.values()) {
         const root = httpRootOf(spans);
         if (root !== undefined) traces.push(toTrace(root, spans));
       }
       return traces.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
     },
     reset(): void {
-      byTrace.clear();
+      retained.clear();
+      open.clear();
     },
   };
 }

package/src/dispatch.ts

@@ -16,10 +16,14 @@ import { exitCodeFor, findingFrom, render } from './output';
 import type { ParsedArgs } from './parse';
 import { parseArgs, wantsJson } from './parse';
 import { commandFor, SPECS } from './registry';
-import { rootEnvAdditions } from './root-env';
+import { applyRootEnv, rootEnvChanges } from './root-env';
 
 export interface DispatchOptions {
   readonly argv: readonly string[];
+  /**
+   * The directory the PROCESS started in (`bin.ts` passes `process.cwd()`): `--cwd` resolves
+   * against it, and it is the only directory whose `.env*` Bun loaded on its own.
+   */
   readonly cwd: string;
   readonly env: Readonly<Record<string, string | undefined>>;
   readonly bunVersion: string;
@@ -122,16 +126,19 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     options.cwd,
     typeof args.flags.get('cwd') === 'string' ? String(args.flags.get('cwd')) : undefined,
   );
-  // The ROOT's `.env*`, not the cwd's: Bun loaded the cwd's at startup, and a command run from
-  // `apps/web` finds its root by walking up. Written into the process env too when that IS the env
-  // passed in, because a package reading `Bun.env` directly must see what the command sees.
-  const added = await rootEnvAdditions(cwd, options.env);
-  if (options.env === Bun.env) Object.assign(Bun.env, added);
+  // The ROOT's `.env*`, not the cwd's: Bun loaded the PROCESS cwd's at startup (`options.cwd`,
+  // before `--cwd` moved it), and a command run from `apps/web` finds its root by walking up.
+  // Applied to the process env too when that IS the env passed in (`applyRootEnv`), so a package
+  // reading `Bun.env` directly sees what the command sees — another app's keys removed included.
+  const env = applyRootEnv(
+    options.env,
+    await rootEnvChanges({ cwd, processCwd: options.cwd, env: options.env }),
+  );
   const ctx: CommandContext = {
     args: helpArgs,
     cwd,
     runner: options.runner ?? exec,
-    env: options.env === Bun.env ? options.env : { ...added, ...options.env },
+    env,
     bunVersion: options.bunVersion,
     ...(options.invocation === undefined ? {} : { invocation: options.invocation }),
   };

package/src/doctor-auth.ts

@@ -3,9 +3,9 @@
 // release reads any more. Reaching the server is `authStorageProbe`, deciding is
 // `authStorageFindings` — the split `doctor-sealed.ts` makes.
 
-import { BuiltinAdapter, countUnsealedMfaSecrets } from '@ultimat3/auth';
+import { countUnsealedMfaSecrets, postgresAuthAdapter } from '@ultimat3/auth';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
-import { createPostgresClient, raw } from '@ultimat3/db';
+import { postgresClient, raw } from '@ultimat3/db';
 import type { Finding } from './output';
 
 /**
@@ -71,7 +71,7 @@ export function authStorageFindings(fact: AuthStorageFact): readonly Finding[] {
  */
 export async function authStorageProbe(url: string | undefined): Promise<AuthStorageFact> {
   if (url === undefined || url.trim() === '') return NO_AUTH_STORAGE_FACT;
-  const client = createPostgresClient({ url, applicationName: 'x-doctor' });
+  const client = postgresClient({ url, applicationName: 'x-doctor' });
   try {
     const present = async (table: string): Promise<boolean> => {
       const rows = await client.query<{ readonly present: boolean }>(
@@ -84,7 +84,7 @@ export async function authStorageProbe(url: string | undefined): Promise<AuthSto
       if (await present(table)) retiredTables.push(table);
     }
     const unsealedMfaSecrets = (await present('x_users'))
-      ? await countUnsealedMfaSecrets({ adapter: new BuiltinAdapter(client) })
+      ? await countUnsealedMfaSecrets({ adapter: postgresAuthAdapter(client) })
       : 0;
     return { unsealedMfaSecrets, retiredTables };
   } catch {

package/src/doctor-offline.ts

@@ -4,11 +4,12 @@
 // diagnostic over.
 
 import { ERROR_DOCS_URL } from '@ultimat3/core';
-import { describeRoutes } from '@ultimat3/render';
+import { describePages } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { APP_CONFIG_FILE } from './app-root';
 import type { Finding } from './output';
 import { loadPwaArtifacts } from './pwa-artifacts';
+import { quoteArg } from './shell-quote';
 
 /** A route as this check reads one: the URL it answers, and the surface that answers it. */
 export interface NavigableRoute {
@@ -46,7 +47,7 @@ export interface OfflineFallbackFact {
  * below already refuses `--surface app`, so the check and the remedy disagreed about one code.
  *
  * Residual, and NOT closed by this: a `site/` route declaring `render: 'ssr'` is not prerendered
- * either. `NavigableRoute` carries no render mode, and `describeRoutes()` has one — the narrower
+ * either. `NavigableRoute` carries no render mode, and `describePages()` has one — the narrower
  * check belongs with it.
  */
 const NAVIGABLE: ReadonlySet<string> = new Set(['site']);
@@ -100,13 +101,13 @@ export function offlineFallbackFinding(fact: OfflineFallbackFact): Finding | und
   const name = GENERATABLE.exec(fallback)?.[1];
   return name === undefined
     ? finding(cause, `set pwa.offline.fallback in ${APP_CONFIG_FILE} to a path a route serves`)
-    : finding(cause, `x g route ${name} --surface site`);
+    : finding(cause, `x g route ${quoteArg(name)} --surface site`);
 }
 
 /**
  * The fact, read off a real app root. Both halves come from the framework's own answers — the
  * config through `loadPwaArtifacts` (the one reader of that file) and the routes through
- * `describeRoutes()` (the projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all
+ * `describePages()` (the projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all
  * built from), so this check and the service worker cannot disagree about which routes exist.
  */
 export async function offlineFallbackProbe(root: string): Promise<OfflineFallbackFact> {
@@ -117,6 +118,6 @@ export async function offlineFallbackProbe(root: string): Promise<OfflineFallbac
     routes:
       app.findings.length > 0
         ? undefined
-        : describeRoutes().map((route) => ({ path: route.path, surface: route.surface })),
+        : describePages().map((route) => ({ path: route.path, surface: route.surface })),
   };
 }

package/src/document-options.ts

@@ -32,6 +32,13 @@ export interface DocumentOptions {
    * decided by `app.config.ts`, which the boot read and the renderer cannot.
    */
   readonly themeHead?: string;
+  /**
+   * The app's brand `<style>` from `theme-brand.ts`, or absent for an app with no
+   * `apps/web/shared/theme.ts`. Rendered AFTER the surface stylesheet `<link>`, never in the head
+   * block `themeHead` rides: the brand answers `theme.scss` at equal specificity, so only a later
+   * position in the cascade lets it win.
+   */
+  readonly brandHead?: string;
   /**
    * The page's sync target — `pageSync(…).head` — rendered as render's `clientSyncTags` on every
    * document this process serves. Principal-free, so a shareable document carries it too; absent

package/src/drift-replica-identity.ts

@@ -13,8 +13,8 @@ import { findingFrom } from './output';
 export type ReplicaIdentityWanted = (tables: ReadonlySet<string>) => readonly string[];
 
 /**
- * The app's own answer: its live queries' `subscribes:` plus every params channel's `records`
- * tables, read off the registries `loadApp` filled. One function with `db-generate.ts`, so the gate
+ * The app's own answer: every params channel's `records` tables, with its live queries'
+ * `subscribes:` validated but never granted (#518), read off the registries `loadApp` filled. One function with `db-generate.ts`, so the gate
  * can never expect an identity the generator would not grant, or miss one it would.
  */
 export const appReplicaIdentity: ReplicaIdentityWanted = (tables) =>

package/src/drift.ts

@@ -53,16 +53,39 @@ async function declaredSchemaJson(root: string): Promise<string> {
  */
 export async function schemaHash(root: string): Promise<string> {
   const glob = new Bun.Glob(SCHEMA_GLOB);
-  const paths: string[] = [];
+  const sources: SchemaSource[] = [];
   for await (const path of glob.scan({ cwd: root, absolute: false })) {
-    if (!path.includes('.test.')) paths.push(path);
+    if (path.includes('.test.')) continue;
+    sources.push({ path, text: await Bun.file(join(root, path)).text() });
   }
-  paths.sort();
+  return hashSchemaSources(await declaredSchemaJson(root), sources);
+}
+
+/** One file under `SCHEMA_GLOB`: its path relative to the app root, as the OS spelled it. */
+export interface SchemaSource {
+  readonly path: string;
+  readonly text: string;
+}
+
+/**
+ * The hash itself, pure. The sidecar is committed and compared on every OS, so what a checkout
+ * spells differently is folded away first: `\` separators (a Windows glob) become `/` BEFORE the
+ * sort — `seed2.ts` and `seed/index.ts` order differently under the two — and CRLF text (Git for
+ * Windows' `core.autocrlf=true`) becomes LF. An LF tree on POSIX is hashed exactly as before, so no
+ * sidecar already recorded moves.
+ */
+export function hashSchemaSources(schemaJson: string, sources: readonly SchemaSource[]): string {
+  const files = sources
+    .map(({ path, text }) => ({
+      path: path.replaceAll('\\', '/'),
+      text: text.replaceAll('\r\n', '\n'),
+    }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
   const hasher = new Bun.CryptoHasher('sha256');
-  hasher.update(await declaredSchemaJson(root));
-  for (const path of paths) {
+  hasher.update(schemaJson);
+  for (const { path, text } of files) {
     hasher.update(path);
-    hasher.update(await Bun.file(join(root, path)).text());
+    hasher.update(text);
   }
   return hasher.digest('hex').slice(0, 16);
 }

package/src/error-codes.ts

@@ -228,6 +228,9 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_TRUSTED_PROXY_HOPS_INVALID',
   'X_PERMISSION_BORROWED',
   'X_ERROR_CODE_UNTHROWN_STALE',
+  'X_DEV_STATE_UNWRITABLE',
+  'X_PACKAGE_TEST_ONLY_SHIPPED',
+  'X_ISLAND_MODULE_DUPLICATED',
 ] as const;
 
 /**
@@ -412,6 +415,9 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_PERMISSION_BORROWED: 'an app rule requires a permission only an imported package declared',
   X_ERROR_CODE_UNTHROWN_STALE:
     'a code UNTHROWN_CODES lists as thrown by nothing is thrown again — delete it from UNTHROWN_CODES in packages/cli/src/unthrown-codes.ts',
+  X_DEV_STATE_UNWRITABLE: 'x dev cannot claim its state directory',
+  X_PACKAGE_TEST_ONLY_SHIPPED: 'a test-only module ships in the tarball',
+  X_ISLAND_MODULE_DUPLICATED: 'An island chunk bundles one module more than once',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/error-page-csp.ts

@@ -1,15 +1,11 @@
-// The `style-src` sources that admit an app's own error pages. `error-pages.ts` serves
-// `apps/web/site/errors/<status>.html` verbatim, and such a page is a self-contained document —
-// it carries its own `<style>`, because the app's stylesheet bundle is not linked from it. Under
-// the enforced policy a container sends, `style-src 'self' <overlay hash>` blocked that block and
-// the page rendered unstyled; `x dev` sends the policy report-only, so the same page looked fine
-// on every author's machine. Hashed at boot, like the hydration runtime: a hash is a function of
-// the body, and these files do not change while a container runs.
+// The inline `<style>` bodies of an app's own error pages, for `style-src` to admit. Such a page
+// (`apps/web/site/errors/<status>.html`, served verbatim by `error-pages.ts`) carries its own
+// `<style>` — no stylesheet bundle is linked from it — and under the container's enforced policy an
+// unadmitted block is a page rendered unstyled; `x dev` is report-only, so it looked fine there.
 
 // why: Bun exposes no path-join primitive, and the directory is app-root-relative — the same
 // necessity `error-pages.ts` records.
 import { join } from 'node:path';
-import { cspHashSource } from '@ultimat3/http';
 import { ERROR_PAGE_DIR } from './error-pages';
 
 /**
@@ -26,18 +22,21 @@ export function inlineStyleBodies(html: string): readonly string[] {
 }
 
 /**
- * One hash per distinct `<style>` body across every error page the app ships. Read once at boot:
- * a page an author drops in while `x dev` runs is served (the reader is per request) but not yet
- * admitted, which the report-only policy there turns into a console report, not a blank page.
+ * Every distinct `<style>` body across every error page the app ships, sorted — BODIES, because
+ * `startRoles({ inlineStyles })` hashes what it is given (`style-csp.ts`). This returned the hashes
+ * until 2026-10, and the boot hashed them again: the policy admitted the hash of a hash, and every
+ * app error page carrying a `<style>` rendered unstyled under the container's enforced CSP. Read
+ * once at boot: a page an author drops in while `x dev` runs is served (the reader is per request)
+ * but not yet admitted, which the report-only policy there turns into a console report.
  */
-export async function errorPageStyleSources(root: string): Promise<readonly string[]> {
+export async function errorPageStyleBodies(root: string): Promise<readonly string[]> {
   const dir = join(root, ERROR_PAGE_DIR);
-  const sources = new Set<string>();
+  const bodies = new Set<string>();
   for (const name of await htmlFilesIn(dir)) {
     const html = await Bun.file(join(dir, name)).text();
-    for (const body of inlineStyleBodies(html)) sources.add(cspHashSource(body));
+    for (const body of inlineStyleBodies(html)) bodies.add(body);
   }
-  return [...sources].sort();
+  return [...bodies].sort();
 }
 
 /** `Bun.Glob.scan` throws `ENOENT` on a missing directory, and no error pages is the common case. */

package/src/exec.ts

@@ -32,6 +32,12 @@ export interface ExecOptions {
    */
   readonly env?: Readonly<Record<string, string | undefined>>;
   readonly stdin?: string;
+  /**
+   * Told the child's pid the moment it exists. A gate step's deadline records it here
+   * (`verify-deadline.ts`): on Windows no process's environment is readable, so the tag sweep
+   * finds nothing and the pid recorded at spawn is the only handle on what the step started.
+   */
+  readonly onSpawn?: (pid: number) => void;
 }
 
 export type Runner = (command: readonly string[], options: ExecOptions) => Promise<ExecResult>;
@@ -112,6 +118,8 @@ export const exec: Runner = async (command, options) => {
     });
   }
   const proc = spawnOrRefuse([head, ...rest], options);
+  // Outside the refusal: a throwing observer is the caller's bug, never "could not run".
+  options.onSpawn?.(proc.pid);
   const [stdout, stderr, code] = await Promise.all([
     new Response(proc.stdout).text(),
     new Response(proc.stderr).text(),

package/src/favicon.ts

@@ -7,7 +7,7 @@
 // it against the root is string work no `Bun.file` overload does — the same necessity
 // `runtime-assets.ts` records for `ICON_SOURCE`.
 import { join } from 'node:path';
-import { createRaster, encodeImage } from '@ultimat3/core';
+import { blankRaster, encodeImage } from '@ultimat3/core';
 import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 
@@ -47,7 +47,7 @@ const FAVICON_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
  * is a third rung under a mechanism that has exactly two.
  */
 export function defaultFavicon(): Uint8Array {
-  const raster = createRaster(DEFAULT_SIZE, DEFAULT_SIZE, 'favicon');
+  const raster = blankRaster(DEFAULT_SIZE, DEFAULT_SIZE, 'favicon');
   const { pixels } = raster;
   for (let i = 0; i < pixels.length; i += 4) {
     pixels[i] = MARK_LEVEL;