@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/scripts/ci/conformance-org-api.mjs

@@ -0,0 +1,792 @@
+#!/usr/bin/env node
+/**
+ * conformance-org-api.mjs — the LIVE wire-contract conformance probe.
+ *
+ * WHY THIS CANNOT BE A UNIT TEST
+ * ------------------------------
+ * hq validates every `/v1/<method>` body with a zod schema that does NOT ship to
+ * the SDK. `lib/org/param-contract.mjs` is this side's best transcription of
+ * those schemas — and a transcription cannot prove itself right. The 2026-08
+ * audit found 18 methods where the name the SDK sent and the name hq reads had
+ * diverged; every one of them passed `npm test` on the day it shipped, because
+ * both halves of the mistake lived on this side of the wire.
+ *
+ * So: drive a REAL org. Call each method with a minimal, well-formed payload and
+ * read the server's own verdict.
+ *
+ * THE DISCRIMINATOR (the whole idea)
+ * ----------------------------------
+ * A probe against a live org gets errors for perfectly legitimate reasons — the
+ * key has no scope for that family, the placeholder id doesn't exist, governance
+ * isn't ready. Those are NOT failures. Exactly one class of error is:
+ *
+ *   BAD_REQUEST citing a param name we did not send   → hq requires a name we
+ *                                                       don't know about (FAIL)
+ *   BAD_REQUEST "Unrecognized key(s): 'x'" for a key
+ *   we DID send                                       → hq's schema is .strict()
+ *                                                       and rejects our name (FAIL)
+ *   BAD_REQUEST citing a param we DID send            → a VALUE complaint about
+ *                                                       our placeholder (warn)
+ *   FORBIDDEN_SCOPE / NOT_FOUND / CONFLICT /
+ *   UNAUTHORIZED / GOVERNANCE_NOT_READY / RATE_LIMITED → the schema PASSED; the
+ *                                                       handler then refused for
+ *                                                       an unrelated reason (skip)
+ *   ok:true                                           → pass
+ *
+ * `classifyFrame` is pure and unit-tested (`conformance-org-api.test.mjs`); the
+ * network is just how it gets its input.
+ *
+ * SAFETY — why this is not a write tool
+ * -------------------------------------
+ * Validation runs BEFORE the handler touches the database, so a side-effecting
+ * method can be probed harmlessly by pointing it at an entity that cannot exist:
+ * zod validates (the thing under test), the handler then 404s (the thing we
+ * ignore) and nothing is written. Every default probe is either read-scope or
+ * gated behind a `probe-<uuid>` id of that kind — marked `writes: false`.
+ *
+ * Probes that WOULD durably create a row (decision.propose, board.createTask,
+ * knowledge.append, memory.author, approval.request, lease.claim,
+ * registry.register — the ones with no entity reference to poison) are marked
+ * `writes: true` and are SKIPPED unless `--write` is passed. Outbound-content
+ * methods are never probed at all: a `messaging.send` probe is safe only because
+ * its channel does not exist, and that is asserted, not assumed.
+ *
+ * USAGE
+ *   node scripts/ci/conformance-org-api.mjs                 # read-safe probes
+ *   node scripts/ci/conformance-org-api.mjs --write         # + row-creating probes
+ *   node scripts/ci/conformance-org-api.mjs --json          # machine-readable
+ *   node scripts/ci/conformance-org-api.mjs --verbose       # every verdict
+ *   node scripts/ci/conformance-org-api.mjs --only=messaging,board
+ *   node scripts/ci/conformance-org-api.mjs --agent-root=/path/to/agent
+ *
+ * CREDENTIALS resolve exactly as the runtime does (lib/org/client#configFromAgent):
+ *   COHORT_BASE / COHORT_API_URL → config base → https://os.cohortapp.com
+ *   COHORT_API_TOKEN / COHORT_TOKEN / COHORT_API_KEY
+ *   COHORT_ORG_ID
+ * With no credentials the probe SKIPS cleanly (exit 0) so it can sit in a CI job
+ * that has no org secret — it is a gate for the environments that do.
+ *
+ * EXIT CODES: 0 = no drift (or skipped), 1 = drift found, 2 = bad invocation.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module scripts/ci/conformance-org-api
+ */
+
+"use strict";
+
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { call, read, loadOrgConfig, configFromAgent } from "../../lib/org/client.mjs";
+import { READS, methodDef } from "../../lib/org/protocol.mjs";
+import { PARAM_CONTRACT, normalizeParams } from "../../lib/org/param-contract.mjs";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** Error codes that mean "your params were fine, the request was refused later". */
+export const SCHEMA_PASSED_CODES = new Set([
+  "FORBIDDEN_SCOPE",
+  "NOT_FOUND",
+  "CONFLICT",
+  "GOVERNANCE_NOT_READY",
+  "RATE_LIMITED",
+  "LEASE_HELD",
+  "IDEMPOTENT_REPLAY",
+]);
+
+/**
+ * Codes that mean "we never actually tested anything".
+ *
+ * UNAUTHORIZED used to sit in the set above, and it is what hq returns for a bad
+ * bearer key on EVERY method and every GET read. So a rotated or revoked
+ * COHORT_API_TOKEN made all 36 method probes `skip`, all 12 read probes `pass`,
+ * and the run print "No wire-contract drift." and exit 0 — forever, while
+ * probing nothing. A gate that greens on a dead credential is worse than no
+ * gate, because it is trusted. The no-credential path was already loud; this is
+ * the bad-credential path, which was silent and indistinguishable from success.
+ */
+export const CREDENTIAL_FAILURE_CODES = new Set(["UNAUTHORIZED"]);
+
+/**
+ * An id shaped like ours but which CANNOT exist — the safety primitive that makes
+ * probing a side-effecting method harmless. The literal "probe" marker is load-
+ * bearing: the safety test greps for it, and an operator seeing one in a log
+ * knows instantly it came from here.
+ * @param {string} [kind]
+ * @returns {string}
+ */
+export function ghostId(kind = "id") {
+  return `probe-${kind}-${randomUUID()}`;
+}
+
+/** Does this payload reference a ghost id anywhere? Pure (safety assertion). */
+export function referencesGhost(params) {
+  try {
+    return JSON.stringify(params || {}).includes("probe-");
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// verdict classification (PURE — the unit-tested core)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pull the param names an hq error message is complaining about.
+ *
+ * hq produces four shapes:
+ *   zod via parse():   "channelId: Required"  /  "why.reason: Required"
+ *   zod strict:        "Unrecognized key(s) in object: 'note', 'stray'"
+ *   manual guards:     "title is required"  /  "actionClass is required"
+ *   enum guards:       "memoryClass must be one of: framework, …"
+ *
+ * @param {string} message
+ * @returns {{cited:string[], unrecognized:string[]}}
+ */
+export function citedParams(message) {
+  const msg = String(message || "");
+  const cited = new Set();
+  const unrecognized = new Set();
+
+  // zod .strict(): "Unrecognized key(s) in object: 'note', 'stray'"
+  const unrec = msg.match(/Unrecognized key\(s\)[^:]*:\s*(.+)$/i);
+  if (unrec) {
+    for (const m of unrec[1].matchAll(/['"`]([A-Za-z0-9_]+)['"`]/g)) unrecognized.add(m[1]);
+  }
+
+  // zod path prefix: "channelId: Required" / "participantIds.0: Required"
+  const path = msg.match(/^([A-Za-z_][A-Za-z0-9_]*)(?:\.[A-Za-z0-9_]+)*\s*:/);
+  if (path) cited.add(path[1]);
+
+  // manual guards: "<name> is required" / "<name> must be …"
+  for (const m of msg.matchAll(/\b([A-Za-z_][A-Za-z0-9_]*)\s+(?:is required|must be|must have)/g)) {
+    cited.add(m[1]);
+  }
+
+  return { cited: [...cited], unrecognized: [...unrecognized] };
+}
+
+/**
+ * Classify one probe result. PURE — no I/O, no clock, no randomness.
+ *
+ * @param {object} probe   the probe descriptor ({method, params, …})
+ * @param {object} sent    the params actually put on the wire (post-contract)
+ * @param {object} frame   the res frame hq returned
+ * @returns {{verdict:"pass"|"fail"|"warn"|"skip", reason:string, detail?:string}}
+ */
+export function classifyFrame(probe, sent, frame) {
+  const method = probe && probe.method;
+  if (!frame || typeof frame !== "object") {
+    return { verdict: "warn", reason: "no frame returned (transport)" };
+  }
+  if (frame.ok) return { verdict: "pass", reason: "accepted" };
+
+  const code = (frame.error && frame.error.code) || "INTERNAL";
+  const message = (frame.error && frame.error.message) || "";
+
+  // A credential failure proves NOTHING about the wire contract: hq rejects at
+  // auth, before any schema runs. It must be its own verdict so the runner can
+  // refuse to call the whole run green.
+  if (CREDENTIAL_FAILURE_CODES.has(code)) {
+    return { verdict: "credential", reason: `${code} — rejected at auth, nothing was tested`, detail: message };
+  }
+  if (SCHEMA_PASSED_CODES.has(code)) {
+    return { verdict: "skip", reason: `${code} — schema accepted, handler declined`, detail: message };
+  }
+  if (code !== "BAD_REQUEST") {
+    return { verdict: "warn", reason: `${code}`, detail: message };
+  }
+
+  // ── BAD_REQUEST: the one code that can mean param-name drift ──────────────
+  const sentKeys = new Set(Object.keys(sent || {}));
+  const { cited, unrecognized } = citedParams(message);
+
+  // (a) hq's .strict() schema rejected a key we sent → our name is wrong.
+  const rejected = unrecognized.filter((k) => sentKeys.has(k));
+  if (rejected.length) {
+    return {
+      verdict: "fail",
+      reason: `hq REJECTS the param name(s) we send: ${rejected.join(", ")}`,
+      detail: message,
+    };
+  }
+  if (unrecognized.length) {
+    return { verdict: "fail", reason: `hq rejected unknown key(s): ${unrecognized.join(", ")}`, detail: message };
+  }
+
+  // (b) hq demands a name we never sent → we are missing/misnaming a param.
+  const unknownToUs = cited.filter((k) => !sentKeys.has(k));
+  if (unknownToUs.length) {
+    return {
+      verdict: "fail",
+      reason: `hq requires param(s) we do not send: ${unknownToUs.join(", ")}`,
+      detail: message,
+    };
+  }
+
+  // (c) hq complained about a param we DID send → a value complaint about the
+  //     probe's placeholder, not a name mismatch. Not drift.
+  if (cited.length) {
+    return { verdict: "warn", reason: `value rejected for ${cited.join(", ")} (probe placeholder)`, detail: message };
+  }
+
+  // (d) an unparseable BAD_REQUEST. Refuse to call it a pass — a human looks.
+  return { verdict: "warn", reason: "BAD_REQUEST (unparsed)", detail: message };
+}
+
+// ---------------------------------------------------------------------------
+// the probe table
+// ---------------------------------------------------------------------------
+
+/**
+ * A probe is `{method, params, writes, guard, why}`.
+ *   writes:false → the handler cannot durably write. `guard` says WHY, and the
+ *                  unit test enforces it:
+ *                    "read"       — read-scope; nothing to write.
+ *                    "ghost"      — every write path is gated behind an id that
+ *                                   cannot exist, so validation runs and the
+ *                                   handler then 404s. Params MUST carry one.
+ *                                   ONLY SOUND when the handler REQUIRES that
+ *                                   entity to exist: a create-or-upsert method
+ *                                   (knowledge.replace) treats an unknown id as
+ *                                   CREATE, so a ghost id guarantees a row
+ *                                   instead of preventing one — those are
+ *                                   `writes:true`.
+ *                    "audit-only" — appends a read-audit event and nothing else
+ *                                   (knowledge.search is side-effecting by
+ *                                   design: retrieval is logged).
+ *                    "no-op"      — a documented no-op for a resource we do not
+ *                                   hold (lease.release).
+ *   writes:true  → running it creates a real row. `--write` only.
+ *
+ * Every method carrying a PARAM_CONTRACT entry is probed (that is the point);
+ * the guard test in `param-contract.test.mjs` asserts the coverage.
+ *
+ * @returns {object[]}
+ */
+export function buildProbes() {
+  const ghostChannel = ghostId("chan");
+  const ghostTask = ghostId("task");
+  const ghostItem = ghostId("item");
+  const ghostDecision = ghostId("dec");
+  const ghostMember = ghostId("mem");
+  const ghostCall = ghostId("call");
+  const hash64 = "0".repeat(64);
+
+  return [
+    // ── read-scope: harmless by construction ────────────────────────────────
+    { method: "messaging.channels", params: {}, writes: false, guard: "read", why: "roster read" },
+    {
+      method: "messaging.history",
+      params: { channelId: ghostChannel, limit: 1 },
+      writes: false,
+      guard: "ghost",
+      why: "channel does not exist → NOT_FOUND after validation",
+    },
+    { method: "member.get", params: { slug: ghostId("slug") }, writes: false, guard: "ghost", why: "slug lookup 404s" },
+    {
+      method: "knowledge.search",
+      params: { q: "conformance probe", limit: 1 },
+      writes: false,
+      guard: "audit-only",
+      why: "retrieval is audited by design; it creates no domain row",
+    },
+    { method: "integration.toolsetVersion", params: {}, writes: false, guard: "read", why: "version read" },
+
+    // ── side-effecting, but poisoned with a ghost id → validation only ───────
+    {
+      method: "messaging.send",
+      params: { channelId: ghostChannel, body: "conformance probe — never delivered", idempotencyId: randomUUID() },
+      writes: false,
+      guard: "ghost",
+      why: "channel cannot exist: assertChannelAccess 404s before any Message row",
+    },
+    {
+      method: "messaging.react",
+      params: { messageId: ghostId("msg"), emoji: "+1" },
+      writes: false,
+      guard: "ghost",
+      why: "message 404s after validation",
+    },
+    {
+      method: "calling.start",
+      params: { channelId: ghostChannel },
+      writes: false,
+      guard: "ghost",
+      why: "channel is resolved (and 404s) before the Call row is created",
+    },
+    { method: "calling.join", params: { callId: ghostCall }, writes: false, guard: "ghost", why: "call 404s" },
+    {
+      method: "calling.invite",
+      params: { callId: ghostCall, memberIds: [ghostMember] },
+      writes: false,
+      guard: "ghost",
+      why: "call 404s after validation",
+    },
+    {
+      method: "messaging.edit",
+      params: { messageId: ghostId("msg"), body: "conformance probe" },
+      writes: false,
+      guard: "ghost",
+      why: "message 404s after validation",
+    },
+    {
+      method: "board.claim",
+      params: { itemId: ghostItem },
+      writes: false,
+      guard: "ghost",
+      why: "requireItem 404s after validation",
+    },
+    {
+      method: "board.assign",
+      params: { itemId: ghostItem, assignee: ghostMember },
+      writes: false,
+      guard: "ghost",
+      why: "STRICT schema; governance-gated, then requireItem 404s",
+    },
+    {
+      method: "approval.resolve",
+      params: { id: ghostId("ap"), decision: "reject" },
+      writes: false,
+      guard: "ghost",
+      why: "approval 404s after validation",
+    },
+    // knowledge.replace is CREATE-or-CAS, NOT a pure CAS: hq's handler treats a
+    // fact that does not exist as the CREATE branch and appends `knowledge.created`
+    // at version 1 (src/server/methods/knowledge/replace.ts). A ghost id therefore
+    // does not make it harmless — it GUARANTEES a durable row, which is the exact
+    // opposite of the guard's assumption. This probe was mis-declared `writes:false`
+    // and a read-only run created a junk fact in the live org before it was caught.
+    //
+    // THE RULE the `ghost` guard depends on: it is only sound when the handler
+    // REQUIRES the referenced entity to exist. Any create-or-upsert method must be
+    // `writes:true`, no matter how unreachable its id looks.
+    {
+      method: "knowledge.replace",
+      params: { id: ghostId("epi"), body: "conformance probe", expectedVersion: 1 },
+      writes: true,
+      guard: "write",
+      why: "create-or-CAS: a nonexistent id CREATES the fact rather than 404ing",
+    },
+    {
+      method: "knowledge.rewrite",
+      params: { id: ghostId("epi"), body: "conformance probe" },
+      writes: false,
+      guard: "ghost",
+      why: "owner-only rewrite of a fact that cannot exist → 404",
+    },
+    {
+      method: "lease.heartbeat",
+      params: { scope: "work-claim", resourceId: ghostId("res") },
+      writes: false,
+      guard: "no-op",
+      why: "sliding a lease we do not hold changes nothing",
+    },
+    {
+      method: "board.complete",
+      params: { itemId: ghostItem, proof: { note: "conformance probe" } },
+      writes: false,
+      guard: "ghost",
+      why: "STRICT schema — the whole point; requireItem then 404s",
+    },
+    {
+      method: "board.updateTask",
+      params: { taskId: ghostTask, col: "review", detail: "conformance probe" },
+      writes: false,
+      guard: "ghost",
+      why: "task 404s after validation",
+    },
+    {
+      method: "board.assignTask",
+      params: { taskId: ghostTask, assigneeId: ghostMember },
+      writes: false,
+      guard: "ghost",
+      why: "task 404s after validation",
+    },
+    {
+      method: "board.moveTask",
+      params: { taskId: ghostTask, col: "todo" },
+      writes: false,
+      guard: "ghost",
+      why: "task 404s after validation",
+    },
+    {
+      method: "board.addTaskComment",
+      params: { taskId: ghostTask, body: "conformance probe" },
+      writes: false,
+      guard: "ghost",
+      why: "task 404s after validation",
+    },
+    {
+      method: "decision.comment",
+      params: { decisionId: ghostDecision, text: "conformance probe" },
+      writes: false,
+      guard: "ghost",
+      why: 'the "text is required" guard runs BEFORE the decision lookup',
+    },
+    {
+      method: "decision.sign",
+      params: { decisionId: ghostDecision },
+      writes: false,
+      guard: "ghost",
+      why: "decision 404s after validation",
+    },
+    {
+      method: "escalation.create",
+      params: { title: "conformance probe", severity: "low", taskId: ghostTask },
+      writes: false,
+      guard: "ghost",
+      why: "the task target 404s before the Escalation row",
+    },
+    {
+      method: "knowledge.invalidate",
+      params: { id: ghostId("epi"), reason: "conformance probe" },
+      writes: false,
+      guard: "ghost",
+      why: "episode 404s",
+    },
+    {
+      method: "lease.release",
+      params: { scope: "work-claim", resourceId: ghostId("res") },
+      // NOT a no-op. hq deletes conditionally but appends `lease.released`
+      // UNCONDITIONALLY, outside the `if` (methods/lease/release.ts:32) — so a
+      // release of a lease we never held still writes a row to the org's
+      // hash-linked event chain, with `freed: false`. Agents tail that feed, so
+      // a "read-only" CI run produced phantom lease.released events for
+      // probe-res-* resources in the live org on every pass. Same defect class
+      // as knowledge.replace: the guard described what we WANTED to be true
+      // rather than what the handler does.
+      writes: true,
+      guard: "write",
+      why: "appends lease.released unconditionally, even when nothing was held",
+    },
+
+    // ── genuinely creates a row: --write only ───────────────────────────────
+    {
+      method: "registry.register",
+      params: { card: { probe: "conformance", at: new Date().toISOString() } },
+      writes: true,
+      guard: "write",
+      why: "updates the SELF seat and appends a registry event",
+    },
+    {
+      method: "board.createTask",
+      params: { title: "[conformance probe] delete me", col: "triage", priority: "P4" },
+      writes: true,
+      guard: "write",
+      why: "creates a real Task",
+    },
+    {
+      method: "decision.propose",
+      params: { title: "[conformance probe] delete me", why: { reason: "wire conformance" }, tag: "probe" },
+      writes: true,
+      guard: "write",
+      why: "creates a real Decision",
+    },
+    {
+      method: "memory.author",
+      params: { memoryClass: "ledger", title: "[conformance probe] delete me", summary: "wire conformance" },
+      writes: true,
+      guard: "write",
+      why: "creates a real MemoryEntry",
+    },
+    {
+      method: "knowledge.append",
+      params: { body: "[conformance probe] wire conformance check", group: "org" },
+      writes: true,
+      guard: "write",
+      why: "appends a real knowledge episode",
+    },
+    {
+      method: "approval.request",
+      params: { actionClass: "conformance_probe", payloadHash: hash64, subject: "[conformance probe]" },
+      writes: true,
+      guard: "write",
+      why: "creates a real pending Approval",
+    },
+    {
+      method: "lease.claim",
+      params: { scope: "work-claim", resourceId: ghostId("res"), ttlMs: 1000 },
+      writes: true,
+      guard: "write",
+      why: "creates a real (1s) Lease row",
+    },
+    {
+      method: "contacts.upsert",
+      params: { kind: "person", displayName: "[conformance probe] delete me" },
+      writes: true,
+      guard: "write",
+      why: "creates a real Contact",
+    },
+    {
+      method: "meetings.record",
+      params: { title: "[conformance probe] delete me" },
+      writes: true,
+      guard: "write",
+      why: "creates a real MeetingRecord",
+    },
+  ];
+}
+
+/**
+ * Which contracted methods have no probe? Pure — the coverage assertion the
+ * unit test enforces so a new contract row cannot ship unprobed.
+ * @param {object[]} [probes]
+ * @returns {string[]}
+ */
+export function uncoveredContractMethods(probes = buildProbes()) {
+  const probed = new Set(probes.map((p) => p.method));
+  return Object.keys(PARAM_CONTRACT).filter((m) => !probed.has(m));
+}
+
+// ---------------------------------------------------------------------------
+// argv
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse argv. Pure.
+ * @param {string[]} argv
+ * @returns {{write:boolean, json:boolean, verbose:boolean, only:string[], agentRoot:string|null, help:boolean, bad:string[]}}
+ */
+export function parseArgs(argv = []) {
+  const out = { write: false, json: false, verbose: false, only: [], agentRoot: null, help: false, bad: [] };
+  for (const raw of argv) {
+    const a = String(raw);
+    if (a === "--write") out.write = true;
+    else if (a === "--json") out.json = true;
+    else if (a === "--verbose" || a === "-v") out.verbose = true;
+    else if (a === "--help" || a === "-h") out.help = true;
+    else if (a.startsWith("--only=")) out.only = a.slice(7).split(",").map((s) => s.trim()).filter(Boolean);
+    else if (a.startsWith("--agent-root=")) out.agentRoot = a.slice(13);
+    else out.bad.push(a);
+  }
+  return out;
+}
+
+/** Does this probe pass the --only family filter? Pure. */
+export function probeSelected(probe, only) {
+  if (!only || !only.length) return true;
+  const def = methodDef(probe.method);
+  const family = (def && def.family) || String(probe.method).split(".")[0];
+  return only.includes(family) || only.includes(probe.method);
+}
+
+// ---------------------------------------------------------------------------
+// runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the probe suite. Injectable (`callImpl`/`readImpl`) so the runner itself
+ * is testable without a network.
+ *
+ * @param {object} o - { base, token, orgId, write?, only?, callImpl?, readImpl? }
+ * @returns {Promise<{results:object[], reads:object[], failures:object[]}>}
+ */
+export async function runProbes(o = {}) {
+  const callImpl = o.callImpl || call;
+  const readImpl = o.readImpl || read;
+  const tx = { base: o.base, token: o.token, orgId: o.orgId, logImpl: () => {} };
+
+  const results = [];
+  for (const probe of buildProbes()) {
+    if (!probeSelected(probe, o.only)) continue;
+    if (probe.writes && !o.write) {
+      results.push({ ...probe, verdict: "skip", reason: "row-creating — pass --write to include", sent: probe.params });
+      continue;
+    }
+    // Record what actually goes on the wire (post-contract) so the classifier
+    // can tell "hq wants a name we don't send" from "hq disliked our value".
+    // What the SHIPPING path actually puts on the wire: client.call applies the
+    // contract, so recompute it here rather than guessing from probe.params. The
+    // classifier needs the real key set to tell "hq wants a name we never send"
+    // apart from "hq disliked our placeholder value".
+    const sent = wireBodyFor(probe.method, probe.params);
+    let frame;
+    try {
+      frame = await callImpl(probe.method, probe.params, { ...tx, fetchImpl: o.fetchImpl });
+    } catch (err) {
+      frame = { ok: false, error: { code: "INTERNAL", message: String((err && err.message) || err) } };
+    }
+    const verdict = classifyFrame(probe, sent, frame);
+    results.push({ ...probe, ...verdict, sent, code: frame && frame.error && frame.error.code });
+  }
+
+  // Every GET read path — a 404/400 here is a routing contract break.
+  const reads = [];
+  if (!o.only || !o.only.length || o.only.includes("reads")) {
+    for (const path of Object.keys(READS)) {
+      if (path === "approval.wait") continue; // a 55s long-poll; not a probe
+      const r = await readImpl(path, { ...tx, timeoutMs: 8000 });
+      const code = r.ok ? null : (r.error && r.error.code) || "INTERNAL";
+      // A read rejected at auth is `credential`, never `pass`. Marking it pass
+      // is how a dead token turned all 12 GET paths green.
+      const verdict = r.ok
+        ? "pass"
+        : CREDENTIAL_FAILURE_CODES.has(code)
+          ? "credential"
+          : SCHEMA_PASSED_CODES.has(code)
+            ? "pass"
+            : code === "BAD_REQUEST"
+              ? "fail"
+              : "warn";
+      reads.push({
+        path,
+        verdict,
+        reason: r.ok ? "200" : `${code}: ${(r.error && r.error.message) || ""}`,
+      });
+    }
+  }
+
+  const failures = [...results, ...reads].filter((x) => x.verdict === "fail");
+  return { results, reads, failures };
+}
+
+/**
+ * The params `client.call()` actually puts on the wire for this method — the same
+ * contract, applied the same way. Fail-open to the raw params.
+ * @param {string} method @param {object} params @returns {object}
+ */
+export function wireBodyFor(method, params) {
+  try {
+    return normalizeParams(method, params).params;
+  } catch {
+    return params || {};
+  }
+}
+
+// ---------------------------------------------------------------------------
+// cli
+// ---------------------------------------------------------------------------
+
+const HELP = `
+conformance-org-api — live wire-contract probe against a real Cohort org.
+
+  node scripts/ci/conformance-org-api.mjs [options]
+
+  --write              include probes that create a real row (default: skipped)
+  --only=fam[,fam]     limit to protocol families (e.g. --only=board,messaging)
+                       or "reads" for the GET surface only
+  --json               machine-readable report on stdout
+  --verbose, -v        print every verdict, not just failures
+  --agent-root=PATH    load config/org.yaml from PATH
+  --help, -h           this text
+
+  exit 0 = no drift (or no credentials → skipped), 1 = drift, 2 = bad usage.
+`.trim();
+
+/** @returns {Promise<number>} process exit code */
+export async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(HELP);
+    return 0;
+  }
+  if (args.bad.length) {
+    console.error(`conformance-org-api: unknown argument(s): ${args.bad.join(", ")}`);
+    console.error(HELP);
+    return 2;
+  }
+
+  // Resolve credentials exactly as the runtime does.
+  const agentRoot = args.agentRoot || process.env.COHORT_AGENT_ROOT || process.env.AGENT_ROOT || REPO_ROOT;
+  const cfg = configFromAgent(loadOrgConfig(agentRoot));
+  const base =
+    (process.env.COHORT_BASE && process.env.COHORT_BASE.replace(/\/+$/, "")) ||
+    (process.env.COHORT_API_URL && process.env.COHORT_API_URL.replace(/\/+$/, "")) ||
+    cfg.base ||
+    "https://os.cohortapp.com";
+  const token = cfg.token;
+  const orgId = cfg.orgId;
+
+  if (!token) {
+    // A CI job with no org secret must not fail — but it must SAY so. A silent
+    // green here would be exactly the failure mode this script exists to end.
+    console.log("conformance-org-api: SKIPPED — no org credentials (set COHORT_API_TOKEN).");
+    console.log("  This check is a no-op without a live org; it is a gate only where the secret exists.");
+    return 0;
+  }
+
+  const uncovered = uncoveredContractMethods();
+  const { results, reads, failures } = await runProbes({ base, token, orgId, write: args.write, only: args.only });
+
+  if (args.json) {
+    console.log(JSON.stringify({ base, orgId, write: args.write, uncovered, results, reads, failures }, null, 2));
+    return failures.length ? 1 : 0;
+  }
+
+  const icon = { pass: "  ok  ", fail: " FAIL ", warn: " warn ", skip: " skip " };
+  console.log(`conformance-org-api → ${base} (org ${orgId || "?"})${args.write ? " [--write]" : ""}\n`);
+  for (const r of results) {
+    if (!args.verbose && r.verdict !== "fail") continue;
+    console.log(`${icon[r.verdict]} ${r.method.padEnd(28)} ${r.reason}`);
+    if (r.detail && r.verdict !== "pass") console.log(`        ↳ ${r.detail}`);
+  }
+  for (const r of reads) {
+    if (!args.verbose && r.verdict !== "fail") continue;
+    console.log(`${icon[r.verdict]} GET ${r.path.padEnd(24)} ${r.reason}`);
+  }
+
+  const tally = (v) => results.filter((r) => r.verdict === v).length;
+  console.log(
+    `\n${results.length} method probes: ${tally("pass")} pass, ${tally("skip")} skip, ` +
+      `${tally("warn")} warn, ${tally("fail")} FAIL — ${reads.length} read paths.`,
+  );
+  if (uncovered.length) {
+    console.log(`\nNOTE: ${uncovered.length} contracted method(s) have no probe: ${uncovered.join(", ")}`);
+  }
+  if (failures.length) {
+    console.log(`\nWIRE-CONTRACT DRIFT — ${failures.length} method(s) reject the params this SDK sends.`);
+    console.log("Fix lib/org/param-contract.mjs (and the call site) so the canonical name goes on the wire.");
+    return 1;
+  }
+
+  // A RUN THAT PROVED NOTHING IS NOT A PASS.
+  //
+  // Every probe rejected at auth means the credential is dead, not that the
+  // contract is sound — and the old code called that green and exited 0. A gate
+  // is only worth having if it can tell "verified" from "never ran"; this one
+  // could not, and would have stayed green forever after a token rotation.
+  const credentialRejected = tally("credential");
+  if (credentialRejected > 0 && tally("pass") === 0) {
+    console.log(
+      `\nNOTHING WAS VERIFIED — all ${credentialRejected} probe(s) were rejected at auth ` +
+        `(UNAUTHORIZED). The token is missing, expired, revoked or scoped out.\n` +
+        `This is NOT a pass: the wire contract was never exercised.`,
+    );
+    return 2;
+  }
+  if (tally("pass") === 0) {
+    console.log(
+      "\nNOTHING WAS VERIFIED — no probe reached a handler. Refusing to report success.",
+    );
+    return 2;
+  }
+
+  console.log(`\nNo wire-contract drift (${tally("pass")} probe(s) genuinely verified).`);
+  return 0;
+}
+
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (isMain) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error(`conformance-org-api: ${(err && err.stack) || err}`);
+      process.exit(1);
+    });
+}
+
+export default {
+  main,
+  classifyFrame,
+  citedParams,
+  buildProbes,
+  parseArgs,
+  probeSelected,
+  runProbes,
+  wireBodyFor,
+  uncoveredContractMethods,
+};