@cohortapp/agent-sdk 2.3.0

package/lib/channels/orgmail/adapter.mjs

@@ -0,0 +1,353 @@
+/**
+ * Maestro — workspace email channel adapter (`orgmail`)
+ *
+ * The Cohort-hosted mailbox lane (companion spec 2026-07-21 §9): every AI
+ * member gets a real address at the org's verified domain; inbound mail is
+ * persisted server-side and delivered here **entirely over org RPC** — no
+ * IMAP, no app passwords, no provider creds on the mini. DISTINCT from the
+ * legacy personal-Gmail lane (`gmail` — scripts/poller/gmail-poller.mjs),
+ * which keeps serving plain Google accounts; the two coexist (separate inbox
+ * dirs: state/inbox/orgmail/ vs state/inbox/gmail/).
+ *
+ * Mechanics (mirrors lib/channels/telegram/adapter.mjs structurally):
+ *   - `_connect` — poll loop, default 45s (the messaging-inbound cadence):
+ *     email.inbox {unreadOnly:true, limit:50} → per summary (newest-LAST) →
+ *     email.message {id} → onRaw(fullDto) → on clean handoff + `mark_read`,
+ *     email.markRead {messageId}. **NO local cursor file** — markRead IS the
+ *     cursor, server-side. At-least-once by design: a failed markRead simply
+ *     re-delivers next tick; duplicates are absorbed downstream (inbox-item id
+ *     = EmailMessage.id + the agent-daemon's dedup locks and claims).
+ *   - `_toEvent` — MessageEvent with the subject PREFIXED into `text` (so it
+ *     survives every downstream shape) AND set as `ev.subject` (eventToInboxItem
+ *     sanitizes + carries the item-shape subject field).
+ *   - `_send` — emailSend({threadId, text, idempotencyId}) — deliberately no
+ *     to/subject: hq's reply rule derives recipients from the thread's newest
+ *     delivered inbound message and D5(b) covers those senders per-recipient,
+ *     so the canonical quick-reply needs no approval. An approval_required
+ *     result maps to {ok:false} pointing at scripts/org/send-orgmail.mjs.
+ *     Inherited send() supplies hook-bus beforeSend + send-gate + reply-storm
+ *     perimeter for free.
+ *   - `pairingMode: "open"` — external senders are inherently unknown; the
+ *     authorization boundary is Cohort-side (mailbox routing, quarantine
+ *     caps, auto-submitted loop guards, first-contact send approvals). A
+ *     deny-gate here would park every customer email in pairing limbo. No
+ *     `internalDomains` machinery either: workspace-mail senders are genuinely
+ *     external.
+ *   - No `_setTyping` / `_react` (email has neither; BaseAdapter no-ops are
+ *     correct).
+ *
+ * Credentials come ONLY from config/org.yaml (`org.cohort.*` — the enrollment
+ * SoT); the gate file config/orgmail.yaml enables the platform.
+ *
+ * @module lib/channels/orgmail/adapter
+ */
+
+"use strict";
+
+import { CHANNEL_CAPABILITIES } from "../channel.mjs";
+import { definePlatform } from "../contract.mjs";
+import { BaseAdapter, CHANNEL_COUNTERS } from "../base-adapter.mjs";
+import { randomUUID } from "node:crypto";
+import { loadOrgConfig, configFromAgent } from "../../org/client.mjs";
+import { emailSend, emailMarkRead, emailInbox, emailMessage } from "../../org/ui-parity.mjs";
+
+export const ORGMAIL_CAPABILITIES = [
+  CHANNEL_CAPABILITIES.SEND,
+  CHANNEL_CAPABILITIES.THREAD,
+  "attachments:metadata",
+];
+
+/** Default poll cadence — the messaging-inbound rhythm. */
+export const DEFAULT_POLL_MS = 45_000;
+
+export class OrgMailAdapter extends BaseAdapter {
+  /**
+   * @param {object} opts
+   * @param {object} [opts.config]     parsed config/orgmail.yaml ({orgmail:{...}} or flat)
+   * @param {object} [opts.orgConfig]  parsed config/org.yaml (else loaded from agentRoot)
+   * @param {Function} [opts.fetchImpl] injected fetch (tests)
+   * @param {number} [opts.pollMs]     poll override (else MAESTRO_ORGMAIL_POLL_MS / config poll_seconds)
+   */
+  constructor(opts = {}) {
+    super({
+      name: "orgmail",
+      capabilities: ORGMAIL_CAPABILITIES,
+      // Companion decision: external senders are inherently unknown — the
+      // authorization boundary is server-side. See module doc.
+      pairingMode: "open",
+      sendGate: true,
+      supervise: true,
+      ...opts,
+      // orgmail's health is the RPC probe below, not a socket; the reconnect
+      // supervisor polls _connectionHealthy which we leave state-based.
+    });
+    this._fetchImpl = opts.fetchImpl;
+    this._orgConfig = opts.orgConfig || null;
+    const gate = normalizeGateConfig(this.config);
+    this._markRead = gate.mark_read !== false;
+    this._pollMs = resolvePollMs(opts.pollMs, gate, process.env);
+    this._timer = null;
+    this._polling = false;
+  }
+
+  /** Resolve {base, token, orgId} from config/org.yaml (the enrollment SoT). */
+  _org() {
+    const cfg = this._orgConfig || loadOrgConfig(this.agentRoot);
+    const c = configFromAgent(cfg);
+    return { base: c.base, token: c.token, orgId: c.orgId, fetchImpl: this._fetchImpl };
+  }
+
+  // -- connect: RPC poll loop ------------------------------------------------
+
+  async _connect({ onRaw, signal }) {
+    const tick = async () => {
+      if (this._polling || this._stopping) return;
+      this._polling = true;
+      try {
+        await this._pollOnce(onRaw);
+      } catch (err) {
+        // Poll errors → log + next tick; repeated failure surfaces via the
+        // reconnect supervisor's health poll.
+        this.log("warn", `orgmail poll failed: ${err && err.message}`);
+      } finally {
+        this._polling = false;
+      }
+    };
+
+    if (signal) {
+      signal.addEventListener?.("abort", () => {
+        if (this._timer) this._clearInterval(this._timer);
+        this._timer = null;
+      });
+    }
+
+    await tick(); // first sweep immediately so start() sees a live adapter
+    this._timer = this._setInterval(tick, this._pollMs);
+    if (this._timer && typeof this._timer.unref === "function") this._timer.unref();
+  }
+
+  /**
+   * One inbox sweep: list unread summaries, fetch each full DTO (newest LAST
+   * so downstream sees chronological order), hand off, then markRead ONLY on a
+   * clean handoff — a throwing onRaw leaves the item unread and it re-delivers
+   * next tick (at-least-once).
+   */
+  async _pollOnce(onRaw) {
+    const o = this._org();
+    if (!o.base || !o.token) return; // not enrolled — dormant, never throws
+    const inbox = await emailInbox({ unreadOnly: true, limit: 50 }, o);
+    if (!inbox.ok) {
+      this.log("warn", `email.inbox error: ${inbox.error?.code || "?"} ${inbox.error?.message || ""}`);
+      return;
+    }
+    const summaries = Array.isArray(inbox.result?.messages) ? inbox.result.messages : [];
+    // Server returns newest-first (keyset createdAt desc); we deliver newest-LAST.
+    const ordered = [...summaries].reverse();
+    for (const summary of ordered) {
+      if (this._stopping) return;
+      const id = summary && summary.id;
+      if (!id) continue;
+      const full = await emailMessage({ id }, o);
+      if (!full.ok) {
+        this.log("warn", `email.message ${id} error: ${full.error?.code || "?"}`);
+        continue;
+      }
+      let clean = true;
+      try {
+        onRaw(full.result);
+      } catch (err) {
+        clean = false; // leave unread → re-delivered next tick
+        this.log("error", `orgmail handoff threw (item stays unread): ${err && err.message}`);
+      }
+      if (clean && this._markRead) {
+        const marked = await emailMarkRead({ messageId: id }, { ...o, idempotencyKey: `orgmail-read:${id}` });
+        if (!marked.ok) this.log("warn", `email.markRead ${id} failed (will re-deliver): ${marked.error?.code || "?"}`);
+      }
+    }
+  }
+
+  /**
+   * UNLIKE the base (which swallows onInbound errors to protect a live socket
+   * loop), the poll loop WANTS the throw: `_pollOnce`'s clean-handoff detection
+   * must see a failed handoff so markRead — the server-side cursor — does not
+   * advance past an undelivered item (at-least-once). Own/peer drops keep the
+   * base semantics (a drop is a CLEAN outcome: the cursor advances). A
+   * `_toEvent` translation throw is also clean by construction (the base onRaw
+   * catches it before reaching here) — a poison item is marked read rather
+   * than re-delivered forever.
+   */
+  _handleEvent(ev) {
+    if (this._isOwnOrPeer(ev)) {
+      this._count(CHANNEL_COUNTERS.PEER_AGENT_DROPPED, { from: this._eventSenderId(ev) });
+      this.log("debug", "dropping own/peer-agent inbound (no auto-reply)");
+      return;
+    }
+    // pairingMode "open": no pairing gate (authorization is Cohort-side).
+    this._onInbound(ev);
+  }
+
+  // -- translate: EmailMessageDTO → MessageEvent -----------------------------
+
+  _toEvent(raw) {
+    if (!raw || typeof raw !== "object" || !raw.id) return null;
+    const subject = typeof raw.subject === "string" ? raw.subject : "";
+    const bodyText =
+      typeof raw.text === "string" && raw.text
+        ? raw.text
+        : htmlToText(typeof raw.html === "string" ? raw.html : "");
+    const from = String(raw.from || "");
+    const threadId = String(raw.threadId || "");
+    const timestamp = raw.receivedAt || raw.createdAt || new Date().toISOString();
+    const attachments = Array.isArray(raw.attachments)
+      ? raw.attachments.map((a) => ({
+          type: "document",
+          mime: a?.contentType || null,
+          filename: a?.filename || null,
+          size_bytes: a?.size || 0,
+          id: a?.id,
+        }))
+      : undefined;
+
+    return {
+      channel: "orgmail",
+      service: "orgmail",
+      kind: "message",
+      message_id: String(raw.id),
+      thread_id: threadId,
+      from: { id: from, display: from, name: from },
+      to: { id: String(raw.mailbox?.address || "") },
+      // Subject prefixed so it survives every downstream shape; ev.subject also
+      // set — eventToInboxItem sanitizes and carries the item-shape field.
+      text: `Subject: ${subject}\n\n${bodyText}`,
+      subject,
+      attachments: attachments && attachments.length ? attachments : undefined,
+      timestamp,
+      in_reply_to: raw.inReplyTo || undefined,
+      raw,
+      sender: from,
+      sender_privilege: "external",
+      channel_id: threadId,
+      channel_label: `email/${from}`,
+      is_reply: !!raw.inReplyTo,
+      priority_signals: {
+        from_ceo: false,
+        tagged_urgent: /\b(urgent|emergency|asap|critical)\b/i.test(subject),
+        contains_deadline: false,
+        mentions_agent: true, // mail to the agent's own mailbox is always directed
+      },
+      raw_ref: `orgmail:${threadId}:${raw.id}`,
+      ingest_source: "orgmail",
+      thread_context: null,
+      source: {
+        channel: "orgmail",
+        chatId: threadId,
+        replyToRef: String(raw.id),
+        userScope: "dm",
+        peerId: from,
+      },
+    };
+  }
+
+  // -- outbound --------------------------------------------------------------
+
+  async _send(out) {
+    const o = this._org();
+    if (!o.base || !o.token) return { ok: false, error: "orgmail: org enrollment missing (config/org.yaml)" };
+    const threadId = out?.source?.chatId || out?.thread_ref || out?.to;
+    if (!threadId) return { ok: false, error: "orgmail._send: thread id required (out.source.chatId)" };
+    const frame = await emailSend(
+      { threadId: String(threadId), text: out.text || "", idempotencyId: randomUUID() },
+      { ...o, idempotencyKey: randomUUID() },
+    );
+    if (!frame.ok) {
+      return { ok: false, error: `${frame.error?.code || "ERROR"}: ${frame.error?.message || "email.send failed"}` };
+    }
+    if (frame.result?.status === "approval_required") {
+      return {
+        ok: false,
+        error:
+          "first-contact approval required — run scripts/org/send-orgmail.mjs --request-approval " +
+          "(the recipient set includes an address this mailbox has never corresponded with)",
+        raw: frame.result,
+      };
+    }
+    return { ok: true, message_id: String(frame.result?.messageId || ""), raw: frame.result };
+  }
+
+  // -- health ---------------------------------------------------------------
+
+  /**
+   * One email.inbox {limit:1} round-trip (the same probe the doctor reuses).
+   * Family-absent / unreachable / unpaired all surface the error frame's
+   * message; the reconnect supervisor handles transient RPC outages.
+   */
+  async healthCheck() {
+    const o = this._org();
+    if (!o.base || !o.token) return { ok: false, detail: "orgmail: org enrollment missing (config/org.yaml)" };
+    const r = await emailInbox({ limit: 1 }, o);
+    if (r.ok) {
+      const addr = r.result?.mailbox?.address || "";
+      return { ok: true, detail: `orgmail mailbox ${addr || "reachable"}` };
+    }
+    return { ok: false, detail: `orgmail: ${r.error?.code || "?"} ${r.error?.message || "unreachable"}` };
+  }
+
+  async stop() {
+    await super.stop();
+    if (this._timer) this._clearInterval(this._timer);
+    this._timer = null;
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+/** Accept {orgmail:{...}} (the gate-file shape) or a flat config object. */
+function normalizeGateConfig(config) {
+  if (config && typeof config === "object" && config.orgmail && typeof config.orgmail === "object") {
+    return config.orgmail;
+  }
+  return config && typeof config === "object" ? config : {};
+}
+
+/** Poll interval: explicit opt → MAESTRO_ORGMAIL_POLL_MS → poll_seconds → 45s. */
+export function resolvePollMs(explicit, gate = {}, env = {}) {
+  if (Number.isFinite(explicit) && explicit > 0) return explicit;
+  const envMs = Number(env.MAESTRO_ORGMAIL_POLL_MS);
+  if (Number.isFinite(envMs) && envMs > 0) return envMs;
+  const cfgS = Number(gate.poll_seconds);
+  if (Number.isFinite(cfgS) && cfgS > 0) return cfgS * 1000;
+  return DEFAULT_POLL_MS;
+}
+
+/** Minimal HTML → text (same approach as the IMAP poller's stripHtml). */
+export function htmlToText(html) {
+  if (typeof html !== "string" || !html) return "";
+  let text = html.replace(/<(style|script)[^>]*>[\s\S]*?<\/\1>/gi, "");
+  text = text.replace(/<br\s*\/?>/gi, "\n");
+  text = text.replace(/<\/(p|div|tr|li|h[1-6])>/gi, "\n");
+  text = text.replace(/<[^>]+>/g, "");
+  text = text.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&");
+  text = text.replace(/&lt;/g, "<").replace(/&gt;/g, ">");
+  text = text.replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  text = text.replace(/&\w+;/g, "");
+  text = text.replace(/[ \t]+/g, " ");
+  text = text.replace(/\n{3,}/g, "\n\n");
+  return text.trim();
+}
+
+/** Factory matching the channel/platform contract. */
+export function createOrgMailChannel(opts = {}) {
+  return new OrgMailAdapter(opts);
+}
+
+// Self-register so the daemon's generic platform loop discovers orgmail by the
+// presence of config/orgmail.yaml (no core edit). Daemon-managed — NOT in
+// DEDICATED_PLIST_PLATFORMS.
+definePlatform({
+  name: "orgmail",
+  gateFile: "config/orgmail.yaml",
+  factory: createOrgMailChannel,
+  capabilities: ORGMAIL_CAPABILITIES,
+});
+
+export default createOrgMailChannel;

package/lib/channels/orgmail/adapter.test.mjs

@@ -0,0 +1,311 @@
+/**
+ * orgmail adapter tests — the workspace email channel over org RPC.
+ *
+ * The hq side is MOCKED the way the other adapter tests mock their provider
+ * (telegram injects a fake grammY bot; here we inject a fake fetchImpl that
+ * routes /api/v1/email.* to canned res frames) — no network, no timers left
+ * running (supervise:false + injected interval fns; ticks driven by hand).
+ *
+ * Run: node --test lib/channels/orgmail/adapter.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  OrgMailAdapter,
+  createOrgMailChannel,
+  resolvePollMs,
+  htmlToText,
+  DEFAULT_POLL_MS,
+  ORGMAIL_CAPABILITIES,
+} from "./adapter.mjs";
+import { getPlatform, isDaemonManagedPlatform } from "../contract.mjs";
+
+const ORG_CFG = { org: { cohort: { enabled: true, base: "https://org.example", orgId: "acme", token: "tok-1" } } };
+
+/**
+ * A fake hq: routes the five email.* endpoints. `inboxPages` is a queue of
+ * summary arrays (one per poll tick); `messages` maps id → full DTO.
+ */
+function hqMock({ inboxPages = [[]], messages = {}, sendBody, markReadFails = false } = {}) {
+  const pages = [...inboxPages];
+  const calls = [];
+  const fn = async (url, init) => {
+    const u = String(url);
+    const body = init && init.body ? JSON.parse(init.body) : {};
+    calls.push({ url: u, body, headers: (init && init.headers) || {} });
+    const respond = (payload, status = 200, ok = true) => ({ ok, status, json: async () => payload, headers: { get: () => undefined } });
+    if (u.endsWith("/api/v1/email.inbox")) {
+      const page = pages.length ? pages.shift() : [];
+      return respond({ ok: true, result: { mailbox: { address: "astra@agents.example", status: "ACTIVE" }, messages: page, nextCursor: null } });
+    }
+    if (u.endsWith("/api/v1/email.message")) {
+      const dto = messages[body.id];
+      return dto ? respond({ ok: true, result: dto }) : respond({ ok: false, error: { code: "NOT_FOUND", message: "no row" } }, 404, false);
+    }
+    if (u.endsWith("/api/v1/email.markRead")) {
+      if (markReadFails) return respond({ ok: false, error: { code: "INTERNAL", message: "boom" } }, 500, false);
+      return respond({ ok: true, result: { updated: 1 } });
+    }
+    if (u.endsWith("/api/v1/email.send")) {
+      return respond(sendBody || { ok: true, result: { status: "queued", messageId: "out-1", threadId: body.threadId } });
+    }
+    return respond({ ok: false, error: { code: "NOT_FOUND", message: `unknown ${u}` } }, 404, false);
+  };
+  fn.calls = calls;
+  fn.callsTo = (suffix) => calls.filter((c) => c.url.endsWith(suffix));
+  return fn;
+}
+
+const DTO = (over = {}) => ({
+  id: "em-1",
+  threadId: "th-1",
+  direction: "INBOUND",
+  status: "RECEIVED",
+  from: "casey@customer.com",
+  to: ["astra@agents.example"],
+  subject: "Quick pricing question",
+  text: "How much for 50 seats?",
+  html: null,
+  receivedAt: "2026-07-21T01:02:03.000Z",
+  createdAt: "2026-07-21T01:02:04.000Z",
+  inReplyTo: null,
+  attachments: [{ id: "att-1", filename: "specs.pdf", contentType: "application/pdf", size: 1234 }],
+  ...over,
+});
+
+function makeAdapter(fetchImpl, over = {}) {
+  const intervals = [];
+  const a = new OrgMailAdapter({
+    agentRoot: "/tmp/orgmail-test",
+    orgConfig: ORG_CFG,
+    config: { orgmail: { enabled: true, poll_seconds: 45, mark_read: true, ...(over.gate || {}) } },
+    fetchImpl,
+    supervise: false,
+    sendGate: over.sendGate ?? false,
+    screenOutbound: over.screenOutbound,
+    setInterval: (fn, ms) => { intervals.push({ fn, ms }); return { unref() {} }; },
+    clearInterval: () => {},
+    log: () => {},
+    ...over.opts,
+  });
+  return { a, intervals };
+}
+
+const settle = () => new Promise((r) => setTimeout(r, 5));
+
+// ── registration ───────────────────────────────────────────────────────────
+
+test("platform self-registration: orgmail gated on config/orgmail.yaml, daemon-managed", () => {
+  const def = getPlatform("orgmail");
+  assert.ok(def, "definePlatform ran at import");
+  assert.equal(def.gateFile, "config/orgmail.yaml");
+  assert.deepEqual(def.capabilities, ORGMAIL_CAPABILITIES);
+  assert.equal(typeof def.factory, "function");
+  assert.equal(isDaemonManagedPlatform("orgmail"), true, "NOT in DEDICATED_PLIST_PLATFORMS");
+  const inst = createOrgMailChannel({ agentRoot: "/tmp", orgConfig: ORG_CFG, supervise: false, log: () => {} });
+  assert.equal(inst.name, "orgmail");
+});
+
+// ── config helpers ─────────────────────────────────────────────────────────
+
+test("resolvePollMs: explicit > env > poll_seconds > 45s default", () => {
+  assert.equal(resolvePollMs(1000, { poll_seconds: 10 }, { MAESTRO_ORGMAIL_POLL_MS: "2000" }), 1000);
+  assert.equal(resolvePollMs(undefined, { poll_seconds: 10 }, { MAESTRO_ORGMAIL_POLL_MS: "2000" }), 2000);
+  assert.equal(resolvePollMs(undefined, { poll_seconds: 10 }, {}), 10_000);
+  assert.equal(resolvePollMs(undefined, {}, {}), DEFAULT_POLL_MS);
+});
+
+test("htmlToText strips markup, decodes entities, preserves paragraph breaks", () => {
+  const text = htmlToText("<div><p>Hello &amp; hi</p><br><script>evil()</script><p>Second&nbsp;line</p></div>");
+  assert.match(text, /Hello & hi/);
+  assert.match(text, /Second line/);
+  assert.ok(!text.includes("evil"), "script bodies stripped");
+});
+
+// ── poll loop ──────────────────────────────────────────────────────────────
+
+test("poll: inbox summaries → per-item email.message → onRaw → markRead on clean handoff", async () => {
+  const fetchImpl = hqMock({
+    inboxPages: [[{ id: "em-2" }, { id: "em-1" }]], // server newest-first
+    messages: { "em-1": DTO({ id: "em-1" }), "em-2": DTO({ id: "em-2", subject: "Follow-up" }) },
+  });
+  const { a } = makeAdapter(fetchImpl);
+  const inbound = [];
+  await a.start({ onInbound: (ev) => inbound.push(ev) });
+  await settle();
+
+  assert.equal(fetchImpl.callsTo("/api/v1/email.inbox").length, 1);
+  assert.deepEqual(fetchImpl.callsTo("/api/v1/email.inbox")[0].body, { unreadOnly: true, limit: 50 });
+  assert.equal(fetchImpl.callsTo("/api/v1/email.message").length, 2, "one body fetch per summary");
+  assert.equal(inbound.length, 2, "both events delivered (pairingMode open)");
+  assert.deepEqual(inbound.map((e) => e.message_id), ["em-1", "em-2"], "newest LAST (chronological)");
+  const marked = fetchImpl.callsTo("/api/v1/email.markRead");
+  assert.deepEqual(marked.map((c) => c.body), [{ messageId: "em-1" }, { messageId: "em-2" }], "markRead per clean handoff — the server-side cursor");
+  await a.stop();
+});
+
+test("poll: a throwing handoff leaves the item UNREAD → re-delivered next tick (at-least-once)", async () => {
+  const fetchImpl = hqMock({
+    inboxPages: [[{ id: "em-1" }], [{ id: "em-1" }]], // still unread on tick 2
+    messages: { "em-1": DTO() },
+  });
+  const { a, intervals } = makeAdapter(fetchImpl);
+  let calls = 0;
+  await a.start({
+    onInbound: () => {
+      calls += 1;
+      if (calls === 1) throw new Error("classifier down");
+    },
+  });
+  await settle();
+  assert.equal(fetchImpl.callsTo("/api/v1/email.markRead").length, 0, "no markRead after a throwing handoff");
+  await intervals[0].fn(); // drive tick 2 by hand
+  await settle();
+  assert.equal(calls, 2, "item re-delivered");
+  assert.equal(fetchImpl.callsTo("/api/v1/email.markRead").length, 1, "clean second handoff marks read");
+  await a.stop();
+});
+
+test("poll: mark_read:false leaves items unread", async () => {
+  const fetchImpl = hqMock({ inboxPages: [[{ id: "em-1" }]], messages: { "em-1": DTO() } });
+  const { a } = makeAdapter(fetchImpl, { gate: { mark_read: false } });
+  const inbound = [];
+  await a.start({ onInbound: (ev) => inbound.push(ev) });
+  await settle();
+  assert.equal(inbound.length, 1);
+  assert.equal(fetchImpl.callsTo("/api/v1/email.markRead").length, 0);
+  await a.stop();
+});
+
+test("poll: a failed markRead is logged, not thrown (re-delivery next tick)", async () => {
+  const fetchImpl = hqMock({ inboxPages: [[{ id: "em-1" }]], messages: { "em-1": DTO() }, markReadFails: true });
+  const { a } = makeAdapter(fetchImpl);
+  const inbound = [];
+  await a.start({ onInbound: (ev) => inbound.push(ev) });
+  await settle();
+  assert.equal(inbound.length, 1, "delivery still happened");
+  await a.stop();
+});
+
+test("poll: unenrolled org (no token) is dormant — zero network, zero throw", async () => {
+  const fetchImpl = hqMock();
+  const a = new OrgMailAdapter({
+    agentRoot: "/tmp/orgmail-none", orgConfig: { org: {} }, fetchImpl,
+    supervise: false, sendGate: false, log: () => {},
+    setInterval: () => ({ unref() {} }), clearInterval: () => {},
+  });
+  await a.start({ onInbound: () => {} });
+  await settle();
+  assert.equal(fetchImpl.calls.length, 0);
+  await a.stop();
+});
+
+// ── _toEvent ───────────────────────────────────────────────────────────────
+
+test("_toEvent: subject-prefixed text, subject field, ids, source, attachments metadata", () => {
+  const { a } = makeAdapter(hqMock());
+  const ev = a._toEvent(DTO());
+  assert.equal(ev.channel, "orgmail");
+  assert.equal(ev.kind, "message");
+  assert.equal(ev.message_id, "em-1");
+  assert.equal(ev.thread_id, "th-1");
+  assert.equal(ev.text, "Subject: Quick pricing question\n\nHow much for 50 seats?");
+  assert.equal(ev.subject, "Quick pricing question", "item-shape subject carried");
+  assert.equal(ev.from.id, "casey@customer.com");
+  assert.equal(ev.timestamp, "2026-07-21T01:02:03.000Z", "receivedAt preferred");
+  assert.deepEqual(ev.source, {
+    channel: "orgmail", chatId: "th-1", replyToRef: "em-1", userScope: "dm", peerId: "casey@customer.com",
+  });
+  assert.equal(ev.attachments.length, 1);
+  assert.equal(ev.attachments[0].filename, "specs.pdf");
+  assert.equal(ev.raw_ref, "orgmail:th-1:em-1");
+});
+
+test("_toEvent: html-only body converts to text; in_reply_to mapped", () => {
+  const { a } = makeAdapter(hqMock());
+  const ev = a._toEvent(DTO({ text: null, html: "<p>Hello <b>there</b></p>", inReplyTo: "<rfc-1@x>" }));
+  assert.match(ev.text, /Hello there/);
+  assert.equal(ev.in_reply_to, "<rfc-1@x>");
+  assert.equal(ev.is_reply, true);
+});
+
+test("_toEvent: junk frames drop (null)", () => {
+  const { a } = makeAdapter(hqMock());
+  assert.equal(a._toEvent(null), null);
+  assert.equal(a._toEvent({}), null);
+});
+
+// ── _send ──────────────────────────────────────────────────────────────────
+
+test("_send: thread reply rides email.send {threadId, text, idempotencyId} — no to/subject (server reply rule)", async () => {
+  const fetchImpl = hqMock();
+  const { a } = makeAdapter(fetchImpl);
+  const res = await a._send({ text: "On it — reply drafted.", source: { channel: "orgmail", chatId: "th-9" } });
+  assert.equal(res.ok, true);
+  assert.equal(res.message_id, "out-1");
+  const sent = fetchImpl.callsTo("/api/v1/email.send");
+  assert.equal(sent.length, 1);
+  assert.equal(sent[0].body.threadId, "th-9");
+  assert.equal(sent[0].body.text, "On it — reply drafted.");
+  assert.ok(sent[0].body.idempotencyId && sent[0].body.idempotencyId.length >= 8, "business dedup id minted");
+  assert.equal(sent[0].body.to, undefined, "recipients derived server-side");
+  assert.equal(sent[0].body.subject, undefined, "subject inherited from the thread");
+  assert.ok(sent[0].headers["x-idempotency-key"], "fresh dispatcher key per invocation");
+});
+
+test("_send: approval_required maps to {ok:false} pointing at send-orgmail.mjs", async () => {
+  const fetchImpl = hqMock({
+    sendBody: { ok: true, result: { status: "approval_required", approval: { actionClass: "external_comms", payloadHash: "h", intent: {} }, firstContactRecipients: ["new@x.com"] } },
+  });
+  const { a } = makeAdapter(fetchImpl);
+  const res = await a._send({ text: "hi", source: { chatId: "th-9" } });
+  assert.equal(res.ok, false);
+  assert.match(res.error, /send-orgmail\.mjs --request-approval/);
+  assert.equal(res.raw.status, "approval_required");
+});
+
+test("send(): the inherited BaseAdapter perimeter screens outbound content", async () => {
+  const screened = [];
+  const fetchImpl = hqMock();
+  const { a } = makeAdapter(fetchImpl, {
+    sendGate: true,
+    screenOutbound: async (o) => { screened.push(o); return { allow: true }; },
+  });
+  const res = await a.send({ text: "gated reply", source: { channel: "orgmail", chatId: "th-2" } });
+  assert.equal(res.ok, true);
+  assert.equal(screened.length, 1, "screenOutbound ran before _send");
+  // and a veto blocks with a uniform SendResult
+  const { a: blocked } = makeAdapter(hqMock(), { sendGate: true, screenOutbound: async () => ({ allow: false, reason: "policy" }) });
+  const b = await blocked.send({ text: "no", source: { chatId: "th-2" } });
+  assert.deepEqual(b, { ok: false, blocked: true, reason: "policy" });
+});
+
+// ── health ─────────────────────────────────────────────────────────────────
+
+test("healthCheck: one email.inbox {limit:1} probe; surfaces the mailbox address", async () => {
+  const fetchImpl = hqMock();
+  const { a } = makeAdapter(fetchImpl);
+  const h = await a.healthCheck();
+  assert.equal(h.ok, true);
+  assert.match(h.detail, /astra@agents\.example/);
+  assert.deepEqual(fetchImpl.callsTo("/api/v1/email.inbox")[0].body, { limit: 1 });
+});
+
+test("healthCheck: server predating the email family (404 frame) degrades honestly", async () => {
+  const fetchImpl = async (url, init) => ({ ok: false, status: 404, json: async () => ({ ok: false, error: { code: "NOT_FOUND", message: "unknown method email.inbox" } }), headers: { get: () => undefined } });
+  const { a } = makeAdapter(fetchImpl);
+  const h = await a.healthCheck();
+  assert.equal(h.ok, false);
+  assert.match(h.detail, /NOT_FOUND/);
+});
+
+test("healthCheck: missing enrollment is an honest unhealthy, not a throw", async () => {
+  const a = new OrgMailAdapter({ agentRoot: "/tmp/none", orgConfig: { org: {} }, supervise: false, log: () => {}, setInterval: () => ({ unref() {} }), clearInterval: () => {} });
+  const h = await a.healthCheck();
+  assert.equal(h.ok, false);
+  assert.match(h.detail, /enrollment missing/);
+});