@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/setup/claude-probe.mjs

@@ -1,12 +1,46 @@
 /**
- * lib/setup/claude-probe.mjs — reachability probe for the Claude API.
+ * lib/setup/claude-probe.mjs — is this agent able to talk to Claude?
  *
- * Mirrors the curl check in bin/maestro.mjs (doctor, ~:1566): POST a 5-token
- * ping to api.anthropic.com with the .env key. Returns a structured result with
- * a remedy line so the wizard's capability table and doctor can share the logic.
+ * One probe, shared by the setup wizard's capability table, `maestro doctor`
+ * and the fleet beat (`lib/telemetry/collect.mjs#detectClaudeAuth`), so the
+ * three never disagree about the same machine.
  *
- * Honors MAESTRO_PREFER_SUBSCRIPTION_AUTH (subscription/keychain OAuth wins → the
- * probe reports `ok` without an API key).
+ * 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
+ *                  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
+ *                  `ok | relogin_required | unknown`. A missing/slow CLI is
+ *                  `unknown`, which is fail-OPEN (`ok:true` + a note): an
+ *                  unverifiable state must not brick setup on a machine that
+ *                  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.
+ *
+ * WHAT THE PROBE CAN AND CANNOT PROVE (`verified` on the result):
+ *   `claude auth status` reports the PRESENCE of a credential, not its
+ *   validity — with CLAUDE_CODE_OAUTH_TOKEN=anything in the env it answers
+ *   `{loggedIn:true, authMethod:"oauth_token"}` and exits 0 (checked
+ *   2026-09-08 with a bogus token). So a subscription `ok` is REPORTED
+ *   (`verified:false`, detail says so) and only a real spawn exercises the
+ *   token: a rejection lands in logs/sessions, which the beat's log scan and
+ *   `detectClaudeAuth` read as `relogin_required`. `relogin_required` from
+ *   the CLI (no credential at all) is a hard answer. The api-key ping makes a
+ *   real call, so its 200 is `verified:true`. Consumers that need proof —
+ *   the fleet beat — treat an unverified ok as `unknown` and let the log
+ *   evidence decide, exactly as before the probe existed.
+ *
+ * Mode resolution reads the agent's `.env` FIRST and the ambient env second
+ * (`opts.env`, default process.env) — the same precedence doctor's `authMode`
+ * uses, and what the headless runbooks prescribe (the token arrives via
+ * 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
+ * outcome is unit-testable offline; never throws.
  *
  * @module lib/setup/claude-probe
  */
@@ -15,35 +49,138 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, execFileSync } from "node:child_process";
+import { resolveClaudeBin } from "../claude-bin.mjs";
+
+/** Hard ceiling on the `claude auth status` fork — the beat must never wedge on it. */
+export const AUTH_STATUS_TIMEOUT_MS = 8000;
 
 /** Parse a single KEY from a .env file body. */
 function envValue(body, key) {
-  const m = body.match(new RegExp(`^${key}=(.+)$`, "m"));
+  const m = String(body || "").match(new RegExp(`^${key}=(.+)$`, "m"));
   return m ? m[1].trim().replace(/^["']|["']$/g, "") : "";
 }
 
 /**
- * Probe Claude API reachability for an agent repo.
+ * Map `claude auth status --json` output to the three-state vocabulary.
+ * Pure. Tolerates the text form (`--text`, older CLIs) by fingerprint.
+ * @param {string|null|undefined} stdout
+ * @returns {"ok"|"relogin_required"|"unknown"}
+ */
+export function parseAuthStatus(stdout) {
+  const s = typeof stdout === "string" ? stdout.trim() : "";
+  if (!s) return "unknown";
+  try {
+    const j = JSON.parse(s);
+    if (j && typeof j === "object" && "loggedIn" in j) return j.loggedIn ? "ok" : "relogin_required";
+  } catch { /* not JSON — fall through to the text fingerprints */ }
+  const lower = s.toLowerCase();
+  if (/not logged in|please run \/login|claude login|login required|expired/.test(lower)) return "relogin_required";
+  if (/logged in\b|loggedin\s*:\s*true/.test(lower)) return "ok";
+  return "unknown";
+}
+
+/**
+ * The env for the auth probe: `baseEnv` plus the .env token when present. Only
+ * the token crosses over — the rest of `.env` is the agent's secret set and has
+ * no business in a diagnostic fork.
+ * @param {string} envBody   the .env file body
+ * @param {object} [baseEnv] usually process.env
+ * @returns {object}
+ */
+export function authStatusEnv(envBody, baseEnv = process.env) {
+  const out = { ...(baseEnv || {}) };
+  const token = envValue(envBody, "CLAUDE_CODE_OAUTH_TOKEN");
+  if (token) out.CLAUDE_CODE_OAUTH_TOKEN = token;
+  return out;
+}
+
+/** `.env` first, then the ambient env — one value per key, empty when neither has it. */
+function resolveValue(body, baseEnv, key) {
+  const fromFile = envValue(body, key);
+  if (fromFile) return fromFile;
+  const v = baseEnv && baseEnv[key];
+  return v == null ? "" : String(v).trim();
+}
+
+/**
+ * Probe Claude auth/reachability for an agent repo.
  * @param {string} agentRoot
  * @param {object} [opts]
- * @param {(args:string[])=>{stdout?:string}} [opts.curl]  injectable curl (for tests)
- * @returns {{ok:boolean, mode:'subscription'|'api-key'|'none', code?:string, name:string, remedy?:string}}
+ * @param {(args:string[])=>{stdout?:string}} [opts.curl]  injectable curl (api-key mode; tests)
+ * @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}}
+ *   `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.
  */
 export function probeClaude(agentRoot, opts = {}) {
   const envPath = join(agentRoot, ".env");
   const body = existsSync(envPath) ? readFileSync(envPath, "utf-8") : "";
-  const preferSubs = /^(1|true|yes)$/i.test(envValue(body, "MAESTRO_PREFER_SUBSCRIPTION_AUTH"));
-  if (preferSubs) {
-    return { ok: true, mode: "subscription", name: "Claude API (subscription auth)" };
-  }
-  const key = envValue(body, "ANTHROPIC_API_KEY");
+  const baseEnv = opts.env || process.env;
+  const token = resolveValue(body, baseEnv, "CLAUDE_CODE_OAUTH_TOKEN");
+  const preferSubs = /^(1|true|yes)$/i.test(resolveValue(body, baseEnv, "MAESTRO_PREFER_SUBSCRIPTION_AUTH"));
+
+  if (token || preferSubs) return probeSubscription(body, opts, token ? "oauth-token" : "keychain");
+
+  const key = resolveValue(body, baseEnv, "ANTHROPIC_API_KEY");
   if (!key) {
     return {
-      ok: false, mode: "none", name: "Claude API reachable",
-      remedy: "set ANTHROPIC_API_KEY in .env, or MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 to use Claude Code subscription",
+      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",
     };
   }
+  return probeApiKey(key, 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),
+      timeout: AUTH_STATUS_TIMEOUT_MS,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 256 * 1024,
+    }) || "");
+  } catch (err) {
+    // A non-zero exit still carries stdout on execFileSync errors (the CLI
+    // prints `{"loggedIn":false}` and exits 1); 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 = parseAuthStatus(stdout);
+  if (auth === "ok") {
+    // REPORTED, not verified — see the module docblock. Say so in the row.
+    return {
+      ok: true, mode: "subscription", auth, verified: false, name,
+      detail: source === "oauth-token"
+        ? "CLI reports a login for the token; the token itself is only proven by a real spawn (a rejection shows in logs/sessions and on the beat as relogin_required)"
+        : "CLI reports a keychain login; it is only proven by a real spawn (a rejection shows in logs/sessions and on the beat as relogin_required)",
+    };
+  }
+  if (auth === "relogin_required") {
+    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)",
+    };
+  }
+  // unknown: fail-OPEN. Say why, never silently.
+  return {
+    ok: true, mode: "subscription", auth: "unknown", verified: false, name,
+    detail: `could not verify (claude auth status ${failed ? `failed: ${failed}` : "gave no usable answer"}) — run \`claude auth status\` by hand`,
+  };
+}
+
+function probeApiKey(key, opts) {
+  const name = "Claude API reachable (api-key)";
   const run = opts.curl || ((args) => spawnSync("curl", args, { encoding: "utf-8" }));
   let code = "";
   try {
@@ -58,17 +195,17 @@ export function probeClaude(agentRoot, opts = {}) {
       "-d", JSON.stringify({ model: "claude-haiku-4-5", max_tokens: 5, messages: [{ role: "user", content: "ping" }] }),
     ]);
     code = (res && res.stdout ? res.stdout : "").trim();
-  } catch { code = ""; }
+  } catch { code = ""; /* curl missing/throwing is reported as "no network" below */ }
 
-  if (code === "200") return { ok: true, mode: "api-key", code, name: "Claude API reachable" };
+  if (code === "200") return { ok: true, mode: "api-key", auth: "ok", verified: true, code, name };
   if (code === "401") {
     return {
-      ok: false, mode: "api-key", code, name: "Claude API reachable",
-      remedy: "ANTHROPIC_API_KEY is INVALID (HTTP 401) — replace it, or set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1",
+      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)",
     };
   }
   if (!code) {
-    return { ok: false, mode: "api-key", code, name: "Claude API reachable", remedy: "no network / curl missing — could not verify the key" };
+    return { ok: false, mode: "api-key", auth: "unknown", verified: false, code, name, remedy: "no network / curl missing — could not verify the key" };
   }
-  return { ok: false, mode: "api-key", code, name: "Claude API reachable", remedy: `unexpected HTTP ${code} (expected 200)` };
+  return { ok: false, mode: "api-key", auth: "unknown", verified: false, code, name, remedy: `unexpected HTTP ${code} (expected 200)` };
 }

package/lib/setup/claude-probe.test.mjs

@@ -0,0 +1,187 @@
+/**
+ * claude-probe.test.mjs — the Claude auth/reachability probe (lib/setup/claude-probe.mjs).
+ *
+ * Hermetic: the `claude auth status` exec and the curl ping are injected, so no
+ * network and no real CLI fork. Covers the three auth modes (oauth-token /
+ * keychain subscription / api-key) and the ok | relogin_required | unknown
+ * mapping the fleet beat reads.
+ *
+ * Run: node --test lib/setup/claude-probe.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { probeClaude, parseAuthStatus, authStatusEnv, AUTH_STATUS_TIMEOUT_MS } from "./claude-probe.mjs";
+
+function rootWithEnv(body) {
+  const root = mkdtempSync(join(tmpdir(), "claude-probe-"));
+  writeFileSync(join(root, ".env"), body);
+  return root;
+}
+
+/** An execFileSync-shaped fake: records the call, returns canned stdout / throws. */
+function fakeExec(reply) {
+  const calls = [];
+  const fn = (cmd, args, opts) => {
+    calls.push({ cmd, args, opts });
+    if (reply instanceof Error) throw reply;
+    if (typeof reply === "function") return reply(cmd, args, opts);
+    return reply;
+  };
+  fn.calls = calls;
+  return fn;
+}
+
+test("parseAuthStatus maps the CLI's JSON to the three-state vocabulary", () => {
+  assert.equal(parseAuthStatus('{"loggedIn":true,"authMethod":"claude.ai","subscriptionType":"max"}'), "ok");
+  assert.equal(parseAuthStatus('{"loggedIn":false}'), "relogin_required");
+  assert.equal(parseAuthStatus("Not logged in. Run `claude login`."), "relogin_required");
+  assert.equal(parseAuthStatus(""), "unknown");
+  assert.equal(parseAuthStatus("garbage that is not json"), "unknown");
+  assert.equal(parseAuthStatus(null), "unknown");
+});
+
+test("authStatusEnv overlays the .env token onto the base env without leaking other keys", () => {
+  const env = authStatusEnv("CLAUDE_CODE_OAUTH_TOKEN=\"tok-123\"\nOTHER=1\n", { PATH: "/usr/bin" });
+  assert.equal(env.CLAUDE_CODE_OAUTH_TOKEN, "tok-123");
+  assert.equal(env.PATH, "/usr/bin");
+  assert.equal(env.OTHER, undefined);
+  // No token in .env → the base env is returned untouched (keychain login may still work).
+  const bare = authStatusEnv("MAESTRO_PREFER_SUBSCRIPTION_AUTH=1\n", { PATH: "/usr/bin" });
+  assert.equal(bare.CLAUDE_CODE_OAUTH_TOKEN, undefined);
+});
+
+test("oauth-token mode: runs `claude auth status` with the .env token in env → ok", () => {
+  const root = rootWithEnv("CLAUDE_CODE_OAUTH_TOKEN=tok-abc\nMAESTRO_PREFER_SUBSCRIPTION_AUTH=1\n");
+  try {
+    const exec = fakeExec('{"loggedIn":true,"authMethod":"claude.ai"}');
+    const r = probeClaude(root, { exec, claudeBin: "/fake/claude", env: { PATH: "/usr/bin" } });
+    assert.equal(r.ok, true);
+    assert.equal(r.mode, "subscription");
+    assert.equal(r.auth, "ok");
+    assert.equal(exec.calls.length, 1);
+    assert.equal(exec.calls[0].cmd, "/fake/claude");
+    assert.deepEqual(exec.calls[0].args, ["auth", "status", "--json"]);
+    assert.equal(exec.calls[0].opts.env.CLAUDE_CODE_OAUTH_TOKEN, "tok-abc");
+    assert.equal(exec.calls[0].opts.timeout, AUTH_STATUS_TIMEOUT_MS);
+    assert.equal(AUTH_STATUS_TIMEOUT_MS, 8000);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("subscription mode: loggedIn:false → relogin_required, not ok, remedy names setup-token", () => {
+  const root = rootWithEnv("MAESTRO_PREFER_SUBSCRIPTION_AUTH=1\n");
+  try {
+    const r = probeClaude(root, { exec: fakeExec('{"loggedIn":false}'), claudeBin: "/fake/claude" });
+    assert.equal(r.ok, false);
+    assert.equal(r.auth, "relogin_required");
+    assert.match(r.remedy, /claude setup-token/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("subscription mode: a missing/broken CLI is unknown and FAIL-OPEN (ok:true with a note)", () => {
+  const root = rootWithEnv("MAESTRO_PREFER_SUBSCRIPTION_AUTH=1\n");
+  try {
+    const r = probeClaude(root, { exec: fakeExec(Object.assign(new Error("ENOENT"), { code: "ENOENT" })), claudeBin: "/fake/claude" });
+    assert.equal(r.ok, true, "an unverifiable auth state must not hard-fail setup/doctor");
+    assert.equal(r.auth, "unknown");
+    assert.match(r.detail, /could not verify/i);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("a token WITHOUT the prefer flag still selects subscription mode (the token is the auth)", () => {
+  const root = rootWithEnv("CLAUDE_CODE_OAUTH_TOKEN=tok-abc\n");
+  try {
+    const r = probeClaude(root, { exec: fakeExec('{"loggedIn":true}'), claudeBin: "/fake/claude" });
+    assert.equal(r.mode, "subscription");
+    assert.equal(r.auth, "ok");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("api-key mode still pings api.anthropic.com via the injected curl", () => {
+  const root = rootWithEnv("ANTHROPIC_API_KEY=sk-ant-test\n");
+  try {
+    const exec = fakeExec("{}");
+    const r = probeClaude(root, { curl: () => ({ stdout: "200" }), exec });
+    assert.equal(r.ok, true);
+    assert.equal(r.mode, "api-key");
+    assert.equal(exec.calls.length, 0, "api-key mode never forks the CLI");
+    const bad = probeClaude(root, { curl: () => ({ stdout: "401" }), exec });
+    assert.equal(bad.ok, false);
+    assert.match(bad.remedy, /INVALID/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("no auth at all → not ok, remedy names the oauth-token path first", () => {
+  const root = rootWithEnv("");
+  try {
+    const r = probeClaude(root, { exec: fakeExec("{}"), curl: () => ({ stdout: "" }) });
+    assert.equal(r.ok, false);
+    assert.equal(r.mode, "none");
+    assert.match(r.remedy, /CLAUDE_CODE_OAUTH_TOKEN/);
+    assert.match(r.remedy, /claude setup-token/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+// ---------------------------------------------------------------------------
+// Review 2026-09-08: what the probe can and cannot prove
+// ---------------------------------------------------------------------------
+
+test("an env-token 'ok' is REPORTED, never VERIFIED: `claude auth status` says loggedIn for any token value", () => {
+  // Verified on 2026-09-08: CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-bogus claude auth status --json
+  // → {loggedIn:true, authMethod:"oauth_token"} exit 0. The CLI reports the
+  // presence of a credential; only a real spawn exercises it.
+  const root = rootWithEnv("CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-bogus\nMAESTRO_PREFER_SUBSCRIPTION_AUTH=1\n");
+  try {
+    const r = probeClaude(root, { exec: fakeExec('{"loggedIn":true,"authMethod":"oauth_token"}'), claudeBin: "/fake/claude", env: {} });
+    assert.equal(r.ok, true);
+    assert.equal(r.auth, "ok");
+    assert.equal(r.verified, false, "the probe cannot validate an OAuth token");
+    assert.match(r.detail, /CLI reports a login/i);
+    assert.match(r.detail, /spawn/i, "says where the token IS proven");
+    assert.doesNotMatch(r.detail, /verified/i);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("an api-key 200 IS verified (a real call was made); 401 is a hard relogin", () => {
+  const root = rootWithEnv("ANTHROPIC_API_KEY=sk-ant-test\n");
+  try {
+    const good = probeClaude(root, { curl: () => ({ stdout: "200" }), exec: fakeExec("{}") });
+    assert.equal(good.verified, true);
+    const bad = probeClaude(root, { curl: () => ({ stdout: "401" }), exec: fakeExec("{}") });
+    assert.equal(bad.verified, false);
+    assert.equal(bad.auth, "relogin_required");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("a token that lives ONLY in the ambient env (no .env) still selects subscription mode — the headless docs prescribe exactly that", () => {
+  const root = rootWithEnv("");
+  try {
+    const exec = fakeExec('{"loggedIn":true,"authMethod":"oauth_token"}');
+    const r = probeClaude(root, { exec, claudeBin: "/fake/claude", env: { PATH: "/usr/bin", CLAUDE_CODE_OAUTH_TOKEN: "tok-from-launchd" } });
+    assert.equal(r.mode, "subscription");
+    assert.equal(r.auth, "ok");
+    assert.match(r.name, /OAuth token/);
+    assert.equal(exec.calls[0].opts.env.CLAUDE_CODE_OAUTH_TOKEN, "tok-from-launchd");
+    // .env wins over the ambient env for the value (same precedence doctor's authMode uses).
+    const root2 = rootWithEnv("CLAUDE_CODE_OAUTH_TOKEN=tok-from-dotenv\n");
+    try {
+      const exec2 = fakeExec('{"loggedIn":true}');
+      probeClaude(root2, { exec: exec2, claudeBin: "/fake/claude", env: { CLAUDE_CODE_OAUTH_TOKEN: "tok-from-launchd" } });
+      assert.equal(exec2.calls[0].opts.env.CLAUDE_CODE_OAUTH_TOKEN, "tok-from-dotenv");
+    } finally { rmSync(root2, { recursive: true, force: true }); }
+    // Ambient MAESTRO_PREFER_SUBSCRIPTION_AUTH / ANTHROPIC_API_KEY count too.
+    const keychain = probeClaude(root, { exec: fakeExec('{"loggedIn":true}'), claudeBin: "/fake/claude", env: { MAESTRO_PREFER_SUBSCRIPTION_AUTH: "1" } });
+    assert.equal(keychain.mode, "subscription");
+    assert.match(keychain.name, /keychain/);
+    const key = probeClaude(root, { exec: fakeExec("{}"), curl: () => ({ stdout: "200" }), env: { ANTHROPIC_API_KEY: "sk-env" } });
+    assert.equal(key.mode, "api-key");
+    // Nothing anywhere → none (the ambient env is the injected one, not the test runner's).
+    const none = probeClaude(root, { exec: fakeExec("{}"), curl: () => ({ stdout: "" }), env: {} });
+    assert.equal(none.mode, "none");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});

package/lib/setup/sections/learning.mjs

@@ -19,6 +19,7 @@
 import { join } from "node:path";
 import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { writeJsonAtomic } from "../../fs-atomic.mjs";
 import * as io from "../io.mjs";
 import { countersPath, emptyCounters } from "../../learning/counters.mjs";
 
@@ -89,7 +90,7 @@ function seedCounters(agentRoot) {
   if (existsSync(p)) return;
   try {
     mkdirSync(join(agentRoot, "state", "learning"), { recursive: true });
-    writeFileSync(p, JSON.stringify(emptyCounters(), null, 2) + "\n");
+    writeJsonAtomic(p, emptyCounters());
   } catch { /* fail-open */ }
 }
 

package/lib/setup/sections/model.mjs

@@ -1,10 +1,22 @@
 /**
  * sections/model.mjs — model / provider selection.  (order 30)
  *
- * Records the provider choice: either Anthropic API key (recorded in .env) or
- * the Claude Code subscription (MAESTRO_PREFER_SUBSCRIPTION_AUTH=1). Optionally
- * drops a config/model-routing.yaml from the shipped example for cost routing.
- * Verify probes Claude API reachability (shared with doctor).
+ * 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.
+ *                 .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.
+ *   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.
+ * Optionally drops a config/model-routing.yaml from the shipped example.
+ * Verify runs the shared Claude probe (lib/setup/claude-probe.mjs).
  *
  * @module lib/setup/sections/model
  */
@@ -12,9 +24,13 @@
 "use strict";
 
 import { join } from "node:path";
-import { existsSync, readFileSync, appendFileSync, writeFileSync, copyFileSync } from "node:fs";
-import * as io from "../io.mjs";
-import { probeClaude } from "../claude-probe.mjs";
+import { existsSync, readFileSync, appendFileSync, writeFileSync, copyFileSync, chmodSync } from "node:fs";
+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 DEFAULT_AUTH_MODE = AUTH_MODES[0];
 
 function readEnv(agentRoot) {
   const p = join(agentRoot, ".env");
@@ -22,14 +38,34 @@ function readEnv(agentRoot) {
 }
 function hasKey(body, key) { return new RegExp(`^${key}=.+`, "m").test(body); }
 
+/**
+ * Write KEY=value into .env without clobbering a real value. Three cases:
+ *   - the key has a non-empty value  → leave it alone (never clobber)
+ *   - the key is present but EMPTY   → fill that line in place. A `.env` copied
+ *     from `.env.example` (doctor's own remedy) ships `CLAUDE_CODE_OAUTH_TOKEN=`
+ *     and `MAESTRO_PREFER_SUBSCRIPTION_AUTH=` as empty placeholders; treating
+ *     those as "already set" left a freshly set-up seat with no auth at all.
+ *     An empty line is "unset" for every consumer we have (dotenv, the probe,
+ *     doctor's parseDotEnv, hasKey() just above) — this writer now agrees.
+ *   - the key is absent              → append
+ */
 function appendEnv(agentRoot, key, value) {
   const p = join(agentRoot, ".env");
-  if (!existsSync(p)) { writeFileSync(p, `${key}=${value}\n`); return; }
+  if (!existsSync(p)) { writeFileSync(p, `${key}=${value}\n`, { mode: 0o600 }); return; }
   const body = readFileSync(p, "utf-8");
-  if (new RegExp(`^${key}=`, "m").test(body)) return; // never clobber an existing value
+  if (hasKey(body, key)) return; // never clobber an existing value
+  const empty = new RegExp(`^${key}=[ \\t]*$`, "m");
+  if (empty.test(body)) { writeFileSync(p, body.replace(empty, `${key}=${value}`)); return; }
   appendFileSync(p, `${body.endsWith("\n") || body === "" ? "" : "\n"}${key}=${value}\n`);
 }
 
+/** .env carries a credential in every mode — owner-only, always. POSIX mode bits only. */
+function lockDownEnv(agentRoot) {
+  const p = join(agentRoot, ".env");
+  if (!existsSync(p) || typeof process.getuid !== "function") return;
+  try { chmodSync(p, 0o600); } catch { /* a foreign-owned .env is reported by doctor, not fixed here */ }
+}
+
 export default {
   id: "model",
   label: "Model & provider",
@@ -37,25 +73,36 @@ export default {
 
   async detect(ctx) {
     const env = readEnv(ctx.agentRoot);
+    const token = hasKey(env, "CLAUDE_CODE_OAUTH_TOKEN");
     const subs = /^MAESTRO_PREFER_SUBSCRIPTION_AUTH=(1|true|yes)/im.test(env);
     const apiKey = hasKey(env, "ANTHROPIC_API_KEY");
-    if (subs) return { status: "complete", summary: "Claude Code subscription auth" };
+    if (token) return { status: "complete", summary: "Claude subscription — OAuth token (.env)" };
+    if (subs) return { status: "complete", summary: "Claude subscription — keychain login" };
     if (apiKey) return { status: "complete", summary: "Anthropic API key (.env)" };
     return { status: "unconfigured", missing: ["provider auth"] };
   },
 
   async prompt(ctx) {
+    const io = ctx.io || defaultIo;
     const provider = await io.select(ctx, {
       message: "How should the agent authenticate to Claude?",
       key: "provider",
       choices: [
-        { label: "Claude Code subscription (keychain OAuth — no API key needed)", value: "subscription" },
-        { label: "Anthropic API key (paste an sk-ant-… key)", value: "api-key" },
+        { label: "Subscription token — run `claude setup-token` on any logged-in machine and paste the result (recommended)", 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: "subscription",
+      default: DEFAULT_AUTH_MODE,
     });
+    let oauthToken = "";
     let apiKey = "";
-    if (provider === "api-key") {
+    if (provider === "oauth-token") {
+      oauthToken = await io.secret(ctx, {
+        message: "Run `claude setup-token` on any machine where you are logged in, then paste the token here (headless: CLAUDE_CODE_OAUTH_TOKEN)",
+        key: "claudeOauthToken",
+        env: "CLAUDE_CODE_OAUTH_TOKEN",
+      });
+    } else if (provider === "api-key") {
       apiKey = await io.secret(ctx, { message: "Paste ANTHROPIC_API_KEY (sk-ant-…)", key: "anthropicApiKey" });
     }
     const routing = await io.confirm(ctx, {
@@ -63,40 +110,73 @@ export default {
       key: "modelRouting",
       default: false,
     });
-    ctx.answers.model = { provider, apiKey, routing };
+    // The credential VALUES stay out of `answers.model`: the runner persists the
+    // whole answers bag to state/setup/progress.json (0644) after prompt(), and
+    // a nested value is as leaked as a top-level one. They live under their own
+    // top-level keys — `claudeOauthToken` / `anthropicApiKey` — which the
+    // checkpoint's SECRET_ANSWER_KEY_RE strips on every save; apply() reads
+    // them from there. `hasToken` / `hasApiKey` record the fact without the value.
+    ctx.answers.claudeOauthToken = String(oauthToken || "").trim();
+    ctx.answers.anthropicApiKey = String(apiKey || "");
+    ctx.answers.model = { provider, hasToken: !!ctx.answers.claudeOauthToken, hasApiKey: !!ctx.answers.anthropicApiKey, routing };
   },
 
   async apply(ctx) {
-    const a = (ctx.answers && ctx.answers.model) || pull(ctx);
+    const a = pull(ctx);
     if (!a) return;
-    if (a.provider === "subscription") {
+    if (a.provider === "oauth-token") {
+      if (a.oauthToken) appendEnv(ctx.agentRoot, "CLAUDE_CODE_OAUTH_TOKEN", a.oauthToken);
+      // Without a token this degrades to the keychain posture: spawns still
+      // strip API keys and ride whatever login exists; verify reports the truth.
+      appendEnv(ctx.agentRoot, "MAESTRO_PREFER_SUBSCRIPTION_AUTH", "1");
+    } else if (a.provider === "subscription") {
       appendEnv(ctx.agentRoot, "MAESTRO_PREFER_SUBSCRIPTION_AUTH", "1");
     } else if (a.provider === "api-key" && a.apiKey) {
       appendEnv(ctx.agentRoot, "ANTHROPIC_API_KEY", a.apiKey);
     }
+    lockDownEnv(ctx.agentRoot);
     if (a.routing) {
       const dst = join(ctx.agentRoot, "config", "model-routing.yaml");
       const example = join(ctx.maestroRoot, "scaffold", "config", "model-routing.yaml.example");
       if (!existsSync(dst) && existsSync(example)) {
-        try { copyFileSync(example, dst); } catch { /* fail-open */ }
+        try { copyFileSync(example, dst); } catch { /* fail-open: routing is an optimisation, never a gate */ }
       }
     }
   },
 
   async verify(ctx) {
-    const probe = probeClaude(ctx.agentRoot);
+    const probe = (ctx.deps && ctx.deps.probeClaude) || defaultProbeClaude;
+    const r = probe(ctx.agentRoot);
     return {
-      ok: probe.ok,
-      checks: [{ name: probe.name, ok: probe.ok, remedy: probe.remedy }],
+      ok: r.ok,
+      checks: [{ name: r.name, ok: r.ok, remedy: r.remedy, detail: r.detail, auth: r.auth, mode: r.mode }],
     };
   },
 };
 
+/**
+ * Resolve the section's answers. `answers.model` (written by prompt(), or by
+ * an older checkpoint) carries the provider and the routing choice; the
+ * credential values are read from the top-level `claudeOauthToken` /
+ * `anthropicApiKey` answers (or, headless, from CLAUDE_CODE_OAUTH_TOKEN in the
+ * environment) — they are never stored under `answers.model`. An older
+ * checkpoint that still nests `oauthToken` / `apiKey` under `model` is honoured
+ * so a mid-flight resume across the upgrade does not lose its paste. A bare
+ * token implies the oauth-token mode; a bare API key implies api-key; nothing
+ * → null.
+ */
 function pull(ctx) {
   const ans = ctx.answers || {};
-  if (ans.model) return ans.model;
-  if ("provider" in ans || "anthropicApiKey" in ans) {
-    return { provider: ans.provider || (ans.anthropicApiKey ? "api-key" : "subscription"), apiKey: ans.anthropicApiKey || "", routing: !!ans.modelRouting };
+  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) || "");
+  if (m) {
+    const provider = m.provider || (apiKey ? "api-key" : DEFAULT_AUTH_MODE);
+    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);
+    return { provider, oauthToken: provider === "oauth-token" ? envToken : "", apiKey, routing: !!ans.modelRouting };
   }
   return null;
 }