@cohortapp/agent-sdk 2.9.1 → 2.10.0

package/scripts/daemon/deliver.mjs

@@ -31,6 +31,10 @@ import { join } from "path";
 import { screenOutbound } from "../../lib/comms/send-gate.mjs";
 import { getHookBus } from "../../lib/hooks/bus.mjs";
 import { recordOutbound } from "../../lib/comms/receipts.mjs";
+// Pure data (a frozen table, no imports of its own) — the surface vocabulary the
+// inbound projection stamps into `raw_ref`. Imported rather than re-listed so a
+// new surface cannot be added upstream without this file's switch noticing.
+import { SURFACE_NAMES } from "../../lib/org/inbound/surfaces.mjs";
 
 const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
 
@@ -63,18 +67,288 @@ export function resolveSlackChannel(item) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Cohort surface routing
+// ---------------------------------------------------------------------------
+
+/**
+ * WHY THIS EXISTS — the `task/<title>` incident.
+ *
+ * Cohort inbound is not one surface, it is fourteen. Four of them are ROOMS (a
+ * DM, an @mention, a thread reply, a call invite) and a reply to those is a
+ * `messaging.send` into a channel id. The other ten are ENTITIES — a board
+ * item's comment thread, a doc's comment thread, a decision's thread, an
+ * approval, a handoff — and their reply surface is the ENTITY, not a room.
+ * `lib/org/inbound/project.mjs` names this exact failure mode in a comment.
+ *
+ * SOME OF THEM DO CARRY A CHANNEL, and this module routes them to the entity
+ * anyway. `lib/org/inbound/hydrate.mjs` sets
+ * `channelId: c.ids.channelId || (task && task.channelId) || ""`, so a task
+ * that lives in a Space has a real, sendable channel id, and the old code did
+ * deliver those — as a loose chat message in the Space, detached from the task
+ * thread the human was reading. THIS IS A DELIBERATE, VISIBLE BEHAVIOUR CHANGE:
+ * a board comment now gets a board comment, always, not "a board comment when
+ * we happen to have nowhere else to put it". The reply lands where the question
+ * was asked. If that is ever wrong, the fix is a `room()` fallback on the board
+ * case — not restoring `channel_id ||` as a silent first choice.
+ *
+ * Downstream never enforced it. `sendCohortReply` read
+ * `item.channel_id || item.channel`, and `item.channel` is the HUMAN LABEL
+ * (`lib/channels/inbox-item.mjs` carries `channel_label` there:
+ * `task/Roll out tier-3 guardrails…`, `doc/AI-BORN-CHARTER…pdf`,
+ * `approval/…`). So a board comment was answered by posting the reply to a
+ * channel whose id was a task's TITLE. hq's messaging.send resolves that to
+ * nothing and throws NOT_FOUND; the daemon caught it, logged a warning, and
+ * `deliverWithRetry` — whose permanent-failure test only matched send-gate
+ * blocks — retried the structurally impossible send three times, every sweep,
+ * forever. Six live items on one agent's disk were in that state.
+ *
+ * The rule this module now enforces, at the ONE chokepoint every outbound
+ * crosses (the answer, the acknowledgement and the assurance sweep all land in
+ * `deliver`):
+ *
+ *   A LABEL IS NEVER AN ID. An item from a surface with no room is answered ON
+ *   THAT SURFACE — a board comment gets a board comment — and an item that
+ *   cannot be addressed at all fails LOUDLY, permanently, with the reason,
+ *   rather than being guessed into a channel that does not exist.
+ *
+ * `item.channel` is not consulted anywhere on the send path any more, on any
+ * service: telegram's is `dm/<name>`, Cohort's is `task/<title>`. There is no
+ * correct case for it.
+ */
+
+/** Surfaces that genuinely live in a Cohort room — these reply with a message. */
+const CHANNEL_SURFACES = Object.freeze(["dm", "mention", "thread_reply", "call"]);
+
+/**
+ * Error frame codes a retry cannot change.
+ *
+ * `UNAUTHORIZED` IS DELIBERATELY NOT ON THIS LIST. The others describe the
+ * REQUEST — a task that does not exist, a body hq will never accept, a scope
+ * this key does not hold — and re-sending the identical bytes cannot change the
+ * answer. A 401 describes the CREDENTIAL at one instant: a token mid-rotation,
+ * an hq restart between issuing and honouring, a clock skew on a signature.
+ * Treating it as permanent throws the reply away on the first blip of an
+ * otherwise healthy deployment, which is a strictly worse failure than one
+ * extra attempt.
+ */
+const PERMANENT_RPC_CODES = Object.freeze([
+  "NOT_FOUND",
+  "BAD_REQUEST",
+  "FORBIDDEN",
+  "FORBIDDEN_SCOPE",
+]);
+
+/**
+ * The one BAD_REQUEST a board comment is allowed to answer by re-asking with a
+ * different author kind. hq's `board/addTaskComment.ts` throws
+ * "this task has no responsible agent to reply" / "responsible agent not found"
+ * when `kind:"agent"` finds no assignee and no reviewer. Matched on the phrase
+ * both messages share, so a reworded message keeps working and an unrelated
+ * BAD_REQUEST (a malformed body, a bad id) stays permanent.
+ */
+const NO_RESPONSIBLE_AGENT = /responsible agent/i;
+
+function str(v) {
+  return v == null ? "" : String(v).trim();
+}
+
+/** The entity id `project.mjs` stamped into `raw_ref` (`cohort:<surface>:<id>:<seq>`). */
+function entityFromRawRef(item) {
+  const m = /^cohort:[a-z_]+:(.+):[^:]*$/.exec(str(item && item.raw_ref));
+  return m ? str(m[1]) : "";
+}
+
+/**
+ * The inbound SURFACE this Cohort item came from.
+ *
+ * `raw_ref` is authoritative — `project.mjs` writes the surface name into it
+ * verbatim. `item.kind` is the fallback, but it is LOSSY: `doc_comment` (a
+ * workspace doc, family `files`) and `file_comment` (a chat attachment, family
+ * `file`) share the MessageEvent kind `file_comment` and take different reply
+ * methods with different id shapes, so they are told apart by the one thing
+ * that distinguishes them — the chat attachment always names its room.
+ */
+export function cohortSurfaceOf(item) {
+  if (!item) return "";
+  // Guarded against the LEGACY raw_ref shape, which is `cohort:<channelId>:
+  // <messageId>` — still on disk today. An all-lowercase channel id would
+  // otherwise parse as a surface name and route a working DM to nowhere.
+  const m = /^cohort:([a-z_]+):/.exec(str(item.raw_ref));
+  if (m && SURFACE_NAMES.includes(m[1])) return m[1];
+  const kind = str(item.kind);
+  if (kind === "file_comment") return str(item.channel_id) ? "file_comment" : "doc_comment";
+  if (!kind || kind === "message") return "dm";
+  return kind;
+}
+
+/**
+ * Where a reply to this Cohort item goes — a pure function of the item, so it
+ * can be asked BEFORE anything is promised (see `canDeliverTo`).
+ *
+ * @param {object} item daemon inbox item (service === "cohort")
+ * @returns {{transport:"channel", surface:string, channelId:string, target:string}
+ *          |{transport:"rpc", surface:string, method:string, params:object, bodyKey:string, target:string}
+ *          |{transport:null, surface:string, error:string}}
+ */
+export function cohortReplyRoute(item) {
+  if (!item) return { transport: null, surface: "", error: "no item" };
+  const surface = cohortSurfaceOf(item);
+  const channelId = str(item.channel_id);
+  const threadId = str(item.thread_id);
+  const scopeId = str(item.scope_id);
+  const entity = entityFromRawRef(item);
+
+  // A surface whose reply IS a room message. `channel_id` only ever carries a
+  // real Cohort channel id (project.mjs guarantees it); blank means no room.
+  const room = (why) =>
+    channelId
+      ? { transport: "channel", surface, channelId, target: channelId }
+      : { transport: null, surface, error: why };
+
+  if (CHANNEL_SURFACES.includes(surface)) {
+    return room(`cohort ${surface} item has no channel_id — nothing to reply into`);
+  }
+
+  switch (surface) {
+    // ── board. The task id comes from `scope_id`, else `thread_id`, else
+    //    `raw_ref`. hydrate.mjs sets `threadId: taskId`; `project.mjs`'s
+    //    `scope_id` is `taskId || decisionId || fileId`, i.e. NOT surface-typed
+    //    — which is safe here only because a board item is the one surface whose
+    //    `scope_id` is a task (the live approval item on disk proves the general
+    //    case: its `scope_id` is a task id while its `thread_id` is the approval,
+    //    and approvals have no RPC route at all).
+    //
+    //    `kind` DECIDES WHOSE NAME IS ON THE COMMENT, and hq resolves it
+    //    server-side (`server/methods/board/addTaskComment.ts`):
+    //      "agent" → the task's assignee, else its reviewer;
+    //      "human" → the ACTING member, i.e. this paired agent.
+    //    "human" is the safer call for authorship and the wrong one for
+    //    LABELLING: `components/board/task-conversation.tsx` renders
+    //    `kind === "human"` as the viewer's own "me" bubble WITHOUT an
+    //    `<Avatar kind>` — so an AI reply arrived looking like something the
+    //    reading human had written themselves, on the one lane whose whole
+    //    argument is AI disclosure. So: ask for "agent", which is both the
+    //    honest label and, for a directed board item, the correct author (the
+    //    inbound is directed here BECAUSE this agent is the assignee/reviewer);
+    //    and fall back to "human" for the one case hq refuses it — an
+    //    unassigned, unreviewed task, where "agent" is a BAD_REQUEST and the
+    //    acting member is the only author there is. See `fallbackParams`.
+    case "task_assigned":
+    case "task_comment": {
+      const taskId = scopeId || threadId || entity;
+      if (!taskId) {
+        return { transport: null, surface, error: "board item carries no task id (scope_id, thread_id and raw_ref all blank)" };
+      }
+      return {
+        transport: "rpc", surface,
+        method: "board.addTaskComment",
+        params: { taskId, kind: "agent" },
+        fallbackParams: { taskId, kind: "human" },
+        fallbackWhen: NO_RESPONSIBLE_AGENT,
+        bodyKey: "body",
+        target: `task:${taskId}`,
+      };
+    }
+
+    // ── workspace doc (family `files`). Both handles are the File id.
+    case "doc_comment": {
+      const fileId = scopeId || threadId || entity;
+      if (!fileId) {
+        return { transport: null, surface, error: "doc comment carries no file id (scope_id, thread_id and raw_ref all blank)" };
+      }
+      return {
+        transport: "rpc", surface,
+        method: "files.commentAdd",
+        params: { fileId },
+        bodyKey: "body",
+        target: `file:${fileId}`,
+      };
+    }
+
+    // ── chat attachment (family `file`). The handle is the opaque `fileKey`,
+    //    which hydrate.mjs puts in `threadId` — `raw_ref` here holds the
+    //    COMMENT id, not the file, so it is deliberately not a fallback. hq's
+    //    `file.addComment` also requires the room the attachment lives in.
+    case "file_comment": {
+      const fileKey = threadId;
+      if (!fileKey) return { transport: null, surface, error: "chat file comment carries no fileKey (thread_id blank)" };
+      if (!channelId) return { transport: null, surface, error: `chat file comment on ${fileKey} has no channel_id — file.addComment requires one` };
+      return {
+        transport: "rpc", surface,
+        method: "file.addComment",
+        params: { fileKey, channelId },
+        bodyKey: "body",
+        target: `file:${fileKey}`,
+      };
+    }
+
+    // ── decision. NOTE the param is `text`, not `body` (decision/comment.ts).
+    case "decision": {
+      const decisionId = scopeId || threadId || entity;
+      if (!decisionId) {
+        return { transport: null, surface, error: "decision carries no decision id (scope_id, thread_id and raw_ref all blank)" };
+      }
+      return {
+        transport: "rpc", surface,
+        method: "decision.comment",
+        params: { decisionId },
+        bodyKey: "text",
+        target: `decision:${decisionId}`,
+      };
+    }
+
+    // ── escalation / calendar. hq attaches a real channel to these when the
+    //    entity is room-bound, and that channel IS the surface. When it is not
+    //    (an escalation hanging off a task, an event with no room) there is no
+    //    prose surface to write into: neither family has a comment method.
+    case "escalation":
+      return room("escalation is not room-bound and has no comment surface (escalation.resolve/answer are verdicts, not messages)");
+    case "calendar":
+      return room("calendar event is not room-bound and has no comment surface");
+
+    // ── verdict surfaces. Answering these is an ACT, not a sentence, and
+    //    guessing an act from generated prose is not something this transport
+    //    is allowed to do. Undeliverable is the honest answer — assurance then
+    //    escalates to an operator instead of promising a reply it cannot send.
+    case "approval":
+      return { transport: null, surface, error: "approval has no comment surface — a response is a verdict (approval.resolve), not a message" };
+    case "handoff":
+      return { transport: null, surface, error: "handoff has no comment surface — a response is handoff.accept/decline, not a message" };
+
+    // ── email. `channel_id` on this surface is a MAILBOX id, which
+    //    messaging.send would reject exactly like a task title did. Replying
+    //    needs `email.send` with a recipient address, and the inbox item does
+    //    not carry one (only the sender's display name survives projection).
+    case "email":
+      return { transport: null, surface, error: "cohort email reply needs email.send with a recipient address; this item carries none (channel_id is a mailbox id, not a channel)" };
+
+    default:
+      return { transport: null, surface, error: `unknown cohort surface ${surface || "(none)"} — no reply route` };
+  }
+}
+
 /**
- * The channel a reply to this item belongs in, whatever the service — the key
- * both the receipt ledger and the obligation ledger are keyed on.
+ * The place a reply to this item belongs, whatever the service — the key both
+ * the receipt ledger and the obligation ledger are keyed on.
+ *
+ * Routing is by SURFACE, not by person: the surface the inbound arrived on is
+ * the surface the answer belongs on. For a room that is the channel id; for an
+ * entity thread it is `task:<id>` / `file:<id>` / `decision:<id>`.
  *
- * Routing is by ROOM, not by person: the room the inbound arrived in is the
- * room the answer belongs in.
+ * Returns null — never a label — when nothing addressable exists.
  */
 export function replyTargetOf(item) {
   if (!item) return null;
   if (item.service === "slack") return resolveSlackChannel(item);
   if (item.service === "gmail") return item.sender_email || item.sender || null;
-  return item.channel_id || item.channel || null;
+  if (item.service === "cohort") {
+    const route = cohortReplyRoute(item);
+    return route.transport ? route.target : null;
+  }
+  // Every other producer addresses by id. `item.channel` is the display LABEL
+  // (`dm/<name>`) and was the fallback here until it got handed to a send.
+  return item.channel_id || null;
 }
 
 /**
@@ -93,7 +367,13 @@ export const DELIVERABLE_SERVICES = Object.freeze(["slack", "gmail", "cohort"]);
 
 /**
  * Can `deliver` reach the human behind this item at all? Requires both a
- * transport for the service AND a resolvable room to write into.
+ * transport for the service AND a resolvable surface to write onto.
+ *
+ * This used to answer TRUE for every Cohort board/doc/decision item, because
+ * `replyTargetOf` fell through to the human label and a label is truthy. The
+ * assurance ledger asks this BEFORE it promises an acknowledgement, so a "yes"
+ * here on an unsendable item is how the daemon came to promise a reply it had
+ * no way to deliver.
  */
 export function canDeliverTo(item) {
   if (!item || !item.service) return false;
@@ -172,9 +452,13 @@ async function sendGmailResponse(item, text) {
 // ---------------------------------------------------------------------------
 
 /**
- * Send onto Cohort. Goes through lib/org/messaging.sendMessage rather than the
- * raw RPC so the outbound send-gate, the afterSend hook and cost attribution
- * all still run.
+ * Send onto Cohort — ONTO THE SURFACE THE ITEM CAME FROM.
+ *
+ * `cohortReplyRoute` decides. A room surface goes through
+ * lib/org/messaging.sendMessage (so the outbound send-gate, the afterSend hook
+ * and cost attribution all still run); an entity thread goes through its own
+ * comment method with the send-gate applied here. Nothing guesses a channel,
+ * and `item.channel` — a human label — is never read.
  *
  * `idempotencySuffix` distinguishes the several distinct things we may say
  * about ONE item — the acknowledgement, the FIRST progress update, the SECOND
@@ -189,29 +473,151 @@ async function sendGmailResponse(item, text) {
  * dedup doing its job.
  */
 async function sendCohortReply(item, text, o = {}) {
+  const route = cohortReplyRoute(item);
+
+  // LOUD. A reply with nowhere to go is a defect in the item or in the routing
+  // table above, and the whole reason this bug survived for months is that its
+  // symptom was a caught NOT_FOUND folded into a warning nobody read. Say the
+  // surface, say why, and mark it PERMANENT so the sweep stops re-sending it.
+  if (!route.transport) {
+    const why = `cannot address a reply to ${route.surface || "unknown"} item ${str(item && (item.raw_ref || item.id)) || "(no ref)"}: ${route.error}`;
+    console.error(`[deliver] ${why}`);
+    return { sent: false, via: null, permanent: true, surface: route.surface, error: why };
+  }
+
   try {
-    const channel = item.channel_id || item.channel || "";
-    if (!channel) return { sent: false, via: null, error: "no channel_id on item" };
-    const { sendMessage } = await import("../../lib/org/messaging.mjs");
-    const { loadOrgConfig } = await import("../../lib/org/client.mjs");
-    const agentRoot = process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+    const agentRoot = o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+    const cfg = o.cfg || (await import("../../lib/org/client.mjs")).loadOrgConfig(agentRoot);
     const base = item.message_id || item.id || item.raw_ref || Date.now();
     const suffix = o.idempotencySuffix ? `-${o.idempotencySuffix}` : "";
-    const frame = await sendMessage(
-      {
-        channel,
-        body: text,
-        idempotencyId: `reply-${base}${suffix}`,
-        ...(item.thread_id ? { threadId: item.thread_id } : {}),
-        ...(Array.isArray(o.mentions) && o.mentions.length ? { mentions: o.mentions } : {}),
-      },
-      { cfg: loadOrgConfig(agentRoot), agentRoot },
-    );
-    if (frame && frame.ok) return { sent: true, via: "cohort", channel };
-    return { sent: false, via: null, channel, error: (frame && frame.error && frame.error.message) || "send failed" };
+    const idempotencyId = `reply-${base}${suffix}`;
+
+    let frame;
+    if (route.transport === "channel") {
+      const sendMessageImpl = o.sendMessageImpl || (await import("../../lib/org/messaging.mjs")).sendMessage;
+      frame = await sendMessageImpl(
+        {
+          channel: route.channelId,
+          body: text,
+          idempotencyId,
+          ...(item.thread_id ? { threadId: item.thread_id } : {}),
+          ...(Array.isArray(o.mentions) && o.mentions.length ? { mentions: o.mentions } : {}),
+        },
+        {
+          cfg, agentRoot,
+          ...(o.gateImpl ? { gateImpl: o.gateImpl } : {}),
+          ...(o.fetchImpl ? { fetchImpl: o.fetchImpl } : {}),
+        },
+      );
+    } else {
+      frame = await sendCohortEntityComment(route, text, { ...o, cfg, agentRoot, idempotencyId });
+    }
+
+    if (frame && frame.ok) return { sent: true, via: route.transport === "channel" ? "cohort" : route.method, channel: route.target, surface: route.surface };
+    const code = str(frame && frame.error && frame.error.code);
+    const message = str(frame && frame.error && frame.error.message) || "send failed";
+    if (code && PERMANENT_RPC_CODES.includes(code)) {
+      // A NOT_FOUND/BAD_REQUEST is the server saying "this can never work".
+      // Retrying it is what produced `"attempts":3` on every failed row.
+      console.error(`[deliver] ${route.method || "messaging.send"} → ${route.target}: ${code} ${message} (permanent, not retrying)`);
+      return { sent: false, via: null, permanent: true, channel: route.target, surface: route.surface, code, error: `${code}: ${message}` };
+    }
+    return { sent: false, via: null, channel: route.target, surface: route.surface, ...(code ? { code } : {}), error: code ? `${code}: ${message}` : message };
   } catch (err) {
-    return { sent: false, via: null, error: err && err.message };
+    return { sent: false, via: null, channel: route.target, surface: route.surface, error: err && err.message };
+  }
+}
+
+/**
+ * Post onto a Cohort ENTITY thread (a task, a doc, a chat attachment, a
+ * decision) rather than into a room.
+ *
+ * The send-gate runs here too, and FAIL-CLOSED. `lib/org/messaging.sendMessage`
+ * is the chokepoint for room messages; these routes bypass it, so without this
+ * a board reply would be the one outbound in the system that skipped
+ * banned-phrase, AI-disclosure and information-barrier screening. Fail-closed
+ * matches messaging.mjs's own Cohort posture: never send what we could not
+ * screen.
+ *
+ * THE GATE IS CALLED WITH THE SAME ARGUMENTS THE ROOM LANE USES, all of them.
+ * `screenOutbound` defaults `firstContact` to TRUE (send-gate.mjs), and under
+ * the shipped `disclose-always` posture that blocks any message which does not
+ * proactively disclose AI. `lib/org/messaging.sendMessage` passes `false` on
+ * purpose — an org room is a continuing conversation with colleagues, not a
+ * cold approach — and so must this. Omitting it made the gate refuse 100% of
+ * board/doc/decision replies with FORBIDDEN_SCOPE, which is in
+ * {@link PERMANENT_RPC_CODES}: dropped on the first attempt, never retried.
+ * A routing table that reaches the wrong wire and a routing table that reaches
+ * no wire at all are the same bug wearing different error strings, so the test
+ * for this lane runs the REAL gate against the REAL policies rather than a stub
+ * (`deliver.test.mjs`, "the real send-gate").
+ */
+async function sendCohortEntityComment(route, text, o = {}) {
+  const { errFrame } = await import("../../lib/org/protocol.mjs");
+  const gate = o.gateImpl || screenOutbound;
+  let screened;
+  try {
+    screened = await gate({
+      channel: "cohort",
+      recipient: route.target,
+      text,
+      agentRoot: o.agentRoot || AGENT_REPO_DIR,
+      jurisdiction: o.jurisdiction,
+      firstContact: o.firstContact !== undefined ? o.firstContact : false,
+      internalDomains: o.internalDomains || [],
+      allowlist: o.allowlist,
+    });
+  } catch (err) {
+    return errFrame("INTERNAL", `send-gate error: ${err && err.message ? err.message : String(err)}`);
+  }
+  if (!screened || !screened.allow) {
+    return errFrame("FORBIDDEN_SCOPE", (screened && screened.reason) || "blocked by send-gate");
+  }
+  const body = screened.redactedText != null ? screened.redactedText : text;
+
+  // Same enrollment resolution messaging.mjs uses — one place decides whether
+  // this agent is paired, and to which base.
+  const { isEnabled, configFromAgent, call } = await import("../../lib/org/client.mjs");
+  if (!isEnabled(o.cfg)) return errFrame("BAD_REQUEST", "org messaging disabled or unconfigured");
+  const c = configFromAgent(o.cfg);
+  if (!c.base) return errFrame("BAD_REQUEST", "org messaging disabled or unconfigured");
+
+  const callImpl = o.callImpl || call;
+  const wire = (params) =>
+    callImpl(
+      route.method,
+      { ...params, [route.bodyKey]: body },
+      { base: c.base, token: c.token, orgId: c.orgId, idempotencyKey: o.idempotencyId || undefined, fetchImpl: o.fetchImpl },
+    );
+
+  let frame = await wire(route.params);
+
+  // ONE re-ask, on ONE named refusal, with a DIFFERENT request — not a retry.
+  // `deliverWithRetry` re-sends the same bytes and cannot help here: hq has
+  // already told us this task has nobody to attribute an agent comment to, and
+  // it will say so again. See the `kind` note on the board route.
+  if (
+    frame && !frame.ok && route.fallbackParams &&
+    str(frame.error && frame.error.code) === "BAD_REQUEST" &&
+    (!route.fallbackWhen || route.fallbackWhen.test(str(frame.error && frame.error.message)))
+  ) {
+    console.warn(`[deliver] ${route.method} → ${route.target}: ${str(frame.error.message)} — re-asking as the acting member`);
+    frame = await wire(route.fallbackParams);
+  }
+
+  if (frame && frame.ok) {
+    try {
+      await getHookBus().emit("afterSend", { channel: "cohort", recipient: route.target, text: body, result: frame.result, source: route.method });
+    } catch { /* observe-only: a broken subscriber must never break a send */ }
+    // Cost/usage attribution, exactly as `lib/org/messaging.sendMessage` does it
+    // for a room send (its invariant #3). Without this the board/doc/decision
+    // lane was the one outbound family missing from the messaging ledger.
+    try {
+      const { attributeMessaging } = await import("../../lib/org/messaging.mjs");
+      await attributeMessaging({ cfg: o.cfg, agentRoot: o.agentRoot, action: route.method, channel: route.target }, o);
+    } catch { /* attribution is observational — never fail a delivered send on it */ }
   }
+  return frame;
 }
 
 // ---------------------------------------------------------------------------
@@ -231,11 +637,17 @@ async function sendCohortReply(item, text, o = {}) {
  * @param {string} text      exactly what the human will read
  * @param {object} [o]
  * @param {string} [o.kind]  receipt kind: "ack" | "progress" | "failure" | "reply"
- * @param {string[]} [o.mentions] org member ids to @-tag (cohort only)
+ * @param {string[]} [o.mentions] org member ids to @-tag (cohort room sends only)
  * @param {function} [o.fetchImpl] test seam
- * @returns {Promise<{sent:boolean, via:string|null, channel?:string, error?:string}>}
+ * @param {function} [o.callImpl] test seam — the org RPC (entity-thread routes)
+ * @param {function} [o.sendMessageImpl] test seam — messaging.send (room routes)
+ * @param {function} [o.gateImpl] test seam — the outbound send-gate
+ * @param {object} [o.cfg] test seam — org config, else loaded from disk
+ * @returns {Promise<{sent:boolean, via:string|null, channel?:string, surface?:string,
+ *                    permanent?:boolean, code?:string, error?:string}>}
  *          NEVER throws — a transport failure is returned, so the caller can
- *          escalate rather than lose the message to an exception.
+ *          escalate rather than lose the message to an exception. `permanent`
+ *          means retrying cannot help (no route, or a NOT_FOUND/BAD_REQUEST).
  */
 export async function deliver(item, text, o = {}) {
   const kind = o.kind || "reply";
@@ -302,8 +714,11 @@ export async function deliverWithRetry(item, text, o = {}) {
     last = await deliver(item, text, o);
     if (last.sent) return { ...last, attempts: i + 1 };
     // A policy block is a decision, not a fault — retrying re-runs the same
-    // deterministic screen and gets the same answer. Stop and surface it.
-    if (last.permanent || (last.error && /send-gate blocked|blocked by send-gate|FORBIDDEN/i.test(last.error))) {
+    // deterministic screen and gets the same answer. So is a NOT_FOUND: the
+    // server has said the thing we are writing to does not exist, and a second
+    // and third attempt only widen the hole. Every `"attempts":3` row in the
+    // response log was one impossible send tried three times. Stop, surface it.
+    if (last.permanent || (last.error && /send-gate blocked|blocked by send-gate|FORBIDDEN|NOT_FOUND/i.test(last.error))) {
       return { ...last, attempts: i + 1, permanent: true };
     }
     if (i < attempts - 1) await sleep(base * Math.pow(2, i));
@@ -311,4 +726,13 @@ export async function deliverWithRetry(item, text, o = {}) {
   return { ...last, attempts };
 }
 
-export default { deliver, deliverWithRetry, resolveSlackChannel, replyTargetOf, canDeliverTo, DELIVERABLE_SERVICES };
+export default {
+  deliver,
+  deliverWithRetry,
+  resolveSlackChannel,
+  replyTargetOf,
+  canDeliverTo,
+  cohortReplyRoute,
+  cohortSurfaceOf,
+  DELIVERABLE_SERVICES,
+};