@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/org/tool-surface.test.mjs

@@ -1,1268 +0,0 @@
-/**
- * tool-surface.test.mjs — the curated org tool table + shared executor.
- *
- * Hermetic: every network call rides an injected fetchImpl; the send-gate is an
- * injected stub; env is snapshotted/cleared so a developer's COHORT_* vars
- * can't leak in. Run: node --test lib/org/tool-surface.test.mjs
- */
-
-"use strict";
-
-import { test, before, after } from "node:test";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import assert from "node:assert/strict";
-
-import {
-  ORG_TOOLS,
-  getOrgTools,
-  isOrgTool,
-  orgToolDef,
-  OUTBOUND_METHODS,
-  emailFamilyAvailable,
-  artifactFamilyAvailable,
-  deskFamilyAvailable,
-  resolveOrgToolConfig,
-  executeOrgTool,
-  DEFAULT_COHORT_BASE,
-} from "./tool-surface.mjs";
-import { methodDef, PROTOCOL_VERSION, READS } from "./protocol.mjs";
-import { ADMIN_TOOLS, expectedAccessFor, normalizeToolAccess } from "./tool-access.mjs";
-
-// ── env hygiene ────────────────────────────────────────────────────────────
-const ENV_KEYS = [
-  "COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY", "COHORT_ORG_ID",
-  "COHORT_BASE", "COHORT_API_URL", "COHORT_AGENT_ROOT", "AGENT_ROOT",
-  "COHORT_AGENT_ID", "COHORT_AGENT_EMAIL",
-];
-const saved = {};
-before(() => {
-  for (const k of ENV_KEYS) { saved[k] = process.env[k]; delete process.env[k]; }
-});
-after(() => {
-  for (const k of ENV_KEYS) {
-    if (saved[k] === undefined) delete process.env[k];
-    else process.env[k] = saved[k];
-  }
-});
-
-// ── helpers ────────────────────────────────────────────────────────────────
-const CFG = { org: { cohort: { enabled: true, base: "https://org.example", orgId: "acme", token: "nlk_secret" } } };
-
-/** fetch stub: records calls, returns a res-frame body. */
-function fakeFetch(body = { ok: true, result: { fine: true } }, { status = 200, ok = true } = {}) {
-  const calls = [];
-  const fn = async (url, init) => {
-    calls.push({ url: String(url), init: init || {} });
-    return { ok, status, json: async () => body, headers: { get: () => undefined } };
-  };
-  fn.calls = calls;
-  return fn;
-}
-
-// ── table shape ────────────────────────────────────────────────────────────
-
-test("table: curated 54 + 5 email + 5 artifact + 77 desk tools, snake_case names, valid access + schemas", () => {
-  // 2026-08 mobile-parity delta: +5 mail (report_spam/react/move_mailbox/
-  // summarise/ask) and +3 asks (files/calendar/crm) → desk 56 → 64; the
-  // call-working-sessions delta adds the 5 calls-desk tools → 69.
-  // The wire-contract fix adds task_assign: hq's editTaskSchema (board.updateTask)
-  // has NO assignee field, so reassignment needs board.assignTask — curated 28 → 29.
-  // The conversation-parity delta adds the per-message actions the human
-  // long-press sheet ships (react/bookmark/delete/mark_unread_from) and the two
-  // huddle verbs the share tools presuppose (start/join) — curated 29 → 35.
-  // They are ALWAYS-ON, not desk-gated: the base messaging/channel/calling
-  // families have been vendored since SP3.
-  // The macro-parity delta adds org_pulse (GET ops?pulse=1 — the founder's
-  // attention surface, previously human-only), org_huddle_end (which closes the
-  // loop org_huddle_start opened) and memory_recall — hq built memory.recall
-  // explicitly because "an SDK-driven seat has been reasoning off a strictly
-  // smaller memory than the chat lane", then shipped no tool for it, so the
-  // reverse-parity fix never reached the plane it was built for.
-  // Curated 35 → 38.
-  // The ENGAGEMENT delta adds the four verbs an SDK seat needs to bring somebody
-  // in and had no binding for, despite all four sitting in the frozen protocol
-  // table since it was written: messaging_open_group (channel.createConversation),
-  // messaging_create_channel (channel.create), messaging_add_to_channel
-  // (channel.addMember), and engage_colleagues — the judged path that decides
-  // WHETHER anyone needs involving before it opens anything at all.
-  // Curated 38 → 42, +1 for work_track → 43.
-  // The VOICE delta adds messaging_send_voice_note — hq could synthesise a
-  // colleague's voice note only as a reflex (answering a human's spoken note in
-  // kind), so an agent ASKED in text for one had no verb and truthfully said it
-  // could not. A `local` binding: it records (messaging.synthesizeVoiceNote)
-  // then posts (plain messaging.send with the file attached). Curated 43 → 44.
-  // The MANDATE + REGISTRY + PREFERENCE delta (+10 → 54). Three families that
-  // were protocol-declared and curated NOWHERE, so a session could reach them
-  // only through `org_rpc` — access:"admin", i.e. not at all below the CEO tier:
-  //   mandate (5)     — hq's own chat colleague has carried the whole belt
-  //                     since the spine landed, under a docblock naming SDK
-  //                     parity as its reason; the SDK plane had none of it, so
-  //                     the daemon knew the seat's objectives and the session it
-  //                     spawned did not. adopt/retire are deliberately absent —
-  //                     `mandate.write` is not in DEFAULT_AGENT_SCOPES.
-  //   subagent (3)    — READS only. hq keeps the registry, maestro generates
-  //                     sub-agents locally, and the two halves never met. The
-  //                     writes stay with lib/subagents/client.mjs, which owns
-  //                     the offline outbox and the lock file a second writer
-  //                     would silently bypass.
-  //   preference (2)  — hq built this family FOR this plane and said so in the
-  //                     handler; no tool was ever added, so the same workspace
-  //                     remembered a standing preference when hq answered and
-  //                     forgot it when the seat's own daemon did.
-  // The RESOURCE delta (+8 desk → 77, table 133 → 141). A venture's artifacts
-  // cross from the portal and are filed as real WorkspaceFile rows, and the
-  // OrgResource catalogue that indexes them was reachable from NO agent code
-  // path in EITHER plane — the venture's own colleagues could not list, add,
-  // correct, reorder or remove one of their own deliverables. Unlike every
-  // block above it, this one is GENERATED from the vendored protocol
-  // declaration (lib/org/resource-tools.mjs) rather than transcribed from hq's
-  // desk, so it cannot acquire the 239-vs-69 drift the hand-copied desks
-  // already carry; resource-tools.test.mjs is the parity that holds it there.
-  // The FRONT-DOOR delta (+3 curated → 57, table 141 → 144; design spec
-  // 2026-09-08 §3.5/§3.7): board_mine (the agent's own items across every
-  // board — board.ready is unassigned-only, so "my tasks" was unreadable from
-  // any plane), board_track (the sanctioned inbound→board seam with the
-  // accepted/done ends of the ladder and title/why passthrough) and
-  // session_status (the main session's liveness + peers from local state,
-  // offline-capable).
-  assert.equal(ORG_TOOLS.length, 144, "57 curated + 5 email + 5 artifact + 77 desk");
-  assert.equal(ORG_TOOLS.filter((t) => t.desk).length, 77, "exactly seventy-seven desk tools");
-  assert.equal(ORG_TOOLS.filter((t) => t.email).length, 5, "exactly five email tools");
-  assert.equal(ORG_TOOLS.filter((t) => t.artifact).length, 5, "exactly five artifact tools");
-  for (const t of ORG_TOOLS) {
-    assert.match(t.name, /^[a-z0-9_]+$/, `${t.name} snake_case`);
-    assert.ok(["read", "write", "admin"].includes(t.access), `${t.name} access`);
-    assert.ok(t.description && t.description.length > 10, `${t.name} described`);
-    assert.equal(t.input_schema.type, "object", `${t.name} schema object`);
-    assert.ok(t.binding && ["rpc", "read", "local"].includes(t.binding.kind), `${t.name} binding`);
-    if (t.binding.kind === "rpc") {
-      assert.ok(methodDef(t.binding.method), `${t.name} binds a real protocol method (${t.binding.method})`);
-    }
-    // The rpc side was already pinned to the frozen table; the READ side was
-    // not, so a curated tool could name a read path the server does not serve
-    // and only fail at runtime, as a bare 404 the model cannot interpret.
-    if (t.binding.kind === "read") {
-      assert.ok(
-        Object.prototype.hasOwnProperty.call(READS, t.binding.path),
-        `${t.name} binds a real protocol read (${t.binding.path})`,
-      );
-      if (t.binding.query !== undefined) {
-        assert.equal(typeof t.binding.query, "object", `${t.name} binding.query is an object`);
-        for (const [k, v] of Object.entries(t.binding.query)) {
-          assert.equal(typeof v, "string", `${t.name} binding.query.${k} is a string`);
-        }
-      }
-    }
-  }
-});
-
-test("OUTBOUND_METHODS is DERIVED from outbound:true tools (messaging/email/mail-desk/share-step sends)", () => {
-  assert.deepEqual([...OUTBOUND_METHODS].sort(), ["calling.appShareAct", "email.draftSend", "email.send", "messaging.send"]);
-  // messaging_send_voice_note is outbound-flagged but adds NOTHING to
-  // OUTBOUND_METHODS: it is a `local` binding, and the derivation reads rpc
-  // bindings only. Its POST leg is messaging.send, which is already in the set,
-  // so the escape hatch stays covered too — the flag here buys the screen on
-  // the SPOKEN words, before a billable character is synthesised.
-  const outboundTools = ORG_TOOLS.filter((t) => t.outbound).map((t) => t.name).sort();
-  assert.deepEqual(outboundTools, [
-    "email_draft_send",
-    "email_send",
-    "messaging_send",
-    "messaging_send_voice_note",
-    "org_call_share_step",
-  ]);
-});
-
-test("email gating: family present in the vendored protocol → tools active; override excludes", () => {
-  // The email family landed in the vendored protocol (sync-protocol phase 1).
-  assert.equal(emailFamilyAvailable(), true, "vendored protocol carries email.send");
-  assert.equal(getOrgTools().length, 144);
-  const without = getOrgTools({ emailAvailable: false });
-  assert.equal(without.length, 139);
-  assert.ok(!without.some((t) => t.email), "email tools excluded when family absent");
-});
-
-test("artifact gating: family present → tools active; override excludes (email precedent)", () => {
-  assert.equal(artifactFamilyAvailable(), true, "vendored protocol carries artifact.act");
-  const without = getOrgTools({ artifactAvailable: false });
-  assert.equal(without.length, 139);
-  assert.ok(!without.some((t) => t.artifact), "artifact tools excluded when family absent");
-  const neither = getOrgTools({ emailAvailable: false, artifactAvailable: false, desksAvailable: false });
-  assert.equal(neither.length, 57, "all additive families off → the 57 always-on tools");
-});
-
-test("isOrgTool / orgToolDef cover the full table; unknown names rejected", () => {
-  for (const t of ORG_TOOLS) assert.equal(isOrgTool(t.name), true);
-  assert.equal(isOrgTool("slack_send"), false);
-  assert.equal(isOrgTool(""), false);
-  assert.equal(orgToolDef("org_rpc").access, "admin");
-});
-
-// ── config resolution (§1.4) ───────────────────────────────────────────────
-
-test("resolveOrgToolConfig: config base/token honoured; default base when nothing names one", () => {
-  const cfg = resolveOrgToolConfig({ orgConfig: CFG, agentRoot: "/tmp/none" });
-  assert.equal(cfg.base, "https://org.example");
-  assert.equal(cfg.token, "nlk_secret");
-  assert.equal(cfg.orgId, "acme");
-  const bare = resolveOrgToolConfig({ orgConfig: {}, agentRoot: "/tmp/none" });
-  assert.equal(bare.base, DEFAULT_COHORT_BASE);
-  assert.equal(bare.token, "");
-});
-
-test("resolveOrgToolConfig: COHORT_BASE env wins over config base (env-first)", () => {
-  process.env.COHORT_BASE = "https://env.example/";
-  try {
-    const cfg = resolveOrgToolConfig({ orgConfig: CFG, agentRoot: "/tmp/none" });
-    assert.equal(cfg.base, "https://env.example", "env base wins, trailing slash stripped");
-  } finally {
-    delete process.env.COHORT_BASE;
-  }
-});
-
-// ── executor: basics ───────────────────────────────────────────────────────
-
-test("executeOrgTool: unknown tool → NOT_FOUND frame, never a throw", async () => {
-  const frame = await executeOrgTool("nope_tool", {}, { orgConfig: CFG, agentRoot: "/tmp/none" });
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "NOT_FOUND");
-});
-
-test("executeOrgTool: missing token → clear UNAUTHORIZED frame for network tools", async () => {
-  const fetchImpl = fakeFetch();
-  const frame = await executeOrgTool("org_directory", {}, { orgConfig: {}, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "UNAUTHORIZED");
-  assert.match(frame.error.message, /COHORT_API_TOKEN/);
-  assert.equal(fetchImpl.calls.length, 0, "no network attempted");
-});
-
-test("org_describe: offline, no network, family filter works", async () => {
-  const fetchImpl = fakeFetch();
-  const frame = await executeOrgTool("org_describe", {}, { orgConfig: {}, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, true);
-  assert.equal(frame.result.protocolVersion, PROTOCOL_VERSION);
-  assert.ok(frame.result.methods.length >= 200, "full method table listed");
-  assert.ok(frame.result.reads.length >= 13, "reads listed");
-  const fam = await executeOrgTool("org_describe", { family: "board" }, { orgConfig: {}, agentRoot: "/tmp/none" });
-  assert.ok(fam.result.methods.every((m) => m.family === "board"));
-  assert.deepEqual(fam.result.families, ["board"]);
-  assert.equal(fetchImpl.calls.length, 0);
-});
-
-// ── executor: rpc + read bindings ──────────────────────────────────────────
-
-test("rpc binding: messaging_history POSTs /api/v1/messaging.history with Bearer + org pin", async () => {
-  const fetchImpl = fakeFetch({ ok: true, result: { messages: [] } });
-  const frame = await executeOrgTool("messaging_history", { channelId: "C1", limit: 5 }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, true);
-  assert.equal(fetchImpl.calls.length, 1);
-  const { url, init } = fetchImpl.calls[0];
-  assert.equal(url, "https://org.example/api/v1/messaging.history");
-  assert.equal(init.method, "POST");
-  assert.equal(init.headers.authorization, "Bearer nlk_secret");
-  assert.equal(init.headers["x-org-id"], "acme");
-  assert.deepEqual(JSON.parse(init.body), { channelId: "C1", limit: 5 });
-});
-
-test("read binding: board_ready GETs /api/v1/board.ready and normalises the bare payload", async () => {
-  const fetchImpl = fakeFetch({ items: [{ id: "w1" }] });
-  const frame = await executeOrgTool("board_ready", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, true);
-  assert.deepEqual(frame.result, { items: [{ id: "w1" }] });
-  assert.equal(fetchImpl.calls[0].init.method, "GET");
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/board\.ready$/);
-});
-
-// ── macro pulse (the founder's attention surface, previously human-only) ────
-
-test("org_pulse: the binding PINS ?pulse=1 — the agent never has to know the param", async () => {
-  const fetchImpl = fakeFetch({
-    chainHead: { seq: 42, rowHash: "abc" },
-    members: 9,
-    openAlerts: 2,
-    readyTasks: 5,
-    pulse: {
-      stats: { agentsRunning: 3, blocked: 1, decisionsToday: 2, needs: 2 },
-      needs: [{ id: "esc_1", severity: "high", what: "Blocked on pricing" }],
-      activity: [{ id: "ev_0", sentence: "Assigned a card in Growth" }],
-    },
-  });
-  const frame = await executeOrgTool("org_pulse", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, true);
-  assert.equal(fetchImpl.calls[0].init.method, "GET");
-  // Without a pinned query this GETs the bare probe and the pulse is null — the
-  // whole capability turns on this one param riding the binding.
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/ops\?pulse=1$/);
-  assert.equal(frame.result.pulse.stats.blocked, 1);
-  assert.equal(frame.result.pulse.needs[0].severity, "high");
-});
-
-test("org_pulse is reachable at the READ tier — not another admin-only escape hatch", () => {
-  const pulse = orgToolDef("org_pulse");
-  assert.equal(pulse.access, "read", "an ordinary agent must be able to ask what needs attention");
-  assert.equal(pulse.desk, undefined, "always-on: `ops` has been in READS since the first protocol");
-  // The failure mode the description must pre-empt: reporting "nothing needs
-  // attention" when the derivation actually failed.
-  assert.match(pulse.description, /pulse: null/);
-  assert.match(pulse.description, /do not report zero/);
-});
-
-test("huddle lifecycle is CLOSED: a room an agent can open is a room it can enter and shut", async () => {
-  const names = ORG_TOOLS.filter((t) => t.name.startsWith("org_huddle_")).map((t) => t.name).sort();
-  assert.deepEqual(names, ["org_huddle_end", "org_huddle_join", "org_huddle_start"]);
-  for (const n of names) {
-    const def = orgToolDef(n);
-    assert.equal(def.desk, undefined, `${n} is always-on (the base calling family predates the desks)`);
-    assert.equal(def.access, "write");
-    assert.ok(def.binding.method.startsWith("calling."), `${n} rides the calling family`);
-  }
-  const fetchImpl = fakeFetch({ ok: true, result: { callId: "call_1", endedAt: "2026-08-12T10:00:00.000Z" } });
-  const frame = await executeOrgTool("org_huddle_end", { callId: "call_1" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, true);
-  assert.equal(fetchImpl.calls[0].url, "https://org.example/api/v1/calling.end");
-  assert.deepEqual(JSON.parse(fetchImpl.calls[0].init.body), { callId: "call_1" });
-  // CONFLICT means "already closed", not "you failed" — the description must
-  // say so, or a model retries a call it successfully ended.
-  assert.match(orgToolDef("org_huddle_end").description, /CONFLICT/);
-});
-
-test("org_directory advertises the derived presence lane (a field nobody is told about is unreachable)", () => {
-  const dir = orgToolDef("org_directory");
-  for (const needle of ["presence", "lane", "detail", "indisposed"]) {
-    assert.match(dir.description, new RegExp(needle), `org_directory names ${needle}`);
-  }
-  // The two honest-reading rules: a human seat's null is not "offline", and the
-  // raw client-stamped `status.ts` is not the dot.
-  assert.match(dir.description, /presence: null/);
-  assert.match(dir.description, /client-stamped/);
-});
-
-test("memory_recall: the SDK seat gets the same memory the chat lane reasons off", async () => {
-  const recall = orgToolDef("memory_recall");
-  assert.equal(recall.access, "read", "recall is read-only — it must not need a write tier");
-  assert.equal(recall.binding.method, "memory.recall");
-  // knowledge.search is a NARROWED PROJECTION of the same index; if the model is
-  // not told that, it keeps reaching for the smaller one out of habit.
-  assert.match(orgToolDef("knowledge_search").description, /memory_recall/);
-  // The two contracts a model gets wrong without being told: the entity pin is
-  // a PAIR, and an empty index is a fact, not a failure to retry.
-  assert.match(recall.description, /TOGETHER/);
-  assert.match(recall.description, /found:false/);
-
-  const fetchImpl = fakeFetch({ ok: true, result: { found: true, items: [{ id: "m1" }] } });
-  const frame = await executeOrgTool(
-    "memory_recall",
-    { query: "what did we decide about pricing", scope: "self", depth: "specific", k: 5 },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
-  );
-  assert.equal(frame.ok, true);
-  assert.equal(fetchImpl.calls[0].url, "https://org.example/api/v1/memory.recall");
-  assert.deepEqual(JSON.parse(fetchImpl.calls[0].init.body), {
-    query: "what did we decide about pricing", scope: "self", depth: "specific", k: 5,
-  });
-  // A read carries no dispatcher idempotency key.
-  assert.equal(fetchImpl.calls[0].init.headers["x-idempotency-key"], undefined);
-});
-
-test("email_triage exposes every facet the server accepts (mark-unread-from, muted, done)", () => {
-  const triage = orgToolDef("email_triage");
-  const props = Object.keys(triage.input_schema.properties).sort();
-  assert.deepEqual(props, [
-    "assigneeMemberId", "category", "done", "muted", "priority",
-    "read", "starred", "tags", "threadId", "unreadFromMessageId",
-  ], "the schema matches email.triage's real param set — an undocumented param is an unreachable one");
-  // The exclusivity rules are the server's; a model that does not know them
-  // burns a turn on a BAD_REQUEST it cannot diagnose.
-  assert.match(triage.description, /mutually exclusive/);
-  assert.match(triage.description, /one-verb-per-call/);
-});
-
-test("org_events_tail: cursor + clamped limit ride the query string", async () => {
-  const fetchImpl = fakeFetch({ events: [] });
-  await executeOrgTool("org_events_tail", { cursor: 7, limit: 9999 }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/events\?cursor=7&limit=500$/, "limit clamped to 500");
-});
-
-test("approval_wait: requires approvalId; dispatches the bounded long-poll", async () => {
-  const missing = await executeOrgTool("approval_wait", {}, { orgConfig: CFG, agentRoot: "/tmp/none" });
-  assert.equal(missing.error.code, "BAD_REQUEST");
-  const fetchImpl = fakeFetch({ id: "a1", status: "approved" });
-  const frame = await executeOrgTool("approval_wait", { approvalId: "a1" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, true);
-  assert.match(fetchImpl.calls[0].url, /approval\.wait\?id=a1&timeoutMs=55000/);
-});
-
-// ── executor: send-gate parity (§1.5a) ─────────────────────────────────────
-
-test("messaging_send: screened through the send-gate, idempotencyId auto-minted", async () => {
-  const screened = [];
-  const fetchImpl = fakeFetch({ ok: true, result: { messageId: "m1" } });
-  const frame = await executeOrgTool(
-    "messaging_send",
-    { channelId: "C9", body: "hello org" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (o) => { screened.push(o); return { allow: true }; } },
-  );
-  assert.equal(frame.ok, true);
-  assert.equal(screened.length, 1, "screenOutbound ran");
-  assert.equal(screened[0].recipient, "C9");
-  assert.equal(screened[0].text, "hello org");
-  const body = JSON.parse(fetchImpl.calls[0].init.body);
-  // hq's sendMessageSchemaV1 REQUIRES `idempotencyId`. Minting `clientMsgId`
-  // (the column name, not the wire name) 400'd every message this plane sent.
-  assert.ok(body.idempotencyId && body.idempotencyId.length >= 8, "idempotencyId auto-minted");
-  assert.equal(body.clientMsgId, undefined, "the column name is NOT the wire name");
-  assert.ok(fetchImpl.calls[0].init.headers["x-idempotency-key"], "dispatcher idempotency key present");
-});
-
-test("messaging_send: a vetoing gate blocks BEFORE any network", async () => {
-  const fetchImpl = fakeFetch();
-  const frame = await executeOrgTool(
-    "messaging_send",
-    { channelId: "C9", body: "As an AI I love this" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async () => ({ allow: false, reason: "banned-phrase" }) },
-  );
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "FORBIDDEN_SCOPE");
-  assert.match(frame.error.message, /banned-phrase/);
-  assert.equal(fetchImpl.calls.length, 0, "blocked before dispatch");
-});
-
-test("a THROWING gate fails open with a counted diagnostic (adapter parity)", async () => {
-  const counted = [];
-  const fetchImpl = fakeFetch({ ok: true, result: {} });
-  const frame = await executeOrgTool(
-    "messaging_send",
-    { channelId: "C9", body: "hi" },
-    {
-      orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl,
-      screenImpl: async () => { throw new Error("gate exploded"); },
-      bumpImpl: (name, attrs) => counted.push({ name, attrs }),
-    },
-  );
-  assert.equal(frame.ok, true, "fail-open");
-  assert.equal(counted[0].name, "channel.send_gate.fail_open");
-});
-
-// ── executor: escape hatches ───────────────────────────────────────────────
-
-test("org_rpc: unknown method rejected against the protocol table, NO network", async () => {
-  const fetchImpl = fakeFetch();
-  const frame = await executeOrgTool("org_rpc", { method: "nope.nothing" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "NOT_FOUND");
-  assert.equal(fetchImpl.calls.length, 0, "validated before any network");
-});
-
-test("org_rpc: escape-hatch parity — messaging.send through org_rpc is ALSO screened", async () => {
-  const screened = [];
-  const fetchImpl = fakeFetch({ ok: true, result: {} });
-  await executeOrgTool(
-    "org_rpc",
-    { method: "messaging.send", params: { channelId: "C2", body: "raw lane" } },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (o) => { screened.push(o); return { allow: true }; } },
-  );
-  assert.equal(screened.length, 1, "escape hatch screened");
-  assert.match(screened[0].text, /raw lane/, "params blob screened");
-  // and a blocked verdict stops the dispatch
-  const fetch2 = fakeFetch();
-  const blocked = await executeOrgTool(
-    "org_rpc",
-    { method: "email.send", params: { to: ["x@y.z"], text: "leak" } },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: fetch2, screenImpl: async () => ({ allow: false, reason: "no" }) },
-  );
-  assert.equal(blocked.ok, false);
-  assert.equal(fetch2.calls.length, 0);
-});
-
-test("org_rpc: non-outbound method dispatches unscreened with optional idempotencyKey", async () => {
-  const screened = [];
-  const fetchImpl = fakeFetch({ ok: true, result: { got: 1 } });
-  const frame = await executeOrgTool(
-    "org_rpc",
-    { method: "member.get", params: { memberId: "m-1" }, idempotencyKey: "k-1" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (o) => { screened.push(o); return { allow: true }; } },
-  );
-  assert.equal(frame.ok, true);
-  assert.equal(screened.length, 0, "reads/non-outbound never screened");
-  assert.match(fetchImpl.calls[0].url, /member\.get$/);
-});
-
-test("org_read: validated against READS; query params encoded; unknown path rejected", async () => {
-  const fetchImpl = fakeFetch({ events: [] });
-  const frame = await executeOrgTool("org_read", { path: "events", query: { cursor: 3, limit: 10 } }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, true);
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/events\?cursor=3&limit=10$/);
-  const bad = await executeOrgTool("org_read", { path: "not-a-read" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(bad.error.code, "NOT_FOUND");
-  assert.equal(fetchImpl.calls.length, 1, "unknown path never dispatched");
-});
-
-// ── executor: email tools ──────────────────────────────────────────────────
-
-test("email_send: idempotencyId auto-minted; screened; rides email.send", async () => {
-  const screened = [];
-  const fetchImpl = fakeFetch({ ok: true, result: { status: "queued", messageId: "e1" } });
-  const frame = await executeOrgTool(
-    "email_send",
-    { to: ["a@ext.com"], subject: "Hi", text: "Body" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (o) => { screened.push(o); return { allow: true }; } },
-  );
-  assert.equal(frame.ok, true);
-  assert.equal(screened[0].recipient, "a@ext.com");
-  assert.match(screened[0].text, /Subject: Hi/);
-  const body = JSON.parse(fetchImpl.calls[0].init.body);
-  assert.ok(body.idempotencyId && body.idempotencyId.length >= 8, "idempotencyId auto-minted");
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/email\.send$/);
-});
-
-test("email tools degrade to NOT_FOUND when the family is gated off (pre-sync install)", async () => {
-  const fetchImpl = fakeFetch();
-  const frame = await executeOrgTool("email_inbox", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, emailAvailable: false });
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "NOT_FOUND");
-  assert.match(frame.error.message, /upgrade/i);
-  assert.equal(fetchImpl.calls.length, 0);
-});
-
-// ── executor: artifact tools ───────────────────────────────────────────────
-
-test("artifact_create: clientMsgId auto-minted; unscreened (in-thread, not outbound); rides artifact.create", async () => {
-  const screened = [];
-  const envelope = { genui: "v2", artifact: { class: "ops.status", version: 1, state: "complete", source: { kind: "native" } }, actions: [], root: { type: "card", tone: "neutral", blocks: [] } };
-  const fetchImpl = fakeFetch({ ok: true, result: { artifactId: "a1", messageId: "m1" } });
-  const frame = await executeOrgTool(
-    "artifact_create",
-    { channelId: "C1", envelope },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (o) => { screened.push(o); return { allow: true }; } },
-  );
-  assert.equal(frame.ok, true);
-  assert.deepEqual(frame.result, { artifactId: "a1", messageId: "m1" });
-  assert.equal(screened.length, 0, "artifact posts are in-thread — never send-gate screened");
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/artifact\.create$/);
-  const body = JSON.parse(fetchImpl.calls[0].init.body);
-  assert.ok(body.clientMsgId && body.clientMsgId.length >= 8, "clientMsgId auto-minted");
-  assert.deepEqual(body.envelope, envelope, "envelope posted verbatim");
-  assert.equal(fetchImpl.calls[0].init.headers["x-idempotency-key"], undefined, "sideEffecting:false — no dispatcher key; the service dedupes on clientMsgId");
-});
-
-test("artifact_act: idempotencyKey auto-minted when absent, caller's key preserved; held result is a NORMAL frame", async () => {
-  const fetchImpl = fakeFetch({ ok: true, result: { held: true, approvalId: "ap-1" } });
-  const frame = await executeOrgTool(
-    "artifact_act",
-    { artifactId: "a1", action: "approve" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
-  );
-  assert.equal(frame.ok, true, "approval-held is a result, not an error");
-  assert.equal(frame.result.held, true);
-  assert.equal(frame.result.approvalId, "ap-1");
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/artifact\.act$/);
-  const minted = JSON.parse(fetchImpl.calls[0].init.body);
-  assert.ok(minted.idempotencyKey && minted.idempotencyKey.length >= 8, "idempotencyKey auto-minted");
-  // A caller-supplied key (retry / post-approval re-invoke) rides through untouched.
-  await executeOrgTool(
-    "artifact_act",
-    { artifactId: "a1", action: "approve", idempotencyKey: "approve-a1" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
-  );
-  assert.equal(JSON.parse(fetchImpl.calls[1].init.body).idempotencyKey, "approve-a1");
-});
-
-test("artifact reads ride their rpc methods; tools degrade to NOT_FOUND when the family is gated off", async () => {
-  const fetchImpl = fakeFetch({ ok: true, result: { items: [] } });
-  await executeOrgTool("artifact_list", { channelId: "C1", state: "complete" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/artifact\.list$/);
-  await executeOrgTool("artifact_catalog", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.match(fetchImpl.calls[1].url, /\/api\/v1\/artifact\.catalog$/);
-  const gated = fakeFetch();
-  const frame = await executeOrgTool("artifact_get", { artifactId: "a1" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: gated, artifactAvailable: false });
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "NOT_FOUND");
-  assert.match(frame.error.message, /upgrade/i);
-  assert.equal(gated.calls.length, 0);
-});
-
-// ── executor: directory + design desks (2026-07) ───────────────────────────
-
-test("directory/design desks gate on their OWN probe, independently of the other desks", () => {
-  // One DESK_PROBES line lights a desk up on BOTH planes; a desk whose probe
-  // method is absent from the vendored protocol must not register.
-  assert.equal(deskFamilyAvailable("directory"), true, "vendored protocol carries directory.search");
-  assert.equal(deskFamilyAvailable("design"), true, "vendored protocol carries branding.getFoundation");
-  assert.equal(deskFamilyAvailable("nope"), false, "unknown desk → default-deny");
-  assert.equal(ORG_TOOLS.filter((t) => t.desk === "directory").length, 14);
-  assert.equal(ORG_TOOLS.filter((t) => t.desk === "design").length, 8);
-  // Neither desk smuggles an outbound lane in: no directory/design tool sends.
-  assert.equal(ORG_TOOLS.filter((t) => (t.desk === "directory" || t.desk === "design") && t.outbound).length, 0);
-});
-
-test("directory reads/writes ride their rpc methods; a side-effecting write carries a dispatcher key", async () => {
-  const fetchImpl = fakeFetch({ ok: true, result: { people: [] } });
-  const o = { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl };
-  await executeOrgTool("directory_search", { q: "hartmann" }, o);
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/directory\.search$/);
-  assert.deepEqual(JSON.parse(fetchImpl.calls[0].init.body), { q: "hartmann" });
-  assert.equal(fetchImpl.calls[0].init.headers["x-idempotency-key"], undefined, "sideEffecting:false read sends no key");
-
-  await executeOrgTool("directory_list_people", { relationship: "client", sort: "touch" }, o);
-  assert.match(fetchImpl.calls[1].url, /\/api\/v1\/directory\.listPeople$/);
-
-  await executeOrgTool(
-    "directory_propose_capture",
-    { kind: "PERSON", payload: { person: { displayName: "Dr. Lena Hartmann" } }, source: "MAIL", sourceFingerprint: "sig:abc" },
-    o,
-  );
-  assert.match(fetchImpl.calls[2].url, /\/api\/v1\/directory\.proposeCapture$/);
-  assert.ok(
-    fetchImpl.calls[2].init.headers["x-idempotency-key"],
-    "sideEffecting write gets a fresh dispatcher key",
-  );
-  assert.equal(JSON.parse(fetchImpl.calls[2].init.body).sourceFingerprint, "sig:abc");
-});
-
-test("design tools ride branding.*; the costed quote call posts budgetCents:0 verbatim", async () => {
-  const fetchImpl = fakeFetch({ ok: true, result: { slots: [], costCents: 0 } });
-  const o = { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl };
-  await executeOrgTool("design_foundation", { historyLimit: 5 }, o);
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/branding\.getFoundation$/);
-  await executeOrgTool("design_voice", {}, o);
-  assert.match(fetchImpl.calls[1].url, /\/api\/v1\/branding\.getVoice$/);
-  await executeOrgTool("design_generate_image", { budgetCents: 0 }, o);
-  assert.match(fetchImpl.calls[2].url, /\/api\/v1\/branding\.generateImage$/);
-  assert.equal(JSON.parse(fetchImpl.calls[2].init.body).budgetCents, 0, "0 is the QUOTE call, not a falsy drop");
-});
-
-test("design_rewrite_in_voice produces copy and is NEVER send-gate screened", async () => {
-  // It returns a rewrite; it sends nothing. Whatever the caller does with the
-  // result is screened at the send verb, not here.
-  const screened = [];
-  const fetchImpl = fakeFetch({ ok: true, result: { text: "Rewritten.", costCents: 3 } });
-  const frame = await executeOrgTool(
-    "design_rewrite_in_voice",
-    { text: "we are excited to announce" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (x) => { screened.push(x); return { allow: true }; } },
-  );
-  assert.equal(frame.ok, true);
-  assert.equal(screened.length, 0);
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/branding\.rewriteInVoice$/);
-});
-
-test("directory/design tools degrade to NOT_FOUND when their desk is gated off (pre-sync install)", async () => {
-  for (const name of ["directory_search", "design_foundation"]) {
-    const gated = fakeFetch();
-    const frame = await executeOrgTool(name, { q: "x" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: gated, desksAvailable: false });
-    assert.equal(frame.ok, false, `${name} gated`);
-    assert.equal(frame.error.code, "NOT_FOUND");
-    assert.match(frame.error.message, /upgrade/i);
-    assert.equal(gated.calls.length, 0, `${name} never dispatched`);
-  }
-});
-
-// ── executor: calls desk (call working sessions, 2026-08) ──────────────────
-
-test("calls desk gates on calling.appShareStart; five tools, one outbound verb", () => {
-  assert.equal(deskFamilyAvailable("calls"), true, "vendored protocol carries calling.appShareStart");
-  const calls = ORG_TOOLS.filter((t) => t.desk === "calls");
-  assert.equal(calls.length, 5);
-  // The share-step verb is the block's ONE outbound lane: its highlight notes
-  // and typed text are read by every human on the call.
-  assert.deepEqual(calls.filter((t) => t.outbound).map((t) => t.name), ["org_call_share_step"]);
-  assert.deepEqual(
-    calls.filter((t) => t.access === "read").map((t) => t.name).sort(),
-    ["org_call_events", "org_call_visual_context"],
-  );
-});
-
-test("org_call_share_start/end ride their rpc methods with a fresh dispatcher key", async () => {
-  const fetchImpl = fakeFetch({ ok: true, result: { sessionId: "s1" } });
-  const o = { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl };
-  const frame = await executeOrgTool(
-    "org_call_share_start",
-    { callId: "call-1", surface: { kind: "doc", ref: "f-1", title: "Q3 plan" } },
-    o,
-  );
-  assert.equal(frame.ok, true);
-  assert.equal(frame.result.sessionId, "s1");
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/calling\.appShareStart$/);
-  assert.ok(fetchImpl.calls[0].init.headers["x-idempotency-key"], "sideEffecting write gets a fresh dispatcher key");
-  assert.deepEqual(JSON.parse(fetchImpl.calls[0].init.body).surface, { kind: "doc", ref: "f-1", title: "Q3 plan" });
-
-  await executeOrgTool("org_call_share_end", { callId: "call-1", sessionId: "s1" }, o);
-  assert.match(fetchImpl.calls[1].url, /\/api\/v1\/calling\.appShareEnd$/);
-});
-
-test("org_call_share_step: screened through the send-gate (notes + typed text), then rides calling.appShareAct", async () => {
-  const screened = [];
-  const fetchImpl = fakeFetch({ ok: true, result: { seq: 4 } });
-  const steps = [
-    { k: "scroll", anchor: "block:3" },
-    { k: "highlight", anchor: "block:3", note: "revenue line" },
-    { k: "type", anchor: "block:4", text: "Draft summary" },
-  ];
-  const frame = await executeOrgTool(
-    "org_call_share_step",
-    { callId: "call-1", sessionId: "s1", steps },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (x) => { screened.push(x); return { allow: true }; } },
-  );
-  assert.equal(frame.ok, true);
-  assert.equal(screened.length, 1, "screenOutbound ran");
-  assert.equal(screened[0].recipient, "call-1");
-  assert.match(screened[0].text, /revenue line/);
-  assert.match(screened[0].text, /Draft summary/);
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/calling\.appShareAct$/);
-  assert.deepEqual(JSON.parse(fetchImpl.calls[0].init.body).steps, steps);
-
-  // A vetoing gate blocks BEFORE any network — messaging_send parity.
-  const fetch2 = fakeFetch();
-  const blocked = await executeOrgTool(
-    "org_call_share_step",
-    { callId: "call-1", sessionId: "s1", steps: [{ k: "highlight", anchor: "block:1", note: "As an AI" }] },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: fetch2, screenImpl: async () => ({ allow: false, reason: "banned-phrase" }) },
-  );
-  assert.equal(blocked.ok, false);
-  assert.equal(blocked.error.code, "FORBIDDEN_SCOPE");
-  assert.equal(fetch2.calls.length, 0, "blocked before dispatch");
-});
-
-test("calls reads ride their rpc methods without a dispatcher key", async () => {
-  const fetchImpl = fakeFetch({ ok: true, result: { events: [] } });
-  const o = { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl };
-  await executeOrgTool("org_call_visual_context", { callId: "call-1", limit: 10 }, o);
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/calling\.getVisualContext$/);
-  assert.equal(fetchImpl.calls[0].init.headers["x-idempotency-key"], undefined, "sideEffecting:false read sends no key");
-  await executeOrgTool("org_call_events", { callId: "call-1" }, o);
-  assert.match(fetchImpl.calls[1].url, /\/api\/v1\/calling\.getCallEvents$/);
-});
-
-test("calls tools degrade to NOT_FOUND when the desk is gated off (pre-sync install)", async () => {
-  const gated = fakeFetch();
-  const frame = await executeOrgTool(
-    "org_call_share_start",
-    { callId: "call-1", surface: { kind: "doc", ref: "f-1" } },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: gated, desksAvailable: false },
-  );
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "NOT_FOUND");
-  assert.match(frame.error.message, /upgrade/i);
-  assert.equal(gated.calls.length, 0, "never dispatched");
-});
-
-// ── executor: org_whoami ───────────────────────────────────────────────────
-
-test("org_whoami: unenrolled → config summary with member:null + note, never an error", async () => {
-  const frame = await executeOrgTool("org_whoami", {}, { orgConfig: {}, agentRoot: "/tmp/none" });
-  assert.equal(frame.ok, true);
-  assert.equal(frame.result.member, null);
-  assert.equal(frame.result.tokenPresent, false);
-  assert.match(frame.result.note, /setup --only org|COHORT_API_TOKEN|COHORT_ORG_ID/);
-});
-
-test("org_whoami: resolves the member via the org-data whoami lane; token never in the result", async () => {
-  const fetchImpl = fakeFetch({ slug: "astra", displayName: "Astra", agentEmail: "astra@agents.example" });
-  const frame = await executeOrgTool("org_whoami", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, true);
-  assert.equal(frame.result.member.slug, "astra");
-  assert.equal(frame.result.tokenPresent, true);
-  assert.equal(frame.result.protocolVersion, PROTOCOL_VERSION);
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/org\/whoami\?orgId=acme/);
-  assert.ok(!JSON.stringify(frame).includes("nlk_secret"), "token never surfaces");
-});
-
-test("org_whoami: unresolvable member degrades to summary + hint note (no error frame)", async () => {
-  const fetchImpl = fakeFetch({ error: { code: "NOT_FOUND", message: "ambiguous" } }, { status: 404, ok: false });
-  const frame = await executeOrgTool("org_whoami", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, true);
-  assert.equal(frame.result.member, null);
-  assert.match(frame.result.note, /COHORT_AGENT_ID/);
-});
-
-test("org_whoami: COHORT_AGENT_ID hint routes to the direct member GET", async () => {
-  const fetchImpl = fakeFetch({ slug: "astra", displayName: "Astra" });
-  const frame = await executeOrgTool("org_whoami", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, env: { COHORT_AGENT_ID: "astra" } });
-  assert.equal(frame.ok, true);
-  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/org\/members\/astra\?orgId=acme/);
-});
-
-// ── engage_colleagues: the judged path through the tool plane ──────────────
-
-test("engage_colleagues returns an OK frame when it decides NOBODY needs involving", async () => {
-  // "Nobody needed involving" is an answer. Returning it as an error would teach
-  // the model to retry until it manages to interrupt somebody.
-  const f = fakeFetch({ ok: true, result: { members: [] } });
-  const res = await executeOrgTool(
-    "engage_colleagues",
-    { id: "W-1", title: "Refresh the digest", state: "in_progress", interestedParties: ["M-2"] },
-    { orgConfig: CFG, agentRoot: "/tmp/engage-tool-test", fetchImpl: f, env: {} },
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.result.engaged, false);
-  assert.equal(res.result.reasonCode, "self_contained");
-  assert.deepEqual(res.result.consideredNotEngaged, ["M-2"]);
-  assert.ok(res.result.why.length, "the reasoning comes back to the model, not just the verdict");
-  assert.ok(
-    !f.calls.some((c) => /messaging\.send/.test(c.url)),
-    "a self-contained decision must not put a message on the wire",
-  );
-});
-
-test("engage_colleagues refuses an unidentified piece of work rather than guessing", async () => {
-  const res = await executeOrgTool(
-    "engage_colleagues",
-    { title: "no id" },
-    { orgConfig: CFG, agentRoot: "/tmp/engage-tool-test", fetchImpl: fakeFetch(), env: {} },
-  );
-  assert.equal(res.ok, false);
-  assert.equal(res.error.code, "BAD_REQUEST");
-});
-
-test("messaging_send passes mentions straight through to the wire", async () => {
-  const f = fakeFetch({ ok: true, result: { id: "m1" } });
-  await executeOrgTool(
-    "messaging_send",
-    { channelId: "C-1", body: "Need a decision here.", mentions: ["M-2"] },
-    { orgConfig: CFG, agentRoot: "/tmp", fetchImpl: f, env: {}, screenImpl: async () => ({ allow: true }) },
-  );
-  const body = JSON.parse(f.calls[0].init.body);
-  // The model writes the obvious thing — an array of id strings — and the param
-  // contract coerces it at the one chokepoint. Sending the string form verbatim
-  // fails hq's zod and 400s the WHOLE message, tags and body alike.
-  assert.deepEqual(body.mentions, [{ memberId: "M-2" }]);
-});
-
-// ── speaking: messaging_send_voice_note ────────────────────────────────────
-//
-// The verb that closes "I can't send audio voice notes". hq could always
-// synthesise an agent's voice note, but only as a REFLEX answering a human's
-// spoken note in kind — asked in text, an agent had nothing to call.
-//
-// What is pinned here is the composition: record, then post the recording as an
-// ORDINARY message attachment. There is no audio-only send path, so the post
-// leg carries the same ACL, audit and dedup as any typed message; and a refused
-// recording must never be followed by a post that implies one was made.
-
-test("messaging_send_voice_note: records, then posts the file as an ordinary attachment", async () => {
-  let n = 0;
-  const calls = [];
-  const fetchImpl = async (url, init) => {
-    calls.push({ url: String(url), body: JSON.parse(init.body) });
-    n += 1;
-    return {
-      ok: true,
-      status: 200,
-      headers: { get: () => undefined },
-      json: async () =>
-        n === 1
-          ? { ok: true, result: { fileId: "file_v1", durationMs: 4200 } }
-          : { ok: true, result: { messageId: "m1" } },
-    };
-  };
-  const frame = await executeOrgTool(
-    "messaging_send_voice_note",
-    { channelId: "C1", text: "Shipping Friday." },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async () => ({ allow: true }) },
-  );
-  assert.equal(frame.ok, true);
-  assert.match(calls[0].url, /messaging\.synthesizeVoiceNote$/);
-  assert.equal(calls[0].body.text, "Shipping Friday.");
-  assert.match(calls[1].url, /messaging\.send$/);
-  assert.deepEqual(calls[1].body.attachments, [{ fileId: "file_v1" }]);
-  // The written body defaults to the spoken words, never an empty message.
-  assert.equal(calls[1].body.body, "Shipping Friday.");
-  assert.ok(calls[1].body.idempotencyId, "the post is dedup-keyed like any send");
-  assert.equal(frame.result.fileId, "file_v1");
-});
-
-test("messaging_send_voice_note: a refused recording is NOT followed by a post", async () => {
-  const calls = [];
-  const fetchImpl = async (url, init) => {
-    calls.push(String(url));
-    return {
-      ok: false,
-      status: 403,
-      headers: { get: () => undefined },
-      json: async () => ({
-        ok: false,
-        error: { code: "FORBIDDEN_SCOPE", message: "voice note not recorded (no-key): ..." },
-      }),
-    };
-  };
-  const frame = await executeOrgTool(
-    "messaging_send_voice_note",
-    { channelId: "C1", text: "hi" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async () => ({ allow: true }) },
-  );
-  assert.equal(frame.ok, false);
-  assert.match(frame.error.message, /no-key/);
-  assert.equal(calls.length, 1, "no post claiming a voice note that was never recorded");
-});
-
-test("messaging_send_voice_note: the send-gate screens the SPOKEN words before synthesis", async () => {
-  const fetchImpl = fakeFetch();
-  const seen = [];
-  const frame = await executeOrgTool(
-    "messaging_send_voice_note",
-    { channelId: "C1", text: "the secret is hunter2", body: "see note" },
-    {
-      orgConfig: CFG,
-      agentRoot: "/tmp/none",
-      fetchImpl,
-      screenImpl: async (args) => {
-        seen.push(args);
-        return args.text.includes("hunter2") ? { allow: false, reason: "credential" } : { allow: true };
-      },
-    },
-  );
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "FORBIDDEN_SCOPE");
-  // The gate sees the PROSE — the spoken words and the written body — not a
-  // stringified params blob. A gate judging JSON would pass sentences it never
-  // actually read.
-  assert.equal(seen[0].text, "the secret is hunter2\nsee note");
-  assert.equal(seen[0].recipient, "C1");
-  // Blocked BEFORE the network: audio is the hardest content to retract, and a
-  // blocked note must not cost a billable synthesis either.
-  assert.equal(fetchImpl.calls.length, 0);
-});
-
-test("messaging_send_voice_note: channelId and text are both required", async () => {
-  const fetchImpl = fakeFetch();
-  const frame = await executeOrgTool(
-    "messaging_send_voice_note",
-    { channelId: "C1" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async () => ({ allow: true }) },
-  );
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "BAD_REQUEST");
-  assert.equal(fetchImpl.calls.length, 0);
-});
-
-// ── mandate / sub-agent registry / preferences (2026-08 parity delta) ───────
-
-test("mandate tools ride their mandate.* methods and POST the params verbatim", async () => {
-  const seen = [];
-  const fetchImpl = async (url, init) => {
-    seen.push({ url: String(url), body: JSON.parse(init.body) });
-    return { ok: true, status: 200, headers: { get: () => undefined }, json: async () => ({ ok: true, result: {} }) };
-  };
-  fetchImpl.calls = seen;
-  const o = { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl };
-  await executeOrgTool("mandate_read", {}, o);
-  await executeOrgTool("mandate_objectives", { state: "active", includeRetired: false }, o);
-  await executeOrgTool("mandate_kpi_series", { objectiveId: "ob-1", limit: 20 }, o);
-  await executeOrgTool("mandate_propose_objective", { key: "pipeline-coverage", text: "3x cover", target: 3 }, o);
-  await executeOrgTool(
-    "mandate_record_kpi_sample",
-    { objectiveId: "ob-1", value: 2.4, window: "2026-W33", evidence: { method: "crm.listDeals" } },
-    o,
-  );
-  assert.deepEqual(seen.map((c) => c.url), [
-    "https://org.example/api/v1/mandate.get",
-    "https://org.example/api/v1/mandate.tree",
-    "https://org.example/api/v1/mandate.series",
-    "https://org.example/api/v1/mandate.propose",
-    "https://org.example/api/v1/mandate.sample",
-  ]);
-  // Pass-through, byte for byte: hq's mandate schemas read these names, and the
-  // evidence OBJECT is what the server's honesty gate inspects — flattening it
-  // to a string here would silently downgrade every sample to `llm`.
-  assert.deepEqual(seen[3].body, { key: "pipeline-coverage", text: "3x cover", target: 3 });
-  assert.deepEqual(seen[4].body.evidence, { method: "crm.listDeals" });
-});
-
-test("the mandate belt stops at PROPOSE — no adopt/retire tool exists at any tier", () => {
-  const names = new Set(ORG_TOOLS.map((t) => t.name));
-  for (const forbidden of ["mandate_adopt", "mandate_retire"]) {
-    assert.equal(names.has(forbidden), false, `${forbidden} must not exist`);
-  }
-  // The absence is structural, not incidental: no curated tool may bind a
-  // method whose scope is missing from DEFAULT_AGENT_SCOPES, because a tool the
-  // seat's own credential can never execute is a promise the model will make
-  // and fail to keep. `mandate.write` is the anti-Goodhart scope.
-  const bound = ORG_TOOLS.filter((t) => t.binding.kind === "rpc").map((t) => t.binding.method);
-  for (const m of bound) {
-    assert.notEqual(methodDef(m).scope, "mandate.write", `${m} needs mandate.write — not an agent's to hold`);
-  }
-});
-
-test("subagent tools are READS ONLY — the writes stay with the outbox-owning client", () => {
-  const subagentTools = ORG_TOOLS.filter(
-    (t) => t.binding.kind === "rpc" && t.binding.method.startsWith("subagent."),
-  );
-  assert.deepEqual(
-    subagentTools.map((t) => t.name).sort(),
-    ["subagent_get", "subagent_list", "subagent_resolve"],
-  );
-  for (const t of subagentTools) {
-    assert.equal(t.access, "read", `${t.name} is a read`);
-    assert.equal(methodDef(t.binding.method).sideEffecting, false, `${t.binding.method} mutates nothing`);
-  }
-});
-
-test("preference tools ship as a PAIR — a write-only memory is not parity", async () => {
-  const names = ORG_TOOLS.filter(
-    (t) => t.binding.kind === "rpc" && t.binding.method.startsWith("preference."),
-  );
-  assert.deepEqual(names.map((t) => t.name).sort(), ["preference_list", "preference_remember"]);
-  assert.equal(orgToolDef("preference_list").access, "read");
-  assert.equal(orgToolDef("preference_remember").access, "write");
-  // `why` is required in the SCHEMA, not just server-side: the evidence rule
-  // has to reach the model, or it learns the rule by BAD_REQUEST.
-  assert.ok(orgToolDef("preference_remember").input_schema.required.includes("why"));
-
-  const fetchImpl = fakeFetch({ ok: true, result: { id: "pref-1" } });
-  const frame = await executeOrgTool(
-    "preference_remember",
-    { domain: "travel", key: "seat", value: "aisle", why: "said so in #travel" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
-  );
-  assert.equal(frame.ok, true);
-  assert.equal(fetchImpl.calls[0].url, "https://org.example/api/v1/preference.upsert");
-  // sideEffecting:true at the dispatcher → a fresh header key per invocation.
-  assert.ok(fetchImpl.calls[0].init.headers["x-idempotency-key"], "dispatcher key attached");
-});
-
-// ── the access mechanism, TABLE-WIDE ───────────────────────────────────────
-//
-// The per-delta assertion below ("the new tools reach the tiers that need
-// them") lists ten names by hand, so it polices the tools whose author
-// remembered to add them and nothing else — every family that ships after it is
-// unguarded by default. These three assertions are the table-wide version:
-// they iterate ORG_TOOLS, so a capability cannot be parked at the CEO-only tier
-// or given a tier its protocol scope contradicts without one of them going red,
-// whether or not anyone updates a list.
-
-test("ACCESS MECHANISM: `admin` is a CLOSED set of two escape hatches, not a parking space", () => {
-  const admins = ORG_TOOLS.filter((t) => t.access === "admin").map((t) => t.name).sort();
-  assert.deepEqual(
-    admins,
-    [...ADMIN_TOOLS].sort(),
-    "only org_rpc/org_read may be admin-tier — anything else is a CAPABILITY, and a capability " +
-      "at admin is CEO-only, i.e. exactly as unreachable for a leadership or default agent as " +
-      "the org_rpc route a curated tool exists to replace",
-  );
-  for (const name of ADMIN_TOOLS) {
-    const def = orgToolDef(name);
-    assert.ok(def, `${name} is in the table`);
-    assert.equal(def.access, "admin", `${name} is the escape hatch it claims to be`);
-    // Both hatches are `local`: they take a method/path NAME and validate it
-    // against the frozen table before any I/O. A desk verb can never be one.
-    assert.equal(def.binding.kind, "local", `${name} is a console, not a capability`);
-  }
-});
-
-test("ACCESS MECHANISM: every rpc-bound tool's tier is DERIVED from its protocol scope", () => {
-  // hq gates on SCOPE, so the native clamp has to mirror the scope lane or it
-  // either withholds a tool hq would have allowed or offers one hq will refuse.
-  // Note the rule this is NOT: `sideEffecting ? "write" : "read"` is wrong for
-  // seven tools already in the table — knowledge.search, directory.ask and the
-  // three branding renders/exports are AUDITED READS (side-effecting, `.read`
-  // scope, runnable by a VIEWER seat), and artifact.create/act are the mirror
-  // case. Deriving from sideEffecting would demote all five audited reads out
-  // of the lookup set every tier gets.
-  let checked = 0;
-  for (const t of ORG_TOOLS) {
-    if (!t.binding || t.binding.kind !== "rpc") continue;
-    checked += 1;
-    const want = expectedAccessFor(t.binding.method);
-    assert.ok(want, `${t.name} binds a vendored method`);
-    assert.equal(
-      t.access,
-      want,
-      `${t.name} (${t.binding.method}, scope ${methodDef(t.binding.method).scope}) must be access:"${want}"`,
-    );
-  }
-  assert.ok(checked >= 120, "the whole rpc-bound belt was checked, not a sample");
-});
-
-test("ACCESS MECHANISM: no tool can fall out of every tier — the partition is exhaustive", () => {
-  // Exact string equality used to bucket the table, so a missing or mis-cased
-  // `access` matched NO bucket and reached NO native access level, while the
-  // MCP plane kept publishing it. normalizeToolAccess is the tool-side twin of
-  // normalizeAccessLevel: it normalises casing and sends a genuinely
-  // unrecognised tier to the most-restricted bucket, loudly.
-  for (const t of ORG_TOOLS) {
-    assert.ok(
-      ["read", "write", "admin"].includes(t.access),
-      `${t.name} declares a known tier verbatim (the normaliser is a safety net, not a licence)`,
-    );
-    const warnings = [];
-    assert.equal(normalizeToolAccess(t.access, t.name, (m) => warnings.push(m)), t.access);
-    assert.equal(warnings.length, 0, `${t.name} normalises silently`);
-  }
-  // And the safety net itself: a typo fails CLOSED and NOISY, never invisible.
-  const warnings = [];
-  assert.equal(normalizeToolAccess("Read", "x_tool", (m) => warnings.push(m)), "read", "casing is forgiven");
-  assert.equal(normalizeToolAccess(undefined, "x_tool", (m) => warnings.push(m)), "admin", "a missing tier fails closed");
-  assert.equal(warnings.length, 1, "and says so out loud");
-  assert.match(warnings[0], /x_tool/);
-});
-
-test("the new tools reach the tiers that need them — reads everywhere, no new admin surface", () => {
-  const added = [
-    "mandate_read", "mandate_objectives", "mandate_kpi_series",
-    "mandate_propose_objective", "mandate_record_kpi_sample",
-    "subagent_list", "subagent_get", "subagent_resolve",
-    "preference_remember", "preference_list",
-  ];
-  for (const n of added) {
-    const def = orgToolDef(n);
-    assert.ok(def, `${n} is in the table`);
-    // The whole point of the delta: NONE of these may land at access:"admin",
-    // which is the CEO-only escape-hatch tier. A capability parked there is
-    // exactly as unreachable as the org_rpc route it was meant to replace.
-    assert.notEqual(def.access, "admin", `${n} must not be admin-tier`);
-    assert.equal(def.outbound, undefined, `${n} sends nothing a human reads as a message`);
-  }
-  assert.equal(
-    added.filter((n) => orgToolDef(n).access === "read").length,
-    7,
-    "seven reads (3 mandate, 3 subagent, 1 preference) land in EVERY tier's lookup set",
-  );
-});
-
-test("the new tools FAIL CLOSED with no credential — refusal, never a silent success", async () => {
-  const fetchImpl = fakeFetch();
-  for (const n of ["mandate_read", "subagent_list", "preference_remember"]) {
-    const frame = await executeOrgTool(n, {}, { orgConfig: {}, agentRoot: "/tmp/none", fetchImpl });
-    assert.equal(frame.ok, false, `${n} refuses`);
-    assert.equal(frame.error.code, "UNAUTHORIZED");
-    assert.match(frame.error.message, /COHORT_API_TOKEN/);
-  }
-  assert.equal(fetchImpl.calls.length, 0, "nothing dispatched without a credential");
-});
-
-test("a 401/403 from hq surfaces VERBATIM on the new tools (a refusal is an answer)", async () => {
-  const denied = fakeFetch(
-    { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "resolving another member's sub-agents requires admin" } },
-    { ok: false, status: 403 },
-  );
-  const frame = await executeOrgTool(
-    "subagent_resolve",
-    { memberId: "someone-else" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: denied },
-  );
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "FORBIDDEN_SCOPE");
-  assert.match(frame.error.message, /admin/);
-
-  const unauth = fakeFetch({ ok: false, error: { code: "UNAUTHORIZED", message: "bad key" } }, { ok: false, status: 401 });
-  const f2 = await executeOrgTool("mandate_read", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: unauth });
-  assert.equal(f2.ok, false);
-  assert.equal(f2.error.code, "UNAUTHORIZED");
-});
-
-test("transport failure on a new tool fails open into an INTERNAL frame, never a throw", async () => {
-  const thrower = async () => { throw new Error("econnrefused"); };
-  const frame = await executeOrgTool(
-    "mandate_objectives",
-    {},
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: thrower },
-  );
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "INTERNAL");
-});
-
-// ── WP-M4: front-door tools (board_mine / board_track / session_status) ────
-
-test("board_mine: read access, GET /v1/board.mine, items normalised, [] when hq lacks the read (fail-open)", async () => {
-  const def = orgToolDef("board_mine");
-  assert.ok(def, "board_mine curated");
-  assert.equal(def.access, "read");
-  assert.equal(def.binding.kind, "local", "local so an hq without board.mine yet degrades to [] instead of a bare 404");
-  const fetchImpl = fakeFetch({ items: [{ itemId: "i1", title: "Deck", col: "doing" }] });
-  const frame = await executeOrgTool("board_mine", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(frame.ok, true);
-  assert.deepEqual(frame.result.items, [{ itemId: "i1", title: "Deck", col: "doing" }]);
-  assert.equal(frame.result.count, 1);
-  assert.match(fetchImpl.calls[0].url, /\/v1\/board\.mine$/);
-  assert.equal(fetchImpl.calls[0].init.method, "GET");
-  const gone = fakeFetch({ error: { code: "NOT_FOUND", message: "no such read" } }, { status: 404, ok: false });
-  const f2 = await executeOrgTool("board_mine", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: gone });
-  assert.equal(f2.ok, true, "fail-open: an older hq is an empty list, not an error the model must interpret");
-  assert.deepEqual(f2.result.items, []);
-  // No token → UNAUTHORIZED like every other network tool.
-  const noTok = await executeOrgTool("board_mine", {}, { orgConfig: { org: { cohort: { enabled: true, base: "https://org.example" } } }, agentRoot: "/tmp/none", fetchImpl });
-  assert.equal(noTok.ok, false);
-  assert.equal(noTok.error.code, "UNAUTHORIZED");
-});
-
-test("board_track: write access on board.track; title/why/stage pass through; whole ladder incl. accepted|done; bad stage rejected offline", async () => {
-  const def = orgToolDef("board_track");
-  assert.ok(def, "board_track curated");
-  assert.equal(def.access, "write");
-  assert.equal(def.binding.method, "board.track");
-  assert.deepEqual(def.input_schema.properties.stage.enum, ["accepted", "working", "blocked", "review", "done", "failed"]);
-  assert.ok(def.input_schema.properties.title, "title passthrough");
-  assert.ok(def.input_schema.properties.why, "why passthrough");
-  const fetchImpl = fakeFetch({ ok: true, result: { tracked: true, taskId: "t1", col: "todo", created: true } });
-  const frame = await executeOrgTool(
-    "board_track",
-    { channelId: "c1", messageId: "m1", stage: "accepted", title: "Build the deck", why: "asked in DM", note: "on it" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
-  );
-  assert.equal(frame.ok, true);
-  assert.equal(frame.result.taskId, "t1");
-  assert.match(fetchImpl.calls[0].url, /\/v1\/board\.track$/);
-  const body = JSON.parse(fetchImpl.calls[0].init.body);
-  assert.equal(body.stage, "accepted");
-  assert.equal(body.title, "Build the deck");
-  assert.equal(body.why, "asked in DM");
-  assert.equal(body.service, "cohort", "service defaults to cohort");
-  assert.equal(body.channelId, "c1");
-  assert.equal(body.messageId, "m1");
-  assert.equal(fetchImpl.calls[0].init.headers["x-idempotency-key"], "board.track:c1:m1:accepted", "stable per (ask, stage)");
-  const bad = fakeFetch();
-  const rej = await executeOrgTool("board_track", { channelId: "c1", messageId: "m1", stage: "later" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: bad });
-  assert.equal(rej.ok, false);
-  assert.equal(rej.error.code, "BAD_REQUEST");
-  assert.equal(bad.calls.length, 0, "validated before any network");
-});
-
-test("session_status: offline local read of state/session + state/org/board-mine; works with no token", async () => {
-  const def = orgToolDef("session_status");
-  assert.ok(def, "session_status curated");
-  assert.equal(def.access, "read");
-  assert.equal(def.binding.kind, "local");
-  const root = mkdtempSync(join(tmpdir(), "ts-session-"));
-  try {
-    mkdirSync(join(root, "state", "session", "handoffs"), { recursive: true });
-    mkdirSync(join(root, "state", "org"), { recursive: true });
-    writeFileSync(join(root, "state", "session", "heartbeat.json"), JSON.stringify({ pid: 1, name: "alex-main", sessionId: "s1", ts: Date.now() }));
-    writeFileSync(join(root, "state", "session", "peers.json"), JSON.stringify([{ name: "alex-deck", purpose: "board deck" }]));
-    writeFileSync(join(root, "state", "session", "handoffs", "t1.json"), "{}");
-    writeFileSync(join(root, "state", "org", "board-mine.json"), JSON.stringify({ items: [{ itemId: "i1" }, { itemId: "i2" }], fetchedAt: new Date().toISOString() }));
-    const fetchImpl = fakeFetch();
-    const frame = await executeOrgTool("session_status", {}, { orgConfig: { org: { cohort: { enabled: true, base: "https://org.example" } } }, agentRoot: root, fetchImpl });
-    assert.equal(frame.ok, true, "no token is fine — this never touches the network");
-    assert.equal(fetchImpl.calls.length, 0);
-    assert.equal(frame.result.live, true);
-    assert.equal(frame.result.name, "alex-main");
-    assert.equal(frame.result.peers[0].name, "alex-deck");
-    assert.equal(frame.result.handoffsOpen, 1);
-    assert.equal(frame.result.boardMineCount, 2);
-    assert.equal(typeof frame.result.summary, "string");
-    // An empty root is "absent", not an error.
-    const empty = await executeOrgTool("session_status", {}, { orgConfig: CFG, agentRoot: join(root, "nope"), fetchImpl });
-    assert.equal(empty.ok, true);
-    assert.equal(empty.result.state, "absent");
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("board_track: the model cannot override service or smuggle extra keys — only the schema's passthrough fields reach hq", async () => {
-  const fetchImpl = fakeFetch({ ok: true, result: { tracked: true, taskId: "t2", col: "doing" } });
-  const frame = await executeOrgTool(
-    "board_track",
-    { channelId: "c1", messageId: "m1", stage: "working", service: "slack", junk: "x", note: "halfway", priority: "P1", notify: ["u1"] },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
-  );
-  assert.equal(frame.ok, true);
-  const body = JSON.parse(fetchImpl.calls[0].init.body);
-  assert.equal(body.service, "cohort", "service is pinned, not model-supplied");
-  assert.equal(body.junk, undefined, "unknown keys are dropped");
-  assert.equal(body.note, "halfway");
-  assert.equal(body.priority, "P1");
-  assert.deepEqual(body.notify, ["u1"]);
-  assert.deepEqual(Object.keys(body).sort(), ["channelId", "messageId", "note", "notify", "priority", "service", "stage"]);
-});