@teamscala/service-boot 0.23.431 → 0.23.432

package/src/resolve-app-base-url.ts

@@ -13,16 +13,23 @@
 
 import { ServiceInstallConfigSchema } from "@teamscala/db-validation/registry-schemas/service-install";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { createCache } from "@teamscala/cache/create-cache";
 
-let cachedAppUrl: string | null = null;
+const appUrlCache = createCache<string>("service-boot:app-base-url", {
+	ttlMs: Number.POSITIVE_INFINITY,
+	maxSize: 1,
+});
 
 export async function resolveAppBaseUrl(): Promise<string> {
-	if (cachedAppUrl) return cachedAppUrl;
+	const hit = appUrlCache.get("default");
+	if (hit) return hit;
 	try {
 		const config = await loadRegistryConfig("service_install", "scala-projects", ServiceInstallConfigSchema);
-		cachedAppUrl = `https://${config.public_hostname}`;
+		const url = `https://${config.public_hostname}`;
+		appUrlCache.set("default", url);
+		return url;
 	} catch {
-		cachedAppUrl = "https://projects.scala.business";
+		appUrlCache.set("default", "https://projects.scala.business");
+		return "https://projects.scala.business";
 	}
-	return cachedAppUrl;
 }

package/src/resolvers/portal-route-paths.ts

@@ -13,17 +13,6 @@
  * `/<last-segment>-toolbar`. Pages without a matching toolbar page simply
  * resolve an empty toolbar region (the source is declared optional).
  */
-export interface ResolverArgs {
-	input: Record<string, unknown>;
-	client: unknown;
-	params: Record<string, unknown>;
-}
-
-// Canonical portal URL shape: /<websiteId>/<organisationId>/<builda path...>.
-// Segment 0 is the portal WEBSITE id; segment 1 is the ORG id. Shared by the
-// resolver below and by extractOrgIdFromCallbackPath (the /sign-in brand path).
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
 /**
  * Extract the organisation id from a portal-shaped callback/path — the single
  * authority for "which segment is the org" so the sign-in brand resolver and the
@@ -41,6 +30,21 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
  * correct-org improvement for the two-UUID portal shape). Returns undefined when
  * neither leading segment is a UUID.
  */
+
+// Why: Extract the organisation id from a portal-shaped callback/pa…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+export interface ResolverArgs {
+	input: Record<string, unknown>;
+	client: unknown;
+	params: Record<string, unknown>;
+}
+
+// Canonical portal URL shape: /<websiteId>/<organisationId>/<builda path...>.
+// Segment 0 is the portal WEBSITE id; segment 1 is the ORG id. Shared by the
+// resolver below and by extractOrgIdFromCallbackPath (the /sign-in brand path).
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
 export function extractOrgIdFromCallbackPath(callbackUrl: string): string | undefined {
 	const segs = callbackUrl.split("?")[0].split("/").filter(Boolean);
 	if (UUID_RE.test(segs[1] ?? "")) return segs[1];

package/src/resource-chat-inject.ts

@@ -20,6 +20,90 @@
  * (fail-soft).
  */
 
+/**
+ * THE ASSISTANT'S WORDS BELONG TO THE AGENT ROW, NOT TO THIS FILE.
+ *
+ * `ai_agents` already carries a column for every one of them -- name,
+ * welcome_message, conversation_starters, primary_color -- and on 2026-08-19
+ * both live agents had welcome_message NULL and conversation_starters empty
+ * while the copy sat spelled in TypeScript here and in proposal-chat-inject.
+ * The intended home existed, sat blank, and the hardcoded copy won, so nobody
+ * could change a word the assistant says without a code change and a deploy.
+ * Two copies of one fact with the stale one winning silently is exactly
+ * `information-exists-in-one-location`.
+ *
+ * `launchLabel` and `placeholder` remain caller arguments only because no
+ * column holds them yet.
+ */
+
+// Why: THE ASSISTANT'S WORDS BELONG TO THE AGENT ROW, NOT TO THIS F…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+/**
+ * The rendered content tree to append the launcher to.
+ *
+ * WHICH KEYS EXIST IS A ROW FACT, SO IT IS NOT SPELLED HERE. A page's resolved
+ * sources and its region slots are declared on the `resource_loader` row, and
+ * the caller has already read that row — so it passes `regionSlots` in. An
+ * earlier draft of this function named "page", "body", "header" and "footer" as
+ * literals, which is a loader row copied into TypeScript, free to drift from it
+ * the moment a loader is edited (`identity-is-imported-never-spelled`).
+ *
+ * A FLAT PAGE KEEPS ITS CONTENT UNDER `page`; A REGION-SLOT PAGE DOES NOT.
+ * Proposals and agreements resolve one `page` source, so the original injector
+ * read `resolved.page.puck_data.content` and returned early when it was absent.
+ * A generated report resolves region slots instead, so that early return fired
+ * and the assistant was silently missing — the same failure shape as the dead
+ * block name, since fail-soft injection logs nothing and the page looks fine.
+ *
+ * ANY RENDERED REGION WILL DO, SO THE FIRST DECLARED ONE IS TAKEN. The launcher
+ * renders `position: fixed` at `zIndex: 50`, anchored to the viewport and not
+ * to its container, so it appears identically whichever region carries it. That
+ * is what makes "first declared region holding a content tree" a derivation
+ * rather than a guess dressed up as one: there is no better region to prefer.
+ *
+ * `PAGE_SOURCE_KEY` is the platform's existing name for a flat page's body
+ * source — the same convention `decideContentPageFloor` already keys on in the
+ * caller. One shared convention, not a per-resource list.
+ */
+
+// Why: The rendered content tree to append the launcher to.
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+/**
+ * Serialise EVERYTHING THIS VIEWER MAY SEE as text for the assistant.
+ *
+ * BOTH THE RESULT AND THE RENDERED DOCUMENT, BECAUSE NEITHER IS SUFFICIENT.
+ * The original serialiser sent the resource record plus the page's content
+ * tree, which is exactly right for a proposal — the proposal's substance IS in
+ * its blocks. It is wrong for anything the platform GENERATES a document from.
+ * A report's body page is a shared template (one `builda_pages` row serves
+ * every respondent) so the content tree holds headings and layout and not one
+ * personal fact, while the substance — the answers, the category scores, the
+ * computed narrative and bands — sits in sibling resolved keys the serialiser
+ * never looked at. Sending only the page would give the assistant a form with
+ * no answers; sending only the record would leave it unable to discuss what the
+ * reader is actually looking at. An assessment result GENERATES a report, so
+ * the assistant needs both halves of that.
+ *
+ * NO KEY IS NAMED, INCLUDED OR EXCLUDED. The loader row decides what a page
+ * resolves; this walks whatever that produced. A draft carried a `CHROME_KEYS`
+ * exclusion list dropping brand, website, header and footer — every one of them
+ * a loader source key, which is to say database facts hardcoded here to save a
+ * few hundred tokens of colours and navigation markup. Not a trade worth a
+ * literal that goes stale in silence. A loader resolving a new source reaches
+ * the assistant with no edit here (`offered-is-derived`).
+ *
+ * IT CANNOT OUTRUN THE GATE, BY CONSTRUCTION. This runs AFTER every content
+ * gate, and a gate withholds by REMOVING content from this same graph. So
+ * "everything in the graph" and "everything this viewer may see" are the same
+ * set, and they cannot drift — which is what makes serialising the whole graph
+ * safe rather than reckless.
+ */
+
+// Why: Serialise EVERYTHING THIS VIEWER MAY SEE as text for the ass…
+// (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 { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import { getServerClient } from "./page-server-orpc/server-client.ts";
@@ -61,21 +145,6 @@ export interface ResourceChatOptions {
 	regionSlots?: readonly string[];
 }
 
-/**
- * THE ASSISTANT'S WORDS BELONG TO THE AGENT ROW, NOT TO THIS FILE.
- *
- * `ai_agents` already carries a column for every one of them -- name,
- * welcome_message, conversation_starters, primary_color -- and on 2026-08-19
- * both live agents had welcome_message NULL and conversation_starters empty
- * while the copy sat spelled in TypeScript here and in proposal-chat-inject.
- * The intended home existed, sat blank, and the hardcoded copy won, so nobody
- * could change a word the assistant says without a code change and a deploy.
- * Two copies of one fact with the stale one winning silently is exactly
- * `information-exists-in-one-location`.
- *
- * `launchLabel` and `placeholder` remain caller arguments only because no
- * column holds them yet.
- */
 export interface AgentPresentation {
 	title?: string;
 	welcomeMessage?: string;
@@ -147,33 +216,6 @@ function puckContentOf(value: unknown): unknown[] | null {
 	return Array.isArray(content) ? content : null;
 }
 
-/**
- * The rendered content tree to append the launcher to.
- *
- * WHICH KEYS EXIST IS A ROW FACT, SO IT IS NOT SPELLED HERE. A page's resolved
- * sources and its region slots are declared on the `resource_loader` row, and
- * the caller has already read that row — so it passes `regionSlots` in. An
- * earlier draft of this function named "page", "body", "header" and "footer" as
- * literals, which is a loader row copied into TypeScript, free to drift from it
- * the moment a loader is edited (`identity-is-imported-never-spelled`).
- *
- * A FLAT PAGE KEEPS ITS CONTENT UNDER `page`; A REGION-SLOT PAGE DOES NOT.
- * Proposals and agreements resolve one `page` source, so the original injector
- * read `resolved.page.puck_data.content` and returned early when it was absent.
- * A generated report resolves region slots instead, so that early return fired
- * and the assistant was silently missing — the same failure shape as the dead
- * block name, since fail-soft injection logs nothing and the page looks fine.
- *
- * ANY RENDERED REGION WILL DO, SO THE FIRST DECLARED ONE IS TAKEN. The launcher
- * renders `position: fixed` at `zIndex: 50`, anchored to the viewport and not
- * to its container, so it appears identically whichever region carries it. That
- * is what makes "first declared region holding a content tree" a derivation
- * rather than a guess dressed up as one: there is no better region to prefer.
- *
- * `PAGE_SOURCE_KEY` is the platform's existing name for a flat page's body
- * source — the same convention `decideContentPageFloor` already keys on in the
- * caller. One shared convention, not a per-resource list.
- */
 const PAGE_SOURCE_KEY = "page";
 
 function findContentHost(
@@ -190,36 +232,6 @@ function findContentHost(
 	return puckContentOf(resolved[PAGE_SOURCE_KEY]);
 }
 
-/**
- * Serialise EVERYTHING THIS VIEWER MAY SEE as text for the assistant.
- *
- * BOTH THE RESULT AND THE RENDERED DOCUMENT, BECAUSE NEITHER IS SUFFICIENT.
- * The original serialiser sent the resource record plus the page's content
- * tree, which is exactly right for a proposal — the proposal's substance IS in
- * its blocks. It is wrong for anything the platform GENERATES a document from.
- * A report's body page is a shared template (one `builda_pages` row serves
- * every respondent) so the content tree holds headings and layout and not one
- * personal fact, while the substance — the answers, the category scores, the
- * computed narrative and bands — sits in sibling resolved keys the serialiser
- * never looked at. Sending only the page would give the assistant a form with
- * no answers; sending only the record would leave it unable to discuss what the
- * reader is actually looking at. An assessment result GENERATES a report, so
- * the assistant needs both halves of that.
- *
- * NO KEY IS NAMED, INCLUDED OR EXCLUDED. The loader row decides what a page
- * resolves; this walks whatever that produced. A draft carried a `CHROME_KEYS`
- * exclusion list dropping brand, website, header and footer — every one of them
- * a loader source key, which is to say database facts hardcoded here to save a
- * few hundred tokens of colours and navigation markup. Not a trade worth a
- * literal that goes stale in silence. A loader resolving a new source reaches
- * the assistant with no edit here (`offered-is-derived`).
- *
- * IT CANNOT OUTRUN THE GATE, BY CONSTRUCTION. This runs AFTER every content
- * gate, and a gate withholds by REMOVING content from this same graph. So
- * "everything in the graph" and "everything this viewer may see" are the same
- * set, and they cannot drift — which is what makes serialising the whole graph
- * safe rather than reckless.
- */
 async function buildResourceContext(
 	resolved: Record<string, unknown>,
 	resourceKey: string,

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", () =>