@ultimat3/cli 23.0.0 → 25.0.0

package/src/budgets.ts

@@ -8,15 +8,20 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { ERROR_DOCS_URL, formatBytes } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
+import { describePages, parseByteBudget, themeScriptBody } from '@ultimat3/render';
+import type { ChargedFile } from './budgets-charged';
+import { chargedClause, chargedMeta, heaviestFirst } from './budgets-charged';
 import {
-  describeRoutes,
-  formatBytes,
-  parseByteBudget,
-  SPECULATION_RULES_TYPE,
-  themeScriptBody,
-} from '@ultimat3/render';
+  artifactPath,
+  carriesJson,
+  ENTRY_ATTR,
+  loadedBy,
+  SCRIPT_TAG,
+  SRC_ATTR,
+} from './budgets-scan';
+import { builtUnmeasuredFinding } from './budgets-unmeasured';
 import type { Finding } from './output';
 import type { UnmeasuredRoute } from './static-report';
 import { SW_REGISTER_PATH } from './sw-artifacts';
@@ -39,17 +44,15 @@ export interface RouteStats {
    * older build simply did not count it, and `checkBudgets` reads `jsBytes` either way.
    */
   readonly frameworkJsBytes?: number;
-  /**
-   * **Written by nothing, `As of 2026-08`.** `apps/web/prerender.ts` is the only producer of this
-   * file and it emits static HTML — there is no browser in the build to observe a paint. So the
-   * comparison in `checkBudgets` below is reachable only for an app that writes its own stats, and
-   * `x new` no longer scaffolds an `lcp` budget for exactly that reason: a budget the build cannot
-   * weigh passes silently the moment a stats row exists, which is the false green this file's
-   * header is about. `RouteBudget.lcp` still accepts one — that key is `@ultimat3/render`'s.
-   */
-  readonly lcpMs?: number;
   /** Import chain that pulled the heaviest module into this route. */
   readonly heaviestChain?: readonly string[];
+  /**
+   * Every app file `jsBytes` charged, heaviest first, at the URL the browser fetches. Optional
+   * for `frameworkJsBytes`' reason: a row from an older build has none, and absent is not empty.
+   */
+  readonly charged?: readonly ChargedFile[];
+  /** The app's inline script bytes inside `jsBytes` — the part no file in `charged` accounts for. */
+  readonly inlineJsBytes?: number;
 }
 
 export interface BuildStats {
@@ -67,8 +70,12 @@ export interface BuildStats {
  * `examples/dummy` was charged 250 B for `/x-sw-register.js` by a file written before
  * `FRAMEWORK_SCRIPTS` exempted it. `2`: that exemption and the page-boot decision (ledger #28).
  * `3`: an island entry's imported chunks are charged, each once per document (shared chunks).
+ * `4`: the exempt theme script's bytes moved — it also stamps `data-theme-default` (plan 101, 09).
+ * `5`: a URL is weighed at the path a browser resolves it to (`\` is `/`, `//host` is another
+ * origin), so two spellings of one fetch are charged once; and an app/ page is weighed as SERVED
+ * — its page boot charged, the runtime chunk that boot makes unfetched not (plan 101 sweep 9).
  */
-export const BUILD_STATS_RULES = 3;
+export const BUILD_STATS_RULES = 5;
 
 const chainOf = (stats: RouteStats): string =>
   stats.heaviestChain === undefined ? 'unknown import chain' : stats.heaviestChain.join(' -> ');
@@ -79,7 +86,7 @@ const jsBudgetOf = (route: RouteFact): number | null => parseByteBudget(route.bu
 export type RouteFileOf = (url: string) => string | undefined;
 
 const declaredFileOf: RouteFileOf = (url) =>
-  describeRoutes().find((route) => route.path === url && route.mount === undefined)?.file;
+  describePages().find((route) => route.path === url && route.mount === undefined)?.file;
 
 const KB = 1024;
 
@@ -94,14 +101,6 @@ function exceededJsFix(url: string, file: string | undefined, bytes: number): st
   return `edit ${where} — set budget: { js: '${String(kb)}kb' } with // measured: ${String(bytes)} B (x build --target static) — why: <the function it buys> directly above it; or x routes --json for the chain and move the heavy import behind hydrate: 'interaction'`;
 }
 
-/** Which budgets the route declared, for a cause line that names what went unmeasured. */
-function declaredBudgets(js: number | null, lcp: number | undefined): string {
-  const labels: string[] = [];
-  if (js !== null) labels.push('JS');
-  if (lcp !== undefined) labels.push('LCP');
-  return labels.join(' and ');
-}
-
 /**
  * Compare declared budgets against measured stats. A declared budget with no measurement is a
  * finding, never a pass: a route that clears the gate without ever being weighed is exactly the
@@ -117,8 +116,13 @@ function declaredBudgets(js: number | null, lcp: number | undefined): string {
  * second build's. Reporting the first as the second is what sends a reader to re-run a build that
  * already did everything it was going to do.
  */
-function unmeasuredFinding(url: string, declared: string, built: boolean, stale = false): Finding {
-  if (stale) {
+function unmeasuredFinding(
+  url: string,
+  declared: string,
+  stats: BuildStats | undefined,
+  unmeasured: readonly UnmeasuredRoute[],
+): Finding {
+  if (stats?.stale === true) {
     return {
       code: 'X_BUDGET_UNMEASURED',
       cause: `${url} declares a ${declared} budget and ${BUILD_STATS_FILE} was written by an earlier measurement rule than this gate's (v${String(BUILD_STATS_RULES)}), so its numbers are not this gate's to read`,
@@ -127,54 +131,19 @@ function unmeasuredFinding(url: string, declared: string, built: boolean, stale
       at: url,
     };
   }
+  // A build ran: the report's account of this route decides the instruction
+  // (`budgets-unmeasured.ts`) — its own code, an actor edit, or the report.
+  if (stats !== undefined) {
+    const entry = unmeasured.find((one) => one.path === url);
+    return builtUnmeasuredFinding(url, declared, BUILD_STATS_FILE, entry);
+  }
   return {
     code: 'X_BUDGET_UNMEASURED',
-    cause: built
-      ? `${url} declares a ${declared} budget and ${BUILD_STATS_FILE} has no row for it, so the build ran and could not weigh it`
-      : `${url} declares a ${declared} budget and no build has written ${BUILD_STATS_FILE} in this repo`,
+    cause: `${url} declares a ${declared} budget and no build has written ${BUILD_STATS_FILE} in this repo`,
     // `--target static` is load-bearing and `x build` alone was a fix that changes nothing: the
     // flag defaults to `docker`, and only the static target runs `apps/web/prerender.ts`, which is
-    // the one caller of `writeBuildStats`. When a build already ran, the second half is where the
-    // answer is — the report names every route it could not weigh, and why.
-    fix: built
-      ? `x build --target static --json   # its "unmeasured" list says why ${url} could not be weighed`
-      : 'x build --target static --json && x verify --json',
-    docs: ERROR_DOCS_URL,
-    at: url,
-  };
-}
-
-/**
- * The ONE code a failed measurement is reported under by its own name rather than as
- * `X_BUDGET_UNMEASURED`. Its cause is complete — the island, the prop, its bytes, the cap — and
- * its fix is an edit to the page, so the step's own "run x build and read the list" would put a
- * second command between the author and a sentence the build had already composed. Every other
- * render failure keeps the generic finding: a `TypeError` from a `load` that wanted a request is
- * a reason to read the report, not an instruction.
- *
- * ONE code and not "any coded error", deliberately. `X_NO_CONTEXT`, `X_UNAUTHENTICATED` and
- * `X_DB_UNAVAILABLE` from a measurement render are facts about the BUILD's environment, and
- * reporting them under their own codes would tell the author to fix a database the gate never
- * had. The list grows by a decision, per code, here.
- */
-const REPORTED_BY_OWN_CODE: ReadonlySet<string> = new Set([
-  'X_ISLAND_PROPS_INVALID',
-  // A dynamic route that lists no `prerender()` path: the edit is in the route, not the build.
-  'X_BUDGET_PARAMS_UNDECLARED',
-]);
-
-/**
- * The build's own finding for a route it could not weigh, when that failure is an instruction.
- * Read off the static report's `unmeasured` list — the same list `X_BUDGET_UNMEASURED`'s `fix:`
- * sends its reader to, now read by the step itself for the one code it can act on.
- */
-function ownCodeFinding(url: string, unmeasured: readonly UnmeasuredRoute[]): Finding | undefined {
-  const entry = unmeasured.find((one) => one.path === url);
-  if (entry?.code === undefined || !REPORTED_BY_OWN_CODE.has(entry.code)) return undefined;
-  return {
-    code: entry.code,
-    cause: entry.cause ?? entry.reason,
-    fix: entry.fix ?? `x build --target static --json   # its "unmeasured" list has ${url}`,
+    // the one caller of `writeBuildStats`.
+    fix: 'x build --target static --json && x verify --json',
     docs: ERROR_DOCS_URL,
     at: url,
   };
@@ -188,7 +157,7 @@ function ownCodeFinding(url: string, unmeasured: readonly UnmeasuredRoute[]): Fi
  * `unmeasured` is the static report's list of routes the build rendered and could not weigh, with
  * each failure's code when it had one. Optional because the report is written beside the stats
  * and can be absent for the same reason; with it, a route whose measurement failed on a code in
- * `REPORTED_BY_OWN_CODE` is reported under that code, with the build's own cause and fix.
+ * `REPORTED_BY_OWN_CODE` (`budgets-unmeasured.ts`) is reported under that code, with the build's own cause and fix.
  *
  * `fileOf` names the file an `X_BUDGET_EXCEEDED` fix edits: the step runs after the app loaded,
  * so render's route table already holds it. A test hands its own.
@@ -210,37 +179,21 @@ export function checkBudgets(
     if (unweighable.has(route.url)) continue;
     const measured = byPath.get(route.url);
     const js = jsBudgetOf(route);
-    const lcp = route.budget?.lcp;
     if (measured === undefined) {
-      if (js !== null || lcp !== undefined) {
-        findings.push(
-          ownCodeFinding(route.url, unmeasured) ??
-            unmeasuredFinding(
-              route.url,
-              declaredBudgets(js, lcp),
-              stats !== undefined,
-              stats?.stale === true,
-            ),
-        );
+      if (js !== null) {
+        findings.push(unmeasuredFinding(route.url, 'JS', stats, unmeasured));
       }
       continue;
     }
     if (js !== null && measured.jsBytes > js) {
+      const meta = chargedMeta(measured.jsBytes, measured.charged, measured.inlineJsBytes);
       findings.push({
         code: 'X_BUDGET_EXCEEDED',
-        cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS (minified, uncompressed) over a ${formatBytes(js)} budget via ${chainOf(measured)}`,
+        cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS (minified, uncompressed) over a ${formatBytes(js)} budget via ${chainOf(measured)}${chargedClause(measured.charged, measured.inlineJsBytes)}`,
         fix: exceededJsFix(route.url, fileOf(route.url), measured.jsBytes),
         docs: ERROR_DOCS_URL,
         at: route.url,
-      });
-    }
-    if (lcp !== undefined && measured.lcpMs !== undefined && measured.lcpMs > lcp) {
-      findings.push({
-        code: 'X_BUDGET_EXCEEDED',
-        cause: `${route.url} LCP ${measured.lcpMs}ms over the ${lcp}ms budget`,
-        fix: `raise the budget in defineRoute, or switch render to 'isr' to serve it prebuilt`,
-        docs: ERROR_DOCS_URL,
-        at: route.url,
+        ...(meta === undefined ? {} : { meta }),
       });
     }
   }
@@ -255,59 +208,29 @@ export async function readBuildStats(root: string): Promise<BuildStats | undefin
   return read.measuredBy === BUILD_STATS_RULES ? read : { routes: [], stale: true };
 }
 
-const SCRIPT_TAG = /<script(?<attrs>[^>]*)>(?<body>[\s\S]*?)<\/script>/g;
-const SRC_ATTR = /\ssrc="(?<src>[^"]*)"/;
-const TYPE_ATTR = /\stype="(?<type>[^"]*)"/;
-
-/**
- * `application/ld+json`, `application/json`, any `…+json`: the body is data, not code — the rule
- * `@ultimat3/render`'s `head.ts` already states, restated because its `carriesJson` reads a
- * `HeadTag` and is not exported, and this side has an attribute string off the emitted document.
- * Without it a page shipping only `meta.ld` structured data and island props measured 8kb of JS
- * and failed a 2kb budget with a `fix:` naming an import chain that does not exist.
- */
-const carriesJson = (attrs: string): boolean => {
-  // Everything from the first `;` is a MIME PARAMETER and not the type: a real document writes
-  // `type="application/ld+json; charset=utf-8"`, which does not END with `json`, so the suffix
-  // test alone charged an SEO structured-data block as executable JavaScript all over again.
-  const [type = ''] = (TYPE_ATTR.exec(attrs)?.groups?.['type'] ?? '').split(';');
-  const declared = type.trim().toLowerCase();
-  // Speculation rules are JSON under a type that does not say so: read by the browser's
-  // prefetcher, never executed — the one script a 0kb page may carry for free.
-  return declared.endsWith('json') || declared === SPECULATION_RULES_TYPE;
-};
-
-/**
- * An island's chunk is reached by `import()` from inside the hydration runtime, so it never appears
- * as a `<script src>` — and a document weighed by script tags alone was charged for the runtime and
- * never for the code that runtime boots. The entry attribute is that module URL, so it is read as
- * exactly what it is: a file the browser will execute.
- */
-const ENTRY_ATTR = /\sdata-x-entry="(?<url>[^"]*)"/g;
-
-/**
- * Static imports and `import()` both. A chunk reached by `import()` was INLINED into its island
- * before islands were split, so charging it keeps a route's number what it was; and it is fetched
- * the moment the island needs it, which is before the page does what it was loaded for.
- */
-const LOADS: ReadonlySet<string> = new Set(['import-statement', 'dynamic-import']);
+/** What `measureDocumentJs` needs beyond the document and the artifact — both for served pages. */
+export interface MeasureOptions {
+  /**
+   * Scripts a document names that the PROCESS serves and the static artifact does not carry, by
+   * URL: the page boot (`/_x/page-boot/<id>.js`). Charged like any `<script src>` — ledger #28.
+   */
+  readonly served?: ReadonlyMap<string, string>;
+  /**
+   * The page boot's path prefix and the runtime chunks it supplies (#505): on a document carrying
+   * the boot an island awaits the runtime the boot installs and never imports the chunk, so the
+   * chunk is not charged there. A document without the boot is charged for it as before.
+   */
+  readonly boot?: { readonly prefix: string; readonly supplies: ReadonlySet<string> };
+}
 
-/** Same-origin paths `code`, served at `url`, makes the browser load. Cross-origin and bare are not this build's. */
-function loadedBy(url: string, code: string): readonly string[] {
-  let imports: readonly { readonly path: string; readonly kind: string }[];
-  try {
-    imports = new Bun.Transpiler({ loader: 'js' }).scanImports(code);
-  } catch {
-    // A file that does not parse as JavaScript imports nothing this gate can name; its own bytes
-    // are already charged.
-    return [];
+/** Whether a `<script src>` in `html` is the page boot `boot.prefix` names. */
+function carriesBoot(html: string, boot: MeasureOptions['boot']): boolean {
+  if (boot === undefined) return false;
+  for (const match of html.matchAll(SCRIPT_TAG)) {
+    const src = SRC_ATTR.exec(match.groups?.['attrs'] ?? '')?.groups?.['src'];
+    if (src !== undefined && artifactPath(src)?.startsWith(boot.prefix) === true) return true;
   }
-  const base = new URL(url, 'https://artifact.invalid');
-  return imports
-    .filter((one) => LOADS.has(one.kind) && /^\.{0,2}\//.test(one.path))
-    .map((one) => new URL(one.path, base))
-    .filter((target) => target.origin === base.origin)
-    .map((target) => target.pathname);
+  return false;
 }
 
 /** One executable module the document names, and what it weighs on disk. */
@@ -321,6 +244,8 @@ export interface MeasuredJs {
   readonly jsBytes: number;
   /** The framework's injected runtime, counted separately so it is reported and never charged. */
   readonly frameworkBytes: number;
+  /** The app's inline script bytes — the part of `jsBytes` that is not a file in `entries`. */
+  readonly inlineBytes: number;
   /** Every APP `src=`/`data-x-entry=` module, so a finding can name the heaviest by file. */
   readonly entries: readonly MeasuredEntry[];
 }
@@ -372,9 +297,14 @@ export const FRAMEWORK_INLINE_SCRIPTS: ReadonlySet<string> = new Set(
  * from the emitted HTML rather than from the declared graph, because the graph is what a route
  * *says* it ships and this gate exists to catch the case where those two disagree.
  */
-export async function measureDocumentJs(html: string, out: string): Promise<MeasuredJs> {
+export async function measureDocumentJs(
+  html: string,
+  out: string,
+  options: MeasureOptions = {},
+): Promise<MeasuredJs> {
   let jsBytes = 0;
   let frameworkBytes = 0;
+  let inlineBytes = 0;
   const entries: MeasuredEntry[] = [];
   // Deduped ONCE, across both readers below, and the unit is the FETCH: a browser downloads a URL
   // once however many times the document names it, so `budget.js` — a byte budget — counts it
@@ -390,13 +320,21 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
   // is not in this set for the same reason: two identical inline bodies are two copies of the
   // bytes in the document, so both are charged.
   const fetched = new Set<string>();
-  const weigh = async (url: string): Promise<void> => {
+  const served = options.served ?? new Map<string, string>();
+  // The runtime chunks this document's page boot makes unfetched: `awaitPageRuntime`'s rule, read
+  // the way it reads it — a `<script src>` under the boot's path is in the document.
+  const bootSupplied = carriesBoot(html, options.boot) ? (options.boot?.supplies ?? null) : null;
+  const weigh = async (named: string): Promise<void> => {
     // Only a path inside the artifact can be weighed; a cross-origin script is not this build's.
-    if (!url.startsWith('/') || fetched.has(url)) return;
+    const url = artifactPath(named);
+    if (url === undefined || fetched.has(url)) return;
     fetched.add(url);
+    // A script the process serves and the artifact does not carry (the page boot) is weighed from
+    // the bytes the build holds; everything else from the file the artifact will serve.
+    const held = served.get(url);
     const file = Bun.file(join(out, url.slice(1)));
-    const exists = await file.exists();
-    const bytes = exists ? file.size : 0;
+    const exists = held !== undefined || (await file.exists());
+    const bytes = held === undefined ? (exists ? file.size : 0) : Buffer.byteLength(held, 'utf8');
     // Counted and set aside, not skipped: the bytes are real and a reader is owed the number.
     // Kept out of `entries` as well as out of `jsBytes`, because `entries` is what a finding reads
     // to name the heaviest import — and on a fresh scaffold every route's `heaviestChain` was
@@ -411,7 +349,9 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     // and each is a fetch the browser makes before the island is whole. Through `weigh`, so a chunk
     // two islands share is charged once and a cycle ends at the first repeat.
     if (exists) {
-      for (const next of loadedBy(url, await file.text())) await weigh(next);
+      for (const next of loadedBy(url, held ?? (await file.text()))) {
+        if (bootSupplied?.has(next) !== true) await weigh(next);
+      }
     }
   };
 
@@ -422,8 +362,12 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     if (src === undefined) {
       const body = match.groups?.['body'] ?? '';
       const bytes = Buffer.byteLength(body, 'utf8');
-      if (FRAMEWORK_INLINE_SCRIPTS.has(body)) frameworkBytes += bytes;
-      else jsBytes += bytes;
+      if (FRAMEWORK_INLINE_SCRIPTS.has(body)) {
+        frameworkBytes += bytes;
+      } else {
+        jsBytes += bytes;
+        inlineBytes += bytes;
+      }
       continue;
     }
     await weigh(src);
@@ -433,7 +377,26 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     if (url === undefined) continue;
     await weigh(url);
   }
-  return { jsBytes, frameworkBytes, entries };
+  return { jsBytes, frameworkBytes, inlineBytes, entries };
+}
+
+/**
+ * The stats row for one measured document — the ONE place a row is assembled, so the static and
+ * the weigh-only branch of the build cannot record different facts about the same kind of page.
+ */
+export function routeStatsRow(
+  path: string,
+  measured: MeasuredJs,
+  chain: readonly string[] | undefined,
+): RouteStats {
+  return {
+    path,
+    jsBytes: measured.jsBytes,
+    frameworkJsBytes: measured.frameworkBytes,
+    ...(chain === undefined ? {} : { heaviestChain: chain }),
+    charged: heaviestFirst(measured.entries),
+    inlineJsBytes: measured.inlineBytes,
+  };
 }
 
 /**

package/src/cdp-shot-driver.ts

@@ -91,7 +91,9 @@ export function cdpShotDriver(options: CdpShotDriverOptions): ShotDriver {
       throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
     }
     const launched = await launch(options.executablePath, timeoutMs);
-    return { connection: launched.connection, end: async () => launched.close() };
+    // Awaited by `close` below: `x shot` exits right after its last picture, and a reap still
+    // running then is a Chrome child left behind and a profile directory it re-creates.
+    return { connection: launched.connection, end: () => launched.close() };
   };
 
   return {
@@ -120,10 +122,22 @@ export function cdpShotDriver(options: CdpShotDriverOptions): ShotDriver {
             detail: 'the browser opened a page and answered no target or session id',
           });
         }
+        // The BROWSER's own session, for the allow list on every target the page opens — a popup
+        // is a new target the page session's `Fetch` never pauses. A browser that refuses the
+        // attach refuses the session: a rule that would hold on one tab only is not a rule.
+        const browserAttached = await connection.send('Target.attachToBrowserTarget');
+        const browserSessionId = field(browserAttached.result, 'sessionId');
+        if (browserSessionId === undefined) {
+          throw new CdpCallFailedError({
+            method: 'Target.attachToBrowserTarget',
+            detail: 'the browser answered no session id, so a popup could not be screened',
+          });
+        }
         // Watching BEFORE the domains are on, so the first request is already counted.
         const watch = watchPage({
           connection,
           sessionId,
+          browserSessionId,
           clock: init.clock,
           allowHosts: init.rules.allowHosts,
         });
@@ -134,6 +148,11 @@ export function cdpShotDriver(options: CdpShotDriverOptions): ShotDriver {
         await on('Page.enable');
         await on('Network.enable');
         await on('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] });
+        await connection.send(
+          'Fetch.enable',
+          { patterns: [{ urlPattern: '*', requestStage: 'Request' }] },
+          browserSessionId,
+        );
         // Before the first navigation, like the metrics below: a header set after `goto` would
         // photograph a document negotiated in the machine's own language.
         if (init.headers !== undefined && Object.keys(init.headers).length > 0) {

package/src/cdp-shot-watch.ts

@@ -2,6 +2,7 @@
 // tail with a count of what the bound threw away. And the allow list, enforced in the browser:
 // every request is paused (`Fetch.requestPaused`) and refused unless its host is allowed, so an
 // injected `<img src="http://169.254.169.254/…">` never leaves — it is recorded as `refused`.
+// Paused at the BROWSER too, so a popup the page opens is decided by the same `hostDecision`.
 import { hostDecision } from '@ultimat3/core';
 import type { CdpConnection } from '@ultimat3/testing';
 import type {
@@ -123,14 +124,22 @@ export interface PageWatch {
  * Subscribe BEFORE the domains are enabled (the caller's order), so the first request of the first
  * navigation is already counted. Only events on `sessionId` are read: a remote browser carries
  * other people's pages.
+ *
+ * `browserSessionId` is the browser target's session, whose `Fetch` pauses what page-level
+ * interception never sees: a `target=_blank` link or a `window.open` is a NEW target, and on the
+ * page session alone it reached an off-list host unrefused. Its pauses are decided by the same
+ * `hostDecision` and answered on the session they arrived on. A page request is decided at the
+ * page first — an allowed one is continued again here, a refused one never arrives — so each
+ * refusal is one ring entry.
  */
 export function watchPage(input: {
   readonly connection: CdpConnection;
   readonly sessionId: string;
+  readonly browserSessionId?: string | undefined;
   readonly clock: ShotClock;
   readonly allowHosts: readonly string[];
 }): PageWatch {
-  const { connection, sessionId } = input;
+  const { connection, sessionId, browserSessionId } = input;
   const lines = new Tail<ConsoleLine>();
   const errors = new Tail<PageError>();
   const requests = new Tail<NetworkEntry>();
@@ -191,38 +200,33 @@ export function watchPage(input: {
           requests.update(id, { ...held, status });
       }),
     ),
-    connection.on(
-      'Fetch.requestPaused',
-      mine((params) => {
-        const pausedId = text(params['requestId']) ?? '';
-        const request = record(params['request']);
-        const url = text(request?.['url']) ?? '';
-        if (hostDecision(url, input.allowHosts).allowed) {
-          void connection
-            .send('Fetch.continueRequest', { requestId: pausedId }, sessionId)
-            .catch(() => undefined);
-          return;
-        }
-        const id = text(params['networkId']) ?? pausedId;
-        const held = requests.get(id);
-        const refused: NetworkEntry = {
-          method: text(request?.['method']) ?? held?.method ?? 'GET',
-          url,
-          resourceType: resourceType(params['resourceType']),
-          at: held?.at ?? now(),
-          refused: 'host',
-        };
-        if (held === undefined) requests.put(refused, id);
-        else requests.update(id, refused);
+    connection.on('Fetch.requestPaused', (params, on) => {
+      // The page's session or the browser's: anything else is somebody else's interception.
+      if (on === undefined || (on !== sessionId && on !== browserSessionId)) return;
+      const pausedId = text(params['requestId']) ?? '';
+      const request = record(params['request']);
+      const url = text(request?.['url']) ?? '';
+      if (hostDecision(url, input.allowHosts).allowed) {
         void connection
-          .send(
-            'Fetch.failRequest',
-            { requestId: pausedId, errorReason: 'BlockedByClient' },
-            sessionId,
-          )
+          .send('Fetch.continueRequest', { requestId: pausedId }, on)
           .catch(() => undefined);
-      }),
-    ),
+        return;
+      }
+      const id = text(params['networkId']) ?? pausedId;
+      const held = requests.get(id);
+      const refused: NetworkEntry = {
+        method: text(request?.['method']) ?? held?.method ?? 'GET',
+        url,
+        resourceType: resourceType(params['resourceType']),
+        at: held?.at ?? now(),
+        refused: 'host',
+      };
+      if (held === undefined) requests.put(refused, id);
+      else requests.update(id, refused);
+      void connection
+        .send('Fetch.failRequest', { requestId: pausedId, errorReason: 'BlockedByClient' }, on)
+        .catch(() => undefined);
+    }),
   ];
 
   let stopped = false;

package/src/cmd-auth-spec.ts

@@ -0,0 +1,16 @@
+// `x auth`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-auth.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const AUTH_SUBCOMMANDS = ['seal-mfa'] as const;
+
+export const authSpec: CommandSpec = {
+  name: 'auth',
+  summary: 'one-shot maintenance of the auth tables: seal every plaintext second-factor secret',
+  usage: 'x auth seal-mfa [--json]',
+  requiresApp: true,
+  // No default: the one subcommand WRITES, and a bare `x auth` must not.
+  subcommands: [...AUTH_SUBCOMMANDS],
+  flags: [],
+};

package/src/cmd-auth.ts

@@ -0,0 +1,65 @@
+// `x auth seal-mfa` — seal every `x_users.mfa_secret` still stored in the clear, in place, under
+// the app's master key. The one-shot an upgrade onto sealed second-factor secrets owes: readers
+// refuse a plaintext value (`X_MFA_SECRET_UNSEALED`), and this is the command that refusal names.
+// Idempotent — a sealed value is counted and left alone — so an interrupted run is finished by
+// running it again.
+
+import type { MfaSecretStore } from '@ultimat3/auth';
+import { postgresAuthAdapter, sealMfaSecrets } from '@ultimat3/auth';
+import { requireAppRoot } from './app-root';
+import { authSpec } from './cmd-auth-spec';
+import type { CliCommand, CommandContext } from './command';
+import { ok } from './command';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { resolveServices } from './runtime-bindings';
+import { startQueue } from './runtime-queue';
+
+export interface OpenAuthStore extends MfaSecretStore {
+  close(): Promise<void>;
+}
+
+/**
+ * The app's own database, opened the way every other command opens it (`startQueue`: the
+ * framework's tables are applied first, so `x_users` exists) and ALWAYS released — a CLI that
+ * exits holding the PGlite lock breaks the next command run against this app.
+ */
+async function openAppAuthStore(root: string, ctx: CommandContext): Promise<OpenAuthStore> {
+  const queue = await startQueue(resolveServices(root, ctx.env), undefined, ctx.env);
+  return { adapter: postgresAuthAdapter(queue.db), close: () => queue.stop() };
+}
+
+/** `open` is the seam a test supplies a store through; the shipped command opens the app's. */
+export const authCommandOver = (
+  open: (root: string, ctx: CommandContext) => Promise<OpenAuthStore>,
+): CliCommand => ({
+  spec: authSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('auth', ctx.cwd).dir;
+    const store = await open(root, ctx);
+    try {
+      // The key is read from the command's own environment and the app's `.secrets.key`: with
+      // neither, the first seal refuses (`X_SEAL_KEY_MISSING`) before any row is written.
+      const report = await sealMfaSecrets(store, { root, env: ctx.env });
+      return ok(
+        'auth',
+        msg('cli.auth.sealed', {
+          sealed: report.sealed,
+          already: report.alreadySealed,
+          skipped: report.skipped,
+        }),
+        {
+          data: {
+            sealed: report.sealed,
+            alreadySealed: report.alreadySealed,
+            skipped: report.skipped,
+          },
+        },
+      );
+    } finally {
+      await store.close();
+    }
+  },
+});
+
+export const authCommand: CliCommand = authCommandOver(openAppAuthStore);

package/src/cmd-build-spec.ts

@@ -8,7 +8,7 @@ export const buildSpec: CommandSpec = {
   summary:
     'build a container image, a single binary, a prerendered static site, or the store an image boots from',
   usage:
-    'x build --target docker|binary|static|prebuilt [--tag name] [--out path] [--no-preflight] [--json]',
+    'x build --target docker|binary|static|prebuilt [--tag name] [--out path] [--platform bun-target] [--no-preflight] [--json]',
   requiresApp: true,
   flags: [
     {
@@ -20,6 +20,12 @@ export const buildSpec: CommandSpec = {
     },
     { name: 'tag', type: 'string', summary: 'image tag (docker target)' },
     { name: 'out', type: 'string', summary: 'output path (binary and static targets)' },
+    {
+      name: 'platform',
+      type: 'string',
+      summary:
+        "binary target only: bun-linux-x64 | bun-linux-arm64 | bun-windows-x64 | bun-darwin-arm64 — Bun's --target; a Windows build is written as <out>.exe",
+    },
     {
       name: 'preflight',
       type: 'boolean',