@teamscala/service-boot 0.23.429 → 0.23.430

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.429",
+  "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

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

@@ -244,6 +244,17 @@ export function episodeNeedsRefresh(
 	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

@@ -21,7 +21,7 @@
  * episode immediately instead of after its configured resolve window.
  */
 import { describe, expect, test } from "bun:test";
-import { episodeNeedsRefresh } from "./platform-fault-escalation-logic.ts";
+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) });
@@ -59,3 +59,27 @@ describe("episodeNeedsRefresh", () => {
 		);
 	});
 });
+
+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

@@ -119,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);