@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/cli/seat-auth.mjs

@@ -0,0 +1,463 @@
+/**
+ * lib/cli/seat-auth.mjs — G4: which Claude billing rail is this seat on, and
+ * is that the fleet posture?
+ *
+ * The fleet posture is a **per-agent Console API key in a workspace with a hard
+ * spend cap** (`docs/guides/billing-console-keys.md`). Subscription OAuth — the
+ * `MAESTRO_PREFER_SUBSCRIPTION_AUTH` flag, a `CLAUDE_CODE_OAUTH_TOKEN`, or the
+ * keychain login behind them — still RUNS, which is exactly why a seat can sit
+ * on it for months with nothing complaining. G4 is the gate that ends that, and
+ * this module is the tooling half: a verdict a seat can state about itself, an
+ * inventory row an operator can paste, and a fleet template to paste it into.
+ *
+ * Three deliberate constraints, each of which is a test:
+ *
+ * 1. **Names, never values.** Every verdict reports which variable NAMES are
+ *    present. No value — masked, truncated or otherwise — ever reaches a
+ *    message, a row or the JSON. A migration tool that prints a fragment of the
+ *    credential it is migrating has created a second copy of the problem.
+ * 2. **Both-set is its own verdict.** A seat carrying a Console key AND a
+ *    subscription credential 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 it while lanes that pass
+ *    the environment straight through may use the key. Spend then lands in two
+ *    places and neither is authoritative. It is called out loudly.
+ * 3. **Warn today, fail when told.** Seats are LIVE. A check that fails by
+ *    default would turn every doctor run red the hour it ships and break the
+ *    very seats it is trying to move. So `subscription` and `both` are `warn`
+ *    until `MAESTRO_REQUIRE_CONSOLE_KEY=1` (documented in `.env.example` and the
+ *    runbook) flips them to `fail`. `neither` is a failure regardless on a
+ *    `claude` seat — a seat with no credential at all is broken, not lax — and
+ *    is the EXPECTED state on an `engine=cohort` seat, which holds no Anthropic
+ *    credential by design.
+ *
+ * Everything here is pure except `runSeatAuth`, whose every edge (the seat's
+ * `.env`, the hostname, the clock, the org directory) is injectable.
+ *
+ * What this module deliberately does NOT do: reach another machine. A seat's
+ * environment lives on the seat's own box; there is no remote inventory
+ * mechanism to invent. The fleet report is a TEMPLATE plus paste-able rows,
+ * which is the honest shape of the job.
+ *
+ * @module lib/cli/seat-auth
+ */
+
+"use strict";
+
+import { hostname as osHostname } from "node:os";
+
+/** The three variables that decide the rail. Order is the report order. */
+export const SEAT_AUTH_VARS = Object.freeze([
+  "ANTHROPIC_API_KEY",
+  "MAESTRO_PREFER_SUBSCRIPTION_AUTH",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+]);
+
+/** Set this to 1/true/yes to turn the G4 warning into a doctor failure. */
+export const REQUIRE_CONSOLE_KEY_VAR = "MAESTRO_REQUIRE_CONSOLE_KEY";
+
+/** The operator runbook every remedy points at. */
+export const RUNBOOK = "docs/guides/billing-console-keys.md";
+
+/**
+ * The one remedy every auth row gives (CF-13). Defined here — the G4 module —
+ * and re-exported by `lib/cli/doctor-checks.mjs` so the two surfaces cannot
+ * drift into saying different things.
+ */
+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";
+
+const TRUTHY = /^(1|true|yes)$/i;
+
+/** Non-empty after trimming, for any value shape an env bag can hold. */
+function nonEmpty(v) {
+  return v !== undefined && v !== null && String(v).trim() !== "";
+}
+
+/**
+ * Is the G4 guard armed in this environment?
+ * @param {Record<string,string>} [env]
+ * @returns {boolean}
+ */
+export function enforcementEnabled(env = {}) {
+  return TRUTHY.test(String((env && env[REQUIRE_CONSOLE_KEY_VAR]) || "").trim());
+}
+
+/** `ANTHROPIC_API_KEY (.env)` when the caller knows where it came from. */
+function labelled(name, sources) {
+  const src = sources && sources[name];
+  return src ? `${name} (${src})` : name;
+}
+
+/**
+ * Which billing rail is this seat on?
+ *
+ * @param {Record<string,string>} [env]  the seat's effective env (`.env` merged
+ *   over the ambient env, the way every consumer sees it). VALUES ARE NEVER
+ *   REPORTED — only whether each name is non-empty.
+ * @param {object} [opts]
+ * @param {"claude"|"cohort"|string} [opts.seatEngine="claude"]  a `cohort` seat
+ *   talks to cohort-llm and is SUPPOSED to hold no Anthropic credential.
+ * @param {Record<string,string>} [opts.sources]  optional `{VAR: ".env"|"env"}`
+ *   provenance, surfaced in the message (a token arriving through launchd's
+ *   environment looks identical to one in `.env` until you say which).
+ * @param {boolean} [opts.enforce]  override the env-derived guard state.
+ * @returns {{verdict:"api-key"|"subscription"|"both"|"neither", level:"ok"|"warn"|"fail",
+ *   compliant:boolean, enforced:boolean, seatEngine:string, present:string[],
+ *   absent:string[], msg:string, remedy:string}}
+ */
+export function seatAuthVerdict(env = {}, opts = {}) {
+  const e = env && typeof env === "object" ? env : {};
+  const sources = (opts && opts.sources) || {};
+  const seatEngine = String((opts && opts.seatEngine) || "claude");
+  const enforced = opts && opts.enforce !== undefined ? !!opts.enforce : enforcementEnabled(e);
+
+  const key = nonEmpty(e.ANTHROPIC_API_KEY);
+  const token = nonEmpty(e.CLAUDE_CODE_OAUTH_TOKEN);
+  const preferPresent = nonEmpty(e.MAESTRO_PREFER_SUBSCRIPTION_AUTH);
+  const preferOn = TRUTHY.test(String(e.MAESTRO_PREFER_SUBSCRIPTION_AUTH || "").trim());
+  // The same test the runtime adapter applies (lib/runtime/adapter.mjs
+  // subscriptionAuth): the prefer flag OR a token puts the seat on the
+  // subscription rail, and that is what decides whether a lane blanks the key.
+  const subscription = token || preferOn;
+
+  const present = SEAT_AUTH_VARS.filter((n) => nonEmpty(e[n]));
+  const absent = SEAT_AUTH_VARS.filter((n) => !nonEmpty(e[n]));
+  const names = present.length ? present.map((n) => labelled(n, sources)).join(", ") : "none";
+  const cohortSeat = seatEngine === "cohort";
+
+  const verdict = key && subscription ? "both" : key ? "api-key" : subscription ? "subscription" : "neither";
+  // A flag that is present but not truthy is ignored by every consumer, and
+  // "MAESTRO_PREFER_SUBSCRIPTION_AUTH is set" reads as the opposite. Say so.
+  const preferNote = preferPresent && !preferOn
+    ? ` MAESTRO_PREFER_SUBSCRIPTION_AUTH is present but not 1/true/yes, so every consumer ignores it.`
+    : "";
+
+  const head = `Seat auth (G4): ${verdict} — names present: ${names}`;
+  const enforceNote = enforced
+    ? ` ${REQUIRE_CONSOLE_KEY_VAR} is set, so this is a failure.`
+    : ` Warning only today; set ${REQUIRE_CONSOLE_KEY_VAR}=1 to make it a doctor failure once the fleet has migrated.`;
+
+  if (verdict === "api-key") {
+    const msg = cohortSeat
+      ? `${head}. This engine-cohort seat needs no Anthropic credential; the key is harmless but unused by the engine lanes.${preferNote}`
+      : `${head}. This is the fleet posture: a Console API key in a capped workspace.${preferNote}`;
+    return { verdict, level: "ok", compliant: true, enforced, seatEngine, present, absent, msg, remedy: "" };
+  }
+
+  if (verdict === "both") {
+    const msg =
+      `${head}. AMBIGUOUS — this seat carries BOTH rails. The runtime adapter blanks ANTHROPIC_API_KEY on a ` +
+      `seat that is on subscription auth (lib/runtime/adapter.mjs subscriptionAuth), so the subscription rail ` +
+      `wins the lanes that go through it while a lane that passes the environment straight through may use the ` +
+      `key: spend lands in two places and neither is authoritative. Migrate, do not stack — ${CONSOLE_KEY_REMEDY}.` +
+      preferNote + enforceNote;
+    return { verdict, level: enforced ? "fail" : "warn", compliant: false, enforced, seatEngine, present, absent, msg, remedy: CONSOLE_KEY_REMEDY };
+  }
+
+  if (verdict === "subscription") {
+    const msg =
+      `${head}. Subscription OAuth is NOT the fleet posture${cohortSeat ? " and an engine-cohort seat should hold no Anthropic credential at all" : ""} — ` +
+      `it has no per-agent ceiling, no central spend visibility, and it expires headlessly. ${CONSOLE_KEY_REMEDY}.` +
+      preferNote + enforceNote;
+    return { verdict, level: enforced ? "fail" : "warn", compliant: false, enforced, seatEngine, present, absent, msg, remedy: CONSOLE_KEY_REMEDY };
+  }
+
+  // neither
+  if (cohortSeat) {
+    return {
+      verdict, level: "ok", compliant: true, enforced, seatEngine, present, absent,
+      msg: `${head}. Expected on an engine-cohort seat: it reaches models through cohort-llm and holds no Anthropic credential.`,
+      remedy: "",
+    };
+  }
+  return {
+    verdict, level: "fail", compliant: false, enforced, seatEngine, present, absent,
+    msg: `${head}. This seat has NO Claude credential at all — every spawn will fail, not fall back. ${CONSOLE_KEY_REMEDY}.`,
+    remedy: CONSOLE_KEY_REMEDY,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The fleet inventory: a template, and rows that paste into it
+// ---------------------------------------------------------------------------
+
+/**
+ * The inventory columns, in order. The measured ones (Seat → Env names
+ * present) a seat can fill in about itself; the rest are Console-side facts
+ * only a human with Console access knows.
+ */
+export const INVENTORY_COLUMNS = Object.freeze([
+  "Seat",
+  "Agent id",
+  "Machine",
+  "Auth verdict",
+  "Env names present",
+  "Checked",
+  "Operator",
+  "Anthropic account backing it",
+  "Console workspace",
+  "Monthly cap",
+  "Key id (last 4)",
+  ".env mode 600",
+  "Old token revoked",
+  "Verified (who / when)",
+]);
+
+/** Keys of the columns a seat measures about itself, in `inventoryRow` order. */
+const MEASURED = Object.freeze(["seat", "agentId", "machine", "verdict", "names", "checked"]);
+
+/** A markdown table cell: never break the table, never invent content. */
+function cell(v) {
+  const s = v === undefined || v === null ? "" : String(v);
+  return s.replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim();
+}
+
+/**
+ * One inventory row. The measured fields are filled; every Console-side field
+ * is left blank for the operator — a tool that guesses them teaches people to
+ * trust a guess.
+ *
+ * @param {{seat?:string, agentId?:string, machine?:string, verdict?:string,
+ *   names?:string[]|string, checked?:string}} [fields]
+ * @returns {string} a markdown table row with `INVENTORY_COLUMNS.length` cells
+ */
+export function inventoryRow(fields = {}) {
+  const f = fields || {};
+  const names = Array.isArray(f.names) ? f.names.join(" + ") : f.names || "";
+  const measured = { seat: f.seat, agentId: f.agentId, machine: f.machine, verdict: f.verdict, names, checked: f.checked };
+  const cells = INVENTORY_COLUMNS.map((_, i) => (i < MEASURED.length ? cell(measured[MEASURED[i]]) : ""));
+  return `| ${cells.join(" | ")} |`;
+}
+
+/**
+ * Turn the org directory into seat stubs for the template. Members that the
+ * directory marks human are dropped; anything ambiguous is KEPT, because a
+ * missing row is a seat nobody audits while a spurious row is one an operator
+ * deletes in a second.
+ *
+ * @param {object[]} [members]
+ * @returns {Array<{seat:string, agentId:string}>}
+ */
+export function seatsFromDirectory(members = []) {
+  const out = [];
+  const seen = new Set();
+  for (const m of Array.isArray(members) ? members : []) {
+    if (!m || typeof m !== "object") continue;
+    const human =
+      m.isHuman === true ||
+      /^human$/i.test(String(m.memberType || m.kind || m.type || "")) ||
+      /^(human|person)$/i.test(String(m.category || ""));
+    if (human) continue;
+    const agentId = String(m.agentId || m.slug || m.memberId || m.id || "").trim();
+    const seat = String(m.name || m.displayName || m.firstName || agentId || "").trim();
+    if (!seat && !agentId) continue;
+    const dedupe = `${seat.toLowerCase()}::${agentId.toLowerCase()}`;
+    if (seen.has(dedupe)) continue;
+    seen.add(dedupe);
+    out.push({ seat, agentId });
+  }
+  out.sort((a, b) => (a.seat || a.agentId).localeCompare(b.seat || b.agentId));
+  return out;
+}
+
+/**
+ * The per-machine inventory an operator fills in, with one pre-filled row per
+ * known member. Pure: the caller supplies the seats and the timestamp.
+ *
+ * @param {{seats?:Array<{seat:string, agentId:string}>, generatedAt?:string,
+ *   source?:string, note?:string}} [o]
+ * @returns {string} markdown
+ */
+export function fleetInventoryTemplate(o = {}) {
+  const seats = Array.isArray(o.seats) ? o.seats : [];
+  const generatedAt = o.generatedAt || "";
+  const source = o.source || "the org directory";
+  const lines = [];
+  lines.push("# G4 seat-auth inventory — off subscription OAuth, onto Console API keys");
+  lines.push("");
+  lines.push(`Generated by \`maestro seat-auth --fleet\`${generatedAt ? ` at ${generatedAt}` : ""} from ${source}.`);
+  lines.push("");
+  lines.push("**How to fill this in.** A seat's environment lives on the seat's own machine — there is no");
+  lines.push("remote inventory and this tool does not pretend otherwise. On EACH machine, in the agent's");
+  lines.push("directory, run:");
+  lines.push("");
+  lines.push("```sh");
+  lines.push("maestro seat-auth --row");
+  lines.push("```");
+  lines.push("");
+  lines.push("and paste the line it prints over that seat's row below. It fills the measured columns");
+  lines.push("(seat, agent id, machine, verdict, which variable NAMES are present, when it was checked)");
+  lines.push("and leaves the Console-side columns blank, because only a human with Console access knows them.");
+  lines.push("");
+  lines.push("**Never record a key value here** — or in a ticket, a commit, or a chat message. The last four");
+  lines.push("characters of a key id identify it; nothing else about a credential belongs in a document.");
+  lines.push("");
+  lines.push(`Migration steps, per seat: \`${RUNBOOK}\`. When every row reads \`api-key\`, set`);
+  lines.push(`\`${REQUIRE_CONSOLE_KEY_VAR}=1\` on the fleet so a seat that regresses fails \`maestro doctor\``);
+  lines.push("instead of warning quietly.");
+  if (o.note) { lines.push(""); lines.push(String(o.note)); }
+  lines.push("");
+  lines.push(`| ${INVENTORY_COLUMNS.join(" | ")} |`);
+  lines.push(`| ${INVENTORY_COLUMNS.map(() => "---").join(" | ")} |`);
+  if (seats.length === 0) {
+    lines.push(inventoryRow({}));
+  } else {
+    for (const s of seats) lines.push(inventoryRow({ seat: s.seat, agentId: s.agentId }));
+  }
+  lines.push("");
+  lines.push("## Record once, for the fleet");
+  lines.push("");
+  lines.push(`- Total live seats (rows above: **${seats.length}** from ${source} — confirm against the live fleet).`);
+  lines.push("- How many distinct Anthropic accounts backed the fleet before migration, and whose. A personal");
+  lines.push("  account powering several 24/7 seats is the most exposed shape.");
+  lines.push("- The date the last subscription token was revoked. That is the date this gate closes.");
+  lines.push(`- The date \`${REQUIRE_CONSOLE_KEY_VAR}=1\` was set fleet-wide, which is what stops it regressing.`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// The edge: `maestro seat-auth [--row] [--fleet] [--json]`
+// ---------------------------------------------------------------------------
+
+export const USAGE = `Usage:
+  maestro seat-auth                 This seat's billing rail: verdict, variable NAMES, remediation
+  maestro seat-auth --row           One markdown row to paste into the G4 inventory
+  maestro seat-auth --fleet         The per-machine inventory template, one row per org member
+  maestro seat-auth --json          The same verdict as JSON
+
+No value of any credential is ever printed. Exit 1 when the seat's verdict is a
+failure (no credential at all, or a non-compliant rail with ${REQUIRE_CONSOLE_KEY_VAR}=1).
+Runbook: ${RUNBOOK}
+`;
+
+/** config/agent.json, or {} — identity for the row, never a credential. */
+function readAgentJson(agentRoot, deps) {
+  try {
+    const { readFileSync, existsSync } = deps.fs || {};
+    const p = `${agentRoot}/config/agent.json`;
+    if (existsSync && !existsSync(p)) return {};
+    return JSON.parse(String(readFileSync(p, "utf8")));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Run `maestro seat-auth …`. Every edge is injectable; nothing is written.
+ *
+ * @param {string[]} [argv]
+ * @param {{env?:Record<string,string>, agentRoot?:string, hostname?:()=>string,
+ *   now?:number, fs?:object, readDotEnv?:(root:string)=>Record<string,string>,
+ *   fetchDirectory?:(o:object)=>Promise<object[]>, orgConfig?:object,
+ *   seatEngine?:string, stdout?:(s:string)=>void}} [deps]
+ * @returns {Promise<number>} exit code
+ */
+export async function runSeatAuth(argv = [], deps = {}) {
+  const write = deps.stdout || ((s) => process.stdout.write(s));
+  const env = deps.env || process.env;
+  const agentRoot = deps.agentRoot || env.AGENT_ROOT || env.AGENT_DIR || process.cwd();
+  const now = Number.isFinite(deps.now) ? deps.now : Date.now();
+  const checked = new Date(now).toISOString().slice(0, 10);
+
+  let wantRow = false;
+  let wantFleet = false;
+  let wantJson = false;
+  for (const a of argv) {
+    if (a === "--row") wantRow = true;
+    else if (a === "--fleet") wantFleet = true;
+    else if (a === "--json") wantJson = true;
+    else if (a === "--help" || a === "-h") { write(USAGE); return 0; }
+    else if (a.startsWith("-")) { write(`seat-auth: unknown flag ${a}\n\n${USAGE}`); return 1; }
+  }
+
+  // The seat's effective env, exactly as every consumer sees it: .env wins over
+  // the ambient environment (dotenv never overrides an already-set variable is
+  // the LOADER's rule; the FILE is the seat's declared intent, which is what an
+  // audit is about — doctor merges the same way).
+  const readDotEnv = deps.readDotEnv || (async (root) => {
+    const { parseDotEnv } = await import("./doctor-checks.mjs");
+    const fs = deps.fs || (await import("node:fs"));
+    try { return parseDotEnv(fs.readFileSync(`${root}/.env`, "utf8")); } catch { return {}; }
+  });
+  const dotEnv = await readDotEnv(agentRoot);
+  const ambient = {};
+  for (const n of [...SEAT_AUTH_VARS, REQUIRE_CONSOLE_KEY_VAR]) if (nonEmpty(env[n])) ambient[n] = String(env[n]);
+  const effective = { ...ambient, ...dotEnv };
+  const sources = {};
+  for (const n of SEAT_AUTH_VARS) {
+    if (nonEmpty(dotEnv[n])) sources[n] = ".env";
+    else if (nonEmpty(ambient[n])) sources[n] = "env";
+  }
+
+  let seatEngine = deps.seatEngine;
+  if (!seatEngine) {
+    try {
+      const { readSeatEngine } = await import("../runtime/adapter.mjs");
+      seatEngine = readSeatEngine(agentRoot);
+    } catch { seatEngine = "claude"; }
+  }
+
+  const verdict = seatAuthVerdict(effective, { seatEngine, sources });
+  const agentJson = readAgentJson(agentRoot, { fs: deps.fs || (await import("node:fs")) });
+  const seat = String(agentJson.firstName || agentJson.name || "").split(/\s+/)[0] || String(agentRoot).split("/").pop();
+  const agentId = String(agentJson.agentId || agentJson.memberId || agentJson.slug || env.COHORT_AGENT_ID || "");
+  const hostname = (deps.hostname || (() => { try { return osHostname(); } catch { return ""; } }))();
+
+  if (wantFleet) {
+    let members = [];
+    let source = "the org directory";
+    try {
+      const fetchDirectory = deps.fetchDirectory || (await import("../org/client.mjs")).fetchDirectory;
+      const { loadOrgConfig } = await import("../org/client.mjs");
+      members = await fetchDirectory({ cfg: deps.orgConfig || loadOrgConfig(agentRoot) });
+    } catch {
+      members = [];
+    }
+    const seats = seatsFromDirectory(members);
+    if (seats.length === 0) source = "the org directory (EMPTY — this seat is not enrolled, or the directory was unreachable; add the rows by hand)";
+    const md = fleetInventoryTemplate({ seats, generatedAt: new Date(now).toISOString(), source });
+    if (wantJson) { write(JSON.stringify({ seats, generatedAt: new Date(now).toISOString() }, null, 2) + "\n"); return 0; }
+    write(md + "\n");
+    return 0;
+  }
+
+  if (wantRow) {
+    write(inventoryRow({ seat, agentId, machine: hostname, verdict: verdict.verdict, names: verdict.present, checked }) + "\n");
+    return verdict.level === "fail" ? 1 : 0;
+  }
+
+  if (wantJson) {
+    write(JSON.stringify({
+      seat, agentId, machine: hostname, checked,
+      verdict: verdict.verdict, level: verdict.level, compliant: verdict.compliant,
+      enforced: verdict.enforced, seatEngine: verdict.seatEngine,
+      present: verdict.present, absent: verdict.absent,
+      remedy: verdict.remedy, runbook: RUNBOOK,
+    }, null, 2) + "\n");
+    return verdict.level === "fail" ? 1 : 0;
+  }
+
+  const mark = verdict.level === "ok" ? "✓" : verdict.level === "warn" ? "!" : "✗";
+  write(`${mark} ${verdict.msg}\n`);
+  write(`  seat ${seat}${agentId ? ` (${agentId})` : ""} on ${hostname || "this machine"}; engine ${verdict.seatEngine}\n`);
+  write(`  absent: ${verdict.absent.length ? verdict.absent.join(", ") : "none"}\n`);
+  write(`  paste into the G4 inventory: maestro seat-auth --row   (template: maestro seat-auth --fleet)\n`);
+  return verdict.level === "fail" ? 1 : 0;
+}
+
+export default {
+  SEAT_AUTH_VARS,
+  REQUIRE_CONSOLE_KEY_VAR,
+  CONSOLE_KEY_REMEDY,
+  RUNBOOK,
+  INVENTORY_COLUMNS,
+  enforcementEnabled,
+  seatAuthVerdict,
+  inventoryRow,
+  seatsFromDirectory,
+  fleetInventoryTemplate,
+  runSeatAuth,
+};

package/lib/cli/session.mjs

@@ -13,8 +13,10 @@
  * Commands:
  *
  *   status [--brief|--json]   lock holder · heartbeat age · main session id ·
- *                             mux session · plist installed/loaded · peers ·
- *                             open handoffs · restart/upgrade flags
+ *          [--all]            mux session · plist installed/loaded · peers ·
+ *                             open handoffs · restart/upgrade flags · the
+ *                             current-work block (lib/session/current-work;
+ *                             `--all` = the operator's unscoped view)
  *   attach                    print the exact `tmux attach` / `screen -r` line;
  *                             exec it when stdin+stdout are a TTY
  *   start                     bootstrap the plist if not loaded, then kickstart
@@ -55,7 +57,8 @@
 
 "use strict";
 
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { basename, dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
@@ -63,9 +66,12 @@ import { parseArgs } from "node:util";
 import { pathToFileURL } from "node:url";
 import { writeJsonAtomic } from "../fs-atomic.mjs";
 import { resolveAgentRoot } from "../agent-root.mjs";
-import { resolveClaudeBin } from "../claude-bin.mjs";
+import { buildSpawn } from "../runtime/adapter.mjs";
+import { resolveSeatSpawn } from "../runtime/seat-engine.mjs";
 import { sessionPermissionArgs } from "../session-permissions.mjs";
 import { withParallelism } from "../prompts/parallelism.mjs";
+import { envFileCommand, renderEnvFile } from "../session/launch-args.mjs";
+import { currentWorkBlock } from "../session/current-work.mjs";
 
 /** The SDK's own package.json version — what "installed" means for an upgrade notice. */
 function ownVersion() {
@@ -229,7 +235,32 @@ export function peerPermissionArgs({ env = process.env, allowedTools } = {}) {
  * @returns {string[]}
  */
 export function buildSpawnArgs({ first, slug, prompt, env, allowedTools }) {
-  return ["--name", `${first}-${slug}`, ...peerPermissionArgs({ env, allowedTools }), withParallelism(prompt)];
+  const spec = peerSpawn({ first, slug, prompt, env, allowedTools, bin: "claude" });
+  // Only the claude engine is wired for peers, so a failure is a defect.
+  if (!spec.ok) throw new Error(`buildSpawnArgs: ${spec.error.message}`);
+  return spec.argv;
+}
+
+/**
+ * The whole peer spawn — binary, argv, env — from the runtime adapter
+ * (lib/runtime/adapter.mjs, lane "peer"). `bin` is the caller's injected binary
+ * (deps.claudeBin); absent, the adapter resolves it.
+ *
+ * W4-E1 (row 5): `seat` is the seat's engine resolved once for this spawn
+ * (lib/runtime/seat-engine.mjs). A claude seat adds no fields (unchanged); an
+ * engine-cohort seat launches `cli.mjs session --name …` with the seat token.
+ * @param {{first:string, slug:string, prompt:string, env?:object, allowedTools?:string[], bin?:string, seat?:{fields:object}}} o
+ */
+export function peerSpawn({ first, slug, prompt, env, allowedTools, bin, seat = { fields: {} } }) {
+  return buildSpawn({
+    lane: "peer",
+    bin: bin || undefined,
+    name: `${first}-${slug}`,
+    permissions: peerPermissionArgs({ env, allowedTools }),
+    prompt: withParallelism(prompt),
+    env,
+    ...seat.fields,
+  });
 }
 
 /**
@@ -280,6 +311,9 @@ function defaultDeps() {
     },
     /** The version the running SDK reports — an upgrade notice for it is already applied. */
     installedVersion: ownVersion(),
+    /** W4-E1: a private (0600) file that must not exist yet — the engine env file. */
+    writePrivateFile(path, text) { writeFileSync(path, text, { mode: 0o600, flag: "wx" }); chmodSync(path, 0o600); },
+    envFileId: () => randomUUID(),
   };
 }
 
@@ -542,7 +576,7 @@ function ensureLoaded(ctx, say) {
 export function usage() {
   return `maestro session <command>
 
-  status [--brief|--json]      lock holder, heartbeat age, mux session, plist, peers, handoffs
+  status [--brief|--json|--all] lock holder, heartbeat age, mux session, plist, peers, handoffs, current work (--all: unscoped)
   attach                       print the attach command (tmux attach / screen -r); exec it on a TTY
   start                        load the launchd job if needed, then kickstart it
   stop                         launchctl bootout the session job
@@ -557,6 +591,7 @@ export function usage() {
 const FLAGS = {
   json: { type: "boolean", default: false },
   brief: { type: "boolean", default: false },
+  all: { type: "boolean", default: false },
   force: { type: "boolean", default: false },
   name: { type: "string" },
   cwd: { type: "string" },
@@ -596,9 +631,21 @@ export async function run(argv = [], opts = {}) {
 
     case "status": {
       const s = snapshot(ctx);
+      // The "what am I doing right now" block (lib/session/current-work) —
+      // the same fact `session_status` returns and the daemon's replies carry.
+      // Scoped like every other reader: by default a live session from any
+      // conversation is reported as existing only; `--all` is the operator's
+      // own view (the files under state/ are theirs to read anyway — the flag
+      // only says the printout may carry what they hold, so it is not pasted
+      // onward by reflex). Fail-open: an unreadable state dir is an empty
+      // block, not a failed status.
+      try { s.currentWork = await (d.currentWorkBlock || currentWorkBlock)(agentRoot, { now: d.now(), audience: flags.all ? null : {} }); } catch { s.currentWork = ""; }
       if (flags.json) say(JSON.stringify(s, null, 2));
       else if (flags.brief) say(briefLine(s));
-      else for (const l of humanStatus(s)) say(l);
+      else {
+        for (const l of humanStatus(s)) say(l);
+        if (s.currentWork) for (const l of s.currentWork.split("\n")) say(l);
+      }
       return { ok: true, code: 0, lines, data: s };
     }
 
@@ -679,12 +726,33 @@ export async function run(argv = [], opts = {}) {
 
       const cfg = await loadCfg(ctx);
       const kind = chooseMux(d, cfg);
-      const bin = d.claudeBin || resolveClaudeBin();
-      const args = buildSpawnArgs({ first, slug, prompt, env: d.env, allowedTools: cfg.allowedTools });
+      // W4-E1: the seat's engine, once for this spawn; an engine-cohort peer never falls back to claude.
+      let seat = { engine: "claude", fields: {} };
+      try { seat = (await (d.seatSpawn || ((root) => resolveSeatSpawn(root)))(agentRoot)) || seat; } catch { seat = { engine: "claude", fields: {} }; }
+      const spec = peerSpawn({ first, slug, prompt, env: d.env, allowedTools: cfg.allowedTools, bin: d.claudeBin, seat });
+      if (!spec.ok) return fail(`session spawn: ${spec.error.message}`);
+      // W4-E1: an engine-cohort peer's env (seat token, Claude credentials
+      // scrubbed) rides a 0600 file the session sources and deletes before exec
+      // (launch-args ENGINE_ENV_SCRIPT). The mux cannot carry it: a tmux server
+      // already running gives a new session its own global env, not the client's.
+      let envFile = null;
+      if (seat.engine === "cohort") {
+        envFile = join(paths.dir, `engine-env-${muxName}-${d.envFileId()}.env`);
+        try {
+          mkdirSync(paths.dir, { recursive: true });
+          d.writePrivateFile(envFile, renderEnvFile(spec.env));
+        } catch (e) {
+          return fail(`session spawn: could not write the engine env file ${envFile}: ${e && e.message ? e.message : e}`);
+        }
+      }
+      const command = envFile ? envFileCommand({ envFile, bin: spec.bin, args: spec.argv }) : [spec.bin, ...spec.argv];
       const r = kind === "tmux"
-        ? d.exec("tmux", ["new-session", "-d", "-s", muxName, "-c", cwd, "--", bin, ...args], { cwd, env: d.env })
-        : d.exec("screen", ["-dmS", muxName, bin, ...args], { cwd, env: d.env });
-      if (r.status !== 0) return fail(`session spawn: ${kind} returned ${r.status}${r.stderr ? `: ${r.stderr.trim()}` : ""}`);
+        ? d.exec("tmux", ["new-session", "-d", "-s", muxName, "-c", cwd, "--", ...command], { cwd, env: d.env })
+        : d.exec("screen", ["-dmS", muxName, ...command], { cwd, env: d.env });
+      if (r.status !== 0) {
+        if (envFile) { try { unlinkSync(envFile); } catch { /* never written */ } }
+        return fail(`session spawn: ${kind} returned ${r.status}${r.stderr ? `: ${r.stderr.trim()}` : ""}`);
+      }
 
       const startedAt = new Date(d.now()).toISOString();
       const reg = updatePeers(paths, (cur) => [

package/lib/collective/capture.mjs

@@ -22,7 +22,7 @@
 import { spawnSync } from "node:child_process";
 import { normalizeCard, appendCards, repoLabel } from "./cards.mjs";
 import { isRepoDenied } from "./config.mjs";
-import { resolveClaudeBin, daemonClaudeArgs, augmentedPath } from "../claude-bin.mjs";
+import { buildSpawn } from "../runtime/adapter.mjs";
 
 const DISTILL_TIMEOUT_MS = 60_000;
 const MAX_TRANSCRIPT_CHARS = 16_000;
@@ -118,13 +118,15 @@ export function extractCardsFromModelOutput(text) {
 /** Default distiller: spawn a cheap `claude --print` pass. Fail-open → "". */
 export function defaultDistiller(prompt, opts = {}) {
   try {
-    const model = opts.model || "haiku";
-    const args = ["--print", "--model", model, ...daemonClaudeArgs()];
-    const res = spawnSync(resolveClaudeBin(), args, {
-      input: prompt,
+    // argv + env from the runtime adapter (lane "capture"): --print --model <m>
+    // <daemon MCP args>, prompt on stdin, PATH augmented.
+    const spec = buildSpawn({ lane: "capture", model: opts.model || "haiku", prompt, mcp: {}, env: process.env });
+    if (!spec.ok) return "";
+    const res = spawnSync(spec.bin, spec.argv, {
+      input: spec.stdin,
       encoding: "utf8",
       timeout: DISTILL_TIMEOUT_MS,
-      env: { ...process.env, PATH: augmentedPath() },
+      env: spec.env,
       maxBuffer: 8 * 1024 * 1024,
     });
     if (res.status === 0 && res.stdout) return res.stdout;