@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/org/inbound/index.test.mjs

@@ -0,0 +1,324 @@
+/**
+ * index.test.mjs — end-to-end `pullWideInbound` over an injected fake org.
+ *
+ * One realistic ledger window carrying ten families is pulled and the result is
+ * asserted twice: as MessageEvents, and as the flat inbox items the daemon
+ * actually consumes. The negative half is asserted by CALL LOG — a private room
+ * this agent is not in must produce no history fetch, no body, and no item.
+ *
+ * Run: node --test lib/org/inbound/index.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { pullWideInbound } from "./index.mjs";
+import { eventToInboxItem } from "../../channels/inbox-item.mjs";
+
+const ME = "M-me";
+const THEM = "M-them";
+const BOSS = "M-boss";
+
+const okFrame = (result) => ({ ok: true, result });
+const okRead = (payload) => ({ ok: true, payload, status: 200 });
+
+/** An org fake: routes for `call` + `read`, with a full call log. */
+function fakeIo(routes = {}) {
+  const calls = [];
+  const logs = [];
+  return {
+    calls,
+    logs,
+    stats: { calls: 0, reads: 0, failures: 0, methods: [] },
+    log: (level, message, meta) => logs.push({ level, message, meta }),
+    async call(method, params) {
+      calls.push({ method, params });
+      this.stats.calls += 1;
+      const h = routes[method];
+      if (!h) return { ok: false, error: { code: "NOT_FOUND", message: method } };
+      return typeof h === "function" ? await h(params) : h;
+    },
+    async read(path) {
+      const base = String(path).split("?")[0];
+      calls.push({ method: `read:${base}`, path });
+      this.stats.reads += 1;
+      const h = routes[`read:${base}`];
+      if (!h) return { ok: false, error: { code: "NOT_FOUND", message: base }, status: 404 };
+      return typeof h === "function" ? await h(path) : h;
+    },
+  };
+}
+
+/** A cfg that passes `isEnabled` + `configFromAgent`. */
+const CFG = { org: { cohort: { enabled: true, base: "https://os.cohortapp.com/adaptic", token: "tok" } } };
+
+// A ledger window with one row per surface, plus three rows that must NOT reach me.
+const LEDGER = [
+  // (1) DM to me
+  { seq: 1, family: "messaging", kind: "send", entity_id: "m-dm", actor: THEM, at: "2026-08-11T09:00:00.000Z",
+    payload: { actor: THEM, channelId: "C-dm", channelKind: "DM", mentionCount: 0, threaded: false } },
+  // (2) @mention in a public space — THE headline gap
+  { seq: 2, family: "messaging", kind: "send", entity_id: "m-mention", actor: THEM, at: "2026-08-11T09:01:00.000Z",
+    payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 1, threaded: false } },
+  // (3) thread reply in a thread I started
+  { seq: 3, family: "messaging", kind: "send", entity_id: "m-thread", actor: THEM, at: "2026-08-11T09:02:00.000Z",
+    payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 0, threaded: true } },
+  // (4) NEGATIVE: someone else's DM
+  { seq: 4, family: "messaging", kind: "send", entity_id: "m-theirs", actor: THEM, at: "2026-08-11T09:03:00.000Z",
+    payload: { actor: THEM, channelId: "C-theirs", channelKind: "DM", mentionCount: 0, threaded: false } },
+  // (5) NEGATIVE: ambient public chatter
+  { seq: 5, family: "messaging", kind: "send", entity_id: "m-noise", actor: THEM, at: "2026-08-11T09:04:00.000Z",
+    payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 0, threaded: false } },
+  // (6) board assignment to me
+  { seq: 6, family: "board", kind: "item.assigned", entity_id: "T-1", actor: BOSS, at: "2026-08-11T09:05:00.000Z",
+    payload: { actor: BOSS, assignee: ME, assignedBy: BOSS } },
+  // (7) comment on my task
+  { seq: 7, family: "board", kind: "item.commented", entity_id: "T-1", actor: THEM, at: "2026-08-11T09:06:00.000Z",
+    payload: { actor: THEM, kind: "human" } },
+  // (8) NEGATIVE: comment on someone else's task
+  { seq: 8, family: "board", kind: "item.commented", entity_id: "T-99", actor: THEM, at: "2026-08-11T09:07:00.000Z",
+    payload: { actor: THEM, kind: "human" } },
+  // (9) doc comment on a doc I own
+  { seq: 9, family: "files", kind: "doc.comment", entity_id: "F-1", actor: THEM, at: "2026-08-11T09:08:00.000Z",
+    payload: { name: "Spec", commentId: "dc1", anchored: false } },
+  // (10) approval on my desk
+  { seq: 10, family: "approval", kind: "approval.requested", entity_id: "A-1", actor: THEM, at: "2026-08-11T09:09:00.000Z",
+    payload: { requester: THEM, actionClass: "spend.over_1k", payloadHash: "h" } },
+  // (11) decision I proposed gets an adjustment request
+  { seq: 11, family: "decision", kind: "decision.adjustment_requested", entity_id: "D-1", actor: THEM, at: "2026-08-11T09:10:00.000Z",
+    payload: { commentId: "c1", authorId: THEM, isAdjustment: true, length: 12 } },
+  // (12) handoff offered to me
+  { seq: 12, family: "handoff", kind: "handoff.offered", entity_id: "R-1", actor: THEM, at: "2026-08-11T09:11:00.000Z",
+    payload: { itemId: "T-1", from: THEM, to: ME, intent: "take this over", handoffId: "H-1" } },
+  // (13) inbound email to my mailbox (surface OFF by default)
+  { seq: 13, family: "email", kind: "received", entity_id: "EM-1", actor: "system", at: "2026-08-11T09:12:00.000Z",
+    payload: { emailMessageId: "EM-1", threadId: "ET-1", mailboxId: "MB-1", memberId: ME, autoSubmitted: false } },
+  // (14) noise family the daemon must never be woken for
+  { seq: 14, family: "presence", kind: "beat", entity_id: null, actor: THEM, at: "2026-08-11T09:13:00.000Z",
+    payload: { focus: "x" } },
+  // (15) my OWN message — the echo that must never come back
+  { seq: 15, family: "messaging", kind: "send", entity_id: "m-mine", actor: ME, at: "2026-08-11T09:14:00.000Z",
+    payload: { actor: ME, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 1, threaded: false } },
+];
+
+function routes(over = {}) {
+  return {
+    "read:events": okRead({ events: LEDGER }),
+    "messaging.channels": okFrame({
+      channels: [
+        { id: "C-dm", kind: "DM", slug: "dm-them", name: "them" },
+        { id: "C-pub", kind: "PUBLIC", slug: "general", name: "General" },
+      ],
+    }),
+    "messaging.history": ({ channelId }) => {
+      if (channelId === "C-dm") {
+        return okFrame({ channelId, messages: [{ id: "m-dm", authorId: THEM, authorName: "Casey", body: "are you free at 3?", mentions: [] }] });
+      }
+      if (channelId === "C-pub") {
+        return okFrame({
+          channelId,
+          messages: [
+            { id: "root-1", authorId: ME, authorName: "Isla", body: "kicking off the migration", mentions: [] },
+            { id: "m-mention", authorId: THEM, authorName: "Casey", body: "@Isla can you review this?", mentions: [ME] },
+            { id: "m-thread", authorId: THEM, authorName: "Casey", body: "one more thing on that", threadRootId: "root-1", mentions: [] },
+            { id: "m-noise", authorId: THEM, authorName: "Casey", body: "standup at 10", mentions: [] },
+            { id: "m-mine", authorId: ME, authorName: "Isla", body: "on it", mentions: [ME] },
+          ],
+        });
+      }
+      throw new Error(`history fetched for a channel outside my roster: ${channelId}`);
+    },
+    "read:board.context": okRead({
+      lanes: [{ columns: { doing: [{ id: "T-1", title: "Migrate the DB", col: "doing", assigneeId: ME, reviewerId: null, detail: "zero downtime" }] } }],
+    }),
+    "board.taskComments": ({ taskId }) => okFrame({ taskId, comments: [{ id: "c1", authorId: THEM, authorName: "Casey", body: "how is this going?" }] }),
+    "files.get": ({ fileId }) =>
+      fileId === "F-1"
+        ? okFrame({ file: { id: "F-1", name: "Spec", ownerId: ME }, permission: "owner" })
+        : { ok: false, error: { code: "NOT_FOUND", message: "no" } },
+    "files.comments": okFrame({ comments: [{ id: "dc1", authorId: THEM, authorName: "Casey", body: "can we cut section 4?" }] }),
+    "approval.get": ({ id }) => okFrame({ id, requester: THEM, approver: ME, status: "pending", actionClass: "spend.over_1k", reason: "vendor renewal" }),
+    "read:decision.list": okRead({ decisions: [{ id: "D-1", title: "Adopt X", status: "proposed", proposedBy: ME, body: "we adopt X" }] }),
+    "decision.listComments": okFrame({ comments: [{ id: "c1", authorId: THEM, authorName: "Casey", body: "what about Y?" }] }),
+    "email.thread": ({ threadId }) =>
+      okFrame({ thread: { id: threadId, subject: "Contract" }, messages: [{ id: "EM-1", subject: "Contract", text: "please review", from: { name: "Dana", address: "dana@acme.com" } }] }),
+    ...over,
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+test("one pull delivers every surface the agent is entitled to", async () => {
+  const io = fakeIo(routes());
+  const { events, nextCursor, stats } = await pullWideInbound({ cfg: CFG, agentId: ME, cursor: 0, io });
+
+  assert.equal(nextCursor, 15, "the cursor advances past every scanned row, delivered or not");
+  const bySurface = {};
+  for (const e of events) bySurface[e.cohort.surface] = (bySurface[e.cohort.surface] || 0) + 1;
+
+  assert.deepEqual(bySurface, {
+    dm: 1,
+    mention: 1,
+    thread_reply: 1,
+    task_assigned: 1,
+    task_comment: 1,
+    doc_comment: 1,
+    approval: 1,
+    decision: 1,
+    handoff: 1,
+  });
+  assert.equal(stats.scanned, 15);
+  assert.equal(stats.delivered, 9);
+});
+
+test("the typed reason rides along on every delivered item", async () => {
+  const io = fakeIo(routes());
+  const { events } = await pullWideInbound({ cfg: CFG, agentId: ME, io });
+  const reasons = Object.fromEntries(events.map((e) => [e.cohort.surface, e.cohort.reason]));
+  assert.deepEqual(reasons, {
+    dm: "dm",
+    mention: "mention",
+    thread_reply: "thread",
+    task_assigned: "assignee",
+    task_comment: "assignee",
+    doc_comment: "owner",
+    approval: "approver",
+    decision: "proposer",
+    handoff: "direct",
+  });
+});
+
+test("NEGATIVE: nothing from someone else's private room, my own echo, or ambient noise", async () => {
+  const io = fakeIo(routes());
+  const { events, stats } = await pullWideInbound({ cfg: CFG, agentId: ME, io });
+
+  const ids = events.map((e) => e.message_id);
+  assert.equal(ids.includes("m-theirs"), false, "someone else's DM must never be delivered");
+  assert.equal(ids.includes("m-mine"), false, "my own message must never come back");
+  assert.equal(ids.includes("m-noise"), false, "ambient public chatter is not inbound");
+  assert.equal(events.some((e) => e.cohort.entity_id === "T-99"), false, "another seat's task is not mine");
+
+  // Asserted by CALL LOG, not just by absence of output: the private room was
+  // never even probed.
+  const probed = io.calls.filter((c) => c.method === "messaging.history").map((c) => c.params.channelId);
+  assert.deepEqual(probed.sort(), ["C-dm", "C-pub"]);
+  assert.ok(stats.dropped.own_echo >= 1);
+  assert.ok(stats.dropped.channel_not_visible >= 1);
+});
+
+test("email is OFF by default and is not even hydrated", async () => {
+  const io = fakeIo(routes());
+  const { events } = await pullWideInbound({ cfg: CFG, agentId: ME, io });
+  assert.equal(events.some((e) => e.cohort.surface === "email"), false);
+  assert.equal(io.calls.some((c) => c.method === "email.thread"), false, "a disabled surface costs nothing");
+});
+
+test("email switches on explicitly (for a fleet with the orgmail adapter off)", async () => {
+  const io = fakeIo(routes());
+  const { events } = await pullWideInbound({ cfg: CFG, agentId: ME, io, surfaces: { email: true } });
+  const mail = events.find((e) => e.cohort.surface === "email");
+  assert.ok(mail, "email must be deliverable when enabled");
+  assert.equal(mail.kind, "email");
+  assert.equal(mail.text, "please review");
+});
+
+test("a surface subset turns everything else off", async () => {
+  const io = fakeIo(routes());
+  const { events } = await pullWideInbound({ cfg: CFG, agentId: ME, io, surfaces: ["mention"] });
+  assert.deepEqual(events.map((e) => e.cohort.surface), ["mention"]);
+});
+
+test("the delivered events survive eventToInboxItem with their routing hints intact", async () => {
+  const io = fakeIo(routes());
+  const { events } = await pullWideInbound({ cfg: CFG, agentId: ME, io });
+  const items = events.map(eventToInboxItem);
+
+  for (const item of items) {
+    assert.equal(item.service, "cohort");
+    assert.ok(item.id, "every item needs a dedup id");
+    assert.ok(item.content, "every item needs a body");
+    assert.ok(item.timestamp);
+  }
+  const kinds = items.map((i) => i.kind || "message").sort();
+  assert.deepEqual(kinds, [
+    "approval", "decision", "file_comment", "handoff", "mention",
+    "message", "task_assigned", "task_comment", "thread_reply",
+  ]);
+});
+
+test("the DM item is unchanged in shape from what ships today", async () => {
+  const io = fakeIo(routes());
+  const { events } = await pullWideInbound({ cfg: CFG, agentId: ME, io });
+  const dm = eventToInboxItem(events.find((e) => e.cohort.surface === "dm"));
+  assert.equal(dm.id, "cohort-m-dm");
+  assert.equal("kind" in dm, false);
+  assert.equal(dm.subject, "Cohort message");
+  assert.equal(dm.content, "are you free at 3?");
+  assert.equal(dm.sender, "Casey");
+  assert.equal(dm.source, "cohort");
+});
+
+// ---------------------------------------------------------------------------
+// failure modes
+// ---------------------------------------------------------------------------
+
+test("no agentId → refuses to pull, LOUDLY (own echoes would come back)", async () => {
+  const logs = [];
+  const io = fakeIo(routes());
+  const out = await pullWideInbound({ cfg: CFG, agentId: "", io, log: (l, m) => logs.push(`${l}:${m}`) });
+  assert.deepEqual(out.events, []);
+  assert.equal(io.calls.length, 0);
+  assert.ok(logs.some((l) => l.startsWith("error:") && /agentId/.test(l)));
+});
+
+test("org not configured → inert, no throw", async () => {
+  const out = await pullWideInbound({ cfg: { org: { cohort: { enabled: false } } }, agentId: ME });
+  assert.deepEqual(out.events, []);
+  assert.equal(out.nextCursor, 0);
+});
+
+test("events read fails → cursor HELD so nothing is skipped", async () => {
+  const io = fakeIo({ ...routes(), "read:events": { ok: false, error: { code: "INTERNAL", message: "boom" }, status: 500 } });
+  const out = await pullWideInbound({ cfg: CFG, agentId: ME, cursor: 7, io });
+  assert.deepEqual(out.events, []);
+  assert.equal(out.nextCursor, 7);
+});
+
+test("a degraded fact set closes surfaces rather than opening them", async () => {
+  // Roster unreadable: every messaging surface must go quiet, and say why.
+  const io = fakeIo({ ...routes(), "messaging.channels": { ok: false, error: { code: "INTERNAL", message: "down" } } });
+  const { events, stats } = await pullWideInbound({ cfg: CFG, agentId: ME, io });
+  assert.equal(events.some((e) => e.cohort.family === "messaging"), false);
+  assert.ok(stats.degraded.includes("channels"));
+  // The families that do not need the roster still work.
+  assert.ok(events.some((e) => e.cohort.surface === "task_assigned"));
+});
+
+test("an unhydratable directed item is dropped with a WARNING, not delivered blank", async () => {
+  const io = fakeIo({ ...routes(), "board.taskComments": { ok: false, error: { code: "INTERNAL", message: "down" } }, "files.get": { ok: false, error: { code: "INTERNAL", message: "down" } } });
+  const logs = [];
+  const { events } = await pullWideInbound({ cfg: CFG, agentId: ME, io, log: (l, m) => logs.push(`${l}:${m}`) });
+  // The board item still renders from the task card; the doc has no ACL entry so
+  // it never becomes directed in the first place.
+  assert.equal(events.some((e) => e.cohort.surface === "doc_comment"), false);
+  for (const e of events) assert.ok(e.text.trim(), "no blank body may ever be delivered");
+});
+
+test("stats report what was spent and why things were dropped", async () => {
+  const io = fakeIo(routes());
+  const { stats } = await pullWideInbound({ cfg: CFG, agentId: ME, io });
+  assert.equal(stats.scanned, 15);
+  // 15 rows in, 1 (`presence`) has no rule at all → never becomes a candidate.
+  assert.equal(stats.classified, 14, "noise families are dropped before any RPC is spent");
+  assert.ok(stats.calls > 0 && stats.reads > 0);
+  assert.ok(Object.keys(stats.dropped).length > 0);
+});
+
+test("an empty ledger window is a no-op that still advances nothing", async () => {
+  const io = fakeIo({ ...routes(), "read:events": okRead({ events: [] }) });
+  const out = await pullWideInbound({ cfg: CFG, agentId: ME, cursor: 5, io });
+  assert.deepEqual(out.events, []);
+  assert.equal(out.nextCursor, 5);
+});

package/lib/org/inbound/io.mjs

@@ -0,0 +1,141 @@
+/**
+ * lib/org/inbound/io.mjs — the ONE injectable network seam for wide inbound.
+ *
+ * Everything the directedness resolver and the hydrators need from hq goes
+ * through this object, so a test injects a plain fake and never touches the
+ * wire. It is a thin adapter over `lib/org/client.mjs` `call` / `read` that
+ * adds exactly three things the raw client does not:
+ *
+ *   1. Config resolution — `{cfg}` → `{base, token, orgId}` via the SAME
+ *      `isEnabled` + `configFromAgent` chain every other org module uses, so a
+ *      disabled agent is inert here for the same reason it is inert everywhere.
+ *   2. Uniform, NEVER-SILENT fail-open — every call returns
+ *      `{ok:false, error}` instead of throwing, AND logs the failure with the
+ *      method that failed. Silent fail-open has caused every bug in this area:
+ *      a swallowed `registry.register` error is why no agent was ever in the
+ *      directory, and a swallowed roster read is why DMs went missing.
+ *   3. A call counter, so the pull loop can report how much it spent and a test
+ *      can assert that a private room was NEVER probed.
+ *
+ * @module lib/org/inbound/io
+ */
+
+"use strict";
+
+import { isEnabled, configFromAgent, call as clientCall, read as clientRead } from "../client.mjs";
+
+/** A no-op logger with the daemon's `(level, message, meta?)` shape. */
+export function noopLog() {}
+
+/**
+ * Resolve `{base, token, orgId}` from an agent cfg, or null when the org
+ * integration is disabled/unconfigured. Mirrors `lib/org/messaging.resolveOrg`.
+ * @param {object} cfg
+ * @returns {{base:string, token:string, orgId:string}|null}
+ */
+export function resolveOrg(cfg) {
+  if (!isEnabled(cfg)) return null;
+  const c = configFromAgent(cfg);
+  if (!c.base) return null;
+  return { base: c.base, token: c.token, orgId: c.orgId };
+}
+
+/**
+ * @typedef {Object} InboundIo
+ * @property {(method:string, params?:object)=>Promise<object>} call  RPC → res frame
+ * @property {(path:string)=>Promise<object>} read                    GET  → {ok,payload}
+ * @property {(level:string, msg:string, meta?:object)=>void} log
+ * @property {{calls:number, reads:number, failures:number, methods:string[]}} stats
+ */
+
+/**
+ * Build the real IO seam from an agent cfg. Returns null when the org
+ * integration is off — the caller then does nothing at all (fail-open).
+ *
+ * @param {{cfg:object, fetchImpl?:Function, log?:Function, timeoutMs?:number}} o
+ * @returns {InboundIo|null}
+ */
+export function makeIo(o = {}) {
+  const org = resolveOrg(o.cfg);
+  if (!org) return null;
+  const log = typeof o.log === "function" ? o.log : noopLog;
+  const conn = {
+    base: org.base,
+    token: org.token,
+    orgId: org.orgId,
+    fetchImpl: o.fetchImpl,
+    ...(Number.isFinite(o.timeoutMs) ? { timeoutMs: o.timeoutMs } : {}),
+  };
+  const stats = { calls: 0, reads: 0, failures: 0, methods: [] };
+
+  return {
+    stats,
+    log,
+    async call(method, params = {}) {
+      stats.calls += 1;
+      stats.methods.push(method);
+      try {
+        const frame = await clientCall(method, params, conn);
+        if (!frame || frame.ok !== true) {
+          stats.failures += 1;
+          // NEVER SILENT. A directedness probe that fails changes the verdict,
+          // so the operator has to be able to see it in the daemon log.
+          log("warn", `[inbound] ${method} failed`, {
+            code: frame && frame.error ? frame.error.code : "NO_FRAME",
+            message: frame && frame.error ? frame.error.message : "no frame",
+          });
+        }
+        return frame;
+      } catch (err) {
+        stats.failures += 1;
+        log("warn", `[inbound] ${method} threw`, { error: err && err.message ? err.message : String(err) });
+        return { ok: false, error: { code: "INTERNAL", message: String((err && err.message) || err) } };
+      }
+    },
+    async read(path) {
+      stats.reads += 1;
+      stats.methods.push(`read:${String(path).split("?")[0]}`);
+      try {
+        const r = await clientRead(path, conn);
+        if (!r || r.ok !== true) {
+          stats.failures += 1;
+          log("warn", `[inbound] read ${path} failed`, {
+            code: r && r.error ? r.error.code : "NO_RESULT",
+            status: r ? r.status : 0,
+          });
+        }
+        return r;
+      } catch (err) {
+        stats.failures += 1;
+        log("warn", `[inbound] read ${path} threw`, { error: err && err.message ? err.message : String(err) });
+        return { ok: false, error: { code: "INTERNAL", message: String((err && err.message) || err) }, status: 0 };
+      }
+    },
+  };
+}
+
+/**
+ * Unwrap an RPC res frame into its result, or null. Accepts the two shapes hq
+ * returns (`{ok:true, result}` and a bare object) without guessing.
+ * @param {object} frame
+ * @returns {object|null}
+ */
+export function resultOf(frame) {
+  if (!frame || frame.ok !== true) return null;
+  return frame.result !== undefined ? frame.result : null;
+}
+
+/**
+ * Pull a named array out of an RPC result, tolerating the bare-array form.
+ * @param {object|null} result
+ * @param {string} key e.g. "messages" | "channels" | "comments"
+ * @returns {object[]}
+ */
+export function arrayOf(result, key) {
+  if (Array.isArray(result)) return result;
+  if (result && Array.isArray(result[key])) return result[key];
+  if (result && Array.isArray(result.items)) return result.items;
+  return [];
+}
+
+export default { makeIo, resolveOrg, resultOf, arrayOf, noopLog };

package/lib/org/inbound/project.mjs

@@ -0,0 +1,201 @@
+/**
+ * lib/org/inbound/project.mjs — surface → the existing MessageEvent contract.
+ *
+ * The whole point of this module is that the DAEMON NEEDS NO CHANGE. The legacy
+ * ingestion path (`scripts/daemon/agent-daemon.mjs poll()` → classifier →
+ * directed gate → thread lease → responder → dispatcher) consumes a flat inbox
+ * item produced by `lib/channels/inbox-item.eventToInboxItem`. Everything a new
+ * surface carries therefore has to ride on fields that converter already
+ * forwards:
+ *
+ *   kind            → `item.kind`  — the ROUTING HINT. One value per surface
+ *                     (see surfaces.mjs). `classifyByKind` returns null for all
+ *                     of them, so they fall through to the normal LLM classifier
+ *                     — correct, because a task assignment or an approval does
+ *                     need triage, unlike a reaction.
+ *   subject         → `item.subject` — "Cohort @mention: <channel>" etc.
+ *   content         → `item.content` — the hydrated body.
+ *   channel/_id     → the surface's own scope key (channel id, task id, …).
+ *   thread_id       → the reply anchor the responder replies INTO.
+ *   thread_context  → prior thread, already rendered.
+ *   raw_ref         → `cohort:<surface>:<entityId>:<seq>` — stable, greppable.
+ *   priority_signals→ mentions_agent / tagged_urgent are real, not guessed.
+ *   is_private      → a CONFIDENTIALITY assertion the daemon's outcome gate
+ *                     reads. Set only when we actually know the room class.
+ *
+ * The DM and call projections are deliberately byte-compatible with what
+ * `lib/org/messaging.toMessageEvent` produces today (kind "message" / "call",
+ * `id: cohort-<messageId>`, `raw_ref: cohort:<channel>:<message>`), so turning
+ * the wide tail on cannot re-deliver or re-shape the inbound that already works.
+ *
+ * PURE — no IO, no clock beyond an injectable `now`.
+ *
+ * @module lib/org/inbound/project
+ */
+
+"use strict";
+
+import { SURFACES } from "./surfaces.mjs";
+
+/** Blank-safe string. */
+function s(v) {
+  return v == null ? "" : String(v);
+}
+
+/** Urgency words that justify raising the item's priority signal. */
+const URGENT = /\b(urgent|asap|immediately|critical|p0|blocker|blocked|sev-?[01]|escalat\w*)\b/i;
+const DEADLINE = /\b(by (mon|tue|wed|thu|fri|sat|sun|tomorrow|today|eod|eow)|due\b|deadline|before \d)/i;
+
+/**
+ * Project a directed, hydrated candidate onto a MessageEvent.
+ *
+ * @param {Object} o
+ * @param {import("./directedness.mjs").Candidate} o.candidate
+ * @param {{surface:string, reason:string}} o.verdict
+ * @param {import("./hydrate.mjs").Hydrated} o.hydrated
+ * @param {string} o.me
+ * @param {import("./facts.mjs").Facts} [o.facts]
+ * @param {string} [o.now] ISO timestamp fallback
+ * @returns {object|null} a MessageEvent, or null when it must not be delivered
+ */
+export function toMessageEvent(o = {}) {
+  const { candidate: c, verdict, hydrated, me } = o;
+  if (!c || !verdict || !verdict.surface || !hydrated || hydrated.ok !== true) return null;
+  const def = SURFACES[verdict.surface];
+  if (!def) return null;
+
+  const facts = o.facts || {};
+  const seq = c.seq != null ? String(c.seq) : "";
+  const entityId = s(c.entityId);
+  const text = s(hydrated.text);
+  if (!text.trim() && verdict.surface !== "call") return null;
+
+  // ── ids. The inbox item's `id` is the DEDUP KEY: `writeInboxItem` refuses a
+  //    second write of the same id, and the cursor is only advanced AFTER the
+  //    write, so a crash re-pulls the same rows and the id must be STABLE across
+  //    that replay. `seq` is stable (it is the ledger position), so it is the
+  //    right discriminator for families whose entityId repeats across events
+  //    (a task gets many comments).
+  const messageId = messageIdFor(c, verdict);
+  const inboxId = inboxIdFor(c, verdict, messageId, seq);
+
+  const channelId = s(hydrated.channelId || c.ids.channelId || "");
+  const channelLabel = s(hydrated.channelLabel || channelId || "cohort");
+  const chan = facts.channels instanceof Map ? facts.channels.get(channelId) : null;
+  const channelKind = s((c.ids.channelKind || (chan && chan.kind) || "")).toUpperCase();
+
+  const subjectDetail = s(hydrated.subjectDetail);
+  const subject = subjectDetail ? `${def.subject}: ${subjectDetail}` : def.subject;
+
+  const from = hydrated.from || { id: s(c.actor), name: s(c.actor) };
+  const scope = scopeFor(verdict.surface, channelKind, def.scope);
+
+  const ev = {
+    channel: "cohort",
+    service: "cohort",
+    message_id: messageId,
+    id: inboxId,
+    thread_id: s(hydrated.threadId),
+    from: { id: s(from.id), name: s(from.name || from.id) },
+    text,
+    timestamp: c.at || o.now || new Date().toISOString(),
+    kind: def.kind,
+    subject,
+    // ONLY ever a real Cohort channel id, never an entity id standing in for
+    // one. `scripts/daemon/responder.mjs sendCohortReply` routes its reply with
+    // `messaging.send({channel: item.channel_id})`, so putting a task/decision
+    // id here would post-to-a-non-channel and 400. A surface with no room leaves
+    // this blank and is routed by `kind` + `raw_ref` instead (see the wiring
+    // note in this directory's module docs).
+    channel_id: channelId,
+    channel_label: channelLabel,
+    sender: s(from.name || from.id),
+    is_reply: Boolean(hydrated.isReply),
+    thread_context: hydrated.threadContext != null ? hydrated.threadContext : null,
+    priority_signals: {
+      from_ceo: false,
+      tagged_urgent: URGENT.test(text) || c.kind === "board.blocked" || c.family === "escalation",
+      contains_deadline: DEADLINE.test(text),
+      // TRUE only when this really is a direct address, so downstream triage can
+      // trust it. `channel`/`assignee` delivery is directed at the SEAT, not a
+      // literal @mention, and says so.
+      mentions_agent:
+        verdict.reason === "mention" ||
+        verdict.reason === "named" ||
+        verdict.reason === "dm" ||
+        verdict.reason === "direct",
+    },
+    raw_ref: `cohort:${verdict.surface}:${entityId || messageId}:${seq}`,
+    ingest_source: "cohort",
+    source: {
+      channel: "cohort",
+      chatId: channelId,
+      ...(hydrated.threadId ? { threadRef: s(hydrated.threadId) } : {}),
+      userScope: scope,
+    },
+    // ── Cohort-specific provenance. `eventToInboxItem` drops unknown keys, so
+    //    these never reach the YAML — they are for in-process consumers (the
+    //    cadence handler's log line, tests, and any future router) that see the
+    //    MessageEvent before it is flattened.
+    cohort: {
+      surface: verdict.surface,
+      topic: def.topic,
+      reason: verdict.reason,
+      family: c.family,
+      event_kind: c.kind,
+      entity_id: entityId || null,
+      seq: c.seq ?? null,
+      me: s(me),
+    },
+  };
+
+  // CONFIDENTIALITY. The daemon's outcome gate reads `is_private === false` as a
+  // positive "this source is public" assertion, so we stamp it ONLY when the
+  // room class is actually known — a default here would forge one.
+  if (channelKind) {
+    ev.channel_type = channelKind.toLowerCase();
+    ev.is_private = channelKind !== "PUBLIC";
+    ev.is_dm = channelKind === "DM";
+  } else if (!channelId) {
+    // A non-channel surface (task / decision / approval / doc / email) is org-
+    // internal and never public.
+    ev.is_private = true;
+  }
+
+  return ev;
+}
+
+/**
+ * The per-surface `message_id`. For messaging this stays the hq message id so
+ * the projection is byte-identical to today's DM path; for everything else the
+ * ledger seq is the only value that is both unique per event and stable across
+ * an at-least-once replay.
+ */
+export function messageIdFor(c, verdict) {
+  if (c.family === "messaging") return s(c.ids.messageId || c.entityId || c.seq);
+  if (c.family === "calling") return s(c.ids.callId || c.entityId || c.seq);
+  return s(c.seq != null ? c.seq : c.entityId);
+}
+
+/**
+ * The inbox item id — the DEDUP key. `cohort-<messageId>` for the two legacy
+ * surfaces (byte-compat with `lib/org/messaging.toMessageEvent`), and
+ * `cohort-<surface>-<seq>` for the new ones so two comments on the same task
+ * never collide.
+ */
+export function inboxIdFor(c, verdict, messageId, seq) {
+  if (c.family === "messaging" || c.family === "calling") {
+    return messageId ? `cohort-${messageId}` : undefined;
+  }
+  return `cohort-${verdict.surface}-${seq || messageId}`;
+}
+
+/** The coarse audience scope the daemon uses for pairing vs membership rules. */
+export function scopeFor(surface, channelKind, fallback) {
+  if (channelKind === "DM") return "dm";
+  if (channelKind === "GROUP_DM" || channelKind === "HUDDLE") return "group";
+  if (channelKind) return "channel";
+  return fallback || "channel";
+}
+
+export default { toMessageEvent, messageIdFor, inboxIdFor, scopeFor };