@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/session/feed-core.mjs

@@ -22,9 +22,19 @@
  *
  * Lines emitted (one JSON object each — the session's whole vocabulary):
  *
- *   {"type":"inbound","id","service","surface","topic","reason","from","channelId","channelName","threadId","preview","path","seq"}
+ *   {"type":"inbound","id","service","surface","topic","reason","collective","from","channelId","channelName","threadId","preview","path","seq"}
  *   {"type":"handoff","id","cadence","promptPath","enqueuedAt","path","seq"}
- *   {"type":"directive","action":"restart"|"upgrade-available"|"daemon-stale","detail","seq"}
+ *   {"type":"directive","action":"restart"|"upgrade-available"|"daemon-unhealthy"|"daemon-stale","detail","seq"}
+ *
+ * `upgrade-available` and `daemon-unhealthy` come from the SAME file,
+ * state/session/upgrade-notice.json, and are deliberately two actions: the
+ * first ({from,to,at}) is autoupdate reporting a healthy hop onto a new
+ * version — the session restarts itself onto it when idle; the second
+ * ({from,to,at,healthy:false,reason}) is the hourly gate reporting the daemon
+ * unhealthy on the version already installed — there is nothing to restart
+ * onto, and a restart would only lose the session's context. Telling them
+ * apart here, not in the skill prose, is what keeps a session from restarting
+ * on a health report.
  *
  * The seen-set is keyed by file, and a key whose file has GONE is dropped —
  * so an item the daemon's assurance sweep re-opens (`.dispatched` → `.yaml`)
@@ -37,6 +47,8 @@
 "use strict";
 
 import { parseInboxItemYaml } from "../../scripts/poller/inbox-scan-poller.mjs";
+import { isRollCallItem } from "../org/inbound/broadcast.mjs";
+import { itemCollectiveIntent } from "../org/inbound/collective.mjs";
 import { SURFACES } from "../org/inbound/surfaces.mjs";
 import { maskTextString } from "../security/redact.mjs";
 import { isDaemonStale } from "./liveness.mjs";
@@ -111,6 +123,28 @@ export function inboundEvent(a) {
     surface,
     topic: TOPIC_BY_KIND.get(surface) || "message",
     reason: item.direct_reason || "",
+    // ── WHAT A MESSAGE TO THE WHOLE ROOM ASKED FOR ────────────────────────
+    //
+    // "" for anything that is not a collective address; otherwise one of
+    // `roll-call` / `work` / `ambient` (lib/org/inbound/collective.mjs).
+    //
+    // WHY IT IS ON THE FEED LINE AND NOT ONLY IN THE DAEMON. The daemon's
+    // `answerItem` — where a work-shaped broadcast opens its board row — is
+    // only reached through `pollService`, which returns 0 the moment
+    // `makeFrontDoorGate` says a live main session owns this service's inbox
+    // (scripts/daemon/agent-daemon.mjs). On a seat whose front door is up,
+    // which is the NORMAL state, the daemon never dispatches the item at all:
+    // it becomes an `inbound` line here and the session answers it. A verdict
+    // that lives only on the daemon's side of that fork is a verdict that
+    // never fires in production — the same dark-path shape as the 13-day board
+    // blackout. So the classifier's answer travels on the line that the live
+    // plane actually reads, and `inbound-triage` tells the session what to do
+    // with it: `work` is outcome 2 (claim, `board track --stage accepted`,
+    // then do it), `roll-call` and `ambient` are outcome 1.
+    //
+    // Best-effort by construction: a body this cannot parse yields "", which
+    // reads as "an ordinary message" and costs the session nothing.
+    collective: itemCollectiveIntent(item, isRollCallItem) || "",
     from: item.sender || "",
     channelId: item.channel_id || "",
     channelName: item.channel || "",
@@ -198,6 +232,8 @@ export function computeFeedEvents(snapshot, seenIn, opts = {}) {
   }
 
   // upgrade-notice: once per notice (keyed by mtime), detail = parsed body.
+  // A body with healthy:false is a health REPORT, not an upgrade (see the
+  // header): it gets its own action so no consumer restarts on it.
   const un = sig.upgradeNotice;
   if (un && Number.isFinite(un.mtimeMs)) {
     if (seen.signals.upgrade !== un.mtimeMs) {
@@ -205,7 +241,8 @@ export function computeFeedEvents(snapshot, seenIn, opts = {}) {
       let notice = null;
       try { notice = JSON.parse(un.body); } catch { notice = null; /* a hand-written marker still announces the upgrade */ }
       const detail = notice && typeof notice === "object" ? { notice } : { notice: null, raw: String(un.body || "").slice(0, PREVIEW_MAX) };
-      events.push({ type: "directive", action: "upgrade-available", detail, seq: next() });
+      const action = notice && typeof notice === "object" && notice.healthy === false ? "daemon-unhealthy" : "upgrade-available";
+      events.push({ type: "directive", action, detail, seq: next() });
     }
   } else {
     delete seen.signals.upgrade;

package/lib/session/launch-args.mjs

@@ -41,6 +41,53 @@ export const BOOTSTRAP_PROMPT =
 export const SESSION_EXIT_SCRIPT =
   'exit_file="$1"; shift; "$@"; rc=$?; printf \'%s\\n\' "$rc" > "$exit_file" 2>/dev/null; exit "$rc"';
 
+/**
+ * W4-E1: how an engine-cohort session gets its environment inside a
+ * multiplexer. tmux does NOT give a new session the env of the client that
+ * asked for it: a session created in an already-running server starts from the
+ * server's global environment — no seat token, and whatever Claude credentials
+ * the server holds. `tmux -e KEY=value` would put the token on argv (visible in
+ * `ps`). So the engine's env is written to a 0600 file under the seat's state
+ * dir, and the session's command is
+ *
+ *   /usr/bin/env -i /bin/sh -c ENGINE_ENV_SCRIPT maestro-env <env-file> <bin> <args…>
+ *
+ * `env -i` drops everything the mux server (or screen) handed down; the script
+ * sources the file (exactly the engine's env), deletes it, and execs the
+ * engine. Positional only, as SESSION_EXIT_SCRIPT: nothing is interpolated.
+ */
+export const ENGINE_ENV_SCRIPT =
+  'maestro_env_file="$1"; shift; ' +
+  'if [ ! -r "$maestro_env_file" ]; then echo "maestro: engine env file $maestro_env_file is missing" >&2; exit 78; fi; ' +
+  '. "$maestro_env_file"; rm -f "$maestro_env_file"; unset maestro_env_file; exec "$@"';
+
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Pure: the env file's text — one `export KEY='value'` per variable, single
+ * quotes escaped, names a shell cannot export skipped.
+ * @param {Record<string, string|undefined|null>} env
+ * @returns {string}
+ */
+export function renderEnvFile(env) {
+  const lines = [];
+  for (const [k, v] of Object.entries(env || {})) {
+    if (v === undefined || v === null || !ENV_KEY_RE.test(k) || k === "maestro_env_file") continue;
+    lines.push(`export ${k}='${String(v).replace(/'/g, "'\\''")}'`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Pure: the argv that runs `bin args…` with exactly the env in `envFile`.
+ * @param {{envFile:string, bin:string, args:string[]}} a
+ * @returns {string[]}
+ */
+export function envFileCommand(a) {
+  if (!a || typeof a.envFile !== "string" || !a.envFile) throw new Error("envFileCommand: envFile is required");
+  return ["/usr/bin/env", "-i", "/bin/sh", "-c", ENGINE_ENV_SCRIPT, "maestro-env", a.envFile, a.bin, ...(a.args || [])];
+}
+
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /** Where the multiplexers live on a Mac (nvm-free, launchd-safe, in order). */
@@ -105,10 +152,15 @@ export function chooseMux(pref, found) {
  *   stop       ends the session on request (SIGTERM to the supervisor):
  *              `screen -S name -X quit` / `tmux kill-session -t =name`.
  *
- * @param {{mux:{kind:string, bin:string}, muxName:string, cwd:string, claudeBin:string, claudeArgs:string[], exitFile:string}} a
+ * `envFile` (W4-E1, engine cohort): the session's command runs through
+ * {@link envFileCommand}, so its env is the file's and never the mux server's.
+ * Absent (a claude seat): the argv is exactly as before.
+ *
+ * @param {{mux:{kind:string, bin:string}, muxName:string, cwd:string, claudeBin:string, claudeArgs:string[], exitFile:string, envFile?:string|null}} a
  */
 export function buildMuxCommands(a) {
-  const wrapped = ["/bin/sh", "-c", SESSION_EXIT_SCRIPT, "maestro-session", a.exitFile, a.claudeBin, ...a.claudeArgs];
+  const command = a.envFile ? envFileCommand({ envFile: a.envFile, bin: a.claudeBin, args: a.claudeArgs }) : [a.claudeBin, ...a.claudeArgs];
+  const wrapped = ["/bin/sh", "-c", SESSION_EXIT_SCRIPT, "maestro-session", a.exitFile, ...command];
   if (a.mux.kind === "screen") {
     return {
       blocking: true,
@@ -156,6 +208,6 @@ export function parseExitFile(text) {
 }
 
 export default {
-  BOOTSTRAP_PROMPT, SESSION_EXIT_SCRIPT, MUX_CANDIDATES,
-  buildClaudeArgs, detectMux, chooseMux, buildMuxCommands, parseScreenList, parseExitFile,
+  BOOTSTRAP_PROMPT, SESSION_EXIT_SCRIPT, ENGINE_ENV_SCRIPT, MUX_CANDIDATES,
+  renderEnvFile, envFileCommand, buildClaudeArgs, detectMux, chooseMux, buildMuxCommands, parseScreenList, parseExitFile,
 };

package/lib/session/status-summary.mjs

@@ -24,6 +24,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { buildIdentityClaudeMd, IDENTITY_BEGIN, IDENTITY_END } from "../collective/global-config.mjs";
+import { sessionPaths } from "./config.mjs";
 
 /** A heartbeat older than this is a dead or wedged session (feed beats every 15 s). */
 export const DEFAULT_STALE_MS = 90_000;
@@ -128,6 +129,29 @@ function readJson(p) {
   }
 }
 
+/**
+ * The open handoff files under `state/session/handoffs` — file NAMES only;
+ * a handoff is counted, never opened. THE one reader of that directory: the
+ * session status here and lib/session/current-work both count handoffs, and
+ * a second copy of this read would have to move in step with the cadence
+ * consumer's file naming (`<tickId>.json`, done ones under `handoffs/done/`,
+ * which is a directory and so never matches). The PARSING reader — the one
+ * that opens each file to act on it — is lib/session/handoffs.listHandoffs;
+ * this one exists so a status line never has to. Fail-open: an absent or
+ * vanished directory is an empty queue.
+ * @param {string} agentRoot
+ * @returns {string[]}
+ */
+export function listOpenHandoffs(agentRoot) {
+  try {
+    const dir = sessionPaths(String(agentRoot || "")).handoffsDir;
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    return []; // a vanished directory mid-read is an empty queue
+  }
+}
+
 /**
  * Read the four state files under an agent root and summarise. Fail-open:
  * an unreadable file is the same as an absent one.
@@ -137,17 +161,10 @@ function readJson(p) {
 export function readSessionStatus(agentRoot, o = {}) {
   const root = String(agentRoot || "");
   const sess = join(root, "state", "session");
-  let handoffs = [];
-  try {
-    const dir = join(sess, "handoffs");
-    if (existsSync(dir)) handoffs = readdirSync(dir).filter((f) => f.endsWith(".json"));
-  } catch {
-    handoffs = []; // a vanished directory mid-read is an empty queue
-  }
   return summarizeSessionStatus({
     heartbeat: readJson(join(sess, "heartbeat.json")),
     peers: readJson(join(sess, "peers.json")),
-    handoffs,
+    handoffs: listOpenHandoffs(root),
     boardMine: readJson(join(root, "state", "org", "board-mine.json")),
     now: o.now,
     staleMs: o.staleMs,
@@ -169,4 +186,4 @@ export function buildPrimerContext(o = {}) {
   return [IDENTITY_BEGIN, block, IDENTITY_END, "", `Session status: ${statusLine(status)}.`].join("\n");
 }
 
-export default { summarizeSessionStatus, readSessionStatus, statusLine, buildPrimerContext, DEFAULT_STALE_MS };
+export default { summarizeSessionStatus, readSessionStatus, listOpenHandoffs, statusLine, buildPrimerContext, DEFAULT_STALE_MS };

package/lib/session/upgrade-notice.mjs

@@ -0,0 +1,42 @@
+/**
+ * lib/session/upgrade-notice.mjs — is a pending upgrade notice HONOURED by
+ * the launch about to happen? Pure.
+ *
+ * autoupdate.sh writes state/session/upgrade-notice.json {from,to,at} after
+ * a healthy hop; the session's feed turns it into an `upgrade-available`
+ * directive and the session restarts itself onto the new code. Nothing then
+ * removed the file: `maestro session status` kept printing "upgrade available
+ * 2.16.0 → 2.17.0" nine days after the seat was on 2.17.0, and there was no
+ * way to tell a notice the session had acted on from one it had ignored
+ * (one seat ignored two — it was wedged on a dialog — and the flag read the
+ * same either way). The supervisor is the one place that KNOWS a relaunch
+ * happened and what version it launches on, so it retires the notice when
+ * the version it is launching onto is the one the notice asked for.
+ *
+ * A {healthy:false} body is a health REPORT, not a restart cue (feed-core):
+ * never retired here — autoupdate rewrites it on recovery.
+ *
+ * @module lib/session/upgrade-notice
+ */
+
+"use strict";
+
+/**
+ * @param {string|null|undefined} noticeText  raw upgrade-notice.json, or null when absent
+ * @param {string|null|undefined} installedVersion  the SDK version this launch runs
+ * @returns {{honoured:boolean, reason:string, from?:string, to?:string}}
+ */
+export function noticeHonouredBy(noticeText, installedVersion) {
+  if (typeof noticeText !== "string" || !noticeText.trim()) return { honoured: false, reason: "no-notice" };
+  let n;
+  try { n = JSON.parse(noticeText); } catch { return { honoured: false, reason: "unparseable" }; }
+  if (!n || typeof n !== "object") return { honoured: false, reason: "unparseable" };
+  if (n.healthy === false) return { honoured: false, reason: "health-report" };
+  const to = typeof n.to === "string" ? n.to.trim() : "";
+  const from = typeof n.from === "string" ? n.from.trim() : "";
+  if (!to) return { honoured: false, reason: "no-to" };
+  const v = typeof installedVersion === "string" ? installedVersion.trim() : "";
+  if (!v) return { honoured: false, reason: "installed-unknown", from, to };
+  if (v !== to) return { honoured: false, reason: `installed-${v}-is-not-${to}`, from, to };
+  return { honoured: true, reason: "launching-on-target", from, to };
+}

package/lib/setup/claude-probe.mjs

@@ -7,8 +7,9 @@
  *
  * Auth modes, resolved from the agent's `.env`:
  *
- *   subscription   CLAUDE_CODE_OAUTH_TOKEN is set (the `claude setup-token`
- *                  output — the fleet default) and/or
+ *   subscription   CLAUDE_CODE_OAUTH_TOKEN is set (a subscription OAuth
+ *                  token — still probed, but NOT the fleet posture: seats run
+ *                  on per-agent Console API keys, docs/guides/billing-console-keys.md) and/or
  *                  MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 (keychain login).
  *                  The probe runs `claude auth status --json` NON-INTERACTIVELY
  *                  with the token in the child env and maps the answer to
@@ -18,7 +19,7 @@
  *                  is otherwise fine, and the beat reports it honestly.
  *   api-key        ANTHROPIC_API_KEY only → a 5-token POST to api.anthropic.com
  *                  (the historic curl ping). 401 is the one hard failure.
- *   none           nothing configured → not ok, remedy names the token path.
+ *   none           nothing configured → not ok, remedy names the Console API key path.
  *
  * WHAT THE PROBE CAN AND CANNOT PROVE (`verified` on the result):
  *   `claude auth status` reports the PRESENCE of a credential, not its
@@ -39,7 +40,16 @@
  * launchd's environment, no .env). The two rows doctor prints can therefore
  * not contradict each other.
  *
- * Injectable (`opts.exec`, `opts.curl`, `opts.claudeBin`, `opts.env`) so every
+ * A seat whose config/agent.json names `runtime.engine: "cohort"` does not
+ * talk to Claude at all (W4 integration, conformance rows 1 and 25): its probe
+ * runs the engine's `auth status --json` with the seat's token helper and
+ * gateway URL, which proves the seat credential against GET /cohort/v1/quota
+ * (`mode:"cohort"`, `verified:true` on ok). A refused credential is
+ * `relogin_required`; an unreachable gateway or a broken engine is `unknown`
+ * and fail-open, as for the subscription probe. Claude seats are unchanged.
+ *
+ * Injectable (`opts.exec`, `opts.curl`, `opts.claudeBin`, `opts.env`,
+ * `opts.seatEngine`, `opts.cfg`, `opts.nodeBin`, `opts.engineCliPath`) so every
  * outcome is unit-testable offline; never throws.
  *
  * @module lib/setup/claude-probe
@@ -50,7 +60,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync, execFileSync } from "node:child_process";
-import { resolveClaudeBin } from "../claude-bin.mjs";
+import { buildSpawn, readSeatEngine, ENGINE_CLI_PATH } from "../runtime/adapter.mjs";
+import { apiKeyHelperCommand, resolveLlmBaseUrl } from "../org/llm-token.mjs";
+import { loadOrgConfig } from "../org/client.mjs";
 
 /** Hard ceiling on the `claude auth status` fork — the beat must never wedge on it. */
 export const AUTH_STATUS_TIMEOUT_MS = 8000;
@@ -111,11 +123,22 @@ function resolveValue(body, baseEnv, key) {
  * @param {(cmd:string,args:string[],o:object)=>string} [opts.exec]  injectable execFileSync (subscription mode; tests)
  * @param {string} [opts.claudeBin]  path of the claude CLI (default: resolveClaudeBin())
  * @param {object} [opts.env]        base env for the CLI fork (default: process.env)
- * @returns {{ok:boolean, mode:'subscription'|'api-key'|'none', auth?:'ok'|'relogin_required'|'unknown', verified:boolean, code?:string, name:string, remedy?:string, detail?:string}}
+ * @returns {{ok:boolean, mode:'subscription'|'api-key'|'none'|'cohort', auth?:'ok'|'relogin_required'|'unknown', verified:boolean, code?:string, name:string, remedy?:string, detail?:string}}
  *   `verified` is true only when a real call proved the credential (api-key 200);
  *   a subscription `ok` is the CLI reporting a login it has not exercised.
  */
+/**
+ * The remedy every probe failure gives (CF-13). Duplicated from
+ * lib/cli/doctor-checks.mjs CONSOLE_KEY_REMEDY rather than imported: the
+ * doctor module imports this one. claude-probe.test.mjs pins them equal.
+ */
+export const CONSOLE_KEY_REMEDY =
+  "put a per-agent Console API key (a workspace with a spend cap) in .env as ANTHROPIC_API_KEY and remove MAESTRO_PREFER_SUBSCRIPTION_AUTH / CLAUDE_CODE_OAUTH_TOKEN — see docs/guides/billing-console-keys.md";
+
 export function probeClaude(agentRoot, opts = {}) {
+  let engine = "claude";
+  try { engine = (opts.seatEngine || readSeatEngine)(agentRoot); } catch { engine = "claude"; /* unreadable config: the default engine */ }
+  if (engine === "cohort") return probeCohortEngine(agentRoot, opts);
   const envPath = join(agentRoot, ".env");
   const body = existsSync(envPath) ? readFileSync(envPath, "utf-8") : "";
   const baseEnv = opts.env || process.env;
@@ -128,7 +151,7 @@ export function probeClaude(agentRoot, opts = {}) {
   if (!key) {
     return {
       ok: false, mode: "none", auth: "unknown", verified: false, name: "Claude auth",
-      remedy: "run `claude setup-token` on any logged-in machine and put the result in .env as CLAUDE_CODE_OAUTH_TOKEN (plus MAESTRO_PREFER_SUBSCRIPTION_AUTH=1) — or set ANTHROPIC_API_KEY",
+      remedy: `nothing configured — ${CONSOLE_KEY_REMEDY}`,
     };
   }
   return probeApiKey(key, opts);
@@ -136,13 +159,16 @@ export function probeClaude(agentRoot, opts = {}) {
 
 function probeSubscription(body, opts, source) {
   const name = source === "oauth-token" ? "Claude auth (subscription — OAuth token)" : "Claude auth (subscription — keychain login)";
-  const bin = opts.claudeBin || resolveClaudeBin();
   const run = opts.exec || ((cmd, args, o) => execFileSync(cmd, args, o));
   let stdout = "";
   let failed = "";
   try {
-    stdout = String(run(bin, ["auth", "status", "--json"], {
-      env: authStatusEnv(body, opts.env || process.env),
+    // Binary + argv from the runtime adapter (lane "auth-status"); the env is
+    // the probe's own, carrying the token it is probing.
+    const spec = buildSpawn({ lane: "auth-status", bin: opts.claudeBin || undefined, env: authStatusEnv(body, opts.env || process.env) });
+    if (!spec.ok) throw new Error(spec.error.message);
+    stdout = String(run(spec.bin, spec.argv, {
+      env: spec.env,
       timeout: AUTH_STATUS_TIMEOUT_MS,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"],
@@ -168,8 +194,8 @@ function probeSubscription(body, opts, source) {
     return {
       ok: false, mode: "subscription", auth, verified: false, name,
       remedy: source === "oauth-token"
-        ? "the OAuth token was rejected — mint a fresh one with `claude setup-token` and replace CLAUDE_CODE_OAUTH_TOKEN in .env"
-        : "not logged in — run `claude setup-token` on any logged-in machine and put the result in .env as CLAUDE_CODE_OAUTH_TOKEN (the keychain login expires headlessly)",
+        ? `the OAuth token was rejected — do not mint another: ${CONSOLE_KEY_REMEDY}`
+        : `not logged in (the keychain login expires headlessly) — ${CONSOLE_KEY_REMEDY}`,
     };
   }
   // unknown: fail-OPEN. Say why, never silently.
@@ -201,7 +227,7 @@ function probeApiKey(key, opts) {
   if (code === "401") {
     return {
       ok: false, mode: "api-key", auth: "relogin_required", verified: false, code, name,
-      remedy: "ANTHROPIC_API_KEY is INVALID (HTTP 401) — replace it, or switch to the subscription token (`claude setup-token` → CLAUDE_CODE_OAUTH_TOKEN)",
+      remedy: "ANTHROPIC_API_KEY is INVALID (HTTP 401) — create a replacement Console API key in this agent's capped workspace and put it in .env (docs/guides/billing-console-keys.md)",
     };
   }
   if (!code) {
@@ -209,3 +235,81 @@ function probeApiKey(key, opts) {
   }
   return { ok: false, mode: "api-key", auth: "unknown", verified: false, code, name, remedy: `unexpected HTTP ${code} (expected 200)` };
 }
+
+/** Hard ceiling on the engine's `auth status` fork (it mints a token and makes one gateway call). */
+export const ENGINE_AUTH_STATUS_TIMEOUT_MS = 20000;
+
+/** Engine error codes that are a hard answer about the credential, not an outage. */
+const ENGINE_CREDENTIAL_REFUSED = new Set(["missing_token", "token_unavailable", "cohort_invalid_token", "cohort_invalid_key", "cohort_forbidden", "cohort_key_revoked", "http_401", "http_403"]);
+
+/**
+ * Map the engine's `auth status --json` output to the probe vocabulary. Pure.
+ * @param {string|null|undefined} stdout
+ * @returns {{auth:"ok"|"relogin_required"|"unknown", result:any}}
+ */
+export function parseEngineAuthStatus(stdout) {
+  const line = String(stdout || "").trim().split(/\r?\n/).filter((l) => l.trim() !== "").pop() || "";
+  let result = null;
+  try { result = JSON.parse(line); } catch { return { auth: "unknown", result: null }; }
+  if (!result || typeof result !== "object" || typeof result.ok !== "boolean") return { auth: "unknown", result: null };
+  if (result.ok) return { auth: "ok", result };
+  const code = result.error && typeof result.error.code === "string" ? result.error.code : "";
+  return { auth: ENGINE_CREDENTIAL_REFUSED.has(code) ? "relogin_required" : "unknown", result };
+}
+
+/**
+ * The engine child's env for the probe: the base env without any inherited
+ * gateway credential or Anthropic key, plus the seat's helper and gateway URL. Pure.
+ */
+export function engineAuthStatusEnv(agentRoot, baseEnv, { baseUrl, nodeBin }) {
+  const out = {};
+  for (const [k, v] of Object.entries(baseEnv || {})) {
+    if (/^ANTHROPIC_/i.test(k) || /^COHORT_LLM_(TOKEN|TOKEN_HELPER|API_KEY_HELPER|BASE_URL)$/i.test(k)) continue;
+    out[k] = v;
+  }
+  out.AGENT_ROOT = agentRoot;
+  out.COHORT_LLM_BASE_URL = baseUrl;
+  out.COHORT_LLM_TOKEN_HELPER = apiKeyHelperCommand({ agentRoot, nodeBin });
+  return out;
+}
+
+function probeCohortEngine(agentRoot, opts) {
+  const name = "Cohort engine auth (cohort-llm)";
+  const run = opts.exec || ((cmd, args, o) => execFileSync(cmd, args, o));
+  const baseEnv = opts.env || process.env;
+  let cfg = opts.cfg;
+  if (cfg === undefined) { try { cfg = loadOrgConfig(agentRoot); } catch { cfg = null; /* no org config: env or the production default */ } }
+  const baseUrl = resolveLlmBaseUrl({ cfg, env: baseEnv });
+  const nodeBin = opts.nodeBin || process.execPath;
+  let stdout = "";
+  let failed = "";
+  try {
+    stdout = String(run(nodeBin, [opts.engineCliPath || ENGINE_CLI_PATH, "auth", "status", "--json"], {
+      env: engineAuthStatusEnv(agentRoot, baseEnv, { baseUrl, nodeBin }),
+      timeout: ENGINE_AUTH_STATUS_TIMEOUT_MS,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 256 * 1024,
+    }) || "");
+  } catch (err) {
+    // Exit 1 still prints the JSON status; read it before giving up.
+    stdout = err && typeof err.stdout === "string" ? err.stdout : (err && err.stdout ? String(err.stdout) : "");
+    failed = err && (err.code || err.message) ? String(err.code || err.message) : "exec failed";
+  }
+  const { auth, result } = parseEngineAuthStatus(stdout);
+  if (auth === "ok") {
+    const who = result.principal ? ` as ${JSON.stringify(result.principal)}` : "";
+    return { ok: true, mode: "cohort", auth, verified: true, name, detail: `the seat credential is accepted by ${result.baseUrl || baseUrl}${who}` };
+  }
+  const err = result && result.error ? result.error : null;
+  if (auth === "relogin_required") {
+    return {
+      ok: false, mode: "cohort", auth, verified: false, code: err.code, name,
+      remedy: `the seat's cohort-llm credential was refused (${err.code}: ${err.message}) — check the seat's OrgApiKey in config/org.yaml or .env, then run \`node ${opts.engineCliPath || ENGINE_CLI_PATH} auth status --json\``,
+    };
+  }
+  return {
+    ok: true, mode: "cohort", auth: "unknown", verified: false, name,
+    detail: `could not verify (${err ? `${err.code}: ${err.message}` : failed ? `engine auth status failed: ${failed}` : "no usable answer"}) — run \`node ${opts.engineCliPath || ENGINE_CLI_PATH} auth status --json\` by hand`,
+  };
+}

package/lib/setup/enrich.mjs

@@ -32,7 +32,7 @@ import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFile } from "node:child_process";
-import { resolveClaudeBin, daemonClaudeArgs } from "../claude-bin.mjs";
+import { buildSpawn } from "../runtime/adapter.mjs";
 import { mergeAgentJson, readAgentJson } from "./sot.mjs";
 import { readContextPack } from "./context-pack.mjs";
 import { markEnrich } from "./state.mjs";
@@ -181,15 +181,18 @@ export function buildPrompt(unit, pack, skeleton) {
  */
 function defaultSpawn(prompt, opts = {}) {
   return new Promise((resolve, reject) => {
-    const bin = resolveClaudeBin();
-    const args = [
-      "--print",
-      ...daemonClaudeArgs(),
-      "--model", opts.model || "claude-sonnet-4-6",
-      "--append-system-prompt", prompt.system,
-      prompt.user,
-    ];
-    execFile(bin, args, { encoding: "utf-8", timeout: opts.timeoutMs || 60000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+    // argv + env from the runtime adapter (lane "enrich"): --print <daemon MCP
+    // args> --model <m> --append-system-prompt <sys> <user>; env inherited.
+    const spec = buildSpawn({
+      lane: "enrich",
+      model: opts.model || "claude-sonnet-4-6",
+      systemPrompt: prompt.system,
+      prompt: prompt.user,
+      mcp: {},
+      env: process.env,
+    });
+    if (!spec.ok) return reject(new Error(spec.error.message));
+    execFile(spec.bin, spec.argv, { encoding: "utf-8", timeout: opts.timeoutMs || 60000, maxBuffer: 4 * 1024 * 1024, env: spec.env }, (err, stdout) => {
       if (err) return reject(err);
       resolve(stdout || "");
     });

package/lib/setup/sections/model.mjs

@@ -4,14 +4,17 @@
  * Records how the agent authenticates to Claude. Three modes, in the order the
  * wizard offers them:
  *
- *   oauth-token   DEFAULT. The operator runs `claude setup-token` on any
- *                 machine where they are logged in and pastes the result.
+ *   api-key       DEFAULT. An Anthropic Console API key created for this agent,
+ *                 in a Console workspace with a spend limit
+ *                 (docs/guides/billing-console-keys.md). .env gets
+ *                 ANTHROPIC_API_KEY. Headless reads ANTHROPIC_API_KEY from the
+ *                 environment.
+ *   oauth-token   A Claude subscription token from `claude setup-token`, for a
+ *                 person's own development machine — not an agent seat.
  *                 .env gets CLAUDE_CODE_OAUTH_TOKEN + MAESTRO_PREFER_SUBSCRIPTION_AUTH=1.
- *                 Headless reads CLAUDE_CODE_OAUTH_TOKEN from the environment.
- *                 This is the fleet posture: the interactive keychain login
- *                 expires headlessly; the long-lived token does not.
+ *                 Headless pre-selects it only when CLAUDE_CODE_OAUTH_TOKEN is
+ *                 the one Claude credential in the environment (see defaultAuthMode).
  *   subscription  Keychain login on this machine (MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 only).
- *   api-key       ANTHROPIC_API_KEY (pay-per-token).
  *
  * Every write goes through appendEnv (never clobbers an existing value) and
  * .env is chmod 600 afterwards — it now carries a credential either way.
@@ -29,9 +32,25 @@ import * as defaultIo from "../io.mjs";
 import { probeClaude as defaultProbeClaude } from "../claude-probe.mjs";
 
 /** The three auth modes, in wizard order. The first is the default. */
-export const AUTH_MODES = Object.freeze(["oauth-token", "subscription", "api-key"]);
+export const AUTH_MODES = Object.freeze(["api-key", "oauth-token", "subscription"]);
 export const DEFAULT_AUTH_MODE = AUTH_MODES[0];
 
+/**
+ * Pure: the mode the wizard pre-selects for an environment. A Console key in
+ * the environment means api-key. A subscription token as the ONLY Claude
+ * credential is the operator stating intent (the pre-2.18 headless bootstrap,
+ * `CLAUDE_CODE_OAUTH_TOKEN=… maestro setup --headless`), so that seat keeps
+ * the mode it asked for. Otherwise the default.
+ * @param {object} [env]
+ * @returns {"api-key"|"oauth-token"|"subscription"}
+ */
+export function defaultAuthMode(env = {}) {
+  const has = (k) => !!env && typeof env[k] === "string" && env[k].trim() !== "";
+  if (has("ANTHROPIC_API_KEY")) return "api-key";
+  if (has("CLAUDE_CODE_OAUTH_TOKEN")) return "oauth-token";
+  return DEFAULT_AUTH_MODE;
+}
+
 function readEnv(agentRoot) {
   const p = join(agentRoot, ".env");
   return existsSync(p) ? readFileSync(p, "utf-8") : "";
@@ -88,11 +107,11 @@ export default {
       message: "How should the agent authenticate to Claude?",
       key: "provider",
       choices: [
-        { label: "Subscription token — run `claude setup-token` on any logged-in machine and paste the result (recommended)", value: "oauth-token" },
+        { label: "Anthropic Console API key — one per agent, in a Console workspace with a spend limit (recommended; headless: ANTHROPIC_API_KEY)", value: "api-key" },
+        { label: "Subscription token from `claude setup-token` — a person's own development machine only, not an agent seat", value: "oauth-token" },
         { label: "Subscription via this machine's keychain login (expires headlessly — not for a seat machine)", value: "subscription" },
-        { label: "Anthropic API key (paste an sk-ant-… key, pay-per-token)", value: "api-key" },
       ],
-      default: DEFAULT_AUTH_MODE,
+      default: defaultAuthMode(process.env),
     });
     let oauthToken = "";
     let apiKey = "";
@@ -103,7 +122,11 @@ export default {
         env: "CLAUDE_CODE_OAUTH_TOKEN",
       });
     } else if (provider === "api-key") {
-      apiKey = await io.secret(ctx, { message: "Paste ANTHROPIC_API_KEY (sk-ant-…)", key: "anthropicApiKey" });
+      apiKey = await io.secret(ctx, {
+        message: "Paste this agent's Anthropic Console API key (sk-ant-api…) — see docs/guides/billing-console-keys.md (headless: ANTHROPIC_API_KEY)",
+        key: "anthropicApiKey",
+        env: "ANTHROPIC_API_KEY",
+      });
     }
     const routing = await io.confirm(ctx, {
       message: "Enable cost-optimised model routing (writes config/model-routing.yaml)?",
@@ -170,12 +193,15 @@ function pull(ctx) {
   const m = ans.model && typeof ans.model === "object" ? ans.model : null;
   const envToken = String(ans.claudeOauthToken || (m && m.oauthToken) || process.env.CLAUDE_CODE_OAUTH_TOKEN || "").trim();
   const apiKey = String(ans.anthropicApiKey || (m && m.apiKey) || "");
+  // With no recorded provider: a key means api-key, a lone token means the
+  // operator asked for oauth-token, nothing means the default.
+  const inferred = apiKey ? "api-key" : envToken ? "oauth-token" : DEFAULT_AUTH_MODE;
   if (m) {
-    const provider = m.provider || (apiKey ? "api-key" : DEFAULT_AUTH_MODE);
+    const provider = m.provider || inferred;
     return { provider, oauthToken: provider === "oauth-token" ? envToken : "", apiKey, routing: !!m.routing };
   }
   if ("provider" in ans || "anthropicApiKey" in ans || envToken) {
-    const provider = ans.provider || (apiKey ? "api-key" : DEFAULT_AUTH_MODE);
+    const provider = ans.provider || inferred;
     return { provider, oauthToken: provider === "oauth-token" ? envToken : "", apiKey, routing: !!ans.modelRouting };
   }
   return null;