@ultimat3/cli 7.0.0 → 8.0.0

package/src/dev-lock.ts

@@ -14,11 +14,12 @@
 // The lock file is what makes the second one nameable at all: nothing else in the process can tell
 // "another dev server owns this directory" from "the database is broken".
 
-import { unlinkSync } from 'node:fs';
+import { closeSync, mkdirSync, openSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { UltimateError } from '@ultimat3/core';
 import { docsFor } from './error-codes';
 import { exec, type Runner } from './exec';
+import { quoteArg } from './shell-quote';
 
 /** Where the running dev server records itself, inside the state directory it already owns. */
 export const DEV_LOCK_FILE = 'dev.lock';
@@ -101,6 +102,28 @@ export class DevAlreadyRunningError extends UltimateError {
   }
 }
 
+/**
+ * The lock file exists, this process could not read it and could not remove it — which is not
+ * "another x dev is running", and was reported as exactly that.
+ *
+ * `DevAlreadyRunningError` needs a `DevLock`, and the only one in hand on that path was `mine`:
+ * the refusal then read `pid <this process> is already running x dev` with `fix: … kill <this
+ * process>`, a remedy that kills the reader and a cause naming the wrong holder. Axiom 4 wants a
+ * runnable fix and an honest cause, so the honest answer is its own code — the file is the
+ * problem, and removing it is what a reader can actually do.
+ */
+export class DevLockUnreadableError extends UltimateError {
+  constructor(input: { readonly path: string; readonly stateDir: string }) {
+    super({
+      code: 'X_DEV_LOCK_UNREADABLE',
+      cause: `${input.path} could not be parsed as a dev lock and could not be removed, so x dev cannot tell whether another process owns ${input.stateDir}`,
+      fix: `rm ${quoteArg(input.path)}   # then re-run x dev`,
+      docs: docsFor('X_DEV_LOCK_UNREADABLE'),
+      meta: { path: input.path, stateDir: input.stateDir },
+    });
+  }
+}
+
 /** Whatever is listening, as far as the OS will say. Both fields absent when it will not say. */
 export interface PortHolder {
   readonly pid?: number;
@@ -207,6 +230,41 @@ export const isPortBound = (port: number, hostname: string): boolean => {
   }
 };
 
+/**
+ * Take the lock, or answer `false` because someone else holds it.
+ *
+ * `wx` is the whole mechanism: the create and the exclusivity are ONE syscall, so two boots racing
+ * this cannot both come back `true`. A check followed by a write is what this replaces, and the
+ * window between those two was seconds wide — `startDev` boots embedded Postgres, the queue, the
+ * transport and the app's modules before anything was written down.
+ *
+ * Only `EEXIST` is "someone else has it". Anything else — a read-only checkout, a `.x/` nobody may
+ * write — is rethrown as it arrives: it is the same failure `writeLock` would have raised seconds
+ * later, and inventing a code for it here would be a second answer to one condition.
+ */
+function claimExclusive(path: string, lock: DevLock): boolean {
+  let fd: number;
+  try {
+    fd = openSync(path, 'wx');
+  } catch (error) {
+    if ((error as { code?: string }).code === 'EEXIST') return false;
+    throw error;
+  }
+  try {
+    writeFileSync(fd, `${JSON.stringify(lock, null, 2)}\n`);
+  } finally {
+    closeSync(fd);
+  }
+  return true;
+}
+
+/** 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());
+};
+
 export interface PreflightInput {
   readonly stateDir: string;
   readonly port: number;
@@ -220,22 +278,53 @@ export interface PreflightInput {
   readonly holder?: (port: number) => Promise<PortHolder>;
 }
 
+export interface PreflightResult {
+  readonly clearedStale: boolean;
+  /**
+   * Give the directory back. The caller runs it when the boot it was preflighting FAILED —
+   * `serve.ts`'s `releaseBoot` shape — because a claim held by a process that gave up refuses
+   * every later boot in that shell for a pid that is gone.
+   */
+  release(): void;
+}
+
 /**
- * Run before anything boots. Throws the coded refusal, or returns the stale lock it cleared so the
- * caller can say so — a lock left by a hard kill is normal and worth one line, not a failure.
+ * Run before anything boots, and it CLAIMS: it returns holding the directory, never having merely
+ * looked at it.
+ *
+ * That is the fix, not a detail. `preflight` read the lock, `startDev` booted for seconds, and
+ * `writeLock` ran last — so two `x dev` in one checkout both passed the check and both opened
+ * `.x/pgdata`, `X_DEV_ALREADY_RUNNING` was unreachable, and what the operator actually got was
+ * `X_DB_UNAVAILABLE` whose `fix:` reads "run `x dev`" — the incident this file's own header
+ * 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.
  */
-export const preflight = async (input: PreflightInput): Promise<{ clearedStale: boolean }> => {
+export const preflight = async (input: PreflightInput): Promise<PreflightResult> => {
   const alive = input.alive ?? isProcessAlive;
   const bound = input.portBound ?? isPortBound;
   const path = lockPath(input.stateDir);
-  const file = Bun.file(path);
+  const release = (): void => clearLock(input.stateDir);
+  // The lock lives inside the state directory, which the database has not created yet — this runs
+  // before anything boots, which is the whole point of it.
+  mkdirSync(input.stateDir, { recursive: true });
+  const mine: DevLock = {
+    pid: process.pid,
+    port: input.port,
+    // Refined by `writeLock` once the server reports the address it really bound; until then this
+    // 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(),
+  };
   let clearedStale = false;
 
-  if (await file.exists()) {
-    const lock = parseLock(await file.text());
-    if (lock !== null && alive(lock.pid)) {
+  if (!claimExclusive(path, mine)) {
+    const held = await readLock(path);
+    if (held !== null && alive(held.pid)) {
       throw new DevAlreadyRunningError({
-        lock,
+        lock: held,
         stateDir: input.stateDir,
         ...(input.embeddedDb === undefined ? {} : { embeddedDb: input.embeddedDb }),
       });
@@ -245,22 +334,45 @@ export const preflight = async (input: PreflightInput): Promise<{ clearedStale:
     try {
       unlinkSync(path);
     } catch {
-      // Already gone, or not ours to remove. Either way the boot below is what decides.
+      // Already gone, or not ours to remove. The claim below is what decides.
     }
     clearedStale = true;
+    if (!claimExclusive(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 }),
+      });
+    }
   }
 
   if (bound(input.port, input.hostname)) {
+    // Released before the throw: the remedy this refusal prints is `x dev --port <n>`, and a claim
+    // left behind would answer that command with X_DEV_ALREADY_RUNNING naming the process that
+    // just exited on it.
+    release();
     throw new DevPortInUseError({
       port: input.port,
       suggestion: suggestPort(input.port),
       holder: await (input.holder ?? portHolder)(input.port),
     });
   }
-  return { clearedStale };
+  return { clearedStale, release };
 };
 
-/** Record this process. Written after the preflight passes and before the roles start. */
+/**
+ * Record this process. The claim is already on disk — `preflight` took it — so this REFINES it
+ * 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> => {
   await Bun.write(lockPath(stateDir), `${JSON.stringify(lock, null, 2)}\n`);
 };

package/src/dev-queue.ts

@@ -20,6 +20,7 @@ import {
   setDbClient,
 } from '@ultimat3/db';
 import type { Tx } from '@ultimat3/entity';
+import { SQL_RATE_LIMIT_TABLE } from '@ultimat3/http';
 import type { EventBus, JobDriver, OutboxStore, PgExecutor } from '@ultimat3/jobs';
 import {
   createJobsFacade,
@@ -82,16 +83,20 @@ export function pgExecutorFor(client: DbClient): PgExecutor {
  * Every table this process's framework packages own, applied before anything reads one.
  *
  * PGlite speaks the extended protocol, which carries one statement per round trip, so the DDL is
- * applied statement by statement. Safe to split on `;`: both constants are fixed, with no
- * semicolon inside a literal, and each package's own SQL test is where that stays true.
+ * applied statement by statement. Safe to split on `;`: every constant is fixed, with no semicolon
+ * inside a literal, and each package's own SQL test is where that stays true.
  *
- * `SQL_IDEMPOTENCY_TABLE` is here and not in `@ultimat3/action` because a package that holds no
- * database dependency cannot apply its own schema — the same reason `SQL_JOBS_TABLE` is applied
- * here. Without it `postgresIdempotencyStore` is a store whose first reservation fails on a
- * missing relation, which is how a retried `POST /api/payments/charge` charges a card twice.
+ * `SQL_IDEMPOTENCY_TABLE` and `SQL_RATE_LIMIT_TABLE` are here and not in `@ultimat3/action` or
+ * `@ultimat3/http` because a package that holds no database dependency cannot apply its own schema
+ * — the same reason `SQL_JOBS_TABLE` is applied here. Each one absent is the same failure at a
+ * different door: a retried `POST /api/payments/charge` charges the card twice, and the FIRST
+ * request a `rateLimitStore` deployment serves dies on a missing `x_rate_limit` relation. The
+ * table is installed whether or not this boot passes `runtime.rateLimitStore` — `create table if
+ * not exists` on an unused table costs one round trip at boot, and a store installed later must
+ * not be the thing that discovers the schema was never applied.
  */
 async function applySchema(client: DevDbClient): Promise<void> {
-  for (const ddl of [SQL_JOBS_TABLE, SQL_IDEMPOTENCY_TABLE]) {
+  for (const ddl of [SQL_JOBS_TABLE, SQL_IDEMPOTENCY_TABLE, SQL_RATE_LIMIT_TABLE]) {
     for (const statement of ddl.split(';')) {
       if (statement.trim().length > 0) await client.execute(raw(statement));
     }

package/src/dev-replicator.ts

@@ -4,13 +4,9 @@
 // roles reading the other end of that transport.
 
 import { describeEntities } from '@ultimat3/entity';
-import type { Replicator, Transport } from '@ultimat3/realtime';
-import {
-  createReplicator,
-  ReplicatorSlotHeldError,
-  replicatorLockKey,
-  selectChangeFeed,
-} from '@ultimat3/realtime';
+import { ReplicatorSlotHeldError } from '@ultimat3/realtime';
+import type { Replicator, Transport } from '@ultimat3/realtime/server';
+import { createReplicator, replicatorLockKey, selectChangeFeed } from '@ultimat3/realtime/server';
 import type { DevServices, Env } from './dev-services';
 import { BadFlagError } from './errors';
 

package/src/dev-roles-fixture.ts

@@ -16,7 +16,7 @@ import {
   resetTasks,
 } from '@ultimat3/jobs';
 import { createMemoryDriver as createMemoryMailDriver } from '@ultimat3/mail';
-import { DEFAULT_PRESENCE_TTL_MS, InProcessTransport } from '@ultimat3/realtime';
+import { DEFAULT_PRESENCE_TTL_MS, InProcessTransport } from '@ultimat3/realtime/server';
 import { defineStorage, localDriver } from '@ultimat3/storage';
 import type { RunningServices } from './dev-runtime';
 import { resolveServices } from './dev-services';

package/src/dev-roles.ts

@@ -8,7 +8,7 @@
 
 import type { Role } from '@ultimat3/core';
 import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
-import type { Route, ServerHandle, ServerHooks } from '@ultimat3/http';
+import type { RateLimitStore, Route, ServerHandle, ServerHooks } from '@ultimat3/http';
 import { configuredAuthenticator, createServer, defineHttpConfig } from '@ultimat3/http';
 import type { OutboxRelay, Scheduler, Worker } from '@ultimat3/jobs';
 import {
@@ -195,11 +195,43 @@ export function trustedHopsFromEnv(env: Env): number | null {
   return hops;
 }
 
+/**
+ * A deployment that substituted a PER-PROCESS store is enforcing every declared number once per
+ * replica, and the shipped chart runs three. Not refused — `assertRateLimitScope` only fires on a
+ * `'shared'` declaration, and the scope below is DERIVED from the store, so the two can never
+ * contradict each other — but the multiplier is stated, in the `warnIfUnauthenticatable` shape:
+ * loud, coded, and naming the call that fixes it.
+ *
+ * Only for a store the host SUPPLIED. A boot with no store at all resolved one of its own
+ * (`startServices`), so the remaining silent case is a hand-built `RunningServices` in a test.
+ */
+function warnIfProcessScoped(store: RateLimitStore): void {
+  if (store.scope === 'shared') return;
+  logger.warn(
+    `X_CONFIG_INVALID: the rate-limit store this deployment passed keeps its counters per process, so every limit the app declares is enforced once per replica — docker/helm/values.yaml runs roles.web.replicas: 3, which is 3x every number — fix: drop runtime.rateLimitStore and the boot installs postgresRateLimitStore({ executor }) on the pool it already opened`,
+  );
+}
+
+/**
+ * Where this web role's limiter keeps its counters: what the deployment SUBSTITUTED, else the
+ * shared Postgres store `startServices` resolved over the pool this boot already opened.
+ *
+ * One expression, one answer, in the order `RuntimeOverrides` documents — an override REPLACES the
+ * resolved default rather than sitting beside it. `undefined` is reachable only from a hand-built
+ * runtime, which is `createServer`'s per-process memory store and `scope: 'process'` below.
+ */
+function rateLimitStoreFor(options: StartRolesOptions): RateLimitStore | undefined {
+  const supplied = options.overrides?.rateLimitStore;
+  if (supplied === undefined) return options.runtime.rateLimitStore;
+  warnIfProcessScoped(supplied);
+  return supplied;
+}
+
 function startWeb(options: StartRolesOptions): ServerHandle {
   warnIfUnauthenticatable(options.routes);
   const binding = options.http ?? DEV_BINDING;
   const hops = trustedHopsFromEnv(options.env);
-  const store = options.overrides?.rateLimitStore;
+  const store = rateLimitStoreFor(options);
   return createServer({
     routes: options.routes,
     role: 'web',
@@ -218,12 +250,12 @@ function startWeb(options: StartRolesOptions): ServerHandle {
       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: the
-      // old `'process'` default meant the shipped chart's three `web` replicas enforced
-      // `login: { limit: 5 }` as fifteen attempts, with `x verify` green. It is DERIVED from the
-      // store rather than hardcoded — a deployment that hands `runtime.rateLimitStore` a shared
-      // store is declaring the fleet-wide numbers, and `assertRateLimitScope` then holds the two
-      // halves together instead of a literal here quietly contradicting the store beside it.
+      // `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

package/src/dev-runtime.ts

@@ -6,7 +6,14 @@
 import { mkdirSync } from 'node:fs';
 import type { PurgeDriver } from '@ultimat3/cache';
 import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
-import { isLocal, renderThrowable, resolveEnvironment } from '@ultimat3/core';
+import {
+  isLocal,
+  registerReadinessCheck,
+  renderThrowable,
+  resolveEnvironment,
+} from '@ultimat3/core';
+import type { RateLimitStore } from '@ultimat3/http';
+import { postgresRateLimitStore } from '@ultimat3/http';
 import type { EventBus, JobDriver, OutboxStore } from '@ultimat3/jobs';
 import type { MailDriver } from '@ultimat3/mail';
 import {
@@ -16,13 +23,13 @@ import {
   selectMailDriver,
   setMailDriver,
 } from '@ultimat3/mail';
-import type { Transport, TransportSelection } from '@ultimat3/realtime';
-import { selectTransport } from '@ultimat3/realtime';
+import type { Transport, TransportSelection } from '@ultimat3/realtime/server';
+import { selectTransport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
 import { startCacheTiers } from './dev-cache';
 import type { DevDbClient } from './dev-queue';
-import { startQueue } from './dev-queue';
+import { pgExecutorFor, startQueue } from './dev-queue';
 import type { DevServices, Env } from './dev-services';
 import { LocalDiskUnsafeError, StorageUnwritableError } from './errors';
 import { msg } from './messages';
@@ -51,6 +58,20 @@ export interface RunningServices {
    * would show members leaving that never left.
    */
   readonly presenceTtlMs: number;
+  /**
+   * Where the HTTP rate limiter keeps its counters, over the pool this boot already opened.
+   *
+   * Resolved HERE and not at `startWeb` for the reason every other driver is: `startServices` is
+   * what holds the connection, and a store built anywhere else would open a second pool against a
+   * url this boot resolved once. Until it did, no boot installed one at all — so `rateLimit.scope`
+   * derived to `'process'` on every deployment the framework produces, while `docker/helm` runs
+   * `roles.web.replicas: 3` and `x new` scaffolds two.
+   *
+   * OPTIONAL because a `RunningServices` can be hand-built: a test's fixture runtime has a stub
+   * client and no shared store, which is `createServer`'s memory store and `scope: 'process'` —
+   * the honest answer for it, and the one `startWeb` derives.
+   */
+  readonly rateLimitStore?: RateLimitStore;
   readonly purge: PurgeDriver;
   /** Same rule as `mailDetail`: the env key that selected the CDN, never the token behind it. */
   readonly purgeDetail: string;
@@ -176,6 +197,59 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
   return defineStorage({ disks: { local: localDriver({ root }) }, default: 'local' });
 }
 
+/**
+ * A readiness check over a dependency that can only be asked asynchronously.
+ *
+ * `ReadinessCheck` is synchronous and that is the mechanism, not a limitation: a probe that awaits
+ * a network call takes as long as the dependency does, so a slow database makes `/readyz` miss its
+ * `timeoutSeconds`, the kubelet reads that as unready, and capacity is pulled from an already
+ * struggling system — the outage the probe existed to prevent, caused by the probe.
+ *
+ * So the read answers the PREVIOUS probe and schedules the next, which is the standard cached
+ * health shape: staleness is one poll period, and the poll period is the operator's own
+ * `periodSeconds`. Deliberately not a `setInterval`: a timer would probe a process nobody is
+ * asking about, and in `x dev` every probe is a statement — one span, one trace id — so a
+ * one-per-second heartbeat would evict every real request from `/_x/timeline` inside a minute.
+ *
+ * It starts `true` because it is already proven: `startQueue` pinged this pool before this line
+ * ran, and a boot that could not would have thrown instead of reaching here.
+ */
+function probedReadinessCheck(name: string, probe: () => Promise<unknown>): () => void {
+  let live = true;
+  let inFlight = false;
+  const refresh = (): void => {
+    if (inFlight) return;
+    inFlight = true;
+    void probe()
+      .then(
+        () => {
+          live = true;
+        },
+        // Every rejection, including the coded `X_DB_UNAVAILABLE` a closed pool answers with. A
+        // check that threw would be reported as failing anyway; catching it here keeps the reason
+        // out of the endpoint's own path, where nothing could report it.
+        () => {
+          live = false;
+        },
+      )
+      .finally(() => {
+        inFlight = false;
+      });
+  };
+  return registerReadinessCheck(name, () => {
+    refresh();
+    return live;
+  });
+}
+
+/** A transport that says whether it is connected. NATS does; the in-process bus has nothing to be. */
+interface ConnectableTransport {
+  readonly connected: boolean;
+}
+
+const saysConnected = (transport: Transport): transport is Transport & ConnectableTransport =>
+  typeof (transport as Partial<ConnectableTransport>).connected === 'boolean';
+
 /**
  * Release what has already started, newest first, and return every failure instead of throwing on
  * the first: a step that rejects must not skip the ones after it, or one transport that will not
@@ -217,6 +291,12 @@ export async function startServices(
   // Boot is a sequence of external resources, and every step after the first can reject — the
   // queue is already up, so from here an unwind must release it exactly like everything after it.
   const started: (() => void | Promise<void>)[] = [() => queue.stop()];
+  // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
+  // registered one, so `/readyz` was `markReady()` alone — "this process bound a socket" — and
+  // `packages/http/src/server.ts` calls that BEFORE `Bun.serve`, while `dev-roles.ts` calls it
+  // before `sync`, `worker` and `scheduler` start. The chart's `readinessProbe` and the container
+  // healthcheck both route on it, so a replica whose pool was gone kept taking traffic.
+  started.push(probedReadinessCheck('database', () => db.ping()));
   try {
     // Dialled here rather than at selection: an unreachable bus must fail at `x dev`, not on the
     // first change nobody receives, and the socket is a resource the unwind below has to release.
@@ -228,6 +308,14 @@ export async function startServices(
       started.push(() => bus.transport.close());
       transport = bus.transport;
     }
+    // Only a transport that can be disconnected gets a check. `NatsTransport.connected` is a
+    // synchronous getter over the client's own state, so no probe is needed; the in-process bus
+    // has nothing to lose a connection to, and a check that can only answer `true` is a number in
+    // `registered` that means nothing.
+    if (saysConnected(transport)) {
+      const connectable = transport;
+      started.push(registerReadinessCheck('transport', () => connectable.connected));
+    }
     const storage = startStorage(services, env, overrides?.storage);
     // With no credential this is the memory driver: caught, not sent, so the `/_x` mail panel can
     // show what a template renders in every locale without a mailbox or a message escaping to a
@@ -257,6 +345,10 @@ export async function startServices(
       mailDetail: selection.detail,
       // The env key that selected the bus — or the honest answer that no env key did, because a
       // boot line reading `NATS_URL` over a transport the host handed in is a lie a script parses.
+      // The same executor the jobs driver, the outbox, the event bus and the idempotency store
+      // run on — one pool, one `Bun.sql` that does NOT satisfy `PgExecutor` (`Bun.sql.query` is
+      // `undefined`), one wrapper. `startWeb` is what an override replaces it at.
+      rateLimitStore: postgresRateLimitStore({ executor: pgExecutorFor(db) }),
       transportDetail: overrides?.transport === undefined ? bus.detail : 'runtime override',
       presenceTtlMs: bus.presenceTtlMs,
       purge,

package/src/dev-sync.ts

@@ -13,7 +13,7 @@ import {
   PresenceRegistry,
   RingChangeBuffer,
   SocketRegistry,
-} from '@ultimat3/realtime';
+} from '@ultimat3/realtime/server';
 import type { StartRolesOptions } from './dev-roles';
 import { syncAuthenticator } from './sync-authenticator';
 
@@ -69,9 +69,14 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
   const hub = new ChannelHub({ transport: options.runtime.transport, sockets });
   // The node evaluated no credential of its own and no host ever handed it one, so every socket
   // the framework opened was anonymous and every guard, gate, presence entry and tenant cap
-  // decided against `null`. An explicit override first — only that one can carry an `expiresAt`
-  // and a `refresh`, which is the whole of re-authorization — then the app's own HTTP resolver,
-  // then nothing at all, which is what `x dev` with no authenticator should stay.
+  // decided against `null`. An explicit override first, then the app's own HTTP resolver, then
+  // nothing at all, which is what `x dev` with no authenticator should stay.
+  //
+  // BOTH of the first two re-authorize: `syncAuthenticator` carries an `expiresAt` and a `refresh`
+  // of its own (`SYNC_GRANT_TTL_MS`), re-asking the app's resolver with the upgrade's own
+  // `cookie`/`authorization`, so `logout` closes the socket and not only the HTTP session. The
+  // override is how a deployment states a window its credential already declares (a token's
+  // `exp`), or resolves identity from a header the adapter deliberately does not retain.
   const authenticate = options.overrides?.syncAuthenticate ?? syncAuthenticator(options.buildId);
   const node = createSyncNode({
     hub,

package/src/dispatch.ts

@@ -3,6 +3,7 @@
 // path as results, so a failure is machine-readable exactly like a success.
 
 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';
@@ -23,8 +24,26 @@ export interface DispatchOptions {
   readonly bunVersion: string;
   readonly runner?: Runner;
   readonly write: (line: string) => void;
+  /**
+   * Where a result declaring `stream: 'stderr'` goes. Optional, and it falls back to `write`: an
+   * embedding caller that supplies one sink must still SEE the line, and `create-ultimate`'s entry
+   * point — which can only ever reach `x new` — would otherwise have to declare a sink for a case
+   * it cannot produce. `bin.ts` passes the real fd 2.
+   */
+  readonly writeError?: (line: string) => void;
 }
 
+/**
+ * Which sink a result is written to. One function because `dispatch` writes in five places — the
+ * version refusal, the parse failure, the unknown command, the result and the catch — and a rule
+ * about fd 1 that four of them apply is not a rule.
+ */
+export const sinkFor = (
+  result: CommandResult,
+  options: Pick<DispatchOptions, 'write' | 'writeError'>,
+): ((line: string) => void) =>
+  result.stream === 'stderr' ? (options.writeError ?? options.write) : options.write;
+
 const resolveCwd = (cwd: string, flag: string | undefined): string => {
   if (flag === undefined) return cwd;
   return isAbsolute(flag) ? flag : resolve(cwd, flag);
@@ -48,7 +67,8 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
   try {
     requireBunVersion(options.bunVersion);
   } catch (error) {
-    options.write(render(errorResult('x', error), wantsJson(options.argv)));
+    const failure = errorResult('x', error);
+    sinkFor(failure, options)(render(failure, wantsJson(options.argv)));
     return 1;
   }
 
@@ -70,7 +90,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);
-    options.write(render(result, wantsJson(options.argv)));
+    sinkFor(result, options)(render(result, wantsJson(options.argv)));
     return 1;
   }
 
@@ -83,7 +103,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
         known: SPECS.map((spec) => spec.name),
       }),
     );
-    options.write(render(result, args.json));
+    sinkFor(result, options)(render(result, args.json));
     return 1;
   }
 
@@ -105,6 +125,16 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
   };
 
   try {
+    // `--json` means fd 1 carries ONE document, and every command that boots an app logs through
+    // core's module-scope `logger`, whose default writer is stdout: `x db migrate --json` printed
+    // `ultimate migrate applied` and then the command's own object, so `json.load` on the output
+    // of a command whose whole contract is `--json` raised on the second. Decided HERE, once, for
+    // all thirty commands — a rule each booting command had to remember is a rule the next one
+    // forgets. A server's stdout stays its log stream; this is about the CLI process only.
+    // Set on EVERY dispatch, both ways: the stream is process-wide state, so `if (args.json)`
+    // alone left a JSON run's `stderr` in place for the next non-JSON one — one `x` process
+    // dispatching twice (the MCP host, a test, an embedding caller) lost its boot logs off stdout.
+    setLogStream(args.json ? 'stderr' : 'stdout');
     // The reader `CommandSpec.requiresApp` never had. Its doc said "the dispatcher enforces it" and
     // `dispatch` did not read the field at all: the guarantee held only because all 17 declaring
     // commands happen to call `requireAppRoot` themselves, so a new command that declares it and
@@ -115,7 +145,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);
-    options.write(render(result, args.json, args.flags.get('verbose') === true));
+    sinkFor(result, options)(render(result, args.json, args.flags.get('verbose') === true));
     // `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.
@@ -123,7 +153,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     return exitCodeFor(result);
   } catch (error) {
     const result = errorResult(args.command, error);
-    options.write(render(result, args.json));
+    sinkFor(result, options)(render(result, args.json));
     return 1;
   }
 }