@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/org/policy.test.mjs

@@ -1,237 +0,0 @@
-/**
- * policy.test.mjs — fetch + verify-signed policy bundle against the PINNED trust
- * root, cache it, isStale, and the policy_stale directive handler. A GOOD
- * signature applies + caches; a BAD/unsigned/wrong-signer bundle is QUARANTINED
- * (never cached). Real Ed25519 keypairs; injected fetchImpl; tmp cache dir.
- * Run: node --test lib/org/policy.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { createPublicKey } from "node:crypto";
-
-import { generateDeviceKey, signWith } from "./keys.mjs";
-import { canonicalize } from "./protocol.mjs";
-import {
-  verifyBundle,
-  readCachedBundle,
-  cacheBundle,
-  isStale,
-  fetchAndApply,
-  handlePolicyStale,
-  parseAllowedSigners,
-  DEFAULT_STALE_MS,
-} from "./policy.mjs";
-
-const BASE = "https://org.cohortapp.com";
-
-delete process.env.COHORT_API_TOKEN;
-delete process.env.COHORT_TOKEN;
-
-/** Build a bundle and sign its canonical body (envelope stripped) with privPem. */
-function signBundle(body, privPem) {
-  // The verify layer strips content_sig/sig/signature/signer from the body, then
-  // canonicalizes — so we sign the body WITHOUT those fields.
-  const material = Buffer.from(canonicalize(body));
-  return { ...body, content_sig: signWith(privPem, material) };
-}
-
-function cfgFor(signersPem) {
-  return { org: { cohort: { enabled: true, base: BASE, token: "tok", trustedSignersPem: signersPem } } };
-}
-
-function fakeFetch(responder) {
-  const calls = [];
-  const impl = async (url, init) => {
-    calls.push({ url, init });
-    const r = responder ? responder(url, init, calls.length - 1) : null;
-    const status = r && typeof r.status === "number" ? r.status : 200;
-    const ok = r && typeof r.ok === "boolean" ? r.ok : status >= 200 && status < 300;
-    const body = r ? r.body : null;
-    return { ok, status, headers: { get: () => undefined }, json: async () => body };
-  };
-  impl.calls = calls;
-  return impl;
-}
-
-const KEY = generateDeviceKey();          // the trusted signer
-const ATTACKER = generateDeviceKey();     // not pinned
-
-/** Encode an Ed25519 SPKI PEM as an OpenSSH `ssh-ed25519 <base64>` blob. */
-function spkiToSshEd25519(spkiPem) {
-  const der = createPublicKey(spkiPem).export({ type: "spki", format: "der" });
-  const raw = der.subarray(12);
-  const sshStr = (buf) => { const l = Buffer.alloc(4); l.writeUInt32BE(buf.length); return Buffer.concat([l, buf]); };
-  return Buffer.concat([sshStr(Buffer.from("ssh-ed25519")), sshStr(raw)]).toString("base64");
-}
-
-const BODY = { kind: "communication-style", version: 7, content: '{"rule":"no-emoji"}', source_commit: "abc123" };
-
-// --- verifyBundle ----------------------------------------------------------
-
-test("verifyBundle: accepts a signature from a pinned signer", () => {
-  const bundle = signBundle(BODY, KEY.privateKeyPem);
-  const v = verifyBundle(bundle, [KEY.publicKeyPem]);
-  assert.equal(v.ok, true);
-  assert.equal(v.signer, KEY.publicKeyPem);
-});
-
-test("verifyBundle: rejects unsigned, wrong-signer, tampered, and empty-trust", () => {
-  // unsigned
-  assert.equal(verifyBundle(BODY, [KEY.publicKeyPem]).ok, false);
-  // wrong signer (attacker signed; only KEY is pinned)
-  const attackerBundle = signBundle(BODY, ATTACKER.privateKeyPem);
-  assert.equal(verifyBundle(attackerBundle, [KEY.publicKeyPem]).ok, false);
-  // tampered body after signing
-  const good = signBundle(BODY, KEY.privateKeyPem);
-  const tampered = { ...good, content: '{"rule":"emoji-ok"}' };
-  assert.equal(verifyBundle(tampered, [KEY.publicKeyPem]).ok, false);
-  // empty pinned list → default-deny
-  assert.equal(verifyBundle(good, []).ok, false);
-});
-
-// --- cache + staleness -----------------------------------------------------
-
-test("cacheBundle / readCachedBundle round-trip; isStale honours the window", () => {
-  const dir = mkdtempSync(join(tmpdir(), "policy-cache-"));
-  const t0 = Date.UTC(2026, 5, 11, 0, 0, 0);
-  cacheBundle("communication-style", BODY, { cacheDir: dir, now: () => t0, signer: KEY.publicKeyPem });
-  const rec = readCachedBundle("communication-style", { cacheDir: dir });
-  assert.equal(rec.bundle.version, 7);
-  assert.equal(rec.signer, KEY.publicKeyPem);
-  // fresh just after caching
-  assert.equal(isStale("communication-style", { cacheDir: dir, now: () => t0 + 1000 }), false);
-  // stale past the window
-  assert.equal(isStale("communication-style", { cacheDir: dir, now: () => t0 + DEFAULT_STALE_MS + 1 }), true);
-  // absent kind → stale (nothing fresh)
-  assert.equal(isStale("model-allowlist", { cacheDir: dir }), true);
-});
-
-// --- fetchAndApply: good applies + caches; bad quarantines -----------------
-
-test("fetchAndApply: verifies a good signature, caches the bundle", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "policy-apply-"));
-  const bundle = signBundle(BODY, KEY.privateKeyPem);
-  const f = fakeFetch((url) => (url.includes("/v1/policy") ? { body: bundle } : null));
-  const r = await fetchAndApply({
-    cfg: cfgFor([KEY.publicKeyPem]),
-    kind: "communication-style",
-    cacheDir: dir,
-    fetchImpl: f,
-  });
-  assert.equal(r.ok, true);
-  assert.equal(r.applied, true);
-  assert.equal(r.signer, KEY.publicKeyPem);
-  // it was cached
-  assert.ok(readCachedBundle("communication-style", { cacheDir: dir }));
-});
-
-test("fetchAndApply: QUARANTINES a bad-signature bundle — never caches it", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "policy-quarantine-"));
-  const forged = signBundle(BODY, ATTACKER.privateKeyPem); // signed by an unpinned key
-  const f = fakeFetch((url) => (url.includes("/v1/policy") ? { body: forged } : null));
-  const r = await fetchAndApply({
-    cfg: cfgFor([KEY.publicKeyPem]),    // only KEY is pinned
-    kind: "communication-style",
-    cacheDir: dir,
-    fetchImpl: f,
-  });
-  assert.equal(r.ok, false);
-  assert.equal(r.quarantined, true);
-  assert.match(r.reason, /not from any pinned signer/);
-  // NOT cached — the last-good state is untouched
-  assert.equal(readCachedBundle("communication-style", { cacheDir: dir }), null);
-});
-
-test("fetchAndApply: fetch failure (disabled/unreachable) → no-bundle, no throw", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "policy-nofetch-"));
-  const f = fakeFetch(() => ({ ok: false, status: 404, body: {} }));
-  const r = await fetchAndApply({ cfg: cfgFor([KEY.publicKeyPem]), kind: "x", cacheDir: dir, fetchImpl: f });
-  assert.equal(r.ok, false);
-  assert.equal(r.reason, "no-bundle");
-});
-
-// --- handlePolicyStale: the directive handler ------------------------------
-
-test("handlePolicyStale: re-fetches + re-verifies + caches the named kind", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "policy-stale-"));
-  const bundle = signBundle(BODY, KEY.privateKeyPem);
-  const f = fakeFetch((url) => (url.includes("/v1/policy") ? { body: bundle } : null));
-  const out = await handlePolicyStale({
-    cfg: cfgFor([KEY.publicKeyPem]),
-    kind: "communication-style",
-    cacheDir: dir,
-    fetchImpl: f,
-  });
-  assert.equal(out.refreshed, 1);
-  assert.equal(out.results[0].applied, true);
-  assert.ok(readCachedBundle("communication-style", { cacheDir: dir }));
-});
-
-test("handlePolicyStale: with no kind, refreshes every cached kind", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "policy-stale-all-"));
-  // seed two cached kinds
-  cacheBundle("communication-style", BODY, { cacheDir: dir });
-  cacheBundle("model-allowlist", { ...BODY, kind: "model-allowlist" }, { cacheDir: dir });
-  // server returns a freshly-signed bundle for whatever kind is asked
-  const f = fakeFetch((url) => {
-    const u = new URL(url);
-    const kind = u.searchParams.get("kind") || "communication-style";
-    return { body: signBundle({ ...BODY, kind, version: 8 }, KEY.privateKeyPem) };
-  });
-  const out = await handlePolicyStale({ cfg: cfgFor([KEY.publicKeyPem]), cacheDir: dir, fetchImpl: f });
-  assert.equal(out.refreshed, 2);
-});
-
-// --- trust-root parsing ----------------------------------------------------
-
-test("parseAllowedSigners: extracts PEM public-key blocks; [] when missing", () => {
-  const dir = mkdtempSync(join(tmpdir(), "policy-trust-"));
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  const path = join(dir, "allowed-signers");
-  writeFileSync(path, `# trust root\n${KEY.publicKeyPem}\n${ATTACKER.publicKeyPem}\n`);
-  const pems = parseAllowedSigners(path);
-  assert.equal(pems.length, 2);
-  // a bundle signed by KEY verifies against the parsed pins
-  const bundle = signBundle(BODY, KEY.privateKeyPem);
-  assert.equal(verifyBundle(bundle, pems).ok, true);
-  // missing file → []
-  assert.deepEqual(parseAllowedSigners(join(dir, "nope")), []);
-});
-
-test("parseAllowedSigners: loads OpenSSH allowed-signers one-liners (SPEC trust-root format)", () => {
-  const dir = mkdtempSync(join(tmpdir(), "policy-trust-ssh-"));
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  const path = join(dir, "allowed-signers");
-  const keyBlob = spkiToSshEd25519(KEY.publicKeyPem);
-  const attackerBlob = spkiToSshEd25519(ATTACKER.publicKeyPem);
-  // The OpenSSH allowed-signers format: principal [namespaces] keytype base64 [comment].
-  writeFileSync(path,
-    `# org trust root (allowed-signers format)\n` +
-    `org@example.com namespaces="policy" ssh-ed25519 ${keyBlob} server-2026\n` +
-    `bad@evil.example ssh-ed25519 ${attackerBlob}\n`,
-  );
-  const pems = parseAllowedSigners(path);
-  assert.equal(pems.length, 2, "both SSH one-liners convert to SPKI PEMs");
-  // a bundle signed by KEY verifies against the SSH-loaded pins
-  const bundle = signBundle(BODY, KEY.privateKeyPem);
-  assert.equal(verifyBundle(bundle, pems).ok, true);
-});
-
-test("parseAllowedSigners: mixes SPKI PEM blocks and SSH one-liners in one file", () => {
-  const dir = mkdtempSync(join(tmpdir(), "policy-trust-mixed-"));
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  const path = join(dir, "allowed-signers");
-  writeFileSync(path,
-    `${KEY.publicKeyPem}\n` +                                   // raw SPKI PEM
-    `peer@example.com ssh-ed25519 ${spkiToSshEd25519(ATTACKER.publicKeyPem)}\n`, // SSH one-liner
-  );
-  const pems = parseAllowedSigners(path);
-  assert.equal(pems.length, 2, "PEM block + SSH line both load (no double-parse of the PEM body)");
-  assert.equal(verifyBundle(signBundle(BODY, KEY.privateKeyPem), pems).ok, true);
-});

package/lib/org/protocol.checksum.test.mjs

@@ -1,90 +0,0 @@
-/**
- * protocol.checksum.test.mjs — cross-repo wire-contract parity guard.
- *
- * `lib/org/protocol.mjs` is the SINGLE canonical source of truth for the Cohort
- * org-protocol wire contract (method names, scopes, mutating-method set, event
- * families, board status vocabulary, error codes, and — critically — the
- * `computeRowHash` function that defines the append-only `org_events` hash chain).
- * Both maestro (ESM .mjs / Node) and Cohort (TS / Next) must agree on it
- * BYTE-FOR-BYTE, or the hash chain and verification will silently diverge.
- *
- * This test pins the sha256 of `protocol.mjs` to a committed checksum reference
- * (`lib/org/protocol.checksum`). If anyone edits `protocol.mjs` without re-vendoring
- * the shared `@cohort/protocol` package and updating BOTH repos' checksums, this
- * test fails — which is exactly the drift we want to catch in CI.
- *
- * The ONLY supported way to evolve the protocol: edit `lib/org/protocol.mjs`, run
- * `node scripts/sync-protocol.mjs` (re-vendors @cohort/protocol + rewrites both
- * checksums), then commit both repos.
- *
- * Node builtins only. Run: node --test lib/org/protocol.checksum.test.mjs
- *
- * @module lib/org/protocol.checksum.test
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const PROTOCOL_PATH = join(HERE, "protocol.mjs");
-const CHECKSUM_PATH = join(HERE, "protocol.checksum");
-
-/**
- * The expected checksum is READ from the committed `protocol.checksum` reference,
- * never hardcoded as a literal. `scripts/sync-protocol.mjs` writes that file when
- * the protocol changes; reading it here means there is no in-test constant that a
- * re-vendor can leave stale (the exact bug class this guard exists to catch). The
- * test still triangulates three independent values so a partial sync can't pass:
- *   sha256(protocol.mjs) === committed protocol.checksum === a fresh digest.
- */
-const EXPECTED = readFileSync(CHECKSUM_PATH, "utf8").trim();
-
-/**
- * sha256 of a file's exact bytes (no normalization — byte-for-byte is the point).
- * @param {string} path
- * @returns {string} lowercase hex digest
- */
-function sha256File(path) {
-  return createHash("sha256").update(readFileSync(path)).digest("hex");
-}
-
-const DRIFT_MSG =
-  "protocol drift: lib/org/protocol.mjs changed — run `node scripts/sync-protocol.mjs` " +
-  "to re-vendor @cohort/protocol + update both checksums, then commit both repos.";
-
-test("EXPECTED is a well-formed sha256 read from protocol.checksum", () => {
-  // Guard the source-of-truth file itself: an empty/corrupt checksum file must
-  // fail loudly here rather than make the digest comparisons trivially pass.
-  assert.match(
-    EXPECTED,
-    /^[0-9a-f]{64}$/,
-    `lib/org/protocol.checksum is missing or malformed (got: ${JSON.stringify(EXPECTED)}). ${DRIFT_MSG}`,
-  );
-});
-
-test("protocol.mjs sha256 matches the committed protocol.checksum", () => {
-  const actual = sha256File(PROTOCOL_PATH);
-  assert.equal(actual, EXPECTED, DRIFT_MSG);
-});
-
-test("committed protocol.checksum reference matches protocol.mjs", () => {
-  const actual = sha256File(PROTOCOL_PATH);
-  const committed = readFileSync(CHECKSUM_PATH, "utf8").trim();
-  assert.equal(
-    committed,
-    actual,
-    `${DRIFT_MSG} (lib/org/protocol.checksum is stale: ${committed} != ${actual})`,
-  );
-});
-
-test("the file-read expectation and the committed checksum agree", () => {
-  // Belt-and-suspenders: EXPECTED is read from protocol.checksum, so this also
-  // asserts a stable, repeatable read of the same on-disk reference.
-  const committed = readFileSync(CHECKSUM_PATH, "utf8").trim();
-  assert.equal(committed, EXPECTED, DRIFT_MSG);
-});

package/lib/org/protocol.test.mjs

@@ -1,323 +0,0 @@
-/**
- * Tests for lib/org/protocol.mjs — the shared Cohort protocol contract.
- * Locks the load-bearing invariants: scope resolution (default-deny + reserved
- * namespaces), the hash chain (determinism + tamper detection), and frame
- * validation. @module lib/org/protocol.test
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import {
-  PROTOCOL_VERSION, METHODS, FAMILIES, BOARD_STATUS,
-  scopeForMethod, actorCan, isReservedAdminNamespace,
-  computeRowHash, verifyChain, canonicalize,
-  validateReqFrame, buildReqFrame, okFrame, errFrame,
-} from "./protocol.mjs";
-
-test("protocol: every method's family is a known family", () => {
-  for (const [name, def] of Object.entries(METHODS)) {
-    assert.ok(FAMILIES.includes(def.family), `${name} family ${def.family} is known`);
-  }
-});
-
-test("scopeForMethod: reserved namespaces always resolve to admin", () => {
-  assert.equal(scopeForMethod("admin.deactivate"), "admin");
-  assert.equal(scopeForMethod("pairing.request"), "admin");
-  assert.equal(scopeForMethod("policy.anything"), "admin");
-  assert.equal(scopeForMethod("governance.x"), "admin");
-  // unknown method → admin (deny)
-  assert.equal(scopeForMethod("totally.unknown"), "admin");
-  // ordinary method → its declared scope
-  assert.equal(scopeForMethod("board.claim"), "board.work");
-});
-
-test("actorCan: default-deny; admin satisfies everything", () => {
-  assert.equal(actorCan(["board.work"], "board.claim"), true);
-  assert.equal(actorCan(["board.read"], "board.claim"), false, "wrong scope denied");
-  assert.equal(actorCan(["admin"], "board.claim"), true, "admin is a superset");
-  assert.equal(actorCan(["board.work"], "admin.deactivate"), false, "non-admin cannot kill-switch");
-  assert.equal(actorCan([], "board.claim"), false);
-  assert.equal(actorCan(null, "board.claim"), false);
-});
-
-test("isReservedAdminNamespace", () => {
-  assert.equal(isReservedAdminNamespace("admin.x"), true);
-  assert.equal(isReservedAdminNamespace("board.claim"), false);
-});
-
-test("canonicalize: key order does not change the bytes", () => {
-  assert.equal(canonicalize({ b: 1, a: 2 }), canonicalize({ a: 2, b: 1 }));
-  assert.equal(canonicalize({ a: { y: 1, x: 2 } }), '{"a":{"x":2,"y":1}}');
-});
-
-test("computeRowHash: deterministic + sensitive to every field", () => {
-  const row = { seq: 1, family: "board", kind: "create", entity_id: "i1", actor: "a", at: "2026-06-11T00:00:00Z", payload: { title: "x" } };
-  const h1 = computeRowHash("", row);
-  const h2 = computeRowHash("", { ...row });
-  assert.equal(h1, h2, "same input → same hash");
-  assert.notEqual(h1, computeRowHash("prev", row), "prev hash matters");
-  assert.notEqual(h1, computeRowHash("", { ...row, payload: { title: "y" } }), "payload matters");
-  assert.notEqual(h1, computeRowHash("", { ...row, seq: 2 }), "seq matters");
-  assert.match(h1, /^[0-9a-f]{64}$/, "lowercase hex sha-256");
-});
-
-test("verifyChain: accepts a valid chain, pinpoints tampering", () => {
-  const mk = (seq, prev, payload) => {
-    const base = { seq, family: "board", kind: "create", entity_id: `i${seq}`, actor: "a", at: `2026-06-11T00:00:0${seq}Z`, payload };
-    return { ...base, prev_hash: prev, row_hash: computeRowHash(prev, base) };
-  };
-  const e1 = mk(1, "", { n: 1 });
-  const e2 = mk(2, e1.row_hash, { n: 2 });
-  const e3 = mk(3, e2.row_hash, { n: 3 });
-  assert.equal(verifyChain([e1, e2, e3]), null, "clean chain verifies");
-
-  // Tamper with e2's payload but keep its stored row_hash → detected at index 1.
-  const tampered = { ...e2, payload: { n: 999 } };
-  const break1 = verifyChain([e1, tampered, e3]);
-  assert.ok(break1 && break1.index === 1, "tamper detected at the rewritten row");
-
-  // Splice/delete e2 → e3.prev_hash no longer matches → detected at index 1.
-  const break2 = verifyChain([e1, e3]);
-  assert.ok(break2 && break2.index === 1, "deletion detected");
-});
-
-test("validateReqFrame: registry-checked", () => {
-  assert.equal(validateReqFrame(buildReqFrame("board.claim", { id: "x" })).ok, true);
-  assert.equal(validateReqFrame({ method: "nope.method" }).ok, false);
-  assert.equal(validateReqFrame({}).ok, false);
-  assert.equal(validateReqFrame({ method: "board.claim", params: 7 }).ok, false);
-});
-
-test("ok/err frames + version", () => {
-  assert.deepEqual(okFrame({ a: 1 }), { ok: true, result: { a: 1 } });
-  const e = errFrame("FORBIDDEN_SCOPE", "no");
-  assert.equal(e.ok, false);
-  assert.equal(e.error.code, "FORBIDDEN_SCOPE");
-  assert.equal(errFrame("MADE_UP", "x").error.code, "INTERNAL", "unknown code coerces to INTERNAL");
-  assert.equal(PROTOCOL_VERSION, 1);
-  assert.ok(BOARD_STATUS.includes("ready") && BOARD_STATUS.includes("done"));
-});
-
-test("protocol phase 2: governance gating + new families/scopes", async () => {
-  const p = await import("./protocol.mjs");
-  // handoffs + assignment/decomposition are governance-gated; ordinary board ops are not.
-  for (const m of ["handoff.offer", "handoff.accept", "handoff.decline", "handoff.cancel", "board.assign", "board.decompose"]) {
-    assert.equal(p.isGovernanceGated(m), true, `${m} is governance-gated`);
-  }
-  for (const m of ["board.create", "board.claim", "lease.claim", "registry.heartbeat"]) {
-    assert.equal(p.isGovernanceGated(m), false, `${m} is NOT governance-gated`);
-  }
-  // new scopes resolve; lease/handoff are in the default agent set, governance is admin-only.
-  assert.equal(p.scopeForMethod("lease.claim"), "lease.write");
-  assert.equal(p.scopeForMethod("handoff.offer"), "handoff.send");
-  assert.equal(p.scopeForMethod("governance.set_decision_rights"), "admin");
-  assert.ok(p.DEFAULT_AGENT_SCOPES.includes("lease.write") && p.DEFAULT_AGENT_SCOPES.includes("handoff.send"));
-  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "governance.set_decision_rights"), false, "agents cannot set decision rights");
-  assert.ok(p.FAMILIES.includes("lease") && p.FAMILIES.includes("handoff") && p.FAMILIES.includes("governance"));
-});
-
-test("protocol: frozen family + method counts (additive evolution guard)", () => {
-  // These counts move ONLY when the protocol intentionally grows; pinning them
-  // catches an accidental method drop/addition that the checksum alone wouldn't
-  // explain. Bump deliberately alongside the descriptors.
-  // 47 = the 19 mesh-protocol families + 20 agent UI-parity families (charter,
-  // member, team, channel, persona, profile, sop, escalation, annotation,
-  // contact, file, memory, compact, notification, invitation, user, settings,
-  // billing, org, integration) + 1 Brand Studio v2 family (branding) + 1
-  // workspace-email family (email; 2026-07-21 agent-email-server spec §8.1)
-  // + 1 generative-UI artifact family (artifact; GU program 2026-07)
-  // + 5 agent-desk families (2026-07): books (Books desk), calendar
-  // (workspace calendar), crm (CRM desk), files (workspace drive — distinct
-  // from the UI-parity "file" pins/comments family), and directory (external
-  // people + organisations; the Design half of that program rides the existing
-  // `branding` family — the section is renamed, the wire name is not).
-  // The 2026-08 protocol-convergence pass adds 4: subagent (the org-scoped
-  // sub-agent registry), agent (the agent.wait control lane), mandate (the
-  // MANDATE spine) and preference (member-scoped preferences) → 51.
-  // The 2026-08 Genesis agent-surface pass adds 2: genesis (the founder's
-  // pre-commit workspace draft — the ten-stage run and its editable sections)
-  // and architecture (the four tier review decisions and the one whole-
-  // architecture approval, which outlive the run as the Org › Architecture
-  // view) → 53.
-  // The 2026-08 venture-deliverable pass adds 1: resource (the OrgResource
-  // catalogue — a venture's own deliverables). The table predates every agent
-  // plane and was reachable from none of them, so a venture's colleagues could
-  // not list, add, correct, reorder or remove one of their own artifacts → 54.
-  assert.equal(FAMILIES.length, 54, "family count");
-  // 357 = the mesh-protocol + agent UI-parity + calling + branding + email
-  // methods, plus the Live Integrations surface: integration.toolsetVersion +
-  // integration.listAgentTools (SP1) and integration.invokeTool (SP5, execute a
-  // granted plugin tool as the seat), plus the six artifact methods
-  // (create/act/patch/get/list/catalog — GU program 2026-07), plus the 141
-  // agent-desk methods (2026-07, the integration manifest's definitive table):
-  // books 43, calendar 8, crm 43 (38 + the guest-call trio addCallGuest/
-  // mintGuestToken/linkEmail back-ported from Cohort 2026-07-25 + the
-  // articulation program's proposeTerms/revokeDealShare), the email Inbox-app
-  // surface 31, files 20, and meetings.recapFile. Then the 2026-07 Directory &
-  // Design program adds 44: directory 34 (11 reads + 23 writes, of which the
-  // merge/awareness/archive verbs are human-gated in the hq domain) and 10 new
-  // branding methods (getFoundation, getVoice, listTemplates, renderTemplate,
-  // rewriteInVoice, exportKit, generateImage, proposeChange, saveFoundation,
-  // restoreFoundation) taking branding 14 → 24. The 2026-08 mobile-program
-  // parity pass adds 16: email 5 (reportSpam/react/moveMailbox/summarise/ask),
-  // files 9 (sheetTabOp/docTabOp/docSuggestResolve/docSuggestions/commentAdd/
-  // commentResolve/comments/sheetFedRange/ask), calendar.ask and crm.ask.
-  // The 2026-08 host-moderation pass adds 2: calling.removeParticipant +
-  // calling.setLock (host-gated remove-from-room + room lock) → 424.
-  // The 2026-08 call working-sessions pass adds 6: calling.appShareStart/
-  // appShareAct/appShareEnd (agent app-share lifecycle) + getAppShare/
-  // getVisualContext/getCallEvents (participation-gated reads) → 430.
-  // Bumped deliberately alongside
-  // The 2026-08 agent-parity pass adds 1: messaging.typing (the write-less
-  // "is composing…" indicator an SDK-driven agent raises while it works —
-  // sideEffecting:false, no chain event, expires client-side) → 431.
-  // Bumped deliberately alongside
-  // The 2026-08 protocol-convergence pass closes the 29-method gap against hq's
-  // vendored table (the client rejected every one of them BEFORE the network,
-  // so mandate.* et al were unreachable from a daemon): messaging.search,
-  // escalation.ask/answer, memory.recall, preference.upsert/list (6 reverse-
-  // parity methods), the 9 subagent.* registry methods, agent.wait, the 11
-  // mandate.* spine methods, and board.requestReview/resolveReview → 460.
-  // The 2026-08 work-visibility pass adds 1: board.track — ONE step of an
-  // agent's work made visible (find-or-open the row for an ask, move its
-  // column, comment progress, attach output, tag the requester). It is the
-  // single door BOTH planes use: hq's in-process responder calls the same
-  // `server/work/ledger.ts` directly, the daemon reaches it over this wire, so
-  // the threshold and the idempotency cannot fork → 461.
-  // the descriptors; the checksum (read at runtime) is the primary drift guard.
-  // The 2026-08 Genesis agent-surface pass adds 13, the 1:1 programmatic
-  // parity for the founder's own Generate surface: genesis 10 (outline/entity/
-  // grid/plan reads + set/insert/remove/reorder/revert/applyPlan writes) and
-  // architecture 3 (status read + accept/approve review gates). The handlers
-  // had shipped WITHOUT descriptors, which made all 13 unreachable — dispatch
-  // rejects unknown methods and scopeForMethod resolves them to `admin`, which
-  // no principal holds → 474.
-  // The 2026-08 voice-capability pass adds 1: messaging.synthesizeVoiceNote —
-  // hq could always synthesise a colleague's voice note but only as a REFLEX
-  // (answering a human's spoken note in kind), so an agent asked in text for a
-  // voice note truthfully answered that it could not. This is the verb that
-  // makes it askable on every plane; the POST stays plain messaging.send → 475.
-  // The 2026-08 venture-deliverable pass adds 8: resource.list/get (reads) and
-  // resource.create/update/delete/reorder/attachFile/detachFile (writes). Both
-  // reads ride `org.read` and every write `org.write`, so the family is
-  // reachable by the VIEWER and EDITOR tiers that already exist rather than by
-  // a scope nobody has been minted. attachFile/detachFile are the ONLY bridge
-  // to `files.*`: a card carries a fileId POINTER and the drive keeps its own
-  // seat-scoped read surface → 483. Then +1: messaging.electResponder (the
-  // fleet's server-side respond-election) → 484.
-  // The 2026-08 architecture live-board pass adds 3, closing the half of the
-  // `architecture` family that was never on the wire: the three methods above
-  // review a Genesis DRAFT, while hq's /org/architecture is a CRUD surface over
-  // the COMMITTED company and no agent could see it, let alone ask it to change.
-  // architecture.board (the read that hands back LIVE ROW IDS beside the
-  // positional `P1`/`S3` labels the board renders — an agent has no browser to
-  // hold the derived-id -> row-id map, so without it every id it could propose
-  // on would be a guess), architecture.propose (the agent's end of hq's
-  // "agents propose, a human with the floor approves" rule) and
-  // architecture.proposals (the queue that says what became of the ask). NOT
-  // approve/reject: those are session acts in hq by design → 487.
-  assert.equal(Object.keys(METHODS).length, 487, "method count");
-});
-
-test("protocol SP3: messaging + calling families/methods/scopes", async () => {
-  const p = await import("./protocol.mjs");
-  // new families exist.
-  assert.ok(p.FAMILIES.includes("messaging") && p.FAMILIES.includes("calling"));
-  // messaging methods + their declared scopes / side-effect posture.
-  const messagingMethods = {
-    "messaging.send": { scope: "messaging.write", sideEffecting: true, idempotent: true },
-    "messaging.react": { scope: "messaging.write", sideEffecting: true },
-    "messaging.edit": { scope: "messaging.write", sideEffecting: true },
-    "messaging.history": { scope: "messaging.read", sideEffecting: false },
-    "messaging.channels": { scope: "messaging.read", sideEffecting: false },
-  };
-  for (const [m, want] of Object.entries(messagingMethods)) {
-    const def = p.METHODS[m];
-    assert.ok(def, `${m} is registered`);
-    assert.equal(def.family, "messaging", `${m} family`);
-    assert.equal(def.scope, want.scope, `${m} scope`);
-    assert.equal(p.scopeForMethod(m), want.scope, `${m} scopeForMethod`);
-    assert.equal(def.sideEffecting, want.sideEffecting, `${m} sideEffecting`);
-    if (want.idempotent) assert.equal(def.idempotent, true, `${m} idempotent`);
-  }
-  // send is idempotent via the client-supplied message id.
-  assert.equal(p.METHODS["messaging.send"].idempotent, true);
-  // calling methods: all calling.write + side-effecting. removeParticipant +
-  // setLock are the 2026-08 host-moderation verbs (host-gated in the hq domain).
-  for (const m of ["calling.start", "calling.join", "calling.end", "calling.invite", "calling.removeParticipant", "calling.setLock"]) {
-    const def = p.METHODS[m];
-    assert.ok(def, `${m} is registered`);
-    assert.equal(def.family, "calling", `${m} family`);
-    assert.equal(def.scope, "calling.write", `${m} scope`);
-    assert.equal(p.scopeForMethod(m), "calling.write", `${m} scopeForMethod`);
-    assert.equal(def.sideEffecting, true, `${m} sideEffecting`);
-  }
-  // messaging/calling are NOT reserved-admin namespaces (scope is NOT forced to admin).
-  assert.equal(p.isReservedAdminNamespace("messaging.send"), false);
-  assert.equal(p.isReservedAdminNamespace("calling.start"), false);
-  // new scopes are first-class capabilities.
-  for (const s of ["messaging.read", "messaging.write", "calling.write"]) {
-    assert.ok(p.SCOPES.includes(s), `SCOPES includes ${s}`);
-  }
-  // agents participate in the human app: the new scopes are in the default set.
-  for (const s of ["messaging.read", "messaging.write", "calling.write"]) {
-    assert.ok(p.DEFAULT_AGENT_SCOPES.includes(s), `DEFAULT_AGENT_SCOPES includes ${s}`);
-  }
-  // a default-scoped agent can actually exercise the new surfaces.
-  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "messaging.send"), true);
-  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "messaging.history"), true);
-  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "calling.start"), true);
-  // default-deny still holds: a read-only token cannot send.
-  assert.equal(p.actorCan(["messaging.read"], "messaging.send"), false);
-});
-
-test("protocol agent desks: per-family scope pairs, counts, and default grants", async () => {
-  const p = await import("./protocol.mjs");
-  // Each desk family rides its OWN read/write scope pair (the integration
-  // manifest's declared contract) so a key can be minted for exactly one desk.
-  // 2026-08 mobile-parity delta: crm +ask (44), calendar +ask (9), files +9
-  // (tab/suggestion/comment/fed-range ops + ask → 29).
-  const desks = { books: 43, crm: 44, files: 29, calendar: 9 };
-  for (const [fam, want] of Object.entries(desks)) {
-    const rows = Object.entries(p.METHODS).filter(([, d]) => d.family === fam);
-    assert.equal(rows.length, want, `${fam} method count`);
-    for (const [name, d] of rows) {
-      assert.ok(
-        d.scope === `${fam}.read` || d.scope === `${fam}.write`,
-        `${name} rides the ${fam}.read/${fam}.write pair (got ${d.scope})`,
-      );
-      if (d.scope === `${fam}.read` && name !== "files.exportRequest") {
-        assert.equal(d.sideEffecting, false, `${name} read is sideEffecting:false`);
-      }
-    }
-    assert.ok(p.SCOPES.includes(`${fam}.read`) && p.SCOPES.includes(`${fam}.write`), `${fam} scope pair declared`);
-    assert.ok(
-      p.DEFAULT_AGENT_SCOPES.includes(`${fam}.read`) && p.DEFAULT_AGENT_SCOPES.includes(`${fam}.write`),
-      `${fam} scopes in the default agent set`,
-    );
-  }
-  // The email Inbox-app surface rides the existing email pair: 41 methods
-  // total (36 + the 2026-08 spam/react/moveMailbox/summarise/ask delta).
-  assert.equal(Object.entries(p.METHODS).filter(([, d]) => d.family === "email").length, 41, "email method count");
-  assert.equal(p.scopeForMethod("email.draftSend"), "email.write");
-  assert.equal(p.scopeForMethod("email.mailboxes"), "email.read");
-  // files.exportRequest is the AUDITED export: read scope, side-effecting.
-  assert.deepEqual(
-    { scope: p.METHODS["files.exportRequest"].scope, se: p.METHODS["files.exportRequest"].sideEffecting },
-    { scope: "files.read", se: true },
-  );
-  // meetings.recapFile is knowledge capture (meetings family, knowledge.write).
-  assert.equal(p.METHODS["meetings.recapFile"].scope, "knowledge.write");
-  assert.equal(p.METHODS["meetings.recapFile"].family, "meetings");
-  // Spot-check idempotency posture from the manifest: draftSend/ruleSave are
-  // NOT idempotent (each send/save is a new act); holdReplies/markAllRead are.
-  assert.ok(!p.METHODS["email.draftSend"].idempotent);
-  assert.ok(!p.METHODS["email.ruleSave"].idempotent);
-  assert.equal(p.METHODS["email.holdReplies"].idempotent, true);
-  assert.equal(p.METHODS["email.markAllRead"].idempotent, true);
-  // A default-scoped agent can work the desks; a single-desk token stays fenced.
-  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "books.invoiceDraft"), true);
-  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "crm.listDeals"), true);
-  assert.equal(p.actorCan(["books.read"], "books.invoiceDraft"), false, "read tier cannot write");
-  assert.equal(p.actorCan(["books.read", "books.write"], "crm.createDeal"), false, "books key cannot touch crm");
-});