@cohortapp/agent-sdk 2.3.0

package/lib/org/handoff.mjs

@@ -0,0 +1,293 @@
+/**
+ * lib/org/handoff.mjs — agent-to-agent (A2A) handoff over the human comms layer.
+ *
+ * An agent delegates work to a colleague by emitting a structured envelope — a
+ * fenced ```maestro-handoff JSON block with a human-readable line above it — over
+ * an EXISTING channel (Slack/email) to the target's coordinates. Because it rides
+ * the human channels, every handoff is visible to the responsible humans:
+ * observability by construction. The receiving daemon recognizes the envelope and
+ * enqueues a provenance-tagged task.
+ *
+ * Pure envelope/parse/resolve/record logic (unit-tested) + a thin, injectable,
+ * fail-open transport (default: scripts/slack-send.sh) and enqueue.
+ *
+ * @module lib/org/handoff
+ */
+
+"use strict";
+
+import { spawnSync } from "node:child_process";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+
+import { canonicalize } from "./protocol.mjs";
+import { isEnabled, configFromAgent, handoffOffer, handoffAccept } from "./client.mjs";
+
+export const HANDOFF_FENCE = "maestro-handoff";
+
+function shortId(s) {
+  return createHash("sha1").update(String(s)).digest("hex").slice(0, 10);
+}
+
+/**
+ * Build a handoff message: a human-readable line + a fenced JSON envelope.
+ * Pure. The envelope carries everything the receiver needs to enqueue a task.
+ *
+ * The envelope is v:2-capable: when a `sign(data)->base64` closure (from
+ * lib/org/keys.mjs) and a `keyId` are supplied, the envelope is signed over its
+ * canonical JSON and bumped to v:2 (adds `sig`, `keyId`, `deadline`) — the shape
+ * the Cohort server (and the receiving agent's verify layer) validate. Absent a
+ * signer it stays v:1 (unsigned), preserving the file-transport path and the
+ * existing build/parse round-trip byte-for-byte.
+ *
+ * @param {object} o - {
+ *   from, to, intent, payload?, dueBy?, visibility?, id?, nowMs?,
+ *   itemId?, deadline?, sign?, keyId?
+ * }
+ * @returns {{ id, text, envelope }}
+ */
+export function buildHandoffEnvelope(o = {}) {
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const createdAt = new Date(nowMs).toISOString();
+  const id = o.id || `ho-${shortId(`${o.from}|${o.to}|${o.intent}|${createdAt}`)}`;
+  const signing = typeof o.sign === "function";
+  const envelope = {
+    v: signing ? 2 : 1,
+    id,
+    from: o.from || "",
+    to: o.to || "",
+    intent: String(o.intent || "").slice(0, 280),
+    payload: o.payload && typeof o.payload === "object" ? o.payload : {},
+    dueBy: o.dueBy || null,
+    visibility: o.visibility || "human-visible",
+    createdAt,
+  };
+  if (o.itemId) envelope.itemId = String(o.itemId);
+  if (signing) {
+    envelope.deadline = o.deadline || o.dueBy || null;
+    envelope.keyId = o.keyId || "";
+    // Sign over the canonical envelope BEFORE the sig field is attached, so both
+    // sides recompute the same signing material (protocol.canonicalize = sorted).
+    try { envelope.sig = o.sign(canonicalize(envelope)); } catch { envelope.sig = ""; }
+  }
+  const human = `🤝 Handoff for ${envelope.to || "you"} from ${envelope.from || "an agent"}: ${envelope.intent}`;
+  const text = `${human}\n\n\`\`\`${HANDOFF_FENCE}\n${JSON.stringify(envelope, null, 2)}\n\`\`\``;
+  return { id, text, envelope };
+}
+
+/**
+ * Extract a handoff envelope from inbound message text. Returns the envelope
+ * object, or null if the text carries no (valid) handoff block. Tolerant.
+ */
+export function parseHandoffEnvelope(text) {
+  if (!text || typeof text !== "string") return null;
+  const re = new RegExp("```" + HANDOFF_FENCE + "\\s*([\\s\\S]*?)```", "i");
+  const m = text.match(re);
+  if (!m) return null;
+  try {
+    const obj = JSON.parse(m[1].trim());
+    if (obj && obj.id && obj.intent) return obj;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a target directory entry from a reference (id, name, slackId, or
+ * email). Pure. Returns the entry or null.
+ */
+export function resolveTarget(directory, toRef) {
+  if (!Array.isArray(directory) || !toRef) return null;
+  const ref = String(toRef).toLowerCase().replace(/^@/, "");
+  for (const e of directory) {
+    const cands = [e.id, e.name, e.fullName, e.slackId, e.email, e.repo]
+      .filter(Boolean).map((x) => String(x).toLowerCase());
+    if (cands.includes(ref)) return e;
+    if (e.name && String(e.name).toLowerCase() === ref) return e;
+  }
+  return null;
+}
+
+/** Append a handoff record to state/org/handoffs.jsonl. Fail-open. */
+export function recordHandoff(agentRoot, envelope, direction) {
+  if (!agentRoot || !envelope) return false;
+  try {
+    const dir = join(agentRoot, "state", "org");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "handoffs.jsonl"), JSON.stringify({ direction, ...envelope, recordedAt: new Date().toISOString() }) + "\n");
+    return true;
+  } catch { return false; }
+}
+
+/** Default transport: send via scripts/slack-send.sh to the target's slackId. Fail-open. */
+export function defaultTransport({ agentRoot, target, text }) {
+  try {
+    if (!target || !target.slackId) return { ok: false, channel: null, reason: "no-slack-id" };
+    const res = spawnSync(join(agentRoot, "scripts", "slack-send.sh"), [target.slackId, text], {
+      cwd: agentRoot,
+      env: { ...process.env, AGENT_DIR: agentRoot },
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    return { ok: res.status === 0, channel: `slack:${target.slackId}`, reason: res.status === 0 ? "sent" : `exit-${res.status}` };
+  } catch (e) {
+    return { ok: false, channel: null, reason: e.message };
+  }
+}
+
+/**
+ * Send a handoff to a colleague. Resolves the target, builds the (signed when a
+ * device-key signer is supplied) envelope, records it, and dispatches.
+ *
+ * Routing (§10 "defaultTransport() becomes client.call('handoff.offer', …)"):
+ *  - When `org.cohort` is enabled (cfg passed), delivery goes THROUGH the
+ *    Cohort server via client.handoffOffer — the signed envelope is the wire
+ *    payload AND the fenced chat-mirror text is retained for human visibility.
+ *    handoff.offer is governance-gated, so a fresh server returns
+ *    GOVERNANCE_NOT_READY (surfaced in transport.reason). Resolution by exact
+ *    agent_id (target.id) only — the server resolves targets, not the channel.
+ *  - Otherwise, the existing file/channel transport (default: slack-send.sh)
+ *    carries the fenced envelope, exactly as before.
+ *
+ * Always resolves (fail-open).
+ *
+ * @param {object} o - {
+ *   agentRoot, from, to, intent, payload?, dueBy?, visibility?,
+ *   directory?, transportFn?, nowMs?,
+ *   cfg?, itemId?, deadline?, sign?, keyId?, fetchImpl?
+ * }
+ * @returns {Promise<{sent:boolean, target:object|null, envelope:object, transport:object, via:string}>}
+ */
+export async function sendHandoff(o = {}) {
+  const directory = Array.isArray(o.directory) ? o.directory : [];
+  const target = resolveTarget(directory, o.to);
+  const built = buildHandoffEnvelope({ ...o, to: (target && (target.name || target.id)) || o.to });
+  recordHandoff(o.agentRoot, { ...built.envelope, targetResolved: !!target }, "outbound");
+
+  // --- Cohort path: route through handoff.offer -----------------------------
+  // The server's handoff.offer contract (services/cohort/src/methods/handoff/
+  // offer.mjs) requires {itemId, toAgent, intent} and rebuilds the envelope
+  // server-side; it returns {runId, ...}. A Cohort handoff attaches to a board
+  // work item, so an itemId is mandatory here — without one we cannot use the
+  // server relay (fall back / report rather than send a request the server 400s).
+  if (isEnabled(o.cfg) && !o.transportFn) {
+    if (!target) return { sent: false, target: null, envelope: built.envelope, runId: null, transport: { ok: false, reason: "no-target" }, via: "cohort" };
+    const itemId = o.itemId || built.envelope.itemId || (o.payload && o.payload.itemId);
+    if (!itemId) {
+      return { sent: false, target, envelope: built.envelope, runId: null, transport: { ok: false, reason: "cohort-handoff-requires-itemId" }, via: "cohort" };
+    }
+    const c = configFromAgent(o.cfg);
+    const frame = await handoffOffer(
+      {
+        itemId: String(itemId),
+        toAgent: target.id,             // exact agent_id only (server resolves)
+        intent: o.intent || built.envelope.intent,
+        payload: o.payload || built.envelope.payload || {},
+        dueBy: built.envelope.deadline || built.envelope.dueBy || o.dueBy || undefined,
+        envelope: built.envelope,       // server keys the run on THIS envelope's id
+        envelopeSig: built.envelope.sig || "",
+      },
+      { base: c.base, token: c.token, idempotencyKey: `handoff.offer:${built.envelope.id}`, fetchImpl: o.fetchImpl },
+    );
+    const ok = !!(frame && frame.ok);
+    const runId = ok && frame.result ? frame.result.runId : null;
+    return {
+      sent: ok,
+      target,
+      envelope: built.envelope,
+      runId,                            // canonical server handoff key (for accept/decline/cancel)
+      transport: { ok, reason: ok ? "offered" : (frame && frame.error && frame.error.code) || "error", frame },
+      via: "cohort",
+    };
+  }
+
+  // --- File/channel fallback (default: slack-send.sh) ------------------------
+  const transport = o.transportFn || defaultTransport;
+  let result = { ok: false, reason: "no-target" };
+  if (target) {
+    try {
+      result = await transport({ agentRoot: o.agentRoot, target, text: built.text, envelope: built.envelope });
+    } catch (e) {
+      result = { ok: false, reason: e.message };
+    }
+  }
+  return { sent: !!result.ok, target, envelope: built.envelope, transport: result, via: "file" };
+}
+
+/**
+ * Ingest an inbound message: if it carries a handoff envelope, record it and
+ * enqueue a provenance-tagged task. Returns the created task or null. Enqueue is
+ * injectable; default appends to state/queues/handoffs.yaml.
+ *
+ * Routing: when `org.cohort` is enabled (cfg passed), the delegatee ACCEPTS the
+ * handoff through the server via client.handoffAccept (governance-gated) BEFORE
+ * enqueueing the local task — so the server-side handoff row flips to `accepted`
+ * and the delegator's deadline timer is satisfied. The accept is fail-open
+ * (a down/gated server is recorded on the task as `accept_status` but never
+ * blocks the local enqueue — the file fallback semantics are preserved). The
+ * local enqueue remains idempotent on handoff_id.
+ *
+ * @param {object} o - { agentRoot, text, enqueueFn?, nowMs?, cfg?, fetchImpl? }
+ * @returns {Promise<object|null>}
+ */
+export async function ingestHandoff(o = {}) {
+  const env = parseHandoffEnvelope(o.text);
+  if (!env) return null;
+  recordHandoff(o.agentRoot, env, "inbound");
+
+  // Cohort path: accept the handoff server-side (fail-open).
+  let acceptStatus = "file";
+  if (isEnabled(o.cfg)) {
+    const c = configFromAgent(o.cfg);
+    const frame = await handoffAccept(
+      { handoffId: env.id },
+      { base: c.base, token: c.token, idempotencyKey: `handoff.accept:${env.id}`, fetchImpl: o.fetchImpl },
+    );
+    acceptStatus = (frame && frame.ok) ? "accepted" : ((frame && frame.error && frame.error.code) || "error");
+  }
+
+  const task = {
+    id: `seed-${env.id}`,
+    title: env.intent,
+    status: "open",
+    priority: env.payload && env.payload.priority ? env.payload.priority : "high",
+    owner: "agent",
+    next_action: env.intent,
+    source: "a2a-handoff",
+    from_agent: env.from,
+    handoff_id: env.id,
+    accept_status: acceptStatus,
+    context: env.payload && env.payload.context ? String(env.payload.context).slice(0, 1000) : "",
+    created: new Date(Number.isFinite(o.nowMs) ? o.nowMs : Date.now()).toISOString(),
+    history: [],
+  };
+  const enqueue = o.enqueueFn || defaultEnqueue;
+  try { await enqueue(o.agentRoot, task); } catch { /* fail-open */ }
+  return task;
+}
+
+/** Default enqueue: read-modify-write state/queues/handoffs.yaml. Fail-open. */
+async function defaultEnqueue(agentRoot, task) {
+  if (!agentRoot) return false;
+  try {
+    const m = await import("js-yaml");
+    const yaml = m.default || m;
+    const dir = join(agentRoot, "state", "queues");
+    mkdirSync(dir, { recursive: true });
+    const p = join(dir, "handoffs.yaml");
+    let doc = { items: [] };
+    if (existsSync(p)) {
+      try {
+        const parsed = yaml.load(readFileSync(p, "utf8"));
+        if (parsed && Array.isArray(parsed.items)) doc = parsed;
+        else if (Array.isArray(parsed)) doc = { items: parsed };
+      } catch { /* start fresh */ }
+    }
+    if (doc.items.some((it) => it && it.handoff_id === task.handoff_id)) return true; // idempotent
+    doc.items.push(task);
+    writeFileSync(p, yaml.dump(doc));
+    return true;
+  } catch { return false; }
+}

package/lib/org/handoff.test.mjs

@@ -0,0 +1,269 @@
+/**
+ * handoff.test.mjs — tests for A2A handoff envelopes + dispatch + ingest.
+ * Run: node --test lib/org/handoff.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  HANDOFF_FENCE, buildHandoffEnvelope, parseHandoffEnvelope, resolveTarget,
+  recordHandoff, sendHandoff, ingestHandoff,
+} from "./handoff.mjs";
+
+function tmp() { return mkdtempSync(join(tmpdir(), "org-handoff-")); }
+const NOW = Date.parse("2026-06-03T12:00:00Z");
+
+test("buildHandoffEnvelope: human line + fenced JSON envelope", () => {
+  const { text, envelope, id } = buildHandoffEnvelope({
+    from: "alex-ai", to: "Bob", intent: "Review the Q3 deck", payload: { context: "due Friday" }, nowMs: NOW,
+  });
+  assert.match(text, /🤝 Handoff for Bob from alex-ai/);
+  assert.match(text, new RegExp("```" + HANDOFF_FENCE));
+  assert.equal(envelope.intent, "Review the Q3 deck");
+  assert.equal(envelope.payload.context, "due Friday");
+  assert.ok(id.startsWith("ho-"));
+});
+
+test("parseHandoffEnvelope: round-trips build output; null for non-handoff", () => {
+  const { text, envelope } = buildHandoffEnvelope({ from: "a", to: "b", intent: "do x", nowMs: NOW });
+  const parsed = parseHandoffEnvelope(text);
+  assert.equal(parsed.id, envelope.id);
+  assert.equal(parsed.intent, "do x");
+  assert.equal(parseHandoffEnvelope("just a normal slack message"), null);
+  assert.equal(parseHandoffEnvelope("```" + HANDOFF_FENCE + "\nnot json\n```"), null);
+});
+
+test("resolveTarget: by id, name, slackId, email; null otherwise", () => {
+  const dir = [{ id: "bob-ai", name: "Bob", fullName: "Bob Lee", slackId: "U2", email: "bob@x.com" }];
+  assert.equal(resolveTarget(dir, "bob-ai").id, "bob-ai");
+  assert.equal(resolveTarget(dir, "Bob").id, "bob-ai");
+  assert.equal(resolveTarget(dir, "@U2").id, "bob-ai");
+  assert.equal(resolveTarget(dir, "bob@x.com").id, "bob-ai");
+  assert.equal(resolveTarget(dir, "carol"), null);
+});
+
+test("recordHandoff: appends to state/org/handoffs.jsonl", () => {
+  const root = tmp();
+  try {
+    recordHandoff(root, { id: "ho-1", intent: "x" }, "outbound");
+    const p = join(root, "state", "org", "handoffs.jsonl");
+    assert.ok(existsSync(p));
+    assert.match(readFileSync(p, "utf8"), /"direction":"outbound"/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("sendHandoff: resolves target, records, dispatches via injected transport", async () => {
+  const root = tmp();
+  try {
+    const calls = [];
+    const transportFn = async ({ target, text }) => { calls.push({ target, text }); return { ok: true, channel: `slack:${target.slackId}` }; };
+    const res = await sendHandoff({
+      agentRoot: root, from: "alex-ai", to: "bob", intent: "ship it",
+      directory: [{ id: "bob-ai", name: "Bob", slackId: "U2" }], transportFn, nowMs: NOW,
+    });
+    assert.equal(res.sent, true);
+    assert.equal(res.target.id, "bob-ai");
+    assert.equal(calls.length, 1);
+    assert.match(readFileSync(join(root, "state", "org", "handoffs.jsonl"), "utf8"), /"direction":"outbound"/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("sendHandoff: no resolvable target → not sent (but still recorded)", async () => {
+  const root = tmp();
+  try {
+    const res = await sendHandoff({ agentRoot: root, from: "a", to: "ghost", intent: "x", directory: [], nowMs: NOW });
+    assert.equal(res.sent, false);
+    assert.equal(res.target, null);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("ingestHandoff: envelope → provenance-tagged task; default enqueue is idempotent", async () => {
+  const root = tmp();
+  try {
+    const { text } = buildHandoffEnvelope({ from: "bob-ai", to: "alex", intent: "draft the memo", payload: { priority: "high", context: "board wants it" }, nowMs: NOW });
+    const task = await ingestHandoff({ agentRoot: root, text, nowMs: NOW });
+    assert.equal(task.source, "a2a-handoff");
+    assert.equal(task.from_agent, "bob-ai");
+    assert.equal(task.title, "draft the memo");
+    assert.equal(task.priority, "high");
+    // idempotent: ingest the same envelope again → still one queue item
+    await ingestHandoff({ agentRoot: root, text, nowMs: NOW });
+    const m = await import("js-yaml");
+    const doc = (m.default || m).load(readFileSync(join(root, "state", "queues", "handoffs.yaml"), "utf8"));
+    assert.equal(doc.items.length, 1, "same handoff_id not enqueued twice");
+    assert.match(readFileSync(join(root, "state", "org", "handoffs.jsonl"), "utf8"), /"direction":"inbound"/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("ingestHandoff: plain text → null", async () => {
+  assert.equal(await ingestHandoff({ agentRoot: tmp(), text: "hello there" }), null);
+});
+
+// --- v2 signed envelope ----------------------------------------------------
+
+test("buildHandoffEnvelope: signer present → v2 with sig/keyId/deadline; verifies", async () => {
+  const { generateDeviceKey, signWith, verifySignature } = await import("./keys.mjs");
+  const { canonicalize } = await import("./protocol.mjs");
+  const kp = generateDeviceKey();
+  const { envelope } = buildHandoffEnvelope({
+    from: "alex-ai", to: "bob-ai", intent: "do x", itemId: "wi_1", deadline: "2026-06-12T00:00:00Z",
+    sign: (d) => signWith(kp.privateKeyPem, d), keyId: "alex#1", nowMs: NOW,
+  });
+  assert.equal(envelope.v, 2);
+  assert.equal(envelope.keyId, "alex#1");
+  assert.equal(envelope.deadline, "2026-06-12T00:00:00Z");
+  assert.ok(envelope.sig);
+  // re-derive the signing material exactly as build did (sig stripped) → verifies
+  const { sig, ...unsigned } = envelope;
+  assert.equal(verifySignature(kp.publicKeyPem, canonicalize(unsigned), sig), true);
+});
+
+test("buildHandoffEnvelope: no signer → stays v1 (file-transport compatible)", () => {
+  const { envelope } = buildHandoffEnvelope({ from: "a", to: "b", intent: "x", nowMs: NOW });
+  assert.equal(envelope.v, 1);
+  assert.ok(!("sig" in envelope));
+});
+
+// --- Cohort routing: sendHandoff through handoff.offer ----------------------
+
+const ON = { org: { cohort: { enabled: true, base: "https://org.cohortapp.com", token: "tok" } } };
+
+/** A fetch fake that records the /v1 calls and returns a canned res frame. */
+function fakeFetch(responder) {
+  const calls = [];
+  const impl = async (url, init) => {
+    calls.push({ url, init });
+    const r = responder ? responder(url, init) : null;
+    const body = r ? r.body : { ok: true, result: null };
+    const status = r && r.status ? r.status : 200;
+    return { ok: status >= 200 && status < 300, status, headers: { get: () => undefined }, json: async () => body };
+  };
+  impl.calls = calls;
+  return impl;
+}
+
+test("sendHandoff: org.cohort enabled → routes through POST /v1/handoff.offer", async () => {
+  const root = tmp();
+  try {
+    const f = fakeFetch((url) => {
+      assert.match(url, /\/v1\/handoff\.offer$/);
+      return { body: { ok: true, result: { handoffId: "x", state: "offered" } } };
+    });
+    const res = await sendHandoff({
+      agentRoot: root, cfg: ON, from: "alex-ai", to: "bob",
+      intent: "ship it", itemId: "wi_1", directory: [{ id: "bob-ai", name: "Bob", slackId: "U2" }],
+      fetchImpl: f, nowMs: NOW,
+    });
+    assert.equal(res.via, "cohort");
+    assert.equal(res.sent, true);
+    assert.equal(res.target.id, "bob-ai");
+    assert.equal(f.calls.length, 1);
+    const body = JSON.parse(f.calls[0].init.body);
+    // The wire contract handoff.offer requires {itemId, toAgent, intent}; the
+    // signed envelope is carried so the server can key the run on its id.
+    assert.equal(body.toAgent, "bob-ai");            // exact agent_id only
+    assert.equal(body.itemId, "wi_1");
+    assert.equal(body.intent, "ship it");
+    assert.equal(body.envelope.id, res.envelope.id);
+    assert.equal(f.calls[0].init.headers["x-idempotency-key"], `handoff.offer:${res.envelope.id}`);
+    // still recorded locally
+    assert.match(readFileSync(join(root, "state", "org", "handoffs.jsonl"), "utf8"), /"direction":"outbound"/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("sendHandoff: enabled but governance not ready → sent:false, code surfaced", async () => {
+  const root = tmp();
+  try {
+    const f = fakeFetch(() => ({ status: 423, body: { ok: false, error: { code: "GOVERNANCE_NOT_READY", message: "no rights" } } }));
+    const res = await sendHandoff({
+      agentRoot: root, cfg: ON, from: "a", to: "bob", intent: "x", itemId: "wi_1",
+      directory: [{ id: "bob-ai", name: "Bob" }], fetchImpl: f, nowMs: NOW,
+    });
+    assert.equal(res.via, "cohort");
+    assert.equal(res.sent, false);
+    assert.equal(res.transport.reason, "GOVERNANCE_NOT_READY");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("sendHandoff: org disabled → falls back to file transport (no /v1 call)", async () => {
+  const root = tmp();
+  try {
+    let fetchHit = false;
+    const f = () => { fetchHit = true; throw new Error("should not be called"); };
+    const calls = [];
+    const transportFn = async ({ target, text }) => { calls.push({ target, text }); return { ok: true }; };
+    const res = await sendHandoff({
+      agentRoot: root, cfg: { org: { cohort: { enabled: false } } },
+      from: "alex-ai", to: "bob", intent: "ship", directory: [{ id: "bob-ai", name: "Bob", slackId: "U2" }],
+      transportFn, fetchImpl: f, nowMs: NOW,
+    });
+    assert.equal(res.via, "file");
+    assert.equal(res.sent, true);
+    assert.equal(calls.length, 1);
+    assert.equal(fetchHit, false, "no /v1 call when org plane is disabled");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("sendHandoff: no cfg → file transport (back-compat with existing callers)", async () => {
+  const root = tmp();
+  try {
+    const calls = [];
+    const res = await sendHandoff({
+      agentRoot: root, from: "alex-ai", to: "bob", intent: "ship",
+      directory: [{ id: "bob-ai", name: "Bob", slackId: "U2" }],
+      transportFn: async ({ target }) => { calls.push(target); return { ok: true }; }, nowMs: NOW,
+    });
+    assert.equal(res.via, "file");
+    assert.equal(res.sent, true);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+// --- Cohort routing: ingestHandoff through handoff.accept -------------------
+
+test("ingestHandoff: org enabled → accepts via POST /v1/handoff.accept, then enqueues", async () => {
+  const root = tmp();
+  try {
+    const { text } = buildHandoffEnvelope({ from: "bob-ai", to: "alex", intent: "draft memo", nowMs: NOW });
+    const f = fakeFetch((url) => {
+      assert.match(url, /\/v1\/handoff\.accept$/);
+      return { body: { ok: true, result: { state: "accepted" } } };
+    });
+    const task = await ingestHandoff({ agentRoot: root, cfg: ON, text, fetchImpl: f, nowMs: NOW });
+    assert.equal(task.accept_status, "accepted");
+    assert.equal(f.calls.length, 1);
+    const body = JSON.parse(f.calls[0].init.body);
+    assert.equal(body.handoffId, task.handoff_id);
+    // local enqueue still happens (idempotent)
+    const m = await import("js-yaml");
+    const doc = (m.default || m).load(readFileSync(join(root, "state", "queues", "handoffs.yaml"), "utf8"));
+    assert.equal(doc.items.length, 1);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("ingestHandoff: org disabled → no /v1 call, accept_status 'file'", async () => {
+  const root = tmp();
+  try {
+    const { text } = buildHandoffEnvelope({ from: "bob-ai", to: "alex", intent: "x", nowMs: NOW });
+    let hit = false;
+    const f = () => { hit = true; throw new Error("nope"); };
+    const task = await ingestHandoff({ agentRoot: root, cfg: { org: { cohort: { enabled: false } } }, text, fetchImpl: f, nowMs: NOW });
+    assert.equal(task.accept_status, "file");
+    assert.equal(hit, false);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("ingestHandoff: enabled but accept gated → fail-open, task still enqueued", async () => {
+  const root = tmp();
+  try {
+    const { text } = buildHandoffEnvelope({ from: "bob-ai", to: "alex", intent: "x", nowMs: NOW });
+    const f = fakeFetch(() => ({ status: 423, body: { ok: false, error: { code: "GOVERNANCE_NOT_READY", message: "x" } } }));
+    const task = await ingestHandoff({ agentRoot: root, cfg: ON, text, fetchImpl: f, nowMs: NOW });
+    assert.equal(task.accept_status, "GOVERNANCE_NOT_READY");
+    assert.equal(task.title, "x");  // local enqueue not blocked by the gated accept
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});