@ultimat3/cli 23.0.0 → 25.0.0

package/src/dev-child-watch.ts

@@ -5,6 +5,10 @@
 // 100% CPU, measured at ~50 MB/s of heap growth). Found on a laptop, 2026-09-29: two children of
 // `cmd-dev-restart.live.test.ts`, six hours old, ppid 1, cwd deleted, one at 7 GB.
 //
+// Both facts and the stop itself hold on Windows: the supervisor is asked for by pid
+// (`process.kill(pid, 0)`), since a Windows child's ppid never changes, and a stop arrives as a
+// `drain` message over IPC — `kill('SIGTERM')` there is TerminateProcess, with no drain at all.
+//
 // And a stop that does not finish is finished for it. A drain is bounded by core's deadline, but a
 // loop starved by a spin like the one above reaches its timers late or never, so every stop this
 // child begins — a signal, the watch below, a restart — carries a hard exit past that bound.
@@ -29,8 +33,8 @@ export interface DevChildWatchInput {
   readonly env: Readonly<Record<string, string | undefined>>;
   /** Called once, when the child decides to leave. */
   readonly leave: (why: DevChildGone) => void;
-  /** Test seams: the defaults read the process and the disk. */
-  readonly parentPid?: () => number;
+  /** Test seams: the defaults read the process table and the disk. */
+  readonly supervisorAlive?: (pid: number) => boolean;
   readonly rootExists?: (root: string) => boolean;
   readonly intervalMs?: number;
 }
@@ -43,21 +47,46 @@ export function supervisorPid(
   return Number.isInteger(said) && said > 0 ? said : undefined;
 }
 
+/** `process.kill(pid, 0)`'s answer: delivered, or refused for permission — both mean it exists. */
+export function pidAlive(
+  pid: number,
+  kill: (pid: number, signal: 0) => void = process.kill,
+): boolean {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as { readonly code?: unknown } | null)?.code === 'EPERM';
+  }
+}
+
+/**
+ * Whether the supervisor at `pid` still runs this child. POSIX asks the ppid — immune to a reused
+ * pid, and a supervisor that died before the first tick is still caught, since the child is
+ * reparented. Windows never reparents (the ppid stays the dead supervisor's forever), so there the
+ * process table is asked directly.
+ */
+export function defaultSupervisorAlive(
+  platform: string = process.platform,
+): (pid: number) => boolean {
+  return platform === 'win32' ? (pid) => pidAlive(pid) : (pid) => process.ppid === pid;
+}
+
 /**
- * Polls both facts until one fails, then calls `leave` once and stops. Answers the stop.
- * `process.ppid` rather than a pipe from the supervisor: stdin is the terminal's (`inherit`), and
- * a supervisor that died before the first tick is still caught — its pid is never ours again.
+ * Polls both facts until one fails, then calls `leave` once and stops. Answers the stop. Polled
+ * rather than a pipe from the supervisor: stdin is the terminal's (`inherit`), and IPC closing is
+ * not a fact Bun reports to the child.
  */
 export function watchDevChild(input: DevChildWatchInput): () => void {
   const expected = supervisorPid(input.env);
-  const parent = input.parentPid ?? (() => process.ppid);
+  const alive = input.supervisorAlive ?? defaultSupervisorAlive();
   const exists = input.rootExists ?? existsSync;
   let left = false;
   const timer = setInterval(
     () => {
       if (left) return;
       const why: DevChildGone | undefined =
-        expected !== undefined && parent() !== expected
+        expected !== undefined && !alive(expected)
           ? 'supervisor'
           : exists(input.root)
             ? undefined
@@ -116,10 +145,26 @@ export function hardExit(
   };
 }
 
+/** What the supervisor sends for a stop: the signal it would have forwarded on POSIX. */
+export interface DevDrainMessage {
+  readonly type: 'x-dev-drain';
+  readonly signal: 'SIGINT' | 'SIGTERM';
+}
+
+export function isDevDrainMessage(message: unknown): message is DevDrainMessage {
+  if (typeof message !== 'object' || message === null) return false;
+  const { type, signal } = message as Record<string, unknown>;
+  return type === 'x-dev-drain' && (signal === 'SIGINT' || signal === 'SIGTERM');
+}
+
+/** The exit code a stop for `signal` answers: 128 + its number, as a shell reports it. */
+export const signalExitCode = (signal: 'SIGINT' | 'SIGTERM'): number =>
+  signal === 'SIGINT' ? 130 : 143;
+
 /**
- * The child's watch, wired to core's drain: the supervisor's death or the root's, and SIGINT or
- * SIGTERM, each begin a stop that ends within `devHardExitMs` however the drain fares. `onGone`
- * marks why, so the hold's exit can answer a code.
+ * The child's watch, wired to core's drain: the supervisor's death or the root's, SIGINT or
+ * SIGTERM, and the supervisor's `drain` message each begin a stop that ends within
+ * `devHardExitMs` however the drain fares. `onGone` marks why, so the hold's exit can answer a code.
  */
 export function startDevChildWatch(
   root: string,
@@ -128,8 +173,14 @@ export function startDevChildWatch(
 ): { readonly stopping: (code: number) => void } {
   const stopping = hardExit((code) => process.exit(code));
   // Beside core's own handlers, never instead of them: the drain is theirs, the deadline is this.
-  process.on('SIGINT', () => stopping(130));
-  process.on('SIGTERM', () => stopping(143));
+  process.on('SIGINT', () => stopping(signalExitCode('SIGINT')));
+  process.on('SIGTERM', () => stopping(signalExitCode('SIGTERM')));
+  // The supervisor's stop, on every platform: the same drain a signal begins, by message.
+  process.on('message', (message: unknown) => {
+    if (!isDevDrainMessage(message)) return;
+    stopping(signalExitCode(message.signal));
+    void drain(message.signal);
+  });
   watchDevChild({
     root,
     env,

package/src/dev-dashboard-guard.ts

@@ -0,0 +1,76 @@
+// The doors in front of `/_x` that a browser can knock on. `x dev` binds loopback, but a page the
+// developer has open can still reach it: by DNS rebinding (a hostile name that resolves to
+// 127.0.0.1, read back same-origin) and by a cross-site request to the SQL panel.
+
+import { proveSameOrigin, renderFixShellArg, UltimateError } from '@ultimat3/core';
+import type { UltimateRequest } from '@ultimat3/http';
+import { csrfBlocked, HttpError, jsonResponse, selfOrigin } from '@ultimat3/http';
+import { t } from '@ultimat3/schema';
+import { isLoopbackHostname } from './loopback-host';
+
+/** A `/_x` request named a Host that is not this machine. Never echoes the Host it was sent. */
+export class DevHostRefusedError extends UltimateError {
+  constructor(input: { devUrl: string }) {
+    super({
+      code: 'X_DEV_HOST_REFUSED',
+      cause:
+        'a /_x request named a Host that is not localhost, a *.localhost name or a loopback address — the shape of a DNS-rebinding page reading the dev dashboard',
+      fix: `curl -sS -H 'accept: application/json' ${renderFixShellArg(`${input.devUrl}/_x`, 'http://localhost:3000/_x')}`,
+    });
+  }
+}
+
+/** The Host as sent, else the one the URL was built from — Bun builds it from the header. */
+const hostnameOf = (request: UltimateRequest): string | undefined => {
+  const header = request.header('host') ?? request.url.host;
+  return URL.parse(`http://${header}`)?.hostname;
+};
+
+/**
+ * `421 Misdirected Request` for a Host that is not this machine, on every `/_x` route. The status
+ * says "not this server", which is the truth: a rebound name was never meant to reach it.
+ */
+export function hostRefusal(request: UltimateRequest, devUrl: string): Response | undefined {
+  const hostname = hostnameOf(request);
+  if (hostname !== undefined && isLoopbackHostname(hostname)) return undefined;
+  const error = new DevHostRefusedError({ devUrl });
+  return jsonResponse(
+    { ok: false, error: { code: error.code, cause: error.cause, fix: error.fix } },
+    { status: 421 },
+  );
+}
+
+/**
+ * A statement runs on a POST that came from this origin — core's `proveSameOrigin`, the rule the
+ * app's own writes and the sync upgrade answer to, asked HERE rather than left to the pipeline's
+ * CSRF stage: an app with `csrf: { mode: 'off' }` must not switch the dev database's door off with
+ * it. Neither header present is `curl`, as `checkCsrf` reads it: no page can drive that client.
+ */
+export function assertSameOrigin(request: UltimateRequest): void {
+  const origin = request.header('origin');
+  const secFetchSite = request.header('sec-fetch-site');
+  if (origin === null && secFetchSite === null) return;
+  const verdict = proveSameOrigin({
+    selfOrigins: [selfOrigin(request.url, request.ctx.https)],
+    origin,
+    secFetchSite,
+    listed: () => false,
+    listName: 'no list — /_x admits its own origin only',
+  });
+  if (!verdict.ok) throw csrfBlocked(request.pathname, verdict.reason, request.ctx.ip);
+}
+
+/** The SQL panel's one input, from a form or a JSON body — `request.body` parses either. */
+export const SQL_BODY = t.object({ sql: t.string });
+
+/**
+ * A statement on the query string is refused rather than run: a GET is what `<img src>` and a
+ * prefetch send cross-site with nobody's consent. The fix is the POST that does run it.
+ */
+export const sqlOnGet = (devUrl: string): HttpError =>
+  new HttpError({
+    code: 'X_METHOD_NOT_ALLOWED',
+    cause:
+      '/_x/db runs a statement on a same-origin POST only — a GET carrying ?sql= is what a cross-site page can send',
+    fix: `curl -sS -H 'accept: application/json' --data-urlencode 'sql=select 1' ${renderFixShellArg(`${devUrl}/_x/db`, 'http://localhost:3000/_x/db')}`,
+  });

package/src/dev-dashboard.ts

@@ -1,6 +1,6 @@
 // Mounting `@ultimat3/admin`'s `/_x` dashboard in the `x dev` process. The CLI contributes only
-// what no registry holds — a SQL runner on the live dev database, the caught outbox, the committed
-// manifest, and two panels of process facts — and projects the dashboard onto HTTP routes.
+// what no registry holds — the live dev database, the caught outbox, the committed manifest, and
+// two panels of process facts — and projects the dashboard onto HTTP routes behind a Host check.
 // A panel implemented here instead of in `admin` would be the second copy this seam exists to ban.
 
 import type {
@@ -14,16 +14,23 @@ import type {
   SqlResult,
   StatementLoopFact,
 } from '@ultimat3/admin/dev';
-import { DEV_BASE_PATH, DEV_PANELS, defaultDevSources, devDashboard } from '@ultimat3/admin/dev';
+import {
+  DEV_BASE_PATH,
+  DEV_PANELS,
+  defaultDevSources,
+  devDashboard,
+  readOnlySql,
+} from '@ultimat3/admin/dev';
 import { recentInvalidations } from '@ultimat3/cache';
 import type { Role } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { json as jsonResponse } from '@ultimat3/http';
+import { jsonResponse } from '@ultimat3/http';
 import type { MemoryMailDriver } from '@ultimat3/mail';
 import { isMemoryDriver } from '@ultimat3/mail';
 import type { Manifest } from '@ultimat3/manifest';
 import { appManifest, readAppManifest } from './app-manifest';
 import { appBoundaryFindings } from './boundary-findings';
+import { assertSameOrigin, hostRefusal, SQL_BODY, sqlOnGet } from './dev-dashboard-guard';
 import type { StatementLedger } from './dev-n-plus-one';
 import { devPolicyMatrix } from './dev-policy';
 import type { TraceRecorder } from './dev-traces';
@@ -31,6 +38,7 @@ import type { Finding } from './output';
 import type { DevServices } from './runtime-bindings';
 import type { RunningServices } from './runtime-services';
 import { loopFacts } from './statement-loop';
+import { styleBundle } from './style-bundle';
 
 export interface DevStatus {
   readonly url: string;
@@ -53,24 +61,6 @@ export interface DevDashboardInput {
   readonly statements?: StatementLedger | undefined;
 }
 
-/**
- * Read-only is already enforced by `assertReadOnly` inside `dbPanel`, before `runSql` is ever
- * reached. A second gate here would be a second authz: two places to update when what the panel
- * allows changes, and one of them would eventually disagree.
- */
-async function runSql(input: DevDashboardInput, sql: string): Promise<SqlResult> {
-  const started = performance.now();
-  const rows = await input.runtime.db.query<Readonly<Record<string, unknown>>>({
-    text: sql,
-    values: [],
-  });
-  const elapsedMs = Math.round(performance.now() - started);
-  // Columns come from the first row because the driver returns objects, not a described result
-  // set; no rows means no columns to name, which the panel renders as an empty grid.
-  const columns = Object.keys(rows[0] ?? {});
-  return { columns, rows: rows.map((row) => columns.map((column) => row[column])), elapsedMs };
-}
-
 /** `MailMessage.locale` is non-optional in `@ultimat3/mail`, so the panel never has to guess. */
 function mailFacts(outbox: MemoryMailDriver): readonly MailFact[] {
   return outbox.outbox().map((entry) => ({
@@ -137,9 +127,13 @@ export function devSources(input: DevDashboardInput): DevSources {
   // the messages are at the provider, so the hook is omitted rather than answered with `[]` —
   // an empty outbox claims nobody was mailed, which is a different and unearned answer.
   const outbox = isMemoryDriver(input.runtime.mail) ? input.runtime.mail : undefined;
+  // `dbPanel`'s `assertReadOnly` is the parse guard; `readOnlySql` is the server saying no — its own
+  // `BEGIN READ ONLY` that always rolls back, a statement timeout and a row ceiling. The plain
+  // `db.query` it replaces ran whatever the guard let through with the app's own credentials.
+  const runSql = readOnlySql(input.runtime.db);
   return defaultDevSources({
     hooks: {
-      runSql: (sql: string): Promise<SqlResult> => runSql(input, sql),
+      runSql: (sql: string): Promise<SqlResult> => runSql(sql),
       ...(outbox === undefined
         ? {}
         : { mail: (): Promise<readonly MailFact[]> => Promise.resolve(mailFacts(outbox)) }),
@@ -222,8 +216,13 @@ const notClaimed = (path: string): Response =>
     { status: 404 },
   );
 
-const devRoute = (path: string, name: string, handler: Route['handler']): Route => ({
-  method: 'GET',
+const devRoute = (
+  path: string,
+  name: string,
+  handler: Route['handler'],
+  method: 'GET' | 'POST' = 'GET',
+): Route => ({
+  method,
   path,
   // Public: /_x exists to be read without credentials by whatever drives the dev loop, and
   // `devDashboard` refuses to construct at all outside development.
@@ -232,9 +231,10 @@ const devRoute = (path: string, name: string, handler: Route['handler']): Route
 });
 
 /**
- * One route for the base path plus one per panel, because the router matches exact paths. The
- * dashboard is built once — its sources close over this process, and rebuilding per request would
- * re-run `assertDevOnly` on every hit for no new answer.
+ * One route for the base path plus one per panel, because the router matches exact paths, and a
+ * `POST` for the SQL panel — the only `/_x` read that runs something. The dashboard is built once
+ * — its sources close over this process, and rebuilding per request would re-run `assertDevOnly`
+ * on every hit for no new answer. Every route answers this machine's Host only.
  */
 export function devDashboardRoutes(input: DevDashboardInput): readonly Route[] {
   const panels = devPanels(input);
@@ -242,16 +242,42 @@ export function devDashboardRoutes(input: DevDashboardInput): readonly Route[] {
     basePath: DEV_BASE_PATH,
     panels,
     sources: devSources(input),
+    // The drawn tabs render ui's components, whose rules ride the `app/` surface's bundle — the
+    // same URL an `app/` document links, asked per request because a rebuild moves the hash.
+    stylesheetHref: () => styleBundle().hrefFor('app'),
     ...(input.env === undefined ? {} : { env: input.env }),
   });
 
-  const handler = async (request: UltimateRequest): Promise<Response> =>
-    (await dashboard.handle(request.raw)) ?? notClaimed(request.pathname);
+  const sqlPath = `${DEV_BASE_PATH}/db`;
+  const handler = async (request: UltimateRequest): Promise<Response> => {
+    const devUrl = input.status().url;
+    const refused = hostRefusal(request, devUrl);
+    if (refused !== undefined) return refused;
+    if (request.pathname === sqlPath && request.url.searchParams.has('sql')) throw sqlOnGet(devUrl);
+    return (await dashboard.handle(request.raw)) ?? notClaimed(request.pathname);
+  };
+  // The statement moves from the body onto the panel's own parameter, server side: `dbPanel`
+  // reads `sql` off the query, and this is the one caller allowed to put it there.
+  const runStatement = async (request: UltimateRequest): Promise<Response> => {
+    const refused = hostRefusal(request, input.status().url);
+    if (refused !== undefined) return refused;
+    assertSameOrigin(request);
+    const { sql } = await request.body(SQL_BODY);
+    const target = new URL(request.url);
+    target.searchParams.set('sql', sql);
+    // A GET carries no body, so the body's own headers stay behind; `accept` and the rest ride.
+    const headers = new Headers(request.headers);
+    headers.delete('content-type');
+    headers.delete('content-length');
+    const forwarded = new Request(target, { headers });
+    return (await dashboard.handle(forwarded)) ?? notClaimed(request.pathname);
+  };
 
   return [
     devRoute(DEV_BASE_PATH, 'dev._x', handler),
     ...panels.map((panel) =>
       devRoute(`${DEV_BASE_PATH}/${panel.key}`, `dev._x.${panel.key}`, handler),
     ),
+    devRoute(sqlPath, 'dev._x.db.run', runStatement, 'POST'),
   ];
 }

package/src/dev-lock.ts

@@ -14,10 +14,11 @@
 // 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 { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+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 { portPairAfter } from './flag-number';
 import { quoteArg } from './shell-quote';
 
 /** Where the running dev server records itself, inside the state directory it already owns. */
@@ -141,6 +142,26 @@ export class DevLockUnreadableError extends UltimateError {
   }
 }
 
+/**
+ * The state directory refused the claim itself: it could not be created, the lock could not be
+ * staged in it, or the filesystem would not hard-link the staged file into place. None of that is
+ * another `x dev` — only `EEXIST` is — and escaping raw it reached the operator as
+ * `X_CLI_UNEXPECTED` with `fix: x doctor --json`, which says nothing about `.x/`.
+ */
+export class DevStateUnwritableError extends UltimateError {
+  constructor(input: { readonly stateDir: string; readonly error: unknown }) {
+    // Read the field, never cast and dereference: `unknown` is what a catch hands over.
+    const errno = stringField(input.error, 'code') ?? 'an unreported errno';
+    super({
+      code: 'X_DEV_STATE_UNWRITABLE',
+      cause: `${input.stateDir} could not be created, written, or hard-linked into (${errno}), so x dev cannot take its lock — a read-only checkout, a .x/ this user may not write, or a filesystem without hard links`,
+      fix: `ls -ld ${quoteArg(input.stateDir)}   # make it writable by this user, on a filesystem that supports hard links, then re-run x dev`,
+      meta: { stateDir: input.stateDir, errno },
+      sourceError: input.error,
+    });
+  }
+}
+
 /** Whatever is listening, as far as the OS will say. Both fields absent when it will not say. */
 export interface PortHolder {
   readonly pid?: number;
@@ -150,7 +171,8 @@ export interface PortHolder {
 
 /**
  * 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.
+ * 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.
@@ -158,7 +180,7 @@ export interface PortHolder {
  * 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 neither still gets the refusal, just without a pid in it.
+ * 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> => {
@@ -184,9 +206,38 @@ export const portHolder = async (port: number, runner: Runner = exec): Promise<P
   if (pid !== undefined && /^\d+$/.test(pid)) {
     return command === undefined ? { pid: Number(pid) } : { command, pid: Number(pid) };
   }
-  return {};
+
+  // 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
@@ -220,12 +271,6 @@ export class DevPortInUseError extends UltimateError {
   }
 }
 
-/**
- * The next port to suggest. Never `port + 1` at the top of the range — 65536 is not a port, and a
- * `fix:` that cannot run is the failure this whole module exists to end.
- */
-export const suggestPort = (port: number): number => (port >= 65535 ? port - 1 : port + 1);
-
 /**
  * Is anything listening? A successful bind-then-close is the only answer that does not lie.
  *
@@ -246,33 +291,46 @@ export const isPortBound = (port: number, hostname: string): boolean => {
   }
 };
 
+/** A sibling of the lock, unique to this process and call, where its bytes are staged. */
+const stagingPath = (path: string): string =>
+  `${path}.${process.pid}.${crypto.randomUUID().slice(0, 8)}.tmp`;
+
+const lockText = (lock: DevLock): string => `${JSON.stringify(lock, null, 2)}\n`;
+
 /**
  * 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.
+ * Written whole to a staging file first, then `linkSync`ed into place: the link is the create AND
+ * the exclusivity in ONE syscall (`EEXIST` when the name is taken), so two boots racing this cannot
+ * both come back `true` — and the lock path never exists without its contents. It was `openSync(
+ * path, 'wx')` and THEN a write; a racing preflight that read the file between the two parsed an
+ * empty lock as stale, unlinked the live claim and took the slot itself.
  *
- * 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.
+ * Only `EEXIST` is "someone else has it". Any other refusal of the staging write or the link — a
+ * `.x/` this user may not write, a filesystem without hard links — is `X_DEV_STATE_UNWRITABLE`
+ * naming the directory and the errno, the original kept as its `sourceError`.
  */
-function claimExclusive(path: string, lock: DevLock): boolean {
-  let fd: number;
+function claimExclusive(stateDir: string, path: string, lock: DevLock): boolean {
+  const staged = stagingPath(path);
   try {
-    fd = openSync(path, 'wx');
+    writeFileSync(staged, lockText(lock));
   } catch (error) {
-    // Same rule as `isProcessAlive` above: read the field, never cast and dereference.
-    if (stringField(error, 'code') === 'EEXIST') return false;
-    throw error;
+    throw new DevStateUnwritableError({ stateDir, error });
   }
   try {
-    writeFileSync(fd, `${JSON.stringify(lock, null, 2)}\n`);
+    linkSync(staged, path);
+    return true;
+  } catch (error) {
+    // Same rule as `isProcessAlive` above: read the field, never cast and dereference.
+    if (stringField(error, 'code') === 'EEXIST') return false;
+    throw new DevStateUnwritableError({ stateDir, error });
   } finally {
-    closeSync(fd);
+    try {
+      unlinkSync(staged);
+    } catch {
+      // Already gone; the staging name is unique to this call, so nothing else can need it.
+    }
   }
-  return true;
 }
 
 /** Whatever is on disk right now, or `null` if it is absent or half-written. */
@@ -326,7 +384,11 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
   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 });
+  try {
+    mkdirSync(input.stateDir, { recursive: true });
+  } catch (error) {
+    throw new DevStateUnwritableError({ stateDir: input.stateDir, error });
+  }
   const mine: DevLock = {
     pid: process.pid,
     port: input.port,
@@ -337,7 +399,7 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
   };
   let clearedStale = false;
 
-  if (!claimExclusive(path, mine)) {
+  if (!claimExclusive(input.stateDir, path, mine)) {
     const held = await readLock(path);
     if (held !== null && alive(held.pid)) {
       throw new DevAlreadyRunningError({
@@ -354,7 +416,7 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
       // Already gone, or not ours to remove. The claim below is what decides.
     }
     clearedStale = true;
-    if (!claimExclusive(path, mine)) {
+    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.
@@ -379,7 +441,9 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
     release();
     throw new DevPortInUseError({
       port: input.port,
-      suggestion: suggestPort(input.port),
+      // `portPairAfter`, never `port + 1`: `x dev` binds a PAIR, so the holder is most often
+      // another `x dev` whose sync role already sits on `port + 1`.
+      suggestion: portPairAfter(input.port),
       holder: await (input.holder ?? portHolder)(input.port),
     });
   }
@@ -391,7 +455,12 @@ 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> => {
-  await Bun.write(lockPath(stateDir), `${JSON.stringify(lock, null, 2)}\n`);
+  // 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));
+  renameSync(staged, path);
 };
 
 /** Remove it. Safe to call twice — shutdown paths overlap, and a throw here would mask the real one. */

package/src/dev-rebuild.ts

@@ -0,0 +1,80 @@
+// The `x dev` reload: one save in, the manifest, the findings and the island bundles rebuilt as
+// one generation, the ISR store emptied, and a save this process cannot serve handed to the
+// supervisor as a restart. Coalesced, so a tick arriving mid-build is one trailing rebuild.
+
+import type { Manifest } from '@ultimat3/manifest';
+import type { IsrController } from '@ultimat3/render/server';
+import { appManifest } from './app-manifest';
+import type { StalePin } from './app-reload-graph';
+import { takeStalePins } from './app-reload-graph';
+import type { ReloadTrigger } from './dev-reload';
+import { coalesceReloads } from './dev-reload';
+import { restartFinding } from './dev-supervisor';
+import type { IslandBundle } from './island-bundle';
+import { buildIslands } from './island-bundle';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+export interface DevState {
+  manifest: Manifest;
+  reloads: number;
+  /** A save that will not build. Replaced on every attempt, so a fixed file clears it. */
+  reloadFinding: Finding | undefined;
+  /**
+   * Modules that would not import and primitives that would not register, as of the LAST scan —
+   * the boot's, then each rebuild's. A page saved with a syntax error is a finding here until the
+   * save that fixes it, and the boot's list alone would never show it.
+   */
+  appFindings: readonly Finding[];
+  /**
+   * The client entries, rebuilt on the same tick as the manifest. An island is the one module this
+   * process never imports, so a fresh `Bun.build` is the whole of its reload. The route module
+   * beside it is re-imported by that same scan (`app-load.ts`) — the two are one generation, or
+   * a save serves a new island under an old page, which is what it did until 2026-09-07.
+   */
+  islands: IslandBundle;
+}
+
+/** What a rebuild reports to, read off `StartDevOptions`. */
+export interface DevRebuildOptions {
+  readonly root: string;
+  readonly onReload?: (file: string, durationMs: number) => void;
+  readonly onRestart?: (pins: readonly StalePin[]) => void;
+}
+
+/** The watcher's `onChange`: rebuild `state` for the saved `file`, never rejecting. */
+export function devRebuilder(
+  options: DevRebuildOptions,
+  state: DevState,
+  isr: IsrController,
+): 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();
+      const [{ manifest, findings }, islands] = await Promise.all([
+        appManifest(options.root),
+        buildIslands(options.root),
+      ]);
+      state.manifest = manifest;
+      state.appFindings = findings;
+      state.islands = islands;
+      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();
+      state.reloadFinding =
+        pins.length > 0 && options.onRestart === undefined
+          ? restartFinding(options.root, pins)
+          : undefined;
+      if (pins.length > 0 && options.onRestart !== undefined) options.onRestart(pins);
+      else options.onReload?.(file, Math.round(performance.now() - started));
+    },
+    // Same rule as a module that will not import: a save the manifest cannot be rebuilt from is
+    // a finding on `/_x`, never an unhandled rejection that takes the dev server down.
+    (error: unknown, file: string) => {
+      state.reloadFinding = { ...findingFrom(error), at: file };
+    },
+  );
+}