@ultimat3/cli 10.0.0 → 11.1.0

package/src/error-contract.ts

@@ -9,11 +9,12 @@ import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { citedCommandProblem, loadCommandCatalog } from './fix-command';
 import { createHelperResolver } from './fix-imports';
+import { citedPathProblem, FILE_TOKEN_PATTERN } from './fix-path';
 import { scanFixSites } from './fix-scan';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest } from './source-files';
-import type { CodeSite, FixSite } from './ts-scan';
-import { isCodeRegistry, scanBorrowedCodes, scanCodes } from './ts-scan';
+import type { CodeSite, FixSite, UnresolvedCodeSite } from './ts-scan';
+import { isCodeRegistry, scanBorrowedCodes, scanCodeDeclarations, scanCodes } from './ts-scan';
 
 /** Advice, not instruction. The list is the one in `docs/architecture/04-error-contract.md`. */
 export const BANNED_PHRASES: readonly RegExp[] = [
@@ -38,7 +39,9 @@ export const COMMAND_TOKENS: readonly RegExp[] = [
   /(?:^|[\s;|&("'`])x\s+[a-z][a-z-]*/,
   /\b(?:bun|bunx|npm|npx|node|git|docker|kubectl|helm|psql|curl|openssl|biome|tsc)\b/,
   /\b[A-Za-z_$][\w$]*\(/,
-  /[\w.@-]*\/[\w.@-]+\.(?:ts|tsx|js|json|md|toml|yaml|yml|css|scss|sql)\b/,
+  // Built from `fix-path.ts`'s extension list, because the token that makes a fix count as an
+  // instruction is exactly the token `citedPathProblem` then has to resolve.
+  new RegExp(FILE_TOKEN_PATTERN),
   /\b(?:app\.config\.ts|package\.json|tsconfig\.json|bunfig\.toml|\.env(?:\.[\w.-]+)?)\b/,
 ];
 
@@ -67,6 +70,19 @@ const fixFinding = (site: FixSite, problem: string): Finding => ({
   at: `${site.at}:${site.line}`,
 });
 
+/**
+ * Its own code, not `X_ERROR_FIX_INVALID`: that one means the fix is not an instruction, and this
+ * one means it IS one and points at nothing. The repairs are different — rewrite the sentence
+ * versus correct the path — and one code for both would hand two readers the same wrong edit.
+ */
+const pathFinding = (site: FixSite, problem: string): Finding => ({
+  code: 'X_ERROR_FIX_PATH_MISSING',
+  cause: `the fix at ${site.at}:${site.line} ${problem}`,
+  fix: `correct the path in the fix at ${site.at}:${site.line} to one this repo holds, or create the file it names`,
+  docs: ERROR_DOCS_URL,
+  at: `${site.at}:${site.line}`,
+});
+
 /**
  * Every `fix:` an agent can be handed, read out of shipped source and held to BOTH rules: it must
  * be an instruction, and any `x <command>` it cites must be one this build ships.
@@ -110,7 +126,14 @@ export async function checkErrorFixReport(root: string): Promise<ErrorFixReport>
       // resolve, and reading `<value>` as one would be a finding nobody can act on.
       const fix = staticFix(site.fix);
       const problem = fixProblem(site.fix) ?? citedCommandProblem(fix, catalog);
-      if (problem !== undefined) findings.push(fixFinding(site, problem));
+      if (problem !== undefined) {
+        findings.push(fixFinding(site, problem));
+        continue;
+      }
+      // Third rule, and the one nothing resolved: a fix that names a file this repo does not have.
+      // Reported only where the first two hold — a line already being rewritten needs one finding.
+      const missing = await citedPathProblem(fix, root);
+      if (missing !== undefined) findings.push(pathFinding(site, missing));
     }
   }
   return { findings, checked, unreadable };
@@ -236,6 +259,40 @@ export async function collectDeclaredCodes(root: string): Promise<readonly CodeS
   return [...sites.values()].map(([site]) => site).sort((a, b) => a.code.localeCompare(b.code));
 }
 
+/**
+ * A `code:` this scan could not turn into a code. Its own finding rather than a silent skip, which
+ * is the whole of #277: `const STALE = 'X_DOC_PACKAGE_GRAPH_STALE'` and then `code: STALE` is the
+ * DRY thing to write, `scripts/package-map-graph.ts` wrote it, and the code went into no manifest,
+ * demanded no row on the reference, was exempt from `bun run gate-codes` and could not be explained
+ * — every reader silent, and every one of them permissive. Resolution closes the same-file case;
+ * this closes the rest, because a scanner that reads only what it likes enforces only what it sees.
+ */
+const unresolvedCodeFinding = (site: UnresolvedCodeSite): Finding => ({
+  code: 'X_ERROR_CODE_UNRESOLVED',
+  cause: `the code at ${site.at}:${site.line} is the name ${site.name}, and no module-scope const in that file gives it a value — so the manifest, the reference page and "x errors explain" are all blind to whatever code it holds`,
+  fix: `write the X_* code as a string literal at ${site.at}:${site.line}, or declare it as a module-scope const in that same file`,
+  docs: ERROR_DOCS_URL,
+  at: `${site.at}:${site.line}`,
+});
+
+/**
+ * The other half of `collectDeclaredCodes`, on its own walk rather than folded into that one: this
+ * asks whether a file's codes are READABLE, and the collector's callers — `x manifest`, the gate's
+ * `errors` step, `bun run gate-codes` — want the codes and not the findings. It runs wherever
+ * source does, with no reference page to check against, which is why it is not a host check.
+ */
+export async function checkErrorCodeResolution(root: string): Promise<readonly Finding[]> {
+  const findings: Finding[] = [];
+  for await (const source of eachSourceFile(root)) {
+    if (isTest(source) || isGenerated(source)) continue;
+    const text = await Bun.file(join(root, source)).text();
+    for (const site of scanCodeDeclarations(text, source).unresolved) {
+      findings.push(unresolvedCodeFinding(site));
+    }
+  }
+  return findings;
+}
+
 /**
  * Every `X_*` code shipped source declares must appear on the repo's error reference. The page is
  * the host repo's to name — a framework monorepo publishes one, a generated app does not — which

package/src/error-pages.ts

@@ -0,0 +1,79 @@
+// The app's own error page, which only a process with a disk can find: `@ultimat3/http` renders the
+// framework's and declares the seam, this file is the half that reads a file. Rails' `public/404.html`,
+// one directory further in — `apps/web/site/` is already where an app's public files live, which is
+// where `favicon.ico` is overridden too.
+
+// why: Bun exposes no path-join primitive, and the source path is app-root-relative — the same
+// necessity `favicon.ts` records for `FAVICON_SOURCE`.
+import { join } from 'node:path';
+import { renderErrorPage } from '@ultimat3/http';
+import { currentLocale } from '@ultimat3/i18n';
+
+/**
+ * One file per status, named by the status, and NO generic `error.html` beside it: a second rung
+ * would need a precedence rule, and a `{{status}}` slot would be a template language the framework
+ * does not otherwise have. An app that wants one page for three statuses writes three files.
+ */
+export const ERROR_PAGE_DIR = 'apps/web/site/errors';
+
+/** What `x verify`, a `fix:` and this reader all name — never spelled twice. */
+export const errorPageSource = (status: number): string =>
+  `${ERROR_PAGE_DIR}/${String(status)}.html`;
+
+/**
+ * What a static host serves for a path that matches no file. `404.html` at the export root is the
+ * convention S3, Cloudflare Pages, Netlify and nginx already look for, so the artifact needs no
+ * configuration to answer the way the served process does.
+ */
+export const STATIC_ERROR_PAGE = '404.html';
+
+/** A status a `Response` can carry. A number outside it never becomes a path. */
+const isStatus = (status: number): boolean =>
+  Number.isInteger(status) && status >= 100 && status <= 599;
+
+/**
+ * The app's page for one status, or `undefined`.
+ *
+ * Read per REQUEST, never cached at boot, for `favicon.ts`'s reason: `x dev` is a running process
+ * an author drops a file into, and a reader that captured "there was none" at startup would keep
+ * answering the framework's page until the server was restarted.
+ */
+export async function errorPageOverride(root: string, status: number): Promise<string | undefined> {
+  if (!isStatus(status)) return undefined;
+  const file = Bun.file(join(root, errorPageSource(status)));
+  return (await file.exists()) ? file.text() : undefined;
+}
+
+/**
+ * `ServerHooks.errorPage`, bound to one app root. Installed by `startWeb` so `x dev` and the
+ * container cannot answer a browser differently — the rule `assetRoutes` already holds for
+ * `/favicon.ico`.
+ */
+export const errorPageHook =
+  (root: string) =>
+  (status: number): Promise<string | undefined> =>
+    errorPageOverride(root, status);
+
+/**
+ * The document that goes into a static export: the app's file if it has one, the framework's page
+ * otherwise. Its own function because the export has no process to ask, exactly as `faviconBytes`
+ * is — a second rule for which page a static build carries would be an artifact that disagrees
+ * with the server it was built from.
+ *
+ * No request id and no pathname: nothing about this file is per-request, and the renderer omits
+ * both rather than inventing them.
+ */
+export async function errorPageDocument(root: string, status: number): Promise<string> {
+  const own = await errorPageOverride(root, status);
+  return (
+    own ??
+    renderErrorPage({
+      status,
+      // What the served 404 carries, so the artifact and the process name one code.
+      code: 'X_ROUTE_NOT_FOUND',
+      // The app's default, resolved after `loadApp` registered its catalogs — a build has no
+      // request to negotiate against.
+      locale: currentLocale(),
+    })
+  );
+}

package/src/errors.ts

@@ -2,6 +2,7 @@
 // that resolves it — the codes themselves, their titles and their registration are `./error-codes`,
 // so a package importing a class does not pull the table and vice versa.
 import { UltimateError } from '@ultimat3/core';
+import { quoteArg } from './shell-quote';
 
 /** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */
 export class UnknownCommandError extends UltimateError {
@@ -47,6 +48,30 @@ export class MissingPositionalError extends UltimateError {
   }
 }
 
+/**
+ * `x new /srv/apps/shop` — a PATH where a NAME goes.
+ *
+ * `names()` slugifies whatever it is given, so the separators became hyphens and the whole path
+ * turned into ONE directory inside the cwd: `x new /tmp/probe/vision` wrote `tmp-probe-vision`
+ * into the current directory and `git init`-ed it there. Nothing failed, and the app the caller
+ * asked for did not exist.
+ *
+ * `--dir` is the flag that takes a path, so the two are one flag apart and the fix is the
+ * invocation the caller meant — built from what they typed, never a placeholder.
+ */
+export class AppNameIsPathError extends UltimateError {
+  constructor(input: { name: string; parent: string; base: string; invocation?: string }) {
+    // The invocation the caller typed, not the literal `x new`: the same command is the whole of
+    // `bunx create-ultimate`, which runs before `x` is installed.
+    const invocation = input.invocation ?? 'x new';
+    super({
+      code: 'X_CLI_BAD_FLAG',
+      cause: `"${invocation}" takes a NAME and got the path "${input.name}" — it would be slugified into one directory name`,
+      fix: `${invocation} ${quoteArg(input.base)} --dir ${quoteArg(input.parent)}`,
+    });
+  }
+}
+
 /**
  * A command that declares subcommands, invoked with none and declaring no `defaultSubcommand`.
  *

package/src/favicon.ts

@@ -0,0 +1,113 @@
+// `/favicon.ico`, which every browser requests unprompted and no Ultimate app answered: the
+// scaffold wrote no file and neither served surface mounted a route, so a permanent 404 sat in the
+// console of every app the framework produces. The app's own file wins; the framework answers when
+// there is none, so an app inherits a clean console rather than a file it has to remember to add.
+
+// why: Bun exposes no path-join primitive, and `FAVICON_SOURCE` is app-root-relative, so resolving
+// it against the root is string work no `Bun.file` overload does — the same necessity
+// `dev-assets.ts` records for `ICON_SOURCE`.
+import { join } from 'node:path';
+import { createRaster, encodeImage } from '@ultimat3/core';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders } from '@ultimat3/http';
+
+/** What a browser asks for with no `<link rel="icon">` to tell it otherwise. */
+export const FAVICON_PATH = '/favicon.ico';
+
+/**
+ * The one file an app overrides it with — beside `ICON_SOURCE`, in the same directory, because
+ * `apps/web/site/` is already where an app's public files live. One path, never a search order: a
+ * mechanism that accepted `favicon.png` too would be two ways to do one thing, and an app whose
+ * icon is not there would have to be told which of them won.
+ */
+export const FAVICON_SOURCE = 'apps/web/site/favicon.ico';
+
+/** 32px, which is what a browser tab and a bookmark bar both ask for. */
+const DEFAULT_SIZE = 32;
+
+/**
+ * Not a colour: one mid-grey LEVEL written to all three channels, exactly as
+ * `templates/scaffold-icon.ts` argues — `@ultimat3/ui` owns the colour roles and `cli -> ui` is a
+ * boundary error, so a placeholder here must claim no brand colour to begin with.
+ */
+const MARK_LEVEL = 128;
+const OPAQUE = 255;
+
+const FAVICON_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
+
+/**
+ * The framework's answer when the app declares none: a solid 32x32 PNG, encoded through
+ * `@ultimat3/core`'s own pipeline rather than shipped as an opaque blob — the same encoder
+ * `x new`'s icon goes through, so there is no second image format in the tree and no base64
+ * constant nobody can verify. Served as `image/png` under an `.ico` URL, which every browser reads
+ * by content type; a real ICO container would be a fourth format for one placeholder.
+ *
+ * Deliberately NOT derived from `ICON_SOURCE`: resizing the app's install icon needs
+ * `@ultimat3/pwa`'s pipeline and would make the answer depend on a file that may be missing, which
+ * is a third rung under a mechanism that has exactly two.
+ */
+export function defaultFavicon(): Uint8Array {
+  const raster = createRaster(DEFAULT_SIZE, DEFAULT_SIZE, 'favicon');
+  const { pixels } = raster;
+  for (let i = 0; i < pixels.length; i += 4) {
+    pixels[i] = MARK_LEVEL;
+    pixels[i + 1] = MARK_LEVEL;
+    pixels[i + 2] = MARK_LEVEL;
+    pixels[i + 3] = OPAQUE;
+  }
+  return encodeImage(raster, 'png');
+}
+
+/** Encoded once per process: the bytes are a pure function of two constants. */
+let builtin: Uint8Array | undefined;
+
+const builtinBytes = (): Uint8Array => {
+  builtin ??= defaultFavicon();
+  return builtin;
+};
+
+const iconResponse = (bytes: Uint8Array, contentType: string): Response =>
+  applyCacheHeaders(
+    // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
+    // `SharedArrayBuffer`, which `Response` does not accept — `dev-assets.ts`'s rule, verbatim.
+    new Response(new Uint8Array(bytes), { headers: { 'content-type': contentType } }),
+    FAVICON_CACHE,
+  );
+
+/** What a surface answers with, and what it says the bytes are. */
+export interface FaviconBytes {
+  readonly bytes: Uint8Array;
+  readonly contentType: string;
+}
+
+/**
+ * Read per REQUEST, never once at boot: `x dev` is a running process an author drops a favicon
+ * into, and a route that captured "there was no file" at startup would keep answering the
+ * placeholder until the server was restarted — the class of dev/prod difference this package's
+ * own header forbids.
+ *
+ * Its own function because the static export has no process to ask: `prerenderSite` writes these
+ * same bytes into the artifact, and a second rule for which favicon a static build carries would
+ * be a build whose tab icon differs from the server's.
+ */
+export async function faviconBytes(root: string): Promise<FaviconBytes> {
+  const own = Bun.file(join(root, FAVICON_SOURCE));
+  if (await own.exists()) return { bytes: await own.bytes(), contentType: 'image/x-icon' };
+  return { bytes: builtinBytes(), contentType: 'image/png' };
+}
+
+export async function faviconResponse(root: string): Promise<Response> {
+  const favicon = await faviconBytes(root);
+  return iconResponse(favicon.bytes, favicon.contentType);
+}
+
+/**
+ * Mounted through `assetRoutes`, so `x dev`, the container and every test that boots either get it
+ * from one place. Public by definition — a browser requests it before anyone has signed in.
+ */
+export const faviconRoute = (root: string): Route => ({
+  method: 'GET',
+  path: FAVICON_PATH,
+  meta: { name: 'assets.favicon', auth: 'public', cache: FAVICON_CACHE, tags: ['assets'] },
+  handler: async (_request: UltimateRequest): Promise<Response> => faviconResponse(root),
+});

package/src/fix-path.ts

@@ -0,0 +1,104 @@
+// The other half of the citation rule: a `fix:` may name a FILE, and nothing resolved it. Only
+// `x <command>` citations were checked (`fix-command.ts`), so a fix telling its reader to open a
+// path that no longer exists — or never did — satisfied every gate the repo has, while a file token
+// is one of the four things that make a fix an instruction at all (`COMMAND_TOKENS`).
+
+// why: Bun exposes no synchronous existence primitive — `Bun.file(p).exists()` is async and answers
+// false for a DIRECTORY, and this rule has to judge both. Delete when Bun ships one.
+import { existsSync } from 'node:fs';
+// why: Bun exposes no path-join or dirname primitive. The same necessity `error-contract.ts`
+// already records for `join`.
+import { dirname, join } from 'node:path';
+
+/**
+ * The extensions a fix line may cite a file by — the SAME set `COMMAND_TOKENS`' file pattern is
+ * built from, exported here so the token that lets a fix count as an instruction and the token this
+ * rule resolves can never drift apart. Two lists would mean a citation that satisfies the first
+ * rule and is invisible to the second, which is the hole this file exists to close.
+ */
+export const CITED_FILE_EXTENSIONS = [
+  'ts',
+  'tsx',
+  'js',
+  'json',
+  'md',
+  'toml',
+  'yaml',
+  'yml',
+  'css',
+  'scss',
+  'sql',
+] as const;
+
+/** `[\w.@-]*\/[\w.@-]+\.(?:ts|…)`, as one source string both rules read. */
+export const FILE_TOKEN_PATTERN = String.raw`[\w.@-]*\/[\w.@-]+\.(?:${CITED_FILE_EXTENSIONS.join('|')})\b`;
+
+/**
+ * A whole path, not the last two segments `FILE_TOKEN_PATTERN` matches: this rule resolves the
+ * citation, so it needs every segment. `*` is in the class because a glob is a citation too.
+ */
+const PATH_CITATION = new RegExp(
+  String.raw`(?:[\w.@*-]+\/)+[\w.@*-]+\.(?:${CITED_FILE_EXTENSIONS.join('|')})\b`,
+  'g',
+);
+
+/** A URL is not a repo path, and `https://ultimate.dev/errors/x.md` is shaped like one. */
+const URL_SPAN = /\b[a-z][\w+.-]*:\/\/\S+/gi;
+
+/**
+ * Whether this repo can judge the citation at all. THREE exclusions, each one a shape that resolves
+ * against something other than the root the gate is running in — reporting any of them would be a
+ * finding nobody can act on:
+ *
+ * - a scoped module specifier (`@ultimat3/ui/global.scss`) resolves through `node_modules`;
+ * - a dot-relative path (`./global.scss`) resolves against the reader's own file, which the fix
+ *   line does not name;
+ * - a path whose PARENT DIRECTORY does not exist here is app-facing by construction — `src/errors.ts`
+ *   means "in the package you are editing", `apps/web/server.ts` and `packages/i18n/catalogs/en.json`
+ *   name directories a generated app has and this repo does not. What is left is the citation this
+ *   root really can answer: a directory that exists, named as holding a file it does not hold.
+ */
+function isJudgeable(token: string, root: string): boolean {
+  if (token.startsWith('@') || token.startsWith('./') || token.startsWith('../')) return false;
+  const star = token.indexOf('*');
+  // A glob's FIXED prefix is what has to exist; the segments a `*` stands for are the answer. Cut
+  // at the separator before the star rather than at the star — `dirname('packages/')` is `.`, and
+  // a glob whose first segment is the wildcard has no prefix to check at all.
+  const cut = star === -1 ? -1 : token.lastIndexOf('/', star);
+  const base = star === -1 ? dirname(token) : token.slice(0, Math.max(cut, 0));
+  return base !== '.' && base !== '' && existsSync(join(root, base));
+}
+
+/** Every path-shaped citation on a fix line that this root can resolve, in the order written. */
+export function pathCitations(fix: string, root: string): readonly string[] {
+  const prose = fix.replaceAll(URL_SPAN, ' ');
+  return [...prose.matchAll(PATH_CITATION)]
+    .map((match) => match[0])
+    .filter((token) => isJudgeable(token, root));
+}
+
+/** A glob matches when at least one file answers it; anything else must exist as written. */
+async function resolves(token: string, root: string): Promise<boolean> {
+  if (!token.includes('*')) return existsSync(join(root, token));
+  for await (const _match of new Bun.Glob(token).scan({ cwd: root, onlyFiles: false })) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * The first path a fix cites that this repo does not have, as one sentence for a `cause:`. One
+ * finding per fix line, never one per token — the same rule `citedCommandProblem` holds to.
+ *
+ * Read off the STATIC form of the fix (the caller blanks `${…}` first): a path assembled at run
+ * time is not a path this can resolve, and guessing at one reports findings nobody can act on.
+ */
+export async function citedPathProblem(fix: string, root: string): Promise<string | undefined> {
+  for (const token of pathCitations(fix, root)) {
+    if (!(await resolves(token, root))) {
+      const kind = token.includes('*') ? 'matches no file' : 'is not a file in this repository';
+      return `cites "${token}", which ${kind}`;
+    }
+  }
+  return undefined;
+}

package/src/hold.ts

@@ -3,7 +3,23 @@
 // before the exit code. Ctrl-C then takes core's own three-phase drain (stop accepting, finish
 // in-flight, close) instead of killing a query mid-round-trip.
 
-import { drain, installSignalHandlers, onShutdown } from '@ultimat3/core';
+import { drain, installSignalHandlers, logger, onShutdown, systemClock } from '@ultimat3/core';
+
+export interface HoldOptions {
+  /**
+   * What to call once the release is done, with `0`. Omit and nothing is called.
+   *
+   * There is exactly one caller: `runRole` in `serve.ts`, which is what `apps/web/server.ts`
+   * awaits — the one entry point with nothing above it to end the process. `bin.ts` ends in
+   * `process.exit(code)`, so `x dev` and `x mcp` need none of this; a container has no such line,
+   * and one non-unref'd interval anywhere in the app then holds an event loop with nothing left to
+   * do until `terminationGracePeriodSeconds` runs out and the kubelet SIGKILLs it.
+   *
+   * A function rather than a boolean because `process.exit` in a library is untestable: this is
+   * the seam the test passes a spy through, and the caller is the one that knows.
+   */
+  readonly exit?: (code: number) => void;
+}
 
 /**
  * Wait for a shutdown, then release what core's lifecycle does not own.
@@ -16,15 +32,29 @@ import { drain, installSignalHandlers, onShutdown } from '@ultimat3/core';
  * `release` runs after the drain completes, so in-flight requests still see the database the
  * 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.
  */
-export function holdUntilShutdown(name: string, release: () => Promise<void>): () => Promise<void> {
+export function holdUntilShutdown(
+  name: string,
+  release: () => Promise<void>,
+  options: HoldOptions = {},
+): () => Promise<void> {
   const uninstall = installSignalHandlers({ exit: false });
   let unregister = (): void => {};
-  const shuttingDown = new Promise<void>((resolve) => {
+  // 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.
+  const shuttingDown = new Promise<number>((resolve) => {
     unregister = onShutdown(
       `cli:${name}:hold`,
-      () => {
-        resolve();
+      (reason) => {
+        resolve(reason.deadlineAt);
       },
       { phase: 'accept' },
     );
@@ -35,14 +65,50 @@ export function holdUntilShutdown(name: string, release: () => Promise<void>): (
     // Memoised: awaiting a hold twice must not release twice, and `dispatch` is not the only
     // caller a test can be.
     held ??= (async () => {
-      await shuttingDown;
+      const deadlineAt = await shuttingDown;
       // Idempotent in core: this joins the drain already in flight and resolves when its last
       // phase is done. Calling it is what makes `release` the step after the drain, not beside it.
       await drain();
       unregister();
       uninstall();
-      await release();
+      await releaseWithin(name, release, deadlineAt - systemClock.monotonic());
+      options.exit?.(0);
     })();
     return held;
   };
 }
+
+/**
+ * `release()` raced against what is left of the drain's 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);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const abandoned = new Promise<'abandoned'>((resolve) => {
+    timer = setTimeout(() => resolve('abandoned'), budget);
+  });
+  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`,
+      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 {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}

package/src/index.ts

@@ -116,6 +116,7 @@ export {
 export type { ErrorCatalog } from './error-catalog';
 export {
   buildErrorCatalog,
+  CATALOG_OPTIONAL_HOSTS,
   CATALOG_PACKAGES,
   loadErrorCatalog,
   registeredErrorCodes,
@@ -129,6 +130,7 @@ export {
   COMMAND_TOKENS,
   checkErrorCodeDocs,
   checkErrorCodeRegistry,
+  checkErrorCodeResolution,
   checkErrorFixes,
   checkErrorFixReport,
   collectDeclaredCodes,
@@ -167,6 +169,13 @@ export {
 } from './errors';
 export type { ExecOptions, ExecResult, Runner } from './exec';
 export { exec, execOutput } from './exec';
+export {
+  defaultFavicon,
+  FAVICON_PATH,
+  FAVICON_SOURCE,
+  faviconResponse,
+  faviconRoute,
+} from './favicon';
 export type { CitationFault, CitationRules, CommandCatalog, FixCitation } from './fix-command';
 export {
   citationFault,
@@ -177,6 +186,12 @@ export {
 } from './fix-command';
 export type { HelperResolver } from './fix-imports';
 export { candidatePaths, createHelperResolver, scanImports } from './fix-imports';
+export {
+  CITED_FILE_EXTENSIONS,
+  citedPathProblem,
+  FILE_TOKEN_PATTERN,
+  pathCitations,
+} from './fix-path';
 export type { FixHelper, FixScan } from './fix-scan';
 export { scanFixes, scanFixHelpers, scanFixSites } from './fix-scan';
 export type { DeclaredFlag } from './flag-reads';
@@ -269,11 +284,19 @@ export { belongsToType, discoverTests, sampleFiles } from './test-select';
 export type { ReproduceOptions, RunShardsOptions, Shard } from './test-shards';
 export { planShards, reproduceFor, runShards, shardArgs } from './test-shards';
 export { availableCpus, defaultWorkers, WORKER_CEILING } from './test-workers';
-export type { CodeFixSite, CodeSite, FixSite, SourceSite } from './ts-scan';
+export type {
+  CodeFixSite,
+  CodeScan,
+  CodeSite,
+  FixSite,
+  SourceSite,
+  UnresolvedCodeSite,
+} from './ts-scan';
 export {
   isCodeRegistry,
   maskLiterals,
   scanBorrowedCodes,
+  scanCodeDeclarations,
   scanCodeFixSites,
   scanCodes,
   stripComments,