@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/docs/runbooks/mac-mini-bootstrap.md

@@ -22,9 +22,9 @@ This runbook covers the complete setup of a Mac mini as the perpetual operations
 
 Before starting, ensure you have credentials for:
 
-- Claude Code Max subscription — the seat runs on a long-lived OAuth token
-  from `claude setup-token` (see Step 6); an Anthropic API key is the
-  pay-per-token alternative, not the default
+- A per-agent Claude Console API key in a workspace with a spend cap — the
+  fleet posture (see Step 6 and `docs/guides/billing-console-keys.md`). Do not
+  provision a seat on Max-subscription OAuth (`claude setup-token`)
 - GitHub (access to maestro repo)
 - Google Workspace (the-agent@the-company)
 - Slack (the company workspace)
@@ -114,14 +114,12 @@ cat > ~/.maestro-env << 'EOF'
 # the agent operating system Environment Variables
 # Source this file in your shell profile
 
-# Required — Claude auth. THE FLEET DEFAULT is the subscription OAuth token:
-# run `claude setup-token` on any machine where you are logged in, paste the
-# result here. (An ANTHROPIC_API_KEY is the pay-per-token alternative; set one
-# or the other, never both.) `maestro setup` writes the same two lines into the
-# agent's .env; doctor reports what `claude auth status` says (it reports the
-# token is present, it does not validate it — `claude -p "ping"` proves it).
-export CLAUDE_CODE_OAUTH_TOKEN="paste-the-output-of-claude-setup-token"
-export MAESTRO_PREFER_SUBSCRIPTION_AUTH=1
+# Required — Claude auth. THE FLEET POSTURE is a per-agent Console API key in a
+# workspace with a hard spend cap (docs/guides/billing-console-keys.md). Do not
+# set MAESTRO_PREFER_SUBSCRIPTION_AUTH or CLAUDE_CODE_OAUTH_TOKEN. `maestro
+# setup` writes the key into the agent's .env; `maestro doctor` verifies it with
+# a real API call.
+export ANTHROPIC_API_KEY="paste-this-agent's-console-api-key"
 
 # Optional but recommended
 export SLACK_TOKEN="your-slack-token-here"
@@ -145,8 +143,8 @@ source ~/.maestro-env
 Verify:
 
 ```bash
-echo $CLAUDE_CODE_OAUTH_TOKEN | head -c 10
-# Should print the first 10 characters of the token
+echo $ANTHROPIC_API_KEY | head -c 10
+# Should print the first 10 characters of the key
 ```
 
 **Security note**: Set file permissions to owner-only:
@@ -356,7 +354,7 @@ echo "=============================="
 - [ ] Git, Node.js, Python, jq, yq installed
 - [ ] Claude Code CLI installed and verified
 - [ ] maestro repo cloned to ~/maestro
-- [ ] Claude auth: CLAUDE_CODE_OAUTH_TOKEN (+ MAESTRO_PREFER_SUBSCRIPTION_AUTH=1) in the agent's .env
+- [ ] Claude auth: a per-agent Console API key (ANTHROPIC_API_KEY) in the agent's .env; `maestro doctor` shows it verified
 - [ ] Environment variables configured in ~/.maestro-env
 - [ ] File permissions set (chmod 600 on secrets)
 - [ ] MCP servers installed and configured

package/lib/action-executor.js

@@ -21,7 +21,9 @@ import {
   normalizeAccessLevel,
 } from "./tool-definitions.js";
 import { isOrgTool, executeOrgTool } from "./org/tool-surface.mjs";
-import { resolveClaudeBin, augmentedPath } from "./claude-bin.mjs";
+import { buildSpawn, DEFAULT_COHORT_TIER_MAP } from "./runtime/adapter.mjs";
+import { resolveSeatSpawn } from "./runtime/seat-engine.mjs";
+import { cohortTierFor } from "./model-router/catalog.mjs";
 
 const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
 
@@ -524,12 +526,26 @@ export async function executeLookup(toolName, input, agentRoot, opts = {}) {
   // unchanged. Fail-open: routing errors yield the historical `haiku` default.
   const routed = await resolveLookupModel(toolName, agentRoot, opts);
 
+  // The seat's engine, read per lookup (conformance row 36: a huddle's or a
+  // voice call's tools land here). A claude seat's buildSpawn input is exactly
+  // what it was; an engine-cohort seat runs `cli.mjs run` with its seat token
+  // and never falls back to claude. The engine is never handed a third-party
+  // model id the router chose for claude: the lane's own slot is used instead.
+  const seat = await (opts.resolveSeatSpawn || resolveSeatSpawn)(agentRoot);
+  const model = seat.engine === "cohort" && !cohortTierFor(routed.modelFlag, DEFAULT_COHORT_TIER_MAP)
+    ? LOOKUP_DEFAULT_MODEL
+    : routed.modelFlag;
+
   try {
     const { stdout } = await new Promise((resolve, reject) => {
-      execFile(resolveClaudeBin(), ["--print", "--model", routed.modelFlag, "-p", prompt], {
+      // argv + env from the runtime adapter (lane "lookup"):
+      // --print --model <m> -p <prompt>, TERM=dumb, PATH augmented.
+      const spec = (opts.buildSpawn || buildSpawn)({ lane: "lookup", model, prompt, env: process.env, ...seat.fields });
+      if (!spec.ok) return reject(new Error(spec.error.message));
+      execFile(spec.bin, spec.argv, {
         timeout: LOOKUP_TIMEOUT_MS,
         maxBuffer: LOOKUP_MAX_BUFFER,
-        env: { ...process.env, TERM: "dumb", PATH: augmentedPath() },
+        env: spec.env,
         cwd: agentRoot,
       }, (err, stdout, stderr) => {
         if (err) reject(err);

package/lib/budget-guard.mjs

@@ -57,6 +57,144 @@ import { join, resolve, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 
 import { summariseRows, imputeUnmeasured } from "./cost/ledger-row.mjs";
+import { quotaBand, quotaStatePath, readQuotaSnapshot } from "./org/quota.mjs";
+import { load as yamlLoad } from "js-yaml";
+
+// ---------------------------------------------------------------------------
+// cohort-metered seats (Cohort Compute, design §8.3)
+// ---------------------------------------------------------------------------
+//
+// A seat whose model routing uses the cohort provider (or whose runtime engine
+// is cohort) is metered by cohort-llm, not by this ledger. hq owns its limits —
+// the seat band's 5h/7d/30d windows, credits and spend limits — and publishes
+// them at GET /cohort/v1/quota. For such a seat the band comes from THAT
+// reading (lib/org/quota.mjs, persisted by the quota client at
+// state/cohort-llm/quota.json), never from summing local JSONL: the gateway's
+// number is the one that refuses, so it is the one that must pace.
+//
+//   utilization ≥ 75 %  → band 80  (warn the supervisor)
+//   utilization ≥ 100 % → band 100 (degrade: self-directed work stops)
+//   canAdmit refused    → band 100
+// Spawn-level refusal is the pre-spawn gate's job (lib/runtime/adapter.mjs
+// admitSpawn), which reads the same endpoint.
+
+/** A persisted quota reading older than this is not trusted for banding. */
+export const COHORT_QUOTA_MAX_AGE_MS = 10 * 60 * 1000;
+
+function agentRootFor(deps) {
+  return resolve((deps && deps.agentRoot) || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+}
+
+/** The catalog provider name cohort-llm rows carry (`cohort/<tier>`). */
+const COHORT_PROVIDER = "cohort";
+
+/** A ledger row billed by cohort-llm is metered by the quota, never summed here. */
+export function isCohortBilledRow(r) {
+  return !!(r && typeof r === "object" && r.billed_by === "cohort-llm");
+}
+
+/**
+ * How much of a routing config's traffic cohort-llm serves. PURE.
+ *   "none"   no routed ref names the cohort provider
+ *   "whole"  every routed ref is cohort AND the Anthropic safety net is off
+ *   "mixed"  anything else that routes at least one ref to cohort
+ * Routed refs are every routing_policy chain member (aliases resolved) plus
+ * every alias value; the fallback is Anthropic unless fallback_to_anthropic is
+ * explicitly false (the router's own rule). An unresolvable member counts as
+ * non-cohort — the conservative direction, because "mixed" takes the worse of
+ * both bands. Parsed, never regex-scanned: a commented-out ref routes nothing.
+ * @param {object|null} cfg  a parsed config/model-routing document
+ * @returns {"none"|"mixed"|"whole"}
+ */
+export function routingCohortMode(cfg) {
+  if (!cfg || typeof cfg !== "object") return "none";
+  const aliases = cfg.aliases && typeof cfg.aliases === "object" && !Array.isArray(cfg.aliases) ? cfg.aliases : {};
+  const refs = [];
+  const add = (member, depth = 0) => {
+    if (Array.isArray(member)) { for (const m of member) add(m, depth); return; }
+    if (typeof member !== "string") return;
+    const s = member.trim();
+    if (!s || s === "rules") return;
+    if (s.includes("/")) { refs.push(s); return; }
+    if (depth < 8 && Object.prototype.hasOwnProperty.call(aliases, s)) { add(aliases[s], depth + 1); return; }
+    refs.push(`unresolved:${s}`);
+  };
+  for (const v of Object.values(aliases)) add(v);
+  for (const rule of Array.isArray(cfg.routing_policy) ? cfg.routing_policy : []) {
+    if (rule && typeof rule === "object") add(rule.chain);
+  }
+  const isCohort = (ref) => ref.split("/")[0].trim().toLowerCase() === COHORT_PROVIDER;
+  const cohortRefs = refs.filter(isCohort).length;
+  if (cohortRefs === 0) return "none";
+  const everyRefCohort = cohortRefs === refs.length;
+  return everyRefCohort && cfg.fallback_to_anthropic === false ? "whole" : "mixed";
+}
+
+/** Read and parse the seat's routing config the way lib/model-router.mjs finds it. null on absence or a parse error. */
+function readRoutingConfigDoc(root, deps) {
+  if (deps && deps.routingConfig !== undefined) return deps.routingConfig;
+  const candidates = [
+    deps && deps.routingConfigPath,
+    process.env.MAESTRO_ROUTING_CONFIG,
+    join(root, "config", "model-routing.yaml"),
+    join(root, "config", "model-routing.json"),
+  ].filter(Boolean);
+  for (const p of candidates) {
+    try {
+      if (!existsSync(p)) continue;
+      const raw = readFileSync(p, "utf-8");
+      return p.endsWith(".json") ? JSON.parse(raw) : yamlLoad(raw);
+    } catch {
+      // The daemon falls back to the stock Anthropic CLI on an invalid config
+      // (dispatcher getRoutingConfig), so nothing routes to cohort: "none".
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * How this seat is metered by cohort-llm: {mode, source}. `deps.cohortMetered`
+ * (boolean → whole/none) or `deps.cohortMetering` ("none"|"mixed"|"whole")
+ * override. Otherwise config/agent.json runtime.engine === "cohort" → whole;
+ * else the parsed routing config ({@link routingCohortMode}). Never throws.
+ */
+export function cohortMetering(deps) {
+  if (deps && typeof deps.cohortMetering === "string" && ["none", "mixed", "whole"].includes(deps.cohortMetering)) {
+    return { mode: deps.cohortMetering, source: "override" };
+  }
+  if (deps && typeof deps.cohortMetered === "boolean") return { mode: deps.cohortMetered ? "whole" : "none", source: "override" };
+  const root = agentRootFor(deps);
+  try {
+    const agentJson = join(root, "config", "agent.json");
+    if (existsSync(agentJson)) {
+      const cfg = JSON.parse(readFileSync(agentJson, "utf-8"));
+      const engine = cfg && cfg.runtime && typeof cfg.runtime.engine === "string" ? cfg.runtime.engine.trim().toLowerCase() : "";
+      if (engine === "cohort") return { mode: "whole", source: "runtime.engine" };
+    }
+  } catch { /* unreadable agent.json → not cohort by this signal */ }
+  try {
+    return { mode: routingCohortMode(readRoutingConfigDoc(root, deps)), source: "model-routing" };
+  } catch {
+    return { mode: "none", source: "model-routing" };
+  }
+}
+
+/** Does cohort-llm serve ANY of this seat's traffic? (whole or mixed) */
+export function isCohortMetered(deps) {
+  return cohortMetering(deps).mode !== "none";
+}
+
+/** The seat's latest trusted quota reading, or null. `deps.cohortQuota` overrides. */
+function cohortQuotaFor(deps) {
+  if (deps && deps.cohortQuota !== undefined) return deps.cohortQuota;
+  return readQuotaSnapshot(quotaStatePath(agentRootFor(deps)), clock(deps)(), COHORT_QUOTA_MAX_AGE_MS);
+}
+
+const microsToUsd = (m) => {
+  const n = Number(m);
+  return Number.isFinite(n) ? +(n / 1e6).toFixed(6) : null;
+};
 
 // ---------------------------------------------------------------------------
 // Config
@@ -305,7 +443,7 @@ function sumToday(deps) {
   let malformed = 0;
   for (const line of body.split("\n")) {
     if (!line.trim()) continue;
-    try { rows.push(JSON.parse(line)); } catch { malformed += 1; }
+    try { const r = JSON.parse(line); if (!isCohortBilledRow(r)) rows.push(r); } catch { malformed += 1; }
   }
 
   const summary = summariseRows(rows);
@@ -369,7 +507,7 @@ function monthMeanSessionUsd(deps) {
     const rows = [];
     for (const line of body.split("\n")) {
       if (!line.trim()) continue;
-      try { rows.push(JSON.parse(line)); } catch { /* skip */ }
+      try { const r = JSON.parse(line); if (!isCohortBilledRow(r)) rows.push(r); } catch { /* skip */ }
     }
     const s = summariseRows(rows);
     usd += s.measuredUsd;
@@ -408,7 +546,7 @@ export function monthToDate(deps) {
     const rows = [];
     for (const line of body.split("\n")) {
       if (!line.trim()) continue;
-      try { rows.push(JSON.parse(line)); } catch { /* skip */ }
+      try { const r = JSON.parse(line); if (!isCohortBilledRow(r)) rows.push(r); } catch { /* skip */ }
     }
     const summary = summariseRows(rows);
     spentUSD += summary.measuredUsd + imputeUnmeasured(summary, { fallbackPerSessionUsd }).imputedUsd;
@@ -672,11 +810,47 @@ export function dailyAllowance(deps) {
  * the log every tick. `deps.subscriptionAuth` overrides for tests.
  */
 export function isSubscriptionAuth(deps) {
+  // A wholly cohort-served seat HAS a meter (cohort-llm), whatever its Claude
+  // auth says: it must never be waved through as a flat-fee subscription. On a
+  // MIXED seat this answers for the Anthropic half only (the local ledger); the
+  // cohort half is banded from the quota regardless (see dailyStatus).
+  if (cohortMetering(deps).mode === "whole") return false;
   if (deps && typeof deps.subscriptionAuth === "boolean") return deps.subscriptionAuth;
   return process.env.MAESTRO_PREFER_SUBSCRIPTION_AUTH === "1" && !process.env.ANTHROPIC_API_KEY;
 }
 
+/**
+ * The seat's budget status. A wholly cohort-served seat is banded from its
+ * /cohort/v1/quota reading alone. A MIXED seat (some routes cohort, some — or
+ * the safety net — Anthropic) is banded on the WORSE of the local ledger (its
+ * Anthropic traffic; cohort-billed rows are excluded) and the cohort quota, so
+ * neither meter can silently stop pacing the traffic it owns.
+ */
 export function dailyStatus(deps) {
+  const metering = cohortMetering(deps);
+  if (metering.mode === "whole") return cohortDailyStatus(deps);
+  const local = ledgerDailyStatus(deps);
+  if (metering.mode === "mixed") return worseOfLedgerAndCohort(local, cohortDailyStatus(deps));
+  return local;
+}
+
+/** Merge a mixed seat's two readings: the ledger status, with the cohort band when it is worse. */
+function worseOfLedgerAndCohort(local, cohort) {
+  const out = { ...local, cohortMetering: "mixed", cohort: cohort.cohort, bandSource: "ledger" };
+  out.degradations = [...(local.degradations || []), ...(cohort.degradations || [])];
+  if (cohort.band > local.band) {
+    const posture = postureForBand(cohort.band);
+    out.band = cohort.band;
+    out.mode = posture.mode;
+    out.posture = posture;
+    out.essentialOnly = cohort.band >= 125;
+    out.pct = Math.max(Number(local.pct) || 0, Number(cohort.pct) || 0);
+    out.bandSource = "cohort-quota";
+  }
+  return out;
+}
+
+function ledgerDailyStatus(deps) {
   const subscriptionAuth = isSubscriptionAuth(deps);
   const iterationCap = cfgIterationCap(deps);
   const today = sumToday(deps);
@@ -803,6 +977,77 @@ export function dailyStatus(deps) {
   };
 }
 
+/**
+ * dailyStatus for a cohort-metered seat: the same shape, banded from the
+ * seat's /cohort/v1/quota reading. Fail-open (band 0) with a loud degradation
+ * when no fresh reading exists — the pre-spawn gate still refuses a spawn the
+ * gateway would refuse.
+ */
+function cohortDailyStatus(deps) {
+  const quota = cohortQuotaFor(deps);
+  const q = quotaBand(quota);
+  const now = clock(deps)();
+  const degradations = [];
+  let band = 0;
+  if (q.band === "unknown") {
+    degradations.push(
+      "COHORT QUOTA UNKNOWN: this seat is metered by cohort-llm but has no fresh /cohort/v1/quota reading " +
+      `(state/cohort-llm/quota.json missing or older than ${COHORT_QUOTA_MAX_AGE_MS / 60000} min) — band 0; ` +
+      "the pre-spawn quota gate is the barrier until a reading lands."
+    );
+  } else if (q.band === "at") {
+    band = 100;
+  } else if (q.band === "approaching") {
+    band = 80;
+  }
+  for (const d of degradations) {
+    try { console.warn(`[budget-guard] degraded: ${d}`); } catch { /* never throw */ }
+  }
+  const pct = q.utilization === null ? (q.canAdmit === false ? 100 : 0) : q.utilization * 100;
+  const month = quota && Array.isArray(quota.windows) ? quota.windows.find((w) => w.kind === "30d") : null;
+  const posture = postureForBand(band);
+  const capUSD = microsToUsd(q.limitMicros) ?? 0;
+  const env = readSeatEnvelope(deps);
+  return {
+    spentUSD: microsToUsd(q.consumedMicros) ?? 0,
+    capUSD,
+    bandingCapUSD: capUSD,
+    pct: +pct.toFixed(2),
+    dayPct: null,
+    monthPct: month && month.utilization !== null ? +(month.utilization * 100).toFixed(2) : 0,
+    band,
+    mode: posture.mode,
+    posture,
+    essentialOnly: band >= 125,
+    sessions: 0,
+    iterationCap: cfgIterationCap(deps),
+    date: todayUtc(deps),
+    funded: q.band !== "unknown",
+    capSource: "cohort-quota",
+    configuredCapUSD: null,
+    envelope: {
+      seatBudgetCents: null,
+      monthUSD: month ? microsToUsd(month.limitMicros) : null,
+      source: "cohort-quota",
+      supervisorMemberId: env.supervisorMemberId,
+    },
+    month: {
+      spentUSD: month ? (microsToUsd(month.consumedMicros) ?? 0) : 0,
+      pct: month && month.utilization !== null ? +(month.utilization * 100).toFixed(2) : null,
+      daysInMonth: daysInUtcMonth(now),
+      dayOfMonth: new Date(now).getUTCDate(),
+    },
+    supervisorMemberId: env.supervisorMemberId || null,
+    measuredUSD: 0,
+    imputedUSD: 0,
+    unmeasuredSessions: 0,
+    nonLlmRows: 0,
+    blind: false,
+    degradations,
+    cohort: { band: q.band, utilization: q.utilization, window: q.window, resetsAt: q.resetsAt, canAdmit: q.canAdmit, asOf: quota ? quota.asOf || null : null },
+  };
+}
+
 /**
  * The lowest binding cap this period has run under, and the envelope it belongs
  * to. See the LATCH comment in {@link dailyStatus} for why banding may not use a
@@ -1140,6 +1385,7 @@ export function rollingWindowUsage(deps) {
       if (!line.trim()) continue;
       let r;
       try { r = JSON.parse(line); } catch { continue; }
+      if (isCohortBilledRow(r)) continue; // metered by the cohort quota, not these windows
       const at = r && r.ts ? Date.parse(r.ts) : NaN;
       if (!Number.isFinite(at)) continue;
       const dt = now - at;
@@ -1159,6 +1405,36 @@ export function rollingWindowUsage(deps) {
  * band is the WORSE of the 5h and weekly horizons.
  */
 export function windowBand(deps) {
+  const metering = cohortMetering(deps);
+  if (metering.mode === "none") return ledgerWindowBand(deps);
+  // cohort-llm's own windows (5h/7d/30d) are the pacing signal for its traffic.
+  const q = quotaBand(cohortQuotaFor(deps));
+  const cohort = {
+    band: q.band === "unknown" ? "ok" : q.band,
+    source: "cohort-quota",
+    active: q.band !== "unknown",
+    utilization: q.utilization,
+    window: q.window,
+    resetsAt: q.resetsAt,
+    canAdmit: q.canAdmit,
+    window5hTokens: 0, window5hSessions: 0, week7dTokens: 0, week7dSessions: 0,
+    cap5h: null, capWeek: null,
+  };
+  if (metering.mode === "whole") return cohort;
+  // Mixed: the worse of the local token windows (Anthropic traffic) and the quota.
+  const local = ledgerWindowBand(deps);
+  const rank = { ok: 0, approaching: 1, at: 2 };
+  const worse = rank[cohort.band] > rank[local.band] ? cohort.band : local.band;
+  return {
+    ...local,
+    band: worse,
+    source: rank[cohort.band] > rank[local.band] ? "cohort-quota" : "ledger",
+    active: local.active || cohort.active,
+    cohort: { band: cohort.band, active: cohort.active, utilization: q.utilization, window: q.window, resetsAt: q.resetsAt, canAdmit: q.canAdmit },
+  };
+}
+
+function ledgerWindowBand(deps) {
   const u = rollingWindowUsage(deps);
   // Caps come from deps first (tests / a per-seat override), else the env consts.
   const cap5 = deps && deps.cap5h != null ? deps.cap5h : WINDOW_5H_TOKEN_CAP;

package/lib/channels/base-adapter.mjs

@@ -448,7 +448,9 @@ export class BaseAdapter {
    * Order (gaps-product-quality P0-3/P0-5):
    *   1. send-gate — the hook-bus `beforeSend` cancellable chain AND the shared
    *      lib/comms/send-gate.screenOutbound. EITHER vetoing blocks the send.
-   *      Now EVERY adapter send passes the gate, not just Gmail.
+   *      Now EVERY adapter send passes the gate, not just Gmail. screenOutbound
+   *      runs screenScaffold first, so a raw model turn is caught here too —
+   *      coverage is real, just not visible at this call site.
    *   2. pair guard — a per-conversation sliding window so two agents in one
    *      channel can't reply-storm.
    *   3. _send — the adapter transport.

package/lib/channels/contract.mjs

@@ -33,7 +33,7 @@
 
 /**
  * @typedef {"message"|"reaction"|"channel_cc"|"voice_note"|"call"
- *          |"mention"|"thread_reply"|"task_assigned"|"task_comment"
+ *          |"mention"|"broadcast"|"thread_reply"|"task_assigned"|"task_comment"
  *          |"file_comment"|"approval"|"decision"|"escalation"|"handoff"
  *          |"email"} EventKind
  *
@@ -73,6 +73,7 @@ export const EVENT_KINDS = Object.freeze([
   "call",
   // Work surfaces (org inbound).
   "mention",
+  "broadcast",
   "thread_reply",
   "task_assigned",
   "task_comment",

package/lib/channels/inbox-item.mjs

@@ -310,6 +310,14 @@ export function eventToInboxItem(ev) {
     item.scope_id = sanitizeYamlField(scopeId);
   }
 
+  // A roll-call's respondent bound: how many AI members the org has, so the
+  // composer can be told it is "one of up to N" answering the same message.
+  // A number, never interpolated; absent for every other surface.
+  const respondents = cohort ? cohort.respondents : null;
+  if (Number.isFinite(respondents) && respondents > 0) {
+    item.respondents = Math.floor(respondents);
+  }
+
   // Carry attachments through when present (voice notes, media). The legacy
   // YAML writer (scripts/poller/utils.mjs) renders these when shaped as
   // { id, name, mimetype, size }; adapters that produce contract-style

package/lib/claude-bin.mjs

@@ -7,12 +7,11 @@
  * fails with ENOENT — even though the operator's interactive shell finds
  * it without trouble.
  *
- * Caller sites:
- *   - scripts/daemon/dispatcher.mjs   (reactive: replies to Slack/Gmail/etc)
- *   - scripts/daemon/responder.mjs    (quick replies + holding messages)
- *   - scripts/daemon/cadence-consumer.mjs (scheduled cadence ticks)
- *   - scripts/poller/intra-session-check.mjs
- *   - any other module that spawns claude from a non-interactive context
+ * Caller: lib/runtime/adapter.mjs, the runtime adapter seam, which owns the
+ * binary, argv and env of every JS lane that starts `claude` (it lists the 17
+ * lanes). Spawn sites ask the adapter, not this module. The remaining direct
+ * readers only resolve the binary without spawning it (the daemon's
+ * `claudeAvailable()` presence check, `global-setup`'s CLI probe).
  */
 
 import { existsSync, statSync } from "node:fs";