@teamscala/service-boot 0.23.430 → 0.23.432

package/src/resource-not-found.ts

@@ -2,7 +2,7 @@
  * @system service-boot
  * @status handwritten
  * @edit edit directly
- * @indivisible-unit
+ * @indivisible-unit owner=unassigned reason=299 lines; pre-2026-08-27 exemption, unreviewed
  *
  * One cohesive unit — the branded resource-not-found / holding page: the
  * PrimaryResourceMissingError trigger, the org-logo resolver the page
@@ -28,6 +28,28 @@
  * floor that must always exist.
  */
 
+/**
+ * The host org's LOGO (wordmark) for the dark error page — the favicon is a
+ * tab glyph, the wrong asset at page scale (operator-observed: a lone "h"
+ * where the launcha wordmark belonged). Resolution: the service's own
+ * install row names its owner (brand_org); the org's dark-theme logo (a
+ * light-coloured mark, correct on the dark page) is preferred, light-theme
+ * second. Every step skew-tolerant: any miss → null → the builder renders a
+ * logo-less dark page.
+ *
+ * Returns the logo as an INLINE data URI (not a `/api/assets/` proxy URL) so
+ * the branded holding/error page ships the logo IN the initial HTML bytes —
+ * no second fetch, no post-paint pop-in, no dependency on the asset proxy the
+ * degraded service is failing to serve (incident 2026-07-27: the logo on a
+ * DEGRADED render-layer holding page appeared after the page painted). The
+ * logo sibling of icons-render-ssr-inline. Size-capped: a pathological
+ * (>MAX_INLINE_LOGO_BYTES) logo falls back to null rather than bloating the
+ * HTML; the page renders logo-less, never broken.
+ */
+
+// Why: The host org's LOGO (wordmark) for the dark error page — the…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { getClient } from "@teamscala/object-storage/create/client/get-client";
 import { createCache } from "@teamscala/cache/create-cache";
 import { registerCacheInvalidation } from "@teamscala/db/notify-listener/index";
@@ -50,24 +72,6 @@ const logoCache = createCache<string | null>("service-boot:error-page-logo", {
 	maxSize: 8,
 });
 
-/**
- * The host org's LOGO (wordmark) for the dark error page — the favicon is a
- * tab glyph, the wrong asset at page scale (operator-observed: a lone "h"
- * where the launcha wordmark belonged). Resolution: the service's own
- * install row names its owner (brand_org); the org's dark-theme logo (a
- * light-coloured mark, correct on the dark page) is preferred, light-theme
- * second. Every step skew-tolerant: any miss → null → the builder renders a
- * logo-less dark page.
- *
- * Returns the logo as an INLINE data URI (not a `/api/assets/` proxy URL) so
- * the branded holding/error page ships the logo IN the initial HTML bytes —
- * no second fetch, no post-paint pop-in, no dependency on the asset proxy the
- * degraded service is failing to serve (incident 2026-07-27: the logo on a
- * DEGRADED render-layer holding page appeared after the page painted). The
- * logo sibling of icons-render-ssr-inline. Size-capped: a pathological
- * (>MAX_INLINE_LOGO_BYTES) logo falls back to null rather than bloating the
- * HTML; the page renders logo-less, never broken.
- */
 export async function resolveErrorPageLogo(
 	serviceSlug: string,
 ): Promise<string | null> {

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

@@ -18,10 +18,10 @@ import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import { decryptSecretConfig } from "@teamscala/encryption/crypto/secret-config";
 import { getGithubPackagesLatestVersion } from "@teamscala/publish-registry";
 import * as v from "valibot";
+import { createCache } from "@teamscala/cache/create-cache";
 
 const PACKAGE_NAME = "@teamscala/scala-tools";
 const PACKAGE_PATH = "node_modules/@teamscala/scala-tools/package.json";
-const PACKAGE_URL = "https://npm.pkg.github.com/@teamgbg%2Fscala-tools";
 const POLL_INTERVAL_MS = 120_000;
 
 const DEFAULT_COMMAND_TIMEOUT_MS = 600_000;
@@ -30,28 +30,43 @@ const CurrencyConfigSchema = v.looseObject({
 	command_timeout_ms: v.optional(v.number(), DEFAULT_COMMAND_TIMEOUT_MS),
 	fetch_timeout_ms: v.optional(v.number(), DEFAULT_FETCH_TIMEOUT_MS),
 });
-let cachedCurrencyConfig: { command_timeout_ms: number; fetch_timeout_ms: number } | null = null;
+const currencyConfigCache = createCache<{
+	command_timeout_ms: number;
+	fetch_timeout_ms: number;
+}>("service-boot:scala-tools-currency-config", {
+	ttlMs: Number.POSITIVE_INFINITY,
+	maxSize: 1,
+});
+
 async function getCurrencyConfig(): Promise<{ command_timeout_ms: number; fetch_timeout_ms: number }> {
-	if (cachedCurrencyConfig) return cachedCurrencyConfig;
+	const hit = currencyConfigCache.get("default");
+	if (hit) return hit;
 	const cfg = await loadRegistryConfig("config", "scala-tools-currency", CurrencyConfigSchema);
-	cachedCurrencyConfig = {
+	const config = {
 		command_timeout_ms: cfg?.command_timeout_ms ?? DEFAULT_COMMAND_TIMEOUT_MS,
 		fetch_timeout_ms: cfg?.fetch_timeout_ms ?? DEFAULT_FETCH_TIMEOUT_MS,
 	};
-	return cachedCurrencyConfig;
+	currencyConfigCache.set("default", config);
+	return config;
 }
 
-let cachedGithubToken: string | null | undefined;
+const githubTokenCache = createCache<string | null>(
+	"service-boot:github-packages-token",
+	{ ttlMs: Number.POSITIVE_INFINITY, maxSize: 1 },
+);
+
 async function getGithubPackagesToken(): Promise<string | null> {
-	if (cachedGithubToken !== undefined) return cachedGithubToken;
+	const hit = githubTokenCache.get("default");
+	if (hit !== undefined) return hit;
 	const raw = await loadRegistryConfig("secret", "github-packages-token", v.unknown());
 	if (!raw) {
-		cachedGithubToken = null;
+		githubTokenCache.set("default", null);
 		return null;
 	}
 	const decrypted = decryptSecretConfig(raw as never) as Record<string, unknown>;
-	cachedGithubToken = typeof decrypted.token === "string" ? decrypted.token : null;
-	return cachedGithubToken;
+	const token = typeof decrypted.token === "string" ? decrypted.token : null;
+	githubTokenCache.set("default", token);
+	return token;
 }
 
 interface PackageManifest {
@@ -86,8 +101,22 @@ function registryFromPackageUrl(pkgUrl: string): { registry: string; name: strin
 async function readLatestVersion(_fetchTimeoutMs: number): Promise<string | null> {
 	const token = await getGithubPackagesToken();
 	if (!token) return null;
-	const { registry, name } = registryFromPackageUrl(PACKAGE_URL);
-	return getGithubPackagesLatestVersion(name, token, registry);
+	const registryHost = await getPublishRegistryHost();
+	if (!registryHost) return null;
+	return getGithubPackagesLatestVersion(PACKAGE_NAME, token, registryHost);
+}
+
+async function getPublishRegistryHost(): Promise<string | null> {
+	try {
+		const row = await loadRegistryConfig(
+			"secret",
+			"publish-registry-config",
+			v.looseObject({ registry: v.string() }),
+		);
+		return row?.registry ?? null;
+	} catch {
+		return null;
+	}
 }
 
 async function checkCurrency(): Promise<{ healthy: boolean; details?: Record<string, unknown> }> {

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

@@ -9,22 +9,6 @@
  * in atomically once complete.
  */
 
-import { getAppLogger } from "@teamscala/logger/app-loggers";
-import type { Hono } from "hono";
-import { buildClientAssets } from "./build-client-assets.ts";
-import { mountPgBoss } from "./pg-boss-mount.ts";
-import { swapApp } from "./mutable-app-ref.ts";
-import type { MinimalAppResult } from "./two-phase-minimal-app.ts";
-import { markFullAppReady, setPageHandler } from "./two-phase-readiness.ts";
-import type { PageServerDeps } from "./ui-service.ts";
-
-export interface FullAppResult {
-	app: Hono;
-	blocks: { slug: string; packagePath: string }[];
-	routes: string[];
-	pgBossJobs: Array<{ handlerSlug: string }>;
-}
-
 /**
  * Build the full app with hydration. This adds the expensive operations that
  * were deferred from the minimal app:
@@ -37,13 +21,10 @@ export interface FullAppResult {
  * NOTE: All routes (including page routes) are already registered in Phase 1,
  * so we don't need to modify the app here. The app reference stays the same.
  */
-export async function buildFullApp(
-	minimalResult: MinimalAppResult,
-	deps: PageServerDeps,
-): Promise<FullAppResult> {
-	const log = getAppLogger();
-	const { config, serviceSlug, mountRegistry, components, loaded, app: minimalApp } = minimalResult;
 
+// Why: Build the full app with hydration. This adds the expensive o…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 	// Client asset building (expensive: Vite build).
 	//
 	// ISOLATED, because a PRESENTATION failure must not take out BACKGROUND WORK.
@@ -63,6 +44,50 @@ export async function buildFullApp(
 	// The steps after this one do not depend on client assets: pg-boss needs the
 	// registry and the DB, not a bundle. Ordering it behind a Vite build was
 	// incidental, so the coupling was never intended.
+
+// Why: Client asset building (expensive: Vite build).
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+	// pg-boss (mount for UI services - wasn't mounted in minimal app)
+	//
+	// Wrapped for the SAME reason buildClientAssets above is, in the other
+	// direction: a background-work failure must not cost the page. Unwrapped,
+	// anything mountPgBoss throws propagates out of the full-app build, the
+	// caller falls back to the MINIMAL app, and the service serves 0 api routes
+	// with /health 503 — so the tunnel health check fails and the site is
+	// unreachable from outside while localhost answers in 0.1s.
+	//
+	// Measured 2026-08-31 on scala-projects: a deps refresh moved pg-boss to a
+	// build expecting a newer shared pgboss schema than the database carried, its
+	// migration threw, and an outage of every page followed from a scheduled-job
+	// dependency. Jobs are the degradable half; pages are not.
+
+// Why: pg-boss (mount for UI services - wasn't mounted in minimal a…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import type { Hono } from "hono";
+import { buildClientAssets } from "./build-client-assets.ts";
+import { mountPgBoss } from "./pg-boss-mount.ts";
+import { swapApp } from "./mutable-app-ref.ts";
+import type { MinimalAppResult } from "./two-phase-minimal-app.ts";
+import { markFullAppReady, setPageHandler } from "./two-phase-readiness.ts";
+import type { PageServerDeps } from "./ui-service.ts";
+
+export interface FullAppResult {
+	app: Hono;
+	blocks: { slug: string; packagePath: string }[];
+	routes: string[];
+	pgBossJobs: Array<{ handlerSlug: string }>;
+}
+
+export async function buildFullApp(
+	minimalResult: MinimalAppResult,
+	deps: PageServerDeps,
+): Promise<FullAppResult> {
+	const log = getAppLogger();
+	const { config, serviceSlug, mountRegistry, components, loaded, app: minimalApp } = minimalResult;
+
 	try {
 		await buildClientAssets(serviceSlug);
 		log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets DONE`);
@@ -76,13 +101,20 @@ export async function buildFullApp(
 		);
 	}
 
-	// pg-boss (mount for UI services - wasn't mounted in minimal app)
-	const { jobs: pgBossJobs } = await mountPgBoss({
-		databaseUrl: minimalResult.databaseUrl,
-		serviceSlug,
-		packages: config.server_packages ?? [],
-	});
-	log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: mountPgBoss DONE (${pgBossJobs.length} jobs)`);
+	let pgBossJobs: Awaited<ReturnType<typeof mountPgBoss>>["jobs"] = [];
+	try {
+		({ jobs: pgBossJobs } = await mountPgBoss({
+			databaseUrl: minimalResult.databaseUrl,
+			serviceSlug,
+			packages: config.server_packages ?? [],
+		}));
+		log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: mountPgBoss DONE (${pgBossJobs.length} jobs)`);
+	} catch (error) {
+		log.error(
+			`[two-phase-boot:${serviceSlug}] phase-2 step: mountPgBoss FAILED — background jobs are DOWN for this service, pages continue`,
+			{ error: error instanceof Error ? error.message : String(error) },
+		);
+	}
 	if (pgBossJobs.length > 0) {
 		log.info(
 			`[two-phase-boot:${serviceSlug}] pg-boss mounted ${pgBossJobs.length} job(s): ${pgBossJobs.map((j) => j.handlerSlug).join(", ")}`,

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

@@ -9,6 +9,45 @@
  * it in atomically — eliminating the ~25s boot outage window.
  */
 
+/**
+ * Build the minimal tool-only app. This excludes the expensive operations:
+ * - Client asset building (Vite build)
+ * - Boot hooks (may have expensive initialization)
+ * - Scheduled jobs (can start later)
+ * - pg-boss (can start later)
+ *
+ * CRITICAL: All route registration MUST happen here before serving, because
+ * Hono's RegExpRouter compiles on the first request and becomes immutable.
+ * Once compiled, no new routes can be added. So we include:
+ * - Block discovery and page routes (registers all page paths)
+ * - All other routes (API, WS, data, static assets)
+ *
+ * The minimal app includes everything needed for MCP tools and ORPC:
+ * - Error handling, readiness gate, health check
+ * - Security headers, CORS, compression, timing
+ * - Content gate access, auth gates, static assets
+ * - ORPC router, API routes, WS routes, data routes, page routes
+ */
+
+// Why: Build the minimal tool-only app. This excludes the expensive…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+	// Fire independent I/O + compilation NOW, overlapping with the gate chain
+	// below. These three touch NO app route and have no ordering dependency on
+	// the gate/mount sequence, so they run concurrently with it:
+	// - preloadServerPackages: warms Bun's module cache (CPU-bound compilation
+	//   that overlaps the gate chain's cross-internet DB I/O — same speculative
+	//   pattern as create-boot-pipeline's preloads). mountServerPackages later
+	//   hits the cache (instant imports), paying only the ~33ms of mount work.
+	// - initGateTtls: loads config rows into module-level vars. The TTL getters
+	//   are read at REQUEST time (inside route-handler closures), not at boot,
+	//   so this only needs to finish before serving — safe to run in parallel.
+	// - discoverBlocks: loads the page-manifest (no app mutation, no gate
+	//   dependency). Its result is consumed by registerPageRoutes much later.
+
+// Why: Fire independent I/O + compilation NOW, overlapping with the…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";
 import { createTimer } from "@teamscala/timing/create-timer";
@@ -63,25 +102,6 @@ export interface MinimalAppResult {
 	skipped: string[]; // Skipped block names
 }
 
-/**
- * Build the minimal tool-only app. This excludes the expensive operations:
- * - Client asset building (Vite build)
- * - Boot hooks (may have expensive initialization)
- * - Scheduled jobs (can start later)
- * - pg-boss (can start later)
- *
- * CRITICAL: All route registration MUST happen here before serving, because
- * Hono's RegExpRouter compiles on the first request and becomes immutable.
- * Once compiled, no new routes can be added. So we include:
- * - Block discovery and page routes (registers all page paths)
- * - All other routes (API, WS, data, static assets)
- *
- * The minimal app includes everything needed for MCP tools and ORPC:
- * - Error handling, readiness gate, health check
- * - Security headers, CORS, compression, timing
- * - Content gate access, auth gates, static assets
- * - ORPC router, API routes, WS routes, data routes, page routes
- */
 export async function buildMinimalApp(
 	config: ServiceInstallConfig,
 	serviceSlug: string,
@@ -167,18 +187,6 @@ export async function buildMinimalApp(
 	);
 	attachRequestLogger(app, serviceSlug);
 
-	// Fire independent I/O + compilation NOW, overlapping with the gate chain
-	// below. These three touch NO app route and have no ordering dependency on
-	// the gate/mount sequence, so they run concurrently with it:
-	// - preloadServerPackages: warms Bun's module cache (CPU-bound compilation
-	//   that overlaps the gate chain's cross-internet DB I/O — same speculative
-	//   pattern as create-boot-pipeline's preloads). mountServerPackages later
-	//   hits the cache (instant imports), paying only the ~33ms of mount work.
-	// - initGateTtls: loads config rows into module-level vars. The TTL getters
-	//   are read at REQUEST time (inside route-handler closures), not at boot,
-	//   so this only needs to finish before serving — safe to run in parallel.
-	// - discoverBlocks: loads the page-manifest (no app mutation, no gate
-	//   dependency). Its result is consumed by registerPageRoutes much later.
 	const serverPackages = ((config as { server_packages?: string[] })
 		.server_packages ?? []) as string[];
 	const preloadPromise = runStep("preload-server-packages", () =>

package/src/two-phase-readiness.ts

@@ -9,30 +9,6 @@
  * handler once phase 2 completes. Every reader goes through these exports.
  */
 
-import { buildWakingPageHtml } from "@teamscala/os/brand/waking-page-html";
-import { WAKING_RETRY_SECONDS } from "@teamscala/os/brand/waking-page-budget.generated";
-import type { Context } from "hono";
-import { getServerClientCapabilityFault } from "./page-server-orpc/server-client.ts";
-import { resolveErrorPageLogo } from "./resource-not-found.ts";
-import type { CreatePageHandler } from "./types.ts";
-
-// Module-level storage for the real page handler, updated when Phase 2 completes.
-// This allows the temporary Phase 1 handler to delegate to the real handler once ready.
-let realPageHandler: CreatePageHandler | null = null;
-let fullAppReady = false;
-
-/**
- * Set the real page handler (called when Phase 2 completes on an SSR service).
- *
- * Registering the SSR handler implies the full app is built, so this also flips
- * readiness — but the reverse does NOT hold, which is why `markFullAppReady`
- * exists separately. See its note.
- */
-export function setPageHandler(handler: CreatePageHandler): void {
-	realPageHandler = handler;
-	markFullAppReady();
-}
-
 /**
  * Flip readiness once phase 2 has built the full app.
  *
@@ -53,10 +29,10 @@ export function setPageHandler(handler: CreatePageHandler): void {
  * 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;
-}
 
+// Why: Flip readiness once phase 2 has built the full app.
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * Reset both phase-2 flags. TEST-ONLY.
  *
@@ -71,18 +47,10 @@ export function markFullAppReady(): void {
  * Never called from production code — `setPageHandler`/`markFullAppReady` are
  * the only writers on the boot path.
  */
-export function __resetPhase2StateForTest(): void {
-	realPageHandler = null;
-	fullAppReady = false;
-}
-
-/**
- * Get the current page handler state.
- */
-export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
-	return { ready: fullAppReady, hasHandler: realPageHandler !== null };
-}
 
+// Why: Reset both phase-2 flags. TEST-ONLY.
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * `/health` for a UI service — 200 ONLY once the full app can actually render
  * a page, 503 before that.
@@ -125,6 +93,50 @@ export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
  * tool surface, which genuinely IS usable at phase 1. Only this endpoint, whose
  * one consumer contract is "can you serve me a page", is moved to phase 2.
  */
+
+// Why: `/health` for a UI service — 200 ONLY once the full app can …
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+import { buildWakingPageHtml } from "@teamscala/os/brand/waking-page-html";
+import { WAKING_RETRY_SECONDS } from "@teamscala/os/brand/waking-page-budget.generated";
+import type { Context } from "hono";
+import { getServerClientCapabilityFault } from "./page-server-orpc/server-client.ts";
+import { resolveErrorPageLogo } from "./resource-not-found.ts";
+import type { CreatePageHandler } from "./types.ts";
+
+// Module-level storage for the real page handler, updated when Phase 2 completes.
+// This allows the temporary Phase 1 handler to delegate to the real handler once ready.
+let realPageHandler: CreatePageHandler | null = null;
+let fullAppReady = false;
+
+/**
+ * Set the real page handler (called when Phase 2 completes on an SSR service).
+ *
+ * Registering the SSR handler implies the full app is built, so this also flips
+ * readiness — but the reverse does NOT hold, which is why `markFullAppReady`
+ * exists separately. See its note.
+ */
+export function setPageHandler(handler: CreatePageHandler): void {
+	realPageHandler = handler;
+	markFullAppReady();
+}
+
+export function markFullAppReady(): void {
+	fullAppReady = true;
+}
+
+export function __resetPhase2StateForTest(): void {
+	realPageHandler = null;
+	fullAppReady = false;
+}
+
+/**
+ * Get the current page handler state.
+ */
+export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
+	return { ready: fullAppReady, hasHandler: realPageHandler !== null };
+}
+
 export function healthHandler(c: Context): Response {
 	if (!fullAppReady) return c.json({ status: "starting" }, 503, { "Retry-After": "1" });
 	// Assert the CAPABILITY, not just the phase flag. On 2026-08-20 this returned

package/src/ui-service.ts

@@ -8,6 +8,56 @@
  * served by @teamscala/service-runtime/serve (one Bun.serve in dev and prod).
  */
 
+/**
+ * Boots a UI service using two-phase boot for fast availability.
+ *
+ * Phase 1 (fast): Build and serve minimal tool-only app (ORPC, data routes,
+ * auth gates). This becomes available within ~10s, enabling the MCP tool
+ * surface to accept requests immediately after restart.
+ *
+ * Phase 2 (background): Build full app (pages, hydration) and atomically swap
+ * it in. The readiness gate flips to ready after Phase 1, not Phase 2.
+ *
+ * The interim mitigation (503 + gateway retry + circuit breaker) remains in
+ * place and is NOT undone.
+ */
+
+// Why: Boots a UI service using two-phase boot for fast availabilit…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+	// Resolve the listen port through the SHARED resolver (`resolveServicePort`),
+	// the same one the backend branch uses. The registry wins wherever it has an
+	// opinion and a contradicting PORT env is reported, never silently obeyed —
+	// full reasoning in that file.
+	//
+	// This branch previously took `process.env.PORT` unconditionally, which is
+	// how scala-quiz (declared 5203) booted onto session-picker's 3021 from a
+	// leaked env and silently split that daemon's traffic (2026-07-31). On the
+	// dev host the registry wins a conflict (below). On Railway the injected PORT
+	// wins instead — Railway healthchecks exactly that port, and the row's port
+	// is the service's LOCAL dev port (e.g. portal 5200), so binding it on Railway
+	// makes the healthcheck probe a dead port and the deploy fails (`isRailway`
+	// path in the resolver).
+
+// Why: Resolve the listen port through the SHARED resolver (`resolv…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+			// NO-SILENT-REVERTS — surface the failed client build to OBSERVABILITY
+			// (event-log → GlitchTip, per event-log-is-the-only-durable-event-log).
+			// The minimal-app fallback keeps serving SSR from the LAST-successful
+			// manifest (now a tombstone, see build-client-assets.ts), so the page
+			// looks "up" while the client bundle is stale. Without this signal the
+			// failure is buried in boot stderr and a published fix that reached
+			// node_modules but failed to bundle ships invisibly stale (the
+			// scala-agents 2026-07-18 incident: ui-foundation@3.4.5 installed but
+			// served pre-fix bytes across restarts while node_modules was
+			// mid-install). The boot.client-build-failed event routes into
+			// event-log's 7-day retention → surfaces in GlitchTip as an incident
+			// trail the operator actually watches.
+
+// Why: NO-SILENT-REVERTS — surface the failed client build to OBSER…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";
@@ -46,19 +96,6 @@ export interface PageServerDeps {
 	getSharedDb?: () => unknown;
 }
 
-/**
- * Boots a UI service using two-phase boot for fast availability.
- *
- * Phase 1 (fast): Build and serve minimal tool-only app (ORPC, data routes,
- * auth gates). This becomes available within ~10s, enabling the MCP tool
- * surface to accept requests immediately after restart.
- *
- * Phase 2 (background): Build full app (pages, hydration) and atomically swap
- * it in. The readiness gate flips to ready after Phase 1, not Phase 2.
- *
- * The interim mitigation (503 + gateway retry + circuit breaker) remains in
- * place and is NOT undone.
- */
 export async function bootUiService(
 	config: ServiceInstallConfig,
 	serviceSlug: string,
@@ -77,19 +114,6 @@ export async function bootUiService(
 		deps.getSharedDb,
 	);
 
-	// Resolve the listen port through the SHARED resolver (`resolveServicePort`),
-	// the same one the backend branch uses. The registry wins wherever it has an
-	// opinion and a contradicting PORT env is reported, never silently obeyed —
-	// full reasoning in that file.
-	//
-	// This branch previously took `process.env.PORT` unconditionally, which is
-	// how scala-quiz (declared 5203) booted onto session-picker's 3021 from a
-	// leaked env and silently split that daemon's traffic (2026-07-31). On the
-	// dev host the registry wins a conflict (below). On Railway the injected PORT
-	// wins instead — Railway healthchecks exactly that port, and the row's port
-	// is the service's LOCAL dev port (e.g. portal 5200), so binding it on Railway
-	// makes the healthcheck probe a dead port and the deploy fails (`isRailway`
-	// path in the resolver).
 	const isRailway = Boolean(process.env.RAILWAY_ENVIRONMENT);
 	const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
 	// The APP binds its PRIVATE port (app_port) when present — for scale-to-zero
@@ -160,18 +184,6 @@ export async function bootUiService(
 			log.error(
 				`[ui-service-boot:${serviceSlug}] Failed to build full app, continuing with minimal app: ${reason}`,
 			);
-			// NO-SILENT-REVERTS — surface the failed client build to OBSERVABILITY
-			// (event-log → GlitchTip, per event-log-is-the-only-durable-event-log).
-			// The minimal-app fallback keeps serving SSR from the LAST-successful
-			// manifest (now a tombstone, see build-client-assets.ts), so the page
-			// looks "up" while the client bundle is stale. Without this signal the
-			// failure is buried in boot stderr and a published fix that reached
-			// node_modules but failed to bundle ships invisibly stale (the
-			// scala-agents 2026-07-18 incident: ui-foundation@3.4.5 installed but
-			// served pre-fix bytes across restarts while node_modules was
-			// mid-install). The boot.client-build-failed event routes into
-			// event-log's 7-day retention → surfaces in GlitchTip as an incident
-			// trail the operator actually watches.
 			recordEvent({
 				kind: "boot.client-build-failed",
 				payload: {

package/src/handlers/pane-outbox-drain.ts

@@ -1,39 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * The `pane-outbox-drain` pg-boss handler — delivers messages the operator's
- * WhatsApp PA queues into `pane_messages` to the addressed agent pane.
- *
- * WHY THE REGISTRATION LIVES HERE AND THE WORK LIVES IN @teamscala/channel.
- * The delivery itself belongs to the channel capability, so `paneOutboxDrainTick`
- * is owned by `@teamscala/channel` beside the dispatch handler it calls. But
- * `pgBossHandlerRegistry` is SERVER tier and `@teamscala/channel` is ADAPTER
- * tier, so the channel package cannot register a pg-boss handler without an
- * upward dependency — forbidden by `vertical-dependency-only`, which has no
- * carve-out. server → adapter is DOWNWARD, so the registration sits here and
- * imports the work, exactly as the four sibling handlers in this directory do.
- *
- * The MountContext route (`ctx.registerScheduledJob`) is tier-legal but NOT
- * usable: `start-scheduled-jobs.ts` offers only `long_running` (invoked once,
- * runs forever) and `recurring` (whose handlers "manage their own setInterval").
- * Both are the in-process timer that `pg-boss-for-background-work` forbids and
- * that the timer half of `in-memory-state-is-not-durable` describes — a timer
- * only fires if its host outlives it, so on a restart-prone service it silently
- * never runs while logging that it started. pg-boss is the only durable option,
- * because the job row outlives any worker.
- *
- * Scoped to scala-channel by its `scheduled_job` row's `service_slug`, so it
- * runs on the service that owns the channel rather than on scala-agents, whose
- * UI-asset build failures used to take PA delivery down with them.
- *
- * Registered under slug `@teamscala/service-boot:pane-outbox-drain`.
- */
-import { paneOutboxDrainTick } from "@teamscala/channel/pane-outbox/drain-tick";
-import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
-
-pgBossHandlerRegistry.register(
-	"@teamscala/service-boot:pane-outbox-drain",
-	paneOutboxDrainTick,
-);