@teamscala/service-boot 0.23.407 → 0.23.409

package/package.json

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

package/src/fn-routers/index.ts

@@ -30,6 +30,7 @@ import { publicGptSessionRouter } from "./public-gpt-session-router.ts";
 import { signInFlowRouter } from "./sign-in-flow-router.ts";
 import { userPreferencesRouter } from "./user-preferences-router.ts";
 import { workItemsRouter } from "./work-items-router.ts";
+import { messagingWhatsappRouter } from "./messaging-whatsapp-router.ts";
 
 export function registerFnRouters(): void {
 	registerCustomRouter("fn", {
@@ -38,6 +39,7 @@ export function registerFnRouters(): void {
 		auth: authRouter,
 		cacheAdmin: cacheAdminRouter,
 		chatSession: chatSessionRouter,
+		messagingWhatsappSend: messagingWhatsappRouter.messagingWhatsappSend,
 		publicAgreement: publicAgreementRouter,
 		publicAssessment: publicAssessmentRouter,
 		publicGptSession: publicGptSessionRouter,

package/src/fn-routers/messaging-whatsapp-router.test.ts

@@ -0,0 +1,119 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Proves fn.messagingWhatsappSend routes through scala-messaging-service: the
+ * URL is DERIVED from the service_install row (never spelled), the sealed-row
+ * credential is passed through the decrypt mock (identity, matching the
+ * public-assessment-router test pattern), the request carries the internal
+ * auth header, and the caller receives WhatsApp's message_id — the only thing
+ * that makes delivery provable. Failure modes (401, blank input) fail loudly
+ * with named causes, never a generic send error.
+ */
+
+import { createRouterClient } from "@orpc/server";
+import { afterAll, describe, expect, mock, test } from "bun:test";
+
+const SEND_CALLS: Array<{ url: string; headers: Record<string, string>; body: unknown }> = [];
+
+mock.module("@teamscala/db/registry/load-config", () => ({
+	loadRegistryConfig: async (type: string, slug: string) => {
+		if (type === "service_install" && slug === "scala-messaging-service") {
+			return { deploy_target: "railway", port: 8080 };
+		}
+		if (type === "secret" && slug === "railway-scala-messaging-whatsapp-webhook-secret") {
+			return { token: "test-token" };
+		}
+		throw new Error(`unexpected loadRegistryConfig(${type}, ${slug})`);
+	},
+}));
+
+// Identity decrypt (the public-assessment-router test pattern).
+mock.module("@teamscala/encryption/crypto/secret-config", () => ({
+	decryptSecretConfig: (raw: unknown) => raw,
+}));
+
+mock.module("@teamscala/logger/app-loggers", () => ({
+	getAppLogger: () => ({
+		info: () => {},
+		warn: () => {},
+		error: () => {},
+		debug: () => {},
+	}),
+}));
+
+const originalFetch = globalThis.fetch;
+(globalThis as { fetch: unknown }).fetch = async (url: string, init: RequestInit) => {
+	SEND_CALLS.push({
+		url,
+		headers: init.headers as Record<string, string>,
+		body: JSON.parse(init.body as string),
+	});
+	const body = JSON.parse(init.body as string) as { phone?: string };
+	if (body.phone === "0-0-1-refuse") {
+		return new Response("no", { status: 401 });
+	}
+	return Response.json({ message_id: "3EB07EE8TESTID" });
+};
+
+const { messagingWhatsappRouter } = await import("./messaging-whatsapp-router.ts");
+
+// Invoke through a real ORPC client so the authed middleware runs too —
+// calling the DecoratedProcedure directly is not a round trip.
+const client = createRouterClient(
+	{ messagingWhatsappSend: messagingWhatsappRouter.messagingWhatsappSend } as never,
+	{
+		context: {
+			user: { id: "system", organisationId: null },
+			headers: new Headers(),
+			prisma: {},
+		} as never,
+	},
+) as { messagingWhatsappSend: (a: unknown) => Promise<unknown> };
+
+describe("fn.messagingWhatsappSend", () => {
+	test("derives the URL from service_install, sends with the decrypted header value, returns the message_id", async () => {
+		SEND_CALLS.length = 0;
+		const result = await client.messagingWhatsappSend({
+			phone: "61428193498",
+			message: "migration probe",
+		});
+
+		expect(SEND_CALLS).toHaveLength(1);
+		expect(SEND_CALLS[0]?.url).toBe(
+			"http://scala-messaging-service.railway.internal:8080/api/messaging/whatsapp/send",
+		);
+		expect(SEND_CALLS[0]?.headers["x-webhook-secret"]).toBe("test-token");
+		expect(SEND_CALLS[0]?.body).toEqual({ phone: "61428193498", message: "migration probe" });
+		expect(result).toEqual({ ok: true, message_id: "3EB07EE8TESTID" });
+	});
+
+	test("a 401 from the messaging service names the credential, not a generic failure", async () => {
+		SEND_CALLS.length = 0;
+		const result = await client.messagingWhatsappSend({
+			phone: "0-0-1-refuse",
+			message: "x",
+		});
+		expect(result).toEqual({
+			ok: false,
+			error: "messaging service refused the webhook secret (401)",
+		});
+	});
+
+	test("blank phone or message is refused before any request is made", async () => {
+		SEND_CALLS.length = 0;
+		const blank = await client.messagingWhatsappSend({
+			phone: "   ",
+			message: "x",
+		});
+		expect(blank).toEqual({ ok: false, error: "phone and message are required" });
+		expect(SEND_CALLS).toHaveLength(0);
+	});
+});
+
+// Restore INSIDE afterAll — a top-level restore would run before the tests
+// (all top-level code executes first) and hand the router back the real fetch.
+afterAll(() => {
+	(globalThis as { fetch: unknown }).fetch = originalFetch;
+});

package/src/fn-routers/messaging-whatsapp-router.ts

@@ -0,0 +1,180 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * fn.messagingWhatsappSend — the agent-facing WhatsApp send that routes through
+ * scala-messaging-service (the Rust owner of the channel), replacing the
+ * retired TS @teamscala/api-gowa SDK send path (operator ruling 2026-08-26:
+ * "make sure the migration is finished, i cant have half ts and half rust").
+ *
+ * The messaging service's POST /api/messaging/whatsapp/send is the single send
+ * surface: it resolves the sending device, returns WhatsApp's message_id for
+ * delivery correlation, and records the send in messaging_logs itself (Rust,
+ * `write_outbound_tracked`) — better than the deleted TS recorder, which only
+ * ran when the send happened to flow through tool-executor.
+ *
+ * Both facts this procedure needs are DERIVED at call time, never spelled:
+ * - the service URL comes from the service_install row (slug + port +
+ *   deploy_target → Railway private DNS <slug>.railway.internal:<port>), the
+ *   same derivation every *.railway.internal consumer uses;
+ * - the auth credential is the existing sealed secret row
+ *   railway-scala-messaging-whatsapp-webhook-secret, decrypted per
+ *   registry-via-helper + the agreement-send precedent.
+ *
+ * Registered flat under the `fn` namespace (two-segment procedure
+ * "fn.messagingWhatsappSend") because the tool-executor ORPC dispatch resolves
+ * "model.method" — nested routers would not be reachable as a tool procedure.
+ */
+
+import { os } from "@orpc/server";
+import * as v from "valibot";
+import {
+	decryptSecretConfig,
+	type SecretConfigLike,
+} from "@teamscala/encryption/crypto/secret-config";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+interface User {
+	id: string;
+	organisationId: string | null;
+}
+
+interface Context {
+	user: User | null | undefined;
+	headers: Headers;
+	resolveUser?: (headers: Headers, prisma: any) => Promise<User | null>;
+	prisma: any;
+}
+
+const authed = os.$context<Context>().use(async (opt) => {
+	const { context } = opt;
+	let user = context.user;
+	if (!user && context.headers && context.resolveUser) {
+		user = await context.resolveUser(context.headers, context.prisma);
+	}
+	if (!user) {
+		const { ORPCError } = await import("@orpc/server");
+		throw new ORPCError("UNAUTHORIZED", { message: "Authentication required" });
+	}
+	return await opt.next({ context: { ...context, user } });
+});
+
+/** service_install shape for deriving the messaging service's internal URL. */
+const MessagingInstallSchema = v.looseObject({
+	port: v.optional(v.number(), 8080),
+	deploy_target: v.string(),
+});
+
+/** The sealed webhook-secret row shape (value is decryptSecretConfig input). */
+const MessagingSecretSchema = v.looseObject({});
+
+/** Derive the messaging service base URL from its service_install row. */
+async function resolveMessagingBaseUrl(): Promise<string> {
+	const install = await loadRegistryConfig(
+		"service_install",
+		"scala-messaging-service",
+		MessagingInstallSchema,
+	);
+	if (install.deploy_target !== "railway") {
+		throw new Error(
+			`scala-messaging-service deploy_target is "${install.deploy_target}", not "railway" — ` +
+				"the private-DNS URL derivation only holds on Railway. Fix the service_install row.",
+		);
+	}
+	return `http://scala-messaging-service.railway.internal:${install.port}`;
+}
+
+const sendSchema = v.object({
+	/** Destination phone number in E.164 (e.g. 61428193498). */
+	phone: v.string(),
+	/** Text body to send. */
+	message: v.string(),
+});
+
+export const messagingWhatsappRouter = {
+	messagingWhatsappSend: authed
+		.input(sendSchema)
+		.handler(async ({ input }) => {
+			const log = getAppLogger();
+			const phone = input.phone.trim();
+			const message = input.message;
+			if (!phone || !message) {
+				return { ok: false as const, error: "phone and message are required" };
+			}
+
+			try {
+				const [baseUrl, rawSecret] = await Promise.all([
+					resolveMessagingBaseUrl(),
+					loadRegistryConfig(
+						"secret",
+						"railway-scala-messaging-whatsapp-webhook-secret",
+						MessagingSecretSchema,
+					).catch(() => {
+						throw new Error(
+							"secret row railway-scala-messaging-whatsapp-webhook-secret is missing — " +
+								"the messaging service send endpoint cannot be authenticated",
+						);
+					}),
+				]);
+				const decrypted = decryptSecretConfig(
+					rawSecret as SecretConfigLike,
+				) as { token?: string };
+				if (!decrypted.token) {
+					return {
+						ok: false as const,
+						error: "whatsapp webhook secret row has no token",
+					};
+				}
+
+				const response = await fetch(
+					`${baseUrl}/api/messaging/whatsapp/send`,
+					{
+						method: "POST",
+						headers: {
+							"Content-Type": "application/json",
+							// The Rust handler accepts x-webhook-secret (or
+							// x-api-key) against WHATSAPP_WEBHOOK_SECRET.
+							"x-webhook-secret": decrypted.token,
+						},
+						body: JSON.stringify({ phone, message }),
+						signal: AbortSignal.timeout(30_000),
+					},
+				);
+				if (response.status === 401) {
+					return {
+						ok: false as const,
+						error: "messaging service refused the webhook secret (401)",
+					};
+				}
+				const body = (await response.json().catch(() => null)) as {
+					message_id?: string;
+					error?: string;
+				} | null;
+				if (!response.ok) {
+					return {
+						ok: false as const,
+						error:
+							body?.error ??
+							`messaging service send failed: ${response.status}`,
+					};
+				}
+				// The message_id is the only thing that makes delivery provable —
+				// hand it back so the caller can correlate the ack (gowa.rs
+				// parse_message_id contract).
+				log.info("[fn.messagingWhatsappSend] sent", {
+					phone,
+					message_id: body?.message_id ?? null,
+				});
+				return {
+					ok: true as const,
+					message_id: body?.message_id ?? null,
+				};
+			} catch (err) {
+				const errorMessage = err instanceof Error ? err.message : String(err);
+				log.error(`[fn.messagingWhatsappSend] failed: ${errorMessage}`);
+				return { ok: false as const, error: errorMessage };
+			}
+		}),
+};

package/src/fn-routers/public-agreement-router.ts

@@ -1,6 +1,6 @@
 /**
  * @system service-boot
- * @status handwritten
+ * @status handwritten @indivisible-unit
  * @edit edit directly
  *
  * Public ORPC procedures for DocuSign-style agreement signing, reached by the

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

@@ -3,25 +3,9 @@
  * @status handwritten
  * @edit edit directly
  *
- * Pure decision logic for the platform-fault escalation sweep
- * (`platform-fault-escalation` handler). Split from the I/O shell so the
- * threshold/dedup/episode semantics are unit-testable with zero adapter
- * dependencies (same shape as whatsapp-liveness-logic).
- *
- * The semantics this locks (from the 2026-08-15 "760 errors escalated to
- * nobody" incident brief):
- * - Threshold on DURATION and RECURRENCE, never a single event. A kind
- *   qualifies as a sustained fault only when BOTH hold inside the lookback
- *   window: at least `min_count` occurrences (recurrence) spread over at
- *   least `min_span_minutes` (duration). One failed push is noise; the same
- *   kind recurring for half an hour is an outage.
- * - One escalation per distinct fault kind per episode. An episode is open
- *   from first qualification until `resolve_after_minutes` of quiet; while
- *   open, the fault never re-fires — it only appends throttled updates.
- * - Delivery is verified, not queued: an episode row with `escalated_at`
- *   NULL is a CLAIM, not an escalation. The sweep re-attempts delivery for
- *   claimed-but-undelivered episodes until the WhatsApp send returns a
- *   message id.
+ * Pure decision logic for the platform-fault escalation sweep — full
+ * contract in curated `apps/escalation.md`. Episodes emit on TRANSITIONS
+ * ONLY; a future-dated `lastSeen` is never recurrence evidence.
  */
 
 export interface FaultAggregate {
@@ -29,6 +13,10 @@ export interface FaultAggregate {
 	count: number;
 	firstSeen: Date;
 	lastSeen: Date;
+	/** Id of the newest row backing `lastSeen`, when the caller resolved it —
+	 * the resolvable handle the escalation cites so "last at T" is checkable
+	 * against a real event_log row, not a computed or cached value. */
+	lastEventId?: string | null;
 }
 
 export interface EscalationEpisode {
@@ -50,8 +38,6 @@ export interface FaultEscalationPolicy {
 	minSpanMinutes: number;
 	/** Quiet period that closes an episode and re-arms escalation, minutes. */
 	resolveAfterMinutes: number;
-	/** Minimum spacing between throttled updates on an open episode, minutes. */
-	updateAfterMinutes: number;
 }
 
 /** Per-kind threshold overrides — a low-rate-but-persistent kind (guard.fail.open
@@ -65,8 +51,6 @@ 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, delivered episodes still recurring — append evidence, never re-send. */
-	update: Array<{ aggregate: FaultAggregate; episode: EscalationEpisode }>;
 	/** Open episodes whose kind went quiet past the resolve window — close them. */
 	resolve: Array<{ episode: EscalationEpisode; quietMinutes: number }>;
 }
@@ -88,9 +72,13 @@ function isSustained(
 	// happening. Without this the 720-minute lookback keeps a dead fault
 	// qualifying for hours, and since a resolved episode reads as no episode
 	// it re-escalates on every sweep until its events age out (2026-08-26).
+	// A future `lastSeen` (producer clock skew / mocked test clock, measured
+	// 2026-08-26: "still recurring" citing a timestamp 44 min in its own
+	// future) makes minutesBetween go NEGATIVE — refuse it as evidence.
 	return (
 		aggregate.count >= minCount &&
 		minutesBetween(aggregate.firstSeen, aggregate.lastSeen) >= minSpan &&
+		aggregate.lastSeen.getTime() <= now.getTime() &&
 		minutesBetween(aggregate.lastSeen, now) < policy.resolveAfterMinutes
 	);
 }
@@ -110,7 +98,7 @@ export function decideSweep(
 ): SweepDecision {
 	const byKind = new Map(episodes.map((e) => [e.kind, e]));
 	const aggregateByKind = new Map(aggregates.map((a) => [a.kind, a]));
-	const decision: SweepDecision = { escalate: [], update: [], resolve: [] };
+	const decision: SweepDecision = { escalate: [], resolve: [] };
 
 	for (const aggregate of aggregates) {
 		const episode = byKind.get(aggregate.kind);
@@ -126,19 +114,23 @@ export function decideSweep(
 		// verified).
 		if (!episode.escalatedAt) {
 			decision.escalate.push({ aggregate, episode });
-			continue;
-		}
-		// Open, delivered, still recurring — throttled evidence update only.
-		const lastUpdate = episode.lastUpdatedAt ?? episode.escalatedAt;
-		if (minutesBetween(lastUpdate, now) >= policy.updateAfterMinutes) {
-			decision.update.push({ aggregate, episode });
 		}
+		// An open, delivered episode emits NOTHING while it recurs: the open
+		// emission already happened and the close emission fires when the kind
+		// goes quiet. A cadence-driven "still recurring" repeat is exactly the
+		// silenced-alarm shape `emit-transitions-not-conditions` prohibits.
 	}
 
 	for (const episode of episodes) {
 		if (episode.resolvedAt) continue;
 		const aggregate = aggregateByKind.get(episode.kind);
-		const quietReference = aggregate?.lastSeen ?? episode.lastSeenAt;
+		// A future-dated aggregate lastSeen (producer clock skew) cannot serve
+		// as the quiet reference — it would freeze quietMinutes negative and
+		// hold the episode open forever while the kind is actually quiet. Fall
+		// back to the episode's own last_seen_at, which the bounded aggregate
+		// wrote and is therefore never in the future.
+		const quietReference =
+			aggregate && aggregate.lastSeen.getTime() <= now.getTime() ? aggregate.lastSeen : episode.lastSeenAt;
 		const quietMinutes = minutesBetween(quietReference, now);
 		if (quietMinutes >= policy.resolveAfterMinutes) {
 			decision.resolve.push({ episode, quietMinutes });
@@ -214,14 +206,17 @@ export function composeEscalationMessage(input: {
 	impact: string;
 	recommendation: string;
 	sample: string;
+	/** ISO timestamp + event id of the newest backing row, when resolved —
+	 * cited verbatim so the reader can resolve the claim against event_log. */
+	lastEvent?: { occurredAt: string; eventId: string } | null;
 }): string {
 	const span = formatSpanMinutes(
 		(input.aggregate.lastSeen.getTime() - input.aggregate.firstSeen.getTime()) / 60_000,
 	);
-	const lines = [
-		`🔴 Platform fault: ${input.kind}`,
-		`Observed: ${input.aggregate.count} errors over ${span}, still recurring.`,
-	];
+	const observed = input.lastEvent
+		? `Observed: ${input.aggregate.count} errors over ${span}, last ${input.lastEvent.occurredAt} (event ${input.lastEvent.eventId.slice(0, 8)}).`
+		: `Observed: ${input.aggregate.count} errors over ${span}, last ${input.aggregate.lastSeen.toISOString()}.`;
+	const lines = [`🔴 Platform fault: ${input.kind}`, observed];
 	if (input.sample) lines.push(`Sample: ${input.sample}`);
 	lines.push(`Impact: ${input.impact}`, `Recommendation: ${input.recommendation}`);
 	return lines.join("\n");

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

@@ -24,7 +24,6 @@ const POLICY: FaultEscalationPolicy = {
 	minCount: 10,
 	minSpanMinutes: 25,
 	resolveAfterMinutes: 30,
-	updateAfterMinutes: 30,
 };
 
 function agg(kind: string, count: number, firstSeenMinutesAgo: number, lastSeenMinutesAgo: number): FaultAggregate {
@@ -102,29 +101,20 @@ describe("decideSweep — dedup (one escalation per fault, no re-fire)", () => {
 		expect(decision.escalate).toHaveLength(0);
 	});
 
-	test("open delivered episode past the update window gets an UPDATE, not a message", () => {
+	test("open delivered episode emits NOTHING while it recurs — transitions, not cadence", () => {
+		// 2026-08-26: the hourly "still recurring" comment made the alarm
+		// skippable noise and hid a real signal. An open, delivered episode now
+		// stays silent until the close transition fires (see the resolve suite).
 		const sustained = agg("llm.provider.call.failed", 300, 720, 0);
-		const open = episode({
+		const longOpen = episode({
 			kind: "llm.provider.call.failed",
-			escalatedAt: new Date(NOW.getTime() - 90 * 60_000), // last update long ago
+			escalatedAt: new Date(NOW.getTime() - 90 * 60_000),
 			lastUpdatedAt: new Date(NOW.getTime() - 90 * 60_000),
 		});
-		const decision = decideSweep([sustained], [open], POLICY, NOW);
-		expect(decision.escalate).toHaveLength(0);
-		expect(decision.update).toHaveLength(1);
-		expect(decision.update[0]!.episode.workItemId).toBe("wi-1");
-	});
-
-	test("open episode inside the update window gets NOTHING (dedup window)", () => {
-		const sustained = agg("llm.provider.call.failed", 300, 720, 0);
-		const open = episode({
-			kind: "llm.provider.call.failed",
-			escalatedAt: new Date(NOW.getTime() - 10 * 60_000),
-			lastUpdatedAt: new Date(NOW.getTime() - 10 * 60_000),
-		});
-		const decision = decideSweep([sustained], [open], POLICY, NOW);
+		const decision = decideSweep([sustained], [longOpen], POLICY, NOW);
 		expect(decision.escalate).toHaveLength(0);
-		expect(decision.update).toHaveLength(0);
+		expect(decision.resolve).toHaveLength(0);
+		expect(Object.keys(decision).sort()).toEqual(["escalate", "resolve"]);
 	});
 
 	test("a claimed-but-undelivered episode is RETRIED, not counted as escalated", () => {
@@ -168,6 +158,34 @@ describe("decideSweep — resolution + re-arm", () => {
 	});
 });
 
+describe("decideSweep — a future-dated lastSeen is not recurrence evidence", () => {
+	// 2026-08-26: an escalation sent 08:20Z cited "last at 09:04:54Z" — 44
+	// minutes in its own future. The rows existed (producer envelopes whose
+	// clock ran 70 minutes ahead), and `minutesBetween(lastSeen, now)` went
+	// negative, passing every recency check while the kind was actually quiet.
+	// A timestamp that has not happened yet cannot evidence a fault happening
+	// now — no matter how the aggregate was built.
+	test("a future-dated aggregate does not escalate", () => {
+		const phantom = agg("guard.fail.open", 40, 720, -44);
+		const decision = decideSweep([phantom], [], POLICY, NOW);
+		expect(decision.escalate).toHaveLength(0);
+	});
+
+	test("a future-dated aggregate does not hold an open episode open past the quiet window", () => {
+		// lastSeen 44 min in the future means the kind's real events are quiet:
+		// the episode's own last_seen_at (honest) drives the resolve decision,
+		// and the phantom aggregate must not veto it.
+		const quietEpisode = episode({
+			kind: "guard.fail.open",
+			lastSeenAt: new Date(NOW.getTime() - 60 * 60_000),
+		});
+		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);
+	});
+});
+
 describe("extractGowaMessageId — delivery verification", () => {
 	test("the canonical GOWA SendResponse shape yields results.message_id", () => {
 		expect(extractGowaMessageId({ code: "SUCCESS", results: { message_id: "3EB089B9D6ADD58153C561", status: "sent" } })).toBe(
@@ -196,6 +214,7 @@ describe("composeEscalationMessage", () => {
 			impact: "scala-tools verbs are failing host-wide",
 			recommendation: "check oxmgr logs for the bus consumer",
 			sample: "",
+			lastEvent: null,
 		});
 		expect(message).toContain("Platform fault: host-command-bus.command.failed");
 		expect(message).toContain("Observed: 490 errors over 12 h");
@@ -204,6 +223,22 @@ describe("composeEscalationMessage", () => {
 		expect(message.split("\n")).toHaveLength(4);
 	});
 
+	// 2026-08-26: an escalation sent 08:20Z cited "last at 09:04:54Z", a
+	// timestamp 44 minutes in its own future matching no event the operator
+	// could find. The Observed line now cites the newest backing row's own
+	// occurred_at and id, so "last at T" resolves to a real event_log row.
+	test("cites the newest backing row's timestamp and event id — resolvable evidence", () => {
+		const message = composeEscalationMessage({
+			kind: "guard.fail.open",
+			aggregate: agg("guard.fail.open", 490, 720, 0),
+			impact: "guard enforcement is failing open",
+			recommendation: "check the guard daemon",
+			sample: "",
+			lastEvent: { occurredAt: "2026-08-26T08:20:29Z", eventId: "01a03b79-c124-748f-a79f-a9a436729544" },
+		});
+		expect(message).toContain("last 2026-08-26T08:20:29Z (event 01a03b79)");
+	});
+
 	// 2026-08-26: three escalations reached the orchestrator seat carrying
 	// kind, count and duration only — triaging each required a hand event_log
 	// query, and the llm.provider.call.failed impact line pointed AWAY from
@@ -217,6 +252,7 @@ describe("composeEscalationMessage", () => {
 			sample: 'status=429; message=Usage limit reached for 5 hour. Your limit will reset at 2026-08-26 01:19:03',
 			impact: "AI chat/completion calls are failing",
 			recommendation: "check provider quota",
+			lastEvent: null,
 		});
 		const lines = message.split("\n");
 		expect(lines).toHaveLength(5);

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

@@ -3,46 +3,10 @@
  * @status handwritten @indivisible-unit
  * @edit edit directly
  *
- * The `platform-fault-escalation` pg-boss handler — closes the "receiving is
- * decoupled from consequence" gap measured 2026-08-15 (760 error events over
- * 12 hours, zero escalations: host-command-bus.command.failed (then spelled
- * host-command-bus.error) 490, llm.provider.call.failed (then spelled
- * llm.provider.error) 231, guard.fail.open 16, scale-to-zero.wake_failed 12,
- * listen.connect_failed 11). Emission works and observability-is-passive is satisfied; nothing
- * acted. This sweep makes RECEIVING have CONSEQUENCE: sustained platform
- * faults escalate to the OPERATOR over the existing PA path (WhatsApp, the
- * scala PA operator-relay bot — escalation-routing's channel; no second
- * channel invented), with the durable record as a work_items task the PA can
- * read back and the operator can answer on.
- *
- * THIS IS NOT A DRIFT-DETECTOR PATROLLING INSTANCES. It reacts only to
- * components reporting THEIR OWN failure — event_log kinds that already
- * assert a fault about their emitter. Thresholds (duration + recurrence,
- * never a single event), the watched-kind patterns, the resolve window, the
- * per-kind impact/recommendation copy and the per-kind payload sample-field
- * whitelists are all in the
- * `config/platform-fault-escalation` registry row — changing policy is a row
- * edit, not a redeploy. Episode dedup lives in the
- * `platform_fault_escalations` table (migration 501): one escalation per
- * distinct fault kind per episode; an already-escalated-and-unresolved fault
- * only appends throttled work-item comments, never a second message.
- *
- * DELIVERY IS VERIFIED, NOT QUEUED. The WhatsApp send goes through the
- * central `/mcp` loopback (`api_gowa_message` sendMessage — the single
- * sealed GOWA-credential surface, same as whatsapp-liveness) and an episode
- * only carries `escalated_at` once the send returned a WhatsApp message id;
- * before that the row is a CLAIM the next sweep retries. Success is recorded
- * only after readback of the delivery facts (message id + work item id).
- *
- * WHY A TICK EXISTS AT ALL, given observability-is-passive and
- * no-polling-for-pushable-state: the trigger is DURATION + RECURRENCE of
- * events already durably logged — a fact about the PATTERN of past events,
- * not a state transition any single event can announce. The sweep reads one
- * server-side aggregate (GROUP BY kind) per run against indexed event_log;
- * while the platform is healthy it returns zero rows and costs nothing
- * beyond the tick (idle-costs-nothing).
- *
- * Registered under slug `@teamscala/service-boot:platform-fault-escalation`.
+ * The `platform-fault-escalation` pg-boss handler. Full contract in curated
+ * `apps/escalation.md` — episodes EMIT ON TRANSITIONS ONLY; evidence bounded
+ * `occurred_at <= now()` and cited by resolvable event id; delivery verified
+ * by WhatsApp message id before `escalated_at` is recorded.
  */
 import type { ExecutionContext } from "@teamscala/os/contracts/mcp";
 import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
@@ -82,7 +46,6 @@ const FaultEscalationConfigSchema = v.object({
 		),
 	),
 	resolve_after_minutes: v.number(),
-	update_after_minutes: v.number(),
 	/** The orchestrator's work item — escalations are COMMENTS on it, never
 	 * task rows (the fleet-task-placement CHECK constraint refuses a system
 	 * task without session identity, and an escalation is a finding, not an
@@ -204,6 +167,11 @@ async function fetchAggregates(patterns: string[], windowMinutes: number): Promi
 	// Patterns come from the valibot-validated registry row and are regex-only
 	// by construction below; embedding them as one alternation keeps the query
 	// parameter-free on the pattern side while the window is a real parameter.
+	// The window is bounded on BOTH sides by the database's own statement
+	// clock: `occurred_at` is producer-claimed, and an unbounded top edge
+	// admits rows stamped in the future by a skewed or mocked producer clock —
+	// which then fabricate "still recurring" for a quiet fault (measured
+	// 2026-08-26). A future row is not evidence of anything happening now.
 	const regexClass = /^[A-Za-z0-9_\\^$.*+?()[\]{}|-]+$/;
 	for (const pattern of patterns) {
 		if (!regexClass.test(pattern)) {
@@ -213,10 +181,11 @@ async function fetchAggregates(patterns: string[], windowMinutes: number): Promi
 	const combined = `(${patterns.join("|")})`;
 	const rows = await prisma.$queryRawUnsafe<EventLogAggregateRow[]>(
 		`SELECT kind, count(*)::bigint AS n, min(occurred_at) AS first_seen, max(occurred_at) AS last_seen
-		 FROM event_log
-		 WHERE occurred_at > now() - ($1::int * interval '1 minute')
-		   AND kind ~ $2::text
-		 GROUP BY kind`,
+			 FROM event_log
+			 WHERE occurred_at > now() - ($1::int * interval '1 minute')
+			   AND occurred_at <= now()
+			   AND kind ~ $2::text
+			 GROUP BY kind`,
 		windowMinutes,
 		combined,
 	);
@@ -229,31 +198,47 @@ async function fetchAggregates(patterns: string[], windowMinutes: number): Promi
 }
 
 /**
- * The message's evidence line: the whitelisted sample fields from the most
- * recent payload for the kind. Field names come from the valibot-validated
- * config row and are constrained to bare identifiers below, so the JSON path
- * cannot break out of the string; only the named keys are selected, so an
- * unlisted field is unreachable by construction rather than filtered later.
+ * The message's evidence: the whitelisted sample fields AND the row identity
+ * (id + occurred_at) of the newest payload for the kind. Field names come
+ * from the valibot-validated config row and are constrained to bare
+ * identifiers below, so the JSON path cannot break out of the string. The
+ * `occurred_at <= now()` bound matches the aggregate's top edge: the cited
+ * "last" row must be a real, non-future event whose id rides in the message
+ * so the claim resolves against event_log.
  */
-async function fetchLatestPayloadSample(kind: string, fields: string[]): Promise<string> {
-	if (fields.length === 0) return "";
+async function fetchLatestEvidence(
+	kind: string,
+	fields: string[],
+): Promise<{ sample: string; lastEvent: { occurredAt: string; eventId: string } | null }> {
+	const prisma = getPrisma();
+	if (fields.length === 0) {
+		const rows = await prisma.$queryRawUnsafe<Array<{ id: unknown; occurred_at: Date }>>(
+			`SELECT id::text, occurred_at
+				 FROM event_log
+				 WHERE kind = $1::text AND occurred_at <= now()
+				 ORDER BY occurred_at DESC
+				 LIMIT 1`,
+			kind,
+		);
+		const top = rows[0];
+		return { sample: "", lastEvent: top ? { occurredAt: isoSeconds(top.occurred_at), eventId: String(top.id) } : null };
+	}
 	for (const field of fields) {
 		if (!/^[A-Za-z0-9_]+$/.test(field)) {
 			throw new Error(`config/${CONFIG_SLUG}: sample_fields entry is not a bare field name: ${field}`);
 		}
 	}
 	const selection = fields.map((field) => `payload_json->'${field}' AS "${field}"`).join(", ");
-	const prisma = getPrisma();
 	const rows = await prisma.$queryRawUnsafe<Array<Record<string, unknown>>>(
-		`SELECT ${selection}
-			 FROM event_log
-			 WHERE kind = $1::text
-			 ORDER BY occurred_at DESC
-			 LIMIT 1`,
+		`SELECT id::text, occurred_at, ${selection}
+				 FROM event_log
+				 WHERE kind = $1::text AND occurred_at <= now()
+				 ORDER BY occurred_at DESC
+				 LIMIT 1`,
 		kind,
 	);
 	const row = rows[0];
-	if (!row) return "";
+	if (!row) return { sample: "", lastEvent: null };
 	const parts: string[] = [];
 	for (const field of fields) {
 		const value = row[field];
@@ -261,7 +246,19 @@ async function fetchLatestPayloadSample(kind: string, fields: string[]): Promise
 		const formatted = formatEscalationSample(value);
 		if (formatted) parts.push(`${field}=${formatted}`);
 	}
-	return parts.join("; ");
+	return {
+		sample: parts.join("; "),
+		lastEvent: {
+			occurredAt: isoSeconds(row.occurred_at as string | Date),
+			eventId: String(row.id),
+		},
+	};
+}
+
+/** ISO-8601 to whole seconds — the same precision event_log stores, so the
+ * cited string round-trips a `WHERE occurred_at = '<cited>'` query. */
+function isoSeconds(value: Date | string): string {
+	return new Date(value).toISOString().replace(/\.\d{3}Z$/, "Z");
 }
 
 async function resolveOperatorRelay(): Promise<OperatorRelayBot> {
@@ -323,11 +320,12 @@ async function deliverEscalation(
 	const bot = await resolveOperatorRelay();
 	const operatorPhone = (bot.flow_config as { operator_phone?: string }).operator_phone!;
 	const copy = config.copy[kind] ?? config.default_copy;
-	const sample = await fetchLatestPayloadSample(kind, config.sample_fields?.[kind] ?? []);
+	const { sample, lastEvent } = await fetchLatestEvidence(kind, config.sample_fields?.[kind] ?? []);
 	const message = composeEscalationMessage({
 		kind,
 		aggregate,
 		sample,
+		lastEvent,
 		impact: copy.impact,
 		recommendation: copy.recommendation,
 	});
@@ -390,6 +388,8 @@ async function deliverEscalation(
 			event_kind: kind,
 			count: aggregate.count,
 			sample,
+			last_event_id: lastEvent?.eventId ?? null,
+			last_event_occurred_at: lastEvent?.occurredAt ?? null,
 			work_item_id: config.orchestrator_work_item_id,
 			delivered_comment_id: comment.id,
 			delivered_message_id: messageId,
@@ -398,33 +398,6 @@ async function deliverEscalation(
 	return { messageId, workItemId: config.orchestrator_work_item_id };
 }
 
-async function updateEpisode(aggregate: FaultAggregate, episode: EscalationEpisode): Promise<void> {
-	const now = new Date();
-	await (await orpc()).platform_fault_escalations.update({
-		where: { kind: episode.kind },
-		data: {
-			last_seen_at: aggregate.lastSeen.toISOString(),
-			event_count: aggregate.count,
-			last_updated_at: now.toISOString(),
-			updated_at: now.toISOString(),
-		},
-	});
-	if (episode.workItemId) {
-		await (await orpc()).comments.create({
-			data: {
-				work_item_id: episode.workItemId,
-				content: `Still recurring: ${aggregate.count} events, last at ${aggregate.lastSeen.toISOString()}. No new escalation (already escalated and unresolved).`,
-				sender_role: "system",
-				sender_name: "platform-fault-escalation",
-			},
-		});
-	}
-	recordEvent({
-		kind: "platform.fault.updated",
-		payload: { event_kind: episode.kind, count: aggregate.count, work_item_id: episode.workItemId },
-	});
-}
-
 async function resolveEpisode(episode: EscalationEpisode, quietMinutes: number): Promise<void> {
 	const now = new Date();
 	await (await orpc()).platform_fault_escalations.update({
@@ -493,7 +466,6 @@ async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig })
 			minCount: config.min_count,
 			minSpanMinutes: config.min_span_minutes,
 			resolveAfterMinutes: config.resolve_after_minutes,
-			updateAfterMinutes: config.update_after_minutes,
 		},
 		now,
 		kindThresholds,
@@ -514,13 +486,6 @@ async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig })
 			recordEvent({ kind: "platform.fault.escalation_failed", payload: { event_kind: aggregate.kind, reason } });
 		}
 	}
-	for (const { aggregate, episode } of decision.update) {
-		try {
-			await updateEpisode(aggregate, episode);
-		} catch (err) {
-			log.error(`[platform-fault-escalation] update for '${episode.kind}' failed: ${err instanceof Error ? err.message : String(err)}`);
-		}
-	}
 	for (const { episode, quietMinutes } of decision.resolve) {
 		try {
 			await resolveEpisode(episode, quietMinutes);
@@ -536,18 +501,17 @@ async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig })
 		payload: {
 			watched_kinds: aggregates.length,
 			escalated: decision.escalate.length,
-			updated: decision.update.length,
 			resolved: decision.resolve.length,
 		},
 	});
-	if (decision.escalate.length > 0 || decision.update.length > 0 || decision.resolve.length > 0) {
+	if (decision.escalate.length > 0 || decision.resolve.length > 0) {
 		log.info(
-			`[platform-fault-escalation] sweep — ${aggregates.length} kind(s) watched, ${decision.escalate.length} escalated, ${decision.update.length} updated, ${decision.resolve.length} resolved`,
+			`[platform-fault-escalation] sweep — ${aggregates.length} kind(s) watched, ${decision.escalate.length} escalated, ${decision.resolve.length} resolved`,
 		);
 	}
-}
+	}
 
-pgBossHandlerRegistry.register(
+	pgBossHandlerRegistry.register(
 	"@teamscala/service-boot:platform-fault-escalation",
 	platformFaultEscalationSweep as (ctx: { config: ScheduledJobConfig }) => Promise<void>,
 );

package/src/mount-orpc-router.ts

@@ -87,6 +87,14 @@ export async function mountOrpcRouter(
 		configureToolExecutor({
 			getAppRouter: () => getAppRouter(),
 			getPrisma: () => getConfiguredPrisma(),
+			// Central MCP gateway URL — sdk:* tool calls from any non-host service
+			// forward here (scala-mcp owns every @teamscala/api-* adapter per
+			// operator ruling 2026-08-26). The HTTP layer reads from the
+			// per-request config surface (the same place getAppRouter / getPrisma
+			// are resolved from), not the ambient environment, to honour
+			// `configured-primitives`.
+			getMcpGatewayUrl: () =>
+				(ctx as { config?: { MCP_GATEWAY_URL?: string } }).config?.MCP_GATEWAY_URL,
 		});
 
 		const resolveUser = async (headers: Headers) => {