@teamscala/service-boot 0.23.406 → 0.23.408

package/package.json

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

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 });
@@ -176,39 +168,56 @@ export function extractGowaMessageId(sendResult: unknown): string | null {
 	return null;
 }
 
+/**
+ * One sampled payload value rendered for the message's evidence line: a
+ * kind+count escalation is a pointer to evidence, not evidence (2026-08-26:
+ * the llm.provider.call.failed payloads held our own bounded-output contract
+ * violations while the escalation's impact line named healthy providers).
+ * JSON-encoded when non-string so structure survives, whitespace-collapsed
+ * to one line, credential shapes redacted before truncation (a hard cut can
+ * never expose the tail of a secret the length limit happened to spare),
+ * hard-truncated with an ellipsis so the reader knows the cut happened.
+ */
+export function formatEscalationSample(value: unknown): string {
+	const maxChars = 200;
+	const redactions: ReadonlyArray<[RegExp, string]> = [
+		[/\b(?:sk|gsk|ghp|gho|xox[baprs])[-_][A-Za-z0-9_-]{8,}/g, "[redacted]"],
+		[/\b(api[_-]?key|token|password|secret|authorization)\b["'=:\s]+(?:(?:bearer|basic)\s+)?[A-Za-z0-9._~+/=-]{4,}/gi, "$1=[redacted]"],
+		[/Bearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, "Bearer [redacted]"],
+	];
+	const raw = typeof value === "string" ? value : (JSON.stringify(value) ?? "");
+	if (raw.length === 0) return "";
+	const redacted = redactions.reduce((acc, [pattern, replacement]) => acc.replace(pattern, replacement), raw);
+	const collapsed = redacted.replace(/\s+/g, " ").trim();
+	return collapsed.length > maxChars ? `${collapsed.slice(0, maxChars)}…` : collapsed;
+}
+
 /**
  * The escalation message — escalation-routing's three-field contract adapted
- * to an automated detector: what was OBSERVED (evidence), what it MEANS
- * (impact), and the RECOMMENDATION. Short: the channel is a phone.
+ * to an automated detector: what was OBSERVED (evidence + sample), what it
+ * MEANS (impact), and the RECOMMENDATION. Short: the channel is a phone. The
+ * sample line is the triage evidence — `sample_fields` whitelisted per kind
+ * by the caller, formatted by formatEscalationSample; empty means the kind
+ * samples nothing or the latest payload carried none of its fields.
  */
 export function composeEscalationMessage(input: {
 	kind: string;
 	aggregate: FaultAggregate;
 	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,
 	);
-	return [
-		`🔴 Platform fault: ${input.kind}`,
-		`Observed: ${input.aggregate.count} errors over ${span}, still recurring.`,
-		`Impact: ${input.impact}`,
-		`Recommendation: ${input.recommendation}`,
-	].join("\n");
-}
-
-/** The work-item description carries the same three fields plus the evidence. */
-export function composeEscalationDescription(input: {
-	aggregate: FaultAggregate;
-	impact: string;
-	recommendation: string;
-}): string {
-	return [
-		"Automated platform-fault escalation (platform-fault-escalation sweep).",
-		`Observed: ${input.aggregate.count} '${input.aggregate.kind}' events in event_log from ${input.aggregate.firstSeen.toISOString()} to ${input.aggregate.lastSeen.toISOString()}, still recurring.`,
-		`Impact: ${input.impact}`,
-		`Recommendation: ${input.recommendation}`,
-		"Delivery: WhatsApp via the scala PA. This task closes automatically when the fault stops for the resolve window; reply via the PA to rule otherwise.",
-	].join("\n");
+	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

@@ -13,6 +13,7 @@ import {
 	composeEscalationMessage,
 	decideSweep,
 	extractGowaMessageId,
+	formatEscalationSample,
 	type EscalationEpisode,
 	type FaultAggregate,
 	type FaultEscalationPolicy,
@@ -23,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 {
@@ -101,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", () => {
@@ -167,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(
@@ -194,6 +213,8 @@ describe("composeEscalationMessage", () => {
 			aggregate: agg("host-command-bus.command.failed", 490, 720, 0),
 			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");
@@ -201,6 +222,74 @@ describe("composeEscalationMessage", () => {
 		expect(message).toContain("Recommendation: check oxmgr logs for the bus consumer");
 		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
+	// the defect (payloads held our own 'Invalid length: Expected <=1200 but
+	// received 1255' contract violations recorded against healthy providers).
+	// The sample line carries the evidence in the first read.
+	test("carries the sampled payload evidence as its own line", () => {
+		const message = composeEscalationMessage({
+			kind: "llm.provider.call.failed",
+			aggregate: agg("llm.provider.call.failed", 26, 560, 0),
+			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);
+		expect(lines[2]).toContain("Sample: status=429");
+		expect(lines[2]).toContain("reset at 2026-08-26 01:19:03");
+	});
+});
+
+describe("formatEscalationSample — evidence truncated hard, secrets never shipped", () => {
+	test("non-string values are JSON-encoded so structure survives the phone channel", () => {
+		expect(formatEscalationSample(429)).toBe("429");
+		expect(formatEscalationSample(true)).toBe("true");
+		expect(formatEscalationSample({ expected: 1200, received: 1255 })).toBe('{"expected":1200,"received":1255}');
+	});
+
+	test("truncates hard at the bound with an ellipsis so the reader knows the cut happened", () => {
+		const formatted = formatEscalationSample("x".repeat(500));
+		expect(formatted.length).toBe(201); // 200 chars + ellipsis
+		expect(formatted.endsWith("…")).toBe(true);
+	});
+
+	test("redacts credential shapes before truncation — a cut can never expose a secret tail", () => {
+		expect(formatEscalationSample("key sk-abcdefghijklmnopqrstuvwxyz failed")).toBe("key [redacted] failed");
+		expect(formatEscalationSample("Authorization: Bearer abcdefghijklmnop")).toBe(
+			"Authorization=[redacted]",
+		);
+		expect(formatEscalationSample("api_key=abcdefgh1234 rejected")).toBe("api_key=[redacted] rejected");
+	});
+
+	test("collapses whitespace to one line — the sample is one message line", () => {
+		expect(formatEscalationSample("line one\nline two\t tabbed")).toBe("line one line two tabbed");
+	});
+
+	test("empty input yields an empty sample (no Sample line)", () => {
+		expect(formatEscalationSample(undefined)).toBe("");
+		expect(formatEscalationSample("")).toBe("");
+	});
 });
 
 describe("decideSweep — qualification asks 'is this happening', not 'did this happen'", () => {

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

@@ -3,45 +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 and
- * the per-kind impact/recommendation copy 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";
@@ -52,10 +17,10 @@ import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
 import {
-	composeEscalationDescription,
 	composeEscalationMessage,
 	decideSweep,
 	extractGowaMessageId,
+	formatEscalationSample,
 	type EscalationEpisode,
 	type FaultAggregate,
 	type KindThresholdOverride,
@@ -81,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
@@ -90,6 +54,10 @@ const FaultEscalationConfigSchema = v.object({
 	/** Per-kind copy for the message (impact + recommendation). Falls back to default_copy. */
 	copy: v.record(v.string(), v.object({ impact: v.string(), recommendation: v.string() })),
 	default_copy: v.object({ impact: v.string(), recommendation: v.string() }),
+	/** Per-kind payload-field whitelist sampled into the message's evidence
+	 * line — named fields ONLY, never the whole payload: some kinds embed
+	 * request context, and the escalation channel is WhatsApp. */
+	sample_fields: v.optional(v.record(v.string(), v.array(v.string()))),
 });
 
 type FaultEscalationConfig = v.InferOutput<typeof FaultEscalationConfigSchema>;
@@ -128,8 +96,9 @@ async function getSystemIdentity(): Promise<{ userId: string | undefined; organi
  * BACKEND service, where the page-server client is never registered — the
  * empty-router fallback returns a client with no model namespaces (the
  * TypeError this replaced). Per `no-direct-prisma-outside-orpc`, every WRITE
- * in this handler routes through this client; the single raw read (the
- * event_log recurrence aggregate, a GROUP BY no generated CRUD expresses) uses
+ * in this handler routes through this client; the two raw reads (the
+ * event_log recurrence aggregate and the latest-payload sample, shapes no
+ * generated CRUD expresses) use
  * the assigned-client form with $queryRawUnsafe. Timestamps are ISO strings,
  * never Date instances (the generated valibot schemas require it).
  */
@@ -184,9 +153,6 @@ interface OrpcSurface {
 	messaging_bots: {
 		findFirst(args: Record<string, unknown>): Promise<Record<string, unknown> | null>;
 	};
-	work_items: {
-		create(args: { data: Record<string, unknown>; select?: Record<string, unknown> }): Promise<{ id: string }>;
-	};
 	comments: {
 		create(args: { data: Record<string, unknown> }): Promise<{ id: string }>;
 	};
@@ -201,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)) {
@@ -210,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,
 	);
@@ -225,6 +197,70 @@ async function fetchAggregates(patterns: string[], windowMinutes: number): Promi
 	}));
 }
 
+/**
+ * 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 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 rows = await prisma.$queryRawUnsafe<Array<Record<string, unknown>>>(
+		`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 { sample: "", lastEvent: null };
+	const parts: string[] = [];
+	for (const field of fields) {
+		const value = row[field];
+		if (value === null || value === undefined) continue;
+		const formatted = formatEscalationSample(value);
+		if (formatted) parts.push(`${field}=${formatted}`);
+	}
+	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> {
 	const bot = (await (await orpc()).messaging_bots.findFirst({
 		where: {
@@ -284,9 +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, lastEvent } = await fetchLatestEvidence(kind, config.sample_fields?.[kind] ?? []);
 	const message = composeEscalationMessage({
 		kind,
 		aggregate,
+		sample,
+		lastEvent,
 		impact: copy.impact,
 		recommendation: copy.recommendation,
 	});
@@ -325,12 +364,7 @@ async function deliverEscalation(
 	const comment = await (await orpc()).comments.create({
 		data: {
 			work_item_id: config.orchestrator_work_item_id,
-			content: composeEscalationMessage({
-				kind,
-				aggregate,
-				impact: copy.impact,
-				recommendation: copy.recommendation,
-			}),
+			content: message,
 			source_cli_session_id: null,
 		},
 	});
@@ -353,6 +387,9 @@ async function deliverEscalation(
 		payload: {
 			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,
@@ -361,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({
@@ -456,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,
@@ -477,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);
@@ -499,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>,
 );