@ultimat3/cli 29.3.2 → 30.0.0

package/src/templates/sign-in-shared.ts

@@ -0,0 +1,268 @@
+// What both `x g sign-in` shapes write: where a signed-in browser lands, the sign-out action, the
+// boot guard that refuses a people-facing role with sign-in unconfigured, and the page's styles.
+// The two shapes differ only in how a person proves who they are (`sign-in-password.ts`,
+// `sign-in-oidc.ts`); the session after that is one session, so its edges are written once.
+
+import type { GeneratedFile } from './naming';
+import { authModule } from './scaffold-auth';
+import { destroySessionTest } from './sign-in-action-tests';
+
+/** Every generated file lives under the scaffold's own auth slice, beside `auth.ts`. */
+export const AUTH_DIR = 'apps/web/app/auth';
+/** The page `x g sign-in` writes, and what `auth.signInPath` names. */
+export const SIGN_IN_PATH = '/auth/sign-in';
+
+/** How the generated page reaches a string: the app's own catalog module, or the framework's. */
+export const catalogImport = (module: string | undefined): string =>
+  module === undefined
+    ? "import { t } from '@ultimat3/i18n';"
+    : `import { useT } from '${module}';`;
+
+export const translatorBinding = (module: string | undefined): string =>
+  module === undefined ? '' : '\n  const t = useT();';
+
+/** `text` as `//` comment lines of at most 100 columns, split on spaces. */
+const commentLines = (text: string): string => {
+  const lines: string[] = [];
+  let line = '//';
+  for (const word of text.split(' ')) {
+    if (line.length + 1 + word.length > 100) {
+      lines.push(line);
+      line = '//';
+    }
+    line = `${line} ${word}`;
+  }
+  return [...lines, line].join('\n');
+};
+
+/**
+ * A string-array literal the way Biome prints it after `prefix`: on one line when it fits in 100
+ * columns, otherwise one item per line with a trailing comma.
+ */
+export const arrayLiteral = (prefix: string, items: readonly string[], suffix: string): string => {
+  const quoted = items.map((item) => `'${item}'`);
+  const inline = `${prefix}[${quoted.join(', ')}]${suffix}`;
+  if (inline.length <= 100) return inline;
+  const indent = /^\s*/.exec(prefix)?.[0] ?? '';
+  const rows = quoted.map((item) => `${indent}  ${item},`).join('\n');
+  return `${prefix}[\n${rows}\n${indent}]${suffix}`;
+};
+
+const flowSource =
+  (): string => `// Where a signed-in browser goes, and the one browser/agent split every sign-in action makes. The
+// destination is a FIXED path or a same-origin \`?next=\`: the endpoint that hands out a session is
+// the classic open redirect, and \`nextAfterSignIn\` is the framework's one check for it.
+import { NEXT_PARAM, nextAfterSignIn, setRedirect, useRequestHeader } from '@ultimat3/http';
+
+/** Where a browser lands with no \`?next=\`. The app's to move. */
+export const AFTER_SIGN_IN = '/dashboard';
+/** The page this app signs in on — \`auth.signInPath\` in \`app.config.ts\` names the same one. */
+export const SIGN_IN_PATH = '${SIGN_IN_PATH}';
+export { NEXT_PARAM };
+
+/** A same-origin path to go to next, or the fallback. Never another origin. */
+export const nextPath = (raw: string | undefined, fallback = AFTER_SIGN_IN): string =>
+  nextAfterSignIn(raw, fallback);
+
+/**
+ * A browser that posted the native form gets a 303 to where it was going; an agent that posted
+ * JSON gets the same path as data. One operation, two audiences — \`setRedirect\` is that seam.
+ */
+export const landAt = (path: string): string => {
+  if ((useRequestHeader('accept') ?? '').includes('text/html')) setRedirect(path);
+  return path;
+};
+`;
+
+const flowTest =
+  (): string => `// The landing rule: a same-origin path is kept, anything else is the fixed destination.
+import { expect, unitTest } from '@ultimat3/testing';
+import { AFTER_SIGN_IN, nextPath, SIGN_IN_PATH } from './sign-in-flow';
+
+unitTest('a same-origin next is kept, another origin is the fixed landing page', () => {
+  expect(nextPath('/posts')).toBe('/posts');
+  expect(nextPath('https://evil.example/steal')).toBe(AFTER_SIGN_IN);
+  expect(nextPath('//evil.example')).toBe(AFTER_SIGN_IN);
+  expect(nextPath(undefined)).toBe(AFTER_SIGN_IN);
+  expect(nextPath(undefined, SIGN_IN_PATH)).toBe(SIGN_IN_PATH);
+});
+`;
+
+const destroySessionSource =
+  (): string => `// Sign out: the session row revoked, the cookie expired and the browser's stored state cleared —
+// \`signOutHeaders()\` is the one list of what a sign-out response carries. Public, because a
+// signed-out caller signing out is a no-op rather than a 401, and a stale tab must not see a 500.
+import { action, t } from '@ultimat3/action';
+import { logout, signOutHeaders } from '@ultimat3/auth';
+import { useRequestContext, useRequestCookie } from '@ultimat3/http';
+import { allow } from '@ultimat3/policy';
+import { appAuth } from '../auth';
+import { landAt } from '../sign-in-flow';
+
+export const destroySession = action({
+  // A native form with no field posts no body, and an action's input is an object: the form
+  // declares one field rather than depending on how a browser encodes nothing.
+  input: t.object({ confirm: t.literal('sign-out') }),
+  output: t.object({ ok: t.boolean, next: t.string, revoked: t.boolean }),
+  policy: allow('public'),
+  mcp: { expose: false },
+  async handle() {
+    const auth = appAuth();
+    const token = useRequestCookie(auth.sessions.policy.cookieName);
+    const revoked = token === null || token === '' ? false : await logout(auth, token);
+    const response = useRequestContext('destroySession').headers;
+    for (const [name, value] of signOutHeaders({ session: auth.sessions.policy })) {
+      response.append(name, value);
+    }
+    return { ok: true, next: landAt('/'), revoked };
+  },
+});
+`;
+
+/**
+ * The guard reads the environment the way the scaffold's authenticator does — `fallback:
+ * 'production'` never applies, because only a NAMED deployed environment is refused: \`x manifest\`
+ * and \`x verify\` import every module with none named, and must not trip it.
+ */
+const guardSource = (
+  keys: readonly string[],
+  why: string,
+): string => `// Refuses to start a people-facing role with sign-in unconfigured. Outside \`development\` and \`test\`, a
+// \`web\` or \`sync\` process with these keys unset would serve every policy-protected route as a 401
+// that nobody can sign in past. Written by \`x g sign-in\` and owned by this app — an API-only app
+// has no sign-in, so this is not a framework rule.
+${commentLines(why)}
+import { signInUnconfigured } from '@ultimat3/auth';
+
+/** Set in the role's environment, or sign-in cannot run. \`x env example\` lists them. */
+${arrayLiteral('export const SIGN_IN_ENV: readonly string[] = ', keys, ';')}
+
+/** The roles a person reaches. \`worker\`, \`scheduler\`, \`replicator\` and \`migrate\` sign nobody in. */
+const PEOPLE_FACING = new Set(['web', 'sync']);
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+const named = (env: Env, key: string): string => (env[key] ?? '').trim();
+
+/**
+ * Throws \`X_AUTH_SIGN_IN_UNCONFIGURED\` naming every unset key, or returns. Only a NAMED deployed
+ * environment is judged: \`x manifest\` and \`x verify\` load the app with none named. Called by
+ * \`apps/web/runtime.ts\`, which the boot imports before it binds a port — a throw there stops the
+ * role, where a throw in a scanned module would only be logged.
+ */
+export function assertSignInConfigured(env: Env): void {
+  const environment = named(env, 'ULTIMATE_ENV') || named(env, 'NODE_ENV');
+  if (environment === '' || environment === 'development' || environment === 'test') return;
+  // \`ROLE\` unset is \`web\`, exactly as the boot reads it.
+  const role = named(env, 'ROLE') || 'web';
+  if (!PEOPLE_FACING.has(role)) return;
+  const missing = SIGN_IN_ENV.filter((key) => named(env, key) === '');
+  if (missing.length > 0) throw signInUnconfigured(role, missing);
+}
+`;
+
+const guardTest = (
+  keys: readonly string[],
+): string => `// The guard refuses a deployed people-facing role with sign-in unset, and nothing else.
+import { expect, unitTest } from '@ultimat3/testing';
+import { assertSignInConfigured, SIGN_IN_ENV } from './sign-in-guard';
+
+const configured = Object.fromEntries(SIGN_IN_ENV.map((key) => [key, 'set']));
+
+const refusal = (env: Readonly<Record<string, string>>): unknown => {
+  try {
+    assertSignInConfigured(env);
+  } catch (error) {
+    return error;
+  }
+  return undefined;
+};
+
+unitTest('a deployed web or sync role with sign-in unset refuses to start', () => {
+  for (const ROLE of ['web', 'sync']) {
+    const error = refusal({ ULTIMATE_ENV: 'production', ROLE });
+    expect(error).toBeUltimateError('X_AUTH_SIGN_IN_UNCONFIGURED');
+  }
+  // \`ROLE\` unset is \`web\`, and \`NODE_ENV\` names the environment as well.
+  expect(refusal({ NODE_ENV: 'production' })).toBeUltimateError('X_AUTH_SIGN_IN_UNCONFIGURED');
+  expect(refusal({ ULTIMATE_ENV: 'staging', ROLE: 'web' })).toBeUltimateError(
+    'X_AUTH_SIGN_IN_UNCONFIGURED',
+  );
+});
+
+unitTest('configured, local, unnamed, or a role nobody signs in to: it starts', () => {
+${arrayLiteral('  expect(SIGN_IN_ENV).toEqual(', keys, ');')}
+  expect(refusal({ ULTIMATE_ENV: 'production', ROLE: 'web', ...configured })).toBeUndefined();
+  expect(refusal({ ULTIMATE_ENV: 'development', ROLE: 'web' })).toBeUndefined();
+  expect(refusal({ NODE_ENV: 'test', ROLE: 'web' })).toBeUndefined();
+  expect(refusal({ ROLE: 'web' })).toBeUndefined();
+  expect(refusal({ ULTIMATE_ENV: 'production', ROLE: 'worker' })).toBeUndefined();
+});
+`;
+
+const styleSource =
+  (): string => `// Semantic tokens only: a raw colour here is refused by guards/raw-colour.ts.
+@use '@ultimat3/ui/tokens' as tokens;
+
+.page {
+  display: grid;
+  gap: tokens.space(4);
+  max-width: 28rem;
+  margin-inline: auto;
+  padding: tokens.space(6);
+  color: tokens.role('fg');
+}
+`;
+
+/** The files both shapes write, with the guard over this shape's settings. */
+/** Where the generated runtime lives: `apps/<app>/runtime.ts` is what both boots read first. */
+export const RUNTIME_MODULE = 'apps/web/runtime.ts';
+
+/** The plain routes a shape mounts: an import line, and the expression `routes:` takes. */
+export interface RuntimeRoutes {
+  readonly importLine: string;
+  readonly expression: string;
+}
+
+const runtimeSource = (
+  routes: RuntimeRoutes | undefined,
+): string => `// What this app hands the framework's boot — \`x dev\` and the container both import it before a
+// port is bound. The sign-in guard runs HERE for that reason: a throw in this module stops the
+// role, where the same throw in a module the app scan imports is logged and the boot goes on.
+import { assertSignInConfigured } from './app/auth/sign-in-guard';${routes === undefined ? '' : `\n${routes.importLine}`}
+
+assertSignInConfigured(process.env);
+
+export const runtime = {${routes === undefined ? '' : ` routes: ${routes.expression} `}};
+`;
+
+const runtimeTest = (
+  routes: RuntimeRoutes | undefined,
+): string => `// The runtime loads under test (the guard judges no local environment)${routes === undefined ? '' : ', and mounts the sign-in routes'}.
+import { expect, unitTest } from '@ultimat3/testing';
+${routes === undefined ? '' : `${routes.importLine}\n`}import { runtime } from './runtime';
+
+unitTest('the runtime loads${routes === undefined ? '' : ' and mounts the sign-in routes'}', () => {
+  ${routes === undefined ? 'expect(runtime).toEqual({});' : `expect(runtime.routes).toBe(${routes.expression});`}
+});
+`;
+
+export function sharedSignInFiles(
+  keys: readonly string[],
+  why: string,
+  routes?: RuntimeRoutes,
+): readonly GeneratedFile[] {
+  return [
+    { path: RUNTIME_MODULE, contents: runtimeSource(routes) },
+    { path: 'apps/web/runtime.test.ts', contents: runtimeTest(routes) },
+    { path: `${AUTH_DIR}/sign-in-flow.ts`, contents: flowSource() },
+    { path: `${AUTH_DIR}/sign-in-flow.test.ts`, contents: flowTest() },
+    { path: `${AUTH_DIR}/sign-in-guard.ts`, contents: guardSource(keys, why) },
+    { path: `${AUTH_DIR}/sign-in-guard.test.ts`, contents: guardTest(keys) },
+    { path: `${AUTH_DIR}/actions/destroy-session.ts`, contents: destroySessionSource() },
+    { path: `${AUTH_DIR}/actions/destroy-session.test.ts`, contents: destroySessionTest() },
+    { path: `${AUTH_DIR}/sign-in/page.module.scss`, contents: styleSource() },
+    // Every action above imports `../auth`; an app from before `x new` wrote it gets it here.
+    { path: `${AUTH_DIR}/auth.ts`, contents: authModule(), merge: 'if-absent' },
+  ];
+}

package/src/templates/slice-foundation.ts

@@ -38,19 +38,17 @@ const errorsSource = (feature: NameSet): string => {
   return `// The ${feature.kebab} feature's X_* codes. Never throw a bare Error: an agent reading the failure
 // needs the code, the cause and the exact command that fixes it.
 
-import { UltimateError } from '@ultimat3/core';
-
-// No \`docs:\`. \`UltimateError\` resolves it from the code's registered descriptor, so the link has
-// one home; a per-code URL written here is a page that does not exist.
-export class ${feature.pascal}NotFoundError extends UltimateError {
-  constructor(input: { id: string }) {
-    super({
-      code: '${errorCode}',
-      cause: \`no ${feature.kebab} with id \${input.id}\`,
-      fix: 'x queries list --json, then pass an id the ${feature.kebab} read returns',
-    });
-  }
-}
+import { defineError } from '@ultimat3/core';
+
+// One declaration: the title, the 404 a response answers, and the class a service throws. No
+// \`docs:\` — it resolves from the code's registered descriptor, so the link has one home.
+export const ${feature.pascal}NotFoundError = defineError<{ readonly id: string }>({
+  code: '${errorCode}',
+  title: 'no such ${feature.kebab}',
+  status: 404,
+  cause: (input) => \`no ${feature.kebab} with id \${input.id}\`,
+  fix: 'x queries list --json, then pass an id the ${feature.kebab} read returns',
+});
 `;
 };
 
@@ -77,13 +75,15 @@ export function sliceFoundation(
   needs: readonly SliceModule[],
   /** Every locale the planted entity's admin labels ship for. Defaults to `['en']`. */
   locales?: readonly string[],
+  /** The slice's entity names no tenant, so a planted policy holds no org rule. */
+  shape: { readonly singleTenant?: boolean } = {},
 ): readonly GeneratedFile[] {
   const feature = names(target.feature);
   const dir = `${target.surfaceDir}/${target.feature}`;
   return [
     ...ifAbsent([
       ...(needs.includes('entity') ? entityFiles(target.feature, target) : []),
-      ...(needs.includes('policy') ? policyFiles(target.feature, target) : []),
+      ...(needs.includes('policy') ? policyFiles(target.feature, target, shape) : []),
       ...(needs.includes('errors')
         ? [{ path: `${dir}/errors.ts`, contents: errorsSource(feature) }]
         : []),
@@ -95,6 +95,61 @@ export function sliceFoundation(
   ];
 }
 
+/** One `export const <binding> = entity('<table>', …)` an `entity.ts` declares. */
+export interface DeclaredEntity {
+  readonly binding: string;
+  readonly table: string;
+}
+
+/** Every entity a slice's `entity.ts` exports, in source order, comments masked. */
+export const declaredEntities = (source: string): readonly DeclaredEntity[] =>
+  [
+    ...stripComments(source).matchAll(
+      /\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*entity\(\s*['"]([^'"]+)['"]/g,
+    ),
+  ].map((match) => ({ binding: match[1] ?? '', table: match[2] ?? '' }));
+
+/**
+ * The entity a slice's `entity.ts` declares when it is NOT the one this generator would write for
+ * `feature` — `shortLink`/`short_links` in a `shortlink/` slice, whose scaffold is
+ * `shortlink`/`shortlinks`. A foundation planted around it is a `repo.ts` reading a table and a row
+ * type nothing declares. `undefined` when there is no file, the file declares the scaffold's, or it
+ * declares nothing this can read.
+ */
+export function foreignSliceEntity(
+  feature: string,
+  sliceEntity: string | undefined,
+): DeclaredEntity | undefined {
+  if (sliceEntity === undefined) return undefined;
+  const own = names(feature);
+  const declared = declaredEntities(sliceEntity);
+  if (declared.some((one) => one.binding === own.camel && one.table === own.table))
+    return undefined;
+  // Nothing readable is "cannot tell", and a slice is never refused on a guess.
+  return declared[0];
+}
+
+/**
+ * Whether the slice's `entity.ts` is there and names no tenant: no `tenant:` key but `'none'`, no
+ * `.tenant()` column, and no column named `orgId` — the three ways `resolveTenantColumn` turns
+ * tenancy on, inference included, so deleting `tenant: 'orgId'` alone is still a tenant-scoped row.
+ * Absent is NOT this: a slice with no entity has decided nothing, and keeps the default shape.
+ */
+export function sliceHasNoTenant(sliceEntity: string | undefined): boolean {
+  if (sliceEntity === undefined) return false;
+  const code = stripComments(sliceEntity);
+  if (/\btenant\s*:\s*'none'/.test(code)) return true;
+  return !/\btenant\s*:|\.tenant\(|\borgId\s*:/.test(code);
+}
+
+/**
+ * Whether a slice's `policy.ts` decides on an org the input names — `input.orgId`, or the
+ * `<Feature>Scope` a scaffolded `can<…>` types its input with. An action dropping `orgId` from its
+ * input would not compile against that rule, and at runtime the rule could only deny.
+ */
+export const policyReadsOrg = (source: string): boolean =>
+  /\binput\??\.orgId\b|\bcan<\s*\w+Scope\b/.test(stripComments(source));
+
 /** The exported names an `export { a, b as c }` list declares — `c`, never `b`. */
 const listedExports = (code: string): readonly string[] =>
   [...code.matchAll(/\bexport\s*\{([^}]*)\}/g)].flatMap((match) =>
@@ -113,7 +168,7 @@ const listedExports = (code: string): readonly string[] =>
 
 /**
  * Whether `source` — a slice module as it stands on the app's disk — exports the VALUE `name`.
- * Read at generation time because assuming it was measured: `x g action` into ai-maxxing's
+ * Read at generation time because assuming it was measured: `x g action` into one adopter's
  * `fleet` slice wrote `import { FleetNotFoundError } from '../errors'` into a slice whose
  * `errors.ts` declared `HostNotFoundError` and `SessionNotFoundError` and no `FleetNotFoundError`.
  * The file failed at import — and because `x db gen` and `x manifest` load every module, one

package/src/test-batches.ts

@@ -5,7 +5,7 @@
 // WHY THERE IS MORE THAN ONE PROCESS, `As of 2026-09-27`. A `--parallel` worker is not freed file
 // by file: it keeps its heap for the life of the `bun test` process and it GROWS with every file it
 // is handed (JIT, module-resolution caches, PGlite heaps the collector has not yet returned). On
-// notificado.co's unit corpus (768 files, PGlite per file, 12-core box, Bun 1.4.0), whole-tree RSS
+// one adopter's unit corpus (768 files, PGlite per file, 12-core box, Bun 1.4.0), whole-tree RSS
 // at 12 workers:
 //
 //   | form                                        | peak tree RSS | wall   |

package/src/test-database.ts

@@ -72,7 +72,7 @@ async function buildTemplate(
     await applyFrameworkSchema((statement) => client.execute(raw(statement)));
     await migrate({ migrations: await readMigrations(root), client, lock: false });
     // Without a checkpoint every boot from the template replays the migrations' WAL as crash
-    // recovery (~130 ms of each ~600 ms boot, measured on notificado.co).
+    // recovery (~130 ms of each ~600 ms boot, measured on one adopter's app).
     await client.execute(raw('CHECKPOINT'));
     const captured = driver as DumpablePglite | undefined;
     assert(

package/src/test-shards.ts

@@ -87,7 +87,7 @@ export function testArgs(input: {
    * A fresh global per FILE. Off by default since 22.7 — `--parallel` implies it, so the default
    * run says `--no-isolate` — and on for a repository whose `x.verify.json` says `"isolate": true`
    * or a caller's `--isolate`. Measured, 4 workers: the framework's unit corpus 168s isolated,
-   * 77s not; a notificado.co third 85-107s isolated, 20s not (`test-workers.ts`).
+   * 77s not; a third of one adopter's corpus 85-107s isolated, 20s not (`test-workers.ts`).
    */
   readonly isolate?: boolean;
   /**
@@ -140,6 +140,8 @@ export interface ReproduceOptions {
   readonly passthrough?: readonly string[];
   /** The run was isolated per file; the rerun must be too. */
   readonly isolate?: boolean;
+  /** The `simulateJobs` seed the run replayed: without it the rerun draws the default seeds. */
+  readonly seed?: number;
 }
 
 /**
@@ -162,6 +164,7 @@ export function reproduceFor(options: ReproduceOptions): string {
     '--workers',
     String(options.workers),
     ...(options.isolate === true ? ['--isolate'] : []),
+    ...(options.seed === undefined ? [] : ['--seed', String(options.seed)]),
     // Last, and after a `--` of its own, because that is where the caller typed it and where the
     // parser will find it again. Quoted for `shell-quote.ts`'s reason: a reproduce line is pasted.
     ...(options.passthrough === undefined || options.passthrough.length === 0
@@ -195,6 +198,8 @@ export interface RunShardsOptions {
   readonly env?: Readonly<Record<string, string | undefined>>;
   /** A fresh global per file (`x.verify.json` `"isolate": true`, or `--isolate`). Default off. */
   readonly isolate?: boolean;
+  /** `--seed`: handed to the children by the caller's runner, printed back in the reproduce. */
+  readonly seed?: number;
   /** The machine-pool lease (`test-slots.ts`), for a default-width run. */
   readonly lease?: (want: number) => Promise<{ readonly count: number; release(): void }>;
 }
@@ -221,6 +226,7 @@ const planOf = (
   ...(options.sample === undefined ? {} : { sample: options.sample.kept }),
   ...(options.affected === undefined ? {} : { affected: options.affected }),
   ...(options.isolate === true ? { isolate: true } : {}),
+  ...(options.seed === undefined ? {} : { seed: options.seed }),
   ...(options.passthrough === undefined || options.passthrough.length === 0
     ? {}
     : { passthrough: options.passthrough }),

package/src/test-workers.ts

@@ -52,19 +52,25 @@ export function availableCpus(): number {
  *   registry per file. Without isolation (the default since 22.7, below) a worker is CPU-bound,
  *   and oversubscribing only multiplies memory.
  *
- * So: `min(GATE_BUDGET_CAP, max(GATE_BUDGET_FLOOR, GATE_BUDGET_SHARE x TOTAL memory))` — total, never free, so the plan
+ * So: `max(GATE_BUDGET_FLOOR, GATE_BUDGET_SHARE x TOTAL memory)` — total, never free, so the plan
  * is the same on every run of the same machine — divided by `WORKER_BYTES`, clamped to 1..cpus.
  * `ULTIMATE_TEST_MEMORY_BUDGET` (e.g. `3g`) replaces the budget, `ULTIMATE_TEST_MAX_WORKERS` caps
  * the width, and an explicit `--workers` wins over both.
+ *
+ * Until 2026-11-07 the budget was also capped at a fixed 4 GiB, which held a 16-core 62 GB box to
+ * the 3 workers a 16 GB laptop gets: the framework's unit step took 374 s there at 3 workers and
+ * 149 s at 12. The cap is gone because the guard it stood for is elsewhere now — every run on a
+ * machine leases its workers from ONE pool sized by this plan (`test-slots.ts`), so a second gate
+ * shares the quarter rather than doubling it. A 16 GB runner's quarter is exactly the old cap, so
+ * CI plans what it always planned.
  */
-export const GATE_BUDGET_CAP = 4 * 1024 * 1024 * 1024;
 
 /** A quarter of the machine: an editor, a language server and another agent's gate need the rest. */
 export const GATE_BUDGET_SHARE = 0.25;
 
 /**
  * The budget never plans below this: enough for TWO workers at `WORKER_BYTES`. A quarter of an
- * 8 GB laptop (2 GiB) planned one worker, ~4.7 min for notificado.co's unit tier; two stay inside
+ * 8 GB laptop (2 GiB) planned one worker, ~4.7 min for one adopter's unit tier; two stay inside
  * the owner's 1-4 GB gate target (~2.6 GB measured).
  */
 export const GATE_BUDGET_FLOOR = 2.75 * 1024 * 1024 * 1024;
@@ -76,9 +82,9 @@ export const GATE_BUDGET_FLOOR = 2.75 * 1024 * 1024 * 1024;
  *   | corpus                                  | workers | batch | peak tree | tree / worker |
  *   |-----------------------------------------|---------|-------|-----------|---------------|
  *   | framework unit (1620 files)             | 4       | 24    | 3.61-3.78 GB | 0.90-0.95 GB |
- *   | notificado.co unit (768 files)          | 4       | 24    | 4.26-4.58 GB | 1.07-1.15 GB |
- *   | notificado.co unit (768 files)          | 4       | 48    | 4.35 GB   | 1.09 GB       |
- *   | notificado.co unit (768 files)          | 3       | 24    | 3.28-3.61 GB | 1.09-1.20 GB |
+ *   | one adopter's unit (768 files)          | 4       | 24    | 4.26-4.58 GB | 1.07-1.15 GB |
+ *   | one adopter's unit (768 files)          | 4       | 48    | 4.35 GB   | 1.09 GB       |
+ *   | one adopter's unit (768 files)          | 3       | 24    | 3.28-3.61 GB | 1.09-1.20 GB |
  *
  * The planning figure is what the TREE costs per worker at its peak — the `x` parent and Bun's
  * coordinator included — rounded up from the heaviest corpus, not the largest single worker:
@@ -103,7 +109,7 @@ export const BATCH_FILES_PER_WORKER = 24;
  * The recycle point WITHOUT isolation (the default since 22.7). A shared worker's peak is set by
  * its live PGlite, not by how many files it has run, and a batch boundary is pure cost: every
  * worker restarts, re-imports the app and re-boots its database, and the batch waits on its
- * slowest file. Measured on notificado.co's unit tier (768 files, 281 s of file time, 3 workers,
+ * slowest file. Measured on one adopter's unit tier (768 files, 281 s of file time, 3 workers,
  * no isolation): 6 batches of 48/worker 150-172 s, ONE batch 92-94 s at 3.9 GB peak — the work
  * floor (281 s / 3). 256 a worker keeps a recycle point for a corpus far past that size.
  */
@@ -167,7 +173,10 @@ export interface WorkerPlan {
 
 const gb = (bytes: number): string => (bytes / 1024 ** 3).toFixed(1);
 
-/** The budget a default run plans on: the env override, or `min(4 GiB, max(2.75 GiB, 25% of RAM))`. */
+/** `memoryBudget`'s default, as every help line and page prints it — derived, never restated. */
+export const BUDGET_RULE = `max(${String(GATE_BUDGET_FLOOR / 1024 ** 3)} GiB, ${String(GATE_BUDGET_SHARE * 100)}% of RAM)`;
+
+/** The budget a default run plans on: the env override, or `BUDGET_RULE`. */
 export function memoryBudget(total: number = totalMemory(), env: Env = Bun.env): number {
   const raw = env[MEMORY_BUDGET_ENV];
   if (raw !== undefined && raw.trim() !== '') {
@@ -175,10 +184,7 @@ export function memoryBudget(total: number = totalMemory(), env: Env = Bun.env):
     if (bytes === undefined) throw new TestBudgetInvalidError(MEMORY_BUDGET_ENV, raw);
     return bytes;
   }
-  return Math.min(
-    GATE_BUDGET_CAP,
-    Math.max(GATE_BUDGET_FLOOR, Math.floor(Math.max(0, total) * GATE_BUDGET_SHARE)),
-  );
+  return Math.max(GATE_BUDGET_FLOOR, Math.floor(Math.max(0, total) * GATE_BUDGET_SHARE));
 }
 
 const maxWorkersOf = (env: Env): number | undefined => {

package/src/tool-gate-names.ts

@@ -0,0 +1,34 @@
+// The `manifest` step's tool-gate half: a name in `mcpConfirmations({ tools })` that no tool answers
+// to. It holds nothing, so an agent's `refundOrder` runs past a gate spelled `refundOrdr`.
+// `defineAppMcp({ confirmations })` refuses that at boot for its own server; this is every other layout.
+
+import { gatedToolNames, knownToolNames, listActions } from '@ultimat3/action';
+import { ERROR_DOCS_URL, isMcpExposed } from '@ultimat3/core';
+import { listQueries } from '@ultimat3/query';
+import { loadApp } from './app-load';
+import type { AppLoader } from './app-permissions';
+import type { Finding } from './output';
+
+/** Every name a gate could hold: what an agent can be offered, on either surface. */
+function toolNames(): readonly string[] {
+  const exposed = [...listActions(), ...listQueries()].filter((one) => isMcpExposed(one.mcp));
+  return [...new Set([...exposed.map((one) => one.name), ...knownToolNames()])].sort();
+}
+
+/** Says nothing when the load failed: a short registry is the load's finding. */
+export async function unknownToolGateFindings(
+  root: string,
+  load: AppLoader = loadApp,
+): Promise<readonly Finding[]> {
+  if ((await load(root)).findings.length > 0) return [];
+  const known = toolNames();
+  const shown = known.length === 0 ? '(none)' : known.join(', ');
+  return gatedToolNames()
+    .filter((name) => !known.includes(name))
+    .map((name) => ({
+      code: 'X_MCP_CONFIRMATION_TOOL_UNKNOWN',
+      cause: `mcpConfirmations({ tools }) names ${name}, which no exposed action, exposed query, MCP tool or in-process tool answers to, so the gate holds nothing and the tool it meant runs unconfirmed`,
+      fix: `mcpConfirmations({ tools: [...] })   # name tools this app declares: ${shown}`,
+      docs: ERROR_DOCS_URL,
+    }));
+}

package/src/upgrade-agents-link.ts

@@ -0,0 +1,49 @@
+// `x upgrade`'s one context-file edit: `x new` writes `AGENTS.md` as a symlink to `CLAUDE.md`, and an
+// app scaffolded before that holds two regular files. Byte-identical, the copy becomes the link;
+// different, it is reported with the merge to do by hand — which half is right is the author's call.
+
+// why: Bun has no lstat, the one call that tells a link from the file it points at.
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeGenerated } from './write-generated';
+
+export const AGENTS_FILE = 'AGENTS.md';
+export const CLAUDE_FILE = 'CLAUDE.md';
+
+/**
+ * `link` — two identical regular files, so the hop replaces `AGENTS.md` with the link;
+ * `linked` — already a symlink; `differs` — two regular files with different text, left alone;
+ * `none` — one of the two is missing, so there is no pair to join.
+ */
+export type AgentsLinkState = 'link' | 'linked' | 'differs' | 'none';
+
+const kindOf = async (path: string): Promise<'file' | 'link' | 'missing'> => {
+  try {
+    const stat = await lstat(path);
+    return stat.isSymbolicLink() ? 'link' : stat.isFile() ? 'file' : 'missing';
+  } catch {
+    return 'missing';
+  }
+};
+
+/** Read-only: what the hop would do to `<root>/AGENTS.md`. `--dry-run` reports exactly this. */
+export async function planAgentsLink(root: string): Promise<AgentsLinkState> {
+  const agents = await kindOf(join(root, AGENTS_FILE));
+  if (agents === 'link') return 'linked';
+  if (agents === 'missing' || (await kindOf(join(root, CLAUDE_FILE))) !== 'file') return 'none';
+  const [held, source] = await Promise.all([
+    Bun.file(join(root, AGENTS_FILE)).bytes(),
+    Bun.file(join(root, CLAUDE_FILE)).bytes(),
+  ]);
+  return Buffer.from(held).equals(Buffer.from(source)) ? 'link' : 'differs';
+}
+
+/**
+ * Performs a `link` plan. The contents are `CLAUDE.md`'s own, so where Windows refuses the link the
+ * fallback rewrites the identical copy — the file is unchanged and the next hop asks again.
+ */
+export async function applyAgentsLink(root: string, state: AgentsLinkState): Promise<void> {
+  if (state !== 'link') return;
+  const contents = await Bun.file(join(root, CLAUDE_FILE)).bytes();
+  await writeGenerated(root, { path: AGENTS_FILE, contents, link: CLAUDE_FILE });
+}