@cohortapp/agent-sdk 2.3.0

package/lib/org/knowledge.test.mjs

@@ -0,0 +1,319 @@
+/**
+ * knowledge.test.mjs — agent-facing shared-memory API over the Cohort knowledge
+ * plane. Verifies the verb surface (remember/recall/forget/rewrite + contacts/
+ * meetings) routes to the right methods, that the client NEVER filters recall
+ * results (the server is authoritative for ACL), that forget invalidates (never
+ * deletes), and the fail-open contract when the integration is disabled.
+ * Uses an injected fetchImpl — no network.
+ * Run: node --test lib/org/knowledge.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  remember,
+  rewrite,
+  recall,
+  recallDetailed,
+  forget,
+  upsertContact,
+  listContacts,
+  recordMeeting,
+  listMeetings,
+  normalizeGroup,
+  _internals,
+} from "./knowledge.mjs";
+
+const BASE = "https://org.cohortapp.com";
+const CFG = { org: { cohort: { enabled: true, base: BASE, token: "tok" } } };
+const OFF = { org: { cohort: { enabled: false } } };
+
+delete process.env.COHORT_API_TOKEN;
+delete process.env.COHORT_TOKEN;
+
+/** A fake fetch that records calls and returns a canned res frame / payload. */
+function fakeFetch(responder) {
+  const calls = [];
+  const impl = async (url, init) => {
+    calls.push({
+      url,
+      init,
+      method: init && init.method,
+      headers: (init && init.headers) || {},
+      body: init && init.body ? JSON.parse(init.body) : null,
+    });
+    const r = responder ? responder(url, init, calls.length - 1) : null;
+    const status = r && typeof r.status === "number" ? r.status : 200;
+    const ok = r && typeof r.ok === "boolean" ? r.ok : status >= 200 && status < 300;
+    const body = r ? r.body : { ok: true, result: null };
+    return { ok, status, headers: { get: () => undefined }, json: async () => body };
+  };
+  impl.calls = calls;
+  return impl;
+}
+
+// --- normalizeGroup (pure shape helper; NOT an ACL decision) ----------------
+
+test("normalizeGroup: org / unit:<id> / barrier:<cell>; rejects unknown kinds", () => {
+  assert.equal(normalizeGroup("org"), "org");
+  assert.equal(normalizeGroup({ kind: "org" }), "org");
+  assert.equal(normalizeGroup({ kind: "unit", id: "eng" }), "unit:eng");
+  assert.equal(normalizeGroup({ kind: "barrier", cell: "deals-2026" }), "barrier:deals-2026");
+  assert.equal(normalizeGroup("unit:eng"), "unit:eng");
+  assert.equal(normalizeGroup("barrier:deals"), "barrier:deals");
+  // unknown kinds / bare ids fall through to "let the server decide"
+  assert.equal(normalizeGroup("bogus:x"), undefined);
+  assert.equal(normalizeGroup("eng"), undefined);
+  assert.equal(normalizeGroup(""), undefined);
+  assert.equal(normalizeGroup(undefined), undefined);
+});
+
+// --- remember → knowledge.append (default) / knowledge.replace (CAS) ---------
+
+test("remember(string): appends an episode (the sole shared-write primitive)", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "k-1", version: 1 } } }));
+  const r = await remember("we closed the Q3 deal", { cfg: CFG, group: "org", fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.equal(r.mode, "append");
+  assert.equal(r.id, "k-1");
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/knowledge.append`);
+  assert.equal(f.calls[0].method, "POST");
+  assert.equal(f.calls[0].headers.authorization, "Bearer tok");
+  assert.deepEqual(f.calls[0].body, { text: "we closed the Q3 deal", group: "org" });
+});
+
+test("remember(fact object): pulls through opts (kind/participants/provenance), normalises group", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "k-2" } } }));
+  await remember(
+    { text: "intro call notes" },
+    { cfg: CFG, group: { kind: "unit", id: "sales" }, kind: "note", participants: ["a", "b"], provenance: { src: "call" }, fetchImpl: f },
+  );
+  assert.deepEqual(f.calls[0].body, {
+    text: "intro call notes",
+    kind: "note",
+    participants: ["a", "b"],
+    provenance: { src: "call" },
+    group: "unit:sales",
+  });
+});
+
+test("remember with {id, expectedVersion}: routes to knowledge.replace (CAS)", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "k-9", version: 4 } } }));
+  const r = await remember({ text: "corrected figure" }, { cfg: CFG, id: "k-9", expectedVersion: 3, fetchImpl: f });
+  assert.equal(r.mode, "replace");
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/knowledge.replace`);
+  assert.equal(f.calls[0].body.id, "k-9");
+  assert.equal(f.calls[0].body.expectedVersion, 3);
+});
+
+test("remember: idempotency key auto-derived from id on append", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "k-5" } } }));
+  await remember({ id: "k-5", text: "x" }, { cfg: CFG, fetchImpl: f });
+  assert.equal(f.calls[0].headers["x-idempotency-key"], "knowledge.append:k-5");
+});
+
+test("remember: disabled → fail-open skipped, no fetch", async () => {
+  const f = fakeFetch();
+  const r = await remember("x", { cfg: OFF, fetchImpl: f });
+  assert.deepEqual(r, { ok: false, skipped: true });
+  assert.equal(f.calls.length, 0);
+});
+
+test("remember: empty fact → BAD_REQUEST, no fetch", async () => {
+  const f = fakeFetch();
+  const r = await remember("", { cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, false);
+  assert.equal(r.error.code, "BAD_REQUEST");
+  assert.equal(f.calls.length, 0);
+});
+
+// --- rewrite → knowledge.rewrite (designated-owner-only) --------------------
+
+test("rewrite: routes to knowledge.rewrite with the id + text", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "k-1" } } }));
+  const r = await rewrite("k-1", "owner-asserted text", { cfg: CFG, fetchImpl: f });
+  assert.equal(r.mode, "rewrite");
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/knowledge.rewrite`);
+  assert.equal(f.calls[0].body.id, "k-1");
+  assert.equal(f.calls[0].body.text, "owner-asserted text");
+});
+
+test("rewrite: non-owner FORBIDDEN_SCOPE surfaces in error (server is authoritative)", async () => {
+  const f = fakeFetch(() => ({ ok: false, status: 403, body: { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "owner only" } } }));
+  const r = await rewrite("k-1", "x", { cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, false);
+  assert.equal(r.error.code, "FORBIDDEN_SCOPE");
+});
+
+// --- recall → knowledge.search; CLIENT NEVER FILTERS ------------------------
+
+test("remember → recall round-trip: recall returns exactly the server's facts", async () => {
+  // The server is the ONLY ACL authority. recall renders whatever it returns —
+  // here a fact the agent appended comes back from search.
+  const serverFacts = [{ id: "k-1", text: "we closed the Q3 deal", group: "org" }];
+  let appended = false;
+  const f = fakeFetch((url) => {
+    if (url.endsWith("/v1/knowledge.append")) { appended = true; return { body: { ok: true, result: { id: "k-1" } } }; }
+    if (url.endsWith("/v1/knowledge.search")) return { body: { ok: true, result: { facts: serverFacts, returned_ids: ["k-1"], groups_considered: ["org"] } } };
+    return { body: { ok: true, result: null } };
+  });
+  await remember("we closed the Q3 deal", { cfg: CFG, group: "org", fetchImpl: f });
+  assert.equal(appended, true);
+  const facts = await recall("Q3 deal", { cfg: CFG, fetchImpl: f });
+  assert.deepEqual(facts, serverFacts);
+});
+
+test("recall: passes the query (+ group hint, limit) to the server; does NOT filter results", async () => {
+  // Server returns a barrier fact AND an org fact. The client must NOT drop the
+  // barrier one — if the server returned it, the agent was granted that cell.
+  const returned = [
+    { id: "k-1", group: "org", text: "public" },
+    { id: "k-2", group: "barrier:deals-2026", text: "walled-but-granted" },
+  ];
+  const f = fakeFetch(() => ({ body: { ok: true, result: { facts: returned, returned_ids: ["k-1", "k-2"], groups_considered: ["org", "barrier:deals-2026"] } } }));
+  const facts = await recall("deal terms", { cfg: CFG, group: { kind: "unit", id: "eng" }, limit: 3, fetchImpl: f });
+  // client renders EVERYTHING the server returned, including the barrier fact
+  assert.deepEqual(facts, returned);
+  // and it forwarded the query + the normalised group hint + limit
+  assert.equal(f.calls[0].body.query, "deal terms");
+  assert.equal(f.calls[0].body.group, "unit:eng");
+  assert.equal(f.calls[0].body.limit, 3);
+});
+
+test("recall: when the server returns FEWER facts (RLS floored), the client returns exactly those", async () => {
+  // Agent asks broadly; server's RLS floor excludes a barrier fact it isn't
+  // granted. The client has no idea a fact was withheld — it just renders [k-1].
+  const f = fakeFetch(() => ({ body: { ok: true, result: { facts: [{ id: "k-1", group: "org" }], returned_ids: ["k-1"], groups_considered: ["org", "unit:eng"] } } }));
+  const facts = await recall("everything", { cfg: CFG, fetchImpl: f });
+  assert.deepEqual(facts, [{ id: "k-1", group: "org" }]);
+});
+
+test("recallDetailed: surfaces returnedIds + groupsConsidered from the read-audit envelope", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { facts: [{ id: "k-1" }, { id: "k-2" }], returned_ids: ["k-1", "k-2"], groups_considered: ["org", "unit:eng"] } } }));
+  const r = await recallDetailed("q", { cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.returnedIds, ["k-1", "k-2"]);
+  assert.deepEqual(r.groupsConsidered, ["org", "unit:eng"]);
+});
+
+test("recallDetailed: derives returnedIds from facts when the server omits returned_ids", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { facts: [{ id: "k-3" }, { id: "k-4" }] } } }));
+  const r = await recallDetailed("q", { cfg: CFG, fetchImpl: f });
+  assert.deepEqual(r.returnedIds, ["k-3", "k-4"]);
+  assert.deepEqual(r.groupsConsidered, []);
+});
+
+test("recall: lexical flag forwarded (keyword stand-in for vector search)", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { facts: [] } } }));
+  await recall("keyword", { cfg: CFG, lexical: true, fetchImpl: f });
+  assert.equal(f.calls[0].body.lexical, true);
+});
+
+test("recall: disabled or empty query → [] (fail-open), no fetch", async () => {
+  const f = fakeFetch();
+  assert.deepEqual(await recall("q", { cfg: OFF, fetchImpl: f }), []);
+  assert.deepEqual(await recall("   ", { cfg: CFG, fetchImpl: f }), []);
+  assert.equal(f.calls.length, 0);
+});
+
+test("recall: server error → [] (fail-open); recallDetailed reports the error", async () => {
+  const f = fakeFetch(() => ({ ok: false, status: 403, body: { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "no knowledge.read" } } }));
+  assert.deepEqual(await recall("q", { cfg: CFG, fetchImpl: f }), []);
+  const f2 = fakeFetch(() => ({ ok: false, status: 403, body: { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "no knowledge.read" } } }));
+  const r = await recallDetailed("q", { cfg: CFG, fetchImpl: f2 });
+  assert.equal(r.ok, false);
+  assert.deepEqual(r.facts, []);
+  assert.equal(r.error.code, "FORBIDDEN_SCOPE");
+});
+
+// --- forget → knowledge.invalidate (tombstone, NEVER hard-delete) -----------
+
+test("forget: calls knowledge.invalidate (not a delete); carries reason + idempotency", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "k-1", invalid: true } } }));
+  const r = await forget("k-1", { cfg: CFG, reason: "superseded by k-2", supersededBy: "k-2", fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.equal(r.mode, "invalidate");
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/knowledge.invalidate`);
+  assert.equal(f.calls[0].body.id, "k-1");
+  assert.equal(f.calls[0].body.reason, "superseded by k-2");
+  assert.equal(f.calls[0].body.supersededBy, "k-2");
+  assert.equal(f.calls[0].headers["x-idempotency-key"], "knowledge.invalidate:k-1");
+});
+
+test("forget: disabled → skipped; missing id → BAD_REQUEST; no fetch", async () => {
+  const f = fakeFetch();
+  assert.deepEqual(await forget("k-1", { cfg: OFF, fetchImpl: f }), { ok: false, skipped: true });
+  const bad = await forget("", { cfg: CFG, fetchImpl: f });
+  assert.equal(bad.error.code, "BAD_REQUEST");
+  assert.equal(f.calls.length, 0);
+});
+
+// --- contacts -------------------------------------------------------------
+
+test("upsertContact: posts the right shape to contacts.upsert (idempotent on id)", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "c-1" } } }));
+  const r = await upsertContact({ id: "c-1", name: "Jordan", emails: ["j@x.com"], group: { kind: "unit", id: "sales" } }, { cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/contacts.upsert`);
+  assert.deepEqual(f.calls[0].body, { id: "c-1", name: "Jordan", emails: ["j@x.com"], group: "unit:sales" });
+  assert.equal(f.calls[0].headers["x-idempotency-key"], "contacts.upsert:c-1");
+});
+
+test("listContacts: returns the server's ACL-filtered list as-is; [] when disabled", async () => {
+  const f = fakeFetch(() => ({ body: { contacts: [{ id: "c-1" }, { id: "c-2" }] } }));
+  assert.deepEqual(await listContacts({ cfg: CFG, q: "jord", fetchImpl: f }), [{ id: "c-1" }, { id: "c-2" }]);
+  assert.match(f.calls[0].url, /\/v1\/contacts\.list\?q=jord$/);
+  assert.deepEqual(await listContacts({ cfg: OFF }), []);
+});
+
+test("upsertContact: server NOT_FOUND (handler lane unbuilt) surfaces unimplemented + warns, never a silent swallow", async () => {
+  const f = fakeFetch(() => ({ body: { ok: false, error: { code: "NOT_FOUND", message: "unknown method contacts.upsert" } } }));
+  const warnings = [];
+  const orig = console.warn;
+  console.warn = (m) => warnings.push(String(m));
+  let r;
+  try {
+    r = await upsertContact({ id: "c-9", name: "Sam" }, { cfg: CFG, fetchImpl: f });
+  } finally {
+    console.warn = orig;
+  }
+  assert.equal(r.ok, false);
+  assert.equal(r.unimplemented, true, "NOT_FOUND is flagged as an unimplemented capability, not a plain failure");
+  assert.equal(r.error.code, "NOT_FOUND");
+  assert.ok(warnings.some((w) => w.includes("contacts.upsert")), "emits a loud, actionable warning naming the missing method");
+});
+
+// --- meetings -------------------------------------------------------------
+
+test("recordMeeting: posts the right shape to meetings.record (idempotent on id)", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "m-1" } } }));
+  const r = await recordMeeting({ id: "m-1", title: "board sync", at: "2026-06-11T10:00:00Z", participants: ["a", "b"] }, { cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/meetings.record`);
+  assert.deepEqual(f.calls[0].body, { id: "m-1", title: "board sync", at: "2026-06-11T10:00:00Z", participants: ["a", "b"] });
+  assert.equal(f.calls[0].headers["x-idempotency-key"], "meetings.record:m-1");
+});
+
+test("listMeetings: returns the server's participant-ACL list as-is; [] when disabled", async () => {
+  const f = fakeFetch(() => ({ body: { meetings: [{ id: "m-1" }] } }));
+  assert.deepEqual(await listMeetings({ cfg: CFG, since: "2026-06-01", fetchImpl: f }), [{ id: "m-1" }]);
+  assert.match(f.calls[0].url, /\/v1\/meetings\.list\?since=2026-06-01$/);
+  assert.deepEqual(await listMeetings({ cfg: OFF }), []);
+});
+
+// --- pure internals --------------------------------------------------------
+
+test("_internals.pickArray: finds the first array key, [] otherwise", () => {
+  assert.deepEqual(_internals.pickArray({ facts: [1, 2] }, ["facts", "results"]), [1, 2]);
+  assert.deepEqual(_internals.pickArray({ results: [3] }, ["facts", "results"]), [3]);
+  assert.deepEqual(_internals.pickArray([9], ["facts"]), [9]);
+  assert.deepEqual(_internals.pickArray({ nope: 1 }, ["facts"]), []);
+  assert.deepEqual(_internals.pickArray(null, ["facts"]), []);
+});
+
+test("_internals.factToParams: string→{text}; opts pull-through; group normalised; id stringified", () => {
+  const p = _internals.factToParams("hi", { kind: "note", id: 42, group: { kind: "unit", id: "eng" } });
+  assert.deepEqual(p, { text: "hi", kind: "note", id: "42", group: "unit:eng" });
+});

package/lib/org/leases.mjs

@@ -0,0 +1,335 @@
+/**
+ * lib/org/leases.mjs — agent-side lease helpers over the Cohort lease primitive.
+ *
+ * The Cohort server exposes one generic lease primitive (lib/org/protocol.mjs
+ * LEASE_SCOPES: work-claim / thread-ownership / session-leadership /
+ * singleton-cadence). Exactly one holder per (scope, resourceId) until
+ * expiry/release — the server resolves the race atomically (single-conditional
+ * CAS), the loser gets a CONFLICT/LEASE_HELD error frame.
+ *
+ * This module is the agent-facing convenience layer over that primitive:
+ *
+ *   - claimLease(scope, resourceId, opts)  — generic claim, 3s fail-open.
+ *   - claimThread(channel, thread, opts)   — thread-ownership claim for
+ *     shared-channel SEND ARBITRATION (§5.4): when ≥2 agents see the same channel
+ *     message, exactly one wins a `thread-ownership` lease on resource_id
+ *     `channel:<thread>` and replies; the others stand down.
+ *   - releaseThread / releaseLease         — free a claimed lease.
+ *   - preSendArbitration(...)              — the cancellable pre-send check the
+ *     channel send path calls; returns {mayReply, leaseToken, ...}. Exactly one
+ *     agent gets mayReply:true for a given thread.
+ *
+ * FAIL-OPEN DISCIPLINE (§5.4 rule 4 / design rule 3 "coordination fails open,
+ * counted"): a lease call that does not resolve within `failOpenTimeoutMs`
+ * (default 3000) is treated as a WIN — the agent proceeds rather than going
+ * silent when the coordination plane is down. Every fail-open is surfaced
+ * (`failedOpen:true`) so the caller can bump `failOpenSends` in
+ * state/org/metrics.json and report it on reconnect.
+ *
+ * Channels NOT listed `claim-on-receive` in config/ownership.yaml are not
+ * arbitrated: preSendArbitration short-circuits to {mayReply:true} for them, so
+ * the send path pays no lease round-trip on un-shared channels.
+ *
+ * Pure-core + injectable IO: the Cohort client is injected as `opts.client`
+ * (defaults to the real lib/org/client.mjs helpers) and the ownership config is
+ * injected as `opts.ownership` (else read from config/ownership.yaml). Node
+ * builtins only. ESM.
+ *
+ * @module lib/org/leases
+ */
+
+"use strict";
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { LEASE_SCOPES } from "./protocol.mjs";
+import * as client from "./client.mjs";
+
+/** Default fail-open ceiling for any single lease round-trip (§5.4). */
+export const DEFAULT_FAIL_OPEN_MS = 3000;
+
+/** The thread-ownership lease scope + default TTL (10m, per §5.4 rule 1). */
+export const THREAD_OWNERSHIP_SCOPE = "thread-ownership";
+const DEFAULT_THREAD_TTL_MS = 10 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// ownership.yaml — which channels are arbitrated
+// ---------------------------------------------------------------------------
+
+/**
+ * Load + parse config/ownership.yaml. Returns the parsed doc, or a benign empty
+ * shape (`{channels:[]}`) when the file is absent/unreadable — so an agent
+ * without the config simply arbitrates nothing (no channel is claim-on-receive).
+ * Fail-open. Injectable root for tests.
+ * @param {string} [agentRoot="."]
+ * @returns {Promise<{schemaVersion?:number, channels:object[], mentionTtlSec?:number, arbitration?:object}>}
+ */
+export async function loadOwnership(agentRoot = ".") {
+  const path = join(String(agentRoot || "."), "config", "ownership.yaml");
+  if (!existsSync(path)) return { channels: [] };
+  try {
+    const m = await import("js-yaml");
+    const yaml = m.default || m;
+    const doc = yaml.load(readFileSync(path, "utf8"));
+    if (doc && typeof doc === "object") {
+      return { channels: Array.isArray(doc.channels) ? doc.channels : [], ...doc };
+    }
+    return { channels: [] };
+  } catch {
+    return { channels: [] };
+  }
+}
+
+/**
+ * Find the ownership rule for a (platform, channel/thread-id) pair, if any.
+ * Matches on `channel` or `chat` (telegram) keys, case-insensitively for ids.
+ * Pure.
+ * @param {{channels:object[]}} ownership
+ * @param {string} platform
+ * @param {string} channelId
+ * @returns {object|null} the matching channel rule, or null
+ */
+export function ownershipRuleFor(ownership, platform, channelId) {
+  const chans = (ownership && Array.isArray(ownership.channels)) ? ownership.channels : [];
+  const plat = String(platform || "").toLowerCase();
+  const id = String(channelId || "");
+  for (const c of chans) {
+    if (!c || typeof c !== "object") continue;
+    if (String(c.platform || "").toLowerCase() !== plat) continue;
+    const ruleId = c.channel != null ? String(c.channel) : (c.chat != null ? String(c.chat) : "");
+    if (ruleId && (ruleId === id || ruleId.toLowerCase() === id.toLowerCase())) return c;
+  }
+  return null;
+}
+
+/**
+ * Is this channel in `claim-on-receive` arbitration mode? Pure. Channels with no
+ * rule (or `send-time-only` / any other mode) are NOT claim-on-receive.
+ * @param {{channels:object[]}} ownership @param {string} platform @param {string} channelId
+ * @returns {boolean}
+ */
+export function isClaimOnReceive(ownership, platform, channelId) {
+  const rule = ownershipRuleFor(ownership, platform, channelId);
+  return !!(rule && rule.mode === "claim-on-receive");
+}
+
+// ---------------------------------------------------------------------------
+// resource-key canonicalisation
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical thread-ownership resource id. Both racing agents must derive the
+ * SAME key for the server to adjudicate a single winner, so we normalise: lower
+ * the platform, keep the channel id as-is (Slack ids are already uppercase by the
+ * conversation-resolver convention), and join with the thread/ts. Pure.
+ * @param {string} channel  the channel/chat id (already canonicalised upstream)
+ * @param {string} thread   the thread root ts / message id (falls back to channel)
+ * @returns {string} e.g. "channel:C0123ABC:1700000000.0001"
+ */
+export function threadResourceId(channel, thread) {
+  const ch = String(channel || "").trim();
+  const th = String(thread || "").trim();
+  return th ? `channel:${ch}:${th}` : `channel:${ch}`;
+}
+
+// ---------------------------------------------------------------------------
+// fail-open lease round-trip
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a value, but never wait longer than `ms`; on timeout resolve with
+ * `onTimeout`. Used to bound every lease round-trip at the fail-open ceiling so
+ * a hung server can never stall a send. Pure over its inputs.
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} ms
+ * @param {() => T} onTimeout
+ * @returns {Promise<T>}
+ */
+function withTimeout(promise, ms, onTimeout) {
+  if (!(ms > 0)) return promise;
+  return new Promise((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      resolve(onTimeout());
+    }, ms);
+    if (timer && typeof timer.unref === "function") timer.unref();
+    Promise.resolve(promise).then(
+      (v) => { if (!settled) { settled = true; clearTimeout(timer); resolve(v); } },
+      () => { if (!settled) { settled = true; clearTimeout(timer); resolve(onTimeout()); } },
+    );
+  });
+}
+
+/** The Cohort client surface this module needs (injectable for tests). */
+function resolveClient(opts) {
+  return (opts && opts.client) || client;
+}
+
+/** Connection options for a client RPC, distilled from opts. */
+function rpcOpts(opts) {
+  return {
+    base: opts && opts.base,
+    token: opts && opts.token,
+    fetchImpl: opts && opts.fetchImpl,
+    idempotencyKey: opts && opts.idempotencyKey,
+  };
+}
+
+/**
+ * Claim a generic lease over the Cohort lease primitive. 3s fail-open: if the
+ * server does not adjudicate within `failOpenTimeoutMs`, the caller WINS (the
+ * coordination plane fails open, counted).
+ *
+ * @param {string} scope        one of LEASE_SCOPES
+ * @param {string} resourceId   the resource the lease guards (e.g. a thread key)
+ * @param {object} [opts] - {
+ *   client?, base, token, fetchImpl?, idempotencyKey?, holder?, ttlMs?,
+ *   failOpenTimeoutMs?
+ * }
+ * @returns {Promise<{held:boolean, leaseToken:string|null, failedOpen:boolean, reason:string, frame?:object}>}
+ */
+export async function claimLease(scope, resourceId, opts = {}) {
+  if (!LEASE_SCOPES.includes(scope)) {
+    return { held: false, leaseToken: null, failedOpen: false, reason: `bad-scope:${scope}` };
+  }
+  if (!resourceId) {
+    return { held: false, leaseToken: null, failedOpen: false, reason: "no-resource" };
+  }
+  const c = resolveClient(opts);
+  const ms = Number.isFinite(opts.failOpenTimeoutMs) ? opts.failOpenTimeoutMs : DEFAULT_FAIL_OPEN_MS;
+  const params = {
+    scope,
+    resourceId,
+    holder: opts.holder || undefined,
+    ttlMs: Number.isFinite(opts.ttlMs) ? opts.ttlMs : undefined,
+  };
+  const frame = await withTimeout(
+    Promise.resolve(c.leaseClaim(params, rpcOpts(opts))),
+    ms,
+    () => ({ __failOpen: true }),
+  );
+  if (frame && frame.__failOpen) {
+    // Server didn't answer in time → fail OPEN: proceed as if we hold it, but
+    // with no real lease token (so we can't heartbeat/release a phantom lease).
+    return { held: true, leaseToken: null, failedOpen: true, reason: "fail-open-timeout" };
+  }
+  if (frame && frame.ok) {
+    const res = frame.result || {};
+    const leaseToken = res.token || res.leaseToken || null;
+    return { held: true, leaseToken, failedOpen: false, reason: "claimed", frame };
+  }
+  // Adjudicated loss (CONFLICT/LEASE_HELD) or any other error frame → stand down.
+  const code = frame && frame.error && frame.error.code;
+  return { held: false, leaseToken: null, failedOpen: false, reason: code || "denied", frame };
+}
+
+/**
+ * Release a generic lease. Best-effort + bounded fail-open; a fail-open claim
+ * (no real token) is a no-op release. Never throws.
+ * @param {string} scope @param {string} resourceId
+ * @param {object} [opts] - { client?, base, token, fetchImpl?, leaseToken, failOpenTimeoutMs? }
+ * @returns {Promise<{released:boolean, reason:string}>}
+ */
+export async function releaseLease(scope, resourceId, opts = {}) {
+  if (!opts.leaseToken) return { released: false, reason: "no-token" };
+  const c = resolveClient(opts);
+  const ms = Number.isFinite(opts.failOpenTimeoutMs) ? opts.failOpenTimeoutMs : DEFAULT_FAIL_OPEN_MS;
+  const frame = await withTimeout(
+    Promise.resolve(c.leaseRelease({ scope, resourceId, leaseToken: opts.leaseToken }, rpcOpts(opts))),
+    ms,
+    () => ({ __failOpen: true }),
+  );
+  if (frame && frame.__failOpen) return { released: false, reason: "fail-open-timeout" };
+  return { released: !!(frame && frame.ok), reason: frame && frame.ok ? "released" : "error" };
+}
+
+/**
+ * Heartbeat a held lease (slide its expiry). Best-effort, bounded fail-open.
+ * @param {string} scope @param {string} resourceId
+ * @param {object} [opts] - { client?, base, token, fetchImpl?, leaseToken, failOpenTimeoutMs? }
+ * @returns {Promise<{ok:boolean, reason:string}>}
+ */
+export async function heartbeatLease(scope, resourceId, opts = {}) {
+  if (!opts.leaseToken) return { ok: false, reason: "no-token" };
+  const c = resolveClient(opts);
+  const ms = Number.isFinite(opts.failOpenTimeoutMs) ? opts.failOpenTimeoutMs : DEFAULT_FAIL_OPEN_MS;
+  const frame = await withTimeout(
+    Promise.resolve(c.leaseHeartbeat({ scope, resourceId, leaseToken: opts.leaseToken }, rpcOpts(opts))),
+    ms,
+    () => ({ __failOpen: true }),
+  );
+  if (frame && frame.__failOpen) return { ok: false, reason: "fail-open-timeout" };
+  return { ok: !!(frame && frame.ok), reason: frame && frame.ok ? "ok" : "error" };
+}
+
+// ---------------------------------------------------------------------------
+// thread-ownership (send arbitration §5.4)
+// ---------------------------------------------------------------------------
+
+/**
+ * Claim the right to reply in a shared channel thread (thread-ownership lease).
+ * Exactly one racing agent wins; the others get held:false. 3s fail-open.
+ *
+ * @param {string} channel  the (canonicalised) channel/chat id
+ * @param {string} thread   the thread root id (or "" for a top-level message)
+ * @param {object} [opts] - { client?, base, token, fetchImpl?, holder?, ttlMs?, failOpenTimeoutMs? }
+ * @returns {Promise<{held:boolean, leaseToken:string|null, failedOpen:boolean, reason:string, resourceId:string}>}
+ */
+export async function claimThread(channel, thread, opts = {}) {
+  const resourceId = threadResourceId(channel, thread);
+  const r = await claimLease(THREAD_OWNERSHIP_SCOPE, resourceId, {
+    ttlMs: Number.isFinite(opts.ttlMs) ? opts.ttlMs : DEFAULT_THREAD_TTL_MS,
+    ...opts,
+  });
+  return { ...r, resourceId };
+}
+
+/**
+ * Release a thread-ownership lease (e.g. after the reply is sent, or on stand-down).
+ * @param {string} channel @param {string} thread
+ * @param {object} [opts] - { client?, base, token, fetchImpl?, leaseToken, failOpenTimeoutMs? }
+ * @returns {Promise<{released:boolean, reason:string}>}
+ */
+export function releaseThread(channel, thread, opts = {}) {
+  return releaseLease(THREAD_OWNERSHIP_SCOPE, threadResourceId(channel, thread), opts);
+}
+
+/**
+ * The cancellable PRE-SEND arbitration check the channel send path calls before
+ * replying in a shared channel (§5.4 rule 3, the send-time backstop). Returns
+ * `{mayReply, leaseToken}`: exactly one agent gets mayReply:true for a given
+ * thread (the server adjudicates the single winner). Channels that are NOT
+ * claim-on-receive short-circuit to mayReply:true with no lease round-trip.
+ *
+ * On a 3s server timeout it FAILS OPEN (mayReply:true, failedOpen:true) so a
+ * down coordination plane never silences the agent — the caller increments the
+ * fail-open counter and reports on reconnect.
+ *
+ * @param {object} args - {
+ *   platform, channel, thread?, ownership?, agentRoot?,
+ *   client?, base, token, fetchImpl?, holder?, ttlMs?, failOpenTimeoutMs?
+ * }
+ * @returns {Promise<{mayReply:boolean, leaseToken:string|null, failedOpen:boolean, arbitrated:boolean, reason:string, resourceId?:string}>}
+ */
+export async function preSendArbitration(args = {}) {
+  const { platform, channel, thread } = args;
+  // Resolve the ownership config (injected or read from disk).
+  const ownership = args.ownership || (await loadOwnership(args.agentRoot || "."));
+  if (!isClaimOnReceive(ownership, platform, channel)) {
+    // Not an arbitrated channel — reply freely, no lease spent.
+    return { mayReply: true, leaseToken: null, failedOpen: false, arbitrated: false, reason: "not-arbitrated" };
+  }
+  const r = await claimThread(channel, thread || "", args);
+  return {
+    mayReply: r.held,
+    leaseToken: r.leaseToken,
+    failedOpen: r.failedOpen,
+    arbitrated: true,
+    reason: r.reason,
+    resourceId: r.resourceId,
+  };
+}