@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/.env.example

@@ -36,7 +36,11 @@ COHORT_BASE=https://os.cohortapp.com
 # agent's workforce member (aliases: COHORT_API_KEY, COHORT_TOKEN).
 COHORT_API_TOKEN=
 
-# Org slug — sent as the x-org-id pin header + used by pull-enrollment.
+# The org's ID — NOT its slug. It has the form org_default_<slug> (Adaptic:
+# org_default_adaptic, slug adaptic) and is sent as the x-org-id pin header,
+# which hq compares with strict equality against the key's Org.id: a slug here
+# 401s every call. `maestro doctor` checks this value against the server and
+# says "you set the slug" when that is what happened. Also used by pull-enrollment.
 COHORT_ORG_ID=
 
 # OPTIONAL — this agent's member id/slug. Used by pull-enrollment, org_whoami,
@@ -53,29 +57,40 @@ COHORT_AGENT_EMAIL=
 # The agent's reasoning engines. At minimum you need Anthropic (Claude).
 #
 
-# REQUIRED — Primary reasoning engine. Two ways to authenticate:
-#
-#   Option A — API key (pay-per-token)
-#     Set ANTHROPIC_API_KEY below to a valid sk-ant-api03-... key.
-#     Get one: https://console.anthropic.com/settings/keys
-#
-#   Option B — Claude Code subscription (Pro/Max, OAuth via Keychain)
-#     LEAVE ANTHROPIC_API_KEY EMPTY *and* set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1.
-#     This tells the cadence consumer to strip ANTHROPIC_API_KEY from every
-#     sub-session spawn so claude --print falls back to the keychain OAuth
-#     token. Most agents on a Mac mini with a Claude Code subscription
-#     should use this option — routine cadence ticks cost zero API credits.
-#
-# Doctor validates the key against api.anthropic.com on every run; an
-# invalid key here will cascade 401s through every sub-session spawn.
-ANTHROPIC_API_KEY=
-
-# OPTIONAL — When set to 1, the cadence consumer strips ANTHROPIC_API_KEY
-# from every claude --print sub-session env so claude falls back to
-# Claude Code subscription auth (Keychain OAuth). Use this when the
-# agent's Mac has a Claude Code Pro/Max subscription.
+# REQUIRED — Primary reasoning engine. ONE auth story, three ways to satisfy it,
+# in order of preference. `maestro setup` (model section, order 30) writes the
+# chosen one here and chmods this file 600; `maestro doctor` reports which mode
+# 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)
+#     On ANY machine where you are logged in to Claude Code, run
+#         claude setup-token
+#     and paste the long-lived token below, together with
+#     MAESTRO_PREFER_SUBSCRIPTION_AUTH=1. Every spawn — the daemon's --print
+#     lane, the main session, cadence sub-sessions — carries it; the interactive
+#     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
+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.
+#
+# 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
+#     Doctor validates it against api.anthropic.com on every run; an invalid
+#     key cascades 401s through every sub-session spawn.
+ANTHROPIC_API_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

@@ -568,6 +568,8 @@ Autonomous work is designed to survive reboot and power loss, and the agent degr
 
 - [Setup Wizard](docs/guides/setup-wizard.md) -- `maestro setup`: sections, resume/checkpoint, source of truth, enrichment, verify probe, all flags
 - [Agent Persona Setup](docs/guides/agent-persona-setup.md) -- Identity, operating charter, and behavioural policies
+- [Front-door Session](docs/guides/front-door-session.md) -- The always-on main session: what runs, how to attach, stop, restart, and read its status
+- [Mac mini bring-up](docs/guides/mac-mini.md) -- Boxed mini to enrolled seat: token, create, setup, session install, Tailscale SSH, doctor
 - [Email Setup](docs/guides/email-setup.md) -- Gmail IMAP polling, SMTP sending, thread dedup, signatures
 - [Slack Setup](docs/guides/slack-setup.md) -- Slack app, tokens, sending, typing indicators, events, CDP
 - [WhatsApp Setup](docs/guides/whatsapp-setup.md) -- Twilio WhatsApp sandbox/production, webhook handler

package/bin/maestro.mjs

@@ -816,12 +816,24 @@ function loadShippedManifest(cwd) {
 function writeShippedManifest(cwd, files) {
   const dst = join(cwd, SHIPPED_MANIFEST_REL);
   mkdirSync(dirname(dst), { recursive: true });
+  // `sdkVersion` (2.12+) is what `upgrade --verify` compares against the
+  // running package; `version` is the manifest FORMAT and stays 1.
   writeFileSync(
     dst,
-    JSON.stringify({ version: 1, files: [...files].sort() }, null, 2) + "\n",
+    JSON.stringify({ version: 1, sdkVersion: readFrameworkVersion(), files: [...files].sort() }, null, 2) + "\n",
   );
 }
 
+/** The SDK version the previous upgrade recorded here, or null (pre-2.12 manifest / none). */
+function readShippedManifestVersion(cwd) {
+  try {
+    const raw = JSON.parse(readFileSync(join(cwd, SHIPPED_MANIFEST_REL), "utf-8"));
+    return typeof raw?.sdkVersion === "string" ? raw.sdkVersion : null;
+  } catch {
+    return null; // absent or unreadable — "from" is simply unknown
+  }
+}
+
 function sha256File(p) {
   return createHash("sha256").update(readFileSync(p)).digest("hex");
 }
@@ -1130,10 +1142,12 @@ function parseUpgradeFlags(args) {
     noIncoming: false,
     verbose: false,
     noPrune: false,
+    verify: false,
   };
   for (const a of args) {
     if (a === "--dry-run" || a === "-n") flags.dryRun = true;
     else if (a === "--force-overwrite" || a === "--force") flags.forceOverwrite = true;
+    else if (a === "--verify") flags.verify = true;
     else if (a === "--no-incoming") flags.noIncoming = true;
     else if (a === "--no-prune") flags.noPrune = true;
     else if (a === "--verbose" || a === "-v") flags.verbose = true;
@@ -1154,9 +1168,25 @@ Flags:
   --force-overwrite      Overwrite even locally-modified files (backs them up)
   --no-incoming          Don't write .maestro/incoming/ shadows for preserved files
   --no-prune             Keep framework files that upstream has deleted
+  --verify               Report only: is this seat wholly on this SDK version
+                         (global bin, local package, shipped manifest, running
+                         daemon, plists installed + loaded, global-setup)?
+                         Exit 1 on any mismatch. doctor prints the same rows.
   --verbose, -v          Print classification for every file
   --help, -h             Show this help
 
+After the file merge (every non-dry run, each step fail-open, reported here
+and in .maestro/upgrade-result.json {from,to,at,steps}):
+  plists         scripts/local-triggers/generate-plists.sh
+  launchd        install / replace / load every generated plist under
+                 ~/Library/LaunchAgents (mode 600, launchctl bootstrap);
+                 -daemon and -session are rewritten, never restarted
+  globalSetup    maestro global-setup (identity block, cohort MCP, settings, skills,
+                 vendored design skill packs)
+  globalInstall  npm i -g @cohortapp/agent-sdk@<this version>
+                 (MAESTRO_SKIP_GLOBAL_INSTALL=1 skips)
+  verify         the --verify report
+
 Per-file behaviour:
   added     — new upstream file → copy
   updated   — existed, byte-equal to your committed copy → safe overwrite
@@ -1190,6 +1220,16 @@ Per-file behaviour:
     process.exit(1);
   }
 
+  if (flags.verify) {
+    // Report only — nothing is written. lib/upgrade/verify.mjs is the core;
+    // the same rows appear in `maestro doctor`.
+    const { runVerify, formatVerifyReport } = await import("../lib/upgrade/verify.mjs");
+    const report = runVerify({ cwd, expected: readFrameworkVersion() });
+    for (const line of formatVerifyReport(report)) console.log(line);
+    process.exitCode = report.ok ? 0 : 1;
+    return;
+  }
+
   const inGit = isGitRepo(cwd);
   if (!inGit) {
     warn("Not in a git repo — cannot detect local modifications.");
@@ -1330,6 +1370,8 @@ Per-file behaviour:
   // Removals are backed up under .maestro/backup/ exactly like a forced
   // overwrite, so a prune is always reversible.
   const priorManifest = loadShippedManifest(cwd);
+  // What this machine ran before this upgrade — the `from` of upgrade-result.json.
+  const priorSdkVersion = readShippedManifestVersion(cwd);
 
   if (flags.noPrune) {
     log("Prune skipped (--no-prune): upstream-deleted files left in place.");
@@ -1614,6 +1656,31 @@ Per-file behaviour:
     }
   }
 
+  // Post-steps (design 2026-09-08, WP-M6): plists → launchd reconcile →
+  // global-setup → global npm install → verify. This is what puts an existing
+  // seat wholly on the new architecture on the first hop from ANY old version,
+  // because the old autoupdate.sh runs THIS upgrade and nothing else. Each
+  // step is fail-open; the daemon is restarted by autoupdate, never here.
+  if (!flags.dryRun) {
+    console.log();
+    console.log(`${C.bold}Seat reconcile${C.reset}`);
+    try {
+      const { runUpgradePostSteps } = await import("../lib/upgrade/post-steps.mjs");
+      await runUpgradePostSteps({
+        cwd,
+        sdkVersion: readFrameworkVersion(),
+        from: priorSdkVersion,
+        say: { log: (m) => console.log(`  ${m}`), ok, warn },
+        // global-setup needs config/agent.json + the collective hook runner;
+        // a repo without them is reported as a skipped step, not a crash.
+        globalSetup: isAgentRepo(cwd) ? () => globalSetup([cwd]) : null,
+      });
+      log("Result: .maestro/upgrade-result.json  ·  re-check any time: maestro upgrade --verify");
+    } catch (e) {
+      warn(`seat reconcile skipped: ${e && e.message ? e.message : e}`);
+    }
+  }
+
   console.log();
   log("Agent-specific paths (config/, CLAUDE.md, knowledge/, memory/, state/, outputs/, logs/, .env) were NOT touched.");
 }
@@ -2301,6 +2368,35 @@ async function doctor() {
     } catch { /* pmset unavailable (non-mac / sandbox) — skip */ }
   }
 
+  // Claude auth, the COHORT_ORG_ID id-vs-slug trap, the effective source of
+  // every Cohort value, the global SDK install, Tailscale SSH and the main
+  // session job — mode-aware, so a seat on the subscription token is no
+  // longer told "ANTHROPIC_API_KEY not set". Pure checks + one injected edge
+  // live in lib/cli/doctor-checks.mjs (design 2026-09-08 §3.9).
+  try {
+    const { runDoctorChecks } = await import("../lib/cli/doctor-checks.mjs");
+    for (const r of await runDoctorChecks({ cwd })) {
+      if (r.level === "ok") ok(r.msg);
+      else if (r.level === "warn") warn(r.msg);
+      else { fail(r.msg); issues++; }
+    }
+  } catch (err) {
+    warn(`auth / front-door checks unavailable: ${err && err.message ? err.message : err}`);
+  }
+
+  // `maestro upgrade --verify` rows: one SDK version end to end (global bin,
+  // local package, shipped manifest, running daemon, plists, global-setup).
+  try {
+    const { runVerify } = await import("../lib/upgrade/verify.mjs");
+    for (const r of runVerify({ cwd, expected: readFrameworkVersion() }).rows) {
+      if (r.level === "ok") ok(r.msg);
+      else if (r.level === "warn") warn(r.msg);
+      else { fail(r.msg); issues++; }
+    }
+  } catch (err) {
+    warn(`upgrade verify unavailable: ${err && err.message ? err.message : err}`);
+  }
+
   // ── .env ────────────────────────────────────────────────────────────────
   if (existsSync(join(cwd, ".env"))) {
     // .env permission hygiene (setup-onboarding W4): every credential — Slack,
@@ -2327,46 +2423,9 @@ async function doctor() {
       else if (required) { warn(`${key} not set`); issues++; }
       else warn(`${key} not set (optional)`);
     };
-    check("ANTHROPIC_API_KEY", true);
     check("SLACK_USER_TOKEN", false);
     check("GMAIL_APP_PASSWORD", false);
 
-    // Auth validity: if ANTHROPIC_API_KEY is set, ping the API to
-    // verify it works. An invalid key in .env will silently be sent
-    // to every `claude --print` sub-session and cause cascading 401s
-    // (exactly the ravi-ai inbox-processor runaway). Better to catch
-    // it here. Skips the check if the user opted out via
-    // MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 (subscription wins).
-    const keyMatch = env.match(/^ANTHROPIC_API_KEY=(.+)$/m);
-    const preferSubsMatch = env.match(/^MAESTRO_PREFER_SUBSCRIPTION_AUTH=(.+)$/m);
-    const preferSubs = preferSubsMatch && /^1|true|yes$/i.test(preferSubsMatch[1].trim());
-    if (keyMatch && !preferSubs) {
-      const key = keyMatch[1].trim().replace(/^"|"$/g, "");
-      try {
-        const result = spawnSync("curl", [
-          "-s", "-o", "/dev/null", "-w", "%{http_code}",
-          "-X", "POST",
-          "-H", `x-api-key: ${key}`,
-          "-H", "anthropic-version: 2023-06-01",
-          "-H", "content-type: application/json",
-          "--max-time", "8",
-          "https://api.anthropic.com/v1/messages",
-          "-d", JSON.stringify({ model: "claude-haiku-4-5", max_tokens: 5, messages: [{ role: "user", content: "ping" }] }),
-        ], { encoding: "utf-8" });
-        const code = (result.stdout || "").trim();
-        if (code === "200") ok("ANTHROPIC_API_KEY validated against api.anthropic.com");
-        else if (code === "401") {
-          warn(`ANTHROPIC_API_KEY is INVALID (HTTP 401 from api.anthropic.com).`);
-          warn(`  This will cause every sub-session spawn to fail. Either:`);
-          warn(`    1. Replace the key in .env with a valid one, OR`);
-          warn(`    2. Set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 in .env to use Claude Code subscription auth.`);
-          issues++;
-        } else if (code) warn(`ANTHROPIC_API_KEY check returned HTTP ${code} (expected 200)`);
-        else warn(`ANTHROPIC_API_KEY check skipped (no network / curl missing)`);
-      } catch { warn("ANTHROPIC_API_KEY check failed (curl error)"); }
-    } else if (preferSubs) {
-      ok("MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 — using Claude Code subscription (Keychain OAuth)");
-    }
 
     // ── Slack Socket Mode ────────────────────────────────────────────────
     // When SLACK_APP_LEVEL_TOKEN is set, verify the launchd job is loaded
@@ -3297,6 +3356,14 @@ async function globalSetup(args = []) {
   if (!dryRun) writeFileSync(pointerFile, JSON.stringify(gc.buildPointer(cwd, agentName), null, 2));
   ok(`${dryRun ? "[dry-run] " : ""}machine pointer → ${pointerFile}`);
 
+  // 4) Front-door session (2026-09 §3.7): identity block, cohort MCP server,
+  //    settings additions, global skills and the vendored design skill packs
+  //    (WP-M7) — lib/cli/global-setup-extras.mjs.
+  try {
+    const extras = await import("../lib/cli/global-setup-extras.mjs");
+    await extras.applyFrontDoorSetup({ agentRoot: cwd, claudeDir, dryRun, log, ok, warn });
+  } catch (err) { warn(`front-door setup skipped: ${err && err.message}`); }
+
   console.log();
   if (dryRun) {
     log("Dry run complete — no files written.");
@@ -3737,6 +3804,11 @@ switch (command) {
   case "router": await routerCmd(args); break;
   case "secrets": await secretsCmd(args); break;
   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 "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 "init":
   case "update-init":
   case "init-update":
@@ -3750,7 +3822,8 @@ Usage:
   npx @cohortapp/agent-sdk setup [section] [flags]    Configure this agent (deterministic, resumable wizard)
   npx @cohortapp/agent-sdk pair <code>                Open a pre-auth pairing handshake (org admin approves it)
   npx @cohortapp/agent-sdk sync [--force] [--dry-run] Re-pull this agent's record from Cohort into config/agent.json
-  npx @cohortapp/agent-sdk upgrade [--dry-run]        Update framework files
+  npx @cohortapp/agent-sdk upgrade [--dry-run]        Update framework files (+ plists, launchd, global-setup, global install)
+  npx @cohortapp/agent-sdk upgrade --verify           Is this seat wholly on this SDK version? (exit 1 on mismatch)
   npx @cohortapp/agent-sdk init [feature] [--apply]   Run pending feature-init steps
   npx @cohortapp/agent-sdk global-setup [--dry-run]   Wire collective memory into ~/.claude (machine-wide)
   npx @cohortapp/agent-sdk doctor                     Verify installation
@@ -3761,6 +3834,11 @@ Usage:
   npx @cohortapp/agent-sdk secrets sync [--name X]    Pull org secrets from the broker into the local store
   npx @cohortapp/agent-sdk secrets rotate --name X    Rotate a secret (new value read from stdin)
   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 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
 
 Upgrade flags:
   --dry-run, -n          Preview changes without writing

package/bin/maestro.test.mjs

@@ -50,6 +50,65 @@ async function rmRoot(path) {
   try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ }
 }
 
+// ---------------------------------------------------------------------------
+// The machine the CLI must NEVER touch from a test: the developer's real
+// ~/Library/LaunchAgents, ~/.claude and global npm. `upgrade` now reconciles
+// all three (WP-M6), so every CLI run gets a throwaway HOME, a `launchctl`
+// stub that treats "installed" as "loaded" (in `list` AND in `print gui/<uid>`,
+// which is what the reconcile reads), an `npm` stub, a `claude` stub (logs and
+// exits 1 → global-setup's JSON fallback) and MAESTRO_SKIP_GLOBAL_INSTALL=1.
+// The claude stub is reached through CLAUDE_BIN, not PATH: lib/claude-bin.mjs
+// resolves ~/.local/bin, /opt/homebrew/bin, /usr/local/bin BEFORE PATH, so a
+// PATH-only stub is silently bypassed by the developer's real `claude`.
+// ---------------------------------------------------------------------------
+
+const TEST_SHIM = await tmpRoot("maestro-shim-global");
+{
+  const stub = async (name, body) => { writeFileSync(join(TEST_SHIM, name), `#!/bin/bash\n${body}\n`); await fsp.chmod(join(TEST_SHIM, name), 0o755); };
+  await stub("launchctl", `echo "launchctl $*" >> "$HOME/launchctl.log"
+if [ "$1" = "list" ]; then
+  if [ -n "\${2:-}" ]; then [ -f "$HOME/Library/LaunchAgents/$2.plist" ] && exit 0 || exit 113; fi
+  printf 'PID\tStatus\tLabel\n'
+  for f in "$HOME"/Library/LaunchAgents/*.plist; do [ -f "$f" ] && printf -- '-\t0\t%s\n' "$(basename "$f" .plist)"; done
+  exit 0
+fi
+if [ "$1" = "print" ]; then
+  case "$2" in
+    gui/*/*) l="\${2##*/}"; if [ -f "$HOME/Library/LaunchAgents/$l.plist" ]; then echo "$l = {}"; exit 0; fi; echo "Could not find service \"$l\" in domain for user gui: 501" >&2; exit 113 ;;
+    gui/*) printf '%s = {\n\tservices = {\n' "$2"; for f in "$HOME"/Library/LaunchAgents/*.plist; do [ -f "$f" ] && printf '\t\t0\t0\t%s\n' "$(basename "$f" .plist)"; done; printf '\t}\n}\n'; exit 0 ;;
+  esac
+fi
+exit 0`);
+  await stub("npm", `echo "npm $*" >> "$HOME/npm.log"
+case "$1" in
+  ls) echo '{}'; exit 1 ;;
+  view) exit 1 ;;
+  root) echo "$HOME/npm-global/lib/node_modules"; exit 0 ;;
+esac
+exit 0`);
+  await stub("claude", `echo "claude $*" >> "$HOME/claude.log"
+exit 1`);
+}
+
+/** A throwaway HOME for one CLI run (or a shared one when the test does not care). */
+async function freshHome() {
+  const home = await tmpRoot("maestro-home");
+  mkdirSync(join(home, "Library", "LaunchAgents"), { recursive: true });
+  return home;
+}
+const TEST_HOME = await freshHome();
+
+function baseEnv(extra = {}) {
+  return {
+    ...process.env,
+    HOME: TEST_HOME,
+    PATH: `${TEST_SHIM}:${process.env.PATH || ""}`,
+    CLAUDE_BIN: join(TEST_SHIM, "claude"),
+    MAESTRO_SKIP_GLOBAL_INSTALL: "1",
+    ...extra,
+  };
+}
+
 /**
  * Build a PATH that shadows `npm` (and optionally `git`) with no-op shims
  * so `create` doesn't actually try to install dependencies. Returns the new
@@ -61,14 +120,14 @@ async function withShim() {
   writeFileSync(npm, "#!/bin/bash\necho '[shim npm]' \"$@\" >&2\nexit 0\n");
   await fsp.chmod(npm, 0o755);
   // Keep real git (we want git init to actually init).
-  const env = { ...process.env, PATH: `${dir}:${process.env.PATH || ""}` };
+  const env = baseEnv({ PATH: `${dir}:${TEST_SHIM}:${process.env.PATH || ""}` });
   return { env, dir };
 }
 
 function runCli(args, cwd, env) {
   return spawnSync(process.execPath, [MAESTRO_CLI, ...args], {
     cwd: cwd || process.cwd(),
-    env: env || process.env,
+    env: env || baseEnv(),
     encoding: "utf-8",
   });
 }
@@ -77,7 +136,7 @@ function runCli(args, cwd, env) {
 function runCliStdin(args, cwd, input, env) {
   return spawnSync(process.execPath, [MAESTRO_CLI, ...args], {
     cwd: cwd || process.cwd(),
-    env: env || process.env,
+    env: env || baseEnv(),
     input,
     encoding: "utf-8",
   });
@@ -1325,10 +1384,17 @@ test("upgrade prune never removes machine-generated launchd plists", async () =>
   try {
     const r = runCli(["upgrade"], root);
     assert.equal(r.status, 0, r.stderr);
+    // Prune backs a file up under .maestro/backup/<path> before unlinking it
+    // and lists it as "pruned"; neither may happen here. (The file itself is
+    // gone after the run since WP-M6 — generate-plists.sh runs unconditionally
+    // as the first post-step and, as it always has, clears scripts/local-
+    // triggers/plists/ before rendering this machine's set. That is the
+    // generator owning its directory, not prune eating machine config.)
     assert.ok(
-      existsSync(join(root, plist)),
-      "generated plists are machine config; prune must leave them alone",
+      !existsSync(join(root, ".maestro", "backup", plist)),
+      "generated plists are machine config; prune must leave them alone (no prune backup)",
     );
+    assert.ok(!/pruned/.test(r.stdout), `prune must not report the plist:\n${r.stdout}`);
   } finally {
     await fsp.rm(root, { recursive: true, force: true });
   }
@@ -1402,3 +1468,107 @@ test("upgrade --dry-run writes no shipped-manifest", async () => {
     await fsp.rm(root, { recursive: true, force: true });
   }
 });
+
+// ---------------------------------------------------------------------------
+// upgrade — seat reconcile post-steps (WP-M6): the first hop from an old
+// version must leave the machine wholly on the new architecture by itself.
+// ---------------------------------------------------------------------------
+
+/** makeLegacyAgent + a NAMED config/agent.json, so plist labels and the identity block use "legacy". */
+async function makeNamedLegacyAgent() {
+  const root = await makeLegacyAgent();
+  writeFileSync(join(root, "config/agent.json"), JSON.stringify({ firstName: "Legacy", lastName: "Tester", fullName: "Legacy Tester" }, null, 2));
+  execFileSync("git", ["add", "-A"], { cwd: root });
+  execFileSync("git", ["-c", "user.email=test@test", "-c", "user.name=test", "commit", "-q", "-m", "name"], { cwd: root });
+  return root;
+}
+
+test("upgrade installs the -session plist into $HOME/Library/LaunchAgents (600, bootstrapped), never kickstarts daemon/session, records sdkVersion in the manifest and writes .maestro/upgrade-result.json", async () => {
+  const root = await makeNamedLegacyAgent();
+  const home = await freshHome();
+  try {
+    // An existing seat: the daemon job is installed (old content) and loaded.
+    writeFileSync(join(home, "Library", "LaunchAgents", "ai.maestro.legacy-daemon.plist"), "<plist>old daemon</plist>");
+    const r = runCli(["upgrade"], root, baseEnv({ HOME: home }));
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+
+    const la = join(home, "Library", "LaunchAgents");
+    const sessionPlist = join(la, "ai.maestro.legacy-session.plist");
+    assert.ok(existsSync(sessionPlist), `session plist must be installed; stdout:\n${r.stdout}`);
+    assert.equal(statSync(sessionPlist).mode & 0o777, 0o600);
+    assert.match(readFileSync(sessionPlist, "utf-8"), /scripts\/session\/supervisor\.sh/);
+    assert.match(readFileSync(join(la, "ai.maestro.legacy-daemon.plist"), "utf-8"), /launchd-wrapper\.sh/, "daemon plist rewritten to the generated one");
+
+    const calls = readFileSync(join(home, "launchctl.log"), "utf-8");
+    assert.match(calls, new RegExp(`^launchctl bootstrap gui/\\d+ ${sessionPlist.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`, "m"), calls);
+    assert.ok(!/kickstart/.test(calls), `nothing is kickstarted by upgrade (the -autoupdate job is the one it runs inside):\n${calls}`);
+    assert.ok(!/bootout|unload/.test(calls), calls);
+    assert.match(calls, /^launchctl print gui\/\d+$/m, "loaded-ness is read from the gui domain");
+
+    // The claude STUB handled `mcp add-json` — not the developer's real CLI.
+    // lib/claude-bin.mjs would otherwise pick /usr/local/bin/claude over PATH;
+    // CLAUDE_BIN in baseEnv is what makes this isolation real.
+    assert.ok(existsSync(join(home, "claude.log")), "the claude stub must be the binary global-setup reached");
+    assert.match(readFileSync(join(home, "claude.log"), "utf-8"), /^claude mcp add-json cohort .* --scope user$/m);
+    const claudeJson = JSON.parse(readFileSync(join(home, ".claude.json"), "utf-8"));
+    assert.equal(claudeJson.mcpServers.cohort.env.COHORT_AGENT_ROOT.replace(/^\/private/, ""), root.replace(/^\/private/, ""), "stub exit 1 → the JSON merge fallback registered the server");
+    assert.ok(!("firstStartVersion" in claudeJson), "a real `claude` would have stamped its own keys into ~/.claude.json");
+    assert.ok(!existsSync(join(home, "npm.log")) || !/npm install -g/.test(readFileSync(join(home, "npm.log"), "utf-8")), "no global install under MAESTRO_SKIP_GLOBAL_INSTALL=1");
+
+    const manifest = JSON.parse(readFileSync(join(root, ".maestro/shipped-manifest.json"), "utf-8"));
+    const sdkVersion = JSON.parse(readFileSync(join(MAESTRO_ROOT, "package.json"), "utf-8")).version;
+    assert.equal(manifest.sdkVersion, sdkVersion);
+    assert.equal(manifest.version, 1, "the manifest FORMAT version is untouched");
+
+    const result = JSON.parse(readFileSync(join(root, ".maestro/upgrade-result.json"), "utf-8"));
+    assert.equal(result.to, sdkVersion);
+    assert.equal(result.from, null, "no prior manifest → from is unknown");
+    assert.match(result.at, /^\d{4}-\d{2}-\d{2}T/);
+    assert.deepEqual(Object.keys(result.steps), ["plists", "launchd", "globalSetup", "globalInstall", "verify"]);
+    assert.equal(result.steps.plists.ok, true, result.steps.plists.detail);
+    assert.equal(result.steps.launchd.ok, true, result.steps.launchd.detail);
+    assert.equal(result.steps.globalSetup.ok, true, result.steps.globalSetup.detail);
+    assert.match(result.steps.globalInstall.detail, /MAESTRO_SKIP_GLOBAL_INSTALL/);
+    assert.match(r.stdout, /Seat reconcile/);
+
+    // global-setup ran for real against the throwaway HOME.
+    assert.match(readFileSync(join(home, ".claude", "CLAUDE.md"), "utf-8"), /BEGIN maestro:identity/);
+    assert.ok(existsSync(join(home, ".claude", "skills", "maestro-main-session", "SKILL.md")));
+
+    // Second run: from is the recorded version, the session job is unchanged.
+    const again = runCli(["upgrade"], root, baseEnv({ HOME: home }));
+    assert.equal(again.status, 0, again.stderr);
+    const result2 = JSON.parse(readFileSync(join(root, ".maestro/upgrade-result.json"), "utf-8"));
+    assert.equal(result2.from, sdkVersion);
+    assert.match(result2.steps.launchd.detail, /0 installed, 0 replaced/);
+    assert.match(result.steps.launchd.detail, /1 replaced/, "the pre-installed daemon plist is rewritten in place");
+  } finally { await rmRoot(root); await rmRoot(home); }
+});
+
+test("upgrade --verify exits 0 on a reconciled seat and 1 once a generated plist is missing; doctor prints the same rows; --dry-run runs no post-steps", async () => {
+  const root = await makeNamedLegacyAgent();
+  const home = await freshHome();
+  try {
+    const dry = runCli(["upgrade", "--dry-run"], root, baseEnv({ HOME: home }));
+    assert.equal(dry.status, 0, dry.stderr);
+    assert.ok(!existsSync(join(root, ".maestro/upgrade-result.json")), "--dry-run writes no result");
+    assert.ok(!existsSync(join(home, "Library", "LaunchAgents", "ai.maestro.legacy-session.plist")), "--dry-run installs nothing");
+
+    assert.equal(runCli(["upgrade"], root, baseEnv({ HOME: home })).status, 0);
+    const v = runCli(["upgrade", "--verify"], root, baseEnv({ HOME: home }));
+    assert.equal(v.status, 0, `verify should pass on a reconciled seat:\n${v.stdout}${v.stderr}`);
+    assert.match(v.stdout, /generated plist\(s\) installed and loaded/);
+    assert.match(v.stdout, /identity, MCP, settings, pointer and skills present/);
+    assert.match(v.stdout, /verify: seat is on/);
+
+    execFileSync("rm", [join(home, "Library", "LaunchAgents", "ai.maestro.legacy-session.plist")]);
+    const bad = runCli(["upgrade", "--verify"], root, baseEnv({ HOME: home }));
+    assert.equal(bad.status, 1);
+    assert.match(bad.stdout, /not installed: ai\.maestro\.legacy-session/);
+    assert.match(bad.stdout, /verify: MISMATCH \(plists\)/);
+
+    const d = runCli(["doctor"], root, baseEnv({ HOME: home }));
+    // doctor's fail() rows go to stderr; ok/warn to stdout.
+    assert.match(d.stdout + d.stderr, /not installed: ai\.maestro\.legacy-session/, `doctor carries the verify rows:\n${d.stdout.slice(-1500)}\n${d.stderr.slice(-1500)}`);
+  } finally { await rmRoot(root); await rmRoot(home); }
+});