@ultimat3/cli 11.2.0 → 12.0.0

package/src/cmd-shot-island.ts

@@ -27,6 +27,7 @@ import { SHOT_DIR } from './shot-server';
 export function islandBrowser(input: {
   readonly root: string;
   readonly executablePath?: string | undefined;
+  readonly cdpUrl?: string | undefined;
 }): IslandBrowser {
   const byViewport = new Map<string, Promise<ScrapeDriver>>();
   return (viewport: IslandViewport): Promise<ScrapeDriver> => {
@@ -36,6 +37,7 @@ export function islandBrowser(input: {
     const started = appBrowser({
       root: input.root,
       ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
+      ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
       viewport: { width: viewport.width, height: viewport.height },
     });
     byViewport.set(key, started);
@@ -86,6 +88,8 @@ export interface IslandShotInput {
   readonly timeoutMs: number;
   readonly extraHosts?: string | undefined;
   readonly executablePath?: string | undefined;
+  /** A provider's session, or a sidecar. One attach per viewport, memoised like a launch. */
+  readonly cdpUrl?: string | undefined;
   readonly boot: () => Promise<ShotServer>;
   /** Injected by a test, so the whole path is proved on a machine with no Chrome. */
   readonly driver?: IslandBrowser | undefined;
@@ -124,6 +128,7 @@ export async function islandShot(input: IslandShotInput): Promise<IslandArtifact
       islandBrowser({
         root: input.root,
         ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
+        ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
       }),
     boot: input.boot,
     settleMs: input.settleMs,

package/src/cmd-shot.ts

@@ -11,7 +11,7 @@ import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
 import type { ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
-import { appBrowser, browserBinaryExists, executablePathFrom } from './browser-launcher';
+import { appBrowser } from './browser-launcher';
 import { islandShot, islandShotResult, refuseRouteWithIsland } from './cmd-shot-island';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, MissingPositionalError } from './errors';
@@ -19,6 +19,7 @@ import { intFlagOr, PORT_RANGE } from './flag-number';
 import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
+import { shotBrowserChoice } from './shot-browser';
 import type { BootDevServer, ShotServer } from './shot-server';
 import { allowHostsFrom, devServerFor, SHOT_DIR } from './shot-server';
 import { SETTLE_POLL_MS, settleIslands } from './shot-settle';
@@ -285,6 +286,11 @@ export const shotCommand: CliCommand = {
       { name: 'settle', type: 'string', summary: 'ms to wait after load before capturing' },
       { name: 'timeout', type: 'string', summary: 'ms one navigation may take' },
       { name: 'browser', type: 'string', summary: 'browser executable puppeteer-core launches' },
+      {
+        name: 'cdp-url',
+        type: 'string',
+        summary: 'attach to a browser somebody else is running (a provider session, a sidecar)',
+      },
       { name: 'allow-hosts', type: 'string', summary: 'extra hosts the page may request' },
       // A FLAG on `x shot` and never a second command: photographing a route and photographing a
       // component are one job with two subjects, and a parallel command would be the second path
@@ -314,15 +320,14 @@ export const shotCommand: CliCommand = {
     const port = intFlag(ctx.args, 'port', PORT_RANGE.min, DEFAULT_PORT, PORT_RANGE.max);
     const settleMs = intFlag(ctx.args, 'settle', 0, DEFAULT_SETTLE_MS);
     const timeoutMs = intFlag(ctx.args, 'timeout', 1, DEFAULT_PAGE_TIMEOUT_MS);
-    const executablePath = executablePathFrom(flagString(ctx.args, 'browser'), ctx.env);
-    if (executablePath !== undefined && !browserBinaryExists(executablePath)) {
-      throw new BadFlagError({
-        flag: 'browser',
-        command: 'shot',
-        reason: `no executable at "${executablePath}"`,
-        fix: 'x shot / --browser /usr/bin/chromium',
-      });
-    }
+    // Which browser this run gets — start one here, or attach to one somebody else is running.
+    // Decided by `shot-browser.ts` over plain inputs, and decided HERE, before a dev server or a
+    // provider session exists to pay for a typo.
+    const { cdpUrl, executablePath } = shotBrowserChoice({
+      cdpFlag: flagString(ctx.args, 'cdp-url'),
+      browserFlag: flagString(ctx.args, 'browser'),
+      env: ctx.env,
+    });
     const out = flagString(ctx.args, 'out');
     const boot = (): Promise<ShotServer> => devServerFor(root, ctx.env, port);
     if (island !== undefined && island !== '') {
@@ -337,6 +342,7 @@ export const shotCommand: CliCommand = {
           settleMs,
           timeoutMs,
           ...(executablePath === undefined ? {} : { executablePath }),
+          ...(cdpUrl === undefined ? {} : { cdpUrl }),
           ...(flagString(ctx.args, 'allow-hosts') === undefined
             ? {}
             : { extraHosts: flagString(ctx.args, 'allow-hosts') }),
@@ -349,6 +355,7 @@ export const shotCommand: CliCommand = {
     const driver = await appBrowser({
       root,
       ...(executablePath === undefined ? {} : { executablePath }),
+      ...(cdpUrl === undefined ? {} : { cdpUrl }),
     });
     return shotResult(
       await runShot({

package/src/compile-externals.ts

@@ -8,10 +8,13 @@
  * `package.json` inside a `catch` — and both sit in `loadCtsDefault`, which only runs while Babel
  * loads a `.cts` CONFIG FILE. `solid-loader.ts` passes `babelrc: false, configFile: false`, so no
  * config file is ever loaded and neither line is reachable at run time. The bundler walks them
- * anyway, and that is the whole failure: Bun 1.3 (what CI pins and what `docker/Dockerfile` builds
- * on) refuses the build with `Could not resolve: "@babel/preset-typescript/package.json"`, while
- * Bun 1.4 bundles the unresolvable `require` as a runtime throw — so one tree compiled on a laptop
- * and did not in CI.
+ * anyway, and that is the whole failure: Bun 1.3 refuses the build with
+ * `Could not resolve: "@babel/preset-typescript/package.json"`, while Bun 1.4 bundles the
+ * unresolvable `require` as a runtime throw — so one tree compiled on a laptop and did not in CI.
+ * That skew is closed `As of 2026-08-20`: CI pins `1.4.x` (`.github/actions/setup/action.yml`),
+ * `docker/Dockerfile` builds on `oven/bun:1.4-slim` and `scripts/setup.ts` holds contributors to
+ * 1.4.0, so every builder now takes the second branch. The external stays regardless — it is the
+ * `--compile` graph that must not reach an unresolvable `require`, on either Bun.
  *
  * Marking the dead specifier external rather than the two live ones: `serve.ts` calls
  * `buildIslands` on every boot, unconditionally, so a binary with `@babel/core` external is a

package/src/dev-queue.ts

@@ -8,6 +8,7 @@ import {
   type PostgresIdempotencyStore,
   postgresIdempotencyStore,
   resetIdempotency,
+  SQL_AUDIT_TABLE,
   SQL_IDEMPOTENCY_TABLE,
   setIdempotencyStore,
 } from '@ultimat3/action';
@@ -36,12 +37,19 @@ import {
   setJobDriver,
   setJobsFacade,
 } from '@ultimat3/jobs';
+import { attachReplica, type ReplicaEnv, replicaUrlFor } from './dev-replica';
 import type { DevServices } from './dev-services';
 import type { RuntimeOverrides } from './runtime-overrides';
 
 /** Both embedded and external clients boot lazily and close explicitly. */
 export type DevDbClient = PgliteClient | PostgresClient;
 
+/** The primary this boot owns, plus the standby pool it opened — `stop()` closes both. */
+interface StartedDb {
+  readonly client: DevDbClient;
+  readonly replica: PostgresClient | undefined;
+}
+
 export interface RunningQueue {
   readonly db: DevDbClient;
   readonly jobs: JobDriver;
@@ -62,7 +70,20 @@ export interface RunningQueue {
   stop(): Promise<void>;
 }
 
-function startDb(services: DevServices): DevDbClient {
+/**
+ * The boot's own client, and the AMBIENT one, which are deliberately not always the same object.
+ *
+ * `setDbClient` receives the replicated pair when `DATABASE_REPLICA_URL` names a standby, so an
+ * app repository reading through `db()` inside an open `withReplicaReads` scope can be served by
+ * it. Everything this file does itself — `applySchema`, the `PgExecutor` behind the queue, the
+ * outbox, `ping()`, `close()` — keeps the PRIMARY: DDL, a claim and a migration are writes by
+ * definition, and routing one would be `25006` at best.
+ *
+ * Before this, `defaultClient()` was the only composer of a replicated pair in the framework and
+ * it runs only from `baseClient()` — the client an app installed NONE for. This line installs one,
+ * so `DATABASE_REPLICA_URL` was read by no booted process at all.
+ */
+function startDb(services: DevServices, env: ReplicaEnv = process.env): StartedDb {
   const binding = services.db;
   const client =
     binding.mode === 'embedded'
@@ -70,8 +91,9 @@ function startDb(services: DevServices): DevDbClient {
         // here is a second thing to keep right when the form changes.
         createPgliteClient({ dataDir: pgliteDataDir(binding.url) })
       : createPostgresClient({ url: binding.url });
-  setDbClient(client);
-  return client;
+  const attached = attachReplica(client, replicaUrlFor(binding, env));
+  setDbClient(attached.client);
+  return { client, replica: attached.replica };
 }
 
 /**
@@ -111,6 +133,13 @@ async function applySchema(client: DevDbClient): Promise<void> {
   for (const ddl of [
     SQL_JOBS_TABLE,
     SQL_IDEMPOTENCY_TABLE,
+    // The DDL only, and deliberately NO `setAuditSink` beside `setIdempotencyStore` below: there
+    // is no default audit sink on purpose, so `X_AUDIT_SINK_MISSING` keeps firing at boot for an
+    // app that declares `audit: true` and installs none. Applying the table without installing a
+    // sink is the same call `SQL_RATE_LIMIT_TABLE` already makes — one round trip at boot on a
+    // possibly-unused table, against `postgresAuditSink` failing its first write with
+    // `relation "x_audit" does not exist`.
+    SQL_AUDIT_TABLE,
     SQL_RATE_LIMIT_TABLE,
     SQL_AUTH_LIMIT_TABLES,
   ]) {
@@ -148,7 +177,11 @@ async function applySchema(client: DevDbClient): Promise<void> {
  * `startServices` runs before `loadApp`, so the store is in place before `registerAction`
  * evaluates a `scope: 'shared'` declaration against it.
  */
-async function startJobs(client: DevDbClient, overrides?: RuntimeOverrides): Promise<RunningQueue> {
+async function startJobs(
+  client: DevDbClient,
+  replica: PostgresClient | undefined,
+  overrides?: RuntimeOverrides,
+): Promise<RunningQueue> {
   await applySchema(client);
   const executor = pgExecutorFor(client);
   const driver = overrides?.jobs ?? createPgDriver({ executor });
@@ -171,7 +204,7 @@ async function startJobs(client: DevDbClient, overrides?: RuntimeOverrides): Pro
     outbox,
     events,
     idempotency,
-    stop: () => releaseQueue(client, driver),
+    stop: () => releaseQueue(client, driver, replica),
   };
 }
 
@@ -184,7 +217,11 @@ async function startJobs(client: DevDbClient, overrides?: RuntimeOverrides): Pro
  * The facade goes with the driver for the same reason: an enqueue routed through a store bound to
  * a closed client is a staged row nothing will ever publish.
  */
-async function releaseQueue(db: DevDbClient, jobs: JobDriver | undefined): Promise<void> {
+async function releaseQueue(
+  db: DevDbClient,
+  jobs: JobDriver | undefined,
+  replica?: PostgresClient,
+): Promise<void> {
   // The idempotency store goes back to the memory default for the same reason the facade does: it
   // holds this client, and the next command in this process would reserve keys over a closed one.
   resetIdempotency();
@@ -193,6 +230,9 @@ async function releaseQueue(db: DevDbClient, jobs: JobDriver | undefined): Promi
   setDbClient(undefined);
   await jobs?.close?.();
   await db.close();
+  // After the primary, and never instead of it: a standby pool left open is a connection slot on
+  // the other server that nothing in this process can reach again.
+  await replica?.close();
 }
 
 /**
@@ -205,18 +245,18 @@ export async function startQueue(
   services: DevServices,
   overrides?: RuntimeOverrides,
 ): Promise<RunningQueue> {
-  const db = startDb(services);
+  const { client: db, replica } = startDb(services);
   try {
     // Pay the Postgres boot here, so the first request is not the slow one and a broken database
     // fails at boot rather than on some later query.
     await db.ping();
-    return await startJobs(db, overrides);
+    return await startJobs(db, replica, overrides);
   } catch (error) {
     // `db.ping()` or `startJobs` is where a broken database is supposed to fail. Without this,
     // the caller exits holding the PGlite lock and the ambient accessors, and nothing is left to
     // release them. The rejection that started the unwind is the one worth reporting.
     try {
-      await releaseQueue(db, undefined);
+      await releaseQueue(db, undefined, replica);
     } catch {
       // Cleanup noise never replaces the boot failure.
     }

package/src/dev-replica.ts

@@ -0,0 +1,99 @@
+// Read-replica routing, WIRED. `@ultimat3/db` ships both halves and a booted process reached
+// neither, so the capability was shipped and unactivated — the "declared and never wired" class
+// this release exists to eliminate.
+//
+// Two things had to be false for it to route, and both were:
+//
+// 1. `defaultClient()` is the one place db composes `replicatedClient(primary, replica)` from
+//    `DATABASE_REPLICA_URL`, and it runs only from `baseClient()` — "the client an app installed
+//    none for". Every process the framework boots installs one: `dev-queue.ts` calls
+//    `setDbClient(createPgliteClient(…) | createPostgresClient({ url }))`, so `defaultClient()` was
+//    unreachable from `x dev`, from `apps/web/server.ts` and from every container role.
+// 2. Routing needs an OPEN scope as well as a configured replica, and nothing opened one.
+//
+// This file answers both from the boot, which is the only tier that may know about a request AND
+// about a pool. It is deliberately NOT a change to `@ultimat3/http`'s pipeline: that would make the
+// HTTP tier depend on `@ultimat3/db` — legal downward, and still a package that would then know
+// what a database is.
+
+import type { DbClient, PostgresClient } from '@ultimat3/db';
+import {
+  createPostgresClient,
+  REPLICA_URL_ENV,
+  replicatedClient,
+  withReplicaReads,
+} from '@ultimat3/db';
+import type { Middleware } from '@ultimat3/http';
+import type { ServiceBinding } from './dev-services';
+import type { RuntimeOverrides } from './runtime-overrides';
+
+export type ReplicaEnv = Readonly<Record<string, string | undefined>>;
+
+/**
+ * The replica url this boot should use, or `undefined`. Two conditions, and the second is the one
+ * a homework app depends on: an EMBEDDED database is PGlite in this process, which has no standby
+ * and never will, so a `DATABASE_REPLICA_URL` left over in a shell must not silently open a second
+ * pool beside it.
+ */
+export function replicaUrlFor(binding: ServiceBinding, env: ReplicaEnv): string | undefined {
+  if (binding.mode !== 'external') return undefined;
+  const url = env[REPLICA_URL_ENV];
+  return url === undefined || url.trim() === '' ? undefined : url;
+}
+
+/** What a boot has to hold on to: the ambient client, and the pool `stop()` must close. */
+export interface ReplicaAttachment {
+  /** What `setDbClient()` receives — the pair when one is configured, the primary otherwise. */
+  readonly client: DbClient;
+  /** The standby pool this boot opened, or nothing. `ReplicatedClient` has no `close()`. */
+  readonly replica: PostgresClient | undefined;
+}
+
+/**
+ * The primary as it is, or the primary with a standby behind it. Composed here rather than by
+ * calling `defaultClient()`, because that function builds its own primary from `DATABASE_URL` and
+ * this boot has already RESOLVED which database it is talking to (`resolveServices`) — asking the
+ * environment a second question is how a process ends up with two answers to "which database is
+ * this". The pieces are db's own, so the routing rule is still stated in one place.
+ */
+export function attachReplica(
+  primary: DbClient,
+  replicaUrl: string | undefined,
+): ReplicaAttachment {
+  if (replicaUrl === undefined) return { client: primary, replica: undefined };
+  const replica = createPostgresClient({ url: replicaUrl, applicationName: 'ultimate-replica' });
+  return { client: replicatedClient(primary, replica), replica };
+}
+
+/**
+ * The scope, opened once per request, OUTSIDE the handler — so a write early in a request pins
+ * every later read in it to the primary, which is what read-your-writes means. `compose()` wraps
+ * each route handler, and every read and write a request makes happens inside one.
+ *
+ * EMPTY when no replica is configured, and that is the whole cost argument: a homework app
+ * installs no middleware, allocates no scope object and enters no `AsyncLocalStorage` run per
+ * request. With one configured, the list is a single frame.
+ */
+export function replicaMiddleware(binding: ServiceBinding, env: ReplicaEnv): readonly Middleware[] {
+  if (replicaUrlFor(binding, env) === undefined) return [];
+  return [(request, ctx, next) => withReplicaReads(() => next(request, ctx))];
+}
+
+/**
+ * The boot's `RuntimeOverrides` with the scope middleware laid in FRONT of whatever a host
+ * supplied — `compose([a, b])` runs `a` outermost, and the scope must open outside every read and
+ * write the request makes or a write early in it cannot pin the reads after it.
+ *
+ * Returns the caller's own value UNCHANGED when no replica is configured, which is what keeps a
+ * homework app from paying for this: no key added, no empty array, nothing for `startRoles` to
+ * forward.
+ */
+export function replicaOverrides(
+  overrides: RuntimeOverrides | undefined,
+  binding: ServiceBinding,
+  env: ReplicaEnv,
+): RuntimeOverrides | undefined {
+  const middleware = replicaMiddleware(binding, env);
+  if (middleware.length === 0) return overrides;
+  return { ...overrides, middleware: [...middleware, ...(overrides?.middleware ?? [])] };
+}

package/src/dev-roles-fixture.ts

@@ -7,6 +7,7 @@
 
 import { noopPurgeDriver } from '@ultimat3/cache';
 import { resetLifecycle } from '@ultimat3/core';
+import { resetHttpConfig } from '@ultimat3/http';
 import {
   createMemoryDriver,
   createMemoryEventBus,
@@ -64,4 +65,10 @@ export function resetDevRolesState(): void {
   resetJobsFacade();
   resetTasks();
   resetLifecycle();
+  // `configureHttp()` is a process-global registration made at MODULE scope, so one file that
+  // loads an app leaves that app's CORS origins, body limit and buckets standing for every later
+  // file in the same `bun test` process — and a scaffolded app now ships such a module
+  // (`apps/web/app/http.ts`). Nothing is broken today; this is the same rule the four resets above
+  // already follow, applied to the fifth global before it is the one that costs an afternoon.
+  resetHttpConfig();
 }

package/src/dev-roles.ts

@@ -9,7 +9,13 @@
 import type { Role } from '@ultimat3/core';
 import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
 import type { RateLimitStore, Route, ServerHandle, ServerHooks } from '@ultimat3/http';
-import { configuredAuthenticator, createServer, defineHttpConfig } from '@ultimat3/http';
+import {
+  configuredAuthenticator,
+  configuredHttp,
+  createServer,
+  defineHttpConfig,
+  mergeHttpConfig,
+} from '@ultimat3/http';
 import type { OutboxRelay, Scheduler, Worker } from '@ultimat3/jobs';
 import {
   createOutboxRelay,
@@ -257,37 +263,45 @@ function startWeb(options: StartRolesOptions): ServerHandle {
       ? {}
       : { middleware: options.overrides.middleware }),
     ...(store === undefined ? {} : { rateLimitStore: store }),
-    config: defineHttpConfig({
-      port: options.port,
-      dev: binding.dev,
-      buildId: options.buildId,
-      hostname: binding.hostname,
-      signInPath: options.signInPath ?? null,
-      // One declaration, never half of one: `defineHttpConfig` refuses `trustProxy` without hops.
-      ...(hops === null ? {} : { trustProxy: true, trustedProxyHops: hops }),
-      // `scope` is mandatory since @ultimat3/http made an undeclared limiter a boot error, and it
-      // is DERIVED from the store rather than hardcoded — a literal here would be a second
-      // declaration quietly contradicting the object beside it, and `assertRateLimitScope` holds
-      // the two halves together. It answered `'process'` on every real boot until `startServices`
-      // resolved a store, so the shipped chart's three `web` replicas enforced `login: { limit: 5 }`
-      // as fifteen attempts, with `x verify` green.
-      rateLimit: { scope: store?.scope ?? 'process' },
-      // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
-      // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a
-      // function of that body. Read after `loadApp` — importing the app IS what registered them.
-      // BOTH directives, and the script half is the one that was missing: the hydration runtime
-      // is emitted inline in every document that carries an island, so `script-src 'self'` meant
-      // no island booted anywhere the policy is enforced — which is every container, and never
-      // `x dev`, where it is report-only.
-      security: {
-        csp: {
-          extend: {
-            'style-src': inlineStyleSources(options.inlineStyles ?? []),
-            'script-src': inlineScriptSources(),
+    // The app's own declaration UNDERNEATH, this boot's facts on top. Without the first half the
+    // entire HTTP tuning surface was unreachable from a shipped app — this literal was its only
+    // construction, so `cors.origins` stayed `[]` in every deployment (no cross-origin call could
+    // ever succeed), `bodyLimitBytes` stayed 1 MiB and `requestTimeoutMs` 30s for a bank and a
+    // blog alike. The ORDER is not a preference: `buildId`, the port, the CSP hashes of what this
+    // process emits and the scope of the store it installed are facts only the boot has.
+    config: defineHttpConfig(
+      mergeHttpConfig(configuredHttp(), {
+        port: options.port,
+        dev: binding.dev,
+        buildId: options.buildId,
+        hostname: binding.hostname,
+        signInPath: options.signInPath ?? null,
+        // One declaration, never half of one: `defineHttpConfig` refuses `trustProxy` without hops.
+        ...(hops === null ? {} : { trustProxy: true, trustedProxyHops: hops }),
+        // `scope` is mandatory since @ultimat3/http made an undeclared limiter a boot error, and it
+        // is DERIVED from the store rather than hardcoded — a literal here would be a second
+        // declaration quietly contradicting the object beside it, and `assertRateLimitScope` holds
+        // the two halves together. It answered `'process'` on every real boot until `startServices`
+        // resolved a store, so the shipped chart's three `web` replicas enforced
+        // `login: { limit: 5 }` as fifteen attempts, with `x verify` green.
+        rateLimit: { scope: store?.scope ?? 'process' },
+        // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
+        // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a
+        // function of that body. Read after `loadApp` — importing the app IS what registered them.
+        // BOTH directives, and the script half is the one that was missing: the hydration runtime
+        // is emitted inline in every document that carries an island, so `script-src 'self'` meant
+        // no island booted anywhere the policy is enforced — which is every container, and never
+        // `x dev`, where it is report-only.
+        security: {
+          csp: {
+            extend: {
+              'style-src': inlineStyleSources(options.inlineStyles ?? []),
+              'script-src': inlineScriptSources(),
+            },
           },
         },
-      },
-    }),
+      }),
+    ),
   }).start();
 }
 

package/src/dev-sync.ts

@@ -16,6 +16,7 @@ import {
 } from '@ultimat3/realtime/server';
 import type { StartRolesOptions } from './dev-roles';
 import { neighbouringPort, PORT_RANGE } from './flag-number';
+import { portFree } from './port-probe';
 import { syncAuthenticator } from './sync-authenticator';
 
 /**
@@ -35,6 +36,46 @@ class SyncPortUnavailableError extends UltimateError {
   }
 }
 
+/**
+ * The neighbour was already listening. `X_PORT_IN_USE` is this package's own and is exactly what
+ * `x doctor` reports for the same condition, so one taken port has one name wherever it is found.
+ *
+ * What shipped instead: `listenSyncNode`'s `Bun.serve` threw, `startSync` re-threw, and the
+ * dispatcher rendered the caught value into `X_CLI_UNEXPECTED`'s cause —
+ * `cause: Error: Failed to start server. Is port 4000 in use?`, `fix: x doctor --json`, from a
+ * command that had just printed `web listening on 3999`. Three defects in one output: an
+ * unstable code, a caught value rendered into a refusal, and a `fix:` that answered
+ * "no findings — environment is shippable" when run (#F5).
+ */
+class SyncPortInUseError extends UltimateError {
+  constructor(input: { port: number; webPort: number }) {
+    super({
+      code: 'X_PORT_IN_USE',
+      cause: `the sync role binds PORT + 1, so \`x dev --port ${input.webPort}\` needs port ${input.port} and something is already listening on it`,
+      fix: `x dev --port ${neighbouringPort(input.webPort)}   # or free port ${input.port}: lsof -nP -iTCP:${input.port} -sTCP:LISTEN`,
+      meta: { port: input.port, webPort: input.webPort },
+    });
+  }
+}
+
+/**
+ * What a failed `listenSyncNode` really was, ASKED rather than read off the caught value: the
+ * thrown thing is `Bun.serve`'s own English and interpolating it into a `cause:` is what
+ * `scripts/catch-render.ts` refuses. `undefined` means "not a taken port" and the original value
+ * is re-thrown untouched — a catch-all that renamed every listener failure would be worse than
+ * the bare one it replaced.
+ *
+ * `probe` is injected so a test can be exactly "the port was taken" without racing a real socket.
+ */
+export async function syncBindRefusal(
+  webPort: number,
+  port: number,
+  probe: (value: number) => Promise<boolean> = portFree,
+): Promise<UltimateError | undefined> {
+  if (await probe(port)) return undefined;
+  return new SyncPortInUseError({ port, webPort });
+}
+
 /**
  * The port the sync node listens on. `PORT + 1`, and `0` stays `0` — the kernel picks, and adding
  * one to it would pick a specific port instead.
@@ -131,8 +172,9 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     }),
   });
   await node.start();
+  const port = syncPortFor(options.port);
   try {
-    const listener = listenSyncNode(node, { port: syncPortFor(options.port) });
+    const listener = listenSyncNode(node, { port });
     return {
       url: listener.url,
       stop: async () => {
@@ -142,6 +184,8 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     };
   } catch (error) {
     await node.stop();
+    const refusal = await syncBindRefusal(options.port, port);
+    if (refusal !== undefined) throw refusal;
     throw error;
   }
 }

package/src/error-codes.ts

@@ -52,6 +52,13 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_STORAGE_UNWRITABLE',
   'X_STORAGE_SECRET_DEV',
   'X_MANIFEST_STALE',
+  // The other half of the same file, and the one that was silence: `x manifest` writes
+  // `x.manifest.json`, `AGENTS.md` tells an agent that facts live in it, `x dev` prints its path —
+  // and nothing ever ran the command, so the gate's `manifest` step reported green over a file
+  // that has never existed in any app `x new` produced. Its own code because the repair differs
+  // from both neighbours: `X_MANIFEST_DRIFT` means the committed file disagrees with the code and
+  // `X_MANIFEST_STALE` means `openapi.json` does; this one means there is nothing there at all.
+  'X_MANIFEST_MISSING',
   'X_BUDGET_UNMEASURED',
   // The other half of #271, and the half no runtime can raise: a route reads a live hook and boots
   // no module in a browser, so its rows have nowhere to arrive and the page renders its loading
@@ -146,6 +153,14 @@ export const CLI_OWNED_ERROR_CODES = [
  */
 export const CLI_BORROWED_ERROR_CODES = [
   'X_NOT_IMPLEMENTED',
+  // `@ultimat3/policy`'s, and the gate's `policy` step reports it verbatim — cause, fix and the
+  // nearest declared name all come from `permissionUnknown`. A CLI-owned twin would be a second
+  // wording for the condition `can()` already refuses at run time, and the two would drift.
+  'X_PERMISSION_UNKNOWN',
+  // `@ultimat3/db`'s, reported by `x doctor`'s database probe with that package's own two-branch
+  // fix. The CLI is the half that asks BEFORE a pool is opened; the condition and the remedy are
+  // both db's, and a CLI twin would be one unreachable database with two names.
+  'X_DB_UNAVAILABLE',
   'X_CONFIG_INVALID',
   'X_ENV_MISSING',
   'X_ENV_EXAMPLE_DRIFT',
@@ -195,6 +210,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_PACKAGE_UNREFERENCED: 'a published workspace is not in the root tsconfig build graph',
   X_RELEASE_VERSION_SKEW: 'a workspace is not at the lockstep version',
   X_MANIFEST_STALE: 'openapi.json is stale',
+  X_MANIFEST_MISSING: 'the app ships no x.manifest.json',
   X_BUDGET_UNMEASURED: 'a route declares a budget the build never measured',
   X_LIVE_ROUTE_NO_ISLAND: 'a route reads live rows and boots nothing that could receive them',
   X_BUILD_FAILED: 'x build failed',

package/src/i18n-index.ts

@@ -0,0 +1,40 @@
+// The one writer of `packages/i18n/src/index.ts`, shared by `x g` and `x i18n add|sync`.
+//
+// A catalog file existing on disk and the app being able to SELECT that locale are two different
+// facts, and only this closes the gap: the index hardcodes `locales: { en }`, so a locale whose
+// catalog nothing registered renders `⟦key⟧` — which the gate's `i18n` step refuses outright
+// (`X_CATALOG_UNREGISTERED`). `x i18n add fr` wrote the file, touched nothing else, and left
+// `x verify` red with a fix line that named an edit nobody could perform (#F4).
+
+// why: Bun has no synchronous existence check — `Bun.file(p).exists()` is async, and this decides
+// whether to write at all, before any await the caller could interleave with.
+import { existsSync } from 'node:fs';
+import { containedPath } from './generate-write';
+import { CATALOG_ROOT, i18nIndex } from './templates';
+
+export const I18N_INDEX_PATH = 'packages/i18n/src/index.ts';
+
+/** Every locale with a catalog on disk, sorted — the file names are the tags. */
+export async function catalogLocales(root: string): Promise<readonly string[]> {
+  const catalogDir = containedPath(root, CATALOG_ROOT);
+  if (!existsSync(catalogDir)) return [];
+  const locales: string[] = [];
+  for await (const entry of new Bun.Glob('*.json').scan({ cwd: catalogDir, absolute: false })) {
+    locales.push(entry.replace(/\.json$/, ''));
+  }
+  return locales.sort();
+}
+
+/**
+ * Re-derives the FULL locale set from `packages/i18n/catalogs/` — never just the locale one
+ * invocation asked for — and rewrites the index to match. It bypasses `writeFiles` on purpose:
+ * this file is a projection of the catalog directory, never app-authored content a conflict check
+ * should protect. An app with no i18n package (deleted, or never scaffolded) is left alone, and
+ * that is what `written` reports.
+ */
+export async function syncI18nIndex(root: string): Promise<boolean> {
+  const indexAbsolute = containedPath(root, I18N_INDEX_PATH);
+  if (!existsSync(indexAbsolute)) return false;
+  await Bun.write(indexAbsolute, i18nIndex(await catalogLocales(root)));
+  return true;
+}