@ultimat3/cli 23.0.0 → 25.0.0

package/src/dev-restart-retire.ts

@@ -0,0 +1,46 @@
+// `x dev`'s restart, worker first (issue #677). A save that reaches a primitive-defining module
+// restarts the child, and the drain that ends it used to be the FIRST thing it did: a job that ran
+// past the drain budget was aborted `X_DRAINING` and requeued, so a non-idempotent one (a bank
+// login) ran twice. The worker is retired first — `stop()` claims nothing and aborts nothing — and
+// only then is the drain asked to release the port, the lock and the embedded database.
+
+import { drain, logger, renderThrowable } from '@ultimat3/core';
+import type { Worker } from '@ultimat3/jobs';
+import { msg } from './messages';
+import { writeErrorLine } from './write-line';
+
+/** The two calls a retire makes, so a test hands in a worker without booting a queue. */
+export type RetiringWorker = Pick<Worker, 'stats' | 'stop'>;
+
+export interface RetireDeps {
+  /** The process drain the restart ends in. Default: core's `drain`. */
+  readonly drain: (reason: string) => Promise<void>;
+  /** Where the wait is said. Default: stderr — fd 1 may be `--json`'s one document. */
+  readonly say: (line: string) => void;
+}
+
+const DEFAULT_DEPS: RetireDeps = { drain, say: writeErrorLine };
+
+/**
+ * Retire `worker`, then drain. Unbounded on purpose: in development a restart that waits for a
+ * long job is the cheaper failure than a side effect run twice, and the line it prints says how to
+ * stop waiting — Ctrl-C is a real drain, which binds the worker's teardown to the drain deadline
+ * and cuts off what is still running there. A retire that FAILS still drains: a restart left
+ * half-done is a child that stopped claiming and never exits.
+ */
+export async function retireThenDrain(
+  worker: RetiringWorker | null,
+  deps: RetireDeps = DEFAULT_DEPS,
+): Promise<void> {
+  try {
+    if (worker !== null) {
+      const { inFlight } = await worker.stats();
+      if (inFlight > 0) deps.say(msg('cli.dev.restartWaiting', { count: inFlight }));
+      await worker.stop('x dev restart');
+    }
+  } catch (error) {
+    logger.warn('cli.dev.restart-retire-failed', { error: renderThrowable(error) });
+  } finally {
+    await deps.drain('restart');
+  }
+}

package/src/dev-route-table.ts

@@ -4,21 +4,23 @@
 
 import type { RealtimeConfig } from '@ultimat3/core';
 import type { RateLimitStore, Route } from '@ultimat3/http';
-import { describeRoutes } from '@ultimat3/render';
+import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
+import { describePages } from '@ultimat3/render';
 import type { IsrController } from '@ultimat3/render/server';
+import type { ImageTransformDriver } from '@ultimat3/seo';
 import type { Storage } from '@ultimat3/storage';
 import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
 import { mountAppMcp } from './app-mcp';
 import type { DevDashboardInput } from './dev-dashboard';
 import { devDashboardRoutes } from './dev-dashboard';
-import { errorPageStyleSources } from './error-page-csp';
+import { errorPageStyleBodies } from './error-page-csp';
 import type { IslandBundle } from './island-bundle';
 import { islandHarnessRoutes } from './island-harness-route';
 import { islandRoutes } from './island-routes';
 import { loadIslandStates } from './island-states-load';
 import { loadNavigation, pageNavigation } from './page-navigation';
 import type { PageSpeculation } from './page-speculation';
-import { loadSpeculation, pageSpeculation } from './page-speculation';
+import { loadSpeculation, otherLocaleSegments, pageSpeculation } from './page-speculation';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { adminMountRoutes } from './runtime-admin';
@@ -33,6 +35,7 @@ import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
 import type { ThemeBoot } from './theme-boot';
 import { loadThemeMode, themeBoot } from './theme-boot';
+import { loadThemeBrand } from './theme-brand';
 
 export interface DevRouteTableInput {
   readonly root: string;
@@ -53,6 +56,12 @@ export interface DevRouteTableInput {
    * empty it: a stored render outlives the module that produced it.
    */
   readonly isr?: IsrController | undefined;
+  /**
+   * `apps/<app>/runtime.ts`'s `images` driver, handed to `/media` exactly as the container hands it
+   * (`serve-web.ts`): dropped here, dev answered every variant from the builtin pipeline and a
+   * CDN-backed transform was first exercised in production.
+   */
+  readonly images?: ImageTransformDriver | undefined;
 }
 
 export interface DevRouteTable {
@@ -61,8 +70,11 @@ export interface DevRouteTable {
   readonly theme: ThemeBoot;
   /** The speculation rules, admitted the same way — `undefined` when no document carries any. */
   readonly speculation: PageSpeculation | undefined;
-  /** The app's own error pages' inline styles, admitted the same way. */
-  readonly errorStyles: readonly string[];
+  /**
+   * Every inline `<style>` body these routes put in a document: the app's error pages' and its
+   * brand's (`theme-brand.ts`) — what `startRoles({ inlineStyles })` hashes into `style-src`.
+   */
+  readonly inlineStyles: readonly string[];
   /** Where the app's default MCP endpoint was mounted, or `null`. */
   readonly mcpPath: string | null;
   /** Every mounted MCP endpoint's path, default first — one per population the app serves. */
@@ -74,6 +86,8 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   // is mounted, and the 0kb baseline is not spent on a `<link>` to a file that does not exist.
   const pwa = await loadPwaArtifacts(input.root);
   const theme = themeBoot(await loadThemeMode(input.root));
+  // Read at boot, like the theme mode: a save to the theme module is applied on the next `x dev`.
+  const brand = await loadThemeBrand(input.root);
   // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
   const site = await loadSiteSettings(input.root);
   const origin = publicOrigin(input.env, site);
@@ -87,8 +101,12 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   const speculation = pageSpeculation({
     config: await loadSpeculation(input.root),
     client: declared.surfaces,
+    localeSegments: otherLocaleSegments(await appLocaleSet(input.root)),
   });
-  const errorStyles = await errorPageStyleSources(input.root);
+  const inlineStyles = [
+    ...(await errorPageStyleBodies(input.root)),
+    ...(brand === undefined ? [] : [brand.style]),
+  ];
   // Built once at boot and NOT rebuilt with the islands on a watcher tick: a service worker that
   // changes under a page it controls is the update path, and one per keystroke exercises it per save.
   const serviceWorker =
@@ -97,7 +115,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       : serviceWorkerArtifacts({
           pwa,
           buildId: input.buildId,
-          routes: describeRoutes(),
+          routes: describePages(),
           islands: input.islands(),
           styles: styleBundle(),
           scripts: [
@@ -126,6 +144,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     ...assetRoutes({
       root: input.root,
       storage: served,
+      ...(input.images === undefined ? {} : { images: input.images }),
       ...(pwa === undefined ? {} : { pwa }),
     }),
     ...storageRoutes({ storage: served }),
@@ -146,6 +165,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     ...islandHarnessRoutes({
       islands: () => input.islands(),
       states: () => loadIslandStates(input.root),
+      devUrl: () => input.dashboard.status().url,
     }),
     ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
     ...sync.routes,
@@ -157,6 +177,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     ...adminMountRoutes({
       buildId: input.buildId,
       themeHead: theme.head,
+      ...(brand === undefined ? {} : { brandHead: brand.head }),
       ...(origin === undefined ? {} : { origin }),
     }),
     ...appRoutes({
@@ -167,6 +188,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       persisted: sync.persisted,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       themeHead: theme.head,
+      ...(brand === undefined ? {} : { brandHead: brand.head }),
       ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
       ...(origin === undefined ? {} : { origin }),
       ...(pwa === undefined
@@ -179,7 +201,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     routes,
     theme,
     speculation,
-    errorStyles,
+    inlineStyles,
     mcpPath: mcpMount.path,
     mcpPaths: mcpMount.paths,
   };

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

@@ -6,9 +6,9 @@ import { isAbsolute, resolve } from 'node:path';
 import { setLogStream } from '@ultimat3/core';
 import { requireAppRoot, requireBunVersion } from './app-root';
 import { createHelpCommand } from './cmd-help';
-import { plannedCommandFor } from './cmd-planned';
+import { plannedCommandError, plannedCommandFor } from './cmd-planned';
 import type { CommandContext } from './command';
-import { CliNotImplementedError, UnknownCommandError } from './errors';
+import { UnknownCommandError } from './errors';
 import type { Runner } from './exec';
 import { exec } from './exec';
 import type { CommandResult } from './output';
@@ -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;
@@ -91,10 +95,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     // X_NOT_IMPLEMENTED with a runnable fix. Substituted here rather than in `parse.ts`, which is
     // pure and knows nothing about what a command means; the precedent is the help swap below.
     const planned = plannedCommandFor(commandFor(options.argv[0] ?? '')?.spec.name);
-    const failure =
-      planned === undefined
-        ? error
-        : new CliNotImplementedError({ feature: `x ${planned.name}`, fix: planned.fix });
+    const failure = planned === undefined ? error : plannedCommandError(planned);
     // `wantsJson`, not `includes('--json')`: a typo'd flag or a typo'd command is exactly the case
     // an agent hits while always passing `-j`, and the short form rendered prose it then parsed.
     const result = errorResult(planned?.name ?? 'x', failure);
@@ -125,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-app-url.ts

@@ -0,0 +1,39 @@
+// `x doctor`'s APP_URL rule, pure: a set APP_URL must be an origin a browser can match, and a
+// loopback one must name the port `x dev` serves on — OAuth's redirect, absolute links and the sync
+// node's admitted origin all read it, and a laptop origin on another port reaches another server.
+
+import { ERROR_DOCS_URL, renderFixShellArg } from '@ultimat3/core';
+import { isLoopbackHostname } from './loopback-host';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+import { syncOriginsFrom } from './sync-url';
+
+/**
+ * Unset is no finding: `x dev` serves without one, and a production build warns on its own
+ * (`originWarning`). A public origin is not judged against the dev port — that is the deploy's
+ * address, not this machine's. The parse is the sync boot's own (`syncOriginsFrom`), so doctor
+ * refuses exactly the values the boot would.
+ */
+export function appUrlFindings(raw: string | undefined, port: number): readonly Finding[] {
+  let origins: readonly string[];
+  try {
+    origins = syncOriginsFrom({ APP_URL: raw });
+  } catch (error) {
+    return [findingFrom(error)];
+  }
+  const origin = origins[0];
+  if (origin === undefined) return [];
+  const url = new URL(origin);
+  if (!isLoopbackHostname(url.hostname)) return [];
+  const declared = url.port === '' ? (url.protocol === 'https:' ? 443 : 80) : Number(url.port);
+  if (declared === port) return [];
+  const wanted = `${url.protocol}//${url.hostname}:${String(port)}`;
+  return [
+    {
+      code: 'X_APP_URL_PORT_MISMATCH',
+      cause: `APP_URL is ${origin}, but x dev serves this app on port ${String(port)} — OAuth redirects, absolute links and the sync origin would point at another server`,
+      fix: `export APP_URL=${renderFixShellArg(wanted, 'http://localhost:3000')}`,
+      docs: ERROR_DOCS_URL,
+    },
+  ];
+}