@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/org/mesh.mjs

@@ -29,6 +29,12 @@
  *        - "session.restart" → touch state/session/restart-requested; the main
  *                           session's feed sees it and the session restarts itself
  *                           at an idle moment (design §3.10). The daemon stays up.
+ *      Every beat outcome is also RECORDED locally in state/org/last-beat.json
+ *      {at, ok, code?} — the only on-disk evidence that the org has actually
+ *      ACKNOWLEDGED this daemon (a log line says the daemon tried; `ok:true`
+ *      says the server answered 2xx). scripts/local-triggers/autoupdate.sh gates
+ *      on it: a daemon can be alive, log "org-mesh connected" and still be
+ *      401'd on every beat — or crash-looping — and nobody in the org sees it.
  *   3. stop() — clears the interval so the daemon can shut the mesh down cleanly.
  *
  * FAIL-OPEN by design (mirrors lib/org/client): if the org is disabled
@@ -193,6 +199,55 @@ function escalateCriticalAlerts(agentRoot, alerts, now) {
   }
 }
 
+/** Where the last beat outcome is recorded, relative to the agent root. */
+export const LAST_BEAT_FILE = join("state", "org", "last-beat.json");
+
+/**
+ * Record the outcome of ONE presence beat in state/org/last-beat.json:
+ *   { at: ISO, ok: true, sdkVersion? }        — the org answered 2xx
+ *   { at: ISO, ok: false, code, message?, sdkVersion? }
+ *                                             — rejected (error frame) or the
+ *                                               transport failed (code "TRANSPORT")
+ * Overwritten on every beat, so `at` is always the LATEST attempt and `ok`
+ * says whether the org accepted it. This is what "the org can see this seat"
+ * means on disk: hq derives online/offline from the server-side presence.beat
+ * ledger (stale after 5 min), and this file is the daemon's own copy of that
+ * fact. Readers (autoupdate.sh's health gate, doctor) compare `at` against the
+ * daemon's start time and require `ok === true`.
+ *
+ * `sdkVersion` is the version THIS beat told the org (status.machine.sdkVersion,
+ * which hq persists to AgentStatus.machine — the fleet view reads it). The
+ * ledger's presence.beat row keeps only a trimmed status, so this field is the
+ * only local proof that an accepted beat carried the installed version and
+ * not the one the previous daemon process was started on. Absent when the
+ * beat went out without a status (collector failure) — a reader treats absence
+ * as "no version proof", never as a mismatch.
+ *
+ * Atomic write, fail-open: a disk error is logged and never breaks the beat.
+ */
+function recordBeat(agentRoot, frame, now, transportError, status) {
+  const at = new Date((typeof now === "function" ? now() : Date.now())).toISOString();
+  const rec = { at, ok: !!(frame && frame.ok === true) };
+  const v = status && status.machine && typeof status.machine.sdkVersion === "string" ? status.machine.sdkVersion.trim() : "";
+  if (v) rec.sdkVersion = v;
+  if (!rec.ok) {
+    if (transportError) {
+      rec.code = "TRANSPORT";
+      rec.message = String((transportError && transportError.message) || transportError).slice(0, 200);
+    } else {
+      rec.code = (frame && frame.error && frame.error.code) || "UNKNOWN";
+      const msg = frame && frame.error && frame.error.message;
+      if (msg) rec.message = String(msg).slice(0, 200);
+    }
+  }
+  try {
+    writeJsonAtomic(join(agentRoot, LAST_BEAT_FILE), rec);
+  } catch (err) {
+    logWarn(`failed to record beat outcome in ${LAST_BEAT_FILE} (${err && err.message})`);
+  }
+  return rec;
+}
+
 /**
  * Collect the SHARED STATUS SNAPSHOT for this beat, fully fail-open: any collector
  * error yields `undefined` so the beat goes out WITHOUT a status (never broken).
@@ -384,9 +439,14 @@ async function beatOnce(ctx) {
     );
   } catch (err) {
     logWarn(`presence beat failed (${err && err.message}) — org may be down, continuing standalone`);
+    recordBeat(ctx.agentRoot, null, ctx.now, err || new Error("presence beat failed"), status);
     return [];
   }
 
+  // Record the outcome BEFORE acting on directives: a `halt` below stops the
+  // daemon, and the record must already say what the org last answered.
+  recordBeat(ctx.agentRoot, frame, ctx.now, undefined, status);
+
   // A REJECTED beat is not a thrown beat. `presenceBeat` RESOLVES with a res
   // FRAME — {ok:false,error:{code,message}} — for 401/403/404/500 alike, so the
   // catch above only ever sees transport failures. Without this, a beat the
@@ -545,6 +605,7 @@ export async function connectOrgMesh(o = {}) {
 
 export const _internals = {
   beatOnce,
+  recordBeat,
   extractDirectives,
   handleDirective,
   tripKillSwitch,

package/lib/org/messaging.mjs

@@ -193,7 +193,9 @@ async function emitAfterSend(ctx, deps = {}) {
  *   1. resolve org enrollment (disabled ⇒ fail-open error frame, no send).
  *   2. screenOutbound({channel, recipient:channel, text:body}) — a BLOCK returns
  *      a frame `{ok:false, error:{code:"FORBIDDEN_SCOPE"|"BAD_REQUEST", message}}`
- *      and the message is NEVER sent (no client.call).
+ *      and the message is NEVER sent (no client.call). This also covers thread
+ *      replies (params.threadId) — screenOutbound runs screenScaffold first, so
+ *      coverage here is real, just not visible at this call site.
  *   3. messaging.send RPC (Bearer + x-org-protocol + x-idempotency-key from the
  *      client-supplied message id, so a retried send dedupes server-side).
  *   4. on ok: emit afterSend + attribute the ledger row.

package/lib/org/protocol.checksum

@@ -1 +1 @@
-8bce96163171fc5b9f23ea03889cd9220113af09e14f87d704c635f33f9aa76e
+24cc454def1119b37d24b9b00232b98d5cd52352be08ca98b53843c610979af5

package/lib/org/protocol.mjs

@@ -236,6 +236,10 @@ export const METHODS = Object.freeze({
   "registry.register": { family: "registry", scope: "registry.write", sideEffecting: true, idempotent: true },
   "registry.heartbeat": { family: "registry", scope: "registry.write", sideEffecting: true },
   "presence.beat": { family: "presence", scope: "presence.write", sideEffecting: true },
+  // Read-only roll-out visibility: which SDK version every seat reports and
+  // whether its daemon is healthy. `org.read` (the fleet's shape is
+  // org-structural), floored to `fleet.view` in the handler.
+  "presence.fleetVersions": { family: "presence", scope: "org.read", sideEffecting: false },
   // --- board (kanban / backlog) ---
   "board.create": { family: "board", scope: "board.write", sideEffecting: true, idempotent: true },
   "board.claim": { family: "board", scope: "board.work", sideEffecting: true },
@@ -349,6 +353,17 @@ export const METHODS = Object.freeze({
   //     side-effecting exactly-one-append contract forbids — so it self-audits its
   //     own chain row like messaging.synthesizeVoiceNote and books.ask do. ---
   "messaging.electResponder": { family: "messaging", scope: "messaging.read", sideEffecting: false },
+  // --- messaging.silences (2026-09): WHY a message got no reply. Reads the
+  //     "responder"/"responder.silence" ledger rows hq's ambient responder writes
+  //     when it routes a human's message and stays quiet (deferred to a human,
+  //     or nobody elected) — for ONE message ({messageId}) or a channel over a
+  //     window ({channelId, windowDays?}). One of the two is required; the room
+  //     is ACL-checked through the same channel policy as messaging.history, and
+  //     there is no org-wide arm on this lane (that is the ADMIN panel's, under
+  //     audit.orgLog). Each row carries the operator reason vocabulary
+  //     (human_mentioned | addressed_to_human | nobody_elected | no_responders)
+  //     and its text. Pure read, zero appends. ---
+  "messaging.silences": { family: "messaging", scope: "messaging.read", sideEffecting: false },
   // --- calling (SP3): call lifecycle in the human app. NOT reserved-admin. ---
   "calling.start": { family: "calling", scope: "calling.write", sideEffecting: true },
   "calling.join": { family: "calling", scope: "calling.write", sideEffecting: true },

package/lib/org/quota.mjs

@@ -0,0 +1,520 @@
+/**
+ * lib/org/quota.mjs — the seat's view of its cohort-llm quota.
+ *
+ * Cohort quota UX comes from Cohort's own channel, not from
+ * `anthropic-ratelimit-unified-*` (design C6): the `GET /cohort/v1/quota`
+ * endpoint, the `x-cohort-quota-*` headers on every success, the terminal
+ * `event: cohort` SSE frame, and the `cohort` refusal object carried by every
+ * 402/429/503/529 body (wire contract §4.8).
+ *
+ * Two halves:
+ *
+ *   PURE   parsers for each of those four surfaces, and the decisions over
+ *          them — `refusalDisposition` (what a spawn site does with a refusal)
+ *          and `quotaBand` (warn at 75 %, at-limit at 100 %). No clock, no I/O:
+ *          `now` is a parameter.
+ *   EDGE   `createQuotaClient` — the GET with a short cache (≤ 30 s), single
+ *          flight, one retry after a 401 with a fresh token, and a snapshot on
+ *          disk (state/cohort-llm/quota.json) so a sibling process on the seat
+ *          (budget-guard in the cadence consumer) reads the same state without
+ *          its own network call.
+ *
+ * Money stays a decimal string of integer micro-USD end to end; nothing here
+ * turns it into a float except the display helpers budget-guard calls.
+ *
+ * @module lib/org/quota
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+
+import { writeJsonAtomic } from "../fs-atomic.mjs";
+
+/** The cache may never be older than this (the pre-spawn gate reads it). */
+export const QUOTA_MAX_TTL_MS = 30_000;
+export const QUOTA_DEFAULT_TTL_MS = 15_000;
+/** Utilization at which a window warns (contract: status "warning" at ≥ 0.75). */
+export const WARN_UTILIZATION = 0.75;
+export const LIMIT_UTILIZATION = 1;
+/** A limit refusal without a parseable resetsAt holds this long, flagged estimated. */
+export const DEFAULT_LIMIT_HOLD_MS = 30 * 60_000;
+export const CONCURRENCY_RETRY_MS = 2_000;
+export const OVERLOADED_RETRY_MS = 30_000;
+/** How long a failed quota read defers a spawn before the gate asks again. */
+export const QUOTA_UNAVAILABLE_RETRY_MS = 30_000;
+export const QUOTA_TIMEOUT_MS = 8_000;
+
+/** Every refusal code in the wire contract. */
+export const REFUSAL_CODES = Object.freeze([
+  "cohort_limit_exceeded",
+  "cohort_credits_exhausted",
+  "cohort_spend_limit_reached",
+  "cohort_concurrency_exceeded",
+  "cohort_upstream_overloaded",
+  "cohort_unpriced_model",
+  "cohort_unavailable",
+  "cohort_seat_suspended",
+  "cohort_seat_required",
+  "cohort_invalid_key",
+]);
+const WINDOWS = ["5h", "7d", "30d"];
+
+const str = (v) => (typeof v === "string" && v !== "" ? v : null);
+const numOrNull = (v) => {
+  if (v === null || v === undefined || v === "") return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+/** Integer micro-USD as a decimal string (digits, optional sign), or null. */
+const micros = (v) => {
+  if (typeof v === "number") return Number.isSafeInteger(v) ? String(v) : null;
+  if (typeof v !== "string") return null;
+  return /^-?\d+$/.test(v.trim()) ? v.trim() : null;
+};
+
+function header(headers, name) {
+  if (!headers) return null;
+  if (typeof headers.get === "function") return headers.get(name);
+  const key = Object.keys(headers).find((k) => k.toLowerCase() === name);
+  if (key === undefined) return null;
+  const v = headers[key];
+  return Array.isArray(v) ? v.join(", ") : v == null ? null : String(v);
+}
+
+// ---------------------------------------------------------------------------
+// Pure: parsers
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalise a refusal object (`<refusal>` in §4.8). Accepts `resets_at` as an
+ * alias of `resetsAt`. null unless it carries a cohort_* code.
+ * @param {any} raw
+ * @returns {{code:string, window:string|null, scope:string|null, resetsAt:string|null, retryable:boolean, requestId:string|null}|null}
+ */
+export function normaliseRefusal(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const code = str(raw.code);
+  if (!code || !code.startsWith("cohort_")) return null;
+  return {
+    code,
+    window: str(raw.window),
+    scope: str(raw.scope),
+    resetsAt: str(raw.resetsAt) || str(raw.resets_at),
+    retryable: raw.retryable === true,
+    requestId: str(raw.requestId) || str(raw.request_id),
+  };
+}
+
+/**
+ * The refusal carried by an error body on either wire. The top-level `cohort`
+ * object wins; an OpenAI-wire `error.code` (or Anthropic-wire `error`) naming a
+ * cohort code is the fallback.
+ * @param {string|object|null} body
+ * @returns {ReturnType<typeof normaliseRefusal>}
+ */
+export function parseRefusalBody(body) {
+  let o = body;
+  if (typeof body === "string") {
+    try { o = JSON.parse(body); } catch { return null; }
+  }
+  if (!o || typeof o !== "object") return null;
+  const top = normaliseRefusal(o.cohort);
+  if (top) return top;
+  const e = o.error && typeof o.error === "object" ? o.error : null;
+  return e ? normaliseRefusal({ ...e, code: e.code }) : null;
+}
+
+/**
+ * The `x-cohort-*` headers on a gateway response.
+ * @param {Headers|object} headers
+ */
+export function parseQuotaHeaders(headers) {
+  const windows = {};
+  for (const w of WINDOWS) {
+    const u = numOrNull(header(headers, `x-cohort-quota-${w}-utilization`));
+    const reset = str(header(headers, `x-cohort-quota-${w}-reset`));
+    if (u !== null || reset !== null) windows[w] = { utilization: u, resetsAt: reset };
+  }
+  return {
+    requestId: str(header(headers, "x-cohort-request-id")),
+    modelTier: str(header(headers, "x-cohort-model-tier")),
+    costMicros: micros(header(headers, "x-cohort-cost-micros")),
+    creditsRemainingMicros: micros(header(headers, "x-cohort-credits-remaining-micros")),
+    funding: str(header(headers, "x-cohort-funding")),
+    limitKind: str(header(headers, "x-cohort-limit-kind")),
+    shouldRetry: (() => {
+      const v = header(headers, "x-should-retry");
+      return v === "false" ? false : v === "true" ? true : null;
+    })(),
+    windows,
+  };
+}
+
+/**
+ * The terminal `event: cohort` frame. Accepts a raw SSE block (or a whole
+ * stream — the LAST cohort event wins), the frame's `data` JSON text, or the
+ * parsed object. An unparseable frame is null: it is advisory and must never
+ * fail a completion that streamed correctly.
+ * @param {string|object} input
+ */
+export function parseCohortSseFrame(input) {
+  let obj = null;
+  if (input && typeof input === "object") {
+    obj = input;
+  } else if (typeof input === "string") {
+    const text = input.trim();
+    if (text.startsWith("{")) {
+      try { obj = JSON.parse(text); } catch { obj = null; }
+    } else {
+      let data = null;
+      for (const block of text.split(/\r?\n\r?\n/)) {
+        const lines = block.split(/\r?\n/);
+        const ev = lines.find((l) => /^event:\s*/.test(l));
+        if (!ev || ev.replace(/^event:\s*/, "").trim() !== "cohort") continue;
+        data = lines.filter((l) => /^data:/.test(l)).map((l) => l.replace(/^data:\s?/, "")).join("\n");
+      }
+      if (data !== null) {
+        try { obj = JSON.parse(data); } catch { obj = null; }
+      }
+    }
+  }
+  if (!obj || typeof obj !== "object") return null;
+  const q = obj.quota && typeof obj.quota === "object" ? obj.quota : {};
+  const windows = {};
+  for (const w of WINDOWS) {
+    const win = q[w];
+    if (!win || typeof win !== "object") continue;
+    windows[w] = { utilization: numOrNull(win.utilization), resetsAt: str(win.resetsAt) || str(win.resets_at) };
+  }
+  return {
+    requestId: str(obj.request_id) || str(obj.requestId),
+    modelTier: str(obj.model_tier) || str(obj.modelTier),
+    costMicros: micros(obj.cost_micros ?? obj.costMicros),
+    funding: str(obj.funding),
+    windows,
+    usage: obj.usage && typeof obj.usage === "object" ? { ...obj.usage } : null,
+  };
+}
+
+/**
+ * Validate and normalise a `GET /cohort/v1/quota` 200 body.
+ * @param {any} body
+ * @returns {{ok:true, quota:object}|{ok:false, error:{code:string, message:string}}}
+ */
+export function parseQuotaResponse(body) {
+  if (!body || typeof body !== "object" || !Array.isArray(body.windows) || !body.canAdmit || typeof body.canAdmit !== "object") {
+    return { ok: false, error: { code: "cohort_quota_malformed", message: "the quota response is missing windows[] or canAdmit" } };
+  }
+  const windows = body.windows
+    .filter((w) => w && typeof w === "object" && WINDOWS.includes(w.kind))
+    .map((w) => ({
+      kind: w.kind,
+      limitMicros: micros(w.limitMicros),
+      consumedMicros: micros(w.consumedMicros),
+      utilization: numOrNull(w.utilization),
+      resetsAt: str(w.resetsAt),
+      status: str(w.status),
+    }));
+  const canAdmit = body.canAdmit.ok === true
+    ? { ok: true, funding: str(body.canAdmit.funding) }
+    : { ok: false, cohort: normaliseRefusal(body.canAdmit.cohort) || { code: "cohort_unavailable", window: null, scope: null, resetsAt: null, retryable: false, requestId: null } };
+  return {
+    ok: true,
+    quota: {
+      principal: body.principal && typeof body.principal === "object" ? { ...body.principal } : null,
+      windows,
+      extraUsageEnabled: body.extraUsageEnabled === true,
+      credits: body.credits && typeof body.credits === "object"
+        ? { remainingMicros: micros(body.credits.remainingMicros), overageEnabled: body.credits.overageEnabled === true }
+        : null,
+      spendLimits: (Array.isArray(body.spendLimits) ? body.spendLimits : [])
+        .filter((s) => s && typeof s === "object")
+        .map((s) => ({ scope: str(s.scope), period: str(s.period), limitMicros: micros(s.limitMicros), consumedMicros: micros(s.consumedMicros), resetsAt: str(s.resetsAt) })),
+      canAdmit,
+      asOf: str(body.asOf),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pure: decisions
+// ---------------------------------------------------------------------------
+
+/**
+ * What a spawn site does with a refusal.
+ *
+ *   cohort_limit_exceeded, cohort_spend_limit_reached → defer_until resetsAt
+ *   cohort_credits_exhausted                          → hold_for_credits
+ *   cohort_concurrency_exceeded, cohort_upstream_overloaded → retry afterMs
+ *   cohort_unavailable (a gateway-side provider outage)     → retry afterMs
+ *   anything else                                      → fail
+ *
+ * @param {object|null} refusal  a normalised refusal
+ * @param {{now?:number, retryAfterMs?:number|null, defaultHoldMs?:number, unavailableRetryMs?:number}} [o]
+ *   unavailableRetryMs overrides QUOTA_UNAVAILABLE_RETRY_MS (the 30 s
+ *   cohort_unavailable hold; its value is pending owner confirmation, CF-143)
+ * @returns {{kind:"defer_until", until:number, code:string, estimated?:true} |
+ *           {kind:"hold_for_credits", code:string} |
+ *           {kind:"retry", afterMs:number, code:string} |
+ *           {kind:"fail", code:string|null}}
+ */
+export function refusalDisposition(refusal, o = {}) {
+  const r = refusal && typeof refusal === "object" ? refusal : null;
+  const code = r ? r.code : null;
+  const now = Number.isFinite(o.now) ? o.now : 0;
+  const retryAfter = Number.isFinite(o.retryAfterMs) && o.retryAfterMs >= 0 ? o.retryAfterMs : null;
+  switch (code) {
+    case "cohort_limit_exceeded":
+    case "cohort_spend_limit_reached": {
+      const until = r.resetsAt ? Date.parse(r.resetsAt) : NaN;
+      if (Number.isFinite(until)) return { kind: "defer_until", until, code };
+      return { kind: "defer_until", until: now + (Number.isFinite(o.defaultHoldMs) ? o.defaultHoldMs : DEFAULT_LIMIT_HOLD_MS), code, estimated: true };
+    }
+    case "cohort_credits_exhausted":
+      return { kind: "hold_for_credits", code };
+    case "cohort_concurrency_exceeded":
+      return { kind: "retry", afterMs: retryAfter ?? CONCURRENCY_RETRY_MS, code };
+    case "cohort_upstream_overloaded":
+      return { kind: "retry", afterMs: retryAfter ?? OVERLOADED_RETRY_MS, code };
+    case "cohort_unavailable":
+      // Cohort's own provider key is refused or unfunded upstream (503,
+      // x-should-retry: true): a gateway outage, not this seat's credential or
+      // quota. Back off and look again; never a fail-hold, never a re-mint.
+      return { kind: "retry", afterMs: retryAfter ?? (Number.isFinite(o.unavailableRetryMs) && o.unavailableRetryMs >= 0 ? o.unavailableRetryMs : QUOTA_UNAVAILABLE_RETRY_MS), code };
+    default:
+      return { kind: "fail", code };
+  }
+}
+
+/**
+ * The seat's band from a quota snapshot: the worst window (and spend limit)
+ * utilization, "approaching" at ≥ 75 %, "at" at ≥ 100 % or when canAdmit is
+ * refused. An absent snapshot is "unknown".
+ * @param {object|null} quota a parseQuotaResponse().quota
+ * @returns {{band:"ok"|"approaching"|"at"|"unknown", utilization:number|null,
+ *            window:string|null, resetsAt:string|null, canAdmit:boolean|null,
+ *            limitMicros:string|null, consumedMicros:string|null}}
+ */
+export function quotaBand(quota) {
+  if (!quota || typeof quota !== "object") {
+    return { band: "unknown", utilization: null, window: null, resetsAt: null, canAdmit: null, limitMicros: null, consumedMicros: null };
+  }
+  let worst = null;
+  const consider = (label, utilization, resetsAt, limitMicros, consumedMicros) => {
+    if (utilization === null || !Number.isFinite(utilization)) return;
+    if (!worst || utilization > worst.utilization) worst = { window: label, utilization, resetsAt, limitMicros, consumedMicros };
+  };
+  for (const w of quota.windows || []) consider(w.kind, w.utilization, w.resetsAt, w.limitMicros, w.consumedMicros);
+  for (const s of quota.spendLimits || []) {
+    const lim = Number(s.limitMicros);
+    const used = Number(s.consumedMicros);
+    if (Number.isFinite(lim) && lim > 0 && Number.isFinite(used)) consider(`spend:${s.scope}:${s.period}`, used / lim, s.resetsAt, s.limitMicros, s.consumedMicros);
+  }
+  const admits = quota.canAdmit ? quota.canAdmit.ok === true : null;
+  const u = worst ? worst.utilization : 0;
+  const band = admits === false || u >= LIMIT_UTILIZATION ? "at" : u >= WARN_UTILIZATION ? "approaching" : "ok";
+  return {
+    band,
+    utilization: worst ? worst.utilization : null,
+    window: worst ? worst.window : null,
+    resetsAt: worst ? worst.resetsAt : (quota.canAdmit && quota.canAdmit.cohort && quota.canAdmit.cohort.resetsAt) || null,
+    canAdmit: admits,
+    limitMicros: worst ? worst.limitMicros : null,
+    consumedMicros: worst ? worst.consumedMicros : null,
+  };
+}
+
+/**
+ * The admission answer for a quota read (or a failed read). Pure.
+ * @param {{ok:boolean, quota?:object, error?:object, refusal?:object, retryAfterMs?:number}} read
+ * @param {number} now
+ */
+export function admissionFromRead(read, now) {
+  if (read && read.ok && read.quota) {
+    const ca = read.quota.canAdmit;
+    if (ca && ca.ok) return { ok: true, funding: ca.funding || null, quota: read.quota };
+    const refusal = (ca && ca.cohort) || null;
+    return { ok: false, refusal, disposition: refusalDisposition(refusal, { now }), quota: read.quota };
+  }
+  const error = (read && read.error) || { code: "cohort_quota_unavailable", message: "no quota read" };
+  if (read && read.refusal) {
+    const d = refusalDisposition(read.refusal, { now, retryAfterMs: read.retryAfterMs });
+    if (d.kind !== "fail") return { ok: false, refusal: read.refusal, disposition: d, error };
+  }
+  // A seat whose key is refused cannot be fixed by waiting 30 s.
+  const hard = error.code === "cohort_invalid_key" || error.code === "cohort_seat_required" || error.code === "cohort_seat_key_missing" || error.code === "cohort_seat_suspended";
+  return {
+    ok: false,
+    error,
+    refusal: read && read.refusal ? read.refusal : null,
+    disposition: hard ? { kind: "fail", code: error.code } : { kind: "retry", afterMs: QUOTA_UNAVAILABLE_RETRY_MS, code: error.code },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Edge: the client
+// ---------------------------------------------------------------------------
+
+/** Where the seat's last quota snapshot lives. */
+export function quotaStatePath(agentRoot) {
+  return join(resolve(agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd()), "state", "cohort-llm", "quota.json");
+}
+
+/**
+ * Read the persisted snapshot if it is no older than `maxAgeMs`. Never throws.
+ * @param {string} path
+ * @param {number} now
+ * @param {number} maxAgeMs
+ * @returns {object|null} the normalised quota, with `fetchedAt`
+ */
+export function readQuotaSnapshot(path, now, maxAgeMs) {
+  try {
+    if (!existsSync(path)) return null;
+    const rec = JSON.parse(readFileSync(path, "utf-8"));
+    const at = rec && Number(rec.fetchedAtMs);
+    if (!rec || !rec.quota || !Number.isFinite(at)) return null;
+    if (Number.isFinite(maxAgeMs) && now - at > maxAgeMs) return null;
+    return { ...rec.quota, fetchedAtMs: at };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.baseUrl
+ * @param {(opts?:{force?:boolean}) => Promise<{ok:boolean, token?:string, error?:object}>} o.getToken
+ * @param {() => void} [o.invalidateToken]
+ * @param {typeof fetch} [o.fetchImpl]
+ * @param {() => number} [o.now]
+ * @param {number} [o.ttlMs]  clamped to ≤ 30 s
+ * @param {string|null} [o.statePath]
+ * @param {(level:string, msg:string) => void} [o.log]
+ */
+export function createQuotaClient(o = {}) {
+  const baseUrl = String(o.baseUrl || "").replace(/\/+$/, "");
+  const now = typeof o.now === "function" ? o.now : Date.now;
+  const ttlMs = Math.min(QUOTA_MAX_TTL_MS, Math.max(0, Number.isFinite(o.ttlMs) ? o.ttlMs : QUOTA_DEFAULT_TTL_MS));
+  const fetchImpl = typeof o.fetchImpl === "function" ? o.fetchImpl : globalThis.fetch;
+  const statePath = o.statePath || null;
+  const log = (level, msg) => { if (typeof o.log === "function") { try { o.log(level, msg); } catch { /* */ } } };
+  let cache = null; // {at, read}
+  let inflight = null;
+
+  async function fetchOnce(token) {
+    let res;
+    try {
+      res = await fetchImpl(`${baseUrl}/cohort/v1/quota`, {
+        method: "GET",
+        headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+        signal: typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(QUOTA_TIMEOUT_MS) : undefined,
+      });
+    } catch (err) {
+      return { ok: false, status: null, error: { code: "cohort_unavailable", message: `quota read did not complete: ${err && err.message ? err.message : err}` } };
+    }
+    let body = null;
+    try { body = await res.json(); } catch { body = null; }
+    if (!res.ok) {
+      const refusal = parseRefusalBody(body);
+      const ra = numOrNull(header(res.headers, "retry-after"));
+      return {
+        ok: false,
+        status: res.status,
+        refusal,
+        retryAfterMs: ra === null ? null : ra * 1000,
+        error: { code: (refusal && refusal.code) || (res.status === 401 ? "cohort_invalid_key" : `http_${res.status}`), message: `quota read refused (HTTP ${res.status})` },
+      };
+    }
+    const parsed = parseQuotaResponse(body);
+    return parsed.ok ? { ok: true, status: res.status, quota: parsed.quota } : { ok: false, status: res.status, error: parsed.error };
+  }
+
+  async function load() {
+    if (!baseUrl || typeof fetchImpl !== "function" || typeof o.getToken !== "function") {
+      return { ok: false, error: { code: "cohort_quota_unconfigured", message: "the quota client has no base URL, fetch, or token source" } };
+    }
+    let t = await o.getToken();
+    if (!t || !t.ok) return { ok: false, error: (t && t.error) || { code: "cohort_unavailable", message: "no seat token" } };
+    let read = await fetchOnce(t.token);
+    if (!read.ok && read.status === 401) {
+      // The token was revoked or rotated under us: mint once more, then give up.
+      // Naming the refused token lets the manager serve a replacement another
+      // process already minted, and caps re-mints per window (CF-136). A 503 or
+      // a 429 on this read never reaches here, so it never mints.
+      const refused = t.token;
+      if (typeof o.invalidateToken === "function") o.invalidateToken(refused);
+      t = await o.getToken({ force: true, rejected: refused });
+      if (!t || !t.ok) return { ok: false, error: (t && t.error) || { code: "cohort_invalid_key", message: "the seat token was refused" } };
+      read = await fetchOnce(t.token);
+    }
+    return read;
+  }
+
+  /**
+   * The quota, from the cache when it is fresh.
+   * @param {{force?:boolean}} [opts]
+   */
+  async function getQuota(opts = {}) {
+    const t = now();
+    if (!opts.force && cache && t - cache.at <= ttlMs) return { ...cache.read, cached: true };
+    if (!inflight) {
+      inflight = load()
+        .then((read) => {
+          const at = now();
+          cache = { at, read };
+          if (read.ok && statePath) {
+            try {
+              mkdirSync(dirname(statePath), { recursive: true });
+              writeJsonAtomic(statePath, { fetchedAtMs: at, quota: read.quota });
+            } catch (err) {
+              log("warn", `could not persist the quota snapshot: ${err && err.message ? err.message : err}`);
+            }
+          }
+          if (!read.ok) log("warn", `cohort-llm quota read failed: ${read.error && read.error.code}`);
+          return read;
+        })
+        .finally(() => { inflight = null; });
+    }
+    return inflight;
+  }
+
+  /** The cached read when fresh, else null. Synchronous. */
+  function peek() {
+    if (cache && now() - cache.at <= ttlMs) return cache.read;
+    return null;
+  }
+
+  /** May a cohort-routed session start now? */
+  async function canAdmit(opts = {}) {
+    const read = await getQuota(opts);
+    return admissionFromRead(read, now());
+  }
+
+  /** Synchronous admission from the cache; `{cold:true}` when there is none. */
+  function canAdmitCached() {
+    const read = peek();
+    if (!read) return { cold: true };
+    return admissionFromRead(read, now());
+  }
+
+  function invalidate() { cache = null; }
+
+  return { getQuota, peek, canAdmit, canAdmitCached, invalidate, ttlMs, baseUrl, statePath };
+}
+
+export default {
+  REFUSAL_CODES,
+  normaliseRefusal,
+  parseRefusalBody,
+  parseQuotaHeaders,
+  parseCohortSseFrame,
+  parseQuotaResponse,
+  refusalDisposition,
+  quotaBand,
+  admissionFromRead,
+  quotaStatePath,
+  readQuotaSnapshot,
+  createQuotaClient,
+};