@ultimat3/cli 22.11.0 → 22.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.11.0",
+  "version": "22.13.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.11.0",
-    "@ultimat3/admin": "22.11.0",
-    "@ultimat3/ai": "22.11.0",
-    "@ultimat3/auth": "22.11.0",
-    "@ultimat3/cache": "22.11.0",
-    "@ultimat3/core": "22.11.0",
-    "@ultimat3/db": "22.11.0",
-    "@ultimat3/entity": "22.11.0",
-    "@ultimat3/flags": "22.11.0",
-    "@ultimat3/http": "22.11.0",
-    "@ultimat3/i18n": "22.11.0",
-    "@ultimat3/jobs": "22.11.0",
-    "@ultimat3/mail": "22.11.0",
-    "@ultimat3/manifest": "22.11.0",
-    "@ultimat3/mcp": "22.11.0",
-    "@ultimat3/money": "22.11.0",
-    "@ultimat3/notify": "22.11.0",
-    "@ultimat3/policy": "22.11.0",
-    "@ultimat3/pwa": "22.11.0",
-    "@ultimat3/query": "22.11.0",
-    "@ultimat3/realtime": "22.11.0",
-    "@ultimat3/render": "22.11.0",
-    "@ultimat3/schema": "22.11.0",
-    "@ultimat3/seo": "22.11.0",
-    "@ultimat3/storage": "22.11.0",
-    "@ultimat3/testing": "22.11.0",
-    "@ultimat3/time": "22.11.0",
+    "@ultimat3/action": "22.13.0",
+    "@ultimat3/admin": "22.13.0",
+    "@ultimat3/ai": "22.13.0",
+    "@ultimat3/auth": "22.13.0",
+    "@ultimat3/cache": "22.13.0",
+    "@ultimat3/core": "22.13.0",
+    "@ultimat3/db": "22.13.0",
+    "@ultimat3/entity": "22.13.0",
+    "@ultimat3/flags": "22.13.0",
+    "@ultimat3/http": "22.13.0",
+    "@ultimat3/i18n": "22.13.0",
+    "@ultimat3/jobs": "22.13.0",
+    "@ultimat3/mail": "22.13.0",
+    "@ultimat3/manifest": "22.13.0",
+    "@ultimat3/mcp": "22.13.0",
+    "@ultimat3/money": "22.13.0",
+    "@ultimat3/notify": "22.13.0",
+    "@ultimat3/policy": "22.13.0",
+    "@ultimat3/pwa": "22.13.0",
+    "@ultimat3/query": "22.13.0",
+    "@ultimat3/realtime": "22.13.0",
+    "@ultimat3/render": "22.13.0",
+    "@ultimat3/schema": "22.13.0",
+    "@ultimat3/seo": "22.13.0",
+    "@ultimat3/storage": "22.13.0",
+    "@ultimat3/testing": "22.13.0",
+    "@ultimat3/time": "22.13.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-reload-graph.ts

@@ -16,7 +16,9 @@
 // A module that DEFINES a primitive is PINNED and never leaves the registry: its exports are held
 // by every importer and by a registry that refuses a second definition of one name (an entity is
 // `X_ENTITY_DUPLICATE`; a second action instance is a handler nobody routes to). The closure stops
-// at a pinned module, and an edit to one still needs a restart — exactly what it needed before.
+// at a pinned module — and RECORDS it (`takeStalePins`): a pinned module above a change still holds
+// the old instance of what changed (a slice's service under its query, an admin page's view under
+// `defineAdmin`), so only a new process serves the save. `x dev` restarts on it (`dev-supervisor.ts`).
 
 // why: Bun ships no path API; import specifiers resolve against the importing file's directory.
 import { dirname, resolve } from 'node:path';
@@ -37,6 +39,27 @@ const nodes = new Map<string, Node>();
 /** Reverse edges: file → the files that import it. */
 const importers = new Map<string, Set<string>>();
 const pinned = new Set<string>();
+
+/** A pinned module that still holds the old instance of `changed` — or IS `changed`. */
+export interface StalePin {
+  /** The saved file, absolute. */
+  readonly changed: string;
+  /** The module that defines a primitive and was not re-evaluated, absolute. */
+  readonly pinned: string;
+}
+
+/** What the last rescans' closures stopped at, until `takeStalePins` reads it. */
+let stale: StalePin[] = [];
+
+/**
+ * Every pinned module a rescan since the last call could not refresh, sorted by pinned path, and
+ * forgets them. Empty: everything the saves reached was re-evaluated and the process serves it.
+ */
+export function takeStalePins(): readonly StalePin[] {
+  const taken = stale;
+  stale = [];
+  return taken;
+}
 /**
  * Edges cost a transpile scan and a resolve per import (~300 ms over notificado.co's 1200 modules),
  * so only the one process that rescans pays it: `x dev` turns this on before its first scan. Off,
@@ -54,6 +77,7 @@ export function resetReloadGraph(): void {
   nodes.clear();
   importers.clear();
   pinned.clear();
+  stale = [];
 }
 
 /** Marks a module that defines a primitive: never evicted, and the closure stops at it. */
@@ -185,18 +209,36 @@ async function changedFiles(root: string): Promise<string[]> {
   return changed;
 }
 
-/** `changed` and everything above it, stopping at — and excluding — every pinned module. */
+/**
+ * `changed` and everything above it, stopping at — and excluding — every pinned module. Each
+ * pinned module a walk stopped at is recorded against the change that reached it, once.
+ */
 function closure(changed: readonly string[]): Set<string> {
   const dirty = new Set<string>();
-  const stack = changed.filter((path) => !pinned.has(path));
-  while (stack.length > 0) {
-    const path = stack.pop();
-    if (path === undefined || dirty.has(path)) continue;
-    dirty.add(path);
-    for (const importer of importers.get(path) ?? []) {
-      if (!pinned.has(importer)) stack.push(importer);
+  const reached = new Map<string, string>();
+  for (const origin of changed) {
+    if (pinned.has(origin)) {
+      if (!reached.has(origin)) reached.set(origin, origin);
+      continue;
+    }
+    const seen = new Set<string>();
+    const stack = [origin];
+    while (stack.length > 0) {
+      const path = stack.pop();
+      if (path === undefined || seen.has(path)) continue;
+      seen.add(path);
+      dirty.add(path);
+      for (const importer of importers.get(path) ?? []) {
+        if (!pinned.has(importer)) stack.push(importer);
+        else if (!reached.has(importer)) reached.set(importer, origin);
+      }
     }
   }
+  const held = new Set(stale.map((entry) => entry.pinned));
+  const found = [...reached]
+    .filter(([module]) => !held.has(module))
+    .map(([module, origin]) => ({ changed: origin, pinned: module }));
+  stale = [...stale, ...found].sort((a, b) => (a.pinned < b.pinned ? -1 : 1));
   return dirty;
 }
 

package/src/bin.ts

@@ -33,6 +33,20 @@ if (local !== undefined) {
   process.exit(await child.exited);
 }
 
+// `x dev` supervises a child that serves (`dev-supervisor.ts`): a save that reaches a module which
+// defines a primitive is a restart, since no re-import in one process can serve it. After the
+// handoff above, so the supervisor and its children are the app's own CLI.
+// Imported only for `dev`: every other command's process must not load, or register, anything more.
+if (Bun.argv[2] === 'dev') {
+  const { devSupervision, freeDevPort, superviseDev } = await import('./dev-supervisor');
+  const supervision = devSupervision(Bun.argv.slice(2), Bun.env, freeDevPort);
+  if (supervision !== undefined) {
+    process.exit(
+      await superviseDev({ bin: import.meta.path, argv: supervision.argv, env: Bun.env }),
+    );
+  }
+}
+
 const code = await dispatch({
   argv: Bun.argv.slice(2),
   cwd: process.cwd(),

package/src/budgets.ts

@@ -60,8 +60,9 @@ export interface BuildStats {
  * rule stops being read as a measurement. `.x/` survives across framework upgrades, and
  * `examples/dummy` was charged 250 B for `/x-sw-register.js` by a file written before
  * `FRAMEWORK_SCRIPTS` exempted it. `2`: that exemption and the page-boot decision (ledger #28).
+ * `3`: an island entry's imported chunks are charged, each once per document (shared chunks).
  */
-export const BUILD_STATS_RULES = 2;
+export const BUILD_STATS_RULES = 3;
 
 const chainOf = (stats: RouteStats): string =>
   stats.heaviestChain === undefined ? 'unknown import chain' : stats.heaviestChain.join(' -> ');
@@ -252,6 +253,31 @@ const carriesJson = (attrs: string): boolean => {
  */
 const ENTRY_ATTR = /\sdata-x-entry="(?<url>[^"]*)"/g;
 
+/**
+ * Static imports and `import()` both. A chunk reached by `import()` was INLINED into its island
+ * before islands were split, so charging it keeps a route's number what it was; and it is fetched
+ * the moment the island needs it, which is before the page does what it was loaded for.
+ */
+const LOADS: ReadonlySet<string> = new Set(['import-statement', 'dynamic-import']);
+
+/** Same-origin paths `code`, served at `url`, makes the browser load. Cross-origin and bare are not this build's. */
+function loadedBy(url: string, code: string): readonly string[] {
+  let imports: readonly { readonly path: string; readonly kind: string }[];
+  try {
+    imports = new Bun.Transpiler({ loader: 'js' }).scanImports(code);
+  } catch {
+    // A file that does not parse as JavaScript imports nothing this gate can name; its own bytes
+    // are already charged.
+    return [];
+  }
+  const base = new URL(url, 'https://artifact.invalid');
+  return imports
+    .filter((one) => LOADS.has(one.kind) && /^\.{0,2}\//.test(one.path))
+    .map((one) => new URL(one.path, base))
+    .filter((target) => target.origin === base.origin)
+    .map((target) => target.pathname);
+}
+
 /** One executable module the document names, and what it weighs on disk. */
 export interface MeasuredEntry {
   readonly url: string;
@@ -337,7 +363,8 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     if (!url.startsWith('/') || fetched.has(url)) return;
     fetched.add(url);
     const file = Bun.file(join(out, url.slice(1)));
-    const bytes = (await file.exists()) ? file.size : 0;
+    const exists = await file.exists();
+    const bytes = exists ? file.size : 0;
     // Counted and set aside, not skipped: the bytes are real and a reader is owed the number.
     // Kept out of `entries` as well as out of `jsBytes`, because `entries` is what a finding reads
     // to name the heaviest import — and on a fresh scaffold every route's `heaviestChain` was
@@ -348,6 +375,12 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     }
     entries.push({ url, bytes });
     jsBytes += bytes;
+    // And every file THAT one loads: an island entry imports its shared chunks (`island-link.ts`),
+    // and each is a fetch the browser makes before the island is whole. Through `weigh`, so a chunk
+    // two islands share is charged once and a cycle ends at the first repeat.
+    if (exists) {
+      for (const next of loadedBy(url, await file.text())) await weigh(next);
+    }
   };
 
   for (const match of html.matchAll(SCRIPT_TAG)) {

package/src/cmd-dev.ts

@@ -16,7 +16,8 @@ import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { createIsrController } from '@ultimat3/render/server';
 import { loadSignInPath } from './app-auth';
 import { appManifest } from './app-manifest';
-import { enableReloadTracking } from './app-reload-graph';
+import type { StalePin } from './app-reload-graph';
+import { enableReloadTracking, takeStalePins } from './app-reload-graph';
 import { requireAppRoot } from './app-root';
 import { loadAppRuntime } from './app-runtime';
 import { devSpec } from './cmd-dev-spec';
@@ -29,6 +30,7 @@ import { createStatementLedger } from './dev-n-plus-one';
 import { devPortFor } from './dev-port';
 import { coalesceReloads } from './dev-reload';
 import { devRouteTable } from './dev-route-table';
+import { childRestart, restartFinding } from './dev-supervisor';
 import { createTraceRecorder } from './dev-traces';
 import { watchTree } from './dev-watch-tree';
 import { holdUntilShutdown } from './hold';
@@ -108,6 +110,12 @@ export interface StartDevOptions {
   readonly env: Readonly<Record<string, string | undefined>>;
   readonly roles?: readonly Role[];
   readonly onReload?: (file: string, durationMs: number) => void;
+  /**
+   * A save reached a module that defines a primitive, so this process cannot serve it
+   * (`takeStalePins`). Given, it is called INSTEAD of `onReload` — `x dev`'s child drains and exits
+   * for its supervisor to boot a fresh one. Absent, the save is `X_DEV_RESTART_REQUIRED` on `/_x`.
+   */
+  readonly onRestart?: (pins: readonly StalePin[]) => void;
 }
 
 /**
@@ -294,8 +302,14 @@ async function bootDev(
       state.islands = islands;
       for (const path of isr.store().paths()) isr.store().delete(path);
       state.reloads += 1;
-      state.reloadFinding = undefined;
-      options.onReload?.(file, Math.round(performance.now() - started));
+      // 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.
@@ -375,6 +389,7 @@ export const devCommand: CliCommand = {
     // The directory is CLAIMED from here down, so a boot that throws has to give it back — the
     // `releaseBoot` shape, with one acquisition. Without it the first failed `x dev` in a shell
     // refuses every later one with a pid that is no longer running.
+    const restart = childRestart(root, ctx.env);
     const server = await startDev({
       root,
       port,
@@ -384,6 +399,8 @@ export const devCommand: CliCommand = {
         if (!ctx.args.json)
           process.stdout.write(`${msg('cli.dev.hmr', { file, ms: durationMs })}\n`);
       },
+      // Supervised, a save this process cannot serve is a drain and an exit for a fresh child.
+      ...restart.options,
     }).catch((error: unknown) => {
       release();
       throw error;
@@ -461,12 +478,17 @@ export const devCommand: CliCommand = {
     // directory locked by a process that no longer exists.
     return {
       ...result,
-      hold: holdUntilShutdown('dev', async () => {
-        // The lock first: a stop() that throws must not leave a file claiming this pid still owns
-        // the directory, because the next boot would then refuse for a process that is gone.
-        clearLock(services.stateDir);
-        await server.stop();
-      }),
+      hold: holdUntilShutdown(
+        'dev',
+        async () => {
+          // The lock first: a stop() that throws must not leave a file claiming this pid still owns
+          // the directory, because the next boot would then refuse for a process that is gone.
+          clearLock(services.stateDir);
+          await server.stop();
+        },
+        // Released — the port, the lock and the embedded database are free for the next child.
+        { exit: restart.exit },
+      ),
     };
   },
 };

package/src/dev-child-watch.ts

@@ -0,0 +1,144 @@
+// A supervised `x dev` child that outlives what it serves stops itself. Two facts nothing else in
+// the child watched: its SUPERVISOR is gone (SIGKILLed, so it forwarded nothing — the child was
+// reparented to init and served forever), and its APP ROOT is gone (the jobs worker, the outbox
+// relay and the scheduler then poll an embedded database whose directory no longer exists, at
+// 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.
+//
+// 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.
+
+import { existsSync } from 'node:fs'; // why: one synchronous stat per tick; Bun has no sync exists.
+import { drain, drainDeadlineMs, ERROR_DOCS_URL, finiteCount, logger } from '@ultimat3/core';
+import { MIN_RELEASE_MS } from './hold';
+
+/** Set on the child by the supervisor: its own pid, so a child started after it died still knows. */
+export const DEV_SUPERVISOR_PID_ENV = 'ULTIMATE_DEV_SUPERVISOR_PID';
+
+/** How often the child asks. A second: a dead supervisor's child is gone about a second later. */
+export const DEV_CHILD_WATCH_MS = 1_000;
+
+/** Past the drain's own deadline and `hold.ts`'s release floor, a stop is not going to finish. */
+export const devHardExitMs = (): number => drainDeadlineMs() + MIN_RELEASE_MS + 5_000;
+
+export type DevChildGone = 'supervisor' | 'root';
+
+export interface DevChildWatchInput {
+  readonly root: string;
+  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;
+  readonly rootExists?: (root: string) => boolean;
+  readonly intervalMs?: number;
+}
+
+/** The supervisor's pid, or `undefined` when this process was not started by one. */
+export function supervisorPid(
+  env: Readonly<Record<string, string | undefined>>,
+): number | undefined {
+  const said = Number(env[DEV_SUPERVISOR_PID_ENV]);
+  return Number.isInteger(said) && said > 0 ? said : undefined;
+}
+
+/**
+ * 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.
+ */
+export function watchDevChild(input: DevChildWatchInput): () => void {
+  const expected = supervisorPid(input.env);
+  const parent = input.parentPid ?? (() => process.ppid);
+  const exists = input.rootExists ?? existsSync;
+  let left = false;
+  const timer = setInterval(
+    () => {
+      if (left) return;
+      const why: DevChildGone | undefined =
+        expected !== undefined && parent() !== expected
+          ? 'supervisor'
+          : exists(input.root)
+            ? undefined
+            : 'root';
+      if (why === undefined) return;
+      left = true;
+      clearInterval(timer);
+      input.leave(why);
+    },
+    finiteCount('watchDevChild', 'intervalMs', input.intervalMs ?? DEV_CHILD_WATCH_MS, 1),
+  );
+  // Never the reason the process is alive — the hold is, and a watch outliving it would be a leak.
+  timer.unref();
+  return () => {
+    left = true;
+    clearInterval(timer);
+  };
+}
+
+/** The line the child leaves on stderr (fd 1 may be `--json`'s one document). */
+export function reportGone(root: string, why: DevChildGone): void {
+  if (why === 'root') {
+    logger.error('X_DEV_ROOT_GONE', {
+      code: 'X_DEV_ROOT_GONE',
+      cause: `${root}, the app root this x dev serves, no longer exists — nothing is left to serve, so it stops instead of polling a database whose directory is gone`,
+      fix: 'x dev   # from the app root, once it exists again (restored, re-cloned or moved back)',
+      docs: ERROR_DOCS_URL,
+    });
+    return;
+  }
+  logger.warn('dev.supervisor.gone', {
+    cause:
+      'the x dev supervisor that started this child exited without stopping it (a SIGKILL cannot be forwarded), so the child stops itself',
+  });
+}
+
+/**
+ * One hard exit, armed by the first stop and never disarmed: it is NOT unref'd, because it is the
+ * one timer that must still fire once everything else is done or stuck. `exit` is the test seam.
+ */
+export function hardExit(
+  exit: (code: number) => void,
+  afterMs: () => number = devHardExitMs,
+): (code: number) => void {
+  let armed = false;
+  return (code: number): void => {
+    if (armed) return;
+    armed = true;
+    const ms = afterMs();
+    setTimeout(() => {
+      logger.warn('dev.stop.forced', {
+        cause: `x dev was still stopping ${String(ms)}ms after it began, so it exits without finishing`,
+      });
+      exit(code);
+    }, ms);
+  };
+}
+
+/**
+ * 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.
+ */
+export function startDevChildWatch(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  onGone: (why: DevChildGone) => void,
+): { 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));
+  watchDevChild({
+    root,
+    env,
+    leave: (why) => {
+      reportGone(root, why);
+      onGone(why);
+      stopping(why === 'root' ? 1 : 0);
+      void drain(why === 'root' ? 'dev-root-gone' : 'dev-supervisor-gone');
+    },
+  });
+  return { stopping };
+}

package/src/dev-live-fixture.ts

@@ -0,0 +1,122 @@
+// The `x dev` live tests' process discipline, in one place: spawn the supervisor, read its two
+// streams, and — on every path, a failing one included — reap every process it started and prove
+// none is left. Two children of `cmd-dev-restart.live.test.ts` ran for six hours with ppid 1 and a
+// deleted cwd because the test's `finally` SIGKILLed the supervisor, which cannot forward a signal
+// it never gets, and nothing then looked for what it had started (2026-09-29).
+
+import { readdirSync, readlinkSync } from 'node:fs'; // why: /proc is read synchronously; Bun has no readlink.
+
+/** One pump per stream — reading a stream twice closes its reader under the first `for await`. */
+export function pump(stream: ReadableStream<Uint8Array>): { seen: () => string } {
+  const decoder = new TextDecoder();
+  let seen = '';
+  void (async () => {
+    for await (const chunk of stream) seen += decoder.decode(chunk, { stream: true });
+  })();
+  return { seen: () => seen };
+}
+
+/** Poll the buffer until `marker` shows up. The caller's own timeout is the deadline. */
+export async function waitFor(output: { seen: () => string }, marker: string): Promise<string> {
+  for (;;) {
+    const seen = output.seen();
+    if (seen.includes(marker)) return seen;
+    await Bun.sleep(25);
+  }
+}
+
+/** Whether `pid` is still a process — signal 0 delivers nothing and only asks. */
+export function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Every descendant of `pid`, depth first — asked while `pid` lives, or its children are init's. */
+export function descendantsOf(pid: number): readonly number[] {
+  const out = Bun.spawnSync(['pgrep', '-P', String(pid)]).stdout.toString();
+  const children = out
+    .split('\n')
+    .map((line) => Number(line.trim()))
+    .filter((child) => Number.isInteger(child) && child > 0);
+  return children.flatMap((child) => [child, ...descendantsOf(child)]);
+}
+
+/**
+ * Every process whose cwd is `dir` — a deleted one included, which Linux spells `<dir> (deleted)`.
+ * The one question that finds an orphan after its parent is gone, when no process tree reaches it.
+ * Empty where there is no `/proc` (macOS): the descendant walk is then the whole answer.
+ */
+export function processesIn(dir: string): readonly number[] {
+  let pids: readonly string[];
+  try {
+    pids = readdirSync('/proc').filter((name) => /^\d+$/.test(name));
+  } catch {
+    return [];
+  }
+  const found: number[] = [];
+  for (const pid of pids) {
+    try {
+      const cwd = readlinkSync(`/proc/${pid}/cwd`);
+      if (cwd === dir || cwd === `${dir} (deleted)`) found.push(Number(pid));
+    } catch {
+      // Gone between the listing and the read, or not ours to read.
+    }
+  }
+  return found;
+}
+
+/** Whether anything still answers on `port` at the loopback address `x dev` binds. */
+export async function listening(port: number): Promise<boolean> {
+  try {
+    const socket = await Bun.connect({
+      hostname: '127.0.0.1',
+      port,
+      socket: { data: () => undefined },
+    });
+    socket.end();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * SIGKILL `pids`, then wait until each is gone. A test's last resort, run in `finally` — by then
+ * every graceful stop the test meant to prove has had its chance. `performance.now()`, never
+ * `Date.now()`: the test preload freezes the wall clock, and a deadline read off it never arrives.
+ */
+export async function reap(pids: readonly number[], timeoutMs = 10_000): Promise<void> {
+  for (const pid of pids) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // Already gone.
+    }
+  }
+  const until = performance.now() + timeoutMs;
+  while (pids.some(alive) && performance.now() < until) await Bun.sleep(25);
+}
+
+/** What was left: the pids still in `dir` and whether `port` still answers. Both empty is clean. */
+export async function leftovers(
+  dir: string,
+  port: number | undefined,
+): Promise<{ readonly pids: readonly number[]; readonly port: boolean }> {
+  return {
+    pids: processesIn(dir),
+    port: port === undefined ? false : await listening(port),
+  };
+}
+
+/**
+ * The net under a TIMED-OUT test: bun abandons its body without running `finally`, so an
+ * `afterEach` reaps whatever still runs in the fixture directory — the only handle left on an
+ * orphan whose parent is gone.
+ */
+export async function reapIn(dir: string): Promise<void> {
+  await reap(processesIn(dir));
+}

package/src/dev-port.ts

@@ -4,7 +4,7 @@
 
 import { PORT_RANGE, readIntFlag } from './flag-number';
 import type { ParsedArgs } from './parse';
-import { portFromEnv } from './serve';
+import { portFromEnv } from './serve-env';
 
 export const DEFAULT_DEV_PORT = 3000;