@ultimat3/cli 19.2.0 → 19.3.1

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()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "19.2.0",
+  "version": "19.3.1",
   "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.1",
+    "@ultimat3/admin": "19.3.1",
+    "@ultimat3/ai": "19.3.1",
+    "@ultimat3/auth": "19.3.1",
+    "@ultimat3/cache": "19.3.1",
+    "@ultimat3/core": "19.3.1",
+    "@ultimat3/db": "19.3.1",
+    "@ultimat3/entity": "19.3.1",
+    "@ultimat3/flags": "19.3.1",
+    "@ultimat3/http": "19.3.1",
+    "@ultimat3/i18n": "19.3.1",
+    "@ultimat3/jobs": "19.3.1",
+    "@ultimat3/mail": "19.3.1",
+    "@ultimat3/manifest": "19.3.1",
+    "@ultimat3/mcp": "19.3.1",
+    "@ultimat3/money": "19.3.1",
+    "@ultimat3/notify": "19.3.1",
+    "@ultimat3/policy": "19.3.1",
+    "@ultimat3/pwa": "19.3.1",
+    "@ultimat3/query": "19.3.1",
+    "@ultimat3/realtime": "19.3.1",
+    "@ultimat3/render": "19.3.1",
+    "@ultimat3/schema": "19.3.1",
+    "@ultimat3/scraping": "19.3.1",
+    "@ultimat3/seo": "19.3.1",
+    "@ultimat3/storage": "19.3.1",
+    "@ultimat3/testing": "19.3.1",
+    "@ultimat3/time": "19.3.1",
     "babel-preset-solid": "^1.9.15"
   }
 }

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

@@ -21,6 +21,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 = [
@@ -95,7 +96,10 @@ 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;

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 };

package/src/cmd-dev.ts

@@ -4,7 +4,6 @@
 // alongside it — mounted, never re-implemented — so an agent can introspect the running app.
 // No Docker, no env setup: an unset variable means the embedded default.
 
-import { watch } from 'node:fs';
 import { join } from 'node:path';
 import { devShellStyle } from '@ultimat3/admin/dev';
 import type { Role } from '@ultimat3/core';
@@ -29,6 +28,7 @@ import { devDashboardRoutes, devPanels } from './dev-dashboard';
 import { liveFeedLabel } from './dev-live-feed';
 import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
+import { coalesceReloads } from './dev-reload';
 import { appRoutes } from './dev-render';
 import { replicaOverrides } from './dev-replica';
 import type { RunningRoles } from './dev-roles';
@@ -39,7 +39,7 @@ import type { DevServices } from './dev-services';
 import { describeServices, reportedUrls, resolveServices } from './dev-services';
 import { storageRoutes } from './dev-storage';
 import { createTraceRecorder } from './dev-traces';
-import { isIgnoredPath } from './dev-watch';
+import { watchTree } from './dev-watch-tree';
 import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { IslandBundle } from './island-bundle';
@@ -96,26 +96,6 @@ interface DevState {
   islands: IslandBundle;
 }
 
-/**
- * Debounced: a save that touches five files is one reload, not five. What counts as a save at all
- * is `dev-watch.ts` — a reload is a full `appManifest()` plus a `buildIslands()` over every island,
- * so a write this cannot rule out is the most expensive no-op the dev loop has.
- */
-function watchApp(root: string, onChange: (file: string) => void): () => void {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let last = '';
-  const watcher = watch(root, { recursive: true }, (_event, filename) => {
-    if (filename === null || isIgnoredPath(filename)) return;
-    last = filename;
-    if (timer !== undefined) clearTimeout(timer);
-    timer = setTimeout(() => onChange(last), 30);
-  });
-  return () => {
-    if (timer !== undefined) clearTimeout(timer);
-    watcher.close();
-  };
-}
-
 export interface StartDevOptions {
   readonly root: string;
   readonly port: number;
@@ -294,22 +274,32 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
   });
 
-  const stopWatching = watchApp(options.root, (file) => {
-    const started = performance.now();
-    void Promise.all([appManifest(options.root), buildIslands(options.root)])
-      .then(([{ manifest }, islands]) => {
-        state.manifest = manifest;
-        state.islands = islands;
-        state.reloads += 1;
-        state.reloadFinding = undefined;
-        options.onReload?.(file, Math.round(performance.now() - started));
-      })
-      // Same rule as a module that will not import: a save the manifest cannot be rebuilt from is
-      // a finding on `/_x`, never an unhandled rejection that takes the dev server down.
-      .catch((error: unknown) => {
-        state.reloadFinding = { ...findingFrom(error), at: file };
-      });
-  });
+  // One rebuild at a time, and the last save wins: a tick arriving mid-build coalesces into ONE
+  // trailing rebuild instead of racing the one in flight for `state.manifest` and `state.islands`.
+  const rebuild = coalesceReloads(
+    async (file) => {
+      const started = performance.now();
+      const [{ manifest }, islands] = await Promise.all([
+        appManifest(options.root),
+        buildIslands(options.root),
+      ]);
+      state.manifest = manifest;
+      state.islands = islands;
+      state.reloads += 1;
+      state.reloadFinding = undefined;
+      options.onReload?.(file, Math.round(performance.now() - started));
+    },
+    // Same rule as a module that will not import: a save the manifest cannot be rebuilt from is
+    // a finding on `/_x`, never an unhandled rejection that takes the dev server down.
+    (error: unknown, file: string) => {
+      state.reloadFinding = { ...findingFrom(error), at: file };
+    },
+  );
+  // Watched one directory at a time, so an ignored one costs no descriptor at all — `dev-watch.ts`
+  // decides which, from the app's own `.gitignore`. A recursive watch on the root registered one
+  // inotify descriptor per directory in the tree, `.git/`, `node_modules/` and the `.x/` this
+  // process writes to included, and filtered the events afterwards.
+  const watcher = watchTree({ root: options.root, onChange: rebuild });
 
   server = {
     url: running.url ?? `http://localhost:${options.port}`,
@@ -333,7 +323,7 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     runtime,
     panels,
     async stop() {
-      stopWatching();
+      watcher.close();
       await running.stop();
       await runtime.stop();
       // Released after the roles: a span opened by an in-flight request still has an exporter to

package/src/cmd-doctor.ts

@@ -4,16 +4,25 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { ERROR_DOCS_URL, tryResolveEnvironment, usesDevCursorSecret } from '@ultimat3/core';
+import {
+  ENV_EXAMPLE_PATH,
+  ERROR_DOCS_URL,
+  tryResolveEnvironment,
+  usesDevCursorSecret,
+} from '@ultimat3/core';
 import { checkDb, createPostgresClient } from '@ultimat3/db';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
-import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
+import { syncPortFor } from './dev-sync';
+import type { OfflineFallbackFact } from './doctor-offline';
+import { offlineFallbackFinding, offlineFallbackProbe } from './doctor-offline';
+import { intFlagOr, PORT_RANGE, portPairAfter } from './flag-number';
 import { ICON_SOURCE } from './icon-assets';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
+import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
 import { portFree } from './port-probe';
 import { checkMigrationDrift } from './schema-drift';
@@ -59,6 +68,12 @@ export interface DoctorProbe {
    * separate remedies — one is "generate a migration", the other is "this migration is incomplete".
    */
   snapshots(): Promise<readonly Finding[]>;
+  /**
+   * What the app declared as its offline fallback, and which routes it really serves. A FACT and
+   * not a finding, because deciding is `offlineFallbackFinding`'s and this seam's whole job is
+   * reaching the disk — the same split `drift()` makes one question over.
+   */
+  offlineFallback(): Promise<OfflineFallbackFact>;
 }
 
 const finding = (code: string, cause: string, fix: string, at?: string): Finding =>
@@ -66,7 +81,8 @@ const finding = (code: string, cause: string, fix: string, at?: string): Finding
     ? { code, cause, fix, docs: ERROR_DOCS_URL }
     : { code, cause, fix, docs: ERROR_DOCS_URL, at };
 
-export const OFFLINE_FALLBACK = 'apps/web/app/offline.tsx';
+/** The file `x doctor` reports missing, and the one the reader creates. */
+export const ENV_DEVELOPMENT = '.env.development';
 
 /** The port `x dev` binds by default, so the probe answers about the port the developer will use. */
 const DEFAULT_DOCTOR_PORT = 3000;
@@ -80,12 +96,30 @@ const DEFAULT_DOCTOR_PORT = 3000;
  * derives `PORT = .port - 1` from it, so it is part of the contract `x dev` runs by.
  *
  * The suggested port moves BOTH: `x dev --port N` occupies N and N+1, so a free N beside a taken
- * N+1 is still not a runnable command.
+ * N+1 is still not a runnable command. It did not move both until 2026-09 — the line was
+ * `neighbouringPort(probe.port)`, which for the sync finding IS the port the finding is about, and
+ * a docblock claiming otherwise is how it survived. `portPairAfter` is the one reader of that rule
+ * and `dev-sync.ts`'s own refusal shares it.
+ *
+ * The sync port is `syncPortFor`, never `neighbouringPort` again: that helper answers 65534 for a
+ * web port of 65535 — BELOW the web port, and a port `x dev` never binds — where the boot refuses
+ * the run outright with `X_PORT_INVALID`. A probe that reports on a socket the command would never
+ * open is answering a question nobody asked, so the boot's own rule decides, and its refusal is
+ * reported instead of a probe. Alone, and ahead of the web port: there is no runnable `x dev` at
+ * this port whatever the other one answers, and a second finding about it is noise over the cause.
  */
 async function portFindings(probe: DoctorProbe): Promise<readonly Finding[]> {
+  let syncPort: number;
+  try {
+    syncPort = syncPortFor(probe.port);
+  } catch (error) {
+    // The boot's own error, carried whole — `findingFrom` reads its code, cause and fix off the
+    // value rather than rendering it, which is what `scripts/catch-render.ts` requires.
+    return [findingFrom(error)];
+  }
   const wanted = [
     { port: probe.port, role: 'web' },
-    { port: neighbouringPort(probe.port), role: 'sync' },
+    { port: syncPort, role: 'sync' },
   ] as const;
   const findings: Finding[] = [];
   for (const entry of wanted) {
@@ -94,10 +128,7 @@ async function portFindings(probe: DoctorProbe): Promise<readonly Finding[]> {
       finding(
         'X_PORT_IN_USE',
         `port ${entry.port} is already listening, and \`x dev --port ${probe.port}\` binds it for the ${entry.role} role`,
-        // Unchanged, and deliberately: the neighbour below the top of the range is the one port
-        // `x dev` is guaranteed to accept (`X_CLI_BAD_FLAG` otherwise), which is what
-        // `cmd-doctor.test.ts` pins by parsing this line with `x dev`'s own flag reader.
-        `x dev --port ${neighbouringPort(probe.port)}`,
+        `x dev --port ${portPairAfter(probe.port)}`,
       ),
     );
   }
@@ -125,13 +156,20 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
     );
     return findings;
   }
-  if (!probe.exists('.env.development')) {
+  if (!probe.exists(ENV_DEVELOPMENT)) {
     findings.push(
       finding(
         'X_ENV_MISSING',
-        '.env.development is missing, so committed defaults cannot be read',
-        'x new --force to restore the committed defaults, or create .env.development',
-        '.env.development',
+        `${ENV_DEVELOPMENT} is missing, so committed defaults cannot be read`,
+        // The file write, named — `X_PWA_ICON_MISSING`'s shape below, and for its reason. This
+        // said `x new --force`, which cannot run where the reader is standing: `x new` takes a
+        // <name> positional (reproduced: `x new --force --json` inside an app answers
+        // `X_CLI_BAD_FLAG`), and with one it scaffolds a SECOND app beside the broken one.
+        // `.env.example` is the committed projection of `envSchema`, so the copy lands every
+        // declared key with its default and blank secrets; `x env example` writes it where an app
+        // has none, and `X_ENV_EXAMPLE_DRIFT` is what reports that.
+        `cp ${ENV_EXAMPLE_PATH} ${ENV_DEVELOPMENT}`,
+        ENV_DEVELOPMENT,
       ),
     );
   }
@@ -183,16 +221,12 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
       ),
     );
   }
-  if (!probe.exists(OFFLINE_FALLBACK)) {
-    findings.push(
-      finding(
-        'X_PWA_NO_OFFLINE_FALLBACK',
-        `${OFFLINE_FALLBACK} is missing, so an offline navigation falls back to the browser error page`,
-        'x g route offline --surface app',
-        OFFLINE_FALLBACK,
-      ),
-    );
-  }
+  // The DECLARED fallback against the ROUTE TABLE, never a filename: this probed
+  // `apps/web/app/offline.tsx`, which is not a route file at all (`assertRouteFilename` refuses
+  // it), so no app could clear the finding and its own `fix:` did not either. `doctor-offline.ts`
+  // holds the rule and the reasons.
+  const offline = offlineFallbackFinding(await probe.offlineFallback());
+  if (offline !== undefined) findings.push(offline);
   const database = await probe.database();
   if (database !== null) findings.push(database);
   findings.push(...(await probe.drift()));
@@ -264,6 +298,10 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     database: () => probeDatabase(process.env['DATABASE_URL']),
     drift: async () => (root === undefined ? [] : checkMigrationDrift(root)),
     snapshots: async () => (root === undefined ? [] : checkMigrationSnapshots(root)),
+    // `routes: undefined` outside an app is "not judged", which is what the caller already is:
+    // `runDoctor` returns on `X_NOT_IN_APP` before this can be asked.
+    offlineFallback: async () =>
+      root === undefined ? { fallback: null, routes: undefined } : offlineFallbackProbe(root),
   };
 }