@ultimat3/cli 30.3.0 → 30.5.0

package/CLAUDE.md

@@ -5,7 +5,7 @@ dashboard), `cli → testing` (islands, the e2e step, `x shot`'s `launchChrome`)
 this except `create-ultimate`. The reasoning behind every rule below, verbatim and dated, is
 [`docs/history/cli.md`](../../docs/history/cli.md); where the two disagree this file wins.
 
-Commands: `bun test packages/cli` (from the repo root — the test preload lives there),
+Commands: `bun test packages/cli` (from the repo root: the preload),
 `bunx tsc --noEmit -p packages/cli/tsconfig.json`.
 
 ## Rules
@@ -51,13 +51,13 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `boundary-findings.ts` / `app-boundaries.ts` / `boundary-cuts.ts` / `package-boundaries.ts` | `package-boundaries.ts`: `X_BOUNDARY_PACKAGE_TO_APP`, its own read of `packages/`, never `readAppSources`. surface + layer rules; a finding's `fix:` is the concrete cut |
 | `app-transport.ts` / `browser-transport.ts` / `transport-calls.ts` / `import-closure.ts` / `server-barrels.ts` | `boundaries`, built in: one browser transport. Never a `guards/` file: an app must not be able to delete it. Full rule: `docs/history/cli.md` |
 | `guards.ts` / `guard-sources.ts` | an app's `guards/*.ts`, discovered, run on `boundaries`, held to the error contract; every `check(root, sources)` shares ONE walk, read and Sass compile per file (`GuardSources`) |
-| `templates/scaffold-guards.ts` | `SHIPPED` — the one list of the twenty-one shipped guards (`native-confirm` the newest): `x new` writes all, `x g guard <name>` writes one, `doctor-guards.ts` lists the ones an app lacks (a listing, never a finding). Full rule: `docs/history/cli.md` |
+| `templates/scaffold-guards.ts` | `SHIPPED` — the one list of the twenty-one shipped guards: `x new` writes all, `x g guard <name>` writes one, `doctor-guards.ts` lists the ones an app lacks (a listing, never a finding). Full rule: `docs/history/cli.md` |
 | `error-contract.ts` / `ts-scan.ts` / `fix-scan.ts` / `fix-imports.ts` / `fix-command.ts` / `fix-path.ts` | the `errors` step: every `fix:` names a runnable command, call or existing file |
 | `workspace-checks.ts` / `test-only-shipped.ts` / `workspace-graph.ts` / `tsconfig-references.ts` / `publish-closure.ts` | `package-shape`, `filesize`. Full rule: `docs/history/cli.md` |
 | `app-permissions.ts` / `permission-grants.ts` / `app-permissions-borrowed.ts` / `app-permissions-site.ts` | `policy`: every permission granted or required is declared and granted (`X_PERMISSION_UNGRANTED`, `X_PERMISSION_BORROWED`). Full rule: `docs/history/cli.md` |
 | `job-registration.ts` | `manifest`: no job or task under a positional `anonymous-*` name (`X_JOB_UNREGISTERED`) |
 | `unscanned-admin.ts` | `manifest`: a `defineAdmin()` outside the app scan (`apps/*/src/`) is `X_ADMIN_UNSCANNED` |
-| `tool-gate-names.ts` | `manifest`: a gate on no tool |
+| `tool-gate-names.ts` · `verify-mcp-mount.ts` | `manifest`: a gate on no tool · `expose` and no `POST /mcp` |
 | `verify-role-load.ts` / `verify-role-load-probe.ts` | `manifest`: a child imports the app as a worker does, then the rest module by module; a registration only a document-reaching module makes is `X_ROLE_LOAD_INCOMPLETE` with the module and the import the API index lacks |
 | `async-pages.ts` / `live-routes.ts` / `budgets.ts` / `budgets-unmeasured.ts` | `budgets` riders: an async `Page` with no `load`, a live read no island imports, bytes per route; an unweighed route's finding names a refused measurement actor and `defineMeasurementActor()` |
 | `budgets-freshness.ts` / `verify-budgets-build.ts` | the step builds first when stats are missing, of an old rule, or older than source: `x build --target static --no-preflight --out .x/verify-static` through `ctx.runner` |
@@ -95,7 +95,7 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `generate-feature-required.ts` | `x g query`/`backfill` with no slice holding an `entity.ts` is `X_FEATURE_REQUIRED` |
 | `generate-sign-in*.ts` | `x g sign-in`: one flag, no name; OIDC swaps only `x new`'s bytes |
 | `generate-format-written.ts` | the app's Biome over the TypeScript a run created, best effort; `lint` judges |
-| `templates/scaffold-mcp-json.ts` / `templates/scaffold-mcp-endpoint.ts` | `.mcp.json` (`bunx @ultimat3/cli mcp serve`, never `bunx x`) and the refusing `apps/web/mcp.ts` + `app/auth/agent-token.ts`; `scaffold-agents-md.test.ts` resolves every command `AGENTS.md` names |
+| `templates/scaffold-mcp-{json,endpoint,admin}.ts` | `.mcp.json` (`bunx @ultimat3/cli mcp serve`, never `bunx x`), the refusing `apps/web/mcp.ts` + `app/auth/agent-token.ts`, `apps/admin/mcp.ts`; `scaffold-agents-md.test.ts` resolves every command `AGENTS.md` names |
 
 ### Boot (`x dev`, the container)
 
@@ -113,7 +113,7 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `app-config-load.ts` | the ONE reader of an app's `app.config.ts`: `loadAppConfig(root)` — the `config` export through core's `defineConfig`, so validated and default-merged; `undefined` with no file; no `config` object is `X_CONFIG_INVALID`. Full rule: `docs/history/cli.md` |
 | `theme-brand.ts` | the ONE reader of an app's theme: `export const brand` in `apps/web/shared/theme.ts` (ui's `defineTheme`), inlined after the surface stylesheet with its hash in `style-src`; none → nothing emitted |
 | `runtime-jobs.ts` / `runtime-realtime.ts` / `runtime-notify-retention.ts` / `runtime-cache.ts` / `runtime-purge.ts` / `runtime-replica.ts` | `app.config.ts` sections the boot obeys (`*Of(config)` over the one loaded config), and what each wires |
-| `runtime-jobs.ts` (queues) | `jobs.queues` ∪ registered queues; `WORKER_QUEUES` = the EXACT set, each entry in that union or `X_WORKER_QUEUE_UNKNOWN`; `queue-unserved` warns the rest |
+| `runtime-jobs.ts` (queues) | `jobs.queues` ∪ registered; `WORKER_QUEUES` = the EXACT set, each in that union or `X_WORKER_QUEUE_UNKNOWN`; `-unserved.ts`: what no live worker serves |
 | `serve-retire.ts` / `dev-restart-retire.ts` | the worker retire, `stop()` claiming and aborting nothing: SIGUSR2 under `runRole`, and before a supervised `x dev` restart's drain (#677). Full rule: `docs/history/cli.md` |
 | `role-start.ts` / `role-start-types.ts` / `role-realtime.ts` / `role-start-devices.ts` | `--role` selection and start/stop for `web`, `sync`, `worker`, `scheduler`; `realtime.enabled: false` drops `sync` and `replicator`; device mounts, swapped per path on save |
 | `role-wake.ts` | the worker's LISTEN session (`@ultimat3/jobs`' `startQueueWake`) — worker role only, only over a client that `canListen` — and `queue_wake_live` |
@@ -131,7 +131,7 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `island-bundle.ts` / `island-store.ts` / `island-sources.ts` / `island-realtime.ts` / `island-realtime-state.ts` / `island-runtime.ts` / `solid-loader.ts` | islands: one `Bun.build` each, source-addressed; the image build writes a verified store, and an edit since the build is a rebuild, never the old chunk |
 | `local-cli.ts` / `local-cli-handoff.ts` | a global `x` hands over to the app's own CLI (`local-cli.ts` decides whether; `x upgrade` alone stays when the app's is strictly older — `upgrade-handover.test.ts`) |
 | `serve-prebuilt.ts` / `serve-prebuilt-paths.ts` | the image's prebuilt store (`node_modules/.cache/ultimate`, never `.x/` — state, tmpfs): every role adopts its compiled stylesheets before importing the app; a boot that built an island or ran Sass logs `X_IMAGE_NOT_PREBUILT` once |
-| `dev-*.ts` | `x dev` only: dashboard sources, traces, the N+1 ledger, the watcher, the reload, the lock, the port |
+| `dev-*.ts` | `x dev` only: dashboard sources, traces, the N+1 ledger, watcher, reload, lock, port |
 | `cmd-stop.ts` / `cmd-stop-spec.ts` | `x stop`: the lock's pid only (its recorded start time must match), SIGTERM, then wait for pid gone and lock clear; Windows clears the lock (`drained: false`); `X_DEV_STOP_TIMEOUT` |
 | `dev-dashboard-guard.ts` / `loopback-host.ts` | `/_x` answers a loopback `Host` only (`X_DEV_HOST_REFUSED`, 421 — DNS rebinding); the SQL panel runs on a same-origin `POST /_x/db` only, through admin's `readOnlySql` |
 | `doctor-pooler.ts` / `runtime-statement-bound.ts` | the applied bound on demand (`data.statementBound`), a pooler's refusal as the one database finding; the one boot line, total. `startDb` hands `poolerFromEnv(env)` to both pools |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "30.3.0",
+  "version": "30.5.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "keywords": [
     "ultimate",
@@ -53,33 +53,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.7",
-    "@ultimat3/action": "30.3.0",
-    "@ultimat3/admin": "30.3.0",
-    "@ultimat3/ai": "30.3.0",
-    "@ultimat3/auth": "30.3.0",
-    "@ultimat3/cache": "30.3.0",
-    "@ultimat3/core": "30.3.0",
-    "@ultimat3/db": "30.3.0",
-    "@ultimat3/entity": "30.3.0",
-    "@ultimat3/flags": "30.3.0",
-    "@ultimat3/http": "30.3.0",
-    "@ultimat3/i18n": "30.3.0",
-    "@ultimat3/jobs": "30.3.0",
-    "@ultimat3/mail": "30.3.0",
-    "@ultimat3/manifest": "30.3.0",
-    "@ultimat3/mcp": "30.3.0",
-    "@ultimat3/money": "30.3.0",
-    "@ultimat3/notify": "30.3.0",
-    "@ultimat3/policy": "30.3.0",
-    "@ultimat3/pwa": "30.3.0",
-    "@ultimat3/query": "30.3.0",
-    "@ultimat3/realtime": "30.3.0",
-    "@ultimat3/render": "30.3.0",
-    "@ultimat3/schema": "30.3.0",
-    "@ultimat3/seo": "30.3.0",
-    "@ultimat3/storage": "30.3.0",
-    "@ultimat3/testing": "30.3.0",
-    "@ultimat3/time": "30.3.0",
+    "@ultimat3/action": "30.5.0",
+    "@ultimat3/admin": "30.5.0",
+    "@ultimat3/ai": "30.5.0",
+    "@ultimat3/auth": "30.5.0",
+    "@ultimat3/cache": "30.5.0",
+    "@ultimat3/core": "30.5.0",
+    "@ultimat3/db": "30.5.0",
+    "@ultimat3/entity": "30.5.0",
+    "@ultimat3/flags": "30.5.0",
+    "@ultimat3/http": "30.5.0",
+    "@ultimat3/i18n": "30.5.0",
+    "@ultimat3/jobs": "30.5.0",
+    "@ultimat3/mail": "30.5.0",
+    "@ultimat3/manifest": "30.5.0",
+    "@ultimat3/mcp": "30.5.0",
+    "@ultimat3/money": "30.5.0",
+    "@ultimat3/notify": "30.5.0",
+    "@ultimat3/policy": "30.5.0",
+    "@ultimat3/pwa": "30.5.0",
+    "@ultimat3/query": "30.5.0",
+    "@ultimat3/realtime": "30.5.0",
+    "@ultimat3/render": "30.5.0",
+    "@ultimat3/schema": "30.5.0",
+    "@ultimat3/seo": "30.5.0",
+    "@ultimat3/storage": "30.5.0",
+    "@ultimat3/testing": "30.5.0",
+    "@ultimat3/time": "30.5.0",
     "babel-preset-solid": "^1.9.16"
   }
 }

package/src/app-mcp.ts

@@ -5,7 +5,8 @@
 // every app ever scaffolded (measured 2026-09-05). The contract is one file: `apps/<app>/mcp.ts`
 // 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: EVERY endpoint at its
-// own `defineAppMcp({ path })`, the one path its RFC 9728 metadata and its 401 also name.
+// own `defineAppMcp({ path })`, the one path its RFC 9728 metadata and its 401 also name — and
+// every app directory's file mounts, so an admin surface's `apps/admin/mcp.ts` stands beside the web one.
 
 // why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
 import { existsSync } from 'node:fs';
@@ -16,6 +17,7 @@ import type { Route } from '@ultimat3/http';
 import { jsonResponse, originListed, selfOrigin } from '@ultimat3/http';
 import {
   type AppMcp,
+  assertIncludeCurrent,
   assertRecipeLinks,
   McpAppUnmountedError,
   McpPathDuplicateError,
@@ -75,22 +77,44 @@ function endpointsOf(exported: unknown): readonly AppMcp[] | 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. */
+/** The web surface's file: endpoint #0 — the default — wherever its directory sorts. */
+const DEFAULT_MCP_FILE = 'apps/web/mcp.ts';
+
+/**
+ * Every `apps/<app>/mcp.ts`, app-root-relative: the web surface's first, then the rest sorted, so
+ * two machines answer in one order and an `apps/admin/mcp.ts` never takes the default endpoint.
+ */
 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
   // is answered as "none", and the warning below says which file to write.
   if (!existsSync(join(root, 'apps'))) return [];
   const files: string[] = [];
   for await (const file of new Bun.Glob(APP_MCP_GLOB).scan({ cwd: root })) files.push(file);
-  return files.sort();
+  files.sort();
+  return files.includes(DEFAULT_MCP_FILE)
+    ? [DEFAULT_MCP_FILE, ...files.filter((file) => file !== DEFAULT_MCP_FILE)]
+    : files;
 }
 
 const NOTHING: AppMcpMount = { routes: [], path: null, paths: [], warning: undefined };
 
+/** One mount file's endpoints. */
+interface MountFile {
+  readonly file: string;
+  readonly endpoints: readonly AppMcp[];
+}
+
 /**
  * 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.
  *
+ * EVERY app directory's `mcp.ts` mounts — an admin surface's `apps/admin/mcp.ts` beside the web
+ * one — on one route table. The first sorted file used to win alone, so an admin surface's file
+ * silently took the app's `/mcp` away. Each is imported HERE, after the boot scan: the scan
+ * evaluates `apps/<app>/mcp.ts` after every `apps/<app>/{site,app,api,shared}/` module, so an
+ * `include: 'exposed'` built at its top level sees every primitive — and one built earlier, in a
+ * module it re-exports, is `X_MCP_INCLUDE_EARLY` rather than a catalog missing tools.
+ *
  * `meta.auth: 'public'` and `enforcedBy: 'handler'` — the http pipeline must not pre-judge:
  * `mcp.route.handle` is the one evaluation, and it reads `Authorization: Bearer` through the
  * `resolveToken` the app gave `defineAppMcp`, then decides per tool through the same policy every
@@ -100,67 +124,78 @@ const NOTHING: AppMcpMount = { routes: [], path: null, paths: [], warning: undef
 export async function appMcpMount(root: string): Promise<AppMcpMount> {
   if (!(await exposed(root))) return NOTHING;
   const files = await candidates(root);
-  const fallbackFile = 'apps/web/mcp.ts';
+  const mounted: MountFile[] = [];
   for (const file of files) {
     const module = (await import(join(root, file))) as Record<string, unknown>;
     const endpoints = endpointsOf(module[APP_MCP_EXPORT]);
     if (endpoints === undefined) continue;
-    // Every endpoint is built by now: an error's declared `docs://recipes/` link must name a recipe
-    // one of them serves (`X_MCP_RECIPE_UNKNOWN`), the union and never one endpoint alone.
-    assertRecipeLinks(servedRecipes());
-    return mountEndpoints(endpoints, file);
+    for (const endpoint of endpoints) assertIncludeCurrent(endpoint, file);
+    mounted.push({ file, endpoints });
   }
-  return {
-    ...NOTHING,
-    warning: new McpAppUnmountedError({
-      reason: 'missing',
-      path: UNROUTED_MCP_PATH,
-      file: files[0] ?? fallbackFile,
-    }),
-  };
+  if (mounted.length === 0) {
+    return {
+      ...NOTHING,
+      warning: new McpAppUnmountedError({
+        reason: 'missing',
+        path: UNROUTED_MCP_PATH,
+        file: files[0] ?? DEFAULT_MCP_FILE,
+      }),
+    };
+  }
+  // Every endpoint is built by now: an error's declared `docs://recipes/` link must name a recipe
+  // one of them serves (`X_MCP_RECIPE_UNKNOWN`), the union and never one endpoint alone.
+  assertRecipeLinks(servedRecipes());
+  return mountEndpoints(mounted);
 }
 
 /**
- * One file's endpoints onto one route table. An endpoint built without `resolveToken` has no
+ * Every 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`.
+ * Numbering: `#n` in a message is the endpoint's index in its own file's export; only the very
+ * first endpoint mounted is the default (#0 of the route names and the root metadata document).
  */
-function mountEndpoints(endpoints: readonly AppMcp[], file: string): AppMcpMount {
+function mountEndpoints(files: readonly MountFile[]): AppMcpMount {
   const routes: Route[] = [];
   const paths: string[] = [];
-  const claimed = new Map<string, number>();
+  const claimed = new Map<string, { readonly file: string; readonly index: number }>();
   let warning: McpAppUnmountedError | undefined;
-  endpoints.forEach((endpoint, index) => {
-    const route = endpoint.route;
-    if (route === undefined) {
-      warning ??= new McpAppUnmountedError({
-        reason: 'no-route',
-        path: UNROUTED_MCP_PATH,
-        file,
-        ...(index === 0 ? {} : { endpoint: index }),
-      });
-      return;
-    }
-    // The descriptor's own path — the one its metadata, its `resourceUrl` and its 401 were built
-    // over. A mount path from anywhere else is a resource advertised where nothing answers.
-    const path = 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],
+  let mountedIndex = 0;
+  for (const { file, endpoints } of files) {
+    endpoints.forEach((endpoint, index) => {
+      const route = endpoint.route;
+      if (route === undefined) {
+        warning ??= new McpAppUnmountedError({
+          reason: 'no-route',
+          path: UNROUTED_MCP_PATH,
           file,
+          ...(index === 0 ? {} : { endpoint: index }),
         });
+        return;
       }
-      claimed.set(key, index);
-      routes.push(mounted);
-    }
-    paths.push(path);
-  });
-  return { routes, path: endpoints[0]?.route?.path ?? null, paths, warning };
+      // The descriptor's own path — the one its metadata, its `resourceUrl` and its 401 were built
+      // over. A mount path from anywhere else is a resource advertised where nothing answers.
+      const path = route.path;
+      for (const one of endpointRoutes(route, path, mountedIndex)) {
+        const key = `${one.method} ${one.path}`;
+        const first = claimed.get(key);
+        if (first !== undefined) {
+          throw new McpPathDuplicateError({
+            method: one.method,
+            path: one.path,
+            endpoints: [first.index, index],
+            file,
+            firstFile: first.file,
+          });
+        }
+        claimed.set(key, { file, index });
+        routes.push(one);
+      }
+      paths.push(path);
+      mountedIndex += 1;
+    });
+  }
+  return { routes, path: paths[0] ?? null, paths, warning };
 }
 
 type Descriptor = NonNullable<AppMcp['route']>;

package/src/cmd-upgrade-spec.ts

@@ -15,7 +15,7 @@ export const upgradeSpec: CommandSpec = {
       name: 'to',
       type: 'string',
       summary:
-        'an exact release inside the next major, or the higher version a mixed set was told to align to (default: the next major’s newest)',
+        'an exact release inside the next major; over a mixed set, inside the lowest pins’ next major, and only those pins move (default: the next major’s newest)',
     },
     {
       name: 'dry-run',

package/src/exercise-findings.ts

@@ -12,7 +12,7 @@ import {
   renderFixShellArg,
 } from '@ultimat3/core';
 import type { ExerciseRecord } from '@ultimat3/testing';
-import { planSweepFindings, tenantProofFindings } from '@ultimat3/testing';
+import { crashEffectPlace, planSweepFindings, tenantProofFindings } from '@ultimat3/testing';
 import type { Finding } from './output';
 import { renderTable } from './table';
 
@@ -44,6 +44,20 @@ export const exerciseCounts = (records: readonly ExerciseRecord[]): ExerciseCoun
   };
 };
 
+/**
+ * A 5xx's own words — the cause testing recorded (credential values already masked there) and the
+ * fields a validation failure names. The statement is inside the cause, so it is not said twice.
+ */
+const defectOf = (record: ExerciseRecord): string => {
+  const defect = record.defect;
+  if (defect === undefined) return '';
+  const fields =
+    defect.fields === undefined
+      ? ''
+      : ` at ${defect.fields.map((field) => renderCauseValue(field)).join(', ')}`;
+  return ` — cause: ${renderCauseValue(defect.cause)}${fields}`;
+};
+
 /**
  * `X_CONTRACT_EXERCISE_UNREACHED`, `@ultimat3/action`'s code for the same silence one level up: a
  * primitive no run got to as an allowed actor. The fix is the override the pass printed, or the
@@ -56,7 +70,7 @@ const unreachedFinding = (record: ExerciseRecord): Finding => {
   const why = record.reason === undefined ? '' : ` (${renderCauseValue(record.reason)})`;
   return {
     code: 'X_CONTRACT_EXERCISE_UNREACHED',
-    cause: `${record.kind} ${renderCauseValue(record.name)} never reached its handler as an allowed actor in the exercise pass${stopped}${why}`,
+    cause: `${record.kind} ${renderCauseValue(record.name)} never reached its handler as an allowed actor in the exercise pass${stopped}${why}${defectOf(record)}`,
     fix:
       record.fix ??
       `defineExercise({ ${override} })   # paste the entry into ${EXERCISE_FILE}, or { off: '<why>' }; then: x exercise ${name} --json`,
@@ -75,27 +89,29 @@ const crashFindingsOf = (record: ExerciseRecord): readonly CrashFinding[] =>
 
 /**
  * `X_JOB_CRASH_DIVERGED`, testing's code: a reached job, killed at a step boundary, made an effect
- * more often than a clean run — it sits outside every `step.run`, so a retry makes it again. One
- * finding per effect and the step it follows, every boundary that showed it named in the cause.
+ * a different number of times than a clean run. Where it ran — outside every `step.run`, or inside
+ * one whose body re-runs — is testing's `crashEffectPlace`, the phrase its error uses too. One
+ * finding per effect and place, every boundary that showed it named in the cause.
  */
 const crashFindings = (record: ExerciseRecord): readonly Finding[] => {
   const groups = new Map<string, CrashFinding[]>();
   for (const one of crashFindingsOf(record)) {
-    const key = `${one.effect}\u0000${one.after ?? ''}`;
+    const key = `${one.effect}\u0000${one.after ?? ''}\u0000${one.inside ?? ''}`;
     groups.set(key, [...(groups.get(key) ?? []), one]);
   }
   const job = renderFixShellArg(record.name, '<job>');
   return [...groups.values()].map((group): Finding => {
     const [first] = group as [CrashFinding, ...CrashFinding[]];
-    const where =
-      first.after === undefined
-        ? 'before the first step'
-        : `after step ${JSON.stringify(first.after)}`;
+    const { place, remedy } = crashEffectPlace(first);
+    const how =
+      first.killed > first.clean
+        ? 'the retry after a crash makes it again'
+        : 'the crash skipped it';
     const at = group.map((one) => JSON.stringify(one.boundary)).join(', ');
     return {
       code: 'X_JOB_CRASH_DIVERGED',
-      cause: `job ${renderCauseValue(record.name)} killed at ${at} made ${renderCauseValue(first.effect)} ${first.killed}× against ${first.clean}× in a clean run: it runs outside every step, ${where}, so the retry after a crash makes it again`,
-      fix: `x exercise ${job} --json   # in job(${renderFixLiteral(record.name, '<job>')}): wrap the ${renderFixLiteral(first.effect, '<effect>')} made ${where} in step.run('<name>', async () => …)`,
+      cause: `job ${renderCauseValue(record.name)} killed at ${at} made ${renderCauseValue(first.effect)} ${first.killed}× against ${first.clean}× in a clean run: ${place}, so ${how}`,
+      fix: `x exercise ${job} --json   # in job(${renderFixLiteral(record.name, '<job>')}), for ${renderFixLiteral(first.effect, '<effect>')}: ${remedy}`,
       docs: ERROR_DOCS_URL,
       at: `${record.kind} ${record.name}`,
     };

package/src/island-bundle.ts

@@ -189,7 +189,9 @@ async function buildAll(
       // gets the same rule (`island-package-dedupe.ts`): a nested copy is a second module where no
       // symlink folds it, which is every `file:` install on Windows.
       plugins: [
-        ...(runtime === undefined ? [] : [islandRealtimePlugin(root, runtime, follows)]),
+        ...(runtime === undefined
+          ? []
+          : [islandRealtimePlugin(root, runtime, follows, live.length === files.length)]),
         solidDedupePlugin(root),
         ...frameworkDedupePlugins(root),
         solidJsxPlugin,

package/src/island-realtime.ts

@@ -5,8 +5,9 @@
 // that reads the record store or the outbox also waits for the page's restore before it mounts
 // (#506); one that only follows the socket does not (`island-realtime-state.ts`).
 
-// why: Bun ships no path API; the entry is joined to the root, the runtime named by its basename.
-import { basename, join } from 'node:path';
+// why: Bun ships no path API; the entry is joined to the root, the runtime named by its basename,
+// core's transport found beside the core module importing it.
+import { basename, dirname, join } from 'node:path';
 import type { BunPlugin } from 'bun';
 import { followsOnly, type IslandRealtime } from './island-realtime-state';
 import { RUNTIME_CHUNK_SPECIFIER, type RuntimeChunk } from './island-runtime';
@@ -29,6 +30,10 @@ const INSTALL = 'ultimate:island-realtime';
 const RESTORE = 'ultimate:island-restore';
 const MODULE = 'ultimate:island-module:';
 const WAIT = 'ultimate:island-page-wait';
+const CORE_TRANSPORT = 'ultimate:island-core-transport';
+/** What core's own modules import the transport by — the one specifier the swap answers. */
+const TRANSPORT_SPECIFIER = /^\.\/client-transport$/;
+const TRANSPORT_MODULE = 'transport:';
 
 /**
  * Whether the island's own graph value-imports realtime. Relative specifiers only, which is the
@@ -108,6 +113,41 @@ const restoreSource = (): string =>
   `import { holdFirstPaint } from '${REALTIME}';\n` +
   `await holdFirstPaint();\n`;
 
+/**
+ * Core's `client-transport.ts`, as a realtime island's bundle sees it: `clientTransport` sends
+ * through the page runtime's copy (`runtimeSend`), and `settleAnswer` — `clientStream`'s, which
+ * the runtime does not expose — is the real one, tree-shaken to what it needs. The island awaited
+ * the runtime before its module body ran, so a send can never find it absent. Measured on
+ * `examples/dummy`'s run console, As of 2026-11-07: see `island-transport.test.ts`'s header.
+ */
+const transportSource = (): string =>
+  `import { runtimeSend } from '${WAIT}';\n` +
+  `export { settleAnswer } from '${CORE_TRANSPORT}';\n` +
+  `export function clientTransport(req) {\n  return runtimeSend(req);\n}\n`;
+
+/** Whether `file` is a source file of an installed `@ultimat3/core` — any copy of it. */
+async function inCore(file: string, cache: Map<string, Promise<boolean>>): Promise<boolean> {
+  const dir = dirname(file);
+  let known = cache.get(dir);
+  if (known === undefined) {
+    known = packageNameAbove(dir).then((name) => name === '@ultimat3/core');
+    cache.set(dir, known);
+  }
+  return await known;
+}
+
+async function packageNameAbove(start: string): Promise<string | undefined> {
+  for (let dir = start; dir !== dirname(dir); dir = dirname(dir)) {
+    const manifest = Bun.file(join(dir, 'package.json'));
+    if (!(await manifest.exists())) continue;
+    const parsed: unknown = await manifest.json();
+    const name =
+      typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'name') : undefined;
+    return typeof name === 'string' ? name : undefined;
+  }
+  return undefined;
+}
+
 /**
  * `runtime` names the realtime every bare `@ultimat3/realtime` of the build resolves to — the copy
  * the runtime chunk was built against, resolved from the first realtime island's directory. One
@@ -115,15 +155,36 @@ const restoreSource = (): string =>
  * sets is only read by hooks from the same module instance, and the page object it reads is the
  * shape that copy's runtime installs. `follows` is THIS build's islands that restore nothing: an
  * island absent from it waits for the restore, which is the answer that can never paint stale.
+ *
+ * `sendThroughRuntime` swaps core's transport for the runtime's (`transportSource`). Only for a
+ * build whose every entry is a realtime island: one split build shares a module between its
+ * entries, and a plain island never waits for a runtime to send through.
  */
 export function islandRealtimePlugin(
   root: string,
   runtime: RuntimeChunk,
   follows: ReadonlySet<string> = new Set(),
+  sendThroughRuntime = false,
 ): BunPlugin {
+  const cores = new Map<string, Promise<boolean>>();
   return {
     name: 'ultimate-island-realtime',
     setup(build) {
+      if (sendThroughRuntime) {
+        // Only core's own `./client-transport` — an app file of that name is the app's. The real
+        // file rides in the namespace path, so the module's SOURCE names no path on this machine.
+        build.onResolve({ filter: TRANSPORT_SPECIFIER }, async (args) =>
+          args.namespace === 'file' && (await inCore(args.importer, cores))
+            ? {
+                path: `${TRANSPORT_MODULE}${join(dirname(args.importer), 'client-transport.ts')}`,
+                namespace: NAMESPACE,
+              }
+            : undefined,
+        );
+        build.onResolve({ filter: /^ultimate:island-core-transport$/ }, (args) => ({
+          path: args.importer.slice(TRANSPORT_MODULE.length),
+        }));
+      }
       build.onResolve({ filter: /^ultimate:island-entry:/ }, (args) => ({
         path: `entry:${args.path.slice(REALTIME_ISLAND_ENTRY.length)}`,
         namespace: NAMESPACE,
@@ -158,7 +219,9 @@ export function islandRealtimePlugin(
             )
           : args.path === 'restore'
             ? restoreSource()
-            : installSource(runtime.url),
+            : args.path.startsWith(TRANSPORT_MODULE)
+              ? transportSource()
+              : installSource(runtime.url),
         loader: 'js',
       }));
     },

package/src/role-start.ts

@@ -26,6 +26,7 @@ import {
   outboxRelay,
   postgresLeaseLeader,
   postgresSchedulerState,
+  registeredJobs,
 } from '@ultimat3/jobs';
 import type { SyncWs } from '@ultimat3/realtime/server';
 import { errorPageHook } from './error-pages';
@@ -45,6 +46,7 @@ import { prepareSync, type RunningSync, syncReadsChanges } from './role-sync';
 import { startWorkerWake } from './role-wake';
 import { devHooks } from './runtime-hooks';
 import { workerOptionsFor } from './runtime-jobs';
+import { reportUnservedQueues } from './runtime-jobs-unserved';
 import { startLiveFeed } from './runtime-live-feed';
 import { type RunningServices, releaseOrThrow } from './runtime-services';
 import { inlineScriptSources } from './script-csp';
@@ -335,16 +337,30 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       prepared === null ? null : await prepared.listen(server === null ? null : server.url());
     if (sync !== null) releaseSync = sync.stop;
 
-    const worker = selected.includes('worker')
-      ? jobWorker({
-          driver: options.runtime.jobs,
-          build: options.buildId,
-          context: () => ctxOf({ role: 'worker', buildId: options.buildId }),
-          ...workerOptionsFor(options.runtime.workerConfig),
-        })
+    const workerOptions = selected.includes('worker')
+      ? workerOptionsFor(options.runtime.workerConfig)
       : null;
+    const worker =
+      workerOptions === null
+        ? null
+        : jobWorker({
+            driver: options.runtime.jobs,
+            build: options.buildId,
+            context: () => ctxOf({ role: 'worker', buildId: options.buildId }),
+            ...workerOptions,
+          });
     worker?.start();
     if (worker !== null) started.push(() => worker.stop('x dev stopped'));
+    // An exact worker (`WORKER_QUEUES`) names the registered queues NO live worker serves — after
+    // its start, so the registry holds its own row and the rest of the fleet's. Never rejects.
+    if (workerOptions !== null && options.runtime.workerConfig?.exact === true) {
+      const introspect = options.runtime.jobs.introspect;
+      void reportUnservedQueues({
+        served: workerOptions.queues ?? [],
+        registered: registeredJobs().map((handle) => handle.queue),
+        workers: introspect === undefined ? undefined : () => introspect.workers(),
+      });
+    }
 
     // The half of the transactional outbox that makes a staged row a running job. Without it
     // `handle.enqueue()` inside a transaction writes to `x_outbox` and nothing ever reads it back

package/src/runtime-jobs-unserved.ts

@@ -0,0 +1,46 @@
+// An exact worker's (`WORKER_QUEUES`) one boot line about the registered queues it leaves: warned
+// only for those NO live worker in the registry serves. Another Deployment serving the rest is the
+// whole point of the split, and a warning at every boot of a correct fleet is noise that hides the
+// one boot where a queue really has no worker.
+
+import { logger, renderThrowable } from '@ultimat3/core';
+import type { WorkerRecord } from '@ultimat3/jobs';
+
+export interface UnservedQueuesInput {
+  /** What this worker claims. */
+  readonly served: readonly string[];
+  /** Every queue a registered job is enqueued on. */
+  readonly registered: readonly string[];
+  /** The fleet's live rows (`introspect.workers`); `undefined` on a driver with no registry. */
+  readonly workers: (() => Promise<readonly WorkerRecord[]>) | undefined;
+}
+
+const FIX =
+  'x jobs list --json — every queue listed with no worker needs one: WORKER_QUEUES=<queue>,<queue> on another worker Deployment, or add it to this one';
+
+/** Never rejects: a boot line is advice, and a failed read of it must not fail the boot. */
+export async function reportUnservedQueues(input: UnservedQueuesInput): Promise<void> {
+  const left = [...new Set(input.registered)].filter((q) => !input.served.includes(q)).sort();
+  if (left.length === 0) return;
+  // Unknowable here: said at info, because the split may well be served elsewhere.
+  const unknown = (reason: string): void =>
+    logger.info('jobs.worker.queue-unserved', {
+      queues: left,
+      served: input.served,
+      checked: false,
+      reason,
+      fix: FIX,
+    });
+  if (input.workers === undefined) return unknown('this driver keeps no worker registry');
+  let rows: readonly WorkerRecord[];
+  try {
+    rows = await input.workers();
+  } catch (error) {
+    return unknown(renderThrowable(error));
+  }
+  // A draining worker is leaving: it claims nothing new, so it serves no queue.
+  const covered = new Set(rows.filter((one) => one.draining !== true).flatMap((one) => one.queues));
+  const queues = left.filter((queue) => !covered.has(queue));
+  if (queues.length === 0) return;
+  logger.warn('jobs.worker.queue-unserved', { queues, served: input.served, fix: FIX });
+}