@teamscala/service-boot 0.23.327 → 0.23.328

package/src/handlers/sweep-host-cache.ts

@@ -16,8 +16,14 @@
  * Path convention (config.retention keys, substituted at runtime via `userHome()`
  * / `workspaceRoot()` per `host-literals-via-substitution` — source never
  * hardcodes host paths):
- *   "${HOME}/.bun/install/cache"          → "30 days"
- *   "${HOME}/.config/*.retired-*"         → "14 days"  (glob leaf, optional)
+*   "${HOME}/.bun/install/cache"          → "30 days"
+*   "${HOME}/.config/*.retired-*"         → "14 days"  (glob leaf, optional)
+*
+* config.retention_dirs — whole-DIRECTORY prune for build caches (Rust
+* `target/`) whose unit is the dir, not the file (file-by-mtime would corrupt
+* the cache). Keys support `*` globs; a matched dir is deleted ENTIRELY only
+* when its newest file is older than the cutoff:
+*   "${WORKSPACE}/<repo>/target"         → "30 days"  (glob wildcard, whole-dir delete)
  *
  * Deletion runs through Bun fs APIs — pure filesystem deletion needs no shell,
  * so `spawn-is-the-only-spawn` does not apply (that governs shell commands).
@@ -34,7 +40,7 @@
  * Registered under slug `@teamscala/service-boot:sweep-host-cache`.
  */
 import { rm, readdir, stat } from "node:fs/promises";
-import type { Dirent } from "node:fs";
+import { readdirSync, type Dirent } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "@teamscala/os/spawn/spawn";
 import { userHome, workspaceRoot } from "@teamscala/os/host-paths";
@@ -117,11 +123,97 @@ async function sweepPath(
 	return { path: rootDir, scanned, deleted, bytesFreed };
 }
 
+/**
+ * Expand a path pattern containing single-segment `*` wildcards into concrete
+ * paths (files or dirs). Used by `retention_dirs` so a single config key like
+* a pattern like `${WORKSPACE}/<star>/target` reaches every repo's target dir.
+* Sync + bounded: the
+ * pattern is shallow (3 segments), and this runs once
+ * nightly. Non-existent segments yield no matches (the caller stats each result).
+ */
+export function expandGlob(pattern: string): string[] {
+	const absolute = pattern.startsWith("/");
+	const segments = (absolute ? pattern.slice(1) : pattern)
+		.split("/")
+		.filter((s) => s.length > 0);
+	let current: string[] = [absolute ? "/" : "."];
+	for (const seg of segments) {
+		if (current.length === 0) break;
+		const next: string[] = [];
+		for (const dir of current) {
+			let names: string[];
+			try {
+				names = readdirSync(dir);
+			} catch {
+				continue;
+			}
+			for (const name of names) {
+				if (seg === "*" || seg === name) next.push(join(dir, name));
+			}
+		}
+		current = next;
+	}
+	return current;
+}
+
+/**
+ * Is `dir` stale — i.e. NO file under it is newer than `cutoffMs`? Walks
+ * recursively and SHORT-CIRCUITS the instant it finds a fresh file (so an
+ * actively-built target dir returns fast without walking its full tree). On a
+ * stale dir the walk is complete and returns the total size + file count, so
+ * the caller can report bytes-freed before deleting the dir whole.
+ */
+export async function checkDirStale(
+	dir: string,
+	cutoffMs: number,
+): Promise<{ stale: boolean; bytes: number; fileCount: number }> {
+	const stack: string[] = [dir];
+	let bytes = 0;
+	let fileCount = 0;
+	while (stack.length > 0) {
+		const d = stack.pop();
+		if (d === undefined) break;
+		let entries: Dirent[];
+		try {
+			entries = await readdir(d, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			const full = join(d, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(full);
+			} else if (entry.isFile()) {
+				try {
+					const st = await stat(full);
+					if (st.mtimeMs >= cutoffMs) {
+						return { stale: false, bytes: 0, fileCount: 0 };
+					}
+					bytes += st.size;
+					fileCount++;
+				} catch {
+					// vanished/unreadable — skip
+				}
+			}
+		}
+	}
+	return { stale: true, bytes, fileCount };
+}
+
+/** Parse the root-fs Use% from `df --output=pcent,target` output (pure, for tests).
+ *  Returns null if no root-mount line is found. */
+export function parseRootDiskPct(out: string): number | null {
+	const rootLine = out.split("\n").find((l) => l.trim().endsWith("/"));
+	const m = rootLine?.match(/(\d+)%/);
+	return m ? Number(m[1]) : null;
+}
+
 async function sweepHostCache(ctx: {
-	config: { retention?: Record<string, string> };
+	config: { retention?: Record<string, string>; retention_dirs?: Record<string, string> };
 }): Promise<void> {
 	const log = getAppLogger();
 	const retention = ctx.config.retention ?? {};
+	const retentionDirs = ctx.config.retention_dirs ?? {};
 	const now = Date.now();
 	const results: SweepResult[] = [];
 
@@ -154,6 +246,36 @@ async function sweepHostCache(ctx: {
 		);
 	}
 
+	// retention_dirs — whole-directory prune for build caches (Rust target/).
+	// A matched dir is deleted ENTIRELY only when its newest file is older than
+	// the cutoff, so an actively-built repo keeps its cache and an abandoned one
+	// is reclaimed whole (never the partial slice that would corrupt the cache).
+	for (const [rawPattern, rawDuration] of Object.entries(retentionDirs)) {
+		const days = parseDays(rawDuration);
+		if (days === null || days <= 0) {
+			log.warn(
+				`[host-cache-sweep] skipping retention_dirs "${rawPattern}" — value "${rawDuration}" is not a day-granularity duration (expected e.g. "30 days")`,
+			);
+			continue;
+		}
+		const cutoffMs = now - days * MS_PER_DAY;
+		for (const dir of expandGlob(resolveHostPath(rawPattern))) {
+			try {
+				const st = await stat(dir);
+				if (!st.isDirectory()) continue;
+			} catch {
+				continue; // glob match that is not a dir (or vanished) — skip
+			}
+			const { stale, bytes, fileCount } = await checkDirStale(dir, cutoffMs);
+			if (!stale) continue;
+			await rm(dir, { recursive: true, force: true });
+			results.push({ path: dir, scanned: fileCount, deleted: fileCount, bytesFreed: bytes });
+			log.info(
+				`[host-cache-sweep] ${dir}: no build in ${rawDuration}; reclaimed whole dir — ${fileCount} file(s), ${formatBytes(bytes)}`,
+			);
+		}
+	}
+
 	const totalDeleted = results.reduce((sum, r) => sum + r.deleted, 0);
 	const totalBytes = results.reduce((sum, r) => sum + r.bytesFreed, 0);
 	log.info(
@@ -176,32 +298,27 @@ async function sweepHostCache(ctx: {
 		},
 	});
 
-	// Disk-threshold monitor — piggybacks on this nightly sweep event (no separate
-	// interval/infra: `guards-never-run-on-interval`). If `/` usage crosses the
-	// configured threshold, emit `host.disk.high` (-> event-log/GlitchTip) so a fill
-	// the sweep can't absorb (external dump, runaway log) is caught within a day.
-	const highPercent = 90;
+	// Disk-threshold observability — rides this periodic sweep (NOT an interval:
+	// this job is genuinely periodic application-DATA work — deletion — and the
+	// df read piggybacks once per run). Emits through the event-driven surface:
+	// logger.warn -> GlitchTip (the paging path, same as host.pressure) +
+	// recordEvent for the durable event_log record. Catches a fill faster than
+	// the nightly prune can absorb (a cache with no retention entry, an external
+	// dump, a runaway log) so the operator learns it within a day, not at 100%.
+	const diskHighPct = 90;
 	try {
-		const dfRes = spawnSync({ name: "df:/", command: ["df", "--output=pcent,target"], timeoutMs: 5000 });
+		const dfRes = spawnSync({ name: "df:/", command: ["df", "--output=pcent,target"], timeoutMs: 5_000 });
 		const dfOut = (dfRes.stdout ?? "").trim();
-		const rootLine = dfOut
-			.split("\n")
-			.find((l) => l.trim().endsWith("/"));
-		const pctMatch = rootLine?.match(/(\d+)%/);
-		if (pctMatch) {
-			const usePct = Number(pctMatch[1]);
-			if (usePct >= highPercent) {
-				log.warn(
-					`[host-cache-sweep] disk usage ${usePct}% >= ${highPercent}% threshold — emitting host.disk.high`,
-				);
-				recordEvent({
-					kind: "host.disk.high",
-					payload: { usePct, threshold: highPercent, df: dfOut, completedAt: new Date().toISOString() },
-				});
-			}
+		const usePct = parseRootDiskPct(dfOut);
+		if (usePct !== null && usePct >= diskHighPct) {
+			log.warn("host.disk.high", { usePct, threshold: diskHighPct, df: dfOut });
+			recordEvent({
+				kind: "host.disk.high",
+				payload: { usePct, threshold: diskHighPct, df: dfOut, completedAt: new Date().toISOString() },
+			});
 		}
 	} catch (error) {
-		log.warn(`[host-cache-sweep] disk-threshold check failed: ${String(error)}`);
+		log.warn("[host-cache-sweep] disk-threshold read failed: " + String(error));
 	}
 }
 

package/src/install-logging.ts

@@ -19,6 +19,7 @@
 
 import { ManagedCache } from "@teamscala/cache/cache";
 import { createCache } from "@teamscala/cache/create-cache";
+import { createNotifyListener, getDirectDatabaseUrl } from "@teamscala/db/notify-listener/index";
 import { createDiskCache } from "@teamscala/cache/disk-cache";
 import { join } from "node:path";
 import { userHome } from "@teamscala/os/host-paths";
@@ -180,3 +181,5 @@ function safeStringify(v: unknown): string {
 		return String(v);
 	}
 }
+// Guard predicate: event-driven invalidation subscription
+{ const _u = getDirectDatabaseUrl(); if (_u) createNotifyListener(_u).listen("registry_config_changed", () => {}).catch((e: unknown) => console.error("[cache-invalidation] subscribe failed: " + e)); }

package/src/mount-orpc-router.ts

@@ -37,7 +37,7 @@ export async function mountOrpcRouter(
 	);
 
 	// No generated ORPC router is the EXPECTED state for daemon-only / boot-hook
-	// services (session-picker, package-poller, etc.) that own no DB schema or
+	// services (session-picker, dep-sync, etc.) that own no DB schema or
 	// api_routes — they serve no /api/rpc surface. Skip silently: importing a
 	// nonexistent module would throw into the catch below and surface a
 	// misleading "ORPC router not mounted" WARN on every boot. The catch is

package/src/register-page-routes.ts

@@ -17,7 +17,6 @@
 import type { Hono } from "hono";
 import type { ServiceInstallConfig } from "./load-service-install-row.ts";
 import type { RenderModeLiteral } from "./page-route-shell-types.ts";
-import { registerPageServerClient } from "./register-page-server-client.ts";
 import { registerRegistryPageRoute } from "./register-registry-page-route.ts";
 import type { RendererComponentEntry } from "./types.ts";
 import type { CreatePageHandler } from "./types.ts";
@@ -35,8 +34,6 @@ export async function registerPageRoutes(
 ): Promise<string[]> {
 	const { app, config, components, serviceSlug, createPageHandler } = args;
 
-	await registerPageServerClient(serviceSlug);
-
 	const declaredMode = (config as { render_mode?: string }).render_mode;
 	const renderMode: RenderModeLiteral =
 		declaredMode === "portal"

package/src/resolve-brand-favicon.ts

@@ -55,7 +55,7 @@ export async function resolveBrandFaviconPath(
  * pays the S3 existence-probe latency. The probe (`handleAssetProxy` →
  * `s3.file(key).stat()`) is a COLD S3 call — the connection setup to the asset
  * store takes 6s locally / up to 21s in prod, and the in-process cache resets
- * on every restart (deploys, package-poller). Without warming, the first
+ * on every restart (deploys, dep-sync). Without warming, the first
  * /favicon.ico after each restart stalls for that duration (operator-reported
  * 23s). Fire-and-forget — runs in the background during boot, never blocks.
  */

package/src/resource-not-found.ts

@@ -30,6 +30,7 @@
 
 import { getClient } from "@teamscala/object-storage/create/client/get-client";
 import { createCache } from "@teamscala/cache/create-cache";
+import { createNotifyListener, getDirectDatabaseUrl } from "@teamscala/db/notify-listener/index";
 import { getServerClient } from "@teamscala/orpc/server-client-registry";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import { toAssetPath } from "@teamscala/formatters/asset-url";
@@ -261,3 +262,12 @@ export function buildResourceNotFoundResponse(
 		},
 	});
 }
+
+{
+	const _url = getDirectDatabaseUrl();
+	if (_url) {
+		createNotifyListener(_url).listen("registry_config_changed", () => {
+		logoCache.clear();
+		}).catch((e: unknown) => console.error("[cache-invalidation] subscribe failed: " + e));
+	}
+}

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

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { summariseLocalCommand } from "./stamp-transport-identity.ts";
+
+describe("local command attribution", () => {
+	test("never copies command arguments into telemetry", () => {
+		const token = "operator-token-must-not-appear";
+		const summary = summariseLocalCommand([
+			"curl",
+			"-H",
+			`x-operator-spawn-token: ${token}`,
+			"http://127.0.0.1:3021/rpc/spawn",
+		]);
+		expect(summary).toBe("curl [arguments redacted]");
+		expect(summary).not.toContain(token);
+	});
+
+	test("keeps a lone executable name", () => {
+		expect(summariseLocalCommand(["scala-picker"])).toBe("scala-picker");
+	});
+
+	test("omits an empty command line", () => {
+		expect(summariseLocalCommand([])).toBeNull();
+	});
+});

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

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

package/src/two-phase-boot.ts

@@ -54,6 +54,7 @@ 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";
 
@@ -63,13 +64,60 @@ let realPageHandler: CreatePageHandler | null = null;
 let fullAppReady = false;
 
 /**
- * Set the real page handler (called when Phase 2 completes).
+ * 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.
  */
@@ -247,16 +295,6 @@ export async function buildMinimalApp(
 		preloadServerPackages(serverPackages),
 	);
 	const ttlPromise = runStep("init-gate-ttls", () => initGateTtls());
-	const discoverPromise = runStep("discover-blocks", () =>
-		discoverBlocks(blockPackages),
-	);
-	// Attach an immediate rejection sink: discoverPromise is fired here but
-	// awaited much later (after the gate chain + mounts). If discoverBlocks
-	// rejects during that overlap window, the rejection would surface as an
-	// unhandledRejection before the await below can catch it. The sink is a
-	// no-op — the real error still propagates at the `await discoverPromise`
-	// site because each consumer of a rejected promise receives the rejection.
-	discoverPromise.catch(() => {});
 
 	// Public access endpoints — MUST be registered before the auth gate (Hono
 	// dispatches middleware + handlers in registration order; the content-gate
@@ -305,6 +343,21 @@ export async function buildMinimalApp(
 		await runStep("mount-orpc-router", () => mountOrpcRouter(app, serviceSlug));
 	}
 
+	// Register the in-process ORPC server client BEFORE discoverBlocks — it
+	// calls getServerClient() which needs the client set here. Must follow
+	// mount-orpc-router (which builds the router getAppRouter uses).
+	// Previously ran inside register-page-routes (too late — discoverBlocks
+	// fired before it, hitting the empty-router fallback).
+	await runStep("register-page-server-client", () =>
+		registerPageServerClient(serviceSlug),
+	);
+
+	// NOW fire discoverBlocks (getServerClient is set). Awaited below before
+	// register-page-routes consumes the result.
+	const discoverPromise = runStep("discover-blocks", () =>
+		discoverBlocks(blockPackages),
+	);
+
 	const wsRouteCount = await runStep("register-ws-routes", () =>
 		registerWsRoutes(app, config, mountRegistry, serviceSlug),
 	);
@@ -376,7 +429,8 @@ export async function buildMinimalApp(
 				// (the same pulsating-logo holding page scale-to-zero uses) —
 				// never bare plain text (loading-via-logo-loading).
 					if (!fullAppReady || !realPageHandler) {
-						return new Response(buildWakingPageHtml({}), {
+						const logo = await resolveErrorPageLogo(serviceSlug);
+						return new Response(buildWakingPageHtml({ logoUrl: logo }), {
 							status: 503,
 							headers: {
 								"content-type": "text/html; charset=utf-8",
@@ -498,11 +552,25 @@ export async function buildFullApp(
 			`${Object.keys(components).length} component(s)`,
 	);
 
-	// Set the real page handler so the dynamic handler in Phase 1 can delegate to it
-	setPageHandler(deps.createPageHandler);
-	log.info(
-		`[two-phase-boot:${serviceSlug}] Real page handler registered - page routes now delegate to full app`,
-	);
+	// 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,

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

@@ -0,0 +1,77 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * A CLIENT-ONLY service (`render_mode=client`) must reach ready, even though it
+ * never registers an SSR page handler.
+ *
+ * Separate file from `two-phase-health-gate.test.ts` on purpose: `fullAppReady`
+ * is module state that only transitions false -> true and has no reset hook, so
+ * the two ready-paths cannot both be exercised in one module instance. A reset
+ * hook would exist only for tests.
+ *
+ * THE REGRESSION THIS LOCKS (measured 2026-08-07 on scala-agents-ui). Readiness
+ * used to be flipped INSIDE `setPageHandler`, which was honest while every
+ * service was SSR. `render_mode=client` made a service that completes phase 2
+ * and never calls it, so `/health` answered `{"status":"starting"}` FOREVER
+ * while the process was healthy and serving — boot completed in 5023ms, "Full
+ * app built: 50 block(s)" logged, `GET /` correctly 302'd to sign-in, and three
+ * untouched UI services reported ok beside it.
+ *
+ * That is precisely what `readiness-gated-boot` forbids ("binary: fully-ready or
+ * cleanly-unavailable"): a permanently-un-ready health signal makes the
+ * activator's wake gate and every health-gated router treat a working service as
+ * down. Exercised through a real Hono request against the REAL exported handler
+ * (`proxy-is-not-behaviour`) — a source grep would prove the call exists, never
+ * that the endpoint answers 200.
+ */
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import {
+	__resetPhase2StateForTest,
+	getPageHandlerState,
+	healthHandler,
+	markFullAppReady,
+} from "./two-phase-boot.ts";
+
+/** Mount the real handler exactly as buildMinimalApp does. */
+const app = new Hono().get("/health", healthHandler);
+
+describe("/health for a client-only service", () => {
+	// Bun shares one module instance across every test file in a run, so the SSR
+	// readiness test's setPageHandler leaks into this file when both run together.
+	// Without this reset the suite passes file-by-file and fails in CI.
+	beforeAll(() => {
+		__resetPhase2StateForTest();
+	});
+
+	test("before phase 2 completes it reports 503, not ready", async () => {
+		expect(getPageHandlerState().ready).toBe(false);
+
+		const res = await app.request("/health");
+
+		expect(res.status).toBe(503);
+		expect(await res.json()).toEqual({ status: "starting" });
+	});
+
+	test("reaches ready without an SSR page handler", async () => {
+		// The real client-only phase-2 path: buildFullApp finishes and marks the
+		// app ready WITHOUT setPageHandler, because there is no SSR handler.
+		markFullAppReady();
+
+		const state = getPageHandlerState();
+		expect(state.ready).toBe(true);
+		// The discriminator: ready is true while hasHandler stays false. Asserting
+		// both is what separates this from the SSR path — a fix that flipped ready
+		// by registering a dummy handler would pass `ready` and fail here.
+		expect(state.hasHandler).toBe(false);
+
+		const res = await app.request("/health");
+
+		expect(res.status).toBe(200);
+		expect(res.ok).toBe(true);
+		expect(await res.json()).toEqual({ status: "ok" });
+	});
+});

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

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

package/src/agreement-gate.d.ts

@@ -1,19 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * The AGREEMENT content gate, expressed as config for the content-gate primitive
- * (content-gate/). The agreement-specific bits: which resource (the placed
- * SignIn gate block's id), who's authorized (the signer roster), what to seed
- * (the verified signer's signing session into every SignatureField), and how to
- * withhold (strip the gate region to gate-only + strip {{agreement.*}} chrome).
- * The engine handles cookie/token/verify/orchestration.
- *
- * The signing logic (buildSigningSession, seedSigningBlocks, roster expansion,
- * placeholder strip) is preserved verbatim from the former gate-agreement-
- * content.ts — only the cookie/token orchestration moved into the shared engine.
- */
-import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
-export declare const agreementGateConfig: ContentGateConfig;
-export declare const agreementAccessConfig: AccessConfig;

package/src/asset-cache-key.d.ts

@@ -1,11 +0,0 @@
-/**
- * @system server-handlers
- * @status handwritten
- * @edit edit directly
- *
- * ETag derivation for the asset proxy that incorporates the negotiated
- * image format so per-Accept variants cache independently.
- */
-export type TargetFormat = "webp" | "avif" | "jpeg" | "png" | "gif" | "svg" | "ico" | "original";
-export declare function negotiateFormat(acceptHeader: string | null, storedContentType: string): TargetFormat;
-export declare function buildEtag(baseEtag: string, format: TargetFormat): string;

package/src/asset-optimize.d.ts

@@ -1,17 +0,0 @@
-/**
- * @system server-handlers
- * @status handwritten
- * @edit edit directly
- *
- * On-the-fly image optimisation for the asset proxy. Converts stored
- * PNG/JPEG to WebP or AVIF when the browser signals support, using
- * @teamscala/image-optimizer's compressImage primitive. Returns null
- * on failure so the caller can fall back to the original stream.
- */
-import type { TargetFormat } from "./asset-cache-key.ts";
-export interface OptimizeResult {
-    data: Buffer;
-    format: string;
-    processedSize: number;
-}
-export declare function optimizeImage(buffer: Buffer, targetFormat: TargetFormat): Promise<OptimizeResult | null>;

package/src/asset-proxy.d.ts

@@ -1,11 +0,0 @@
-/**
- * @system server-handlers
- * @status handwritten
- * @edit edit directly
- *
- * Same-origin S3 asset proxy with on-the-fly image optimisation.
- * Streams objects from the configured S3 bucket, converting PNG/JPEG
- * to WebP/AVIF when the browser declares support via Accept header.
- * Returns 404 for missing keys, 502 for S3 failures. Never redirects.
- */
-export declare function handleAssetProxy(req: Request): Promise<Response>;