@teamscala/service-boot 0.23.385 → 0.23.387

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.385",
+  "version": "0.23.387",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",
@@ -418,6 +418,22 @@
       "types": "./src/handlers/bun-stable-watch.d.ts",
       "default": "./src/handlers/bun-stable-watch.ts"
     },
+    "./handlers/messaging-send-recording-logic": {
+      "types": "./src/handlers/messaging-send-recording-logic.d.ts",
+      "default": "./src/handlers/messaging-send-recording-logic.ts"
+    },
+    "./handlers/messaging-send-recording-logic.ts": {
+      "types": "./src/handlers/messaging-send-recording-logic.d.ts",
+      "default": "./src/handlers/messaging-send-recording-logic.ts"
+    },
+    "./handlers/messaging-send-recording-watch": {
+      "types": "./src/handlers/messaging-send-recording-watch.d.ts",
+      "default": "./src/handlers/messaging-send-recording-watch.ts"
+    },
+    "./handlers/messaging-send-recording-watch.ts": {
+      "types": "./src/handlers/messaging-send-recording-watch.d.ts",
+      "default": "./src/handlers/messaging-send-recording-watch.ts"
+    },
     "./handlers/pane-outbox-drain": {
       "types": "./src/handlers/pane-outbox-drain.d.ts",
       "default": "./src/handlers/pane-outbox-drain.ts"
@@ -922,13 +938,29 @@
       "types": "./src/server-error-page.d.ts",
       "default": "./src/server-error-page.ts"
     },
-    "./two-phase-boot": {
-      "types": "./src/two-phase-boot.d.ts",
-      "default": "./src/two-phase-boot.ts"
+    "./two-phase-full-app": {
+      "types": "./src/two-phase-full-app.d.ts",
+      "default": "./src/two-phase-full-app.ts"
+    },
+    "./two-phase-full-app.ts": {
+      "types": "./src/two-phase-full-app.d.ts",
+      "default": "./src/two-phase-full-app.ts"
+    },
+    "./two-phase-minimal-app": {
+      "types": "./src/two-phase-minimal-app.d.ts",
+      "default": "./src/two-phase-minimal-app.ts"
+    },
+    "./two-phase-minimal-app.ts": {
+      "types": "./src/two-phase-minimal-app.d.ts",
+      "default": "./src/two-phase-minimal-app.ts"
+    },
+    "./two-phase-readiness": {
+      "types": "./src/two-phase-readiness.d.ts",
+      "default": "./src/two-phase-readiness.ts"
     },
-    "./two-phase-boot.ts": {
-      "types": "./src/two-phase-boot.d.ts",
-      "default": "./src/two-phase-boot.ts"
+    "./two-phase-readiness.ts": {
+      "types": "./src/two-phase-readiness.d.ts",
+      "default": "./src/two-phase-readiness.ts"
     },
     "./types": {
       "types": "./src/types.d.ts",

package/src/page-server-orpc/server-client.test.ts

@@ -19,7 +19,9 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import {
 	getServerClient,
+	getServerClientCapabilityFault,
 	isServerClientRegistered,
+	recordServerClientCapability,
 	setServerClient,
 } from "./server-client.ts";
 
@@ -66,3 +68,45 @@ describe("page-server server client", () => {
 		expect(isServerClientRegistered()).toBe(true);
 	});
 });
+
+describe("declared-vs-present capability probe (/health)", () => {
+	test("no fault when every declared model is servable", () => {
+		setServerClient({
+			assessments: { findFirst: async () => null },
+			assessment_responses: { findFirst: async () => null },
+		} as never);
+		recordServerClientCapability(["assessments", "assessment_responses"]);
+		expect(getServerClientCapabilityFault()).toBeNull();
+	});
+
+	test("names the models the client cannot serve", () => {
+		// THE OUTAGE, AS A HEALTH ANSWER. A client was registered and carried only
+		// the platform routers, so every process-existence signal was green while
+		// every data-backed page 500d. /health must be able to say this.
+		setServerClient({ puckPages: {}, userPreferences: {} } as never);
+		recordServerClientCapability(["assessments", "assessment_responses"]);
+		const fault = getServerClientCapabilityFault();
+		expect(fault).toContain("assessments");
+		expect(fault).toContain("assessment_responses");
+	});
+
+	test("a service declaring no models is never faulted", () => {
+		// Daemon/portal shells own no DB schema and are healthy with an empty client.
+		setServerClient({ puckPages: {} } as never);
+		recordServerClientCapability([]);
+		expect(getServerClientCapabilityFault()).toBeNull();
+	});
+
+	test("an unregistered client is itself the fault", () => {
+		setServerClient(null as never);
+		recordServerClientCapability(["assessments"]);
+		expect(getServerClientCapabilityFault()).toContain("no ORPC server client registered");
+	});
+
+	test("a model present without findFirst still counts as missing", () => {
+		// The generated router shape is what matters, not mere key presence.
+		setServerClient({ assessments: {} } as never);
+		recordServerClientCapability(["assessments"]);
+		expect(getServerClientCapabilityFault()).toContain("assessments");
+	});
+});

package/src/page-server-orpc/server-client.ts

@@ -55,3 +55,36 @@ export function setServerClient(
 ): void {
 	serverClient = client;
 }
+
+/**
+ * Declared-vs-present capability, recorded once at boot by
+ * registerPageServerClient and read by /health.
+ *
+ * The outage this exists for: a client WAS registered, so every
+ * process-existence signal was green, and it carried no CRUD models. Liveness
+ * must be a capability probe, never a registration check
+ * (`liveness-by-capability-not-process-existence`).
+ */
+let capabilityFault: string | null = null;
+
+/**
+ * Record whether the registered client can actually serve the models the
+ * service declares. Property lookups only — no I/O — so /health stays cheap.
+ */
+export function recordServerClientCapability(declaredModels: readonly string[]): void {
+	if (!serverClient) {
+		capabilityFault = "no ORPC server client registered";
+		return;
+	}
+	const client = serverClient as unknown as Record<string, { findFirst?: unknown } | undefined>;
+	const missing = declaredModels.filter((m) => typeof client[m]?.findFirst !== "function");
+	capabilityFault =
+		missing.length === 0
+			? null
+			: `generated client exposes no findFirst for ${missing.length} declared model(s): ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ", …" : ""}`;
+}
+
+/** The capability fault, or null when the service can serve its declared models. */
+export function getServerClientCapabilityFault(): string | null {
+	return capabilityFault;
+}

package/src/register-page-server-client.ts

@@ -148,6 +148,9 @@ export async function registerPageServerClient(
 			} as never,
 		);
 		mod.setServerClient(client);
+		// Record declared-vs-present capability for /health. Property lookups only.
+		(mod as unknown as { recordServerClientCapability?: (m: readonly string[]) => void })
+			.recordServerClientCapability?.(declaredModels);
 		// State the model count. "registered" alone was true in the outage and told
 		// nobody anything; a zero here is now visible in the boot log.
 		log.info(

package/src/{two-phase-boot.test.ts → two-phase-full-app.test.ts}

@@ -17,7 +17,7 @@
 
 import { describe, expect, test } from "bun:test";
 
-const src = await Bun.file(new URL("./two-phase-boot.ts", import.meta.url)).text();
+const src = await Bun.file(new URL("./two-phase-full-app.ts", import.meta.url)).text();
 
 /** The body of buildFullApp, where phase-2 ordering lives. */
 function buildFullAppBody(): string {

package/src/two-phase-full-app.ts

@@ -0,0 +1,138 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Phase 2 of the two-phase boot: the full app. Adds the expensive operations
+ * deferred from phase 1 (two-phase-minimal-app.ts) — client asset building
+ * (Vite build), pg-boss, the readiness/page-handler flip — and is swapped
+ * in atomically once complete.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import type { Hono } from "hono";
+import { buildClientAssets } from "./build-client-assets.ts";
+import { mountPgBoss } from "./pg-boss-mount.ts";
+import { swapApp } from "./mutable-app-ref.ts";
+import type { MinimalAppResult } from "./two-phase-minimal-app.ts";
+import { markFullAppReady, setPageHandler } from "./two-phase-readiness.ts";
+import type { PageServerDeps } from "./ui-service.ts";
+
+export interface FullAppResult {
+	app: Hono;
+	blocks: { slug: string; packagePath: string }[];
+	routes: string[];
+	pgBossJobs: Array<{ handlerSlug: string }>;
+}
+
+/**
+ * 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 async function buildFullApp(
+	minimalResult: MinimalAppResult,
+	deps: PageServerDeps,
+): Promise<FullAppResult> {
+	const log = getAppLogger();
+	const { config, serviceSlug, mountRegistry, components, loaded, app: minimalApp } = minimalResult;
+
+	// Client asset building (expensive: Vite build).
+	//
+	// ISOLATED, because a PRESENTATION failure must not take out BACKGROUND WORK.
+	// This was awaited unguarded, so a throw here aborted buildFullApp before
+	// mountPgBoss ran, and the caller's catch logged
+	// "Failed to build full app, continuing with minimal app" — which reads as a
+	// UI-only degradation while having silently killed every pg-boss handler on
+	// the service.
+	//
+	// Measured 2026-07-30: a stale @teamscala/portal-ui artifact still importing
+	// the retired @teamgbg scope threw ENOENT on a missing theme CSS file in
+	// scala-agents. Zero "scheduledJobs DONE" lines appeared for ~20 minutes
+	// across repeated boots, the pane-outbox drain never mounted, and the
+	// operator's WhatsApp assistant went silent — because of a stylesheet. The
+	// service stayed `online` and healthy throughout, so nothing surfaced it.
+	//
+	// The steps after this one do not depend on client assets: pg-boss needs the
+	// registry and the DB, not a bundle. Ordering it behind a Vite build was
+	// incidental, so the coupling was never intended.
+	try {
+		await buildClientAssets(serviceSlug);
+		log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets DONE`);
+	} catch (error) {
+		// Loud but non-fatal: the tombstone manifest written by buildClientAssets
+		// already makes SSR serve the prior bundle, so degrading here costs the
+		// new bundle, never the background work.
+		log.error(
+			`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets FAILED — continuing to scheduled jobs and pg-boss (a client-asset failure must not stop background work)`,
+			{ error: error instanceof Error ? error.message : String(error) },
+		);
+	}
+
+	// pg-boss (mount for UI services - wasn't mounted in minimal app)
+	const { jobs: pgBossJobs } = await mountPgBoss({
+		databaseUrl: minimalResult.databaseUrl,
+		serviceSlug,
+		packages: config.server_packages ?? [],
+	});
+	log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: mountPgBoss DONE (${pgBossJobs.length} jobs)`);
+	if (pgBossJobs.length > 0) {
+		log.info(
+			`[two-phase-boot:${serviceSlug}] pg-boss mounted ${pgBossJobs.length} job(s): ${pgBossJobs.map((j) => j.handlerSlug).join(", ")}`,
+		);
+	}
+
+	log.info(
+		`[two-phase-boot:${serviceSlug}] Full app built: ${loaded.length} block(s), ` +
+			`${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`,
+		);
+	}
+
+	const resolvedBlocks = loaded.map((slug) => ({
+		slug,
+		packagePath: "block_packages",
+	}));
+
+	return {
+		app: minimalApp, // Same app reference, all routes already registered
+		blocks: resolvedBlocks,
+		routes: [], // Routes already registered in Phase 1
+		pgBossJobs,
+	};
+}
+
+/**
+ * Swap the minimal app for the full app. This atomically replaces the
+ * app reference that Bun.serve is using.
+ */
+export function swapToFullApp(fullApp: Hono, serviceSlug: string): void {
+	const oldLabel = swapApp(fullApp, "full");
+	const log = getAppLogger();
+	log.info(`[two-phase-boot:${serviceSlug}] Swapped from ${oldLabel} app to full app`);
+}

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

@@ -34,7 +34,7 @@ import {
 	getPageHandlerState,
 	healthHandler,
 	markFullAppReady,
-} from "./two-phase-boot.ts";
+} from "./two-phase-readiness.ts";
 
 /** Mount the real handler exactly as buildMinimalApp does. */
 const app = new Hono().get("/health", healthHandler);

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

@@ -34,7 +34,7 @@ import {
 	getPageHandlerState,
 	healthHandler,
 	setPageHandler,
-} from "./two-phase-boot.ts";
+} from "./two-phase-readiness.ts";
 
 /** Mount the real handler exactly as buildMinimalApp does. */
 const app = new Hono().get("/health", healthHandler);

package/src/{two-phase-boot.ts → two-phase-minimal-app.ts}

@@ -3,21 +3,16 @@
  * @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.
+ * Phase 1 of the two-phase boot: the minimal tool-only app (ORPC, data
+ * routes, auth gates) that serves immediately (<10s); phase 2
+ * (two-phase-full-app.ts) builds the full app in the background and swaps
+ * it in atomically — eliminating the ~25s boot outage window.
  */
 
 import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { buildWakingPageHtml } from "@teamscala/os/brand/waking-page-html";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";
 import { createTimer } from "@teamscala/timing/create-timer";
-import { Hono, type Context } from "hono";
+import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { compress } from "hono/compress";
 import { cors } from "hono/cors";
@@ -37,7 +32,6 @@ import { attachRequestLogger } from "./install-logging.ts";
 import type { ServiceInstallConfig } from "./load-service-install-row.ts";
 import { mountOrpcRouter } from "./mount-orpc-router.ts";
 import { mountServerPackages, preloadServerPackages } from "./mount-server-packages.ts";
-import { mountPgBoss } from "./pg-boss-mount.ts";
 import { registerApiRoutes } from "./register-api-routes.ts";
 import { readinessGate } from "./readiness-gate.ts";
 import { registerStaticAssets } from "./register-static-assets";
@@ -48,129 +42,11 @@ import {
 	resolveErrorPageLogo,
 } from "./resource-not-found.ts";
 import { injectSecurityHeaders } from "./security-headers.ts";
-import type { PageServerDeps } from "./ui-service.ts";
 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";
-
-// Module-level storage for the real page handler, updated when Phase 2 completes.
-// This allows the temporary Phase 1 handler to delegate to the real handler once ready.
-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.
- */
-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.
- */
-export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
-	return { ready: fullAppReady, hasHandler: realPageHandler !== null };
-}
-
-/**
- * `/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 function healthHandler(c: Context): Response {
-	return fullAppReady
-		? c.json({ status: "ok" })
-		: c.json({ status: "starting" }, 503, { "Retry-After": "1" });
-}
+import { createPhase1PageHandler, healthHandler } from "./two-phase-readiness.ts";
 
 export interface MinimalAppResult {
 	app: Hono;
@@ -187,13 +63,6 @@ export interface MinimalAppResult {
 	skipped: string[]; // Skipped block names
 }
 
-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)
@@ -437,39 +306,13 @@ export async function buildMinimalApp(
 	// Register page routes with a dynamic handler that delegates to the real handler once Phase 2 completes.
 	// All route paths must be registered before serving to avoid Hono
 	// RegExpRouter compilation issues (matcher becomes immutable).
-	//
-	// CRITICAL: During Phase 1 (minimal app), page requests MUST return 503 BEFORE
-	// attempting to resolve page data. The config object doesn't have proper loadData
-	// set up until Phase 2, and attempting to resolve undefined loadData crashes
-	// resolveDataGraph with "undefined is not an object (evaluating 'Object.keys(spec)')".
 	const registeredPageRoutes = await runStep("register-page-routes", () =>
 		registerPageRoutes({
 			app,
 			config,
 			components,
 			serviceSlug,
-			createPageHandler: (pageConfig) => {
-				// Return a handler that checks if the full app is ready BEFORE processing
-				return async (req, extras) => {
-					// If full app is NOT ready yet, return the branded waking page
-				// (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 }), {
-							status: 503,
-							headers: {
-								"content-type": "text/html; charset=utf-8",
-								"cache-control": "no-store, no-transform",
-								"retry-after": "5",
-							},
-						});
-					}
-					// Full app is ready - delegate to the real handler
-					const handler = realPageHandler(pageConfig);
-					return handler(req, extras);
-				};
-			},
+			createPageHandler: createPhase1PageHandler(serviceSlug),
 		}),
 	);
 	const pageRouteCount = registeredPageRoutes.length;
@@ -504,115 +347,3 @@ export async function buildMinimalApp(
 		skipped,
 	};
 }
-
-/**
- * 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 async function buildFullApp(
-	minimalResult: MinimalAppResult,
-	deps: PageServerDeps,
-): Promise<FullAppResult> {
-	const log = getAppLogger();
-	const { config, serviceSlug, mountRegistry, components, loaded, app: minimalApp } = minimalResult;
-
-	// Client asset building (expensive: Vite build).
-	//
-	// ISOLATED, because a PRESENTATION failure must not take out BACKGROUND WORK.
-	// This was awaited unguarded, so a throw here aborted buildFullApp before
-	// mountPgBoss ran, and the caller's catch logged
-	// "Failed to build full app, continuing with minimal app" — which reads as a
-	// UI-only degradation while having silently killed every pg-boss handler on
-	// the service.
-	//
-	// Measured 2026-07-30: a stale @teamscala/portal-ui artifact still importing
-	// the retired @teamgbg scope threw ENOENT on a missing theme CSS file in
-	// scala-agents. Zero "scheduledJobs DONE" lines appeared for ~20 minutes
-	// across repeated boots, the pane-outbox drain never mounted, and the
-	// operator's WhatsApp assistant went silent — because of a stylesheet. The
-	// service stayed `online` and healthy throughout, so nothing surfaced it.
-	//
-	// The steps after this one do not depend on client assets: pg-boss needs the
-	// registry and the DB, not a bundle. Ordering it behind a Vite build was
-	// incidental, so the coupling was never intended.
-	try {
-		await buildClientAssets(serviceSlug);
-		log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets DONE`);
-	} catch (error) {
-		// Loud but non-fatal: the tombstone manifest written by buildClientAssets
-		// already makes SSR serve the prior bundle, so degrading here costs the
-		// new bundle, never the background work.
-		log.error(
-			`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets FAILED — continuing to scheduled jobs and pg-boss (a client-asset failure must not stop background work)`,
-			{ error: error instanceof Error ? error.message : String(error) },
-		);
-	}
-
-	// pg-boss (mount for UI services - wasn't mounted in minimal app)
-	const { jobs: pgBossJobs } = await mountPgBoss({
-		databaseUrl: minimalResult.databaseUrl,
-		serviceSlug,
-		packages: config.server_packages ?? [],
-	});
-	log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: mountPgBoss DONE (${pgBossJobs.length} jobs)`);
-	if (pgBossJobs.length > 0) {
-		log.info(
-			`[two-phase-boot:${serviceSlug}] pg-boss mounted ${pgBossJobs.length} job(s): ${pgBossJobs.map((j) => j.handlerSlug).join(", ")}`,
-		);
-	}
-
-	log.info(
-		`[two-phase-boot:${serviceSlug}] Full app built: ${loaded.length} block(s), ` +
-			`${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`,
-		);
-	}
-
-	const resolvedBlocks = loaded.map((slug) => ({
-		slug,
-		packagePath: "block_packages",
-	}));
-
-	return {
-		app: minimalApp, // Same app reference, all routes already registered
-		blocks: resolvedBlocks,
-		routes: [], // Routes already registered in Phase 1
-		pgBossJobs,
-	};
-}
-
-/**
- * Swap the minimal app for the full app. This atomically replaces the
- * app reference that Bun.serve is using.
- */
-export function swapToFullApp(fullApp: Hono, serviceSlug: string): void {
-	const oldLabel = swapApp(fullApp, "full");
-	const log = getAppLogger();
-	log.info(`[two-phase-boot:${serviceSlug}] Swapped from ${oldLabel} app to full app`);
-}

package/src/two-phase-readiness.ts

@@ -0,0 +1,171 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Phase-2 readiness state box for the two-phase boot: the real page handler +
+ * readiness flags (private lets), the writers/flippers, the `/health` endpoint
+ * that gates on them, and the phase-1 page handler that delegates to the real
+ * handler once phase 2 completes. Every reader goes through these exports.
+ */
+
+import { buildWakingPageHtml } from "@teamscala/os/brand/waking-page-html";
+import type { Context } from "hono";
+import { getServerClientCapabilityFault } from "./page-server-orpc/server-client.ts";
+import { resolveErrorPageLogo } from "./resource-not-found.ts";
+import type { CreatePageHandler } from "./types.ts";
+
+// Module-level storage for the real page handler, updated when Phase 2 completes.
+// This allows the temporary Phase 1 handler to delegate to the real handler once ready.
+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.
+ */
+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.
+ */
+export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
+	return { ready: fullAppReady, hasHandler: realPageHandler !== null };
+}
+
+/**
+ * `/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 function healthHandler(c: Context): Response {
+	if (!fullAppReady) return c.json({ status: "starting" }, 503, { "Retry-After": "1" });
+	// Assert the CAPABILITY, not just the phase flag. On 2026-08-20 this returned
+	// 200 through a total outage: the process was up and phase 2 had completed
+	// while the registered client carried no CRUD models, so every data-backed
+	// page 500d and nothing alerted
+	// (`liveness-by-capability-not-process-existence`).
+	const fault = getServerClientCapabilityFault();
+	if (fault) return c.json({ status: "degraded", reason: fault }, 503);
+	return c.json({ status: "ok" });
+}
+
+/**
+ * The page handler `buildMinimalApp` registers on every page route during
+ * phase 1: 503 + the branded waking page until the full app is ready, then
+ * delegation to the real handler. Lives here, beside the state it reads —
+ * the flags stay private to this module.
+ */
+export function createPhase1PageHandler(serviceSlug: string): CreatePageHandler {
+	// CRITICAL: During Phase 1 (minimal app), page requests MUST return 503 BEFORE
+	// attempting to resolve page data. The config object doesn't have proper loadData
+	// set up until Phase 2, and attempting to resolve undefined loadData crashes
+	// resolveDataGraph with "undefined is not an object (evaluating 'Object.keys(spec)')".
+	// Return a handler that checks if the full app is ready BEFORE processing
+	return (pageConfig) =>
+		async (req, extras) => {
+			// If full app is NOT ready yet, return the branded waking page
+			// (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 }), {
+					status: 503,
+					headers: {
+						"content-type": "text/html; charset=utf-8",
+						"cache-control": "no-store, no-transform",
+						"retry-after": "5",
+					},
+				});
+			}
+			// Full app is ready - delegate to the real handler
+			const handler = realPageHandler(pageConfig);
+			return handler(req, extras);
+		};
+}

package/src/ui-service.ts

@@ -15,7 +15,8 @@ import { Hono } from "hono";
 import type { ServiceInstallConfig } from "./load-service-install-row.ts";
 import { setReady } from "./readiness-gate.ts";
 import { resolveServicePort } from "./resolve-service-port.ts";
-import { buildMinimalApp, buildFullApp, swapToFullApp } from "./two-phase-boot.ts";
+import { buildMinimalApp } from "./two-phase-minimal-app.ts";
+import { buildFullApp, swapToFullApp } from "./two-phase-full-app.ts";
 import type { UpgradeWebSocket } from "./register-ws-routes.ts";
 
 export interface ResolvedBlock {