@teamscala/service-boot 0.23.329 → 0.23.331

package/src/resource-chat-inject.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Injects the generic ResourceChatLauncher block into an AUTHORISED resource
+ * page (proposal, agreement, or any gated document) — called from a gate's
+ * onAuthorized, so the floating GPT bubble lives strictly behind the email gate
+ * and every resource of that type gets it with no per-page Puck edit. It builds
+ * the resource's page content into a runtime-context string and passes it to the
+ * launcher, which forwards it to the chat as <runtime_context> — so ONE shared
+ * assistant agent answers about whichever resource is being viewed.
+ *
+ * RESOURCE-AGNOSTIC by design (one-ai-chat-system / chat-ui-is-one-canonical-block):
+ * the launcher, the chat engine, and this injector are generic; only the
+ * per-resource CONFIG differs (which agent, the copy, which resolved key holds
+ * the record). The agent id is config, not code (registries-are-source-of-truth):
+ * each resource type names a `config / <slug>-assistant-agent` row carrying
+ * { agentId }. No row (or no agent) → no injection, page renders unchanged
+ * (fail-soft).
+ */
+/** Per-resource-type injection config — the only thing that varies. */
+export interface ResourceChatOptions {
+    /** Key in `resolved` holding the record (e.g. "proposal", "agreement"). */
+    resourceKey: string;
+    /** `config` row slug carrying { agentId } (e.g. "agreement-assistant-agent"). */
+    agentConfigSlug: string;
+    /** Org id to scope the chat. If omitted, read from resolved[resourceKey].organisation_id
+     *  (proposals); agreements pass it explicitly (org isn't on the resolved record). */
+    organisationId?: string;
+    /** Overlay title-bar label (e.g. "Agreement Assistant"). */
+    title: string;
+    /** Floating button label / speech bubble (e.g. "Ask about this agreement"). */
+    launchLabel: string;
+    /** First assistant message. */
+    welcomeMessage?: string;
+    /** Input placeholder. */
+    placeholder?: string;
+    /** Suggested starter questions. */
+    conversationStarters?: string[];
+}
+/**
+ * Inject the generic ResourceChatLauncher behind the gate. `opts` is the only
+ * per-resource-type variation; everything else is shared.
+ */
+export declare function injectResourceChatLauncher(resolved: Record<string, unknown>, viewerEmail: string, opts: ResourceChatOptions): Promise<void>;

package/src/resource-not-found.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ * @indivisible-unit
+ *
+ * One cohesive unit — the branded resource-not-found / holding page: the
+ * PrimaryResourceMissingError trigger, the org-logo resolver the page
+ * renders, and the HTML builder are tightly coupled (the builder consumes
+ * the logo; the error drives the page) and cannot be split without churn.
+ *
+ * Branded 404 for registry page routes whose PRIMARY resource is missing.
+ *
+ * A route that declares `resource_type` (proposal, form, quiz, agreement…)
+ * is meaningless without that entity. Before this existed, a dead link
+ * (wrong id, deleted row) fell through the loader with nulls and rendered
+ * whatever default content the shell could scrape together — leaking
+ * internal pages (the "Vision Toolbar" incident, operator-observed
+ * 2026-06-05) on the org's own branded host, with a 200 status that
+ * search engines and link unfurlers would happily cache.
+ *
+ * The replacement: loadData throws PrimaryResourceMissingError; the page
+ * binder maps it to a minimal branded 404 — correct status, noindex, the
+ * host's own favicon (which resolves the owning org per brand_org), and a
+ * plain human sentence. Deliberately NOT a puck page: the error surface
+ * must render even when data loading is the thing that failed. A
+ * website-editable /404 puck page can layer on top later; this is the
+ * floor that must always exist.
+ */
+/**
+ * The host org's LOGO (wordmark) for the dark error page — the favicon is a
+ * tab glyph, the wrong asset at page scale (operator-observed: a lone "h"
+ * where the launcha wordmark belonged). Resolution: the service's own
+ * install row names its owner (brand_org); the org's dark-theme logo (a
+ * light-coloured mark, correct on the dark page) is preferred, light-theme
+ * second. Every step skew-tolerant: any miss → null → the builder renders a
+ * logo-less dark page.
+ *
+ * Returns the logo as an INLINE data URI (not a `/api/assets/` proxy URL) so
+ * the branded holding/error page ships the logo IN the initial HTML bytes —
+ * no second fetch, no post-paint pop-in, no dependency on the asset proxy the
+ * degraded service is failing to serve (incident 2026-07-27: the logo on a
+ * DEGRADED render-layer holding page appeared after the page painted). The
+ * logo sibling of icons-render-ssr-inline. Size-capped: a pathological
+ * (>MAX_INLINE_LOGO_BYTES) logo falls back to null rather than bloating the
+ * HTML; the page renders logo-less, never broken.
+ */
+export declare function resolveErrorPageLogo(serviceSlug: string): Promise<string | null>;
+export declare class PrimaryResourceMissingError extends Error {
+    readonly resourceType: string;
+    readonly httpStatus: number;
+    readonly empty: boolean;
+    constructor(resourceType: string, httpStatus?: number, opts?: {
+        empty?: boolean;
+    });
+}
+export declare function buildResourceNotFoundResponse(resourceType: string, logoUrl?: string | null, status?: number, opts?: {
+    homeUrl?: string;
+    empty?: boolean;
+}): Response;

package/src/run-boot-hook-list.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Runs the service's boot hooks. A server_package registers a hook via
+ * ctx.registerBootHook during the mount phase; a hook registered by an
+ * INSTALLED server_package is intended to run (the package is installed
+ * because the service wants it). This therefore invokes EVERY registered
+ * hook — those declared in `service_install.boot_hooks[]` first (preserving
+ * their declared order), then any registered-but-undeclared hooks. Requiring a
+ * hook to be BOTH registered by its package AND re-declared in boot_hooks is a
+ * double-declaration footgun — it left the realtime-utils pg-notify bridge
+ * registered-but-never-invoked (boot_hooks was null), so the live-refresh
+ * relay never started (2026-06-29).
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
+export declare function runBootHookList(config: ServiceInstallConfig, mountRegistry: MountRegistry, serviceSlug: string): Promise<void>;

package/src/run-boot-hooks.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Runs service_install.boot_hooks in declaration order. A boot hook is a
+ * registry-declared, one-shot startup function that needs to execute after
+ * prisma + registry are ready but before the HTTP server starts serving.
+ * Used for custom startup logic (stale-run reconciliation, cache hydration,
+ * ALS seeding, long-running watcher start) that doesn't fit the pg-boss
+ * recurring model and is too specific to be a generic installer step.
+ *
+ * Each hook is resolved by dynamic-importing its handler_slug (or slug when
+ * handler_slug is absent) and awaiting its default export. The export must
+ * be an async function accepting a BootHookContext. Hooks are invoked in
+ * ascending order of their `order` field (default 100).
+ *
+ * Failures are fatal. The installer has no partial-boot concept: if a
+ * declared hook cannot run, the service is broken, and booting anyway would
+ * mask the regression. BootFatalError is thrown to propagate to the
+ * top-level boot-error handler.
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+export interface BootHookContext {
+    serviceSlug: string;
+    config: ServiceInstallConfig;
+}
+export type BootHookHandler = (ctx: BootHookContext) => Promise<void> | void;
+export declare function runBootHooks(serviceSlug: string, config: ServiceInstallConfig): Promise<{
+    ran: string[];
+}>;

package/src/scala-tools-currency-watchdog.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Polls the installed scala-tools package against GitHub Packages and repairs
+ * stale daemon tooling by reinstalling and letting PM2 restart the process.
+ */
+export declare function startScalaToolsCurrencyWatchdog(): void;
+export declare function stopScalaToolsCurrencyWatchdog(): void;

package/src/security-headers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Middleware that injects security headers into every response.
+ * Uses Hono's secureHeaders as the base for standard headers (X-Content-Type-Options,
+ * X-Frame-Options, Referrer-Policy, etc.), then layers registry-driven CSP with
+ * nonce injection on top.
+ */
+import type { Context, Next } from "hono";
+export declare function injectSecurityHeaders(c: Context, next: Next): Promise<void>;

package/src/serve/serve.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @system runtime-serve
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Listener primitives. Provides the Bun.serve production listener (serveStart)
+ * and the WebSocket upgrade helper (upgradeWebSocket) that work identically
+ * dev and prod.
+ */
+import type { Hono } from "hono";
+/**
+ * Hono `upgradeWebSocket` helper bound to the same `createBunWebSocket()`
+ * pair that drives Bun.serve.websocket. Use exclusively from this package so
+ * the upgrade path and the message dispatch share state.
+ */
+export declare const upgradeWebSocket: import("hono/ws").UpgradeWebSocket<unknown, any, import("hono/ws").WSEvents<unknown>>;
+export interface ServeOptions {
+    /** TCP port to bind. */
+    port: number;
+    /** For logging only. */
+    serviceSlug: string;
+    /**
+     * Optional logger; defaults to console.
+     */
+    logger?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+export interface ServeHandle {
+    server: ReturnType<typeof Bun.serve>;
+    stop(): void;
+}
+/**
+ * Start Bun.serve listening on the configured port. Used by:
+ *   - bootUiService when running the production bundle (`bun dist/server/index.js`)
+ *   - bootBackendService for non-UI services
+ *
+ * UI services in dev mode also call this — they run `bun src/index.ts`
+ * directly under PM2 with the same Bun.serve listener.
+ *
+ * Two-phase boot variant: when useMutableRef is true, `app` is used as the
+ * initial app for the mutable reference (minimal tool-only surface), and the
+ * caller can swap to the full app later via swapApp().
+ */
+export declare function serveStart(app: Hono, options: ServeOptions, useMutableRef?: boolean): ServeHandle;

package/src/serve/stamp-transport-identity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Stamp transport-derived identity onto a request — the single shared stamp
+ * point used by BOTH serve paths (direct `createFetchHandler` + mutable-ref
+ * `fetchWithMutableApp`), so every request on every UI service carries the
+ * same identity regardless of boot mode.
+ *
+ * Two identity layers, both transport-derived (no-client-controlled-trust-
+ * signals — never from a client-controllable header):
+ *   1. `x-caller-remote-address` / `-port` — the unforgeable socket peer, from
+ *      `Bun.serve.requestIP`. ALWAYS sanitised (any client-supplied spoof
+ *      deleted) then set to the verified peer. The /mcp + fleet loopback gates
+ *      read this.
+ *   2. `x-caller-local-comm` / `-cmd` — for a LOOPBACK peer with no forwarding
+ *      header (a local `fetch` carries no CF-Connecting-IP), the owning local
+ *      PROCESS resolved via /proc (@teamscala/proc-walker). Names the daemon
+ *      behind every local request on the access log — including an unidentified
+ *      sweeper. Attribution only (trust stays transport-derived).
+ *
+ * Best-effort + never throws: a resolution miss returns the original request
+ * unchanged (the request is always served; identity degrades to address-only).
+ * WebSocket upgrades are returned untouched (Bun tracks upgrades by Request
+ * identity — a clone can never upgrade).
+ */
+/**
+ * Return a Request with transport-identity headers stamped, or the original
+ * `req` when no stamping is needed/possible. Never throws.
+ */
+export declare function stampTransportIdentity(req: Request, server: ReturnType<typeof Bun.serve>): Request;

package/src/serve/stamp-transport-identity.ts

@@ -31,18 +31,6 @@ import { resolveSocketPeer } from "@teamscala/proc-walker/socket-peer";
 
 const LOOPBACK = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
 
-/**
- * Preserve useful process attribution without copying arbitrary argv into logs.
- * Arguments routinely contain bearer headers, inline scripts, URLs and secret
- * values. There is no complete flag-name redaction list, so the safe boundary
- * is structural: retain argv[0] and state that arguments were removed.
- */
-export function summariseLocalCommand(cmdline: readonly string[]): string | null {
-	const executable = cmdline[0]?.trim();
-	if (!executable) return null;
-	return cmdline.length > 1 ? `${executable} [arguments redacted]` : executable;
-}
-
 /**
  * Return a Request with transport-identity headers stamped, or the original
  * `req` when no stamping is needed/possible. Never throws.
@@ -89,8 +77,8 @@ export function stampTransportIdentity(
 			const owner = resolveSocketPeer(port);
 			if (owner) {
 				headers.set(CALLER_HEADERS.LOCAL_COMM, owner.comm);
-				const cmd = summariseLocalCommand(owner.cmdline);
-				if (cmd) headers.set(CALLER_HEADERS.LOCAL_CMD, cmd);
+				const cmd = owner.cmdline.join(" ").trim();
+				if (cmd) headers.set(CALLER_HEADERS.LOCAL_CMD, cmd.slice(0, 160));
 			}
 		}
 		return new Request(req.url, {

package/src/server-error-page.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The branded HTML error page for a FAILED PAGE RENDER — the page-server
+ * render catch's response surface (constitution `error-responses-via-error-
+ * report`). When SSR resolve+render fails (render budget exhausted, DEGRADED
+ * protective layer, a thrown loader), the browser is mid-navigation: serving
+ * a JSON body there is the violation this closes (2026-07-24: the operator
+ * saw a raw `{"error":"Request failed"}` blob where the dashboard should be).
+ *
+ * Classification stays in `buildErrorReport` (`@teamscala/os`) — the ONE
+ * classifier; this file is ONLY the HTML shaper for the page-navigation
+ * surface (API/ORPC `onError` keeps the JSON body, consumed by code). It
+ * renders the report's already-decided status + Retry-After + message, so the
+ * screen, the log line, and the GlitchTip event all share one `errorId`.
+ *
+ * Deliberately NOT a Puck page: it must render even when data loading is what
+ * failed. Sibling of `resource-not-found.ts` (the missing-resource floor) —
+ * same dark branded template + org-logo resolver, distinct trigger.
+ */
+import type { ErrorReport } from "@teamscala/os/errors/error-report";
+/**
+ * Render an `ErrorReport` as a branded HTML page. Pure shaper — the caller
+ * classifies via `buildErrorReport` and resolves the logo first. Skew-tolerant
+ * by construction: a missing logo degrades to a plain branded dark page.
+ */
+export declare function buildServerErrorPageResponse(report: ErrorReport, logoUrl?: string | null): Response;

package/src/start-scheduled-jobs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Starts `service_install.scheduled_jobs[]`. Two kinds:
+ *
+ *   - `long_running`: handler invoked once at boot, runs for the lifetime of
+ *      the process (e.g. SSE subscribers, WAL watchers). Failures are logged.
+ *   - `recurring`: declared here but cron scheduling lands via pg-boss in a
+ *      follow-up — currently a no-op log.
+ *
+ * Implementations are registered by server_packages via
+ * ctx.registerScheduledJob during the mount phase.
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
+export declare function startScheduledJobs(config: ServiceInstallConfig, mountRegistry: MountRegistry, serviceSlug: string): void;

package/src/two-phase-boot.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Two-phase boot for UI services. Splits the boot process into:
+ * 1. Minimal app (tool-only surface): ORPC, data routes, auth gates
+ * 2. Full app (with pages and hydration): adds block discovery, page routes,
+ *    client asset building, boot hooks, scheduled jobs
+ *
+ * The minimal app starts serving immediately (<10s), then the full app is
+ * built in the background and atomically swapped in. This eliminates the
+ * ~25s channel outage window during scala-agents restart.
+ */
+import { Hono, type Context } from "hono";
+import type { ServiceInstallConfig } from "./load-service-install-row.ts";
+import { mountServerPackages } from "./mount-server-packages.ts";
+import type { PageServerDeps } from "./ui-service.ts";
+import type { CreatePageHandler } from "./types.ts";
+/**
+ * Set the real page handler (called when Phase 2 completes).
+ */
+export declare function setPageHandler(handler: CreatePageHandler): void;
+/**
+ * Get the current page handler state.
+ */
+export declare function getPageHandlerState(): {
+    ready: boolean;
+    hasHandler: boolean;
+};
+/**
+ * `/health` for a UI service — 200 ONLY once the full app can actually render
+ * a page, 503 before that.
+ *
+ * This endpoint is not decoration: it is the wake gate for every scale-to-zero
+ * app. `scala-activator` (`@teamscala/scale-to-zero`) holds the client's TCP
+ * connection through a cold wake and pipes it the instant `isHealthy(port)` —
+ * a plain `GET /health` — returns ok, which is what `scale-to-zero-apps-sleep-
+ * on-demand` means by "`/health`-gates the wake (the client never sees a boot
+ * 503)".
+ *
+ * It previously answered a flat `{status:"ok"}` as soon as the MINIMAL app was
+ * serving, because the readiness gate flips ready after phase 1 so the ORPC/MCP
+ * surface can accept traffic early. But phase 1 CANNOT render: the phase-1 page
+ * handler below returns 503 until `setPageHandler` runs at the phase-2 swap. So
+ * `/health` reported ready while every page 503'd, the activator believed the
+ * wake had landed, and it piped the customer's first request straight into that
+ * window — the customer got the 503.
+ *
+ * Measured 2026-07-31 on quiz-dev/sign-dev: the activator logged `awake` for
+ * scala-quiz at 05:58:25.446 and the app logged `GET / 503 3ms` at 05:58:25.452
+ * — 6ms later, and 1004ms BEFORE "Swapped from minimal app to full app". Nine
+ * such 503s on scala-quiz and two on scala-sign, every one 0-23ms (the
+ * placeholder, which does no render work). scala-public logged ZERO, which is
+ * the whole reason it looked healthy while the other two did not: the gap is a
+ * RACE whose width is the phase-1→phase-2 build time (1420ms cold, 137ms warm),
+ * not a config difference between the apps.
+ *
+ * Gating this on `fullAppReady` makes the signal honest for every consumer at
+ * once (the activator's wake gate, `poller-post-restart-health-gate`, any
+ * health-gated router) rather than teaching each one its own probe, and it is
+ * what `readiness-gated-boot` already requires: "/health returns 503 until
+ * ready, 200 after — so it is the real readiness signal", a service being
+ * "binary: fully-ready or cleanly-unavailable". A UI service that cannot render
+ * is not ready, per `liveness-by-capability-not-process-existence` — liveness is
+ * a probe of the capability being REQUESTED, never of process existence or of
+ * some other surface that happens to answer.
+ *
+ * The early readiness-gate flip is deliberately left alone: it gates the ORPC
+ * tool surface, which genuinely IS usable at phase 1. Only this endpoint, whose
+ * one consumer contract is "can you serve me a page", is moved to phase 2.
+ */
+export declare function healthHandler(c: Context): Response;
+export interface MinimalAppResult {
+    app: Hono;
+    mountRegistry: Awaited<ReturnType<typeof mountServerPackages>>;
+    apiRouteCount: number;
+    wsRouteCount: number;
+    pageRouteCount: number;
+    config: ServiceInstallConfig;
+    serviceSlug: string;
+    databaseUrl: string;
+    blockPackages: string[];
+    components: Record<string, unknown>;
+    loaded: string[];
+    skipped: string[];
+}
+export interface FullAppResult {
+    app: Hono;
+    blocks: {
+        slug: string;
+        packagePath: string;
+    }[];
+    routes: string[];
+    pgBossJobs: Array<{
+        handlerSlug: string;
+    }>;
+}
+/**
+ * Build the minimal tool-only app. This excludes the expensive operations:
+ * - Client asset building (Vite build)
+ * - Boot hooks (may have expensive initialization)
+ * - Scheduled jobs (can start later)
+ * - pg-boss (can start later)
+ *
+ * CRITICAL: All route registration MUST happen here before serving, because
+ * Hono's RegExpRouter compiles on the first request and becomes immutable.
+ * Once compiled, no new routes can be added. So we include:
+ * - Block discovery and page routes (registers all page paths)
+ * - All other routes (API, WS, data, static assets)
+ *
+ * The minimal app includes everything needed for MCP tools and ORPC:
+ * - Error handling, readiness gate, health check
+ * - Security headers, CORS, compression, timing
+ * - Content gate access, auth gates, static assets
+ * - ORPC router, API routes, WS routes, data routes, page routes
+ */
+export declare function buildMinimalApp(config: ServiceInstallConfig, serviceSlug: string, databaseUrl: string): Promise<MinimalAppResult>;
+/**
+ * Build the full app with hydration. This adds the expensive operations that
+ * were deferred from the minimal app:
+ * - Client asset building (Vite build)
+ * - Boot hooks (may have expensive initialization)
+ * - Scheduled jobs (can start later)
+ * - pg-boss (can start later)
+ *
+ * This runs in the background after the minimal app is already serving.
+ * NOTE: All routes (including page routes) are already registered in Phase 1,
+ * so we don't need to modify the app here. The app reference stays the same.
+ */
+export declare function buildFullApp(minimalResult: MinimalAppResult, deps: PageServerDeps): Promise<FullAppResult>;
+/**
+ * Swap the minimal app for the full app. This atomically replaces the
+ * app reference that Bun.serve is using.
+ */
+export declare function swapToFullApp(fullApp: Hono, serviceSlug: string): void;

package/src/two-phase-boot.ts

@@ -54,7 +54,6 @@ import { registerPageRoutes } from "./register-page-routes.ts";
 import { runBootHookList } from "./run-boot-hook-list.ts";
 import { buildClientAssets } from "./build-client-assets.ts";
 import { discoverBlocks } from "./discover-blocks.ts";
-import { registerPageServerClient } from "./register-page-server-client.ts";
 import { swapApp } from "./mutable-app-ref.ts";
 import type { CreatePageHandler } from "./types.ts";
 
@@ -64,60 +63,13 @@ let realPageHandler: CreatePageHandler | null = null;
 let fullAppReady = false;
 
 /**
- * Set the real page handler (called when Phase 2 completes on an SSR service).
- *
- * Registering the SSR handler implies the full app is built, so this also flips
- * readiness — but the reverse does NOT hold, which is why `markFullAppReady`
- * exists separately. See its note.
+ * Set the real page handler (called when Phase 2 completes).
  */
 export function setPageHandler(handler: CreatePageHandler): void {
 	realPageHandler = handler;
-	markFullAppReady();
-}
-
-/**
- * Flip readiness once phase 2 has built the full app.
- *
- * SEPARATE FROM `setPageHandler` BECAUSE THE TWO FACTS CAME APART. Readiness
- * means "phase 2 finished"; the page handler means "this service renders pages
- * server-side". Every service was SSR, so one flag honestly carried both — until
- * `render_mode=client` (`granular runtime`) made a service that completes phase 2
- * and never registers an SSR handler.
- *
- * Leaving readiness inside `setPageHandler` made such a service PERMANENTLY
- * un-ready: `/health` answered `{"status":"starting"}` forever while the process
- * was healthy and serving. That is the failure `readiness-gated-boot` is written
- * against — a service must be "binary: fully-ready or cleanly-unavailable", and
- * a never-ready health signal makes the activator's wake gate and every
- * health-gated router treat a working service as down.
- *
- * Measured 2026-08-07 on scala-agents-ui: boot completed in 5023ms, "Full app
- * built: 50 block(s)" logged, `GET /` correctly 302'd to sign-in, and `/health`
- * still reported starting — while three untouched UI services reported ok.
- */
-export function markFullAppReady(): void {
 	fullAppReady = true;
 }
 
-/**
- * Reset both phase-2 flags. TEST-ONLY.
- *
- * `fullAppReady` is module state that only ever transitions false -> true in
- * production, and Bun shares a module instance across every test file in a run —
- * so the SSR readiness test and the client-only readiness test contaminate each
- * other purely by file order. Splitting them across files does NOT isolate them;
- * it only hides the coupling until CI runs them together.
- *
- * A test that passes alone and fails in a suite is worse than no test, so the
- * reset is exported rather than left as an ordering convention nobody can see.
- * Never called from production code — `setPageHandler`/`markFullAppReady` are
- * the only writers on the boot path.
- */
-export function __resetPhase2StateForTest(): void {
-	realPageHandler = null;
-	fullAppReady = false;
-}
-
 /**
  * Get the current page handler state.
  */
@@ -295,6 +247,16 @@ export async function buildMinimalApp(
 		preloadServerPackages(serverPackages),
 	);
 	const ttlPromise = runStep("init-gate-ttls", () => initGateTtls());
+	const discoverPromise = runStep("discover-blocks", () =>
+		discoverBlocks(blockPackages),
+	);
+	// Attach an immediate rejection sink: discoverPromise is fired here but
+	// awaited much later (after the gate chain + mounts). If discoverBlocks
+	// rejects during that overlap window, the rejection would surface as an
+	// unhandledRejection before the await below can catch it. The sink is a
+	// no-op — the real error still propagates at the `await discoverPromise`
+	// site because each consumer of a rejected promise receives the rejection.
+	discoverPromise.catch(() => {});
 
 	// Public access endpoints — MUST be registered before the auth gate (Hono
 	// dispatches middleware + handlers in registration order; the content-gate
@@ -343,21 +305,6 @@ export async function buildMinimalApp(
 		await runStep("mount-orpc-router", () => mountOrpcRouter(app, serviceSlug));
 	}
 
-	// Register the in-process ORPC server client BEFORE discoverBlocks — it
-	// calls getServerClient() which needs the client set here. Must follow
-	// mount-orpc-router (which builds the router getAppRouter uses).
-	// Previously ran inside register-page-routes (too late — discoverBlocks
-	// fired before it, hitting the empty-router fallback).
-	await runStep("register-page-server-client", () =>
-		registerPageServerClient(serviceSlug),
-	);
-
-	// NOW fire discoverBlocks (getServerClient is set). Awaited below before
-	// register-page-routes consumes the result.
-	const discoverPromise = runStep("discover-blocks", () =>
-		discoverBlocks(blockPackages),
-	);
-
 	const wsRouteCount = await runStep("register-ws-routes", () =>
 		registerWsRoutes(app, config, mountRegistry, serviceSlug),
 	);
@@ -429,8 +376,7 @@ export async function buildMinimalApp(
 				// (the same pulsating-logo holding page scale-to-zero uses) —
 				// never bare plain text (loading-via-logo-loading).
 					if (!fullAppReady || !realPageHandler) {
-						const logo = await resolveErrorPageLogo(serviceSlug);
-						return new Response(buildWakingPageHtml({ logoUrl: logo }), {
+						return new Response(buildWakingPageHtml({}), {
 							status: 503,
 							headers: {
 								"content-type": "text/html; charset=utf-8",
@@ -552,25 +498,11 @@ export async function buildFullApp(
 			`${Object.keys(components).length} component(s)`,
 	);
 
-	// Set the real page handler so the dynamic handler in Phase 1 can delegate to it.
-	// Client-only services (render_mode=client) have no SSR page handler — skip
-	// (they serve via the client bundle, never SSR). Guarded so undefined is a
-	// no-op rather than a crash.
-	if (deps.createPageHandler) {
-		setPageHandler(deps.createPageHandler);
-		log.info(
-			`[two-phase-boot:${serviceSlug}] Real page handler registered - page routes now delegate to full app`,
-		);
-	} else {
-		// The full app IS built — this service simply never renders server-side,
-		// so readiness is flipped directly rather than as a side effect of
-		// registering an SSR handler that will never exist. Without this a
-		// client-only service is permanently un-ready (see markFullAppReady).
-		markFullAppReady();
-		log.info(
-			`[two-phase-boot:${serviceSlug}] Client-only mode (render_mode=client) — no SSR page handler registered`,
-		);
-	}
+	// Set the real page handler so the dynamic handler in Phase 1 can delegate to it
+	setPageHandler(deps.createPageHandler);
+	log.info(
+		`[two-phase-boot:${serviceSlug}] Real page handler registered - page routes now delegate to full app`,
+	);
 
 	const resolvedBlocks = loaded.map((slug) => ({
 		slug,

package/src/two-phase-health-gate.test.ts

@@ -27,14 +27,9 @@
  * 137ms warm), which is why one app looked healthy and the others did not.
  */
 
-import { beforeAll, describe, expect, test } from "bun:test";
+import { describe, expect, test } from "bun:test";
 import { Hono } from "hono";
-import {
-	__resetPhase2StateForTest,
-	getPageHandlerState,
-	healthHandler,
-	setPageHandler,
-} from "./two-phase-boot.ts";
+import { healthHandler, setPageHandler, getPageHandlerState } from "./two-phase-boot.ts";
 
 /** Mount the real handler exactly as buildMinimalApp does. */
 const app = new Hono().get("/health", healthHandler);
@@ -46,12 +41,6 @@ const app = new Hono().get("/health", healthHandler);
  * hook and adding one would exist only for tests.
  */
 describe("/health is gated on page-serving readiness", () => {
-	// Bun shares one module instance across test files, so a sibling file that
-	// marks the app ready would otherwise decide this file's first assertion.
-	beforeAll(() => {
-		__resetPhase2StateForTest();
-	});
-
 	test("before the phase-2 swap it reports 503, not ready", async () => {
 		expect(getPageHandlerState().ready).toBe(false);