@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/runtime/adapter.mjs

@@ -0,0 +1,833 @@
+/**
+ * lib/runtime/adapter.mjs — the runtime adapter seam.
+ *
+ * The ONE owner of "which agent runtime, which binary, which argv, which env"
+ * for every JavaScript site that starts an agent runtime. A site describes what
+ * it wants (`lane`, `model`, `prompt`, …); `buildSpawn` answers with the exact
+ * `{bin, argv, env}` to hand to `spawn`/`execFile`/a multiplexer. Before this
+ * seam each of the 17 sites below built its own argv inline and five of them
+ * hand-built their own Claude auth env, so swapping the runtime meant editing
+ * ~20 files and re-deriving each one's credential rules (A1 §11).
+ *
+ * Engines
+ * -------
+ *   claude  the Claude Code CLI. Implemented; the default for every seat.
+ *   cohort  the Cohort Engine (lib/engine/cli.mjs `cohort run`). buildSpawn
+ *           maps the lane's claude `--print` argv onto engine flags
+ *           (`translateClaudeArgv`), runs it under this node, and hands it the
+ *           gateway URL + a seat token with every Anthropic/Claude credential
+ *           scrubbed. A flag the engine does not support yet is a returned
+ *           `engine_flag_unsupported` naming the flag — never silently dropped
+ *           (dropping `--allowedTools` would WIDEN a session's tools). No seat
+ *           runs it by default (design §8.4: flip per seat behind parity gates).
+ *           Outbound sends (CF-20): the engine screens and counts every
+ *           `mcp__*__{messaging_send,…}` call with its in-process send gate,
+ *           so this adapter mounts NO pre-send-audit hook for an engine spawn
+ *           (it passes no hook-bearing --settings at all). The seat's global
+ *           ~/.claude/settings.json still carries that hook for the claude
+ *           binary; the engine's hook runner skips it for the gated tools
+ *           (lib/engine/hooks.mjs `supersededBySendGate`), so a send is
+ *           counted once.
+ *
+ * cohort-llm admission
+ * --------------------
+ * A session routed to cohort-llm (engine cohort, or the claude binary
+ * retargeted to the cohort provider) must not start when the seat's quota
+ * already refuses it: stock Claude Code retries a 429 up to ten times and
+ * ignores the gateway's quota headers (design C6), so the gate BEFORE the spawn
+ * is the barrier. `admitSpawn` (async) / `admitSpawnCached` (sync, from the
+ * quota cache) answer with a typed deferral the call site turns into a requeue.
+ *
+ * Lanes (the JS spawn sites, A1 §3)
+ * ---------------------------------
+ *   dispatcher   scripts/daemon/dispatcher.mjs spawnSession       --print json, prompt argv, retargetable
+ *   resume       scripts/daemon/dispatcher.mjs buildResumeSpawn   same shape as dispatcher
+ *   cadence      scripts/daemon/cadence-consumer.mjs               --print json, prompt argv, retargetable
+ *   responder    scripts/daemon/responder.mjs runClaudeCLI         --print json, prompt stdin
+ *   classifier   scripts/daemon/classifier.mjs runClaudeCLI        --print, prompt stdin
+ *   ack          scripts/daemon/assurance.mjs runAckModel          --print, prompt stdin
+ *   lookup       lib/action-executor.js executeLookup              --print -p <prompt>
+ *   capture      lib/collective/capture.mjs defaultDistiller       --print, prompt stdin
+ *   reflect      lib/learning/reflect.mjs defaultReviewSpawn       --print, prompt stdin
+ *   curator      lib/learning/curator.mjs defaultConsolidateSpawn  --print, prompt stdin
+ *   enrich       lib/setup/enrich.mjs defaultSpawn                 --print, prompt argv
+ *   auth-status  lib/setup/claude-probe.mjs probeSubscription      `auth status --json`
+ *   mcp-register lib/cli/global-setup-extras.mjs                   `mcp add-json … --scope user`
+ *   main-session scripts/session/supervisor.mjs (launch-args)      interactive, --name/--session-id|--resume
+ *   peer         lib/cli/session.mjs `session spawn`               interactive, --name
+ *   voice-brief  lib/voice/post-call-brief.mjs briefSpawnSpec      --print, prompt argv
+ *   huddle       scripts/huddle/huddle-llm.mjs huddleCliSpawn      --print -p <prompt>
+ *
+ * Both voice lanes, and the lookup lane their tools reach, read the seat's
+ * engine per call (seat-engine resolveSeatSpawn, row 36). The huddle's direct API lane (HUDDLE_USE_API=1) is not a spawn: on
+ * a claude seat it is the Anthropic SDK, on an engine-cohort seat the engine
+ * wire to cohort-llm with the seat token (scripts/huddle/huddle-llm.mjs
+ * runHuddleApiTurn).
+ *
+ * Legacy shell lanes — NOT behind this seam
+ * -----------------------------------------
+ * Three shell scripts still run `claude` directly. They are legacy, manual or
+ * one-shot tools (no daemon lane depends on them). W4-E1 RETIRED them for
+ * engine-cohort seats: each calls lib/runtime/legacy-shell-guard.mjs first,
+ * which refuses (exit 3) when the seat's runtime.engine is cohort, and doctor
+ * warns on such seats. On a claude seat they run as before:
+ *   scripts/spawn-session.sh:115-124         `claude -p "$SESSION_PROMPT" --output-format text`
+ *   scripts/continuous-monitor.sh:48-57      `claude -p "<observe prompt>" --output-format text`
+ *   scripts/local-triggers/run-trigger.sh:59 `"$CLAUDE_BIN" --print --dangerously-skip-permissions "$PROMPT"`
+ * See {@link SHELL_LEGACY_LANES}.
+ *
+ * Env postures
+ * ------------
+ * Every lane's env is composed here from ONE credential builder,
+ * `lib/runtime/child-env.mjs#buildRuntimeEnv`, for the retargetable lanes, and
+ * from one of a small set of named postures for the rest. The postures are the
+ * five hand-built envs the sites used to carry, byte-for-byte:
+ *   stock-oauth  {...env, PATH, ANTHROPIC_API_KEY:"", ANTHROPIC_AUTH_TOKEN:""}
+ *                — strip stale API keys so the CLI rides the seat's
+ *                subscription credential (dispatcher/resume/responder/classifier/ack).
+ *                An API-key seat (no prefer flag, no OAuth token) keeps its
+ *                ANTHROPIC_API_KEY: stripping it would leave no credential.
+ *   cadence      {...env, AGENT_ROOT, AGENT_DIR, PATH}, ANTHROPIC_API_KEY deleted
+ *                when subscription auth is preferred or the key is a placeholder
+ *   path         {...env, PATH}              (capture/reflect/curator)
+ *   lookup       {...env, TERM:"dumb", PATH} (lookup)
+ *   huddle       {...env, TERM:"dumb"}       (huddle)
+ *   agent-root   {...env, AGENT_ROOT, AGENT_DIR} (voice-brief)
+ *   inherit      {...env}                    (enrich/auth-status/mcp-register/main-session/peer)
+ * A retarget (router envForSpawn carrying ANTHROPIC_BASE_URL) is accepted only
+ * on the three retargetable lanes and always goes through buildRuntimeEnv, which
+ * scrubs the OAuth token, forces the attribution header off and refuses a
+ * retarget with no third-party token.
+ *
+ * Results, not throws: an unavailable engine, an unsupported retarget or a
+ * refused retarget is a returned `{ok:false, error}`. An unknown lane is a
+ * programming defect and throws.
+ *
+ * @module lib/runtime/adapter
+ */
+
+"use strict";
+
+import { resolveClaudeBin, daemonClaudeArgs, augmentedPath } from "../claude-bin.mjs";
+import { join, dirname } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { buildRuntimeEnv, isRetarget, isCohortHelperRetarget, COHORT_HELPER_KEY } from "./child-env.mjs";
+import { buildClaudeArgs } from "../session/launch-args.mjs";
+import { cohortTierFor } from "../model-router/catalog.mjs";
+import { DEFAULT_LLM_BASE_URL, apiKeyHelperCommand } from "../org/llm-token.mjs";
+import { COHORT_BACKEND } from "../rate-guard.mjs";
+import { COLLECTIVE_CHILD_ENV } from "../collective/loop-guard.mjs";
+
+/** Engines a seat can name in `runtime.engine`. */
+export const ENGINES = Object.freeze(["claude", "cohort"]);
+export const DEFAULT_ENGINE = "claude";
+
+/** The legacy shell lanes that do not go through this seam (documented, not wired). */
+export const SHELL_LEGACY_LANES = Object.freeze([
+  Object.freeze({ path: "scripts/spawn-session.sh", invocation: "claude -p \"$SESSION_PROMPT\" --output-format text" }),
+  Object.freeze({ path: "scripts/continuous-monitor.sh", invocation: "claude -p \"<observe prompt>\" --output-format text" }),
+  Object.freeze({ path: "scripts/local-triggers/run-trigger.sh", invocation: "\"$CLAUDE_BIN\" --print --dangerously-skip-permissions \"$PROMPT\"" }),
+]);
+
+/** Placeholder API keys the cadence lane has always stripped. */
+const PLACEHOLDER_API_KEY = /^(your-api-key|placeholder|xxx+|sk-ant-xxx)/i;
+
+/**
+ * Pure: the engine a seat runs, from its agent config. `runtime.engine` must be
+ * one of {@link ENGINES}; anything else (absent, blank, unknown) is the default.
+ * @param {object} [agentConfig] config/agent.json
+ * @returns {"claude"|"cohort"}
+ */
+export function resolveEngine(agentConfig) {
+  const v = agentConfig && agentConfig.runtime && typeof agentConfig.runtime.engine === "string"
+    ? agentConfig.runtime.engine.trim().toLowerCase()
+    : "";
+  return ENGINES.includes(v) ? v : DEFAULT_ENGINE;
+}
+
+/**
+ * The engine the seat at `agentRoot` runs, read from its config/agent.json.
+ * The edge twin of {@link resolveEngine}: the daemon's pre-spawn gates call it
+ * so a seat on engine cohort is metered and gated even when model routing
+ * never names the cohort provider.
+ *
+ * An absent or unparseable config answers the default engine — exactly what
+ * `resolveEngine(undefined)` answers, and what every spawn on such a seat runs.
+ * @param {string} agentRoot
+ * @param {{readFile?:(p:string)=>string}} [deps]
+ * @returns {"claude"|"cohort"}
+ */
+export function readSeatEngine(agentRoot, deps = {}) {
+  const readFile = deps.readFile || ((p) => readFileSync(p, "utf-8"));
+  try {
+    return resolveEngine(JSON.parse(readFile(join(String(agentRoot || ""), "config", "agent.json"))));
+  } catch {
+    // No/invalid config/agent.json: the seat runs the default engine, so its
+    // gate is the default engine's gate (routing still decides cohort-ness).
+    return DEFAULT_ENGINE;
+  }
+}
+
+/** `--max-turns`/`--effort`/`--agents` from the router's spawn knobs. Order is fixed. */
+function knobArgs(knobs) {
+  const out = [];
+  if (!knobs || typeof knobs !== "object") return out;
+  if (knobs.maxTurns != null && Number.isFinite(Number(knobs.maxTurns))) out.push("--max-turns", String(knobs.maxTurns));
+  if (knobs.effort) out.push("--effort", String(knobs.effort));
+  if (knobs.agentsJson) out.push("--agents", typeof knobs.agentsJson === "string" ? knobs.agentsJson : JSON.stringify(knobs.agentsJson));
+  return out;
+}
+
+/** The MCP flags for a lane: none, strict-only, or the daemon's per-source set. */
+function mcpArgs(mcp, deps) {
+  if (mcp == null || mcp === false) return [];
+  if (mcp === "strict") return ["--strict-mcp-config"];
+  if (typeof mcp === "object") return deps.daemonArgs(mcp.agentRoot, mcp.source ? { source: mcp.source } : {});
+  return [];
+}
+
+const arr = (v) => (Array.isArray(v) ? v : []);
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+
+/** Is this env on Claude subscription auth (prefer flag, or an OAuth token)? */
+export function subscriptionAuth(env) {
+  const e = env && typeof env === "object" ? env : {};
+  return /^(1|true|yes)$/i.test(String(e.MAESTRO_PREFER_SUBSCRIPTION_AUTH || "").trim()) || nonEmpty(e.CLAUDE_CODE_OAUTH_TOKEN);
+}
+
+/**
+ * Lane table. `argv(i, x)` gets the normalised input and the computed flag
+ * fragments `x = {perm, mcp, knobs}`; `stdin` says whether the prompt is
+ * written to the child's stdin instead of argv; `posture` names the env shape;
+ * `retarget` says whether a router retarget is legal on the lane.
+ * `collectiveChild` marks the collective layer's own model passes: their env
+ * carries MAESTRO_COLLECTIVE_CHILD=1 so the global Stop/PreCompact hook does not
+ * capture the child's transcript (lib/collective/loop-guard.mjs) — without it,
+ * every capture spawns a session whose end spawns another capture.
+ */
+const LANES = Object.freeze({
+  dispatcher: {
+    posture: "stock-oauth", stdin: false, retarget: true,
+    argv: (i, x) => ["--print", "--output-format", "json", ...x.settings, ...x.perm, ...x.mcp, ...x.knobs, "--session-id", i.sessionId, "--model", i.model, i.prompt],
+  },
+  resume: {
+    posture: "stock-oauth", stdin: false, retarget: true,
+    argv: (i, x) => ["--print", "--output-format", "json", ...x.settings, ...x.perm, ...x.mcp, ...x.knobs, "--session-id", i.sessionId, "--model", i.model, i.prompt],
+  },
+  cadence: {
+    posture: "cadence", stdin: false, retarget: true,
+    argv: (i, x) => ["--print", "--output-format", "json", ...x.settings, ...x.perm, ...x.mcp, ...x.knobs, ...(i.model ? ["--model", String(i.model)] : []), i.prompt],
+  },
+  responder: {
+    posture: "stock-oauth", stdin: true, retarget: false,
+    argv: (i, x) => ["--print", ...x.perm, ...x.mcp, "--model", i.model, "--append-system-prompt", i.systemPrompt, "--output-format", "json", ...(i.sessionId ? ["--session-id", i.sessionId] : [])],
+  },
+  classifier: {
+    posture: "stock-oauth", stdin: true, retarget: false,
+    argv: (i, x) => ["--print", ...x.perm, ...x.mcp, "--model", i.model, "--append-system-prompt", i.systemPrompt],
+  },
+  ack: {
+    posture: "stock-oauth", stdin: true, retarget: false,
+    argv: (i, x) => ["--print", ...x.perm, ...x.mcp, "--model", i.model, "--append-system-prompt", i.systemPrompt],
+  },
+  lookup: {
+    posture: "lookup", stdin: false, retarget: false,
+    argv: (i) => ["--print", "--model", i.model, "-p", i.prompt],
+  },
+  capture: {
+    posture: "path", stdin: true, retarget: false, collectiveChild: true,
+    argv: (i, x) => ["--print", "--model", i.model, ...x.mcp],
+  },
+  reflect: {
+    posture: "path", stdin: true, retarget: false, collectiveChild: true,
+    argv: (i, x) => ["--print", "--model", i.model, ...x.mcp],
+  },
+  curator: {
+    posture: "path", stdin: true, retarget: false, collectiveChild: true,
+    argv: (i, x) => ["--print", "--model", i.model, ...x.mcp],
+  },
+  enrich: {
+    posture: "inherit", stdin: false, retarget: false,
+    argv: (i, x) => ["--print", ...x.mcp, "--model", i.model, "--append-system-prompt", i.systemPrompt, i.prompt],
+  },
+  "auth-status": {
+    posture: "inherit", stdin: false, retarget: false,
+    argv: () => ["auth", "status", "--json"],
+  },
+  "mcp-register": {
+    posture: "inherit", stdin: false, retarget: false,
+    argv: (i) => {
+      const r = i.registration || {};
+      return ["mcp", "add-json", r.name, r.config, "--scope", r.scope || "user"];
+    },
+  },
+  "main-session": {
+    posture: "inherit", stdin: false, retarget: false,
+    // launch-args owns the main-session argv contract (and its defect checks).
+    argv: (i, x) => buildClaudeArgs({
+      first: i.first,
+      sessionId: i.sessionId,
+      mode: i.resumeMode,
+      permissionArgs: x.perm,
+      extraArgs: arr(i.extraArgs),
+      prompt: i.prompt,
+    }),
+  },
+  peer: {
+    posture: "inherit", stdin: false, retarget: false,
+    argv: (i, x) => ["--name", i.name, ...x.perm, i.prompt],
+  },
+  "voice-brief": {
+    posture: "agent-root", stdin: false, retarget: false,
+    defaultPermissions: ["--dangerously-skip-permissions"],
+    argv: (i, x) => ["--print", ...x.perm, ...x.mcp, "--model", i.model, i.prompt],
+  },
+  huddle: {
+    posture: "huddle", stdin: false, retarget: false,
+    argv: (i) => ["--print", "--model", i.model, "-p", i.prompt],
+  },
+});
+
+/** Every lane name, for tests and docs. */
+export const LANE_NAMES = Object.freeze(Object.keys(LANES));
+
+/**
+ * Compose a lane's env. Pure over its inputs.
+ * @returns {{ok:true, env:object, retargeting:boolean}|{ok:false, error:object}}
+ */
+function laneEnv(spec, i, deps) {
+  const base = i.env && typeof i.env === "object" ? i.env : {};
+  const retargeting = isRetarget(i.retarget);
+  const path = () => deps.augmentedPath();
+
+  if (retargeting) {
+    // Only the retargetable lanes reach here (checked by the caller).
+    const pre = spec.posture === "cadence"
+      ? { ...base, AGENT_ROOT: i.agentRoot, AGENT_DIR: i.agentRoot, PATH: path() }
+      : { ...base, PATH: path() };
+    const built = buildRuntimeEnv({ baseEnv: pre, retarget: i.retarget });
+    if (!built.ok) return built;
+    const env = spec.posture === "cadence"
+      ? { ...built.env, AGENT_ROOT: i.agentRoot, AGENT_DIR: i.agentRoot, PATH: path() }
+      : { ...built.env, PATH: path() };
+    return { ok: true, env, retargeting: true };
+  }
+
+  switch (spec.posture) {
+    case "stock-oauth": {
+      // A non-retarget router set (an Anthropic decision) may still carry
+      // harmless keys; they ride on top exactly as the sites always merged them.
+      const overlay = i.retarget && typeof i.retarget === "object" ? i.retarget : {};
+      const env = { ...base, PATH: path(), ANTHROPIC_API_KEY: "", ANTHROPIC_AUTH_TOKEN: "", ...overlay };
+      // A seat on subscription auth (the prefer flag or an OAuth token) strips
+      // stale keys so the CLI rides the subscription — the historical posture,
+      // unchanged for every such seat. A seat with NEITHER is an API-key seat
+      // (the setup wizard's default since W1-E): blanking its key would leave
+      // the CLI with no credential at all, so the key is kept.
+      if (!subscriptionAuth(base) && nonEmpty(base.ANTHROPIC_API_KEY) && !("ANTHROPIC_API_KEY" in overlay)) {
+        env.ANTHROPIC_API_KEY = base.ANTHROPIC_API_KEY;
+      }
+      return { ok: true, retargeting: false, env };
+    }
+    case "cadence": {
+      const env = { ...base, AGENT_ROOT: i.agentRoot, AGENT_DIR: i.agentRoot, PATH: path() };
+      const preferSubscription = base.MAESTRO_PREFER_SUBSCRIPTION_AUTH === "1";
+      const apiKey = env.ANTHROPIC_API_KEY || "";
+      if (preferSubscription || !String(apiKey).trim() || PLACEHOLDER_API_KEY.test(apiKey)) delete env.ANTHROPIC_API_KEY;
+      return { ok: true, retargeting: false, env };
+    }
+    case "path":
+      return { ok: true, retargeting: false, env: { ...base, PATH: path() } };
+    case "lookup":
+      return { ok: true, retargeting: false, env: { ...base, TERM: "dumb", PATH: path() } };
+    case "huddle":
+      return { ok: true, retargeting: false, env: { ...base, TERM: "dumb" } };
+    case "agent-root":
+      return { ok: true, retargeting: false, env: { ...base, AGENT_ROOT: i.agentRoot, AGENT_DIR: i.agentRoot } };
+    case "inherit":
+    default:
+      return { ok: true, retargeting: false, env: { ...base } };
+  }
+}
+
+/**
+ * Build one runtime spawn.
+ *
+ * @param {object} i
+ * @param {string} i.lane           one of {@link LANE_NAMES} (unknown → throws: a defect)
+ * @param {"claude"|"cohort"} [i.engine="claude"]
+ * @param {string} [i.model]        the --model value
+ * @param {string} [i.prompt]       the prompt; argv or stdin per lane
+ * @param {string} [i.systemPrompt] --append-system-prompt (responder/classifier/ack/enrich)
+ * @param {string} [i.sessionId]    --session-id (dispatcher/resume/responder/main-session)
+ * @param {null|"strict"|{source?:string, agentRoot?:string}} [i.mcp] MCP flags
+ * @param {string[]} [i.permissions] resolved permission args (lib/session-permissions.mjs)
+ * @param {object} [i.knobs]        {maxTurns, effort, agentsJson} router spawn knobs
+ * @param {object} [i.env]          the base env (default process.env)
+ * @param {object} [i.retarget]     the router's envForSpawn (retargetable lanes only)
+ * @param {object} [i.extraEnv]     plain identifiers set after every merge (never credentials)
+ * @param {string[]} [i.extraArgs]  main-session only: args before the prompt
+ * @param {string} [i.agentRoot]    cadence/voice-brief: AGENT_ROOT/AGENT_DIR
+ * @param {string} [i.name]         peer: the --name value
+ * @param {string} [i.first]        main-session: the agent's first name
+ * @param {"session-id"|"resume"} [i.resumeMode] main-session launch mode
+ * @param {{name:string, config:string, scope?:string}} [i.registration] mcp-register
+ * @param {string} [i.bin]          explicit binary (a caller's injected dep); else resolved
+ * @param {number} [i.maxBudgetUsd] engine cohort run lanes only: `--max-budget-usd` (ignored for claude)
+ * @param {string} [i.cohortToken]  engine cohort: the seat token the spawn starts with
+ * @param {object} [deps]           {resolveBin, daemonArgs, augmentedPath} — test seams
+ * @returns {{ok:true, engine:string, lane:string, bin:string, argv:string[], env:object, stdin:string|null, retargeting:boolean} |
+ *           {ok:false, error:{code:string, message:string, lane:string, engine:string}}}
+ */
+export function buildSpawn(i = {}, deps = {}) {
+  const spec = LANES[i.lane];
+  if (!spec) throw new TypeError(`buildSpawn: unknown lane ${JSON.stringify(i.lane)} (known: ${LANE_NAMES.join(", ")})`);
+  const engine = i.engine == null ? DEFAULT_ENGINE : i.engine;
+  const fail = (code, message) => ({ ok: false, error: { code, message, lane: i.lane, engine: String(engine) } });
+
+  if (engine !== "claude" && engine !== "cohort") {
+    return fail("unknown_engine", `unknown runtime engine ${JSON.stringify(engine)} (known: ${ENGINES.join(", ")})`);
+  }
+  if (isRetarget(i.retarget) && !spec.retarget) {
+    return fail("retarget_unsupported", `lane "${i.lane}" cannot be retargeted to another backend`);
+  }
+
+  const d = {
+    resolveBin: deps.resolveBin || resolveClaudeBin,
+    daemonArgs: deps.daemonArgs || daemonClaudeArgs,
+    augmentedPath: deps.augmentedPath || augmentedPath,
+  };
+  // A collective lane's marker rides extraEnv so both engines set it after
+  // every merge; a caller cannot drop it by passing its own extraEnv.
+  const extraEnv = spec.collectiveChild
+    ? { ...(i.extraEnv && typeof i.extraEnv === "object" ? i.extraEnv : {}), [COLLECTIVE_CHILD_ENV]: "1" }
+    : i.extraEnv;
+  const input = { ...i, env: i.env === undefined ? process.env : i.env, extraEnv };
+
+  if (engine === "cohort") return buildCohortEngineSpawn(spec, input, d, deps, fail);
+
+  const envResult = laneEnv(spec, input, d);
+  if (!envResult.ok) return fail(envResult.error.code, envResult.error.message);
+
+  const perm = Array.isArray(i.permissions) ? i.permissions : (spec.defaultPermissions || []);
+  // Path B: a cohort-llm retarget authenticates through the seat-token helper,
+  // which Claude Code only reads from settings (child-env COHORT_HELPER_KEY).
+  const settings = envResult.retargeting && isCohortHelperRetarget(i.retarget)
+    ? ["--settings", JSON.stringify({ apiKeyHelper: i.retarget[COHORT_HELPER_KEY] })]
+    : [];
+  const x = { perm, mcp: mcpArgs(i.mcp, d), knobs: knobArgs(i.knobs), settings };
+  const argv = spec.argv(input, x);
+
+  const env = envResult.env;
+  if (input.extraEnv && typeof input.extraEnv === "object") {
+    for (const [k, v] of Object.entries(input.extraEnv)) if (v !== undefined && v !== null) env[k] = String(v);
+  }
+
+  return {
+    ok: true,
+    engine,
+    lane: i.lane,
+    bin: i.bin || d.resolveBin(),
+    argv,
+    env,
+    stdin: spec.stdin ? (i.prompt == null ? "" : String(i.prompt)) : null,
+    retargeting: envResult.retargeting,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Engine: cohort
+// ---------------------------------------------------------------------------
+
+/** The engine's headless entry point. */
+export const ENGINE_CLI_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "engine", "cli.mjs");
+
+/**
+ * The flags `cohort run` accepts TODAY (lib/engine/cli.mjs `parseRunArgs`).
+ * adapter-cohort.test.mjs pins this list against the real parser in both
+ * directions, so when the engine grows a flag (W2-D: MCP, permissions) the
+ * test fails until the flag is listed here — and only then does the adapter
+ * pass it through.
+ */
+export const ENGINE_RUN_FLAGS = Object.freeze([
+  "-p", "--print", "--output-format", "--model", "--session-id", "--resume", "--max-turns", "--append-system-prompt",
+  // W2-D: MCP, permissions, settings.
+  "--mcp-config", "--strict-mcp-config", "--permission-mode", "--dangerously-skip-permissions",
+  "--allowedTools", "--disallowedTools", "--settings",
+  // W3-G (CF-45): the router knobs and the daemon's bare mode.
+  "--add-dir", "--plugin-dir", "--effort", "--agents", "--bare",
+  // W4-E1 (row 24): the per-session spend cap.
+  "--max-budget-usd",
+]);
+
+/**
+ * The claude `--print` subset maestro's lanes emit, and the engine flag each
+ * becomes. Anything not in this table is unsupported by construction.
+ */
+const CLAUDE_TO_ENGINE = Object.freeze({
+  "-p": { flag: "-p", value: false },
+  "--print": { flag: "-p", value: false },
+  "--output-format": { flag: "--output-format", value: true, values: ["json", "text"] },
+  "--model": { flag: "--model", value: true, model: true },
+  "--session-id": { flag: "--session-id", value: true },
+  "--resume": { flag: "--resume", value: true },
+  "--append-system-prompt": { flag: "--append-system-prompt", value: true },
+  "--max-turns": { flag: "--max-turns", value: true },
+  "--mcp-config": { flag: "--mcp-config", value: true },
+  "--strict-mcp-config": { flag: "--strict-mcp-config", value: false },
+  "--dangerously-skip-permissions": { flag: "--dangerously-skip-permissions", value: false },
+  "--permission-mode": { flag: "--permission-mode", value: true },
+  "--allowedTools": { flag: "--allowedTools", value: true },
+  "--disallowedTools": { flag: "--disallowedTools", value: true },
+  "--settings": { flag: "--settings", value: true },
+  "--add-dir": { flag: "--add-dir", value: true },
+  "--plugin-dir": { flag: "--plugin-dir", value: true },
+  "--effort": { flag: "--effort", value: true },
+  "--agents": { flag: "--agents", value: true },
+  "--bare": { flag: "--bare", value: false },
+  "--max-budget-usd": { flag: "--max-budget-usd", value: true },
+});
+
+/**
+ * The Anthropic-slot → Cohort-tier map the engine lane uses when the caller
+ * does not pass one. Pinned equal to lib/model-router/catalog/cohort.yaml
+ * `tier_map` by adapter-cohort.test.mjs.
+ */
+export const DEFAULT_COHORT_TIER_MAP = Object.freeze({ fable: "cohort-reason", opus: "cohort-agentic", sonnet: "cohort-agentic", haiku: "cohort-fast" });
+
+/** Lanes whose shape the engine cannot serve (claude CLI subcommands). */
+const ENGINE_UNSUPPORTED_LANES = new Set(["auth-status", "mcp-register"]);
+
+/**
+ * W4-A1: the interactive lanes, served by `cohort session` (lib/engine/cli.mjs
+ * `session`, session-runtime/runner.mjs). Not enabled for any seat: a seat's
+ * engine stays `claude` until the §8.4 gate.
+ */
+export const ENGINE_INTERACTIVE_LANES = Object.freeze(["main-session", "peer"]);
+
+/**
+ * The flags `cohort session` accepts that the interactive lanes may emit
+ * (lib/engine/session-runtime/args.mjs `SESSION_FLAGS`). adapter-session.test.mjs
+ * pins this list against the real session parser.
+ */
+export const ENGINE_SESSION_FLAGS = Object.freeze([
+  "--name", "--session-id", "--resume", "--model", "--max-turns", "--append-system-prompt",
+  "--mcp-config", "--strict-mcp-config", "--permission-mode", "--dangerously-skip-permissions",
+  "--allowedTools", "--disallowedTools", "--settings", "--add-dir", "--plugin-dir", "--effort", "--agents", "--bare",
+]);
+
+/**
+ * Map an interactive lane's claude argv (`--name …, --session-id|--resume …,
+ * permission/extra flags, prompt`) onto `cohort session` argv. The last element
+ * is always the prompt. PURE.
+ * @param {string[]} argv
+ * @param {{tierMap?:Record<string,string>, engineFlags?:readonly string[]}} [o]
+ * @returns {{ok:true, argv:string[]}|{ok:false, error:{code:string, message:string, flag?:string}}}
+ */
+export function translateInteractiveArgv(argv, o = {}) {
+  const engineFlags = o.engineFlags || ENGINE_SESSION_FLAGS;
+  const tierMap = o.tierMap || DEFAULT_COHORT_TIER_MAP;
+  const args = [...(Array.isArray(argv) ? argv : [])];
+  const bad = (code, message, flag) => ({ ok: false, error: { code, message, ...(flag ? { flag } : {}) } });
+  if (args.length === 0) return bad("engine_argument_unsupported", "an interactive session needs a prompt");
+  const prompt = String(args.pop());
+  const out = ["session"];
+  for (let k = 0; k < args.length; k++) {
+    const a = String(args[k]);
+    const m = a === "--name" ? { flag: "--name", value: true } : CLAUDE_TO_ENGINE[a];
+    if (!m || m.flag === "-p" || m.flag === "--output-format") {
+      if (a.startsWith("-")) return bad("engine_flag_unsupported", `cohort session does not support ${a}`, a);
+      return bad("engine_argument_unsupported", `unexpected positional argument for cohort session: ${JSON.stringify(a.slice(0, 40))}`);
+    }
+    if (!engineFlags.includes(m.flag)) return bad("engine_flag_unsupported", `cohort session does not support ${a} yet`, a);
+    if (!m.value) { out.push(m.flag); continue; }
+    let v = args[++k];
+    if (v === undefined) return bad("engine_argument_unsupported", `${a} needs a value`, a);
+    v = String(v);
+    if (m.model) {
+      const tier = cohortTierFor(v, tierMap);
+      if (!tier) return bad("engine_model_unmapped", `--model ${v} has no Cohort tier (expected cohort-* or an opus/sonnet/haiku/fable slot)`, a);
+      v = tier;
+    }
+    out.push(m.flag, v);
+  }
+  out.push("--", prompt);
+  return { ok: true, argv: out };
+}
+
+/**
+ * Map a lane's claude argv onto `cohort run` argv. PURE.
+ * @param {string[]} argv       the claude argv the lane table built
+ * @param {object} o
+ * @param {string|null} [o.prompt] the prompt, when it rides argv (last element)
+ * @param {boolean} [o.stdin]    the prompt rides stdin
+ * @param {Record<string,string>} [o.tierMap]
+ * @param {readonly string[]} [o.engineFlags]
+ * @returns {{ok:true, argv:string[]}|{ok:false, error:{code:string, message:string, flag?:string}}}
+ */
+export function translateClaudeArgv(argv, o = {}) {
+  const engineFlags = o.engineFlags || ENGINE_RUN_FLAGS;
+  const tierMap = o.tierMap || DEFAULT_COHORT_TIER_MAP;
+  const args = [...(Array.isArray(argv) ? argv : [])];
+  let promptArg = null;
+  if (!o.stdin && o.prompt != null && args.length && args[args.length - 1] === o.prompt) promptArg = args.pop();
+  const out = ["run", "-p"];
+  const bad = (code, message, flag) => ({ ok: false, error: { code, message, ...(flag ? { flag } : {}) } });
+  for (let k = 0; k < args.length; k++) {
+    const a = String(args[k]);
+    const m = CLAUDE_TO_ENGINE[a];
+    if (!m) {
+      if (a.startsWith("-")) return bad("engine_flag_unsupported", `the cohort engine does not support ${a}`, a);
+      return bad("engine_argument_unsupported", `unexpected positional argument for the cohort engine: ${JSON.stringify(a.slice(0, 40))}`);
+    }
+    if (!engineFlags.includes(m.flag)) {
+      return bad("engine_flag_unsupported", `the cohort engine does not support ${a} yet`, a);
+    }
+    if (m.flag === "-p") continue; // always emitted once, up front
+    if (!m.value) { out.push(m.flag); continue; }
+    let v = args[++k];
+    if (v === undefined) return bad("engine_argument_unsupported", `${a} needs a value`, a);
+    v = String(v);
+    if (m.values && !m.values.includes(v)) return bad("engine_flag_unsupported", `the cohort engine does not support ${a} ${v}`, a);
+    if (m.model) {
+      const tier = cohortTierFor(v, tierMap);
+      if (!tier) return bad("engine_model_unmapped", `--model ${v} has no Cohort tier (expected cohort-* or an opus/sonnet/haiku/fable slot)`, a);
+      v = tier;
+    }
+    out.push(m.flag, v);
+  }
+  if (promptArg != null) out.push("--", String(promptArg));
+  return { ok: true, argv: out };
+}
+
+/**
+ * The engine child's env: the lane's own posture with every Anthropic/Claude
+ * credential scrubbed, plus the gateway URL, the seat token minted at spawn,
+ * and — when the seat's root is known — the token helper that re-mints it
+ * (the engine re-runs it on a TTL and after a 401, so a long-lived
+ * `cohort session` never outlives its credential). PURE.
+ */
+export function cohortEngineEnv(laneBaseEnv, { baseUrl, token, tokenHelper = null }) {
+  const out = {};
+  for (const [k, v] of Object.entries(laneBaseEnv || {})) {
+    if (/^ANTHROPIC_/i.test(k)) continue;
+    if (/^CLAUDE_CODE_/i.test(k) && /(OAUTH|TOKEN|KEY|SECRET|HELPER)/i.test(k)) continue;
+    if (/^COHORT_LLM_(TOKEN|API_KEY_HELPER|TOKEN_HELPER)$/i.test(k)) continue;
+    out[k] = v;
+  }
+  out.COHORT_LLM_BASE_URL = baseUrl;
+  out.COHORT_LLM_TOKEN = token;
+  if (nonEmpty(tokenHelper)) out.COHORT_LLM_TOKEN_HELPER = tokenHelper;
+  return out;
+}
+
+/** The seat root an engine spawn's token helper reads its key from: the lane's, its MCP seat's, or its env's. PURE. */
+function engineSeatRoot(input, laneEnvValues, deps) {
+  const mcpRoot = input.mcp && typeof input.mcp === "object" ? input.mcp.agentRoot : null;
+  for (const v of [input.agentRoot, mcpRoot, laneEnvValues && laneEnvValues.AGENT_ROOT, input.env && input.env.AGENT_ROOT, deps.agentRoot]) {
+    if (nonEmpty(v)) return String(v);
+  }
+  return null;
+}
+
+function buildCohortEngineSpawn(spec, input, d, deps, fail) {
+  if (ENGINE_UNSUPPORTED_LANES.has(input.lane)) {
+    return fail("engine_lane_unsupported", `lane "${input.lane}" is interactive or a claude subcommand; the cohort engine runs headless lanes only`);
+  }
+  if (isRetarget(input.retarget)) {
+    return fail("retarget_unsupported", "the cohort engine talks to cohort-llm directly; a router retarget does not apply");
+  }
+  const perm = Array.isArray(input.permissions) ? input.permissions : (spec.defaultPermissions || []);
+  const claudeArgv = spec.argv(input, { perm, mcp: mcpArgs(input.mcp, d), knobs: knobArgs(input.knobs), settings: [] });
+  const tierMap = input.cohortTierMap || deps.cohortTierMap;
+  const mapped = ENGINE_INTERACTIVE_LANES.includes(input.lane)
+    ? translateInteractiveArgv(claudeArgv, { tierMap })
+    : translateClaudeArgv(claudeArgv, { prompt: input.prompt, stdin: spec.stdin, tierMap });
+  if (!mapped.ok) return fail(mapped.error.code, mapped.error.message);
+  // W4-E1 (row 24): a per-session spend cap, for engine cohort run lanes only (a claude
+  // spawn ignores `maxBudgetUsd`, so a claude seat's argv is unchanged). Before the prompt's `--`.
+  if (input.maxBudgetUsd != null) {
+    if (ENGINE_INTERACTIVE_LANES.includes(input.lane)) return fail("engine_argument_unsupported", `lane "${input.lane}" is interactive; --max-budget-usd applies to cohort run lanes`);
+    const usd = Number(input.maxBudgetUsd);
+    if (!Number.isFinite(usd) || usd <= 0) return fail("engine_argument_unsupported", `maxBudgetUsd must be a positive number, got ${JSON.stringify(input.maxBudgetUsd)}`);
+    const at = mapped.argv.indexOf("--");
+    mapped.argv.splice(at === -1 ? mapped.argv.length : at, 0, "--max-budget-usd", String(usd));
+  }
+
+  const tokenValue = typeof input.cohortToken === "string" ? input.cohortToken
+    : (typeof deps.cohortToken === "function" ? deps.cohortToken() : null);
+  const token = tokenValue && typeof tokenValue === "object" ? tokenValue.token : tokenValue;
+  if (!nonEmpty(token)) {
+    return fail("cohort_token_unavailable", "no cohort-llm seat token for the engine — admit the spawn first (admitSpawn mints/caches one)");
+  }
+  const baseUrl = String(input.cohortBaseUrl || deps.cohortBaseUrl || (input.env && input.env.COHORT_LLM_BASE_URL) || DEFAULT_LLM_BASE_URL).replace(/\/+$/, "");
+
+  const envResult = laneEnv(spec, { ...input, retarget: {} }, d);
+  if (!envResult.ok) return fail(envResult.error.code, envResult.error.message);
+  const seatRoot = engineSeatRoot(input, envResult.env, deps);
+  const tokenHelper = seatRoot
+    ? apiKeyHelperCommand({ agentRoot: seatRoot, nodeBin: deps.nodeBin || process.execPath, ...(deps.apiKeyHelperPath ? { helperPath: deps.apiKeyHelperPath } : {}) })
+    : null;
+  const env = cohortEngineEnv(envResult.env, { baseUrl, token, tokenHelper });
+  if (input.extraEnv && typeof input.extraEnv === "object") {
+    for (const [k, v] of Object.entries(input.extraEnv)) if (v !== undefined && v !== null) env[k] = String(v);
+  }
+  return {
+    ok: true,
+    engine: "cohort",
+    lane: input.lane,
+    bin: deps.nodeBin || process.execPath,
+    argv: [deps.engineCliPath || ENGINE_CLI_PATH, ...mapped.argv],
+    env,
+    stdin: spec.stdin ? (input.prompt == null ? "" : String(input.prompt)) : null,
+    retargeting: false,
+  };
+}
+
+/**
+ * Can this seat generate a reply at all — the NECESSARY presence check the
+ * daemon's ack-before-work fail-safe reads (agent-daemon claudeAvailable).
+ * A claude seat needs a safe claude binary; an engine-cohort seat never
+ * spawns claude, so it needs the engine entry point instead (conformance
+ * row 1). Neither proves the credential or the network. PURE.
+ * @param {{engine:string, claudeBinOk:()=>boolean, engineCliPresent:()=>boolean}} o
+ * @returns {boolean}
+ */
+export function seatGenerationAvailable({ engine, claudeBinOk, engineCliPresent }) {
+  try {
+    return engine === "cohort" ? engineCliPresent() === true : claudeBinOk() === true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// cohort-llm admission (the pre-spawn gate)
+// ---------------------------------------------------------------------------
+
+/** A credits hold re-checks after this long. */
+export const COHORT_CREDITS_RECHECK_MS = 10 * 60 * 1000;
+/** A refusal that waiting cannot fix (a bad key, an unpriced tier) re-checks after this long. */
+export const COHORT_FAIL_HOLD_MS = 15 * 60 * 1000;
+
+/**
+ * Is this spawn served by cohort-llm? engine cohort, a target routed to the
+ * cohort provider, or a retarget authenticated by the cohort key helper. PURE.
+ * @param {{engine?:string, target?:object|null}} o
+ */
+export function isCohortRouted({ engine, target } = {}) {
+  if (engine === "cohort") return true;
+  const t = target && typeof target === "object" ? target : null;
+  if (!t) return false;
+  if (t.backend === COHORT_BACKEND) return true;
+  return isCohortHelperRetarget(t.envForSpawn || t.retarget || null);
+}
+
+/**
+ * Turn an admission refusal into the deferral a call site acts on. PURE.
+ * `until` is always an epoch ms: the refusal's resetsAt, or a re-check time.
+ * @returns {{kind:string, until:number, code:string|null, message:string, refusal:object|null}}
+ */
+export function deferralFromAdmission(adm, now) {
+  const d = (adm && adm.disposition) || { kind: "fail", code: null };
+  const code = d.code || (adm && adm.error && adm.error.code) || null;
+  let until;
+  if (d.kind === "defer_until") until = d.until;
+  else if (d.kind === "retry") until = now + (Number(d.afterMs) || 0);
+  else if (d.kind === "hold_for_credits") until = now + COHORT_CREDITS_RECHECK_MS;
+  else until = now + COHORT_FAIL_HOLD_MS;
+  const what = {
+    defer_until: `cohort-llm refused (${code}); deferring until ${new Date(until).toISOString()}`,
+    hold_for_credits: "cohort-llm credits are exhausted; holding until a top-up",
+    retry: `cohort-llm is busy (${code}); retrying at ${new Date(until).toISOString()}`,
+    fail: `cohort-llm cannot admit this seat (${code})`,
+  }[d.kind] || `cohort-llm refused (${code})`;
+  return { kind: d.kind, until, code, message: what, refusal: (adm && adm.refusal) || null };
+}
+
+function holdDeferral(rateGuard, rateGuardDeps, now) {
+  if (!rateGuard || typeof rateGuard.checkRateLimit !== "function") return null;
+  try {
+    const hold = rateGuard.checkRateLimit(COHORT_BACKEND, rateGuardDeps);
+    if (hold && hold.allowed === false) {
+      return { kind: "defer_until", until: hold.retryAt, code: "cohort_hold", message: `a cohort-llm refusal holds this seat until ${new Date(hold.retryAt).toISOString()}`, refusal: null };
+    }
+  } catch { /* a hold we cannot read never blocks — the quota read still gates */ }
+  return null;
+}
+
+/**
+ * Record a refusal as a cohort hold, and when one was recorded drop the quota
+ * cache: the reading that refused must not be the one a gate trusts once the
+ * hold lifts (the cache would otherwise answer for up to its TTL).
+ */
+function recordRefusalHold(rateGuard, rateGuardDeps, adm, quota) {
+  if (!adm || !adm.refusal || !rateGuard || typeof rateGuard.recordCohortRefusal !== "function") return;
+  let rec = null;
+  try { rec = rateGuard.recordCohortRefusal(adm.refusal, rateGuardDeps); } catch { /* best-effort */ }
+  if (rec && rec.recorded && quota && typeof quota.invalidate === "function") {
+    try { quota.invalidate(); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * May this spawn start? Not cohort-routed → always yes. Cohort-routed → an
+ * existing cohort hold (rate-guard, backend "cohort") defers without a network
+ * call; otherwise `quota.canAdmit()` decides, and a refusal is recorded as a
+ * cohort hold so the next spawn does not ask again. Human replies are NOT
+ * exempt: a refused seat would 429/402 them just the same.
+ *
+ * @param {{engine?:string, target?:object|null}} o
+ * @param {{quota?:{canAdmit:Function}, token?:{peek:Function}, rateGuard?:object, rateGuardDeps?:object, now?:()=>number}} [deps]
+ * @returns {Promise<{ok:true, cohort:boolean, funding?:string|null, token?:string|null} |
+ *                   {ok:false, cohort:true, deferral:object}>}
+ */
+export async function admitSpawn(o = {}, deps = {}) {
+  if (!isCohortRouted(o)) return { ok: true, cohort: false };
+  const now = typeof deps.now === "function" ? deps.now() : Date.now();
+  const held = holdDeferral(deps.rateGuard, deps.rateGuardDeps, now);
+  if (held) return { ok: false, cohort: true, deferral: held };
+  if (!deps.quota || typeof deps.quota.canAdmit !== "function") {
+    return { ok: false, cohort: true, deferral: deferralFromAdmission({ disposition: { kind: "retry", afterMs: 30_000, code: "cohort_quota_unconfigured" } }, now) };
+  }
+  let adm;
+  try { adm = await deps.quota.canAdmit(); } catch (err) {
+    adm = { ok: false, error: { code: "cohort_unavailable", message: String(err && err.message || err) }, disposition: { kind: "retry", afterMs: 30_000, code: "cohort_unavailable" } };
+  }
+  if (adm && adm.ok) {
+    const t = deps.token && typeof deps.token.peek === "function" ? deps.token.peek({ allowStale: true }) : null;
+    return { ok: true, cohort: true, funding: adm.funding || null, token: (t && t.token) || null };
+  }
+  recordRefusalHold(deps.rateGuard, deps.rateGuardDeps, adm, deps.quota);
+  return { ok: false, cohort: true, deferral: deferralFromAdmission(adm, now) };
+}
+
+/**
+ * The synchronous twin of {@link admitSpawn} for call sites that must decide
+ * inside a synchronous spawn path (the dispatcher). It reads only the quota
+ * cache; with nothing cached it answers `{cold:true}` and the caller primes the
+ * cache (`quota.canAdmit()`) and retries — it never spawns on a guess.
+ */
+export function admitSpawnCached(o = {}, deps = {}) {
+  if (!isCohortRouted(o)) return { ok: true, cohort: false };
+  const now = typeof deps.now === "function" ? deps.now() : Date.now();
+  const held = holdDeferral(deps.rateGuard, deps.rateGuardDeps, now);
+  if (held) return { ok: false, cohort: true, deferral: held };
+  const adm = deps.quota && typeof deps.quota.canAdmitCached === "function" ? deps.quota.canAdmitCached() : { cold: true };
+  if (adm.cold) {
+    return { ok: false, cohort: true, cold: true, deferral: { kind: "retry", until: now, code: "cohort_quota_cold", message: "no fresh cohort-llm quota reading yet", refusal: null } };
+  }
+  if (adm.ok) {
+    const t = deps.token && typeof deps.token.peek === "function" ? deps.token.peek({ allowStale: true }) : null;
+    return { ok: true, cohort: true, funding: adm.funding || null, token: (t && t.token) || null };
+  }
+  recordRefusalHold(deps.rateGuard, deps.rateGuardDeps, adm, deps.quota);
+  return { ok: false, cohort: true, deferral: deferralFromAdmission(adm, now) };
+}
+
+export default {
+  buildSpawn, resolveEngine, readSeatEngine, seatGenerationAvailable, ENGINES, DEFAULT_ENGINE, LANE_NAMES, SHELL_LEGACY_LANES,
+  translateClaudeArgv, cohortEngineEnv, isCohortRouted, admitSpawn, admitSpawnCached, deferralFromAdmission,
+};