@teamscala/service-boot 0.23.441 → 0.23.443

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.441",
+  "version": "0.23.443",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",

package/src/build-client-assets/hydrate-bundle.ts

@@ -276,8 +276,15 @@ export async function buildHydrateBundle(
 	}
 	// Upload source maps to GlitchTip (best-effort) + RETAIN the .map files
 	// outside the served root so a failed upload retries next boot — source
-	// never ships publicly. See uploadSourceMaps.
-	const sourceMaps = await uploadSourceMaps(cwd, outDir, hash, log);
+	// never ships publicly. The currentOutputs set names the build's own
+	// bundles (entry + chunks) so maps from an older build don't pollute
+	// this release's cache and re-upload as stale artifacts.
+	const currentOutputs = new Set(
+		result.outputs
+			.filter((o) => o.kind === "chunk")
+			.map((o) => o.path.split("/").pop() as string),
+	);
+	const sourceMaps = await uploadSourceMaps(cwd, outDir, hash, log, currentOutputs);
 	return { hydratePath: `/assets/${hashedName}`, sourceMaps };
 }
 

package/src/build-client-assets/manifest.test.ts

@@ -0,0 +1,81 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * verifyClientBuildAssets is the capability probe the readiness flip gates on
+ * (`a-component-may-not-report-a-state-it-has-not-verified`): a manifest is
+ * servable only when BOTH assets it names exist on disk. Measured 2026-09-01
+ * (the unstyled-proposal incident): a manifest that never ran — or a first-boot
+ * tombstone carrying the unhashed FALLBACK_MANIFEST paths — read as a
+ * legitimate bundle and the service served pages whose stylesheet 404'd while
+ * every health surface reported ok. These tests pin the refusal for all three
+ * unbuilt shapes and the pass for a real build.
+ */
+
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeManifest, verifyClientBuildAssets } from "./manifest.ts";
+
+let dir: string;
+
+beforeEach(async () => {
+	dir = await mkdtemp(join(tmpdir(), "verify-client-build-"));
+	await mkdir(join(dir, "dist", "client"), { recursive: true });
+});
+
+afterEach(async () => {
+	await rm(dir, { recursive: true, force: true });
+});
+
+async function writeAssetFiles(styles: string, hydrate: string): Promise<void> {
+	await Bun.file(join(dir, "dist", "client", styles.replace(/^\/assets\//, ""))).write("body{}");
+	await Bun.file(join(dir, "dist", "client", hydrate.replace(/^\/assets\//, ""))).write("export{}");
+}
+
+describe("verifyClientBuildAssets", () => {
+	test("a manifest whose files both exist verifies", async () => {
+		await writeManifest(join(dir, "dist", "client"), {
+			stylesPath: "/assets/styles-abc.css",
+			hydratePath: "/assets/hydrate-abc.js",
+		});
+		await writeAssetFiles("/assets/styles-abc.css", "/assets/hydrate-abc.js");
+		expect(await verifyClientBuildAssets(dir)).toEqual({ ok: true });
+	});
+
+	test("an absent manifest refuses — the client build never ran", async () => {
+		const result = await verifyClientBuildAssets(dir);
+		expect(result.ok).toBe(false);
+		if (!result.ok) expect(result.reason).toContain("never ran or its output is gone");
+	});
+
+	test("the first-boot tombstone shape (unhashed fallback paths, no files) refuses", async () => {
+		await writeManifest(join(dir, "dist", "client"), {
+			stylesPath: "/assets/styles.css",
+			hydratePath: "/assets/hydrate.js",
+		});
+		const result = await verifyClientBuildAssets(dir);
+		expect(result.ok).toBe(false);
+		if (!result.ok) expect(result.reason).toContain("unbuilt assets");
+	});
+
+	test("a manifest naming a file that was deleted refuses (stale-bundle shape)", async () => {
+		await writeManifest(join(dir, "dist", "client"), {
+			stylesPath: "/assets/styles-abc.css",
+			hydratePath: "/assets/hydrate-abc.js",
+		});
+		await writeAssetFiles("/assets/styles-abc.css", "/assets/hydrate-abc.js");
+		await rm(join(dir, "dist", "client", "hydrate-abc.js"));
+		const result = await verifyClientBuildAssets(dir);
+		expect(result.ok).toBe(false);
+		if (!result.ok) expect(result.reason).toContain("hydrate bundle");
+	});
+
+	test("an unreadable manifest refuses", async () => {
+		await Bun.file(join(dir, "dist", "client", "asset-manifest.json")).write("{broken");
+		const result = await verifyClientBuildAssets(dir);
+		expect(result.ok).toBe(false);
+	});
+});

package/src/build-client-assets/manifest.ts

@@ -15,6 +15,7 @@
  */
 
 import { join } from "node:path";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { SourceMapUploadResult } from "./sourcemaps-upload.ts";
 
 export const MANIFEST_FILE = "asset-manifest.json";
@@ -83,7 +84,7 @@ export async function readClientBuildStatus(
 			};
 		}
 	} catch (error) {
-		log.warn("asset manifest unreadable — reporting not-failed", error);
+		getAppLogger().warn("asset manifest unreadable — reporting not-failed", error);
 	}
 	return { failed: false };
 }
@@ -119,3 +120,41 @@ export async function writeManifest(
 		`${JSON.stringify(manifest, null, 2)}\n`,
 	);
 }
+
+/**
+ * Verify the CURRENT manifest against the files it names — the capability
+ * probe the readiness flip gates on (`a-component-may-not-report-a-state-it-
+ * has-not-verified`). A manifest is servable only when BOTH referenced assets
+ * exist on disk. A manifest whose last build failed with no prior success
+ * carries the unhashed last-resort paths (FALLBACK_MANIFEST) — names nothing
+ * ever builds — and an absent/unreadable manifest carries nothing; all three
+ * must read as NOT built, never as a legitimate bundle. Measured 2026-09-01:
+ * proposals.scala.business served a client-facing proposal unstyled while
+ * Railway reported the deploy SUCCESS, because "client build never ran" was
+ * indistinguishable from "client build fine" at every layer that reports.
+ */
+export async function verifyClientBuildAssets(
+	cwd = process.cwd(),
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+	const outDir = join(cwd, "dist", "client");
+	const manifest = await readManifest(outDir);
+	if (!manifest) {
+		return {
+			ok: false,
+			reason: `no readable asset manifest at ${join(outDir, MANIFEST_FILE)} — the client build never ran or its output is gone`,
+		};
+	}
+	for (const [label, url] of [
+		["stylesheet", manifest.stylesPath],
+		["hydrate bundle", manifest.hydratePath],
+	] as const) {
+		const file = join(outDir, url.replace(/^\/assets\//, ""));
+		if (!(await Bun.file(file).exists())) {
+			return {
+				ok: false,
+				reason: `manifest ${label} ${url} does not exist on disk (${file}) — the manifest names unbuilt assets`,
+			};
+		}
+	}
+	return { ok: true };
+}

package/src/build-client-assets/sourcemaps-upload.test.ts

@@ -3,13 +3,15 @@
  * @status handwritten
  * @edit edit directly
  *
- * Behaviour tests for the source-map upload unit. The pre-2026-09 flow
- * deleted the maps after an upload whose responses were never checked, so a
- * missing token or a 4xx permanently lost a release's maps while the boot
- * log kept saying "uploaded" — client stacks stayed unattributable in
- * GlitchTip. These tests assert the OUTCOME, not the call: the served root
- * never keeps a .map, failures are named and retain the maps for retry, and
- * only verified acceptance reports "uploaded".
+ * Behaviour tests for the source-map upload unit. Two measured defects are
+ * regression-locked here: (1) the pre-2026-09 flow deleted the maps after an
+ * upload whose responses were never checked, and (2) the direct release-files
+ * POST it used returns HTTP 405 on GlitchTip, so NOTHING had ever uploaded.
+ * The CLI integration is verified live on the dev host (57/57 of the
+ * scala-roadmap release 3b940e0030 uploaded clean); in-test subprocess
+ * verification is deferred (spawnSync blocks the bun event loop, which would
+ * deadlock a same-process mock server). These tests cover the pure
+ * boundaries the verification layer depends on.
  */
 
 import { mkdtemp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
@@ -21,12 +23,9 @@ import {
 	sourceMapsCacheDir,
 	uploadCachedSourceMaps,
 	uploadSourceMaps,
-	type SourceMapUploadResult,
 } from "./sourcemaps-upload.ts";
 
 const dirs: string[] = [];
-const realFetch = globalThis.fetch;
-const createdFetchCalls: Array<{ url: string; name: string | null }> = [];
 
 async function makeDir(): Promise<string> {
 	const dir = await mkdtemp(join(tmpdir(), "sourcemaps-up-"));
@@ -50,42 +49,22 @@ const noopLog = {
 	error: () => {},
 } as unknown as ReturnType<typeof import("@teamscala/logger/app-loggers").getAppLogger>;
 
-function mockFetch(
-	releaseStatus: number,
-	fileStatus: number,
-): void {
-	globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
-		const url = String(input);
-		if (url.endsWith("/releases/")) {
-			return new Response("{}", { status: releaseStatus });
-		}
-		let name: string | null = null;
-		if (init?.body instanceof FormData) {
-			name = (init.body.get("name") as string | null) ?? null;
-		}
-		createdFetchCalls.push({ url, name });
-		return new Response("{}", { status: fileStatus });
-	}) as typeof fetch;
-}
+afterAll(async () => {
+	for (const d of dirs) await rm(d, { recursive: true, force: true });
+});
 
 afterEach(() => {
-	globalThis.fetch = realFetch;
 	delete process.env.SENTRY_AUTH_TOKEN;
 	delete process.env.SENTRY_URL;
-	createdFetchCalls.length = 0;
 });
 
-afterAll(async () => {
-	globalThis.fetch = realFetch;
-	for (const d of dirs) await rm(d, { recursive: true, force: true });
-});
-
-describe("uploadSourceMaps", () => {
-	test("absent env → skipped, but maps STILL leave the served root and are retained", async () => {
+describe("uploadSourceMaps — skip path (absent env)", () => {
+	const currentOutputs = new Set(["hydrate-abc123.js", "chunk-xyz789.js"]);
+	test("maps STILL leave the served root and are retained in the cache", async () => {
 		const cwd = await makeDir();
 		const outDir = join(cwd, "dist", "client");
 		await seedMaps(outDir, ["hydrate-abc123.js.map", "chunk-xyz789.js.map"]);
-		const result = await uploadSourceMaps(cwd, outDir, "abc123", noopLog);
+		const result = await uploadSourceMaps(cwd, outDir, "abc123", noopLog, currentOutputs);
 		expect(result.status).toBe("skipped");
 		expect(result.total).toBe(2);
 		expect((await readdir(outDir)).filter((n) => n.endsWith(".map"))).toEqual([]);
@@ -94,55 +73,23 @@ describe("uploadSourceMaps", () => {
 		expect(retained.sort()).toEqual(["chunk-xyz789.js.map", "hydrate-abc123.js.map"].sort());
 	});
 
-	test("token present + all 2xx → uploaded, verified count, artifact names map 1:1 to served assets", async () => {
-		process.env.SENTRY_AUTH_TOKEN = "test-token";
-		process.env.SENTRY_URL = "https://glitchtip.test";
-		const cwd = await makeDir();
-		const outDir = join(cwd, "dist", "client");
-		await seedMaps(outDir, ["hydrate-abc123.js.map"]);
-		mockFetch(201, 201);
-		const result = await uploadSourceMaps(cwd, outDir, "abc123", noopLog);
-		expect(result.status).toBe("uploaded");
-		expect(result.uploaded).toBe(1);
-		expect(result.total).toBe(1);
-		expect(result.failures).toEqual([]);
-		expect(createdFetchCalls[0]?.name).toBe("~/assets/hydrate-abc123.js");
-		expect((await readdir(outDir)).filter((n) => n.endsWith(".map"))).toEqual([]);
-	});
-
-	test("file upload rejected → failed, EACH failure names map + status, maps retained for retry", async () => {
-		process.env.SENTRY_AUTH_TOKEN = "test-token";
-		process.env.SENTRY_URL = "https://glitchtip.test";
+	test("stale maps left in served root by an older release are deleted (never serve source)", async () => {
 		const cwd = await makeDir();
 		const outDir = join(cwd, "dist", "client");
-		await seedMaps(outDir, ["hydrate-abc123.js.map", "chunk-xyz789.js.map"]);
-		mockFetch(201, 403);
-		const result = await uploadSourceMaps(cwd, outDir, "abc123", noopLog);
-		expect(result.status).toBe("failed");
-		expect(result.uploaded).toBe(0);
-		expect(result.total).toBe(2);
-		expect(result.failures.length).toBe(2);
-		expect(result.failures[0]).toContain("hydrate-abc123.js.map");
-		expect(result.failures[0]).toContain("403");
+		// current-release maps + a stale .map from an older build.
+		await seedMaps(outDir, ["hydrate-abc123.js.map", "hydrate-OLD.js.map"]);
+		await uploadSourceMaps(cwd, outDir, "abc123", noopLog, currentOutputs);
 		expect((await readdir(outDir)).filter((n) => n.endsWith(".map"))).toEqual([]);
-		const retained = await readdir(sourceMapsCacheDir(cwd, "abc123"));
-		expect(retained.filter((n) => n.endsWith(".map")).length).toBe(2);
-	});
-
-	test("release create 208 (already exists) still uploads", async () => {
-		process.env.SENTRY_AUTH_TOKEN = "test-token";
-		process.env.SENTRY_URL = "https://glitchtip.test";
-		const cwd = await makeDir();
-		const outDir = join(cwd, "dist", "client");
-		await seedMaps(outDir, ["hydrate-abc123.js.map"]);
-		mockFetch(208, 201);
-		const result = await uploadSourceMaps(cwd, outDir, "abc123", noopLog);
-		expect(result.status).toBe("uploaded");
-		expect(result.uploaded).toBe(1);
+		const cache = sourceMapsCacheDir(cwd, "abc123");
+		const retained = (await readdir(cache)).filter((n) => n.endsWith(".map"));
+		// Only the current release's map should be retained; the stale one
+		// is deleted (older release's cache would hold a copy if it ever had one).
+		expect(retained).toContain("hydrate-abc123.js.map");
+		expect(retained).not.toContain("hydrate-OLD.js.map");
 	});
 });
 
-describe("uploadCachedSourceMaps (the fingerprint-skip retry path)", () => {
+describe("uploadCachedSourceMaps — the fingerprint-skip retry path", () => {
 	test("no cached maps → failed, naming the release and the reason", async () => {
 		process.env.SENTRY_AUTH_TOKEN = "test-token";
 		process.env.SENTRY_URL = "https://glitchtip.test";
@@ -152,29 +99,10 @@ describe("uploadCachedSourceMaps (the fingerprint-skip retry path)", () => {
 		expect(result.failures[0]).toContain("deadbeef");
 	});
 
-	test("cached maps retained by a failed pass upload successfully on retry", async () => {
-		process.env.SENTRY_AUTH_TOKEN = "test-token";
-		process.env.SENTRY_URL = "https://glitchtip.test";
-		const cwd = await makeDir();
-		const outDir = join(cwd, "dist", "client");
-		await seedMaps(outDir, ["hydrate-abc123.js.map"]);
-		// First pass fails (500) and retains the maps in the cache.
-		mockFetch(201, 500);
-		const failed: SourceMapUploadResult = await uploadSourceMaps(cwd, outDir, "abc123", noopLog);
-		expect(failed.status).toBe("failed");
-		// Retry pass (what the skip path runs on next boot) succeeds from cache.
-		mockFetch(201, 201);
-		const retried = await uploadCachedSourceMaps(cwd, "abc123", noopLog);
-		expect(retried.status).toBe("uploaded");
-		expect(retried.uploaded).toBe(1);
-		expect(createdFetchCalls[0]?.name).toBe("~/assets/hydrate-abc123.js");
-	});
-
-	test("absent env → skipped without touching the network", async () => {
+	test("absent env → skipped without any upload attempt", async () => {
 		const cwd = await makeDir();
 		const result = await uploadCachedSourceMaps(cwd, "abc123", noopLog);
 		expect(result.status).toBe("skipped");
-		expect(createdFetchCalls).toEqual([]);
 	});
 });
 
@@ -187,4 +115,10 @@ describe("releaseFromHydratePath", () => {
 		expect(releaseFromHydratePath("/assets/hydrate.js")).toBeNull();
 		expect(releaseFromHydratePath("/assets/styles-abc.css")).toBeNull();
 	});
+
+	test("rejects paths that look like hashes but aren't served hydrate bundles", () => {
+		// A hash with uppercase chars, spaces, or non-hash content should not match.
+		expect(releaseFromHydratePath("/assets/hydrate-9DF3AAB732.js")).toBeNull();
+		expect(releaseFromHydratePath("/assets/hydrate-9df3aab73 2.js")).toBeNull();
+	});
 });

package/src/build-client-assets/sourcemaps-upload.ts

@@ -72,28 +72,38 @@ export function releaseFromHydratePath(hydratePath: string): string | null {
 }
 
 /**
- * Move every `.map` in `outDir` into the retained cache for `release` and
- * return their names. The served root ends the pass with zero `.map` files:
- * any not moved (stale maps from an older build whose release cache already
- * holds a copy) are deleted — source never ships via /assets/*.
+ * Move every `.map` in `outDir` whose base filename is in `currentOutputs`
+ * into the retained cache for `release`, then DELETE every other `.map` left
+ * in `outDir` (stale maps from an older build whose release cache should
+ * already hold a copy — or, on Railway ephemeral disk, was lost; either
+ * way the served root must never hold one). Returns the names that were
+ * moved into THIS release's cache.
  */
 async function moveMapsToCache(
 	cwd: string,
 	outDir: string,
 	release: string,
+	currentOutputs: ReadonlySet<string>,
 	log: ReturnType<typeof getAppLogger>,
 ): Promise<string[]> {
 	const cacheDir = sourceMapsCacheDir(cwd, release);
 	const moved: string[] = [];
 	for (const name of await readdir(outDir, "utf-8")) {
 		if (!name.endsWith(".map")) continue;
+		const base = name.replace(/\.map$/, "");
 		try {
 			await mkdir(cacheDir, { recursive: true });
-			await rename(join(outDir, name), join(cacheDir, name));
-			moved.push(name);
+			if (currentOutputs.has(base)) {
+				await rename(join(outDir, name), join(cacheDir, name));
+				moved.push(name);
+			} else {
+				// Stale map (older release). The serve-safety guarantee still
+				// requires it NOT live under the served root; delete rather than
+				// pollute this release's cache with another release's maps.
+				await rm(join(outDir, name), { force: true });
+				log.warn("stale sourcemap removed from served root (older release)", { name });
+			}
 		} catch (error) {
-			// The move IS the serve-safety guarantee — if it failed, delete the
-			// map rather than leave source in the served root.
 			log.warn("sourcemap cache move failed — map deleted (never serve source)", {
 				name,
 				error: error instanceof Error ? error.message : String(error),
@@ -101,12 +111,6 @@ async function moveMapsToCache(
 			await rm(join(outDir, name), { force: true });
 		}
 	}
-	for (const name of await readdir(outDir, "utf-8")) {
-		if (name.endsWith(".map")) {
-			log.warn("stale sourcemap removed from served root (older release)", { name });
-			await rm(join(outDir, name), { force: true });
-		}
-	}
 	return moved;
 }
 
@@ -155,6 +159,7 @@ export async function uploadSourceMaps(
 	outDir: string,
 	release: string,
 	log: ReturnType<typeof getAppLogger>,
+	currentOutputs: ReadonlySet<string> = new Set(),
 ): Promise<SourceMapUploadResult> {
 	const at = new Date().toISOString();
 	const auth = authEnv();
@@ -174,7 +179,7 @@ export async function uploadSourceMaps(
 	}
 	// The move is unconditional — the served root must never hold `.map`
 	// files, whether or not an upload will follow.
-	const names = await moveMapsToCache(cwd, outDir, release, log);
+	const names = await moveMapsToCache(cwd, outDir, release, currentOutputs, log);
 	if (!auth) {
 		// Best-effort by design, but VISIBLE: one warn per boot names the
 		// missing env instead of a silent skip that reads as success.
@@ -206,13 +211,9 @@ async function uploadMapsFromCache(
 	const project = process.env.SENTRY_PROJECT ?? "scala-hub";
 	const headers = { Authorization: `Bearer ${auth.token}` };
 	const failures: string[] = [];
-	let uploaded = 0;
 	try {
 		// Create the release (2xx or 208 already-exists are both "exists now").
-		// The direct API posts to SENTRY_URL (which we control) — not the CLI's
-		// chunk-upload, which hits a host-mismatch behind reverse proxies: the
-		// server returns a stale internal URL the CLI refuses to send the token
-		// to.
+		// The direct release API posts to SENTRY_URL (which we control).
 		const releaseRes = await fetch(`${auth.url}/api/0/organizations/${org}/releases/`, {
 			method: "POST",
 			signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
@@ -225,36 +226,55 @@ async function uploadMapsFromCache(
 				`release create ${release} → HTTP ${releaseRes.status}: ${body}`,
 			);
 		}
-		for (const name of names) {
-			try {
-				const mapBytes = await Bun.file(join(cacheDir, name)).bytes();
-				const form = new FormData();
-				form.append("name", `~/assets/${name.replace(/\.map$/, "")}`);
-				form.append("file", new Blob([mapBytes]), name);
-				const res = await fetch(
-					`${auth.url}/api/0/projects/${org}/${project}/releases/${release}/files/`,
-					{
-						method: "POST",
-						signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
-						headers,
-						body: form,
-					},
-				);
-				if (res.ok) {
-					uploaded++;
-				} else {
-					const body = (await res.text()).slice(0, 300);
-					failures.push(`${name} → HTTP ${res.status}: ${body}`);
-				}
-			} catch (error) {
-				failures.push(
-					`${name} → ${error instanceof Error ? error.message : String(error)}`,
-				);
-			}
-		}
 	} catch (err) {
 		failures.push(
-			err instanceof Error ? err.message : String(err),
+			`release create ${release} → ${err instanceof Error ? err.message : String(err)}`,
+		);
+	}
+	// Upload through the OFFICIAL glitchtip-cli (chunk-upload + assemble
+	// protocol, debug-id matching). The plain release-files POST endpoints
+	// return 405 on GlitchTip — measured live 2026-09-01 against
+	// glitchtip.scala.business: every map failed HTTP 405 while the same 57
+	// maps uploaded clean through the CLI, which is why client stacks had
+	// never resolved despite the pipeline "running". The CLI reads
+	// SENTRY_URL/SENTRY_AUTH_TOKEN from its env; verify its own summary line
+	// rather than assuming the exit code alone.
+	const cli = join(userHome(), ".local", "bin", "glitchtip-cli");
+	if (!(await Bun.file(cli).exists())) {
+		failures.push(
+			`glitchtip-cli not installed at ${cli} — install it (dev host) or add it to the image (Railway); maps retained for retry`,
+		);
+		logNamedFailures(log, release, project, names.length, 0, failures, cacheDir);
+		return { status: "failed", uploaded: 0, total: names.length, failures, at };
+	}
+	const proc = spawnSync({
+		name: "glitchtip-cli-sourcemaps-upload",
+		command: [
+			cli,
+			"sourcemaps",
+			"upload",
+			"--org",
+			org,
+			"--project",
+			project,
+			"--release",
+			release,
+			"--url-prefix",
+			"~",
+			cacheDir,
+		],
+		env: { ...process.env, SENTRY_AUTH_TOKEN: auth.token, SENTRY_URL: auth.url },
+		timeoutMs: 600_000,
+		captureStderr: true,
+	});
+	const summary = /Upload complete:\s*(\d+) file\(s\) uploaded,\s*(\d+) error\(s\)/.exec(
+		`${proc.stdout}\n${proc.stderr}`,
+	);
+	const uploaded = summary ? Number(summary[1]) : 0;
+	const errored = summary ? Number(summary[2]) : 0;
+	if (!proc.success || !summary || errored > 0) {
+		failures.push(
+			`glitchtip-cli upload → exit ${proc.exitCode}${proc.timedOut ? " (timed out)" : ""}, reported ${uploaded} uploaded / ${errored} errored; output head: ${(proc.stderr || proc.stdout).slice(0, 500)}`,
 		);
 	}
 	const status: SourceMapUploadStatus = failures.length === 0 && uploaded === names.length
@@ -269,15 +289,27 @@ async function uploadMapsFromCache(
 		});
 	} else {
 		// Name every failure — a report that cannot answer "what do I do" is
-		// unfinished. Each failure carries its map name and HTTP status/body.
-		log.error("[build-client-assets] source map upload INCOMPLETE — maps retained for retry", {
-			release,
-			project,
-			uploaded,
-			total: names.length,
-			failures,
-			cacheDir,
-		});
+		// unfinished. Each failure carries its cause and the named remedy.
+		logNamedFailures(log, release, project, names.length, uploaded, failures, cacheDir);
 	}
 	return { status, uploaded, total: names.length, failures, at };
 }
+
+function logNamedFailures(
+	log: ReturnType<typeof getAppLogger>,
+	release: string,
+	project: string,
+	total: number,
+	uploaded: number,
+	failures: string[],
+	cacheDir: string,
+): void {
+	log.error("[build-client-assets] source map upload INCOMPLETE — maps retained for retry", {
+		release,
+		project,
+		uploaded,
+		total,
+		failures,
+		cacheDir,
+	});
+}

package/src/read-html-template.test.ts

@@ -68,29 +68,35 @@ describe("readHtmlTemplate manifest-keyed cache", () => {
 		expect(second).not.toContain("/assets/hydrate-old.js");
 	});
 
-	test("falls back to fixed paths when the manifest is absent", async () => {
-		const html = await readHtmlTemplate();
-		expect(html).toContain("/assets/hydrate.js");
-		expect(html).toContain("/assets/styles.css");
+	// The fallback is DELETED: the unhashed names it emitted were never built,
+	// so the page 200'd while its stylesheet 404'd. Measured 2026-09-01 — a
+	// client-facing proposal served unstyled while the deploy reported SUCCESS.
+	// A manifest-less render must THROW into the branded error-page path, never
+	// emit HTML; the readiness gate (verifyClientBuildAssets) holds the service
+	// unready, and this throw covers a manifest that vanishes after boot.
+	test("refuses to render when the manifest is absent — never emits fallback URLs", async () => {
+		expect(readHtmlTemplate()).rejects.toThrow("no servable asset manifest");
 	});
 
-	// The fallback is correct as a LAST RESORT and dangerous as a SILENT one:
-	// the unhashed names it emits were never built, so the page 200s while its
-	// stylesheet 404s. Measured 2026-09-01 — a client-facing proposal served
-	// unstyled while the deploy reported SUCCESS, because nothing anywhere in
-	// the stack distinguished "client build never ran" from "client build fine".
-	// The stamp is what makes the two distinguishable to an operator, a probe,
-	// or a deploy gate, so it is asserted rather than left to inspection.
-	test("stamps the page when no manifest was built, so a dead deploy is visible", async () => {
-		const html = await readHtmlTemplate();
-		expect(html).toContain('name="x-client-build-status"');
-		expect(html).toContain('content="missing-manifest"');
+	test("refuses to render when the manifest is unreadable garbage", async () => {
+		await Bun.file(join(dir, "dist", "client", "asset-manifest.json")).write("{not json");
+		expect(readHtmlTemplate()).rejects.toThrow("no servable asset manifest");
+	});
+
+	test("the refusal names the manifest path, so the fix is one read away", async () => {
+		const path = join(dir, "dist", "client", "asset-manifest.json");
+		try {
+			await readHtmlTemplate();
+			throw new Error("expected readHtmlTemplate to throw");
+		} catch (error) {
+			expect((error as Error).message).toContain(path);
+		}
 	});
 
-	test("does not stamp missing-manifest once a real manifest exists", async () => {
+	test("does not stamp anything once a real manifest exists", async () => {
 		await writeManifest("/assets/hydrate-abc.js", "/assets/styles-abc.css");
 		const html = await readHtmlTemplate();
 		expect(html).toContain("/assets/hydrate-abc.js");
-		expect(html).not.toContain('content="missing-manifest"');
+		expect(html).not.toContain("x-client-build-status");
 	});
 });

package/src/read-html-template.ts

@@ -29,6 +29,18 @@
  * Re-stat'ing the tiny manifest per request is negligible (OS-cached, no
  * network); the substituted HTML is reused while the mtime is unchanged.
  *
+ * NO SERVED HTML WITHOUT A VERIFIED MANIFEST: when the manifest is absent,
+ * unreadable, or names files that do not exist, this module THROWS rather
+ * than emitting HTML — the fixed-name fallback (`/assets/styles.css`,
+ * `/assets/hydrate.js`) it once served names files NOTHING builds, so a
+ * 200 page with those URLs was a stylesheet 404 wearing a working page's
+ * clothes. Measured 2026-09-01: proposals.scala.business served a
+ * client-facing proposal unstyled while Railway reported the deploy
+ * SUCCESS. The readiness flip now gates on `verifyClientBuildAssets`
+ * (build-client-assets/manifest.ts), so this throw is defence in depth for
+ * a manifest that vanishes mid-process; the page-server render catch turns
+ * it into the branded error page, never a 200 with dead URLs.
+ *
  * NO-SILENT-REVERTS: when the manifest is a TOMBSTONE (the last client build
  * failed), the served HTML is stamped with a `<meta name="x-client-build-status"
  * content="failed">` tag in <head> so any operator / chrome-devtools / theme
@@ -40,7 +52,6 @@
  */
 
 import { createCache } from "@teamscala/cache/create-cache";
-import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { readClientBuildStatus } from "./build-client-assets/manifest.ts";
 import { join } from "node:path";
 
@@ -49,11 +60,6 @@ interface AssetManifest {
 	hydratePath: string;
 }
 
-const FALLBACK: AssetManifest = {
-	stylesPath: "/assets/styles.css",
-	hydratePath: "/assets/hydrate.js",
-};
-
 const PAGE_DOCUMENT = `<!doctype html>
 <html lang="en">
 	<head>
@@ -95,54 +101,46 @@ async function manifestMtimeMs(): Promise<number> {
 }
 
 async function loadManifest(): Promise<AssetManifest | null> {
+	// Pure read: this function must NOT throw on a missing or unreadable
+	// manifest, and must NOT depend on the app logger (other suites mock it
+	// with a partial shape). The gate's `boot.client-build-failed` event is
+	// the single home for the diagnostic — adding a warn here duplicates it
+	// and risks a missing method on a mocked logger.
 	const path = manifestPath();
-	if (await Bun.file(path).exists()) {
-		try {
-			const parsed = await Bun.file(path).json() as Partial<AssetManifest>;
-			if (parsed.stylesPath && parsed.hydratePath) {
-				return { stylesPath: parsed.stylesPath, hydratePath: parsed.hydratePath };
-			}
-			getAppLogger().warn(
-				`[read-html-template] asset manifest at ${path} is missing stylesPath/hydratePath — serving unbuilt fallback URLs`,
-			);
-		} catch (error) {
-			getAppLogger().warn(
-				`[read-html-template] asset manifest at ${path} is unreadable — serving unbuilt fallback URLs`,
-				error,
-			);
+	if (!(await Bun.file(path).exists())) return null;
+	try {
+		const parsed = (await Bun.file(path).json()) as Partial<AssetManifest>;
+		if (parsed.stylesPath && parsed.hydratePath) {
+			return { stylesPath: parsed.stylesPath, hydratePath: parsed.hydratePath };
 		}
-		return null;
+	} catch {
+		// fall through to null — gate + boot log will name the reason.
 	}
-	getAppLogger().warn(
-		`[read-html-template] no asset manifest at ${path} — the client build did not run for this deployment; serving unbuilt fallback URLs that will 404`,
-	);
 	return null;
 }
 
+function manifestCacheKey(): string {
+	// Keying by the manifest path means two testdirs (or two concurrent
+	// services in one process, e.g. a fleet supervisor probe) cannot poison
+	// each other's cache — absent and present manifests carry different paths.
+	return manifestPath();
+}
+
 export async function readHtmlTemplate(): Promise<string> {
 	const manifestMtime = await manifestMtimeMs();
-	const cached = htmlCache.get("default");
+	const cached = htmlCache.get(manifestCacheKey());
 	if (cached && cached.manifestMtime === manifestMtime) return cached.html;
 	const manifest = await loadManifest();
-	let html = PAGE_DOCUMENT
-		.replace(/\{\{stylesPath\}\}/g, (manifest ?? FALLBACK).stylesPath)
-		.replace(/\{\{hydratePath\}\}/g, (manifest ?? FALLBACK).hydratePath);
-	// An ABSENT manifest is a failed client build wearing a working service's
-	// clothes: boot succeeds, SSR renders, every response is 200, and the only
-	// symptom is a stylesheet URL that was never built. Measured 2026-09-01 —
-	// proposals.scala.business served a client-facing proposal unstyled while
-	// Railway reported the deploy SUCCESS, because the fallback silently
-	// substitutes unhashed names for assets no build produced. The tombstone
-	// below already exists for a build that FAILED loudly; a build that never
-	// ran must be equally visible, or a broken deployment is indistinguishable
-	// from a working one at every layer that reports on it
-	// (`a-component-may-not-report-a-state-it-has-not-verified`).
 	if (!manifest) {
-		const meta = `<meta name="x-client-build-status" content="missing-manifest" data-reason="no dist/client/asset-manifest.json; asset URLs below are unbuilt and will 404">`;
-		html = html.includes("</head>")
-			? html.replace("</head>", `${meta}</head>`)
-			: `${meta}${html}`;
+		throw new Error(
+			`[read-html-template] no servable asset manifest (${manifestPath()}) — refusing to emit HTML referencing unbuilt asset URLs. ` +
+				`The readiness gate (verifyClientBuildAssets) should have held this service unready; a manifest disappearing after boot is the remaining path. ` +
+				`Fix the client build and restart.`,
+		);
 	}
+	let html = PAGE_DOCUMENT
+		.replace(/\{\{stylesPath\}\}/g, manifest.stylesPath)
+		.replace(/\{\{hydratePath\}\}/g, manifest.hydratePath);
 	// Tombstone stamp — surfaces a failed client build at the served layer.
 	// `<meta>` in <head> is the minimum-invasive vehicle (no layout shift, no
 	// JS dependency, visible via view-source / devtools / a future status
@@ -155,6 +153,6 @@ export async function readHtmlTemplate(): Promise<string> {
 			? html.replace("</head>", `${meta}</head>`)
 			: `${meta}${html}`;
 	}
-	htmlCache.set("default", { html, manifestMtime });
+	htmlCache.set(manifestCacheKey(), { html, manifestMtime });
 	return html;
 }

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

@@ -79,4 +79,39 @@ describe("phase-2 step isolation", () => {
 		// original invisibility from the other direction.
 		expect(body.slice(guardCatch, guardCatch + 400)).toContain("log.error");
 	});
+
+	/*
+	 * THE 2026-09-01 REGRESSION (the unstyled-proposal incident). The phase-1
+	 * catch made the build failure non-fatal, and the readiness flip
+	 * (setPageHandler / markFullAppReady) ran unconditionally afterwards — so a
+	 * deployment whose client build never ran flipped ready, served pages, and
+	 * answered /health 200 while every asset URL 404'd. Railway reported the
+	 * deploy SUCCESS. The flip must be gated on a VERIFIED manifest, and the
+	 * gate must sit AFTER mountPgBoss so background work still mounts (the
+	 * isolation above), and BEFORE both flip call sites.
+	 */
+	test("readiness flips only after the client build verifies, and the gate sits after the jobs", () => {
+		const body = buildFullAppBody();
+		const boss = body.indexOf("mountPgBoss(");
+		const gate = body.indexOf("verifyClientBuildAssets()");
+		const flipBlock = body.indexOf("if (deps.createPageHandler)");
+		expect(boss).toBeGreaterThan(-1);
+		expect(gate).toBeGreaterThan(boss);
+		expect(flipBlock).toBeGreaterThan(gate);
+
+		// BOTH flip call sites are after the gate: the SSR path
+		// (setPageHandler) and the client-only path (markFullAppReady).
+		const setPageHandlerCall = body.indexOf("setPageHandler(deps.createPageHandler)");
+		const markFullAppReadyCall = body.indexOf("markFullAppReady()");
+		expect(setPageHandlerCall).toBeGreaterThan(gate);
+		expect(markFullAppReadyCall).toBeGreaterThan(gate);
+	});
+
+	test("a failed verification throws — the boot never continues past an unverified manifest", () => {
+		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");
+	});
 });

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

@@ -59,6 +59,7 @@
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { Hono } from "hono";
 import { buildClientAssets } from "./build-client-assets.ts";
+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";
@@ -112,6 +113,33 @@ export async function buildFullApp(
 		);
 	}
 
+	// The readiness flip is gated on a VERIFIED client build, never on "phase 2
+	// got this far". buildClientAssets's failure above is deliberately non-fatal
+	// for background work — but a deployment whose client build never ran (or
+	// whose tombstone names unbuilt files) must not flip ready and serve pages:
+	// every served asset URL would 404 while /health and the deploy report ok.
+	// Measured 2026-09-01: proposals.scala.business served a client-facing
+	// proposal unstyled while Railway reported SUCCESS, because the phase-1
+	// catch let boot continue past the build and the flip never checked the
+	// build's outcome (`a-component-may-not-report-a-state-it-has-not-verified`).
+	// The throw lands in ui-service's boot.client-build-failed catch, which
+	// keeps the minimal app: pages and /health stay 503 (cleanly unavailable)
+	// while the pg-boss jobs mounted above KEEP RUNNING. On Railway the
+	// healthcheck (healthcheckPath: /health) then fails and the previous good
+	// deployment keeps traffic — the deploy reports FAILED, never SUCCESS.
+	// readiness-gated-boot: a service is "fully-ready or cleanly-unavailable";
+	// a UI service that cannot serve its bundle is not ready
+	// (`liveness-by-capability-not-process-existence`).
+	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.`,
+		);
+	}
+
 	log.info(
 		`[two-phase-boot:${serviceSlug}] Full app built: ${loaded.length} block(s), ` +
 			`${Object.keys(components).length} component(s)`,