@cohortapp/agent-sdk 2.3.0

package/lib/org/messaging.test.mjs

@@ -0,0 +1,238 @@
+/**
+ * messaging.test.mjs — the SP10 org messaging seam: send-gate enforcement,
+ * wire shape + idempotency header, afterSend hook + source="messaging"
+ * attribution, calling, and the inbound projection. Injected client/fetch +
+ * send-gate + hook bus + ledger, so no network and no disk writes leak.
+ * Run: node --test lib/org/messaging.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  sendMessage,
+  reactMessage,
+  fetchHistory,
+  listChannels,
+  initiateCall,
+  joinCall,
+  pullInbound,
+  isDirectedAtAgent,
+  toMessageEvent,
+} from "./messaging.mjs";
+import { PROTOCOL_VERSION } from "./protocol.mjs";
+
+const BASE = "https://org.cohortapp.com";
+const TOKEN = "tok-msg";
+const CFG = { org: { cohort: { enabled: true, base: BASE, token: TOKEN, agentId: "agent-1" } } };
+
+delete process.env.COHORT_API_TOKEN;
+delete process.env.COHORT_TOKEN;
+delete process.env.MESSAGING_INBOUND_ESCALATE;
+
+/** A fake fetch that records calls and returns a canned res frame (mirrors client.test). */
+function fakeFetch(responder) {
+  const calls = [];
+  const impl = async (url, init) => {
+    calls.push({ url, init, headers: (init && init.headers) || {}, body: init && init.body ? JSON.parse(init.body) : null });
+    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 : { ok: true, result: null };
+    return { ok, status, headers: { get: () => undefined }, json: async () => body };
+  };
+  impl.calls = calls;
+  return impl;
+}
+
+/** Allow-all send-gate (the default screen would also allow benign text). */
+const allowGate = async () => ({ allow: true, reason: "" });
+/** A capturing ledger so we can assert source="messaging" without touching disk. */
+function captureLedger() {
+  const rows = [];
+  const writeLedgerRow = (_catalog, entry) => { rows.push(entry); return { row: entry, written: true, path: "" }; };
+  writeLedgerRow.rows = rows;
+  return writeLedgerRow;
+}
+/** A hook bus stub that records afterSend emits. */
+function captureBus() {
+  const emits = [];
+  return { emits, emit: async (ev, ctx) => { emits.push({ ev, ctx }); return { cancelled: false }; } };
+}
+
+// --- send-gate enforcement (the load-bearing invariant) --------------------
+
+test("sendMessage: a banned-phrase message is BLOCKED by the send-gate and NEVER sent", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "m1" } } }));
+  // Real send-gate (no gateImpl): "I'm here to help" is a banned AI-tell.
+  const frame = await sendMessage(
+    { channel: "C-eng", body: "Hi — I'm here to help with the deploy." },
+    { cfg: CFG, fetchImpl: f, ledgerImpl: null }
+  );
+  assert.equal(frame.ok, false, "blocked → not ok");
+  assert.equal(frame.blocked, true, "marked blocked (policy refusal, not transport)");
+  assert.match(frame.error.message, /banned/i);
+  assert.equal(f.calls.length, 0, "NO messaging.send was issued for a blocked message");
+});
+
+test("sendMessage: a clean message posts to /v1/messaging.send with Bearer + protocol + idempotency", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "m2", ts: "t" } } }));
+  const ledger = captureLedger();
+  const bus = captureBus();
+  const frame = await sendMessage(
+    { channel: "C-eng", body: "Deploy is green on staging.", mentions: ["agent-2"], idempotencyId: "msg-xyz" },
+    { cfg: CFG, fetchImpl: f, gateImpl: allowGate, hookBus: bus, ledgerImpl: ledger }
+  );
+  assert.equal(frame.ok, true);
+  assert.equal(f.calls.length, 1);
+  assert.match(f.calls[0].url, /\/v1\/messaging\.send$/);
+  assert.equal(f.calls[0].headers.authorization, `Bearer ${TOKEN}`);
+  assert.equal(f.calls[0].headers["x-org-protocol"], String(PROTOCOL_VERSION));
+  assert.equal(f.calls[0].headers["x-idempotency-key"], "msg-xyz", "idempotent on the client message id");
+  // wire shape
+  assert.equal(f.calls[0].body.channel, "C-eng");
+  assert.equal(f.calls[0].body.body, "Deploy is green on staging.");
+  assert.deepEqual(f.calls[0].body.mentions, ["agent-2"]);
+  assert.equal(f.calls[0].body.id, "msg-xyz");
+});
+
+test("sendMessage: emits afterSend + attributes a source='messaging' ledger row on success", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "m3" } } }));
+  const ledger = captureLedger();
+  const bus = captureBus();
+  await sendMessage(
+    { channel: "C-ops", body: "Status nominal." },
+    { cfg: CFG, agentRoot: "/tmp/agent", fetchImpl: f, gateImpl: allowGate, hookBus: bus, ledgerImpl: ledger }
+  );
+  assert.equal(bus.emits.length, 1, "one afterSend emit");
+  assert.equal(bus.emits[0].ev, "afterSend");
+  assert.equal(bus.emits[0].ctx.source, "messaging");
+  assert.equal(ledger.rows.length, 1, "one ledger row");
+  assert.equal(ledger.rows[0].source, "messaging");
+  assert.equal(ledger.rows[0].inputTokens, 0, "zero-token attribution row (not LLM spend)");
+});
+
+test("sendMessage: redactedText from the gate is what hits the wire", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "m4" } } }));
+  const redactGate = async () => ({ allow: true, reason: "", redactedText: "REDACTED" });
+  await sendMessage({ channel: "C", body: "secret" }, { cfg: CFG, fetchImpl: f, gateImpl: redactGate, ledgerImpl: null });
+  assert.equal(f.calls[0].body.body, "REDACTED");
+});
+
+test("sendMessage: missing channel/body → BAD_REQUEST and never touches the gate or wire", async () => {
+  const f = fakeFetch();
+  assert.equal((await sendMessage({ body: "x" }, { cfg: CFG, fetchImpl: f })).error.code, "BAD_REQUEST");
+  assert.equal((await sendMessage({ channel: "C" }, { cfg: CFG, fetchImpl: f })).error.code, "BAD_REQUEST");
+  assert.equal(f.calls.length, 0);
+});
+
+test("sendMessage: org disabled → fail-open error frame, gate ran but no wire", async () => {
+  const f = fakeFetch();
+  const frame = await sendMessage({ channel: "C", body: "hello team" }, { cfg: { org: { cohort: { enabled: false } } }, fetchImpl: f, gateImpl: allowGate, ledgerImpl: null });
+  assert.equal(frame.ok, false);
+  assert.equal(f.calls.length, 0, "no wire when org is disabled");
+});
+
+test("sendMessage: a gate that throws fails CLOSED (no send)", async () => {
+  const f = fakeFetch();
+  const boom = async () => { throw new Error("gate down"); };
+  const frame = await sendMessage({ channel: "C", body: "hello" }, { cfg: CFG, fetchImpl: f, gateImpl: boom, ledgerImpl: null });
+  assert.equal(frame.ok, false);
+  assert.equal(frame.blocked, true);
+  assert.equal(f.calls.length, 0);
+});
+
+// --- react / history / channels --------------------------------------------
+
+test("reactMessage: posts messaging.react and attributes the action", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  const ledger = captureLedger();
+  const frame = await reactMessage({ channel: "C", messageId: "m1", emoji: "eyes" }, { cfg: CFG, fetchImpl: f, ledgerImpl: ledger });
+  assert.equal(frame.ok, true);
+  assert.match(f.calls[0].url, /messaging\.react$/);
+  assert.equal(ledger.rows[0].source, "messaging");
+});
+
+test("fetchHistory: returns the messages array (fail-open [] on error)", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { messages: [{ id: "a" }, { id: "b" }] } } }));
+  const msgs = await fetchHistory({ channel: "C", limit: 10 }, { cfg: CFG, fetchImpl: f });
+  assert.equal(msgs.length, 2);
+  assert.equal(f.calls[0].body.limit, 10);
+  const bad = fakeFetch(() => ({ ok: false, status: 500, body: { ok: false, error: { code: "INTERNAL" } } }));
+  assert.deepEqual(await fetchHistory({ channel: "C" }, { cfg: CFG, fetchImpl: bad }), []);
+});
+
+test("listChannels: returns the channels array (fail-open [])", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { channels: [{ id: "C1" }] } } }));
+  assert.deepEqual(await listChannels({ cfg: CFG, fetchImpl: f }), [{ id: "C1" }]);
+  assert.deepEqual(await listChannels({ cfg: { org: { cohort: { enabled: false } } } }), []);
+});
+
+// --- calling ----------------------------------------------------------------
+
+test("initiateCall: posts calling.start with invitees + attributes the action", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { callId: "call-1" } } }));
+  const ledger = captureLedger();
+  const frame = await initiateCall({ channel: "C", invitees: ["agent-2"], topic: "sync", idempotencyId: "c1" }, { cfg: CFG, fetchImpl: f, ledgerImpl: ledger });
+  assert.equal(frame.ok, true);
+  assert.match(f.calls[0].url, /calling\.start$/);
+  assert.equal(f.calls[0].headers["x-idempotency-key"], "c1");
+  assert.deepEqual(f.calls[0].body.invitees, ["agent-2"]);
+  assert.equal(ledger.rows[0].source, "messaging");
+});
+
+test("joinCall: posts calling.join (missing callId → BAD_REQUEST)", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  assert.equal((await joinCall({}, { cfg: CFG, fetchImpl: f })).error.code, "BAD_REQUEST");
+  const frame = await joinCall({ callId: "call-1" }, { cfg: CFG, fetchImpl: f, ledgerImpl: null });
+  assert.equal(frame.ok, true);
+  assert.match(f.calls[0].url, /calling\.join$/);
+});
+
+// --- inbound projection -----------------------------------------------------
+
+test("isDirectedAtAgent: @mention / DM-to / invitee = directed; own echo / ambient = not", () => {
+  assert.equal(isDirectedAtAgent({ family: "messaging", payload: { from: "x", mentions: ["me"], body: "hi" } }, "me"), true);
+  assert.equal(isDirectedAtAgent({ family: "messaging", payload: { from: "x", to: ["me"], kind: "dm", body: "hi" } }, "me"), true);
+  assert.equal(isDirectedAtAgent({ family: "calling", payload: { from: "x", invitees: ["me"], topic: "t" } }, "me"), true);
+  assert.equal(isDirectedAtAgent({ family: "messaging", payload: { from: "me", mentions: ["me"], body: "echo" } }, "me"), false, "own echo ignored");
+  assert.equal(isDirectedAtAgent({ family: "messaging", payload: { from: "x", body: "ambient channel chatter" } }, "me"), false);
+  assert.equal(isDirectedAtAgent({ family: "board", payload: {} }, "me"), false, "non-messaging family ignored");
+});
+
+test("toMessageEvent: projects a messaging event onto the MessageEvent contract", () => {
+  const ev = toMessageEvent({ family: "messaging", seq: 7, at: "2026-06-12T00:00:00Z", payload: { id: "m9", channel: "C-eng", from: "agent-2", fromName: "Robin", body: "ping", mentions: ["me"] } }, "me");
+  assert.equal(ev.channel, "cohort");
+  assert.equal(ev.message_id, "m9");
+  assert.equal(ev.text, "ping");
+  assert.equal(ev.channel_id, "C-eng");
+  assert.equal(ev.from.id, "agent-2");
+  assert.equal(ev.kind, "message");
+  assert.equal(ev.priority_signals.mentions_agent, true);
+  assert.equal(ev.ingest_source, "cohort");
+});
+
+test("pullInbound: filters to directed events and advances the cursor to max seq", async () => {
+  const f = fakeFetch(() => ({
+    body: {
+      events: [
+        { family: "messaging", seq: 10, payload: { id: "a", channel: "C", from: "x", body: "ambient" } },
+        { family: "messaging", seq: 11, payload: { id: "b", channel: "C", from: "x", mentions: ["agent-1"], body: "@me hi" } },
+        { family: "calling", seq: 12, payload: { id: "c", callId: "call-9", from: "x", invitees: ["agent-1"], topic: "sync" } },
+      ],
+    },
+  }));
+  const { events, nextCursor } = await pullInbound({ cfg: CFG, agentId: "agent-1", cursor: 9, fetchImpl: f });
+  assert.equal(events.length, 2, "only the @mention + the call-invite are directed");
+  assert.equal(nextCursor, 12, "cursor advanced to the highest seq seen (incl. the skipped ambient)");
+  // the events query carried the family filter + cursor
+  assert.match(f.calls[0].url, /events\?cursor=9/);
+  assert.match(f.calls[0].url, /family=messaging,calling/);
+});
+
+test("pullInbound: org disabled → empty, cursor preserved (fail-open)", async () => {
+  const { events, nextCursor } = await pullInbound({ cfg: { org: { cohort: { enabled: false } } }, cursor: 5 });
+  assert.deepEqual(events, []);
+  assert.equal(nextCursor, 5);
+});

package/lib/org/policy.mjs

@@ -0,0 +1,345 @@
+/**
+ * lib/org/policy.mjs — fetch, verify, cache, and stale-check the signed policy
+ * bundle (SPEC-org-server §6 governance-as-code + §G3 detective layer).
+ *
+ * Policy bundles (communication-style, model-allowlist, action-classification,
+ * org/unit budgets) are authored in the protected `org-governance` git repo and
+ * distributed by Cohort as SIGNED bundles with a ring rollout. Because the org
+ * server is a convenient coordinator and NOT a trusted authority (§G3), every
+ * fetched bundle is independently verified here against a PINNED trust root
+ * (`config/org-trust/allowed-signers`) that Cohort NEVER serves — a compromised
+ * server can withhold or DoS, but cannot forge a bundle the agent will apply.
+ *
+ * Flow:
+ *   1. policyFetch (lib/org/client) GETs /v1/policy → the raw signed bundle.
+ *   2. verifyBundle re-checks `content_sig` over the canonical bundle body against
+ *      the pinned signer PEMs (lib/org/verify.verifySignature). A bad/unsigned/
+ *      wrong-signer bundle is QUARANTINED (never cached, never applied).
+ *   3. A good bundle is cached to `config/cache/policy/<kind>.json` with its
+ *      verified-at timestamp; isStale() flags a cache older than the freshness
+ *      window so the daemon can refresh / degrade.
+ *   4. handlePolicyStale() is the presence.beat `policy_stale` directive handler:
+ *      the beat response nudges the agent that a newer bundle exists; this
+ *      re-fetches + re-verifies and returns the applied/quarantined verdict.
+ *
+ * G16 (zero-LLM-in-the-coordination-loop): pure fetch + signature verify + file
+ * cache. ZERO LLM calls.
+ *
+ * Node builtins only (node:crypto via verify.mjs, node:fs). Fail-open /
+ * quarantine-on-mismatch — never throws past the verdict. `fetchImpl`, `now`, and
+ * `cacheDir`/`agentRoot` injectable. ESM.
+ *
+ * @module lib/org/policy
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { canonicalize } from "./protocol.mjs";
+import { verifySignature } from "./keys.mjs";
+import { sshEd25519ToSpkiPem } from "./verify.mjs";
+import { configFromAgent, policyFetch } from "./client.mjs";
+import { writeJsonAtomic } from "../fs-atomic.mjs";
+
+/** Default freshness window: a bundle older than this is "stale" (24h). */
+export const DEFAULT_STALE_MS = 24 * 60 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Trust root + cache locations
+// ---------------------------------------------------------------------------
+
+function agentRootOf(o = {}) {
+  return resolve(o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+}
+
+/** The PINNED trust root path (Cohort NEVER serves this). */
+function trustRootPath(o = {}) {
+  return o.trustRootPath || join(agentRootOf(o), "config", "org-trust", "allowed-signers");
+}
+
+/** Where verified bundles are cached. */
+function cacheDir(o = {}) {
+  return o.cacheDir ? resolve(o.cacheDir) : join(agentRootOf(o), "config", "cache", "policy");
+}
+
+function cachePath(kind, o = {}) {
+  return join(cacheDir(o), `${sanitizeKind(kind)}.json`);
+}
+
+function sanitizeKind(kind) {
+  return String(kind || "bundle").replace(/[^a-z0-9._-]/gi, "_");
+}
+
+/**
+ * Load the pinned signer PEMs for verification. Precedence:
+ *   1. explicit `o.trustedSignersPem` (e.g. from configFromAgent)
+ *   2. `o.cfg` → configFromAgent(cfg).trustedSignersPem
+ *   3. the allowed-signers trust-root FILE (OpenSSH allowed-signers format:
+ *      `principal namespaces? keytype base64key` per line; we extract PEM-able
+ *      keys, tolerating both raw PEM blocks and SSH one-liners we can wrap).
+ * An EMPTY result means "nothing trusted" → every bundle is quarantined
+ * (default-deny). Never throws.
+ *
+ * @param {object} o - { trustedSignersPem?, cfg?, trustRootPath?, agentRoot? }
+ * @returns {string[]} signer PEM strings
+ */
+export function loadTrustedSigners(o = {}) {
+  if (Array.isArray(o.trustedSignersPem) && o.trustedSignersPem.length) {
+    return o.trustedSignersPem.filter((s) => typeof s === "string" && s);
+  }
+  if (o.cfg) {
+    const c = configFromAgent(o.cfg);
+    if (Array.isArray(c.trustedSignersPem) && c.trustedSignersPem.length) return c.trustedSignersPem;
+  }
+  return parseAllowedSigners(trustRootPath(o));
+}
+
+/**
+ * Parse the trust-root file into signer PEMs. Tolerant — accepts BOTH formats the
+ * trust root may carry:
+ *   1. raw `-----BEGIN PUBLIC KEY-----` SPKI blocks (returned verbatim), and
+ *   2. OpenSSH allowed-signers one-liners (`principal namespaces? ssh-ed25519
+ *      base64key comment`), converted to SPKI PEM via verify.sshEd25519ToSpkiPem
+ *      so the SPEC-format (allowed-signers) trust root loads directly.
+ * Blank lines and `#` comments are ignored; an unparseable line is skipped (not
+ * fatal). Returns [] when the file is missing/unreadable (default-deny). Never throws.
+ */
+export function parseAllowedSigners(path) {
+  if (!path || !existsSync(path)) return [];
+  let raw;
+  try { raw = readFileSync(path, "utf-8"); } catch { return []; }
+  const pems = [];
+  // First, lift any inline SPKI PEM blocks verbatim and blank them out so the
+  // line scan below doesn't re-parse their base64 bodies as SSH keys.
+  const re = /-----BEGIN [A-Z ]*PUBLIC KEY-----[\s\S]*?-----END [A-Z ]*PUBLIC KEY-----/g;
+  let m;
+  while ((m = re.exec(raw)) !== null) pems.push(m[0]);
+  const withoutPem = raw.replace(re, "");
+  // Then scan the remaining lines for OpenSSH allowed-signers entries.
+  for (const line of withoutPem.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    if (!trimmed.includes("ssh-ed25519")) continue;
+    const pem = sshEd25519ToSpkiPem(trimmed);
+    if (pem) pems.push(pem);
+  }
+  return pems;
+}
+
+// ---------------------------------------------------------------------------
+// Verify a fetched bundle against the pinned trust root
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the canonical signing material for a bundle: the governance content with
+ * the envelope stripped. The envelope is everything the server signs OVER, not
+ * the signature itself NOR the publish-time metadata — so we drop the signature
+ * fields (`content_sig`/`sig`/`signature`/`signer`) AND the publisher identity +
+ * timestamp (`publishedBy`/`publishedAt`, snake-case variants too), which the
+ * server stamps at insert time and therefore cannot include in the signature it
+ * computes before the row exists. What remains — name, version, body, kind,
+ * source provenance — is exactly what the server's asymmetric signer signs over
+ * (services/cohort policy.publish signBundle), so a fetched bundle verifies
+ * end-to-end against the PINNED root. Matches the envelope convention in
+ * lib/org/verify.mjs. Pure.
+ */
+function bundleSigningMaterial(bundle) {
+  const {
+    content_sig, sig, signature, signer,
+    publishedBy, publishedAt, published_by, published_at,
+    ...body
+  } = bundle || {};
+  void content_sig; void sig; void signature; void signer;
+  void publishedBy; void publishedAt; void published_by; void published_at;
+  return canonicalize(body);
+}
+
+/**
+ * Verify a policy bundle against the PINNED signer PEMs. Tries every pinned
+ * signer; accepts iff one verifies the `content_sig` over the canonical body. An
+ * unsigned, wrong-signer, or tampered bundle is rejected. An EMPTY pinned list
+ * means "nothing trusted" → reject (default-deny). Never throws.
+ *
+ * @param {object} bundle the fetched bundle (must carry content_sig / sig)
+ * @param {string[]} trustedSignersPem pinned SPKI PEMs
+ * @returns {{ok:true, signer:string}|{ok:false, reason:string}}
+ */
+export function verifyBundle(bundle, trustedSignersPem) {
+  if (!bundle || typeof bundle !== "object") return { ok: false, reason: "bundle not an object" };
+  const sig = bundle.content_sig || bundle.sig || bundle.signature;
+  if (!sig || typeof sig !== "string") return { ok: false, reason: "bundle missing signature" };
+  const signers = Array.isArray(trustedSignersPem) ? trustedSignersPem.filter(Boolean) : [];
+  if (signers.length === 0) return { ok: false, reason: "no pinned signers (default-deny)" };
+  const material = Buffer.from(bundleSigningMaterial(bundle));
+  for (const pem of signers) {
+    if (verifySignature(pem, material, sig)) return { ok: true, signer: pem };
+  }
+  return { ok: false, reason: "signature not from any pinned signer" };
+}
+
+// ---------------------------------------------------------------------------
+// Cache read/write
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a cached, previously-verified bundle for a kind. Returns the cache record
+ * `{ bundle, verifiedAt, signer }` or null. Never throws.
+ * @param {string} kind
+ * @param {object} o - { cacheDir?, agentRoot? }
+ */
+export function readCachedBundle(kind, o = {}) {
+  const path = cachePath(kind, o);
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, "utf-8")); } catch { return null; }
+}
+
+/**
+ * Cache a verified bundle. Atomic write. Never throws. Returns the cache record.
+ * @param {string} kind @param {object} bundle @param {object} o - { now?, cacheDir?, agentRoot?, signer? }
+ */
+export function cacheBundle(kind, bundle, o = {}) {
+  const now = (typeof o.now === "function" ? o.now : Date.now)();
+  const record = {
+    kind: sanitizeKind(kind),
+    bundle,
+    version: bundle && bundle.version != null ? bundle.version : null,
+    source_commit: bundle && bundle.source_commit ? bundle.source_commit : null,
+    verifiedAt: new Date(now).toISOString(),
+    verifiedAtMs: now,
+    signer: o.signer || null,
+  };
+  try { writeJsonAtomic(cachePath(kind, o), record); } catch { /* fail-open */ }
+  return record;
+}
+
+/**
+ * Is the cached bundle for a kind stale (older than the freshness window, or
+ * absent)? Absent ⇒ stale (we have nothing fresh). Never throws.
+ * @param {string} kind
+ * @param {object} o - { now?, staleMs?, cacheDir?, agentRoot? }
+ * @returns {boolean}
+ */
+export function isStale(kind, o = {}) {
+  const record = readCachedBundle(kind, o);
+  if (!record) return true;
+  const now = (typeof o.now === "function" ? o.now : Date.now)();
+  const staleMs = Number.isFinite(o.staleMs) && o.staleMs > 0 ? o.staleMs : DEFAULT_STALE_MS;
+  const at = Number.isFinite(record.verifiedAtMs)
+    ? record.verifiedAtMs
+    : (record.verifiedAt ? Date.parse(record.verifiedAt) : NaN);
+  if (!Number.isFinite(at)) return true;
+  return now - at > staleMs;
+}
+
+// ---------------------------------------------------------------------------
+// Fetch → verify → cache
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch the current policy bundle, verify it against the PINNED trust root, and
+ * (on success) cache it. The single entry point the daemon/setup uses.
+ *
+ * On a GOOD signature: caches the bundle and returns
+ * `{ ok:true, applied:true, bundle, signer, record }`.
+ * On a BAD/unsigned/wrong-signer bundle: QUARANTINES — does NOT cache or apply —
+ * and returns `{ ok:false, quarantined:true, reason }`. The caller falls back to
+ * the last-good cached bundle (readCachedBundle).
+ * On a fetch failure (disabled/unreachable): `{ ok:false, reason:"no-bundle" }`.
+ *
+ * Always resolves (fail-open). G16: no LLM call.
+ *
+ * @param {object} o - { cfg, kind?, trustedSignersPem?, trustRootPath?, agentRoot?, cacheDir?, now?, fetchImpl? }
+ * @returns {Promise<{
+ *   ok:boolean, applied?:boolean, quarantined?:boolean, reason?:string,
+ *   bundle?:object, signer?:string, record?:object
+ * }>}
+ */
+export async function fetchAndApply(o = {}) {
+  const c = configFromAgent(o.cfg || {});
+  const bundle = await policyFetch({ base: c.base, token: c.token, kind: o.kind, fetchImpl: o.fetchImpl });
+  if (!bundle) return { ok: false, reason: "no-bundle" };
+
+  const signers = loadTrustedSigners(o);
+  const verdict = verifyBundle(bundle, signers);
+  if (!verdict.ok) {
+    // Quarantine: never cache or apply an unverifiable bundle.
+    return { ok: false, quarantined: true, reason: verdict.reason, bundle };
+  }
+  const kind = o.kind || (bundle && bundle.kind) || "bundle";
+  const record = cacheBundle(kind, bundle, { ...o, signer: verdict.signer });
+  return { ok: true, applied: true, bundle, signer: verdict.signer, record };
+}
+
+/**
+ * Handle the presence.beat `policy_stale` directive: a beat response carrying
+ * `policy_stale` is the rollout nudge that a newer signed bundle exists. Re-fetch
+ * + re-verify (+ cache on success). Returns the fetchAndApply verdict per kind.
+ *
+ * Accepts either a single kind, an array of kinds, or (when none given) refreshes
+ * every kind we already have cached so the whole policy set converges on the nudge.
+ *
+ * Fail-open: a quarantined or unreachable refresh leaves the last-good cache in
+ * place and returns the verdict so the daemon can surface it.
+ *
+ * @param {object} o - { cfg, kinds?|kind?, trustedSignersPem?, agentRoot?, cacheDir?, now?, fetchImpl? }
+ * @returns {Promise<{ refreshed:number, results:Array<{kind:string} & object> }>}
+ */
+export async function handlePolicyStale(o = {}) {
+  let kinds = [];
+  if (Array.isArray(o.kinds)) kinds = o.kinds.slice();
+  else if (o.kind) kinds = [o.kind];
+  else kinds = listCachedKinds(o);
+  if (kinds.length === 0) kinds = [undefined]; // let the server return the default bundle
+
+  const results = [];
+  let refreshed = 0;
+  for (const kind of kinds) {
+    const r = await fetchAndApply({ ...o, kind });
+    results.push({ kind: kind || (r.bundle && r.bundle.kind) || "bundle", ...r });
+    if (r.ok && r.applied) refreshed += 1;
+  }
+  return { refreshed, results };
+}
+
+/** List the kinds we currently have cached (by cache filenames). Never throws. */
+export function listCachedKinds(o = {}) {
+  const dir = cacheDir(o);
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => f.slice(0, -5));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The canonical asymmetric signing material for a policy bundle. Exported so the
+ * SERVER's signer (services/cohort policy.publish) signs over the EXACT bytes
+ * the client reconstructs at verify time — the single source of truth for the
+ * material, so the two halves can never drift. Pure.
+ * @param {object} bundle a bundle (or projected bundle) — envelope fields ignored
+ * @returns {string} canonical JSON of the signed content
+ */
+export function policyBundleSigningMaterial(bundle) {
+  return bundleSigningMaterial(bundle);
+}
+
+export const _internals = { bundleSigningMaterial, cachePath, sanitizeKind, trustRootPath, cacheDir };
+
+export default {
+  DEFAULT_STALE_MS,
+  loadTrustedSigners,
+  parseAllowedSigners,
+  policyBundleSigningMaterial,
+  verifyBundle,
+  readCachedBundle,
+  cacheBundle,
+  isStale,
+  fetchAndApply,
+  handlePolicyStale,
+  listCachedKinds,
+};