@cohortapp/agent-sdk 2.5.0 → 2.6.0

package/lib/org/ui-parity.test.mjs

@@ -1,7 +1,7 @@
 /**
  * ui-parity.test.mjs — Agent UI-parity helpers (full human-action mirror).
  *
- * The 328 wrappers in ui-parity.mjs are each a one-liner over call() from
+ * The 359 wrappers in ui-parity.mjs are each a one-liner over call() from
  * client.mjs, so client.test.mjs already proves the transport contract (headers,
  * idempotency, fail-open, frame normalisation). Here we just prove a representative
  * slice across families ROUTES to the correct method name, POSTs the params body,
@@ -326,7 +326,7 @@ test("a human-gated directory verb surfaces the server's refusal verbatim, never
   assert.match(frame.error.message, /human/);
 });
 
-test("every desk protocol method has exactly one ui-parity wrapper (196 desks / 328 total)", async () => {
+test("every desk protocol method has exactly one ui-parity wrapper (196 desks / 359 total)", async () => {
   const fs = await import("node:fs");
   const path = await import("node:path");
   const url = await import("node:url");
@@ -335,8 +335,22 @@ test("every desk protocol method has exactly one ui-parity wrapper (196 desks /
   const called = [...src.matchAll(/return call\("([a-z]+\.[A-Za-z]+)"/g)].map((x) => x[1]);
   // 2026-08 mobile-parity delta: +16 desk methods (email 5, files 9,
   // calendar.ask, crm.ask) → 312 → 328.
-  assert.equal(called.length, 328, "one call() site per wrapper");
+  // 2026-08 conversation-parity delta: the module claimed "one per agent-facing
+  // org method the human app exposes" while carrying 6 of messaging's 15 and
+  // NONE of calling's 22 — so the huddle control, the calendar Join, host
+  // mute/lock/remove, hand-raising and in-call chat had no wrapper at all.
+  // +9 messaging +22 calling → 328 → 359.
+  assert.equal(called.length, 359, "one call() site per wrapper");
   assert.equal(new Set(called).size, called.length, "no duplicate method bindings");
+  // The two conversation families are now WHOLE, which is what makes the
+  // module docblock's claim true rather than aspirational.
+  for (const fam of ["messaging", "calling"]) {
+    const famMethods = Object.entries((await import("./protocol.mjs")).METHODS)
+      .filter(([, d]) => d.family === fam)
+      .map(([n]) => n);
+    const unwrapped = famMethods.filter((m) => !new Set(called).has(m));
+    assert.deepEqual(unwrapped, [], `every ${fam}.* method is wrapped`);
+  }
   const p = await import("./protocol.mjs");
   const deskFams = new Set(["books", "calendar", "crm", "directory", "files"]);
   const deskMethods = Object.entries(p.METHODS)
@@ -346,3 +360,82 @@ test("every desk protocol method has exactly one ui-parity wrapper (196 desks /
   const missing = deskMethods.filter((m) => !bound.has(m));
   assert.deepEqual(missing, [], "every desk method is wrapped");
 });
+
+/**
+ * The methods in a CLAIMED family that ui-parity deliberately does NOT wrap,
+ * with the reason. The module docblock lists its families flatly, which reads as
+ * "every method in these families" — so the exceptions have to be written down
+ * and enforced, or the docblock is an orphan describing a surface that is not
+ * there. Ledger, not an excuse list: each line says which OTHER surface carries
+ * the verb.
+ */
+const DELIBERATELY_UNWRAPPED = new Map([
+  // board — the agent work kernel; no human control, curated tools instead.
+  ["board.create", "agent work kernel"],
+  ["board.claim", "agent work kernel — curated board_claim"],
+  ["board.heartbeat", "agent work kernel (lease slide)"],
+  ["board.complete", "agent work kernel — curated board_complete"],
+  ["board.block", "agent work kernel"],
+  ["board.comment", "agent work kernel (kanban comments = board.addTaskComment)"],
+  ["board.decompose", "agent work kernel — governance-gated §0.4"],
+  ["board.assign", "agent work kernel — governance-gated §0.4"],
+  ["board.link", "agent work kernel (DAG edge)"],
+  ["board.requestReview", "agent work kernel"],
+  ["board.resolveReview", "agent work kernel"],
+  // A human never calls this: it records where an AGENT is on an ask it took
+  // on. The daemon drives it from its own dispatch path (lib/org/work-ledger)
+  // and a session may nudge it mid-work via the curated `work_track` tool.
+  ["board.track", "agent work kernel — daemon-driven, curated work_track"],
+  // decision — the §0.4 control-plane acts, not the human ledger surface.
+  ["decision.propose", "control plane — curated decision_propose"],
+  ["decision.adopt", "control plane — governance-gated §0.4"],
+  ["decision.supersede", "control plane — governance-gated §0.4"],
+  // the rest — a different artifact or a different plane entirely.
+  ["escalation.ask", "OpenQuestion artifact, not the escalation strip"],
+  ["escalation.answer", "OpenQuestion artifact, not the escalation strip"],
+  ["memory.recall", "semantic retrieval — curated memory_recall"],
+  ["integration.toolsetVersion", "runtime toolset plane (daemon poll)"],
+  ["integration.listAgentTools", "runtime toolset plane (daemon poll)"],
+  ["integration.invokeTool", "runtime toolset plane (executor)"],
+  ["meetings.record", "knowledge plane writer, not the desk verb"],
+]);
+
+test("the claimed families are wrapped WHOLE, minus a declared, self-cleaning exception list", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(path.join(here, "ui-parity.mjs"), "utf8");
+  const wrapped = new Set([...src.matchAll(/return call\("([a-z]+\.[A-Za-z]+)"/g)].map((x) => x[1]));
+  const p = await import("./protocol.mjs");
+
+  // Exactly the families the module docblock names (branding lives in client.mjs).
+  const CLAIMED = [
+    "charter", "member", "team", "channel", "persona", "profile", "sop",
+    "escalation", "annotation", "contact", "file", "memory", "compact",
+    "notification", "decision", "messaging", "calling", "board", "invitation",
+    "user", "settings", "billing", "org", "integration", "email", "artifact",
+    "books", "calendar", "crm", "directory", "files",
+  ];
+  const undeclared = [];
+  for (const name of Object.keys(p.METHODS)) {
+    const fam = name.slice(0, name.indexOf("."));
+    if (!CLAIMED.includes(fam)) continue;
+    if (wrapped.has(name)) continue;
+    if (DELIBERATELY_UNWRAPPED.has(name)) continue;
+    undeclared.push(name);
+  }
+  // If this fails: add the wrapper, or add a DELIBERATELY_UNWRAPPED line saying
+  // which surface carries the verb instead. Silence is the one option gone.
+  assert.deepEqual(undeclared, [], "every method of a claimed family is wrapped or declared");
+
+  // Self-cleaning both ways: a stale exception (now wrapped, or no longer a
+  // real method) must be deleted rather than left as decoration.
+  const nowWrapped = [...DELIBERATELY_UNWRAPPED.keys()].filter((m) => wrapped.has(m));
+  assert.deepEqual(nowWrapped, [], "these are wrapped now — delete their exception lines");
+  const notMethods = [...DELIBERATELY_UNWRAPPED.keys()].filter((m) => !p.methodDef(m));
+  assert.deepEqual(notMethods, [], "these are not protocol methods — delete their exception lines");
+
+  // And the docblock's own numbers stay honest.
+  assert.equal(wrapped.size, 359, "the docblock's wrapper count");
+});

package/lib/org/work-ledger.mjs

@@ -0,0 +1,241 @@
+/**
+ * lib/org/work-ledger.mjs — the daemon's half of "make the work visible".
+ *
+ * THE COMPLAINT THIS EXISTS FOR. A colleague writes to the agent. The typing
+ * indicator comes on. Then nothing — for fifteen, thirty, forty-five minutes,
+ * because the reply IS the session and the session is long. Meanwhile the board
+ * says nothing was ever asked, nothing is in progress, and when the session dies
+ * (it does: `onClose({ok:false})` emits telemetry and messages nobody) the board
+ * still says nothing. The work is invisible from the moment it is accepted to
+ * the moment it silently fails.
+ *
+ * THE FIX IS NOT HERE. It is in hq's `server/work/ledger.ts`, which hq's own
+ * LLM responder calls directly and which this module reaches over the wire as
+ * `board.track`. All of the judgement — whether the ask deserves a board row,
+ * find-or-open, the column ladder, comment de-duplication, attachment de-
+ * duplication, who gets @-tagged and when — lives THERE, once. This file maps a
+ * daemon inbox item onto that call and gets out of the way.
+ *
+ * That asymmetry is deliberate. `4d762d30` means a member is animated by hq OR
+ * by their daemon, never both, and the owner must not be able to tell which is
+ * driving. Two implementations of "when does an ask deserve a board row" would
+ * be two answers within a week. So there is one, and this is a client of it.
+ *
+ * IDENTITY, NOT DIGESTS. We send the ask's identity (`service`, `channelId`,
+ * `messageId`) and let the server derive the dedupe key. The hashing algorithm
+ * therefore exists in exactly one repo, and a daemon can never compute a
+ * different key than hq would for the same message — which is what makes
+ * re-delivery after a dead session find the SAME row instead of opening a
+ * second one.
+ *
+ * FAIL-OPEN, NEVER SILENT. Every path returns a benign `{tracked:false, reason}`
+ * rather than throwing: a board write must never cost the user their reply. But
+ * the reason always comes back and the daemon always logs it — the entire reason
+ * this workstream exists is that a process died quietly.
+ *
+ * Pure-core + injectable IO: `trackImpl` / `cfg` / `fetchImpl` are all
+ * injectable, so the tests drive the real logic with no server. ESM, Node
+ * builtins only.
+ *
+ * @module lib/org/work-ledger
+ */
+
+"use strict";
+
+import { isEnabled as orgEnabled, configFromAgent, trackWork } from "./client.mjs";
+
+/** The stages the ledger understands. Mirrors hq's `WorkStage`. */
+export const WORK_STAGES = ["accepted", "working", "blocked", "review", "done", "failed"];
+
+const MAX_NOTE = 4000;
+const MAX_TITLE = 200;
+const MAX_BODY = 20000;
+
+/**
+ * Which Cohort channel did this inbox item arrive on?
+ *
+ * A board row inherits the visibility of the channel it lands on, so this is
+ * also the privacy answer: a DM's task lands on the DM's own board and is seen
+ * by exactly the DM's members. (That is strictly better than
+ * `session-outcomes.mjs`, which had to REFUSE every DM outright because
+ * `board.create` gives a channel-less row org-wide visibility. The owner's asks
+ * arrive by DM; refusing them meant refusing the actual use case.)
+ *
+ * Returns null for anything that is not a Cohort conversation — a Slack channel
+ * or an email thread is not a board we can write to, and guessing would put a
+ * task on a stranger's board.
+ *
+ * @param {object} item inbox item
+ * @returns {string|null}
+ */
+export function cohortChannelId(item) {
+  if (!item || typeof item !== "object") return null;
+  const service = String(item.service || "").trim().toLowerCase();
+  if (service !== "cohort") return null;
+  const id = String(item.cohort_channel_id || item.channel_id || "").trim();
+  return id || null;
+}
+
+/**
+ * The originating Cohort entity id — the thing the ask IS, which for a messaging
+ * surface is the message id.
+ *
+ * Read off `raw_ref` (`cohort:<surface>:<entityId>:<seq>`, stamped by
+ * `lib/org/inbound/project.mjs` and carried verbatim through the YAML
+ * round-trip), falling back to the inbox id, which `inboxIdFor` mints as
+ * `cohort-<messageId>` for messaging. Both are STABLE across a re-delivery —
+ * which is the whole point: a session that died and left the item un-processed
+ * comes back with the same id, computes the same key server-side, and finds the
+ * SAME row rather than opening a second one.
+ *
+ * @param {object} item
+ * @returns {string|null}
+ */
+export function cohortMessageId(item) {
+  if (!item || typeof item !== "object") return null;
+  const raw = String(item.raw_ref || "").trim();
+  if (raw.startsWith("cohort:")) {
+    const parts = raw.split(":");
+    if (parts.length >= 3 && parts[2]) return parts[2];
+  }
+  const id = String(item.id || "").trim();
+  if (id.startsWith("cohort-")) return id.slice("cohort-".length) || null;
+  return id || null;
+}
+
+/**
+ * The requester's Cohort member id.
+ *
+ * Deliberately usually NULL. The flattened inbox item carries the sender's
+ * NAME, not their id (`lib/channels/inbox-item.mjs` collapses `from:{id,name}`
+ * to a single `sender` string), and a name is not something to tag anybody on.
+ * Rather than plumb a new field through the poller, the YAML and the parser, the
+ * server resolves the requester from the originating message's own `authorId` —
+ * which it already holds, and which a client cannot spoof. This reads an id only
+ * when a caller genuinely has one.
+ *
+ * @param {object} item
+ * @returns {string|null}
+ */
+export function requesterMemberId(item) {
+  if (!item || typeof item !== "object") return null;
+  const id = String(item.sender_member_id || item.cohort_author_id || "").trim();
+  return id || null;
+}
+
+/** Clip a string, tolerating non-strings. */
+function clip(s, n) {
+  return String(s == null ? "" : s).slice(0, n);
+}
+
+/**
+ * Record one step of the agent's work on the board.
+ *
+ * @param {object} a
+ * @param {object} a.item the inbox item the work is for
+ * @param {string} a.stage one of {@link WORK_STAGES}
+ * @param {boolean} [a.deferred] could this NOT be answered inside the turn?
+ *   (true for the session path — the same signal that fires the holding
+ *   message; false for the quick-reply path). The server's gate reads it.
+ * @param {string} [a.title] row title (defaults server-side from the ask)
+ * @param {string} [a.detail] row detail, written once at open
+ * @param {string} [a.note] a progress comment for this step
+ * @param {string[]} [a.notify] extra member ids to @-tag on this step
+ * @param {Array<{name:string,mimeType?:string,sizeBytes?:number,dataUrl:string}>} [a.attachments]
+ * @param {object} [a.source] free provenance stamped into the row's `why`
+ * @param {object} [a.cfg] agent org config (config/org.yaml shape)
+ * @param {Function} [a.trackImpl] injectable board.track
+ * @param {Function} [a.fetchImpl] injectable fetch
+ * @returns {Promise<{tracked:boolean, reason:string, taskId?:string|null, col?:string|null,
+ *                    created?:boolean, moved?:boolean, commented?:boolean,
+ *                    attached?:number, tagged?:number}>}
+ */
+export async function recordWorkStep(a = {}) {
+  try {
+    const cfg = a.cfg || {};
+    if (!orgEnabled(cfg)) return { tracked: false, reason: "org-disabled" };
+
+    const stage = String(a.stage || "").trim();
+    if (!WORK_STAGES.includes(stage)) return { tracked: false, reason: "bad-stage" };
+
+    const channelId = cohortChannelId(a.item);
+    if (!channelId) return { tracked: false, reason: "not-a-cohort-channel" };
+    const messageId = cohortMessageId(a.item);
+    if (!messageId) return { tracked: false, reason: "no-message-id" };
+
+    const conn = configFromAgent(cfg);
+    const impl = a.trackImpl || trackWork;
+
+    const params = {
+      service: "cohort",
+      channelId,
+      messageId,
+      stage,
+      // The flattened inbox item carries the ask under `content`.
+      body: clip(a.item && (a.item.content || a.item.text || a.item.subject), MAX_BODY),
+      // `mentions_agent` is the ingest layer's REAL directedness verdict (a DM,
+      // an @mention, a named address, a direct assignment) — `project.mjs` sets
+      // it only when the address is genuine, never guessed. A channel message
+      // the agent merely overheard is not assigned work.
+      directed: !!(a.item && a.item.priority_signals && a.item.priority_signals.mentions_agent),
+      authorKind: a.item && a.item.author_kind === "AI_AGENT" ? "AI_AGENT" : "HUMAN",
+      deferred: a.deferred === true,
+    };
+    const requester = requesterMemberId(a.item);
+    if (requester) params.requesterId = requester;
+    if (a.title) params.title = clip(a.title, MAX_TITLE);
+    if (a.detail) params.detail = clip(a.detail, MAX_BODY);
+    if (a.note) params.note = clip(a.note, MAX_NOTE);
+    if (Array.isArray(a.notify) && a.notify.length) params.notify = a.notify.slice(0, 8);
+    if (Array.isArray(a.attachments) && a.attachments.length) {
+      params.attachments = a.attachments.slice(0, 6);
+    }
+    if (a.source && typeof a.source === "object") {
+      // The wire schema is `.strict()` and string-valued; drop anything else
+      // rather than have the whole step rejected for one stray field.
+      const src = {};
+      for (const [k, v] of Object.entries(a.source)) {
+        if (v == null) continue;
+        src[String(k)] = clip(v, 300);
+      }
+      if (Object.keys(src).length) params.source = src;
+    }
+
+    const res = await impl(params, {
+      base: conn.base,
+      token: conn.token,
+      fetchImpl: a.fetchImpl,
+      // Same ask + same stage = the same call. A retry after a timeout must not
+      // double-post the tag.
+      idempotencyKey: `board.track:${channelId}:${messageId}:${stage}`,
+    });
+
+    // The client never throws; a failure comes back as an error frame.
+    if (!res || res.error) {
+      const reason = res && res.error ? `${res.error.code || "error"}: ${res.error.message || ""}` : "no-response";
+      return { tracked: false, reason: reason.slice(0, 200) };
+    }
+    const out = res.result !== undefined ? res.result : res;
+    return {
+      tracked: !!(out && out.tracked),
+      reason: (out && out.reason) || "ok",
+      taskId: (out && out.taskId) || null,
+      col: (out && out.col) || null,
+      created: !!(out && out.created),
+      moved: !!(out && out.moved),
+      commented: !!(out && out.commented),
+      attached: (out && out.attached) || 0,
+      tagged: (out && out.tagged) || 0,
+    };
+  } catch (err) {
+    return { tracked: false, reason: `error: ${err && err.message ? err.message : String(err)}`.slice(0, 200) };
+  }
+}
+
+export default {
+  WORK_STAGES,
+  cohortChannelId,
+  cohortMessageId,
+  requesterMemberId,
+  recordWorkStep,
+};

package/lib/org/work-ledger.test.mjs

@@ -0,0 +1,237 @@
+/**
+ * lib/org/work-ledger.test.mjs — the daemon's half of the work ledger.
+ *
+ * What is worth testing here is deliberately NARROW, because the policy is not
+ * here: the threshold, the idempotency and the tagging all live server-side in
+ * hq's `server/work/ledger.ts`, so re-testing them in this repo would be
+ * testing a second implementation that must not exist. What IS this module's
+ * job — and what these tests pin — is the mapping: does a real flattened inbox
+ * item become the right wire call, does a re-delivery of the SAME item produce
+ * the SAME identity, and does every failure path come back as a benign,
+ * REASONED refusal rather than an exception on the dispatch path.
+ *
+ * Run: node --test lib/org/work-ledger.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  WORK_STAGES,
+  cohortChannelId,
+  cohortMessageId,
+  requesterMemberId,
+  recordWorkStep,
+} from "./work-ledger.mjs";
+
+const CFG = {
+  org: { cohort: { enabled: true, base: "https://os.example.test", token: "tok_test" } },
+};
+
+/** A flattened Cohort inbox item, in the shape lib/channels/inbox-item.mjs writes. */
+function inboxItem(over = {}) {
+  return {
+    id: "cohort-msg_abc123",
+    service: "cohort",
+    channel: "Owner ↔ Isla",
+    channel_id: "ch_dm_1",
+    sender: "The Owner",
+    sender_privilege: "ceo",
+    timestamp: "2026-08-13T05:47:51.000Z",
+    subject: "Direct message",
+    content: "fix these issues you just noted please and push their fixes to git",
+    thread_id: "",
+    is_reply: false,
+    priority_signals: {
+      from_ceo: true,
+      tagged_urgent: false,
+      contains_deadline: false,
+      mentions_agent: true,
+    },
+    raw_ref: "cohort:message:msg_abc123:4821",
+    source: "cohort",
+    ...over,
+  };
+}
+
+/** Capture the params a step would send, without a server. */
+function capture(result = { result: { tracked: true, taskId: "t_1", col: "triage", created: true } }) {
+  const calls = [];
+  const impl = async (params, opts) => {
+    calls.push({ params, opts });
+    return result;
+  };
+  return { calls, impl };
+}
+
+// ---------------------------------------------------------------------------
+// Identity — the thing that makes a re-delivery find the same row
+// ---------------------------------------------------------------------------
+
+test("cohortMessageId reads the entity id off raw_ref", () => {
+  assert.equal(cohortMessageId(inboxItem()), "msg_abc123");
+});
+
+test("cohortMessageId falls back to the inbox id when raw_ref is absent", () => {
+  assert.equal(cohortMessageId(inboxItem({ raw_ref: "" })), "msg_abc123");
+});
+
+test("a re-delivered item yields the SAME identity", () => {
+  // The dead-session case: the item was never marked processed, so the poller
+  // hands back a byte-identical file. Same channel + same message = same key
+  // server-side = the same board row, not a second one.
+  const first = inboxItem();
+  const again = inboxItem();
+  assert.equal(cohortChannelId(first), cohortChannelId(again));
+  assert.equal(cohortMessageId(first), cohortMessageId(again));
+});
+
+test("requesterMemberId is null for a normal item — the server resolves it", () => {
+  // The flat item carries the sender's NAME, not their id. Guessing a member id
+  // from a display name is how you tag the wrong person.
+  assert.equal(requesterMemberId(inboxItem()), null);
+  assert.equal(requesterMemberId({ sender_member_id: "m_owner" }), "m_owner");
+});
+
+// ---------------------------------------------------------------------------
+// The mapping
+// ---------------------------------------------------------------------------
+
+test("an accepted step sends the ask's identity and the deferred fact", async () => {
+  const { calls, impl } = capture();
+  const res = await recordWorkStep({
+    item: inboxItem(),
+    stage: "accepted",
+    deferred: true,
+    note: "Picked this up.",
+    cfg: CFG,
+    trackImpl: impl,
+    source: { service: "cohort", trace_id: "tr_9" },
+  });
+
+  assert.equal(calls.length, 1);
+  const { params, opts } = calls[0];
+  assert.equal(params.service, "cohort");
+  assert.equal(params.channelId, "ch_dm_1");
+  assert.equal(params.messageId, "msg_abc123");
+  assert.equal(params.stage, "accepted");
+  assert.equal(params.deferred, true);
+  assert.equal(params.directed, true);
+  assert.equal(params.authorKind, "HUMAN");
+  assert.equal(
+    params.body,
+    "fix these issues you just noted please and push their fixes to git",
+  );
+  assert.equal(params.note, "Picked this up.");
+  assert.deepEqual(params.source, { service: "cohort", trace_id: "tr_9" });
+  // Same ask + same stage = the same call, so a retry after a timeout cannot
+  // double-post the tag.
+  assert.equal(opts.idempotencyKey, "board.track:ch_dm_1:msg_abc123:accepted");
+  assert.equal(opts.base, CFG.org.cohort.base);
+  assert.equal(res.tracked, true);
+  assert.equal(res.taskId, "t_1");
+});
+
+test("directedness comes from the ingest layer's real verdict, never a guess", async () => {
+  const { calls, impl } = capture();
+  await recordWorkStep({
+    item: inboxItem({
+      priority_signals: { mentions_agent: false, from_ceo: false, tagged_urgent: false, contains_deadline: false },
+    }),
+    stage: "accepted",
+    cfg: CFG,
+    trackImpl: impl,
+  });
+  // An overheard channel message is not assigned work — and the SERVER is what
+  // acts on that, so the client's job is only to report it honestly.
+  assert.equal(calls[0].params.directed, false);
+});
+
+test("a session death is reported as `failed`, not swallowed", async () => {
+  const { calls, impl } = capture({ result: { tracked: true, taskId: "t_1", col: "blocked", moved: true } });
+  const res = await recordWorkStep({
+    item: inboxItem(),
+    stage: "failed",
+    deferred: true,
+    note: "The session handling this ended without completing (exit 143).",
+    cfg: CFG,
+    trackImpl: impl,
+  });
+  assert.equal(calls[0].params.stage, "failed");
+  assert.equal(res.col, "blocked");
+});
+
+test("attachments and extra tags are forwarded, and bounded", async () => {
+  const { calls, impl } = capture();
+  await recordWorkStep({
+    item: inboxItem(),
+    stage: "review",
+    cfg: CFG,
+    trackImpl: impl,
+    notify: Array.from({ length: 20 }, (_, i) => `m_${i}`),
+    attachments: Array.from({ length: 20 }, (_, i) => ({ name: `f${i}.txt`, dataUrl: "data:text/plain;base64,eA==" })),
+  });
+  assert.equal(calls[0].params.notify.length, 8);
+  assert.equal(calls[0].params.attachments.length, 6);
+});
+
+// ---------------------------------------------------------------------------
+// Fail-open, never silent
+// ---------------------------------------------------------------------------
+
+test("a non-Cohort item is refused with a reason, not an exception", async () => {
+  const { calls, impl } = capture();
+  const res = await recordWorkStep({ item: inboxItem({ service: "slack" }), stage: "accepted", cfg: CFG, trackImpl: impl });
+  assert.equal(res.tracked, false);
+  assert.equal(res.reason, "not-a-cohort-channel");
+  assert.equal(calls.length, 0, "no wire call for a board we cannot write to");
+});
+
+test("an item with no resolvable channel is refused", async () => {
+  const res = await recordWorkStep({ item: inboxItem({ channel_id: "" }), stage: "accepted", cfg: CFG, trackImpl: async () => ({}) });
+  assert.equal(res.tracked, false);
+  assert.equal(res.reason, "not-a-cohort-channel");
+});
+
+test("a bad stage is refused rather than sent", async () => {
+  const { calls, impl } = capture();
+  const res = await recordWorkStep({ item: inboxItem(), stage: "finished", cfg: CFG, trackImpl: impl });
+  assert.equal(res.reason, "bad-stage");
+  assert.equal(calls.length, 0);
+});
+
+test("org integration off ⇒ a clean skip", async () => {
+  const res = await recordWorkStep({ item: inboxItem(), stage: "accepted", cfg: {}, trackImpl: async () => ({}) });
+  assert.equal(res.tracked, false);
+  assert.equal(res.reason, "org-disabled");
+});
+
+test("a server error frame comes back as a REASON, never a throw", async () => {
+  const res = await recordWorkStep({
+    item: inboxItem(),
+    stage: "accepted",
+    cfg: CFG,
+    trackImpl: async () => ({ error: { code: "FORBIDDEN_SCOPE", message: "board.write not granted" } }),
+  });
+  assert.equal(res.tracked, false);
+  assert.match(res.reason, /FORBIDDEN_SCOPE/);
+  assert.match(res.reason, /board\.write not granted/);
+});
+
+test("a thrown transport error is contained — the dispatch path never sees it", async () => {
+  const res = await recordWorkStep({
+    item: inboxItem(),
+    stage: "accepted",
+    cfg: CFG,
+    trackImpl: async () => {
+      throw new Error("ECONNREFUSED");
+    },
+  });
+  assert.equal(res.tracked, false);
+  assert.match(res.reason, /ECONNREFUSED/);
+});
+
+test("WORK_STAGES matches the server's ladder", () => {
+  assert.deepEqual(WORK_STAGES, ["accepted", "working", "blocked", "review", "done", "failed"]);
+});