@teamscala/service-boot 0.23.428 → 0.23.430

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.428",
+  "version": "0.23.430",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",

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

@@ -33,6 +33,12 @@ export const FaultEscalationConfigSchema = v.object({
 		),
 	),
 	resolve_after_minutes: v.number(),
+	/** Kinds a standing agent lane answers, which therefore escalate to the
+	 * work item WITHOUT paging the operator (operator ruling 2026-08-28: "why
+	 * is the WhatsApp PA messaging me about stuff that you should be doing").
+	 * The episode, the comment and the durable record are unchanged — only the
+	 * phone is spared, so silencing a page never silences the signal. */
+	agent_handled_kinds: v.optional(v.array(v.string())),
 	/** Per-kind volume sources closing the quiet-vs-dead gap: a fault kind
 	 * whose producer can DIE maps to the kind whose row VOLUME proves the
 	 * pipeline alive. Without a source, resolution on quiet is unchanged;

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

@@ -18,6 +18,7 @@ import {
 	composeEscalationMessage,
 	composeZeroVolumeMessage,
 	extractWhatsAppMessageId,
+	pagesOperator,
 	type EscalationEpisode,
 	type FaultAggregate,
 	type ZeroVolumeSource,
@@ -53,7 +54,7 @@ export async function deliverEscalation(
 	kind: string,
 	aggregate: FaultAggregate,
 	config: FaultEscalationConfig,
-): Promise<{ messageId: string; workItemId: string }> {
+): Promise<{ messageId: string | null; workItemId: string }> {
 	const now = new Date();
 
 	// 1. Claim the episode BEFORE sending, so a send failure leaves a durable
@@ -80,8 +81,11 @@ export async function deliverEscalation(
 	// that picks the device and records the send in messaging_logs. The retired
 	// api_gowa_message tool (deactivated 2026-08-26) is no longer callable;
 	// naming it here left every escalation send failing with "Unknown tool".
-	const bot = await resolveOperatorRelay();
-	const operatorPhone = (bot.flow_config as { operator_phone?: string }).operator_phone!;
+
+	// PAGING IS PER-KIND (operator ruling 2026-08-28). Only the phone is
+	// skipped; episode, comment and record are identical, so a silenced page
+	// never becomes a silenced signal.
+	const paging = pagesOperator(kind, config.agent_handled_kinds);
 	const copy = config.copy[kind] ?? config.default_copy;
 	const { sample, lastEvent } = await fetchLatestEvidence(kind, config.sample_fields?.[kind] ?? []);
 	const message = composeEscalationMessage({
@@ -93,23 +97,31 @@ export async function deliverEscalation(
 		recommendation: copy.recommendation,
 	});
 
-	const { userId, organisationId } = await getSystemIdentity();
-	const systemCtx: ExecutionContext = { userId, organisationId } as ExecutionContext;
-	const { forwardToolToCentralMcp } = await import("@teamscala/chat-completion/central-tool-forwarder");
-	const sendResult = await forwardToolToCentralMcp(
-		"messaging_whatsapp_send",
-		{ phone: operatorPhone, message },
-		systemCtx,
-	);
-
 	// 3. VERIFY delivery before recording it: the send must return a WhatsApp
 	// message id. No id => throw, the claim stays undelivered, next sweep retries.
-	const messageId = extractWhatsAppMessageId(sendResult);
-	if (!messageId) {
-		throw new Error(
-			`platform-fault-escalation: WhatsApp send for '${kind}' returned no message id — not recording delivery. ` +
-				`Response: ${JSON.stringify(sendResult).slice(0, 400)}`,
+	// An agent-handled kind sends nothing, so there is no id to verify and none
+	// is recorded — absence here means "never paged", never "paged unverified".
+	let messageId: string | null = null;
+	if (paging) {
+		const bot = await resolveOperatorRelay();
+		const operatorPhone = (bot.flow_config as { operator_phone?: string }).operator_phone!;
+		const { userId, organisationId } = await getSystemIdentity();
+		const systemCtx: ExecutionContext = { userId, organisationId } as ExecutionContext;
+		const { forwardToolToCentralMcp } = await import(
+			"@teamscala/chat-completion/central-tool-forwarder"
 		);
+		const sendResult = await forwardToolToCentralMcp(
+			"messaging_whatsapp_send",
+			{ phone: operatorPhone, message },
+			systemCtx,
+		);
+		messageId = extractWhatsAppMessageId(sendResult);
+		if (!messageId) {
+			throw new Error(
+				`platform-fault-escalation: WhatsApp send for '${kind}' returned no message id — not recording delivery. ` +
+					`Response: ${JSON.stringify(sendResult).slice(0, 400)}`,
+			);
+		}
 	}
 
 	// 4. Durable record: a COMMENT on the orchestrator's work item — an
@@ -178,6 +190,30 @@ export async function resolveEpisode(
 	});
 }
 
+/**
+ * Refresh an OPEN episode's window facts from the live aggregate.
+ *
+ * Escalation wrote the row once and never again, so its facts froze while the
+ * fault kept firing (2026-08-28: fifteen hours stale, 1,150 later events).
+ * That also corrupts RESOLUTION, since `decideSweep` falls back to
+ * `lastSeenAt` once a kind leaves the window. Fields mirror the escalation
+ * upsert. `last_updated_at` is untouched: it gates the resolve-hold dedupe.
+ */
+export async function refreshOpenEpisode(
+	kind: string,
+	aggregate: { firstSeen: Date; lastSeen: Date; count: number },
+): Promise<void> {
+	await (await orpc()).platform_fault_escalations.update({
+		where: { kind },
+		data: {
+			first_seen_at: aggregate.firstSeen.toISOString(),
+			last_seen_at: aggregate.lastSeen.toISOString(),
+			event_count: aggregate.count,
+			updated_at: new Date().toISOString(),
+		},
+	});
+}
+
 /** Send one message to the operator through the verified WhatsApp relay and
  * record it as a comment on the orchestrator's work item. Returns the
  * verified ids; throws when the send carries no message id so the caller's

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

@@ -229,6 +229,32 @@ export function decideSweep(
 }
 
 /** Human "N min" span, rounded — for the phone-sized escalation message. */
+/**
+ * Do this OPEN episode's stored window facts lag the live aggregate?
+ *
+ * Both NEGATIVE answers carry weight: a quiet kind keeps its last true
+ * sighting (the value resolve falls back to), and an aggregate no newer than
+ * the row is never written, so a steady-state sweep writes nothing.
+ */
+export function episodeNeedsRefresh(
+	episode: Pick<EscalationEpisode, "lastSeenAt">,
+	aggregate: { lastSeen: Date } | undefined,
+): boolean {
+	if (!aggregate) return false;
+	return aggregate.lastSeen.getTime() > episode.lastSeenAt.getTime();
+}
+
+/**
+ * Does this fault kind page the operator, or land on the work item alone?
+ *
+ * DEFAULT IS TO PAGE. An unlisted kind reaches the phone, so forgetting to
+ * classify a new fault fails loudly rather than silently — the opposite
+ * default would let a kind be silenced by omission.
+ */
+export function pagesOperator(kind: string, agentHandledKinds?: string[]): boolean {
+	return !(agentHandledKinds ?? []).includes(kind);
+}
+
 export function formatSpanMinutes(minutes: number): string {
 	if (minutes < 60) return `${Math.round(minutes)} min`;
 	const hours = minutes / 60;

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

@@ -0,0 +1,85 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Unit tests for episode FACT CURRENCY — a separate concern from the
+ * threshold/dedup semantics locked by `platform-fault-escalation.test.ts`,
+ * and kept in its own file because that one already sits over the size
+ * budget.
+ *
+ * WHAT THIS LOCKS. The sweep escalated once and then never wrote the row
+ * again, so an open episode's window facts froze at their escalation-time
+ * values while the fault kept firing. Measured 2026-08-28: the
+ * `host-command-bus.command.failed` row read `last_seen_at` fifteen hours old
+ * with 1,150 further events recorded after it, and a reader — this lane
+ * included — concluded from the row that the fault had stopped.
+ *
+ * The stale value is not only cosmetic: `decideSweep` falls back to
+ * `episode.lastSeenAt` once a kind drops out of the window, so a frozen
+ * timestamp makes a just-gone-quiet fault look quiet for hours and closes the
+ * episode immediately instead of after its configured resolve window.
+ */
+import { describe, expect, test } from "bun:test";
+import { episodeNeedsRefresh, pagesOperator } from "./platform-fault-escalation-logic.ts";
+
+const at = (iso: string) => ({ lastSeenAt: new Date(iso) });
+const seen = (iso: string) => ({ lastSeen: new Date(iso) });
+
+describe("episodeNeedsRefresh", () => {
+	test("a still-firing fault whose row has fallen behind is refreshed", () => {
+		// The measured incident, in miniature: row frozen at escalation time,
+		// events still arriving fifteen hours later.
+		expect(episodeNeedsRefresh(at("2026-08-27T12:25:03Z"), seen("2026-08-28T03:00:41Z"))).toBe(
+			true,
+		);
+	});
+
+	test("a kind that has gone quiet keeps its last true sighting", () => {
+		// No aggregate means nothing landed in the window. The stored value must
+		// STAND rather than advance, because it is the reference the resolve
+		// decision falls back to — advancing it here would hold every quiet
+		// episode open forever.
+		expect(episodeNeedsRefresh(at("2026-08-27T12:25:03Z"), undefined)).toBe(false);
+	});
+
+	test("an unchanged fault is not written back", () => {
+		// Equal timestamps must not write: a sweep over steady state performs
+		// zero updates, so the refresh cannot become a per-sweep write storm.
+		const same = "2026-08-28T03:00:41Z";
+		expect(episodeNeedsRefresh(at(same), seen(same))).toBe(false);
+	});
+
+	test("an aggregate OLDER than the row never rewinds it", () => {
+		// A shrinking window can report an older newest-event than the row
+		// already holds. Rewinding would fabricate quiet time and resolve a
+		// live fault early.
+		expect(episodeNeedsRefresh(at("2026-08-28T03:00:41Z"), seen("2026-08-28T01:00:00Z"))).toBe(
+			false,
+		);
+	});
+});
+
+describe("pagesOperator", () => {
+	// Operator ruling 2026-08-28: "why is the WhatsApp PA messaging me about
+	// stuff that you should be doing". A kind a standing lane answers escalates
+	// to the work item; the phone is spared.
+	const AGENT_HANDLED = ["guard.fail.open", "host-command-bus.command.failed"];
+
+	test("a kind the maintenance lane answers does not page", () => {
+		expect(pagesOperator("guard.fail.open", AGENT_HANDLED)).toBe(false);
+		expect(pagesOperator("host-command-bus.command.failed", AGENT_HANDLED)).toBe(false);
+	});
+
+	test("an unlisted kind still pages", () => {
+		expect(pagesOperator("supervisor.halt.entered", AGENT_HANDLED)).toBe(true);
+	});
+
+	test("DEFAULT IS TO PAGE when nothing is configured", () => {
+		// The load-bearing direction: a kind is silenced only by being named.
+		// If the list is missing or empty, every fault reaches the operator, so
+		// a new kind can never be silenced by omission.
+		expect(pagesOperator("guard.fail.open", undefined)).toBe(true);
+		expect(pagesOperator("guard.fail.open", [])).toBe(true);
+	});
+});

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

@@ -20,6 +20,7 @@ import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
 import {
 	decideSweep,
+	episodeNeedsRefresh,
 	type EscalationEpisode,
 	type KindThresholdOverride,
 	type ZeroVolumeInputs,
@@ -37,6 +38,7 @@ import {
 	clearZeroVolumeHold,
 	deliverEscalation,
 	deliverZeroVolumeHold,
+	refreshOpenEpisode,
 	resolveEpisode,
 } from "./platform-fault-escalation/delivery.ts";
 
@@ -117,7 +119,7 @@ async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig })
 		try {
 			const delivered = await deliverEscalation(aggregate.kind, aggregate, config);
 			log.warn(
-				`[platform-fault-escalation] ESCALATED '${aggregate.kind}' — WhatsApp message ${delivered.messageId}, work item ${delivered.workItemId}`,
+				`[platform-fault-escalation] ESCALATED '${aggregate.kind}' — ${delivered.messageId ? `WhatsApp message ${delivered.messageId}` : "work item only (agent-handled kind, operator not paged)"}, work item ${delivered.workItemId}`,
 			);
 		} catch (err) {
 			const reason = err instanceof Error ? err.message : String(err);
@@ -125,6 +127,24 @@ async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig })
 			recordEvent({ kind: "platform.fault.escalation_failed", payload: { event_kind: aggregate.kind, reason } });
 		}
 	}
+	// AN OPEN EPISODE KEEPS ITS FACTS CURRENT. Escalation is a TRANSITION and
+	// fires once (`emit-transitions-not-conditions`) — but the ROW is the
+	// durable record of the condition, and a record that stops updating starts
+	// lying. Refreshing is not emitting: nothing is delivered here, no comment
+	// is written, no message is sent. Only the stored window facts move.
+	const aggregateByKind = new Map(aggregates.map((aggregate) => [aggregate.kind, aggregate]));
+	for (const episode of episodes) {
+		const aggregate = aggregateByKind.get(episode.kind);
+		if (!episodeNeedsRefresh(episode, aggregate) || !aggregate) continue;
+		try {
+			await refreshOpenEpisode(episode.kind, aggregate);
+		} catch (err) {
+			log.error(
+				`[platform-fault-escalation] refresh for '${episode.kind}' failed (facts stay stale for this sweep, retried next): ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+	}
+
 	for (const { episode, quietMinutes } of decision.zeroVolumeHold) {
 		const source = volumeSources[episode.kind];
 		if (!source) continue;