@ultimat3/cli 22.3.0 → 22.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.3.0",
+  "version": "22.3.2",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.3.0",
-    "@ultimat3/admin": "22.3.0",
-    "@ultimat3/ai": "22.3.0",
-    "@ultimat3/auth": "22.3.0",
-    "@ultimat3/cache": "22.3.0",
-    "@ultimat3/core": "22.3.0",
-    "@ultimat3/db": "22.3.0",
-    "@ultimat3/entity": "22.3.0",
-    "@ultimat3/flags": "22.3.0",
-    "@ultimat3/http": "22.3.0",
-    "@ultimat3/i18n": "22.3.0",
-    "@ultimat3/jobs": "22.3.0",
-    "@ultimat3/mail": "22.3.0",
-    "@ultimat3/manifest": "22.3.0",
-    "@ultimat3/mcp": "22.3.0",
-    "@ultimat3/money": "22.3.0",
-    "@ultimat3/notify": "22.3.0",
-    "@ultimat3/policy": "22.3.0",
-    "@ultimat3/pwa": "22.3.0",
-    "@ultimat3/query": "22.3.0",
-    "@ultimat3/realtime": "22.3.0",
-    "@ultimat3/render": "22.3.0",
-    "@ultimat3/schema": "22.3.0",
-    "@ultimat3/seo": "22.3.0",
-    "@ultimat3/storage": "22.3.0",
-    "@ultimat3/testing": "22.3.0",
-    "@ultimat3/time": "22.3.0",
+    "@ultimat3/action": "22.3.2",
+    "@ultimat3/admin": "22.3.2",
+    "@ultimat3/ai": "22.3.2",
+    "@ultimat3/auth": "22.3.2",
+    "@ultimat3/cache": "22.3.2",
+    "@ultimat3/core": "22.3.2",
+    "@ultimat3/db": "22.3.2",
+    "@ultimat3/entity": "22.3.2",
+    "@ultimat3/flags": "22.3.2",
+    "@ultimat3/http": "22.3.2",
+    "@ultimat3/i18n": "22.3.2",
+    "@ultimat3/jobs": "22.3.2",
+    "@ultimat3/mail": "22.3.2",
+    "@ultimat3/manifest": "22.3.2",
+    "@ultimat3/mcp": "22.3.2",
+    "@ultimat3/money": "22.3.2",
+    "@ultimat3/notify": "22.3.2",
+    "@ultimat3/policy": "22.3.2",
+    "@ultimat3/pwa": "22.3.2",
+    "@ultimat3/query": "22.3.2",
+    "@ultimat3/realtime": "22.3.2",
+    "@ultimat3/render": "22.3.2",
+    "@ultimat3/schema": "22.3.2",
+    "@ultimat3/seo": "22.3.2",
+    "@ultimat3/storage": "22.3.2",
+    "@ultimat3/testing": "22.3.2",
+    "@ultimat3/time": "22.3.2",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/browser-launcher-fake.ts

@@ -26,6 +26,8 @@ export interface FakeShotPage {
   readonly url: string;
   readonly html: string;
   readonly evaluate?: Readonly<Record<string, string>> | undefined;
+  /** The document's HTTP status. Absent is 200 — the page was recorded because it exists. */
+  readonly status?: number | undefined;
 }
 
 /** A PNG signature, and nothing behind it: deterministic bytes, never a render. */
@@ -76,7 +78,8 @@ function fakePage(byUrl: ReadonlyMap<string, FakeShotPage>, init: ShotSessionIni
     network.push({
       method: 'GET',
       url: page.url,
-      status: 200,
+      // Data the page answers with, never a bound — a recorded page exists, so absent is a 200.
+      status: page.status === undefined ? 200 : page.status,
       resourceType: 'document',
       at: init.clock.now().getTime(),
     });

package/src/cmd-shot-spec.ts

@@ -7,7 +7,7 @@ export const shotSpec: CommandSpec = {
   name: 'shot',
   summary: 'photograph one route, one island in a state it declares, or every island in the app',
   usage:
-    'x shot <route> [--locale <l>] [--theme light|dark] | --matrix [<route>] | --island <name> [--state <id>] | --all-islands [--port 0] [--out <dir>] [--settle 2000] [--json]',
+    'x shot <route> [--locale <l>] [--theme light|dark] | --matrix [<route>] | --island <name> [--state <id>] | --all-islands [--expect-status 404] [--port 0] [--out <dir>] [--settle 2000] [--json]',
   requiresApp: true,
   flags: [
     { name: 'port', type: 'string', summary: 'dev port (0 lets the kernel pick a free one)' },
@@ -15,6 +15,12 @@ export const shotSpec: CommandSpec = {
     { name: 'full', type: 'boolean', summary: 'whole page, not the fold', default: true },
     { name: 'settle', type: 'string', summary: 'ms to wait after load before capturing' },
     { name: 'timeout', type: 'string', summary: 'ms one navigation may take' },
+    {
+      name: 'expect-status',
+      type: 'string',
+      summary:
+        'the document status this shot is ok with (e.g. 404); absent: any 2xx, else it fails',
+    },
     { name: 'browser', type: 'string', summary: 'Chrome or Chromium binary to launch' },
     {
       name: 'cdp-url',

package/src/cmd-shot.ts

@@ -45,6 +45,7 @@ import { readThemeFlag, themeChoiceExpression } from './shot-theme';
 import type { IslandCount, ShotArtifacts } from './shot-verdict';
 import {
   buildVerdict,
+  documentStatus,
   ISLAND_PROBE,
   parseIslandProbe,
   shotLines,
@@ -218,6 +219,11 @@ export interface ShotRun {
    */
   readonly acceptLanguage?: string | undefined;
   readonly now?: (() => Date) | undefined;
+  /**
+   * `--expect-status`: the document status this shot is ok with — `404` to photograph the not-found
+   * page on purpose. Absent means any 2xx, and anything else fails the verdict with the status.
+   */
+  readonly expectStatus?: number | undefined;
   /**
    * Something to do with the page AFTER the islands settled and BEFORE the picture — `ui.inspect`
    * reads the DOM here, on the one navigation the picture already paid for. `settle` re-runs the
@@ -265,6 +271,9 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       if (choice !== undefined) await page.prepare(choice);
     }
     await page.goto(requestedUrl, { timeout: options.timeoutMs });
+    // Read NOW as well as at capture: the network ring is bounded, and a page that fires a few
+    // hundred requests while it settles evicts the document entry the verdict needs.
+    const landedStatus = documentStatus(page.network(), page.url());
     if (options.settleMs > 0) await Bun.sleep(options.settleMs);
     // The probe may legitimately answer nothing — a page that refuses evaluation, a driver with no
     // JS engine. `null` says so; a `0` would read as "the route renders no islands", which is a
@@ -303,6 +312,8 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       network: page.network(),
       networkDropped: page.networkDropped(),
       islands,
+      landedStatus,
+      ...(options.expectStatus === undefined ? {} : { expectStatus: options.expectStatus }),
     });
     mkdirSync(options.outDir, { recursive: true });
     const image = join(options.outDir, SHOT_IMAGE);
@@ -387,6 +398,11 @@ export const shotCommand: CliCommand = {
     const port = intFlag(ctx.args, 'port', PORT_RANGE.min, DEFAULT_PORT, PORT_RANGE.max);
     const settleMs = intFlag(ctx.args, 'settle', 0, DEFAULT_SETTLE_MS);
     const timeoutMs = intFlag(ctx.args, 'timeout', 1, DEFAULT_PAGE_TIMEOUT_MS);
+    // Read only when given: its absence means "any 2xx", which no single default number can say.
+    const expectStatus =
+      flagString(ctx.args, 'expect-status') === undefined
+        ? undefined
+        : intFlag(ctx.args, 'expect-status', 100, 200, 599);
     // Which browser this run gets — start one here, or attach to one somebody else is running.
     // Decided by `shot-browser.ts` over plain inputs, and decided HERE, before a dev server or a
     // provider session exists to pay for a typo. It also PROBES for an installed Chrome and refuses
@@ -427,6 +443,7 @@ export const shotCommand: CliCommand = {
       timeoutMs,
       fullPage: flagBool(ctx.args, 'full'),
       extraHosts: flagString(ctx.args, 'allow-hosts'),
+      ...(expectStatus === undefined ? {} : { expectStatus }),
     };
     if (matrix) {
       // `--locale` and `--theme` narrow the matrix to one value of their axis.

package/src/messages.ts

@@ -189,6 +189,12 @@ const CATALOG = {
   'cli.shot.ok': '{route} clean — {islands} island(s) mounted, nothing logged and nothing threw',
   'cli.shot.errors': '{route}: {errors} console error(s) — verdict.json names each one',
   'cli.shot.redirected': '{route} redirected to {url} — the picture is not the route asked for',
+  // After the redirect and before everything else: a 404 page can be spotless, and a picture of
+  // "Not found" read as the route is the capture lying about its subject.
+  'cli.shot.status':
+    '{route} answered HTTP {status}, expected {expected} — the picture is that response, not the page',
+  'cli.shot.document': '  document HTTP {status}',
+  'cli.shot.documentUnknown': '  document status not seen — the driver recorded no response for it',
   'cli.shot.server.booted': '  server   booted for this shot on {url}',
   'cli.shot.server.reused': '  server   the x dev already running on {url}',
   'cli.shot.canvas': '  canvas   {width}x{height}',

package/src/revalidated-response.ts

@@ -0,0 +1,38 @@
+// The one answer for a public file whose URL carries NO content hash: cacheable, revalidated on
+// every use, and a 304 when the bytes have not moved. `immutable` belongs to a URL that IS its
+// content (islands, styles, `asset()` files) and to nothing else — a file served immutable under a
+// name that outlives its bytes is a file no client refreshes for a year.
+
+import type { UltimateRequest } from '@ultimat3/http';
+import { etagMatches } from './runtime-storage';
+
+/**
+ * The document's own posture (`@ultimat3/render`'s `render-static.ts`), for the same reason: the
+ * URL says nothing about the bytes, so a cache may keep them and must ask before reusing them.
+ * Written as a header rather than a `CacheHint`, which has no `must-revalidate`.
+ */
+export const REVALIDATE_CACHE_CONTROL = 'public, max-age=0, must-revalidate';
+
+/**
+ * A strong validator from the bytes — xxHash32, the function `contentHash` applies to a document,
+ * taken here over bytes because an icon is not a string. Revalidating costs a request and no body.
+ */
+export function revalidatedResponse(
+  request: UltimateRequest,
+  body: string | Uint8Array,
+  contentType: string,
+): Response {
+  // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
+  // `SharedArrayBuffer`, which `Response` does not accept — `runtime-assets.ts`'s rule, verbatim.
+  const bytes = typeof body === 'string' ? new TextEncoder().encode(body) : new Uint8Array(body);
+  const etag = `"${Bun.hash.xxHash32(bytes).toString(16).padStart(8, '0')}"`;
+  const headers = {
+    'content-type': contentType,
+    'cache-control': REVALIDATE_CACHE_CONTROL,
+    etag,
+  };
+  if (etagMatches(request.header('if-none-match'), etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(bytes, { headers });
+}

package/src/runtime-assets.ts

@@ -20,6 +20,7 @@ import { faviconRoute } from './favicon';
 import { iconPlan, iconRenderer } from './icon-assets';
 import type { PwaArtifacts } from './pwa-artifacts';
 import { pwaManifestRoute } from './pwa-artifacts';
+import { revalidatedResponse } from './revalidated-response';
 import {
   AUTHORIZED_OBJECT_CACHE,
   assertReadableKey,
@@ -41,8 +42,10 @@ import { siteAssetTable } from './site-assets';
 export const MEDIA_BASE_PATH = '/media';
 
 /**
- * A generated icon and a content-addressed variant answer forever with the same bytes, so the
- * immutable hint is a fact about the key. It is NOT a fact about this route — see `mediaCache`.
+ * A content-addressed variant answers forever with the same bytes, so the immutable hint is a fact
+ * about the key. It is NOT a fact about this route — see `mediaCache`. The generated ICONS are not
+ * content-addressed (`/icons/icon-192.png` names a size, not bytes), so they revalidate instead —
+ * see `revalidatedResponse`.
  */
 const IMMUTABLE_IMAGE: CacheHint = { mode: 'immutable' };
 
@@ -198,8 +201,12 @@ export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
     method: 'GET',
     path: entry.outputPath,
     meta: { name: `assets.icon.${entry.spec.filename}`, auth: 'public', tags: ['assets'] },
+    // Revalidated, never `immutable` (22.3.2): the file name is the icon's SIZE, so a new
+    // `icon.png` shipped under the same URLs and every client that had seen the old one kept it for
+    // a year. The manifest and the apple-touch links name these paths, so a hashed URL would move
+    // every document and the manifest with it; a 304 is the cheaper fix.
     handler: async (request: UltimateRequest): Promise<Response> =>
-      imageResponse(await render(plan, request.pathname), 'image/png', IMMUTABLE_IMAGE),
+      revalidatedResponse(request, await render(plan, request.pathname), 'image/png'),
   }));
   // The icons above are genuinely public — they are rendered from a file committed in the app, and
   // an install prompt fetches them before anyone has signed in. `/media` is the opposite: it serves

package/src/shot-verdict.ts

@@ -25,6 +25,9 @@ export const SHOT_MESSAGE_KEYS = [
   'cli.shot.ok',
   'cli.shot.errors',
   'cli.shot.redirected',
+  'cli.shot.status',
+  'cli.shot.document',
+  'cli.shot.documentUnknown',
   'cli.shot.picture',
   'cli.shot.verdict',
   'cli.shot.server.booted',
@@ -146,6 +149,13 @@ export interface ShotInput {
   readonly networkDropped: number;
   /** `null` when the probe could not run or did not parse. Never a zero standing in for unknown. */
   readonly islands: IslandCount | null;
+  /**
+   * The document's status as read right after navigation. Only a fallback: the network ring is
+   * bounded, so on a page of a few hundred requests the document entry may be gone by capture time.
+   */
+  readonly landedStatus?: number | null | undefined;
+  /** `--expect-status`: the one status this shot is ok with. Absent means any 2xx. */
+  readonly expectStatus?: number | undefined;
 }
 
 export interface ShotVerdict extends ShotInput {
@@ -161,10 +171,44 @@ export interface ShotVerdict extends ShotInput {
    * gating, like a console warning: a missing favicon would otherwise fail every shot of every app.
    */
   readonly failed: number;
+  /**
+   * The HTTP status of the document photographed. `null` when no driver response carried one —
+   * "not seen" never gates, like an uncounted island, and is never reported as a 200.
+   */
+  readonly status: number | null;
+  /** The status asked for with `--expect-status`, or `null` for "any 2xx". */
+  readonly expectedStatus: number | null;
   /** What this verdict cannot see, stated every time — a `0` whose blind spots are named. */
   readonly blind: readonly string[];
 }
 
+const withoutFragment = (url: string): string => {
+  const hash = url.indexOf('#');
+  return hash === -1 ? url : url.slice(0, hash);
+};
+
+/**
+ * The status of the LAST document response at `url` — the last, because a reload or a redirect
+ * back re-requests it and the picture is of the latest. The fragment is dropped: `location.href`
+ * keeps it and no request ever carries one.
+ */
+export function documentStatus(network: readonly NetworkEntry[], url: string): number | null {
+  const target = withoutFragment(url);
+  for (let index = network.length - 1; index >= 0; index -= 1) {
+    const entry = network[index];
+    if (entry === undefined || entry.resourceType !== 'document') continue;
+    if (withoutFragment(entry.url) !== target) continue;
+    if (entry.status !== undefined) return entry.status;
+  }
+  return null;
+}
+
+/** ok for a status: the one expected, or any 2xx when none was. Unseen is not a failure. */
+const statusOk = (status: number | null, expected: number | null): boolean => {
+  if (expected !== null) return status === expected;
+  return status === null || (status >= 200 && status < 300);
+};
+
 /**
  * What a shot is blind to, each naming the mechanism rather than apologising. Constant because
  * these are properties of the browser port, not of a run — and in the artifact because `errors: 0`
@@ -183,7 +227,7 @@ const levelCount = (lines: readonly ConsoleLine[], level: ConsoleLine['level']):
   lines.filter((line) => line.level === level).length;
 
 /**
- * `ok` is four conditions, and every one is something a picture cannot show: nothing on the page
+ * `ok` is five conditions, and every one is something a picture cannot show: nothing on the page
  * logged an error, nothing THREW, no island's `mount()` REJECTED, and the document photographed is
  * the route that was asked for.
  *
@@ -195,16 +239,23 @@ const levelCount = (lines: readonly ConsoleLine[], level: ConsoleLine['level']):
  * an uncounted probe (`null`) out of the verdict — "not counted" is not "none failed".
  * A redirect is a failure of the CAPTURE rather than of the app: an agent that
  * photographs the sign-in page and files "the island did not mount" is the outcome this prevents.
+ * A fifth (`As of 2026-09-26`): the document answered 2xx, or exactly `--expect-status`. A 404
+ * page is clean by every other clause, and `x shot /typo` reported it ok.
  */
 export function buildVerdict(input: ShotInput): ShotVerdict {
   const errors = levelCount(input.console, 'error');
+  const status = documentStatus(input.network, input.finalUrl) ?? input.landedStatus ?? null;
+  const expectedStatus = input.expectStatus ?? null;
   return {
     ...input,
     ok:
       errors === 0 &&
       input.pageErrors.length === 0 &&
       (input.islands?.failed ?? 0) === 0 &&
-      input.requestedUrl === input.finalUrl,
+      input.requestedUrl === input.finalUrl &&
+      statusOk(status, expectedStatus),
+    status,
+    expectedStatus,
     redirected: input.requestedUrl !== input.finalUrl,
     errors,
     warnings: levelCount(input.console, 'warn'),
@@ -241,6 +292,8 @@ export function verdictJson(verdict: ShotVerdict): JsonValue {
     requestedUrl: verdict.requestedUrl,
     finalUrl: verdict.finalUrl,
     redirected: verdict.redirected,
+    status: verdict.status,
+    expectedStatus: verdict.expectedStatus,
     server: verdict.server,
     capturedAt: verdict.capturedAt,
     screenshot: verdict.screenshot,
@@ -301,6 +354,9 @@ export function shotLines(artifacts: ShotArtifacts): readonly string[] {
   const canvas = verdict.canvas;
   return [
     msg(`cli.shot.server.${verdict.server}`, { url: verdict.finalUrl }),
+    verdict.status === null
+      ? msg('cli.shot.documentUnknown')
+      : msg('cli.shot.document', { status: verdict.status }),
     canvas === null
       ? msg('cli.shot.canvasUnreadable', { bytes: verdict.bytes.byteLength })
       : msg('cli.shot.canvas', { width: canvas.width, height: canvas.height }),
@@ -338,6 +394,13 @@ export const shotSummary = (verdict: ShotVerdict): string => {
   if (verdict.redirected) {
     return msg('cli.shot.redirected', { route: verdict.route, url: verdict.finalUrl });
   }
+  if (!statusOk(verdict.status, verdict.expectedStatus)) {
+    return msg('cli.shot.status', {
+      route: verdict.route,
+      status: verdict.status ?? 'unseen',
+      expected: verdict.expectedStatus ?? '2xx',
+    });
+  }
   // Ahead of the console count, because a throw is the more severe fact AND the quieter one: an
   // island that died can log nothing at all, so `errors` would report a clean page.
   if (verdict.pageErrors.length > 0) {

package/src/sw-artifacts.ts

@@ -23,10 +23,13 @@ export const SW_SCOPE = '/';
  */
 export const SW_REGISTER_PATH = '/x-sw-register.js';
 
+/** How long a returning tab waits between two `sw.js` update checks — five minutes. */
+export const SW_UPDATE_INTERVAL_MS = 300_000;
+
 export interface ServiceWorkerArtifacts {
   /** `sw.js`, deterministic for identical input. */
   readonly source: string;
-  /** `x-sw-register.js`, the four lines that install it. */
+  /** `x-sw-register.js`, the lines that install it and look for its successor. */
   readonly register: string;
   /** The `<script src>` tag, appended to `PwaArtifacts.head` by every surface that serves it. */
   readonly head: string;
@@ -133,25 +136,42 @@ const staticAssets = (
     .sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
 
 /**
- * Four lines, and every one of them earns it. `load` because registration competes with the page's
- * own first paint for the same network. `scope: '/'` stated rather than inferred, so a change to
- * where the file is served is a build-time refusal (`assertScope`) instead of a worker that
- * silently controls a subdirectory. The `catch` because a registration that throws in a browser
- * with service workers disabled — an incognito profile, an enterprise policy — must not take an
- * otherwise working page down with it.
+ * The registration, and every line of it earns its bytes. `load` because registration competes with
+ * the page's own first paint for the same network. `scope: '/'` stated rather than inferred, so a
+ * change to where the file is served is a build-time refusal (`assertScope`) instead of a worker
+ * that silently controls a subdirectory. The `catch` because a registration that throws in a
+ * browser with service workers disabled — an incognito profile, an enterprise policy — must not
+ * take an otherwise working page down with it.
+ *
+ * `registration.update()` when a hidden tab comes back, at most once per `SW_UPDATE_INTERVAL_MS`
+ * (22.3.2). A browser checks for a new `sw.js` on a NAVIGATION; a tab left open for days makes
+ * none, so the new worker was found only on the click that was already answered by the old one. The
+ * throttle keeps an alt-tabbing reader from re-downloading the worker on every focus, and the
+ * swallowed rejection is the offline case. It never posts `skip-waiting` and never reloads: the
+ * worker skips waiting itself (`@ultimat3/pwa`'s install block), and a reload under a reader who is
+ * typing is the one thing an update must not do — the next navigation gets the new HTML.
  *
  * EXPORTED because a static export has to put these bytes on disk BEFORE it renders, not after.
  * The file is named by every document and weighed by `measureDocumentJs`, and it used to be
  * written last, beside `sw.js` — so the measurement read a file that did not exist yet on a clean
  * output directory, and the PREVIOUS build's copy on a reused one. `sw.js` still comes last, for
  * the reason its own comment gives (its precache manifest is built from the rendered documents'
- * content hashes); this half depends on nothing but two constants, so it can and must come first.
+ * content hashes); this half depends on nothing but constants, so it can and must come first.
  */
 export const serviceWorkerRegistration = (): string =>
   `if ('serviceWorker' in navigator) {
   addEventListener('load', function () {
     navigator.serviceWorker
       .register(${JSON.stringify(SERVICE_WORKER_PATH)}, { scope: ${JSON.stringify(SW_SCOPE)} })
+      .then(function (registration) {
+        var checked = Date.now();
+        document.addEventListener('visibilitychange', function () {
+          if (document.visibilityState !== 'visible') return;
+          if (Date.now() - checked < ${SW_UPDATE_INTERVAL_MS}) return;
+          checked = Date.now();
+          registration.update().catch(function () {});
+        });
+      })
       .catch(function (error) { console.warn('service worker registration failed', error); });
   });
 }

package/src/sw-routes.ts

@@ -2,8 +2,9 @@
 // Split from the emitter because mounting is HTTP and generation is a build: `prerender.ts` writes
 // both artifacts as files and mounts nothing, and it must not have to import a route table to do it.
 
-import type { CacheHint, Route } from '@ultimat3/http';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
+import { revalidatedResponse } from './revalidated-response';
 import type { ServiceWorkerArtifacts } from './sw-artifacts';
 import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, SW_SCOPE } from './sw-artifacts';
 
@@ -15,9 +16,6 @@ import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, SW_SCOPE } from './sw-artifacts'
  */
 const SW_CACHE: CacheHint = { mode: 'private', maxAgeSeconds: 0 };
 
-/** Content-addressed in neither path, so the register script gets the favicon's hour. */
-const REGISTER_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
-
 /** `/sw.js` and `/x-sw-register.js`, mounted by `x dev` and by the container alike. */
 export const serviceWorkerRoutes = (artifacts: ServiceWorkerArtifacts): readonly Route[] => [
   {
@@ -42,12 +40,11 @@ export const serviceWorkerRoutes = (artifacts: ServiceWorkerArtifacts): readonly
     method: 'GET',
     path: SW_REGISTER_PATH,
     meta: { name: 'pwa.serviceWorkerRegister', auth: 'public' },
-    handler: () =>
-      applyCacheHeaders(
-        new Response(artifacts.register, {
-          headers: { 'content-type': 'text/javascript; charset=utf-8' },
-        }),
-        REGISTER_CACHE,
-      ),
+    // Revalidated on every load, never an hour (22.3.2). The URL carries no content hash — it is
+    // named by every document, so hashing it would re-render them all for a four-line script — and
+    // at `max-age=3600` a changed register script reached a returning visitor up to an hour late.
+    // A strong ETag makes the check a 304. Still an EXTERNAL script: see `SW_REGISTER_PATH`.
+    handler: (request: UltimateRequest) =>
+      revalidatedResponse(request, artifacts.register, 'text/javascript; charset=utf-8'),
   },
 ];

package/src/test-workers.ts

@@ -90,6 +90,19 @@ export const defaultWorkers = (
   return Math.max(WORKER_FLOOR, Math.min(byCpu, byMemory, WORKER_CEILING));
 };
 
+/**
+ * The width for a parallel suite that SHARES the machine — `x verify` runs the static steps beside
+ * `live`, `job`, `e2e` and `eval` (`verify-run.ts`), and each of those scans is a CPU-bound process
+ * of its own. `defaultWorkers()`' oversubscription fills a worker's own stalls when nothing else
+ * wants the cores; beside six other processes it only multiplies the contention. Measured on
+ * notificado.co, 8 vCPU (#537): at 1.5x, `errors` went 1.8s alone → 7.9s in the gate and
+ * `boundaries` 2.3s → 9.7s. So: one worker per core, still held to what memory can carry.
+ */
+export const sharedWorkers = (
+  available: number = availableCpus(),
+  freeBytes: number = availableMemory(),
+): number => Math.min(defaultWorkers(available, freeBytes), Math.max(WORKER_FLOOR, available));
+
 /**
  * Which types run across worker processes, and why the other two cannot.
  *

package/src/verify-run.ts

@@ -5,6 +5,7 @@
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
+import { sharedWorkers } from './test-workers';
 import {
   floorRequires,
   readVerifyFloor,
@@ -40,6 +41,10 @@ export async function runVerify(
     await pending;
     pending = undefined;
   };
+  // A parallel suite inside that window shares the cores with the static group, so its DEFAULT
+  // width is one per core (`sharedWorkers`); an explicit `--workers` is the caller's and stands.
+  const shared: VerifyContext =
+    ctx.workers === undefined && beside.length > 0 ? { ...ctx, workers: sharedWorkers() } : ctx;
   for (const step of selected) {
     if (beside.includes(step)) continue;
     if (step.name === SERIAL_SUITES[0]) {
@@ -51,7 +56,8 @@ export async function runVerify(
     } else if (!SERIAL_SUITES.includes(step.name)) {
       await join();
     }
-    byName.set(step.name, await runStep(step, ctx, floor));
+    const inWindow = pending !== undefined && SERIAL_SUITES.includes(step.name);
+    byName.set(step.name, await runStep(step, inWindow ? shared : ctx, floor));
   }
   await join();
   // Reported in the declared order, whatever order the steps finished in: the table, `--json` and