tina4-nodejs 3.13.94 → 3.13.95

package/packages/core/src/server.ts

@@ -12,15 +12,20 @@ import { Router, defaultRouter, runRouteMiddlewares } from "./router.js";
 import { enforceRouteAuth } from "./authGate.js";
 import { discoverRoutes } from "./routeDiscovery.js";
 import { createRequest } from "./request.js";
+import {
+  resetRequestCaches,
+  headStripIntercept,
+  sessionAutoStart,
+} from "./dispatchPipeline.js";
 import { createResponse, setDefaultTemplatesDir } from "./response.js";
-import { MiddlewareChain, MiddlewareRunner, cors, requestLogger } from "./middleware.js";
+import { MiddlewareChain, MiddlewareRunner, cors, requestLogger, isMiddlewareClass } from "./middleware.js";
 import { tryServeStatic } from "./static.js";
 import { loadEnv, isTruthy } from "./dotenv.js";
 import { createHealthRoutes } from "./health.js";
 import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
 import { DevAdmin, RequestInspector, WsTracker } from "./devAdmin.js";
-import { devReloadWs, serveWebSocketRoute, wsRouteManager } from "./websocket.js";
+import { CLOSE_GOING_AWAY, devReloadWs, serveWebSocketRoute, wsRouteManager } from "./websocket.js";
 import { feedbackEnabled, injectFeedbackWidget } from "./feedback.js";
 import { I18n } from "./i18n.js";
 import { stopAllBackgroundTasks } from "./background.js";
@@ -55,6 +60,34 @@ function isSwaggerAssetPath(pathname: string): boolean {
   return pathname === "/swagger" || pathname.startsWith("/swagger/");
 }
 
+/** How long a graceful shutdown waits for in-flight requests, in seconds. */
+export const DEFAULT_SHUTDOWN_TIMEOUT_SECONDS = 30;
+
+/**
+ * Resolve the shutdown budget from `TINA4_SHUTDOWN_TIMEOUT` (seconds).
+ *
+ * 30s matches Kubernetes' default `terminationGracePeriodSeconds` and
+ * Gunicorn's `graceful_timeout`, so the drain finishes just BEFORE the
+ * orchestrator's SIGKILL rather than being truncated by it. Same env var and
+ * same default as tina4-ruby's `Tina4::Shutdown`.
+ *
+ * A non-numeric or negative value falls back to the default rather than
+ * silently disabling the drain - a typo must not turn shutdown into a
+ * zero-second force-kill.
+ */
+export function shutdownTimeoutSeconds(): number {
+  const raw = process.env.TINA4_SHUTDOWN_TIMEOUT;
+  if (raw === undefined || raw.trim() === "") return DEFAULT_SHUTDOWN_TIMEOUT_SECONDS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    Log.warning(
+      `TINA4_SHUTDOWN_TIMEOUT="${raw}" is not a valid number of seconds - using ${DEFAULT_SHUTDOWN_TIMEOUT_SECONDS}`,
+    );
+    return DEFAULT_SHUTDOWN_TIMEOUT_SECONDS;
+  }
+  return parsed;
+}
+
 /**
  * Build the startup banner's optional surface lines (issue #99).
  *
@@ -754,7 +787,6 @@ let _dispatchFn: ((rawReq: IncomingMessage, rawRes: ServerResponse) => Promise<v
 // not installed). Memoised so the dynamic import happens once, then every
 // request reuses the resolved function — see the request-scoped cache boundary
 // in dispatch().
-let _resetRequestCaches: Promise<(() => void) | null> | undefined;
 
 /** Module-level server handle for start()/stop() parity. */
 let _serverHandle: { close: () => void; router: Router; port: number } | null = null;
@@ -809,6 +841,526 @@ export async function handle(rawReq: IncomingMessage, rawRes: ServerResponse): P
   return _dispatchFn(rawReq, rawRes);
 }
 
+/**
+ * Run one global-middleware pass.
+ *
+ * The pre-match and post-match passes had byte-identical bodies; this is that
+ * body, once.
+ *
+ * AFTER-ON-4xx RULE (M2): the after_* hooks ALWAYS run when a before_*
+ * short-circuited (4xx, a clean 500, or the response already ended), so they
+ * can still add headers and logging. Consistent across all four frameworks.
+ *
+ * @returns true when the pass answered the request and the handler must be skipped
+ */
+async function runGlobalMiddlewarePass(
+  middleware: unknown[],
+  req: Tina4Request,
+  res: Tina4Response,
+): Promise<boolean> {
+  if (middleware.length === 0) return false;
+
+  const [, , proceed] = await MiddlewareRunner.runBefore(middleware as never, req, res);
+  if (proceed && !res.raw.writableEnded) return false;
+
+  await MiddlewareRunner.runAfter(middleware as never, req, res);
+  if (!res.raw.writableEnded) res.raw.end();
+  return true;
+}
+
+/**
+ * Invoke a matched route's handler, binding path params BY NAME.
+ *
+ * A handler declares whatever it needs - `(id, request, response)`, `(req, res)`,
+ * or nothing - and each parameter is resolved by its name: a path param wins,
+ * then `request`/`req`, then the response.
+ */
+async function invokeRouteHandler(
+  match: { handler: unknown },
+  req: Tina4Request,
+  res: Tina4Response,
+): Promise<unknown> {
+  const routeParams = req.params || {};
+  const fnStr = (match.handler as { toString(): string }).toString();
+  const argMatch = fnStr.match(/^(?:async\s*)?(?:function\s*\w*)?\s*\(([^)]*)\)/);
+  const argNames = argMatch?.[1]?.split(",").map((a: string) => a.trim().replace(/[:=].*/, "")) ?? [];
+  const filteredArgs = argNames.filter((n: string) => n.length > 0);
+
+  if (filteredArgs.length === 0) return await (match.handler as any)();
+
+  const args = filteredArgs.map((name: string) => {
+    if (name in routeParams) return routeParams[name];
+    if (name === "request" || name === "req") return req;
+    return res;
+  });
+  return await (match.handler as any)(...args);
+}
+
+/**
+ * Render a template route's return value, when it is one.
+ *
+ * A route that exports a template AND whose handler returned a plain object
+ * renders through the template engine instead of being sent as JSON. Every
+ * other shape - a handler that already wrote, no template, null/undefined, a
+ * string, a Buffer - is left exactly as it was.
+ */
+async function renderIfTemplateRoute(
+  match: { template?: string },
+  res: Tina4Response,
+  result: unknown,
+): Promise<void> {
+  if (res.raw.writableEnded) return;
+  if (!match.template) return;
+  if (result === null || result === undefined) return;
+  if (typeof result !== "object" || Buffer.isBuffer(result)) return;
+
+  await res.render(match.template, result as Record<string, unknown>);
+}
+
+/** State the matched-route pipeline needs. */
+interface MatchedRouteContext {
+  req: Tina4Request;
+  res: Tina4Response;
+  pathname: string;
+  match: { params?: Record<string, unknown>; handler: unknown; template?: string; middlewares?: unknown[] };
+  postMatchMiddleware: unknown[];
+  /**
+   * EVERY global middleware, both phases. The after pass runs over all of it,
+   * not just the post-match group - see runMatchedRoute.
+   */
+  allGlobalMiddleware: unknown[];
+}
+
+/**
+ * Run a matched route end to end.
+ *
+ * Order, and it is BEHAVIOUR (ADR-0012):
+ *   post-match globals -> auth gate -> the route's own middleware -> handler
+ *
+ * The globals run BEFORE the gate so a rate limiter can throttle a brute-force
+ * login and an access log records the 401 - neither is possible if they only
+ * run on authenticated requests (Django enforces auth in a view decorator after
+ * all MIDDLEWARE; Laravel's `web` group runs before the `auth` route
+ * middleware; ASP.NET puts UseAuthorization last before the endpoint).
+ *
+ * The route's OWN middleware runs AFTER, so middleware attached to a secured
+ * route never processes an unauthenticated request. Node used to run it first,
+ * which meant a body-parsing or audit middleware on a secured route saw traffic
+ * that was about to be rejected.
+ */
+async function runMatchedRoute(ctx: MatchedRouteContext): Promise<void> {
+  const { req, res, match, postMatchMiddleware } = ctx;
+  req.params = match.params as never;
+
+  if (await runGlobalMiddlewarePass(postMatchMiddleware, req, res)) return;
+
+  // Auth enforcement lives in enforceRouteAuth (authGate.ts) so the in-process
+  // TestClient enforces the EXACT same gate - parity with Python #PY2, where a
+  // tokenless write must 401 in tests too, or a green test hides a live 401.
+  // Dev admin routes (/__dev) are always public.
+  if (enforceRouteAuth(req, res, match as never, ctx.pathname.startsWith("/__dev"))) return;
+
+  // The route's OWN class middleware: its beforeX hooks run inside
+  // runRouteMiddlewares, its afterX hooks join the after pass below - one
+  // effective list for the response phase, the way Python merges the globals
+  // and the route's middleware into `_effective_middleware` for both passes.
+  const routeMiddlewareClasses = (match.middlewares ?? []).filter(isMiddlewareClass);
+
+  let handlerSkipped = false;
+  if (match.middlewares && match.middlewares.length > 0) {
+    const proceed = await runRouteMiddlewares(match.middlewares as never, req, res);
+    handlerSkipped = !proceed || res.raw.writableEnded;
+  }
+
+  if (!handlerSkipped) {
+    await renderIfTemplateRoute(match, res, await invokeRouteHandler(match, req, res));
+  }
+
+  // Global afterX hooks (logging / post-processing), over EVERY global
+  // middleware - both phases, not just the post-match group - PLUS the route's
+  // own middleware classes.
+  //
+  // The response phase must cover everything the request phase entered, so it
+  // also runs when the ROUTE's middleware short-circuited - the after hooks of a
+  // middleware whose before hook denied the request are exactly what add the
+  // headers and the access-log line for that denial. Dispatch used to return
+  // early there, so a cache HIT (a route middleware that answers and ends)
+  // skipped every global after hook, and a route middleware that short-circuited
+  // WITHOUT ending the response left the request hanging with no end() at all.
+  //
+  // Running only the post-match group meant a `preMatch` middleware's afterX NEVER ran
+  // on a successful request: measured 0 runs in 5 requests. An acquire/release
+  // pair leaked one slot per request, unbounded; a timer started in beforeX was
+  // never stopped; an access log saw the request and never the response - the
+  // very hole ADR-0012 moved the globals ahead of the auth gate to close.
+  //
+  // Worse, it inverted: the pre-match afterX DID run when the pre-match pass
+  // short-circuited, so it fired on the error path and not the happy one.
+  //
+  // Django unwinds its single MIDDLEWARE list in reverse, Laravel runs the
+  // response/terminate phase for global, group AND route middleware, Rails runs
+  // every declared after_action, ASP.NET unwinds through every component
+  // entered. Ruby and PHP already did this. Splitting the BEFORE pass by
+  // dependency (ADR-0012) says nothing about the after pass: an after hook adds
+  // headers or logging and needs no route metadata either way.
+  //
+  // No double-run: when the pre-match pass short-circuits, dispatch returns
+  // before ever reaching this.
+  //
+  // Header mutations here are no-ops once the response is flushed - Node sends
+  // headers with the body - so response headers belong in beforeX.
+  const afterMiddleware = [...ctx.allGlobalMiddleware, ...routeMiddlewareClasses];
+  if (afterMiddleware.length > 0) {
+    await MiddlewareRunner.runAfter(afterMiddleware as never, req, res);
+  }
+
+  if (!res.raw.writableEnded) res.raw.end();
+}
+
+/** State the response-end wrappers need. */
+interface ResponseWrapContext {
+  req: Tina4Request;
+  res: Tina4Response;
+  pathname: string;
+  router: Router;
+  reqStartTime: number;
+  requestId: string;
+  /** Holder, because the wrapper reads this at end() time - after route matching. */
+  matchedPattern: { value: string };
+  isAiPortRequest: boolean;
+}
+
+/**
+ * Block /__dev_reload on the AI port so AI tools never trigger a browser reload.
+ *
+ * @returns true when the request was answered
+ */
+function blockAiPortReload(res: Tina4Response, pathname: string, isAiPortRequest: boolean): boolean {
+  if (!isAiPortRequest || pathname !== "/__dev_reload") return false;
+
+  res.raw.writeHead(404, { "Content-Type": "application/json" });
+  res.raw.end(JSON.stringify({ error: "Not available on AI port" }));
+  return true;
+}
+
+/**
+ * Rebuild the arguments `end` was called with.
+ *
+ * Node's `end` has three overloads and the wrappers must forward exactly the
+ * shape they were given, or a callback lands in the encoding slot.
+ */
+function callOriginalEnd(
+  originalEnd: (...args: any[]) => any,
+  chunk: unknown,
+  encodingOrCb?: BufferEncoding | (() => void),
+  cb?: () => void,
+): any {
+  if (typeof encodingOrCb === "function") return originalEnd(chunk, encodingOrCb);
+  if (encodingOrCb !== undefined) return originalEnd(chunk, encodingOrCb, cb);
+  return originalEnd(chunk, cb);
+}
+
+/** Whether the response is declaring itself as HTML. */
+function isHtmlResponse(res: Tina4Response): boolean {
+  const contentType = res.raw.getHeader("content-type");
+  return typeof contentType === "string" && contentType.includes("text/html");
+}
+
+/** The chunk as an HTML string, or null when it is neither a string nor a Buffer. */
+function asHtmlString(chunk: unknown): string | null {
+  if (typeof chunk === "string") return chunk;
+  if (Buffer.isBuffer(chunk)) return chunk.toString("utf-8");
+  return null;
+}
+
+/**
+ * Inject the dev toolbar (dev mode only) and the feedback widget into an HTML body.
+ *
+ * The feedback injector re-checks the whitelist, path and html marker itself,
+ * so calling it unconditionally is cheap when it no-ops.
+ */
+function injectIntoHtml(ctx: ResponseWrapContext, devToolbar: boolean, html: string): string {
+  if (!devToolbar) return injectFeedbackWidget(ctx.req, html);
+
+  const toolbarCtx: DevToolbarContext = {
+    version: TINA4_VERSION,
+    method: ctx.req.method ?? "GET",
+    path: ctx.pathname,
+    matchedPattern: ctx.matchedPattern.value || ctx.pathname,
+    requestId: ctx.requestId,
+    routeCount: ctx.router.getRoutes().length,
+  };
+  return injectFeedbackWidget(ctx.req, injectDevToolbar(html, toolbarCtx));
+}
+
+/**
+ * Wrap `res.raw.end` to inject the dev toolbar and/or the feedback widget, and
+ * to capture the request for the dev inspector.
+ *
+ * Two modes, and the distinction is deliberate:
+ *   * dev mode (off the AI port, outside /__dev) gets the toolbar, the feedback
+ *     widget and inspector capture;
+ *   * otherwise a whitelisted user still gets the feedback widget alone. The
+ *     injector re-checks the whitelist, path and html marker itself, so the
+ *     wrapper is cheap when it no-ops.
+ *
+ * Content-Length is removed on injection because the body size changes.
+ */
+function wrapResponseEnd(ctx: ResponseWrapContext): void {
+  const { req, res, pathname } = ctx;
+  const devToolbar = isDevMode() && !pathname.startsWith("/__dev") && !ctx.isAiPortRequest;
+  const feedbackOnly =
+    !devToolbar &&
+    feedbackEnabled() &&
+    !pathname.startsWith("/__dev") &&
+    !pathname.startsWith("/__feedback");
+
+  if (!devToolbar && !feedbackOnly) return;
+
+  const originalEnd = res.raw.end.bind(res.raw);
+  res.raw.end = function (
+    chunk?: unknown,
+    encodingOrCb?: BufferEncoding | (() => void),
+    cb?: () => void,
+  ) {
+    if (devToolbar && ctx.reqStartTime > 0) {
+      RequestInspector.capture(
+        req.method ?? "GET",
+        pathname,
+        res.raw.statusCode ?? 200,
+        Date.now() - ctx.reqStartTime,
+      );
+    }
+
+    if (isHtmlResponse(res)) {
+      const html = asHtmlString(chunk);
+      if (html !== null) chunk = injectIntoHtml(ctx, devToolbar, html);
+      // Dropped for ANY html response, not only one carrying a body: that is
+      // what the two original wrappers did, and a refactor does not get to
+      // narrow it. An end() with no chunk on a text/html response still has
+      // its stale content-length removed.
+      if (!res.raw.headersSent) res.raw.removeHeader("content-length");
+    }
+
+    return callOriginalEnd(originalEnd, chunk, encodingOrCb, cb);
+  } as typeof res.raw.end;
+}
+
+/**
+ * Turn an uncaught dispatch error into a response, and surface it.
+ *
+ * v3.13.7: log structured + surface to observability BEFORE rendering.
+ * Listeners get the canonical {exception, request} payload mirrored by Python /
+ * PHP / Ruby. Listener errors are swallowed and warning-logged so a broken
+ * listener cannot break the 500 page.
+ *
+ * SECURITY (CWE-209): the production response body must NOT contain the stack
+ * trace or the exception message. `error_message` is passed empty - 500.twig
+ * only renders the trace block when it is truthy. The rich overlay with stack
+ * and source context is dev-only.
+ *
+ * @param err          The thrown value (not necessarily an Error)
+ * @param req          The request, for the log line and the error page
+ * @param res          The response; untouched if it has already ended
+ * @param templatesDir Where to look for 500.twig
+ */
+async function renderDispatchError(
+  err: unknown,
+  req: Tina4Request,
+  res: Tina4Response,
+  templatesDir: string,
+): Promise<void> {
+  Log.error(`Route error: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`, {
+    method: req?.method,
+    path: req?.path,
+  });
+
+  try {
+    const { Events } = await import("./events.js");
+    Events.emit("tina4.request.error", { exception: err, request: req });
+  } catch (listenerErr) {
+    try {
+      Log.warn(
+        `Listener for tina4.request.error raised: ${
+          listenerErr instanceof Error
+            ? `${listenerErr.name}: ${listenerErr.message}`
+            : String(listenerErr)
+        }`
+      );
+    } catch {
+      // Log failures must never block the 500 render.
+    }
+  }
+
+  if (res.raw.writableEnded) return;
+
+  if (isDevMode() && err instanceof Error) {
+    // Rich error overlay with stack trace, source context, and line numbers
+    const { renderErrorOverlay } = await import("./errorOverlay.js");
+    res.raw.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });
+    res.raw.end(renderErrorOverlay(err, req));
+    return;
+  }
+
+  const html500 = await renderErrorPage(500, {
+    error_message: "",
+    request_id: `${Date.now().toString(36)}`,
+    path: req.path,
+  }, templatesDir);
+  if (html500) {
+    res.raw.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });
+    res.raw.end(html500);
+  } else {
+    res({ error: "Internal Server Error", statusCode: 500 }, 500);
+  }
+}
+
+/**
+ * State the not-found fallback stages need.
+ *
+ * Passed explicitly rather than closed over, so each stage is callable on its
+ * own instead of only from inside `dispatch`. That coupling is what the
+ * extraction removes.
+ */
+interface FallbackContext {
+  req: Tina4Request;
+  res: Tina4Response;
+  pathname: string;
+  router: Router;
+  port: number;
+  staticDir: string;
+  srcPublicDir: string;
+  templatesDir: string;
+  frondEngine: { render(file: string, data: Record<string, unknown>): string } | null;
+  swaggerAssetsEnabled: boolean;
+}
+
+/**
+ * Serve a template file for a GET (e.g. /hello -> src/templates/pages/hello.twig).
+ *
+ * Rendered through Frond so {% include %} / {% extends %} work, rather than a
+ * raw readFileSync.
+ */
+function serveTemplateFallback(ctx: FallbackContext): boolean {
+  if ((ctx.req.method ?? "GET") !== "GET") return false;
+
+  const tplFile = resolveTemplate(ctx.pathname, ctx.templatesDir);
+  if (!tplFile) return false;
+
+  const html = ctx.frondEngine
+    ? ctx.frondEngine.render(tplFile, {})
+    : readFileSync(resolve(ctx.templatesDir, tplFile), "utf-8");
+  ctx.res.raw.writeHead(200, undefined, { "Content-Type": "text/html; charset=utf-8" });
+  ctx.res.raw.end(html);
+  return true;
+}
+
+/**
+ * The branded landing page.
+ *
+ * Renders only at "/" AND only when TINA4_DEBUG=true. In production "/" with no
+ * static index.html and no pages/index.twig falls through to a clean 404, so
+ * the framework's welcome, gallery and version never leak to real users.
+ */
+function serveLandingPage(ctx: FallbackContext): boolean {
+  if ((ctx.req.method ?? "GET") !== "GET") return false;
+  if (ctx.pathname !== "/" || !isDevMode()) return false;
+
+  const allRoutes = ctx.router.getRoutes().map((r) => ({
+    method: r.method,
+    pattern: r.pattern,
+    flags: [] as string[],
+  }));
+  ctx.res.raw.writeHead(200, undefined, { "Content-Type": "text/html; charset=utf-8" });
+  ctx.res.raw.end(renderLandingPage(allRoutes, ctx.port));
+  return true;
+}
+
+/**
+ * RFC 9110 conformance - before falling through to 404, check whether the PATH
+ * is registered under any OTHER method.
+ *   - OPTIONS -> 204 with Allow (s9.3.7)
+ *   - Any other method (PUT on GET-only, TRACE, CONNECT) -> 405 with Allow
+ *     (s15.5.6 + s10.2.1)
+ */
+function serveMethodNotAllowed(ctx: FallbackContext): boolean {
+  const allowedMethods = ctx.router.methodsAllowedForPath(ctx.pathname);
+  if (allowedMethods.length === 0) return false;
+
+  const allowHeader = allowedMethods.join(", ");
+  const requestMethod = (ctx.req.method ?? "GET").toUpperCase();
+
+  if (requestMethod === "OPTIONS") {
+    ctx.res.raw.writeHead(204, undefined, { Allow: allowHeader, "Content-Length": "0" });
+    ctx.res.raw.end();
+    return true;
+  }
+
+  const body = JSON.stringify({
+    error: "Method Not Allowed",
+    path: ctx.pathname,
+    method: requestMethod,
+    allow: allowedMethods,
+    statusCode: 405,
+  });
+  ctx.res.raw.writeHead(405, httpReason(405), {
+    Allow: allowHeader,
+    "Content-Type": "application/json",
+    "Content-Length": String(Buffer.byteLength(body)),
+  });
+  ctx.res.raw.end(body);
+  return true;
+}
+
+/**
+ * No route claimed the path, so NOW try the filesystem (ADR-0010).
+ *
+ * Index resolution: "/" or "/foo/" picks up index.html so SPA builds Just Work.
+ * The framework-bundled directory holds the Swagger UI (public/swagger/), so
+ * that lookup MUST honour the swagger gate or /swagger is served in production
+ * regardless of TINA4_SWAGGER_ENABLED / TINA4_DEBUG.
+ */
+function serveStaticAsset(ctx: FallbackContext): boolean {
+  if (existsSync(ctx.staticDir) && tryServeStatic(ctx.staticDir, ctx.req, ctx.res)) return true;
+  if (existsSync(ctx.srcPublicDir) && tryServeStatic(ctx.srcPublicDir, ctx.req, ctx.res)) return true;
+
+  if (ctx.swaggerAssetsEnabled || !isSwaggerAssetPath(ctx.pathname)) {
+    if (tryServeStatic(BUILTIN_PUBLIC_DIR, ctx.req, ctx.res)) return true;
+  }
+  return false;
+}
+
+/** Terminal stage: 404, with the canonical reason phrase so the status line is well-formed. */
+async function serveNotFound(ctx: FallbackContext): Promise<boolean> {
+  const html404 = await renderErrorPage(404, { path: ctx.pathname }, ctx.templatesDir);
+  if (html404) {
+    ctx.res.raw.writeHead(404, httpReason(404), { "Content-Type": "text/html; charset=utf-8" });
+    ctx.res.raw.end(html404);
+  } else {
+    ctx.res(
+      { error: "Not Found", statusCode: 404, message: `No route found for ${ctx.req.method} ${ctx.pathname}` },
+      404,
+    );
+  }
+  return true;
+}
+
+/**
+ * The not-found fallback chain, in order. Data, so the pipeline can be read and
+ * compared across frameworks without reading an implementation.
+ *
+ * Order is BEHAVIOUR: a template beats the landing page (so a project's own
+ * pages/index.twig wins at "/"), 405 beats static (a known path with the wrong
+ * method is not a missing file), and the 404 is terminal.
+ */
+const FALLBACK_STAGES: Array<(ctx: FallbackContext) => boolean | Promise<boolean>> = [
+  serveTemplateFallback,
+  serveLandingPage,
+  serveMethodNotAllowed,
+  serveStaticAsset,
+  serveNotFound,
+];
+
 export async function startServer(config?: Tina4Config): Promise<{
   close: () => void;
   router: Router;
@@ -1128,108 +1680,25 @@ ${reset}
     const req = createRequest(rawReq);
     const res = createResponse(rawRes);
 
-    // Request-scoped DB query cache boundary: clear the request-scoped cache on
-    // every live connection at the START of each request so it never serves
-    // rows across requests (persistent-mode connections are left alone). The
-    // ORM is loaded lazily and may be absent — failures here must never break a
-    // request, so this is best-effort. Mirrors Python's dispatcher calling
-    // Database.reset_request_caches(). The cached() promise resolves once on
-    // first use; subsequent requests reuse the resolved module.
-    if (_resetRequestCaches === undefined) {
-      _resetRequestCaches = import("../../orm/src/index.js")
-        .then((orm) => orm.resetRequestCaches as () => void)
-        .catch(() => null);
-    }
-    try {
-      const reset = await _resetRequestCaches;
-      if (reset) reset();
-    } catch {
-      /* ORM not installed / cache unavailable — non-fatal */
-    }
-
-    // RFC 9110 §9.3.2: the server MUST NOT send content in a HEAD response.
-    // Intercept rawRes.write / rawRes.end so every code path — explicit
-    // Router.head() handler, GET auto-fallback, 405 / 404 responses — drops
-    // its body. Content-Length is preserved when present, so cache
-    // validators / link checkers / monitoring probes still see the size
-    // the equivalent GET would have sent.
-    if ((rawReq.method ?? "GET").toUpperCase() === "HEAD") {
-      const origEnd = rawRes.end.bind(rawRes);
-      const origWrite = rawRes.write.bind(rawRes);
-      let accumulated = 0;
-      rawRes.write = ((chunk?: any, _enc?: any, cb?: any): boolean => {
-        if (chunk != null) {
-          accumulated += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk));
-        }
-        if (typeof cb === "function") cb();
-        return true;
-      }) as typeof rawRes.write;
-      rawRes.end = ((chunk?: any, _enc?: any, cb?: any): any => {
-        if (chunk != null && typeof chunk !== "function") {
-          accumulated += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk));
-        }
-        if (accumulated > 0 && !rawRes.headersSent && !rawRes.hasHeader("Content-Length")) {
-          rawRes.setHeader("Content-Length", String(accumulated));
-        }
-        const realCb = typeof chunk === "function" ? chunk : cb;
-        void origWrite; // referenced to keep tsc happy
-        return typeof realCb === "function" ? origEnd(realCb) : origEnd();
-      }) as typeof rawRes.end;
-    }
-
-    // Auto-start session — read cookie, create session, save + set cookie on response end
-    {
-      const { Session, buildSessionCookie, sessionCookieName } = await import("./session.js");
-      const cookieHeader = rawReq.headers.cookie ?? "";
-      // Read the incoming session cookie by the SAME configured name the write
-      // side emits (TINA4_SESSION_NAME, default tina4_session) via the shared
-      // sessionCookieName() resolver — otherwise a renamed cookie would be
-      // written but never read back and the session would silently never
-      // resume. Match a whole cookie pair by its exact `name=` prefix (split on
-      // ";", trim, startsWith) so `tina4_session` never matches
-      // `tina4_session_foo=` nor a value mid-header. Parity with Python
-      // core/server._init_session.
-      const cookiePrefix = sessionCookieName() + "=";
-      let existingSid: string | undefined;
-      for (const part of cookieHeader.split(";")) {
-        const trimmed = part.trim();
-        if (trimmed.startsWith(cookiePrefix)) {
-          existingSid = trimmed.slice(cookiePrefix.length);
-          break;
-        }
-      }
-      const sess = new Session();
-      sess.start(existingSid);
-      (req as any).session = sess;
-
-      const origEnd = rawRes.end.bind(rawRes);
-      rawRes.end = function (...args: any[]) {
-        sess.save();
-
-        // Probabilistic garbage collection (~1% of requests)
-        if (Math.floor(Math.random() * 100) === 0) {
-          try { sess.gc(); } catch { /* GC failure is non-critical */ }
-        }
-
-        const newSid = (sess as any).sessionId ?? (sess as any).getSessionId?.();
-        if (newSid && newSid !== existingSid && !rawRes.headersSent) {
-          const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-          // Thread the client's real scheme in so an HTTPS deploy behind a
-          // TLS-terminating proxy ships the session cookie with `Secure`
-          // (nodejs#34). `x-forwarded-proto` is the same header request.ts
-          // trusts for URL construction; native socket TLS is the fallback.
-          const xfProto = rawReq.headers["x-forwarded-proto"];
-          const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
-          const socketEncrypted = (rawReq.socket as { encrypted?: boolean })?.encrypted === true;
-          rawRes.setHeader("Set-Cookie", buildSessionCookie(newSid, ttl, undefined, forwardedProto, socketEncrypted));
-        }
-        return origEnd(...args);
-      } as typeof rawRes.end;
-    }
+    // PROLOGUE STAGES. Extracted to dispatchPipeline.ts - see PROLOGUE_STAGES
+    // there for the ordered list and why the order is behaviour, not taste.
+    // These three close over nothing from startServer, which is why they went
+    // first: no context object is needed for them at all.
+    await resetRequestCaches();
+    headStripIntercept(rawReq, rawRes);
 
     // res.render() is handled natively by response.ts via Frond
 
     try {
+      // sessionAutoStart is the one prologue stage INSIDE the try. It degrades
+      // on its own (ADR-0021), so the only thing that escapes it is a
+      // TINA4_SESSION_STRICT refusal - and that must become a 500 through the
+      // normal error renderer, like Python's raise becomes a 500 in the ASGI
+      // server. Outside the try it rejected `dispatch`, and nothing awaits the
+      // listener http.createServer() calls: an unhandled rejection that takes
+      // the whole worker down is not "refuse this request".
+      await sessionAutoStart(rawReq, rawRes, req);
+
       // Run middleware chain
       await middleware.run(req, res);
       if (res.raw.writableEnded) return;
@@ -1243,334 +1712,68 @@ ${reset}
       const reqStartTime = DevAdmin.isEnabled() ? Date.now() : 0;
 
       // Mutable ref so wrappedEnd can read the matched pattern after route matching
-      let matchedPattern = "";
+      // A HOLDER, not a plain string: the end-wrapper below reads it at end()
+      // time, after route matching has assigned it.
+      const matchedPattern = { value: "" };
       const requestId = Date.now().toString(36);
 
       // Wrap res.raw.end to inject dev toolbar and capture requests
       // Skip toolbar injection on the AI port (no-reload behaviour)
       const isAiPortRequest = !!(rawReq as any)._tina4AiPort;
 
-      // AI port: block /__dev_reload so AI tools never trigger a browser reload
-      if (isAiPortRequest && pathname === "/__dev_reload") {
-        res.raw.writeHead(404, { "Content-Type": "application/json" });
-        res.raw.end(JSON.stringify({ error: "Not available on AI port" }));
-        return;
-      }
+      // AI port: block /__dev_reload so AI tools never trigger a browser reload.
+      if (blockAiPortReload(res, pathname, isAiPortRequest)) return;
 
-      if (isDevMode() && !pathname.startsWith("/__dev") && !isAiPortRequest) {
-        const originalEnd = res.raw.end.bind(res.raw);
-
-        const wrappedEnd: typeof res.raw.end = function (
-          chunk?: unknown,
-          encodingOrCb?: BufferEncoding | (() => void),
-          cb?: () => void,
-        ) {
-          // Capture request for dev inspector
-          if (reqStartTime > 0) {
-            const duration = Date.now() - reqStartTime;
-            const status = res.raw.statusCode ?? 200;
-            RequestInspector.capture(req.method ?? "GET", pathname, status, duration);
-          }
+      // Wrap res.raw.end so the dev toolbar / feedback widget can be injected
+      // and the request captured for the inspector. Extracted - see
+      // wrapResponseEnd. matchedPattern is a HOLDER because the wrapper reads
+      // it at end() time, long after route matching has assigned it.
+      wrapResponseEnd({
+        req, res, pathname, router,
+        reqStartTime, requestId, matchedPattern, isAiPortRequest,
+      });
 
-          const contentType = res.raw.getHeader("content-type");
-          if (typeof contentType === "string" && contentType.includes("text/html")) {
-            const toolbarCtx: DevToolbarContext = {
-              version: TINA4_VERSION,
-              method: req.method ?? "GET",
-              path: pathname,
-              matchedPattern: matchedPattern || pathname,
-              requestId,
-              routeCount: router.getRoutes().length,
-            };
-            if (typeof chunk === "string") {
-              chunk = injectDevToolbar(chunk, toolbarCtx);
-              chunk = injectFeedbackWidget(req, chunk as string);
-            } else if (Buffer.isBuffer(chunk)) {
-              const html = chunk.toString("utf-8");
-              chunk = injectFeedbackWidget(req, injectDevToolbar(html, toolbarCtx));
-            }
-            // Remove content-length since toolbar injection changes body size
-            if (!res.raw.headersSent) {
-              res.raw.removeHeader("content-length");
-            }
-          }
-          if (typeof encodingOrCb === "function") {
-            return originalEnd(chunk, encodingOrCb);
-          }
-          if (encodingOrCb !== undefined) {
-            return originalEnd(chunk, encodingOrCb, cb);
-          }
-          return originalEnd(chunk, cb);
-        };
-        res.raw.end = wrappedEnd;
-      } else if (
-        feedbackEnabled() &&
-        !pathname.startsWith("/__dev") &&
-        !pathname.startsWith("/__feedback")
-      ) {
-        // Production / non-dev path: still inject the feedback widget for
-        // whitelisted users. The injector itself re-checks the whitelist,
-        // path, and html marker so the wrapper is cheap when it no-ops.
-        const originalEnd = res.raw.end.bind(res.raw);
-        const wrappedEnd: typeof res.raw.end = function (
-          chunk?: unknown,
-          encodingOrCb?: BufferEncoding | (() => void),
-          cb?: () => void,
-        ) {
-          const contentType = res.raw.getHeader("content-type");
-          if (
-            typeof contentType === "string" &&
-            contentType.includes("text/html")
-          ) {
-            if (typeof chunk === "string") {
-              chunk = injectFeedbackWidget(req, chunk);
-            } else if (Buffer.isBuffer(chunk)) {
-              chunk = injectFeedbackWidget(req, chunk.toString("utf-8"));
-            }
-            if (!res.raw.headersSent) {
-              res.raw.removeHeader("content-length");
-            }
-          }
-          if (typeof encodingOrCb === "function") {
-            return originalEnd(chunk, encodingOrCb);
-          }
-          if (encodingOrCb !== undefined) {
-            return originalEnd(chunk, encodingOrCb, cb);
-          }
-          return originalEnd(chunk, cb);
-        };
-        res.raw.end = wrappedEnd;
-      }
+      // Global middleware, split by what it depends on (ADR-0012). The
+      // PRE-match set runs before a route is even looked up, so CORS and
+      // anything else that must survive a short-circuit can set headers that
+      // outlive a 401/403; opt in with `static preMatch = true`.
+      const { pre: preMatchMiddleware, post: postMatchMiddleware } =
+        MiddlewareRunner.partitionByMatchPhase([
+          ...new Set([...Router.getClassMiddlewares(), ...MiddlewareRunner.getGlobal()]),
+        ]);
 
-      // Try static files first (project public dir, src/public dir, then framework built-in)
-      // Index resolution: "/" or "/foo/" picks up index.html so SPA builds Just Work.
-      if (existsSync(staticDir) && tryServeStatic(staticDir, req, res)) {
-        return;
-      }
-      if (existsSync(srcPublicDir) && tryServeStatic(srcPublicDir, req, res)) {
-        return;
-      }
-      // Framework-bundled assets. The Swagger UI lives here (public/swagger/),
-      // and static files resolve BEFORE routes -- so this path MUST honour the
-      // swagger gate or /swagger is served in production regardless of
-      // TINA4_SWAGGER_ENABLED / TINA4_DEBUG.
-      if (swaggerAssetsEnabled || !isSwaggerAssetPath(pathname)) {
-        if (tryServeStatic(BUILTIN_PUBLIC_DIR, req, res)) {
-          return;
-        }
-      }
+      if (await runGlobalMiddlewarePass(preMatchMiddleware, req, res)) return;
 
-      // Match route
+      // Match route. ROUTES BEAT FILES (ADR-0010): static assets resolve in
+      // the not-found fallback below, only once no route has claimed the path.
+      // A file in public/ can arrive from a build step, an upload directory or
+      // a careless deploy, and it must never silently shadow a reviewed route.
       const match = router.match(req.method ?? "GET", pathname);
       if (match) {
-        req.params = match.params;
-        matchedPattern = match.pattern;
-
-        // Global class-based middleware registered via Router.use(...) /
-        // MiddlewareRunner.use(...) — run the beforeX hooks before the handler.
-        // beforeX may set response headers (they persist through the handler's
-        // write), mutate the request, or short-circuit on a >= 400 status.
-        // (Parity with Python/PHP/Ruby, whose Router.use class middleware runs.)
-        const globalMiddleware = [
-          ...new Set([...Router.getClassMiddlewares(), ...MiddlewareRunner.getGlobal()]),
-        ];
-        if (globalMiddleware.length > 0) {
-          const [, , proceed] = await MiddlewareRunner.runBefore(globalMiddleware, req, res);
-          if (!proceed || res.raw.writableEnded) {
-            // AFTER-ON-4xx RULE (M2): after_* ALWAYS run even when a before_*
-            // short-circuited (4xx / clean 500 / response ended), so they can
-            // still add headers / logging. Run them, then stop the handler.
-            await MiddlewareRunner.runAfter(globalMiddleware, req, res);
-            if (!res.raw.writableEnded) res.raw.end();
-            return;
-          }
-        }
-
-        // Run per-route middlewares if any
-        if (match.middlewares && match.middlewares.length > 0) {
-          const proceed = await runRouteMiddlewares(match.middlewares, req, res);
-          if (!proceed || res.raw.writableEnded) return;
-        }
-
-        // Auth enforcement: secure routes require a valid token. Extracted into
-        // enforceRouteAuth (authGate.ts) so the in-process TestClient enforces
-        // the EXACT same gate (parity with Python #PY2 — a tokenless write must
-        // 401 in tests too, or a green test hides a live 401). Dev admin routes
-        // (/__dev) are always public. Returns true when a 401 was written.
-        const isDevAdmin = pathname.startsWith("/__dev");
-        if (enforceRouteAuth(req, res, match, isDevAdmin)) {
-          return;
-        }
-
-        // Inject path params by name into handler arguments, then request/response
-        let result: unknown;
-        const routeParams = req.params || {};
-        const fnStr = match.handler.toString();
-        const argMatch = fnStr.match(/^(?:async\s*)?(?:function\s*\w*)?\s*\(([^)]*)\)/);
-        const argNames = argMatch?.[1]?.split(",").map((s: string) => s.trim().replace(/[:=].*/,"")) ?? [];
-        const filteredArgs = argNames.filter((n: string) => n.length > 0);
-
-        if (filteredArgs.length === 0) {
-          result = await (match.handler as any)();
-        } else {
-          const args = filteredArgs.map((name: string) => {
-            if (name in routeParams) return routeParams[name];
-            if (name === "request" || name === "req") return req;
-            return res;
-          });
-          result = await (match.handler as any)(...args);
-        }
-
-        // If the route exports a template and the handler returned a plain object,
-        // render it through the template engine instead of sending as JSON.
-        if (
-          !res.raw.writableEnded &&
-          match.template &&
-          result !== null &&
-          result !== undefined &&
-          typeof result === "object" &&
-          !Buffer.isBuffer(result)
-        ) {
-          await res.render(match.template, result as Record<string, unknown>);
-        }
-
-        // Global class-based middleware afterX hooks (logging / post-processing).
-        // Header mutations here are no-ops once the response is flushed (Node
-        // sends headers with the body) — set response headers in beforeX.
-        if (globalMiddleware.length > 0) {
-          await MiddlewareRunner.runAfter(globalMiddleware, req, res);
-        }
-
-        if (!res.raw.writableEnded) {
-          res.raw.end();
-        }
-        return;
-      }
-
-      // Try serving a template file (e.g. /hello -> src/templates/pages/hello.twig)
-      if ((req.method ?? "GET") === "GET") {
-        const tplFile = resolveTemplate(pathname, templatesDir);
-        if (tplFile) {
-          // Render through Frond so {% include %} / {% extends %} work,
-          // not raw readFileSync.
-          if (frondEngine) {
-            const html = frondEngine.render(tplFile, {});
-            res.raw.writeHead(200, undefined, { "Content-Type": "text/html; charset=utf-8" });
-            res.raw.end(html);
-          } else {
-            const html = readFileSync(resolve(templatesDir, tplFile), "utf-8");
-            res.raw.writeHead(200, undefined, { "Content-Type": "text/html; charset=utf-8" });
-            res.raw.end(html);
-          }
-          return;
-        }
-
-        // Landing page renders only at "/" AND only when TINA4_DEBUG=true.
-        // In production "/" with no static index.html and no pages/index.twig
-        // falls through to a clean 404 — the framework's branded welcome,
-        // gallery and version never leak to real users.
-        if (pathname === "/" && isDevMode()) {
-          const allRoutes = router.getRoutes().map((r) => ({
-            method: r.method,
-            pattern: r.pattern,
-            flags: [] as string[],
-          }));
-          const html = renderLandingPage(allRoutes, port);
-          res.raw.writeHead(200, undefined, { "Content-Type": "text/html; charset=utf-8" });
-          res.raw.end(html);
-          return;
-        }
-      }
-
-      // RFC 9110 conformance — before falling through to 404, check whether
-      // the PATH is registered under any OTHER method.
-      //   - OPTIONS request → 204 with Allow header (§9.3.7)
-      //   - Any other method (PUT on GET-only, TRACE, CONNECT, etc.)
-      //     → 405 with Allow header (§15.5.6 + §10.2.1)
-      const allowedMethods = router.methodsAllowedForPath(pathname);
-      if (allowedMethods.length > 0) {
-        const allowHeader = allowedMethods.join(", ");
-        const requestMethod = (req.method ?? "GET").toUpperCase();
-        if (requestMethod === "OPTIONS") {
-          res.raw.writeHead(204, undefined, { Allow: allowHeader, "Content-Length": "0" });
-          res.raw.end();
-          return;
-        }
-        const body = JSON.stringify({
-          error: "Method Not Allowed",
-          path: pathname,
-          method: requestMethod,
-          allow: allowedMethods,
-          statusCode: 405,
-        });
-        res.raw.writeHead(405, httpReason(405), {
-          Allow: allowHeader,
-          "Content-Type": "application/json",
-          "Content-Length": String(Buffer.byteLength(body)),
+        matchedPattern.value = match.pattern;
+        await runMatchedRoute({
+          req, res, pathname, match, postMatchMiddleware,
+          allGlobalMiddleware: [...preMatchMiddleware, ...postMatchMiddleware],
         });
-        res.raw.end(body);
         return;
       }
 
-      // 404 — pass canonical reason phrase so the status line is well-formed
-      const html404 = await renderErrorPage(404, { path: pathname }, templatesDir);
-      if (html404) {
-        res.raw.writeHead(404, httpReason(404), { "Content-Type": "text/html; charset=utf-8" });
-        res.raw.end(html404);
-      } else {
-        res({ error: "Not Found", statusCode: 404, message: `No route found for ${req.method} ${pathname}` }, 404);
+      // NOT-FOUND FALLBACK STAGES. Nothing matched a route, so walk the
+      // fallback chain in order - see FALLBACK_STAGES. Each returns true when
+      // it has answered the request.
+      //
+      // ADR-0010 (routes beat files) is why this chain runs AFTER matching: a
+      // file dropped into public/ by a build step or a careless deploy must
+      // never shadow a reviewed route.
+      const fallback: FallbackContext = {
+        req, res, pathname, router, port, staticDir, srcPublicDir,
+        templatesDir, frondEngine, swaggerAssetsEnabled,
+      };
+      for (const stage of FALLBACK_STAGES) {
+        if (await stage(fallback)) return;
       }
     } catch (err) {
-      // v3.13.7: log structured + surface to observability BEFORE rendering.
-      // Listeners get the canonical {exception, request} payload mirrored
-      // by Python / PHP / Ruby. Listener errors are swallowed + warning-
-      // logged so a broken listener can't break the 500 page.
-      Log.error(`Route error: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`, {
-        method: req?.method,
-        path: req?.path,
-      });
-      try {
-        const { Events } = await import("./events.js");
-        Events.emit("tina4.request.error", { exception: err, request: req });
-      } catch (listenerErr) {
-        try {
-          Log.warn(
-            `Listener for tina4.request.error raised: ${
-              listenerErr instanceof Error
-                ? `${listenerErr.name}: ${listenerErr.message}`
-                : String(listenerErr)
-            }`
-          );
-        } catch {
-          // Log failures must never block the 500 render.
-        }
-      }
-
-      if (!res.raw.writableEnded) {
-        if (isDevMode() && err instanceof Error) {
-          // Rich error overlay with stack trace, source context, and line numbers
-          const { renderErrorOverlay } = await import("./errorOverlay.js");
-          const overlayHtml = renderErrorOverlay(err, req);
-          res.raw.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });
-          res.raw.end(overlayHtml);
-        } else {
-          // v3.13.7 SECURITY (CWE-209): production response body must NOT
-          // contain the stack trace or exception message. Pass an empty
-          // error_message — the 500.twig template only renders the trace
-          // block when error_message is truthy.
-          const html500 = await renderErrorPage(500, {
-            error_message: "",
-            request_id: `${Date.now().toString(36)}`,
-            path: req.path,
-          }, templatesDir);
-          if (html500) {
-            res.raw.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });
-            res.raw.end(html500);
-          } else {
-            res({ error: "Internal Server Error", statusCode: 500 }, 500);
-          }
-        }
-      }
+      await renderDispatchError(err, req, res, templatesDir);
     }
   }
 
@@ -1651,7 +1854,30 @@ ${reset}
       let aiServer: ReturnType<typeof createServer> | null = null;
       let testPort = port + 1000;
 
-      if (isDebug && !noAiPort) {
+      // A DERIVED port is still a port. `port + 1000` leaves the legal range as
+      // soon as the base port is above 64535, and Node's listen() validates the
+      // number and throws ERR_SOCKET_BAD_PORT SYNCHRONOUSLY — it is not an
+      // "error" event, so the handler below never sees it. Thrown here it
+      // escapes this listen callback ABOVE the resolvePromise() at the end of
+      // it, and in debug mode devAdmin's ErrorTracker has already installed an
+      // uncaughtException handler that only RECORDS the error. Net effect,
+      // measured: the main port stayed bound and served traffic while
+      // `await startServer(...)` never settled — a half-started server that
+      // hangs the caller with nothing printed. `PORT=65000 TINA4_DEBUG=true`
+      // was enough to trigger it; in the test suite an OS-assigned ephemeral
+      // base port (macOS hands out 49152-65535) hit it about one run in
+      // sixteen and the whole file vanished from the counts.
+      const aiPortInRange = testPort <= 65535;
+
+      if (isDebug && !noAiPort && !aiPortInRange) {
+        Log.warning(
+          `Stable AI/test port ${testPort} is out of range (a port must be <= 65535), ` +
+          `so it is disabled for base port ${port}. Use a base port of 64535 or lower, ` +
+          `or set TINA4_NO_AI_PORT=true to silence this.`,
+        );
+      }
+
+      if (isDebug && !noAiPort && aiPortInRange) {
         // Stable AI port (port+1000): tag requests so /__dev_reload + toolbar are suppressed.
         aiServer = createServer(async (req, res) => {
           (req as any)._tina4AiPort = true;
@@ -1679,8 +1905,12 @@ ${reset}
         aiServer.listen(testPort, host);
       }
 
-      // Banner goes to stdout via console.log — NOT through the framework logger
-      const dualPortLines = (isDebug && !noAiPort)
+      // Banner goes to stdout via console.log — NOT through the framework logger.
+      // Only advertise the test port when one was actually attempted: an
+      // out-of-range derived port is not bound, and printing it would send a
+      // developer to a URL that cannot exist (same rule as the swagger/dashboard
+      // lines below).
+      const dualPortLines = (isDebug && !noAiPort && aiPortInRange)
         ? `\n  Test Port: http://localhost:${testPort} (stable — no hot-reload)`
         : "";
 
@@ -1711,8 +1941,115 @@ ${reset}
         // Open the browser on the MAIN port — that's the hot-reload port.
         openBrowser(`http://${displayHost}:${port}`);
       }
+      // ── Graceful shutdown ─────────────────────────────────────────────
+      // A container orchestrator sends SIGTERM and SIGKILLs after a grace
+      // period, so dropping in-flight requests here is a production defect,
+      // not a style question. The order below mirrors Python/PHP/Ruby:
+      // stop accepting -> let in-flight requests finish -> release resources
+      // -> exit 0.
+      //
+      // Two traps this replaces, both measured against a real signal:
+      //
+      //  1. Nothing here trapped the signal at all, so a plain startServer()
+      //     app died on SIGTERM's DEFAULT disposition: process gone in ~150ms,
+      //     every in-flight response dropped, exit 143.
+      //  2. `server.close()` is ASYNCHRONOUS and, in Node's own words, "keeps
+      //     existing connections". The CLI's `server.close(); process.exit(0)`
+      //     therefore killed the very requests close() was waiting to drain.
+      //     The close CALLBACK is the only honest "everything drained" signal.
+      let shuttingDown = false;
+
+      const closeListeners = (): Promise<void> =>
+        new Promise((done) => {
+          let pending = aiServer ? 2 : 1;
+          const one = (): void => {
+            if (--pending === 0) done();
+          };
+          server.close(one);
+          if (aiServer) aiServer.close(one);
+          // A keep-alive socket with no request on it still counts as an open
+          // connection, so close() would sit on it until the client wandered
+          // off. Without this a fully drained server still burns the whole
+          // shutdown budget.
+          server.closeIdleConnections();
+          aiServer?.closeIdleConnections();
+        });
+
+      const gracefulShutdown = async (signal: string): Promise<void> => {
+        if (shuttingDown) return;
+        shuttingDown = true;
+        Log.info(`Received ${signal}, shutting down gracefully...`);
+
+        stopAllBackgroundTasks();
+
+        // Tell live WebSocket peers we are going away (RFC 6455 s7.4.1 code
+        // 1001) BEFORE closing the listeners. A WS connection never "finishes"
+        // the way a request does, so waiting for one to drain would burn the
+        // whole budget every time; the honest move is a proper close frame so
+        // a tina4-js client reconnects on a schedule instead of erroring on a
+        // socket that simply vanished.
+        const wsClosed =
+          wsRouteManager.closeAll(CLOSE_GOING_AWAY, "server shutting down") +
+          devReloadWs.closeAll(CLOSE_GOING_AWAY, "server shutting down");
+        if (wsClosed > 0) {
+          Log.info(`Closed ${wsClosed} WebSocket connection(s) with 1001 going away`);
+        }
+
+        // Race the drain against the shutdown budget. Whatever is still in
+        // flight when the budget expires gets force-closed: SIGKILL is what
+        // arrives next, so a bounded drain is strictly better than an
+        // unbounded one that the orchestrator truncates anyway.
+        const budgetSeconds = shutdownTimeoutSeconds();
+        let timer: NodeJS.Timeout | undefined;
+        const outcome = await Promise.race([
+          closeListeners().then(() => "drained" as const),
+          new Promise<"timeout">((r) => {
+            timer = setTimeout(() => r("timeout"), budgetSeconds * 1000);
+            timer.unref();
+          }),
+        ]);
+        if (timer) clearTimeout(timer);
+
+        if (outcome === "timeout") {
+          Log.warning(
+            `Shutdown timeout (${budgetSeconds}s) reached with requests still in flight - forcing close`,
+          );
+          server.closeAllConnections();
+          aiServer?.closeAllConnections();
+        }
+
+        try {
+          const orm = await import("../../orm/src/index.js");
+          await orm.closeDatabase();
+        } catch {
+          /* ORM never initialised - nothing to close */
+        }
+
+        Log.info("Server stopped.");
+        // Exit 0: this process was ASKED to stop and did so cleanly. 128+signum
+        // is what waitpid reports for a process killed BY a signal, i.e. one
+        // that did NOT handle it - it is a diagnosis, not a target. Gunicorn
+        // and Puma both halt 0 on a handled TERM, and a container exiting 0 is
+        // a clean termination rather than a signal-kill.
+        process.exit(0);
+      };
+
+      const onSigterm = (): void => {
+        void gracefulShutdown("SIGTERM");
+      };
+      const onSigint = (): void => {
+        void gracefulShutdown("SIGINT");
+      };
+      process.on("SIGTERM", onSigterm);
+      process.on("SIGINT", onSigint);
+
       resolvePromise({
         close: () => {
+          // An explicit close() is not a signal shutdown: drop the handlers so
+          // a test that starts many servers in one process does not pile up
+          // listeners (and trip Node's MaxListeners warning).
+          process.off("SIGTERM", onSigterm);
+          process.off("SIGINT", onSigint);
           // Clear any registered background timers so graceful shutdown actually exits.
           stopAllBackgroundTasks();
           if (aiServer) aiServer.close();