@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/scripts/local-triggers/autoupdate.test.mjs

@@ -0,0 +1,518 @@
+/**
+ * autoupdate.test.mjs — scripts/local-triggers/autoupdate.sh
+ *
+ * Front-door session design §3.10: a fleet upgrade must NOT kill the agent's
+ * main interactive session. After a successful, health-gated upgrade the
+ * script writes state/session/upgrade-notice.json {from,to,at}; the session's
+ * feed surfaces it as a directive and the session restarts ITSELF at an idle
+ * moment (`maestro session restart`). The daemon health gate + rollback stay
+ * exactly as before.
+ *
+ * Everything the script shells out to (npm, launchctl, pgrep) is a stub on
+ * PATH that logs its argv; `node` is the real one (the script uses `node -p`
+ * to read the installed version). Jitter and the health wait are zeroed via
+ * the MAESTRO_AUTOUPDATE_JITTER_MAX / MAESTRO_AUTOUPDATE_HEALTH_WAIT knobs.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, chmodSync, rmSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(__dirname, "autoupdate.sh");
+const scriptSrc = readFileSync(SCRIPT, "utf8");
+
+/**
+ * Today, in the SAME basis the code under test uses: `date +%Y-%m-%d`, which is
+ * LOCAL. Both log files this suite fabricates are read back by shell that names
+ * them that way — `autoupdate.sh` for its own log, and for the daemon log the
+ * health gate tails (which `scripts/daemon/launchd-wrapper.sh` also writes with
+ * local `date`).
+ *
+ * This used to be `new Date().toISOString().slice(0, 10)` — UTC — and the two
+ * agree for exactly as long as the machine sits at or west of Greenwich. On a
+ * UTC+4 developer machine they diverge from 20:00 to midnight local, so the
+ * fixture wrote `daemon-<yesterday>.log`, the health gate looked for
+ * `daemon-<today>.log`, found nothing, and all twelve upgrade cases failed with
+ * "UNHEALTHY … ROLLBACK" — a four-hour window each evening in which a green
+ * suite turned red with no code change. Keep the basis matched to the shell.
+ */
+function localDay(d = new Date()) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+function stub(bin, name, body) {
+  writeFileSync(join(bin, name), `#!/bin/bash\n${body}\n`);
+  chmodSync(join(bin, name), 0o755);
+}
+
+/**
+ * Build a fixture: an agent dir with the SDK "installed" at 1.0.0, a healthy
+ * daemon log, a HOME with daemon + session plists, and stubs for npm/launchctl/pgrep.
+ */
+function fixture({ latest = "2.0.0", healthy = true, supervisorAlive = true, sessionPlist = false, loadedLabels = ["ai.maestro.ivy-daemon"], npmViewFailures = 0, npmInstallFailures = 0, firstName = null, installedSessionPlist = true } = {}) {
+  const root = mkdtempSync(join(tmpdir(), "autoupdate-test-"));
+  const agent = join(root, "agent");
+  const home = join(root, "home");
+  const bin = join(root, "bin");
+  const log = join(root, "calls.log");
+  mkdirSync(join(agent, "node_modules", "@cohortapp", "agent-sdk", "bin"), { recursive: true });
+  mkdirSync(join(agent, "logs", "daemon"), { recursive: true });
+  mkdirSync(join(agent, "scripts", "local-triggers"), { recursive: true });
+  mkdirSync(join(home, "Library", "LaunchAgents"), { recursive: true });
+  mkdirSync(bin, { recursive: true });
+
+  writeFileSync(join(agent, "node_modules", "@cohortapp", "agent-sdk", "package.json"), JSON.stringify({ version: "1.0.0" }));
+  writeFileSync(join(agent, "node_modules", "@cohortapp", "agent-sdk", "bin", "maestro.mjs"), "process.exit(0);\n");
+  const day = localDay();
+  writeFileSync(join(agent, "logs", "daemon", `daemon-${day}.log`), "[daemon] Running\n");
+  writeFileSync(join(home, "Library", "LaunchAgents", "ai.maestro.ivy-daemon.plist"), "<plist/>");
+  if (installedSessionPlist) writeFileSync(join(home, "Library", "LaunchAgents", "ai.maestro.ivy-session.plist"), "<plist/>");
+  writeFileSync(join(agent, "scripts", "local-triggers", "autoupdate.sh"), scriptSrc);
+  if (firstName) { mkdirSync(join(agent, "config"), { recursive: true }); writeFileSync(join(agent, "config", "agent.json"), JSON.stringify({ firstName })); }
+  // A generated -session plist (what the NEW upgrade renders) turns the
+  // session half of the health gate on.
+  mkdirSync(join(agent, "scripts", "local-triggers", "plists"), { recursive: true });
+  if (sessionPlist) writeFileSync(join(agent, "scripts", "local-triggers", "plists", "ai.maestro.ivy-session.plist"), "<plist/>");
+
+  // npm: `view <pkg> version` prints latest; `install <pkg>@v` bumps the
+  // installed package.json to the requested version (so a rollback is
+  // observable); `install -g …` only logs. The first N view/install calls can
+  // be made to fail so the retry/backoff path is observable.
+  stub(bin, "npm", `echo "npm $*" >> "${log}"
+count(){ grep -c "^npm $1" "${log}" 2>/dev/null || echo 0; }
+if [ "$1" = "view" ]; then
+  if [ "$(count view)" -le ${npmViewFailures} ]; then echo "npm ERR! network" >&2; exit 1; fi
+  echo "${latest}"; exit 0
+fi
+if [ "$1" = "install" ]; then
+  if [ "$2" = "-g" ]; then exit 0; fi
+  if [ "$(count install)" -le ${npmInstallFailures} ]; then echo "npm ERR! network" >&2; exit 1; fi
+  v="\${2##*@}"
+  printf '{"version":"%s"}' "$v" > "${join(agent, "node_modules", "@cohortapp", "agent-sdk", "package.json")}"
+  exit 0
+fi
+exit 0`);
+  // launchctl: `list` prints the loaded labels; `print gui/<uid>/<label>`
+  // answers per label the way launchd does; everything else only logs.
+  stub(bin, "launchctl", `echo "launchctl $*" >> "${log}"
+if [ "$1" = "list" ]; then
+  if [ -n "\${2:-}" ]; then for k in ${loadedLabels.join(" ")}; do [ "$k" = "$2" ] && exit 0; done; exit 113; fi
+  printf 'PID\tStatus\tLabel\n'; for l in ${loadedLabels.join(" ")}; do printf -- '-\t0\t%s\n' "$l"; done
+fi
+if [ "$1" = "print" ]; then l="\${2##*/}"; for k in ${loadedLabels.join(" ")}; do [ "$k" = "$l" ] && { echo "$l = {}"; exit 0; }; done; echo "Could not find service \"$l\" in domain for user gui: 501" >&2; exit 113; fi
+exit 0`);
+  // pgrep: the daemon pattern answers \`healthy\`; the supervisor pattern answers \`supervisorAlive\`.
+  stub(bin, "pgrep", `echo "pgrep $*" >> "${log}"
+case "$*" in *supervisor*) exit ${supervisorAlive ? 0 : 1} ;; esac
+exit ${healthy ? 0 : 1}`);
+  // Any kill-ish tool reaching a stub is a test failure signal, not a no-op.
+  for (const k of ["pkill", "kill", "killall"]) stub(bin, k, `echo "${k} $*" >> "${log}"; exit 0`);
+
+  return { root, agent, home, bin, log };
+}
+
+function run(fx, extraEnv) {
+  return spawnSync("/bin/bash", [join(fx.agent, "scripts", "local-triggers", "autoupdate.sh")], {
+    encoding: "utf8",
+    env: {
+      HOME: fx.home,
+      AGENT_ROOT: fx.agent,
+      PATH: `${fx.bin}:${dirname(process.execPath)}:/usr/bin:/bin`,
+      MAESTRO_AUTOUPDATE_REEXEC: "1",
+      // The script prepends the standard tool dirs to PATH; this prefix wins
+      // over them so the stubs — never the real npm/launchctl — are reached.
+      MAESTRO_AUTOUPDATE_PATH_PREFIX: fx.bin,
+      // The child shell names its log files with `date +%Y-%m-%d` and this
+      // suite fabricates those names with `localDay()`. `env` here is an
+      // explicit whitelist, so without this line the shell inherits NO TZ and
+      // falls back to the system zone while Node honours the ambient one — the
+      // two then disagree whenever a run sets TZ (e.g. `TZ=UTC npm test` on a
+      // UTC+4 machine), and every upgrade case fails on a log file neither
+      // side is wrong about. Pass the zone through so both agree by construction.
+      ...(process.env.TZ ? { TZ: process.env.TZ } : {}),
+      MAESTRO_AUTOUPDATE_JITTER_MAX: "0",
+      MAESTRO_AUTOUPDATE_HEALTH_WAIT: "0",
+      MAESTRO_AUTOUPDATE_RETRY_SLEEP: "0",
+      // Never a real `npm install -g` from a test — the script logs the
+      // command it would have run instead.
+      MAESTRO_SKIP_GLOBAL_INSTALL: "1",
+      ...(extraEnv || {}),
+    },
+  });
+}
+
+const calls = (fx) => (existsSync(fx.log) ? readFileSync(fx.log, "utf8") : "");
+const noticePath = (fx) => join(fx.agent, "state", "session", "upgrade-notice.json");
+const lastPath = (fx) => join(fx.agent, "state", "autoupdate", "last.json");
+const readLast = (fx) => JSON.parse(readFileSync(lastPath(fx), "utf8"));
+const scriptLog = (fx) => {
+  const dir = join(fx.agent, "logs", "autoupdate");
+  try { return readFileSync(join(dir, `${localDay()}.log`), "utf8"); } catch { return ""; }
+};
+
+test("a healthy upgrade writes state/session/upgrade-notice.json {from,to,at} and never touches the session job", () => {
+  const fx = fixture();
+  try {
+    const r = run(fx);
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    assert.ok(existsSync(noticePath(fx)), "upgrade-notice.json must be written after a healthy upgrade");
+    const notice = JSON.parse(readFileSync(noticePath(fx), "utf8"));
+    assert.equal(notice.from, "1.0.0");
+    assert.equal(notice.to, "2.0.0");
+    assert.match(notice.at, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/, "at must be an ISO-8601 UTC timestamp");
+    const c = calls(fx);
+    // The daemon IS restarted (health gate unchanged) …
+    assert.match(c, /^launchctl kickstart -k gui\/\d+\/ai\.maestro\.ivy-daemon$/m, `daemon must be kickstarted; calls:\n${c}`);
+    // … the session is NOT: no kickstart/bootout of the session label, no kill.
+    assert.ok(!/-session/.test(c), `must not touch the session job; calls:\n${c}`);
+    assert.ok(!/^(pkill|kill|killall) /m.test(c), `must not kill anything; calls:\n${c}`);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("an unhealthy upgrade rolls back and leaves NO upgrade notice", () => {
+  const fx = fixture({ healthy: false });
+  try {
+    run(fx);
+    assert.ok(!existsSync(noticePath(fx)), "no notice after a rollback — the session must not restart onto a bad version");
+    const installed = JSON.parse(readFileSync(join(fx.agent, "node_modules", "@cohortapp", "agent-sdk", "package.json"), "utf8"));
+    assert.equal(installed.version, "1.0.0", "rollback must reinstall the prior version");
+    assert.ok(!/-session/.test(calls(fx)));
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("up to date: no install, no restart, no notice", () => {
+  const fx = fixture({ latest: "1.0.0" });
+  try {
+    const r = run(fx);
+    assert.equal(r.status, 0);
+    assert.ok(!existsSync(noticePath(fx)));
+    assert.ok(!/npm install/.test(calls(fx)));
+    assert.ok(!/launchctl/.test(calls(fx)));
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("source: the daemon health gate is intact and the session label is never kickstarted or killed", () => {
+  assert.match(scriptSrc, /is_healthy\(\)/, "health gate function must remain");
+  assert.match(scriptSrc, /ROLLBACK/, "rollback path must remain");
+  assert.ok(!/kickstart[^\n]*-session/.test(scriptSrc), "must not kickstart the session job");
+  // The ONE bootout in the script is the rollback's revert of a session job
+  // THIS RUN installed (guarded by the PRE_SESSION_PLISTS snapshot). Nothing
+  // else may bootout, and never a pre-existing job.
+  assert.equal((scriptSrc.match(/launchctl bootout/g) || []).length, 1, "exactly one bootout: the rollback revert");
+  assert.match(scriptSrc, /revert_session_install\(\)\{[^]*?PRE_SESSION_PLISTS[^]*?launchctl bootout "gui\/\$UID_\/\$label"/, "the bootout lives inside revert_session_install, behind the pre-run snapshot");
+  assert.ok(!/\b(pkill|killall)\b/.test(scriptSrc), "must not kill processes");
+  assert.match(scriptSrc, /upgrade-notice\.json/, "must write the upgrade notice");
+});
+
+test("a healthy upgrade runs scripts/poller-launchd/migrate.sh (audit F6 follow-through); a rollback does not", () => {
+  const fx = fixture();
+  try {
+    mkdirSync(join(fx.agent, "scripts", "poller-launchd"), { recursive: true });
+    writeFileSync(join(fx.agent, "scripts", "poller-launchd", "migrate.sh"), `#!/bin/bash\necho "migrate $*" >> "${fx.log}"\n`);
+    chmodSync(join(fx.agent, "scripts", "poller-launchd", "migrate.sh"), 0o755);
+    const r = run(fx);
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    assert.match(calls(fx), /^migrate/m, `expected the poller migration after a healthy upgrade; calls:\n${calls(fx)}`);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+  const bad = fixture({ healthy: false });
+  try {
+    mkdirSync(join(bad.agent, "scripts", "poller-launchd"), { recursive: true });
+    writeFileSync(join(bad.agent, "scripts", "poller-launchd", "migrate.sh"), `#!/bin/bash\necho "migrate $*" >> "${bad.log}"\n`);
+    chmodSync(join(bad.agent, "scripts", "poller-launchd", "migrate.sh"), 0o755);
+    run(bad);
+    assert.ok(!/^migrate/m.test(calls(bad)), "no migration on a rolled-back upgrade");
+  } finally { rmSync(bad.root, { recursive: true, force: true }); }
+});
+
+// ---------------------------------------------------------------------------
+// WP-M6 hardening: lock, retries, session half of the health gate, last.json,
+// rollback refreshes the global install, no daemon plist → still upgrade.
+// ---------------------------------------------------------------------------
+
+test("a healthy upgrade writes state/autoupdate/last.json {from,to,at,ok,healthy,reason} and releases the overlap lock", () => {
+  const fx = fixture();
+  try {
+    const r = run(fx);
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    const last = readLast(fx);
+    assert.equal(last.from, "1.0.0");
+    assert.equal(last.to, "2.0.0");
+    assert.equal(last.ok, true);
+    assert.equal(last.healthy, true);
+    assert.equal(last.reason, "");
+    assert.match(last.at, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
+    assert.ok(!existsSync(join(fx.agent, "state", "locks", "autoupdate")), "lock released on exit");
+    assert.match(calls(fx), /^npm install @cohortapp\/agent-sdk@2\.0\.0 --save --no-audit --no-fund --prefer-online$/m, calls(fx));
+    assert.match(calls(fx), /^npm view @cohortapp\/agent-sdk version --no-audit --no-fund --prefer-online$/m);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("overlap lock: a live holder younger than the stale bar makes the run skip; a dead holder is reclaimed", () => {
+  const live = fixture();
+  try {
+    mkdirSync(join(live.agent, "state", "locks", "autoupdate"), { recursive: true });
+    writeFileSync(join(live.agent, "state", "locks", "autoupdate", "pid"), String(process.pid));
+    const r = run(live);
+    assert.equal(r.status, 0);
+    assert.ok(!/npm view/.test(calls(live)), "must not even check npm while another run holds the lock");
+    assert.match(scriptLog(live), /SKIP: another autoupdate \(pid \d+\) holds/);
+    assert.ok(existsSync(join(live.agent, "state", "locks", "autoupdate")), "the other run's lock is left in place");
+  } finally { rmSync(live.root, { recursive: true, force: true }); }
+  const dead = fixture();
+  try {
+    mkdirSync(join(dead.agent, "state", "locks", "autoupdate"), { recursive: true });
+    writeFileSync(join(dead.agent, "state", "locks", "autoupdate", "pid"), "999999");
+    const r = run(dead);
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(scriptLog(dead), /reclaiming stale autoupdate lock/);
+    assert.match(calls(dead), /npm install/, "the reclaimed run proceeds");
+    assert.ok(!existsSync(join(dead.agent, "state", "locks", "autoupdate")));
+  } finally { rmSync(dead.root, { recursive: true, force: true }); }
+  const stale = fixture();
+  try {
+    mkdirSync(join(stale.agent, "state", "locks", "autoupdate"), { recursive: true });
+    writeFileSync(join(stale.agent, "state", "locks", "autoupdate", "pid"), String(process.pid));
+    const r = run(stale, { MAESTRO_AUTOUPDATE_LOCK_STALE_S: "0" });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(scriptLog(stale), /reclaiming stale autoupdate lock/, "a holder older than the stale bar is reclaimed even when alive");
+  } finally { rmSync(stale.root, { recursive: true, force: true }); }
+});
+
+test("npm view and npm install are retried 3x with backoff; a third failure aborts with last.json reason install-failed and no notice", () => {
+  const flaky = fixture({ npmViewFailures: 2, npmInstallFailures: 2 });
+  try {
+    const r = run(flaky);
+    assert.equal(r.status, 0, r.stderr);
+    const c = calls(flaky);
+    assert.equal((c.match(/^npm view/gm) || []).length, 3, `3 view attempts:\n${c}`);
+    assert.equal((c.match(/^npm install @cohortapp/gm) || []).length, 3, `3 install attempts:\n${c}`);
+    assert.match(scriptLog(flaky), /npm view: attempt 1 failed; retrying in 0s/);
+    assert.match(scriptLog(flaky), /attempt 2 failed; retrying/);
+    assert.ok(existsSync(noticePath(flaky)), "third attempt succeeded → normal healthy path");
+  } finally { rmSync(flaky.root, { recursive: true, force: true }); }
+  const dead = fixture({ npmInstallFailures: 3 });
+  try {
+    const r = run(dead);
+    assert.equal(r.status, 1);
+    assert.equal((calls(dead).match(/^npm install @cohortapp/gm) || []).length, 3);
+    assert.ok(!existsSync(noticePath(dead)));
+    assert.ok(!/launchctl kickstart/.test(calls(dead)), "no restart when nothing was installed");
+    const last = readLast(dead);
+    assert.equal(last.ok, false);
+    assert.equal(last.healthy, false);
+    assert.equal(last.reason, "install-failed");
+  } finally { rmSync(dead.root, { recursive: true, force: true }); }
+  const offline = fixture({ npmViewFailures: 3 });
+  try {
+    const r = run(offline);
+    assert.equal(r.status, 0);
+    assert.ok(!/npm install/.test(calls(offline)));
+    assert.match(scriptLog(offline), /npm view failed after 3 attempts/);
+  } finally { rmSync(offline.root, { recursive: true, force: true }); }
+});
+
+test("session half of the health gate: with a generated -session plist, a loaded label + live supervisor is fully healthy; absence is logged as reconcile-failed but does NOT roll back", () => {
+  const ok = fixture({ sessionPlist: true, loadedLabels: ["ai.maestro.ivy-daemon", "ai.maestro.ivy-session"] });
+  try {
+    run(ok);
+    const last = readLast(ok);
+    assert.equal(last.ok, true);
+    assert.equal(last.reason, "");
+    assert.match(calls(ok), /^launchctl print gui\/\d+\/ai\.maestro\.ivy-session$/m, "loaded-ness is asked in the gui domain (right from ssh too)");
+    assert.ok(!/^launchctl list/m.test(calls(ok)), "no domain-less list when print answered");
+    assert.match(calls(ok), new RegExp(`^pgrep -f ${ok.agent.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/scripts/session/supervisor$`, "m"), "the supervisor question is scoped to THIS agent dir");
+    assert.ok(existsSync(noticePath(ok)));
+  } finally { rmSync(ok.root, { recursive: true, force: true }); }
+  const notLoaded = fixture({ sessionPlist: true, loadedLabels: ["ai.maestro.ivy-daemon"] });
+  try {
+    run(notLoaded);
+    const last = readLast(notLoaded);
+    assert.equal(last.ok, true, "the daemon is healthy → the upgrade stands");
+    assert.equal(last.healthy, true);
+    assert.equal(last.reason, "session-reconcile-failed");
+    assert.match(scriptLog(notLoaded), /reconcile-failed: session job ai\.maestro\.ivy-session is not loaded/);
+    assert.ok(!/ROLLBACK/.test(scriptLog(notLoaded)), "session absence never rolls back");
+    assert.ok(existsSync(noticePath(notLoaded)), "the notice is still written — the daemon is on the new version");
+    const installed = JSON.parse(readFileSync(join(notLoaded.agent, "node_modules", "@cohortapp", "agent-sdk", "package.json"), "utf8"));
+    assert.equal(installed.version, "2.0.0");
+    assert.ok(!/-session/.test(calls(notLoaded).replace(/^launchctl (list|print) [^\n]*$/gm, "")), "the session job itself is never touched");
+  } finally { rmSync(notLoaded.root, { recursive: true, force: true }); }
+  const noSupervisor = fixture({ sessionPlist: true, loadedLabels: ["ai.maestro.ivy-daemon", "ai.maestro.ivy-session"], supervisorAlive: false });
+  try {
+    run(noSupervisor);
+    assert.equal(readLast(noSupervisor).reason, "session-reconcile-failed");
+    assert.match(scriptLog(noSupervisor), /no supervisor process is alive/);
+  } finally { rmSync(noSupervisor.root, { recursive: true, force: true }); }
+  const noPlist = fixture({ sessionPlist: false, loadedLabels: ["ai.maestro.ivy-daemon"] });
+  try {
+    run(noPlist);
+    assert.equal(readLast(noPlist).reason, "", "no generated -session plist → the session half is not asked");
+    assert.ok(!/launchctl (list|print)/.test(calls(noPlist)));
+  } finally { rmSync(noPlist.root, { recursive: true, force: true }); }
+});
+
+test("rollback: last.json says unhealthy-rolled-back, and the global install is put back to the previous version (skipped-but-logged under MAESTRO_SKIP_GLOBAL_INSTALL=1)", () => {
+  const fx = fixture({ healthy: false });
+  try {
+    run(fx);
+    const last = readLast(fx);
+    assert.equal(last.from, "1.0.0");
+    assert.equal(last.to, "2.0.0");
+    assert.equal(last.ok, false);
+    assert.equal(last.healthy, false, "the daemon stub is unhealthy on both versions here");
+    assert.equal(last.reason, "rollback-unhealthy");
+    assert.match(scriptLog(fx), /global refresh skipped \(MAESTRO_SKIP_GLOBAL_INSTALL=1\): npm install -g @cohortapp\/agent-sdk@1\.0\.0 --no-audit --no-fund/);
+    assert.ok(!/npm install -g/.test(calls(fx)), "no real global install from a test");
+    assert.equal((calls(fx).match(/^launchctl kickstart -k gui\/\d+\/ai\.maestro\.ivy-daemon$/gm) || []).length, 2, "kickstart after the upgrade and after the rollback");
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("no daemon plist installed at all: the upgrade still runs, and whatever -daemon label the upgrade installed is kickstarted", () => {
+  const fx = fixture();
+  try {
+    rmSync(join(fx.home, "Library", "LaunchAgents", "ai.maestro.ivy-daemon.plist"));
+    // The (stubbed) maestro.mjs upgrade installs the daemon plist — as the real
+    // one's launchd reconcile does — so the label exists by the time restart runs.
+    writeFileSync(join(fx.agent, "node_modules", "@cohortapp", "agent-sdk", "bin", "maestro.mjs"),
+      `import { writeFileSync } from "node:fs";\nwriteFileSync(${JSON.stringify(join(fx.home, "Library", "LaunchAgents", "ai.maestro.ivy-daemon.plist"))}, "<plist/>");\n`);
+    const r = run(fx);
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(calls(fx), /^npm install @cohortapp\/agent-sdk@2\.0\.0/m, "the upgrade runs without a daemon plist");
+    assert.match(calls(fx), /^launchctl kickstart -k gui\/\d+\/ai\.maestro\.ivy-daemon$/m, "the label the upgrade installed is kickstarted");
+    assert.equal(readLast(fx).ok, true);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+  const none = fixture();
+  try {
+    rmSync(join(none.home, "Library", "LaunchAgents", "ai.maestro.ivy-daemon.plist"));
+    const r = run(none);
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(scriptLog(none), /no -daemon plist under ~\/Library\/LaunchAgents — nothing to kickstart/);
+    assert.ok(!/kickstart/.test(calls(none)));
+  } finally { rmSync(none.root, { recursive: true, force: true }); }
+});
+
+test("source: the overlap lock, the retry, the session gate and the last.json writer are all present", () => {
+  assert.match(scriptSrc, /mkdir "\$LOCK_DIR"/, "mkdir-based overlap lock");
+  assert.match(scriptSrc, /state\/locks\/autoupdate/);
+  assert.match(scriptSrc, /--no-audit --no-fund --prefer-online/);
+  assert.match(scriptSrc, /RETRIES=3/);
+  assert.match(scriptSrc, /org-mesh connected\|daemon\\\] Running/, "the daemon health line must stay intact");
+  assert.match(scriptSrc, /scripts\/session\/supervisor/);
+  assert.match(scriptSrc, /state\/autoupdate\/last\.json|"\$dir\/last\.json"/);
+  assert.match(scriptSrc, /MAESTRO_SKIP_GLOBAL_INSTALL/);
+});
+
+// ---------------------------------------------------------------------------
+// Review fixes: failed-target hold, rollback reverts only what this run
+// installed, per-agent scoping, the re-exec copy cleans itself up.
+// ---------------------------------------------------------------------------
+
+test("a version that failed the health gate here is held (no install, no restart) while last.json is younger than the hold; an old failure, another version, or an install-failed entry do not hold", () => {
+  const writeLast = (fx, o) => { mkdirSync(join(fx.agent, "state", "autoupdate"), { recursive: true }); writeFileSync(lastPath(fx), JSON.stringify({ from: "1.0.0", to: "2.0.0", at: new Date().toISOString(), ok: false, healthy: true, reason: "unhealthy-rolled-back", ...o })); };
+  const held = fixture();
+  try {
+    writeLast(held, {});
+    const r = run(held);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(!/npm install/.test(calls(held)), `must not reinstall a version that already failed here:\n${calls(held)}`);
+    assert.ok(!/kickstart/.test(calls(held)));
+    assert.match(scriptLog(held), /SKIP: 2\.0\.0 already failed the health gate here \(unhealthy-rolled-back at .*\); holding 86400s \(still 1\.0\.0\)/);
+    assert.equal(readLast(held).reason, "unhealthy-rolled-back", "last.json is left as the fleet's evidence");
+    assert.ok(!existsSync(join(held.agent, "state", "locks", "autoupdate")));
+  } finally { rmSync(held.root, { recursive: true, force: true }); }
+  const heldTwice = fixture();
+  try { writeLast(heldTwice, { reason: "rollback-unhealthy", healthy: false }); run(heldTwice); assert.ok(!/npm install/.test(calls(heldTwice)), "a failed rollback holds too"); } finally { rmSync(heldTwice.root, { recursive: true, force: true }); }
+  const expired = fixture();
+  try { writeLast(expired, {}); run(expired, { MAESTRO_AUTOUPDATE_FAILED_HOLD_S: "0" }); assert.match(calls(expired), /npm install @cohortapp\/agent-sdk@2\.0\.0/, "past the hold the version is tried again"); } finally { rmSync(expired.root, { recursive: true, force: true }); }
+  const other = fixture({ latest: "2.0.1" });
+  try { writeLast(other, {}); run(other); assert.match(calls(other), /npm install @cohortapp\/agent-sdk@2\.0\.1/, "a NEWER version is not held by 2.0.0's failure"); } finally { rmSync(other.root, { recursive: true, force: true }); }
+  const network = fixture();
+  try { writeLast(network, { reason: "install-failed", healthy: false }); run(network); assert.match(calls(network), /npm install @cohortapp\/agent-sdk@2\.0\.0/, "install-failed is transient: retried"); } finally { rmSync(network.root, { recursive: true, force: true }); }
+  const corrupt = fixture();
+  try { mkdirSync(join(corrupt.agent, "state", "autoupdate"), { recursive: true }); writeFileSync(lastPath(corrupt), "{not json"); run(corrupt); assert.match(calls(corrupt), /npm install/, "an unreadable last.json holds nothing (fail-open)"); } finally { rmSync(corrupt.root, { recursive: true, force: true }); }
+});
+
+test("rollback reverts the -session job ONLY when this run installed it: bootout + plist removed; a pre-existing session plist is never touched", () => {
+  // The (stubbed) new upgrade installs the session plist, as the real reconcile does; the daemon is unhealthy → rollback.
+  const installedByRun = fixture({ healthy: false, installedSessionPlist: false, sessionPlist: true, loadedLabels: ["ai.maestro.ivy-daemon", "ai.maestro.ivy-session"] });
+  try {
+    const plist = join(installedByRun.home, "Library", "LaunchAgents", "ai.maestro.ivy-session.plist");
+    writeFileSync(join(installedByRun.agent, "node_modules", "@cohortapp", "agent-sdk", "bin", "maestro.mjs"),
+      `import { writeFileSync } from "node:fs";\nwriteFileSync(${JSON.stringify(plist)}, "<plist/>");\n`);
+    const r = run(installedByRun);
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(scriptLog(installedByRun), /ROLLBACK/);
+    assert.match(calls(installedByRun), /^launchctl bootout gui\/\d+\/ai\.maestro\.ivy-session$/m, `the job this run installed is booted out on rollback:\n${calls(installedByRun)}`);
+    assert.ok(!existsSync(plist), "and its plist is removed — the previous version has no front-door session");
+    assert.match(scriptLog(installedByRun), /rollback: reverted session job ai\.maestro\.ivy-session — this run installed it/);
+    assert.equal(readLast(installedByRun).reason, "rollback-unhealthy");
+    assert.ok(!existsSync(noticePath(installedByRun)));
+  } finally { rmSync(installedByRun.root, { recursive: true, force: true }); }
+  const preExisting = fixture({ healthy: false, installedSessionPlist: true, sessionPlist: true, loadedLabels: ["ai.maestro.ivy-daemon", "ai.maestro.ivy-session"] });
+  try {
+    run(preExisting);
+    assert.match(scriptLog(preExisting), /ROLLBACK/);
+    assert.ok(!/bootout/.test(calls(preExisting)), `a session job that was there before the run is the operator's — never booted out:\n${calls(preExisting)}`);
+    assert.ok(existsSync(join(preExisting.home, "Library", "LaunchAgents", "ai.maestro.ivy-session.plist")));
+  } finally { rmSync(preExisting.root, { recursive: true, force: true }); }
+  const healthy = fixture({ installedSessionPlist: false, sessionPlist: true, loadedLabels: ["ai.maestro.ivy-daemon", "ai.maestro.ivy-session"] });
+  try {
+    const plist = join(healthy.home, "Library", "LaunchAgents", "ai.maestro.ivy-session.plist");
+    writeFileSync(join(healthy.agent, "node_modules", "@cohortapp", "agent-sdk", "bin", "maestro.mjs"), `import { writeFileSync } from "node:fs";\nwriteFileSync(${JSON.stringify(plist)}, "<plist/>");\n`);
+    run(healthy);
+    assert.ok(!/bootout/.test(calls(healthy)), "a healthy upgrade never boots anything out");
+    assert.ok(existsSync(plist));
+  } finally { rmSync(healthy.root, { recursive: true, force: true }); }
+});
+
+test("two seats on one Mac: every launchd / pgrep question is scoped to THIS agent's first name — the other seat's daemon is not kickstarted and its session does not satisfy the gate", () => {
+  const fx = fixture({ firstName: "Ivy", sessionPlist: true, supervisorAlive: true, loadedLabels: ["ai.maestro.zed-daemon", "ai.maestro.zed-session", "ai.maestro.ivy-daemon"] });
+  try {
+    // Seat B (zed) is installed on the same machine, and sorts BEFORE ivy.
+    for (const l of ["ai.maestro.zed-daemon", "ai.maestro.zed-session"]) writeFileSync(join(fx.home, "Library", "LaunchAgents", `${l}.plist`), "<plist/>");
+    // Seat A's own generated set also carries its daemon plist (as the real generator renders it).
+    writeFileSync(join(fx.agent, "scripts", "local-triggers", "plists", "ai.maestro.ivy-daemon.plist"), "<plist/>");
+    // Make the ivy-session plist sort AFTER zed's in LaunchAgents too — the scoping, not the sort order, must pick ivy.
+    const r = run(fx);
+    assert.equal(r.status, 0, r.stderr);
+    const c = calls(fx);
+    assert.match(c, /^launchctl kickstart -k gui\/\d+\/ai\.maestro\.ivy-daemon$/m, c);
+    assert.ok(!/zed/.test(c), `seat B must never be touched or consulted:\n${c}`);
+    assert.match(c, /^launchctl print gui\/\d+\/ai\.maestro\.ivy-session$/m);
+    assert.ok(!/pgrep -f .*supervisor/.test(c), "ivy's label is not loaded → the gate stops there; zed's supervisor is never consulted");
+    assert.equal(readLast(fx).reason, "session-reconcile-failed", "ivy's session is not loaded — zed's loaded session must not count");
+    assert.match(scriptLog(fx), /agent: ivy \(launchd\/pgrep questions are scoped to ai\.maestro\.ivy-\*\)/);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+  const bothLoaded = fixture({ firstName: "Ivy", sessionPlist: true, supervisorAlive: true, loadedLabels: ["ai.maestro.zed-daemon", "ai.maestro.zed-session", "ai.maestro.ivy-daemon", "ai.maestro.ivy-session"] });
+  try {
+    for (const l of ["ai.maestro.zed-daemon", "ai.maestro.zed-session"]) writeFileSync(join(bothLoaded.home, "Library", "LaunchAgents", `${l}.plist`), "<plist/>");
+    run(bothLoaded);
+    const c = calls(bothLoaded);
+    assert.match(c, new RegExp(`^pgrep -f ${bothLoaded.agent.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/scripts/session/supervisor$`, "m"), "the supervisor question names THIS agent dir, so seat B's supervisor cannot answer it");
+    assert.equal(readLast(bothLoaded).reason, "");
+    assert.ok(!/zed/.test(c));
+  } finally { rmSync(bothLoaded.root, { recursive: true, force: true }); }
+});
+
+test("the /tmp re-exec copy removes itself on exit (and a run with MAESTRO_AUTOUPDATE_REEXEC=1 never deletes the script it was given)", () => {
+  const fx = fixture({ latest: "1.0.0" });
+  try {
+    const tmp = join(fx.root, "tmp"); mkdirSync(tmp, { recursive: true });
+    const r = spawnSync("/bin/bash", [join(fx.agent, "scripts", "local-triggers", "autoupdate.sh")], {
+      encoding: "utf8",
+      // This case spawns directly rather than through `run()`, so it needs the
+      // same TZ passthrough for the same reason — see the note in `run()`.
+      env: { HOME: fx.home, AGENT_ROOT: fx.agent, TMPDIR: tmp, PATH: `${fx.bin}:${dirname(process.execPath)}:/usr/bin:/bin`, ...(process.env.TZ ? { TZ: process.env.TZ } : {}), MAESTRO_AUTOUPDATE_PATH_PREFIX: fx.bin, MAESTRO_AUTOUPDATE_JITTER_MAX: "0", MAESTRO_AUTOUPDATE_HEALTH_WAIT: "0", MAESTRO_AUTOUPDATE_RETRY_SLEEP: "0", MAESTRO_SKIP_GLOBAL_INSTALL: "1" },
+    });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(scriptLog(fx), /up to date \(1\.0\.0\)/, "the re-exec'd copy ran the script");
+    assert.deepEqual(readdirSync(tmp), [], "no maestro-autoupdate.XXXXXX copy left behind");
+    assert.ok(existsSync(join(fx.agent, "scripts", "local-triggers", "autoupdate.sh")), "the agent dir's script is untouched");
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});

package/scripts/local-triggers/generate-plists.sh

@@ -95,6 +95,11 @@ generate_plist() {
     local SCHEDULE="$3"      # Optional: StartCalendarInterval dict content
     local INTERVAL="$4"      # Optional: StartInterval in seconds
     local KEEP_ALIVE="$5"    # Optional: true for daemon-style
+    local LOG_SUBDIR="${6:-daemon}"  # Optional: logs/<subdir>/ for launchd's
+                             # StandardOut/ErrorPath. Defaults to logs/daemon
+                             # (every job shared it historically); the session
+                             # job uses logs/session so its launchd output never
+                             # interleaves with the daemon's.
 
     local FILE="$PLIST_DIR/$LABEL.plist"
 
@@ -195,7 +200,10 @@ PLIST_ENV_END
     # Resolve symlinked log path to a real path so launchd can write to it.
     # If logs/ is a symlink (e.g. when redirected to an external SSD), launchd's
     # StandardErrorPath/StandardOutPath sometimes fail with EX_CONFIG (78).
-    LOG_REAL=$(cd -P "$AGENT_DIR/logs/daemon" 2>/dev/null && pwd -P || echo "$AGENT_DIR/logs/daemon")
+    # launchd creates the log FILE but not its directory, so make sure the
+    # directory exists (idempotent; logs/daemon already does via init-agent).
+    mkdir -p "$AGENT_DIR/logs/$LOG_SUBDIR" 2>/dev/null || true
+    LOG_REAL=$(cd -P "$AGENT_DIR/logs/$LOG_SUBDIR" 2>/dev/null && pwd -P || echo "$AGENT_DIR/logs/$LOG_SUBDIR")
 
     cat >> "$FILE" << PLIST_FOOTER
 
@@ -269,6 +277,21 @@ generate_plist "ai.maestro.${AGENT_FIRST}-daemon" \
     "${AGENT_DIR}/scripts/daemon/launchd-wrapper.sh" \
     "" "" "true"
 
+# 1b. Front-door Claude Code session (KeepAlive) — the agent's BRAIN, next to
+#     the daemon's PLUMBING. scripts/session/supervisor.sh sources .env, takes
+#     the `session` singleton lock and runs the main interactive session inside
+#     a foreground multiplexer (screen/tmux), so the supervisor lives exactly as
+#     long as the session: when the session ends it exits 75 (EX_TEMPFAIL) and
+#     launchd's KeepAlive {SuccessfulExit:false, Crashed:true} + ThrottleInterval
+#     30 bring it back. A second supervisor (lock held) exits 0 and is NOT
+#     restarted, so launchd never thrashes. No cron, no periodic kill: relaunch
+#     happens only on death. Replaces the Terminal.app boot-claude-session job.
+#     Logs go to logs/session/ (not logs/daemon/).
+#     See docs/superpowers/specs/2026-09-08-front-door-session-design.md §3.1.
+generate_plist "ai.maestro.${AGENT_FIRST}-session" \
+    "${AGENT_DIR}/scripts/session/supervisor.sh" \
+    "" "" "true" "session"
+
 # 2. Slack events relay polling job (every 5 sec).
 #    The local Mac mini polls the Railway-hosted webhook relay for buffered
 #    Slack events. This replaces the older local slack-events-server.mjs which