@ultimat3/cli 19.2.0 → 19.3.1

package/src/gitignore.ts

@@ -0,0 +1,145 @@
+// What git ignores, as data. The one reader of a `.gitignore` in this package: `dev-watch.ts` asks
+// it which directories `x dev` must not watch, and `fix-path.ts` asks it which citations name a
+// file this repository never commits. A second reader would be a second answer, and the two would
+// disagree on the first pattern neither author anticipated.
+
+// why: Bun exposes no synchronous file read and no synchronous existence primitive —
+// `Bun.file(p).text()` is async, and the ignore set is rebuilt inside an `fs.watch` callback where
+// an await opens a window for the next event. Delete when Bun ships sync equivalents.
+import { existsSync, readFileSync } from 'node:fs';
+// why: Bun exposes no path-join, dirname or relative primitive. The same necessity `fix-path.ts`
+// already records for `join`.
+import { dirname, join, relative, sep } from 'node:path';
+
+/** One line of a `.gitignore`, read for what it states rather than for what a reader assumes. */
+export interface IgnorePattern {
+  /** The glob, without its leading `/` or trailing `/`. */
+  readonly glob: string;
+  /** Held against the whole path relative to the file's own directory, never the basename. */
+  readonly anchored: boolean;
+  /** A trailing `/`: it matches a directory and never a file of that name. */
+  readonly directoryOnly: boolean;
+  /** A leading `!`: it re-includes what an earlier pattern ignored, at the same level. */
+  readonly negated: boolean;
+}
+
+/** One `.gitignore` file and the directory every one of its patterns is relative to. */
+export interface IgnoreScope {
+  readonly base: string;
+  readonly patterns: readonly IgnorePattern[];
+}
+
+/**
+ * A pattern is ANCHORED when it holds a `/` anywhere but at its end — git's own rule, and the one
+ * a hand-rolled reader gets wrong in both directions: `coverage/` ignores a `coverage` directory at
+ * any depth, while `/coverage/` and a pattern holding an inner slash only ever match where they
+ * are written.
+ */
+export function parseGitignore(text: string): readonly IgnorePattern[] {
+  const patterns: IgnorePattern[] = [];
+  for (const raw of text.split('\n')) {
+    // Trailing whitespace carries no rule unless escaped; a leading `#` is a comment, and `\#` is
+    // a filename that starts with one.
+    const line = raw.replace(/\\?\s+$/, (match) => (match.startsWith('\\') ? match : ''));
+    if (line === '' || line.startsWith('#')) continue;
+    const negated = line.startsWith('!');
+    const body = (negated ? line.slice(1) : line).replace(/^\\(?=[#!])/, '');
+    if (body === '' || body === '/') continue;
+    const directoryOnly = body.endsWith('/');
+    const trimmed = directoryOnly ? body.slice(0, -1) : body;
+    const rooted = trimmed.startsWith('/');
+    const glob = rooted ? trimmed.slice(1) : trimmed;
+    if (glob === '') continue;
+    patterns.push({ glob, anchored: rooted || glob.includes('/'), directoryOnly, negated });
+  }
+  return patterns;
+}
+
+/** The patterns one directory's own `.gitignore` states, or none where it has no such file. */
+export function readIgnoreFile(directory: string): readonly IgnorePattern[] {
+  const file = join(directory, '.gitignore');
+  return existsSync(file) ? parseGitignore(readFileSync(file, 'utf8')) : [];
+}
+
+/**
+ * The `.gitignore` files that govern `root`: its own last, then every ancestor up to and including
+ * the directory holding `.git`. Outermost first, so a nearer file's pattern is read last and wins —
+ * `examples/dummy` carries no ignore file of its own and every rule about it lives in the
+ * repository root's, which is why reading one file made `touch tsconfig.tsbuildinfo` a full reload.
+ */
+export function ignoreScopes(root: string): readonly IgnoreScope[] {
+  const scopes: IgnoreScope[] = [];
+  let directory = root;
+  for (;;) {
+    const patterns = readIgnoreFile(directory);
+    if (patterns.length > 0) scopes.unshift({ base: directory, patterns });
+    if (existsSync(join(directory, '.git'))) break;
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return scopes;
+}
+
+/** Compiled once per pattern: one `x dev` walk asks the same glob of every directory it meets. */
+const globs = new Map<string, Bun.Glob>();
+
+function globFor(pattern: string): Bun.Glob {
+  const known = globs.get(pattern);
+  if (known !== undefined) return known;
+  const glob = new Bun.Glob(pattern);
+  globs.set(pattern, glob);
+  return glob;
+}
+
+/** The path relative to `base`, POSIX-separated, or `undefined` when it is not under it. */
+function relativeUnder(base: string, path: string): string | undefined {
+  const rel = relative(base, path).split(sep).join('/');
+  return rel === '' || rel.startsWith('../') || rel === '..' ? undefined : rel;
+}
+
+function matches(pattern: IgnorePattern, path: string, isDirectory: boolean): boolean {
+  if (pattern.directoryOnly && !isDirectory) return false;
+  const subject = pattern.anchored ? path : (path.split('/').at(-1) ?? path);
+  return globFor(pattern.glob).match(subject);
+}
+
+/** Last match wins, across every scope in order — git's rule, and the reason `!` works at all. */
+function verdictFor(
+  scopes: readonly IgnoreScope[],
+  path: string,
+  isDirectory: boolean,
+): boolean | undefined {
+  let verdict: boolean | undefined;
+  for (const scope of scopes) {
+    const rel = relativeUnder(scope.base, path);
+    if (rel === undefined) continue;
+    for (const pattern of scope.patterns) {
+      if (matches(pattern, rel, isDirectory)) verdict = !pattern.negated;
+    }
+  }
+  return verdict;
+}
+
+/**
+ * Whether git would ignore this absolute path. Every ancestor between the outermost scope and the
+ * path is judged as a DIRECTORY first: an ignored directory takes everything under it, which is how
+ * `coverage/` reaches `coverage/lcov.info` and the only reason a walk may prune at all.
+ */
+export function isGitIgnored(
+  scopes: readonly IgnoreScope[],
+  path: string,
+  isDirectory: boolean,
+): boolean {
+  const outermost = scopes[0];
+  if (outermost === undefined) return false;
+  const rel = relativeUnder(outermost.base, path);
+  if (rel === undefined) return false;
+  const segments = rel.split('/');
+  for (let depth = 0; depth < segments.length; depth += 1) {
+    const prefix = join(outermost.base, ...segments.slice(0, depth + 1));
+    const last = depth === segments.length - 1;
+    if (verdictFor(scopes, prefix, last ? isDirectory : true) === true) return true;
+  }
+  return false;
+}

package/src/hold.ts

@@ -33,12 +33,15 @@ export interface HoldOptions {
  * handler opened them against. It is the resources core never learned about: the embedded
  * Postgres, the worker, the file watcher.
  *
- * It runs INSIDE the drain's own deadline, and that is not a detail. `drain()` ABANDONS a hook
- * that overruns `ShutdownReason.deadlineAt` — the process is meant to exit without it — and
- * `release` here re-enters the very same teardown one call later: `app.stop()` ->
- * `startRoles().stop()` -> `worker.stop()`, memoised in the package that owns it, so awaiting it
- * is awaiting the promise the drain just walked away from. Unbounded, that hangs forever and the
- * deadline buys nothing.
+ * It is BOUNDED, and that is not a detail. `drain()` ABANDONS a hook that overruns
+ * `ShutdownReason.deadlineAt` — the process is meant to exit without it — and `release` here
+ * re-enters the very same teardown one call later: `app.stop()` -> `startRoles().stop()` ->
+ * `worker.stop()`, memoised in the package that owns it, so awaiting it is awaiting the promise
+ * the drain just walked away from. Unbounded, that hangs forever and the deadline buys nothing.
+ *
+ * The bound is what is LEFT of the drain's budget, under a floor of `MIN_RELEASE_MS` — see there
+ * for why the remainder alone answered `0` on every busy pod and abandoned the teardown before it
+ * closed anything.
  */
 export function holdUntilShutdown(
   name: string,
@@ -48,8 +51,8 @@ export function holdUntilShutdown(
   const uninstall = installSignalHandlers({ exit: false });
   let unregister = (): void => {};
   // The hook's own `reason`, not a stopwatch of ours: `deadlineAt` is the instant core computed
-  // when the drain began, on the same real monotonic clock, so this budget IS the drain's budget
-  // rather than a second one that happens to be the same length.
+  // when the drain began, on the same real monotonic clock, so what is left of the drain's budget
+  // is read off the drain's own number and never off a second one of the same length.
   const shuttingDown = new Promise<number>((resolve) => {
     unregister = onShutdown(
       `cli:${name}:hold`,
@@ -71,7 +74,7 @@ export function holdUntilShutdown(
       await drain();
       unregister();
       uninstall();
-      await releaseWithin(name, release, deadlineAt - systemClock.monotonic());
+      await releaseWithin(name, release, releaseBudgetMs(deadlineAt - systemClock.monotonic()));
       options.exit?.(0);
     })();
     return held;
@@ -79,33 +82,63 @@ export function holdUntilShutdown(
 }
 
 /**
- * `release()` raced against what is left of the drain's budget.
+ * The floor under `release`'s budget, and the reason the drain's REMAINDER alone is the wrong one.
+ *
+ * The remainder is what is left of a budget that was spent on something else. A drain that used
+ * all of it — one request over budget is enough, and that is the ordinary shutdown on a busy pod —
+ * hands `release` a NEGATIVE number, `Math.max(0, …)` reads it as `0`, and `setTimeout(resolve, 0)`
+ * wins against any teardown whose first await is real work. Measured at `deadlineMs: 60` with one
+ * `beginWork()` outstanding: the release STARTED and was abandoned 0ms later, so `app.stop()` never
+ * reached the pool close, the NATS close, the cache tiers or the mail driver, and the outbox relay
+ * was abandoned somewhere between `driver.enqueue` and `markPublished` — a duplicate job on the
+ * next boot. The abandonment is not the harmless "exit slightly early" it was written as: it is
+ * every resource the process holds, left to the kernel.
+ *
+ * So `release` gets a budget of its own, floored, never a leftover. 5s, and the arithmetic is
+ * what makes it defensible rather than a feel: `DEFAULT_DEADLINE_MS` is 25s
+ * (`packages/core/src/lifecycle.ts`) and `docker/helm/templates/deployments.yaml` sets
+ * `terminationGracePeriodSeconds: 45`, so a drain that spends everything PLUS a release that
+ * spends everything is 30s — still inside the grace period, so the kubelet never SIGKILLs a
+ * process this floor kept alive. It stays a floor and not a clamp: an app that raised
+ * `deadlineMs` for a slow teardown keeps the bigger number.
+ */
+export const MIN_RELEASE_MS = 5_000;
+
+/**
+ * What `release` really gets. Non-finite is the floor rather than the input, for the reason
+ * `packages/core/src/lifecycle-bounds.test.ts` exists: `Math.max(n, NaN)` is `NaN` and
+ * `setTimeout(fn, NaN)` fires on the next tick, which is this whole defect a second time.
+ */
+export const releaseBudgetMs = (remainingMs: number): number =>
+  Number.isFinite(remainingMs) ? Math.max(MIN_RELEASE_MS, remainingMs) : MIN_RELEASE_MS;
+
+/**
+ * `release()` raced against its own budget.
  *
  * A local race and not core's `settleWithin`, which is internal to `lifecycle-deadline.ts` and not
  * on core's barrel. The semantics are deliberately the same, including the one that matters: a
  * REJECTION still rejects — `dispatch` awaits the hold inside its own `try`, and an embedded
  * database that would not close is a finding on the way out, never a clean exit over it.
- *
- * A budget already spent is `0`, and that abandons immediately by design: past `deadlineAt` the
- * orchestrator is already counting down to SIGKILL, so the honest move is to say so and exit
- * rather than to start a second grace period nobody granted.
  */
 async function releaseWithin(
   name: string,
   release: () => Promise<void>,
   budgetMs: number,
 ): Promise<void> {
-  const budget = Math.max(0, budgetMs);
+  // Screened by `releaseBudgetMs`, which is the one answer to "how long does a teardown get" —
+  // a second `Math.max` here would be a second, quieter one.
   let timer: ReturnType<typeof setTimeout> | undefined;
   const abandoned = new Promise<'abandoned'>((resolve) => {
-    timer = setTimeout(() => resolve('abandoned'), budget);
+    timer = setTimeout(() => resolve('abandoned'), budgetMs);
   });
   try {
     const outcome = await Promise.race([release().then(() => 'released' as const), abandoned]);
     if (outcome === 'released') return;
     logger.warn('X_SHUTDOWN_TIMEOUT', {
       code: 'X_SHUTDOWN_TIMEOUT',
-      cause: `the "${name}" release was still running ${budget}ms after the drain finished and has been ABANDONED — the process exits without it, so anything it held may not be closed`,
+      // Rounded: `deadlineAt - monotonic()` is a float, and `4923.185900000001ms` in a shutdown
+      // log reads as a bug in the number rather than as the budget it is.
+      cause: `the "${name}" release was still running ${Math.round(budgetMs)}ms after the drain finished and has been ABANDONED — the process exits without it, so anything it held may not be closed`,
       fix: 'raise the budget past the slowest teardown — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds',
     });
   } finally {

package/src/index.ts

@@ -68,7 +68,7 @@ export { deployCommand, planDeploy } from './cmd-deploy';
 export type { DevServer, StartDevOptions } from './cmd-dev';
 export { devCommand, startDev } from './cmd-dev';
 export type { DoctorProbe } from './cmd-doctor';
-export { doctorCommand, OFFLINE_FALLBACK, probeFor, runDoctor } from './cmd-doctor';
+export { doctorCommand, ENV_DEVELOPMENT, probeFor, runDoctor } from './cmd-doctor';
 export { ERRORS_SUBCOMMANDS, errorsCommand } from './cmd-errors';
 export { FIX_SUBCOMMANDS, fixCommand } from './cmd-fix';
 export type { GenerateOptions, Generator } from './cmd-generate';

package/src/island-bundle.ts

@@ -12,6 +12,7 @@ import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/
 import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
 import { islandStylesPlugin } from './island-styles';
+import { hasPathSegment } from './path-segments';
 import { solidJsxPlugin } from './solid-loader';
 
 /**
@@ -59,7 +60,7 @@ export interface IslandBundle {
 export async function discoverIslands(root: string): Promise<readonly string[]> {
   const files: string[] = [];
   for await (const absolute of new Bun.Glob(ISLAND_GLOB).scan({ cwd: root, absolute: true })) {
-    if (absolute.includes('node_modules')) continue;
+    if (hasPathSegment(absolute, 'node_modules')) continue;
     files.push(relative(root, absolute).split(sep).join('/'));
   }
   return files.sort();

package/src/island-states-load.ts

@@ -16,6 +16,7 @@ import {
 } from '@ultimat3/testing';
 import { ISLAND_GLOB } from './island-bundle';
 import { IslandStatesFileEmptyError } from './island-shot-errors';
+import { hasPathSegment } from './path-segments';
 
 /**
  * `.island.states.ts`, built from the two constants that own its halves and restated as neither:
@@ -37,7 +38,7 @@ export async function discoverIslandStates(root: string): Promise<readonly strin
   const files: string[] = [];
   const scan = new Bun.Glob(ISLAND_STATES_GLOB).scan({ cwd: root, absolute: true });
   for await (const absolute of scan) {
-    if (absolute.includes('node_modules')) continue;
+    if (hasPathSegment(absolute, 'node_modules')) continue;
     files.push(relative(root, absolute).split(sep).join('/'));
   }
   return files.sort();

package/src/jobs-driver.ts

@@ -24,7 +24,10 @@ export async function withJobDriver(
   const ambient = jobDriver();
   if (ambient !== undefined) return fn(ambient);
   const services = resolveServices(root, ctx.env);
-  const queue = await startQueue(services);
+  // The command's own environment on both halves: `resolveServices` reads DATABASE_URL off it, so
+  // a queue that resolved its standby from `process.env` would talk to a pair the same call had
+  // just decided against.
+  const queue = await startQueue(services, undefined, ctx.env);
   try {
     return await fn(queue.jobs);
   } finally {

package/src/mcp-host.ts

@@ -45,6 +45,7 @@ import { databaseTarget } from './mcp-db-target';
 import { explainErrorCode } from './mcp-errors';
 import { parseBunTest } from './mcp-test-output';
 import { readMigrations } from './migrations';
+import { retryMemo } from './retry-memo';
 
 export interface DevHostInput {
   readonly root: string;
@@ -91,7 +92,11 @@ export interface LazyServices {
  */
 export function lazyServices(input: DevHostInput): LazyServices {
   const services = resolveServices(input.root, input.env);
-  let started: Promise<RunningServices> | undefined;
+  // `retryMemo`, not `??=`: a boot that REJECTED is not an answer to keep. A Postgres that refused
+  // one connection wedged every later tool call in the session with that first error, and the only
+  // way out was restarting the host — `startServices` unwinds everything it started before it
+  // rejects, so there is nothing left over for a second attempt to collide with.
+  const boot = retryMemo(() => startServices(services, input.env));
   let closed = false;
   return {
     services,
@@ -104,14 +109,14 @@ export function lazyServices(input: DevHostInput): LazyServices {
           fix: 'x mcp serve --transport stdio   # keep the host open for the whole session',
         });
       }
-      started ??= startServices(services, input.env);
-      return started;
+      return boot.get();
     },
     async close(): Promise<void> {
       if (closed) return;
       closed = true;
-      // A boot that rejected has nothing to stop, and close() must not throw on the way out.
-      await (await started?.catch(() => undefined))?.stop();
+      // `started()` and never `get()`: closing must not BOOT a database in order to stop one. A
+      // boot that rejected has nothing to stop, and close() must not throw on the way out.
+      await (await boot.started()?.catch(() => undefined))?.stop();
     },
   };
 }
@@ -175,8 +180,13 @@ export async function readOnlyRows(
 function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities {
   const { root, runner } = input;
   // Layer 1 is seven idempotent DDL statements, and `db.query` is a tool an agent calls in a
-  // loop — resolve the role once per process and reuse the answer, `null` included.
-  let readOnlyRole: Promise<string | null> | undefined;
+  // loop — resolve the role once per process and reuse the answer, `null` included. A FAILED
+  // resolution is not an answer: `??=` kept the rejection, so a statement timeout on the DDL
+  // meant every later `db.query` in the session refused with it instead of trying again.
+  //
+  // It asks `lazy.running()` for the client rather than closing over one: this runs before any
+  // boot has happened, and the boot is memoised, so it is the same connection `runQuery` uses.
+  const readOnlyRole = retryMemo(async () => ensureReadOnlyRole((await lazy.running()).db));
 
   return {
     database: databaseTarget(lazy.services, input.env),
@@ -185,8 +195,7 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
       const { db } = await lazy.running();
       // A managed Postgres may refuse CREATE ROLE; `ensureReadOnlyRole` answers null and the
       // layer is reported absent in `guards` rather than quietly assumed present.
-      readOnlyRole ??= ensureReadOnlyRole(db);
-      return readOnlyRows(db, sql, limits, await readOnlyRole);
+      return readOnlyRows(db, sql, limits, await readOnlyRole.get());
     },
 
     async runMigrations(branch: string, dryRun: boolean) {

package/src/parse.ts

@@ -88,6 +88,15 @@ export interface CommandSpec {
    * that declared it and forgot the call ran outside an app with no refusal.
    */
   readonly requiresApp?: boolean;
+  /**
+   * The command hands everything after a bare `--` to another tool, so `ParsedArgs.passthrough`
+   * has a READER. Declared, because it did not until 2026-09 and nothing read it anywhere:
+   * `x test unit -- --coverage --bail` parsed both flags, carried them the whole way and dropped
+   * them, and every other command did the same in the same silence. A command that declares this
+   * forwards them; one that does not refuses the `--` (`X_CLI_BAD_FLAG`), which is the only way an
+   * argument that changes nothing becomes visible to the caller who typed it.
+   */
+  readonly passthrough?: true;
 }
 
 export interface ParsedArgs {
@@ -170,6 +179,14 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
   }
 
   const spec = resolveCommand(first, specs);
+  if (passthrough.length > 0 && spec.passthrough !== true) {
+    throw new BadFlagError({
+      flag: '',
+      command: spec.name,
+      reason: `hands nothing to another tool, so ${passthrough.join(' ')} would be dropped in silence`,
+      fix: `x ${spec.name} --help`,
+    });
+  }
   const flags = defaults(spec);
   const positionals: string[] = [];
   // What argv actually SET, as against what `defaults()` seeded: a default is nobody's request,

package/src/path-segments.ts

@@ -0,0 +1,14 @@
+// One answer to "does this path pass through a directory called X". Six modules asked it with
+// `path.includes('node_modules')`, which is a SUBSTRING match: an app checked out under
+// `~/dev/node_modules-experiments/myapp` answered true for every file it holds, so `loadApp`
+// imported none of them and the app registered nothing at all.
+
+/** Split on either separator: a rule that reads `a/b` and not `a\b` does not exist on Windows. */
+export function pathSegments(path: string): readonly string[] {
+  return path.replaceAll('\\', '/').split('/');
+}
+
+/** Whether any whole segment of `path` is `segment` — never a substring of one. */
+export function hasPathSegment(path: string, segment: string): boolean {
+  return pathSegments(path).includes(segment);
+}

package/src/prerender.ts

@@ -22,7 +22,13 @@ import { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifa
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 import { styleBundle, writeStyles } from './style-bundle';
-import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, serviceWorkerArtifacts } from './sw-artifacts';
+import type { RenderedDocument } from './sw-artifacts';
+import {
+  SERVICE_WORKER_PATH,
+  SW_REGISTER_PATH,
+  serviceWorkerArtifacts,
+  serviceWorkerHead,
+} 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.
@@ -141,6 +147,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const skipped: SkippedRoute[] = [];
   const routes: RouteStats[] = [];
   const unmeasured: UnmeasuredRoute[] = [];
+  // What the loop below rendered, by the path it rendered — the service worker's precache
+  // revisions. A `Map` and not a record, so a route path spelling a prototype member cannot answer
+  // with one; insertion order is never read, because `pwaRoutes` walks the route table and
+  // `buildPrecacheManifest` sorts its own entries by code unit.
+  const documents = new Map<string, RenderedDocument>();
 
   // Before the first document: a page's `data-x-entry` is a built chunk's URL, so the chunks have
   // to exist to be named. Written into `out` too — a static export is served with no process
@@ -174,24 +185,15 @@ 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,
-          styles,
-        });
-  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);
-  }
+  // The registration TAG now, the worker itself after the render loop — the two halves are wanted
+  // at different moments and used to be taken at the same one. Every document below has to name
+  // `/x-sw-register.js`, and the worker's precache manifest is built from the content hash of
+  // those same documents, which do not exist yet: emitted here, every route's revision was the
+  // BUILD ID and every route's byte count was 0, so a deploy of a byte-identical site re-fetched
+  // everything and the precache budget could not count one byte of HTML (`precache.ts`' own
+  // header). `serviceWorkerHead` is the one predicate behind both, so a page can never name a
+  // script the export does not carry.
+  const swHead = pwa === undefined ? undefined : serviceWorkerHead(pwa);
   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
@@ -224,7 +226,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     runWithContext(as, () =>
       routeDocument(entry, data, {
         resolveIsland: (file: string) => islands.resolverFor(file),
-        ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
+        ...(pwa === undefined ? {} : { pwaHead: pwa.head + (swHead ?? '') }),
       }),
     );
   const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
@@ -299,6 +301,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         hash: artifact.hash,
         bytes,
       });
+      // `artifact.hash` is `contentHash(html)` — the same identity that becomes this page's ETag,
+      // so the precache revision and the HTTP validator can never disagree about one document.
+      // Keyed by the FILLED path, which for a non-dynamic route is the declared one; a dynamic
+      // route is not precached as a single URL anyway (`buildPrecacheManifest` skips it).
+      documents.set(artifact.path, { revision: artifact.hash, bytes });
       // Measured from the document that was just written, so the `budgets` step compares a
       // declared budget against bytes that exist on disk rather than against a graph's estimate.
       const measured = await measureDocumentJs(artifact.html, options.out);
@@ -312,6 +319,25 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     }
     if (heaviest !== undefined) routes.push(heaviest);
   }
+  // The worker, LAST: every document it precaches has now been rendered, hashed and weighed. A
+  // static host runs no route table, so both files go into the artifact — a
+  // `<script src="/x-sw-register.js">` in every document is a 404 otherwise, which is the same
+  // promise `favicon.ico` and the icons above keep.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands,
+          styles,
+          documents,
+        });
+  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);
+  }
   const stats = await writeBuildStats(options.root, { routes });
   // Written LAST and by the same call that writes the stats, so an app whose `prerender.ts` does
   // not reach `prerenderSite` produces neither — and `x verify`'s `budgets` step already reds that

package/src/retry-memo.ts

@@ -0,0 +1,37 @@
+// One in-flight attempt, shared — and a FAILED one not kept. `started ??= boot()` caches the
+// rejection with the value, so a Postgres that refused a connection once answered every later
+// call in the session with that same error and no retry was possible short of restarting the host.
+
+/**
+ * A lazily made attempt that may be made again.
+ *
+ * `started()` is the half `??=` has no spelling for: it answers the attempt already in flight or
+ * already made, and `undefined` when nobody has asked yet — so a `close()` can stop what was
+ * booted without BOOTING one in order to stop it.
+ */
+export interface RetryMemo<T> {
+  get(): Promise<T>;
+  started(): Promise<T> | undefined;
+}
+
+/**
+ * `start` runs at most once per SUCCESS. `@ultimat3/db`'s `createPgliteClient` states the rule this
+ * generalises — "a failed boot must not be cached" — and the clearing handler is attached at
+ * creation for the reason that matters: it therefore runs ahead of every caller's own `await`
+ * continuation, so by the time anyone sees the rejection the slot is already empty and the next
+ * call really does start a new attempt. Cleared inside the caller's `catch` instead, there is a
+ * window in which a second call is handed the dead promise.
+ */
+export function retryMemo<T>(start: () => Promise<T>): RetryMemo<T> {
+  let attempt: Promise<T> | undefined;
+  return {
+    get(): Promise<T> {
+      attempt ??= start().catch((error: unknown) => {
+        attempt = undefined;
+        throw error;
+      });
+      return attempt;
+    },
+    started: (): Promise<T> | undefined => attempt,
+  };
+}

package/src/serve.ts

@@ -195,7 +195,11 @@ export type StartedApp = ServedApp | MigratedApp;
  * is what fails on it.
  */
 export async function runMigrations(options: ServeOptions): Promise<MigratedApp> {
-  const queue = await startQueue(resolveServices(options.root, options.env), options.runtime);
+  const queue = await startQueue(
+    resolveServices(options.root, options.env),
+    options.runtime,
+    options.env,
+  );
   try {
     const migrations = await readMigrations(options.root);
     const report = await migrate({

package/src/source-files.ts

@@ -2,6 +2,8 @@
 // and an app. One list for every step that walks source, because two steps scanning different sets
 // means a finding one of them can never see.
 
+import { hasPathSegment } from './path-segments';
+
 export const SOURCE_GLOBS = [
   'packages/*/src/**/*.{ts,tsx}',
   // Three packages carry an `e2e` directory beside `src`. It is shipped source by every rule that
@@ -21,7 +23,7 @@ export const SOURCE_GLOBS = [
  * root. `dist/` is build output: the sources that produced it are already in the set.
  */
 export const isVendored = (path: string): boolean =>
-  path.includes('node_modules') || path.includes('/dist/') || path.startsWith('dist/');
+  hasPathSegment(path, 'node_modules') || hasPathSegment(path, 'dist');
 
 /** Emitted declarations, not authored source — a rule about authored code cannot apply to them. */
 export const isGenerated = (path: string): boolean => path.endsWith('.d.ts');