@teamscala/service-boot 0.23.430 → 0.23.432

package/src/fn-routers/work-items-router.ts

@@ -15,6 +15,27 @@
  * behaviour the board wants.
  */
 
+	/**
+	 * Org-scoped member list for the task-comments panel — @mention matching AND
+	 * comment-sender display (name + avatar). ChatPanel.tsx has no
+	 * serverLoader/orgId prop (client-only overlay content), so it can't do the
+	 * SSR raw-SQL org-scope join load-project-list-view.ts uses; this exposes
+	 * the same result via a custom procedure instead of widening service_schema
+	 * to the raw better_auth_member table.
+	 *
+	 * This is the SINGLE source of member display info for the comments panel:
+	 * it coalesces BOTH name/email/avatar families on the user model into one
+	 * shape (the `full_name`/`primary_email`/`avatar_url` family AND the
+	 * better-auth `name`/`email`/`image` family). Returning avatar here lets the
+	 * client resolve sender name+avatar from this one list and drop the separate
+	 * `user.findMany` enrichment fetch it previously ran as a second waterfall
+	 * hop after `comments.findMany` (loading-shape: one wave-parallel hit, not a
+	 * dependent client-side round-trip chain).
+	 */
+
+// Why: Org-scoped member list for the task-comments panel — @mentio…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { createEmailClient } from "@teamscala/email-client/client";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { authed, type Context } from "./auth-router.ts";
@@ -227,23 +248,6 @@ export const workItemsRouter = {
 			return { notified: 0 };
 		}
 	}),
-	/**
-	 * Org-scoped member list for the task-comments panel — @mention matching AND
-	 * comment-sender display (name + avatar). ChatPanel.tsx has no
-	 * serverLoader/orgId prop (client-only overlay content), so it can't do the
-	 * SSR raw-SQL org-scope join load-project-list-view.ts uses; this exposes
-	 * the same result via a custom procedure instead of widening service_schema
-	 * to the raw better_auth_member table.
-	 *
-	 * This is the SINGLE source of member display info for the comments panel:
-	 * it coalesces BOTH name/email/avatar families on the user model into one
-	 * shape (the `full_name`/`primary_email`/`avatar_url` family AND the
-	 * better-auth `name`/`email`/`image` family). Returning avatar here lets the
-	 * client resolve sender name+avatar from this one list and drop the separate
-	 * `user.findMany` enrichment fetch it previously ran as a second waterfall
-	 * hop after `comments.findMany` (loading-shape: one wave-parallel hit, not a
-	 * dependent client-side round-trip chain).
-	 */
 	orgMembers: authed.handler(async ({ input, context }) => {
 		const { orgId } = input as { orgId: string };
 		const prisma = (context as Context).prisma as {

package/src/handlers/platform-fault-escalation/delivery.ts

@@ -72,6 +72,12 @@ export async function deliverEscalation(
 			last_seen_at: aggregate.lastSeen.toISOString(),
 			event_count: aggregate.count,
 			resolved_at: null,
+			// CLEARING THIS IS WHAT STOPS AN ESCALATION STORM. A re-armed row
+			// keeps resolved_at NULL, so it still loads as open, and
+			// `escalate` fires for any episode that is resolved OR re-armed.
+			// Leaving rearmed_at set would therefore re-escalate the same kind
+			// on EVERY sweep — the firing state must be consumed by the firing.
+			rearmed_at: null,
 		},
 	});
 
@@ -165,6 +171,36 @@ export async function deliverEscalation(
 	return { messageId, workItemId: config.orchestrator_work_item_id };
 }
 
+/**
+ * Re-arm an episode whose kind went quiet but whose condition NOBODY CHECKED.
+ * The alarm becomes audible again and no claim is made that the fault
+ * stopped, so there is deliberately NO operator comment: "Fault stopped" on
+ * the strength of silence is the sentence this change exists to stop writing.
+ * The event is still recorded — re-arming is a state change. See migration 811.
+ */
+export async function rearmEpisode(
+	episode: EscalationEpisode,
+	quietMinutes: number,
+): Promise<void> {
+	const now = new Date();
+	await (await orpc()).platform_fault_escalations.update({
+		where: { kind: episode.kind },
+		data: { rearmed_at: now.toISOString(), updated_at: now.toISOString() },
+	});
+	recordEvent({
+		kind: "platform.fault.rearmed",
+		payload: {
+			event_kind: episode.kind,
+			quiet_minutes: Math.round(quietMinutes),
+			work_item_id: episode.workItemId,
+			// Named so a reader never mistakes this for a resolution: no probe
+			// exists for this kind, so nothing verified the condition ended.
+			verified: false,
+			reason: "no capability probe declared for this kind",
+		},
+	});
+}
+
 export async function resolveEpisode(
 	episode: EscalationEpisode,
 	quietMinutes: number,

package/src/handlers/platform-fault-escalation/orpc-client.ts

@@ -11,20 +11,6 @@
  * byte-for-byte move; import paths adjusted only.
  */
 
-import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
-import * as v from "valibot";
-
-let cachedSystemIdentity: { userId: string | undefined; organisationId: string | undefined } | undefined;
-export async function getSystemIdentity(): Promise<{ userId: string | undefined; organisationId: string | undefined }> {
-	if (cachedSystemIdentity) return cachedSystemIdentity;
-	const row = await loadRegistryConfig("config", "system-identity", v.looseObject({}));
-	cachedSystemIdentity = {
-		userId: row?.system_user_id as string | undefined,
-		organisationId: row?.system_org_id as string | undefined,
-	};
-	return cachedSystemIdentity;
-}
-
 /**
  * The system-authed in-process ORPC client, built LAZILY on first use from the
  * SAME composed appRouter the /api/rpc mount uses (getAppRouter — never a raw
@@ -40,9 +26,42 @@ export async function getSystemIdentity(): Promise<{ userId: string | undefined;
  * the assigned-client form with $queryRawUnsafe. Timestamps are ISO strings,
  * never Date instances (the generated valibot schemas require it).
  */
-let cachedOrpc: OrpcSurface | null = null;
+
+// Why: The system-authed in-process ORPC client, built LAZILY on fi…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+import { createCache } from "@teamscala/cache/create-cache";
+
+const systemIdentityCache = createCache<{
+	userId: string | undefined;
+	organisationId: string | undefined;
+}>("service-boot:fault-escalation-system-identity", {
+	ttlMs: Number.POSITIVE_INFINITY,
+	maxSize: 1,
+});
+
+export async function getSystemIdentity(): Promise<{ userId: string | undefined; organisationId: string | undefined }> {
+	const hit = systemIdentityCache.get("default");
+	if (hit) return hit;
+	const row = await loadRegistryConfig("config", "system-identity", v.looseObject({}));
+	const identity = {
+		userId: row?.system_user_id as string | undefined,
+		organisationId: row?.system_org_id as string | undefined,
+	};
+	systemIdentityCache.set("default", identity);
+	return identity;
+}
+
+const orpcSurfaceCache = createCache<OrpcSurface>(
+	"service-boot:fault-escalation-orpc",
+	{ ttlMs: Number.POSITIVE_INFINITY, maxSize: 1 },
+);
+
 export async function orpc(): Promise<OrpcSurface> {
-	if (cachedOrpc) return cachedOrpc;
+	const hit = orpcSurfaceCache.get("default");
+	if (hit) return hit;
 	const { createRouterClient } = await import("@orpc/server");
 	const { getAppRouter } = await import("@teamscala/orpc/app-router");
 	const appRouter = (await getAppRouter()) as Record<string, unknown> | null;
@@ -61,7 +80,7 @@ export async function orpc(): Promise<OrpcSurface> {
 		"platform-identity",
 		PlatformIdentitySchema,
 	);
-	cachedOrpc = createRouterClient(
+	const surface = createRouterClient(
 		{ ...appRouter } as never,
 		{
 			context: {
@@ -74,7 +93,8 @@ export async function orpc(): Promise<OrpcSurface> {
 			},
 		} as never,
 	) as unknown as OrpcSurface;
-	return cachedOrpc;
+	orpcSurfaceCache.set("default", surface);
+	return surface;
 }
 
 /** The router subset this handler uses — mirrors the generated procedure args. */

package/src/handlers/platform-fault-escalation-logic.ts

@@ -26,7 +26,13 @@ export interface EscalationEpisode {
 	eventCount: number;
 	escalatedAt: Date | null;
 	workItemId: string | null;
+	/** VERIFIED over — a capability probe answered OK, or a declared recovery
+	 * transition arrived. Never written from silence. */
 	resolvedAt: Date | null;
+	/** The kind went quiet and the alarm is ARMED AGAIN. This is all that
+	 * quiet ever honestly supported, and it is deliberately weaker than
+	 * `resolvedAt`: it claims nothing about the condition. */
+	rearmedAt: Date | null;
 	lastUpdatedAt: Date | null;
 	deliveredCommentId?: string | null;
 }
@@ -51,8 +57,18 @@ export interface KindThresholdOverride {
 export interface SweepDecision {
 	/** Sustained faults needing a FIRST delivery (new episode, or a claim whose send failed). */
 	escalate: Array<{ aggregate: FaultAggregate; episode: EscalationEpisode | null }>;
-	/** Open episodes whose kind went quiet past the resolve window — close them. */
+	/** Open episodes whose kind went quiet past the resolve window — close them.
+	 * ONLY reachable from the probe gate: quiet alone never populates this. */
 	resolve: Array<{ episode: EscalationEpisode; quietMinutes: number; clearZeroVolumeFlag: boolean }>;
+	/** Open episodes quiet past the resolve window whose kind declares NO
+	 * capability probe: the alarm is RE-ARMED (the next occurrence escalates
+	 * again) and nothing is claimed about the condition. Quiet used to write
+	 * `resolved_at` and post "Fault stopped", which is the unsound close
+	 * `emit-transitions-not-conditions` names. It is re-armed rather than
+	 * merely held open because `escalate` fires only for an absent, resolved
+	 * or re-armed episode — holding it open would silence the alarm for good.
+	 * Rationale + measurements: migration 811. */
+	rearm: Array<{ episode: EscalationEpisode; quietMinutes: number; clearZeroVolumeFlag: boolean }>;
 	/** Open episodes quiet past the resolve window whose producer ALSO went
 	 * silent: zero failure rows AND zero call volume that would produce them.
 	 * Quiet is NOT evidence of health here (measured 2026-08-27: llm-router
@@ -150,14 +166,17 @@ export function decideSweep(
 	const byKind = new Map(episodes.map((e) => [e.kind, e]));
 	const aggregateByKind = new Map(aggregates.map((a) => [a.kind, a]));
 	const decision: SweepDecision =
-		{ escalate: [], resolve: [], resolveProbeGate: [], zeroVolumeHold: [] };
+		{ escalate: [], resolve: [], rearm: [], resolveProbeGate: [], zeroVolumeHold: [] };
 
 	for (const aggregate of aggregates) {
 		const episode = byKind.get(aggregate.kind);
 		if (!isSustained(aggregate, policy, kindThresholds[aggregate.kind], now)) continue;
 		// No episode, or the previous episode closed (quiet past resolve window):
 		// a NEW episode begins and must be delivered.
-		if (!episode || episode.resolvedAt) {
+		// A RE-ARMED episode starts a new one exactly as a resolved one does.
+		// This is the half that keeps the alarm audible: without it, dropping
+		// the quiet-close would leave every probe-less kind permanently silent.
+		if (!episode || episode.resolvedAt || episode.rearmedAt) {
 			decision.escalate.push({ aggregate, episode: episode ?? null });
 			continue;
 		}
@@ -174,7 +193,7 @@ export function decideSweep(
 	}
 
 	for (const episode of episodes) {
-		if (episode.resolvedAt) continue;
+		if (episode.resolvedAt || episode.rearmedAt) continue;
 		const aggregate = aggregateByKind.get(episode.kind);
 		// A future-dated aggregate lastSeen (producer clock skew) cannot serve
 		// as the quiet reference — it would freeze quietMinutes negative and
@@ -218,7 +237,9 @@ export function decideSweep(
 			});
 			continue;
 		}
-		decision.resolve.push({
+		// NO PROBE DECLARED: re-arm, never resolve. Quiet re-arms the alarm and
+		// says nothing about the condition — see the `rearm` field's comment.
+		decision.rearm.push({
 			episode,
 			quietMinutes,
 			clearZeroVolumeFlag: Boolean(source && zeroVolume?.flagActiveByKind[episode.kind]),

package/src/handlers/platform-fault-escalation.test.ts

@@ -44,6 +44,7 @@ function episode(overrides: Partial<EscalationEpisode> & { kind: string }): Esca
 		escalatedAt: new Date(NOW.getTime() - 60 * 60_000),
 		workItemId: "wi-1",
 		resolvedAt: null,
+		rearmedAt: null,
 		lastUpdatedAt: null,
 		...overrides,
 	};
@@ -117,6 +118,7 @@ describe("decideSweep — dedup (one escalation per fault, no re-fire)", () => {
 		expect(decision.resolve).toHaveLength(0);
 		expect(Object.keys(decision).sort()).toEqual([
 			"escalate",
+			"rearm",
 			"resolve",
 			"resolveProbeGate",
 			"zeroVolumeHold",
@@ -133,17 +135,60 @@ describe("decideSweep — dedup (one escalation per fault, no re-fire)", () => {
 });
 
 describe("decideSweep — resolution + re-arm", () => {
-	test("quiet past the resolve window closes the episode", () => {
+	// QUIET RE-ARMS, IT DOES NOT RESOLVE. These two asserted `resolve` until
+	// 2026-08-29, which is the unsound close: only a probe can say a condition
+	// ended, and no probe is declared for these kinds.
+	test("quiet past the resolve window RE-ARMS the episode, and claims nothing", () => {
 		const gone = episode({ kind: "wake.failed", lastSeenAt: new Date(NOW.getTime() - 60 * 60_000) });
 		const decision = decideSweep([], [gone], POLICY, NOW);
-		expect(decision.resolve).toHaveLength(1);
-		expect(decision.resolve[0]!.quietMinutes).toBeGreaterThanOrEqual(30);
+		expect(decision.rearm).toHaveLength(1);
+		expect(decision.rearm[0]!.quietMinutes).toBeGreaterThanOrEqual(30);
+		expect(decision.resolve).toHaveLength(0);
 	});
 
-	test("an absent kind resolves by its episode's last_seen, not the sweep clock", () => {
+	test("an absent kind re-arms by its episode's last_seen, not the sweep clock", () => {
 		const gone = episode({ kind: "listen.connect_failed", lastSeenAt: new Date(NOW.getTime() - 45 * 60_000) });
 		const decision = decideSweep([], [gone], POLICY, NOW);
-		expect(decision.resolve).toHaveLength(1);
+		expect(decision.rearm).toHaveLength(1);
+		expect(decision.resolve).toHaveLength(0);
+	});
+
+	// THE INVARIANT THAT MAKES RE-ARMING SAFE. If a re-armed episode did not
+	// escalate again, dropping the quiet-close would have left every
+	// probe-less alarm permanently silent — worse than the false close.
+	test("a RE-ARMED episode escalates again when its fault recurs", () => {
+		const recurring = agg("guard.fail.open", 50, 40, 0);
+		const rearmed = episode({
+			kind: "guard.fail.open",
+			rearmedAt: new Date(NOW.getTime() - 35 * 60_000),
+		});
+		const decision = decideSweep([recurring], [rearmed], POLICY, NOW);
+		expect(decision.escalate).toHaveLength(1);
+	});
+
+	// A re-armed episode is already armed; re-arming it every sweep would emit
+	// a transition per sweep, which is the repeating-condition shape itself.
+	test("an already re-armed episode is not re-armed again while it stays quiet", () => {
+		const rearmed = episode({
+			kind: "guard.fail.open",
+			lastSeenAt: new Date(NOW.getTime() - 60 * 60_000),
+			rearmedAt: new Date(NOW.getTime() - 35 * 60_000),
+		});
+		const decision = decideSweep([], [rearmed], POLICY, NOW);
+		expect(decision.rearm).toHaveLength(0);
+		expect(decision.resolve).toHaveLength(0);
+	});
+
+	// A kind WITH a probe keeps the stronger path: it is never re-armed on
+	// quiet, because something can actually be asked about it.
+	test("a kind declaring a capability probe goes to the probe gate, never to re-arm", () => {
+		const gone = episode({ kind: "llm.provider.call.failed", lastSeenAt: new Date(NOW.getTime() - 60 * 60_000) });
+		const decision = decideSweep([], [gone], POLICY, NOW, {}, undefined, {
+			"llm.provider.call.failed": { url: "http://127.0.0.1:9/health" },
+		});
+		expect(decision.resolveProbeGate).toHaveLength(1);
+		expect(decision.rearm).toHaveLength(0);
+		expect(decision.resolve).toHaveLength(0);
 	});
 
 	test("after resolution the same fault escalates again (new episode)", () => {
@@ -161,6 +206,7 @@ describe("decideSweep — resolution + re-arm", () => {
 		const open = episode({ kind: "slow.error", lastSeenAt: active.lastSeen });
 		const decision = decideSweep([active], [open], POLICY, NOW);
 		expect(decision.resolve).toHaveLength(0);
+		expect(decision.rearm).toHaveLength(0);
 	});
 });
 
@@ -188,7 +234,9 @@ describe("decideSweep — a future-dated lastSeen is not recurrence evidence", (
 		const phantom = agg("guard.fail.open", 40, 720, -44);
 		const decision = decideSweep([phantom], [quietEpisode], POLICY, NOW);
 		expect(decision.escalate).toHaveLength(0);
-		expect(decision.resolve).toHaveLength(1);
+		// Re-armed rather than resolved: no probe is declared for this kind.
+		expect(decision.rearm).toHaveLength(1);
+		expect(decision.resolve).toHaveLength(0);
 	});
 });
 
@@ -354,19 +402,21 @@ describe("decideSweep — zero-volume gate (quiet vs dead producer)", () => {
 		expect(decision.zeroVolumeHold[0].volumeCount).toBe(0);
 	});
 
-	test("quiet WITH healthy call volume still resolves (the normal close)", () => {
+	test("quiet WITH healthy call volume re-arms (the normal path for a probe-less kind)", () => {
 		const episodes = [episode({ kind: "llm.provider.call.failed", lastSeenAt: new Date(NOW.getTime() - 45 * 60_000) })];
 		const inputs = { ...VOLUME_BACKED, countByKind: { "llm.provider.call.failed": 120 } };
 		const decision = decideSweep([], episodes, POLICY, NOW, {}, inputs);
 		expect(decision.zeroVolumeHold).toHaveLength(0);
-		expect(decision.resolve).toHaveLength(1);
-		expect(decision.resolve[0].clearZeroVolumeFlag).toBe(false);
+		expect(decision.rearm).toHaveLength(1);
+		expect(decision.resolve).toHaveLength(0);
+		expect(decision.rearm[0]!.clearZeroVolumeFlag).toBe(false);
 	});
 
-	test("a sourceless kind resolves on quiet exactly as before", () => {
+	test("a sourceless kind re-arms on quiet", () => {
 		const episodes = [episode({ kind: "guard.fail.open", lastSeenAt: new Date(NOW.getTime() - 45 * 60_000) })];
 		const decision = decideSweep([], episodes, POLICY, NOW, {}, { ...VOLUME_BACKED, countByKind: {} });
-		expect(decision.resolve).toHaveLength(1);
+		expect(decision.rearm).toHaveLength(1);
+		expect(decision.resolve).toHaveLength(0);
 		expect(decision.zeroVolumeHold).toHaveLength(0);
 	});
 
@@ -378,13 +428,14 @@ describe("decideSweep — zero-volume gate (quiet vs dead producer)", () => {
 			flagActiveByKind: { "llm.provider.call.failed": true },
 		};
 		const decision = decideSweep([], episodes, POLICY, NOW, {}, inputs);
-		expect(decision.resolve[0].clearZeroVolumeFlag).toBe(true);
+		expect(decision.rearm[0]!.clearZeroVolumeFlag).toBe(true);
 	});
 
 	test("without a sixth argument the legacy shape is untouched", () => {
 		const episodes = [episode({ kind: "llm.provider.call.failed", lastSeenAt: new Date(NOW.getTime() - 45 * 60_000) })];
 		const decision = decideSweep([], episodes, POLICY, NOW);
-		expect(decision.resolve).toHaveLength(1);
+		expect(decision.rearm).toHaveLength(1);
+		expect(decision.resolve).toHaveLength(0);
 	});
 });
 
@@ -422,10 +473,11 @@ describe("decideSweep — probe-gated resolution (operator ruling 2026-08-28)",
 		expect(decision.resolveProbeGate[0]!.quietMinutes).toBeGreaterThanOrEqual(30);
 	});
 
-	test("a kind without a declared probe resolves on quiet exactly as before", () => {
+	test("a kind without a declared probe RE-ARMS on quiet — it is never closed unverified", () => {
 		const gone = episode({ kind: "wake.failed", lastSeenAt: new Date(NOW.getTime() - 60 * 60_000) });
 		const decision = decideSweep([agg("wake.failed", 10, 700, 60)], [gone], POLICY, NOW, {}, undefined, PROBE_SOURCES);
-		expect(decision.resolve).toHaveLength(1);
+		expect(decision.rearm).toHaveLength(1);
+		expect(decision.resolve).toHaveLength(0);
 		expect(decision.resolveProbeGate).toHaveLength(0);
 	});
 

package/src/handlers/platform-fault-escalation.ts

@@ -39,6 +39,7 @@ import {
 	deliverEscalation,
 	deliverZeroVolumeHold,
 	refreshOpenEpisode,
+	rearmEpisode,
 	resolveEpisode,
 } from "./platform-fault-escalation/delivery.ts";
 
@@ -61,6 +62,7 @@ async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig })
 		escalated_at: string | Date | null;
 		work_item_id: string | null;
 		resolved_at: string | Date | null;
+		rearmed_at: string | Date | null;
 		last_updated_at: string | Date | null;
 	}>;
 	const episodes: EscalationEpisode[] = openEpisodes.map((row) => ({
@@ -71,6 +73,7 @@ async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig })
 		escalatedAt: row.escalated_at ? new Date(row.escalated_at) : null,
 		workItemId: row.work_item_id,
 		resolvedAt: row.resolved_at ? new Date(row.resolved_at) : null,
+		rearmedAt: row.rearmed_at ? new Date(row.rearmed_at) : null,
 		lastUpdatedAt: row.last_updated_at ? new Date(row.last_updated_at) : null,
 	}));
 
@@ -204,6 +207,19 @@ async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig })
 			log.error(`[platform-fault-escalation] resolve for '${episode.kind}' failed: ${err instanceof Error ? err.message : String(err)}`);
 		}
 	}
+	// RE-ARM, NOT RESOLVE (2026-08-29). A kind with no declared capability
+	// probe went quiet: the alarm is armed for the next occurrence and NOTHING
+	// is claimed about the condition. No operator comment is written here on
+	// purpose — see rearmEpisode.
+	for (const { episode, quietMinutes, clearZeroVolumeFlag } of decision.rearm) {
+		try {
+			await rearmEpisode(episode, quietMinutes);
+			if (clearZeroVolumeFlag) await clearZeroVolumeHold(episode, zeroVolume.countByKind[episode.kind] ?? 0);
+			log.info(`[platform-fault-escalation] RE-ARMED '${episode.kind}' after ${Math.round(quietMinutes)} quiet min — no probe declared, so the condition is UNVERIFIED and no close was claimed`);
+		} catch (err) {
+			log.error(`[platform-fault-escalation] re-arm for '${episode.kind}' failed (retried next sweep): ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
 
 	// Emitted every run, even when nothing fired — a sweep that only reports
 	// when it escalated is indistinguishable from one that stopped running.

package/src/handlers/projects-digest.ts

@@ -4,7 +4,7 @@
  * @edit edit directly
  *
  * The `projects-daily-digest` / `projects-weekly-digest` pg-boss handlers for
- * scala-projects. Same fixed-query shape as prune-stale-data: no row-driven
+ * scala-projects. Fixed-query shape: no row-driven
  * SQL, every query is a literal Prisma call against work_items; the
  * scheduled_job row only carries the cron.
  *

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

@@ -1,5 +1,4 @@
 import { describe, expect, test } from "bun:test";
-import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 /**
@@ -20,10 +19,7 @@ import { join } from "node:path";
  * the module proves it cannot fire on any path. It also stays honest if someone
  * reintroduces the restart behind a new condition.
  */
-const SOURCE = readFileSync(
-	join(import.meta.dir, "scala-tools-currency-watch.ts"),
-	"utf-8",
-);
+const SOURCE = await Bun.file(join(import.meta.dir, "scala-tools-currency-watch.ts")).text();
 
 /** Comment prose legitimately discusses the removed restart; code must not do it. */
 const CODE = SOURCE.split("\n")

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

@@ -25,6 +25,29 @@
  *
  * Registered under slug `@teamscala/service-boot:scala-tools-currency-watch`.
  */
+		// NO RESTART. The reinstall alone is sufficient, and restarting here was actively harmful.
+		//
+		// The premise this watch was written on — "restart so the fresh scala-tools loads" — does not hold for THIS package. scala-sentinel never
+		// imports `@teamscala/scala-tools`; it SPAWNS `node_modules/.bin/scala-tools` per invocation, so a freshly installed binary is picked up by the next
+		// spawn with no process restart at all. Verified 2026-07-27: the package is declared in scala-sentinel/package.json, yet scala-guard/src contains zero
+		// import statements resolving to it — it is spawned, never linked. dep-sync already encodes the same conclusion — HARNESS_CRITICAL_FAST_PATH
+		// maps this exact pair to install-WITHOUT-restart, while its PM2_CACHED sibling map exists for packages a daemon really does load at boot
+		// (@teamscala/codegen → codegen-daemon). This handler was the odd one out.
+		//
+		// The cost was not theoretical. Restarting the guard daemon takes enforcement offline for its warmup, and every shutdown logs "152 guard(s)
+		// failed to run (fail-open)" — so each unnecessary restart opened a window in which tool-check, turn-end and pre-push silently did not run. Three
+		// scala-tools versions published on 2026-07-26 alone, and this watch polls, so it re-fired for each. That inverts
+		// `infrastructure-outranks-application-durability`: a currency convenience was repeatedly disabling the thing it exists to keep current.
+		//
+		// It also used a bare `pm2 restart`, which is forbidden (`forbid-bare-pm2-restart`) precisely because it bypasses the
+		// currency-gated canonical pipeline — the guard blocks agents from that exact call.
+		//
+		// If a future package genuinely needs a restart to take effect, it does not belong here: add it to dep-sync's PM2_CACHED map, which already owns
+		// install-plus-restart and coalesces them.
+
+// Why: NO RESTART. The reinstall alone is sufficient, and restartin…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
 import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
@@ -124,38 +147,6 @@ async function scalaToolsCurrencyWatch(_ctx: { config: ScheduledJobConfig }): Pr
 			payload: { from: installed, to: latest },
 		});
 
-		// NO RESTART. The reinstall alone is sufficient, and restarting here was
-		// actively harmful.
-		//
-		// The premise this watch was written on — "restart so the fresh
-		// scala-tools loads" — does not hold for THIS package. scala-sentinel never
-		// imports `@teamscala/scala-tools`; it SPAWNS `node_modules/.bin/scala-tools`
-		// per invocation, so a freshly installed binary is picked up by the next
-		// spawn with no process restart at all. Verified 2026-07-27: the package is
-		// declared in scala-sentinel/package.json, yet scala-guard/src contains zero
-		// import statements resolving to it — it is spawned, never linked.
-		// dep-sync already encodes the same conclusion — HARNESS_CRITICAL_FAST_PATH
-		// maps this exact pair to install-WITHOUT-restart, while its PM2_CACHED
-		// sibling map exists for packages a daemon really does load at boot
-		// (@teamscala/codegen → codegen-daemon). This handler was the odd one out.
-		//
-		// The cost was not theoretical. Restarting the guard daemon takes
-		// enforcement offline for its warmup, and every shutdown logs "152 guard(s)
-		// failed to run (fail-open)" — so each unnecessary restart opened a window
-		// in which tool-check, turn-end and pre-push silently did not run. Three
-		// scala-tools versions published on 2026-07-26 alone, and this watch polls,
-		// so it re-fired for each. That inverts
-		// `infrastructure-outranks-application-durability`: a currency convenience
-		// was repeatedly disabling the thing it exists to keep current.
-		//
-		// It also used a bare `pm2 restart`, which is forbidden
-		// (`forbid-bare-pm2-restart`) precisely because it bypasses the
-		// currency-gated canonical pipeline — the guard blocks agents from that
-		// exact call.
-		//
-		// If a future package genuinely needs a restart to take effect, it does not
-		// belong here: add it to dep-sync's PM2_CACHED map, which already owns
-		// install-plus-restart and coalesces them.
 		log.info(
 			`[scala-tools-currency-watch] reinstalled ${PKG} ${installed} → ${latest} (no restart: sentinel spawns the binary, it does not import it)`,
 		);

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

@@ -1,11 +1,7 @@
 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 SOURCE = await Bun.file(join(import.meta.dir, "singleton-tools-currency-watch.ts")).text();
 
 const CODE = SOURCE.split("\n")
 	.filter((l) => !l.trimStart().startsWith("//") && !l.trimStart().startsWith("*"))

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

@@ -23,14 +23,6 @@
  *
  * 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 { getDistTagVersion } from "@teamscala/publish-registry";
-import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
-
 /**
  * Where a tool's "latest" comes from.
  *
@@ -47,6 +39,33 @@ import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
  * never shadow a /usr/local/bin singleton wrapper. The gap was currency
  * tracking, never placement.
  */
+
+// Why: Where a tool's "latest" comes from.
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+		// 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.
+
+// Why: A GitHub-released binary is NOT installed by a package manag…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+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 { getDistTagVersion } from "@teamscala/publish-registry";
+import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
+
 type VersionSource =
 	| {
 			type: "npm_package";
@@ -210,17 +229,6 @@ async function reinstallTool(tool: SingletonTool, latest: string): Promise<boole
 	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.`,
 		);