@cohortapp/agent-sdk 2.3.0

package/lib/org/client.mjs

@@ -0,0 +1,1628 @@
+/**
+ * lib/org/client.mjs — maestro-side Cohort org client over the /v1 HTTP binding.
+ *
+ * The agent half of the Cohort org protocol (SPEC-org-server §2.4, phase-1 HTTP
+ * binding). Grows out of lib/org/cohort-client.mjs — it keeps the original
+ * fail-open contract (`isEnabled/publishEntry/heartbeat/fetchDirectory` are
+ * re-exported with their old signatures so existing callers don't break) but
+ * routes everything through the frozen wire contract in lib/org/protocol.mjs.
+ *
+ * Wire shape (must match the server byte-for-byte — see protocol.mjs):
+ *   - RPC:   POST {base}/v1/{method}  body=params JSON, res frame {ok,result|error}
+ *            headers: authorization: Bearer, x-org-protocol: 1, content-type,
+ *            and x-idempotency-key for side-effecting methods.
+ *   - Reads: GET {base}/v1/{snapshot|directory|events|hierarchy|board.ready},
+ *            Bearer auth, bare payload JSON on 200, error frame + status on fail.
+ *   - Pairing (pre-auth): POST /v1/pairing.request, POST /v1/pairing.approve.
+ *
+ * Fail-open by design: a network/parse error or a disabled integration yields a
+ * benign value (an error res frame, [] for directory, etc.) — never a throw —
+ * so the org binding can never take down the agent's main path. `fetchImpl` is
+ * injectable everywhere for deterministic tests.
+ *
+ * Node builtins only (uses global fetch on Node 20). ESM.
+ *
+ * @module lib/org/client
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import {
+  PROTOCOL_VERSION,
+  METHODS,
+  methodDef,
+  READS,
+  okFrame,
+  errFrame,
+} from "./protocol.mjs";
+import { applyBrandEnvCompat } from "../env-compat.mjs";
+
+// SDK self-bridge: agent instances import this module directly from their own
+// bins — they never pass through maestro's process entrypoints — so the client
+// itself must alias NEOLITH_* ⇄ COHORT_* before the env-first token/org
+// resolution below. Idempotent and never clobbers an explicitly-set name.
+applyBrandEnvCompat();
+
+const DEFAULT_TIMEOUT_MS = 8000;
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the agent's org config from disk — `config/org.yaml` (the canonical file
+ * `lib/setup/sections/org.mjs` writes and the wizard captures). Returns the
+ * parsed object ({ org: { cohort: {...} } }) or {} when absent/unparseable.
+ * THE single disk loader for org config, so the daemon and any caller resolve
+ * org enrollment from the same place (fixes the daemon reading collective.yaml
+ * by mistake). Fail-open: never throws.
+ * @param {string} agentRoot
+ * @returns {object}
+ */
+export function loadOrgConfig(agentRoot) {
+  try {
+    const p = join(agentRoot, "config", "org.yaml");
+    if (!existsSync(p)) return {};
+    const require = createRequire(import.meta.url);
+    const yaml = require("js-yaml");
+    return yaml.load(readFileSync(p, "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Is the cohort integration configured + enabled? Back-compat shape: requires
+ * `org.cohort.enabled` plus a reachable endpoint (apiUrl or base).
+ * @param {object} cfg
+ * @returns {boolean}
+ */
+export function isEnabled(cfg) {
+  const n = cfg && cfg.org && cfg.org.cohort;
+  if (!n || !n.enabled) return false;
+  return !!(n.base || (n.apiUrl && n.orgId));
+}
+
+/**
+ * Distil the org client config from an agent config object. Resolves:
+ *   - base:   the server origin for the /v1 binding (explicit `org.cohort.base`,
+ *             else derived from `apiUrl` [+ `orgId` path] for back-compat).
+ *   - orgId:  the org slug — config `org.cohort.orgId` else COHORT_ORG_ID env
+ *             (hq's documented var). Used by the legacy directory-path derivation
+ *             and, when known, sent as the `x-org-id` pin header (defence-in-depth).
+ *   - token:  bearer credential — the RAW OrgApiKey. Resolution order:
+ *             config `token` → COHORT_API_TOKEN → COHORT_TOKEN → COHORT_API_KEY.
+ *             hq's auth doc names the agent var COHORT_API_KEY; the older
+ *             COHORT_API_TOKEN/COHORT_TOKEN are still accepted (Bearer) so an
+ *             existing agent env keeps working.
+ *   - trustedSignersPem: PINNED snapshot signer PEMs for the detective layer.
+ * Never throws; returns a fully-populated object with empty strings for missing
+ * fields so callers can null-check uniformly.
+ * @param {object} cfg
+ * @returns {{enabled:boolean, base:string, orgId:string, token:string, trustedSignersPem:string[]}}
+ */
+export function configFromAgent(cfg) {
+  const n = (cfg && cfg.org && cfg.org.cohort) || {};
+  const apiUrl = n.apiUrl ? String(n.apiUrl).replace(/\/+$/, "") : "";
+  const orgId = (n.orgId ? String(n.orgId) : "") || process.env.COHORT_ORG_ID || "";
+  let base = n.base ? String(n.base).replace(/\/+$/, "") : "";
+  if (!base && apiUrl) {
+    // Legacy back-compat: apiUrl[/orgId] is the server origin for the binding.
+    base = orgId ? `${apiUrl}/${encodeURIComponent(orgId)}` : apiUrl;
+  }
+  const token =
+    (n.token && String(n.token)) ||
+    process.env.COHORT_API_TOKEN ||
+    process.env.COHORT_TOKEN ||
+    process.env.COHORT_API_KEY ||
+    "";
+  const signers = Array.isArray(n.trustedSignersPem)
+    ? n.trustedSignersPem.filter((s) => typeof s === "string" && s)
+    : [];
+  return { enabled: !!(n.enabled && base), base, orgId, token, trustedSignersPem: signers };
+}
+
+// ---------------------------------------------------------------------------
+// Low-level transport
+// ---------------------------------------------------------------------------
+
+function pickFetch(fetchImpl) {
+  if (typeof fetchImpl === "function") return fetchImpl;
+  if (typeof fetch === "function") return fetch;
+  return null;
+}
+
+function baseHeaders(token, orgId) {
+  const h = {
+    "content-type": "application/json",
+    "x-org-protocol": String(PROTOCOL_VERSION),
+  };
+  if (token) h.authorization = `Bearer ${token}`;
+  // Defence-in-depth: pin the org when we know it. hq treats a mismatch as 401
+  // and a match as harmless, so this only ever fences a misrouted key.
+  if (orgId) h["x-org-id"] = String(orgId);
+  return h;
+}
+
+/**
+ * Perform a single HTTP request with timeout + JSON parse. Returns the raw
+ * outcome ({ok,status,body}); never throws.
+ */
+async function httpRequest(fetchImpl, url, init, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const f = pickFetch(fetchImpl);
+  if (!f) return { ok: false, status: 0, body: null };
+  const ctrl = typeof AbortController === "function" ? new AbortController() : null;
+  const timer = ctrl ? setTimeout(() => ctrl.abort(), timeoutMs) : null;
+  try {
+    const res = await f(url, { ...init, signal: ctrl ? ctrl.signal : undefined });
+    let body = null;
+    try { body = await res.json(); } catch { body = null; }
+    return { ok: !!res.ok, status: typeof res.status === "number" ? res.status : 0, body };
+  } catch {
+    return { ok: false, status: 0, body: null };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Join an org server ORIGIN + a /v1 RPC/read path.
+ *
+ * hq serves the whole agent binding at `/api/v1/<path>` (the catch-all route
+ * `src/app/api/v1/[...method]/route.ts` — there is NO bare `/v1` mount), and the
+ * org-data DTO reads (fetchSelfProfile/orgDataGet) already build `/api/v1/org/…`.
+ * So the ONE canonical convention is `${origin}/api/v1/${path}` — this keeps the
+ * RPC/read binding and the org-data reads pointed at the same base.
+ *
+ * Back-compat: a `base` that ALREADY carries the mount path baked in (ends in
+ * `/api/v1` or a legacy bare `/v1`) is respected as-is rather than double-
+ * prefixed, so a service configured the old way keeps working.
+ */
+function v1Url(base, path) {
+  const b = String(base).replace(/\/+$/, "");
+  if (/\/(?:api\/)?v1$/.test(b)) return `${b}/${path}`;
+  return `${b}/api/v1/${path}`;
+}
+
+/** Normalise a server body into a res frame ({ok,result} | {ok,error}). */
+function asResFrame(r) {
+  const b = r.body;
+  if (b && typeof b === "object" && typeof b.ok === "boolean") return b; // already a frame
+  if (r.ok) return okFrame(b);
+  return errFrame(httpStatusToCode(r.status), `http ${r.status}`);
+}
+
+function httpStatusToCode(status) {
+  switch (status) {
+    case 400: return "BAD_REQUEST";
+    case 401: return "UNAUTHORIZED";
+    case 403: return "FORBIDDEN_SCOPE";
+    case 404: return "NOT_FOUND";
+    case 409: return "CONFLICT";
+    case 423: return "GOVERNANCE_NOT_READY";
+    case 429: return "RATE_LIMITED";
+    default: return "INTERNAL";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pairing handshake (pre-auth)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pre-auth pairing handshake. POST /v1/pairing.request — no bearer token (the
+ * agent has none yet). The operator picks a `code` and shares it with an org
+ * admin, who resolves the handshake via pairing.approve; hq keys the
+ * PairingRequest row on `(orgId, code)` (server contract: `code` is required,
+ * `agentId` optional). We ALSO send the device `pubkey` + `displayName` so a
+ * server that pins the device key on approval has it (hq currently ignores the
+ * extra fields — zod strips unknown keys — so this stays forward-compatible).
+ * Returns the res frame; on transport failure returns a fail-open error frame.
+ * @param {object} o - { base, agentId, pubkey, code?, displayName?, fetchImpl? }
+ * @returns {Promise<object>} res frame {ok:true,result:{status,code}}|{ok:false,error}
+ */
+export async function pairRequest(o = {}) {
+  const { base, agentId, displayName, pubkey, code } = o;
+  if (!base) return errFrame("BAD_REQUEST", "missing base");
+  if (!agentId || !pubkey) return errFrame("BAD_REQUEST", "missing agentId or pubkey");
+  const body = { agentId, displayName: displayName || agentId, pubkey };
+  // `code` is the operator-chosen handshake token hq keys the row on. Include it
+  // whenever supplied so a real end-to-end pairing.request/approve flow works.
+  if (code != null && String(code).trim()) body.code = String(code).trim();
+  const r = await httpRequest(o.fetchImpl, v1Url(base, "pairing.request"), {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-org-protocol": String(PROTOCOL_VERSION) },
+    body: JSON.stringify(body),
+  });
+  return asResFrame(r);
+}
+
+// ---------------------------------------------------------------------------
+// RPC (POST /v1/{method})
+// ---------------------------------------------------------------------------
+
+/**
+ * Invoke an RPC method over the /v1 binding. Builds the correct headers
+ * (Bearer, x-org-protocol, and x-idempotency-key for side-effecting methods),
+ * posts the params object, and returns the parsed res frame. Fail-open: a
+ * transport error yields an INTERNAL error frame rather than throwing.
+ *
+ * @param {string} method full dotted method name (e.g. "board.claim")
+ * @param {object} params the params object (request body)
+ * @param {object} o - { base, token, orgId?, idempotencyKey?, fetchImpl? }
+ * @returns {Promise<object>} res frame
+ */
+export async function call(method, params, o = {}) {
+  const { base, token, orgId } = o;
+  if (!base) return errFrame("BAD_REQUEST", "missing base");
+  const def = methodDef(method);
+  if (!def) return errFrame("NOT_FOUND", `unknown method ${method}`);
+
+  const headers = baseHeaders(def.auth === false ? "" : token, def.auth === false ? "" : orgId);
+  if (def.sideEffecting) {
+    const key = o.idempotencyKey || (def.idempotent ? defaultIdempotencyKey(method, params) : "");
+    if (key) headers["x-idempotency-key"] = String(key);
+  }
+  const r = await httpRequest(o.fetchImpl, v1Url(base, method), {
+    method: "POST",
+    headers,
+    body: JSON.stringify(params || {}),
+  });
+  return asResFrame(r);
+}
+
+/** Derive a stable idempotency key for an idempotent method (best-effort). */
+function defaultIdempotencyKey(method, params) {
+  const id = params && (params.id || params.entityId || params.agentId);
+  return id ? `${method}:${id}` : "";
+}
+
+// ---------------------------------------------------------------------------
+// Reads (GET)
+// ---------------------------------------------------------------------------
+
+/**
+ * GET a read endpoint. Reads return the BARE payload JSON on 200 (not wrapped in
+ * a frame); on failure the server returns an error frame. We normalise: success
+ * → { ok:true, payload }, failure → { ok:false, error, status }. Fail-open.
+ *
+ * @param {string} path the read path under /v1 (e.g. "snapshot", "events?cursor=0")
+ * @param {object} o - { base, token, orgId?, etag?, fetchImpl? }
+ * @returns {Promise<{ok:boolean, payload?:any, error?:object, status:number, etag?:string, notModified?:boolean}>}
+ */
+export async function read(path, o = {}) {
+  const { base, token, orgId } = o;
+  if (!base) return { ok: false, error: errFrame("BAD_REQUEST", "missing base").error, status: 0 };
+  const headers = baseHeaders(token, orgId);
+  delete headers["content-type"]; // GET has no body
+  if (o.etag) headers["if-none-match"] = o.etag;
+
+  const f = pickFetch(o.fetchImpl);
+  if (!f) return { ok: false, error: errFrame("INTERNAL", "no fetch").error, status: 0 };
+  const ctrl = typeof AbortController === "function" ? new AbortController() : null;
+  const readTimeoutMs = Number.isFinite(o.timeoutMs) && o.timeoutMs > 0 ? o.timeoutMs : DEFAULT_TIMEOUT_MS;
+  const timer = ctrl ? setTimeout(() => ctrl.abort(), readTimeoutMs) : null;
+  try {
+    const res = await f(v1Url(base, path), { method: "GET", headers, signal: ctrl ? ctrl.signal : undefined });
+    const status = typeof res.status === "number" ? res.status : 0;
+    const respEtag = readHeader(res, "etag");
+    if (status === 304) return { ok: true, notModified: true, status, etag: o.etag };
+    let body = null;
+    try { body = await res.json(); } catch { body = null; }
+    if (res.ok) return { ok: true, payload: body, status, etag: respEtag };
+    const error = body && body.error ? body.error : errFrame(httpStatusToCode(status), `http ${status}`).error;
+    return { ok: false, error, status };
+  } catch {
+    return { ok: false, error: errFrame("INTERNAL", "transport error").error, status: 0 };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Org-data API (GET /api/v1/org/...) — the directory/profile read surface
+// ---------------------------------------------------------------------------
+//
+// DISTINCT from the /v1 RPC binding above: the org-data API is the human-facing
+// directory surface (`/api/v1/org/whoami`, `/api/v1/org/members/<slug>`) that
+// returns a MemberProfileDTO. `maestro setup`/`sync` PULL from here to
+// auto-populate config/agent.json so an admin describes each agent ONCE in
+// Cohort. Auth is the org API KEY (Bearer) + the org slug; the agent id (slug)
+// selects a specific member, its absence selects whoami (sole-agent / email hint).
+//
+// Fail-open like everything else: a missing key / unreachable server / non-200
+// yields an error frame, never a throw, so the wizard simply falls back to the
+// manual prompts.
+
+/**
+ * Pull THIS agent's record from the Cohort org-data API as a MemberProfileDTO.
+ * Selects `GET /api/v1/org/members/<agentId>` when an agentId (slug) is supplied,
+ * else `GET /api/v1/org/whoami?orgId=<orgId>[&slug=<memberHint>][&email=<hint>]`
+ * (sole-agent / member-hinted resolution — orgId is the tenant PIN, not a member
+ * hint; `slug`/`email` are member hints). Returns the standard res frame
+ * ({ok:true,result:DTO}|{ok:false,error}); fail-open (never throws).
+ *
+ * @param {object} o
+ * @param {string} o.base    Cohort server origin (e.g. https://cohort.internal)
+ * @param {string} o.apiKey  org API key (Bearer)
+ * @param {string} o.orgId   org slug — sent as the `?orgId=`/`x-org-id` tenant pin
+ * @param {string} [o.agentId]   member slug — when set, hits /org/members/<slug>
+ * @param {string} [o.memberSlug] member-slug hint for whoami resolution (?slug=)
+ * @param {string} [o.emailHint] email hint for whoami resolution
+ * @param {Function} [o.fetchImpl] injectable fetch for tests
+ * @returns {Promise<object>} res frame
+ */
+export async function fetchSelfProfile(o = {}) {
+  const base = o.base ? String(o.base).replace(/\/+$/, "") : "";
+  const apiKey = o.apiKey ? String(o.apiKey) : "";
+  const orgId = o.orgId ? String(o.orgId) : "";
+  if (!base) return errFrame("BAD_REQUEST", "missing base");
+  if (!apiKey) return errFrame("UNAUTHORIZED", "missing api key");
+  if (!orgId) return errFrame("BAD_REQUEST", "missing orgId");
+
+  // The org is resolved server-side from the API KEY, not from a query param.
+  // Pin it defence-in-depth via `?orgId=` + the `x-org-id` header (hq treats a
+  // mismatch as 401, a match as harmless). whoami's `slug`/`email` params are
+  // reserved for genuine MEMBER hints — never the org slug — so we send a member
+  // slug hint (o.memberSlug) only when one is explicitly supplied.
+  const memberHint = o.memberSlug ? String(o.memberSlug) : "";
+  const path = o.agentId
+    ? `org/members/${encodeURIComponent(String(o.agentId))}?orgId=${encodeURIComponent(orgId)}`
+    : `org/whoami?orgId=${encodeURIComponent(orgId)}${memberHint ? `&slug=${encodeURIComponent(memberHint)}` : ""}${o.emailHint ? `&email=${encodeURIComponent(String(o.emailHint))}` : ""}`;
+  const url = `${base}/api/v1/${path}`;
+  const headers = { authorization: `Bearer ${apiKey}`, accept: "application/json", "x-org-id": orgId };
+
+  const r = await httpRequest(o.fetchImpl, url, { method: "GET", headers });
+  if (!r.ok) {
+    const b = r.body;
+    if (b && typeof b === "object" && b.error) return errFrame(b.error.code || httpStatusToCode(r.status), b.error.message || `http ${r.status}`);
+    return errFrame(httpStatusToCode(r.status), `http ${r.status}`);
+  }
+  // The org-data API returns the BARE MemberProfileDTO on 200 (it may also wrap
+  // it under {member}/{profile}/{result}); normalise to a res frame.
+  const dto = unwrapProfile(r.body);
+  if (!dto) return errFrame("NOT_FOUND", "no profile in response");
+  return okFrame(dto);
+}
+
+/** Normalise the org-data API payload to the bare MemberProfileDTO (or null). */
+function unwrapProfile(body) {
+  if (!body || typeof body !== "object") return null;
+  if (body.slug || body.displayName || body.agentEmail) return body;
+  for (const key of ["member", "profile", "result", "data"]) {
+    const v = body[key];
+    if (v && typeof v === "object" && (v.slug || v.displayName || v.agentEmail)) return v;
+  }
+  return null;
+}
+
+/** Read a response header across fetch Response and plain-object fakes. */
+function readHeader(res, name) {
+  try {
+    if (res && res.headers && typeof res.headers.get === "function") return res.headers.get(name) || undefined;
+    if (res && res.headers && typeof res.headers === "object") return res.headers[name] || res.headers[name.toLowerCase()];
+  } catch { /* ignore */ }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Org-data API: structural reads (chart / relationships / strategy)
+// ---------------------------------------------------------------------------
+//
+// The SAME human-facing directory surface as fetchSelfProfile (GET
+// /api/v1/org/*, Bearer org API key + `?slug=<org>`), extended to the org's
+// STRUCTURE: the chart (nodes + reporting/governance edges), a single member's
+// relationships, and the org strategy doc. A provisioned agent consumes these as
+// its source of truth so it knows who owns what, who it escalates to, and the
+// org's north star — instead of inferring everything from its local archetype.
+//
+// hq returns these as `{ ok:true, ...DTO }` (chart/relationships) or
+// `{ ok:true, strategy:DTO }`. We normalise to the same res frame fetchSelfProfile
+// uses ({ok:true,result:DTO}|{ok:false,error}) so callers null-check uniformly.
+// Fail-open like everything else: a missing key / unreachable server / non-200
+// yields an error frame, never a throw.
+
+/**
+ * Shared org-data GET. Builds `GET {base}/api/v1/org/{path}?slug=<orgId>[&…]`
+ * with Bearer auth, runs it fail-open, and projects the 200 body through `pick`
+ * (body → meaningful DTO) into a res frame. Mirrors fetchSelfProfile's contract.
+ * @param {object} o - { base, apiKey, orgId, fetchImpl? }
+ * @param {string} path the sub-path under /api/v1/org/ (e.g. "chart")
+ * @param {object} extraParams extra query params (merged after slug)
+ * @param {(body:any)=>any} pick projects the 200 body to the DTO (null ⇒ NOT_FOUND)
+ * @returns {Promise<object>} res frame
+ */
+async function orgDataGet(o, path, extraParams, pick) {
+  const base = o && o.base ? String(o.base).replace(/\/+$/, "") : "";
+  const apiKey = o && o.apiKey ? String(o.apiKey) : "";
+  const orgId = o && o.orgId ? String(o.orgId) : "";
+  if (!base) return errFrame("BAD_REQUEST", "missing base");
+  if (!apiKey) return errFrame("UNAUTHORIZED", "missing api key");
+  if (!orgId) return errFrame("BAD_REQUEST", "missing orgId");
+
+  // Org is resolved from the API key server-side; `orgId` is the defence-in-depth
+  // pin (`?orgId=` + `x-org-id` header), NOT a `slug` (which hq reads as a member
+  // hint). `member=<slug>` and other genuine params ride in via extraParams.
+  const qs = new URLSearchParams({ orgId, ...(extraParams || {}) }).toString();
+  const url = `${base}/api/v1/org/${path}?${qs}`;
+  const headers = { authorization: `Bearer ${apiKey}`, accept: "application/json", "x-org-id": orgId };
+
+  const r = await httpRequest(o.fetchImpl, url, { method: "GET", headers });
+  if (!r.ok) {
+    const b = r.body;
+    if (b && typeof b === "object" && b.error) return errFrame(b.error.code || httpStatusToCode(r.status), b.error.message || `http ${r.status}`);
+    return errFrame(httpStatusToCode(r.status), `http ${r.status}`);
+  }
+  const result = pick(r.body);
+  if (result == null) return errFrame("NOT_FOUND", `no ${path} payload`);
+  return okFrame(result);
+}
+
+/** Project the chart body ({ok,nodes,edges} | {chart:{…}}) → { nodes, edges }. */
+function pickChart(body) {
+  if (!body || typeof body !== "object") return null;
+  const src = Array.isArray(body.nodes) || Array.isArray(body.edges) ? body : (body.chart || body.result);
+  if (!src || typeof src !== "object") return null;
+  return { nodes: Array.isArray(src.nodes) ? src.nodes : [], edges: Array.isArray(src.edges) ? src.edges : [] };
+}
+
+/** Project the relationships body → { member, reportingLine, reports, governance }. */
+function pickRelationships(body) {
+  if (!body || typeof body !== "object") return null;
+  const has = body.member || body.reportingLine || Array.isArray(body.reports) || Array.isArray(body.governance);
+  const src = has ? body : (body.relationships || body.result);
+  if (!src || typeof src !== "object") return null;
+  return {
+    member: src.member || null,
+    reportingLine: src.reportingLine || null,
+    reports: Array.isArray(src.reports) ? src.reports : [],
+    governance: Array.isArray(src.governance) ? src.governance : [],
+  };
+}
+
+/** Project the strategy body ({ok,strategy:{…}} | bare StrategyDTO) → StrategyDTO. */
+function pickStrategy(body) {
+  if (!body || typeof body !== "object") return null;
+  if (body.strategy && typeof body.strategy === "object") return body.strategy;
+  if (body.northStar !== undefined || Array.isArray(body.phases) || Array.isArray(body.streams)) return body;
+  if (body.result && typeof body.result === "object") return body.result;
+  return null;
+}
+
+/**
+ * Fetch the org chart (GET /api/v1/org/chart): active-member nodes + reporting/
+ * governance edges (keyed by member slug). Org-scoped via the API key. Returns a
+ * res frame whose result is `{ nodes, edges }`; fail-open (never throws).
+ * @param {object} o - { base, apiKey, orgId, fetchImpl? }
+ * @returns {Promise<object>} res frame {ok:true,result:{nodes,edges}}|{ok:false,error}
+ */
+export async function fetchOrgChart(o = {}) {
+  return orgDataGet(o, "chart", undefined, pickChart);
+}
+
+/**
+ * Fetch ONE member's relationships (GET /api/v1/org/relationships?member=<slug>):
+ * reporting line, reports, and governance edges. The member slug is `o.member`
+ * (falls back to `o.agentId`). Returns a res frame whose result is
+ * `{ member, reportingLine, reports, governance }`; fail-open.
+ * @param {object} o - { base, apiKey, orgId, member|agentId, fetchImpl? }
+ * @returns {Promise<object>} res frame
+ */
+export async function fetchRelationships(o = {}) {
+  const member = (o && (o.member || o.agentId)) ? String(o.member || o.agentId) : "";
+  if (!member) return errFrame("BAD_REQUEST", "missing member slug");
+  return orgDataGet(o, "relationships", { member }, pickRelationships);
+}
+
+/**
+ * Fetch the org strategy doc (GET /api/v1/org/strategy): north star, levers,
+ * phases and streams with their RACI assignments. Org-scoped via the API key.
+ * Returns a res frame whose result is the StrategyDTO; fail-open. A tenant with
+ * no strategy doc yet yields a NOT_FOUND error frame (the agent runs without it).
+ * @param {object} o - { base, apiKey, orgId, fetchImpl? }
+ * @returns {Promise<object>} res frame
+ */
+export async function fetchStrategy(o = {}) {
+  return orgDataGet(o, "strategy", undefined, pickStrategy);
+}
+
+/**
+ * Fetch the org hierarchy over the /v1 read surface (GET /v1/hierarchy). Unlike
+ * the org-data DTO reads above this is the protocol read binding (Bearer token,
+ * BARE payload on 200 per the read contract). Returns the bare
+ * `{ members, reporting }` payload (normalised), or null on any failure
+ * (fail-open). The agent uses it as the authoritative reporting graph.
+ * @param {object} o - { base, token, orgId?, fetchImpl? }
+ * @returns {Promise<{members:object[], reporting:object[]}|null>}
+ */
+export async function fetchHierarchy(o = {}) {
+  const r = await read("hierarchy", o);
+  if (!r.ok || !r.payload) return null;
+  const p = r.payload;
+  const members = Array.isArray(p) ? p : (Array.isArray(p.members) ? p.members : []);
+  const reporting = Array.isArray(p.reporting) ? p.reporting : [];
+  return { members, reporting };
+}
+
+// ---------------------------------------------------------------------------
+// Typed RPC helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * register self with the org (registry.register). Idempotent.
+ * @param {object} entry directory entry (id, displayName, role, focus, pubkey…)
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function register(entry, o = {}) {
+  return call("registry.register", entry || {}, o);
+}
+
+/** Heartbeat the registry liveness (registry.heartbeat). */
+export function heartbeat(params, o = {}) {
+  return call("registry.heartbeat", params || {}, o);
+}
+
+/**
+ * Presence beat (presence.beat) — the result carries directives[] (subset of
+ * DIRECTIVES) incl. the "halt" kill switch when this agent was deactivated.
+ */
+export function presenceBeat(params, o = {}) {
+  return call("presence.beat", params || {}, o);
+}
+
+/** Create a board work-item (board.create). Idempotent. */
+export function createItem(item, o = {}) {
+  return call("board.create", item || {}, o);
+}
+
+/**
+ * Claim a board item (board.claim). The server resolves the race atomically; the
+ * loser gets a CONFLICT error frame. Caller MUST pass a stable idempotencyKey
+ * for safe retries.
+ */
+export function claimItem(params, o = {}) {
+  return call("board.claim", params || {}, o);
+}
+
+/** Complete a board item (board.complete). */
+export function completeItem(params, o = {}) {
+  return call("board.complete", params || {}, o);
+}
+
+/**
+ * List the ready feed (GET /v1/board.ready). Returns the items array, or [] on
+ * any failure (fail-open).
+ * @param {object} o - { base, token, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function listReady(o = {}) {
+  const r = await read("board.ready", o);
+  if (!r.ok || !r.payload) return [];
+  if (Array.isArray(r.payload)) return r.payload;
+  if (Array.isArray(r.payload.items)) return r.payload.items;
+  return [];
+}
+
+/**
+ * Fetch the event slice (GET /v1/events?cursor=N&limit=500). Returns the events
+ * array (or [] on failure). The caller pipes these to verify.verifyEvents.
+ * @param {number} cursor seq to read from (exclusive)
+ * @param {object} o - { base, token, limit?, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function fetchEvents(cursor = 0, o = {}) {
+  const limit = Number.isFinite(o.limit) ? o.limit : 500;
+  const path = `events?cursor=${encodeURIComponent(cursor)}&limit=${encodeURIComponent(limit)}`;
+  const r = await read(path, o);
+  if (!r.ok || !r.payload) return [];
+  if (Array.isArray(r.payload)) return r.payload;
+  if (Array.isArray(r.payload.events)) return r.payload.events;
+  return [];
+}
+
+/**
+ * Fetch the signed snapshot (GET /v1/snapshot). Returns the raw snapshot payload
+ * (with its `sig` envelope) for the detective layer to verify, or null on
+ * failure. Verification is the CALLER's job (verify.verifySnapshot with PINNED
+ * signers) — this function does not trust the server.
+ * @param {object} o - { base, token, fetchImpl? }
+ * @returns {Promise<object|null>}
+ */
+export async function fetchSnapshot(o = {}) {
+  const r = await read("snapshot", o);
+  if (!r.ok || !r.payload) return null;
+  return r.payload;
+}
+
+// ---------------------------------------------------------------------------
+// Phase-2 typed RPC helpers — leases, handoffs, board DAG, governance
+// ---------------------------------------------------------------------------
+//
+// Every helper below is a thin wrapper over call() over the /v1 binding: Bearer
+// auth + x-org-protocol on every request, x-idempotency-key on the side-effecting
+// ones (lease/handoff/board.* are all sideEffecting in the registry, so the
+// caller SHOULD pass a stable `o.idempotencyKey` for safe retries; lease.claim /
+// board.* are non-idempotent in the registry so no key is auto-synthesised — the
+// server resolves the race atomically and the loser gets LEASE_HELD/CONFLICT).
+// All fail open: a disabled/unreachable server yields an error frame, never a
+// throw, so the lease/handoff/board paths can never take down the agent.
+
+// --- leases (one primitive, scope ∈ LEASE_SCOPES) --------------------------
+
+/**
+ * Claim a generic lease (lease.claim). Exactly one holder per (scope,resourceId)
+ * until expiry/release; the loser gets a CONFLICT/LEASE_HELD error frame. The
+ * winning frame carries `{ token, expiresAt, ttlMs }` (token = the bearer for
+ * heartbeat/release; redacted everywhere else).
+ * @param {object} params - { scope, resourceId, holder?, ttlMs? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function leaseClaim(params, o = {}) {
+  return call("lease.claim", params || {}, o);
+}
+
+/**
+ * Extend a held lease (lease.heartbeat). Slides expiry by the original TTL.
+ * @param {object} params - { scope, resourceId, leaseToken }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function leaseHeartbeat(params, o = {}) {
+  return call("lease.heartbeat", params || {}, o);
+}
+
+/**
+ * Release a held lease (lease.release). Frees (scope,resourceId) immediately.
+ * @param {object} params - { scope, resourceId, leaseToken }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function leaseRelease(params, o = {}) {
+  return call("lease.release", params || {}, o);
+}
+
+// --- handoffs (signed delegation lifecycle — ALL governance-gated §0.4) -----
+
+/**
+ * Offer a handoff (handoff.offer). The delegator posts the signed envelope; the
+ * server records a handoff row in state `offered`. governanceGated — returns a
+ * GOVERNANCE_NOT_READY error frame until the server is governance_ready.
+ * @param {object} params - { handoffId, itemId?, to, envelope, envelopeSig, deadlineAt? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function handoffOffer(params, o = {}) {
+  return call("handoff.offer", params || {}, o);
+}
+
+/**
+ * Accept an offered handoff (handoff.accept). The delegatee claims the work.
+ * governanceGated.
+ * @param {object} params - { handoffId }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function handoffAccept(params, o = {}) {
+  return call("handoff.accept", params || {}, o);
+}
+
+/**
+ * Decline an offered handoff (handoff.decline). governanceGated.
+ * @param {object} params - { handoffId, reason? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function handoffDecline(params, o = {}) {
+  return call("handoff.decline", params || {}, o);
+}
+
+/**
+ * Cancel a handoff the caller offered (handoff.cancel). governanceGated.
+ * @param {object} params - { handoffId, reason? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function handoffCancel(params, o = {}) {
+  return call("handoff.cancel", params || {}, o);
+}
+
+// --- board DAG (decompose/assign governance-gated; link not) ----------------
+
+/**
+ * Decompose a board item into children + blocking links (board.decompose).
+ * governanceGated. Server creates the child items and the typed edges in one
+ * transaction (DFS cycle check on insert).
+ * @param {object} params - { itemId, children:[{title,…}], linkType? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function boardDecompose(params, o = {}) {
+  return call("board.decompose", params || {}, o);
+}
+
+/**
+ * Assign an owner to a board item (board.assign). governanceGated (lead-agent +
+ * decision_rights checked server-side).
+ * @param {object} params - { itemId, assignee }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function boardAssign(params, o = {}) {
+  return call("board.assign", params || {}, o);
+}
+
+/**
+ * Link two board items with a typed edge (board.link). NOT governance-gated.
+ * @param {object} params - { fromItem, toItem, linkType? }  (linkType default "blocks"; server contract)
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function boardLink(params, o = {}) {
+  return call("board.link", params || {}, o);
+}
+
+// --- governance ------------------------------------------------------------
+
+/**
+ * Read the governance readiness status (GET-style RPC governance.status).
+ * Non-side-effecting; returns the res frame whose result carries
+ * `{ governanceReady, decisionRightsCount, signingLive, verifiedCards }` (server
+ * shape). Used by the daemon/doctor to know whether handoffs/assignment will flow.
+ * @param {object} o - { base, token, fetchImpl? }
+ */
+export function governanceStatus(o = {}) {
+  return call("governance.status", {}, o);
+}
+
+// ---------------------------------------------------------------------------
+// Phase-3 typed RPC helpers — approvals, decisions, cost, policy
+// ---------------------------------------------------------------------------
+//
+// Same contract as the phase-1/2 helpers: a thin wrapper over call() / read()
+// over the /v1 binding, Bearer + x-org-protocol on every request, and the
+// idempotent side-effecting methods (approval.request / decision.propose /
+// cost.report) get an x-idempotency-key (auto-derived from a stable id when the
+// caller doesn't supply one). All fail open — a disabled/unreachable server
+// yields an error frame, never a throw — so the coordination loop (G16: ZERO LLM
+// calls in any of these paths) can never take down the agent.
+
+// --- approvals (G5 requester != approver; sha256 payload binding) -----------
+
+/**
+ * Request approval for a classified action (approval.request). Idempotent — the
+ * caller MUST pass a stable `o.idempotencyKey` (or `params.id`) so a retried
+ * request reuses the same approval row rather than spawning a duplicate ask.
+ *
+ * The params carry the sha256 `payload_hash` ("the human approved exactly this")
+ * — the server binds the approval to it and rejects a resolve whose executing
+ * payload hash differs. lib/org/approvals.requestApproval computes the hash and
+ * fills this in; call this directly only when you already have the hash.
+ *
+ * @param {object} params - { id?, kind, subject, payload_hash, itemId?, expiresInMs? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function approvalRequest(params, o = {}) {
+  return call("approval.request", params || {}, o);
+}
+
+/**
+ * Resolve (approve/deny) an approval (approval.resolve). Requires the
+ * `approval.decide` scope — approvers/humans only; an ordinary agent token is
+ * rejected with FORBIDDEN_SCOPE. The server ALSO enforces requester != approver
+ * (G5: DB CHECK + method-layer) and re-checks the bound `payload_hash`.
+ * NOT idempotent in the registry; pass a stable `o.idempotencyKey` for retries.
+ *
+ * @param {object} params - { id, decision:'approved'|'denied', reason?, payload_hash? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function approvalResolve(params, o = {}) {
+  return call("approval.resolve", params || {}, o);
+}
+
+/**
+ * Fetch a single approval's current state (approval.get). Non-side-effecting.
+ * @param {object} params - { id }
+ * @param {object} o - { base, token, fetchImpl? }
+ */
+export function approvalGet(params, o = {}) {
+  return call("approval.get", params || {}, o);
+}
+
+/**
+ * List approvals visible to the actor (approval.list). Non-side-effecting.
+ * @param {object} params - { status?, requestedBy?, limit? }
+ * @param {object} o - { base, token, fetchImpl? }
+ */
+export function approvalList(params, o = {}) {
+  return call("approval.list", params || {}, o);
+}
+
+/**
+ * Bounded long-poll for an approval outcome (GET /v1/approval.wait?id=&timeoutMs=).
+ * Resolves when the approval is decided OR the timeout elapses (returning the
+ * CURRENT state either way). `timeoutMs` is clamped to <= 55000 server-side, so
+ * we clamp here too and budget the client abort timeout to outlast it. The
+ * server polls storage on an interval and never holds a DB write lock.
+ *
+ * Returns the standard read shape ({ ok, payload, error, status }); the payload
+ * carries `{ id, status, resolved_by_agent?, resolved_at?, ... }`. Fail-open.
+ *
+ * @param {object} params - { id, timeoutMs? }
+ * @param {object} o - { base, token, fetchImpl? }
+ * @returns {Promise<{ok:boolean, payload?:any, error?:object, status:number}>}
+ */
+export function approvalWait(params, o = {}) {
+  const id = params && params.id;
+  if (!id) return Promise.resolve({ ok: false, error: errFrame("BAD_REQUEST", "missing id").error, status: 0 });
+  const timeoutMs = clampWaitMs(params && params.timeoutMs);
+  const path = `approval.wait?id=${encodeURIComponent(id)}&timeoutMs=${encodeURIComponent(timeoutMs)}`;
+  // The long-poll deliberately outlives the default RPC timeout: give the client
+  // abort a margin over the server's bound so the server gets to return the
+  // timed-out state rather than us aborting first.
+  return read(path, { ...o, timeoutMs: timeoutMs + 5000 });
+}
+
+/** Clamp a long-poll timeout to the protocol-bounded [0, 55000] ms window. */
+function clampWaitMs(ms) {
+  const n = Number(ms);
+  if (!Number.isFinite(n) || n <= 0) return 55000;
+  return Math.min(55000, Math.floor(n));
+}
+
+// --- decisions registry (adopt/supersede governance-gated) ------------------
+
+/**
+ * Propose a decision into the registry (decision.propose). Idempotent — pass a
+ * stable `o.idempotencyKey` (or `params.id`) so a retry reuses the row.
+ * @param {object} params - { id?, title, rationale?, scope?, links? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function decisionPropose(params, o = {}) {
+  return call("decision.propose", params || {}, o);
+}
+
+/**
+ * Adopt a proposed decision (decision.adopt). governanceGated — returns
+ * GOVERNANCE_NOT_READY until the server is governance_ready.
+ * @param {object} params - { id }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function decisionAdopt(params, o = {}) {
+  return call("decision.adopt", params || {}, o);
+}
+
+/**
+ * Supersede an adopted decision with a newer one (decision.supersede).
+ * governanceGated.
+ * @param {object} params - { id, supersededBy }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function decisionSupersede(params, o = {}) {
+  return call("decision.supersede", params || {}, o);
+}
+
+/**
+ * List adopted decisions (GET /v1/decision.list). Returns the decisions array,
+ * or [] on any failure (fail-open).
+ * @param {object} o - { base, token, status?, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function decisionList(o = {}) {
+  const qs = o && o.status ? `?status=${encodeURIComponent(o.status)}` : "";
+  const r = await read(`decision.list${qs}`, o);
+  if (!r.ok || !r.payload) return [];
+  if (Array.isArray(r.payload)) return r.payload;
+  if (Array.isArray(r.payload.decisions)) return r.payload.decisions;
+  return [];
+}
+
+// --- cost rollups (agents report usage; rollups read org-wide) --------------
+
+/**
+ * Report per-session usage into the org rollup (cost.report). Idempotent on the
+ * row id / decision_id — pass a stable `o.idempotencyKey` so a re-pushed batch
+ * never double-counts. The params shape mirrors the maestro router ledger row
+ * (agent, model, input_tokens, output_tokens, estimated_usd, decision_id,
+ * cadence/source) — see lib/org/cost-sync.mjs.
+ * @param {object} params - { rows:[…] } or a single row
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function costReport(params, o = {}) {
+  return call("cost.report", params || {}, o);
+}
+
+/**
+ * Read the org-wide cost rollup (GET /v1/cost.rollup). Aggregated by
+ * agent/model/cadence/day server-side. Returns the bare payload, or null on
+ * failure (fail-open). The payload includes the G16 honesty line: any LLM spend
+ * attributed to a coordination cadence is surfaced here so a violation is visible.
+ * @param {object} o - { base, token, day?, agent?, fetchImpl? }
+ * @returns {Promise<object|null>}
+ */
+export async function costRollup(o = {}) {
+  const params = [];
+  if (o && o.day) params.push(`day=${encodeURIComponent(o.day)}`);
+  if (o && o.agent) params.push(`agent=${encodeURIComponent(o.agent)}`);
+  const qs = params.length ? `?${params.join("&")}` : "";
+  const r = await read(`cost.rollup${qs}`, o);
+  if (!r.ok || !r.payload) return null;
+  return r.payload;
+}
+
+// --- policy distribution (publish admin; fetch via the read surface) --------
+
+/**
+ * Publish a signed policy bundle (policy.publish). ADMIN — reserved namespace,
+ * always requires the `admin` scope; an ordinary agent token is rejected with
+ * FORBIDDEN_SCOPE. Agents FETCH via policyFetch; they never publish.
+ * @param {object} params - { bundleId, version, kind, content, content_sig, source_commit, reload_kind?, rollout? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function policyPublish(params, o = {}) {
+  return call("policy.publish", params || {}, o);
+}
+
+/**
+ * Fetch the current signed policy bundle(s) (GET /v1/policy). Returns the raw
+ * bundle payload (with its `content_sig` envelope) for lib/org/policy.mjs to
+ * verify against the PINNED trust root — this function does NOT trust the server.
+ * Returns null on failure (fail-open).
+ * @param {object} o - { base, token, kind?, fetchImpl? }
+ * @returns {Promise<object|null>}
+ */
+export async function policyFetch(o = {}) {
+  const qs = o && o.kind ? `?kind=${encodeURIComponent(o.kind)}` : "";
+  const r = await read(`policy${qs}`, o);
+  if (!r.ok || !r.payload) return null;
+  return r.payload;
+}
+
+// ---------------------------------------------------------------------------
+// Org credential broker — the single source of truth for org third-party creds
+// ---------------------------------------------------------------------------
+//
+// The payoff of the org plane: an org runs 50-100 agents on separate machines
+// and must NOT provision a DeepSeek/Kimi/OpenAI key onto every one (unmanageable
+// + a breach surface). Instead an admin sets each provider key ONCE in Cohort
+// (credential.put); an agent LEASES it short-lived, role-scoped, and audited
+// (credential.lease) — the org key never persists on the agent machine.
+//
+// Same contract as every other helper: a thin wrapper over call() over the /v1
+// binding, Bearer + x-org-protocol on every request, x-idempotency-key on the
+// side-effecting methods. All fail open — a disabled/unreachable server yields an
+// error frame, never a throw — so a missing org credential surfaces downstream as
+// the router's existing `missing_credential`, never as a crash.
+//
+// SCOPES (frozen in protocol.mjs): credential.put / list / revoke are ADMIN
+// (reserved namespace ⇒ always require `admin`; an ordinary agent token is
+// rejected with FORBIDDEN_SCOPE). credential.lease requires `credential.use`,
+// which IS in DEFAULT_AGENT_SCOPES — so a normal paired agent can lease but never
+// put/list/revoke.
+//
+// SECURITY: credential.lease returns the plaintext ONLY in the response frame
+// (over TLS in prod). credential.list NEVER returns the value (metadata only).
+// The value is NEVER logged anywhere on either side. These helpers MUST NOT
+// persist the leased value to disk; the in-memory cache lives in
+// lib/model-router/org-credentials.mjs, not here.
+
+/**
+ * Lease an org-level third-party credential (credential.lease). Scope
+ * `credential.use` (in DEFAULT_AGENT_SCOPES). The server resolves the caller's
+ * verified identity, checks the credential's allowedRoles/allowedAgents, and —
+ * on success — OPENS the AES-256-GCM box transiently and returns the plaintext
+ * in the result frame ONLY: `{ provider, value, ttlMs, expiresAt, auth_env? }`.
+ * A role/agent the credential does not permit gets FORBIDDEN_SCOPE.
+ *
+ * NOT idempotent in the registry (each lease is a fresh short-lived grant +
+ * audit row); only pass an `o.idempotencyKey` if you explicitly want to coalesce
+ * identical retries. Fail-open: an unreachable server yields an error frame so
+ * the router falls through to whatever local env already has.
+ *
+ * @param {object} params - { provider }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ * @returns {Promise<object>} res frame {ok:true,result:{provider,value,ttlMs,expiresAt}}|{ok:false,error}
+ */
+export function credentialLease(params, o = {}) {
+  return call("credential.lease", params || {}, o);
+}
+
+/**
+ * Set (upsert) an org-level third-party credential (credential.put). ADMIN —
+ * reserved namespace, always requires the `admin` scope; an ordinary agent token
+ * is rejected with FORBIDDEN_SCOPE. The admin sets each provider key ONCE; the
+ * server SEALS the value at rest (AES-256-GCM) and never logs it. Idempotent on
+ * `provider` — pass a stable `o.idempotencyKey` (auto-derived from
+ * `params.provider` when absent) so a re-pushed key collapses to one rotation.
+ *
+ * @param {object} params - { provider, value, auth_env?, allowedRoles?, allowedAgents?, ttlMs? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function credentialPut(params, o = {}) {
+  const opts = o;
+  if (!opts.idempotencyKey && params && params.provider) {
+    opts.idempotencyKey = `credential.put:${params.provider}`;
+  }
+  return call("credential.put", params || {}, opts);
+}
+
+/**
+ * List org credentials' METADATA (credential.list). ADMIN. NEVER returns the
+ * value — only provider, auth_env, allowedRoles/allowedAgents, ttl, timestamps.
+ * Non-side-effecting. Returns the res frame; the caller reads `result.credentials`.
+ * @param {object} params - { provider? }
+ * @param {object} o - { base, token, fetchImpl? }
+ */
+export function credentialList(params, o = {}) {
+  return call("credential.list", params || {}, o);
+}
+
+/**
+ * Revoke an org credential (credential.revoke). ADMIN. Future leases for the
+ * provider fail; already-leased values expire at their TTL (the org key never
+ * persisted on the agent, so revoke + TTL is the bound on exposure). NOT
+ * idempotent in the registry; pass a stable `o.idempotencyKey` for retries.
+ * @param {object} params - { provider, reason? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function credentialRevoke(params, o = {}) {
+  return call("credential.revoke", params || {}, o);
+}
+
+// ---------------------------------------------------------------------------
+// Phase-4 typed RPC helpers — knowledge plane, contacts, meetings
+// ---------------------------------------------------------------------------
+//
+// The agent half of the shared knowledge plane (SPEC-org-server §4.7). Same
+// contract as the phase-1/2/3 helpers: a thin wrapper over call() / read() over
+// the /v1 binding, Bearer + x-org-protocol on every request, x-idempotency-key
+// on the idempotent side-effecting methods (knowledge.append / contacts.upsert /
+// meetings.record — auto-derived from a stable id when the caller doesn't supply
+// one). All fail open — a disabled/unreachable server yields an error frame,
+// never a throw.
+//
+// CRITICAL — the SERVER is authoritative for ACL. These helpers NEVER decide
+// what a fact's group is, never filter a search result, and never inspect a
+// barrier cell. The non-bypassable RLS floor (group membership, barrier:<cell>
+// deny-override, participant-derived ACLs) lives in the server's query layer.
+// The client only renders what the server chose to return. knowledge.search is
+// SIDE-EFFECTING by contract: every retrieval is logged to org_events family
+// 'knowledge' (the regulator-facing read-audit trail) — so it carries the same
+// idempotency/Bearer treatment as a write, not a read.
+
+// --- knowledge facts (mutable-artifact semantics) --------------------------
+
+/**
+ * Append a knowledge episode (knowledge.append). THE sole shared-write primitive;
+ * commutes (concurrent appends both land) and is IDEMPOTENT — pass a stable
+ * `o.idempotencyKey` (or `params.id`) so a retried append doesn't double-write.
+ * The server assigns the fact's group from the caller's verified identity / the
+ * supplied `group` hint subject to the RLS floor — the client never decides ACL.
+ * @param {object} params - { id?, group?, text, kind?, participants?, provenance?, links?, refs? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function knowledgeAppend(params, o = {}) {
+  return call("knowledge.append", params || {}, o);
+}
+
+/**
+ * Replace a fact via compare-and-swap on its version (knowledge.replace). The
+ * server rejects a stale CAS with CONFLICT. NOT idempotent in the registry; pass
+ * a stable `o.idempotencyKey` for safe retries.
+ * @param {object} params - { id, expectedVersion, text, group?, provenance? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function knowledgeReplace(params, o = {}) {
+  return call("knowledge.replace", params || {}, o);
+}
+
+/**
+ * Rewrite a fact in place (knowledge.rewrite) — DESIGNATED-OWNER-ONLY. The server
+ * rejects a non-owner with FORBIDDEN_SCOPE / a method-layer owner check. NOT
+ * idempotent; pass a stable `o.idempotencyKey` for retries.
+ * @param {object} params - { id, text, group?, provenance? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function knowledgeRewrite(params, o = {}) {
+  return call("knowledge.rewrite", params || {}, o);
+}
+
+/**
+ * Invalidate a fact (knowledge.invalidate) — INVALIDATE, DON'T DELETE. Marks the
+ * fact invalid (provenance + tombstone) and excludes it from future search; the
+ * row PERSISTS for audit and provenance/blast-radius queries. NOT idempotent;
+ * pass a stable `o.idempotencyKey` for retries.
+ * @param {object} params - { id, reason?, supersededBy? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function knowledgeInvalidate(params, o = {}) {
+  return call("knowledge.invalidate", params || {}, o);
+}
+
+/**
+ * Search the ACL'd shared facts (knowledge.search). SIDE-EFFECTING by contract:
+ * every retrieval appends a 'knowledge' org_events row capturing
+ * {agent, query, returned_ids, groups_considered} — the read-audit trail. The
+ * SERVER applies the RLS floor and returns ONLY the facts this agent's verified
+ * groups may see (barrier:<cell> deny-override); the client does not filter. NOT
+ * idempotent in the registry (each search is a distinct audited retrieval) — only
+ * pass an `o.idempotencyKey` if you explicitly want to coalesce identical retries.
+ * @param {object} params - { query, group?, limit?, includeInvalid?, kind? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ * @returns {Promise<object>} res frame whose result carries { facts:[…], returned_ids:[…], groups_considered:[…] }
+ */
+export function knowledgeSearch(params, o = {}) {
+  return call("knowledge.search", params || {}, o);
+}
+
+// --- contacts registry (ACL-filtered) --------------------------------------
+
+/**
+ * Upsert an org contact (contacts.upsert). Idempotent — pass a stable
+ * `o.idempotencyKey` (or `params.id`) so a re-pushed contact collapses to one row.
+ * @param {object} params - { id?, name?, emails?, phones?, handles?, org?, group?, fields? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function contactsUpsert(params, o = {}) {
+  return call("contacts.upsert", params || {}, o);
+}
+
+/**
+ * List org contacts visible to the actor (GET /v1/contacts.list). The server
+ * ACL-filters; returns the contacts array, or [] on any failure (fail-open).
+ * @param {object} o - { base, token, q?, group?, limit?, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function contactsList(o = {}) {
+  const params = [];
+  if (o && o.q) params.push(`q=${encodeURIComponent(o.q)}`);
+  if (o && o.group) params.push(`group=${encodeURIComponent(o.group)}`);
+  if (o && Number.isFinite(o.limit)) params.push(`limit=${encodeURIComponent(o.limit)}`);
+  const qs = params.length ? `?${params.join("&")}` : "";
+  const r = await read(`contacts.list${qs}`, o);
+  if (!r.ok || !r.payload) return [];
+  if (Array.isArray(r.payload)) return r.payload;
+  if (Array.isArray(r.payload.contacts)) return r.payload.contacts;
+  return [];
+}
+
+// --- meetings registry (ACL-filtered) --------------------------------------
+
+/**
+ * Record a meeting (meetings.record). Idempotent — pass a stable
+ * `o.idempotencyKey` (or `params.id`) so a re-pushed meeting collapses to one row.
+ * @param {object} params - { id?, title?, at?, participants?, notes?, group?, refs?, fields? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function meetingsRecord(params, o = {}) {
+  return call("meetings.record", params || {}, o);
+}
+
+/**
+ * List org meetings visible to the actor (GET /v1/meetings.list). The server
+ * ACL-filters (participant-derived ACL); returns the meetings array, or [] on any
+ * failure (fail-open).
+ * @param {object} o - { base, token, q?, group?, since?, limit?, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function meetingsList(o = {}) {
+  const params = [];
+  if (o && o.q) params.push(`q=${encodeURIComponent(o.q)}`);
+  if (o && o.group) params.push(`group=${encodeURIComponent(o.group)}`);
+  if (o && o.since) params.push(`since=${encodeURIComponent(o.since)}`);
+  if (o && Number.isFinite(o.limit)) params.push(`limit=${encodeURIComponent(o.limit)}`);
+  const qs = params.length ? `?${params.join("&")}` : "";
+  const r = await read(`meetings.list${qs}`, o);
+  if (!r.ok || !r.payload) return [];
+  if (Array.isArray(r.payload)) return r.payload;
+  if (Array.isArray(r.payload.meetings)) return r.payload.meetings;
+  return [];
+}
+
+// ---------------------------------------------------------------------------
+// Messaging + calling (SP3/SP10) — participate in the org's human messaging app
+// ---------------------------------------------------------------------------
+//
+// The agent half of the messaging.*/calling.* surface (protocol.mjs). Same
+// contract as every other helper: a thin wrapper over call() / read() over the
+// /v1 binding, Bearer + x-org-protocol on every request, x-idempotency-key on the
+// idempotent side-effecting methods (messaging.send is idempotent on the
+// client-supplied message id; calling.* are not, so pass a stable key only when
+// you want to coalesce retries). All fail open — a disabled/unreachable server
+// yields an error frame, never a throw.
+//
+// These are the RAW RPC wrappers. The POLICY + TELEMETRY layer (the send-gate
+// chokepoint, the afterSend hook, and the source="messaging" cost attribution)
+// lives in lib/org/messaging.mjs, which composes these. Outbound CONTENT sends
+// should go through lib/org/messaging.sendMessage, NOT messagingSend directly,
+// so the send-gate is never bypassed.
+
+/** Post a message to an org channel (messaging.send). Idempotent on the message id. */
+export function messagingSend(params, o = {}) {
+  return call("messaging.send", params || {}, o);
+}
+
+/** React to an org message (messaging.react). */
+export function messagingReact(params, o = {}) {
+  return call("messaging.react", params || {}, o);
+}
+
+/** Edit an org message the agent sent (messaging.edit). */
+export function messagingEdit(params, o = {}) {
+  return call("messaging.edit", params || {}, o);
+}
+
+/** Read channel history (messaging.history). Read scope, non-mutating. */
+export function messagingHistory(params, o = {}) {
+  return call("messaging.history", params || {}, o);
+}
+
+/** List the org channels visible to this agent (messaging.channels). Read scope. */
+export function messagingChannels(params, o = {}) {
+  return call("messaging.channels", params || {}, o);
+}
+
+/** Start a call (calling.start). */
+export function callingStart(params, o = {}) {
+  return call("calling.start", params || {}, o);
+}
+
+/** Join a call (calling.join). */
+export function callingJoin(params, o = {}) {
+  return call("calling.join", params || {}, o);
+}
+
+/** Invite participants to a call (calling.invite). */
+export function callingInvite(params, o = {}) {
+  return call("calling.invite", params || {}, o);
+}
+
+/** End a call (calling.end). */
+export function callingEnd(params, o = {}) {
+  return call("calling.end", params || {}, o);
+}
+
+/**
+ * Append one finalized transcript line to a live call (calling.addTranscriptLine).
+ * Agent-operability write: the server persists a CallTranscriptLine projection row
+ * (speaker = the acting member) and appends ONE redacted `calling` event — the
+ * chain records line metadata (callId, memberId, ts) but NEVER the text (spec §3).
+ * The actor must be a participant in a still-live call. Side-effecting.
+ * @param {{callId:string, text:string}} params
+ * @param {object} o - { base, token, orgId?, idempotencyKey?, fetchImpl? }
+ */
+export function callingAddTranscriptLine(params, o = {}) {
+  return call("calling.addTranscriptLine", params || {}, o);
+}
+
+/**
+ * Post one message to a live call's in-call chat panel (calling.chat). Same
+ * contract as addTranscriptLine: one CallChatMessage projection row + one redacted
+ * `calling` event (metadata only, never the body). Participant-gated. Side-effecting.
+ * @param {{callId:string, text:string}} params
+ * @param {object} o - { base, token, orgId?, idempotencyKey?, fetchImpl? }
+ */
+export function callingChat(params, o = {}) {
+  return call("calling.chat", params || {}, o);
+}
+
+// ---------------------------------------------------------------------------
+// Calling working sessions + vision fusion (2026-08)
+// ---------------------------------------------------------------------------
+//
+// The app-share surface: an AI participant "presents" a Cohort surface
+// (doc/sheet/channel/board/charter) on the call stage, rendered locally by
+// every client and driven by step frames over the room data lane. The three
+// writes persist a CallShareSession projection and append REDACTED share.*
+// events (ids/counts only — never step text or doc content); the three reads
+// hydrate late joiners, the narrated visual stream, and recent non-speech call
+// events. Same thin fail-open call() wrappers as the rest of calling.*.
+
+/**
+ * Start presenting a Cohort surface on a live call (calling.appShareStart).
+ * One active session per call: your own previous session is superseded; a
+ * CONFLICT frame comes back while another member is presenting. Appends ONE
+ * redacted `share.started` event and publishes the state frame to the room.
+ * The actor must be a participant in a still-live call. Side-effecting.
+ * @param {{callId:string, surface:{kind:string, ref:string, title?:string}}} params
+ * @param {object} o - { base, token, orgId?, idempotencyKey?, fetchImpl? }
+ */
+export function callingAppShareStart(params, o = {}) {
+  return call("calling.appShareStart", params || {}, o);
+}
+
+/**
+ * Drive the active share with a step batch (calling.appShareAct): cursor /
+ * scroll / highlight / type / refresh, ≤20 steps per call. Steps animate the
+ * tile on every client; the chain records ONE redacted `share.acted` event
+ * ({sessionId, stepCount} — never the step text). Session must be active and
+ * owned by the acting member. Side-effecting.
+ * @param {{callId:string, sessionId:string, steps:Array<object>}} params
+ * @param {object} o - { base, token, orgId?, idempotencyKey?, fetchImpl? }
+ */
+export function callingAppShareAct(params, o = {}) {
+  return call("calling.appShareAct", params || {}, o);
+}
+
+/**
+ * End the active share session (calling.appShareEnd). Sharer or call host.
+ * Appends one redacted `share.ended` event and clears the stage tile.
+ * Side-effecting.
+ * @param {{callId:string, sessionId:string, reason?:('ended'|'superseded')}} params
+ * @param {object} o - { base, token, orgId?, idempotencyKey?, fetchImpl? }
+ */
+export function callingAppShareEnd(params, o = {}) {
+  return call("calling.appShareEnd", params || {}, o);
+}
+
+/**
+ * The call's active share session, or null (calling.getAppShare) — what a late
+ * joiner renders: {sessionId, by, surface, startedAt, state}. Read-style.
+ * @param {{callId:string}} params
+ * @param {object} o - { base, token, orgId?, fetchImpl? }
+ */
+export function callingGetAppShare(params, o = {}) {
+  return call("calling.getAppShare", params || {}, o);
+}
+
+/**
+ * The narrated visual stream for a call (calling.getVisualContext): the last N
+ * CallVisualEvent rows ({kind, sourceMemberId, summary, at}, chronological,
+ * limit ≤50 default 20). Narration TEXT only — frames are never persisted
+ * server-side. Read-style.
+ * @param {{callId:string, limit?:number}} params
+ * @param {object} o - { base, token, orgId?, fetchImpl? }
+ */
+export function callingGetVisualContext(params, o = {}) {
+  return call("calling.getVisualContext", params || {}, o);
+}
+
+/**
+ * Recent non-speech call events (calling.getCallEvents): reactions, raised /
+ * lowered hands, joins and share.* lifecycle, mapped {kind, actorId, at,
+ * payload} (payloads already redacted), limit ≤100 default 30. Read-style.
+ * @param {{callId:string, limit?:number}} params
+ * @param {object} o - { base, token, orgId?, fetchImpl? }
+ */
+export function callingGetCallEvents(params, o = {}) {
+  return call("calling.getCallEvents", params || {}, o);
+}
+
+// ---------------------------------------------------------------------------
+// Pairing admin approval (authed)
+// ---------------------------------------------------------------------------
+//
+// pairRequest() (above) is the pre-auth half of the handshake. pairApprove is
+// the ADMIN half: an already-paired admin agent resolves a pending request by
+// code. Reserved-admin namespace ⇒ the dispatcher enforces `admin` scope. Thin
+// authed call() wrapper (Bearer + x-org-protocol; the request is side-effecting).
+
+/**
+ * Approve a pending pairing request by code (pairing.approve). Admin scope.
+ * Flips the PairingRequest pending→approved server-side (CONFLICT if already
+ * resolved) and appends one `pairing` event. Side-effecting.
+ * @param {{code:string}} params
+ * @param {object} o - { base, token, orgId?, idempotencyKey?, fetchImpl? }
+ */
+export function pairApprove(params, o = {}) {
+  return call("pairing.approve", params || {}, o);
+}
+
+// ---------------------------------------------------------------------------
+// Branding (Brand Studio v2 write surface) — agent mirror of the human
+// branding-generation / brand-templates / brand-export server actions.
+// ---------------------------------------------------------------------------
+//
+// Thin call() wrappers over the branding.* RPCs (protocol.mjs). Writes require
+// ADMIN (the server mirrors requireWorkspaceRole("ADMIN")); the two reads
+// (listVersions/exportTemplate) use org.read. The branding surface owns its OWN
+// versioned mutation + audit (the BrandVersion spine + self-appended events), so
+// these methods are sideEffecting:false at the dispatcher layer — no
+// x-idempotency-key is derived. Fail-open like every other wrapper.
+
+/** Regenerate the workspace brand system / registry copy (branding.regenerate). Admin. */
+export function brandingRegenerate(params, o = {}) {
+  return call("branding.regenerate", params || {}, o);
+}
+
+/** Kick off the bespoke-template pipeline for the workspace (branding.regenerateTemplates). Admin. */
+export function brandingRegenerateTemplates(params, o = {}) {
+  return call("branding.regenerateTemplates", params || {}, o);
+}
+
+/** Regenerate ONE bespoke template by slug (branding.regenerateTemplate). Admin. @param {{slug:string}} params */
+export function brandingRegenerateTemplate(params, o = {}) {
+  return call("branding.regenerateTemplate", params || {}, o);
+}
+
+/** Regenerate all canonical brand image slots (branding.regenerateImages). Admin. */
+export function brandingRegenerateImages(params, o = {}) {
+  return call("branding.regenerateImages", params || {}, o);
+}
+
+/** Set a brand image slot from a data URL (branding.uploadImage). Admin. @param {{slot:string, dataUrl:string}} params */
+export function brandingUploadImage(params, o = {}) {
+  return call("branding.uploadImage", params || {}, o);
+}
+
+/** AI-amend one registry-copy surface (branding.amendArtifact). Admin. @param {{key:string, instruction:string, elementRef?:string}} params */
+export function brandingAmendArtifact(params, o = {}) {
+  return call("branding.amendArtifact", params || {}, o);
+}
+
+/** AI-amend a CLONE/GENERATED template's copy (branding.amendTemplate). Admin. @param {{slug:string, instruction:string, elementRef?:string}} params */
+export function brandingAmendTemplate(params, o = {}) {
+  return call("branding.amendTemplate", params || {}, o);
+}
+
+/** Clone a registry/generated template into a new CLONE (branding.cloneTemplate). Admin. @param {{baseRef:string}} params */
+export function brandingCloneTemplate(params, o = {}) {
+  return call("branding.cloneTemplate", params || {}, o);
+}
+
+/** Soft-delete a CLONE/GENERATED template by slug (branding.deleteTemplate). Admin. @param {{slug:string}} params */
+export function brandingDeleteTemplate(params, o = {}) {
+  return call("branding.deleteTemplate", params || {}, o);
+}
+
+/** Restore a versioned brand target to a specific seq (branding.restoreVersion). Admin. @param {{targetKind:"ARTIFACT"|"TEMPLATE", ref:string, seq:number}} params */
+export function brandingRestoreVersion(params, o = {}) {
+  return call("branding.restoreVersion", params || {}, o);
+}
+
+/** Move a versioned brand target's head to the previous version (branding.undo). Admin. @param {{targetKind:"ARTIFACT"|"TEMPLATE", ref:string}} params */
+export function brandingUndo(params, o = {}) {
+  return call("branding.undo", params || {}, o);
+}
+
+/** Move a versioned brand target's head to the next version (branding.redo). Admin. @param {{targetKind:"ARTIFACT"|"TEMPLATE", ref:string}} params */
+export function brandingRedo(params, o = {}) {
+  return call("branding.redo", params || {}, o);
+}
+
+/** Read the version history of a versioned brand target (branding.listVersions). org.read. @param {{targetKind:"ARTIFACT"|"TEMPLATE", ref:string}} params */
+export function brandingListVersions(params, o = {}) {
+  return call("branding.listVersions", params || {}, o);
+}
+
+/** Deterministic key-free server render of a READY template to a PNG data URL (branding.exportTemplate). org.read. @param {{templateId:string, sizeId?:"mobile"|"tablet"|"desktop", theme?:"light"|"dark"}} params */
+export function brandingExportTemplate(params, o = {}) {
+  return call("branding.exportTemplate", params || {}, o);
+}
+
+// --- Design read/propose surface (2026-07) ---------------------------------
+//
+// The ten methods below are the half of the family an ORDINARY agent seat can
+// reach: `design.read` for the foundation/voice/template reads and the three
+// costed producers (renderTemplate / rewriteInVoice / exportKit), `design.write`
+// for generateImage + proposeChange. Foundation MUTATIONS stay human-gated
+// (DECISIONS D-7): proposeChange stages a reviewable diff and writes nothing,
+// while saveFoundation / restoreFoundation are `admin` and only an admin
+// credential reaches them at all.
+//
+// The costed methods (renderTemplate, exportKit, generateImage, rewriteInVoice)
+// return their spend — surface it. `generateImage` with `budgetCents: 0` is the
+// QUOTE call: it generates nothing, spends nothing, and still returns every
+// slot's price and staleness.
+
+/** The workspace brand foundation + version-history head (branding.getFoundation). design.read. @param {{versionId?:string, historyLimit?:number}} params */
+export function brandingGetFoundation(params, o = {}) {
+  return call("branding.getFoundation", params || {}, o);
+}
+
+/** Voice statement, traits, SAY/AVOID lexicon, in-practice examples (branding.getVoice). design.read. */
+export function brandingGetVoice(params, o = {}) {
+  return call("branding.getVoice", params || {}, o);
+}
+
+/** The template gallery with per-template status chips (branding.listTemplates). design.read. @param {{visibleOnly?:boolean, category?:"digital"|"print"|"email"|"social"|"og"}} params */
+export function brandingListTemplates(params, o = {}) {
+  return call("branding.listTemplates", params || {}, o);
+}
+
+/** Render a template to HTML (any) or PNG (GENERATED only) (branding.renderTemplate). design.read, costed. @param {{templateId:string, theme?:string, size?:string, format?:"html"|"png", content?:object, budgetCents?:number}} params */
+export function brandingRenderTemplate(params, o = {}) {
+  return call("branding.renderTemplate", params || {}, o);
+}
+
+/** Rewrite a sentence in the workspace brand voice (branding.rewriteInVoice). design.read, costed. Produces copy; sends nothing. @param {{text:string, subject?:string}} params */
+export function brandingRewriteInVoice(params, o = {}) {
+  return call("branding.rewriteInVoice", params || {}, o);
+}
+
+/** Export the brand kit — tokens, voice, and (by default) the mark bytes (branding.exportKit). design.read, costed. @param {{unit?:"px"|"rem"|"em", includeMarks?:boolean, versionId?:string, budgetCents?:number}} params */
+export function brandingExportKit(params, o = {}) {
+  return call("branding.exportKit", params || {}, o);
+}
+
+/** Regenerate canonical brand image slots; omit `slots` for every STALE slot, `budgetCents:0` to QUOTE only (branding.generateImage). design.write, costed. @param {{slots?:string[], force?:boolean, budgetCents?:number}} params */
+export function brandingGenerateImage(params, o = {}) {
+  return call("branding.generateImage", params || {}, o);
+}
+
+/** Stage a REVIEWABLE foundation diff — writes nothing to the foundation (branding.proposeChange). design.write. Blocks are replaced wholesale: send each COMPLETE block. @param {{patch:object, note?:string, rationale?:string, expectedVersionId?:string|null}} params */
+export function brandingProposeChange(params, o = {}) {
+  return call("branding.proposeChange", params || {}, o);
+}
+
+/** Save the brand foundation (branding.saveFoundation). ADMIN — an ordinary agent seat proposes instead. @param {{foundation:object, expectedVersionId?:string|null, note?:string}} params */
+export function brandingSaveFoundation(params, o = {}) {
+  return call("branding.saveFoundation", params || {}, o);
+}
+
+/** Restore a historical foundation version as a NEW version (branding.restoreFoundation). ADMIN. @param {{versionId:string, note?:string, expectedVersionId?:string|null}} params */
+export function brandingRestoreFoundation(params, o = {}) {
+  return call("branding.restoreFoundation", params || {}, o);
+}
+
+// ---------------------------------------------------------------------------
+// Back-compat surface (drop-in for lib/org/cohort-client.mjs)
+// ---------------------------------------------------------------------------
+
+/**
+ * Project a maestro directory entry (assembleSelfEntry shape — id, name,
+ * fullName, archetype{object}, towers, focus, presence, …) onto the params that
+ * hq's `registry.register` accepts. The server schema is `.strict()` and only
+ * models { displayName, archetype:string, humanSponsor, card } — so we MUST trim
+ * here or a rich entry 400s (BAD_REQUEST). Everything the server doesn't model is
+ * preserved REDACTION-SAFE under `card` (the handler records only a `hasCard`
+ * boolean on the chain, never the blob). Pure; never throws.
+ * @param {object} entry
+ * @returns {object} registerSchema-shaped params
+ */
+function entryToRegisterParams(entry) {
+  const e = entry || {};
+  const displayName = e.fullName || e.name || e.displayName || String(e.id || "");
+  // archetype is an object in the maestro entry ({function,altitude,label}); the
+  // server wants a single string. Prefer the human label, then the function.
+  const arch = e.archetype;
+  const archetype =
+    typeof arch === "string"
+      ? arch
+      : (arch && (arch.label || arch.function || arch.altitude)) || "";
+  const humanSponsor =
+    (e.principal && (e.principal.fullName || e.principal.title)) || e.humanSponsor || "";
+  const params = { card: e };
+  if (displayName) params.displayName = String(displayName).slice(0, 200);
+  if (archetype) params.archetype = String(archetype).slice(0, 120);
+  if (humanSponsor) params.humanSponsor = String(humanSponsor).slice(0, 200);
+  return params;
+}
+
+/**
+ * Publish (upsert) this agent's directory entry — now via the /v1 binding
+ * (registry.register), preserving the legacy return shape `{ok,status}` /
+ * `{ok:false,skipped:true}` so existing callers (org-sync) don't break. The rich
+ * maestro entry is projected onto the server's strict registerSchema (extra
+ * fields ride under `card`, chain-redacted to a `hasCard` flag). Carries the
+ * derived idempotency key + optional x-org-id pin. Fail-open.
+ * @param {object} o - { cfg, entry, fetchImpl? }
+ * @returns {Promise<{ok:boolean, status?:number, skipped?:boolean, reason?:string}>}
+ */
+export async function publishEntry(o = {}) {
+  const { cfg, entry } = o;
+  if (!isEnabled(cfg)) return { ok: false, skipped: true };
+  if (!entry || !entry.id) return { ok: false, skipped: false, reason: "no-entry" };
+  const c = configFromAgent(cfg);
+  const frame = await register(entryToRegisterParams(entry), {
+    base: c.base,
+    token: c.token,
+    orgId: c.orgId,
+    idempotencyKey: `registry.register:${entry.id}`,
+    fetchImpl: o.fetchImpl,
+  });
+  return { ok: !!(frame && frame.ok), status: frame && frame.ok ? 200 : 0 };
+}
+
+/**
+ * Fetch the live org directory — now via GET /v1/directory, preserving the
+ * legacy contract (returns [] when disabled or on any error). Parses the array,
+ * the hq `{members:[…]}` shape (each member carries its latest presence.beat
+ * status snapshot per-member), and the legacy `{agents:[…]}` shape.
+ * @param {object} o - { cfg, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function fetchDirectory(o = {}) {
+  const { cfg } = o;
+  if (!isEnabled(cfg)) return [];
+  const c = configFromAgent(cfg);
+  const r = await read("directory", { base: c.base, token: c.token, orgId: c.orgId, fetchImpl: o.fetchImpl });
+  if (!r.ok || !r.payload) return [];
+  if (Array.isArray(r.payload)) return r.payload;
+  if (Array.isArray(r.payload.members)) return r.payload.members;
+  if (Array.isArray(r.payload.agents)) return r.payload.agents;
+  return [];
+}