@ultimat3/cli 29.4.0 → 30.1.0

package/src/dev-lock.ts

@@ -17,7 +17,9 @@
 import { linkSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { stringField, UltimateError } from '@ultimat3/core';
-import { exec, type Runner } from './exec';
+import { reusedPid, startedOf } from './dev-lock-identity';
+import { type PortHolder, portHolder } from './dev-lock-port-holder';
+import { stealStale } from './dev-lock-steal';
 import { portPairAfter } from './flag-number';
 import { quoteArg } from './shell-quote';
 
@@ -30,8 +32,16 @@ export interface DevLock {
   readonly url: string;
   /** ISO 8601. Only ever printed — a stale lock is decided by the pid, never by the clock. */
   readonly startedAt: string;
+  /** The holder's OS start time (`dev-lock-identity.ts`): a reused pid does not match it. */
+  readonly started?: string;
 }
 
+export { netstatListener, portHolder, tasklistImage } from './dev-lock-port-holder';
+// Re-exported: the port refusal's holder, split out at the file ceiling.
+export type { PortHolder };
+// Re-exported: `cmd-stop.ts` asks the same question before it signals.
+export { reusedPid };
+
 export const lockPath = (stateDir: string): string => join(stateDir, DEV_LOCK_FILE);
 
 /**
@@ -47,6 +57,7 @@ export const parseLock = (raw: string): DevLock | null => {
       port: value.port,
       url: typeof value.url === 'string' ? value.url : `http://localhost:${value.port}`,
       startedAt: typeof value.startedAt === 'string' ? value.startedAt : '',
+      ...(typeof value.started === 'string' ? { started: value.started } : {}),
     };
   } catch {
     return null;
@@ -115,7 +126,8 @@ export class DevAlreadyRunningError extends UltimateError {
     super({
       code: 'X_DEV_ALREADY_RUNNING',
       cause: `pid ${input.lock.pid} is already running x dev on ${input.lock.url} and holds ${input.stateDir}${single}`,
-      fix: `use the one already running at ${input.lock.url}, or stop it: kill ${input.lock.pid}`,
+      // `x stop`, not `kill <pid>`: a kill returns before the drain ends and the next boot refuses.
+      fix: `use the one already running at ${input.lock.url}, or stop it: x stop --json`,
       meta: { pid: input.lock.pid, port: input.lock.port, stateDir: input.stateDir },
     });
   }
@@ -162,82 +174,6 @@ export class DevStateUnwritableError extends UltimateError {
   }
 }
 
-/** Whatever is listening, as far as the OS will say. Both fields absent when it will not say. */
-export interface PortHolder {
-  readonly pid?: number;
-  /** The process name, e.g. `bun`. Enough to recognise "that is my other project". */
-  readonly command?: string;
-}
-
-/**
- * Who holds the port. `ss` first because it is present on every Linux box the framework targets and
- * needs no elevation for your own processes; `lsof` is the macOS answer; `netstat -ano` plus
- * `tasklist` the Windows one.
- *
- * Through `exec.ts`, like every other subprocess the CLI runs, so a test injects a fake `Runner`
- * rather than racing a real socket.
- *
- * EVERY PROBE IS CAUGHT SEPARATELY. `exec` refuses a missing program with `X_CLI_UNEXPECTED`, and
- * letting that escape would mean a box without `ss` gets the CLI's catch-all instead of
- * `X_PORT_IN_USE` — the exact substitution this module exists to end. A missing `ss` must fall
- * through to `lsof`, and a box with none still gets the refusal, just without a pid in it.
- */
-export const portHolder = async (port: number, runner: Runner = exec): Promise<PortHolder> => {
-  const probe = async (command: readonly string[]): Promise<string> => {
-    try {
-      const result = await runner(command, { cwd: process.cwd() });
-      return result.stdout;
-    } catch {
-      return '';
-    }
-  };
-
-  const parsed = /users:\(\("([^"]+)",pid=(\d+)/.exec(
-    await probe(['ss', '-lptnH', `sport = :${port}`]),
-  );
-  const name = parsed?.[1];
-  if (parsed !== null && name !== undefined) return { command: name, pid: Number(parsed[2]) };
-
-  const lines = (
-    await probe(['lsof', '-nP', `-iTCP:${String(port)}`, '-sTCP:LISTEN', '-Fpc'])
-  ).split('\n');
-  const pid = lines.find((line) => line.startsWith('p'))?.slice(1);
-  const command = lines.find((line) => line.startsWith('c'))?.slice(1);
-  if (pid !== undefined && /^\d+$/.test(pid)) {
-    return command === undefined ? { pid: Number(pid) } : { command, pid: Number(pid) };
-  }
-
-  // Windows has neither: `netstat -ano` names the listening pid, `tasklist` its image.
-  const listener = netstatListener(await probe(['netstat', '-ano', '-p', 'TCP']), port);
-  if (listener === undefined) return {};
-  const image = tasklistImage(
-    await probe(['tasklist', '/FI', `PID eq ${String(listener)}`, '/FO', 'CSV', '/NH']),
-  );
-  return image === undefined ? { pid: listener } : { command: image, pid: listener };
-};
-
-/**
- * The pid `netstat -ano` reports LISTENING on `port`, any local address: `TCP 127.0.0.1:3000
- * 0.0.0.0:0 LISTENING 4242`, and `[::1]:3000` for IPv6. The state column is the word Windows
- * prints in English on every locale this was read on; an unrecognised line is skipped.
- */
-export function netstatListener(text: string, port: number): number | undefined {
-  for (const line of text.split(/\r?\n/)) {
-    const [proto, local, , state, pid] = line.trim().split(/\s+/);
-    if (proto !== 'TCP' || state !== 'LISTENING' || pid === undefined || !/^\d+$/.test(pid)) {
-      continue;
-    }
-    if (local?.endsWith(`:${String(port)}`) === true) return Number(pid);
-  }
-  return undefined;
-}
-
-/** The image name off `tasklist /FO CSV /NH`'s one row — `"bun.exe","4242",…` — or `undefined`. */
-export function tasklistImage(text: string): string | undefined {
-  const name = /^"([^"]+)","\d+"/m.exec(text.trim())?.[1];
-  return name === undefined || name === '' ? undefined : name;
-}
-
 /**
  * The port is bound by something that is not us. Named separately from the lock case because the
  * remedy is different: a stranger's port is worked around with `--port`, while a second `x dev` on
@@ -333,11 +269,23 @@ function claimExclusive(stateDir: string, path: string, lock: DevLock): boolean
   }
 }
 
+/**
+ * The lock's bytes right now, or `null` when there is no file to read. Total: a rival's steal may
+ * remove the file between `exists()` and the read, and that is "absent", never a bare `ENOENT`.
+ */
+const readRaw = async (path: string): Promise<string | null> => {
+  const file = Bun.file(path);
+  try {
+    return (await file.exists()) ? await file.text() : null;
+  } catch {
+    return null;
+  }
+};
+
 /** Whatever is on disk right now, or `null` if it is absent or half-written. */
 const readLock = async (path: string): Promise<DevLock | null> => {
-  const file = Bun.file(path);
-  if (!(await file.exists())) return null;
-  return parseLock(await file.text());
+  const raw = await readRaw(path);
+  return raw === null ? null : parseLock(raw);
 };
 
 export interface PreflightInput {
@@ -363,6 +311,62 @@ export interface PreflightResult {
   release(): void;
 }
 
+/** Rounds of claim-or-clear before the lock is reported unreadable, and the wait on a busy steal. */
+const CLAIM_ROUNDS = 200;
+const STEAL_BUSY_MS = 5;
+
+/**
+ * The claim, clearing a stale lock on the way: `true` when one was cleared. Each round claims, or
+ * reads the holder and refuses a live one, or clears a stale one under `dev.lock.steal`
+ * (`stealStale`) and goes round again — so a lock that changed hands mid-round is judged afresh,
+ * never deleted by path. A rival's fresh claim then reads as live and is refused; an unlink after
+ * an unguarded read deleted it, and two boots shared one `.x/pgdata`.
+ */
+async function claimOrClearStale(
+  input: PreflightInput,
+  path: string,
+  mine: DevLock,
+  alive: (pid: number) => boolean,
+): Promise<boolean> {
+  let clearedStale = false;
+  let held: DevLock | null = null;
+  for (let round = 0; round < CLAIM_ROUNDS; round += 1) {
+    if (claimExclusive(input.stateDir, path, mine)) return clearedStale;
+    const raw = await readRaw(path);
+    const now = raw === null ? null : parseLock(raw);
+    // `held` keeps the last identity read: a half-written file parses as `null` for microseconds.
+    held = now ?? held;
+    if (now !== null && alive(now.pid) && !(await reusedPid(now))) {
+      throw new DevAlreadyRunningError({
+        lock: now,
+        stateDir: input.stateDir,
+        ...(input.embeddedDb === undefined ? {} : { embeddedDb: input.embeddedDb }),
+      });
+    }
+    // Stale: a hard kill, or a file nothing here wrote. No bytes read (a directory at the lock's
+    // path, say) leaves nothing to compare, so nothing is removed and the claim decides alone.
+    clearedStale = true;
+    if (raw === null) continue;
+    const outcome = stealStale({
+      path,
+      judged: raw,
+      claim: (guard) => claimExclusive(input.stateDir, guard, mine),
+      alive: isProcessAlive,
+    });
+    if (outcome === 'busy') await Bun.sleep(STEAL_BUSY_MS);
+  }
+  // NEVER `mine`, which is what it fell back to: with an unparseable lock that could not be
+  // cleared, both reads answered `null` and the refusal named THIS pid as the holder — `kill
+  // <self>` as the remedy for a file nobody could read.
+  const holder = (await readLock(path)) ?? held;
+  if (holder === null) throw new DevLockUnreadableError({ path, stateDir: input.stateDir });
+  throw new DevAlreadyRunningError({
+    lock: holder,
+    stateDir: input.stateDir,
+    ...(input.embeddedDb === undefined ? {} : { embeddedDb: input.embeddedDb }),
+  });
+}
+
 /**
  * Run before anything boots, and it CLAIMS: it returns holding the directory, never having merely
  * looked at it.
@@ -374,8 +378,8 @@ export interface PreflightResult {
  * records. The claim closes the window it names.
  *
  * The stale path still exists and is still normal (a hard kill leaves a lock behind): the file is
- * removed and the claim retried once. A retry that ALSO loses is another boot that claimed the
- * cleared slot in that instant, which is a refusal and not a third boot.
+ * removed (`claimOrClearStale`) and the claim retried. A retry that ALSO loses is another boot
+ * that claimed the cleared slot in that instant, which is a refusal and not a third boot.
  */
 export const preflight = async (input: PreflightInput): Promise<PreflightResult> => {
   const alive = input.alive ?? isProcessAlive;
@@ -396,43 +400,9 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
     // is what the refusal prints, and it is the address the boot is about to ask for.
     url: `http://${input.hostname}:${input.port}`,
     startedAt: new Date().toISOString(),
+    ...(await startedOf(process.pid)),
   };
-  let clearedStale = false;
-
-  if (!claimExclusive(input.stateDir, path, mine)) {
-    const held = await readLock(path);
-    if (held !== null && alive(held.pid)) {
-      throw new DevAlreadyRunningError({
-        lock: held,
-        stateDir: input.stateDir,
-        ...(input.embeddedDb === undefined ? {} : { embeddedDb: input.embeddedDb }),
-      });
-    }
-    // Stale: a hard kill, or a file nothing here wrote. Removing it is what makes the next boot
-    // work, and `unlinkSync` because a lock that outlives its own cleanup is the bug being fixed.
-    try {
-      unlinkSync(path);
-    } catch {
-      // Already gone, or not ours to remove. The claim below is what decides.
-    }
-    clearedStale = true;
-    if (!claimExclusive(input.stateDir, path, mine)) {
-      // Lost the race for the slot we just cleared. `held` is the best identity available — a
-      // half-written file parses as `null` for microseconds — and refusing on a stale pid beats
-      // the alternative, which is two processes writing one single-writer data directory.
-      //
-      // NEVER `mine`, which is what it fell back to: with an unparseable lock and a failed
-      // `unlinkSync`, both reads answer `null` and the refusal named THIS pid as the holder —
-      // `kill <self>` as the remedy for a file nobody could read.
-      const holder = (await readLock(path)) ?? held;
-      if (holder === null) throw new DevLockUnreadableError({ path, stateDir: input.stateDir });
-      throw new DevAlreadyRunningError({
-        lock: holder,
-        stateDir: input.stateDir,
-        ...(input.embeddedDb === undefined ? {} : { embeddedDb: input.embeddedDb }),
-      });
-    }
-  }
+  const clearedStale = await claimOrClearStale(input, path, mine, alive);
 
   if (bound(input.port, input.hostname)) {
     // Released before the throw: the remedy this refusal prints is `x dev --port <n>`, and a claim
@@ -455,11 +425,13 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
  * with the address the server actually bound, which is the one field the preflight could not know.
  */
 export const writeLock = async (stateDir: string, lock: DevLock): Promise<void> => {
+  const stamped: DevLock =
+    lock.started === undefined ? { ...lock, ...(await startedOf(lock.pid)) } : lock;
   // Staged and renamed over the claim, never rewritten in place: a truncate-then-write leaves an
   // empty lock for an instant, and a preflight reading it then would clear a live claim as stale.
   const path = lockPath(stateDir);
   const staged = stagingPath(path);
-  writeFileSync(staged, lockText(lock));
+  writeFileSync(staged, lockText(stamped));
   renameSync(staged, path);
 };
 

package/src/dev-mail-templates.ts

@@ -0,0 +1,51 @@
+// The `/_x` mail panel's templates source: every registered mail, its declared `preview` rendered
+// in each of the app's locales by `@ultimat3/mail`'s `previewMail` — the same render
+// `x mail preview` prints. Dates in a preview render in UTC, named: there is no ambient zone.
+
+import type { MailTemplateFact, MailTemplatePreviewFact } from '@ultimat3/admin/dev';
+import { InternalError, renderFixShellArg, renderThrowable, stringField } from '@ultimat3/core';
+import { mailFor, previewMail, registeredMailIds } from '@ultimat3/mail';
+
+/** The zone a preview's dates render in: a sample has no reader, so no reader's zone. */
+const PREVIEW_ZONE = 'UTC';
+
+export function mailTemplateFacts(locales: readonly string[]): readonly MailTemplateFact[] {
+  return registeredMailIds().map((id) => {
+    const hasPreview = mailFor(id)?.preview !== undefined;
+    return {
+      id,
+      hasPreview,
+      previews: hasPreview ? locales.map((locale) => previewIn(id, locale)) : [],
+    };
+  });
+}
+
+/**
+ * A preview function's data is parsed at each render, so one locale's can be refused while the
+ * others render: that refusal is this cell's, shown with its fix, never the whole panel's.
+ */
+function previewIn(id: string, locale: string): MailTemplatePreviewFact {
+  try {
+    const preview = previewMail(id, { locale, tz: PREVIEW_ZONE });
+    return {
+      locale,
+      ok: true,
+      subject: preview.subject,
+      html: preview.html,
+      text: preview.text,
+      missing: preview.misses.map((miss) => miss.key),
+    };
+  } catch (error) {
+    return {
+      locale,
+      ok: false,
+      error: {
+        code: stringField(error, 'code') ?? InternalError.code,
+        cause: stringField(error, 'cause') ?? renderThrowable(error),
+        fix:
+          stringField(error, 'fix') ??
+          `x mail preview ${renderFixShellArg(id, '<mail-id>')} --locale ${renderFixShellArg(locale, '<locale>')} --json`,
+      },
+    };
+  }
+}

package/src/dev-rebuild.ts

@@ -3,6 +3,7 @@
 // supervisor as a restart. Coalesced, so a tick arriving mid-build is one trailing rebuild.
 
 import type { Manifest } from '@ultimat3/manifest';
+import { beginDeviceSocketGeneration } from '@ultimat3/realtime/server';
 import type { IsrController } from '@ultimat3/render/server';
 import { appManifest } from './app-manifest';
 import type { StalePin } from './app-reload-graph';
@@ -42,17 +43,36 @@ export interface DevRebuildOptions {
   readonly onRestart?: (pins: readonly StalePin[]) => void;
 }
 
-/** The watcher's `onChange`: rebuild `state` for the saved `file`, never rejecting. */
+/**
+ * A save that declared a `deviceSocket()` path the listener did not bind: Bun's websocket paths
+ * are fixed when it starts, so only a new process serves it — `restartFinding`'s code and fix.
+ */
+export function unservedDeviceFinding(path: string, file: string): Finding {
+  return {
+    code: 'X_DEV_RESTART_REQUIRED',
+    cause: `deviceSocket('${path}') was declared after x dev bound its listener, which serves only the device paths it booted with`,
+    fix: 'x stop && x dev   # the listener binds its websocket paths once, at boot',
+    at: file,
+  };
+}
+
+/**
+ * The watcher's `onChange`: rebuild `state` for the saved `file`, never rejecting. `refreshDevices`
+ * is the running roles' (`RunningRoles.refreshDevices`): the rescan is a new device generation, so
+ * a re-evaluated `deviceSocket()` replaces its path's old value instead of colliding with it.
+ */
 export function devRebuilder(
   options: DevRebuildOptions,
   state: DevState,
   isr: IsrController,
+  refreshDevices: () => Promise<readonly string[]>,
 ): ReloadTrigger {
   // One rebuild at a time, and the last save wins: a tick arriving mid-build coalesces into ONE
   // trailing rebuild instead of racing the one in flight for `state.manifest` and `state.islands`.
   return coalesceReloads(
     async (file) => {
       const started = performance.now();
+      beginDeviceSocketGeneration();
       const [{ manifest, findings }, islands] = await Promise.all([
         appManifest(options.root),
         buildIslands(options.root),
@@ -60,14 +80,18 @@ export function devRebuilder(
       state.manifest = manifest;
       state.appFindings = findings;
       state.islands = islands;
+      const unserved = await refreshDevices();
       for (const path of isr.store().paths()) isr.store().delete(path);
       state.reloads += 1;
       // Read on EVERY rebuild, so a pin one save reached is never reported against the next save.
       const pins = takeStalePins();
+      const [device] = unserved;
       state.reloadFinding =
         pins.length > 0 && options.onRestart === undefined
           ? restartFinding(options.root, pins)
-          : undefined;
+          : device === undefined
+            ? undefined
+            : unservedDeviceFinding(device, file);
       if (pins.length > 0 && options.onRestart !== undefined) options.onRestart(pins);
       else options.onReload?.(file, Math.round(performance.now() - started));
     },

package/src/dev-route-table.ts

@@ -11,7 +11,10 @@ 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 { loadAppConfig } from './app-config-load';
 import { mountAppMcp } from './app-mcp';
+import { clientErrorsSurface } from './client-errors-routes';
+import { clientScriptHeads, clientVitalsSurface } from './client-vitals-route';
 import type { DevDashboardInput } from './dev-dashboard';
 import { devDashboardRoutes } from './dev-dashboard';
 import { errorPageStyleBodies } from './error-page-csp';
@@ -37,6 +40,7 @@ import { serviceWorkerRoutes } from './sw-routes';
 import type { ThemeBoot } from './theme-boot';
 import { loadThemeMode, themeBoot } from './theme-boot';
 import { loadThemeBrand } from './theme-brand';
+import { type ZoneBoot, zoneBoot } from './zone-boot';
 
 export interface DevRouteTableInput {
   readonly root: string;
@@ -71,6 +75,8 @@ export interface DevRouteTable {
   readonly theme: ThemeBoot;
   /** The speculation rules, admitted the same way — `undefined` when no document carries any. */
   readonly speculation: PageSpeculation | undefined;
+  /** The zone script (`time.detect`), admitted the same way — `undefined` when the app left it off. */
+  readonly zone: ZoneBoot | undefined;
   /**
    * 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`.
@@ -138,6 +144,13 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   const mcpMount = await mountAppMcp(input.root);
   // `serve-boot.ts`'s answer: the app's declared disks when it has any, read per request.
   const served = servedStorage(input.storage);
+  // `clientErrors.enabled` or nothing: off, the route is a 404 and no document names the script.
+  const appConfig = await loadAppConfig(input.root);
+  const reporting = appConfig?.clientErrors;
+  const zone = zoneBoot(appConfig?.time);
+  const clientErrors = clientErrorsSurface(reporting, input.buildId);
+  // Real-user timings: their own switch (`clientErrors.vitals.enabled`), the same door.
+  const vitals = clientVitalsSurface(reporting?.vitals);
   const routes: readonly Route[] = [
     ...devDashboardRoutes(input.dashboard),
     // The same API table the container serves: a read that answers here and 404s in production
@@ -156,6 +169,8 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       ...(pwa === undefined ? {} : { pwa }),
     }),
     ...storageRoutes({ storage: served }),
+    ...(clientErrors?.routes ?? []),
+    ...(vitals?.routes ?? []),
     // The chunks the documents below name. Mounted before the app's routes for the reason
     // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
     ...islandRoutes(() => input.islands()),
@@ -205,6 +220,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       ...(pwa === undefined
         ? {}
         : { pwaHead: (locale: string) => pwa.headFor(locale) + (serviceWorker?.head ?? '') }),
+      ...clientScriptHeads(clientErrors, vitals, zone),
     }),
   ];
 
@@ -212,6 +228,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     routes,
     theme,
     speculation,
+    zone,
     inlineStyles,
     mcpPath: mcpMount.path,
     mcpPaths: mcpMount.paths,

package/src/dev-supervisor.ts

@@ -7,7 +7,7 @@
 
 import type { StalePin } from './app-reload-graph';
 import { devSpec } from './cmd-dev-spec';
-import type { DevChildGone, DevDrainMessage } from './dev-child-watch';
+import type { DevChildLeaving, DevDrainMessage } from './dev-child-watch';
 import {
   DEV_SUPERVISOR_PID_ENV,
   devHardExitMs,
@@ -267,7 +267,7 @@ export function childRestart(
   if (env[DEV_CHILD_ENV] !== '1') {
     return { options: {}, exit: () => undefined, adopt: () => undefined };
   }
-  let leaving: 'restart' | DevChildGone | undefined;
+  let leaving: 'restart' | DevChildLeaving | undefined;
   let worker: RetiringWorker | null = null;
   let restarting = false;
   const watched =
@@ -279,6 +279,9 @@ export function childRestart(
   return {
     options: {
       onRestart: (pins) => {
+        // Already stopping for a signal (`x stop`, Ctrl-C) or a gone supervisor or root: a save
+        // landing during that drain must not respawn a child its operator asked to end.
+        if (leaving !== undefined && leaving !== 'restart') return;
         writeErrorLine(msg('cli.dev.restart', { reason: restartReason(root, pins) }));
         leaving ??= 'restart';
         watched?.stopping(DEV_RESTART_EXIT_CODE);

package/src/dev-watch-tree.ts

@@ -47,14 +47,17 @@ export interface WatchTree {
 const DEFAULT_DEBOUNCE_MS = 30;
 
 /**
- * Every directory under `root` an event could be a source change in, `''` first. Ignored
- * directories are not descended, so a `node_modules` tree costs one `readdir` and nothing else.
- * A symlinked directory is deliberately not followed: `Dirent.isDirectory()` is false for one, and
- * a workspace symlink pointing back into the checkout would otherwise be walked twice.
+ * Every directory at or under `from` (`''`, the app root, by default) an event could be a source
+ * change in, `from` first, every path root-relative. Ignored directories are not descended, so a
+ * `node_modules` tree costs one `readdir` and nothing else. A symlinked directory is deliberately
+ * not followed: `Dirent.isDirectory()` is false for one, and a workspace symlink pointing back into
+ * the checkout would otherwise be walked twice. Root-relative because the ignore set is the ROOT's
+ * `.gitignore`: a walk rooted at a new directory asked an anchored `/build` about `build`, and hid
+ * `apps/web/build/` when `apps/web` appeared after boot.
  */
-export function admittedDirectories(root: string, ignore: DevIgnore): readonly string[] {
-  const admitted: string[] = [''];
-  const pending: string[] = [''];
+export function admittedDirectories(root: string, ignore: DevIgnore, from = ''): readonly string[] {
+  const admitted: string[] = [from];
+  const pending: string[] = [from];
   for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
     for (const entry of childrenOf(join(root, next))) {
       if (!entry.isDirectory()) continue;
@@ -156,9 +159,7 @@ export function watchTree(options: WatchTreeOptions): WatchTree {
 
   /** The admitted directories at or under `directory`, discovered rather than assumed. */
   const subtree = (directory: string): readonly string[] =>
-    admittedDirectories(join(root, directory), ignore).map((found) =>
-      found === '' ? directory : `${directory}/${found}`,
-    );
+    admittedDirectories(root, ignore, directory);
 
   /** The whole set, re-derived: a directory the author just ignored gives its descriptor back. */
   const reconcile = (): void => {

package/src/dev-watch.ts

@@ -30,7 +30,7 @@ import { pathSegments } from './path-segments';
  * - `node_modules` — an install, not an edit. `x dev` cannot reload for a dependency change: the
  *   modules are already in this process's cache.
  * - `.personal` — an app's uncommitted local state, written by scripts while the dev server runs.
- * - `.claude` — agent scratch, session logs and worktrees. ai-maxxing keeps two entire copies of
+ * - `.claude` — agent scratch, session logs and worktrees. One adopter keeps two entire copies of
  *   the app under `.claude/worktrees/`, so a second agent's edit rebuilt the first agent's islands.
  *
  * `dist` and `coverage` were here and are deliberately not: both are ordinary build output that

package/src/dispatch.ts

@@ -2,7 +2,9 @@
 // whether it is printed as text or JSON and what the process exits with. Errors take the same
 // path as results, so a failure is machine-readable exactly like a success.
 
-import { isAbsolute, resolve } from 'node:path';
+// why: a synchronous bin probe at the one place a result is rendered; Bun has no path helpers.
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { setLogStream } from '@ultimat3/core';
 import { requireAppRoot, requireBunVersion } from './app-root';
 import { createHelpCommand } from './cmd-help';
@@ -13,6 +15,7 @@ import type { Runner } from './exec';
 import { exec } from './exec';
 import type { CommandResult } from './output';
 import { exitCodeFor, findingFrom, render } from './output';
+import type { ReaderOptions } from './output-findings';
 import type { ParsedArgs } from './parse';
 import { parseArgs, wantsJson } from './parse';
 import { commandFor, SPECS } from './registry';
@@ -56,11 +59,29 @@ export const sinkFor = (
 ): ((line: string) => void) =>
   result.stream === 'stderr' ? (options.writeError ?? options.write) : options.write;
 
+/** `x` where Bun links it: on POSIX, and the shim it writes on Windows. */
+const LOCAL_BINS = ['x', 'x.exe'];
+
 const resolveCwd = (cwd: string, flag: string | undefined): string => {
   if (flag === undefined) return cwd;
   return isAbsolute(flag) ? flag : resolve(cwd, flag);
 };
 
+/**
+ * Whether this reader's fixes should name `bunx x`. Only where it resolves to the app's own CLI: with
+ * no local bin, `bunx x` fetches whatever npm calls `x`, and a global `x` is what ran anyway. An
+ * entry point with its own name (`invocation`, `create-ultimate`) already names its runner.
+ */
+const readerFor = (cwd: string, invocation: string | undefined): ReaderOptions => {
+  if (invocation !== undefined) return {};
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    if (LOCAL_BINS.some((bin) => existsSync(join(dir, 'node_modules', '.bin', bin)))) {
+      return { bunxRunner: true };
+    }
+    if (dirname(dir) === dir) return {};
+  }
+};
+
 const errorResult = (command: string, error: unknown): CommandResult => ({
   ok: false,
   command,
@@ -74,13 +95,14 @@ const errorResult = (command: string, error: unknown): CommandResult => ({
  * end without terminating the test runner.
  */
 export async function dispatch(options: DispatchOptions): Promise<number> {
+  const earlyReader = readerFor(options.cwd, options.invocation);
   // Its own branch, ahead of the parse: an unsupported Bun is a fact about the environment and
   // outranks anything argv says, including the planned pre-empt below.
   try {
     requireBunVersion(options.bunVersion);
   } catch (error) {
     const failure = errorResult('x', error);
-    sinkFor(failure, options)(render(failure, wantsJson(options.argv)));
+    sinkFor(failure, options)(render(failure, wantsJson(options.argv), false, earlyReader));
     return 1;
   }
 
@@ -99,7 +121,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     // `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);
-    sinkFor(result, options)(render(result, wantsJson(options.argv)));
+    sinkFor(result, options)(render(result, wantsJson(options.argv), false, earlyReader));
     return 1;
   }
 
@@ -112,7 +134,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
         known: SPECS.map((spec) => spec.name),
       }),
     );
-    sinkFor(result, options)(render(result, args.json));
+    sinkFor(result, options)(render(result, args.json, false, earlyReader));
     return 1;
   }
 
@@ -134,6 +156,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     options.env,
     await rootEnvChanges({ cwd, processCwd: options.cwd, env: options.env }),
   );
+  const reader = readerFor(cwd, options.invocation);
   const ctx: CommandContext = {
     args: helpArgs,
     cwd,
@@ -164,7 +187,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     // command, which declares nothing: usage for a command must be readable from anywhere.
     if (target.spec.requiresApp === true) requireAppRoot(target.spec.name, ctx.cwd);
     const result = await target.run(ctx);
-    sinkFor(result, options)(render(result, args.json, args.flags.get('verbose') === true));
+    sinkFor(result, options)(render(result, args.json, args.flags.get('verbose') === true, reader));
     // `x dev` and `x mcp serve --transport http` are still listening here: report first, so the
     // url is on stdout the moment it is reachable, then stay in the process until the drain that
     // stops them. Without this the exit code below is what takes the server down.
@@ -172,7 +195,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     return exitCodeFor(result);
   } catch (error) {
     const result = errorResult(args.command, error);
-    sinkFor(result, options)(render(result, args.json));
+    sinkFor(result, options)(render(result, args.json, false, reader));
     return 1;
   }
 }