@cohortapp/agent-sdk 2.5.0 → 2.6.0

package/lib/channels/repeat-suppressor.mjs

@@ -0,0 +1,198 @@
+/**
+ * lib/channels/repeat-suppressor.mjs — say it once, keep saying it occasionally,
+ * and say when it stops.
+ *
+ * ── The problem ─────────────────────────────────────────────────────────────
+ *
+ * A channel adapter's poll loop turns a STANDING condition into a per-tick log
+ * line. On a live seat the orgmail adapter polled `email.inbox` every 45s
+ * against a member with no mailbox and wrote
+ *
+ *   [orgmail:warn] email.inbox error: NOT_FOUND no active mailbox is assigned…
+ *
+ * 478 times in one day (164 the day before). Every line was true. The net
+ * information content of the 478th was zero, and the volume actively hid
+ * everything else in the log. That is the failure mode this module exists to
+ * prevent — and it is the mirror image of a silent catch: FAIL-OPEN IS FINE,
+ * SILENT IS NOT, but "not silent" means *audible*, not *deafening*.
+ *
+ * ── The contract ────────────────────────────────────────────────────────────
+ *
+ * Per condition key:
+ *   - the FIRST occurrence always emits, in full;
+ *   - repeats are counted and swallowed;
+ *   - every `restateMs` (default 1h) one line is emitted carrying the
+ *     suppressed count and how long the condition has stood, so a standing
+ *     problem cannot fade out of the log entirely;
+ *   - `clear()` reports the recovery, WITH the total suppressed — so the log
+ *     reads "started at T, still broken at T+1h (79 more), fixed at T+3h after
+ *     231 attempts" instead of a wall of identical lines.
+ *
+ * `observe()` also classifies whether a condition is TERMINAL — one that no
+ * amount of retrying will fix because it needs a human act (an admin assigning
+ * a mailbox, re-minting a key). Callers use that to back their poll off, so a
+ * seat waiting on an admin stops hammering the server as well as the log.
+ *
+ * Pure, injectable clock, no I/O, never throws.
+ *
+ * @module lib/channels/repeat-suppressor
+ */
+
+"use strict";
+
+/** Default gap between re-statements of a standing condition. */
+export const DEFAULT_RESTATE_MS = 60 * 60 * 1000;
+
+/**
+ * RPC error codes that will NOT resolve by retrying: they need a human to do
+ * something in Cohort. Callers slow their poll while one of these stands.
+ */
+export const TERMINAL_CODES = Object.freeze([
+  "NOT_FOUND",
+  "FORBIDDEN_SCOPE",
+  "FORBIDDEN",
+  "UNAUTHORIZED",
+]);
+
+export class RepeatSuppressor {
+  /**
+   * @param {object} [o]
+   * @param {number} [o.restateMs] gap between re-statements (default 1h)
+   * @param {() => number} [o.now] injectable clock
+   */
+  constructor(o = {}) {
+    this.restateMs =
+      Number.isFinite(o.restateMs) && o.restateMs > 0 ? o.restateMs : DEFAULT_RESTATE_MS;
+    this._now = typeof o.now === "function" ? o.now : Date.now;
+    /** @type {Map<string, {firstAt:number, lastEmitAt:number, count:number, sinceLastEmit:number, code:string}>} */
+    this._conditions = new Map();
+  }
+
+  /**
+   * Record one occurrence of a condition.
+   *
+   * @param {string} key   stable identity of the condition (e.g. "inbox:NOT_FOUND")
+   * @param {object} [meta]
+   * @param {string} [meta.code] RPC error code, for terminal classification
+   * @returns {{
+   *   emit: boolean,
+   *   first: boolean,
+   *   restated: boolean,
+   *   count: number,
+   *   suppressed: number,
+   *   standingMs: number,
+   *   terminal: boolean,
+   *   suffix: string,
+   * }}
+   */
+  observe(key, meta = {}) {
+    const now = this._now();
+    const code = String(meta.code || "");
+    const terminal = TERMINAL_CODES.includes(code);
+    const prev = this._conditions.get(key);
+
+    if (!prev) {
+      this._conditions.set(key, {
+        firstAt: now,
+        lastEmitAt: now,
+        count: 1,
+        sinceLastEmit: 0,
+        code,
+      });
+      return {
+        emit: true,
+        first: true,
+        restated: false,
+        count: 1,
+        suppressed: 0,
+        standingMs: 0,
+        terminal,
+        suffix: "",
+      };
+    }
+
+    prev.count += 1;
+    prev.sinceLastEmit += 1;
+    prev.code = code || prev.code;
+    const standingMs = now - prev.firstAt;
+
+    if (now - prev.lastEmitAt >= this.restateMs) {
+      const suppressed = prev.sinceLastEmit - 1;
+      prev.lastEmitAt = now;
+      prev.sinceLastEmit = 0;
+      return {
+        emit: true,
+        first: false,
+        restated: true,
+        count: prev.count,
+        suppressed,
+        standingMs,
+        terminal,
+        suffix: ` [STILL UNRESOLVED after ${fmtDuration(standingMs)}; ${suppressed} identical occurrence(s) suppressed since the last line]`,
+      };
+    }
+
+    return {
+      emit: false,
+      first: false,
+      restated: false,
+      count: prev.count,
+      suppressed: prev.sinceLastEmit,
+      standingMs,
+      terminal,
+      suffix: "",
+    };
+  }
+
+  /**
+   * Mark a condition resolved.
+   *
+   * @param {string} key
+   * @returns {{wasActive: boolean, count: number, standingMs: number, message: string}}
+   */
+  clear(key) {
+    const prev = this._conditions.get(key);
+    if (!prev) return { wasActive: false, count: 0, standingMs: 0, message: "" };
+    this._conditions.delete(key);
+    const standingMs = this._now() - prev.firstAt;
+    return {
+      wasActive: true,
+      count: prev.count,
+      standingMs,
+      message: `RESOLVED after ${fmtDuration(standingMs)} and ${prev.count} failed attempt(s)`,
+    };
+  }
+
+  /** Is `key` currently standing? */
+  isActive(key) {
+    return this._conditions.has(key);
+  }
+
+  /** Snapshot of every standing condition — for healthCheck / state files. */
+  active() {
+    const now = this._now();
+    return [...this._conditions.entries()].map(([key, v]) => ({
+      key,
+      code: v.code,
+      count: v.count,
+      firstAt: new Date(v.firstAt).toISOString(),
+      standingMs: now - v.firstAt,
+      terminal: TERMINAL_CODES.includes(v.code),
+    }));
+  }
+}
+
+/** "3h 12m" / "45s" — short enough to sit inside a log line. */
+export function fmtDuration(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  const rem = m % 60;
+  if (h < 24) return rem ? `${h}h ${rem}m` : `${h}h`;
+  const d = Math.floor(h / 24);
+  return `${d}d ${h % 24}h`;
+}
+
+export default { RepeatSuppressor, DEFAULT_RESTATE_MS, TERMINAL_CODES, fmtDuration };

package/lib/channels/repeat-suppressor.test.mjs

@@ -0,0 +1,134 @@
+/**
+ * repeat-suppressor.test.mjs — coverage for lib/channels/repeat-suppressor.mjs.
+ *
+ * The behaviour under test is the fix for a real incident: 478 identical
+ * `email.inbox NOT_FOUND` lines in one day from a 45s poll loop. The rules that
+ * must hold are "say it once", "keep saying it occasionally so it cannot fade
+ * out", and "say when it stops" — the middle one being what separates this from
+ * a silent catch.
+ *
+ * Hermetic: injected clock, no I/O.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { RepeatSuppressor, fmtDuration, TERMINAL_CODES } from "./repeat-suppressor.mjs";
+
+/** A controllable clock. */
+function clock(start = 0) {
+  const c = { t: start, now: () => c.t, advance: (ms) => { c.t += ms; } };
+  return c;
+}
+
+test("the first occurrence always emits, in full", () => {
+  const s = new RepeatSuppressor({ now: clock().now });
+  const r = s.observe("k", { code: "NOT_FOUND" });
+  assert.equal(r.emit, true);
+  assert.equal(r.first, true);
+  assert.equal(r.suppressed, 0);
+  assert.equal(r.suffix, "");
+});
+
+test("repeats inside the restate window are counted and swallowed", () => {
+  const c = clock();
+  const s = new RepeatSuppressor({ now: c.now, restateMs: 3_600_000 });
+  s.observe("k", { code: "NOT_FOUND" });
+  let emitted = 0;
+  // 45s poll for 30 minutes = 40 more ticks. The incident shape, in miniature.
+  for (let i = 0; i < 40; i += 1) {
+    c.advance(45_000);
+    if (s.observe("k", { code: "NOT_FOUND" }).emit) emitted += 1;
+  }
+  assert.equal(emitted, 0, "not one repeat may reach the log inside the window");
+});
+
+test("a standing condition is RE-STATED once per window, carrying the suppressed count", () => {
+  const c = clock();
+  const s = new RepeatSuppressor({ now: c.now, restateMs: 3_600_000 });
+  s.observe("k", { code: "NOT_FOUND" });
+  let restatement = null;
+  for (let i = 0; i < 100; i += 1) {
+    c.advance(45_000); // 100 ticks ≈ 75 minutes
+    const r = s.observe("k", { code: "NOT_FOUND" });
+    if (r.emit) { restatement = r; break; }
+  }
+  assert.ok(restatement, "a standing condition must not fade out of the log entirely");
+  assert.equal(restatement.restated, true);
+  assert.ok(restatement.suppressed > 70, `expected ~79 suppressed, got ${restatement.suppressed}`);
+  assert.match(restatement.suffix, /STILL UNRESOLVED after 1h/);
+  assert.match(restatement.suffix, /suppressed/);
+});
+
+test("over a full day the 478-line incident collapses to first + hourly re-statements", () => {
+  const c = clock();
+  const s = new RepeatSuppressor({ now: c.now, restateMs: 3_600_000 });
+  let emitted = 0;
+  const ticks = Math.round((24 * 3_600_000) / 45_000); // 1920 polls in a day
+  for (let i = 0; i < ticks; i += 1) {
+    if (s.observe("k", { code: "NOT_FOUND" }).emit) emitted += 1;
+    c.advance(45_000);
+  }
+  // 1 first line + one re-statement per elapsed hour (the 24th hour's
+  // re-statement lands just past the window, so 24 lines cover the day).
+  assert.equal(emitted, 24, `expected 24 lines a day, got ${emitted}`);
+  assert.ok(emitted < ticks / 50, "the whole point: ~2 orders of magnitude quieter than 1920 polls");
+});
+
+test("clear() reports the recovery WITH the total attempts, then forgets", () => {
+  const c = clock();
+  const s = new RepeatSuppressor({ now: c.now });
+  s.observe("k", { code: "NOT_FOUND" });
+  for (let i = 0; i < 9; i += 1) { c.advance(45_000); s.observe("k", { code: "NOT_FOUND" }); }
+  c.advance(45_000);
+  const r = s.clear("k");
+  assert.equal(r.wasActive, true);
+  assert.equal(r.count, 10);
+  assert.match(r.message, /RESOLVED after/);
+  assert.match(r.message, /10 failed attempt/);
+  // Idempotent: clearing a healthy condition says nothing at all.
+  assert.equal(s.clear("k").wasActive, false);
+});
+
+test("terminal codes are flagged so a caller can back its poll off", () => {
+  const s = new RepeatSuppressor({ now: clock().now });
+  assert.equal(s.observe("a", { code: "NOT_FOUND" }).terminal, true);
+  assert.equal(s.observe("b", { code: "FORBIDDEN_SCOPE" }).terminal, true);
+  assert.equal(s.observe("c", { code: "INTERNAL" }).terminal, false);
+  assert.equal(s.observe("d", { code: "TIMEOUT" }).terminal, false);
+  for (const code of TERMINAL_CODES) {
+    assert.equal(s.observe(`t-${code}`, { code }).terminal, true);
+  }
+});
+
+test("distinct keys are tracked independently", () => {
+  const c = clock();
+  const s = new RepeatSuppressor({ now: c.now });
+  assert.equal(s.observe("inbox", { code: "NOT_FOUND" }).emit, true);
+  assert.equal(s.observe("send", { code: "NOT_FOUND" }).emit, true);
+  c.advance(45_000);
+  assert.equal(s.observe("inbox", { code: "NOT_FOUND" }).emit, false);
+  assert.equal(s.isActive("send"), true);
+  assert.equal(s.active().length, 2);
+});
+
+test("active() snapshots standing conditions for healthCheck / state files", () => {
+  const c = clock(1_700_000_000_000);
+  const s = new RepeatSuppressor({ now: c.now });
+  s.observe("inbox", { code: "NOT_FOUND" });
+  c.advance(3 * 3_600_000);
+  const [a] = s.active();
+  assert.equal(a.key, "inbox");
+  assert.equal(a.code, "NOT_FOUND");
+  assert.equal(a.terminal, true);
+  assert.equal(a.standingMs, 3 * 3_600_000);
+  assert.match(a.firstAt, /^\d{4}-/);
+});
+
+test("fmtDuration stays short enough to live inside a log line", () => {
+  assert.equal(fmtDuration(45_000), "45s");
+  assert.equal(fmtDuration(90_000), "1m");
+  assert.equal(fmtDuration(3_600_000), "1h");
+  assert.equal(fmtDuration(3_600_000 + 720_000), "1h 12m");
+  assert.equal(fmtDuration(26 * 3_600_000), "1d 2h");
+});

package/lib/comms/receipts.mjs

@@ -0,0 +1,297 @@
+/**
+ * receipts.mjs — the durable record of "did a human actually hear from us".
+ *
+ * Every user-facing send in this agent funnels through one of three places:
+ *   * the daemon's own delivery path      (scripts/daemon/deliver.mjs)
+ *   * lib/org/messaging.sendMessage       (the in-process org send)
+ *   * lib/org/tool-surface.executeOrgTool (what a spawned SESSION uses)
+ *
+ * The third one is the reason this file exists at all. A dispatched session is a
+ * separate `claude` child process; when it posts a reply, the daemon that
+ * spawned it learns nothing. The daemon therefore had no way to tell the
+ * difference between "the session answered the human" and "the session exited 0
+ * having said nothing", and it treated both as success — marking the item
+ * processed forever and emitting `sent`. That is the true silent death: a
+ * SUCCESSFUL session with zero human-facing output.
+ *
+ * A receipt is an append-only line on disk, so it crosses the process boundary.
+ * `spokeSince()` answers the only question the daemon actually needs: since this
+ * item arrived, did anything at all reach this channel?
+ *
+ * Everything here is fail-open and never throws. A receipt subsystem that could
+ * break a send would be worse than the bug it fixes — but note the asymmetry we
+ * deliberately choose: if the ledger is unreadable, `spokeSince()` returns
+ * `false`, i.e. "assume the human heard nothing". The failure mode is one extra
+ * message, never silence.
+ *
+ * @module lib/comms/receipts
+ */
+
+"use strict";
+
+import { appendFileSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync } from "fs";
+import { join } from "path";
+
+/** Receipts older than this are irrelevant to any live obligation. */
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
+function rootOf(agentRoot) {
+  return agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+}
+
+function receiptDir(agentRoot) {
+  const dir = join(rootOf(agentRoot), "state", "comms");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function dayFile(agentRoot, ms) {
+  const day = new Date(ms).toISOString().slice(0, 10);
+  return join(receiptDir(agentRoot), `receipts-${day}.jsonl`);
+}
+
+/**
+ * Normalise a channel identifier so a receipt written by a session (which knows
+ * the org channel id) matches a lookup by the daemon (which may hold the inbox
+ * item's `channel` or `channel_id`). Case-folded, trimmed; never null.
+ */
+export function channelKey(channel) {
+  return String(channel == null ? "" : channel).trim().toLowerCase();
+}
+
+/**
+ * WHO the send belongs to, taken from the environment the dispatcher stamped on
+ * the session child. This is the difference between "somebody spoke into that
+ * room" and "the session that owes THIS person an answer spoke".
+ *
+ * Without it, receipts are keyed on the room alone, and a room is shared: two
+ * asks arriving in the same DM within a minute produce two debts and one
+ * channel. The first session's reply then discharges BOTH, and the second ask —
+ * the one nobody answered — is closed as "answered" with the human never told.
+ * Attribution is what makes the discharge specific.
+ */
+function ambientAttribution(env = process.env) {
+  return {
+    obligationKey: env.MAESTRO_OBLIGATION_KEY || null,
+    sessionId: env.MAESTRO_SESSION_ID || env.AGENT_SESSION_ID || null,
+  };
+}
+
+/**
+ * Record that something user-facing left the agent.
+ *
+ * @param {object} rec
+ * @param {string} rec.service   "cohort" | "slack" | "gmail" | …
+ * @param {string} rec.channel   channel / thread / recipient the text went to
+ * @param {string} [rec.kind]    "reply" | "ack" | "progress" | "failure" | "session"
+ * @param {string} [rec.via]     transport that carried it
+ * @param {number} [rec.chars]   length of the delivered text (never the text)
+ * @param {string} [rec.obligationKey] the debt this send discharges, when known
+ * @param {string} [rec.sessionId]     the session that sent it, when known
+ * @param {object} [rec.env]     environment to read ambient attribution from
+ * @param {string} [rec.agentRoot]
+ * @param {number} [rec.now]     injectable clock (tests)
+ * @returns {boolean} true if the receipt was durably appended
+ */
+export function recordOutbound(rec = {}) {
+  try {
+    const ch = channelKey(rec.channel);
+    if (!ch) return false;
+    const now = Number.isFinite(rec.now) ? rec.now : Date.now();
+    const ambient = ambientAttribution(rec.env || process.env);
+    const line = JSON.stringify({
+      ts: new Date(now).toISOString(),
+      at: now,
+      service: rec.service || "unknown",
+      channel: ch,
+      kind: rec.kind || "reply",
+      via: rec.via || null,
+      chars: Number.isFinite(rec.chars) ? rec.chars : null,
+      // Explicit argument wins; the dispatcher's env is the fallback, which is
+      // what lets a CLI send lane inside a spawned session attribute itself
+      // without every script having to know about obligations.
+      obligationKey: rec.obligationKey || ambient.obligationKey,
+      sessionId: rec.sessionId || ambient.sessionId,
+    });
+    appendFileSync(dayFile(rec.agentRoot, now), line + "\n");
+    return true;
+  } catch {
+    // Fail-open: a send must never be broken by its own bookkeeping.
+    return false;
+  }
+}
+
+/**
+ * Read every receipt at or after `sinceMs`. Scans only the day-files that can
+ * possibly contain them (today and yesterday cover any realistic obligation).
+ *
+ * @returns {object[]} receipts, oldest first; [] on any failure
+ */
+export function readReceiptsSince(sinceMs, o = {}) {
+  const out = [];
+  try {
+    const dir = receiptDir(o.agentRoot);
+    const files = readdirSync(dir).filter((f) => f.startsWith("receipts-") && f.endsWith(".jsonl"));
+    for (const f of files) {
+      // `receipts-YYYY-MM-DD.jsonl` — skip whole days that end before `since`.
+      const day = f.slice("receipts-".length, -".jsonl".length);
+      const dayEnd = Date.parse(`${day}T23:59:59.999Z`);
+      if (Number.isFinite(dayEnd) && dayEnd < sinceMs) continue;
+      let raw = "";
+      try { raw = readFileSync(join(dir, f), "utf-8"); } catch { continue; }
+      for (const line of raw.split("\n")) {
+        if (!line.trim()) continue;
+        try {
+          const rec = JSON.parse(line);
+          const at = Number.isFinite(rec.at) ? rec.at : Date.parse(rec.ts);
+          if (Number.isFinite(at) && at >= sinceMs) out.push({ ...rec, at });
+        } catch { /* a torn line is not a reason to lose the rest */ }
+      }
+    }
+  } catch { return []; }
+  out.sort((a, b) => a.at - b.at);
+  return out;
+}
+
+/**
+ * Did anything reach `channel` at or after `sinceMs`?
+ *
+ * This is the daemon's delivery check on session close. `kinds` lets the caller
+ * ask the sharper question — "did anything OTHER than my own acknowledgement
+ * reach them?" — because an ack is not an answer.
+ *
+ * @param {object} q
+ * @param {string} q.channel
+ * @param {number} q.sinceMs
+ * @param {string[]} [q.kinds]  restrict to these receipt kinds
+ * @param {string[]} [q.excludeKinds] ignore these kinds (e.g. ["ack","progress"])
+ * @returns {boolean} false whenever we cannot prove a send happened
+ */
+export function spokeSince(q = {}) {
+  const ch = channelKey(q.channel);
+  if (!ch || !Number.isFinite(q.sinceMs)) return false;
+  const recs = readReceiptsSince(q.sinceMs, q);
+  return recs.some((r) => {
+    if (r.channel !== ch) return false;
+    if (Array.isArray(q.kinds) && q.kinds.length && !q.kinds.includes(r.kind)) return false;
+    if (Array.isArray(q.excludeKinds) && q.excludeKinds.includes(r.kind)) return false;
+    return true;
+  });
+}
+
+/**
+ * Did the work for THIS obligation reach its human?
+ *
+ * `spokeSince` answers a question about a room. This answers a question about a
+ * debt, and the two differ precisely when a room holds more than one debt —
+ * which is the normal case for a DM with an owner who sends three messages in a
+ * row. The ladder is deliberate, most specific first:
+ *
+ *   1. a receipt stamped with this obligation's key      → certain
+ *   2. a receipt stamped with this obligation's session  → certain
+ *   3. an UNATTRIBUTED receipt in the room, and this debt is the only one open
+ *      in that room, and a session of ours has actually run                 → assumed
+ *   4. anything else                                     → NOT heard
+ *
+ * Rung 3 exists because attribution is best-effort: a send lane that loses the
+ * dispatcher's env still leaves an unattributed receipt, and treating that as
+ * silence would make every such reply produce a redundant "I didn't get back to
+ * you". Its two conditions are what keep it honest — with a second debt open in
+ * the room the receipt is ambiguous, and before any session of ours has run the
+ * message cannot have been our answer.
+ *
+ * Rung 4 is the module's standing bias made specific: unproven means not heard,
+ * and the cost of being wrong is one redundant message rather than silence.
+ *
+ * @param {object} q
+ * @param {object} q.obligation  {key, channel, openedAt, sessionId, attempts}
+ * @param {number} [q.now]
+ * @param {number} [q.siblingOpenCount] open debts sharing this room, incl. self
+ * @param {string[]} [q.excludeKinds]
+ * @param {string} [q.agentRoot]
+ * @returns {{heard:boolean, basis:string}}
+ */
+export function spokeFor(q = {}) {
+  const rec = q.obligation || {};
+  const ch = channelKey(rec.channel);
+  const since = Number.isFinite(rec.openedAt) ? rec.openedAt : q.now;
+  if (!ch || !Number.isFinite(since)) return { heard: false, basis: "no-channel" };
+  const exclude = Array.isArray(q.excludeKinds) ? q.excludeKinds : ["ack", "progress", "failure"];
+  const recs = readReceiptsSince(since, q).filter(
+    (r) => r.channel === ch && !exclude.includes(r.kind),
+  );
+  if (!recs.length) return { heard: false, basis: "no-receipts" };
+
+  if (rec.key && recs.some((r) => r.obligationKey === rec.key)) {
+    return { heard: true, basis: "obligation-keyed" };
+  }
+  if (rec.sessionId && recs.some((r) => r.sessionId && r.sessionId === rec.sessionId)) {
+    return { heard: true, basis: "session-keyed" };
+  }
+  // Any receipt that names a DIFFERENT debt or a DIFFERENT session is positive
+  // evidence that this one was not the sender — it must never count here.
+  const unattributed = recs.filter((r) => !r.obligationKey && !r.sessionId);
+  if (!unattributed.length) return { heard: false, basis: "attributed-elsewhere" };
+  const siblings = Number.isFinite(q.siblingOpenCount) ? q.siblingOpenCount : 1;
+  if (siblings > 1) return { heard: false, basis: "ambiguous-room" };
+  if (!(rec.attempts > 0)) return { heard: false, basis: "no-session-yet" };
+  return { heard: true, basis: "sole-debt-in-room" };
+}
+
+/** Drop receipt day-files past retention. Best-effort; returns files removed. */
+export function pruneReceipts(o = {}) {
+  let removed = 0;
+  const now = Number.isFinite(o.now) ? o.now : Date.now();
+  try {
+    const dir = receiptDir(o.agentRoot);
+    for (const f of readdirSync(dir)) {
+      if (!f.startsWith("receipts-")) continue;
+      const p = join(dir, f);
+      try {
+        if (now - statSync(p).mtimeMs > RETENTION_MS) { unlinkSync(p); removed++; }
+      } catch { /* best-effort */ }
+    }
+  } catch { /* best-effort */ }
+  return removed;
+}
+
+// ---------------------------------------------------------------------------
+// CLI — `node lib/comms/receipts.mjs record --service slack --channel C123 …`
+// ---------------------------------------------------------------------------
+
+/**
+ * The send lanes a spawned session is REQUIRED to use are a bash script, a
+ * python script and a node script (prompt-builder mandates them; the org MCP
+ * send tools are hard-blocked by a pre-tool hook). None of them can import this
+ * module, so without this entry point no session send is ever witnessed — and
+ * the daemon's whole "did the session actually answer?" check reads every
+ * successful reply as silence and apologises for it.
+ *
+ * Exit code is always 0. A receipt that could break a send would be worse than
+ * the bug it fixes.
+ */
+export function runReceiptCli(argv = []) {
+  if (argv[0] !== "record") return 0;
+  const a = {};
+  for (let i = 1; i < argv.length; i++) {
+    const m = /^--([a-zA-Z-]+)$/.exec(argv[i]);
+    if (m) a[m[1]] = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "1";
+  }
+  recordOutbound({
+    service: a.service,
+    channel: a.channel,
+    kind: a.kind || "session",
+    via: a.via || null,
+    chars: a.chars ? parseInt(a.chars, 10) : null,
+    obligationKey: a["obligation-key"] || undefined,
+    sessionId: a["session-id"] || undefined,
+    agentRoot: a["agent-root"] || undefined,
+  });
+  return 0;
+}
+
+if (process.argv[1] && process.argv[1].endsWith("receipts.mjs")) {
+  try { runReceiptCli(process.argv.slice(2)); } catch { /* never fail a send */ }
+}
+
+export default { recordOutbound, readReceiptsSince, spokeSince, spokeFor, channelKey, pruneReceipts };