@teamscala/service-boot 0.23.322 → 0.23.324

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

@@ -0,0 +1,82 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lane-close write-through for task-sync. The session-owning fleet runtime
+ * calls this ORPC procedure before releasing an ACP lane, so work_items remains
+ * the durable lifecycle source without a second raw-SQL writer in the host.
+ */
+
+import { ORPCError } from "@orpc/server";
+import * as v from "valibot";
+import { authed, type Context } from "./auth-router.ts";
+import type { Prisma, WorkItem } from "./task-sync-router.ts";
+
+export const closeLaneInput = v.object({
+	lane_session: v.pipe(v.string(), v.minLength(1, "lane_session is required")),
+	disposition: v.picklist([
+		"completed",
+		"needs_retry",
+		"failed",
+		"orchestrator_closed",
+		"orphaned",
+	]),
+});
+
+export interface ClosedTaskState {
+	task_id: string;
+	task_status: "done" | "archived";
+	completed: boolean;
+	kind_data: Record<string, unknown>;
+}
+
+export function closedTaskState(
+	task: Pick<WorkItem, "id" | "kind_data">,
+	disposition: v.InferOutput<typeof closeLaneInput>["disposition"],
+): ClosedTaskState {
+	const completed = disposition === "completed";
+	const lane =
+		task.kind_data.lane && typeof task.kind_data.lane === "object"
+			? (task.kind_data.lane as Record<string, unknown>)
+			: {};
+	return {
+		task_id: task.id,
+		task_status: completed ? "done" : "archived",
+		completed,
+		kind_data: { ...task.kind_data, lane: { ...lane, live: false } },
+	};
+}
+
+export const closeLaneHandler = authed
+	.input(closeLaneInput)
+	.handler(async ({ input, context }) => {
+		const prisma = (context as Context).prisma as Prisma;
+		const task = await prisma.work_items.findFirst({
+			where: {
+				kind: "task",
+				kind_data: { path: ["lane", "session"], equals: input.lane_session },
+			},
+			orderBy: { created_at: "desc" },
+		});
+		if (!task) {
+			throw new ORPCError("NOT_FOUND", {
+				message: `No task is bound to ACP lane ${input.lane_session}`,
+			});
+		}
+		const state = closedTaskState(task, input.disposition);
+		await prisma.work_items.update({
+			where: { id: task.id },
+			data: {
+				kind_data: state.kind_data,
+				status: state.task_status,
+				completed: state.completed,
+			},
+			select: { id: true },
+		});
+		return {
+			task_id: state.task_id,
+			task_status: state.task_status,
+			reconciled: true,
+		};
+	});

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

@@ -3,42 +3,60 @@
  * @status handwritten
  * @edit edit directly
  *
- * Unit tests for the pure event-payload builder in task-sync-dispatch. The HTTP
- * POST + registry resolution are side-effectful (covered end-to-end by the
- * DB->AGENT direction demo — a published orchestrator.message with slotName
- * cross-pane delivers to the target pane's <channel> tag); buildTaskChangedEvent
- * is pure and tested here. Satisfies what-must-have-a-test / primitive-api-has-test.
+ * Unit tests for the pure durable comment-payload builder in task-sync-dispatch.
+ * The runtime path writes this payload through the canonical comments model.
  */
 import { describe, it, expect } from "bun:test";
-import { buildTaskChangedEvent } from "./task-sync-dispatch.ts";
+import { buildTaskChangeComment, notifyLaneOfTaskChange } from "./task-sync-dispatch.ts";
 
-describe("task-sync buildTaskChangedEvent", () => {
-	it("is an orchestrator.message addressed to the owning lane pane", () => {
-		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
-		expect(e.type).toBe("orchestrator.message");
-		expect(e.orchestratorSessionId).toBe("tmux:%5");
-	});
-
-	it("uses slotName cross-pane so watchEvents bypasses the fleet-run-existence check", () => {
-		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
-		expect(e.slotName).toBe("cross-pane");
-	});
+	describe("task-sync buildTaskChangeComment", () => {
+		it("addresses the canonical task and runtime with no pane transport", () => {
+			const comment = buildTaskChangeComment("task-7", "session-5", "subtask-1:completed");
+			expect(comment).toMatchObject({
+				work_item_id: "task-7",
+				source_cli_session_id: "session-5",
+				sender_role: "system",
+				sender_name: "TaskSync",
+			});
+			expect(comment.system_key).toBe("task-sync:task-7:session-5:subtask-1:completed");
+			expect(comment.content).toContain("readTaskList");
+			expect(comment).not.toHaveProperty("pane");
+		});
 
-	it("carries the task id in the message so the recipient can re-read just it", () => {
-		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
-		expect(e.message).toContain("task-7");
-		expect(e.message).toContain("readTaskList");
-	});
-
-	it("produces a single-line message (the <channel> tag renders it inline)", () => {
-		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
-		expect(e.message.includes("\n")).toBe(false);
-	});
+		it("writes one durable comment addressed by the active cli_session", async () => {
+			const calls: unknown[] = [];
+			const result = await notifyLaneOfTaskChange(
+				{
+					cli_sessions: { findFirst: async () => ({ id: "session-5" }) },
+					comments: {
+						upsert: async (args) => {
+							calls.push(args);
+							return { id: "comment-1" };
+						},
+					},
+				},
+				"task-7",
+				"subtask-1:completed",
+			);
+			expect(result).toMatchObject({ delivered: true, sessionId: "session-5", commentId: "comment-1" });
+			expect(calls[0]).toMatchObject({ create: { work_item_id: "task-7", source_cli_session_id: "session-5" } });
+		});
 
-	it("stamps the system sender + a deterministic runId + the provided epoch-ms ts", () => {
-		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
-		expect(e.fromOrchestratorId).toBe("task-sync");
-		expect(e.runId).toBe("task-sync-task-7-1700000000000");
-		expect(e.ts).toBe(1700000000000);
+		it("does not fabricate a pre-launch session or comment", async () => {
+			let writes = 0;
+			const result = await notifyLaneOfTaskChange(
+				{
+					cli_sessions: { findFirst: async () => null },
+					comments: {
+						upsert: async () => {
+							writes++;
+							return { id: "unexpected" };
+						},
+					},
+				},
+				"task-7",
+			);
+			expect(result).toEqual({ delivered: false, sessionId: null, commentId: null });
+			expect(writes).toBe(0);
+		});
 	});
-});

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

@@ -0,0 +1,36 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Behavioral tests for canonical CLI-session lane resolution.
+ */
+import { describe, expect, it } from "bun:test";
+import { resolveLaneWorkName } from "./task-sync-lane.ts";
+
+describe("resolveLaneWorkName", () => {
+	it("reads the visible label from the active cli_sessions route", async () => {
+		let query: unknown;
+		const name = await resolveLaneWorkName(
+			{
+				cli_sessions: {
+					findFirst: async (args: unknown) => {
+						query = args;
+						return { id: "session-1", label: "ZeroStack" };
+					},
+				},
+			} as never,
+			"tmux:%7",
+		);
+		expect(name).toBe("ZeroStack");
+		expect(query).toMatchObject({ where: { host_route: { path: ["pane_id"], equals: "tmux:%7" } } });
+	});
+
+	it("returns no unverified title when no active session owns the pane", async () => {
+		const name = await resolveLaneWorkName(
+			{ cli_sessions: { findFirst: async () => null } } as never,
+			"tmux:%8",
+		);
+		expect(name).toBeNull();
+	});
+});

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

@@ -12,6 +12,7 @@
 import { describe, expect, it } from "bun:test";
 import {
 	STATUS_TO_WORK_ITEM,
+	deriveEvidenceProgress,
 	normalizeStatus,
 	planReconcile,
 	resolveProjectedStatus,
@@ -29,6 +30,31 @@ describe("STATUS_TO_WORK_ITEM", () => {
 	});
 });
 
+describe("evidence-derived task progress", () => {
+	it("counts only required subtasks with independent Orchestrator acceptance", () => {
+		const out = deriveEvidenceProgress(
+			[
+				{ id: "a", status: "done" },
+				{ id: "b", status: "done" },
+				{ id: "c", status: "todo", kind_data: { pm_progress: { required: false } } },
+			],
+			[
+				{ work_item_id: "a", sender_role: "orchestrator", system_key: "acceptance:a" },
+				{ work_item_id: "b", sender_role: "worker", system_key: "acceptance:b" },
+			],
+		);
+		expect(out).toEqual({ total: 2, accepted: 1, percentage: 50 });
+	});
+
+	it("does not treat prose, context, or done alone as evidence", () => {
+		expect(
+			deriveEvidenceProgress([{ id: "a", status: "done" }], [
+				{ work_item_id: "a", sender_role: "orchestrator", system_key: "progress:100" },
+			]),
+		).toEqual({ total: 1, accepted: 0, percentage: 0 });
+	});
+});
+
 describe("status translation is a single non-drifting source", () => {
 	// The forward map (CLI → work_items) is canonical; the reverse is DERIVED from
 	// it (+ a closed synonym set). This locks the structural fix: the two

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

@@ -74,6 +74,57 @@ export function normalizeStatus(s: string | null): TaskListItem["status"] {
 	return (s && WORK_ITEM_TO_STATUS[s]) || "pending";
 }
 
+export interface ProgressSubtask {
+	id: string;
+	status: string | null;
+	kind_data?: Record<string, unknown> | null;
+}
+
+export interface ProgressAcceptanceEvidence {
+	work_item_id: string | null;
+	sender_role: string | null;
+	system_key: string | null;
+}
+
+export interface EvidenceProgress {
+	total: number;
+	accepted: number;
+	percentage: number;
+}
+
+/**
+ * Derive progress from the canonical checklist and independent acceptance
+ * comments. A done status without an Orchestrator acceptance comment is not
+ * evidence of completion; prose percentages and context gauges never enter
+ * this calculation. Subtasks are required by default, with an explicit
+ * `kind_data.pm_progress.required: false` opt-out for non-gating notes.
+ */
+export function deriveEvidenceProgress(
+	subtasks: ProgressSubtask[],
+	evidence: ProgressAcceptanceEvidence[],
+): EvidenceProgress {
+	const required = subtasks.filter(
+		(s) => (s.kind_data?.pm_progress as { required?: boolean } | undefined)?.required !== false,
+	);
+	const accepted = new Set(
+		evidence
+			.filter(
+				(e) =>
+					e.sender_role === "orchestrator" &&
+					typeof e.system_key === "string" &&
+					e.system_key.startsWith("acceptance:") &&
+					e.work_item_id,
+			)
+			.map((e) => e.work_item_id as string),
+	);
+	const acceptedCount = required.filter((s) => s.status === "done" && accepted.has(s.id)).length;
+	return {
+		total: required.length,
+		accepted: acceptedCount,
+		percentage: required.length === 0 ? 0 : Math.round((acceptedCount / required.length) * 100),
+	};
+}
+
 /**
  * Decide the status to WRITE for an existing row, given what the CLI list says.
  *

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

@@ -0,0 +1,53 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit directly
+ *
+ * Unit tests for the rename back-write leg: renameOutcome (the pure
+ * no-task ⇒ not-updated decision) + source-contract assertions that the handler
+ * resolves the lane task BY SESSION (never pane) and updates its title. Covers
+ * `what-must-have-a-test` for the new procedure + the `lane-identity-is-cli-
+ * session-id` invariant it rides on.
+ */
+import { describe, it, expect } from "bun:test";
+import { renameOutcome } from "./task-sync-rename.ts";
+
+describe("renameOutcome (no verdict from no data)", () => {
+	it("returns not-updated with a null task_id when no task is bound to the session", () => {
+		// A rename of a tab whose lane has no resolvable task updates nothing —
+		// never an error, never a fake id. updated:false is the signal the caller
+		// treats as best-effort (the window was already renamed; this only missed
+		// the DB echo, which is the rare archived-and-pruned case).
+		expect(renameOutcome(null)).toEqual({ task_id: null, updated: false });
+	});
+
+	it("returns the bound task id + updated:true when a task resolves", () => {
+		expect(renameOutcome({ id: "task-9" })).toEqual({ task_id: "task-9", updated: true });
+	});
+});
+
+describe("renameLaneTask resolves BY SESSION and writes the title (source contract)", () => {
+	const renameSrc = Bun.file(new URL("./task-sync-rename.ts", import.meta.url).pathname);
+
+	it("resolves the lane task by lane_session (the CLI session id), never by pane", async () => {
+		// `lane-identity-is-cli-session-id`: binding is by session because a pane
+		// outlives the session inside it. A pane-keyed rename would let a dead
+		// session's task answer for a live lane.
+		const text = await renameSrc.text();
+		expect(text).toContain("resolveLaneTask(prisma, lane_session)");
+		// No pane matching anywhere in the resolution path.
+		expect(text).not.toContain("lane.pane");
+	});
+
+	it("updates the resolved task's title by id", async () => {
+		const text = await renameSrc.text();
+		expect(text).toContain('where: { id: task.id }');
+		expect(text).toContain("data: { title }");
+	});
+
+	it("requires lane_session + title at the signature (incomplete rename unconstructible)", async () => {
+		const text = await renameSrc.text();
+		expect(text).toContain('lane_session: v.pipe(v.string()');
+		expect(text).toContain('title: v.pipe(v.string()');
+	});
+});

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

@@ -0,0 +1,111 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lane RENAME back-write for task-sync: a tab rename EMITS to update the bound
+ * work_items task's title in the DB, by CLI session id. This is the DB half of
+ * `tab-rename-emits-back-to-task-title`: the operator's tab bar is how they see
+ * what is being worked on (`lane-labels-and-task-lists`), so the tmux window
+ * name and the task title must never diverge silently. Renaming a tab from
+ * `scala-tools session rename` (or the lane renaming itself through the same
+ * surface) updates the task title so the project board agrees with the tab bar.
+ *
+ * THE EMISSION, not a poll (`actions-are-rows-then-emissions`): a caller renames
+ * the window (a row/state change) and that change emits the title update — the
+ * task-sync owner reacts by updating the row. State lives in the row, never in a
+ * return value a caller may never receive.
+ *
+ * Bound by CLI SESSION ID, never pane id (`lane-identity-is-cli-session-id`): a
+ * pane OUTLIVES the session inside it, so matching on a pane would let a dead
+ * session's task answer for a live lane. The session is the stable identity a
+ * rename resolves to (the daemon resolves the pane's tab → its stored session id
+ * and passes that here), so the rename lands on the lane that owns the tab.
+ *
+ * Split out of task-sync-router.ts for the same reason task-sync-brief/lane/
+ * assign exist: the router sits at its 1000-line commit gate, so every cohesive
+ * task-sync unit that can live in a sibling does. This owns the rename handler +
+ * its pure outcome decision.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Bound to the work_items schema and to task-sync's own
+ * kind_data.lane.session convention; no unrelated app could install this
+ * unmodified.
+ */
+
+import * as v from "valibot";
+import type { Prisma } from "./task-sync-router.ts";
+import { authed, type Context } from "./auth-router.ts";
+import { resolveLaneTask } from "./task-sync-lane.ts";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+/**
+ * renameLaneTask ORPC input. `lane_session` is the lane's CLI-native session id
+ * (kind_data.lane.session) — the stable identity a pane rename resolves to.
+ * `title` is the new task title (the renamed tab's label). Both required:
+ * oRPC rejects a call missing either at the signature
+ * (`prevention-over-detection`), so a malformed rename is a 400, never a silent
+ * no-op that leaves the title stale.
+ */
+export const renameLaneTaskInput = v.object({
+	lane_session: v.pipe(v.string(), v.minLength(1, "lane_session is required")),
+	title: v.pipe(v.string(), v.minLength(1, "title is required")),
+});
+
+/**
+ * The rename outcome from a resolved lane task — pure so the "no task bound ⇒
+ * not updated, never an error" decision is unit-testable with no DB. A rename
+ * whose lane has no task is best-effort (returns updated:false): every spawn
+ * now mints a task, so this is the rare case (a tab whose task was archived and
+ * pruned), not a path the operator hits. Failing loudly here would refuse a
+ * rename of the WINDOW for a DB miss, which couples two surfaces that must not
+ * be — the tmux rename already succeeded before this is called.
+ */
+export function renameOutcome(task: { id: string } | null): {
+	task_id: string | null;
+	updated: boolean;
+} {
+	if (!task) return { task_id: null, updated: false };
+	return { task_id: task.id, updated: true };
+}
+
+/**
+ * renameLaneTask ORPC handler. The session-picker daemon calls this from
+ * `/rpc/rename` after it renames the tmux window: it resolves the pane's tab to
+ * its session id and posts it here. Same transport as bindLane/readTaskList:
+ * page-gate-exempt (fn.taskSync), localhost super-admin. Resolves the lane's
+ * task BY SESSION (never pane) and updates its title. Idempotent: renaming to
+ * the same title writes the same row.
+ *
+ * An archived parent is matched too (resolveLaneTask falls back to the archived
+ * lane task for the session), so a rename of a tab whose run closed still lands
+ * on its task — the title is the title regardless of run state.
+ */
+export const renameLaneTaskHandler = authed
+	.input(renameLaneTaskInput)
+	.handler(async ({ input, context }) => {
+		const ctx = context as Context;
+		const prisma = ctx.prisma as Prisma;
+		const { lane_session, title } = input;
+		const task = await resolveLaneTask(prisma, lane_session);
+		const outcome = renameOutcome(task);
+		if (!task) return outcome;
+		try {
+			await prisma.work_items.update({
+				where: { id: task.id },
+				data: { title },
+				select: { id: true },
+			});
+		} catch (err) {
+			// The window was already renamed by the caller; a DB update failure must
+			// not surface as an error that implies the rename failed. Report
+			// not-updated + log, so the two surfaces stay decoupled
+			// (`a-component-may-not-report-a-state-it-has-not-verified`).
+			getAppLogger().warn("[task-sync] renameLaneTask: title update failed", {
+				taskId: task.id,
+				error: err instanceof Error ? err.message : String(err),
+			});
+			return { task_id: task.id, updated: false };
+		}
+		return outcome;
+	});

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

@@ -337,8 +337,20 @@ describe("a blocked row survives a CLI list that cannot express it", () => {
 	it("planReconcile leaves a blocked subtask blocked when the list says pending", () => {
 		// The end-to-end shape: this is what re-blocked the lane three times.
 		const plan = planReconcile(
-			[{ mark: "1", content: "Deploy the fix", status: "pending" }],
-			[{ id: "row-1", title: "Deploy the fix", status: "blocked", completed: false, position: "0", kind_data: { task_sync: { mark: "1" } } }] as never,
+			[
+				{
+					id: "row-1",
+					kind: "subtask",
+					parent_id: "task-1",
+					organisation_id: "org-1",
+					title: "Deploy the fix",
+					status: "blocked",
+					position: "0",
+					completed: false,
+					kind_data: { task_sync: { mark: "1" } },
+				},
+			],
+			[{ content: "Deploy the fix", status: "pending" }],
 			"claude-code",
 		);
 		const update = plan.toUpdate.find((u) => u.id === "row-1");

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({