@ultimat3/cli 22.12.0 → 22.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.12.0",
+  "version": "22.14.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.12.0",
-    "@ultimat3/admin": "22.12.0",
-    "@ultimat3/ai": "22.12.0",
-    "@ultimat3/auth": "22.12.0",
-    "@ultimat3/cache": "22.12.0",
-    "@ultimat3/core": "22.12.0",
-    "@ultimat3/db": "22.12.0",
-    "@ultimat3/entity": "22.12.0",
-    "@ultimat3/flags": "22.12.0",
-    "@ultimat3/http": "22.12.0",
-    "@ultimat3/i18n": "22.12.0",
-    "@ultimat3/jobs": "22.12.0",
-    "@ultimat3/mail": "22.12.0",
-    "@ultimat3/manifest": "22.12.0",
-    "@ultimat3/mcp": "22.12.0",
-    "@ultimat3/money": "22.12.0",
-    "@ultimat3/notify": "22.12.0",
-    "@ultimat3/policy": "22.12.0",
-    "@ultimat3/pwa": "22.12.0",
-    "@ultimat3/query": "22.12.0",
-    "@ultimat3/realtime": "22.12.0",
-    "@ultimat3/render": "22.12.0",
-    "@ultimat3/schema": "22.12.0",
-    "@ultimat3/seo": "22.12.0",
-    "@ultimat3/storage": "22.12.0",
-    "@ultimat3/testing": "22.12.0",
-    "@ultimat3/time": "22.12.0",
+    "@ultimat3/action": "22.14.0",
+    "@ultimat3/admin": "22.14.0",
+    "@ultimat3/ai": "22.14.0",
+    "@ultimat3/auth": "22.14.0",
+    "@ultimat3/cache": "22.14.0",
+    "@ultimat3/core": "22.14.0",
+    "@ultimat3/db": "22.14.0",
+    "@ultimat3/entity": "22.14.0",
+    "@ultimat3/flags": "22.14.0",
+    "@ultimat3/http": "22.14.0",
+    "@ultimat3/i18n": "22.14.0",
+    "@ultimat3/jobs": "22.14.0",
+    "@ultimat3/mail": "22.14.0",
+    "@ultimat3/manifest": "22.14.0",
+    "@ultimat3/mcp": "22.14.0",
+    "@ultimat3/money": "22.14.0",
+    "@ultimat3/notify": "22.14.0",
+    "@ultimat3/policy": "22.14.0",
+    "@ultimat3/pwa": "22.14.0",
+    "@ultimat3/query": "22.14.0",
+    "@ultimat3/realtime": "22.14.0",
+    "@ultimat3/render": "22.14.0",
+    "@ultimat3/schema": "22.14.0",
+    "@ultimat3/seo": "22.14.0",
+    "@ultimat3/storage": "22.14.0",
+    "@ultimat3/testing": "22.14.0",
+    "@ultimat3/time": "22.14.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-mcp.ts

@@ -3,7 +3,9 @@
 // `ai: { mcp: { expose: true, path: '/mcp' } }` by DEFAULT, and nothing between the two served it:
 // neither `x dev` nor `runRole` mounted the route, so `POST /mcp` answered `X_ROUTE_NOT_FOUND` in
 // every app ever scaffolded (measured 2026-09-05). The contract is one file: `apps/<app>/mcp.ts`
-// exports `mcp`, an `AppMcp`; this module finds it, and both boots mount what it carries.
+// exports `mcp` — one `AppMcp`, or an array of them, one per population (customers, staff,
+// affiliates) — this module finds it, and both boots mount what it carries: endpoint #0 at
+// `ai.mcp.path`, every other at its own `defineAppMcp({ path })`.
 
 // why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
 import { existsSync } from 'node:fs';
@@ -12,23 +14,38 @@ import { join } from 'node:path';
 import { logger } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
 import { json, selfOrigin } from '@ultimat3/http';
-import { type AppMcp, McpAppUnmountedError } from '@ultimat3/mcp';
+import {
+  type AppMcp,
+  McpAppUnmountedError,
+  McpPathDuplicateError,
+  PROTECTED_RESOURCE_WELL_KNOWN,
+} from '@ultimat3/mcp';
 import { APP_CONFIG_EXPORT } from './app-auth';
 import { APP_CONFIG_FILE } from './app-root';
 
 /** The one file an app writes, per app directory. */
 export const APP_MCP_GLOB = 'apps/*/mcp.ts';
-/** The export that file makes — an `AppMcp`, the value `defineAppMcp` returns. */
+/**
+ * The export that file makes — an `AppMcp`, the value `defineAppMcp` returns, or a non-empty array
+ * of them. ONE export name either way: a second named export per endpoint would be a second way
+ * to say the same thing, and the array's order is the one fact the mount needs (#0 is the default).
+ */
 export const APP_MCP_EXPORT = 'mcp';
-/** What the boot line and `/_x` call the route. */
+/** What the boot line and `/_x` call endpoint #0's route; endpoint #n is `mcp:<its path>`. */
 export const APP_MCP_ROUTE_NAME = 'mcp';
 
 export interface AppMcpMount {
-  /** `[]` when `expose` is false, when nothing exports `mcp`, or when the export has no route. */
+  /** `[]` when `expose` is false, when nothing exports `mcp`, or when no endpoint has a route. */
   readonly routes: readonly Route[];
-  /** `POST <path>` when mounted, else `null` — the boot line prints it. */
+  /** Endpoint #0's `POST <path>` when mounted, else `null` — the default, at `ai.mcp.path`. */
   readonly path: string | null;
-  /** Set exactly when `expose` is true and `routes` is empty: the reason, as an instruction. */
+  /** Every mounted endpoint's `POST <path>`, in export order — the boot line prints one each. */
+  readonly paths: readonly string[];
+  /**
+   * Set when `expose` is true and an endpoint could not be mounted — nothing exports `mcp`, or the
+   * first endpoint built without `resolveToken`: the reason, as an instruction. The endpoints that
+   * could be mounted still are.
+   */
   readonly warning: McpAppUnmountedError | undefined;
 }
 
@@ -65,6 +82,13 @@ async function exposeDeclaration(root: string): Promise<ExposeDeclaration | unde
 const isAppMcp = (value: unknown): value is AppMcp =>
   isRecord(value) && 'server' in value && 'tools' in value && 'route' in value;
 
+/** The export as a list of endpoints, or `undefined` when it is not one (the "missing" case). */
+function endpointsOf(exported: unknown): readonly AppMcp[] | undefined {
+  if (isAppMcp(exported)) return [exported];
+  if (!Array.isArray(exported) || exported.length === 0) return undefined;
+  return exported.every(isAppMcp) ? (exported as readonly AppMcp[]) : undefined;
+}
+
 /** Every `apps/<app>/mcp.ts`, app-root-relative and sorted, so two apps answer in one order. */
 async function candidates(root: string): Promise<readonly string[]> {
   // A root with no `apps/` is an app with no MCP file, never a boot failure — the scan's ENOENT
@@ -75,8 +99,10 @@ async function candidates(root: string): Promise<readonly string[]> {
   return files.sort();
 }
 
+const NOTHING: AppMcpMount = { routes: [], path: null, paths: [], warning: undefined };
+
 /**
- * The route to mount, or the reason there is none. Pure over the filesystem it is pointed at;
+ * The routes to mount, or the reason there are none. Pure over the filesystem it is pointed at;
  * `mountAppMcp` below is the one place the warning becomes a log line.
  *
  * `meta.auth: 'public'` and `enforcedBy: 'handler'` — the http pipeline must not pre-judge:
@@ -87,72 +113,17 @@ async function candidates(root: string): Promise<readonly string[]> {
  */
 export async function appMcpMount(root: string): Promise<AppMcpMount> {
   const declared = await exposeDeclaration(root);
-  if (declared === undefined || !declared.expose)
-    return { routes: [], path: null, warning: undefined };
+  if (declared === undefined || !declared.expose) return NOTHING;
   const files = await candidates(root);
   const fallbackFile = 'apps/web/mcp.ts';
-  if (files.length === 0) {
-    return {
-      routes: [],
-      path: null,
-      warning: new McpAppUnmountedError({
-        reason: 'missing',
-        path: declared.path,
-        file: fallbackFile,
-      }),
-    };
-  }
   for (const file of files) {
     const module = (await import(join(root, file))) as Record<string, unknown>;
-    const exported = module[APP_MCP_EXPORT];
-    if (!isAppMcp(exported)) continue;
-    const route = exported.route;
-    if (route === undefined) {
-      return {
-        routes: [],
-        path: null,
-        warning: new McpAppUnmountedError({ reason: 'no-route', path: declared.path, file }),
-      };
-    }
-    // The PUBLIC origin, as the pipeline resolved it (`ctx.https` honours a trusted proxy's
-    // `x-forwarded-proto`): behind a TLS-terminating ingress the raw request URL is `http://` on
-    // an internal host, and a `resource_metadata` naming that is a URL no client can reach.
-    const resource = route.protectedResource;
-    return {
-      routes: [
-        {
-          method: 'POST',
-          path: declared.path,
-          handler: (request, ctx) =>
-            route.handle(request.raw, { origin: selfOrigin(ctx.url, ctx.https) }),
-          meta: { name: APP_MCP_ROUTE_NAME, auth: 'public', enforcedBy: 'handler' },
-        },
-        // RFC 9728 protected-resource metadata, when the app declared `oauth`: path-inserted and
-        // at the root, so a client probing either finds the authorization server.
-        ...(resource === undefined
-          ? []
-          : resource.paths.map(
-              (path): Route => ({
-                method: 'GET',
-                path,
-                handler: (_request, ctx) => {
-                  const response = json(resource.document(selfOrigin(ctx.url, ctx.https)));
-                  // A browser-hosted MCP client reads this cross-origin; it holds nothing secret.
-                  response.headers.set('access-control-allow-origin', '*');
-                  response.headers.set('cache-control', 'public, max-age=3600');
-                  return response;
-                },
-                meta: { name: `${APP_MCP_ROUTE_NAME}.oauth-protected-resource`, auth: 'public' },
-              }),
-            )),
-      ],
-      path: declared.path,
-      warning: undefined,
-    };
+    const endpoints = endpointsOf(module[APP_MCP_EXPORT]);
+    if (endpoints === undefined) continue;
+    return mountEndpoints(endpoints, declared.path, file);
   }
   return {
-    routes: [],
-    path: null,
+    ...NOTHING,
     warning: new McpAppUnmountedError({
       reason: 'missing',
       path: declared.path,
@@ -161,6 +132,95 @@ export async function appMcpMount(root: string): Promise<AppMcpMount> {
   };
 }
 
+/**
+ * One file's endpoints onto one route table. An endpoint built without `resolveToken` has no
+ * route: it is skipped and the FIRST such is the warning, so one unfinished population never takes
+ * the others down with it. Two endpoints on one route is thrown — see `McpPathDuplicateError`.
+ */
+function mountEndpoints(
+  endpoints: readonly AppMcp[],
+  defaultPath: string,
+  file: string,
+): AppMcpMount {
+  const routes: Route[] = [];
+  const paths: string[] = [];
+  const claimed = new Map<string, number>();
+  let warning: McpAppUnmountedError | undefined;
+  endpoints.forEach((endpoint, index) => {
+    const route = endpoint.route;
+    if (route === undefined) {
+      warning ??= new McpAppUnmountedError({
+        reason: 'no-route',
+        path: defaultPath,
+        file,
+        ...(index === 0 ? {} : { endpoint: index }),
+      });
+      return;
+    }
+    const path = index === 0 ? defaultPath : route.path;
+    for (const mounted of endpointRoutes(route, path, index)) {
+      const key = `${mounted.method} ${mounted.path}`;
+      const first = claimed.get(key);
+      if (first !== undefined) {
+        throw new McpPathDuplicateError({
+          method: mounted.method,
+          path: mounted.path,
+          endpoints: [first, index],
+          file,
+        });
+      }
+      claimed.set(key, index);
+      routes.push(mounted);
+    }
+    paths.push(path);
+  });
+  const path = endpoints[0]?.route === undefined ? null : defaultPath;
+  return { routes, path, paths, warning };
+}
+
+type Descriptor = NonNullable<AppMcp['route']>;
+
+/** One endpoint's `POST` and, when it declared `oauth`, its RFC 9728 metadata `GET`s. */
+function endpointRoutes(route: Descriptor, path: string, index: number): readonly Route[] {
+  const name = index === 0 ? APP_MCP_ROUTE_NAME : `${APP_MCP_ROUTE_NAME}:${path}`;
+  const resource = route.protectedResource;
+  // The ROOT document belongs to endpoint #0 alone: a client that probes the bare well-known URL
+  // is asking about the default resource, and a second endpoint answering there would collide.
+  // Every endpoint keeps its path-inserted document (RFC 9728 §3.1), which its own 401 names.
+  const metadata: readonly Route[] =
+    resource === undefined
+      ? []
+      : resource.paths
+          .filter((metadataPath) => index === 0 || metadataPath !== PROTECTED_RESOURCE_WELL_KNOWN)
+          .map(
+            (metadataPath): Route => ({
+              method: 'GET',
+              path: metadataPath,
+              handler: (_request, ctx) => {
+                const response = json(resource.document(selfOrigin(ctx.url, ctx.https)));
+                // A browser-hosted MCP client reads this cross-origin; it holds nothing secret.
+                response.headers.set('access-control-allow-origin', '*');
+                response.headers.set('cache-control', 'public, max-age=3600');
+                return response;
+              },
+              meta: { name: `${name}.oauth-protected-resource`, auth: 'public' },
+            }),
+          );
+  return [
+    {
+      method: 'POST',
+      path,
+      // The PUBLIC origin, as the pipeline resolved it (`ctx.https` honours a trusted proxy's
+      // `x-forwarded-proto`): behind a TLS-terminating ingress the raw request URL is `http://`
+      // on an internal host, and a `resource_metadata` naming that is a URL no client can reach.
+      handler: (request, ctx) =>
+        route.handle(request.raw, { origin: selfOrigin(ctx.url, ctx.https) }),
+      meta: { name, auth: 'public', enforcedBy: 'handler' },
+    },
+    ...metadata,
+  ];
+}
+
 /**
  * The boot's call: the routes to spread into the table, with the warning already logged ONCE and
  * the mount announced. Both `x dev` and `runRole` go through here, so a developer's terminal and a
@@ -171,6 +231,6 @@ export async function mountAppMcp(root: string): Promise<AppMcpMount> {
   if (mount.warning !== undefined) {
     logger.warn(`${mount.warning.code}: ${mount.warning.cause} — fix: ${mount.warning.fix}`);
   }
-  if (mount.path !== null) logger.info('app mcp mounted', { method: 'POST', path: mount.path });
+  for (const path of mount.paths) logger.info('app mcp mounted', { method: 'POST', path });
   return mount;
 }

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

@@ -79,8 +79,10 @@ export interface DevServer {
   readonly runtime: RunningServices;
   /** Panel keys `/_x` mounted, in tab order. Reported so `--json` names what is reachable. */
   readonly panels: readonly string[];
-  /** `POST <path>` of the app's own MCP endpoint, or `null` when nothing was mounted. */
+  /** `POST <path>` of the app's default MCP endpoint, or `null` when nothing was mounted. */
   readonly mcp: string | null;
+  /** `POST <path>` of every mounted MCP endpoint, default first — `[]` when none was. */
+  readonly mcpPaths: readonly string[];
   stop(): Promise<void>;
 }
 
@@ -240,7 +242,7 @@ async function bootDev(
   // `x dev`'s own, so a reload can empty it: an `isr` page's first render was otherwise served for
   // its whole ttl after every save, whatever the modules behind it now said.
   const isr = createIsrController({ buildId });
-  const { routes, theme, errorStyles, mcpPath } = await devRouteTable({
+  const { routes, theme, errorStyles, mcpPath, mcpPaths } = await devRouteTable({
     isr,
     root: options.root,
     env: options.env,
@@ -328,6 +330,7 @@ async function bootDev(
     services,
     roles: running.roles,
     mcp: mcpPath,
+    mcpPaths,
     get buildId(): string {
       return stamped ?? state.manifest.buildId;
     },
@@ -447,6 +450,7 @@ export const devCommand: CliCommand = {
         introspect: `${server.url}/_x`,
         panels: [...server.panels],
         mcp: server.mcp,
+        mcpPaths: [...server.mcpPaths],
       },
       lines: [
         // A hard kill leaves the lock behind; clearing it is normal and worth one line, never a
@@ -458,7 +462,8 @@ export const devCommand: CliCommand = {
         msg('cli.dev.introspect', { url: `${server.url}/_x` }),
         // Only when something was mounted: the unmounted case has already said why, once, as a
         // warning with a fix, and a summary line reading `mcp none` would be a second copy of it.
-        ...(server.mcp === null ? [] : [msg('cli.dev.mcp', { path: server.mcp })]),
+        // One line per endpoint, so an app serving customers, staff and affiliates sees all three.
+        ...server.mcpPaths.map((path) => msg('cli.dev.mcp', { path })),
       ],
     };
     await writeLock(services.stateDir, {

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 };
+}