@abide/abide 0.48.0 → 0.50.0

package/src/lib/server/runtime/createServer.ts

@@ -5,31 +5,17 @@ import type { McpServer } from '../../mcp/types/McpServer.ts'
 import { abideLog } from '../../shared/abideLog.ts'
 import { basePathFromAppUrl } from '../../shared/basePathFromAppUrl.ts'
 import { baseSlot } from '../../shared/baseSlot.ts'
-import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
-import { CLI_PATH } from '../../shared/CLI_PATH.ts'
-import { DEV_HOT_PREFIX } from '../../shared/DEV_HOT_PREFIX.ts'
-import { DEV_RELOAD_PATH } from '../../shared/DEV_RELOAD_PATH.ts'
 import { extraForwardHeaders } from '../../shared/extraForwardHeaders.ts'
-import { HEALTH_PATH } from '../../shared/HEALTH_PATH.ts'
 import { healthReadSlot } from '../../shared/healthReadSlot.ts'
-import { IDENTITY_PATH } from '../../shared/IDENTITY_PATH.ts'
-import { INSPECTOR_PATH } from '../../shared/INSPECTOR_PATH.ts'
 import { isDebugNegated } from '../../shared/isDebugNegated.ts'
 import { logClosingRecord } from '../../shared/logClosingRecord.ts'
-import { matchRoute } from '../../shared/matchRoute.ts'
-import { normalizePathname } from '../../shared/normalizePathname.ts'
 import { OFFLINE_HEADER } from '../../shared/OFFLINE_HEADER.ts'
 import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
-import { parseRouteSegments } from '../../shared/parseRouteSegments.ts'
 import { requestScopeSlot } from '../../shared/requestScopeSlot.ts'
-import { SOCKETS_PATH } from '../../shared/SOCKETS_PATH.ts'
 import { setAppName } from '../../shared/setAppName.ts'
-import { TEXT_PLAIN } from '../../shared/TEXT_PLAIN.ts'
 import type { Layouts } from '../../ui/types/Layouts.ts'
 import type { Pages } from '../../ui/types/Pages.ts'
 import type { AppModule } from '../AppModule.ts'
-import { handleCliDownload } from '../cli/handleCliDownload.ts'
-import { handleCliInstall } from '../cli/handleCliInstall.ts'
 import type { PromptRoutes } from '../prompts/types/PromptRoutes.ts'
 import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
 import { createSocketDispatcher } from '../sockets/createSocketDispatcher.ts'
@@ -38,20 +24,16 @@ import { buildHealthPayload } from './buildHealthPayload.ts'
 import { buildOpenApiSpec } from './buildOpenApiSpec.ts'
 import { buildPreloadManifest } from './buildPreloadManifest.ts'
 import { createAppAssetServer } from './createAppAssetServer.ts'
+import { createAppRouteResolver } from './createAppRouteResolver.ts'
+import { createPlumbingRouter, PLUMBING_PASS } from './createPlumbingRouter.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
 import { createRouteDispatcher } from './createRouteDispatcher.ts'
 import { createUiPageRenderer } from './createUiPageRenderer.ts'
-import { crossOriginGate } from './crossOriginGate.ts'
 import { DEFAULT_PORT } from './DEFAULT_PORT.ts'
 import { DEV_READY_MESSAGE } from './DEV_READY_MESSAGE.ts'
-import { DEV_REBUILD_MESSAGE } from './DEV_REBUILD_MESSAGE.ts'
 import { DEV_RELOAD_CLIENT_SCRIPT } from './DEV_RELOAD_CLIENT_SCRIPT.ts'
 import { devClientFingerprint } from './devClientFingerprint.ts'
-import { devHotModuleResponse } from './devHotModuleResponse.ts'
-import { devReloadResponse } from './devReloadResponse.ts'
-import { disableIdleTimeoutForStream } from './disableIdleTimeoutForStream.ts'
 import { finalizeResponse } from './finalizeResponse.ts'
-import { gzipResponse } from './gzipResponse.ts'
 import { installAmbientScopeStore } from './installAmbientScopeStore.ts'
 import { internalErrorResponse } from './internalErrorResponse.ts'
 import { listenOnOpenPort } from './listenOnOpenPort.ts'
@@ -63,15 +45,11 @@ import { ensureRegistriesLoaded, setRegistryManifests } from './registryManifest
 import { requestContext } from './requestContext.ts'
 import { runWithRequestScope } from './runWithRequestScope.ts'
 import { setActiveServer } from './setActiveServer.ts'
+import { textResponse } from './textResponse.ts'
 import type { Assets } from './types/Assets.ts'
 import type { RequestStore } from './types/RequestStore.ts'
 import { warnUnguardedMcp } from './warnUnguardedMcp.ts'
 
-const SOCKETS_REST_PREFIX = `${SOCKETS_PATH}/`
-const MCP_PATH = '/__abide/mcp'
-const CLI_DOWNLOAD_PREFIX = `${CLI_PATH}/`
-// Dev-only manual rebuild trigger; POSTing signals the orchestrator to rebuild + restart.
-const DEV_REBUILD_PATH = '/__abide/reload'
 /*
 Unlike the framework's own plumbing routes above (the socket multiplex, MCP
 endpoint, CLI download), the OpenAPI document describes the app's public HTTP
@@ -196,13 +174,6 @@ export async function createServer({
     // In dev, append the live-reload client to the shell so every rendered
     // page reconnects to /__abide/dev and reloads after a restart.
     const devShell = dev ? shell.replace('</body>', `${DEV_RELOAD_CLIENT_SCRIPT}</body>`) : shell
-    // When the inspector is enabled, flag the client so startClient installs the
-    // BroadcastChannel bridge that streams scope + router state to the inspector
-    // page. Independent of dev — the inspector can run on a build server too.
-    const inspectedShell =
-        process.env.ABIDE_ENABLE_INSPECTOR === 'true'
-            ? devShell.replace('</body>', `<script>window.__abideInspect=true</script></body>`)
-            : devShell
     /*
     Mount base from APP_URL's pathname (e.g. https://foo.com/v2 → /v2). Install
     the server-side resolver so url() prefixes SSR-generated links, and rewrite
@@ -214,9 +185,17 @@ export async function createServer({
     baseSlot.resolver = () => base
     // Rebase the shell's rooted `/_app/` entry refs onto the mount base, matching
     // either quote style so a custom app.html using single quotes still rewrites.
-    const activeShell = base
-        ? inspectedShell.replace(/(["'])\/_app\//g, `$1${base}/_app/`)
-        : inspectedShell
+    const activeShell = base ? devShell.replace(/(["'])\/_app\//g, `$1${base}/_app/`) : devShell
+    /*
+    The physical dir the `/_app/*` URLs map onto. Production reads the stable
+    `dist/_app`; under `abide dev` the orchestrator serves each build generation from
+    its own `_app.gen-<id>` dir and passes it as ABIDE_APP_DIR, so this worker serves
+    exactly the generation it was spawned on. A rebuild's replacement worker gets a
+    fresh dir while this one keeps reading its own, immutable for its lifetime — which
+    is why a retiring worker never 500s on chunks a rebuild would otherwise have
+    deleted. Must match the dir abideResolverPlugin rewrote the shell's entry ref from.
+    */
+    const appDir = process.env.ABIDE_APP_DIR ?? `${distDir}/_app`
     /*
     Boot-path disk scans run concurrently — they share no data, and under
     `abide dev` the worker-swap window is bounded by exactly this boot.
@@ -235,9 +214,20 @@ export async function createServer({
               })
             : undefined,
         createPublicAssetServer({ publicDir, publicAssets }),
-        createAppAssetServer({ distDir, assets }),
-        buildPreloadManifest({ distDir, assets }),
+        createAppAssetServer({ appDir, assets }),
+        buildPreloadManifest({ appDir, assets }),
     ])
+    /*
+    Diagnostic (DEBUG=abide:dev): one line recording what this worker actually serves —
+    its generation dir and the hashed client entry the shell points at. Pinning makes a
+    shell⇄disk mismatch structurally impossible (the entry always lives in appDir), so
+    this is confirmation/defense-in-depth, not a routine line: it stays off by default.
+    Dev only — an embedded standalone build has no on-disk generation dir.
+    */
+    if (dev && !assets) {
+        const entryRef = activeShell.match(/\/_app\/(client-[a-z0-9]+\.js)/i)?.[1] ?? 'client.js'
+        abideLog.channel('abide:dev')(`serving ${appDir.split('/').pop()} · entry ${entryRef}`)
+    }
     setRegistryManifests({ rpc, sockets, prompts })
     mcpResourceServerSlot.server = createMcpResourceServer({ resourcesDir, mcpResources })
     const cliName = cliProgramName ?? 'app'
@@ -246,17 +236,16 @@ export async function createServer({
     const appVersion = appInfo?.version ?? '0.0.0'
     /* The app's default log channel — every unchanneled record speaks as [appName]. */
     setAppName(appName)
+    /* The single health-payload builder, bound to this app's identity — shared by the
+       /__abide/health probe and the renderer's __SSR__ seed so the wire and seed can't drift. */
+    const healthPayloadFor = (request: Request) =>
+        buildHealthPayload(request, { app, appName, appVersion })
     /*
     Opt-in inspector (ABIDE_ENABLE_INSPECTOR=true): a dynamically-imported
     `@abide/inspector` handler, or undefined when the flag is off / the package
     isn't installed. Resolved at boot so the fetch route below can branch on it.
     */
     const inspectorHandler = await maybeMountInspector({ name: appName, version: appVersion })
-    /* Built on first request, then reused — the rpc registry is frozen after load.
-       Memoised as a promise so two concurrent cold requests share one build instead
-       of both building (the second otherwise clobbering the first). A rejected build
-       clears the memo so the next request retries rather than caching the failure. */
-    let openApiSpec: Promise<ReturnType<typeof buildOpenApiSpec>> | undefined
     const cliCwd = process.cwd()
 
     /* Request closing records are on by default — DEBUG=-abide is the off switch (negation, like the abide channel itself). */
@@ -305,7 +294,7 @@ export async function createServer({
         layouts,
         routePreloads,
         /* The wire payload, rebuilt per marked render — the __SSR__ health seed must match what /__abide/health serves. */
-        healthPayload: (request) => buildHealthPayload(request, { app, appName, appVersion }),
+        healthPayload: healthPayloadFor,
     })
 
     /*
@@ -319,32 +308,25 @@ export async function createServer({
     const buildRouteHandler = createRouteDispatcher({ pages, rpc, renderPage })
 
     /*
-    Handlers pre-bound per registered URL. rpc URLs are flat literals (always
-    `/rpc/...`), so they dispatch by direct lookup; page URLs carry `[name]` /
-    `[[name]]` / `[...rest]` segments and resolve through matchRoute. Page and
-    rpc URLs are disjoint by construction, so a request lands in exactly one.
+    URL-shape resolution — canonical-slash 308s, the openapi doc's build + memo,
+    and asset precedence (page routes shadow same-path public files; `/_app/`
+    before public/) — lives behind createAppRouteResolver. It composes the
+    dispatcher's per-URL handlers and returns a data-only decision the fetch
+    closure wires to its effect (ALS dispatch, asset serve, 404 render), so those
+    URL-shape decisions stay testable without booting Bun.serve. The openapi doc
+    is built from the frozen rpc registry, memoised across concurrent cold
+    requests, and cleared on a failed build so a later request retries.
     */
-    const rpcHandlers = new Map<string, ReturnType<typeof buildRouteHandler>>()
-    for (const routeUrl of Object.keys(rpc)) {
-        rpcHandlers.set(routeUrl, buildRouteHandler(routeUrl))
-    }
-    const pageHandlers = new Map<string, ReturnType<typeof buildRouteHandler>>()
-    for (const routeUrl of Object.keys(pages)) {
-        /* A `[...rest]` consumes every remaining segment, so segments after it
-           can never constrain matching — the route would silently serve paths
-           it shouldn't. Fail at boot instead. */
-        const segments = parseRouteSegments(routeUrl)
-        const catchAllIndex = segments.findIndex(
-            (segment) => segment.kind === 'param' && segment.catchAll,
-        )
-        if (catchAllIndex !== -1 && catchAllIndex !== segments.length - 1) {
-            throw new Error(
-                `[abide] invalid page route ${routeUrl}: a [...name] catch-all must be the last segment`,
-            )
-        }
-        pageHandlers.set(routeUrl, buildRouteHandler(routeUrl))
-    }
-    const pageRouteUrls = Object.keys(pages)
+    const resolveAppRoute = createAppRouteResolver({
+        pages,
+        rpc,
+        buildRouteHandler,
+        openApiPath: OPENAPI_PATH,
+        buildOpenApiDocument: () =>
+            ensureRegistriesLoaded().then(() =>
+                buildOpenApiSpec({ title: appName, version: appVersion }),
+            ),
+    })
 
     function dispatchRequest(
         req: Request,
@@ -376,6 +358,24 @@ export async function createServer({
     */
     const socketDispatcher = createSocketDispatcher(sockets)
 
+    /*
+    Framework HTTP surface — the health/identity probe, inspector, dev
+    channels, sockets upgrade + REST face, MCP, and CLI — resolved ahead of the
+    app's rpc/page routes. Returns PLUMBING_PASS for any path it doesn't own so
+    the fetch handler falls through to the app routes below.
+    */
+    const routePlumbing = createPlumbingRouter({
+        dev,
+        clientFingerprint,
+        inspectorHandler,
+        socketDispatcher,
+        mcp,
+        cliName,
+        cliCwd,
+        healthPayload: healthPayloadFor,
+        dispatchRequest,
+    })
+
     /*
     Bind the real server on `boundPort`. Only the port varies between scan
     attempts, so the rest of the config lives inline and just the port is spread
@@ -411,233 +411,31 @@ export async function createServer({
             async fetch(req, bunServer) {
                 const url = new URL(req.url)
                 /*
-                Health/identity probe — answered directly, ahead of any app.handle
-                middleware, so the bundle's connect screen, the CLI, and the client
-                health() can confirm a URL really is a live abide server even when
-                the app guards everything behind auth (reporting
-                `authenticated: false` requires exactly that). The app's optional
-                health hook contributes fields; the framework's identity keys win
-                on collision, and a thrown hook is logged and skipped so an app
-                bug can't masquerade as an unreachable server. IDENTITY_PATH is
-                the compatibility alias for the same payload.
-                */
-                if (url.pathname === HEALTH_PATH || url.pathname === IDENTITY_PATH) {
-                    const payload = await buildHealthPayload(req, { app, appName, appVersion })
-                    return gzipResponse(
-                        req,
-                        Response.json(
-                            /*
-                            The IDENTITY_PATH alias keeps the legacy `abide: true`
-                            shape: already-shipped probers check it with strict
-                            equality, and a version string would make them treat
-                            an upgraded healthy server as not-abide.
-                            */
-                            url.pathname === IDENTITY_PATH ? { ...payload, abide: true } : payload,
-                            { headers: { 'Cache-Control': NO_STORE } },
-                        ),
-                    )
-                }
-                /*
-                Inspector surface — answered directly, ahead of app.handle, since
-                it's privileged operator tooling gated by ABIDE_ENABLE_INSPECTOR
-                (not the app's user auth). Undefined handler = flag off, so the
-                whole block compiles out of the hot path when the inspector's off.
-                */
-                if (
-                    inspectorHandler &&
-                    (url.pathname === INSPECTOR_PATH ||
-                        url.pathname.startsWith(`${INSPECTOR_PATH}/`))
-                ) {
-                    // The events feed is long-lived SSE: opt it out of the idle
-                    // timeout, else Bun reaps it and the reconnect replays the
-                    // whole buffer (duplicate boot logs every ~10s).
-                    return disableIdleTimeoutForStream(
-                        bunServer,
-                        req,
-                        await inspectorHandler(req, url),
-                    )
-                }
-                /*
-                Dev live-reload channel — answered directly, ahead of app.handle,
-                so a restart-driven reconnect always lands even when the app guards
-                everything behind auth. Only mounted under `abide dev`.
-                */
-                if (clientFingerprint !== undefined && url.pathname === DEV_RELOAD_PATH) {
-                    // Long-lived SSE: opt out of the idle timeout, else Bun reaps
-                    // it and the reconnect triggers a spurious reload loop.
-                    return disableIdleTimeoutForStream(
-                        bunServer,
-                        req,
-                        devReloadResponse(clientFingerprint),
-                    )
-                }
-                /* Component hot module — the browser imports one edited `.abide`'s
-                   hot build here instead of reloading (dev component HMR). */
-                if (clientFingerprint !== undefined && url.pathname.startsWith(DEV_HOT_PREFIX)) {
-                    /* This endpoint serves `application/javascript` for the browser's
-                       `import()`. A TOP-LEVEL NAVIGATION to it — clicking the module link in a
-                       stack trace, or opening the URL — would DOWNLOAD the file, since browsers
-                       can't render JS as a document. A navigation sends `Accept: text/html`;
-                       `import()` sends a wildcard Accept. Redirect a navigation back to a real
-                       page (the referring page when same-origin, else the mount root) so the
-                       error surfaces in context as a normal render instead of saving a file. */
-                    if ((req.headers.get('accept') ?? '').includes('text/html')) {
-                        const referer = req.headers.get('referer')
-                        const page =
-                            referer !== null &&
-                            URL.canParse(referer) &&
-                            new URL(referer).origin === url.origin &&
-                            !new URL(referer).pathname.startsWith(DEV_HOT_PREFIX)
-                                ? referer
-                                : base || '/'
-                        return new Response(null, {
-                            status: 302,
-                            headers: { Location: page, 'Cache-Control': NO_STORE },
-                        })
-                    }
-                    return devHotModuleResponse(
-                        decodePathSegment(url.pathname.slice(DEV_HOT_PREFIX.length)),
-                    )
-                }
-                /*
-                Manual rebuild trigger: signal the orchestrator parent over IPC to
-                rebuild + restart. Same-origin sibling of the live-reload channel, so
-                a script refreshes on the app's own port. process.send exists only when
-                the dev orchestrator spawned us with ipc; the optional chain no-ops on a
-                bare server.
+                Framework HTTP surface — the health/identity probe, inspector,
+                the dev live-reload/rebuild channels, the sockets
+                upgrade and its SSE/JSON face, MCP, and CLI — resolved ahead of
+                the app's rpc/page routes (see createPlumbingRouter). Each answers
+                either directly (ahead of app.handle) or through dispatchRequest,
+                exactly as before. PLUMBING_PASS means the path is none of them, so
+                fall through to the app routes below.
                 */
-                if (dev && req.method === 'POST' && url.pathname === DEV_REBUILD_PATH) {
-                    process.send?.(DEV_REBUILD_MESSAGE)
-                    return new Response('rebuilding\n', {
-                        headers: { 'Content-Type': TEXT_PLAIN },
-                    })
-                }
-                if (url.pathname === SOCKETS_PATH) {
-                    // Reject cross-origin upgrades (CSWSH) before handing off to Bun.
-                    const upgradeForbidden = crossOriginGate(req, url)
-                    if (upgradeForbidden) {
-                        return upgradeForbidden
-                    }
-                    if (bunServer.upgrade(req, { data: {} })) {
-                        return undefined as unknown as Response
-                    }
-                    return new Response('Upgrade failed', {
-                        status: 400,
-                        headers: { 'Content-Type': TEXT_PLAIN },
-                    })
+                const plumbed = routePlumbing(req, url, bunServer)
+                if (plumbed !== PLUMBING_PASS) {
+                    return plumbed
                 }
                 /*
-                HTTP face of a socket (`/__abide/sockets/<name>`) — tail over
-                SSE / JSON and publish — for the CLI and MCP. Runs through
-                dispatchRequest so app.handle auth applies, like the rpc paths.
-                The socket name may contain `/` (nested files), so it's the
-                whole remaining pathname, percent-decoded.
+                App routes — the rpc-vs-page-vs-308-vs-asset URL-shape decision
+                lives behind createAppRouteResolver, resolved AFTER the `/__abide/*`
+                plumbing above (a reserved namespace no app route occupies). It
+                returns a data-only decision; the closure below is the thin wiring
+                that applies each to its effect.
                 */
-                if (url.pathname.startsWith(SOCKETS_REST_PREFIX)) {
-                    /*
-                    Gate cross-origin browser publishes (CSRF, see crossOriginGate).
-                    GET tail reads stay open cross-origin like rpc reads; only
-                    the mutating POST is gated.
-                    */
-                    const publishForbidden = crossOriginGate(req, url, { allowReadOnly: true })
-                    if (publishForbidden) {
-                        return publishForbidden
-                    }
-                    const name = decodePathSegment(url.pathname.slice(SOCKETS_REST_PREFIX.length))
-                    return dispatchRequest(
-                        req,
-                        {},
-                        async () => socketDispatcher.rest(req, name),
-                        url,
-                    )
-                }
-                if (url.pathname === MCP_PATH && mcp) {
-                    // Gate cross-site browser posts (CSRF, see crossOriginGate).
-                    const mcpForbidden = crossOriginGate(req, url)
-                    if (mcpForbidden) {
-                        return mcpForbidden
-                    }
-                    return dispatchRequest(req, {}, async () => mcp.handle(req), url)
+                const resolution = resolveAppRoute(req, url)
+                if (resolution.kind === 'handler') {
+                    return dispatchRequest(req, resolution.params, resolution.handler, url)
                 }
-                if (url.pathname === CLI_PATH) {
-                    return dispatchRequest(req, {}, async () => handleCliInstall(req, cliName), url)
-                }
-                if (url.pathname.startsWith(CLI_DOWNLOAD_PREFIX)) {
-                    const platform = url.pathname.slice(CLI_DOWNLOAD_PREFIX.length)
-                    return dispatchRequest(
-                        req,
-                        {},
-                        async () => handleCliDownload(req, platform, cliName, cliCwd),
-                        url,
-                    )
-                }
-                /*
-                App routes — rpc by flat lookup, pages through the shared
-                matcher (the client router runs the same one). Matched AFTER
-                the `/__abide/*` plumbing above (a reserved namespace no app
-                route occupies) and BEFORE the root-level framework surfaces
-                (/openapi.json, /_app/, public/ files), so a page route
-                shadows a same-path public file — the precedence the Bun
-                routes table used to impose implicitly, now pinned here.
-                */
-                const rpcHandler = rpcHandlers.get(url.pathname)
-                if (rpcHandler) {
-                    return dispatchRequest(req, {}, rpcHandler, url)
-                }
-                /*
-                Pages match only in canonical slash form; a non-canonical
-                request (`/admin/`, `//admin`) that would match is 308'd to the
-                canonical URL instead of served. Serving it directly would hand
-                app.handle — the auth seam — a pathname the matcher silently
-                normalized away, so an exact-match guard on `/admin` never sees
-                the request it's guarding (the old Bun routes table 404'd these
-                forms; the redirect keeps the guard sound AND the URL friendly).
-                rpc URLs stay exact-match strict, as they always were.
-                */
-                const canonicalPathname = normalizePathname(url.pathname)
-                if (canonicalPathname !== url.pathname) {
-                    if (matchRoute(pageRouteUrls, canonicalPathname)) {
-                        return new Response(null, {
-                            status: 308,
-                            headers: {
-                                Location: `${canonicalPathname}${url.search}`,
-                                'Cache-Control': NO_STORE,
-                            },
-                        })
-                    }
-                } else {
-                    const matchedPage = matchRoute(pageRouteUrls, url.pathname)
-                    if (matchedPage) {
-                        const pageHandler = pageHandlers.get(matchedPage.route)
-                        if (pageHandler) {
-                            return dispatchRequest(req, matchedPage.params, pageHandler, url)
-                        }
-                    }
-                }
-                if (url.pathname === OPENAPI_PATH) {
-                    return dispatchRequest(
-                        req,
-                        {},
-                        async () => {
-                            openApiSpec ??= ensureRegistriesLoaded()
-                                .then(() =>
-                                    buildOpenApiSpec({
-                                        title: appName,
-                                        version: appVersion,
-                                    }),
-                                )
-                                .catch((error) => {
-                                    // Don't cache a failed build — clear the memo so a
-                                    // later request retries instead of 500-ing forever.
-                                    openApiSpec = undefined
-                                    throw error
-                                })
-                            return Response.json(await openApiSpec, {
-                                headers: { 'Cache-Control': NO_STORE },
-                            })
-                        },
-                        url,
-                    )
+                if (resolution.kind === 'redirect') {
+                    return resolution.response
                 }
                 /*
                 Static assets sidestep ALS + the per-request CacheStore + the
@@ -646,7 +444,7 @@ export async function createServer({
                 dozens of chunks. The global server.error() handler still
                 catches anything that goes wrong inside serveAppAsset.
                 */
-                if (url.pathname.startsWith('/_app/')) {
+                if (resolution.kind === 'appAsset') {
                     return timedServe(() => serveAppAsset(req, url), req, url)
                 }
                 /*
@@ -669,13 +467,7 @@ export async function createServer({
                     req,
                     {},
                     async (_req, _pathParams, store) => {
-                        return (
-                            (await renderError(404, 'Not Found', store)) ??
-                            new Response('Not Found', {
-                                status: 404,
-                                headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
-                            })
-                        )
+                        return (await renderError(404, 'Not Found', store)) ?? textResponse(404)
                     },
                     url,
                 )
@@ -729,20 +521,6 @@ export async function createServer({
     process.once('SIGINT', shutdown)
     process.once('SIGTERM', shutdown)
 
-    /*
-    Diagnostic only, and only under `abide` debug logging — eager-loads the
-    registry to print the page/socket/rpc surface maps (routing + which
-    declarations reach mcp/cli/openapi), making abide's multimodal-by-default
-    exposure auditable. Awaited so `ready` lands after all of abide's own
-    startup output rather than interleaving with it.
-    */
-    if (logRequests) {
-        await logExposedSurfaces({ pages })
-    }
-    // Unguarded machine surface check — app.handle is the blessed auth seam.
-    if (mcp && !app?.handle) {
-        await warnUnguardedMcp()
-    }
     abideLog.success(`ready at http://localhost:${server.port}`)
     // Tell the dev orchestrator (when it spawned us with ipc) that boot is
     // complete, so it can retire the previous worker — finishing the
@@ -750,17 +528,35 @@ export async function createServer({
     if (dev) {
         process.send?.(DEV_READY_MESSAGE)
     }
-    return server
-}
-
-/* Lenient percent-decode for the internal-route names above (dev hot-module
-   paths, socket names) — the same leniency matchRoute applies to page params.
-   A malformed escape (`/%`) keeps the raw text so the downstream lookup misses
-   naturally instead of a URIError escaping the fetch handler as a 500. */
-function decodePathSegment(segment: string): string {
-    try {
-        return decodeURIComponent(segment)
-    } catch {
-        return segment
+    /* Unguarded machine surface check — app.handle is the blessed auth seam. Runs AFTER ready
+       like the surface map below: warnUnguardedMcp eager-loads the registry (building the rpc
+       ts.Program via the onLoad transform), so leaving it pre-ready would re-block boot for an
+       unguarded-MCP app. Guarded so the warning can't fell a now-ready worker. */
+    if (mcp && !app?.handle) {
+        try {
+            await warnUnguardedMcp()
+        } catch (error) {
+            abideLog.error(error)
+        }
+    }
+    /*
+    Diagnostic surface map (on by default via `logRequests`; opt out with DEBUG=-abide):
+    eager-loads the registry to
+    print the page/socket/rpc surface (routing + which declarations reach mcp/cli/openapi),
+    making abide's multimodal-by-default exposure auditable. It runs AFTER the ready signal
+    because that eager load imports every rpc/socket module — which builds the rpc ts.Program
+    via the onLoad transform — ~1.4s that used to block readiness on EVERY dev worker boot.
+    The server is already listening, so printing it now costs nothing off time-to-ready, and
+    the registry (and its program) stays lazy on the reload hot path. In dev only the first
+    worker prints it (ABIDE_DEV_SURFACE, set by the orchestrator) — a respawn's surface is
+    identical. Guarded: a diagnostic failure must never fell a now-ready worker.
+    */
+    if (logRequests && (!dev || process.env.ABIDE_DEV_SURFACE === '1')) {
+        try {
+            await logExposedSurfaces({ pages })
+        } catch (error) {
+            abideLog.error(error)
+        }
     }
+    return server
 }