@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/upgrade/verify.mjs

@@ -0,0 +1,215 @@
+/**
+ * lib/upgrade/verify.mjs — `maestro upgrade --verify` (design 2026-09-08,
+ * WP-M6 step 5): is this seat wholly on ONE SDK version, with the launchd job
+ * set and the global Claude Code config that version expects?
+ *
+ * The rows:
+ *   · global bin version  — `npm ls -g @cohortapp/agent-sdk`
+ *   · local package       — <agent>/node_modules/@cohortapp/agent-sdk/package.json
+ *   · shipped manifest    — .maestro/shipped-manifest.json `sdkVersion`
+ *   · running daemon      — state/dashboards/daemon-health.yaml `sdk_version`
+ *   · plists              — every generated label installed AND loaded
+ *   · global-setup        — identity block, collective block, cohort MCP entry,
+ *                           session settings, machine pointer, global skills
+ *
+ * `buildVerifyReport` is PURE over collected values; `collectVerifyInputs` is
+ * the edge (files + `npm ls -g` + `launchctl list`, all fail-open);
+ * `runVerify` glues them. A `fail` row is a mismatch → the CLI exits 1.
+ * `doctor` prints the same rows.
+ *
+ * @module lib/upgrade/verify
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createRequire } from "node:module";
+import { readGlobalVersion, SKIP_ENV, SDK_PACKAGE } from "./global-refresh.mjs";
+import { readLaunchdState, defaultExec } from "./launchd-reconcile.mjs";
+import { IDENTITY_BEGIN, CLAUDE_MD_BEGIN, mergeSessionSettings } from "../collective/global-config.mjs";
+import { GLOBAL_SKILL_PREFIX } from "../collective/global-skills.mjs";
+
+/** The skill every seat must carry for the front-door session to work. */
+export const REQUIRED_SKILL = "main-session";
+
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the two lines verify needs out of daemon-health.yaml. The dashboard
+ * is a flat `key: value` list at the top level (health.mjs).
+ * @param {string} yaml
+ * @returns {{version:string, updatedAt:string, pid:number|null}}
+ */
+export function parseDaemonHealth(yaml) {
+  const s = String(yaml || "");
+  const grab = (k) => { const m = s.match(new RegExp(`^${k}:\\s*(.+)$`, "m")); return m ? m[1].trim() : ""; };
+  const pid = Number(grab("pid"));
+  return { version: grab("sdk_version"), updatedAt: grab("updated"), pid: Number.isFinite(pid) && pid > 0 ? pid : null };
+}
+
+/**
+ * Build the report. Pure.
+ *
+ * @param {object} i
+ * @param {string} i.expected              the SDK version running verify
+ * @param {string} [i.globalVersion]       "" = not installed globally
+ * @param {boolean} [i.skipGlobal]         MAESTRO_SKIP_GLOBAL_INSTALL=1 → warn, not fail
+ * @param {string} [i.localVersion]        "" = no agent-dir dependency (framework checkout)
+ * @param {string} [i.manifestVersion]     "" = pre-2.12 manifest or none
+ * @param {boolean} [i.manifestPresent]
+ * @param {{version:string, updatedAt:string}} [i.daemon]
+ * @param {boolean} [i.daemonRestartPending]  true right after upgrade(): autoupdate restarts it next
+ * @param {{generated:string[], installed:string[], loaded:string[], launchctlOk?:boolean}} [i.plists]
+ * @param {{identityConfigured:boolean, identity:boolean, collective:boolean, mcp:boolean, settings:boolean, pointer:boolean, skills:boolean}} [i.markers]
+ * @returns {{ok:boolean, expected:string, rows:Array<{level:"ok"|"warn"|"fail", name:string, msg:string}>, mismatches:string[]}}
+ */
+export function buildVerifyReport(i = {}) {
+  const expected = String(i.expected || "").trim();
+  const rows = [];
+  const row = (level, name, msg) => rows.push({ level, name, msg });
+
+  // Global bin.
+  const g = String(i.globalVersion || "").trim();
+  if (g === expected && expected) row("ok", "global", `global ${SDK_PACKAGE} ${g} (maestro / cohort / cohort-mcp on PATH match the agent dir)`);
+  else if (i.skipGlobal) row("warn", "global", `global ${SDK_PACKAGE} ${g || "not installed"} vs ${expected} — ${SKIP_ENV}=1, refresh skipped on purpose`);
+  else if (!g) row("fail", "global", `${SDK_PACKAGE} is not installed globally — npm i -g ${SDK_PACKAGE}@${expected} --no-audit --no-fund`);
+  else row("fail", "global", `global ${SDK_PACKAGE} is ${g}, agent dir is ${expected} — npm i -g ${SDK_PACKAGE}@${expected} --no-audit --no-fund`);
+
+  // Local package.
+  const l = String(i.localVersion || "").trim();
+  if (!l) row("warn", "local", `no ${SDK_PACKAGE} under node_modules (a framework checkout runs its own code)`);
+  else if (l === expected) row("ok", "local", `agent dir ${SDK_PACKAGE} ${l}`);
+  else row("fail", "local", `agent dir ${SDK_PACKAGE} is ${l} but this upgrade is ${expected} — npm install ${SDK_PACKAGE}@${expected} --save`);
+
+  // Shipped manifest.
+  const m = String(i.manifestVersion || "").trim();
+  if (!i.manifestPresent) row("warn", "manifest", ".maestro/shipped-manifest.json absent — no upgrade has completed here yet");
+  else if (!m) row("warn", "manifest", ".maestro/shipped-manifest.json carries no sdkVersion (written by a pre-2.12 upgrade); the next upgrade records it");
+  else if (m === expected) row("ok", "manifest", `shipped manifest ${m}`);
+  else row("fail", "manifest", `shipped manifest says ${m}, expected ${expected} — the framework files on disk are from another version; run maestro upgrade`);
+
+  // Running daemon.
+  const d = i.daemon || {};
+  const dv = String(d.version || "").trim();
+  if (!dv) row("warn", "daemon", "daemon has not reported sdk_version (state/dashboards/daemon-health.yaml) — older daemon or not running yet");
+  else if (dv === expected) row("ok", "daemon", `running daemon ${dv}${d.updatedAt ? ` (health written ${d.updatedAt})` : ""}`);
+  else if (i.daemonRestartPending) row("warn", "daemon", `running daemon is ${dv}; ${expected} takes effect when autoupdate kickstarts it`);
+  else row("fail", "daemon", `running daemon is ${dv}, expected ${expected} — launchctl kickstart -k gui/$(id -u)/ai.maestro.<first>-daemon`);
+
+  // Plists.
+  const p = i.plists || {};
+  const gen = (p.generated || []);
+  const inst = new Set(p.installed || []);
+  const loaded = new Set(p.loaded || []);
+  if (gen.length === 0) row("warn", "plists", "no generated plists (scripts/local-triggers/plists is empty) — run scripts/local-triggers/generate-plists.sh");
+  else {
+    const missing = gen.filter((x) => !inst.has(x));
+    const unloaded = gen.filter((x) => inst.has(x) && !loaded.has(x));
+    if (missing.length) row("fail", "plists", `${missing.length} generated plist(s) not installed: ${missing.join(", ")} — run maestro upgrade (it installs them)`);
+    if (unloaded.length) {
+      if (p.launchctlOk === false) row("warn", "plists", `launchctl list unavailable — could not confirm ${unloaded.length} installed job(s) are loaded`);
+      else row("fail", "plists", `${unloaded.length} installed plist(s) not loaded: ${unloaded.join(", ")} — launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<label>.plist`);
+    }
+    if (!missing.length && !unloaded.length) row("ok", "plists", `${gen.length} generated plist(s) installed and loaded`);
+  }
+
+  // Global-setup markers.
+  const k = i.markers || {};
+  if (k.identityConfigured === false) row("warn", "global-setup", "identity block skipped: config/agent.json has no name yet (maestro setup)");
+  else if (!k.identity) row("fail", "global-setup", "~/.claude/CLAUDE.md has no maestro:identity block — maestro global-setup");
+  const rest = [["collective", "~/.claude/CLAUDE.md maestro:collective block"], ["mcp", "~/.claude.json cohort MCP server for this agent dir"], ["settings", "~/.claude/settings.json front-door additions"], ["pointer", "~/.claude/maestro-agent.json pointer to this agent dir"], ["skills", `~/.claude/skills/${GLOBAL_SKILL_PREFIX}${REQUIRED_SKILL}/SKILL.md`]];
+  const missingMarkers = rest.filter(([key]) => !k[key]).map(([, label]) => label);
+  if (missingMarkers.length) row("fail", "global-setup", `missing: ${missingMarkers.join("; ")} — maestro global-setup`);
+  else if (k.identity || k.identityConfigured === false) row("ok", "global-setup", "identity, MCP, settings, pointer and skills present");
+
+  const mismatches = rows.filter((r) => r.level === "fail").map((r) => r.name);
+  return { ok: mismatches.length === 0, expected, rows, mismatches: [...new Set(mismatches)] };
+}
+
+/** Render rows for a terminal. */
+export function formatVerifyReport(report) {
+  const mark = { ok: "✓", warn: "⚠", fail: "✗" };
+  const lines = report.rows.map((r) => `${mark[r.level] || "·"} ${r.msg}`);
+  lines.push(report.ok ? `verify: seat is on ${report.expected}` : `verify: MISMATCH (${report.mismatches.join(", ")})`);
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// Edge
+// ---------------------------------------------------------------------------
+
+function safeRead(p) { try { return readFileSync(p, "utf8"); } catch { return ""; /* absent → "" */ } }
+function safeJson(p) { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; /* absent/corrupt → null */ } }
+
+/** The agent dir's own @cohortapp/agent-sdk dependency version, "" when none. */
+export function readLocalVersion(cwd) {
+  try {
+    const req = createRequire(join(resolve(cwd), "package.json"));
+    const pkg = JSON.parse(readFileSync(req.resolve(`${SDK_PACKAGE}/package.json`), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "";
+  } catch {
+    // No agent package.json to resolve from (or the dep is not declared): read
+    // the node_modules copy directly; absent → "" and the row degrades to warn.
+    const p = join(resolve(cwd), "node_modules", ...SDK_PACKAGE.split("/"), "package.json");
+    const j = safeJson(p);
+    return j && typeof j.version === "string" ? j.version : "";
+  }
+}
+
+/**
+ * Read everything `buildVerifyReport` needs. Every read is fail-open.
+ * @param {{cwd:string, home?:string, env?:object, exec?:Function, expected:string, daemonRestartPending?:boolean}} o
+ */
+export function collectVerifyInputs(o = {}) {
+  const cwd = resolve(o.cwd || process.cwd());
+  const home = o.home || homedir();
+  const env = o.env || process.env;
+  const exec = o.exec || defaultExec;
+  const skipGlobal = String(env[SKIP_ENV] || "") === "1";
+  const claudeDir = join(home, ".claude");
+
+  const manifest = safeJson(join(cwd, ".maestro", "shipped-manifest.json"));
+  const daemon = parseDaemonHealth(safeRead(join(cwd, "state", "dashboards", "daemon-health.yaml")));
+  const plists = readLaunchdState({ generatedDir: join(cwd, "scripts", "local-triggers", "plists"), launchAgentsDir: join(home, "Library", "LaunchAgents"), exec });
+
+  const agentJson = safeJson(join(cwd, "config", "agent.json"));
+  const identityConfigured = !!(agentJson && (agentJson.fullName || agentJson.firstName));
+  const md = safeRead(join(claudeDir, "CLAUDE.md"));
+  const claudeJson = safeJson(join(home, ".claude.json"));
+  const mcpEntry = claudeJson && claudeJson.mcpServers && claudeJson.mcpServers.cohort;
+  const settings = safeJson(join(claudeDir, "settings.json"));
+  const pointer = safeJson(join(claudeDir, "maestro-agent.json"));
+  const markers = {
+    identityConfigured,
+    identity: md.includes(IDENTITY_BEGIN),
+    collective: md.includes(CLAUDE_MD_BEGIN),
+    mcp: !!(mcpEntry && mcpEntry.env && String(mcpEntry.env.COHORT_AGENT_ROOT || "") === cwd),
+    settings: !!settings && mergeSessionSettings(settings, { agentRoot: cwd }).changes.length === 0,
+    pointer: !!(pointer && String(pointer.agentRepo || "") === cwd),
+    skills: existsSync(join(claudeDir, "skills", `${GLOBAL_SKILL_PREFIX}${REQUIRED_SKILL}`, "SKILL.md")),
+  };
+
+  return {
+    expected: o.expected,
+    globalVersion: skipGlobal ? "" : readGlobalVersion({ exec }),
+    skipGlobal,
+    localVersion: readLocalVersion(cwd),
+    manifestPresent: !!manifest,
+    manifestVersion: manifest && typeof manifest.sdkVersion === "string" ? manifest.sdkVersion : "",
+    daemon,
+    daemonRestartPending: !!o.daemonRestartPending,
+    plists,
+    markers,
+  };
+}
+
+/** Collect + build. */
+export function runVerify(o = {}) {
+  return buildVerifyReport(collectVerifyInputs(o));
+}
+
+export default { buildVerifyReport, formatVerifyReport, collectVerifyInputs, runVerify, parseDaemonHealth, readLocalVersion, REQUIRED_SKILL };

package/lib/upgrade/verify.test.mjs

@@ -0,0 +1,164 @@
+/**
+ * verify.test.mjs — buildVerifyReport is pure; collectVerifyInputs reads a
+ * temp HOME + agent dir with a recorded exec (never the real npm/launchctl).
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { buildVerifyReport, formatVerifyReport, parseDaemonHealth, collectVerifyInputs, runVerify } from "./verify.mjs";
+import { IDENTITY_BEGIN, IDENTITY_END, CLAUDE_MD_BEGIN, CLAUDE_MD_END, mergeSessionSettings } from "../collective/global-config.mjs";
+
+const G = ["ai.maestro.ivy-daemon", "ai.maestro.ivy-session"];
+const allMarkers = { identityConfigured: true, identity: true, collective: true, mcp: true, settings: true, pointer: true, skills: true };
+
+function good(over = {}) {
+  return {
+    expected: "2.12.0", globalVersion: "2.12.0", localVersion: "2.12.0", manifestPresent: true, manifestVersion: "2.12.0",
+    daemon: { version: "2.12.0", updatedAt: "2026-09-08T12:00:00Z" },
+    plists: { generated: G, installed: G, loaded: G, launchctlOk: true }, markers: allMarkers, ...over,
+  };
+}
+
+const byName = (r) => Object.fromEntries(r.rows.map((x) => [x.name, x]));
+
+test("a seat wholly on the expected version is ok with no mismatches", () => {
+  const r = buildVerifyReport(good());
+  assert.equal(r.ok, true, JSON.stringify(r.rows));
+  assert.deepEqual(r.mismatches, []);
+  assert.ok(r.rows.every((x) => x.level === "ok"));
+  assert.match(formatVerifyReport(r).pop(), /seat is on 2\.12\.0/);
+});
+
+test("global bin behind → fail; under MAESTRO_SKIP_GLOBAL_INSTALL it is a warn", () => {
+  const r = buildVerifyReport(good({ globalVersion: "2.11.17" }));
+  assert.equal(r.ok, false);
+  assert.deepEqual(r.mismatches, ["global"]);
+  assert.match(byName(r).global.msg, /npm i -g @cohortapp\/agent-sdk@2\.12\.0 --no-audit --no-fund/);
+  const s = buildVerifyReport(good({ globalVersion: "", skipGlobal: true }));
+  assert.equal(s.ok, true);
+  assert.equal(byName(s).global.level, "warn");
+  assert.equal(buildVerifyReport(good({ globalVersion: "" })).mismatches[0], "global");
+});
+
+test("local / manifest / daemon: missing is a warn, a different version is a fail; daemonRestartPending downgrades the daemon row", () => {
+  assert.equal(byName(buildVerifyReport(good({ localVersion: "" }))).local.level, "warn");
+  assert.deepEqual(buildVerifyReport(good({ localVersion: "2.11.17" })).mismatches, ["local"]);
+  assert.equal(byName(buildVerifyReport(good({ manifestPresent: false }))).manifest.level, "warn");
+  assert.equal(byName(buildVerifyReport(good({ manifestVersion: "" }))).manifest.level, "warn");
+  assert.deepEqual(buildVerifyReport(good({ manifestVersion: "2.11.17" })).mismatches, ["manifest"]);
+  assert.equal(byName(buildVerifyReport(good({ daemon: { version: "" } }))).daemon.level, "warn");
+  assert.deepEqual(buildVerifyReport(good({ daemon: { version: "2.11.17" } })).mismatches, ["daemon"]);
+  const pending = buildVerifyReport(good({ daemon: { version: "2.11.17" }, daemonRestartPending: true }));
+  assert.equal(pending.ok, true);
+  assert.match(byName(pending).daemon.msg, /autoupdate kickstarts/);
+});
+
+test("plists: a generated label that is not installed, or installed but not loaded, is a fail naming the label", () => {
+  const notInstalled = buildVerifyReport(good({ plists: { generated: G, installed: [G[0]], loaded: [G[0]], launchctlOk: true } }));
+  assert.deepEqual(notInstalled.mismatches, ["plists"]);
+  assert.match(byName(notInstalled).plists.msg, /not installed: ai\.maestro\.ivy-session/);
+  const notLoaded = buildVerifyReport(good({ plists: { generated: G, installed: G, loaded: [G[0]], launchctlOk: true } }));
+  assert.match(byName(notLoaded).plists.msg, /not loaded: ai\.maestro\.ivy-session/);
+  const noLaunchctl = buildVerifyReport(good({ plists: { generated: G, installed: G, loaded: [], launchctlOk: false } }));
+  assert.equal(noLaunchctl.ok, true, "cannot prove loaded without launchctl → warn");
+  assert.equal(byName(buildVerifyReport(good({ plists: { generated: [], installed: [], loaded: [] } }))).plists.level, "warn");
+});
+
+test("global-setup markers: any missing marker is a fail; an unconfigured identity is a warn", () => {
+  const r = buildVerifyReport(good({ markers: { ...allMarkers, mcp: false, skills: false } }));
+  assert.deepEqual(r.mismatches, ["global-setup"]);
+  assert.match(byName(r)["global-setup"].msg, /cohort MCP server/);
+  assert.match(byName(r)["global-setup"].msg, /maestro-main-session\/SKILL\.md/);
+  const unconf = buildVerifyReport(good({ markers: { ...allMarkers, identityConfigured: false, identity: false } }));
+  assert.equal(unconf.ok, true);
+  assert.equal(unconf.rows.filter((x) => x.name === "global-setup")[0].level, "warn");
+  const noId = buildVerifyReport(good({ markers: { ...allMarkers, identity: false } }));
+  assert.equal(noId.ok, false);
+});
+
+test("parseDaemonHealth reads sdk_version / updated / pid from the flat YAML the daemon writes", () => {
+  const y = "updated: 2026-09-08T12:00:00.000Z\nuptime_s: 40\nsdk_version: 2.12.0\npid: 4242\ndispatcher:\n  {\n  }\n";
+  assert.deepEqual(parseDaemonHealth(y), { version: "2.12.0", updatedAt: "2026-09-08T12:00:00.000Z", pid: 4242 });
+  assert.deepEqual(parseDaemonHealth(""), { version: "", updatedAt: "", pid: null });
+});
+
+// ---------------------------------------------------------------------------
+// collectVerifyInputs — the edge over a temp HOME + agent dir
+// ---------------------------------------------------------------------------
+
+function seat({ version = "2.12.0", withSetup = true } = {}) {
+  const root = mkdtempSync(join(tmpdir(), "verify-"));
+  const cwd = join(root, "ivy-ai");
+  const home = join(root, "home");
+  const claudeDir = join(home, ".claude");
+  mkdirSync(join(cwd, "config"), { recursive: true });
+  mkdirSync(join(cwd, "node_modules", "@cohortapp", "agent-sdk"), { recursive: true });
+  mkdirSync(join(cwd, ".maestro"), { recursive: true });
+  mkdirSync(join(cwd, "state", "dashboards"), { recursive: true });
+  mkdirSync(join(cwd, "scripts", "local-triggers", "plists"), { recursive: true });
+  mkdirSync(join(home, "Library", "LaunchAgents"), { recursive: true });
+  mkdirSync(join(claudeDir, "skills", "maestro-main-session"), { recursive: true });
+  writeFileSync(join(cwd, "config", "agent.json"), JSON.stringify({ firstName: "Ivy", fullName: "Ivy Tester" }));
+  writeFileSync(join(cwd, "package.json"), JSON.stringify({ name: "ivy-ai" }));
+  writeFileSync(join(cwd, "node_modules", "@cohortapp", "agent-sdk", "package.json"), JSON.stringify({ name: "@cohortapp/agent-sdk", version }));
+  writeFileSync(join(cwd, ".maestro", "shipped-manifest.json"), JSON.stringify({ version: 1, sdkVersion: version, files: [] }));
+  writeFileSync(join(cwd, "state", "dashboards", "daemon-health.yaml"), `updated: 2026-09-08T12:00:00Z\nsdk_version: ${version}\n`);
+  for (const l of G) {
+    writeFileSync(join(cwd, "scripts", "local-triggers", "plists", `${l}.plist`), `<plist>${l}</plist>`);
+    writeFileSync(join(home, "Library", "LaunchAgents", `${l}.plist`), `<plist>${l}</plist>`);
+  }
+  if (withSetup) {
+    writeFileSync(join(claudeDir, "CLAUDE.md"), `${CLAUDE_MD_BEGIN}\nx\n${CLAUDE_MD_END}\n${IDENTITY_BEGIN}\nid\n${IDENTITY_END}\n`);
+    writeFileSync(join(home, ".claude.json"), JSON.stringify({ mcpServers: { cohort: { command: "cohort-mcp", args: [], env: { COHORT_AGENT_ROOT: cwd } } } }));
+    writeFileSync(join(claudeDir, "settings.json"), JSON.stringify(mergeSessionSettings({}, { agentRoot: cwd }).settings));
+    writeFileSync(join(claudeDir, "maestro-agent.json"), JSON.stringify({ agentRepo: cwd }));
+    writeFileSync(join(claudeDir, "skills", "maestro-main-session", "SKILL.md"), "# skill");
+  }
+  return { root, cwd, home };
+}
+
+function execFor({ globalVersion = "2.12.0", loaded = G } = {}) {
+  const calls = [];
+  const exec = (cmd, args) => {
+    calls.push([cmd, ...args]);
+    if (cmd === "npm") return { status: 0, stdout: JSON.stringify({ dependencies: { "@cohortapp/agent-sdk": { version: globalVersion } } }), stderr: "" };
+    if (cmd === "launchctl") return { status: 0, stdout: `PID\tStatus\tLabel\n${loaded.map((l) => `1\t0\t${l}`).join("\n")}\n`, stderr: "" };
+    return { status: 1, stdout: "", stderr: "" };
+  };
+  exec.calls = calls;
+  return exec;
+}
+
+test("collectVerifyInputs reads a fully-set-up seat as all-ok; runVerify agrees", () => {
+  const s = seat();
+  try {
+    const exec = execFor();
+    const inputs = collectVerifyInputs({ cwd: s.cwd, home: s.home, env: {}, exec, expected: "2.12.0" });
+    assert.equal(inputs.globalVersion, "2.12.0");
+    assert.equal(inputs.localVersion, "2.12.0");
+    assert.equal(inputs.manifestVersion, "2.12.0");
+    assert.equal(inputs.daemon.version, "2.12.0");
+    assert.deepEqual(inputs.plists.generated.sort(), G);
+    assert.deepEqual(inputs.markers, { identityConfigured: true, identity: true, collective: true, mcp: true, settings: true, pointer: true, skills: true });
+    const r = runVerify({ cwd: s.cwd, home: s.home, env: {}, exec, expected: "2.12.0" });
+    assert.equal(r.ok, true, JSON.stringify(r.rows));
+    assert.ok(exec.calls.some((c) => c[0] === "npm" && c[1] === "ls" && c[2] === "-g"));
+  } finally { rmSync(s.root, { recursive: true, force: true }); }
+});
+
+test("collectVerifyInputs: a seat with no global-setup and a stale global bin reports both mismatches; MAESTRO_SKIP_GLOBAL_INSTALL skips the npm read", () => {
+  const s = seat({ withSetup: false });
+  try {
+    const exec = execFor({ globalVersion: "2.11.17", loaded: [G[0]] });
+    const r = runVerify({ cwd: s.cwd, home: s.home, env: {}, exec, expected: "2.12.0" });
+    assert.equal(r.ok, false);
+    assert.deepEqual(r.mismatches.sort(), ["global", "global-setup", "plists"]);
+    const skipExec = execFor();
+    const inputs = collectVerifyInputs({ cwd: s.cwd, home: s.home, env: { MAESTRO_SKIP_GLOBAL_INSTALL: "1" }, exec: skipExec, expected: "2.12.0" });
+    assert.equal(inputs.skipGlobal, true);
+    assert.ok(!skipExec.calls.some((c) => c[0] === "npm"), "no npm call under the skip flag");
+  } finally { rmSync(s.root, { recursive: true, force: true }); }
+});

package/lib/voice/outbound.mjs

@@ -29,6 +29,7 @@
  */
 
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
+import { writeJsonAtomic } from "../fs-atomic.mjs";
 import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { synthesizeSpeech, pickDefaultVoice, ttsCostEstimate } from "./tts.mjs";
@@ -335,14 +336,14 @@ export async function placeOutboundCall(opts = {}) {
   // Persist brief locally (always — for audit + later post-call processing)
   const briefsDir = join(agentRoot, "state/voice/outbound-briefs");
   mkdirSync(briefsDir, { recursive: true });
-  writeFileSync(join(briefsDir, `${callId}.json`), JSON.stringify({
+  writeJsonAtomic(join(briefsDir, `${callId}.json`), {
     call_id: callId,
     to: opts.to,
     brief: opts.brief,
     voice: opts.voice || "cedar",
     transport,
     created_at: new Date().toISOString(),
-  }, null, 2));
+  });
 
   // For media_streams, we use URL-based TwiML — Twilio fetches the TwiML
   // from /twilio/twiml when the call connects, instead of us passing it

package/lib/voice/post-call-brief.mjs

@@ -36,6 +36,7 @@
 import { spawn } from "node:child_process";
 import { writeFileSync, readFileSync, mkdirSync, existsSync, appendFileSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
+import { writeJsonAtomic } from "../fs-atomic.mjs";
 
 const BRIEF_PROMPT = `You are an executive operator processing the transcript of a voice call.
 Produce a structured post-call brief in JSON only — no preamble, no commentary.
@@ -145,7 +146,7 @@ export async function generateBrief(opts = {}) {
   const mdPath = join(briefDir, `${date}-${safeCallId}.md`);
   const jsonPath = join(briefDir, `${date}-${safeCallId}.json`);
   writeFileSync(mdPath, briefMd);
-  writeFileSync(jsonPath, JSON.stringify(briefJson, null, 2));
+  writeJsonAtomic(jsonPath, briefJson);
 
   // Push extracted action items to action-stack queue (best-effort)
   await pushActionItems({ agentRoot, brief: briefJson, callId, peer });

package/lib/voice/session-rotation.mjs

@@ -38,16 +38,21 @@ export const SESSION_ROTATION_DEFAULTS = Object.freeze({
  *     recent_latencies_ms: number[],   // last N turn latencies
  *   }
  * @param {object} opts  Optional overrides for the defaults.
+ * @param {number} [opts.now]  Injectable clock (ms epoch); defaults to Date.now().
  * @returns {{ rotate: boolean, reason?: string }}
  */
 export function shouldRotate(state, opts = {}) {
   const cfg = { ...SESSION_ROTATION_DEFAULTS, ...opts };
   if (!state) return { rotate: false };
+  // The clock is an input: without it the max_duration rule could only be
+  // exercised by waiting out a real session. Defaulted, so every existing
+  // caller is unchanged.
+  const now = typeof opts.now === "number" ? opts.now : Date.now();
 
   if ((state.turns || 0) >= cfg.max_turns) {
     return { rotate: true, reason: "max_turns" };
   }
-  const ageMs = Date.now() - (state.started_at || Date.now());
+  const ageMs = now - (state.started_at || now);
   if (ageMs >= cfg.max_duration_ms) {
     return { rotate: true, reason: "max_duration" };
   }

package/lib/voice/session-rotation.test.mjs

@@ -0,0 +1,114 @@
+/**
+ * Tests for shouldRotate — the voice-session rotation decision.
+ *
+ * These tests exist because the clock became an argument. Before that, the
+ * `max_duration` rule read `Date.now()` internally, so the only way to observe
+ * it firing was to hold a real voice session open for four minutes. That is not
+ * a test anyone writes, which is why there were none.
+ *
+ * @module lib/voice/session-rotation.test
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  shouldRotate,
+  SESSION_ROTATION_DEFAULTS,
+} from "./session-rotation.mjs";
+
+const T0 = 1_700_000_000_000; // a fixed instant; any would do
+const { max_duration_ms: MAX_MS, max_turns: MAX_TURNS } = SESSION_ROTATION_DEFAULTS;
+
+/** A session started at T0 with no turns and no latency history. */
+const fresh = (over = {}) => ({
+  turns: 0,
+  started_at: T0,
+  recent_latencies_ms: [],
+  ...over,
+});
+
+describe("shouldRotate: no state", () => {
+  it("does not rotate when there is no session", () => {
+    assert.deepEqual(shouldRotate(null), { rotate: false });
+    assert.deepEqual(shouldRotate(undefined), { rotate: false });
+  });
+});
+
+describe("shouldRotate: the duration boundary", () => {
+  it("holds one millisecond before the limit", () => {
+    const r = shouldRotate(fresh(), { now: T0 + MAX_MS - 1 });
+    assert.equal(r.rotate, false);
+  });
+
+  it("rotates exactly ON the limit", () => {
+    const r = shouldRotate(fresh(), { now: T0 + MAX_MS });
+    assert.deepEqual(r, { rotate: true, reason: "max_duration" });
+  });
+
+  it("rotates well past the limit", () => {
+    const r = shouldRotate(fresh(), { now: T0 + MAX_MS * 10 });
+    assert.equal(r.reason, "max_duration");
+  });
+
+  it("honours an overridden limit", () => {
+    const r = shouldRotate(fresh(), { now: T0 + 100, max_duration_ms: 50 });
+    assert.deepEqual(r, { rotate: true, reason: "max_duration" });
+  });
+
+  it("treats a missing started_at as age zero rather than as epoch", () => {
+    // The pre-existing semantics: `now - (started_at || now)` === 0. Pinned so a
+    // future refactor cannot silently turn an unknown start into a 55-year age.
+    const r = shouldRotate({ turns: 0, recent_latencies_ms: [] }, { now: T0 });
+    assert.equal(r.rotate, false);
+  });
+});
+
+describe("shouldRotate: turn count takes precedence", () => {
+  it("rotates on max_turns even inside the duration window", () => {
+    const r = shouldRotate(fresh({ turns: MAX_TURNS }), { now: T0 });
+    assert.deepEqual(r, { rotate: true, reason: "max_turns" });
+  });
+
+  it("holds one turn below the limit", () => {
+    assert.equal(shouldRotate(fresh({ turns: MAX_TURNS - 1 }), { now: T0 }).rotate, false);
+  });
+
+  it("reports max_turns, not max_duration, when both are exceeded", () => {
+    const r = shouldRotate(fresh({ turns: MAX_TURNS }), { now: T0 + MAX_MS * 5 });
+    assert.equal(r.reason, "max_turns");
+  });
+});
+
+describe("shouldRotate: latency drift", () => {
+  it("ignores latency until there are five samples", () => {
+    const slow = [9999, 9999, 9999, 9999];
+    assert.equal(shouldRotate(fresh({ recent_latencies_ms: slow }), { now: T0 }).rotate, false);
+  });
+
+  it("rotates once five samples drift past p95", () => {
+    const slow = [9999, 9999, 9999, 9999, 9999];
+    const r = shouldRotate(fresh({ recent_latencies_ms: slow }), { now: T0 });
+    assert.deepEqual(r, { rotate: true, reason: "latency_drift" });
+  });
+
+  it("does not rotate on five fast samples", () => {
+    const fast = [10, 12, 11, 9, 13];
+    assert.equal(shouldRotate(fresh({ recent_latencies_ms: fast }), { now: T0 }).rotate, false);
+  });
+});
+
+describe("shouldRotate: determinism", () => {
+  it("is a pure function of (state, opts) — same inputs, same answer", () => {
+    const state = fresh({ turns: 3, recent_latencies_ms: [10, 20, 30, 40, 50] });
+    const a = shouldRotate(state, { now: T0 + 1000 });
+    const b = shouldRotate(state, { now: T0 + 1000 });
+    assert.deepEqual(a, b);
+  });
+
+  it("does not mutate the state it is given", () => {
+    const state = fresh({ turns: 2, recent_latencies_ms: [5, 4, 3, 2, 1] });
+    const before = JSON.stringify(state);
+    shouldRotate(state, { now: T0 + 5 });
+    assert.equal(JSON.stringify(state), before);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.11.15",
+  "version": "2.13.0",
   "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {
@@ -121,7 +121,7 @@
   "scripts": {
     "test": "node scripts/ci/run-tests.mjs",
     "test:coverage": "node scripts/ci/run-coverage.mjs",
-    "test:list": "node --test bin/maestro.test.mjs lib/action-executor.test.mjs lib/archetype.test.mjs lib/autonomy.test.mjs lib/backlog.test.mjs lib/budget-guard.test.mjs lib/cadence-bus-schedule.test.mjs lib/cadence-bus.test.mjs lib/cadences.test.mjs lib/capability.test.mjs lib/channels/base-adapter.test.mjs lib/channels/channels.test.mjs lib/channels/contract.test.mjs lib/channels/inbox-item.test.mjs lib/channels/pairing.test.mjs lib/channels/slack-adapter.test.mjs lib/channels/telegram-adapter.test.mjs lib/channels/whatsapp/baileys-typing.test.mjs lib/charter.test.mjs lib/claude-bin.test.mjs lib/collective/capture.test.mjs lib/collective/cards.test.mjs lib/collective/config.test.mjs lib/collective/global-config.test.mjs lib/collective/presence.test.mjs lib/collective/recall.test.mjs lib/comms.test.mjs lib/fs-atomic.test.mjs lib/fs-ownership.test.mjs lib/learning/config.test.mjs lib/learning/counters.test.mjs lib/learning/curator-consolidate.test.mjs lib/learning/curator.test.mjs lib/learning/reflect.test.mjs lib/learning/session-index.test.mjs lib/learning/skill-writer.test.mjs lib/model-router.test.mjs lib/model-router/catalog.test.mjs lib/model-router/economics.test.mjs lib/model-router/failover.test.mjs lib/model-router/health.test.mjs lib/model-router/integration.test.mjs lib/model-router/integration-coverage.test.mjs lib/model-router/ledger.test.mjs lib/model-router/llm-task.test.mjs lib/model-router/org-credentials.test.mjs lib/model-router/reconcile.test.mjs lib/model-router/repair.test.mjs lib/model-router/spawn.test.mjs lib/model-router/taxonomy.test.mjs lib/org/approvals.test.mjs lib/org/board.test.mjs lib/org/client.test.mjs lib/org/cost-sync.test.mjs lib/org/handoff.test.mjs lib/org/keys.test.mjs lib/org/knowledge.test.mjs lib/org/activity.test.mjs lib/org/leases.test.mjs lib/org/mesh.test.mjs lib/org/messaging.test.mjs lib/org/cohort-client.test.mjs lib/org/policy.test.mjs lib/org/registry.test.mjs lib/org/tool-surface.test.mjs lib/org/ui-parity.test.mjs lib/org/doctor.test.mjs lib/org/verify.test.mjs lib/mcp/server.test.mjs lib/channels/orgmail/adapter.test.mjs lib/rag/rag.test.mjs lib/rate-guard.test.mjs lib/render.test.mjs lib/resource-governor.test.mjs lib/security/coerce-args.test.mjs lib/security/dangerous-tools.test.mjs lib/security/external-content.test.mjs lib/security/redact.test.mjs lib/security/secret-equal.test.mjs lib/session-permissions.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/enroll-from-cohort.test.mjs lib/setup/integration.test.mjs lib/setup/io.test.mjs lib/setup/runner.test.mjs lib/setup/sections/identity.test.mjs lib/setup/sections/learning.test.mjs lib/setup/sections/messaging.test.mjs lib/setup/sections/org.test.mjs lib/setup/sections/orgmail.test.mjs lib/setup/sections/recovery.test.mjs lib/setup/sections/subagents.test.mjs lib/setup/sot.test.mjs lib/setup/state.test.mjs lib/singleton.test.mjs lib/subagents/schema.test.mjs lib/subagents/refs.test.mjs lib/subagents/manifest.test.mjs lib/subagents/lock.test.mjs lib/subagents/resolve.test.mjs lib/subagents/gap.test.mjs lib/subagents/client.test.mjs lib/subagents/cli.test.mjs lib/telemetry/alerts.test.mjs lib/telemetry/collect.test.mjs lib/tool-definitions.test.mjs lib/voice/outbound.test.mjs lib/voice/stt.test.mjs lib/voice/voice.test.mjs scripts/cadence/enqueue-cadence-tick.test.mjs scripts/ci/check-no-build-artifacts.test.mjs scripts/ci/check-no-residual-identity.test.mjs scripts/ci/check.test.mjs scripts/collective/hook-runner.test.mjs scripts/cost/fleet-digest.test.mjs scripts/daemon/cadence-consumer-governance.test.mjs scripts/daemon/cadence-consumer.test.mjs scripts/daemon/cadence-handlers.test.mjs scripts/daemon/classify-kind.test.mjs scripts/daemon/dispatcher-cooldown.test.mjs scripts/daemon/dispatcher-governance.test.mjs scripts/daemon/inbox-deferral.test.mjs scripts/daemon/lib/session-router.test.mjs scripts/daemon/prompt-builder.test.mjs scripts/daemon/typing-registry.test.mjs scripts/hooks/pre-send-audit.test.mjs scripts/local-triggers/generate-plists.test.mjs scripts/poller/inbox-scan-poller.test.mjs scripts/poller/lib/cloud-relay-dedup.test.mjs scripts/poller/slack-socket-mode.test.mjs scripts/setup/gen-subagent-manifest.test.mjs scripts/setup/init-agent.test.mjs services/webhook-relay/server.test.mjs",
+    "test:list": "node --test bin/maestro.test.mjs lib/action-executor.test.mjs lib/archetype.test.mjs lib/autonomy.test.mjs lib/backlog.test.mjs lib/budget-guard.test.mjs lib/cadence-bus-schedule.test.mjs lib/cadence-bus.test.mjs lib/cadences.test.mjs lib/capability.test.mjs lib/channels/base-adapter.test.mjs lib/channels/channels.test.mjs lib/channels/contract.test.mjs lib/channels/inbox-item.test.mjs lib/channels/pairing.test.mjs lib/channels/slack-adapter.test.mjs lib/channels/telegram-adapter.test.mjs lib/channels/whatsapp/baileys-typing.test.mjs lib/charter.test.mjs lib/claude-bin.test.mjs lib/collective/capture.test.mjs lib/collective/cards.test.mjs lib/collective/config.test.mjs lib/collective/global-config.test.mjs lib/collective/presence.test.mjs lib/collective/recall.test.mjs lib/comms.test.mjs lib/fs-atomic.test.mjs lib/fs-ownership.test.mjs lib/learning/config.test.mjs lib/learning/counters.test.mjs lib/learning/curator-consolidate.test.mjs lib/learning/curator.test.mjs lib/learning/reflect.test.mjs lib/learning/session-index.test.mjs lib/learning/skill-writer.test.mjs lib/model-router.test.mjs lib/model-router/catalog.test.mjs lib/model-router/economics.test.mjs lib/model-router/failover.test.mjs lib/model-router/health.test.mjs lib/model-router/integration.test.mjs lib/model-router/integration-coverage.test.mjs lib/model-router/ledger.test.mjs lib/model-router/llm-task.test.mjs lib/model-router/org-credentials.test.mjs lib/model-router/reconcile.test.mjs lib/model-router/repair.test.mjs lib/model-router/spawn.test.mjs lib/model-router/taxonomy.test.mjs lib/org/approvals.test.mjs lib/org/board.test.mjs lib/org/client.test.mjs lib/org/cost-sync.test.mjs lib/org/handoff.test.mjs lib/org/keys.test.mjs lib/org/knowledge.test.mjs lib/org/activity.test.mjs lib/org/leases.test.mjs lib/org/mesh.test.mjs lib/org/messaging.test.mjs lib/org/cohort-client.test.mjs lib/org/policy.test.mjs lib/org/registry.test.mjs lib/org/tool-surface.test.mjs lib/org/ui-parity.test.mjs lib/org/doctor.test.mjs lib/org/verify.test.mjs lib/mcp/server.test.mjs lib/channels/orgmail/adapter.test.mjs lib/rag/rag.test.mjs lib/rate-guard.test.mjs lib/render.test.mjs lib/resource-governor.test.mjs lib/security/coerce-args.test.mjs lib/security/dangerous-tools.test.mjs lib/security/external-content.test.mjs lib/security/redact.test.mjs lib/security/secret-equal.test.mjs lib/session-permissions.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/enroll-from-cohort.test.mjs lib/setup/integration.test.mjs lib/setup/io.test.mjs lib/setup/runner.test.mjs lib/setup/sections/identity.test.mjs lib/setup/sections/learning.test.mjs lib/setup/sections/messaging.test.mjs lib/setup/sections/org.test.mjs lib/setup/sections/orgmail.test.mjs lib/setup/sections/recovery.test.mjs lib/setup/sections/subagents.test.mjs lib/setup/sot.test.mjs lib/setup/state.test.mjs lib/singleton.test.mjs lib/subagents/schema.test.mjs lib/subagents/refs.test.mjs lib/subagents/manifest.test.mjs lib/subagents/lock.test.mjs lib/subagents/resolve.test.mjs lib/subagents/gap.test.mjs lib/subagents/client.test.mjs lib/subagents/cli.test.mjs lib/telemetry/alerts.test.mjs lib/telemetry/collect.test.mjs lib/tool-definitions.test.mjs lib/voice/session-rotation.test.mjs lib/voice/outbound.test.mjs lib/voice/stt.test.mjs lib/voice/voice.test.mjs scripts/cadence/enqueue-cadence-tick.test.mjs scripts/ci/check-durable-write-seam.test.mjs scripts/ci/check-no-build-artifacts.test.mjs scripts/ci/check-no-residual-identity.test.mjs scripts/ci/check.test.mjs scripts/collective/hook-runner.test.mjs scripts/cost/fleet-digest.test.mjs scripts/daemon/cadence-consumer-governance.test.mjs scripts/daemon/cadence-consumer.test.mjs scripts/daemon/cadence-handlers.test.mjs scripts/daemon/classify-kind.test.mjs scripts/daemon/dispatcher-cooldown.test.mjs scripts/daemon/dispatcher-governance.test.mjs scripts/daemon/inbox-deferral.test.mjs scripts/daemon/lib/session-router.test.mjs scripts/daemon/prompt-builder.test.mjs scripts/daemon/typing-registry.test.mjs scripts/hooks/pre-send-audit.test.mjs scripts/local-triggers/generate-plists.test.mjs scripts/poller/inbox-scan-poller.test.mjs scripts/poller/lib/cloud-relay-dedup.test.mjs scripts/poller/slack-socket-mode.test.mjs scripts/setup/gen-subagent-manifest.test.mjs scripts/setup/init-agent.test.mjs services/webhook-relay/server.test.mjs lib/cadence-bus-requeue.test.mjs lib/cli/inbox.test.mjs lib/cli/session-ack.test.mjs lib/org/mesh-directives.test.mjs lib/session/frontdoor.test.mjs lib/session/handoffs.test.mjs lib/session/inbox-claims.test.mjs scripts/daemon/agent-daemon-frontdoor.test.mjs scripts/daemon/cadence-consumer-frontdoor.test.mjs scripts/daemon/dispatcher-resume.test.mjs scripts/daemon/inbox-deferral-session.test.mjs scripts/watchdog/memory-watchdog.test.mjs lib/upgrade/launchd-reconcile.test.mjs lib/upgrade/global-refresh.test.mjs lib/upgrade/verify.test.mjs lib/upgrade/post-steps.test.mjs lib/org/board-mine-cache.test.mjs scripts/daemon/agent-daemon-board-mine.test.mjs scripts/local-triggers/autoupdate.test.mjs scripts/daemon/sdk-version.test.mjs",
     "test:setup": "node --test lib/setup/io.test.mjs lib/setup/state.test.mjs lib/setup/sot.test.mjs lib/setup/completeness.test.mjs lib/setup/context-pack.test.mjs lib/setup/enrich.test.mjs lib/setup/runner.test.mjs lib/setup/integration.test.mjs lib/setup/sections/subagents.test.mjs",
     "check": "node scripts/ci/check.mjs",
     "conformance:org": "node scripts/ci/conformance-org-api.mjs",
@@ -136,7 +136,7 @@
     "test:org": "node --test $(find lib/org -name '*.test.mjs')",
     "test:pack": "node scripts/ci/check-tarball-fidelity.mjs",
     "test:plists": "node --test scripts/local-triggers/generate-plists.test.mjs",
-    "prepublishOnly": "echo 'Publishing @cohortapp/agent-sdk...'"
+    "prepublishOnly": "npm run check && npm test && npm run test:pack"
   },
   "engines": {
     "node": ">=20.0.0"