@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/org/llm-token.mjs

@@ -0,0 +1,879 @@
+/**
+ * lib/org/llm-token.mjs — the seat's short-lived cohort-llm token.
+ *
+ * A seat talks to the cohort-llm gateway with a `cst_…` seat token, never with
+ * its long-lived OrgApiKey and never with an Anthropic credential. The token is
+ * minted by exchanging the seat-bound OrgApiKey at `POST /cohort/v1/tokens`
+ * (hq docs/cohort-llm/design.md §4.3 lane 2, wire contract §4.8):
+ *
+ *   POST <base>/cohort/v1/tokens
+ *     Authorization: Bearer <seat-bound OrgApiKey>
+ *     body {"purpose":"llm","ttlSeconds":3600}
+ *   200  {"token":"cst_<id>_<secret>","tokenType":"Bearer","expiresAt":"…",
+ *         "orgId":"…","memberId":"…","seatBand":"…|null","baseUrl":"…"}
+ *   401 cohort_invalid_key · 403 cohort_seat_required · 503 cohort_unavailable
+ *
+ * What this module guarantees:
+ *   - CACHED twice: in memory, and on disk at state/cohort-llm/token.json (mode
+ *     0600, through lib/fs-atomic.mjs — the repo's durable-write seam) so a
+ *     second process on the seat (the apiKeyHelper, the cadence consumer) reuses
+ *     the token instead of minting its own. The disk record carries a
+ *     fingerprint of the OrgApiKey, never the key: a rotated key invalidates it.
+ *   - REFRESHED at 80% of the token's lifetime, not at expiry, so a spawn never
+ *     starts on a token about to die. A refresh that fails while the current
+ *     token is still valid keeps serving it (and says so) — a gateway blip must
+ *     not take down a seat whose credential still works.
+ *   - SINGLE-FLIGHT: concurrent callers share one in-flight exchange.
+ *   - TYPED returned errors: `{ok:false, error:{code, message, status}}` with
+ *     code cohort_invalid_key | cohort_seat_required | cohort_unavailable |
+ *     cohort_token_exchange_failed | cohort_seat_key_missing. Nothing throws.
+ *   - NEVER LOGS A SECRET: every log line and error message passes through
+ *     `redactSecrets`, which strips `cst_…`, `nlk_…`, `sk-ant-…` shapes and the
+ *     literal key/token values.
+ *
+ * @module lib/org/llm-token
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, mkdirSync, openSync, closeSync, unlinkSync, writeFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { writeJsonAtomic } from "../fs-atomic.mjs";
+import { loadOrgConfig } from "./client.mjs";
+import { createQuotaClient, quotaStatePath } from "./quota.mjs";
+
+/** The production gateway, used when neither config nor env names one. */
+export const DEFAULT_LLM_BASE_URL = "https://llm.cohortapp.com";
+/** Refresh once this fraction of the token's lifetime has elapsed. */
+export const TOKEN_REFRESH_FRACTION = 0.8;
+/** Requested lifetime; the contract caps it at 3600. */
+export const DEFAULT_TOKEN_TTL_SECONDS = 3600;
+/** How long one exchange may take before it counts as `cohort_unavailable`. */
+export const EXCHANGE_TIMEOUT_MS = 10_000;
+/**
+ * A FORCED exchange (after a 401) may run at most MAX_REMINTS_PER_WINDOW times
+ * per REMINT_WINDOW_MS for one seat key, across every process on the seat (the
+ * history is kept in the token record on disk, read and written under a lock).
+ * Without it each 401 minted a fresh gateway token, and a gateway that refuses
+ * every token became a mint storm (CF-136). A plain read that finds the token
+ * invalidated after a 401 is a forced exchange too.
+ */
+export const REMINT_WINDOW_MS = 5 * 60_000;
+export const MAX_REMINTS_PER_WINDOW = 3;
+/**
+ * A forced attempt that ends in `cohort_unavailable` (the token endpoint was
+ * down, so no token was issued) spends budget for this shorter window instead:
+ * an outage still bounds attempts, but a recovered gateway is not locked out
+ * for the full REMINT_WINDOW_MS.
+ */
+export const UNAVAILABLE_REMINT_WINDOW_MS = 60_000;
+/**
+ * The re-mint caps as one named config (CF-143). The VALUES are the W7 defaults
+ * and stay as they are pending owner confirmation; `createTokenManager({
+ * remintCaps })` overrides them per manager (tests, or an owner decision
+ * landing in config). docs/engine/README.md "Retry caps" lists every cap.
+ */
+export const DEFAULT_REMINT_CAPS = Object.freeze({
+  max: MAX_REMINTS_PER_WINDOW,
+  windowMs: REMINT_WINDOW_MS,
+  unavailableWindowMs: UNAVAILABLE_REMINT_WINDOW_MS,
+});
+/**
+ * A token exchange that meets a transient outage (503/5xx or 408 at POST
+ * /cohort/v1/tokens, or a refused connection) is retried inside the SAME
+ * exchange (CF-143): at most `maxRetries` times, sleeping retry-after when the
+ * gateway sent one (never longer than `maxRetryAfterMs` — a longer one ends the
+ * retries) else the `backoffMs` ladder. `deadlineMs` bounds the WHOLE exchange,
+ * sends included, from the first send: a retry starts only when its sleep plus
+ * `minSendMs` still fits, and every send's request timeout is cut to what is
+ * left of the deadline, so a slow outage ends by `deadlineMs` and the engine
+ * (which kills its token helper at 20 s, TOKEN_HELPER_TIMEOUT_MS) reads the
+ * helper's own `cohort_unavailable` instead of a kill. An exchange issues at
+ * most one token and spends the re-mint budget once, whatever it retries, so
+ * this cannot become a mint storm. A request that times out (our own
+ * EXCHANGE_TIMEOUT_MS, or the deadline cut) is not retried.
+ */
+export const DEFAULT_EXCHANGE_RETRY = Object.freeze({
+  maxRetries: 2,
+  backoffMs: Object.freeze([500, 1000]),
+  maxRetryAfterMs: 5_000,
+  deadlineMs: 15_000,
+  minSendMs: 1_000,
+});
+/** The token record's cross-process lock: how long to wait, and when a holder counts as dead. */
+const RECORD_LOCK_TIMEOUT_MS = 2_000;
+const RECORD_LOCK_SPIN_MS = 5;
+/** The env var the engine sets for the helper: the fingerprint of the token a 401 refused. */
+export const REJECTED_TOKEN_FP_ENV = "COHORT_LLM_TOKEN_REJECTED_FP";
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+/** The helper Claude Code runs as `apiKeyHelper` on a cohort retarget. */
+export const API_KEY_HELPER_PATH = join(REPO_ROOT, "scripts", "cohort-llm", "api-key-helper.mjs");
+
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+
+// ---------------------------------------------------------------------------
+// Pure: configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * The gateway base URL. Config `org.cohort.llmBaseUrl` first, then
+ * `COHORT_LLM_BASE_URL`, then the production default. Trailing slashes are
+ * dropped so `<base>/v1` and `<base>/cohort/v1/…` are always well formed.
+ * @param {{cfg?:object, env?:object}} [o]
+ * @returns {string}
+ */
+export function resolveLlmBaseUrl({ cfg, env = process.env } = {}) {
+  const n = (cfg && cfg.org && cfg.org.cohort) || {};
+  const picked = [n.llmBaseUrl, env && env.COHORT_LLM_BASE_URL].find(nonEmpty) || DEFAULT_LLM_BASE_URL;
+  return String(picked).trim().replace(/\/+$/, "");
+}
+
+/**
+ * The catalog endpoints for the cohort provider at a base URL (design §8.3:
+ * both wires point at the gateway).
+ * @param {string} baseUrl
+ */
+export function cohortEndpoints(baseUrl) {
+  const b = String(baseUrl || DEFAULT_LLM_BASE_URL).replace(/\/+$/, "");
+  return { openai: `${b}/v1`, anthropic: b };
+}
+
+/**
+ * The seat's OrgApiKey — the same resolution order as lib/org/client.mjs
+ * `configFromAgent` (config token → COHORT_API_TOKEN → COHORT_TOKEN →
+ * COHORT_API_KEY), with the env injected, and the agent's `.env` as a last
+ * resort for a child (the apiKeyHelper) whose env was scrubbed of credentials.
+ * @param {{cfg?:object, env?:object, dotEnv?:object}} [o]
+ * @returns {string} "" when the seat has none
+ */
+export function seatApiKey({ cfg, env = process.env, dotEnv } = {}) {
+  const n = (cfg && cfg.org && cfg.org.cohort) || {};
+  const e = env || {};
+  const d = dotEnv || {};
+  const picked = [n.token, e.COHORT_API_TOKEN, e.COHORT_TOKEN, e.COHORT_API_KEY, d.COHORT_API_TOKEN, d.COHORT_TOKEN, d.COHORT_API_KEY].find(nonEmpty);
+  return picked ? String(picked).trim() : "";
+}
+
+/** Where a seat's token record lives. */
+export function tokenStatePath(agentRoot) {
+  return join(resolve(agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd()), "state", "cohort-llm", "token.json");
+}
+
+/** A short, non-reversible fingerprint of a credential (for cache keys and logs). */
+export function keyFingerprint(secret) {
+  return createHash("sha256").update(String(secret || "")).digest("hex").slice(0, 16);
+}
+
+/**
+ * Single-quote a string for /bin/sh (Claude Code runs apiKeyHelper in a shell).
+ * @param {string} s
+ */
+function shq(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The `apiKeyHelper` command for a seat: node + the helper + the agent root.
+ * No secret is ever on this command line — the helper reads the cached token,
+ * or the seat's key from config/.env, itself.
+ * @param {{agentRoot:string, nodeBin?:string, helperPath?:string}} o
+ */
+export function apiKeyHelperCommand({ agentRoot, nodeBin = process.execPath, helperPath = API_KEY_HELPER_PATH } = {}) {
+  return `${shq(nodeBin)} ${shq(helperPath)} --agent-root ${shq(resolve(agentRoot || process.cwd()))}`;
+}
+
+// ---------------------------------------------------------------------------
+// Pure: redaction, refresh policy, error classification
+// ---------------------------------------------------------------------------
+
+const SECRET_SHAPES = [/cst_[A-Za-z0-9_\-]+/g, /nlk_[A-Za-z0-9_\-]+/g, /sk-ant-[A-Za-z0-9_\-]+/g];
+
+/**
+ * Remove every secret from a string: the known credential shapes, plus any
+ * literal value passed in `secrets` (an OrgApiKey need not look like nlk_…).
+ * @param {unknown} text
+ * @param {string[]} [secrets]
+ * @returns {string}
+ */
+export function redactSecrets(text, secrets = []) {
+  let out = String(text ?? "");
+  for (const s of secrets) {
+    if (nonEmpty(s) && s.length >= 6) out = out.split(s).join("***");
+  }
+  for (const re of SECRET_SHAPES) out = out.replace(re, "***");
+  return out;
+}
+
+/**
+ * Has this record reached its refresh point (80% of lifetime) or expired?
+ * A record with unparseable times always needs a refresh.
+ * @param {object|null} rec  {token, issuedAt, expiresAt}
+ * @param {number} nowMs
+ * @param {number} [fraction]
+ */
+export function needsRefresh(rec, nowMs, fraction = TOKEN_REFRESH_FRACTION) {
+  if (!rec || !nonEmpty(rec.token)) return true;
+  const issued = Date.parse(rec.issuedAt);
+  const expires = Date.parse(rec.expiresAt);
+  if (!Number.isFinite(issued) || !Number.isFinite(expires)) return true;
+  if (expires <= issued) return nowMs >= expires;
+  return nowMs >= issued + fraction * (expires - issued);
+}
+
+/** Is the token still valid at all (not yet expired)? */
+export function isUnexpired(rec, nowMs) {
+  if (!rec || !nonEmpty(rec.token)) return false;
+  const expires = Date.parse(rec.expiresAt);
+  return Number.isFinite(expires) && nowMs < expires;
+}
+
+/** In-window entries of a history, ascending. A future-stamped entry (clock skew) still counts. */
+function inWindow(history, nowMs, windowMs) {
+  return (Array.isArray(history) ? history : [])
+    .filter((at) => Number.isFinite(at) && at > nowMs - windowMs)
+    .sort((a, b) => a - b);
+}
+
+/**
+ * The sliding-window re-mint budget. PURE.
+ * @param {unknown} history  epoch ms of earlier forced mints
+ * @param {number} nowMs
+ * @param {{max?:number, windowMs?:number, unavailable?:unknown, unavailableWindowMs?:number}} [o]
+ *   `unavailable`: epoch ms of forced attempts that ended in cohort_unavailable,
+ *   counted for the shorter `unavailableWindowMs`.
+ * @returns {{allowed:boolean, recent:number[], retryAt:number|null}}
+ */
+export function remintBudget(history, nowMs, { max = MAX_REMINTS_PER_WINDOW, windowMs = REMINT_WINDOW_MS, unavailable = [], unavailableWindowMs = UNAVAILABLE_REMINT_WINDOW_MS } = {}) {
+  const recent = inWindow(history, nowMs, windowMs);
+  const expiries = [
+    ...recent.map((at) => at + windowMs),
+    ...inWindow(unavailable, nowMs, unavailableWindowMs).map((at) => at + unavailableWindowMs),
+  ].sort((a, b) => a - b);
+  if (expiries.length < max) return { allowed: true, recent, retryAt: null };
+  return { allowed: false, recent, retryAt: expiries[expiries.length - max] };
+}
+
+/**
+ * Merge copies of one re-mint history. PURE. Every copy is some process's view
+ * of the same append-only list, so a timestamp appears as many times as the
+ * copy that holds it most often (two mints in the same millisecond stay two).
+ * @param {...unknown} copies
+ * @returns {number[]} ascending
+ */
+export function mergeRemintHistory(...copies) {
+  const counts = new Map();
+  for (const copy of copies) {
+    if (!Array.isArray(copy)) continue;
+    const here = new Map();
+    for (const at of copy) if (Number.isFinite(at)) here.set(at, (here.get(at) || 0) + 1);
+    for (const [at, n] of here) counts.set(at, Math.max(counts.get(at) || 0, n));
+  }
+  const out = [];
+  for (const [at, n] of counts) for (let i = 0; i < n; i++) out.push(at);
+  return out.sort((a, b) => a - b);
+}
+
+/**
+ * How long to wait before resending a token exchange that met a transient
+ * outage, or null to stop retrying. PURE.
+ * @param {{attempt:number, retryAfterMs?:number|null, elapsedMs?:number}} s
+ *   attempt: retries already made (0 before the first retry)
+ * @param {{maxRetries:number, backoffMs:readonly number[], maxRetryAfterMs:number, deadlineMs:number, minSendMs?:number}} [caps]
+ *   a retry is refused unless elapsed + wait + minSendMs ≤ deadlineMs, so the
+ *   send it leads to still has time to complete inside the deadline
+ * @returns {number|null}
+ */
+export function exchangeRetryDelay({ attempt, retryAfterMs = null, elapsedMs = 0 }, caps = DEFAULT_EXCHANGE_RETRY) {
+  if (!Number.isInteger(attempt) || attempt < 0 || attempt >= caps.maxRetries) return null;
+  let wait;
+  if (Number.isFinite(retryAfterMs) && retryAfterMs >= 0) {
+    if (retryAfterMs > caps.maxRetryAfterMs) return null; // not slept through
+    wait = retryAfterMs;
+  } else {
+    const ladder = caps.backoffMs;
+    wait = ladder.length ? ladder[Math.min(attempt, ladder.length - 1)] : 0;
+  }
+  const elapsed = Number.isFinite(elapsedMs) && elapsedMs > 0 ? elapsedMs : 0;
+  const minSend = Number.isFinite(caps.minSendMs) && caps.minSendMs > 0 ? caps.minSendMs : 0;
+  if (elapsed + wait + minSend > caps.deadlineMs) return null;
+  return wait;
+}
+
+/** retry-after (seconds or an HTTP date) in ms, or null. PURE. */
+export function parseRetryAfterMs(value, nowMs) {
+  if (value == null || value === "") return null;
+  const secs = Number(value);
+  if (Number.isFinite(secs)) return secs >= 0 ? Math.round(secs * 1000) : null;
+  const at = Date.parse(String(value));
+  return Number.isFinite(at) ? Math.max(0, at - nowMs) : null;
+}
+
+const EXCHANGE_CODES = new Set(["cohort_invalid_key", "cohort_seat_required", "cohort_unavailable"]);
+
+/**
+ * Map a failed exchange onto the typed error vocabulary. A cohort refusal code
+ * in the body wins; otherwise the status decides.
+ * @param {number|null} status
+ * @param {any} body parsed JSON body (or null)
+ * @returns {{code:string, message:string, status:number|null}}
+ */
+export function classifyExchangeFailure(status, body) {
+  const b = body && typeof body === "object" ? body : {};
+  const bodyCode = (b.cohort && b.cohort.code) || (b.error && b.error.code) || null;
+  const message = (b.error && typeof b.error.message === "string" && b.error.message) || null;
+  let code;
+  if (typeof bodyCode === "string" && EXCHANGE_CODES.has(bodyCode)) code = bodyCode;
+  else if (status === 401) code = "cohort_invalid_key";
+  else if (status === 403) code = "cohort_seat_required";
+  // 408: the gateway's body idle timeout — the request stalled, the key is fine.
+  else if (status === 408 || status === 503 || status === null || status >= 500) code = "cohort_unavailable";
+  else code = "cohort_token_exchange_failed";
+  const why = {
+    cohort_invalid_key: "the seat's OrgApiKey was refused by cohort-llm",
+    cohort_seat_required: "cohort-llm tokens need a seat-bound key (this key is seatless or a guest key)",
+    cohort_unavailable: "cohort-llm is unavailable",
+    cohort_token_exchange_failed: `the token exchange failed (HTTP ${status})`,
+  }[code];
+  return { code, message: message ? `${why}: ${message}` : why, status };
+}
+
+// ---------------------------------------------------------------------------
+// Edge: the token manager
+// ---------------------------------------------------------------------------
+
+function readRecord(path) {
+  try {
+    if (!existsSync(path)) return null;
+    const r = JSON.parse(readFileSync(path, "utf-8"));
+    return r && typeof r === "object" ? r : null;
+  } catch {
+    return null;
+  }
+}
+
+function busyWaitMs(ms) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { /* spin */ }
+}
+
+/**
+ * O_EXCL lock on `<record>.lock`, the same discipline as
+ * lib/model-router/health.mjs: spin on EEXIST, steal a lock older than the
+ * timeout (its holder died). Wall-clock time, never an injected clock: the lock
+ * is about real processes. null when it cannot be taken.
+ */
+function acquireRecordLock(lockPath) {
+  const deadline = Date.now() + RECORD_LOCK_TIMEOUT_MS;
+  for (;;) {
+    try {
+      const fd = openSync(lockPath, "wx");
+      try { writeFileSync(fd, JSON.stringify({ at: Date.now(), pid: process.pid })); } catch { /* stamp is best-effort */ }
+      return fd;
+    } catch (err) {
+      if (!err || err.code !== "EEXIST") return null;
+      try {
+        const heldAt = Number(JSON.parse(readFileSync(lockPath, "utf-8")).at);
+        if (Number.isFinite(heldAt) && Date.now() - heldAt > RECORD_LOCK_TIMEOUT_MS) {
+          try { unlinkSync(lockPath); } catch { /* another process stole it first */ }
+          continue;
+        }
+      } catch { /* unreadable (being written) — spin */ }
+      if (Date.now() >= deadline) return null;
+      busyWaitMs(RECORD_LOCK_SPIN_MS);
+    }
+  }
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.baseUrl      gateway base (no trailing slash)
+ * @param {string} o.apiKey       the seat's OrgApiKey
+ * @param {string} [o.statePath]  on-disk cache (null disables disk)
+ * @param {typeof fetch} [o.fetchImpl]
+ * @param {() => number} [o.now]
+ * @param {number} [o.ttlSeconds]
+ * @param {number} [o.timeoutMs]
+ * @param {(level:string, msg:string) => void} [o.log]
+ * @param {(ms:number) => Promise<void>} [o.sleep]  the exchange's retry sleep (default a real timer)
+ * @param {Partial<typeof DEFAULT_REMINT_CAPS>} [o.remintCaps]
+ * @param {Partial<typeof DEFAULT_EXCHANGE_RETRY>} [o.exchangeRetry]
+ * @param {(ms:number) => AbortSignal} [o.timeoutSignal]  one send's timeout signal (default AbortSignal.timeout; tests inject a clocked one)
+ */
+export function createTokenManager(o = {}) {
+  const baseUrl = String(o.baseUrl || DEFAULT_LLM_BASE_URL).replace(/\/+$/, "");
+  const apiKey = nonEmpty(o.apiKey) ? o.apiKey.trim() : "";
+  const keyFp = apiKey ? keyFingerprint(apiKey) : null;
+  const statePath = o.statePath === undefined ? null : o.statePath;
+  const now = typeof o.now === "function" ? o.now : Date.now;
+  const ttlSeconds = Math.min(DEFAULT_TOKEN_TTL_SECONDS, Math.max(60, Number(o.ttlSeconds) || DEFAULT_TOKEN_TTL_SECONDS));
+  const timeoutMs = Number(o.timeoutMs) > 0 ? Number(o.timeoutMs) : EXCHANGE_TIMEOUT_MS;
+  const fetchImpl = typeof o.fetchImpl === "function" ? o.fetchImpl : globalThis.fetch;
+  const sleep = typeof o.sleep === "function" ? o.sleep : (ms) => new Promise((r) => setTimeout(r, ms));
+  const caps = { ...DEFAULT_REMINT_CAPS, ...(o.remintCaps || {}) };
+  const retryCaps = { ...DEFAULT_EXCHANGE_RETRY, ...(o.exchangeRetry || {}) };
+  const timeoutSignal = typeof o.timeoutSignal === "function"
+    ? o.timeoutSignal
+    : (ms) => (typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(ms) : undefined);
+  let mem = null;
+  let inflight = null;
+  /**
+   * Forced-mint history this process has seen, merged with the disk record's on
+   * every locked write: `remints` (REMINT_WINDOW_MS) and `unavailable` — forced
+   * attempts that ended in cohort_unavailable (UNAVAILABLE_REMINT_WINDOW_MS).
+   */
+  let hist = { remints: [], unavailable: [] };
+  /** This process invalidated the token and has not minted since (the disk-less twin of `invalidatedAt`). */
+  let invalidatedHere = false;
+
+  const secrets = () => [apiKey, mem && mem.token].filter(Boolean);
+  const log = (level, msg) => {
+    if (typeof o.log !== "function") return;
+    try { o.log(level, redactSecrets(msg, secrets())); } catch { /* never throw from logging */ }
+  };
+  const fail = (err) => ({ ok: false, error: { ...err, message: redactSecrets(err.message, secrets()) } });
+  const view = (rec, extra = {}) => ({
+    ok: true,
+    token: rec.token,
+    expiresAt: rec.expiresAt,
+    orgId: rec.orgId ?? null,
+    memberId: rec.memberId ?? null,
+    seatBand: rec.seatBand ?? null,
+    baseUrl: rec.baseUrl || baseUrl,
+    ...extra,
+  });
+
+  /** The best record we hold for THIS key and base URL (memory, then disk). */
+  function current() {
+    if (mem && mem.keyFp === keyFp && mem.baseUrl === baseUrl) return mem;
+    if (!statePath) return null;
+    const disk = readRecord(statePath);
+    if (disk && disk.keyFp === keyFp && disk.baseUrl === baseUrl && nonEmpty(disk.token)) {
+      mem = disk;
+      return disk;
+    }
+    return null;
+  }
+
+  const mineOf = (disk) => (disk && disk.keyFp === keyFp ? disk : null);
+  const histFields = (h) => ({ remints: h.remints, remintsUnavailable: h.unavailable });
+
+  /** This process's history merged with the disk record's, pruned to the windows. */
+  function mergedHist(disk, t) {
+    const m = mineOf(disk);
+    return {
+      remints: inWindow(mergeRemintHistory(hist.remints, m && m.remints), t, caps.windowMs),
+      unavailable: inWindow(mergeRemintHistory(hist.unavailable, m && m.remintsUnavailable), t, caps.unavailableWindowMs),
+    };
+  }
+
+  /**
+   * Read-modify-write the disk record under its lock: `mutator(disk)` returns
+   * the record to write, or null to leave it. Without a state path the mutator
+   * runs against null and nothing is written. When the lock cannot be taken the
+   * write still happens, unlocked (a slightly racy history beats none). Never
+   * throws.
+   * @param {(disk:object|null) => object|null} mutator
+   */
+  function withRecord(mutator) {
+    if (!statePath) { mutator(null); return; }
+    const lockPath = `${statePath}.lock`;
+    let fd = null;
+    try {
+      mkdirSync(dirname(statePath), { recursive: true, mode: 0o700 });
+      fd = acquireRecordLock(lockPath);
+    } catch { fd = null; }
+    try {
+      const next = mutator(readRecord(statePath));
+      if (next) writeJsonAtomic(statePath, next, { mode: 0o600 });
+    } catch (err) {
+      log("warn", `could not persist the cohort-llm token record (${err && err.message ? err.message : err}); continuing in memory`);
+    } finally {
+      if (fd !== null) {
+        try { closeSync(fd); } catch { /* */ }
+        try { unlinkSync(lockPath); } catch { /* */ }
+      }
+    }
+  }
+
+  /** Was the token invalidated after a 401 with no mint since (here, or by any process on the seat)? */
+  function wasInvalidated() {
+    if (invalidatedHere) return true;
+    const m = statePath ? mineOf(readRecord(statePath)) : null;
+    return !!(m && !nonEmpty(m.token) && m.invalidatedAt);
+  }
+
+  /** @param {{forced?:boolean}} [xo] */
+  async function exchange(xo = {}) {
+    if (!apiKey) {
+      return fail({ code: "cohort_seat_key_missing", message: "this seat has no OrgApiKey (org.cohort.token / COHORT_API_KEY), so it cannot mint a cohort-llm token", status: null });
+    }
+    if (typeof fetchImpl !== "function") {
+      return fail({ code: "cohort_unavailable", message: "no fetch implementation available", status: null });
+    }
+    const issuedAt = now();
+    if (xo.forced) {
+      // Check and spend the budget in ONE locked step, so two processes cannot
+      // both read "2 of 3 used" and both mint. Counted when attempted, and
+      // persisted before the fetch: a helper that dies mid-mint still spent it.
+      let capped = null;
+      withRecord((disk) => {
+        const h = mergedHist(disk, issuedAt);
+        const budget = remintBudget(h.remints, issuedAt, { max: caps.max, windowMs: caps.windowMs, unavailable: h.unavailable, unavailableWindowMs: caps.unavailableWindowMs });
+        if (!budget.allowed) {
+          hist = h;
+          capped = budget;
+          return null;
+        }
+        hist = { remints: [...h.remints, issuedAt], unavailable: h.unavailable };
+        return { ...(mineOf(disk) || { keyFp }), ...histFields(hist) };
+      });
+      if (capped) {
+        return fail({
+          code: "cohort_token_remint_capped",
+          message: `cohort-llm refused ${caps.max} freshly minted tokens within ${Math.round(caps.windowMs / 60000)} minutes; not minting again before ${new Date(capped.retryAt).toISOString()}`,
+          status: null,
+          retryAt: capped.retryAt,
+        });
+      }
+    }
+    /** A forced attempt that issued no token because cohort-llm was down moves to the short window. */
+    const failExchange = (err) => {
+      if (xo.forced && err.code === "cohort_unavailable") {
+        const dropOne = (arr) => {
+          const list = Array.isArray(arr) ? arr : [];
+          const i = list.indexOf(issuedAt);
+          return i < 0 ? list : [...list.slice(0, i), ...list.slice(i + 1)];
+        };
+        hist = { remints: dropOne(hist.remints), unavailable: [...hist.unavailable, issuedAt] };
+        withRecord((disk) => {
+          const m = mineOf(disk);
+          const t = now();
+          hist = {
+            remints: inWindow(mergeRemintHistory(hist.remints, m && dropOne(m.remints)), t, caps.windowMs),
+            unavailable: inWindow(mergeRemintHistory(hist.unavailable, m && m.remintsUnavailable), t, caps.unavailableWindowMs),
+          };
+          return { ...(m || { keyFp }), ...histFields(hist) };
+        });
+      }
+      return fail(err);
+    };
+    // One exchange, bounded retries on a transient outage (DEFAULT_EXCHANGE_RETRY).
+    // The budget above was spent once for the whole exchange; at most one token
+    // is issued, so a retry here never counts as, or becomes, another mint.
+    let res;
+    let body = null;
+    for (let retries = 0; ; retries++) {
+      // Every send, and the body read it covers, ends by the exchange deadline:
+      // the request timeout is cut to what is left of it, so retries can never
+      // carry the helper past the engine's kill (TOKEN_HELPER_TIMEOUT_MS).
+      const leftMs = retryCaps.deadlineMs - (now() - issuedAt);
+      if (retries > 0 && leftMs <= 0) {
+        return failExchange({ code: "cohort_unavailable", message: `cohort-llm token endpoint still unavailable after ${retries} retries; the ${retryCaps.deadlineMs} ms exchange deadline has passed`, status: null });
+      }
+      const sendTimeoutMs = Math.max(1, Math.min(timeoutMs, leftMs));
+      const cutByDeadline = sendTimeoutMs < timeoutMs;
+      let transportError = null;
+      try {
+        res = await fetchImpl(`${baseUrl}/cohort/v1/tokens`, {
+          method: "POST",
+          headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json", accept: "application/json" },
+          body: JSON.stringify({ purpose: "llm", ttlSeconds }),
+          signal: timeoutSignal(sendTimeoutMs),
+        });
+        body = null;
+        try { body = await res.json(); } catch (err) {
+          // A body read aborted by the timeout is a transport failure, not an empty body.
+          if (err && (err.name === "TimeoutError" || err.name === "AbortError")) throw err;
+          body = null;
+        }
+      } catch (err) {
+        transportError = err || new Error("fetch failed");
+      }
+      const elapsedMs = now() - issuedAt;
+      if (transportError) {
+        // A timed-out send (EXCHANGE_TIMEOUT_MS, or cut short by the deadline) is not retried.
+        const timedOut = transportError.name === "TimeoutError" || transportError.name === "AbortError";
+        const wait = timedOut ? null : exchangeRetryDelay({ attempt: retries, elapsedMs }, retryCaps);
+        if (wait !== null) {
+          log("warn", `cohort-llm token exchange did not complete (${transportError.message || transportError}); retrying in ${wait} ms`);
+          await sleep(wait);
+          continue;
+        }
+        const why = timedOut && cutByDeadline
+          ? `no response before the ${retryCaps.deadlineMs} ms exchange deadline (after ${retries} retries)`
+          : `${transportError.message || transportError}`;
+        return failExchange({ code: "cohort_unavailable", message: `cohort-llm token exchange did not complete: ${why}`, status: null });
+      }
+      if (res.ok) break;
+      const failure = classifyExchangeFailure(res.status, body);
+      const header = (name) => (res.headers && typeof res.headers.get === "function" ? res.headers.get(name) : null);
+      if (failure.code === "cohort_unavailable" && header("x-should-retry") !== "false") {
+        const wait = exchangeRetryDelay({ attempt: retries, retryAfterMs: parseRetryAfterMs(header("retry-after"), now()), elapsedMs }, retryCaps);
+        if (wait !== null) {
+          log("warn", `cohort-llm token endpoint answered ${res.status} (cohort_unavailable); retrying in ${wait} ms`);
+          await sleep(wait);
+          continue;
+        }
+      }
+      return failExchange(failure);
+    }
+    const token = body && body.token;
+    const expiresMs = body ? Date.parse(body.expiresAt) : NaN;
+    if (!nonEmpty(token) || !Number.isFinite(expiresMs)) {
+      return fail({ code: "cohort_token_exchange_failed", message: "cohort-llm returned a token response without a token or a parseable expiresAt", status: res.status });
+    }
+    const rec = {
+      token,
+      tokenType: body.tokenType || "Bearer",
+      expiresAt: new Date(expiresMs).toISOString(),
+      issuedAt: new Date(issuedAt).toISOString(),
+      orgId: body.orgId ?? null,
+      memberId: body.memberId ?? null,
+      seatBand: body.seatBand ?? null,
+      baseUrl,
+      keyFp,
+      ...histFields(hist),
+    };
+    // Re-read under the lock and merge: another process may have spent budget
+    // while this fetch was in flight, and this write must not erase it.
+    withRecord((disk) => {
+      hist = mergedHist(disk, now());
+      Object.assign(rec, histFields(hist));
+      return rec;
+    });
+    mem = rec;
+    invalidatedHere = false;
+    log("info", `minted a cohort-llm seat token (key ${keyFp}, expires ${rec.expiresAt})`);
+    return view(rec, { refreshed: true });
+  }
+
+  /**
+   * A token fit to use now: cached when it is before its refresh point, else a
+   * (single-flight) exchange. A failed refresh falls back to a still-valid
+   * token, marked `stale:true`.
+   *
+   * After a 401 pass the refused token as `rejected` (or its fingerprint as
+   * `rejectedFp`, which is all the engine's helper is given). When the cached
+   * token is no longer that one — another request or process already replaced
+   * it — the replacement is served with no exchange. Otherwise the exchange is
+   * FORCED and counts against the re-mint budget (MAX_REMINTS_PER_WINDOW per
+   * REMINT_WINDOW_MS); past it the answer is `cohort_token_remint_capped`.
+   * `force:true` alone is a forced exchange under the same budget.
+   * @param {{force?:boolean, rejected?:string, rejectedFp?:string}} [opts]
+   */
+  async function getToken(opts = {}) {
+    let rec = current();
+    const t = now();
+    const rejectedFp = nonEmpty(opts.rejectedFp) ? opts.rejectedFp.trim() : nonEmpty(opts.rejected) ? keyFingerprint(opts.rejected) : null;
+    if (rejectedFp && rec && keyFingerprint(rec.token) === rejectedFp && statePath) {
+      // This process's memory holds the refused token; another process may
+      // already have written its replacement to disk.
+      const disk = readRecord(statePath);
+      if (disk && disk.keyFp === keyFp && disk.baseUrl === baseUrl && nonEmpty(disk.token) && keyFingerprint(disk.token) !== rejectedFp && isUnexpired(disk, t)) {
+        mem = disk;
+        rec = disk;
+      }
+    }
+    if (rejectedFp && rec && keyFingerprint(rec.token) !== rejectedFp && isUnexpired(rec, t)) {
+      return view(rec, { cached: true, replaced: true });
+    }
+    // No token because a 401 invalidated it: the next mint is a re-mint, whoever
+    // asks for it (a quota poll, the next helper run). Without this a plain read
+    // after invalidate() minted outside the budget.
+    const forced = !!opts.force || !!rejectedFp || (!rec && wasInvalidated());
+    if (!forced && rec && !needsRefresh(rec, t)) return view(rec, { cached: true });
+    if (!inflight) {
+      inflight = exchange({ forced }).finally(() => { inflight = null; });
+    }
+    const r = await inflight;
+    if (r.ok) return r;
+    const still = current();
+    if (!forced && still && isUnexpired(still, now())) {
+      log("warn", `cohort-llm token refresh failed (${r.error.code}); serving the current token until it expires at ${still.expiresAt}`);
+      return view(still, { stale: true, refreshError: r.error });
+    }
+    log("error", `cohort-llm token unavailable: ${r.error.code} — ${r.error.message}`);
+    return r;
+  }
+
+  /**
+   * Synchronous read of a token that is before its refresh point (or merely
+   * unexpired, with `allowStale`). null when there is nothing usable.
+   * @param {{allowStale?:boolean}} [opts]
+   */
+  function peek(opts = {}) {
+    const rec = current();
+    const t = now();
+    if (!rec) return null;
+    if (!needsRefresh(rec, t)) return view(rec, { cached: true });
+    if (opts.allowStale && isUnexpired(rec, t)) return view(rec, { stale: true });
+    return null;
+  }
+
+  /**
+   * Drop the cached token (after a 401 from the gateway). With `rejectedToken`,
+   * only when the cache still holds that token: a replacement another process
+   * already minted is kept. The re-mint history survives either way.
+   * @param {string} [rejectedToken]
+   */
+  function invalidate(rejectedToken) {
+    if (nonEmpty(rejectedToken)) {
+      if (mem && mem.token === rejectedToken) mem = null;
+      if (mem) return; // this process already holds a replacement
+    } else {
+      mem = null;
+    }
+    let replaced = false;
+    withRecord((disk) => {
+      const m = mineOf(disk);
+      if (nonEmpty(rejectedToken) && m && nonEmpty(m.token) && m.token !== rejectedToken) {
+        replaced = true; // another process wrote one
+        return null;
+      }
+      hist = mergedHist(disk, now());
+      // The marker makes the next mint on this seat a forced one, from any process.
+      return { invalidatedAt: new Date(now()).toISOString(), keyFp, baseUrl, ...histFields(hist) };
+    });
+    if (!replaced) invalidatedHere = true;
+  }
+
+  return { getToken, peek, invalidate, baseUrl, keyFp, statePath };
+}
+
+// ---------------------------------------------------------------------------
+// Edge: the seat's own manager (config + env resolved once per process)
+// ---------------------------------------------------------------------------
+
+/** Parse KEY=value lines (quotes stripped). Never throws. */
+function parseDotEnvFile(path) {
+  const out = {};
+  let body = "";
+  try { body = existsSync(path) ? readFileSync(path, "utf-8") : ""; } catch { return out; }
+  for (const raw of body.split("\n")) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/.exec(raw);
+    if (!m) continue;
+    const v = m[2].replace(/^(['"])(.*)\1$/, "$2");
+    if (v) out[m[1]] = v;
+  }
+  return out;
+}
+
+const _managers = new Map();
+
+/**
+ * The token manager for a seat, memoised per (state path, key, base URL).
+ * @param {object} [o]
+ * @param {string} [o.agentRoot]
+ * @param {object} [o.cfg]     org config (default: config/org.yaml)
+ * @param {object} [o.env]
+ * @param {boolean} [o.readDotEnv=false] also read <agentRoot>/.env for the key
+ * @param {typeof fetch} [o.fetchImpl]
+ * @param {() => number} [o.now]
+ * @param {(level:string, msg:string) => void} [o.log]
+ */
+export function seatTokenManager(o = {}) {
+  const agentRoot = resolve(o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+  const env = o.env || process.env;
+  const cfg = o.cfg !== undefined ? o.cfg : loadOrgConfig(agentRoot);
+  const dotEnv = o.readDotEnv ? parseDotEnvFile(join(agentRoot, ".env")) : undefined;
+  const baseUrl = resolveLlmBaseUrl({ cfg, env });
+  const apiKey = seatApiKey({ cfg, env, dotEnv });
+  const statePath = tokenStatePath(agentRoot);
+  const key = `${statePath}|${keyFingerprint(apiKey)}|${baseUrl}`;
+  if (!o.fetchImpl && !o.now && _managers.has(key)) return _managers.get(key);
+  const m = createTokenManager({ baseUrl, apiKey, statePath, fetchImpl: o.fetchImpl, now: o.now, log: o.log, sleep: o.sleep });
+  if (!o.fetchImpl && !o.now) _managers.set(key, m);
+  return m;
+}
+
+/**
+ * Can this seat authenticate to cohort-llm at all? True when it holds an
+ * OrgApiKey (config or env) or an unexpired cached token. Never throws.
+ *
+ * `helperReadable: true` is the router's question for a Path B retarget: can
+ * the apiKeyHelper — a grandchild of the scrubbed claude child, which never
+ * sees a `*_API_KEY` from the daemon's process env — mint a token? Only a key
+ * in config/org.yaml or <agentRoot>/.env, or a live cached token, counts. An
+ * env-only key would route the seat to the gateway with a helper that exits 1.
+ * @param {{agentRoot?:string, env?:object, cfg?:object, dotEnv?:object, now?:number, helperReadable?:boolean}} [o]
+ */
+export function hasSeatCredential(o = {}) {
+  try {
+    const env = o.env || process.env;
+    const agentRoot = o.agentRoot || env.AGENT_ROOT || env.AGENT_DIR;
+    if (!o.helperReadable && seatApiKey({ env })) return true;
+    if (!agentRoot) return false;
+    const cfg = o.cfg !== undefined ? o.cfg : loadOrgConfig(agentRoot);
+    if (seatApiKey({ cfg, env: {} })) return true;
+    if (o.helperReadable) {
+      const dotEnv = o.dotEnv !== undefined ? o.dotEnv : parseDotEnvFile(join(resolve(agentRoot), ".env"));
+      if (seatApiKey({ env: {}, dotEnv })) return true;
+    }
+    return isUnexpired(readRecord(tokenStatePath(agentRoot)), Number.isFinite(o.now) ? o.now : Date.now());
+  } catch {
+    return false;
+  }
+}
+
+const _clients = new Map();
+
+/**
+ * The seat's cohort-llm clients — its token manager and a quota client that
+ * authenticates with that token — memoised per seat so every gate in one
+ * process shares one quota cache.
+ * @param {object} [o]  as seatTokenManager, plus ttlMs
+ * @returns {{token: ReturnType<typeof createTokenManager>, quota: ReturnType<typeof createQuotaClient>}}
+ */
+export function seatCohortClients(o = {}) {
+  const agentRoot = resolve(o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+  const token = seatTokenManager({ ...o, agentRoot });
+  const injected = !!(o.fetchImpl || o.now);
+  const key = `${token.statePath}|${token.keyFp}|${token.baseUrl}`;
+  if (!injected && _clients.has(key)) return _clients.get(key);
+  const quota = createQuotaClient({
+    baseUrl: token.baseUrl,
+    getToken: (opts) => token.getToken(opts),
+    invalidateToken: (rejected) => token.invalidate(rejected),
+    fetchImpl: o.fetchImpl,
+    now: o.now,
+    ttlMs: o.ttlMs,
+    statePath: quotaStatePath(agentRoot),
+    log: o.log,
+  });
+  const pair = { token, quota };
+  if (!injected) _clients.set(key, pair);
+  return pair;
+}
+
+/** Test seam: forget every memoised seat manager and client. */
+export function _resetTokenManagersForTests() {
+  _managers.clear();
+  _clients.clear();
+}
+
+export default {
+  DEFAULT_LLM_BASE_URL,
+  resolveLlmBaseUrl,
+  cohortEndpoints,
+  seatApiKey,
+  tokenStatePath,
+  keyFingerprint,
+  apiKeyHelperCommand,
+  redactSecrets,
+  needsRefresh,
+  isUnexpired,
+  classifyExchangeFailure,
+  remintBudget,
+  exchangeRetryDelay,
+  parseRetryAfterMs,
+  DEFAULT_REMINT_CAPS,
+  DEFAULT_EXCHANGE_RETRY,
+  createTokenManager,
+  seatTokenManager,
+  seatCohortClients,
+  hasSeatCredential,
+};