@teamscala/service-boot 0.23.317 → 0.23.319

package/src/handlers/singleton-tools-currency-watch.ts

@@ -30,11 +30,40 @@ import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { spawn } from "@teamscala/os/spawn";
 import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
 
-interface VersionSource {
-	type: "npm_package";
-	name: string;
-	dist_tag: string;
-}
+/**
+ * Where a tool's "latest" comes from.
+ *
+ * A DISCRIMINATED UNION, deliberately, rather than an optional `repo` field
+ * hanging off one shape: an unhandled variant then fails to compile instead of
+ * silently taking the npm branch. The previous single-member form
+ * (`type: "npm_package"`) made a GitHub-released binary UNREPRESENTABLE, not
+ * merely unregistered — which is why codex and zerostack are absent from
+ * `config/scala-singleton-tools` entirely. Both are standalone ELF binaries in
+ * ~/.local/bin and neither is npm-managed, so neither could be described at all.
+ *
+ * Their LOCATION is correct and must not be "fixed": `bun-bin-is-unstable`
+ * designates ${HOME}/.local/bin as the home for operator CLIs precisely so they
+ * never shadow a /usr/local/bin singleton wrapper. The gap was currency
+ * tracking, never placement.
+ */
+type VersionSource =
+	| {
+			type: "npm_package";
+			name: string;
+			dist_tag: string;
+	  }
+	| {
+			/** A GitHub release asset — the shape codex and zerostack ship as. */
+			type: "github_release";
+			/** "owner/repo". */
+			repo: string;
+			/**
+			 * Regex matched against each release asset's name to pick the download.
+			 * Required: a repo publishing several platform builds has no safe default,
+			 * and guessing one installs the wrong architecture silently.
+			 */
+			asset_pattern: string;
+	  };
 
 interface SingletonTool {
 	name: string;
@@ -98,9 +127,13 @@ function semverLt(a: string, b: string): boolean {
 /** Read the installed version from a tool's real_path (symlink-resolved binary). */
 async function readInstalledVersion(tool: SingletonTool): Promise<string | null> {
 	try {
-		if (tool.kind === "js" && tool.install_dir) {
+		const vs = tool.version_source;
+		// The package.json path only exists for an npm-sourced JS tool. A
+		// github_release tool has no node_modules entry, so it falls through to the
+		// `--version` probe below like any other binary.
+		if (tool.kind === "js" && tool.install_dir && vs?.type === "npm_package") {
 			// JS tools: read the installed package's package.json
-			const pkgJsonPath = `${tool.install_dir}/node_modules/${tool.version_source!.name}/package.json`;
+			const pkgJsonPath = `${tool.install_dir}/node_modules/${vs.name}/package.json`;
 			const pkg = await Bun.file(pkgJsonPath).json() as { version: string };
 			return pkg.version;
 		}
@@ -119,6 +152,30 @@ async function readInstalledVersion(tool: SingletonTool): Promise<string | null>
 	}
 }
 
+/**
+ * Latest published version for a GitHub-released tool.
+ *
+ * Reads the repo's latest release tag rather than enumerating assets, because
+ * the tag is what carries the VERSION; the asset pattern only decides which
+ * build to download at install time. A leading "v" is stripped so the value
+ * compares against `readInstalledVersion` output under the same semver parser.
+ */
+async function fetchLatestGithubRelease(repo: string): Promise<string | null> {
+	try {
+		const res = await fetch(
+			`https://api.github.com/repos/${repo}/releases/latest`,
+			{ headers: { accept: "application/vnd.github+json" } },
+		);
+		if (!res.ok) return null;
+		const release = (await res.json()) as { tag_name?: string };
+		const tag = (release.tag_name ?? "").trim().replace(/^v/, "");
+		if (!tag || !parseSemver(tag)) return null;
+		return tag;
+	} catch {
+		return null;
+	}
+}
+
 /** Fetch the latest version from npm for a given package + dist-tag. */
 async function fetchLatestVersion(pkg: string, distTag: string): Promise<string | null> {
 	try {
@@ -153,7 +210,35 @@ async function fetchLatestVersion(pkg: string, distTag: string): Promise<string
 /** Reinstall a stale tool to the latest version. */
 async function reinstallTool(tool: SingletonTool, latest: string): Promise<boolean> {
 	const log = getAppLogger();
-	const vs = tool.version_source!;
+	const vs = tool.version_source;
+	if (!vs) return false;
+
+	if (vs.type === "github_release") {
+		// A GitHub-released binary is NOT installed by a package manager, so there
+		// is no "reinstall" verb to call — it would have to be downloaded, verified,
+		// made executable and swapped atomically over a file that may be RUNNING.
+		// That is a real install path with real failure modes (partial download,
+		// wrong architecture, replacing a binary mid-execution), and doing it badly
+		// is worse than not doing it: a half-written CLI is a broken CLI.
+		//
+		// So this reports the drift and stops. Detection is live from today; the
+		// automated swap is a separate, deliberate change. Reporting a version the
+		// watcher cannot actually install is honest — silently claiming currency
+		// would not be.
+		log.warn(
+			`[singleton-tools-currency] ${tool.name}: STALE, latest ${latest} from ${vs.repo}. Automated github_release install is not implemented — update it manually.`,
+		);
+		recordEvent({
+			kind: "singleton-tools.currency.tick",
+			payload: {
+				tool: tool.name,
+				latest,
+				status: "stale-manual-update-required",
+				repo: vs.repo,
+			},
+		});
+		return false;
+	}
 
 	if (tool.kind === "js" && tool.install_dir) {
 		// JS tool: bun add in the install_dir
@@ -212,8 +297,21 @@ async function singletonToolsCurrencyWatch(_ctx: { config: ScheduledJobConfig })
 
 	for (const tool of config.tools) {
 		const vs = tool.version_source;
-		if (!vs || vs.type !== "npm_package") {
-			// No version_source declared — skip (the tool is not yet inside the mechanism)
+		if (!vs) {
+			// A tool with no version_source is NOT tracked, and that must be loud.
+			// This previously `continue`d silently as "not yet inside the mechanism",
+			// which is how a gap becomes permanent: nothing distinguishes a tool
+			// nobody has declared from one that is up to date, so the watcher reports
+			// a clean tick while the tool rots. That is the exact shape of
+			// `a-component-may-not-report-a-state-it-has-not-verified` — the run
+			// advertises coverage it never performed.
+			log.warn(
+				`[singleton-tools-currency] ${tool.name}: NO version_source — not tracked, cannot be kept current. Add one to config/scala-singleton-tools.`,
+			);
+			recordEvent({
+				kind: "singleton-tools.currency.tick",
+				payload: { tool: tool.name, status: "no-version-source" },
+			});
 			continue;
 		}
 
@@ -236,7 +334,12 @@ async function singletonToolsCurrencyWatch(_ctx: { config: ScheduledJobConfig })
 			continue;
 		}
 
-		const latest = await fetchLatestVersion(vs.name, vs.dist_tag);
+		// Branch on the discriminant, never on a field's presence — an unhandled
+		// variant is a compile error here rather than a silent fall-through to npm.
+		const latest =
+			vs.type === "npm_package"
+				? await fetchLatestVersion(vs.name, vs.dist_tag)
+				: await fetchLatestGithubRelease(vs.repo);
 		if (!latest) {
 			log.warn(`[singleton-tools-currency] ${tool.name}: cannot fetch latest — skip`);
 			recordEvent({

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-api-routes.ts

@@ -19,14 +19,20 @@ import { BootFatalError } from "@teamscala/os/errors/boot-error";
 import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
 import type { Context, Hono } from "hono";
 import { getConnInfo } from "hono/bun";
+import { CALLER_HEADERS } from "@teamscala/os/contracts/mcp";
 
-const REMOTE_PORT_HEADER = "x-caller-remote-port";
+// From CALLER_HEADERS, never a literal: this name is one end of a contract the
+// gateway's caller-resolution reads, and a literal stores it twice. The
+// 2026-08-02 outage was that exact drift on a sibling header (reader on
+// `x-user-id`, writer on `x-caller-user-id`), and it took every tool on the
+// cloud MCP down once the branch masking it was closed.
+const REMOTE_PORT_HEADER = CALLER_HEADERS.REMOTE_PORT;
 // Verified socket-peer address (unforgeable transport origin). Sanitized
 // (client-supplied value deleted) then set from getConnInfo so handlers that
 // receive only a Request (e.g. mcp-tool-runtime/mount.ts) can gate on the
 // genuine transport origin per no-client-controlled-trust-signals — an external
 // attacker cannot make their TCP connection appear on the server's loopback.
-const REMOTE_ADDR_HEADER = "x-caller-remote-address";
+const REMOTE_ADDR_HEADER = CALLER_HEADERS.REMOTE_ADDRESS;
 
 export function registerApiRoutes(
 	app: Hono,

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();
+	});
+});