@cohortapp/agent-sdk 2.3.0

package/lib/org/approvals.mjs

@@ -0,0 +1,448 @@
+/**
+ * lib/org/approvals.mjs — agent-mediated approval delivery + the action-class gate.
+ *
+ * The agent half of the phase-3 approval flow (SPEC-org-server §4.6 / §5.4). The
+ * Cohort server holds NO Slack/WhatsApp credentials; an `approval.request`
+ * merely records the pending row and emits an `approval.pending` event. THIS
+ * module is the side that (a) decides whether an action even needs approval (the
+ * action-class gate), (b) sha256-binds the exact payload the human will approve,
+ * (c) posts `approval.request`, and (d) — agent-mediated — delivers the
+ * approve/deny ask to a human over the configured channel (default Slack). The
+ * human's reply routes back through the channel adapter → `approval.resolve` (the
+ * approver side; not this module), and the requester wakes via the
+ * `approval.wait` long-poll for a <60s end-to-end round-trip.
+ *
+ * G16 (zero-LLM-in-the-coordination-loop): NOTHING here makes an LLM call. The
+ * classification is a pure table lookup over policies/action-classification.yaml;
+ * delivery is a deterministic channel send; the wait is a bounded HTTP long-poll.
+ * If this module ever needs a model to decide whether to gate, the invariant is
+ * broken — keep it deterministic.
+ *
+ * G5 (requester != approver): enforced at the storage + method layer server-side
+ * (the approvals-table CHECK constraint and approval.resolve actor check). This
+ * module never resolves an approval it requested; it only requests + waits.
+ *
+ * Pure gate/hash/classify logic (unit-tested) + a thin, injectable, fail-open
+ * channel transport (default: scripts/slack-send.sh) and the long-poll. Node
+ * builtins only beyond the optional js-yaml policy parse (loaded via createRequire,
+ * same as lib/voice/tool-bridge.mjs — absent it the gate fails CLOSED).
+ *
+ * @module lib/org/approvals
+ */
+
+"use strict";
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createRequire } from "node:module";
+
+import { isEnabled, configFromAgent, approvalRequest, approvalWait } from "./client.mjs";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * The gated action classes (SPEC §4.6 + the SHARED CONTRACT). An action that maps
+ * to ANY of these MUST be approved before it executes. Keyed off the action
+ * classification — `irreversible` / `external` / `financial`.
+ * @type {readonly string[]}
+ */
+export const GATED_CLASSES = Object.freeze(["irreversible", "external", "financial"]);
+
+/**
+ * Map an action-classification level (the `risk`/`level`/`approval` triple from
+ * policies/action-classification.yaml) onto the gated action classes. Pure.
+ *
+ * The default/template policy speaks in `action_levels` (observe / draft /
+ * execute_autonomous / escalate_to_principal) and per-action `risk` + `approval`.
+ * The mapping below is conservative — anything that escalates to the principal,
+ * is approval-gated, or is explicitly tagged high/critical risk is treated as a
+ * gated class. We also honour an explicit `classes:[…]` / `action_class` field
+ * when the archetype factory emits one (the per-action map it generates).
+ *
+ * @param {object} def normalised classification entry for the action
+ * @returns {string[]} the subset of GATED_CLASSES this action falls under
+ */
+export function classesForAction(def) {
+  if (!def || typeof def !== "object") return [];
+  const out = new Set();
+  // 1. Explicit class tags win (archetype-generated `actions` map may carry these).
+  const explicit = []
+    .concat(def.classes || [])
+    .concat(def.action_class ? [def.action_class] : [])
+    .concat(def.action_classes || []);
+  for (const c of explicit) {
+    const k = String(c || "").toLowerCase();
+    if (GATED_CLASSES.includes(k)) out.add(k);
+  }
+  if (out.size) return [...out];
+
+  // 2. Derive from risk + approval + level when no explicit tag is present.
+  const risk = String(def.risk || def.level || "").toLowerCase();
+  const approval = String(def.approval || def.gate || "").toLowerCase();
+  const level = String(def.action_level || def.level || "").toLowerCase();
+  const highRisk = risk.includes("high") || risk.includes("critical");
+  const gated =
+    highRisk ||
+    approval.includes("escalat") ||
+    approval.includes("principal") ||
+    approval.includes("approval") ||
+    level.includes("escalate");
+  if (!gated) return [];
+
+  // Heuristic class assignment from the action's notes/keywords (deterministic).
+  const hay = `${def.notes || ""} ${def.description || ""} ${def.name || ""}`.toLowerCase();
+  if (/spend|payment|invoice|wire|financ|budget|purchase|pricing|deal terms/.test(hay)) out.add("financial");
+  if (/external|public|press|partner|customer|regulat|submission|filing/.test(hay)) out.add("external");
+  if (/delete|irreversible|destroy|prod|merge|binding|commit/.test(hay)) out.add("irreversible");
+  // A gated action with no keyword signal still needs approval — default to the
+  // most generic gated class so the gate never silently passes it.
+  if (!out.size) out.add("irreversible");
+  return [...out];
+}
+
+/**
+ * Load + normalise the action-classification policy (YAML or JSON), mirroring
+ * lib/voice/tool-bridge.loadActionClassification: a map of
+ * `{ actionName: { risk, approval, level, classes?, notes } }`. Absent js-yaml
+ * (and no JSON), the gate fails CLOSED (returns {} → unknown actions gate by the
+ * caller's `defaultGate`). Never throws.
+ *
+ * @param {string} agentRoot
+ * @returns {Record<string, object>}
+ */
+export function loadActionClassification(agentRoot) {
+  const root = resolve(agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+  const candidates = [
+    join(root, "policies/action-classification.json"),
+    join(root, "policies/action-classification.yaml"),
+  ];
+  for (const path of candidates) {
+    if (!existsSync(path)) continue;
+    let raw;
+    try { raw = readFileSync(path, "utf-8"); } catch { continue; }
+    try {
+      const parsed = path.endsWith(".json") ? JSON.parse(raw) : require("js-yaml").load(raw);
+      return normaliseClassification(parsed);
+    } catch {
+      // Misconfigured/absent parser → empty map; the gate fails closed.
+      return {};
+    }
+  }
+  return {};
+}
+
+function normaliseClassification(raw) {
+  if (!raw || typeof raw !== "object") return {};
+  const out = {};
+  const actions = raw.actions || raw.action_levels || raw;
+  for (const [name, def] of Object.entries(actions)) {
+    if (!def || typeof def !== "object") continue;
+    out[name] = {
+      name,
+      risk: def.risk || def.level || "low",
+      approval: def.approval || def.gate || "none",
+      action_level: def.action_level || def.level || "",
+      classes: def.classes || def.action_classes || (def.action_class ? [def.action_class] : []),
+      notes: def.notes || def.description || "",
+    };
+  }
+  return out;
+}
+
+/**
+ * Classify an action by name against the loaded policy → its gated classes. When
+ * the caller already knows the classification (e.g. a tool that self-declares
+ * `irreversible`), pass `classification` directly and skip the lookup. Pure.
+ *
+ * @param {object} o - { action, classification?, policy?, agentRoot? }
+ * @returns {{ gated:boolean, classes:string[], source:string }}
+ */
+export function classifyAction(o = {}) {
+  // Caller-supplied classification short-circuits the policy lookup.
+  if (o.classification) {
+    const list = []
+      .concat(o.classification)
+      .map((c) => String(c || "").toLowerCase())
+      .filter((c) => GATED_CLASSES.includes(c));
+    return { gated: list.length > 0, classes: list, source: "explicit" };
+  }
+  const policy = o.policy || loadActionClassification(o.agentRoot);
+  const def = policy[o.action];
+  if (!def) {
+    // Unknown action: fail closed — treat as gated unless caller opts out.
+    return { gated: true, classes: ["irreversible"], source: "unknown-fail-closed" };
+  }
+  const classes = classesForAction(def);
+  return { gated: classes.length > 0, classes, source: "policy" };
+}
+
+/**
+ * sha256-bind a payload: the canonical "the human approved exactly this" hash.
+ * Stable across re-serialization (keys sorted) so the executor can recompute it
+ * and the server can reject a resolve whose executing payload hash differs. Pure.
+ *
+ * @param {unknown} payload
+ * @returns {string} lowercase hex sha-256 over the canonical JSON
+ */
+export function hashPayload(payload) {
+  return createHash("sha256").update(canonicalJson(payload)).digest("hex");
+}
+
+/** Deterministic JSON: object keys sorted recursively. */
+function canonicalJson(value) {
+  return JSON.stringify(sortDeep(value));
+}
+function sortDeep(v) {
+  if (Array.isArray(v)) return v.map(sortDeep);
+  if (v && typeof v === "object") {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = sortDeep(v[k]);
+    return out;
+  }
+  return v;
+}
+
+// ---------------------------------------------------------------------------
+// Agent-mediated delivery (default transport: scripts/slack-send.sh)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the human-facing approval ask (a plain-text message the delivery agent
+ * posts to the approver's channel). Deterministic; no LLM. The approver replies
+ * over the same channel → the channel adapter routes the reply to
+ * `approval.resolve`. Pure.
+ *
+ * @param {object} o - { id, action, classes, subject?, requester? }
+ * @returns {string}
+ */
+export function buildApprovalAsk(o = {}) {
+  const classes = Array.isArray(o.classes) && o.classes.length ? o.classes.join(", ") : "gated";
+  const who = o.requester ? ` (requested by ${o.requester})` : "";
+  const subject = o.subject ? `\n${String(o.subject).slice(0, 800)}` : "";
+  return (
+    `Approval needed${who}: ${o.action || "an action"} [${classes}]` +
+    subject +
+    `\nReply "approve ${o.id}" or "deny ${o.id}".`
+  );
+}
+
+/** Default delivery transport: scripts/slack-send.sh to the approver. Fail-open. */
+export function defaultDeliver({ agentRoot, approver, text }) {
+  try {
+    const dest = approver && (approver.slackId || approver.channel || approver.id);
+    if (!dest) return { ok: false, channel: null, reason: "no-approver-coordinates" };
+    const res = spawnSync(join(agentRoot, "scripts", "slack-send.sh"), [String(dest), String(text)], {
+      cwd: agentRoot,
+      env: { ...process.env, AGENT_DIR: agentRoot },
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    return { ok: res.status === 0, channel: `slack:${dest}`, reason: res.status === 0 ? "delivered" : `exit-${res.status}` };
+  } catch (e) {
+    return { ok: false, channel: null, reason: e.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// requestApproval — classify, bind, request, deliver
+// ---------------------------------------------------------------------------
+
+/**
+ * Request approval for a classified action and deliver the ask to a human.
+ *
+ * Steps (all deterministic; G16):
+ *   1. Classify the action (irreversible/external/financial) via the policy (or
+ *      the caller-supplied `classification`). If NOT gated, returns immediately
+ *      with `{ gated:false }` — no server call, no delivery.
+ *   2. sha256-bind the EXACT payload (`payload_hash`) so the human approves this
+ *      and only this; the executor re-checks the hash before acting.
+ *   3. POST approval.request (idempotent on the derived id) — the server records
+ *      the pending row + emits approval.pending.
+ *   4. Agent-mediated delivery: post the approve/deny ask to the approver's
+ *      channel (default Slack). Delivery failure is recorded, not fatal — the
+ *      pending row + /ops dashboard remain the fallback surface.
+ *
+ * Always resolves (fail-open).
+ *
+ * @param {object} o - {
+ *   cfg, agentRoot, action, payload, classification?, policy?,
+ *   subject?, kind?, itemId?, requester?, approver?, channel?,
+ *   expiresInMs?, id?, deliverFn?, fetchImpl?, nowMs?
+ * }
+ * @returns {Promise<{
+ *   gated:boolean, classes:string[], id:string|null, payloadHash:string,
+ *   requested:boolean, frame:object|null, delivery:object|null
+ * }>}
+ */
+export async function requestApproval(o = {}) {
+  const { gated, classes } = classifyAction({
+    action: o.action,
+    classification: o.classification,
+    policy: o.policy,
+    agentRoot: o.agentRoot,
+  });
+  const payloadHash = hashPayload(o.payload ?? null);
+
+  if (!gated) {
+    return { gated: false, classes: [], id: null, payloadHash, requested: false, frame: null, delivery: null };
+  }
+
+  // Stable approval id: caller-supplied else derived from action+payload so a
+  // retried request (same action, same payload) reuses the same approval row.
+  const id = o.id || `ap-${payloadHash.slice(0, 16)}`;
+  const kind = o.kind || classToKind(classes);
+  const subject = o.subject || `${o.action || "action"} (${classes.join(", ")})`;
+
+  if (!isEnabled(o.cfg)) {
+    // Org binding disabled: surface the gate decision + hash but make no call.
+    return { gated: true, classes, id, payloadHash, requested: false, frame: null, delivery: null };
+  }
+
+  const c = configFromAgent(o.cfg);
+  const params = {
+    id,
+    kind,
+    subject,
+    payload_hash: payloadHash,
+    requester: o.requester || c.orgId || undefined,
+  };
+  if (o.itemId) params.itemId = String(o.itemId);
+  if (Number.isFinite(o.expiresInMs)) params.expiresInMs = o.expiresInMs;
+
+  const frame = await approvalRequest(params, {
+    base: c.base,
+    token: c.token,
+    idempotencyKey: `approval.request:${id}`,
+    fetchImpl: o.fetchImpl,
+  });
+  const requested = !!(frame && frame.ok);
+
+  // Agent-mediated delivery (only when the request landed).
+  let delivery = null;
+  if (requested && o.approver) {
+    const text = buildApprovalAsk({ id, action: o.action, classes, subject: o.subject, requester: o.requester });
+    const deliver = o.deliverFn || defaultDeliver;
+    try {
+      delivery = await deliver({ agentRoot: o.agentRoot, approver: o.approver, channel: o.channel, text, id });
+    } catch (e) {
+      delivery = { ok: false, reason: e.message };
+    }
+  }
+
+  return { gated: true, classes, id, payloadHash, requested, frame, delivery };
+}
+
+/** Pick the approvals.kind enum value (§4.6) from the derived classes. */
+function classToKind(classes) {
+  if (classes.includes("financial")) return "spend";
+  if (classes.includes("external")) return "external_comms";
+  if (classes.includes("irreversible")) return "exec";
+  return "exec";
+}
+
+// ---------------------------------------------------------------------------
+// awaitDecision — bounded long-poll for the outcome
+// ---------------------------------------------------------------------------
+
+/**
+ * Wait for an approval to be decided via the bounded long-poll (approval.wait),
+ * with optional re-polling until an overall deadline so the caller can wait
+ * longer than one 55s window without holding the connection open. Fail-open.
+ *
+ * @param {string} id approval id
+ * @param {number} timeoutMs overall deadline (each poll bounded to <=55s)
+ * @param {object} o - { cfg, fetchImpl?, nowMs?, pollMs? }
+ * @returns {Promise<{ decided:boolean, status:string, payload:object|null }>}
+ */
+export async function awaitDecision(id, timeoutMs = 55000, o = {}) {
+  if (!id) return { decided: false, status: "unknown", payload: null };
+  if (!isEnabled(o.cfg)) return { decided: false, status: "unknown", payload: null };
+  const c = configFromAgent(o.cfg);
+  const now = typeof o.nowMs === "function" ? o.nowMs : Date.now;
+  const deadline = now() + (Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 55000);
+
+  let last = null;
+  // Each iteration is one bounded long-poll; loop until decided or the deadline.
+  // The first poll is given the full remaining budget (clamped to 55s by the
+  // client), so a single call covers the common <60s case in one round-trip.
+  do {
+    const remaining = deadline - now();
+    const pollMs = Math.max(1, Math.min(55000, remaining));
+    const r = await approvalWait({ id, timeoutMs: pollMs }, { base: c.base, token: c.token, fetchImpl: o.fetchImpl });
+    last = r && r.ok ? r.payload : last;
+    const status = decisionStatus(last);
+    if (isDecided(status)) return { decided: true, status, payload: last };
+  } while (now() < deadline);
+
+  return { decided: false, status: decisionStatus(last) || "pending", payload: last };
+}
+
+function decisionStatus(payload) {
+  if (!payload || typeof payload !== "object") return "";
+  return String(payload.status || payload.state || "").toLowerCase();
+}
+
+function isDecided(status) {
+  return status === "approved" || status === "denied" || status === "expired";
+}
+
+// ---------------------------------------------------------------------------
+// gateActionClass — the blocking helper the action-executor calls
+// ---------------------------------------------------------------------------
+
+/**
+ * Block an action-class until it is approved. The helper the action-executor
+ * wraps a gated tool with: classify → (if gated) request + deliver + wait →
+ * return `{ approved, reason }`. Targets <60s end-to-end via the long-poll.
+ *
+ * Non-gated actions return `{ approved:true, reason:"not-gated" }` immediately
+ * (no server round-trip). A disabled org binding returns
+ * `{ approved:false, reason:"org-disabled", ... }` so the executor can decide its
+ * own fallback (the gate never silently passes a gated action when it cannot
+ * obtain an approval). The returned `payloadHash` lets the executor verify it
+ * runs exactly the approved payload.
+ *
+ * @param {object} o - all of requestApproval's params + { timeoutMs?, pollMs? }
+ * @returns {Promise<{
+ *   approved:boolean, reason:string, id:string|null, classes:string[],
+ *   payloadHash:string, status?:string
+ * }>}
+ */
+export async function gateActionClass(o = {}) {
+  const req = await requestApproval(o);
+  if (!req.gated) {
+    return { approved: true, reason: "not-gated", id: null, classes: [], payloadHash: req.payloadHash };
+  }
+  if (!req.requested) {
+    const reason = isEnabled(o.cfg) ? "request-failed" : "org-disabled";
+    return { approved: false, reason, id: req.id, classes: req.classes, payloadHash: req.payloadHash };
+  }
+  const dec = await awaitDecision(req.id, Number.isFinite(o.timeoutMs) ? o.timeoutMs : 55000, {
+    cfg: o.cfg,
+    fetchImpl: o.fetchImpl,
+    nowMs: o.nowMs,
+    pollMs: o.pollMs,
+  });
+  if (dec.status === "approved") {
+    return { approved: true, reason: "approved", id: req.id, classes: req.classes, payloadHash: req.payloadHash, status: dec.status };
+  }
+  const reason = dec.decided ? dec.status : "timeout";
+  return { approved: false, reason, id: req.id, classes: req.classes, payloadHash: req.payloadHash, status: dec.status };
+}
+
+export const _internals = { canonicalJson, classToKind, decisionStatus, isDecided, normaliseClassification };
+
+export default {
+  GATED_CLASSES,
+  classesForAction,
+  loadActionClassification,
+  classifyAction,
+  hashPayload,
+  buildApprovalAsk,
+  defaultDeliver,
+  requestApproval,
+  awaitDecision,
+  gateActionClass,
+};

package/lib/org/approvals.test.mjs

@@ -0,0 +1,216 @@
+/**
+ * approvals.test.mjs — action-class gate, sha256 payload binding, agent-mediated
+ * delivery, and the bounded long-poll awaitDecision / gateActionClass blocking
+ * helper. Injected fetchImpl + deliverFn; no network, no real channels.
+ * Run: node --test lib/org/approvals.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+
+import {
+  GATED_CLASSES,
+  classesForAction,
+  classifyAction,
+  hashPayload,
+  buildApprovalAsk,
+  requestApproval,
+  awaitDecision,
+  gateActionClass,
+} from "./approvals.mjs";
+
+const BASE = "https://org.cohortapp.com";
+const CFG = { org: { cohort: { enabled: true, base: BASE, token: "tok", orgId: "alex-ai" } } };
+const OFF = { org: { cohort: { enabled: false } } };
+
+delete process.env.COHORT_API_TOKEN;
+delete process.env.COHORT_TOKEN;
+
+/** Fake fetch capturing POST bodies and returning canned res frames / read payloads. */
+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;
+}
+
+// --- classification --------------------------------------------------------
+
+test("classesForAction: explicit class tags win; gated-by-risk derivation; non-gated empty", () => {
+  assert.deepEqual(classesForAction({ classes: ["financial"] }), ["financial"]);
+  assert.deepEqual(classesForAction({ action_class: "external" }), ["external"]);
+  // high-risk + escalation, no explicit tag, keyword "delete prod" → irreversible
+  const d = classesForAction({ risk: "high", approval: "principal_escalation", notes: "delete production data" });
+  assert.ok(d.includes("irreversible"));
+  // low-risk autonomous action is not gated
+  assert.deepEqual(classesForAction({ risk: "low", approval: "autonomous" }), []);
+});
+
+test("classifyAction: explicit classification short-circuits; unknown fails closed", () => {
+  assert.deepEqual(classifyAction({ action: "x", classification: "financial" }), { gated: true, classes: ["financial"], source: "explicit" });
+  const unknown = classifyAction({ action: "never-seen", policy: {} });
+  assert.equal(unknown.gated, true);
+  assert.equal(unknown.source, "unknown-fail-closed");
+  const seen = classifyAction({ action: "send_slack", policy: { send_slack: { risk: "low", approval: "autonomous" } } });
+  assert.equal(seen.gated, false);
+});
+
+test("GATED_CLASSES are the three action classes", () => {
+  assert.deepEqual([...GATED_CLASSES].sort(), ["external", "financial", "irreversible"]);
+});
+
+// --- payload binding -------------------------------------------------------
+
+test("hashPayload: stable sha256 over canonical JSON (key order independent)", () => {
+  const a = hashPayload({ amount: 100, to: "bob" });
+  const b = hashPayload({ to: "bob", amount: 100 });
+  assert.equal(a, b);
+  assert.equal(a, createHash("sha256").update(JSON.stringify({ amount: 100, to: "bob" })).digest("hex"));
+});
+
+// --- requestApproval: binds the hash + posts approval.request ---------------
+
+test("requestApproval: binds payload hash and POSTs approval.request with it", async () => {
+  const payload = { action: "wire", amount: 5000, to: "vendor" };
+  const expected = hashPayload(payload);
+  const f = fakeFetch((url) => {
+    if (url.endsWith("/v1/approval.request")) return { body: { ok: true, result: { id: "ap-x", status: "pending" } } };
+    return { body: { ok: true, result: null } };
+  });
+  const r = await requestApproval({
+    cfg: CFG,
+    action: "wire_funds",
+    classification: "financial",
+    payload,
+    approver: { slackId: "U123" },
+    deliverFn: async () => ({ ok: true, channel: "slack:U123", reason: "delivered" }),
+    fetchImpl: f,
+  });
+  assert.equal(r.gated, true);
+  assert.deepEqual(r.classes, ["financial"]);
+  assert.equal(r.requested, true);
+  assert.equal(r.payloadHash, expected);
+  // the request body carried the exact payload_hash ("approved exactly this")
+  const reqCall = f.calls.find((c) => c.url.endsWith("/v1/approval.request"));
+  assert.equal(reqCall.body.payload_hash, expected);
+  assert.equal(reqCall.body.kind, "spend");
+  // agent-mediated delivery fired
+  assert.equal(r.delivery.ok, true);
+});
+
+test("requestApproval: NON-gated action makes no server call and no delivery", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  const r = await requestApproval({
+    cfg: CFG,
+    action: "send_slack",
+    classification: [],         // explicitly not a gated class
+    payload: { msg: "hi" },
+    fetchImpl: f,
+  });
+  assert.equal(r.gated, false);
+  assert.equal(r.requested, false);
+  assert.equal(f.calls.length, 0);
+});
+
+test("requestApproval: org disabled → gated decision + hash, but no call", async () => {
+  const r = await requestApproval({ cfg: OFF, action: "x", classification: "irreversible", payload: { a: 1 } });
+  assert.equal(r.gated, true);
+  assert.equal(r.requested, false);
+  assert.ok(r.payloadHash);
+});
+
+test("buildApprovalAsk: human-readable approve/deny affordance referencing the id", () => {
+  const ask = buildApprovalAsk({ id: "ap-1", action: "wire_funds", classes: ["financial"], requester: "alex" });
+  assert.match(ask, /Approval needed/);
+  assert.match(ask, /approve ap-1/);
+  assert.match(ask, /deny ap-1/);
+  assert.match(ask, /financial/);
+});
+
+// --- awaitDecision: resolves on approval -----------------------------------
+
+test("awaitDecision: resolves decided=true when approval.wait returns approved", async () => {
+  const f = fakeFetch(() => ({ body: { id: "ap-1", status: "approved", resolved_by_agent: "human-1" } }));
+  const dec = await awaitDecision("ap-1", 10000, { cfg: CFG, fetchImpl: f });
+  assert.equal(dec.decided, true);
+  assert.equal(dec.status, "approved");
+  assert.match(f.calls[0].url, /\/v1\/approval\.wait\?id=ap-1/);
+});
+
+test("awaitDecision: denied is decided; pending past deadline is not decided", async () => {
+  const denied = fakeFetch(() => ({ body: { id: "ap-1", status: "denied" } }));
+  const d1 = await awaitDecision("ap-1", 5000, { cfg: CFG, fetchImpl: denied });
+  assert.equal(d1.decided, true);
+  assert.equal(d1.status, "denied");
+
+  // pending forever: a fixed clock makes now() === deadline after the first poll,
+  // so the do/while runs exactly once and then exits not-decided.
+  let t = 1000;
+  const clock = () => t;
+  const pending = fakeFetch(() => { t += 100000; return { body: { id: "ap-1", status: "pending" } }; });
+  const d2 = await awaitDecision("ap-1", 5000, { cfg: CFG, fetchImpl: pending, nowMs: clock });
+  assert.equal(d2.decided, false);
+  assert.equal(d2.status, "pending");
+});
+
+// --- gateActionClass: blocks then unblocks ---------------------------------
+
+test("gateActionClass: non-gated → approved immediately, no server call", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  const g = await gateActionClass({ cfg: CFG, action: "send_slack", classification: [], payload: {}, fetchImpl: f });
+  assert.equal(g.approved, true);
+  assert.equal(g.reason, "not-gated");
+  assert.equal(f.calls.length, 0);
+});
+
+test("gateActionClass: gated action BLOCKS then UNBLOCKS on human approval", async () => {
+  const payload = { action: "merge", repo: "core", pr: 42 };
+  const expectHash = hashPayload(payload);
+  // request → pending; wait → approved (the human approved exactly this payload).
+  const f = fakeFetch((url) => {
+    if (url.includes("/v1/approval.request")) return { body: { ok: true, result: { id: "ap-m", status: "pending" } } };
+    if (url.includes("/v1/approval.wait")) return { body: { id: "ap-m", status: "approved" } };
+    return { body: { ok: true, result: null } };
+  });
+  const g = await gateActionClass({
+    cfg: CFG,
+    action: "merge_pr",
+    classification: "irreversible",
+    payload,
+    approver: { slackId: "U1" },
+    deliverFn: async () => ({ ok: true }),
+    timeoutMs: 10000,
+    fetchImpl: f,
+  });
+  assert.equal(g.approved, true);
+  assert.equal(g.reason, "approved");
+  assert.deepEqual(g.classes, ["irreversible"]);
+  // the executor can verify it runs EXACTLY the approved payload
+  assert.equal(g.payloadHash, expectHash);
+});
+
+test("gateActionClass: denied → not approved with reason 'denied'", async () => {
+  const f = fakeFetch((url) => {
+    if (url.includes("/v1/approval.request")) return { body: { ok: true, result: { id: "ap-d", status: "pending" } } };
+    if (url.includes("/v1/approval.wait")) return { body: { id: "ap-d", status: "denied" } };
+    return { body: { ok: true, result: null } };
+  });
+  const g = await gateActionClass({ cfg: CFG, action: "x", classification: "external", payload: { a: 1 }, timeoutMs: 5000, fetchImpl: f });
+  assert.equal(g.approved, false);
+  assert.equal(g.reason, "denied");
+});
+
+test("gateActionClass: org disabled → not approved, reason org-disabled (never silently passes)", async () => {
+  const g = await gateActionClass({ cfg: OFF, action: "x", classification: "financial", payload: { a: 1 } });
+  assert.equal(g.approved, false);
+  assert.equal(g.reason, "org-disabled");
+});