@teamscala/service-boot 0.23.303 → 0.23.305

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.303",
+  "version": "0.23.305",
   "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/resolve-service-port.d.ts

@@ -16,11 +16,17 @@
  * The rule, and why it is not "env always wins":
  *
  * Railway injects PORT and healthchecks that exact port, reporting the service
- * unavailable if it listens elsewhere — so where there is NO routing row (a
- * Railway-only backend), the env is the only truth and must win.
+ * unavailable if it listens elsewhere. So on Railway the injected PORT is
+ * authoritative period — a `service_install`/`service_routing` row carries the
+ * service's LOCAL dev port (e.g. portal 5200), and on Railway binding that
+ * instead of PORT means Railway probes a port nothing listens on and the deploy
+ * fails healthcheck. The registry-wins rule below exists to stop LOCAL port
+ * collisions (one host, many services); inside a Railway container there are no
+ * sibling services to collide with, so PORT must win. `isRailway` is the caller's
+ * assertion that it is booting inside Railway (from `RAILWAY_ENVIRONMENT`).
  *
- * But a `service_routing` row means this service has a DECLARED port on this
- * host. There, a PORT that disagrees is a polluted launcher environment, never
+ * Off Railway, a `service_routing`/`service_install` row means this service has
+ * a DECLARED port on this host. There, a PORT that disagrees is a polluted launcher environment, never
  * an intention, and obeying it binds someone else's port. That is not a
  * hypothetical: mcp-ai-chat-system booted onto 3021 — session-picker's port —
  * while its own MCP_SERVER_URL still pointed at 8080. Both processes bound 3021,
@@ -60,7 +66,10 @@ export interface PortResolution {
  * @param envPort   parsed PORT env, or undefined when unset/unparseable
  * @param declaredPort `service_routing.local_port`, or undefined when the
  *                     service has no routing row (the Railway-only case)
+ * @param isRailway  true when booting inside Railway (caller derives from
+ *                   `RAILWAY_ENVIRONMENT`); there the injected PORT is authoritative
+ *                   regardless of the row, because Railway healthchecks it
  */
-export declare function resolveServicePort(envPort: number | undefined, declaredPort: number | undefined): PortResolution | {
+export declare function resolveServicePort(envPort: number | undefined, declaredPort: number | undefined, isRailway?: boolean): PortResolution | {
     error: "no-port-source";
 };

package/src/resolve-service-port.test.ts

@@ -95,4 +95,31 @@ describe("resolveServicePort", () => {
 			});
 		});
 	});
+
+	describe("Railway: injected PORT is authoritative over the row's dev port", () => {
+		// The 2026-07-31 portal incident: portal declares its dev port 5200 in
+		// service_install, Railway injects PORT=8080 and healthchecks 8080. The
+		// registry-wins rule (correct on the shared dev host) made portal bind 5200
+		// on Railway, so Railway's healthcheck probed a dead port and the deploy
+		// failed — despite the service booting healthy. On Railway PORT must win.
+		test("a conflicting declared port does NOT override Railway's injected PORT", () => {
+			expect(resolveServicePort(8080, 5200, true)).toEqual({ port: 8080, source: "env" });
+		});
+
+		test("an agreeing declared port still resolves to env on Railway", () => {
+			expect(resolveServicePort(8080, 8080, true)).toEqual({ port: 8080, source: "env" });
+		});
+
+		test("Railway with no injected PORT falls back to the declared port", () => {
+			expect(resolveServicePort(undefined, 5200, true)).toEqual({ port: 5200, source: "service_routing" });
+		});
+
+		test("isRailway defaults to false: off Railway the registry still wins a conflict", () => {
+			expect(resolveServicePort(8080, 5200)).toEqual({
+				port: 5200,
+				source: "service_routing",
+				conflict: { envPort: 8080, declaredPort: 5200 },
+			});
+		});
+	});
 });

package/src/resolve-service-port.ts

@@ -16,11 +16,17 @@
  * The rule, and why it is not "env always wins":
  *
  * Railway injects PORT and healthchecks that exact port, reporting the service
- * unavailable if it listens elsewhere — so where there is NO routing row (a
- * Railway-only backend), the env is the only truth and must win.
+ * unavailable if it listens elsewhere. So on Railway the injected PORT is
+ * authoritative period — a `service_install`/`service_routing` row carries the
+ * service's LOCAL dev port (e.g. portal 5200), and on Railway binding that
+ * instead of PORT means Railway probes a port nothing listens on and the deploy
+ * fails healthcheck. The registry-wins rule below exists to stop LOCAL port
+ * collisions (one host, many services); inside a Railway container there are no
+ * sibling services to collide with, so PORT must win. `isRailway` is the caller's
+ * assertion that it is booting inside Railway (from `RAILWAY_ENVIRONMENT`).
  *
- * But a `service_routing` row means this service has a DECLARED port on this
- * host. There, a PORT that disagrees is a polluted launcher environment, never
+ * Off Railway, a `service_routing`/`service_install` row means this service has
+ * a DECLARED port on this host. There, a PORT that disagrees is a polluted launcher environment, never
  * an intention, and obeying it binds someone else's port. That is not a
  * hypothetical: mcp-ai-chat-system booted onto 3021 — session-picker's port —
  * while its own MCP_SERVER_URL still pointed at 8080. Both processes bound 3021,
@@ -63,14 +69,26 @@ function isBindablePort(value: number | undefined): value is number {
  * @param envPort   parsed PORT env, or undefined when unset/unparseable
  * @param declaredPort `service_routing.local_port`, or undefined when the
  *                     service has no routing row (the Railway-only case)
+ * @param isRailway  true when booting inside Railway (caller derives from
+ *                   `RAILWAY_ENVIRONMENT`); there the injected PORT is authoritative
+ *                   regardless of the row, because Railway healthchecks it
  */
 export function resolveServicePort(
 	envPort: number | undefined,
 	declaredPort: number | undefined,
+	isRailway = false,
 ): PortResolution | { error: "no-port-source" } {
 	const envUsable = isBindablePort(envPort);
 	const declaredUsable = isBindablePort(declaredPort);
 
+	// On Railway the injected PORT is authoritative: Railway healthchecks that
+	// exact port, and the declared port is the service's LOCAL dev port — binding
+	// it makes the healthcheck probe a port nothing listens on. There are no
+	// sibling services to collide with inside a container, so PORT wins.
+	if (isRailway && envUsable) {
+		return { port: envPort, source: "env" };
+	}
+
 	// No routing row: Railway's injected PORT is the only truth available.
 	if (!declaredUsable) {
 		return envUsable ? { port: envPort, source: "env" } : { error: "no-port-source" };

package/src/ui-service.ts

@@ -74,9 +74,13 @@ export async function bootUiService(
 	//
 	// This branch previously took `process.env.PORT` unconditionally, which is
 	// how scala-quiz (declared 5203) booted onto session-picker's 3021 from a
-	// leaked env and silently split that daemon's traffic (2026-07-31). Railway
-	// is unaffected by construction: it injects PORT and a Railway-only service
-	// has no declared port, so the env still wins there.
+	// leaked env and silently split that daemon's traffic (2026-07-31). On the
+	// dev host the registry wins a conflict (below). On Railway the injected PORT
+	// wins instead — Railway healthchecks exactly that port, and the row's port
+	// is the service's LOCAL dev port (e.g. portal 5200), so binding it on Railway
+	// makes the healthcheck probe a dead port and the deploy fails (`isRailway`
+	// path in the resolver).
+	const isRailway = Boolean(process.env.RAILWAY_ENVIRONMENT);
 	const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
 	// The APP binds its PRIVATE port (app_port) when present — for scale-to-zero
 	// services `port` is the ACTIVATOR's ingress (what callers resolve), not the
@@ -85,7 +89,7 @@ export async function bootUiService(
 	// bind the activator's port → SO_REUSEPORT silent load-balancing (the
 	// service-ports-from-registry trap: clean boot, two owners in ss -ltnp).
 	const declaredAppPort = config.app_port ?? config.port;
-	const resolution = resolveServicePort(envPort, declaredAppPort);
+	const resolution = resolveServicePort(envPort, declaredAppPort, isRailway);
 	if ("error" in resolution) {
 		throw new BootFatalError(
 			"ui-service.port-resolution",