@open-everywhere/core 0.1.0

package/agent/control/delivery-history.ts

@@ -0,0 +1,558 @@
+// DELIVERY AUDIT READ MODEL (OPE-212) — the durable answer to "my webhook is wired up, so why did
+// nothing happen?", assembled from rows the ingress and the fan-out ALREADY write.
+//
+// ── IT IS A READ MODEL. IT ADDS NO STORAGE, AND THAT IS THE DESIGN, NOT A SHORTCUT ──────────────
+// Every fact below is already durable somewhere: `webhook.fired` / `webhook.declined` (one row per
+// ACCEPTED delivery, unthrottled — channels/webhooks.ts), `webhook.rejected` (throttled, one per
+// identity per minute — webhooks/reject-audit.ts), and the fan-out's own `routine.fire` /
+// `routine.skip` / `routine.fire_lost` (routines/fire-audit.ts). What did NOT exist was anything
+// that JOINED them: the delivery rows live under the hook's target partition, the routine rows under
+// each ROUTINE's partition, and no query spanned both. So "the hook is delivering AND my routine is
+// refused" was two separate investigations by two different people, and the honest answer to "why
+// didn't it fire" was "read the audit log yourself".
+//
+// 🔴 NO PAYLOAD BODY IS READ, RETURNED OR PERSISTED ON ANY PATH IN THIS FILE. The audit code refuses
+// to copy sender-supplied bytes into a tamper-evident table (audit/audit.ts, and the raw-body
+// discipline in channels/webhooks.ts), and this reader inherits that refusal rather than restating
+// it: it reads `AuditEntry.detail`, which holds ids, counts, reasons and byte COUNTS and never a
+// body. `bytes` is a number. There is no branch here that can reach a request body, because no
+// request body was ever stored for one to reach.
+//
+// ⚠️ CORRECTED, BECAUSE THE FORWARD REFERENCE CAME TRUE: temporary capture SHIPPED (OPE-211) as a
+// separate table (`webhook_capture`), a separate read model (`control/capture-window-read.ts`) and a
+// separate arming act. It retains the jq FILTER DOCUMENT, never the raw body or the headers, and
+// only inside an explicitly-armed window. Everything above still describes THIS file exactly — no
+// path here reaches that table — but the claim "no request body was ever stored" is now a statement
+// about this reader's inputs, not about the deployment as a whole. `resolveHook` below is shared
+// with that read model on purpose: one hook-resolution and one `readableBy` gate for both, because
+// two differently-shaped gates over the same hooks is how a hole opens.
+//
+// ── WHY MISSES, NOT JUST HITS (doctrine 7: "audit what went unmatched") ─────────────────────────
+// A history that shows only fires cannot answer the question it exists for — the interesting rows
+// are exactly the ones a hits-only model discards. Three miss classes are surfaced, all pre-existing:
+//   • REFUSED AT THE DOOR — `webhook.rejected` (bad signature, unknown id, oversized, replayed). The
+//     sender thinks it is delivering; nothing here ever saw a routable event.
+//   • ACCEPTED, MATCHED NOTHING — a delivery row whose `matched` is 0. The hook works and the filter
+//     does not. (Distinguishing "filter wrong" from "nothing has arrived" is `firstMatchAt` /
+//     `lastMatchAt` on the routine itself — OPE-184; this side says whether anything ARRIVED.)
+//   • MATCHED, THEN REFUSED — `routine.skip`, carrying the closed {@link RoutineSkipReason}. This is
+//     the one that kills the silent-failure class: a zero-domain hook (OPE-206) now reads as
+//     "matched, refused: grant_refused" instead of as nothing at all.
+//
+// ⭐ NO NEW REASON VOCABULARY IS MINTED HERE. Misses are reported with `RoutineSkipReason`'s values
+// VERBATIM (routines/fire-audit.ts) — the same closed set the fan-out writes and the same set
+// docs/capabilities/proactivity-and-routines.md tabulates. channels/ambient-skip.ts's header asks
+// that this read model share its vocabulary rather than grow a second one; the shape that honours it
+// is one ANSWER SURFACE over the existing sets, not a merged enum. The two sets stay distinct because
+// they answer different questions about different planes — `AmbientSkip` ("no-domain" /
+// "domain-refused") is about whether a SURFACE's standing supervisor engaged, written only by the
+// provider chat/issue ingresses, and is not attributable to a hook — and a union enum would have to
+// pick one word for two facts. What is shared is the rule: a reason string here is always a value
+// some existing writer already emits, never one this reader invented.
+//
+// ── THE GATE IS `readableBy`, AND IT IS LITERALLY THE FIRE GATE ────────────────────────────────
+// The authorization argument in one line: **if a routine on this surface could have been FIRED by
+// this hook, this surface may READ that hook's delivery history.** It is not an analogy — the check
+// below calls the same two functions the fire path calls (`resolveAccessForPartition` +
+// `scopeGrantsRead`, routines/event-authz.ts + access/read-grant.ts), in the same order, so the read
+// boundary cannot drift from the fire boundary by anyone editing one and not the other. A second,
+// hand-rolled copy of "may this surface see this hook" is exactly the divergence `readableBy` was
+// reinstated to end (access/read-grant.ts rule 1).
+//
+// That is also why the read is ORG-WIDE over the hook rather than partition-pinned the way
+// routines/fire-audit.ts's `listRoutineFires` is. The rows it needs are written in several
+// partitions by construction, so partition-pinning would silently return a fraction of the truth —
+// which for a diagnostic is worse than refusing. The scope of the query is therefore not the
+// boundary here; `readableBy` is, which is the whole point of it existing.
+//
+// 🔴 A REFUSAL NAMES THE GRANT. A hook readable by nobody is the live defect this ticket's bonus is
+// about, so refusing silently would reproduce it one layer up. The refusal renders the grant through
+// `describeReadableBy`, whose empty case is the sentence "NOBODY (no routine can ever read this
+// hook's events)" — so asking about a dead hook TELLS YOU IT IS DEAD.
+//
+// ── VOLUME ──────────────────────────────────────────────────────────────────────────────────────
+// The firehose this ticket had to avoid is a row PER DELIVERY on a busy unrouted source. This module
+// cannot cause one: it writes no per-delivery row, because it writes nothing on the delivery path at
+// all. Its only write is ONE `webhook.history_read` row per READ — a model- or human-initiated
+// action inside a paid turn, which is the same volume class as `routine.transcript_read` and
+// `control.service_call` and is unthrottled for the same reason. That property is asserted rather
+// than asserted-in-prose: scripts/webhook-history-test.ts drives a fixture with many deliveries and
+// many misses through {@link readDeliveryHistory} and fails if the injected audit sink sees anything
+// other than exactly one row.
+//
+// The throttles on the rows it READS are a different matter, and the model must not launder them
+// into a false per-delivery story: `routine.skip` is one row per (routine, reason) per hour and
+// `webhook.rejected` one per identity per minute, each carrying the count it stands in for. So every
+// miss below reports `standsFor`, and {@link DeliveryHistory} carries `throttled` to say so in
+// words. The absence of a miss row is NOT proof a delivery was fine — it may have been suppressed —
+// and the read model says that rather than implying otherwise.
+//
+// ── THE READ IS AUDITED ─────────────────────────────────────────────────────────────────────────
+// `webhook.history_read`, mirroring `routine.transcript_read` (control/transcript-relay.ts): ids and
+// counts only, never content, written where the disclosure actually happens. Both verdicts are
+// recorded — a REFUSED read is the more interesting row, since it is the trace of someone asking
+// about a hook their domain cannot read. A read of an UNKNOWN source writes nothing, deliberately:
+// the source name is caller-supplied and unbounded, and webhooks/reject-audit.ts's rule ("the
+// throttle key must not contain an attacker-chosen string", and the row's labels likewise) applies
+// to any row a caller can mint the identity of. Once a hook has RESOLVED, every field in the row is
+// host-owned.
+
+import { appendAudit, readAudit, type AuditEntry, type AuditFilter, type AuditInput } from "../audit/audit.js";
+import { getConfig } from "../access/config.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { describeReadableBy, scopeGrantsRead, type ReadableBy } from "../access/read-grant.js";
+import type { EffectiveAccess } from "../access/resolver.js";
+import { resolveAccessForPartition } from "../routines/event-authz.js";
+import { FORENSIC_SCAN_LIMIT, FORENSIC_WINDOW_MS, ROUTINE_AUDIT } from "../routines/fire-audit.js";
+import { isEventTrigger } from "../routines/event-match.js";
+import { listAllRoutines } from "../routines/store.js";
+import { findWebhook, type WebhookHook } from "../webhooks/config.js";
+import type { Partition } from "../memory/partition.js";
+import type { Routine } from "../routines/routine.js";
+
+/** The audit action a history read writes about itself. Sibling of `routine.transcript_read`.
+ *  ATTRIBUTED since OPE-295 item 7 — the row already carried the room, the hook and the verdict, and
+ *  left the acting principal unset, so "who ran this read" was the one thing it could not answer. */
+export const WEBHOOK_HISTORY_READ = "webhook.history_read";
+
+/** The delivery actions this model reads. Deliberately the constants, not literals scattered about. */
+const WEBHOOK_DELIVERY_ACTIONS = {
+  fired: "webhook.fired",
+  declined: "webhook.declined",
+  rejected: "webhook.rejected",
+} as const;
+
+/** The look-back window. THE SAME 7 days routine forensics uses (routines/fire-audit.ts), on purpose:
+ *  "what a delivery history can reach" must equal "what the run history in `list_routines` already
+ *  showed", or the two diagnostics disagree about whether something happened. */
+const HISTORY_WINDOW_MS = FORENSIC_WINDOW_MS;
+
+/** Row ceiling on each underlying audit scan. Counts are therefore "over at most the newest N rows
+ *  in the window" — stated, not silently approximated. Shared with routine forensics for the same
+ *  reason the window is. */
+const HISTORY_SCAN_LIMIT = FORENSIC_SCAN_LIMIT;
+
+/** How many individual deliveries come back, newest-first. Small on purpose: this is a page rendered
+ *  into a model's context, and the counts above it already carry the volume story. */
+export const HISTORY_MAX_DELIVERIES = 25;
+
+/** Per-routine miss rows returned, newest-first — each already stands for up to an hour of its own
+ *  (routine, reason) pair, so a handful covers a day. */
+const HISTORY_MAX_MISSES = 10;
+
+/** Cap on any string this model copies out of an audit row's `detail`. Those strings originate
+ *  off-host (a vendor's rejection text, jq's own evaluator message) and are not ours to trust as
+ *  short — the same bound webhooks/reject-audit.ts and `auditRoutineFireLost` already apply on the
+ *  way IN, re-applied on the way OUT so a row written before those caps existed cannot flood a page. */
+export const HISTORY_DETAIL_MAX_CHARS = 300;
+
+/** How a delivery was authenticated, as the audit rows record it. Not a new vocabulary — each value
+ *  is the reading of a flag `channels/webhooks.ts` already stamps. */
+export type DeliveryVerification = "signed" | "previous-key" | "unverified" | "refused";
+
+/** One delivery, as the permanent metadata says it happened. NO PAYLOAD — `bytes` is a count. */
+export interface DeliveryRecord {
+  /** When the row was written (the ingress's own clock). */
+  readonly at: string;
+  /** `fired` / `declined` = it passed the gate; `rejected` = it never did. */
+  readonly outcome: "fired" | "declined" | "rejected";
+  /** The SENDER's delivery id when the source declares a header for one (OPE-201), else null.
+   *  Length-capped: the value is sender-supplied. */
+  readonly deliveryId: string | null;
+  /** Body size in bytes. A COUNT — the bytes themselves were never stored. */
+  readonly bytes: number | null;
+  readonly verification: DeliveryVerification;
+  /** HTTP status, for a rejection (401/404/409/413). Null for an accepted delivery. */
+  readonly status: number | null;
+  /** Why it was rejected/declined, or why the routing plane could not route it. Capped. */
+  readonly reason: string | null;
+  /** Fan-out counters, present for an accepted delivery: how many event routines matched, how many
+   *  fired, how many matched-then-skipped. `matched: 0` is the "the hook works, the filter does not"
+   *  reading. Null when the delivery never reached the routing plane. */
+  readonly matched: number | null;
+  readonly fired: number | null;
+  readonly skipped: number | null;
+  /** How many further rows this one stands in for (rejections are throttled). 0 = exactly one. */
+  readonly standsFor: number;
+}
+
+/** One miss against one routine: the closed {@link RoutineSkipReason} plus its own throttle count. */
+export interface RoutineMiss {
+  readonly at: string;
+  /** A `RoutineSkipReason` value verbatim, or `fire_lost` for a rejected dispatch. */
+  readonly reason: string;
+  /** The row's own supporting field, capped — jq's message for `filter_invalid`, the refusing
+   *  partition for `grant_refused`, the delivery error for `fire_lost`. Null when the reason says
+   *  everything (`fanout_cap`). */
+  readonly detail: string | null;
+  /** How many suppressed rows this one stands in for (skips are throttled per routine+reason/hour). */
+  readonly standsFor: number;
+}
+
+/** What one subscribing routine did with this hook's deliveries over the window. */
+export interface SubscriberOutcome {
+  readonly routineId: string;
+  readonly status: string;
+  readonly surfaceKey: string;
+  /** Completed fires in the window (`routine.fire` rows). */
+  readonly fires: number;
+  readonly lastFireAt: string | null;
+  /** Misses, newest-first, capped at {@link HISTORY_MAX_MISSES}. */
+  readonly misses: readonly RoutineMiss[];
+}
+
+/** The composed answer. Every number is "over at most {@link HISTORY_SCAN_LIMIT} rows in the window". */
+export interface DeliveryHistory {
+  /** The hook's MODEL-FACING handle — what a routine's `trigger.source` matches. Never an id. */
+  readonly source: string;
+  /** `config` = declared in code and reviewed in a diff. ONE MEMBER since OPE-224 — see
+   *  {@link ResolvedHook.hookClass} for why it is still a union and not a dropped field. */
+  readonly hookClass: "config";
+  /** The read grant in words (`describeReadableBy`) — the same sentence a refusal would carry. */
+  readonly readableBy: string;
+  readonly sinceIso: string;
+  readonly deliveries: readonly DeliveryRecord[];
+  /** Totals over the WHOLE window, not just the returned page. */
+  readonly totals: {
+    readonly accepted: number;
+    readonly rejected: number;
+    readonly matchedNothing: number;
+  };
+  /** True when {@link deliveries} is a truncated page of a longer window. */
+  readonly moreDeliveries: boolean;
+  readonly subscribers: readonly SubscriberOutcome[];
+  /** The honesty field. Set whenever any returned row carried a suppression count, so a reader is
+   *  never invited to conclude "no miss row ⇒ no miss" from a throttled log. */
+  readonly throttled: boolean;
+}
+
+/** Granted, or refused with the reason spelled out. Never throws for an authorization outcome. */
+export type DeliveryHistoryResult =
+  | { readonly ok: true; readonly history: DeliveryHistory }
+  | { readonly ok: false; readonly reason: "unknown-hook" | "not-readable"; readonly message: string };
+
+/** Injectable edges — the live defaults are the registered config, the operational store and the
+ *  SAME access resolution the fire path uses. */
+export interface DeliveryHistoryDeps {
+  readonly configHooks?: () => readonly WebhookHook[];
+  readonly routines?: () => Promise<Routine[]>;
+  /** Deliberately NOT `typeof readAudit`: this module reads `ts`, `action` and `detail` and never a
+   *  row's storage `seq`, so the seam asks for the fields it uses. `readAudit` satisfies it (an
+   *  `AuditReadRow` is an `AuditEntry`), and a test double does not have to mint a `seq` it would
+   *  then be free to invent. */
+  readonly read?: (filter: AuditFilter) => Promise<readonly AuditEntry[]>;
+  readonly audit?: (entry: AuditInput) => Promise<void>;
+  readonly resolve?: (p: Partition) => EffectiveAccess;
+  readonly now?: () => Date;
+}
+
+function cap(v: unknown): string | null {
+  return typeof v === "string" && v.length > 0 ? v.slice(0, HISTORY_DETAIL_MAX_CHARS) : null;
+}
+
+function num(v: unknown): number | null {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+function count(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0;
+}
+
+/** A hook resolved for reading: its handle, its class, its grant, and the id the AUDIT ROWS key on.
+ *  `id` never leaves this module — a runtime hook's id IS its URL (tools/list_webhooks.ts). */
+export interface ResolvedHook {
+  readonly id: string;
+  readonly source: string;
+  /**
+   * ⚠️ COLLAPSED TO ONE MEMBER (OPE-224). It was `"config" | "runtime"` while two hook classes
+   * existed; the chat-created one is deleted, so the union has one inhabitant. KEPT as a field
+   * rather than dropped because it is rendered into the read model and into `list_recent_events`'s
+   * output, and a reader who has seen the two-class world is entitled to see which one this is —
+   * and because a widening (a hook class that is not config-declared) must come back as a NEW member
+   * here rather than as an untyped string somebody adds later.
+   */
+  readonly hookClass: "config";
+  readonly readableBy: ReadableBy;
+}
+
+/**
+ * Resolve a model-facing handle to a declared hook, or undefined.
+ *
+ * A hook's handle is its `id` — `POST /webhooks/deploy-status` is `source: "deploy-status"` to a
+ * routine, which is the only handle this model accepts.
+ *
+ * ⚠️ IT USED TO BE A TWO-STEP LOOKUP, config first then the chat-created store (OPE-224 deleted the
+ * second). One registry is now the whole answer, which is exactly why OPE-227 and OPE-228 stopped
+ * being expressible: there is one thing to enumerate and one namespace to be unique within.
+ */
+export async function resolveHook(org: string, handle: string, deps: DeliveryHistoryDeps): Promise<ResolvedHook | undefined> {
+  const configured = (deps.configHooks ?? (() => getConfig().loadWebhooks?.() ?? []))();
+  const cfg = findWebhook(configured, handle);
+  return cfg ? { id: cfg.id, source: cfg.id, hookClass: "config", readableBy: cfg.readableBy } : undefined;
+}
+
+/** Read one action's rows for this org over the window. */
+async function scan(deps: DeliveryHistoryDeps, org: string, action: string, since: string): Promise<readonly AuditEntry[]> {
+  return (deps.read ?? readAudit)({ org, action, since, limit: HISTORY_SCAN_LIMIT });
+}
+
+/** Fold one accepted-delivery row (`webhook.fired` / `webhook.declined`) into a record. */
+function acceptedRecord(row: AuditEntry, outcome: "fired" | "declined"): DeliveryRecord {
+  const d = row.detail ?? {};
+  // The verification grade is READ, never re-derived: `channels/webhooks.ts` stamps `unverified` for
+  // the dev hatch and `previousKey` for a delivery that verified against a superseded key, and an
+  // absent stamp is the ordinary current-key signature. Inventing a fourth reading here would be a
+  // second opinion about a fact the ingress already decided.
+  const verification: DeliveryVerification = d["unverified"] === true ? "unverified" : d["previousKey"] === true ? "previous-key" : "signed";
+  return {
+    at: row.ts,
+    outcome,
+    deliveryId: cap(d["deliveryId"]),
+    bytes: num(d["bytes"]),
+    verification,
+    status: null,
+    // `routingReason` is the EVENT-PLANE's own refusal (an unmodelled event, a replay); `reason` is
+    // the declared fire's decline. Both are one-line, neither carries payload bytes.
+    reason: cap(d["routingReason"]) ?? cap(d["reason"]),
+    matched: num(d["matched"]),
+    fired: num(d["fired"]),
+    skipped: num(d["skipped"]),
+    standsFor: 0,
+  };
+}
+
+/** Fold one `webhook.rejected` row. These never reached the routing plane, so the fan-out fields are
+ *  null rather than zero — "we never asked" is not "nothing matched". */
+function rejectedRecord(row: AuditEntry): DeliveryRecord {
+  const d = row.detail ?? {};
+  return {
+    at: row.ts,
+    outcome: "rejected",
+    deliveryId: null,
+    bytes: null,
+    verification: "refused",
+    status: num(d["status"]),
+    reason: cap(d["reason"]),
+    matched: null,
+    fired: null,
+    skipped: null,
+    standsFor: count(d["suppressed"]),
+  };
+}
+
+/**
+ * THE READ. Compose one hook's delivery history from rows already written, gated at the hook's own
+ * `readableBy`, and audit the read itself.
+ *
+ * NEVER THROWS for an authorization outcome — an unknown handle and an ungranted one are both
+ * `ok: false` with a sentence, because this is a diagnostic and a thrown error is the least useful
+ * possible answer to "why is nothing happening". A STORE failure does throw: a history that silently
+ * degraded to "no deliveries" would answer the question wrongly rather than not at all, which on
+ * this particular tool is the one failure mode that matters.
+ */
+export async function readDeliveryHistory(
+  request: {
+    readonly partition: Partition;
+    readonly source: string;
+    /** WHO is asking — stamped onto the audit row (OPE-295 item 7). See {@link WEBHOOK_HISTORY_READ}. */
+    readonly principalId?: string;
+  },
+  deps: DeliveryHistoryDeps = {},
+): Promise<DeliveryHistoryResult> {
+  const org = request.partition.org;
+  const hook = await resolveHook(org, request.source, deps);
+  if (!hook) {
+    // NOT AUDITED, and see the header: the handle is caller-supplied and unbounded, so a row here
+    // would carry a label the caller chose. Nothing was disclosed and no grant was consulted.
+    return {
+      ok: false,
+      reason: "unknown-hook",
+      message: `no inbound webhook named "${request.source.slice(0, 80)}" exists for this org — check the name with list_webhooks.`,
+    };
+  }
+
+  // THE GATE. The same two calls the fire path makes, in the same order (see the header). Fail-closed
+  // on a resolution failure: a config that will not load must never read as "granted".
+  const grantText = describeReadableBy(hook.readableBy);
+  let granted: boolean;
+  try {
+    const access = (deps.resolve ?? resolveAccessForPartition)(request.partition);
+    granted = scopeGrantsRead(hook.readableBy, access);
+  } catch {
+    granted = false;
+  }
+
+  const now = deps.now?.() ?? new Date();
+  const audit = deps.audit ?? appendAudit;
+  // Written for BOTH verdicts, before the read, from the partition that asked. Ids, counts and the
+  // verdict — never a delivery, never a reason string read out of a row.
+  await audit({
+    org,
+    platform: request.partition.platform,
+    workspace: request.partition.workspace,
+    surface: request.partition.surface,
+    ...(request.principalId !== undefined ? { principalId: request.principalId } : {}),
+    action: WEBHOOK_HISTORY_READ,
+    detail: {
+      // The hook id is fine in an OPERATOR-plane row and is the join key for it (channels/
+      // webhooks.ts says so explicitly); it is the model-facing surfaces that never see it, and the
+      // result this function returns does not carry it.
+      hookId: hook.id,
+      source: hook.source,
+      hookClass: hook.hookClass,
+      granted,
+      readableBy: grantText,
+    },
+  }).catch(() => undefined);
+
+  if (!granted) {
+    return {
+      ok: false,
+      reason: "not-readable",
+      message:
+        `the "${hook.source}" hook's events are readable by: ${grantText}. This channel's domain is not among them, ` +
+        "so its delivery history cannot be read from here (and no routine here could be fired by it either — it is the same grant).",
+    };
+  }
+
+  const sinceIso = new Date(now.getTime() - HISTORY_WINDOW_MS).toISOString();
+  const [firedRows, declinedRows, rejectedRows] = await Promise.all([
+    scan(deps, org, WEBHOOK_DELIVERY_ACTIONS.fired, sinceIso),
+    scan(deps, org, WEBHOOK_DELIVERY_ACTIONS.declined, sinceIso),
+    scan(deps, org, WEBHOOK_DELIVERY_ACTIONS.rejected, sinceIso),
+  ]);
+
+  // `detail.hookId` is the UNIFORM join key across all three delivery actions — both classes of hook
+  // stamp it, and so does the throttled rejection row (length-capped there, which is why the compare
+  // is against the stored id rather than the other way round).
+  const mine = (rows: readonly AuditEntry[]): AuditEntry[] => rows.filter((r) => r.detail?.["hookId"] === hook.id);
+  const accepted = [
+    ...mine(firedRows).map((r) => acceptedRecord(r, "fired")),
+    ...mine(declinedRows).map((r) => acceptedRecord(r, "declined")),
+  ];
+  const rejected = mine(rejectedRows).map(rejectedRecord);
+  const deliveries = [...accepted, ...rejected].sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : 0));
+
+  // THE SUBSCRIBERS. Resolved from the routine store rather than from a stamp on the skip rows: a
+  // routine has exactly one trigger, so "every routine whose event trigger names this hook" is an
+  // exact set, and filtering the routine rows by that set attributes them without any write-side
+  // change. Inactive and self-disabled routines are INCLUDED — "it used to fire and stopped" is the
+  // question, and dropping them would hide the answer.
+  const all = await (deps.routines ?? listAllRoutines)();
+  const subscribed = all.filter((r) => r.org === org && isEventTrigger(r.trigger) && r.trigger.source === hook.source);
+  const ids = new Set(subscribed.map((r) => r.id));
+
+  const [fireRows, skipRows, lostRows] =
+    ids.size === 0
+      ? [[], [], []]
+      : await Promise.all([
+          scan(deps, org, ROUTINE_AUDIT.fire, sinceIso),
+          scan(deps, org, ROUTINE_AUDIT.skip, sinceIso),
+          scan(deps, org, ROUTINE_AUDIT.fireLost, sinceIso),
+        ]);
+  const forRoutine = (rows: readonly AuditEntry[], id: string): AuditEntry[] => rows.filter((r) => r.detail?.["routineId"] === id);
+
+  const subscribers: SubscriberOutcome[] = subscribed.map((r) => {
+    const fires = forRoutine(fireRows, r.id);
+    const misses: RoutineMiss[] = [
+      ...forRoutine(skipRows, r.id).map((row) => {
+        const d = row.detail ?? {};
+        const reason = typeof d["reason"] === "string" ? d["reason"] : "unknown";
+        // ONE supporting field per reason, chosen because it is the one a reader acts on. `why`
+        // (jq's own message) and `error` come from off-host evaluators/vendors, so both are capped.
+        const detail = cap(d["why"]) ?? cap(d["grant"]) ?? cap(d["partition"]) ?? cap(d["floor"]) ?? cap(d["note"]);
+        return { at: row.ts, reason, detail, standsFor: count(d["suppressed"]) };
+      }),
+      ...forRoutine(lostRows, r.id).map((row) => ({
+        at: row.ts,
+        reason: "fire_lost",
+        detail: cap(row.detail?.["error"]),
+        standsFor: 0,
+      })),
+    ]
+      .sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : 0))
+      .slice(0, HISTORY_MAX_MISSES);
+    return {
+      routineId: r.id,
+      status: r.status,
+      surfaceKey: r.surfaceKey,
+      fires: fires.length,
+      lastFireAt: fires[0]?.ts ?? null, // readAudit is newest-first and the filter preserves order
+      misses,
+    };
+  });
+
+  const page = deliveries.slice(0, HISTORY_MAX_DELIVERIES);
+  const throttled =
+    page.some((d) => d.standsFor > 0) || subscribers.some((s) => s.misses.some((m) => m.standsFor > 0));
+  return {
+    ok: true,
+    history: {
+      source: hook.source,
+      hookClass: hook.hookClass,
+      readableBy: grantText,
+      sinceIso,
+      deliveries: page,
+      totals: {
+        accepted: accepted.length,
+        rejected: rejected.length,
+        matchedNothing: accepted.filter((d) => d.matched === 0).length,
+      },
+      moreDeliveries: deliveries.length > page.length,
+      subscribers,
+      throttled,
+    },
+  };
+}
+
+/** Render a history as the plain text the tool hands the model. Host-composed, ids and counts only —
+ *  every off-host string it embeds was capped on the way out of {@link readDeliveryHistory}. */
+export function renderDeliveryHistory(h: DeliveryHistory): string {
+  const lines: string[] = [];
+  lines.push(
+    `webhook "${h.source}" (${h.hookClass}-declared) — deliveries since ${h.sinceIso}`,
+    `readable by: ${h.readableBy}`,
+    `${h.totals.accepted} accepted, ${h.totals.rejected} rejected at the door, ${h.totals.matchedNothing} accepted but matched no routine`,
+    "",
+  );
+  if (h.deliveries.length === 0) {
+    lines.push("No deliveries at all in the window — the sender has not reached this endpoint. Nothing downstream can be wrong yet.");
+  } else {
+    lines.push(`deliveries (newest first${h.moreDeliveries ? `, showing ${h.deliveries.length}` : ""}):`);
+    for (const d of h.deliveries) {
+      const parts = [
+        d.at,
+        d.outcome.toUpperCase(),
+        d.status !== null ? `HTTP ${d.status}` : "",
+        d.verification,
+        d.bytes !== null ? `${d.bytes}B` : "",
+        d.deliveryId ? `id=${d.deliveryId}` : "",
+        d.matched !== null ? `matched ${d.matched} -> fired ${d.fired}, skipped ${d.skipped}` : "",
+        d.reason ? `(${d.reason})` : "",
+        d.standsFor > 0 ? `[+${d.standsFor} more like this, throttled]` : "",
+      ].filter((s) => s.length > 0);
+      lines.push(`  ${parts.join(" | ")}`);
+    }
+  }
+  lines.push("");
+  if (h.subscribers.length === 0) {
+    lines.push("No event routine subscribes to this hook, so an accepted delivery has nothing to fire. Create one with create_routine.");
+  } else {
+    lines.push("subscribed routines:");
+    for (const s of h.subscribers) {
+      lines.push(`  ${s.routineId} [${s.status}] on ${s.surfaceKey} — ${s.fires} fire(s)${s.lastFireAt ? `, last ${s.lastFireAt}` : ""}`);
+      if (s.misses.length === 0 && s.fires === 0) lines.push("    no fires and no recorded misses — its filter has not matched anything.");
+      for (const m of s.misses) {
+        lines.push(`    MISS ${m.at} ${m.reason}${m.detail ? `: ${m.detail}` : ""}${m.standsFor > 0 ? ` [+${m.standsFor} suppressed]` : ""}`);
+      }
+    }
+  }
+  if (h.throttled) {
+    lines.push(
+      "",
+      "NOTE: miss and rejection rows are rate-limited (one per routine+reason per hour, one per rejection identity per minute) " +
+        "and carry the count they stand in for. The ABSENCE of a row for a given delivery is not proof that delivery was fine.",
+    );
+  }
+  return lines.join("\n");
+}