@teamscala/service-boot 0.23.322 → 0.23.324

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

@@ -0,0 +1,133 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Unit tests for the `retention_dirs` helpers (`expandGlob`, `checkDirStale`) —
+ * the whole-directory prune that bounds Rust `target/` waste. The file-by-mtime
+ * `retention` path is unchanged; these cover ONLY the new build-cache model:
+ * (1) glob expansion reaches every repo's target dir; (2) an actively-built dir
+ * is kept (short-circuits on a fresh file); (3) an abandoned dir is reported
+ * stale with its full size. Lives next to the handler per co-located-test rule.
+ */
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { expandGlob, checkDirStale, parseRootDiskPct } from "./sweep-host-cache.ts";
+
+const DAY = 86_400_000;
+const now = Date.now();
+const daysAgo = (n: number) => new Date(now - n * DAY);
+const touch = (p: string, t: Date) => utimesSync(p, t, t);
+
+let root: string;
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "sweep-"));
+});
+afterEach(() => {
+	rmSync(root, { recursive: true, force: true });
+});
+
+describe("expandGlob", () => {
+	test("expands a single-segment wildcard to concrete dirs", () => {
+		mkdirSync(join(root, "scala-rust", "target"), { recursive: true });
+		mkdirSync(join(root, "scala-os", "target"), { recursive: true });
+		mkdirSync(join(root, "scala-os", "src"), { recursive: true });
+		const matches = expandGlob(`${root}/*/target`).sort();
+		expect(matches).toEqual(
+			[join(root, "scala-os", "target"), join(root, "scala-rust", "target")].sort(),
+		);
+	});
+	test("literal segment matches only itself", () => {
+		mkdirSync(join(root, "scala-rust", "target"), { recursive: true });
+		mkdirSync(join(root, "other", "target"), { recursive: true });
+		const matches = expandGlob(`${root}/scala-rust/target`);
+		expect(matches).toEqual([join(root, "scala-rust", "target")]);
+	});
+	test("no matches when the wildcard segment has no children", () => {
+		const matches = expandGlob(`${root}/does-not-exist/*/target`);
+		expect(matches).toEqual([]);
+	});
+});
+
+describe("checkDirStale", () => {
+	test("stale dir: all files older than cutoff → stale + full size", async () => {
+		const dir = join(root, "target");
+		mkdirSync(join(dir, "debug", "deps"), { recursive: true });
+		writeFileSync(join(dir, "debug", "deps", "a.o"), "x".repeat(40));
+		writeFileSync(join(dir, "debug", "deps", "b.o"), "y".repeat(60));
+		touch(join(dir, "debug", "deps", "a.o"), daysAgo(40));
+		touch(join(dir, "debug", "deps", "b.o"), daysAgo(35));
+		const res = await checkDirStale(dir, now - 30 * DAY);
+		expect(res.stale).toBe(true);
+		expect(res.fileCount).toBe(2);
+		expect(res.bytes).toBe(100);
+	});
+	test("active dir: a file newer than cutoff → not stale (short-circuit)", async () => {
+		const dir = join(root, "target");
+		mkdirSync(join(dir, "debug"), { recursive: true });
+		writeFileSync(join(dir, "debug", "old.o"), "x".repeat(40));
+		touch(join(dir, "debug", "old.o"), daysAgo(40));
+		writeFileSync(join(dir, "debug", "fresh.o"), "y".repeat(60));
+		touch(join(dir, "debug", "fresh.o"), daysAgo(1));
+		const res = await checkDirStale(dir, now - 30 * DAY);
+		expect(res.stale).toBe(false);
+	});
+	test("empty dir → stale with zero bytes", async () => {
+		const dir = join(root, "target");
+		mkdirSync(dir, { recursive: true });
+		const res = await checkDirStale(dir, now - 30 * DAY);
+		expect(res.stale).toBe(true);
+		expect(res.bytes).toBe(0);
+		expect(res.fileCount).toBe(0);
+	});
+});
+
+describe("parseRootDiskPct", () => {
+	test("extracts root-fs Use% from df --output=pcent,target output", () => {
+		const df =
+			"Use% Mounted on\n" +
+			"  97% /\n" +
+			"  45% /home\n";
+		expect(parseRootDiskPct(df)).toBe(97);
+	});
+	test("picks the root mount (/) over nested mounts", () => {
+		const df =
+			"Use% Mounted on\n" +
+			"  10% /proc/x\n" +
+			"  76% /\n";
+		expect(parseRootDiskPct(df)).toBe(76);
+	});
+	test("returns null when no root-mount line present", () => {
+		const df = "Use% Mounted on\n  40% /mnt/other\n";
+		expect(parseRootDiskPct(df)).toBeNull();
+	});
+	test("returns null on empty / malformed output", () => {
+		expect(parseRootDiskPct("")).toBeNull();
+		expect(parseRootDiskPct("Use% Mounted on")).toBeNull();
+	});
+});
+
+describe("disk-threshold early-warning regression lock", () => {
+	const { readFileSync } = require("node:fs");
+	// Source-shape lock (same pattern as singleton-tools-currency-watch.test.ts):
+	// the df-check that rides this periodic sweep was once removed in favour of an
+	// in-process interval watchdog — the wrong architecture (interval watchdogs
+	// are forbidden; observability is event-driven). This asserts the corrected
+	// shape survives: the sweep handler MUST carry the event-driven host.disk.high
+	// emission (logger.warn -> GlitchTip) + the pure parseRootDiskPct helper that
+	// backs it. Removing either fails this test. The asserted surface is the
+	// disk early-warning cell of host-resources-have-complete-monitoring.
+	const src = readFileSync(import.meta.dir + "/sweep-host-cache.ts", "utf-8");
+	test("handler emits the host.disk.high event (event-driven, not an interval)", () => {
+		expect(src).toContain('log.warn("host.disk.high"');
+		expect(src).toContain('kind: "host.disk.high"');
+	});
+	test("handler reads df via the sanctioned spawn (no in-process poller)", () => {
+		expect(src).toContain('command: ["df", "--output=pcent,target"]');
+	});
+	test("threshold parse is the exported pure helper", () => {
+		expect(src).toContain("export function parseRootDiskPct");
+	});
+});

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,