@ultimat3/cli 30.3.0 → 30.5.0

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