@teamscala/service-boot 0.23.302 → 0.23.304

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.302",
+  "version": "0.23.304",
   "sideEffects": false,
   "files": [
     "src"
@@ -386,6 +386,14 @@
       "types": "./src/fn-routers/sign-in-flow-router.d.ts",
       "default": "./src/fn-routers/sign-in-flow-router.ts"
     },
+    "./fn-routers/task-sync-brief": {
+      "types": "./src/fn-routers/task-sync-brief.d.ts",
+      "default": "./src/fn-routers/task-sync-brief.ts"
+    },
+    "./fn-routers/task-sync-brief.ts": {
+      "types": "./src/fn-routers/task-sync-brief.d.ts",
+      "default": "./src/fn-routers/task-sync-brief.ts"
+    },
     "./fn-routers/task-sync-dispatch": {
       "types": "./src/fn-routers/task-sync-dispatch.d.ts",
       "default": "./src/fn-routers/task-sync-dispatch.ts"
@@ -506,6 +514,14 @@
       "types": "./src/handlers/scala-tools-currency-watch.d.ts",
       "default": "./src/handlers/scala-tools-currency-watch.ts"
     },
+    "./handlers/singleton-tools-currency-watch": {
+      "types": "./src/handlers/singleton-tools-currency-watch.d.ts",
+      "default": "./src/handlers/singleton-tools-currency-watch.ts"
+    },
+    "./handlers/singleton-tools-currency-watch.ts": {
+      "types": "./src/handlers/singleton-tools-currency-watch.d.ts",
+      "default": "./src/handlers/singleton-tools-currency-watch.ts"
+    },
     "./handlers/sweep-event-log": {
       "types": "./src/handlers/sweep-event-log.d.ts",
       "default": "./src/handlers/sweep-event-log.ts"

package/src/fn-routers/task-sync-brief.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lane BRIEF resolution for task-sync: a spawned lane PULLS its own brief. The
+ * lane's CLI extension reads its own session id on load, resolves the task
+ * assigned to that session, and reads the brief from that task's LATEST comment.
+ * Nothing is pasted, typed, passed as an argument or sent over a channel
+ * (`scala-docs/reference/action-emission-architecture.md` "The lane PULLS its
+ * brief"). This file owns the readAssignedBrief ORPC handler + its pure helper;
+ * the router mounts the handler.
+ *
+ * Split out of task-sync-router.ts for the same reason task-sync-lane.ts +
+ * task-sync-projection.ts exist: the router sits at its 1000-line commit gate,
+ * so every cohesive unit that can live in a sibling does. The self-brief leg is
+ * one unit — the handler + the response-shaping decision belong together.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Bound to the work_items + comments schema and to task-sync's own
+ * kind_data.lane.session convention; no unrelated app could install this
+ * unmodified.
+ */
+import type { Prisma, CommentRow } from "./task-sync-router.ts";
+import { type Context } from "./auth-router.ts";
+/**
+ * Shape the readAssignedBrief response from a resolved task + its latest
+ * comment. Pure (no prisma) so the decision — "no task/comment ⇒ nulls, never a
+ * verdict from no data" (`no-verdict-from-no-data`) — is unit-testable. A null
+ * task or null comment returns all-null rather than an empty/fake brief, so the
+ * extension can distinguish "nothing to inject" from "inject this".
+ */
+export declare function shapeBriefResponse(task: {
+    id: string;
+} | null, comment: Pick<CommentRow, "content" | "created_at"> | null): {
+    work_item_id: string | null;
+    brief: string | null;
+    comment_created_at: string | null;
+};
+/**
+ * Read the LATEST comment on a work_items task. The comment IS the brief for a
+ * run: every spawn writes a NEW comment, and the description is never the brief,
+ * so "what was this lane told" always has exactly one answer
+ * (`assignment-as-dispatch`). Newest-first by created_at. Returns null when the
+ * task has no comment yet — the extension treats that as "no brief to inject".
+ */
+export declare function readLatestTaskComment(prisma: Prisma, workItemId: string): Promise<CommentRow | null>;
+/**
+ * readAssignedBrief ORPC handler. A lane's CLI extension calls this with its
+ * own session id to pull its brief. Same transport as bindLane/readTaskList: the
+ * session id arrives on x-lane-session (and body.lane_session as fallback). The
+ * procedure is page-gate-exempt (fn.taskSync), so a localhost pane shell
+ * authenticates as super-admin via resolveUser with no session cookie.
+ */
+export declare const readAssignedBriefHandler: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+    headers: Headers;
+    resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+    prisma: any;
+    user: import("./auth-router.ts").User;
+    orgId: string | null | undefined;
+}>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+    work_item_id: string | null;
+    brief: string | null;
+    comment_created_at: string | null;
+}, {
+    work_item_id: string | null;
+    brief: string | null;
+    comment_created_at: string | null;
+}>, Record<never, never>, Record<never, never>>;

package/src/fn-routers/task-sync-brief.test.ts

@@ -0,0 +1,77 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Unit tests for the self-brief leg: shapeBriefResponse (the pure
+ * no-task/no-comment ⇒ nulls decision) + source-contract assertions that
+ * readLatestTaskComment reads the LATEST comment and the handler resolves by
+ * session. Covers `what-must-have-a-test` for the new procedure.
+ */
+import { describe, it, expect } from "bun:test";
+import { shapeBriefResponse, readLatestTaskComment } from "./task-sync-brief.ts";
+
+describe("shapeBriefResponse (no verdict from no data)", () => {
+	it("returns all-null when there is no task", () => {
+		// A lane with no bound task has no brief — null, never an empty fake.
+		expect(shapeBriefResponse(null, { content: "x", created_at: new Date() })).toEqual({
+			work_item_id: null,
+			brief: null,
+			comment_created_at: null,
+		});
+	});
+
+	it("returns all-null when the task has no comment yet", () => {
+		// The task exists but no spawn comment landed; the extension must inject
+		// nothing rather than a fabricated brief.
+		expect(shapeBriefResponse({ id: "task-1" }, null)).toEqual({
+			work_item_id: null,
+			brief: null,
+			comment_created_at: null,
+		});
+	});
+
+	it("returns the comment content + ISO created_at for a resolved task+comment", () => {
+		const ts = new Date("2026-08-01T03:24:00.000Z");
+		expect(shapeBriefResponse({ id: "task-7" }, { content: "Do the thing", created_at: ts })).toEqual({
+			work_item_id: "task-7",
+			brief: "Do the thing",
+			comment_created_at: "2026-08-01T03:24:00.000Z",
+		});
+	});
+
+	it("serializes the comment created_at deterministically (Date → ISO)", () => {
+		const ts = new Date(0);
+		const out = shapeBriefResponse({ id: "t" }, { content: "c", created_at: ts });
+		expect(out.comment_created_at).toBe("1970-01-01T00:00:00.000Z");
+	});
+});
+
+describe("readAssignedBrief reads the LATEST comment (source contract)", () => {
+	const briefSrc = Bun.file(new URL("./task-sync-brief.ts", import.meta.url).pathname);
+
+	it("queries comments newest-first by created_at on work_item_id", async () => {
+		// The comment IS the brief for a run; ordering by created_at desc makes the
+		// LATEST comment (this run's) the answer, never a stale prior-run comment.
+		const text = await briefSrc.text();
+		expect(text).toContain('orderBy: { created_at: "desc" }');
+		expect(text).toContain("work_item_id: workItemId");
+	});
+
+	it("resolves the task by session before reading its comment", async () => {
+		// The lane's own session id is the join key — a pane id is never the key
+		// (it outlives the session and would inherit a prior session's brief).
+		const text = await briefSrc.text();
+		expect(text).toContain("resolveLaneTask(prisma, session)");
+	});
+});
+
+describe("readLatestTaskComment is a single latest-comment read", () => {
+	it("returns null when the prisma client has no comments model (feature-detect)", async () => {
+		// `comments` is a universal shared model, but the access is feature-detected
+		// like the fleet_agent_runs reads so a client without it degrades to "no
+		// brief" rather than throwing.
+		const out = await readLatestTaskComment({} as never, "task-1");
+		expect(out).toBe(null);
+	});
+});

package/src/fn-routers/task-sync-brief.ts

@@ -0,0 +1,97 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lane BRIEF resolution for task-sync: a spawned lane PULLS its own brief. The
+ * lane's CLI extension reads its own session id on load, resolves the task
+ * assigned to that session, and reads the brief from that task's LATEST comment.
+ * Nothing is pasted, typed, passed as an argument or sent over a channel
+ * (`scala-docs/reference/action-emission-architecture.md` "The lane PULLS its
+ * brief"). This file owns the readAssignedBrief ORPC handler + its pure helper;
+ * the router mounts the handler.
+ *
+ * Split out of task-sync-router.ts for the same reason task-sync-lane.ts +
+ * task-sync-projection.ts exist: the router sits at its 1000-line commit gate,
+ * so every cohesive unit that can live in a sibling does. The self-brief leg is
+ * one unit — the handler + the response-shaping decision belong together.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Bound to the work_items + comments schema and to task-sync's own
+ * kind_data.lane.session convention; no unrelated app could install this
+ * unmodified.
+ */
+
+import type { Prisma, CommentRow } from "./task-sync-router.ts";
+import type { WorkItem } from "./task-sync-router.ts";
+import { authed, type Context } from "./auth-router.ts";
+import { resolveLaneTask } from "./task-sync-lane.ts";
+
+/**
+ * Shape the readAssignedBrief response from a resolved task + its latest
+ * comment. Pure (no prisma) so the decision — "no task/comment ⇒ nulls, never a
+ * verdict from no data" (`no-verdict-from-no-data`) — is unit-testable. A null
+ * task or null comment returns all-null rather than an empty/fake brief, so the
+ * extension can distinguish "nothing to inject" from "inject this".
+ */
+export function shapeBriefResponse(
+	task: { id: string } | null,
+	comment: Pick<CommentRow, "content" | "created_at"> | null,
+): { work_item_id: string | null; brief: string | null; comment_created_at: string | null } {
+	if (!task || !comment) {
+		return { work_item_id: null, brief: null, comment_created_at: null };
+	}
+	return {
+		work_item_id: task.id,
+		brief: comment.content,
+		comment_created_at:
+			comment.created_at instanceof Date ? comment.created_at.toISOString() : String(comment.created_at),
+	};
+}
+
+/**
+ * Read the LATEST comment on a work_items task. The comment IS the brief for a
+ * run: every spawn writes a NEW comment, and the description is never the brief,
+ * so "what was this lane told" always has exactly one answer
+ * (`assignment-as-dispatch`). Newest-first by created_at. Returns null when the
+ * task has no comment yet — the extension treats that as "no brief to inject".
+ */
+export async function readLatestTaskComment(
+	prisma: Prisma,
+	workItemId: string,
+): Promise<CommentRow | null> {
+	const comments = (
+		prisma as unknown as {
+			comments?: {
+				findFirst: (a: unknown) => Promise<CommentRow | null>;
+			};
+		}
+	).comments;
+	if (!comments?.findFirst) return null;
+	return comments.findFirst({
+		where: { work_item_id: workItemId },
+		orderBy: { created_at: "desc" },
+	});
+}
+
+/**
+ * readAssignedBrief ORPC handler. A lane's CLI extension calls this with its
+ * own session id to pull its brief. Same transport as bindLane/readTaskList: the
+ * session id arrives on x-lane-session (and body.lane_session as fallback). The
+ * procedure is page-gate-exempt (fn.taskSync), so a localhost pane shell
+ * authenticates as super-admin via resolveUser with no session cookie.
+ */
+export const readAssignedBriefHandler = authed.handler(async ({ input, context }) => {
+	const ctx = context as Context;
+	const prisma = ctx.prisma as Prisma;
+	const body = (input ?? {}) as { lane_session?: string };
+	const session = body.lane_session ?? ctx.headers?.get("x-lane-session") ?? null;
+	if (!session) {
+		const { ORPCError } = await import("@orpc/server");
+		throw new ORPCError("BAD_REQUEST", { message: "readAssignedBrief requires lane_session" });
+	}
+	const task = (await resolveLaneTask(prisma, session)) as (WorkItem & { id: string }) | null;
+	if (!task) return shapeBriefResponse(null, null);
+	const comment = await readLatestTaskComment(prisma, task.id);
+	return shapeBriefResponse(task, comment);
+});

package/src/fn-routers/task-sync-router.d.ts

@@ -102,7 +102,15 @@ export type Prisma = {
             count: number;
         }>;
     };
+    comments?: {
+        findFirst: (a: unknown) => Promise<CommentRow | null>;
+    };
 };
+/** A `comments` row — only the fields readAssignedBrief touches. */
+export interface CommentRow {
+    content: string;
+    created_at: Date;
+}
 /**
  * A dispatched run already points at its fleet_tasks row. Task-sync may fill
  * the convenience join for an adopted lane, but must never replace that
@@ -285,6 +293,32 @@ export declare const taskSyncRouter: {
         task_title: string;
         subtasks: TaskListItem[];
     }>, Record<never, never>, Record<never, never>>;
+    /**
+     * DB→AGENT self-brief leg. A spawned lane PULLS its own brief — nothing is
+     * pasted, typed, passed as an argument or sent over a channel
+     * (`action-emission-architecture.md` "The lane PULLS its brief"). The lane's
+     * CLI extension reads its own session id on load, calls this procedure, and
+     * reads the brief from the task's LATEST comment. The comment — not the
+     * description, not a stale comment — is the brief for THIS run: every spawn
+     * writes a NEW comment, so "what was this lane told" always has exactly one
+     * answer (`assignment-as-dispatch`). Handler lives in task-sync-brief.ts
+     * (router is at its line budget); mounted here so fn.taskSync surfaces it.
+     */
+    readAssignedBrief: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        work_item_id: string | null;
+        brief: string | null;
+        comment_created_at: string | null;
+    }, {
+        work_item_id: string | null;
+        brief: string | null;
+        comment_created_at: string | null;
+    }>, Record<never, never>, Record<never, never>>;
     /**
      * DB→AGENT realtime leg (explicit dispatch path). Record an out-of-band
      * change to a subtask's status (operator toggles it in the projects UI,

package/src/fn-routers/task-sync-router.ts

@@ -41,6 +41,7 @@ import { getPlatformOrgId } from "@teamscala/db/registry/platform";
 import { authed, type Context } from "./auth-router.ts";
 import { notifyLaneOfTaskChange } from "./task-sync-dispatch.ts";
 import { resolveLaneTask, resolveLaneWorkName } from "./task-sync-lane.ts";
+import { readAssignedBriefHandler } from "./task-sync-brief.ts";
 import * as v from "valibot";
 import {
 	STATUS_TO_WORK_ITEM,
@@ -122,8 +123,21 @@ export type Prisma = {
 		update: (a: unknown) => Promise<WorkItem>;
 		deleteMany: (a: unknown) => Promise<{ count: number }>;
 	};
+	// `comments` is a universal shared model (owned by @teamgbg/db), so every
+	// service with the db client carries it. Declared here rather than
+	// feature-detected because, unlike fleet_agent_runs (fleet-service-only), it
+	// is part of the shared client every consumer installs.
+	comments?: {
+		findFirst: (a: unknown) => Promise<CommentRow | null>;
+	};
 };
 
+/** A `comments` row — only the fields readAssignedBrief touches. */
+export interface CommentRow {
+	content: string;
+	created_at: Date;
+}
+
 /**
  * A dispatched run already points at its fleet_tasks row. Task-sync may fill
  * the convenience join for an adopted lane, but must never replace that
@@ -900,6 +914,19 @@ export const taskSyncRouter = {
 		return { task_id: task.id, task_title: task.title, subtasks };
 	}),
 
+	/**
+	 * DB→AGENT self-brief leg. A spawned lane PULLS its own brief — nothing is
+	 * pasted, typed, passed as an argument or sent over a channel
+	 * (`action-emission-architecture.md` "The lane PULLS its brief"). The lane's
+	 * CLI extension reads its own session id on load, calls this procedure, and
+	 * reads the brief from the task's LATEST comment. The comment — not the
+	 * description, not a stale comment — is the brief for THIS run: every spawn
+	 * writes a NEW comment, so "what was this lane told" always has exactly one
+	 * answer (`assignment-as-dispatch`). Handler lives in task-sync-brief.ts
+	 * (router is at its line budget); mounted here so fn.taskSync surfaces it.
+	 */
+	readAssignedBrief: readAssignedBriefHandler,
+
 	/**
 	 * DB→AGENT realtime leg (explicit dispatch path). Record an out-of-band
 	 * change to a subtask's status (operator toggles it in the projects UI,

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SOURCE = readFileSync(
+	join(import.meta.dir, "singleton-tools-currency-watch.ts"),
+	"utf-8",
+);
+
+const CODE = SOURCE.split("\n")
+	.filter((l) => !l.trimStart().startsWith("//") && !l.trimStart().startsWith("*"))
+	.join("\n");
+
+describe("singleton-tools-currency-watch", () => {
+	test("reads version_source from config/scala-singleton-tools", () => {
+		expect(CODE).toContain("scala-singleton-tools");
+	});
+
+	test("reinstalls stale tools", () => {
+		expect(CODE).toContain("reinstall");
+	});
+
+	test("skips bare tools (bun) with a deferred event", () => {
+		expect(CODE).toContain("deferred-to-bun-stable-watch");
+	});
+
+	test("records tick events for observability", () => {
+		expect(CODE).toContain("singleton-tools.currency.tick");
+	});
+
+	test("records reinstall events", () => {
+		expect(CODE).toContain("singleton-tools.currency.reinstalled");
+	});
+
+	test("records install-failed events", () => {
+		expect(CODE).toContain("singleton-tools.currency.install-failed");
+	});
+
+	test("uses semver comparison (not string comparison)", () => {
+		expect(CODE).toContain("semverLt");
+	});
+
+	test("handles unreadable installed version gracefully", () => {
+		expect(CODE).toContain("unreadable");
+	});
+});

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

@@ -0,0 +1,279 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The `singleton-tools-currency-watch` pg-boss handler — keeps every tool
+ * declared in `config/scala-singleton-tools` at its `version_source` latest.
+ *
+ * Each tool entry now carries a `version_source` block:
+ *   { type: "npm_package", name: "<pkg>", dist_tag: "latest" }
+ * The handler reads the row, checks each tool's installed version against the
+ * registry dist-tag, and reinstalls when stale. Reinstall strategy per kind:
+ *   - "js" (oxlint): `bun add <pkg>@<dist_tag>` in the tool's `install_dir`
+ *   - "elf" (tsgo/tsc): `bun add -g <pkg>@<dist_tag>` (global install)
+ *   - "bare" (bun): SKIPPED — bun is a standalone ELF binary; its upgrade is
+ *     owned by `bun-stable-watch` (which watches for 1.4.0 stable). This handler
+ *     logs a skip event so the gap is observable, never silent.
+ *
+ * Boot-safety (protective-layers-fail-explicitly): every step is wrapped — a
+ * dist-tag fetch failure, version-parse failure, or install failure NEVER
+ * crashes the job or loga; each records a failure event + returns. Repeated
+ * reinstalls are prevented by strict semver-lt comparison.
+ *
+ * Registered under slug `@teamscala/service-boot:singleton-tools-currency-watch`.
+ */
+import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { recordEvent } from "@teamscala/event-log/record-event";
+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;
+}
+
+interface SingletonTool {
+	name: string;
+	kind: "elf" | "bare" | "js";
+	real_path: string;
+	lock_name?: string;
+	install_dir?: string;
+	version_source?: VersionSource;
+}
+
+interface SingletonToolsConfig {
+	tools: SingletonTool[];
+}
+
+interface SemverParts {
+	major: number;
+	minor: number;
+	patch: number;
+	/** Pre-release suffix, e.g. "dev.20260620.1" or "" for stable. */
+	pre: string;
+}
+
+function parseSemver(v: string): SemverParts | null {
+	const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(v.trim());
+	if (!m) return null;
+	return { major: Number(m[1]!), minor: Number(m[2]!), patch: Number(m[3]!), pre: m[4] ?? "" };
+}
+
+/** Compare two pre-release identifiers: "dev.20260707.2" > "dev.20260620.1". */
+function preLt(a: string, b: string): boolean {
+	// Split on dots, compare each segment numerically if possible, else lexicographically.
+	const sa = a.split(".");
+	const sb = b.split(".");
+	for (let i = 0; i < Math.min(sa.length, sb.length); i++) {
+		const na = Number(sa[i]);
+		const nb = Number(sb[i]);
+		if (!Number.isNaN(na) && !Number.isNaN(nb)) {
+			if (na !== nb) return na < nb;
+		} else if (sa[i] !== sb[i]) {
+			return sa[i]! < sb[i]!;
+		}
+	}
+	return sa.length < sb.length;
+}
+
+function semverLt(a: string, b: string): boolean {
+	const pa = parseSemver(a);
+	const pb = parseSemver(b);
+	if (!pa || !pb) return false;
+	if (pa.major !== pb.major) return pa.major < pb.major;
+	if (pa.minor !== pb.minor) return pa.minor < pb.minor;
+	if (pa.patch !== pb.patch) return pa.patch < pb.patch;
+	// Same major.minor.patch — compare pre-release.
+	// No pre-release (stable) > any pre-release.
+	if (!pa.pre && !pb.pre) return false;
+	if (!pa.pre) return false; // a is stable, b is pre — a is newer
+	if (!pb.pre) return true; // a is pre, b is stable — a is older
+	return preLt(pa.pre, pb.pre);
+}
+
+/** 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) {
+			// JS tools: read the installed package's package.json
+			const pkgJsonPath = `${tool.install_dir}/node_modules/${tool.version_source!.name}/package.json`;
+			const pkg = await Bun.file(pkgJsonPath).json() as { version: string };
+			return pkg.version;
+		}
+		// ELF/bare: run --version on the binary
+		const result = await spawn({
+			name: `singleton-tools-currency:version-${tool.name}`,
+			command: [tool.real_path, "--version"],
+			timeoutMs: 15_000,
+		});
+		const out = (result.stdout ?? "").trim();
+		// tsgo prints "Version 7.0.0-dev.20260620.1" — extract the version
+		const vMatch = /(\d+\.\d+\.\d+(?:-dev\.\d+)?)/.exec(out);
+		return vMatch?.[1] ?? out;
+	} 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 {
+		// @teamscala/* packages use the internal dist-tag tool; public npm packages
+		// fetch directly from the npm registry (same pattern as bun-stable-watch).
+		if (pkg.startsWith("@teamscala/")) {
+			const result = await spawn({
+				name: "singleton-tools-currency:dist-tag",
+				command: ["scala-tools", "packages", "dist-tag", "get", pkg, distTag],
+				timeoutMs: 30_000,
+			});
+			const latest =
+				(result.stdout ?? "")
+					.split("\n")
+					.map((l) => l.trim())
+					.filter(Boolean)
+					.pop() ?? "";
+			if (!latest || !parseSemver(latest)) return null;
+			return latest;
+		}
+		// Public npm package: fetch the dist-tag manifest directly.
+		const url = `https://registry.npmjs.org/${encodeURIComponent(pkg)}/${encodeURIComponent(distTag)}`;
+		const res = await fetch(url, { headers: { accept: "application/json" } });
+		if (!res.ok) return null;
+		const manifest = (await res.json()) as { version: string };
+		return manifest.version ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/** 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!;
+
+	if (tool.kind === "js" && tool.install_dir) {
+		// JS tool: bun add in the install_dir
+		const result = await spawn({
+			name: `singleton-tools-currency:install-${tool.name}`,
+			command: ["bun", "add", `${vs.name}@${vs.dist_tag}`],
+			cwd: tool.install_dir,
+			timeoutMs: 300_000,
+		});
+		if ((result.exitCode ?? -1) !== 0) {
+			log.error(
+				`[singleton-tools-currency] ${tool.name} install failed (exit ${result.exitCode}): ${(result.stderr ?? "").slice(0, 200)}`,
+			);
+			return false;
+		}
+		return true;
+	}
+
+	if (tool.kind === "elf") {
+		// ELF tool: bun add -g
+		const result = await spawn({
+			name: `singleton-tools-currency:install-${tool.name}`,
+			command: ["bun", "add", "-g", `${vs.name}@${vs.dist_tag}`],
+			timeoutMs: 300_000,
+		});
+		if ((result.exitCode ?? -1) !== 0) {
+			log.error(
+				`[singleton-tools-currency] ${tool.name} global install failed (exit ${result.exitCode}): ${(result.stderr ?? "").slice(0, 200)}`,
+			);
+			return false;
+		}
+		return true;
+	}
+
+	// bare (bun) — skip, owned by bun-stable-watch
+	log.info(`[singleton-tools-currency] ${tool.name} (bare) — skip, owned by bun-stable-watch`);
+	return false;
+}
+
+async function singletonToolsCurrencyWatch(_ctx: { config: ScheduledJobConfig }): Promise<void> {
+	const log = getAppLogger();
+
+	let config: SingletonToolsConfig;
+	try {
+		config = loadRegistryConfig("config", "scala-singleton-tools") as never as SingletonToolsConfig;
+	} catch (err) {
+		log.warn(
+			`[singleton-tools-currency] cannot load config/scala-singleton-tools — skip: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		recordEvent({
+			kind: "singleton-tools.currency.tick",
+			payload: { note: "config/scala-singleton-tools unreadable" },
+		});
+		return;
+	}
+
+	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)
+			continue;
+		}
+
+		if (tool.kind === "bare") {
+			// bun: owned by bun-stable-watch; log a tick so the gap is observable
+			recordEvent({
+				kind: "singleton-tools.currency.tick",
+				payload: { tool: tool.name, status: "deferred-to-bun-stable-watch" },
+			});
+			continue;
+		}
+
+		const installed = await readInstalledVersion(tool);
+		if (!installed) {
+			log.warn(`[singleton-tools-currency] ${tool.name}: cannot read installed version — skip`);
+			recordEvent({
+				kind: "singleton-tools.currency.tick",
+				payload: { tool: tool.name, installed: null, note: "unreadable" },
+			});
+			continue;
+		}
+
+		const latest = await fetchLatestVersion(vs.name, vs.dist_tag);
+		if (!latest) {
+			log.warn(`[singleton-tools-currency] ${tool.name}: cannot fetch latest — skip`);
+			recordEvent({
+				kind: "singleton-tools.currency.tick",
+				payload: { tool: tool.name, installed, latest: null, note: "dist-tag unreadable" },
+			});
+			continue;
+		}
+
+		if (!semverLt(installed, latest)) {
+			recordEvent({
+				kind: "singleton-tools.currency.tick",
+				payload: { tool: tool.name, installed, latest, status: "current" },
+			});
+			continue;
+		}
+
+		// STALE — reinstall
+		log.warn(
+			`[singleton-tools-currency] ${tool.name} ${installed} < latest ${latest} — reinstalling`,
+		);
+		const ok = await reinstallTool(tool, latest);
+		if (ok) {
+			recordEvent({
+				kind: "singleton-tools.currency.reinstalled",
+				payload: { tool: tool.name, from: installed, to: latest },
+			});
+		} else {
+			recordEvent({
+				kind: "singleton-tools.currency.install-failed",
+				payload: { tool: tool.name, from: installed, to: latest },
+			});
+		}
+	}
+}
+
+pgBossHandlerRegistry.register(
+	"@teamscala/service-boot:singleton-tools-currency-watch",
+	singletonToolsCurrencyWatch,
+);

package/src/pg-boss-mount.d.ts

@@ -18,6 +18,7 @@ import "./handlers/bun-stable-watch.ts";
 import "./handlers/whatsapp-liveness.ts";
 import "./handlers/upstream-issue-sync.ts";
 import "./handlers/scala-tools-currency-watch.ts";
+import "./handlers/singleton-tools-currency-watch.ts";
 import "./handlers/registry-stale-inactive-sweep.ts";
 import "./handlers/pane-outbox-drain.ts";
 export interface PgBossMountContext {

package/src/pg-boss-mount.ts

@@ -31,6 +31,7 @@ import "./handlers/bun-stable-watch.ts";
 import "./handlers/whatsapp-liveness.ts";
 import "./handlers/upstream-issue-sync.ts";
 import "./handlers/scala-tools-currency-watch.ts";
+import "./handlers/singleton-tools-currency-watch.ts";
 import "./handlers/registry-stale-inactive-sweep.ts";
 import "./handlers/pane-outbox-drain.ts";
 

package/src/two-phase-boot.d.ts

@@ -12,7 +12,7 @@
  * built in the background and atomically swapped in. This eliminates the
  * ~25s channel outage window during scala-agents restart.
  */
-import { Hono } from "hono";
+import { Hono, type Context } from "hono";
 import type { ServiceInstallConfig } from "./load-service-install-row.ts";
 import { mountServerPackages } from "./mount-server-packages.ts";
 import type { PageServerDeps } from "./ui-service.ts";
@@ -28,6 +28,49 @@ export declare function getPageHandlerState(): {
     ready: boolean;
     hasHandler: boolean;
 };
+/**
+ * `/health` for a UI service — 200 ONLY once the full app can actually render
+ * a page, 503 before that.
+ *
+ * This endpoint is not decoration: it is the wake gate for every scale-to-zero
+ * app. `scala-activator` (`@teamscala/scale-to-zero`) holds the client's TCP
+ * connection through a cold wake and pipes it the instant `isHealthy(port)` —
+ * a plain `GET /health` — returns ok, which is what `scale-to-zero-apps-sleep-
+ * on-demand` means by "`/health`-gates the wake (the client never sees a boot
+ * 503)".
+ *
+ * It previously answered a flat `{status:"ok"}` as soon as the MINIMAL app was
+ * serving, because the readiness gate flips ready after phase 1 so the ORPC/MCP
+ * surface can accept traffic early. But phase 1 CANNOT render: the phase-1 page
+ * handler below returns 503 until `setPageHandler` runs at the phase-2 swap. So
+ * `/health` reported ready while every page 503'd, the activator believed the
+ * wake had landed, and it piped the customer's first request straight into that
+ * window — the customer got the 503.
+ *
+ * Measured 2026-07-31 on quiz-dev/sign-dev: the activator logged `awake` for
+ * scala-quiz at 05:58:25.446 and the app logged `GET / 503 3ms` at 05:58:25.452
+ * — 6ms later, and 1004ms BEFORE "Swapped from minimal app to full app". Nine
+ * such 503s on scala-quiz and two on scala-sign, every one 0-23ms (the
+ * placeholder, which does no render work). scala-public logged ZERO, which is
+ * the whole reason it looked healthy while the other two did not: the gap is a
+ * RACE whose width is the phase-1→phase-2 build time (1420ms cold, 137ms warm),
+ * not a config difference between the apps.
+ *
+ * Gating this on `fullAppReady` makes the signal honest for every consumer at
+ * once (the activator's wake gate, `poller-post-restart-health-gate`, any
+ * health-gated router) rather than teaching each one its own probe, and it is
+ * what `readiness-gated-boot` already requires: "/health returns 503 until
+ * ready, 200 after — so it is the real readiness signal", a service being
+ * "binary: fully-ready or cleanly-unavailable". A UI service that cannot render
+ * is not ready, per `liveness-by-capability-not-process-existence` — liveness is
+ * a probe of the capability being REQUESTED, never of process existence or of
+ * some other surface that happens to answer.
+ *
+ * The early readiness-gate flip is deliberately left alone: it gates the ORPC
+ * 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.
+ */
+export declare function healthHandler(c: Context): Response;
 export interface MinimalAppResult {
     app: Hono;
     mountRegistry: Awaited<ReturnType<typeof mountServerPackages>>;

package/src/two-phase-boot.ts

@@ -17,7 +17,7 @@ import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { buildWakingPageHtml } from "@teamscala/os/brand/waking-page-html";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";
 import { createTimer } from "@teamscala/timing/create-timer";
-import { Hono } from "hono";
+import { Hono, type Context } from "hono";
 import { compress } from "hono/compress";
 import { cors } from "hono/cors";
 import { timing } from "hono/timing";
@@ -77,6 +77,54 @@ export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
 	return { ready: fullAppReady, hasHandler: realPageHandler !== null };
 }
 
+/**
+ * `/health` for a UI service — 200 ONLY once the full app can actually render
+ * a page, 503 before that.
+ *
+ * This endpoint is not decoration: it is the wake gate for every scale-to-zero
+ * app. `scala-activator` (`@teamscala/scale-to-zero`) holds the client's TCP
+ * connection through a cold wake and pipes it the instant `isHealthy(port)` —
+ * a plain `GET /health` — returns ok, which is what `scale-to-zero-apps-sleep-
+ * on-demand` means by "`/health`-gates the wake (the client never sees a boot
+ * 503)".
+ *
+ * It previously answered a flat `{status:"ok"}` as soon as the MINIMAL app was
+ * serving, because the readiness gate flips ready after phase 1 so the ORPC/MCP
+ * surface can accept traffic early. But phase 1 CANNOT render: the phase-1 page
+ * handler below returns 503 until `setPageHandler` runs at the phase-2 swap. So
+ * `/health` reported ready while every page 503'd, the activator believed the
+ * wake had landed, and it piped the customer's first request straight into that
+ * window — the customer got the 503.
+ *
+ * Measured 2026-07-31 on quiz-dev/sign-dev: the activator logged `awake` for
+ * scala-quiz at 05:58:25.446 and the app logged `GET / 503 3ms` at 05:58:25.452
+ * — 6ms later, and 1004ms BEFORE "Swapped from minimal app to full app". Nine
+ * such 503s on scala-quiz and two on scala-sign, every one 0-23ms (the
+ * placeholder, which does no render work). scala-public logged ZERO, which is
+ * the whole reason it looked healthy while the other two did not: the gap is a
+ * RACE whose width is the phase-1→phase-2 build time (1420ms cold, 137ms warm),
+ * not a config difference between the apps.
+ *
+ * Gating this on `fullAppReady` makes the signal honest for every consumer at
+ * once (the activator's wake gate, `poller-post-restart-health-gate`, any
+ * health-gated router) rather than teaching each one its own probe, and it is
+ * what `readiness-gated-boot` already requires: "/health returns 503 until
+ * ready, 200 after — so it is the real readiness signal", a service being
+ * "binary: fully-ready or cleanly-unavailable". A UI service that cannot render
+ * is not ready, per `liveness-by-capability-not-process-existence` — liveness is
+ * a probe of the capability being REQUESTED, never of process existence or of
+ * some other surface that happens to answer.
+ *
+ * The early readiness-gate flip is deliberately left alone: it gates the ORPC
+ * 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.
+ */
+export function healthHandler(c: Context): Response {
+	return fullAppReady
+		? c.json({ status: "ok" })
+		: c.json({ status: "starting" }, 503, { "Retry-After": "1" });
+}
+
 export interface MinimalAppResult {
 	app: Hono;
 	mountRegistry: Awaited<ReturnType<typeof mountServerPackages>>;
@@ -161,7 +209,7 @@ export async function buildMinimalApp(
 
 	// Core middleware
 	app.use("*", readinessGate);
-	app.get("/health", (c) => c.json({ status: "ok" }));
+	app.get("/health", healthHandler);
 	app.use("*", injectSecurityHeaders);
 	const cookieDomain = await getCookieDomain();
 	app.use(

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

@@ -0,0 +1,71 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The wake gate for every scale-to-zero app: `/health` must not report ready
+ * while the service still 503s pages.
+ *
+ * Exercised through a real Hono request against the REAL exported handler, not
+ * asserted against source text — `proxy-is-not-behaviour`: a source grep proves
+ * a line exists, never that the endpoint answers 503. This test fails if anyone
+ * restores the flat `{status:"ok"}`, which is the regression it locks.
+ *
+ * THE MEASURED OUTAGE (2026-07-31, quiz-dev + sign-dev returning 503 to
+ * customers). `scala-activator` gates a cold wake on `isHealthy(port)` — a
+ * plain `GET /health` — then pipes the held client connection the moment it
+ * returns ok. `/health` answered ok as soon as the MINIMAL app served, but the
+ * phase-1 page handler returns 503 until the phase-2 swap, so the activator
+ * piped the customer's first request into that window:
+ *
+ *   05:58:25.446  activator: awake scala-quiz (4227ms)
+ *   05:58:25.452  scala-quiz: GET / 503 3ms      <- the customer's request
+ *   05:58:26.456  scala-quiz: Swapped from minimal app to full app
+ *
+ * Nine such 503s on scala-quiz, two on scala-sign, zero on scala-public — the
+ * gap is a race whose width is the phase-1→phase-2 build time (1420ms cold,
+ * 137ms warm), which is why one app looked healthy and the others did not.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { healthHandler, setPageHandler, getPageHandlerState } from "./two-phase-boot.ts";
+
+/** Mount the real handler exactly as buildMinimalApp does. */
+const app = new Hono().get("/health", healthHandler);
+
+/*
+ * Ordered, and deliberately so: `fullAppReady` is module state that only ever
+ * transitions false -> true (via setPageHandler at the phase-2 swap), so the
+ * pre-swap assertion has to run before the swap is simulated. There is no reset
+ * hook and adding one would exist only for tests.
+ */
+describe("/health is gated on page-serving readiness", () => {
+	test("before the phase-2 swap it reports 503, not ready", async () => {
+		expect(getPageHandlerState().ready).toBe(false);
+
+		const res = await app.request("/health");
+
+		// The activator treats any non-ok as "not awake yet" and keeps holding
+		// the client connection instead of piping it into a 503.
+		expect(res.status).toBe(503);
+		expect(res.ok).toBe(false);
+		expect(await res.json()).toEqual({ status: "starting" });
+		// Retry-After is the contract readiness-gated-boot specifies alongside
+		// the 503, so a caller backs off rather than hot-looping the wake.
+		expect(res.headers.get("Retry-After")).toBe("1");
+	});
+
+	test("after the phase-2 swap it reports 200 ok", async () => {
+		// Simulate the phase-2 swap: this is the real call ui-service.ts makes
+		// via buildFullApp, and it is what flips fullAppReady.
+		setPageHandler(() => async () => new Response("page"));
+		expect(getPageHandlerState().ready).toBe(true);
+
+		const res = await app.request("/health");
+
+		expect(res.status).toBe(200);
+		expect(res.ok).toBe(true);
+		expect(await res.json()).toEqual({ status: "ok" });
+	});
+});