@ultimat3/cli 30.3.0 → 30.4.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.4.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.4.0",
+    "@ultimat3/admin": "30.4.0",
+    "@ultimat3/ai": "30.4.0",
+    "@ultimat3/auth": "30.4.0",
+    "@ultimat3/cache": "30.4.0",
+    "@ultimat3/core": "30.4.0",
+    "@ultimat3/db": "30.4.0",
+    "@ultimat3/entity": "30.4.0",
+    "@ultimat3/flags": "30.4.0",
+    "@ultimat3/http": "30.4.0",
+    "@ultimat3/i18n": "30.4.0",
+    "@ultimat3/jobs": "30.4.0",
+    "@ultimat3/mail": "30.4.0",
+    "@ultimat3/manifest": "30.4.0",
+    "@ultimat3/mcp": "30.4.0",
+    "@ultimat3/money": "30.4.0",
+    "@ultimat3/notify": "30.4.0",
+    "@ultimat3/policy": "30.4.0",
+    "@ultimat3/pwa": "30.4.0",
+    "@ultimat3/query": "30.4.0",
+    "@ultimat3/realtime": "30.4.0",
+    "@ultimat3/render": "30.4.0",
+    "@ultimat3/schema": "30.4.0",
+    "@ultimat3/seo": "30.4.0",
+    "@ultimat3/storage": "30.4.0",
+    "@ultimat3/testing": "30.4.0",
+    "@ultimat3/time": "30.4.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/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 });
+}

package/src/runtime-jobs.ts

@@ -6,7 +6,6 @@
 import type { AppConfig, JobsConcurrency } from '@ultimat3/core';
 import {
   ConfigInvalidError,
-  logger,
   renderCauseValue,
   renderFixShellArg,
   UltimateError,
@@ -99,21 +98,6 @@ export function workerQueuesFor(
   return served.length === 0 ? undefined : served;
 }
 
-/**
- * An exact worker's one boot line about what it leaves: the queues registered jobs are enqueued
- * on that it will never claim. A warning and not a refusal — another Deployment serving them is
- * the whole point of the split — but this process cannot see that one, so it says what to check.
- */
-function reportUnserved(served: readonly string[], registered: readonly string[]): void {
-  const queues = [...new Set(registered)].filter((queue) => !served.includes(queue)).sort();
-  if (queues.length === 0) return;
-  logger.warn('jobs.worker.queue-unserved', {
-    queues,
-    served,
-    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's`,
-  });
-}
-
 /**
  * A `WORKER_QUEUES` entry no registered job and no `jobs.queues` entry names. The worker would
  * claim a queue nothing is enqueued on and leave the real ones waiting while its pod stays Ready —
@@ -183,7 +167,6 @@ export function workerOptionsFor(config: WorkerConfig | undefined): WorkerConfig
   const exact = config?.exact === true;
   if (exact) refuseUnknownQueues(config?.queues ?? [], config?.configured ?? [], registered);
   const queues = workerQueuesFor(config?.queues ?? [], registered, exact);
-  if (exact) reportUnserved(queues ?? [], registered);
   // Passed as written: `jobWorker` reads a table by own key and runs a queue it does not name at
   // core's `JOBS_CONCURRENCY_DEFAULT` — the one slot default, so no second table is built here.
   const concurrency = config?.concurrency;

package/src/templates/entity-module.ts

@@ -3,9 +3,14 @@
 // "the entity files this run wrote" asks here: three of them matched `/entity.ts` alone, so a
 // second entity in a feature could be written by nothing and registered by nothing.
 
-/** `apps/<app>/<surface>/<feature>/entity.ts` or `…/entity-<name>.ts` — never a test beside it. */
+/**
+ * `apps/<app>/<surface>/<feature>/entity.ts` or `…/entity-<name>.ts` — never a test beside it. A
+ * slice nests (`app/runs/canary/entity.ts`) as freely as any other feature directory does, so the
+ * feature is one segment or more: a depth-one rule refused a nested slice's entity at the package
+ * boundary while the app's own surface rules accepted the same file.
+ */
 const ENTITY_MODULE =
-  /^apps\/[^/]+\/(?<rest>[^/]+\/[a-z0-9-]+)\/(?<stem>entity(?:-[a-z0-9-]+)?)\.ts$/;
+  /^apps\/[^/]+\/(?<rest>[^/]+(?:\/[a-z0-9-]+)+)\/(?<stem>entity(?:-[a-z0-9-]+)?)\.ts$/;
 
 /** Whether `path` is a module a generator declares an entity in. */
 export const isEntityModule = (path: string): boolean => ENTITY_MODULE.test(path);

package/src/templates/scaffold-db-client.ts

@@ -111,7 +111,9 @@ const clientTest = (
 ): string => `// Which store the handle reads: memory under \`bun test\`, the process's Postgres client
 // everywhere else. A handle that silently took the memory driver in a container would serve an
 // empty database with a green gate.
+import { ctxOf, runWithContext } from '@ultimat3/core';
 import { recordingClient, setDbClient } from '@ultimat3/db';
+import { testActor } from '@ultimat3/policy';
 import { expect, unitTest } from '@ultimat3/testing';
 import { db, driver, selectDriver } from './client';
 
@@ -123,9 +125,27 @@ unitTest('${app.kebab} reads memory under test and Postgres everywhere else', ()
   expect(selectDriver({ ULTIMATE_ENV: 'development' }).reset).toBeUndefined();
 });
 
-unitTest('the handle is built over the driver this module exports', () => {
+// Every table on \`db\` reads through \`driver\`: a client installed under it sees each table's
+// statement. \`database(entities)\` with no driver takes the process default — memory — and would
+// answer every test from rows no migration made while this file stayed green. The reads run as an
+// actor because a tenant table refuses one with no org to scope it (\`X_TENANCY_UNSCOPED\`).
+unitTest('the handle is built over the driver this module exports', async () => {
   expect(driver.reset).toBeDefined();
-  expect(typeof db).toBe('object');
+  const tables: readonly { all(): Promise<readonly unknown[]> }[] = Object.values(db);
+  const { actor } = testActor('client-test', { orgId: '00000000-0000-4000-8000-000000000001' });
+  const client = recordingClient();
+  setDbClient(client);
+  try {
+    await runWithContext(ctxOf({ actor }), async () => {
+      for (const table of tables) {
+        const before = client.statements.length;
+        await table.all();
+        expect(client.statements.length).toBeGreaterThan(before);
+      }
+    });
+  } finally {
+    setDbClient(undefined);
+  }
 });
 
 // The test driver decides per call: a migrated database installed with \`setDbClient\` is what

package/src/templates/scaffold-mcp-admin.ts

@@ -0,0 +1,99 @@
+// The admin surface's own MCP endpoint, as `x new` writes it: `apps/admin/mcp.ts` — the file the
+// mount reads for that app directory (`app-mcp.ts`) — serving the admin catalog and the app's
+// exposed tools at `/admin/mcp`, behind the web surface's agent-token resolver. Mounted beside
+// `apps/web/mcp.ts`, and REFUSING without a token, like it.
+
+import { sortedImports } from './imports';
+import type { GeneratedFile, NameSet } from './naming';
+
+const endpoint = (
+  app: NameSet,
+): string => `// The admin surface's MCP endpoint: \`POST /admin/mcp\`, mounted beside \`apps/web/mcp.ts\` by \`x dev\`
+// and the web role, which mount every \`apps/<app>/mcp.ts\` by its path and its \`mcp\` export. Staff
+// agents get the admin's own tools (\`admin.<entity>.list\`, …) AND the app's exposed actions and
+// queries (\`include: 'exposed'\`), each gated by the actor's permissions and the token's scope.
+//
+// Built HERE, at module scope, and nowhere under \`apps/admin/app/\`: the boot scan evaluates this
+// file after every \`apps/*/{site,app,api,shared}\` module has registered its primitives, and the mount
+// refuses a catalog projected before that (X_MCP_INCLUDE_EARLY) rather than serve it short.
+${sortedImports([
+  `import { type AgentCaller, resolveAgentToken } from '@${app.kebab}/web/app/auth/agent-token';`,
+  "import { type AdminMcpActor, adminMcp } from '@ultimat3/admin';",
+])}
+import { admin } from './app/admin/admin';
+
+/**
+ * The admin's actor for the agent the app's resolver answered — the same agent \`/mcp\` serves,
+ * tenant and grants included. A key issued with scopes is held to its \`admin:*\` ones (a key
+ * scoped \`posts:write\` alone may call nothing here); a key with none is as strong as its actor.
+ */
+export const adminAgentOf = (caller: AgentCaller | null): AdminMcpActor | null => {
+  if (caller === null) return null;
+  const { id, roles, permissions, orgId } = caller.actor;
+  return {
+    id,
+    roles,
+    permissions,
+    ...(orgId === undefined ? {} : { orgId }),
+    ...(caller.scopes.size === 0 ? {} : { tokenScopes: [...caller.scopes] }),
+  };
+};
+
+export const mcp = adminMcp({
+  app: admin,
+  path: '/admin/mcp',
+  include: 'exposed',
+  // The app's one resolver: an issued API key in every environment, \`dev-agent.<role>\` under
+  // \`x dev\` from this machine alone — decided on how the request arrived (\`facts\`).
+  actor: async ({ token, facts }) =>
+    adminAgentOf(token === undefined ? null : await resolveAgentToken(token, facts)),
+});
+`;
+
+const endpointTest = (
+  app: NameSet,
+): string => `// The admin endpoint is mounted and refusing: a route at /admin/mcp, and a 401 for a request that
+// carries no token or one this process does not honour — before any tool, or the body, is read.
+${sortedImports([
+  `import { DEV_AGENT_TOKEN_PREFIX } from '@${app.kebab}/web/app/auth/agent-token';`,
+  `import { DEMO_ORG_ID } from '@${app.kebab}/web/shared/demo-org';`,
+  "import { agentActor } from '@ultimat3/core';",
+  "import { expect, unitTest } from '@ultimat3/testing';",
+])}
+import { adminAgentOf, mcp } from './mcp';
+
+const post = (headers: Record<string, string>) =>
+  new Request('http://localhost/admin/mcp', { method: 'POST', headers, body: '{}' });
+
+unitTest('POST /admin/mcp is mounted, and answers 401 without a token', async () => {
+  const route = mcp.route;
+  if (route === undefined) return expect.unreachable('apps/admin/mcp.ts built no route');
+  expect(route.path).toBe('/admin/mcp');
+  const response = await route.handle(post({}));
+  expect(response.status).toBe(401);
+  // The development token is refused outside \`x dev\`: \`bun test\` is not development.
+  const dev = await route.handle(post({ authorization: \`Bearer \${DEV_AGENT_TOKEN_PREFIX}admin\` }));
+  expect(dev.status).toBe(401);
+});
+
+unitTest('the agent /mcp resolves is the admin actor, tenant kept and scopes held', () => {
+  const actor = agentActor({ id: 'k1', orgId: DEMO_ORG_ID, roles: ['admin'] });
+  expect(adminAgentOf(null)).toBeNull();
+  // No scopes on the key: as strong as its actor, whose own grants still decide each tool.
+  expect(adminAgentOf({ actor, scopes: new Set() })).toEqual({
+    id: 'k1',
+    roles: ['admin'],
+    permissions: [],
+    orgId: DEMO_ORG_ID,
+  });
+  expect(adminAgentOf({ actor, scopes: new Set(['admin:read']) })?.tokenScopes).toEqual([
+    'admin:read',
+  ]);
+});
+`;
+
+/** `apps/admin/mcp.ts` and the test that pins it mounted and refusing. */
+export const mcpAdminFiles = (app: NameSet): readonly GeneratedFile[] => [
+  { path: 'apps/admin/mcp.ts', contents: endpoint(app) },
+  { path: 'apps/admin/mcp.test.ts', contents: endpointTest(app) },
+];

package/src/templates/scaffold-mcp-package.ts

@@ -1,8 +1,10 @@
 // The generated app's `packages/mcp`: the app's own MCP surface, projected straight from the
 // action registry rather than re-listed, plus the test that pins every projected tool describing
-// itself — and the `apps/web/mcp.ts` endpoint that mounts it (`scaffold-mcp-endpoint.ts`).
+// itself — and the endpoints that mount it: `apps/web/mcp.ts` (`scaffold-mcp-endpoint.ts`) and the
+// admin surface's `apps/admin/mcp.ts` (`scaffold-mcp-admin.ts`).
 
 import type { GeneratedFile, NameSet } from './naming';
+import { mcpAdminFiles } from './scaffold-mcp-admin';
 import { mcpEndpointFiles } from './scaffold-mcp-endpoint';
 import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shape';
 
@@ -77,7 +79,7 @@ contractTest('the app exposes its actions as MCP tools', () => {
 });
 `;
 
-/** Every file the `packages/mcp` workspace ships, then the endpoint that mounts it. */
+/** Every file the `packages/mcp` workspace ships, then the endpoints that mount it: web's, admin's. */
 export const mcpPackageFiles = (app: NameSet): readonly GeneratedFile[] => [
   { path: 'packages/mcp/package.json', contents: workspacePackageJson(app, 'mcp', DESCRIPTION) },
   ...packageShapeFiles(app, 'mcp', DESCRIPTION),
@@ -85,4 +87,5 @@ export const mcpPackageFiles = (app: NameSet): readonly GeneratedFile[] => [
   { path: 'packages/mcp/src/index.test.ts', contents: mcpUnitTest() },
   { path: 'packages/mcp/src/index.contract.test.ts', contents: mcpTest() },
   ...mcpEndpointFiles(app),
+  ...mcpAdminFiles(app),
 ];

package/src/upgrade-pins.ts

@@ -5,7 +5,7 @@
 // why: Bun exposes no path-join primitive; Bun.file takes one already joined.
 import { join } from 'node:path';
 import { UltimateError } from '@ultimat3/core';
-import { pinVersion, type UpgradePin } from './upgrade-plan';
+import { pinMoves, type UpgradePin } from './upgrade-plan';
 import { workspaceGlobs, workspaceManifestPaths } from './workspace-graph';
 
 const ROOT_MANIFEST = 'package.json';
@@ -53,11 +53,12 @@ export function readPins(manifests: readonly WorkspaceManifest[]): readonly Upgr
 }
 
 /**
- * Every pin at the exact version, the rest of the file byte-identical. Exact whatever it was: a
- * caret is how `^19.0.0` beside `^19.4.0` came to be mixed, and a range is a silent upgrade.
- * A spec naming no version never reaches here (`planHop` refused it), and is left as written.
+ * Every pin the hop moves at the exact version, the rest of the file byte-identical. Exact whatever
+ * it was: a caret is how `^19.0.0` beside `^19.4.0` came to be mixed, and a range is a silent
+ * upgrade. A pin above `to` is a workspace a mixed set has further on and stays (`pinMoves`); a
+ * spec naming no version never reaches here (`planHop` refused it), and is left as written.
  */
 export const rewritePins = (text: string, to: string): string =>
   text.replace(PIN_ENTRY, (whole, head: string, _name: string, spec: string, tail: string) =>
-    pinVersion(spec) === undefined ? whole : `${head}${to}${tail}`,
+    pinMoves(spec, to) ? `${head}${to}${tail}` : whole,
   );

package/src/upgrade-plan.ts

@@ -63,7 +63,7 @@ export function releaseOf(version: string): Triple | undefined {
 
 const tripleOf = (version: string): Triple => releaseOf(version) ?? [0, 0, 0];
 
-const compare = (a: string, b: string): number => {
+const compareVersions = (a: string, b: string): number => {
   const left = tripleOf(a);
   const right = tripleOf(b);
   return left[0] - right[0] || left[1] - right[1] || left[2] - right[2];
@@ -71,6 +71,15 @@ const compare = (a: string, b: string): number => {
 
 const majorOf = (version: string): number => tripleOf(version)[0];
 
+/**
+ * Whether a hop to `to` rewrites this pin. One at or below it moves; one above it — a workspace a
+ * mixed set already has further on — stays, since rewriting it would move it backwards.
+ */
+export const pinMoves = (spec: string, to: string): boolean => {
+  const version = pinVersion(spec);
+  return version !== undefined && compareVersions(version, to) <= 0;
+};
+
 /** The walkthrough that gets an app into `major`, built from the heading rule. */
 export function sectionFor(major: number): UpgradeSection {
   const from = RECORDED_FROM.get(major) ?? `${String(major - 1)}.x`;
@@ -97,7 +106,7 @@ const bareTarget = (from: string, released: readonly string[]): string | undefin
   const next = nextMajorNewest(from, released);
   if (next !== undefined) return next;
   const newest = newestOfMajor(majorOf(from), released);
-  return newest !== undefined && compare(newest, from) > 0 ? newest : undefined;
+  return newest !== undefined && compareVersions(newest, from) > 0 ? newest : undefined;
 };
 
 const unreadablePin = (cause: string, file: string): UltimateError =>
@@ -133,10 +142,21 @@ function readVersions(pins: readonly UpgradePin[]): readonly string[] {
  */
 const aligningVersion = (high: string, released: readonly string[]): string => {
   const newest = newestOfMajor(majorOf(high), released);
-  if (newest !== undefined && compare(newest, high) >= 0) return newest;
+  if (newest !== undefined && compareVersions(newest, high) >= 0) return newest;
   return nextMajorNewest(high, released) ?? high;
 };
 
+/**
+ * The one hop out of a mixed set: its lowest pins' next major, one walkthrough at a time, until that
+ * major reaches the highest pin's — where the hop that brings the set level is the next one.
+ */
+const lowestHop = (low: string, high: string, released: readonly string[]): string => {
+  const next = nextMajorNewest(low, released);
+  return next !== undefined && majorOf(next) < majorOf(high)
+    ? next
+    : aligningVersion(high, released);
+};
+
 const tooWide = (cause: string, target: string | undefined): UltimateError =>
   new UltimateError({
     code: 'X_UPGRADE_HOP_TOO_WIDE',
@@ -159,16 +179,18 @@ function checkTarget(input: {
       fix: 'bun pm view @ultimat3/cli versions --json   # then: x upgrade --to <one of them> --json',
     });
   }
-  // A mixed set has one way out, so every refusal over it names that way: a fix aimed at the next
-  // major of the lowest pin would itself be refused, for sitting below the highest.
-  const aligning = aligningVersion(high, released);
-  const way = low === high ? bareTarget(low, released) : aligning;
-  if (compare(to, high) < 0) {
+  // A mixed set has one way out, so every refusal over it names that way: its lowest pins, one
+  // major further. Never the highest pin's version: that skipped every walkthrough between.
+  const mixed = low !== high;
+  const step = mixed ? lowestHop(low, high, released) : (nextMajorNewest(low, released) ?? low);
+  const way = mixed ? step : bareTarget(low, released);
+  if (mixed && compareVersions(to, low) <= 0) {
+    throw tooWide(`--to ${to} moves none of the lowest pins, at ${low}`, way);
+  }
+  if (!mixed && compareVersions(to, high) < 0) {
     throw tooWide(`--to ${to} is below the ${high} this app already pins`, way);
   }
-  // The second operand is what makes the mixed refusal's own fix runnable: `^6` beside `^19` is told
-  // `--to <19.x>`, which brings the straggler level and crosses nothing the rest of the app has not.
-  const widest = Math.max(majorOf(nextMajorNewest(low, released) ?? low), majorOf(aligning));
+  const widest = majorOf(step);
   if (majorOf(to) > widest) {
     throw tooWide(
       `--to ${to} skips a major: from ${low} a run reaches ${String(widest)}.x at most, so each hop's gate attributes its red to that hop`,
@@ -184,11 +206,11 @@ export function planHop(input: {
   readonly to?: string;
 }): UpgradeHop {
   const { pins, to } = input;
-  const distinct = [...new Set(readVersions(pins))].sort(compare);
+  const distinct = [...new Set(readVersions(pins))].sort(compareVersions);
   const low = distinct[0] ?? '0.0.0';
   const high = distinct.at(-1) ?? low;
   const released = input.versions.filter((version) => releaseOf(version) !== undefined);
-  released.sort(compare);
+  released.sort(compareVersions);
 
   if (to === undefined && distinct.length > 1) {
     // The stragglers, not the first few: `^19.4.0` nineteen times says nothing about the one `^19.3.1`.
@@ -196,19 +218,24 @@ export function planHop(input: {
     const held = stragglers.map((pin) => `${pin.file}: ${pin.name} ${pin.spec}`);
     throw new UltimateError({
       code: 'X_UPGRADE_MIXED_PINS',
-      cause: `the workspaces pin ${distinct.join(', ')}, and the framework only moves in lockstep. ${String(held.length)} of ${String(pins.length)} below ${high}: ${held.slice(0, 6).join('; ')}`,
-      fix: `x upgrade --to ${quoteArg(aligningVersion(high, released))} --json`,
+      cause: `the workspaces pin ${distinct.join(', ')}, and the framework only moves in lockstep, so a run moves the lowest pins one major until the set is level. ${String(held.length)} of ${String(pins.length)} below ${high}: ${held.slice(0, 6).join('; ')}`,
+      fix: `x upgrade --to ${quoteArg(lowestHop(low, high, released))} --json`,
     });
   }
   if (to !== undefined) checkTarget({ to, low, high, released });
 
   const target = to ?? bareTarget(low, released) ?? low;
-  const after = bareTarget(target, released) ?? null;
+  // Still below the highest pin, the set stays mixed: the next run is the lowest pins' next hop.
+  const after =
+    compareVersions(target, high) < 0
+      ? lowestHop(target, high, released)
+      : (bareTarget(target, released) ?? null);
   return {
     from: low,
     to: target,
     next: after,
     atTarget: distinct.length === 1 && target === low,
-    section: majorOf(target) > majorOf(high) ? sectionFor(majorOf(target)) : null,
+    // The lowest pins are the ones that cross: theirs is the walkthrough this hop needs.
+    section: majorOf(target) > majorOf(low) ? sectionFor(majorOf(target)) : null,
   };
 }

package/src/upgrade-report.ts

@@ -7,6 +7,7 @@ import type { AgentsLinkState } from './upgrade-agents-link';
 import type { BunEdit, BunManual } from './upgrade-bun-floor';
 import type { GateFinding, HopGate, RepoScript } from './upgrade-gate';
 import type { UpgradeHop, UpgradePin } from './upgrade-plan';
+import { pinMoves } from './upgrade-plan';
 
 export interface PlannedWrites {
   /** Absolute path to final text; a manifest holding both a pin and a floor is written once. */
@@ -125,7 +126,9 @@ export const report = (input: {
     section: hop.section,
     pins: hop.atTarget
       ? []
-      : pins.map((pin) => ({ file: pin.file, name: pin.name, from: pin.spec, to: hop.to })),
+      : pins
+          .filter((pin) => pinMoves(pin.spec, hop.to))
+          .map((pin) => ({ file: pin.file, name: pin.name, from: pin.spec, to: hop.to })),
     bun: { from: bunFrom, to: bunTo, edited: writes.edited, manual: writes.manual },
     agentsMd: input.agentsMd ?? null,
     guards: gate?.guards ?? null,

package/src/verify-checks.ts

@@ -52,6 +52,7 @@ import { unknownToolGateFindings } from './tool-gate-names';
 import { measureIfStale } from './verify-budgets-build';
 import { exerciseStep } from './verify-exercise';
 import { floorProblemFindings, readVerifyFloor } from './verify-floor';
+import { mcpMountFindings } from './verify-mcp-mount';
 import { roleLoadFindings } from './verify-role-load';
 import type { VerifyStep } from './verify-step';
 import { fromExec, fromFindings, hostFindings } from './verify-step';
@@ -400,6 +401,8 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
               ...(await unregisteredJobFindings(ctx.root)),
               ...(await retainUnsweptFindings(ctx.root)),
               ...(await readJobBudgetFindings(ctx.root)),
+              // `ai.mcp.expose: true` and no mounted `POST /mcp`: what every boot only logged.
+              ...(await mcpMountFindings(ctx.root)),
               ...(await unknownToolGateFindings(ctx.root)),
               ...remote.findings,
             ]

package/src/verify-mcp-mount.ts

@@ -0,0 +1,30 @@
+// The `manifest` step's MCP rider: `ai.mcp.expose: true` with nothing mounted is a finding. The
+// boot's own `appMcpMount` decides it — the same answer `x dev` and the web role log — so the gate
+// and the boot can never disagree about whether `POST /mcp` exists. A boot only WARNED, and every
+// tracked app shipped its catalog unmounted behind that warning.
+
+import { isUltimateError } from '@ultimat3/core';
+import { loadApp } from './app-load';
+import { appMcpMount } from './app-mcp';
+import type { AppLoader } from './app-permissions';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/**
+ * Empty when the app did not load (the load findings say so, once) or `expose` is off. A refusal
+ * the mount THROWS — two files on one path (`X_MCP_PATH_DUPLICATE`), a catalog projected before the
+ * scan (`X_MCP_INCLUDE_EARLY`) — is a finding too: the boot would stop on it.
+ */
+export async function mcpMountFindings(
+  root: string,
+  load: AppLoader = loadApp,
+): Promise<readonly Finding[]> {
+  if ((await load(root)).findings.length > 0) return [];
+  try {
+    const { warning } = await appMcpMount(root);
+    return warning === undefined ? [] : [findingFrom(warning)];
+  } catch (error) {
+    if (isUltimateError(error)) return [findingFrom(error)];
+    throw error;
+  }
+}

package/wiki/Admin-Dashboard.md

@@ -253,6 +253,37 @@ mcp: { expose: true, description: 'Publish a draft post' },
 
 The projected tool calls `action.run(...)` — the same entry point the HTTP route calls. Policy evaluation lives inside `run`, so there is nothing to keep in sync. Details: [MCP and AI](MCP-And-AI).
 
+### An admin surface serves the app's tools
+
+`As of 2026-11`. One way: `apps/admin/mcp.ts` exports `adminMcp(...)`, at module scope, and the
+mount serves it beside `apps/web/mcp.ts`. `x new` writes it.
+
+```ts
+// apps/admin/mcp.ts
+import { type AdminApp, type AdminMcpActor, adminMcp } from '@ultimat3/admin';
+import type { McpRequestFacts } from '@ultimat3/mcp';
+declare const admin: AdminApp; // `import { admin } from './app/admin/admin'` — the defineAdmin() module
+// The web surface's resolver (`apps/web/app/auth/agent-token.ts`) and its mapping onto an admin actor,
+// both as `x new` writes them.
+declare function resolveAgentToken(token: string, facts?: McpRequestFacts): Promise<unknown>;
+declare function adminAgentOf(caller: unknown): AdminMcpActor | null;
+
+export const mcp = adminMcp({
+  app: admin,
+  path: '/admin/mcp',
+  include: 'exposed',
+  actor: async ({ token, facts }) =>
+    adminAgentOf(token === undefined ? null : await resolveAgentToken(token, facts)),
+});
+```
+
+| Option | Rule |
+|---|---|
+| `path` | `defineAppMcp`'s own; default `/mcp`, which collides with the web endpoint (`X_MCP_PATH_DUPLICATE`) — an admin surface says `/admin/mcp` |
+| `include: 'exposed'` | every action and query with `mcp: { expose: true }`, projected as on `/mcp` (opt-in, the one predicate), each under its kind's admin scope: a query `admin:read`, an action `admin:write` |
+| `actor({ token, facts })` | `facts` is how the request arrived (address, `Origin`) — what a development token is decided on |
+| where it is built | `apps/<app>/mcp.ts`, never under `apps/admin/app/`: the scan evaluates the former after every primitive registered; one built earlier is `X_MCP_INCLUDE_EARLY` at the mount |
+
 ### Tool scopes
 
 `As of 2026-10`. `adminMcp()` hands the MCP registry one scope per tool (`adminToolScopes`, `packages/admin/src/mcp-scopes.ts`). Tool names are unchanged.

package/wiki/CLI-Reference.md

@@ -1532,7 +1532,7 @@ One major per run, so each hop's gate attributes its red to that hop. `As of 30.
 
 A dry run refuses exactly what the real run would, then stops before step 4. It never commits; `git diff` is the hop. Under `--json` fd 1 is one document, fd 2 a `{"upgrade":"<stage>"}` line per stage and a heartbeat a minute.
 
-`--to`: an exact release in the next major. Over a mixed set every refusal names the aligning version, the newest release at or above the highest pin: `^6` beside `^19` is told `--to 19.x.y`, it is accepted across any distance, and that report names no section.
+`--to`: an exact release in the next major. Over a mixed set a run moves the LOWEST pins one major: `^19` beside `^29` is told `--to 20.x.y`, that hop rewrites only the pins at or below it (a pin above is never moved backwards) and names its walkthrough, `next` names the following hop, and the last one levels the set. A straggler jump straight to the highest major is `X_UPGRADE_HOP_TOO_WIDE`: it skipped every walkthrough between.
 
 | `data` field | Meaning |
 |---|---|

package/wiki/Configuration.md

@@ -148,7 +148,7 @@ ROLE: worker                          ROLE: worker
 WORKER_QUEUES: banks                  WORKER_QUEUES: banks-long
 ```
 
-Each worker then claims its list and nothing else. Every entry must be a queue the app knows — in `jobs.queues` or a registered job's — or the boot refuses with `X_WORKER_QUEUE_UNKNOWN` (`As of 29.0.0`). At boot it logs `jobs.worker.queue-unserved` (a warning, not a refusal) naming every queue a registered job is enqueued on that it will not claim, so a queue no Deployment serves is visible in the first log line rather than as a backlog. `x jobs list --json` shows each queue's workers.
+Each worker then claims its list and nothing else. Every entry must be a queue the app knows — in `jobs.queues` or a registered job's — or the boot refuses with `X_WORKER_QUEUE_UNKNOWN` (`As of 29.0.0`). After it starts it logs `jobs.worker.queue-unserved` (a warning, not a refusal) naming every queue a registered job is enqueued on that NO live worker in the registry serves (`As of 2026-11-07`), so a queue no Deployment serves is visible in the first log line rather than as a backlog — and a split fleet whose other Deployments serve the rest logs nothing. A driver with no worker registry says it at `info`. `x jobs list --json` shows each queue's workers.
 
 ## `realtime`
 

package/wiki/Deployment.md

@@ -248,7 +248,7 @@ services:
   # WORKER_QUEUES is the EXACT set a worker claims (25.0.0): `integrations` runs on its own
   # service, so the other worker names every remaining queue itself. Unset, a worker claims
   # jobs.queues plus every queue a registered job is enqueued on; set, `jobs.worker.queue-unserved`
-  # at boot names the registered queues this one leaves to another.
+  # names the registered queues it leaves that NO live worker serves — none, once `integrations` is up.
   worker:     { <<: *app, environment: { ROLE: worker, WORKER_QUEUES: 'myapp-default,default' },
                 deploy: { replicas: 4 } }
   worker-integrations: { <<: *app, environment: { ROLE: worker, WORKER_QUEUES: integrations },

package/wiki/Jobs-And-Workflows.md

@@ -148,6 +148,8 @@ run: async ({ input, ctx, step }) => {
 
 **A cancelled body writes nothing** (`As of 2026-11-02`). Once `ctx.signal` is aborted with a coded reason (`X_ABORTED`, `X_DRAINING`, `X_JOB_TIMEOUT`, `X_JOB_SLOT_LOST`, `X_JOB_LEASE_LOST`), a transaction, an entity write and an `enqueue` rethrow that reason. The step record stays fenced as before and a drained step still lands. Wrap work that must land in `runToCompletion(fn)`.
 
+**A finished attempt is not a cancelled one** (`As of 2026-11-07`). A body that completed, and whose `ack` landed, leaves `ctx.signal` un-aborted: no other attempt owns the run, so a timer it armed — a log sink's flush, an `end()` timeout, a deferred `enqueue` — still writes. A step it never awaited is refused (`X_ABORTED`, "had already ended"). A failed or suspended attempt, or a completed one whose `ack` did not land, aborts with `X_ABORTED` as before. Work meant to outlive the attempt whatever its end has ONE way: `runToCompletion(() => work)` from `@ultimat3/core`.
+
 **SIGTERM fires it too** (`As of 2026-09-07`). The moment the process starts draining, the worker aborts `ctx.signal` on every job it holds with `X_DRAINING` — naming the worker and the signal — and then gives the body the drain's budget to unwind in. A body that stops is **interrupted**, not failed: the job goes straight back to the ready bucket with the attempt uncounted, so `attempts: 1` survives a rollout and the worker replacing this one claims it at once. The verdict is read off the signal, not off whatever the body threw, so an app's own error for a child the shutdown killed is an interruption too. A body that ignores the signal is waited on to the deadline and abandoned there, as before; a manual `worker.stop()` aborts nothing and waits for its work — until a SIGTERM lands on it, at which point the teardown already waiting adopts the shutdown's deadline and every held job hears the abort.
 
 | Past the cancel | What happens |

package/wiki/MCP-And-AI.md

@@ -257,16 +257,19 @@ developer's.
 `As of 2026-09-05`. `defineAppMcp({ …, resolveToken })` builds `mcp.route`, and `app.config.ts`
 declares `ai: { mcp: { expose: true } }` **by default** (the path is `defineAppMcp`'s own, `/mcp` by default) — and until this date nothing
 between the two served it: `POST /mcp` was `X_ROUTE_NOT_FOUND` under `x dev` and in every
-container. The contract is one file:
+container. The contract is one file per app directory:
 
 | Piece | Where | Rule |
 |---|---|---|
 | the declaration | `apps/<app>/mcp.ts` | `export const mcp = defineAppMcp({ include: 'exposed', resolveToken })` |
-| the switch and the path | `app.config.ts` → `ai.mcp` | `expose` (default `true`), `path` (default `/mcp`) |
+| the switch | `app.config.ts` → `ai.mcp` | `expose` (default `true`). The path is each endpoint's own `defineAppMcp({ path })` (default `/mcp`) |
+| several app directories | every `apps/<app>/mcp.ts` mounts (`As of 2026-11`) | `apps/web/mcp.ts` first — its first endpoint is the default — then the rest sorted. An admin surface's `apps/admin/mcp.ts` stands beside the web one; until 2026-11 the first sorted file mounted ALONE, so it silently took `/mcp` away. Two files claiming one route: `X_MCP_PATH_DUPLICATE` naming both |
+| when it is built | at the top level of `apps/<app>/mcp.ts` | the boot scan evaluates that file after every `apps/*/{site,app,api,shared}` module has registered, so `include: 'exposed'` sees every exposed primitive. An endpoint projected earlier — in a module under `apps/<app>/app/` that `mcp.ts` re-exports — is `X_MCP_INCLUDE_EARLY` at the mount, naming the tools it lacks, never a short catalog. Never import the API index to fill the registry (`X_BOUNDARY_APP_TO_API`) |
 | the mount | `x dev` **and** `runRole`, through one call | `POST <path>` → `mcp.route.handle(request)`; the boot log says `app mcp mounted`, `x dev`'s summary prints `mcp POST /mcp` |
 | auth | the route's own | `auth: 'public'`, `enforcedBy: 'handler'` on the http route — the bearer token is read by `resolveToken`, never pre-judged by the pipeline |
 | exposed and unmountable | `X_MCP_APP_UNMOUNTED`, logged once | no file exports `mcp`, or it was built without `resolveToken` (no `route`); the fix names the file to write |
 | a new app | `x new` writes it | `apps/web/mcp.ts` over the `@<app>/mcp` catalog, `resolveToken` from `apps/web/app/auth/agent-token.ts`: an API key (`issueApiKey`, `x_api_keys`) is an agent in every environment; `dev-agent.<role>` is one under `x dev` alone, and only from a loopback address with no `Origin` (a page rebound to 127.0.0.1 sends one). No token, or one it does not know: 401 |
+| the admin surface | `x new` writes it too | `apps/admin/mcp.ts`: `adminMcp({ app: admin, path: '/admin/mcp', include: 'exposed', actor })` — the admin's own tools and the app's exposed ones, the actor from the same `resolveAgentToken` (handed the request's `facts`). A key with scopes is held to its `admin:*` ones, a key with none is as strong as its actor → [Admin dashboard](Admin-Dashboard#an-admin-surface-serves-the-apps-tools) |
 
 **A token from an external issuer** (`As of 2026-11-05`): an app whose agents present an IdP's JWT
 rather than an API key hands `defineAppMcp` `jwtBearerResolver` from `@ultimat3/auth` — the twin of

package/wiki/Testing.md

@@ -594,6 +594,7 @@ unitTest('a row deleted before the run is skipped, not failed', async ({ runJobs
 | On the trace or the call | Is |
 |---|---|
 | `trace.executions[n].result` | what the body returned. Absent on a run that failed, suspended or was interrupted |
+| `trace.executions[n].code` | the stable `X_*` code a failed run's error carried, beside its `error` message. Absent on an uncoded throw and on a run that did not fail |
 | `trace.steps[name].executions` | times the step body ran — a replay from storage does not count. Cumulative for the test |
 | `runJobs(job, input, { actor })` · `drain({ actor })` | the identity the **worker** runs as (`WorkerOptions.context()` in a real one). Its org is still the job's declared `tenant`; `tenant: 'none'` strips it. Absent is the anonymous actor |
 | `runJobs(job, input, { tenantId })` · `enqueue(…, { tenantId })` | the **enqueuer's** tenant on the row: the limiter's bucket and the dedupe namespace, as `handle.as(actor, input)` files it. One key in two tenants is two jobs |
@@ -673,6 +674,12 @@ describeIslandState(counterStates, 'idle', island, (mounted) => {
 The props are the manifest's, so the picture `x shot --island` takes and the test are of one
 component. `mountIsland` stays the call for props no state declares. `As of 2026-10`.
 
+A realtime island's page outlives its mount: the socket, the record store and the outbox sit on
+`globalThis`, shared by every bundle. Between files (or cases that need a fresh page) call
+`resetPageRealtime()` from `@ultimat3/realtime` in `afterAll` — it closes the socket the CHUNK's copy
+of realtime built and drops every page global. Never `Reflect.deleteProperty(globalThis,
+Symbol.for('ultimate.realtime'))`: that leaves the socket open. `As of 2026-11`.
+
 ## Testing an authenticator
 
 ```ts
@@ -846,7 +853,7 @@ A column whose value comes from another factory, built with the **same strategy*
 
 `ids.uuid()` and `ids.number()` come from the seeded generators; `index` starts at 1 for the first row.
 
-`factoriesFor(registry, seed?)` derives a factory per entity, each value read off the column's **declaration**, never its name (`As of 2026-11`, 30.0.0 entry 89): the declared default first, else an enumerated value, else what the kind offers (uuid, text, integer, boolean, timestamp, money as `{ minor, currency }`, …), and `null` only where the column is nullable. Every candidate goes through the column's own `$parse`, so a built row is one the table stores. A registry entry whose `$columns` are not `entity()` columns, or a column that refuses every generated value (a `json(t.object(…))` with required keys), throws `X_SEED_GRAPH_UNSATISFIED` at `build()`, naming the `defineFactory` to write. Source: `packages/testing/src/factory-registry.ts`, `seed-graph-values.ts`.
+`factoriesFor(registry, seed?)` derives a factory per entity, each value read off the column's **declaration**, never its name (`As of 2026-11`, 30.0.0 entry 89): the declared default first, else an enumerated value, else what the kind offers (uuid, text, integer, boolean, timestamp, money as `{ minor, currency }`, …), and `null` only where the column is nullable. A text column held to a `matches(/…/)` invariant is also offered strings built from that pattern, and those come first; a `json(schema)` column is offered values its schema accepts (`As of 2026-11-07`). Every candidate goes through the column's own `$parse`, so a built row is one the table stores. A registry entry whose `$columns` are not `entity()` columns, or a column that refuses every generated value (a `json()` whose schema carries a `pattern` its sampler cannot meet), throws `X_SEED_GRAPH_UNSATISFIED` at `build()`, naming the `defineFactory` to write. Source: `packages/testing/src/factory-registry.ts`, `seed-graph-values.ts`.
 
 ### Persisting
 
@@ -889,8 +896,9 @@ await insertSeedGraph(graph, writer);
 |---|---|
 | order | parents before children, over the entities' own `$references()` |
 | tenancy | each child points at a parent of its **own** tenant; the entity a tenant column references holds one row per tenant, keyed by the tenant. A table with no tenant column whose references reach a tenant-owned one, and no `shared` reason, is seeded per tenant too, under its own tenant's parent — `row.tenant` is that parent's tenant |
-| a cycle | broken at a nullable key: inserted `null`, set by an entry of `graph.updates` once its target exists. A cycle with no nullable key is `X_SEED_GRAPH_UNSATISFIED` |
+| a cycle | broken at a nullable key: inserted `null`, set by an entry of `graph.updates` once its target exists. The break prefers a table that takes updates — never an `appendOnly` one, whose key stays `null` when it is the only break. In `x exercise`, a deferred update the database refuses (a trigger no declaration carries) leaves the key `null`; an environment failure still fails. A cycle with no nullable key is `X_SEED_GRAPH_UNSATISFIED` |
 | values | read off the declaration, as `factoriesFor` reads them, and kept only if `$parse` accepts them |
+| patterns and schemas | a `matches(/…/)` pattern adds strings drawn from the pattern itself: literals, classes, `.`, groups, `\|`, quantifiers, anchors. Lookaround, backreferences, `\b` and `\p{…}` add nothing, so the column's other candidates stand. A `json(schema)` column draws from its schema, as the contract step's `arbitrary` does. Both are seeded by the row, so the same seed gives the same bytes |
 | rules | every invariant, the primary key, unique columns and unique indexes are kept; a partial unique is treated as total. A unique column that runs out of values ends its table early — but a table-wide unique that runs out before every tenant holds a row is `X_SEED_GRAPH_UNSATISFIED` (`… runs out of values before tenant 2 of 2 holds a row`): that tenant's children would have no parent |
 | an unseeded target | a key — the tenant column included — whose target entity is not in the set is `X_SEED_GRAPH_UNSATISFIED` (`… which is not in the set seeded — pass it too`) |
 | soft delete | a soft-deleting table's `deletedAt` is `null` unless a factory builds it: seeded rows are live |
@@ -957,7 +965,8 @@ A legal input that crashes the handler is red in `contract`, the day the action
 | Runs | 16 (`EXERCISE_RUNS` from `@ultimat3/core`), `runs` from 1 to 64. Runs 0-3 sit on the IR's bounds (`minLength`, `maxLength`, `minimum`, `maximum`, `minItems`). The rest draw multibyte text, every enum and union member, optional keys on and off, `null` where nullable. A format value (`t.uuid`, `t.email`, …) is never varied |
 | Seed | `fnv1a(<action name>)`, never time, so a red run replays: `bun test <file> -t '<name>: handler survives generated input'` |
 | Rolled back | each run inside a memory transaction, always, and in it `withTransaction` when SQL can hold the writes: a SAVEPOINT in a test's open transaction, a root transaction once `setDbClient` installed a client. Both always roll back. The handler's SQL writes, its memory-store writes (`storeMode` `memory`, `tx` passed or not, since `memoryTransactor().run` is ambient), the outbox stage and the post-commit bust drop with it (`packages/action/src/tx-scope.ts` `inRolledBackScope`) |
-| **Not rolled back** | a write on a second client or `outsideTransaction`. A job enqueued with `outbox: false`. Storage puts. Mail and outbound fetch: the test preload seals both, so a real one is only sent where a test opted out. Rate-limit counters. An audit record a non-database sink accepted |
+| **Not rolled back** | a write on a second client or `outsideTransaction`. A job enqueued with `outbox: false`. Storage puts. Mail and outbound fetch: the test preload seals both, so a real one is only sent where a test opted out. An audit record a non-database sink accepted |
+| Rate-limit counters | spent in a scratch store of the exercise's own (`withScratchRateLimitStore`, `@ultimat3/http`), answering for the installed store's scope: the same file's next call has its whole declared limit |
 | Where it runs | `development` and `test` only. `staging` or `production` (`ULTIMATE_ENV`, else `NODE_ENV`) is `X_CONTRACT_EXERCISE_ENVIRONMENT` before the first run: generated input never reaches a deploy. `bun test` sets `NODE_ENV=test` |
 | Pass | the output parsed, or a coded refusal under 500 |
 | Defect, `X_CONTRACT_DEFECT` | an uncoded throw, `X_OUTPUT_INVALID`, or a coded 5xx (an undeclared `errors:` code is one). `meta.run`, `meta.input`, `meta.failure` |
@@ -984,11 +993,13 @@ shape, same unreached code. `As of 2026-11`.
 | Rows | one seed graph for the pass, a fresh pair of tenants per primitive in it — the first the actor's (A), the second the tenant proof's intruder (B); every table seeded off its declaration, parents first, same-tenant keys (`x db seed --generate`'s graph). A view and a `readOnly: '<why>'` table get no row; a NOT NULL key into a `readOnly` one is `X_SEED_GRAPH_UNSATISFIED` naming it ([Read-only tables](Entities-And-Migrations#read-only-tables)) |
 | Actor | the first of `x policy explain`'s actors the policy allows, in the primitive's tenant. None allowed is `refused`, by design |
 | Input | the override, then an id field whose stem names a seeded entity (`postId` → `posts`), then the schema's minimal draw. A wrong guess shows as `unreached` |
-| A job's org | the field(s) its `tenant(input)` reads — any name, nested, or left out of the draw — are set to the tenant it is enqueued in, found by reading them: A's for the control, B's for the tenant proof (B's own job, carrying A's ids). A `tenant` no input field moves (one fixed org) is `unreached`, `X_JOB_TENANT_MISMATCH`, its `fix:` the declaration: `tenant: (input) => input.orgId` |
+| A job's org | the field(s) its `tenant(input)` reads — any name, nested, left out of the draw, or under a parent the draw left out (a scoped backfill's `payload.input.orgId`) — are set to the tenant it is enqueued in, found by reading them: A's for the control, B's for the tenant proof (B's own job, carrying A's ids). A `tenant` no input field moves (one fixed org) is `unreached`, `X_JOB_TENANT_MISMATCH`, its `fix:` the declaration: `tenant: (input) => input.orgId` |
+| A job's failure | judged by the action rule: a coded refusal under 500 (an app's 409) is `unreached` under its own code, never a defect; an uncoded throw or a coded 5xx is `X_CONTRACT_DEFECT` |
 | Async input | an override's `input` may be `async`: it is awaited inside the call's request, as the call's actor, so it can mint what the action checks (a one-time token, a passkey assertion). `x drill`'s load skips an `async` input and says why |
 | Room | network sealed, mail captured, jobs in memory, clock frozen — from before the app loads and the scratch database boots, as `bun test`'s preload does, so the embedded Postgres never sees its clock jump. A call out is refused and counted, so the primitive is `unreached` |
 | Cost | rows are primitives × tables; statements are not: the graph is written one `insertAll` per table, each tenant-proof snapshot is one statement, and a primitive reads only its own pair's rows of the graph |
 | Overrides | `apps/web/exercise.ts`: `export const exercise = defineExercise({ publishPost: { actor, input }, sendInvoice: { off: '<why>' } })`. Each value is `.contract({ exercise })`'s option. An unknown name is `X_DECLARATION_UNKNOWN`; a blank `off` is `X_CONTRACT_EXERCISE_UNDECLARED` |
+| A handler that calls a vendor | `defineExercise({ … }, { setup: () => { mockFetch('https://api.vendor.test/*', handler); } })` — or `setup: () => cassette(import.meta.dir, 'exercise')`. Runs once in the exercise process, after the seal and before the first row; what it returns is disposed after the pass. A call a setup route answers is reached, not refused. `allowHost` in it is `X_EXERCISE_SETUP_UNSEALED` |
 | Rows a generated value cannot satisfy | a cross-column `c.satisfies(…)` reads `X_SEED_GRAPH_UNSATISFIED`: `defineExercise({ … }, { factories: { bosses: defineFactory(bosses, { defaults: (i) => ({ … }) }) } })`, keyed by entity name, the graph's keys kept. A column that follows from a key or reference the graph picked: `derive: (row) => ({ scopeKey: … })` beside `build`/`reset`, reading `row.ownerOrgId`. A partial unique whose columns the factory builds is the database's to judge. An unknown name is `X_DECLARATION_UNKNOWN` |
 | Report | `.x/exercise.json` and `--json`: `{ seed, counts, records[] }`, each record `{ kind, name, outcome, code?, reason?, statements, effects, ms, override?, fix?, tenant?, crash? }` — `fix` where no override reaches it. The fields before `tenant` are A's call. The human table's `tenant` and `crash` columns are the verdicts, `-` where none ran |
 | Gate | the `exercise` step, after `job`, runs `x exercise --json` as a child and is red on its findings: `X_CONTRACT_EXERCISE_UNREACHED`, `X_TENANT_LEAK`, `X_TENANT_WRITE_CROSSED`, `X_JOB_CRASH_DIVERGED`, and — on a whole pass, not `x exercise <name>` — `X_ENTITY_TENANT_UNDECLARED`. `unreached` is never sampled or skipped: it is a finding whose `fix:` is the entry to paste |

package/wiki/Upgrading.md

@@ -1,6 +1,6 @@
 # Upgrading
 
-**`As of 2026-08`. Semver applies from here.** A breaking change to a documented API needs a major. Every `@ultimat3/*` package moves in lockstep — never mix versions. An app declares them at `^<version>`, as `x new` writes, and `bun.lock` pins the exact build.
+**`As of 2026-08`. Semver applies from here.** A breaking change to a documented API needs a major. Every `@ultimat3/*` package moves in lockstep — never mix versions. `x new` declares them at `^<version>`, so `bun update` takes a same-major fix before the first hop; `x upgrade` rewrites every pin it moves exact (`20.1.0`, no caret), on purpose — a caret is how `^19.0.0` beside `^19.4.0` came to be mixed, and a range is a silent upgrade. `bun.lock` pins the exact build either way.
 
 > **From v30, one major per 90 days.** The window, what semver covers, the support window and the security exception: [Stability](Stability). A removal now ships its `@deprecated` alias for at least one minor before a major takes it, so `x upgrade` across one major names no edit a minor did not already warn about. The 29 sections below stay as they are.
 
@@ -299,6 +299,7 @@ Only an app that relied on the old behaviour has anything to do:
 | What moved | Do |
 |---|---|
 | with `DATABASE_REPLICA_URL` set, a request that wrote sets `__Host-x-pos` and `x-ultimate-position` | nothing. A proxy with a cookie allowlist passes `__Host-x-pos`; stripped, the next read may land on a standby that has not replayed the write |
+| a job attempt that completed and was acked leaves `ctx.signal` un-aborted (`As of 2026-11-07`); before, its timers' writes and enqueues were refused `X_ABORTED`, "was cancelled" | nothing. A body that read an aborted signal as "the run ended" reads the settle instead (`onSettled`); work that must outlive a FAILED attempt too runs in `runToCompletion(() => work)` from `@ultimat3/core` |
 | `onSettled`'s `ctx.signal` is live | a hook that treated an aborted signal as "the run ended" reads `settled.outcome` instead. It is aborted at `onSettledTimeout`, 30 s across every try by default: raise it on a hook that takes longer |
 | `publishEvent` inside a transaction commits and rolls back with it | nothing, unless a rolled-back event must still resume a run: publish it in `outsideTransaction(fn)` |
 | the `drift` step's `rollingSince` rail is off until set | optional: set `rollingSince` in `x.verify.json` to your newest applied migration id. `x doctor` reminds you |
@@ -3566,7 +3567,7 @@ bunx @ultimat3/cli@latest upgrade --json    # an app below 30.0.0, whose own CLI
 
 A repository with pins and no `app.config.ts` hops too: no `x verify` can run, so it runs the `typecheck` and `test` scripts it declares, and `data.proof` (`verify`, `scripts`, `none`) says what `done` rests on.
 
-Refusals name their own fix: `X_UPGRADE_MIXED_PINS` (`x upgrade --to <the higher version> --json`), `X_UPGRADE_HOP_TOO_WIDE`, `X_UPGRADE_PIN_UNREADABLE`, `X_UPGRADE_REGISTRY_UNREACHABLE`, `X_UPGRADE_VERSION_UNPUBLISHED`, `X_UPGRADE_INSTALL_FAILED`. `data.bun.manual[]` lists what only you can move: a digest-pinned image, an expression. `data.guards.differs[]` offers `x g guard <name> --force`, and your guard is never touched. A hop below 30.0.0 reports `X_BUDGET_UNMEASURED` until `x build --target static --json` has run. Field by field: [CLI reference](CLI-Reference#x-upgrade).
+Refusals name their own fix: `X_UPGRADE_MIXED_PINS` (`x upgrade --to <the lowest pins' next major> --json`), `X_UPGRADE_HOP_TOO_WIDE`, `X_UPGRADE_PIN_UNREADABLE`, `X_UPGRADE_REGISTRY_UNREACHABLE`, `X_UPGRADE_VERSION_UNPUBLISHED`, `X_UPGRADE_INSTALL_FAILED`. `data.bun.manual[]` lists what only you can move: a digest-pinned image, an expression. `data.guards.differs[]` offers `x g guard <name> --force`, and your guard is never touched. A hop below 30.0.0 reports `X_BUDGET_UNMEASURED` until `x build --target static --json` has run. Field by field: [CLI reference](CLI-Reference#x-upgrade).
 
 ## Breaking-change classes and how each is detected