@ultimat3/cli 18.0.0 → 19.1.0

package/src/local-cli.ts

@@ -0,0 +1,71 @@
+// A globally installed `x` defers to the app's own `@ultimat3/cli` when the two are different
+// files. Measured 2026-09-05 in an app whose global `x` was a `bun link` of this checkout: the
+// global CLI's `@ultimat3/entity` was a second module instance with an EMPTY registry, so `x g`,
+// `x db gen` and `x manifest` wrote a manifest with zero entities and proposed dropping every
+// table — silently, with a green exit code. The app's entities register into the instance under
+// its `node_modules`; only the CLI under that same `node_modules` can see them. So the rule is the
+// one `tsc` and `eslint` follow: the project-local binary wins, and the global one only says so.
+//
+// The same registry split is what turned `x verify` green over that app: `@ultimat3/policy`'s
+// `isKnownPermission` deliberately checks nothing while no permission is declared, and the global
+// CLI's instance had none declared — so the `policy` step that exists to refuse an undeclared
+// grant (`app-permissions.ts`) had an empty set to refuse against. One process, one registry.
+
+// why: `realpathSync` is the whole decision — Bun ships no symlink-resolving stat of its own, and
+// `Bun.file(path).exists()` follows a link without saying where it went.
+import { existsSync, realpathSync } from 'node:fs';
+// why: Bun exposes no path-join primitive; the local bin is assembled from the app root.
+import { join } from 'node:path';
+import { findAppRoot } from './app-root';
+
+/**
+ * Set to any value to keep the CLI that was invoked. Nothing in this repository's CI needs it —
+ * both tracked apps symlink `node_modules/@ultimat3/cli` to `packages/cli`, so the realpath test
+ * below already answers "same file" — it exists for the one deliberate case: running a checkout's
+ * CLI against an app that pins an older release, to see what the next release would say.
+ */
+export const KEEP_GLOBAL_CLI_ENV = 'ULTIMATE_KEEP_GLOBAL_CLI';
+
+export const LOCAL_CLI_BIN = join('node_modules', '@ultimat3', 'cli', 'src', 'bin.ts');
+
+export interface LocalCliIo {
+  exists(path: string): boolean;
+  realpath(path: string): string;
+}
+
+const nodeIo: LocalCliIo = {
+  exists: existsSync,
+  realpath: (path) => realpathSync(path),
+};
+
+/**
+ * The app-local `bin.ts` to re-execute, or undefined when this process already IS the app's CLI
+ * (a workspace symlink resolves to the same file), when there is no app, when this process is a
+ * compiled binary, or when the caller opted out. Pure over the injected filesystem so the
+ * decision has a test without a checkout.
+ *
+ * A compiled `x` (`x build --target binary`, the container's `/app/x`) has an `import.meta.path`
+ * inside Bun's virtual `/$bunfs/` — no such file exists on disk, so `realpath` throws. That is
+ * the keep case, not the hand-over case: the binary is the deliberate artifact, and the runtime
+ * image carries no `bun` to hand over to. The other unresolvable side — a `node_modules` entry
+ * that exists but whose link is dangling — is kept for the same reason: nothing there can run.
+ */
+export function resolveLocalCli(
+  input: {
+    readonly cwd: string;
+    readonly selfPath: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+  },
+  io: LocalCliIo = nodeIo,
+): string | undefined {
+  if (input.env[KEEP_GLOBAL_CLI_ENV] !== undefined) return undefined;
+  const root = findAppRoot(input.cwd);
+  if (root === undefined) return undefined;
+  const local = join(root.dir, LOCAL_CLI_BIN);
+  if (!io.exists(local)) return undefined;
+  try {
+    return io.realpath(local) === io.realpath(input.selfPath) ? undefined : local;
+  } catch {
+    return undefined;
+  }
+}

package/src/mcp-errors.ts

@@ -78,6 +78,15 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_E2E_LOCATOR_AMBIGUOUS:
     'x test e2e --json   # the fix line carries the same call with .first() on it',
   X_E2E_SERVICE_WORKER_ABSENT: 'x build --target static --json',
+  // The four raw-CDP codes. `x doctor` for the missing browser, because that is the command whose
+  // whole job is reporting what this machine does not have; the other three are raised inside a
+  // running suite, so the runnable half is the command that re-runs it.
+  X_CDP_BROWSER_MISSING:
+    'x doctor --json   # or set CHROME_PATH to a Chrome binary; unset, the browser-backed suite skips',
+  X_CDP_LAUNCH_FAILED:
+    'x test e2e --json   # the cause carries the last lines of the browser\u2019s own stderr',
+  X_CDP_CALL_FAILED: 'x test e2e --json   # the cause names the DevTools call the browser refused',
+  X_CDP_TIMEOUT: 'x test e2e --json   # the cause names the call that never answered',
   X_GH_UNAVAILABLE: 'gh auth login   # install first from https://cli.github.com',
   X_GH_NOT_AUTHENTICATED: 'gh auth login',
   X_GH_COMMAND_FAILED: 'x ci --json   # the finding carries the gh invocation that failed',

package/src/measurement-actor.ts

@@ -0,0 +1,26 @@
+// The actor a route is rendered AS when the render exists only to be weighed. `app/` pages are
+// authed by construction: a `load` that calls a policy-guarded query denies an anonymous actor with
+// `X_UNAUTHENTICATED`, so under the anonymous build context every authed page was reported
+// `X_BUDGET_UNMEASURED` and a real app could not pass the `budgets` step (measured 2026-09-05).
+// Weighing bytes needs no data authority — the rendered document is discarded — so this actor holds
+// every permission. It is handed ONLY to the weigh-and-discard branch of `prerender.ts`, never to
+// `renderStatic`: a `site/` artifact is published to everyone, and a guarded query inside its `load`
+// must keep failing the build rather than rendering another actor's rows into a file.
+
+import type { Actor } from '@ultimat3/core';
+
+/** The id every trace and log line under a measurement render carries, so it is recognisable. */
+export const MEASUREMENT_ACTOR_ID = 'x-build-measure';
+
+/**
+ * `kind: 'service'` and not `'user'`: an app's own `requireMember()`-style helper that resolves a
+ * user to a row has nothing to resolve here, and the honest kind says so. `'*'` is the grant
+ * `actorHas` reads as everything — the same spelling a role map uses for a superuser.
+ */
+export const measurementActor = (): Actor => ({
+  kind: 'service',
+  id: MEASUREMENT_ACTOR_ID,
+  roles: [],
+  scopes: [],
+  permissions: ['*'],
+});

package/src/messages.ts

@@ -11,6 +11,10 @@ const CATALOG = {
   'cli.commands.heading': 'commands',
   'cli.build.done': 'built {target}',
   'cli.build.failed': '{target} build failed',
+  // A build-output line, so it belongs here rather than inline beside the emitter: `x build` is a
+  // human surface and every other word it prints comes from this catalog.
+  'cli.build.pushUnwired':
+    'pwa.push is true and no VAPID key is configured, so the emitted sw.js carries no push handler',
   // `describeCron`'s vocabulary. `@ultimat3/time` is tier 1 and reaches no i18n runtime, so the
   // caller supplies the words — and the caller here is a rendered `x tasks show` line, which is
   // exactly what this catalog holds. `msg()` leaves an un-supplied `{n}`/`{time}`/`{days}`/
@@ -79,6 +83,7 @@ const CATALOG = {
   'cli.dev.panels': '  panels {panels}',
   'cli.dev.introspect': '  introspect {url}',
   'cli.dev.manifest': '  manifest {path}',
+  'cli.dev.mcp': '  mcp POST {path}',
   'cli.deploy.plan': 'containers only: {images} image, roles {roles}',
   'cli.doctor.clean': 'no findings — environment is shippable',
   'cli.doctor.findings': '{count} finding(s)',

package/src/prerender.ts

@@ -6,7 +6,7 @@
 import { join } from 'node:path';
 import { createContext, renderThrowable, runWithContext } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
-import { routeEntries } from '@ultimat3/render';
+import { describeRoutes, routeEntries } from '@ultimat3/render';
 import { renderStatic } from '@ultimat3/render/server';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
@@ -17,9 +17,11 @@ import { errorPageDocument, STATIC_ERROR_PAGE } from './error-pages';
 import { FAVICON_PATH, faviconBytes } from './favicon';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
+import { measurementActor } from './measurement-actor';
 import { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifacts';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
+import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, serviceWorkerArtifacts } from './sw-artifacts';
 
 // Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
 // carries it, and this file already imports that module.
@@ -76,6 +78,15 @@ export interface PrerenderReport {
   readonly report: string;
   /** Client entries emitted, one chunk each. Reported so "which JS shipped?" needs no unzip. */
   readonly islands: readonly string[];
+  /**
+   * What the service worker could not express, and what its precache manifest weighs too much of.
+   *
+   * `PrecacheManifest.warnings` had no reader anywhere in the tree — the precache budget was, in
+   * `wiki/Troubleshooting.md`'s own words, "a designed thing that is not one" (#390). An install
+   * that stalls on a bad connection is invisible on a laptop and fatal on a phone, so the number
+   * has to reach the build's own report. Empty for an app with no service worker.
+   */
+  readonly serviceWorkerWarnings: readonly string[];
 }
 
 /**
@@ -154,6 +165,18 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // wiring exists to close. `undefined` when the app is not installable, and then no document
   // names it either.
   const pwa = await loadPwaArtifacts(options.root);
+  // The worker and its registration script, written as FILES. A static host runs no route table,
+  // so a `<script src="/x-sw-register.js">` in every document is a 404 unless the bytes are in the
+  // artifact — the same promise `favicon.ico` and the icons above keep, for the asset that decides
+  // whether the export works offline at all.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands });
+  if (serviceWorker !== undefined) {
+    await Bun.write(join(options.out, SERVICE_WORKER_PATH.slice(1)), serviceWorker.source);
+    await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorker.register);
+  }
   if (pwa !== undefined) {
     await Bun.write(join(options.out, WEB_MANIFEST_PATH.slice(1)), pwa.body);
     // And the icons that manifest NAMES. A static host runs no `assetRoutes()`, so every
@@ -172,13 +195,25 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // documents, and this build's own id so a component reading `ctx.buildId` stamps the artifact
   // with the id the report and the stats carry.
   const ctx = createContext({ role: 'web', buildId });
-  const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
-    runWithContext(ctx, () =>
+  // A SECOND context, for the branch below that renders only to weigh. Its actor holds every
+  // permission (`measurement-actor.ts`), because an `app/` page's `load` calls policy-guarded
+  // queries and denied the anonymous one with `X_UNAUTHENTICATED` — every authed page unmeasured.
+  // `renderStatic` keeps `ctx`: its output is a published file, and a `site/` load that a policy
+  // refuses must fail the build, never render another actor's rows into it.
+  const measureCtx = createContext({ role: 'web', buildId, actor: measurementActor() });
+  const documentAs = (
+    as: typeof ctx,
+    entry: RouteEntry,
+    data: { url: string; params: Record<string, string> },
+  ) =>
+    runWithContext(as, () =>
       routeDocument(entry, data, {
         resolveIsland: (file: string) => islands.resolverFor(file),
-        ...(pwa === undefined ? {} : { pwaHead: pwa.head }),
+        ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       }),
     );
+  const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
+    documentAs(ctx, entry, data);
 
   for (const entry of routeEntries()) {
     const facts = { surface: entry.surface, render: entry.config.render, route: entry.path };
@@ -191,7 +226,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       // routes it never used to touch would be a worse regression than the gap it closes. A route
       // that will not render here is reported, gets no stats entry, and stays `X_BUDGET_UNMEASURED`.
       try {
-        const html = await document(entry, {
+        const html = await documentAs(measureCtx, entry, {
           url: new URL(entry.path, origin).href,
           params: {},
         });
@@ -267,6 +302,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     // stdout — so the one command the finding tells an author to run printed no `unmeasured` key
     // and no reason. Written into the report is what makes the instruction true.
     unmeasured,
+    serviceWorkerWarnings: serviceWorker?.warnings ?? [],
   });
   return {
     out: options.out,
@@ -277,5 +313,6 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     stats,
     report,
     islands: islands.chunks.map((chunk) => chunk.file),
+    serviceWorkerWarnings: serviceWorker?.warnings ?? [],
   };
 }

package/src/pwa-artifacts.ts

@@ -22,7 +22,7 @@ import { existsSync } from 'node:fs';
 // why: Bun exposes no path-join primitive, and `APP_CONFIG_FILE` is app-root-relative — the same
 // necessity `favicon.ts` and `dev-assets.ts` each record for their own root-relative constant.
 import { join } from 'node:path';
-import type { PwaColors } from '@ultimat3/core';
+import type { PwaColors, PwaOfflineConfig } from '@ultimat3/core';
 import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 import {
@@ -56,6 +56,15 @@ export interface PwaArtifacts {
    * no manifest is an iOS icon for an app iOS will not add.
    */
   readonly head: string;
+  /**
+   * The three `pwa` keys the SERVICE WORKER needs, carried here because this is the one module
+   * that reads an app's config file — `sw-artifacts.ts` needs the route table and the island
+   * bundle as well, and a second `await import` of `app.config.ts` would be a second answer to
+   * "what did this app declare".
+   */
+  readonly offline: PwaOfflineConfig;
+  readonly backgroundSync: boolean;
+  readonly push: boolean;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -93,6 +102,9 @@ function colorsOf(value: unknown): PwaColors | undefined {
 interface InstallableApp {
   readonly name: string;
   readonly colors: PwaColors;
+  readonly offline: PwaOfflineConfig;
+  readonly backgroundSync: boolean;
+  readonly push: boolean;
 }
 
 async function loadInstallable(root: string): Promise<InstallableApp | undefined> {
@@ -109,9 +121,36 @@ async function loadInstallable(root: string): Promise<InstallableApp | undefined
   const name = text(pwa['name']);
   const colors = colorsOf(pwa['colors']);
   if (name === undefined || colors === undefined) return undefined;
-  return { name, colors };
+  return { name, colors, offline: offlineOf(pwa['offline']), ...flags(pwa) };
+}
+
+/**
+ * The offline block, read structurally for `colorsOf`'s reason: `defineConfig` refuses
+ * `enabled: true` without an absolute `offline.fallback`, but a HAND-WRITTEN config object never
+ * passed through it. A missing or relative fallback answers `null`, and `serviceWorkerArtifacts`
+ * then emits no worker at all — never a path the framework invented, which offline would be a
+ * cached 404 answering every navigation.
+ */
+function offlineOf(value: unknown): PwaOfflineConfig {
+  const block = isRecord(value) ? value : {};
+  const fallback = text(block['fallback']);
+  const patterns = block['neverCache'];
+  return {
+    fallback: fallback?.startsWith('/') === true ? fallback : null,
+    image: text(block['image']) ?? null,
+    font: text(block['font']) ?? null,
+    neverCache: Array.isArray(patterns)
+      ? patterns.filter((entry): entry is string => typeof entry === 'string')
+      : [],
+  };
 }
 
+/** `=== true` for `enabled`'s reason: a hand-written `backgroundSync: 'yes'` wires nothing. */
+const flags = (pwa: Record<string, unknown>): { backgroundSync: boolean; push: boolean } => ({
+  backgroundSync: pwa['backgroundSync'] === true,
+  push: pwa['push'] === true,
+});
+
 /**
  * Resolved ONCE at boot, like `loadSignInPath` and `loadCacheTiers` and unlike `faviconBytes`:
  * `await import` caches the module, so re-reading per request would answer the same object at a
@@ -139,6 +178,9 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
     icons: icons?.manifestIcons ?? [],
   });
   return {
+    offline: app.offline,
+    backgroundSync: app.backgroundSync,
+    push: app.push,
     body: serializeWebManifest(result.manifest),
     head:
       `<link rel="manifest" href="${escapeAttribute(WEB_MANIFEST_PATH)}">` +

package/src/serve.ts

@@ -20,11 +20,14 @@ import {
   migrate,
 } from '@ultimat3/db';
 import type { Route } from '@ultimat3/http';
+import { describeRoutes } from '@ultimat3/render';
 import { createIsrController } from '@ultimat3/render/server';
 import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
+import { mountAppMcp } from './app-mcp';
+import { loadAppRuntime } from './app-runtime';
 import { acceptCreatedTables } from './db-accept-created';
 import { assetRoutes } from './dev-assets';
 import { startQueue } from './dev-queue';
@@ -46,6 +49,8 @@ import { readMigrations } from './migrations';
 import { startOtlpExport } from './otlp-export';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import type { RuntimeOverrides } from './runtime-overrides';
+import { serviceWorkerArtifacts } from './sw-artifacts';
+import { serviceWorkerRoutes } from './sw-routes';
 
 export const DEFAULT_PORT = 3000;
 
@@ -249,7 +254,22 @@ export async function releaseBoot(
  * table is the same three contributions minus the dashboard — a `/_x` in production would expose
  * the app's policy matrix, its outbox and its spans to the internet.
  */
-export async function serveApp(options: ServeOptions): Promise<ServedApp> {
+/**
+ * A caller's `runtime` wins; with none, the app's own `apps/<app>/runtime.ts` is what this boot
+ * reads — the SAME file `x dev` reads — so the two boots compose one middleware chain, one
+ * rate-limit store, one ISR store, rather than a development set and a production set. Resolved
+ * ONCE, at each public entry, so every reader below (`startServices`, `startQueue`, the asset and
+ * ISR seams, the replica override) sees one object: a per-read fallback would be the partial read
+ * this repository names as its most repeated defect.
+ */
+export async function withAppRuntime(options: ServeOptions): Promise<ServeOptions> {
+  if (options.runtime !== undefined) return options;
+  const runtime = await loadAppRuntime(options.root);
+  return runtime === undefined ? options : { ...options, runtime };
+}
+
+export async function serveApp(input: ServeOptions): Promise<ServedApp> {
+  const options = await withAppRuntime(input);
   const role = options.role ?? roleFromEnv(options.env);
   const runtime = await startServices(
     resolveServices(options.root, options.env),
@@ -303,8 +323,19 @@ async function bootRoles(boot: {
   // on a laptop and absent in the image is exactly the dev/prod difference this file exists to
   // prevent, and it is the one an operator cannot see without installing the app.
   const pwa = await loadPwaArtifacts(options.root);
+  // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
+  // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
+  // route added here cannot be missing from the precache manifest.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands });
+  // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
+  const mcpMount = await mountAppMcp(options.root);
   const routes: readonly Route[] = [
     ...apiRoutes(),
+    ...mcpMount.routes,
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
     ...assetRoutes({
       root: options.root,
       storage: runtime.storage,
@@ -316,7 +347,7 @@ async function bootRoles(boot: {
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),
-      ...(pwa === undefined ? {} : { pwaHead: pwa.head }),
+      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       // Only when a store was supplied. `createIsrController` defaults to a per-process memory
       // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
       // the fleet while the other eleven keep serving the page it just invalidated.
@@ -375,8 +406,11 @@ async function bootRoles(boot: {
  * holds for every other role until core's drain completes, so SIGTERM from a rolling restart takes
  * the three-phase path (stop accepting, finish in-flight, close) instead of killing a query.
  */
-export async function runRole(options: ServeOptions): Promise<StartedApp> {
-  const role = options.role ?? roleFromEnv(options.env);
+export async function runRole(input: ServeOptions): Promise<StartedApp> {
+  // The role FIRST: a bad `ROLE` is refused before the root is read at all, so a boot that was
+  // always going to fail creates nothing under it — the same order `resolveServices` is held to.
+  const role = input.role ?? roleFromEnv(input.env);
+  const options = await withAppRuntime(input);
   if (role === 'migrate') {
     const migrated = await runMigrations({ ...options, role });
     // The release phase has one channel — the exit code — so drift is thrown here rather than

package/src/source-files.ts

@@ -29,12 +29,24 @@ export const isGenerated = (path: string): boolean => path.endsWith('.d.ts');
 /** Every opt-in suffix (`*.{contract,live,job,eval,e2e}.test.ts`) still ends `.test.ts`. */
 export const isTest = (path: string): boolean => /\.test\.tsx?$/.test(path);
 
-/** Every source file under `root`, repo-relative and deduplicated across the globs. */
+/**
+ * Every source file under `root`, repo-relative and deduplicated across the globs — in a SORTED
+ * order per pattern, `As of 2026-09-05`. `Bun.Glob.scan` yields in the filesystem's `readdir`
+ * order, which ext4 hashes: the first offender a scan names was `index.ts` on one machine and
+ * `tools.ts` on a GitHub runner, so a finding's `cause` depended on which disk held the checkout
+ * (`workspace-graph.test.ts`, red on CI and green everywhere else). Code-unit compare, never
+ * `localeCompare`, for the reason `describeRoutes` states: one order on every machine.
+ */
 export async function* eachSourceFile(root: string): AsyncGenerator<string> {
   const seen = new Set<string>();
   for (const pattern of SOURCE_GLOBS) {
+    const matches: string[] = [];
     for await (const path of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
-      if (isVendored(path) || seen.has(path)) continue;
+      if (!isVendored(path)) matches.push(path);
+    }
+    matches.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    for (const path of matches) {
+      if (seen.has(path)) continue;
       seen.add(path);
       yield path;
     }

package/src/static-report.ts

@@ -13,6 +13,7 @@ import { RENDER_MODES } from '@ultimat3/core';
 import type { Surface } from '@ultimat3/render';
 import { SURFACE_SPECS, SURFACES, surfaceAllows } from '@ultimat3/render';
 import type { JsonValue } from './output';
+import { SERVICE_WORKER_PATH } from './sw-artifacts';
 
 /** Beside `.x/build-stats.json`, and written by the same call — see `readStaticReport` below. */
 export const STATIC_REPORT_FILE = join('.x', 'static-report.json');
@@ -84,6 +85,15 @@ export type StaticReport = {
    * the reader.
    */
   readonly unmeasured: readonly UnmeasuredRoute[];
+  /**
+   * The service worker's own findings: a capability declared with nothing to wire it to, and a
+   * precache manifest over its byte ceiling. `PrecacheManifest.warnings` had no reader anywhere in
+   * the tree (#390), so the ceiling was — in `wiki/Troubleshooting.md`'s own words — "a designed
+   * thing that is not one". Written here for `unmeasured`'s reason: `cmd-build.ts` discards a
+   * successful subprocess's stdout, so a warning that lives only on the in-process report reaches
+   * nobody. Empty for an app with no service worker.
+   */
+  readonly serviceWorkerWarnings: readonly string[];
 };
 
 /**
@@ -177,7 +187,7 @@ const isEmitted = (value: unknown): value is EmittedPage =>
  */
 export function parseStaticReport(value: unknown): StaticReport | undefined {
   if (!isRecord(value)) return undefined;
-  const { target, out, buildId, emitted, skipped, unmeasured } = value;
+  const { target, out, buildId, emitted, skipped, unmeasured, serviceWorkerWarnings } = value;
   if (target !== 'static' || typeof out !== 'string' || typeof buildId !== 'string') {
     return undefined;
   }
@@ -190,7 +200,25 @@ export function parseStaticReport(value: unknown): StaticReport | undefined {
   if (unmeasured !== undefined && (!Array.isArray(unmeasured) || !unmeasured.every(isUnmeasured))) {
     return undefined;
   }
-  return { target, out, buildId, emitted, skipped, unmeasured: unmeasured ?? [] };
+  // Optional on the way in for `unmeasured`'s reason, and a non-string entry drops the whole
+  // report for a malformed skip row's reason: a warning list with a hole in it is a build that
+  // says less than it measured, which is how the worker's findings went unread in the first place.
+  if (
+    serviceWorkerWarnings !== undefined &&
+    (!Array.isArray(serviceWorkerWarnings) ||
+      !serviceWorkerWarnings.every((entry) => typeof entry === 'string'))
+  ) {
+    return undefined;
+  }
+  return {
+    target,
+    out,
+    buildId,
+    emitted,
+    skipped,
+    unmeasured: unmeasured ?? [],
+    serviceWorkerWarnings: (serviceWorkerWarnings as readonly string[] | undefined) ?? [],
+  };
 }
 
 export async function writeStaticReport(root: string, report: StaticReport): Promise<string> {
@@ -232,7 +260,12 @@ export function staticReportData(report: StaticReport | undefined): Record<strin
   // which the inventory is about — `data` already carries `artifact` and the build's own id.
   return report === undefined
     ? {}
-    : { emitted: report.emitted, skipped: report.skipped, unmeasured: report.unmeasured };
+    : {
+        emitted: report.emitted,
+        skipped: report.skipped,
+        unmeasured: report.unmeasured,
+        serviceWorkerWarnings: report.serviceWorkerWarnings,
+      };
 }
 
 /**
@@ -247,6 +280,16 @@ export function renderStaticReport(report: StaticReport): readonly string[] {
     // whose budget could not be weighed is invisible in `emitted` and, when it also rendered, in
     // `skipped` too — and it is the row `X_BUDGET_UNMEASURED` sends its reader here to read.
     ...report.unmeasured.map((route) => ['unmeasured', route.path, route.reason]),
+    // The service worker's own findings, in the same three columns — a precache manifest over its
+    // byte ceiling AND a capability declared with nothing to wire it to, which is why neither the
+    // field nor this label says `precache`. `sw.js` is the one artifact that keeps serving after a
+    // deploy is over, so both are build-time facts that have to be visible in the build's own
+    // output — `PrecacheManifest` computed the first and nothing read it (#390).
+    ...report.serviceWorkerWarnings.map((warning) => [
+      'service-worker',
+      SERVICE_WORKER_PATH,
+      warning,
+    ]),
   ];
   const widths = [0, 1].map((index) =>
     Math.max(...rows.map((row) => (row[index] ?? '').length), 0),