@ultimat3/cli 19.2.0 → 19.3.2

package/CLAUDE.md

@@ -8,12 +8,13 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | stdout | `write-line.ts`'s `writeLine` — synchronous fd 1, never `process.stdout.write`, which truncates at the 64KB pipe buffer when `process.exit` follows. Exported, because `create-ultimate`'s entry point needs the same one |
 | stderr | `write-line.ts`'s `writeErrorLine` — the same loop on fd 2, for a line that is not the command's answer. A `CommandResult` declaring `stream: 'stderr'` is routed there by `dispatch.ts`'s `sinkFor`, and `x mcp serve --transport stdio` is the one case: its fd 1 carries JSON-RPC frames, so the `✓ mcp stdio serving 13 tools` line rendered after the loop was a malformed frame. Neither renderer carries `stream`, exactly like `hold` |
 | Boot logs under `--json` | `dispatch.ts` calls core's `setLogStream('stderr')` when `args.json` is set, once, for all thirty commands. `x db migrate --json` printed the boot logger's `ultimate migrate applied` and then the command's own object, so `json.load` raised on the second document. A server's stdout stays its log stream; this is the CLI process only |
-| Test execution | `test-shards.ts`'s `testArgs` — ONE `bun test --parallel=N`, never N processes this repo packs itself. It did pack them, largest-first greedy over file SIZE, and the packer was deleted for buying **nothing**: four interleaved runs each on the 1296-file unit corpus gave 58.2/60.0/65.0/66.5s hand-packed against 54.5/57.8/61.7/64.5s under `--parallel=8`, within noise, because both are work-bound — 436.7s of file time is a 54.6s floor on 8 workers and the slowest single file is 20.5s. A greedy pack of 1296 small items lands near-optimal by accident. `--timings` is refused on the same evidence (#342). `--parallel` implies `--isolate`, so the per-file module registry is unchanged, and the per-worker database is too: `@ultimat3/testing`'s `workerId` already read `BUN_TEST_WORKER_ID`, which Bun sets 1..N. `ULTIMATE_TEST_WORKER` is set only for a single-shard `x test --worker I` rerun, which is one process |
+| Test execution | `test-shards.ts`'s `testArgs` — ONE `bun test --parallel=N` per PASS (`test-passes.ts`; a selection mixing `live`/`e2e` files with the rest is two passes, the serial one at `--parallel=1`), never N processes this repo packs itself. It did pack them, largest-first greedy over file SIZE, and the packer was deleted for buying **nothing**: four interleaved runs each on the 1296-file unit corpus gave 58.2/60.0/65.0/66.5s hand-packed against 54.5/57.8/61.7/64.5s under `--parallel=8`, within noise, because both are work-bound — 436.7s of file time is a 54.6s floor on 8 workers and the slowest single file is 20.5s. A greedy pack of 1296 small items lands near-optimal by accident. `--timings` is refused on the same evidence (#342). `--parallel` implies `--isolate`, so the per-file module registry is unchanged, and the per-worker database is too: `@ultimat3/testing`'s `workerId` already read `BUN_TEST_WORKER_ID`, which Bun sets 1..N. `ULTIMATE_TEST_WORKER` is set only for a single-shard `x test --worker I` rerun, which is one process |
 | Numeric flags | `flag-number.ts` — one reader for `--port` / `--workers` / `--shard`. A bare `Number.parseInt` accepts `4abc` and answers `NaN`, which turned three checks into ones that cannot fail |
 | Shell quoting | `shell-quote.ts`'s `quoteArg` — every value the CLI pastes into a `fix:` or a reproduce line, `exec.ts`'s missing-program refusal and `test-shards.ts`'s reproduce command both. A name holding a space or a `;` interpolated bare is an instruction that runs something else |
 | Missing positionals | `MissingPositionalError`, never `BadFlagError` (names a flag that does not exist) and never `UnknownCommandError` (says a known command form is not one). Its `example` is a REAL invocation — `x g route <name>` in a shell is a redirect |
 | Bare subcommands | `CommandSpec.defaultSubcommand`, **declared**. The parser answered `subcommands[0]` until 1.2.0, so `x db` ran `gen` — the migration GENERATOR — because it sorted first, and `x mcp` started a server. A command with no defensible default declares none and `MissingSubcommandError` refuses the bare form; `parse.test.ts` pins the set at exactly `db` and `mcp`. Its fix is `x help <command>`. Both forms answer now: `--help` is read off the flag loop and `readSubcommand` is SKIPPED when it is set, so `x db --help`, `x mcp --help` and `x pr --help` print usage instead of exiting 1 with this same refusal — which is what they did on every command taking a subcommand until 2026-08 (`parse.test.ts` pins it across the shipped registry) |
 | Closed flag values | a flag whose values are a closed set is READ through a function that refuses the rest — `cmd-build.ts`'s `readTarget`, `cmd-deploy.ts`'s `readMethod`, `cmd-routes.ts`'s `readSurfaceFilter`, `cmd-mcp.ts`'s `isTransport`. `=== 'helm' ? 'helm' : 'compose'` made `x deploy --method helmm` a COMPOSE deploy reporting `method: "compose"`, and `--surface App` reported `0 routes` and exit 0 — a typo and an empty table rendering identically. The set is the framework's own where one exists (`SURFACES` from `@ultimat3/render`), never a list restated here |
+| Passthrough | `CommandSpec.passthrough`, **declared**. `ParsedArgs.passthrough` says "handed to the underlying tool verbatim" and had no reader anywhere, so `x test unit -- --coverage --bail` parsed both flags and dropped both — a run that measured nothing reporting what a coverage run reports. `x test` forwards them to `bun test` (before the file list) and prints them back in its reproduce line; every other command refuses a non-empty `--` tail with `X_CLI_BAD_FLAG` rather than dropping it. `help`/`version` short-circuit ahead of the command and are exempt |
 | App root | `CommandSpec.requiresApp`, **enforced by `dispatch.ts`** before `target.run` — the field's doc said so for 17 commands and nothing read it, so the promise was kept only by each command remembering to call `requireAppRoot` itself. Those 17 calls stay (they hand the command its root, and name subcommands the dispatcher cannot see), but the DECLARATION is what decides, ahead of any check a command makes about its own arguments; `--help` is exempt, because `target` is the help command by then |
 | Result helpers | `command.ts`'s `ok()` / `failed()` write `ok` **after** the `extra` spread: the function's name is the verdict and nothing a caller passes can overturn it. Spread last, `failed('verify', '1 of 20 steps failed', { ok: true })` answered `ok: true` and `exitCodeFor` exited **0** on it — a green CI over a red command (`command.test.ts`) |
 | I/O | only `dispatch.ts` renders or exits; commands return `CommandResult` |
@@ -81,7 +82,7 @@ source only: a test file's import is not judged, because `packages/*` here decla
 read is its own finding rather than a silent skip — a skipped workspace is a hiding place for the
 very edge the rule is looking for.
 
-`app-permissions.ts` is the `policy` step, and it is the twentieth. Two references in the whole
+`app-permissions.ts` is the `policy` step. Two references in the whole
 framework are bare strings nothing checks — `RoleDef.grants` and `RouteGuard.permission` — while
 `can()` calls `assertPermission` and throws `X_PERMISSION_UNKNOWN` on the first request that
 reaches the route. So `x new` shipped an app that granted `dashboard:read`, required it on
@@ -108,9 +109,19 @@ halves are `undefined`/empty with no replica configured, and an EMBEDDED binding
 PGlite has no standby. Not `@ultimat3/http`'s pipeline, which would make the HTTP tier know what a
 database is; the boot is the only tier that may know about a request and a pool.
 
+`flag-number.ts`'s `portPairAfter` is the one suggestion for a caller that binds a PAIR, and
+`neighbouringPort` is for a caller that binds one port. `x dev` takes `PORT` **and** `PORT + 1`, so
+the neighbour of a taken web port is the sync port — both `x doctor`'s `X_PORT_IN_USE` and
+`dev-sync.ts`'s handed back the port the finding had just named as taken, each under a test that
+said it ended the failure. It answers downward at the top of the range for the reason
+`neighbouringPort` does, and one further: the suggestion's own neighbour has to exist, or
+`syncPortFor` refuses it with `X_PORT_INVALID`.
+
 `port-probe.ts` is the one `portFree`, because two commands ask it and must not disagree:
-`x doctor` reports it as a finding for BOTH ports `x dev` binds — the web port and the `PORT + 1`
-sync port, each labelled with the role that wants it — and `startSync` asks it after a failed
+`x doctor` reports it as a finding for BOTH ports `x dev` binds — the web port and the sync port,
+which it derives with `syncPortFor` (the boot's own rule: a `--port` at the top of the range has no
+sync port at all, so the probe reports `X_PORT_INVALID` instead of probing the port BELOW it, which
+is what `neighbouringPort` answered there) — each labelled with the role that wants it — and `startSync` asks it after a failed
 `listenSyncNode` so a taken neighbour is `X_PORT_IN_USE` rather than `X_CLI_UNEXPECTED` over
 `Bun.serve`'s own English rendered into a `cause:`. It is ASKED, never read off the caught value,
 which is what `scripts/catch-render.ts` refuses; anything else the listener failed on is re-thrown
@@ -119,6 +130,36 @@ untouched. `x doctor` also probes `DATABASE_URL` with a real `select 1` through
 credentials, which is the case an operator most needs told about — and reports `X_DB_UNAVAILABLE`
 with that package's own two-branch fix. An EMBEDDED binding is not probed: that lock is `x dev`'s.
 
+`doctor-offline.ts` is `x doctor`'s offline-fallback check, and it is the shape of a diagnostic
+that could not be closed. The probe was the literal `apps/web/app/offline.tsx` — a filename
+`assertRouteFilename` REFUSES (`X_ROUTE_FILE_INVALID`: the directory is the URL, so a page is
+`page.tsx`) — while `x new` scaffolds `apps/web/site/offline/page.tsx` and the finding's own `fix:`
+writes `apps/web/app/offline/page.tsx`. Three different paths, so every app the framework has ever
+produced reported `X_PWA_NO_OFFLINE_FALLBACK` from its first `x doctor`, running the fix changed
+nothing, and the app that HAD the route was told it did not. It now reads the DECLARED
+`pwa.offline.fallback` through `loadPwaArtifacts` and matches it against `describeRoutes()` —
+**`site/` only**, `As of 2026-09`. It accepted `app/` too, on the argument that both surfaces answer
+the same URL; true, and not the question. `SURFACE_SPECS` allows `app/` exactly `stream | ssr`, only
+a `static` route is prerendered, and `serviceWorkerArtifacts` precaches a rendered DOCUMENT
+(`documents.get(fallback)`) — so an `app/` fallback has nothing to precache and the offline
+navigation reaches the network it exists to survive without. The check and its own `fix:` disagreed
+about one code. Not closed by this: a `site/` route declaring `render: 'ssr'` is not prerendered
+either, and `NavigableRoute` carries no render mode. An app whose modules will not import is not
+judged at all, which is
+`appEntities`' rule (`schema-drift.ts`) one registry over. The fix is `x g route <name>
+--surface site` only where the fallback is one path segment the generator can really produce: a
+nested path slugifies to a DIFFERENT url, so there it is the config edit instead — a `fix:` that
+runs and leaves the finding where it was is the defect this file exists to end. **`site`, not
+`app`**: the document that answers a lost network has to render with no network, no session and no
+database, which `app/` (`ssr | stream`) cannot promise, and it is the line `@ultimat3/pwa`'s own
+`X_PWA_NO_OFFLINE_FALLBACK` hands out for the same code — two fixes for one code are two answers.
+
+`X_ENV_MISSING`'s fix is the file write, for the same reason. It was `x new --force`, which cannot
+run where the reader is standing: `x new` takes a `<name>` positional (`X_CLI_BAD_FLAG` without
+one) and with one it scaffolds a SECOND app beside the broken one. `cp .env.example
+.env.development` — the committed projection of `envSchema`, which is what `x env example` writes
+and `X_ENV_EXAMPLE_DRIFT` keeps honest.
+
 `i18n-index.ts` is the one writer of an app's `packages/i18n/src/index.ts`, shared by `x g` and
 `x i18n add|sync`. A catalog on disk and a SELECTABLE locale were two different sets: `x i18n add
 fr` wrote the file, exited 0, and left `x verify --only i18n` red with `X_CATALOG_UNREGISTERED`
@@ -406,7 +447,26 @@ cannot be missing from the precache manifest.
 |---|---|
 | `cmd-dev.ts` | mounts `/sw.js` and `/x-sw-register.js`; built ONCE at boot and deliberately not rebuilt on the watcher tick — a worker that changes under a page it already controls is the update path, and re-emitting one per keystroke exercises it on every save |
 | `serve.ts` | the same two routes in the container, from the same call |
-| `prerender.ts` | writes both as FILES into the export — 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 |
+| `prerender.ts` | writes both as FILES into the export — 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. In TWO halves, `As of 2026-09-06`: `serviceWorkerHead(pwa)` before the render loop, because every document has to name the script, and `serviceWorkerArtifacts` AFTER it, because a precache revision is the content hash of a document that does not exist yet |
+
+**A precache revision is the DOCUMENT's content hash, and until 2026-09-06 it was the build id.**
+`pwaRoutes` projected four of `PwaRoute`'s eight fields, so every route entry read
+`{"url":"/","revision":"<buildId>","bytes":0}`: two deploys of a byte-identical site re-fetched
+every precached page, which is the one thing `packages/pwa/src/precache.ts`' own header says must
+never happen, and `DEFAULT_PRECACHE_WARN_BYTES` was a 5 MB budget over a total that could not count
+one byte of HTML. The cause was ORDER — `prerender.ts` emitted the worker before the render loop —
+so the emission moved after it and `ServiceWorkerInput.documents` carries `renderStatic`'s own
+`hash` and byte count per rendered path. `x dev` and `serve.ts` pass none and keep the build id:
+neither has rendered a page at boot, and inventing a hash for bytes that do not exist is a revision
+that never changes when the page does. **The offline document is fed through its own pair**, because
+`buildPrecacheManifest` adds it ITSELF as `reason: 'fallback'` ahead of every route and `add()`
+keeps the first entry per url — so the route entry of the same url is shadowed and only
+`offlineFallbackRevision` / `offlineFallbackBytes` (`ServiceWorkerConfig`, `@ultimat3/pwa`) can
+decide it. That pair was declared and fed by nobody for one commit; `serviceWorkerArtifacts` reads
+the fallback path out of the same `documents` map, so the one page an offline navigation depends on
+is content-addressed like every other. A fallback this pass did not render — no route serves it,
+which `x doctor` reports as `X_PWA_NO_OFFLINE_FALLBACK` — is absent from the map and keeps the
+build id.
 
 **Registration is an EXTERNAL script, never inline**, and that is a CSP fact rather than a
 preference: `startWeb` computes a `script-src` sha256 per inline script, so an unhashed one is
@@ -996,7 +1056,11 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `statement-loop.ts` | one verdict → the finding, the panel fact, the overlay notice and the log line |
 | `dev-policy.ts` | which actors to ask about, and which capability each policy gates |
 | `cmd-dev.ts` | boot order, mounting `/_x`, installing the span exporter, the file watcher |
-| `dev-watch.ts` | which writes under the app root are a source change. Seven directories are never one — `.x`, `node_modules`, `.git`, `.personal`, `.claude`, `dist`, `coverage` — and each is matched as a path SEGMENT: the rule was `filename.includes('.x/') \|\| filename.includes('node_modules')`, so `git status`, an agent's scratch file and a coverage run each ran a full `appManifest()` + `buildIslands()` (measured in ai-maxxing, which keeps two whole copies of the app under `.claude/worktrees/`), while a directory named `my-node_modules-notes/` got no reload at all |
+| `dev-watch.ts` | which paths under the app root `x dev` may not watch: the app's own `.gitignore` (`gitignore.ts`) plus a floor of five directory names an ignore file cannot be relied on to carry — `.git`, `.x`, `node_modules`, `.personal`, `.claude` — every one of them dotted or an install, matched as a path SEGMENT at any depth |
+| `dev-watch-tree.ts` | the watch SET: one `watch(dir, { recursive: false })` per ADMITTED directory, a new directory picked up on `rename`, a removed one giving its descriptor back, and the 30ms trailing debounce |
+| `dev-reload.ts` | one rebuild at a time — a tick arriving mid-build coalesces into ONE trailing rebuild, for the newest file |
+| `gitignore.ts` | what git ignores, as data: parse, the ancestor chain up to the repository, and last-match-wins |
+| `path-segments.ts` | `hasPathSegment` — a directory of that exact name, never a substring of one |
 | `style-bundle.ts` / `style-routes.ts` | a surface's CSS as one content-hashed file under `/styles/`, served `immutable` — `island-bundle.ts` / `island-routes.ts`' shape one asset over. It was an inline `<style>` until 2026-09-06: 156,738 bytes, identical on every page, inside a `private, no-store` document. The URL is the hash alone, no surface in the name: a surface is not a property of the bytes, and an app whose only CSS is its global layer would otherwise write three identical files into its static export and three entries into a precache manifest that has a budget |
 | `mcp-host.ts` | the `DevCapabilities` half of `@ultimat3/mcp`'s `DevHost` — db, tests, logs, verify |
 | `mcp-db-target.ts` | which database the host is pointed at: whether it is a branch, and whether it is production |
@@ -1005,6 +1069,44 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `mcp-test-output.ts` | reading `bun test`'s own summary back into a `TestRun` |
 | `cmd-mcp.ts` | `x mcp serve`: the two transports, and the local developer's caller |
 
+**The watch set is a REGISTRATION decision, not a filter, `As of 2026-09-06`.** `watch(root, {
+recursive: true })` takes one inotify descriptor per directory in the tree — measured on `x dev`
+against `examples/dummy`: **110 descriptors, 39 of them (35%) under `.x/` and `node_modules/`**, and
+on a monorepo root **1901, of which 1490 (78%) were `.git/` and `node_modules/`**, where one
+`git status` delivered 5 `.git/index` events into the JS callback. `isIgnoredPath` answered
+correctly every time and answered too late: the kernel queue entry, the callback and the slot out of
+`max_user_watches` (8192 on many distributions) were already spent. Bun 1.4.0's `fs.watch` has no
+ignore option, so `dev-watch-tree.ts` walks the root itself and registers one non-recursive watcher
+per admitted directory, pruning at descent.
+
+**And the ignore set is the app's own `.gitignore`.** Seven hand-listed directory names were wrong
+in both directions. Nothing read the ignore file, so `touch tsconfig.tsbuildinfo` — the file every
+`bun run typecheck` rewrites, named by `x new`'s own scaffolded `.gitignore` — logged
+`reloaded tsconfig.tsbuildinfo in 113ms`, a full `appManifest()` plus `buildIslands()`; on the
+framework root 54 git-ignored directories were unfiltered. And `dist` and `coverage` were matched at
+ANY depth, so an app's own `/dist` or `/coverage` ROUTE never reloaded — silently, which the file's
+own header calls worse than a spurious rebuild. `gitignore.ts` reads it with git's own anchoring
+(unanchored at any depth, a leading `/` or an inner slash where it is written, `!` re-including,
+a trailing `/` directory-only) and walks ANCESTOR ignore files up to the directory holding `.git` —
+`examples/dummy` carries none of its own and every rule about it lives in the repository root's. The
+file is re-read, and the whole watch set re-walked, on any write naming `.gitignore`; nothing ever
+spawns `git check-ignore`. `x new`'s scaffold writes `/dist/` and `/coverage/` **root-anchored** for
+this reason, plus `packages/*/dist/`. It is `fix-path.ts`'s parser, lifted: two readers of one file
+are two answers to what an app committed.
+
+**A watcher event carries no filename when the WATCHED directory itself moves.** Bun's recursive
+watcher delivers `undefined` — not `null` — on `mv myapp myapp2`, a re-clone or a volume remount,
+and `isIgnoredPath(undefined)` threw a `TypeError` inside an fs callback, outside any `try`, with no
+`uncaughtException` handler: `x dev` died with a stack trace. The listener is total over
+`string | Buffer | null | undefined` and logs `dev.watch.unnamed_event` once.
+
+**The reload has an in-flight guard, and it is the state that needed it.** A 45ms drip — a slow
+`git checkout`, a formatter walking files, `x db gen` — measured **40 reloads for 40 files**, each
+launching `Promise.all([appManifest, buildIslands])` while the previous still ran and assigning
+`state.manifest` / `state.islands` in COMPLETION order, so a slower earlier tick could land on top
+of a newer one. `coalesceReloads` (`dev-reload.ts`) keeps the LAST tick that arrived during a
+rebuild and starts exactly one more.
+
 `api-routes.ts` is the app's own API surface, composed **once** and mounted by both `cmd-dev.ts`
 and `serve.ts`: `listActions().map(toRoute)` from `@ultimat3/action` plus
 `listQueries().map(toQueryRoute)` from `@ultimat3/query`. Two lists is how `query.client()`
@@ -1022,6 +1124,16 @@ The roles live in `@ultimat3/core` (`ROLES`, `isRole`), never in a second list h
 driver, a dev-only authorizer or a dev-only queue is the bug this design exists to prevent — the
 only thing dev changes is which driver is behind an interface.
 
+### `HOST` is the interface, read the way `PORT` is
+
+`serve.ts`'s `hostnameFromEnv` — `HOST`, trimmed, empty is `0.0.0.0` — and `ServeOptions.hostname`
+overrides it as `port` overrides `PORT`; `containerBinding(env, hostname)` is the one `WebBinding`
+`serveApp` hands `startRoles`, so `web`, `sync` and the metrics endpoint bind the same interface.
+Before 2026-09-07 `CONTAINER_BINDING` was the only production binding and an app whose auth mode
+admits one implicit actor without a login — which must refuse a public interface — could not run in
+a container at all. A loopback bind in a container is unreachable through `-p`; the wiki row says
+where it IS reachable. Not `HOSTNAME`: Docker sets that to the container id.
+
 ### `RuntimeOverrides` is the only way to hand the framework a driver
 
 `ServeOptions` was `{ root, env, role?, port?, metricsPort? }`, so the ONLY way an app could
@@ -1154,9 +1266,23 @@ Delete `graphHash` the day `Bun.build` is deterministic.
 
 **`x dev`, the container and the static export all mount the same table.** `serve.ts` builds the
 islands at boot for the same reason it mounts `apiRoutes()`: a seam that works in dev and not in the
-image is the same failure one release later. `x dev` rebuilds them on the watcher tick, and that is
-the one reload that actually takes effect — an island is the single module this process never
-imports, so there is no Bun module cache to invalidate.
+image is the same failure one release later. `x dev` rebuilds them on the watcher tick — an island
+is the single module this process never imports, so there is no Bun module cache to invalidate —
+and the SAME tick re-imports the route module beside them when its source changed
+(`app-load.ts`'s `reloadRoute`: `<path>?x-reload=<hash>` is the one cache key Bun honours,
+`registerRoute` replaces the entry for the same file, and `dev-render.ts` reads the entry back from
+the table on every request rather than closing over the one it was built from). Until 2026-09-07
+the island was the only reload that took effect, so a save served a new island under an old page —
+the old props, the placeholder the new island renders when they are missing. A route module and
+nothing else: an action, a query or an entity is held by every module that imported it, and no
+re-import can rebind those. `@ultimat3/render`'s loader admits the query
+(`/\.tsx(?:\?[^/]*)?$/`) and strips it before reading the file — anchored on `.tsx$`, the
+re-import fell through to Bun's own JSX loader and every reloaded page died on `__xh`.
+
+**The dev fixture is its own repository** (`.git/HEAD` in `DEV_FIXTURE_FILES`). The framework's root
+`.gitignore` lists `packages/cli/.dev-fixture/`, `devIgnore` honours every ancestor up to a `.git`,
+and so the watcher admitted the fixture root and nothing under it: every run booted the reload path
+and none exercised it. The marker is what lets `cmd-dev.test.ts` save a page and await the tick.
 
 **`app-load.ts` skips `*.island.tsx` deliberately.** It registers no primitive, and importing it
 would put the one module guaranteed to be outside the server's graph inside this process's, where a

package/README.md

@@ -123,7 +123,7 @@ is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUAR
 | `app-openapi.ts` | `openapi.json`, projected by `@ultimat3/action` |
 | `app-boundaries.ts` | app import boundaries, over `@ultimat3/render`'s surface check |
 | `app-agents-md.ts` | `AGENTS.md` exists and stays short, over `@ultimat3/manifest`'s check |
-| `serve.ts` | **what a container starts** — `runRole(options)`, the same boot `x dev` runs minus the watcher, `/_x` and `dev: true`. `x new`'s `apps/web/server.ts` is three lines that call it |
+| `serve.ts` | **what a container starts** — `runRole(options)`, the same boot `x dev` runs minus the watcher, `/_x` and `dev: true`. `x new`'s `apps/web/server.ts` is three lines that call it. `ROLE`, `PORT` and `HOST` are read from `env`; `role`, `port` and `hostname` on `ServeOptions` override each |
 | `prerender.ts` | `x build --target static`: which `site/` routes qualify, and where the bytes land |
 | `metrics-endpoint.ts` | the `METRICS_PATH` scrape listener every role opens, on `METRICS_PORT` |
 | `otlp-export.ts` | the exporters `OTEL_EXPORTER_OTLP_ENDPOINT` switches on, and their drain hooks |

package/package.json

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

package/src/app-agents-md.ts

@@ -15,11 +15,22 @@ export interface AgentsMdOutcome {
   readonly warnings: readonly string[];
 }
 
-/** `assertAgentsMd` throws `X_AGENTS_MD_*`; a gate step reports, so the error becomes a finding. */
-export async function checkAgentsMd(root: string): Promise<AgentsMdOutcome> {
+/**
+ * `assertAgentsMd` throws `X_AGENTS_MD_*`; a gate step reports, so the error becomes a finding.
+ *
+ * `maxBytes` is this repository's own budget, out of `x.verify.json`, and `undefined` means the
+ * 12kB default. `@ultimat3/manifest` has taken the option since it was written and this function
+ * never passed one, so the default was the only budget any app could have: a repository whose
+ * conventions genuinely need more room had to delete a rule to make space, which is the opposite
+ * of what a context-file budget is for.
+ */
+export async function checkAgentsMd(root: string, maxBytes?: number): Promise<AgentsMdOutcome> {
   const path = join(root, AGENTS_MD_FILENAME);
   try {
-    const { warnings } = await assertAgentsMd({ path });
+    const { warnings } = await assertAgentsMd({
+      path,
+      ...(maxBytes === undefined ? {} : { maxBytes }),
+    });
     return { findings: [], warnings };
   } catch (error) {
     return { findings: [{ ...findingFrom(error), at: AGENTS_MD_FILENAME }], warnings: [] };

package/src/app-boundaries.ts

@@ -18,6 +18,7 @@ import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { BoundaryRule, ImportGraph } from '@ultimat3/render';
 import { checkSurfaceBoundary, importGraph, SURFACES } from '@ultimat3/render';
 import type { Finding } from './output';
+import { hasPathSegment } from './path-segments';
 import { quoteArg } from './shell-quote';
 
 export const BOUNDARY_CODES = [
@@ -56,8 +57,16 @@ const isDbSpecifier = (specifier: string): boolean =>
   specifier.endsWith('/db') ||
   /^@[^/]+\/db$/.test(specifier) ||
   specifier === 'drizzle-orm';
+/**
+ * `node:http` and `node:https` are HTTP too, and the anchor could not reach them: `http` had to
+ * follow a `/` or start the string, and a `node:` specifier has a colon there. So the one spelling
+ * that needs no dependency at all — a service reaching straight for the runtime's own client — was
+ * the one spelling this rule could not see. Matched on the boundary character rather than by
+ * listing every prefix, and still anchored at both ends: `node:http2-fake` and
+ * `@ultimat3/https-client` are names, not HTTP.
+ */
 const isHttpSpecifier = (specifier: string): boolean =>
-  specifier === '@ultimat3/http' || /(^|\/)http($|\/)/.test(specifier);
+  specifier === '@ultimat3/http' || /(^|[/:])https?($|\/)/.test(specifier);
 
 /** The transpiler rejects a shebang, and an app's `bin/` entry points legitimately have one. */
 export const stripShebang = (source: string): string =>
@@ -236,7 +245,7 @@ export async function readAppSources(root: string): Promise<readonly SourceFile[
   for (const pattern of APP_GLOBS) {
     const glob = new Bun.Glob(pattern);
     for await (const path of glob.scan({ cwd: root, absolute: false })) {
-      if (path.includes('node_modules') || path.includes('.test.')) continue;
+      if (hasPathSegment(path, 'node_modules') || path.includes('.test.')) continue;
       const posix = path.split('\\').join('/');
       files.push({ path: posix, source: await Bun.file(joinPath(root, posix)).text() });
     }

package/src/app-load.ts

@@ -10,6 +10,7 @@ import { registerActions } from '@ultimat3/action';
 import { localeConfig } from '@ultimat3/i18n';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
 import { registerQueries } from '@ultimat3/query';
+import type { RouteConfig } from '@ultimat3/render';
 import { isRouteConfig, pageComponentOf, registerRoute } from '@ultimat3/render';
 // For the SIDE EFFECT, and it is this module's to hold: importing `@ultimat3/render/server`
 // installs the `.tsx`/`.scss` Bun plugin, a plugin only transforms modules loaded AFTER it, and
@@ -21,6 +22,7 @@ import '@ultimat3/render/server';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';
+import { hasPathSegment } from './path-segments';
 
 /** Every place an app keeps code the framework has to see. */
 const APP_GLOBS = [
@@ -73,20 +75,32 @@ export interface LoadedApp {
   readonly findings: readonly Finding[];
 }
 
-// A module is imported and registered exactly once per PROCESS: `import()` caches, and a registry
-// rejects a second registration of a name. So a rescan refreshes only the facts DERIVED from the
-// registries — the manifest and its build id — and never the primitives themselves: an edited route
-// config, action or query needs a restart. Clearing the registries would not change that. Bun
-// exposes no way to invalidate a cached module, so the re-import hands back the same stale exports,
-// and a cache-busting query string leaks a fresh module instance on every save.
+// A module is imported and registered once per PROCESS: `import()` caches, and a registry rejects
+// a second registration of a name. So a rescan refreshes the facts DERIVED from the registries —
+// the manifest and its build id — and, for exactly one kind of module, the primitive itself. A
+// ROUTE module whose source changed is imported again under `?x-reload=<hash>`, the one cache key
+// Bun honours, and `registerRoute` replaces the entry for the same file; its own imports resolve
+// to the modules already cached, which is what makes it safe. An action, a query or an entity
+// stays registered once: its exports are held by every module that imported it, a second instance
+// would be a duplicate name in its registry, and no re-import can rebind the importers — those
+// edits need a restart. Until 2026-09-07 the route module took the same rule, so a save re-bundled
+// the island (`buildIslands` reads the disk) and kept the FIRST page component — a new island
+// rendering under an old page's props, which is the mixed generation `x dev` served.
 const registered = new Set<string>();
 // A registration failure is sticky: the file is never retried, so the finding is replayed.
 const failures = new Map<string, Finding>();
+// Route modules only: the hash of the source each one registered from, which is what a rescan
+// compares the disk against. A save that leaves the bytes alone re-imports nothing.
+const routeSources = new Map<string, bigint>();
+
+/** The query a re-imported route module carries. `module-loader.ts`'s filter admits it. */
+const RELOAD_QUERY = 'x-reload';
 
 /** Test seam, and what `x dev` would call if it ever restarted the registries in-process. */
 export function resetAppLoad(): void {
   registered.clear();
   failures.clear();
+  routeSources.clear();
 }
 
 export async function loadApp(root: string): Promise<LoadedApp> {
@@ -95,11 +109,21 @@ export async function loadApp(root: string): Promise<LoadedApp> {
 
   for (const pattern of APP_GLOBS) {
     for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
-      if (absolute.includes('node_modules') || absolute.includes('.test.')) continue;
+      // A SEGMENT, never a substring: an app checked out under
+      // `~/dev/node_modules-experiments/myapp` answered `includes('node_modules')` for every
+      // file it holds, so this loop imported none of them and the app registered nothing.
+      if (hasPathSegment(absolute, 'node_modules') || absolute.includes('.test.')) continue;
       const file = relative(root, absolute).split(sep).join('/');
       if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
         continue;
       }
+      // The source is read BEFORE the import, and only on the file's first pass — a rescan of a
+      // registered module reads nothing here. A route entry is bound to the bytes the module was
+      // evaluated from, and a read AFTER the import cannot know which bytes those were: a save
+      // landing between the two bound V1's component to V2's hash, so the next scan saw nothing to
+      // do and served V1 until the save after. Read first, the worst case is one re-import the
+      // next tick, of a file that did change.
+      const snapshot = registered.has(absolute) ? undefined : await Bun.file(absolute).text();
       let module: Record<string, unknown>;
       try {
         module = (await import(absolute)) as Record<string, unknown>;
@@ -108,7 +132,7 @@ export async function loadApp(root: string): Promise<LoadedApp> {
         continue;
       }
       files.push(file);
-      const finding = await register(absolute, file, module);
+      const finding = await register(absolute, file, module, snapshot);
       if (finding !== undefined) findings.push(finding);
     }
   }
@@ -124,35 +148,29 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   };
 }
 
-/** Registers a module once; every later call replays whatever the first one reported. */
+/**
+ * Registers a module once; every later call replays whatever the first one reported — except for
+ * a route module, which a later call re-registers from disk when its source has changed.
+ * `snapshot` is the source read before the module's first import, and absent on every later call.
+ */
 async function register(
   absolute: string,
   file: string,
   module: Record<string, unknown>,
+  snapshot: string | undefined,
 ): Promise<Finding | undefined> {
   const previous = failures.get(absolute);
   if (previous !== undefined) return previous;
-  if (registered.has(absolute)) return undefined;
+  if (snapshot === undefined) return reloadRoute(absolute, file);
   registered.add(absolute);
   try {
     const config = module['config'];
-    if (isRouteConfig(config)) {
-      // The build counts boundaries from the compiled JSX; before a build there is only the
-      // source, and `render: 'stream'` is rejected without one — so count them in the text.
-      const source = await Bun.file(absolute).text();
-      // The page component comes from the same module as its config, resolved by render's own
-      // rule — the CLI does not decide which export is a page any more than it decides what a
-      // route is. A module with no component registers without one, and renders a bare shell.
-      const component = pageComponentOf(module);
-      registerRoute({
-        file,
-        config,
-        suspenseBoundaries: countSuspense(source),
-        ...(component === undefined ? {} : { component }),
-      });
-    }
+    const route = isRouteConfig(config) ? config : undefined;
+    if (route !== undefined) registerRouteModule(file, module, route, snapshot);
     registerActions(module);
     registerQueries(module);
+    // Only a route module is ever re-imported, so only a route module's hash is worth keeping.
+    if (route !== undefined) routeSources.set(absolute, Bun.hash.wyhash(snapshot));
     return undefined;
   } catch (error) {
     const finding: Finding = { ...findingFrom(error), at: file };
@@ -161,6 +179,59 @@ async function register(
   }
 }
 
+/**
+ * The route half of a registration, and the whole of a re-registration. `source` is the text the
+ * module was imported from — read by the caller BEFORE the import, never here after it — and the
+ * hash the entry is bound to is that text's. Until 2026-09-07 this read the file again, and a save
+ * between the import and that read registered the old component under the new hash: the next
+ * scan compared equal, and the page on disk was not served until the save after it.
+ */
+function registerRouteModule(
+  file: string,
+  module: Record<string, unknown>,
+  config: RouteConfig,
+  source: string,
+): void {
+  // The page component comes from the same module as its config, resolved by render's own
+  // rule — the CLI does not decide which export is a page any more than it decides what a
+  // route is. A module with no component registers without one, and renders a bare shell.
+  const component = pageComponentOf(module);
+  registerRoute({
+    file,
+    config,
+    // The build counts boundaries from the compiled JSX; before a build there is only the
+    // source, and `render: 'stream'` is rejected without one — so count them in the text.
+    suspenseBoundaries: countSuspense(source),
+    ...(component === undefined ? {} : { component }),
+  });
+}
+
+/**
+ * A registered route module, on a rescan: imported again if the file no longer hashes to what it
+ * registered from, and left alone otherwise. A save that will not import is a finding at the file
+ * and NOT a sticky one — the next save is tried again — and the entry it would have replaced stays
+ * registered, so the last page that did import is the one served meanwhile.
+ */
+async function reloadRoute(absolute: string, file: string): Promise<Finding | undefined> {
+  const registeredFrom = routeSources.get(absolute);
+  if (registeredFrom === undefined) return undefined;
+  const source = await Bun.file(absolute).text();
+  const hash = Bun.hash.wyhash(source);
+  if (hash === registeredFrom) return undefined;
+  try {
+    const module = (await import(`${absolute}?${RELOAD_QUERY}=${hash}`)) as Record<string, unknown>;
+    const config = module['config'];
+    // A file that stopped being a route is not un-registered — the table has no verb for it, and a
+    // deleted file needs a restart either way. Its hash is recorded so the same save is not
+    // re-imported on every later tick.
+    if (isRouteConfig(config)) registerRouteModule(file, module, config, source);
+    routeSources.set(absolute, hash);
+    return undefined;
+  } catch (error) {
+    return { ...findingFrom(error), at: file };
+  }
+}
+
 const countSuspense = (source: string): number => source.match(/<Suspense[\s/>]/g)?.length ?? 0;
 
 /** `packages/db/src/errors.ts` → `packages/db`; `apps/web/app/posts/errors.ts` → `apps/web`. */

package/src/budgets.ts

@@ -227,9 +227,24 @@ export interface MeasuredJs {
 export async function measureDocumentJs(html: string, out: string): Promise<MeasuredJs> {
   let jsBytes = 0;
   const entries: MeasuredEntry[] = [];
+  // Deduped ONCE, across both readers below, and the unit is the FETCH: a browser downloads a URL
+  // once however many times the document names it, so `budget.js` — a byte budget — counts it
+  // once. Two instances of one island are two wrappers and one chunk; so are a `<script src>`
+  // repeated by a page and its layout, and a src that is also an island entry. Only the island
+  // half was deduped, so a document naming one script twice was charged twice and could fail a
+  // budget it clears.
+  //
+  // EXECUTION is a different count and this is deliberately not it. A repeated classic
+  // `<script src>` runs once per element (a module runs once per document, off the module map), so
+  // the layout-plus-page case above really does execute twice — for zero extra bytes. That is a
+  // CPU cost, and this gate is a bound on what the browser downloads and parses. An INLINE script
+  // is not in this set for the same reason: two identical inline bodies are two copies of the
+  // bytes in the document, so both are charged.
+  const fetched = new Set<string>();
   const weigh = async (url: string): Promise<void> => {
     // Only a path inside the artifact can be weighed; a cross-origin script is not this build's.
-    if (!url.startsWith('/')) return;
+    if (!url.startsWith('/') || fetched.has(url)) return;
+    fetched.add(url);
     const file = Bun.file(join(out, url.slice(1)));
     const bytes = (await file.exists()) ? file.size : 0;
     entries.push({ url, bytes });
@@ -246,13 +261,9 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     }
     await weigh(src);
   }
-  // Deduped: two instances of one island are two wrappers and one chunk, and a browser that
-  // imports the same module twice fetches and executes it once.
-  const booted = new Set<string>();
   for (const match of html.matchAll(ENTRY_ATTR)) {
     const url = match.groups?.['url'];
-    if (url === undefined || booted.has(url)) continue;
-    booted.add(url);
+    if (url === undefined) continue;
     await weigh(url);
   }
   return { jsBytes, entries };