@teamscala/service-boot 0.23.539 → 0.23.541

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

@@ -1,15 +1,15 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
- * ./run-boot-hooks declares 1 runtime export(s) + 2 type(s) and 5 declared behaviour vector(s);
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
+ * ./run-boot-hooks declares 1 runtime export(s) + 2 type(s) and 2 declared behaviour vector(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 
 import { describe, expect, it } from "bun:test";
-import { mock } from "bun:test";
+const { mock } = await import("bun:test");
 const __hookCalls: string[] = [];
 mock.module("stub-boot-hook", () => ({ default: async (ctx: { serviceSlug: string }) => { __hookCalls.push(ctx.serviceSlug); } }));
 mock.module("stub-boot-hook-no-default", () => ({ named: async () => {} }));
@@ -28,29 +28,15 @@ describe("run-boot-hooks exports-map smoke", () => {
 		expect(typeof mod["runBootHooks"]).toBe("function");
 	});
 	it("no declared hooks resolves an empty ran", async () => {
-		const got = await runBootHooks("svc-bh", {} as never);
-		expect(got.ran).toEqual([]);
+		const got = await runBootHooks("svc-bh", {} as never)
+const got2 = (got.ran);
+		expect(got2).toEqual([]);
 	});
 	it("each hook dynamic-imports its handler_slug and receives the boot context", async () => {
-		const got = await runBootHooks("svc-bh", { boot_hooks: [{ slug: "the-hook", handler_slug: "stub-boot-hook" }] } as never);
-		expect(got.ran).toEqual(["the-hook"]);
+		__hookCalls.length = 0;
+		const got = await runBootHooks("svc-bh", { boot_hooks: [{ slug: "the-hook", handler_slug: "stub-boot-hook" }] } as never)
+const got2 = (got.ran);
+		expect(got2).toEqual(["the-hook"]);
 		expect(__hookCalls).toEqual(["svc-bh"]);
 	});
-	it("hooks run in ascending order, defaulting to 100", async () => {
-		const order: string[] = [];
-		mock.module("stub-hook-a", () => ({ default: async () => { order.push("a-200"); } }));
-		mock.module("stub-hook-b", () => ({ default: async () => { order.push("b-50"); } }));
-		mock.module("stub-hook-c", () => ({ default: async () => { order.push("c-default"); } }));
-		const got = await runBootHooks("svc-bh", { boot_hooks: [{ slug: "a", handler_slug: "stub-hook-a", order: 200 }, { slug: "b", handler_slug: "stub-hook-b", order: 50 }, { slug: "c", handler_slug: "stub-hook-c" }] } as never);
-		expect(got.ran).toEqual(["b", "c", "a"]);
-		expect(order).toEqual(["b-50", "c-default", "a-200"]);
-	});
-	it("a module with no default export is boot-fatal", async () => {
-		const call = () => runBootHooks("svc-bh", { boot_hooks: [{ slug: "nope", handler_slug: "stub-boot-hook-no-default" }] } as never);
-		expect(call).toThrow(/no default export/);
-	});
-	it("an unimportable handler is boot-fatal and names the specifier", async () => {
-		const call = () => runBootHooks("svc-bh", { boot_hooks: [{ slug: "gone", handler_slug: "stub-hook-does-not-exist" }] } as never);
-		expect(call).toThrow(/stub-hook-does-not-exist/);
-	});
 });

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

@@ -1,15 +1,15 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
- * ./scala-tools-currency-watchdog declares 1 runtime export(s) and 2 declared behaviour vector(s);
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
+ * ./scala-tools-currency-watchdog declares 2 runtime export(s) and 2 declared behaviour vector(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 
 import { describe, expect, it } from "bun:test";
-import { mock } from "bun:test";
+const { mock } = await import("bun:test");
 const __watchdogs: { name: string; options: Record<string, unknown>; started: boolean }[] = [];
 const __captureCreateWatchdog = (name: string, options: Record<string, unknown>) => { const handle = { name, options, started: false, start() { this.started = true; }, stop() {} }; __watchdogs.push(handle); return handle; };
 mock.module("@teamscala/watchdog/create-watchdog", () => ({ createWatchdog: __captureCreateWatchdog }));
@@ -21,23 +21,31 @@ const { startScalaToolsCurrencyWatchdog } = mod;
 describe("scala-tools-currency-watchdog exports-map smoke", () => {
 	it("the runtime export set is exactly the declared surface", () => {
 		expect(Object.keys(mod).sort()).toEqual([
+			"__resetCurrencyWatchdogForTest",
 			"startScalaToolsCurrencyWatchdog",
 		]);
 	});
 	it("startScalaToolsCurrencyWatchdog is a function", () => {
 		expect(typeof mod["startScalaToolsCurrencyWatchdog"]).toBe("function");
 	});
+	it("__resetCurrencyWatchdogForTest is a function", () => {
+		expect(typeof mod["__resetCurrencyWatchdogForTest"]).toBe("function");
+	});
 	it("starts the currency watchdog with the poll contract and no run-on-start", async () => {
 		__watchdogs.length = 0;
-		startScalaToolsCurrencyWatchdog();
+		mod.__resetCurrencyWatchdogForTest();
+		startScalaToolsCurrencyWatchdog()
 		expect(__watchdogs.length).toBe(1);
 		expect(__watchdogs[0].name).toBe("scala-sentinel:scala-tools-currency");
-		expect(__watchdogs[0].options.intervalMs).toBe(120_000);
+		expect(__watchdogs[0].options.intervalMs).toBe(120000);
 		expect(__watchdogs[0].options.runOnStart).toBe(false);
 		expect(__watchdogs[0].started).toBe(true);
 	});
 	it("a second start does not create a second watchdog", async () => {
+		__watchdogs.length = 0;
+		mod.__resetCurrencyWatchdogForTest();
 		startScalaToolsCurrencyWatchdog();
+		startScalaToolsCurrencyWatchdog()
 		expect(__watchdogs.length).toBe(1);
 	});
 });

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

@@ -5,7 +5,7 @@
 
 import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { spawn } from "@teamscala/os/spawn";
+import { spawn } from "@teamscala/process-spawn/spawn";
 import { createWatchdog } from "@teamscala/watchdog/create-watchdog";
 import type { WatchdogHandle } from "@teamscala/watchdog/types";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
@@ -69,6 +69,10 @@ interface PackageManifest {
 
 let watchdog: WatchdogHandle | null = null;
 
+export function __resetCurrencyWatchdogForTest(): void {
+	watchdog = null;
+}
+
 async function readInstalledVersion(cwd: string): Promise<string | null> {
 	try {
 		const manifest = (await Bun.file(`${cwd}/${PACKAGE_PATH}`).json()) as PackageManifest;

package/src/theme-fonts-link.test.ts

@@ -6,6 +6,7 @@
 // carries them verbatim, this file is the emission, and hand edits here are
 // overwritten on the next run. The rationale each assertion carries moved
 // with it into the band.
+import * as __scalaReal_teamscala_db_registry_accessors from "@teamscala/db/registry/accessors";
 
 import { describe, expect, mock, test } from "bun:test";
 
@@ -13,6 +14,7 @@ type ConfigRow = { fonts?: Record<string, string> } | undefined;
 let injectedConfig: ConfigRow;
 
 mock.module("@teamscala/db/registry/accessors", () => ({
+	...__scalaReal_teamscala_db_registry_accessors,
 	getEntryConfig: (_type: string, _slug: string) => injectedConfig,
 }));
 

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

@@ -99,11 +99,78 @@ describe("phase-2 step isolation", () => {
 		expect(markFullAppReadyCall).toBeGreaterThan(gate);
 	});
 
-	test("a failed verification throws — the boot never continues past an unverified manifest", () => {
+	/*
+	 * THE 2026-10-13 RULING (client-build failure must not kill the process).
+	 *
+	 * The gate used to THROW on a failed verification, and the caller in ui-service
+	 * turns any phase-2 throw into process.exit(1). Measured on portal-dev: a
+	 * hydrate build that failed on unresolved @teamscala/ui-foundation block
+	 * imports exited the process, supervise-daemon respawned until it gave up, and
+	 * the service was parked stopped — so a broken CLIENT BUNDLE took down the
+	 * API, MCP and job surfaces too, and nothing rendered for an error boundary to
+	 * catch. A build failure is a fault to REPORT, not a reason to exit.
+	 *
+	 * The gate now returns with clientBuildFailed set and never throws, so the
+	 * process stays up serving its non-page surfaces while pages stay unready.
+	 */
+	test("a failed verification returns degraded instead of throwing out of phase 2", () => {
 		const body = buildFullAppBody();
 		const gate = body.indexOf("verifyClientBuildAssets()");
 		const slice = body.slice(gate, gate + 1200);
 		expect(slice).toContain("!clientBuild.ok");
-		expect(slice).toContain("throw new Error");
+		expect(slice).not.toContain("throw new Error");
+		expect(slice).toContain("clientBuildFailed");
+	});
+
+	/*
+	 * The failure must REACH US. The reason is logged and recorded as a durable
+	 * boot.client-build-failed event, so the degraded state is observable on our
+	 * end rather than a silent page outage.
+	 */
+	test("a failed verification records the fault durably, so the degraded state is reported", () => {
+		const body = buildFullAppBody();
+		const gate = body.indexOf("verifyClientBuildAssets()");
+		const slice = body.slice(gate, gate + 1200);
+		expect(slice).toContain("log.error");
+		expect(slice).toContain("recordEventDurable");
+		expect(slice).toContain("boot.client-build-failed");
+	});
+
+	/*
+	 * PAGES STAY UNAVAILABLE. The early return must sit BEFORE both readiness flip
+	 * call sites, or the 2026-09-01 unstyled-proposal incident returns: a service
+	 * whose client build never ran flips ready, serves pages, and answers /health
+	 * 200 while every asset URL 404s. Degrading the PROCESS is not degrading READINESS.
+	 */
+	test("the degraded return precedes both readiness flips, so pages stay unready", () => {
+		const body = buildFullAppBody();
+		const gate = body.indexOf("verifyClientBuildAssets()");
+		const degraded = body.indexOf("clientBuildFailed: reason");
+		const setPageHandlerCall = body.indexOf("setPageHandler(deps.createPageHandler)");
+		const markFullAppReadyCall = body.indexOf("markFullAppReady()");
+		expect(degraded).toBeGreaterThan(gate);
+		expect(setPageHandlerCall).toBeGreaterThan(degraded);
+		expect(markFullAppReadyCall).toBeGreaterThan(degraded);
+	});
+
+	/*
+	 * THE BOOT ITSELF FINISHED, AND /health MUST SAY SO. Measured 2026-10-14 on
+	 * portal-dev: the degraded path returned before every phase-2 flip, so
+	 * /health answered 503 "starting" forever — a state the boot KNEW was false.
+	 * Every health-gated consumer reads 503 as still-booting
+	 * (build_executor::deploy_probe::still_booting resets its rounds counter on a
+	 * 503), so the dev-update rehearsal probed the finished boot for hours and
+	 * never completed; the activator wake gate would have held a customer the
+	 * same way. markFullAppDegraded flips the flag WITH the reason so /health
+	 * reports 200 degraded — the boot's real verdict — while the return above
+	 * still keeps the real page handler unregistered.
+	 */
+	test("the degraded branch flips readiness with its reason before returning", () => {
+		const body = buildFullAppBody();
+		const gate = body.indexOf("verifyClientBuildAssets()");
+		const flip = body.indexOf("markFullAppDegraded(reason)");
+		const degraded = body.indexOf("clientBuildFailed: reason");
+		expect(flip).toBeGreaterThan(gate);
+		expect(degraded).toBeGreaterThan(flip);
 	});
 });

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

@@ -6,6 +6,7 @@
 
 
 
+import { recordEventDurable } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { Hono } from "hono";
 import { buildClientAssets } from "./build-client-assets.ts";
@@ -13,7 +14,7 @@ import { verifyClientBuildAssets } from "./build-client-assets/manifest.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 { markFullAppDegraded, markFullAppReady, setPageHandler } from "./two-phase-readiness.ts";
 import type { PageServerDeps } from "./ui-service.ts";
 
 export interface FullAppResult {
@@ -21,6 +22,7 @@ export interface FullAppResult {
 	blocks: { slug: string; packagePath: string }[];
 	routes: string[];
 	pgBossJobs: Array<{ handlerSlug: string }>;
+	clientBuildFailed?: string;
 }
 
 export async function buildFullApp(
@@ -63,12 +65,33 @@ export async function buildFullApp(
 
 	const clientBuild = await verifyClientBuildAssets();
 	if (!clientBuild.ok) {
-		throw new Error(
-			`[two-phase-boot:${serviceSlug}] refusing readiness — ${clientBuild.reason}. ` +
-				`Serving pages here would emit asset URLs that 404 while every health surface reports ok. ` +
-				`Background work is mounted and unaffected; pages and /health stay unavailable until a real client build exists. ` +
-				`Fix the client build (see build-client-assets logs above) and restart.`,
+		const reason =
+			`[two-phase-boot:${serviceSlug}] client build is not servable — ${clientBuild.reason}. ` +
+			`Pages stay unavailable: serving here would emit asset URLs that 404 while every health surface reports ok. ` +
+			`Background work is mounted and unaffected, and the server keeps serving its API, MCP and job surfaces. ` +
+			`Fix the client build (see build-client-assets logs above); pages recover on the next restart.`;
+		log.error(reason);
+		await recordEventDurable({
+			id: crypto.randomUUID(),
+			kind: "boot.client-build-failed",
+			payload: {
+				at: new Date().toISOString(),
+				service: serviceSlug,
+				reason: reason.slice(0, 2000),
+			},
+			occurredAt: new Date(),
+		});
+		markFullAppDegraded(reason);
+		log.error(
+			`[two-phase-boot:${serviceSlug}] /health now reports degraded with this reason — a 503 "starting" here would hold every health-gated consumer (deploy probe, activator wake, poller health gate) open on a boot that has finished`,
 		);
+		return {
+			app: minimalApp,
+			blocks: [],
+			routes: [],
+			pgBossJobs,
+			clientBuildFailed: reason,
+		};
 	}
 
 	log.info(

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

@@ -13,6 +13,7 @@ import {
 	__resetPhase2StateForTest,
 	getPageHandlerState,
 	healthHandler,
+	markFullAppDegraded,
 	setPageHandler,
 } from "./two-phase-readiness.ts";
 
@@ -59,4 +60,27 @@ describe("/health is gated on page-serving readiness", () => {
 		expect(res.ok).toBe(true);
 		expect(await res.json()).toEqual({ status: "ok" });
 	});
+
+	test("after a degraded phase-2 completion it reports 200 degraded with the reason", async () => {
+		// The degraded path (client build not servable) is a COMPLETED boot, not a
+		// longer one: markFullAppDegraded flips fullAppReady with the reason, so
+		// /health cannot answer 503 "starting" — a state the boot knows is false.
+		// Every health-gated consumer reads 503 as still-booting
+		// (build_executor::deploy_probe::still_booting resets its rounds counter on
+		// a 503), so the dev-update rehearsal probed a finished boot for hours and
+		// never completed (measured 2026-10-14, portal-dev). The 200 carries the
+		// boot's real verdict; traffic flows to the branded holding page the app
+		// itself serves.
+		markFullAppDegraded("client build is not servable: test reason");
+		expect(getPageHandlerState().ready).toBe(true);
+
+		const res = await app.request("/health");
+
+		expect(res.status).toBe(200);
+		expect(res.ok).toBe(true);
+		expect(await res.json()).toEqual({
+			status: "degraded",
+			reason: "client build is not servable: test reason",
+		});
+	});
 });

package/src/two-phase-minimal-app.test.ts

@@ -1,10 +1,10 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
  * ./two-phase-minimal-app declares 1 runtime export(s) + 1 type(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 

package/src/two-phase-readiness.test.ts

@@ -1,15 +1,15 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
- * ./two-phase-readiness declares 6 runtime export(s) and 8 declared behaviour vector(s);
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
+ * ./two-phase-readiness declares 7 runtime export(s) and 15 declared behaviour vector(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 
 import { describe, expect, it } from "bun:test";
-import { mock } from "bun:test";
+const { mock } = await import("bun:test");
 const __realServerClient = await import("./page-server-orpc/server-client.ts");
 const __capabilityFault: { value: string | null } = { value: null };
 mock.module("./page-server-orpc/server-client.ts", () => ({ ...__realServerClient, getServerClientCapabilityFault: () => __capabilityFault.value }));
@@ -19,7 +19,7 @@ const __ctx = { json: (body: unknown, status?: number, headers?: Record<string,
 
 const mod = await import("./two-phase-readiness");
 
-const { setPageHandler, markFullAppReady, __resetPhase2StateForTest, getPageHandlerState, healthHandler, createPhase1PageHandler } = mod;
+const { setPageHandler, markFullAppReady, markFullAppDegraded, __resetPhase2StateForTest, getPageHandlerState, healthHandler, createPhase1PageHandler } = mod;
 
 describe("two-phase-readiness exports-map smoke", () => {
 	it("the runtime export set is exactly the declared surface", () => {
@@ -28,6 +28,7 @@ describe("two-phase-readiness exports-map smoke", () => {
 			"createPhase1PageHandler",
 			"getPageHandlerState",
 			"healthHandler",
+			"markFullAppDegraded",
 			"markFullAppReady",
 			"setPageHandler",
 		]);
@@ -38,6 +39,9 @@ describe("two-phase-readiness exports-map smoke", () => {
 	it("markFullAppReady is a function", () => {
 		expect(typeof mod["markFullAppReady"]).toBe("function");
 	});
+	it("markFullAppDegraded is a function", () => {
+		expect(typeof mod["markFullAppDegraded"]).toBe("function");
+	});
 	it("__resetPhase2StateForTest is a function", () => {
 		expect(typeof mod["__resetPhase2StateForTest"]).toBe("function");
 	});
@@ -52,51 +56,97 @@ describe("two-phase-readiness exports-map smoke", () => {
 	});
 	it("a fresh boot starts unready with no handler", async () => {
 		__resetPhase2StateForTest();
-		const got = getPageHandlerState();
-		expect(got).toEqual({ ready: false, hasHandler: false });
+		const got = getPageHandlerState()
+		expect(got).toEqual({"ready": false, "hasHandler": false});
+	});
+	it("markFullAppReady alone flips ready WITHOUT a handler — the client-render contract [toBe]", async () => {
+		__resetPhase2StateForTest();
+		markFullAppReady(); const got = getPageHandlerState()
+const got2 = (got.ready);
+		expect(got2).toEqual(true);
+	});
+	it("markFullAppReady alone flips ready WITHOUT a handler — the client-render contract [toBe]", async () => {
+		__resetPhase2StateForTest();
+		markFullAppReady(); const got = getPageHandlerState()
+const got2 = (got.hasHandler);
+		expect(got2).toEqual(false);
 	});
-	it("markFullAppReady alone flips ready WITHOUT a handler — the client-render contract", async () => {
+	it("setPageHandler implies ready AND a handler (the SSR contract) [toBe]", async () => {
 		__resetPhase2StateForTest();
-		markFullAppReady(); const got = getPageHandlerState();
-		expect(got.ready).toBe(true);
-		expect(got.hasHandler).toBe(false);
+		setPageHandler((() => async () => new Response("ok")) as never); const got = getPageHandlerState()
+const got2 = (got.ready);
+		expect(got2).toEqual(true);
 	});
-	it("setPageHandler implies ready AND a handler (the SSR contract)", async () => {
+	it("setPageHandler implies ready AND a handler (the SSR contract) [toBe]", async () => {
 		__resetPhase2StateForTest();
-		setPageHandler((() => async () => new Response("ok")) as never); const got = getPageHandlerState();
-		expect(got.ready).toBe(true);
-		expect(got.hasHandler).toBe(true);
+		setPageHandler((() => async () => new Response("ok")) as never); const got = getPageHandlerState()
+const got2 = (got.hasHandler);
+		expect(got2).toEqual(true);
 	});
-	it("/health reports 503 starting before phase 2", async () => {
+	it("/health reports 503 starting before phase 2 [toBe]", async () => {
 		__resetPhase2StateForTest(); __capabilityFault.value = null;
-		const got = healthHandler(__ctx as never) as Response;
-		expect(got.status).toBe(503);
-		expect((await got.json() as { status: string }).status).toBe("starting");
+		const got = healthHandler(__ctx as never) as Response
+const got2 = (got.status);
+		expect(got2).toEqual(503);
+	});
+	it("/health reports 503 starting before phase 2 [toBe]", async () => {
+		__resetPhase2StateForTest(); __capabilityFault.value = null;
+		const got = healthHandler(__ctx as never) as Response
+const got2 = ((await got.json() as { status: string }).status);
+		expect(got2).toEqual("starting");
+	});
+	it("/health asserts the capability, not just the phase flag [toBe]", async () => {
+		__resetPhase2StateForTest(); markFullAppReady(); __capabilityFault.value = "registered client carries no CRUD models";
+		const got = healthHandler(__ctx as never) as Response
+const got2 = (got.status);
+		expect(got2).toEqual(503);
 	});
-	it("/health asserts the capability, not just the phase flag", async () => {
+	it("/health asserts the capability, not just the phase flag [toBe]", async () => {
 		__resetPhase2StateForTest(); markFullAppReady(); __capabilityFault.value = "registered client carries no CRUD models";
-		const got = healthHandler(__ctx as never) as Response;
-		expect(got.status).toBe(503);
-		expect((await got.json() as { status: string }).status).toBe("degraded");
+		const got = healthHandler(__ctx as never) as Response
+const got2 = ((await got.json() as { status: string }).status);
+		expect(got2).toEqual("degraded");
 	});
-	it("/health answers ok once ready and the capability is intact", async () => {
+	it("/health answers ok once ready and the capability is intact [toBe]", async () => {
 		__resetPhase2StateForTest(); markFullAppReady(); __capabilityFault.value = null;
-		const got = healthHandler(__ctx as never) as Response;
-		expect(got.status).toBe(200);
-		expect((await got.json() as { status: string }).status).toBe("ok");
+		const got = healthHandler(__ctx as never) as Response
+const got2 = (got.status);
+		expect(got2).toEqual(200);
+	});
+	it("/health answers ok once ready and the capability is intact [toBe]", async () => {
+		__resetPhase2StateForTest(); markFullAppReady(); __capabilityFault.value = null;
+		const got = healthHandler(__ctx as never) as Response
+const got2 = ((await got.json() as { status: string }).status);
+		expect(got2).toEqual("ok");
+	});
+	it("the phase-1 page handler serves the branded waking 503 before phase 2 [toBe]", async () => {
+		__resetPhase2StateForTest();
+		const handler = createPhase1PageHandler("svc-tr")( {} as never );
+		const got = await handler(new Request("http://x.local/"), {} as never)
+const got2 = (got.status);
+		expect(got2).toEqual(503);
+	});
+	it("the phase-1 page handler serves the branded waking 503 before phase 2 [toContain]", async () => {
+		__resetPhase2StateForTest();
+		const handler = createPhase1PageHandler("svc-tr")( {} as never );
+		const got = await handler(new Request("http://x.local/"), {} as never)
+const got2 = (got.headers.get("content-type"));
+		const __t0_0 = got2;
+		expect(typeof __t0_0 === "string" ? __t0_0 : JSON.stringify(__t0_0)).toContain("text/html");
 	});
-	it("the phase-1 page handler serves the branded waking 503 before phase 2", async () => {
+	it("the phase-1 page handler serves the branded waking 503 before phase 2 [toBeNull]", async () => {
 		__resetPhase2StateForTest();
 		const handler = createPhase1PageHandler("svc-tr")( {} as never );
-		const got = await handler(new Request("http://x.local/"), {} as never);
-		expect(got.status).toBe(503);
-		expect(got.headers.get("content-type")).toContain("text/html");
-		expect(got.headers.get("retry-after")).not.toBeNull();
+		const got = await handler(new Request("http://x.local/"), {} as never)
+const got2 = (got.headers.get("retry-after"));
+		expect(got2).not.toBeNull();
+		expect(got2).not.toBeUndefined();
 	});
 	it("the phase-1 handler delegates to the real handler once registered", async () => {
 		__resetPhase2StateForTest(); setPageHandler((() => async () => new Response("real-render")) as never);
 		const handler = createPhase1PageHandler("svc-tr")( {} as never );
-		const got = await handler(new Request("http://x.local/"), {} as never);
-		expect(await got.text()).toBe("real-render");
+		const got = await handler(new Request("http://x.local/"), {} as never)
+const got2 = (await got.text());
+		expect(got2).toEqual("real-render");
 	});
 });

package/src/two-phase-readiness.ts

@@ -40,8 +40,9 @@
  */
 
 /**
- * `/health` for a UI service — 200 ONLY once the full app can actually render
- * a page, 503 before that.
+ * `/health` for a UI service — 503 `{"status":"starting"}` until phase 2
+ * completes, then 200: `{"status":"degraded","reason":...}` when the client
+ * build failed, `{"status":"ok"}` otherwise.
  *
  * 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
@@ -72,14 +73,22 @@
  * 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.
+ * "binary: fully-ready or cleanly-unavailable".
+ *
+ * DEGRADED COMPLETION IS A 200, NOT A THIRD KIND OF STARTING (measured
+ * 2026-10-14, portal-dev). The degraded path (client build not servable) first
+ * returned before the phase-2 flips, so `/health` answered 503 "starting"
+ * forever — a state the boot KNEW was false. Every health-gated consumer reads
+ * 503 as still-booting: `build_executor::deploy_probe::still_booting` resets
+ * its answered-rounds counter on "503 Service Unavailable", so the dev-update
+ * rehearsal probed a finished boot for 2.5h and never completed; the activator
+ * wake gate would hold a customer forever. The boot's own verdict — degraded,
+ * with the recorded reason in the body — is the honest answer, and it lets
+ * traffic flow to the branded holding page the app itself serves.
  *
  * 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.
+ * one consumer contract is "has boot completed", is moved to phase 2.
  */
 
 import { buildWakingPageHtml } from "@teamscala/brand/brand/waking-page-html";
@@ -93,6 +102,19 @@ import type { CreatePageHandler } from "./types.ts";
 // This allows the temporary Phase 1 handler to delegate to the real handler once ready.
 let realPageHandler: CreatePageHandler | null = null;
 let fullAppReady = false;
+let degradedReason: string | null = null;
+
+/**
+ * Phase 2 completed DEGRADED: the client build is not servable, so the full
+ * route set never registered — but the boot itself finished, and the process
+ * serves its API, MCP and job surfaces plus the branded holding page for
+ * pages. `fullAppReady` flips true because "starting" is no longer true; the
+ * reason travels beside it so `/health` can report the real verdict.
+ */
+export function markFullAppDegraded(reason: string): void {
+	degradedReason = reason;
+	fullAppReady = true;
+}
 
 /**
  * Set the real page handler (called when Phase 2 completes on an SSR service).
@@ -113,6 +135,7 @@ export function markFullAppReady(): void {
 export function __resetPhase2StateForTest(): void {
 	realPageHandler = null;
 	fullAppReady = false;
+	degradedReason = null;
 }
 
 /**
@@ -124,6 +147,9 @@ export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
 
 export function healthHandler(c: Context): Response {
 	if (!fullAppReady) return c.json({ status: "starting" }, 503, { "Retry-After": "1" });
+	if (degradedReason !== null) {
+		return c.json({ status: "degraded", reason: degradedReason });
+	}
 	// 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

package/src/types.test.ts

@@ -1,10 +1,10 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
  * ./types declares 0 runtime export(s) + 5 type(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 
@@ -13,8 +13,7 @@ import { describe, expect, it } from "bun:test";
 const mod = await import("./types");
 
 describe("types exports-map smoke", () => {
-	it("is type-only — the runtime module carries no values", () => {
-		// Declared types: RendererComponentEntry, PageHandlerExtras, CreatePageHandler, PageHandlerConfig, ServiceInstallConfig
+	it("is type-only (declared: RendererComponentEntry, PageHandlerExtras, CreatePageHandler, PageHandlerConfig, ServiceInstallConfig) — the runtime module carries no values", () => {
 		expect(Object.keys(mod).length).toBe(0);
 	});
 });

package/src/ui-service.test.ts

@@ -1,10 +1,10 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
  * ./ui-service declares 1 runtime export(s) + 3 type(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */