@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/.claude/settings.json

@@ -122,6 +122,15 @@
             "command": "./scripts/hooks/block-mcp-cohort-send.sh"
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./scripts/hooks/pre-write-yaml-validate.mjs"
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -133,6 +142,15 @@
             "command": "./scripts/hooks/post-action-log.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./scripts/hooks/validate-state-yaml.sh"
+          }
+        ]
       }
     ],
     "Stop": [

package/.env.example

@@ -63,7 +63,7 @@ COHORT_AGENT_EMAIL=
 # is in effect and what `claude auth status` reports (presence of a credential,
 # not its validity — a bad token surfaces on the first real spawn).
 #
-#   Option A — subscription OAuth token  ← THE FLEET DEFAULT (seat machines)
+#   Option A — subscription OAuth token  (NOT the fleet posture — see Option C)
 #     On ANY machine where you are logged in to Claude Code, run
 #         claude setup-token
 #     and paste the long-lived token below, together with
@@ -72,25 +72,38 @@ COHORT_AGENT_EMAIL=
 #     keychain login is NOT relied on because it expires headlessly. The token is
 #     per seat; mint a fresh one with the same command when it is rejected.
 #     Headless setup reads it from the environment: CLAUDE_CODE_OAUTH_TOKEN=… maestro setup --headless
+#     It still RUNS, but it has no per-agent ceiling and no central spend
+#     visibility: do NOT provision a new agent seat on it (gate G4).
 CLAUDE_CODE_OAUTH_TOKEN=
 
 #   Option B — keychain login on this machine (interactive / dev boxes only)
 #     `claude login` here, leave CLAUDE_CODE_OAUTH_TOKEN and ANTHROPIC_API_KEY
 #     empty, set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1. Doctor warns: the login
-#     expires headlessly and a seat machine should hold the token instead.
+#     expires headlessly and an agent seat belongs on Option C.
 #
 # Set to 1 for Option A and Option B: every claude spawn strips
 # ANTHROPIC_API_KEY from its env so claude rides the subscription (token or
 # keychain) — routine cadence ticks then cost zero API credits.
 MAESTRO_PREFER_SUBSCRIPTION_AUTH=
 
-#   Option C — API key (pay-per-token)
-#     Set ANTHROPIC_API_KEY to a valid sk-ant-api03-... key and leave the two
-#     above empty. Get one: https://console.anthropic.com/settings/keys
+#   Option C — API key (pay-per-token)  ← THE FLEET POSTURE (agent seats)
+#     Set ANTHROPIC_API_KEY to a valid sk-ant-api03-... key created INSIDE a
+#     Console workspace with a monthly spend cap, one workspace per agent, and
+#     leave the two above empty. Get one:
+#     https://console.anthropic.com/settings/keys
 #     Doctor validates it against api.anthropic.com on every run; an invalid
 #     key cascades 401s through every sub-session spawn.
+#     Runbook: docs/guides/billing-console-keys.md
 ANTHROPIC_API_KEY=
 
+# OPTIONAL — Arm the G4 guard. `maestro doctor` and `maestro seat-auth` WARN on
+# a seat still using subscription OAuth (and on a seat carrying both rails,
+# which is ambiguous about where its spend lands). Set this to 1 and those
+# warnings become failures — do that once the fleet has migrated, so a seat that
+# regresses to a subscription token announces itself. Never fails an
+# engine=cohort seat that holds no Anthropic credential: that is its posture.
+MAESTRO_REQUIRE_CONSOLE_KEY=
+
 # OPTIONAL — Supplemental model access (GPT-4, embeddings)
 # Get your key: https://platform.openai.com/api-keys
 # Subscription: OpenAI API plan (pay-per-token)

package/README.md

@@ -161,6 +161,7 @@ Verifies the agent installation end-to-end. Checks include:
 - **Config:** `config/environment.yaml`, `config/contacts.yaml`, `config/priorities.yaml`, `config/sla-defaults.yaml`.
 - **State:** `state/dashboards/executive-summary.yaml`, `state/queues/action-stack.yaml`, `knowledge/decisions/decision-schema.yaml`.
 - **Environment:** `.env` file with `ANTHROPIC_API_KEY` (required), `SLACK_USER_TOKEN`, `GMAIL_APP_PASSWORD` (optional).
+- **Billing rail (G4):** which Claude rail this seat is on — `api-key` (the fleet posture: a per-agent Console key in a capped workspace), `subscription`, `both` (ambiguous, flagged loudly) or `neither`. Variable **names** only; no credential value is ever printed. A warning today; `MAESTRO_REQUIRE_CONSOLE_KEY=1` turns it into a failure once the fleet has migrated. `maestro seat-auth --row` prints the paste-able inventory row and `maestro seat-auth --fleet` the template it pastes into — see [billing: Console API keys](docs/guides/billing-console-keys.md).
 - **Dependencies:** `node_modules` installed, Claude CLI available, jq available, emergency-stop script present.
 
 Doctor exits non-zero when issues are found and prints actionable remediation (most commonly: `npx @cohortapp/agent-sdk upgrade`). Doctor also verifies the collective-memory wiring (see below).

package/bin/maestro.mjs

@@ -37,6 +37,7 @@ import { runAudit, applyFixes, buildAttestation } from "../lib/security/audit-en
 import { selectProvider } from "../lib/secrets/providers.mjs";
 import { syncSecrets, rotateSecret, makeBroker, auditLogPath } from "../lib/secrets/broker.mjs";
 import { applyBrandEnvCompat } from "../lib/env-compat.mjs";
+import { buildIgnoredDriftReport, formatIgnoredLine, IGNORED_DRIFT_REL } from "../lib/upgrade/ignored-drift.mjs";
 
 // Fleet back-compat FIRST: bridge NEOLITH_* ⇄ COHORT_* env names before any
 // env-first resolution below — installed hosts still export the legacy names.
@@ -1249,6 +1250,8 @@ Per-file behaviour:
   const counts = { added: 0, updated: 0, same: 0, ignored: 0, preserved: 0, mergeKept: 0, forced: 0, pruned: 0, pruneKept: 0 };
   const preservedFiles = [];
   const ignoredFiles = [];
+  // repoRel → the upstream file the protection kept out (null when upstream ships nothing there): the drift report's input.
+  const ignoredSources = new Map();
   const prunedFiles = [];
   const pruneKeptFiles = [];
   // What upstream ships right now — becomes this machine's provenance record.
@@ -1276,6 +1279,7 @@ Per-file behaviour:
       if (isIgnored) {
         counts.ignored++;
         ignoredFiles.push(repoRel);
+        ignoredSources.set(repoRel, srcFile);
         if (flags.verbose) console.log(`  · ${repoRel} (ignored via .maestroignore)`);
         continue;
       }
@@ -1414,6 +1418,7 @@ Per-file behaviour:
         if (matchesIgnore(repoRel, ignorePatterns)) {
           counts.ignored++;
           ignoredFiles.push(repoRel);
+          ignoredSources.set(repoRel, null);
           if (flags.verbose) console.log(`  · ${repoRel} (orphan, ignored via .maestroignore)`);
           continue;
         }
@@ -1504,6 +1509,7 @@ Per-file behaviour:
       if (matchesIgnore(repoRel, ignorePatterns)) {
         counts.ignored++;
         ignoredFiles.push(repoRel);
+        ignoredSources.set(repoRel, src);
         if (flags.verbose) console.log(`  · ${repoRel} (ignored via .maestroignore)`);
         continue;
       }
@@ -1596,6 +1602,26 @@ Per-file behaviour:
   if (counts.updated)   ok(`${counts.updated} updated (vendored, no local edits)`);
   if (counts.same)      console.log(`  = ${counts.same} already up-to-date`);
   if (counts.ignored)   console.log(`  · ${counts.ignored} ignored (.maestroignore protected)`);
+  // A protected file is a fork the operator owns; "N ignored" hid how far
+  // upstream had moved under each one. Say it per file, and keep the answer
+  // in .maestro/ignored-drift.json for doctor and the next reader.
+  let ignoredDrift = null;
+  if (ignoredFiles.length) {
+    const readOrNull = (p) => { try { return p && existsSync(p) ? readFileSync(p, "utf8") : null; } catch { return null; } };
+    ignoredDrift = buildIgnoredDriftReport(
+      [...new Set(ignoredFiles)].sort().map((repoRel) => ({ path: repoRel, local: readOrNull(join(cwd, repoRel)), upstream: readOrNull(ignoredSources.get(repoRel)) })),
+      { sdkVersion: readFrameworkVersion(), at: new Date().toISOString() },
+    );
+    for (const f of ignoredDrift.files) console.log(formatIgnoredLine(f));
+    if (ignoredDrift.counts.drifts) warn(`${ignoredDrift.counts.drifts} protected file(s) drift from upstream — every upstream fix to those paths stops here until you port it (diff each against node_modules/@cohortapp/agent-sdk/<path>)`);
+    if (!flags.dryRun) {
+      try {
+        const out = join(cwd, IGNORED_DRIFT_REL);
+        mkdirSync(dirname(out), { recursive: true });
+        writeFileSync(out, JSON.stringify(ignoredDrift, null, 2) + "\n");
+      } catch (e) { warn(`could not write ${IGNORED_DRIFT_REL}: ${e && e.message ? e.message : e}`); }
+    }
+  }
   if (counts.mergeKept) console.log(`  ~ ${counts.mergeKept} merge-mode kept (agents/ custom files preserved)`);
   if (counts.preserved) warn(`${counts.preserved} preserved (local edits — kept your version)`);
   if (counts.forced)    warn(`${counts.forced} force-overwritten (backups in .maestro/backup/)`);
@@ -3341,6 +3367,38 @@ async function globalSetup(args = []) {
     ok("global hooks already present (no change)");
   }
 
+  // 1b) Per-seat .claude/settings.json: the state-YAML gate hooks (PreToolUse on
+  //     Write|Edit, PostToolUse on Bash|Write|Edit). These belong in the SEAT file,
+  //     not ~/.claude — their commands are seat-relative and only mean anything
+  //     inside an agent repo. A hand edit there does not survive a fresh checkout
+  //     or an upgrade, which is why the scaffold copy carries them for new seats
+  //     and this merge carries them onto existing ones (upgrade runs global-setup
+  //     as a post-step). Deep-merged, idempotent, backed up before write.
+  {
+    const seatSettingsPath = join(cwd, ".claude", "settings.json");
+    let seat = {};
+    if (existsSync(seatSettingsPath)) {
+      try { seat = JSON.parse(readFileSync(seatSettingsPath, "utf-8")); } catch { seat = null; }
+    }
+    if (seat === null) {
+      warn(`${seatSettingsPath} is not valid JSON — state-YAML gate hooks not merged (repair it, then re-run global-setup)`);
+    } else {
+      const merged = gc.mergeStateYamlGateHooks(seat);
+      if (merged.added.length > 0) {
+        if (!dryRun) {
+          mkdirSync(dirname(seatSettingsPath), { recursive: true });
+          if (existsSync(seatSettingsPath)) {
+            try { copyFileSync(seatSettingsPath, `${seatSettingsPath}.backup.${tsStamp()}`); } catch { /* */ }
+          }
+          writeFileSync(seatSettingsPath, JSON.stringify(merged.settings, null, 2) + "\n");
+        }
+        ok(`${dryRun ? "[dry-run] " : ""}seat hooks added to .claude/settings.json: ${merged.added.join(", ")}`);
+      } else {
+        ok("seat state-YAML gate hooks already present (no change)");
+      }
+    }
+  }
+
   // 2) global CLAUDE.md directive (only our delimited block is touched).
   let mdContent = "";
   if (existsSync(claudeMdPath)) { try { mdContent = readFileSync(claudeMdPath, "utf-8"); } catch { /* */ } }
@@ -3806,9 +3864,11 @@ switch (command) {
   case "who-owns": case "who": await whoOwnsCmd(args); break;
   case "inbox": process.exitCode = await (await import("../lib/cli/inbox.mjs")).runInbox(args); break;
   case "session-ack": process.exitCode = await (await import("../lib/cli/session-ack.mjs")).runSessionAck(args); break;
+  case "seat-auth": process.exitCode = await (await import("../lib/cli/seat-auth.mjs")).runSeatAuth(args); break;
   case "session": { const r = await (await import("../lib/cli/session.mjs")).run(args); process.exitCode = r.code; break; }
   case "board": await (await import("../lib/cli/board.mjs")).boardCmd(args); break;
   case "design": await (await import("../lib/cli/design.mjs")).designCmd(args); break;
+  case "run": process.exitCode = await (await import("../lib/engine/cli.mjs")).runFromProcess(args); break;
   case "init":
   case "update-init":
   case "init-update":
@@ -3836,9 +3896,11 @@ Usage:
   npx @cohortapp/agent-sdk who-owns <scope>           Who owns a scope / escalate-to / reports (org context, zero-LLM)
   npx @cohortapp/agent-sdk inbox list|show|claim|reply|done|defer   The main session's inbox (JSON; shares the daemon's markers)
   npx @cohortapp/agent-sdk session-ack <tickId>       Ack a cadence tick handed to the main session
+  npx @cohortapp/agent-sdk seat-auth [--row|--fleet]  Which Claude billing rail this seat is on (G4) — variable NAMES only, never a value
   npx @cohortapp/agent-sdk session <cmd>              Front-door session: status|attach|start|stop|restart|spawn|peers|handoffs|ack
   npx @cohortapp/agent-sdk board mine|track|claim|complete   Your work across every board (maestro board --help)
   npx @cohortapp/agent-sdk design sync [--out <dir>]  Pull the brand foundation → DESIGN.md + PRODUCT.md
+  npx @cohortapp/agent-sdk run -p "<prompt>" [flags]  Cohort Engine, headless (cohort run --help)
 
 Upgrade flags:
   --dry-run, -n          Preview changes without writing

package/docs/guides/billing-console-keys.md

@@ -65,6 +65,7 @@ make per-agent spend attribution and revocation possible).
 
 ```sh
 maestro doctor      # validates ANTHROPIC_API_KEY against api.anthropic.com
+maestro seat-auth   # which rail this seat is on, by variable NAME (see below)
 ```
 
 After the cost-telemetry work (roadmap item 0.3) lands, `maestro doctor` also
@@ -72,6 +73,65 @@ turns RED when sessions have run but recorded spend is $0, and a nightly digest
 reconciles the local ledger against the Admin Cost API. Until then, confirm spend
 is accruing in the Console workspace view for a canary agent.
 
+## The tooling: `maestro seat-auth` (G4)
+
+A seat can state, about itself, which rail it is on — and the answer is a
+**verdict over variable names**, never a value. Nothing here prints, logs or
+stores a credential, not even truncated.
+
+| Verdict        | Meaning                                                                | Doctor level                     |
+| -------------- | ---------------------------------------------------------------------- | -------------------------------- |
+| `api-key`      | `ANTHROPIC_API_KEY` only — the fleet posture                           | ok                               |
+| `subscription` | `MAESTRO_PREFER_SUBSCRIPTION_AUTH` and/or `CLAUDE_CODE_OAUTH_TOKEN`    | warn (fail when armed, below)    |
+| `both`         | a Console key **and** a subscription credential on the same seat       | warn (fail when armed) — loud    |
+| `neither`      | no Claude credential at all                                            | fail — except on an engine-cohort seat, where it is expected |
+
+**`both` is its own verdict and is worth flagging loudly.** It is not "half
+migrated": it is ambiguous. The runtime adapter blanks `ANTHROPIC_API_KEY` on a
+seat that `subscriptionAuth()` calls true (`lib/runtime/adapter.mjs`), so the
+subscription rail wins the lanes that go through the adapter while a lane that
+passes the environment straight through may use the key. Spend then lands in
+two places and neither is authoritative. Migrate, do not stack.
+
+```sh
+maestro seat-auth            # the verdict, the names present, the remediation
+maestro seat-auth --json     # the same, machine-readable
+maestro seat-auth --row      # ONE markdown row to paste into the fleet inventory
+maestro seat-auth --fleet    # the inventory template, one row per org member
+```
+
+The same verdict appears as a row in `maestro doctor`, so an operator who runs
+only doctor still sees it.
+
+### The fleet inventory
+
+A seat's environment lives on the seat's own machine. There is no remote
+inventory mechanism and this tooling does not invent one. So the fleet report is
+a **template plus paste-able rows**: run `maestro seat-auth --fleet` once (it
+pre-fills one row per member from the org directory), then on each machine run
+`maestro seat-auth --row` and paste the line over that seat's row. The measured
+columns — seat, agent id, machine, verdict, which variable names are present,
+when it was checked — fill themselves; the Console-side columns (account,
+workspace, cap, key id last 4, revocation date) stay blank, because only a human
+with Console access knows them and a tool that guessed them would teach people
+to trust a guess.
+
+### Arming the guard
+
+The check **warns** by default, deliberately: seats are live, and a check that
+failed on the day it shipped would break the seats it exists to move. Once every
+row of the inventory reads `api-key`, set
+
+```sh
+MAESTRO_REQUIRE_CONSOLE_KEY=1
+```
+
+in each seat's `.env` (or the fleet's environment). `subscription` and `both`
+then FAIL `maestro doctor` and exit 1 from `maestro seat-auth`, so a seat that
+regresses to a subscription token announces itself instead of quietly billing a
+personal plan. Record the date it was set fleet-wide — that, plus the last token
+revocation, is what closes this gate.
+
 ## What is automated vs human
 
 maestro cannot create Console workspaces or keys for you — that requires a human

package/docs/guides/front-door-session.md

@@ -177,15 +177,60 @@ summary and in `.maestro/upgrade-result.json` `{from, to, at, steps}`:
 | `globalInstall` | `npm i -g @cohortapp/agent-sdk@<this version>` so `maestro` / `cohort` / `cohort-mcp` on PATH match the agent dir (`MAESTRO_SKIP_GLOBAL_INSTALL=1` skips) |
 | `verify` | the `maestro upgrade --verify` report, below |
 
-autoupdate then kickstarts the daemon and health-gates it: the daemon
-process must be alive with a fresh `org-mesh connected` / `[daemon] Running`
-line, and — when a `-session` plist was generated — the session label must be
-in `launchctl list` with a live supervisor process. A missing session is
-logged as `reconcile-failed` and does **not** roll back (the daemon's
-`--print` lane is the front door meanwhile; doctor says what to do). Every
-launchd and `pgrep` question is scoped to *this* agent (`ai.maestro.<first>-*`
-and its own agent dir), so two seats on one Mac never gate on — or restart —
-each other.
+autoupdate then kickstarts the daemon and health-gates it. **The gate means
+health, not "running"** — it used to be "pid alive + a fresh `org-mesh
+connected` line", and a crash-looping daemon satisfies both (launchd respawns
+it, and every respawn prints the line again): one seat logged `up to date
+(2.17.0)` hourly for six days, 2026-09-15..21, while its daemon died ~25 s
+after every start, and the org saw no presence beat from it for ten days. The
+daemon now has to answer all of:
+
+- **pid stability** — the daemon pid set is unchanged across two samples 90 s
+  apart and every pid's `ps etime` is ≥ 90 s (3× the observed crash
+  interval, well inside the hourly cadence; `MAESTRO_AUTOUPDATE_STABLE_S`);
+- **no fatal line** in its own log since the restart (`[DAEMON]
+  uncaughtException:`, `[daemon] Fatal:`, `[wrapper] FATAL:`,
+  `ERR_MODULE_NOT_FOUND`) — the log has no per-line timestamps and the
+  wrapper names the file for the day the process started, so "since the
+  restart" is a line offset taken before the kickstart;
+- **an org-acknowledged beat** — `state/org/last-beat.json` `{at, ok, code?}`,
+  which `lib/org/mesh.mjs` overwrites on every presence beat (`ok:true` only
+  when the org answered 2xx), must say `ok:true`, post-date the daemon's start
+  and be younger than 5 min (`MAESTRO_AUTOUPDATE_BEAT_FRESH_S`, the same bar
+  after which hq's presence view calls a seat offline). Skipped only for a
+  seat `config/org.yaml` does not enrol.
+
+When a `-session` plist was generated, the session label must also be loaded
+with a live supervisor process; a missing session is logged as
+`reconcile-failed` and does **not** roll back (the daemon's `--print` lane is
+the front door meanwhile; doctor says what to do). Every launchd and `pgrep`
+question is scoped to *this* agent (`ai.maestro.<first>-*` and its own agent
+dir), so two seats on one Mac never gate on — or restart — each other.
+
+**Being up to date is not an exemption.** When the installed version is
+already `@latest` the run still runs the same gate on the current version.
+An unhealthy daemon is logged loudly, recorded in `state/autoupdate/last.json`
+as `{ok:false, healthy:false, reason:"unhealthy-current: …"}` (the beat
+carries it as `machine.upgrade`), and announced once per episode through
+`state/session/upgrade-notice.json` `{from:CUR, to:CUR, healthy:false,
+reason}` so the front-door session's feed surfaces it as a `daemon-unhealthy`
+directive — a distinct action from `upgrade-available`, so no session restarts
+on a health report. Nothing is rolled back (there is no upgrade to undo), an
+`unhealthy-current` entry never holds a later release, and a recovery restores
+`last.json`.
+
+**A stale daemon is reconciled on the same path.** A hand-run `maestro
+upgrade` installs the package and reconciles the seat but never restarts the
+daemon (its verify row says the new version "takes effect when autoupdate
+kickstarts it"). When `state/dashboards/daemon-health.yaml` shows the live
+daemon started on a different `sdk_version` than the installed one, the hourly
+run kickstarts it, waits, and runs the gate exactly as after an automatic
+install — a healthy outcome writes the same `{from:<old>, to:<new>}` notice, so
+the session restarts itself onto the new code when idle. The fatal scan starts
+at the running daemon's own boot marker (`[DAEMON] boot pid=<pid>`, the first
+line `maestro-daemon.mjs` prints), never at the top of the shared start-day
+log, so a one-off crash earlier the same day that launchd already recovered
+from is history, not health.
 
 An unhealthy daemon **rolls back**: the previous SDK is reinstalled into the
 agent dir and *that* package's `upgrade` runs, the global install is put back

package/docs/guides/mac-mini.md

@@ -32,20 +32,17 @@ npm i -g @cohortapp/agent-sdk        # GLOBAL on purpose: every Claude Code sess
                                      # this seat needs `maestro` + `cohort-mcp` on PATH
 ```
 
-## 3. The Claude token — one auth story for the whole seat
+## 3. The Claude credential — one Console API key per seat
 
 Every `claude` the seat runs (the daemon's `--print` lane, the main session,
-cadence sub-sessions) authenticates with a **long-lived subscription OAuth
-token**, never the interactive keychain login (which expires headlessly and
-has stranded seats before). Mint it on **any** machine where you are logged
-in to Claude Code with the Max subscription — your laptop is fine:
+cadence sub-sessions) authenticates with an **Anthropic Console API key**
+created for this agent, in a Console workspace with its own spend limit. Do
+not use a Claude subscription on an agent seat: neither a `claude setup-token`
+token nor the keychain login (which also expires headlessly). Creating the
+workspace and the key: [billing-console-keys.md](billing-console-keys.md).
 
-```bash
-claude setup-token          # prints one token; copy it
-```
-
-Keep it in your clipboard / password manager for step 5. It is per seat: mint
-a fresh one whenever `cohort doctor` reports the token as rejected.
+Keep the key in your password manager for step 5. It is per seat: rotate it in
+the Console whenever `cohort doctor` reports it as rejected.
 
 ## 4. Create the agent repo
 
@@ -59,7 +56,7 @@ including `.mcp.json`, which exposes the `cohort-mcp` org tool surface to
 interactive Claude sessions, and the PreToolUse hooks that keep its outbound
 writes on the CLI lane).
 
-## 5. Enroll against `https://os.cohortapp.com` — and paste the token
+## 5. Enroll against `https://os.cohortapp.com` — and paste the API key
 
 Two lanes — pick one:
 
@@ -68,13 +65,13 @@ Two lanes — pick one:
 
   ```bash
   export COHORT_API_KEY=nlk_…  COHORT_ORG_ID=<org-ID>  COHORT_AGENT_ID=<member-slug>
-  cohort setup                       # the model section (order 30) asks for the token from step 3
-  # headless / one-paste bootstrap: the token comes from the environment instead of a prompt
-  CLAUDE_CODE_OAUTH_TOKEN=<token> cohort setup --headless
+  cohort setup                       # the model section (order 30) asks for the API key from step 3
+  # headless / one-paste bootstrap: the key comes from the environment instead of a prompt
+  ANTHROPIC_API_KEY=<key> cohort setup --headless
   ```
 
-  Either way `.env` ends up with `CLAUDE_CODE_OAUTH_TOKEN` +
-  `MAESTRO_PREFER_SUBSCRIPTION_AUTH=1`, mode 600. No `ANTHROPIC_API_KEY`.
+  Either way `.env` ends up with `ANTHROPIC_API_KEY`, mode 600, and no
+  `CLAUDE_CODE_OAUTH_TOKEN` or `MAESTRO_PREFER_SUBSCRIPTION_AUTH`.
 
   > **`COHORT_ORG_ID` is the org's ID, not its slug** — this line said
   > `<org-slug>` and that would 401 every call. The value rides as `x-org-id`
@@ -98,7 +95,7 @@ Two lanes — pick one:
 
 | Order | Section | What it does |
 | --- | --- | --- |
-| 30 | `model` | Claude auth — **`oauth-token` by default**: paste the `claude setup-token` output; writes `CLAUDE_CODE_OAUTH_TOKEN` + `MAESTRO_PREFER_SUBSCRIPTION_AUTH=1`, chmods `.env` 600 |
+| 30 | `model` | Claude auth — **`api-key` by default**: paste the agent's Console API key; writes `ANTHROPIC_API_KEY`, chmods `.env` 600 |
 | 75 | `org` | endpoint + token (the enrollment SoT) |
 | 76 | `messaging` | messaging.read/write + calling.write scopes, home channels |
 | 77 | `orgmail` | **workspace mailbox** — writes `config/orgmail.yaml` |
@@ -144,13 +141,11 @@ cohort doctor
 
 All green includes, in this order:
 
-- **Claude auth** — the mode in effect (`subscription OAuth token` is the
-  expected line) and what `claude auth status` reports. The CLI reports that
-  a credential is PRESENT — it answers "logged in" for any token value — so a
-  bad token is only caught by the first real spawn (`logs/sessions`, and the
-  beat flips to `relogin_required`); a `claude -p "ping"` after doctor is the
-  cheap way to prove it. "keychain login"
-  or "nothing configured" means step 3/5 was skipped.
+- **Claude auth** — the mode in effect (`ANTHROPIC_API_KEY` is the expected
+  line for an agent seat). In API-key mode the probe makes a real call, so a
+  rejected key shows here. A subscription line (OAuth token or keychain login)
+  on an agent seat means it is still on the pre-migration setup — see step 3.
+  "nothing configured" means step 3/5 was skipped.
 - **Cohort sources** — for each of `base` / `orgId` / `token` / `agentId`,
   which file won (`config/org.yaml` beats the environment beats `.env`) and
   every value that lost. If you edited `.env` and nothing changed, this line

package/docs/guides/setup-wizard.md

@@ -52,7 +52,7 @@ core runner.
 |---------|-------|-------------|
 | `identity` | 10 | Agent name and title, the **function × altitude** archetype, and the principal. Writes `config/agent.json`. |
 | `company` | 20 | Company-context interview — name, website, industry, one-line + detailed overview, stage/size, footprint, regulation, top priorities, and key people. Writes `config/company.json`. |
-| `model` | 30 | Claude auth. Three modes, **`oauth-token` the default**: run `claude setup-token` on any logged-in machine and paste the result (headless: `CLAUDE_CODE_OAUTH_TOKEN` in the environment) → `.env` gets `CLAUDE_CODE_OAUTH_TOKEN` + `MAESTRO_PREFER_SUBSCRIPTION_AUTH=1`; or this machine's keychain login; or a pasted Anthropic API key. Chmods `.env` 600. |
+| `model` | 30 | Claude auth. Three modes, **`api-key` the default**: paste an Anthropic Console API key created for this agent in a Console workspace with a spend limit (headless: `ANTHROPIC_API_KEY` in the environment) → `.env` gets `ANTHROPIC_API_KEY`. Setup runbook: [billing-console-keys.md](billing-console-keys.md). The other two modes — a `claude setup-token` subscription token, or this machine's keychain login — are for a person's own development machine, not an agent seat. Chmods `.env` 600. |
 | `comms` | 45 | Wires each messaging channel — Slack, Gmail, SMS, WhatsApp, Telegram, voice — into `.env`/gate files and verifies inbound. |
 | `tools` | 50 | Selects which channels and MCP servers the agent should run. |
 | `operating-model` | 60 | Deterministically generates the operating charter, a seeded WBS backlog (≥5 open items), 40–60 sub-agents + skills + workflows + MCP servers + event-routing, archetype cadences, the autonomy policy, the communication profile, and the launchd plists. |

package/docs/runbooks/fleet-rollout.md

@@ -0,0 +1,156 @@
+# Fleet rollout — publish one version, then prove the fleet took it
+
+`scripts/fleet/rollout.mjs` is the whole propagation path in one command.
+
+```
+node scripts/fleet/rollout.mjs [--dry-run] [--verify-only]
+                               [--deadline <min>] [--interval <s>]
+                               [--seat-window <min>] [--agent-root <path>] [--json]
+```
+
+There is exactly one way an SDK change reaches the fleet: it is published to
+npm, and each seat's hourly `scripts/local-triggers/autoupdate.sh` installs
+`@latest`. Nothing is pushed to a machine. **This tool never ssh's anywhere**,
+and it takes **no credential as an argument or environment variable** — npm auth
+comes from the operator's own `npm login`, org auth from the agent config the
+rest of `lib/org` reads.
+
+Both promises are enforced **twice**, because a source-reading test only catches
+the shapes it was taught — `execSync("ssh …")` and `deps.exec(cmd, [])` both
+slipped past the first version of it. `runCommand()` refuses any command but
+`npm` and `git` at runtime, on the value; `parseArgs()` drops everything after
+the first `=` before an error string is built, so no branch can echo a
+credential back into your scrollback. The structural tests in
+`scripts/fleet/rollout.test.mjs` sit on top, pinning the import surface of
+`node:child_process` so nothing can reach a process without that guarded seam.
+
+## The three stages
+
+**1 — pre-flight.** Refuses the publish unless all of:
+
+| gate | why it is here |
+| --- | --- |
+| `npm whoami` succeeds | a publish with no auth fails halfway and leaves you guessing |
+| local version > registry `@latest` | the registry, not a changelog, is the authority on what is published |
+| working tree clean | you can only publish what is committed |
+| `v<version>` exists locally **and** on the remote | published bytes stay findable |
+| `npm run check` passes | … |
+| `npm test` passes | … on the bytes about to be published |
+
+The last two are **re-run**, never read from a log: a green run from an hour ago
+is a fact about a different tree. They are skipped only when a cheaper gate has
+already blocked the publish — and the run says so in that case, so "pre-flight
+passed" can never quietly mean "was not run".
+
+**2 — publish.** `npm publish`, then poll the registry until `@latest` **is** the
+new version. A 404 or a stale answer in the first seconds is **read lag, not
+failure** — that has been misread as a failed publish before, so the poll
+retries and only fails when its attempts run out.
+
+**3 — verify propagation.** Poll the org directory — hq's server-stamped
+presence-beat derivation, the same signal the human fleet page paints — and
+print a per-seat table every round until every seat reports the new version or
+the deadline passes. The run exits non-zero naming exactly which seats are
+behind.
+
+A **seat** is an AI colleague with a server-stamped beat inside `--seat-window`
+(default 30 min). An agent with no machine (responder-only) takes no SDK version
+and is counted separately, never as "behind".
+
+## Exit codes
+
+| code | meaning |
+| --- | --- |
+| 0 | published (or already published) **and** every seat reports the version |
+| 1 | pre-flight refusal — nothing was published, nothing changed |
+| 2 | publish failed, or the registry never served the new version |
+| 3 | deadline passed with seats behind or unverifiable |
+
+### `3` is three different things — do not gate on the exit code yet
+
+**`rollout` cannot be used as a success gate today.** Every seat classifies as
+`unverifiable` (see below), an unverified seat is deliberately not counted as
+done, so a flawless publish onto a fully propagated fleet **still exits 3**.
+A cron, a CI step or a wrapper script that treats `0` as "shipped" will never
+fire; one that treats `3` as "seats are behind" will page you for nothing.
+
+Branch on `--json` instead. It prints one object — `{code, reason, note,
+summary}` — whose `reason` separates the cases the exit code merges:
+
+| `reason` | meaning |
+| --- | --- |
+| `verified` | every seat reports the target version (`code` 0) |
+| `behind` | at least one seat is **provably** on an older version |
+| `unverifiable` | no seat is known to be behind; nothing available can prove any seat is current |
+| `empty-fleet` | no beating seats were found — never treated as done |
+| `no-fleet-read` | the org read never succeeded; says nothing about the fleet |
+
+`unverifiable` becomes `verified` the moment the one-line hq change below lands,
+with no change to this script. `propagationOutcome()` is pure and exported, so
+the mapping is pinned by test rather than by this table.
+
+Idempotent: when `@latest` already equals the local version the run prints
+`already published, verifying propagation` and goes straight to stage 3.
+Re-running it is the supported way to watch a rollout land. `--verify-only`
+does stage 3 alone, against any version, without touching npm.
+
+## Today's blocker, and the one honest gap
+
+**npm auth.** `npm whoami` is a 401 on this machine, so stage 1 refuses. Only a
+human can clear it (`npm login` as the publisher). The moment it is cleared,
+this command is the entire rollout.
+
+**`unverifiable` seats.** Stage 3 wants each seat's *running* version. Every seat
+already reports it — the presence beat carries `status.machine.sdkVersion` and
+hq persists it to `AgentStatus.machine` — but **no read an agent can make gives
+it back**: hq's `directory` read (`src/server/rpc/reads.ts#directory`) selects
+five `AgentStatus` columns and `machine` is not among them, and `member.get`
+does not read `AgentStatus` at all. So every seat currently reads `unknown` and
+the run exits 3.
+
+That is deliberate. The tool does **not** count a beating seat as up to date:
+treating "running" as "healthy" is exactly what let one seat sit six days behind
+while its own log said "up to date" every hour. It proves liveness, says plainly
+that it cannot prove the version, and fails.
+
+**To close it (hq side, one lane):** add `machine: true` to the `agentStatus`
+select in `directory()` and echo `sdkVersion` (only that key — `machine` is an
+open record and the rest is seat telemetry) into the per-member `status` object,
+with a test pinning the field. `seatVersion()` in the script already reads
+`status.machine.sdkVersion` first and will light up with no change here.
+
+Until it does, the run says so in words on every all-unverifiable finish — that
+exit 3 does **not** mean a seat is behind — rather than leaving the reader to
+infer it from a count.
+
+## One wrinkle: the gates dirty the tree
+
+`npm test` appends to a tracked runtime ledger (`.claude-flow/policy/state.json`),
+so a second run in a row would refuse on a file the *first* run wrote. The
+clean-tree gate is not relaxed for it — the run names those paths and tells you
+to `git checkout --` them. The gate order also means a first run is unaffected:
+cleanliness is read before the gates run.
+
+## Reading a round
+
+```
+Fleet vs 2.18.1  (round 2 · 46s elapsed)
+SEAT            ID    BEAT  REPORTS  VERDICT
+--------------  ----  ----  -------  ------------
+<name>          A0xx  6s    2.18.1   current
+<name>          A0xx  15s   2.17.0   stale
+<name>          A0xx  20s   unknown  unverifiable
+15 seat(s): 1 current · 1 stale · 13 unverifiable  (+32 agent(s) with no beating machine — not rollout targets)
+```
+
+`BEAT` is the age of the seat's last **server-stamped** beat — the only honest
+liveness signal there is. `REPORTS` is what that seat says it is running.
+
+## What the suite covers
+
+`npm test` discovers every `*.test.mjs` under `lib/`, `scripts/`, `bin/`,
+`services/` and `test/` — there is no list to append to. `npm run test:list`
+asks the same runner what it found and prints it without running anything; it
+used to be a hand-typed enumeration that had drifted to 46 of 82 files, and
+`scripts/ci/run-tests.test.mjs` now fails the build if any `package.json` script
+starts enumerating the suite again.