@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/cli/session.test.mjs

@@ -1,613 +0,0 @@
-/**
- * session.test.mjs — `maestro session <sub>` (design §3.1, §3.6, §6 WP-M3).
- *
- * `run()` returns `{ok, code, lines, data?}` and only prints when asked, so the
- * whole verb surface is testable without importing bin/maestro.mjs. State is a
- * real temp agent dir (the module's durable writes go through fs-atomic);
- * every process boundary — launchctl/tmux/screen/claude execs, TTY, uid, HOME,
- * clock, pid liveness — is injected via `deps`.
- *
- * Run: node --test lib/cli/session.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import {
-  run, usage, resolveFirstName, sessionLabel, muxSessionName, sessionPaths,
-  heartbeatAgeMs, isLive, attachCommand, buildSpawnArgs, prunePeers, STALE_MS, updatePeers,
-} from "./session.mjs";
-import { withParallelism, countParallelism, PARALLELISM_DIRECTIVE } from "../prompts/parallelism.mjs";
-
-const NOW = Date.parse("2026-09-08T12:00:00Z");
-
-function agentRepo(first = "Ivy") {
-  const root = mkdtempSync(join(tmpdir(), "session-cli-"));
-  mkdirSync(join(root, "config"), { recursive: true });
-  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ firstName: first, lastName: "Tester" }));
-  return root;
-}
-function writeJson(p, obj) { mkdirSync(join(p, ".."), { recursive: true }); writeFileSync(p, JSON.stringify(obj)); }
-
-/**
- * Fake exec: `table` maps "<cmd> <first arg>" → {status, stdout}. Everything
- * else exits 1. Records every call.
- */
-function fakeExec(table = {}) {
-  const calls = [];
-  const fn = (cmd, args = []) => {
-    calls.push([cmd, ...args]);
-    const key = `${cmd} ${args[0] || ""}`.trim();
-    const r = table[key] || table[cmd] || { status: 1, stdout: "", stderr: "" };
-    return { status: r.status ?? 0, stdout: r.stdout || "", stderr: r.stderr || "" };
-  };
-  fn.calls = calls;
-  return fn;
-}
-
-function deps(over = {}) {
-  const home = mkdtempSync(join(tmpdir(), "session-home-"));
-  mkdirSync(join(home, "Library", "LaunchAgents"), { recursive: true });
-  return {
-    exec: fakeExec(),
-    execInherit: fakeExec(),
-    now: () => NOW,
-    uid: () => 501,
-    home,
-    isTTY: false,
-    isAlive: () => false,
-    claudeBin: "/stub/claude",
-    env: {},
-    ...over,
-  };
-}
-const opts = (agentRoot, d, extra = {}) => ({ agentRoot, print: false, deps: d, ...extra });
-
-// ---------------------------------------------------------------------------
-// Pure helpers
-// ---------------------------------------------------------------------------
-
-test("resolveFirstName: config/agent.json firstName lowercased, else dir basename minus -ai", () => {
-  const root = agentRepo("Sigrid");
-  assert.equal(resolveFirstName(root), "sigrid");
-  const bare = join(mkdtempSync(join(tmpdir(), "bare-")), "Nadia-ai");
-  mkdirSync(bare);
-  assert.equal(resolveFirstName(bare), "nadia");
-});
-
-test("sessionLabel / muxSessionName / sessionPaths follow the design names", () => {
-  assert.equal(sessionLabel("ivy"), "ai.maestro.ivy-session");
-  assert.equal(muxSessionName("ivy"), "maestro-ivy");
-  const p = sessionPaths("/a");
-  assert.equal(p.heartbeat, "/a/state/session/heartbeat.json");
-  assert.equal(p.mainSession, "/a/state/session/main-session.json");
-  assert.equal(p.peers, "/a/state/session/peers.json");
-  assert.equal(p.handoffsDir, "/a/state/session/handoffs");
-  assert.equal(p.handoffsDone, "/a/state/session/handoffs/done");
-  assert.equal(p.restartRequested, "/a/state/session/restart-requested");
-  assert.equal(p.upgradeNotice, "/a/state/session/upgrade-notice.json");
-  assert.equal(p.lock, "/a/state/locks/process/session.pid");
-});
-
-test("heartbeatAgeMs accepts ms or ISO ts; isLive uses the 90s stale window with `now` injected", () => {
-  assert.equal(heartbeatAgeMs({ ts: NOW - 5000 }, NOW), 5000);
-  assert.equal(heartbeatAgeMs({ ts: new Date(NOW - 7000).toISOString() }, NOW), 7000);
-  assert.equal(heartbeatAgeMs(null, NOW), null);
-  assert.equal(heartbeatAgeMs({}, NOW), null);
-  assert.equal(STALE_MS, 90_000);
-  assert.equal(isLive({ ts: NOW - 89_999 }, NOW), true);
-  assert.equal(isLive({ ts: NOW - 90_001 }, NOW), false);
-  assert.equal(isLive(null, NOW), false);
-});
-
-test("attachCommand prints the exact tmux/screen attach line", () => {
-  assert.deepEqual(attachCommand("ivy", "tmux"), ["tmux", "attach", "-t", "maestro-ivy"]);
-  assert.deepEqual(attachCommand("ivy", "screen"), ["screen", "-r", "maestro-ivy"]);
-});
-
-test("buildSpawnArgs: claude --name <first>-<slug> + permission args + the prompt, led by the parallelism directive", () => {
-  const prev = process.env.MAESTRO_SCOPED_PERMISSIONS;
-  delete process.env.MAESTRO_SCOPED_PERMISSIONS;
-  try {
-    // WP-M7 mechanic 5: a peer is spawned precisely when there is more work than
-    // one session can hold, so every peer prompt carries the standing permission
-    // to fan out — and the file-scope rule that makes fanning out safe.
-    const a = buildSpawnArgs({ first: "ivy", slug: "research", prompt: "Look into X" });
-    assert.deepEqual(a, ["--name", "ivy-research", "--dangerously-skip-permissions", withParallelism("Look into X")]);
-    assert.equal(countParallelism(a[3]), 1);
-    assert.ok(a[3].startsWith(PARALLELISM_DIRECTIVE) && a[3].endsWith("Look into X"));
-
-    // Idempotent: a caller that already led its prompt with it is not doubled.
-    const b = buildSpawnArgs({ first: "ivy", slug: "research", prompt: withParallelism("Look into X") });
-    assert.deepEqual(b, a);
-  } finally {
-    if (prev === undefined) delete process.env.MAESTRO_SCOPED_PERMISSIONS; else process.env.MAESTRO_SCOPED_PERMISSIONS = prev;
-  }
-});
-
-test("prunePeers keeps only peers whose mux session is present", () => {
-  const peers = [{ name: "a", muxName: "maestro-ivy-a" }, { name: "b", muxName: "maestro-ivy-b" }];
-  const { live, dead } = prunePeers(peers, (muxName) => muxName.endsWith("-a"));
-  assert.deepEqual(live.map((p) => p.name), ["a"]);
-  assert.deepEqual(dead.map((p) => p.name), ["b"]);
-});
-
-// ---------------------------------------------------------------------------
-// status
-// ---------------------------------------------------------------------------
-
-test("status --json on a bare repo: nothing running, nothing installed, no peers", async () => {
-  const root = agentRepo();
-  const d = deps();
-  const r = await run(["status", "--json"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  const s = JSON.parse(r.lines.join("\n"));
-  assert.equal(s.first, "ivy");
-  assert.equal(s.label, "ai.maestro.ivy-session");
-  assert.equal(s.lock.held, false);
-  assert.equal(s.heartbeat.live, false);
-  assert.equal(s.heartbeat.ageMs, null);
-  assert.equal(s.mux.present, false);
-  assert.equal(s.plist.installed, false);
-  assert.equal(s.plist.loaded, false);
-  assert.deepEqual(s.peers, []);
-  assert.equal(s.handoffs.open, 0);
-  assert.equal(s.live, false);
-});
-
-test("status reads lock holder, heartbeat age, mux presence, plist state, peers and flags", async () => {
-  const root = agentRepo();
-  const d = deps({
-    // Pin the running version: the notice below targets 2.12.0 and must read as
-    // PENDING regardless of what package.json says at the time the test runs.
-    installedVersion: "2.11.17",
-    isAlive: (pid) => pid === 4242,
-    exec: fakeExec({
-      "tmux has-session": { status: 0 },
-      "launchctl list": { status: 0, stdout: '{ "PID" = 4242; }' },
-    }),
-  });
-  mkdirSync(join(root, "state", "locks", "process"), { recursive: true });
-  writeFileSync(join(root, "state", "locks", "process", "session.pid"), "4242\nMon Sep  8 11:00:00 2026\n");
-  writeJson(join(root, "state", "session", "heartbeat.json"), { pid: 4243, sessionId: "sid-1", name: "ivy-main", ts: NOW - 15_000, feedVersion: 1 });
-  writeJson(join(root, "state", "session", "main-session.json"), { sessionId: "sid-1", createdAt: "2026-09-01T00:00:00Z", resumes: 3 });
-  writeJson(join(root, "state", "session", "peers.json"), { peers: [
-    { name: "research", muxName: "maestro-ivy-research", startedAt: "2026-09-08T11:50:00Z", purpose: "Look into X" },
-  ] });
-  mkdirSync(join(root, "state", "session", "handoffs", "done"), { recursive: true });
-  writeJson(join(root, "state", "session", "handoffs", "t1.json"), { tickId: "t1", cadence: "daily-morning-brief", enqueuedAt: NOW - 60_000, deadlineAt: NOW + 60_000 });
-  writeJson(join(root, "state", "session", "handoffs", "done", "t0.json"), { tickId: "t0" });
-  writeFileSync(join(root, "state", "session", "restart-requested"), "");
-  writeJson(join(root, "state", "session", "upgrade-notice.json"), { from: "2.11.17", to: "2.12.0", at: "2026-09-08T11:59:00Z" });
-  writeFileSync(join(d.home, "Library", "LaunchAgents", "ai.maestro.ivy-session.plist"), "<plist/>");
-
-  const r = await run(["status", "--json"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  const s = JSON.parse(r.lines.join("\n"));
-  assert.equal(s.lock.held, true);
-  assert.equal(s.lock.pid, 4242);
-  assert.equal(s.heartbeat.live, true);
-  assert.equal(s.heartbeat.ageMs, 15_000);
-  assert.equal(s.heartbeat.sessionId, "sid-1");
-  assert.equal(s.mainSession.sessionId, "sid-1");
-  assert.equal(s.mainSession.resumes, 3);
-  assert.equal(s.mux.present, true);
-  assert.equal(s.mux.kind, "tmux");
-  assert.equal(s.mux.name, "maestro-ivy");
-  assert.equal(s.plist.installed, true);
-  assert.equal(s.plist.loaded, true);
-  assert.equal(s.peers.length, 1);
-  assert.equal(s.peers[0].name, "research");
-  assert.equal(s.handoffs.open, 1, "done/ must not count as open");
-  assert.equal(s.restartRequested, true);
-  assert.equal(s.upgradeNotice.to, "2.12.0");
-  assert.equal(s.live, true);
-  // A stale lock (dead pid) is reported as not held.
-  const d2 = deps({ isAlive: () => false });
-  const r2 = await run(["status", "--json"], opts(root, d2));
-  assert.equal(JSON.parse(r2.lines.join("\n")).lock.held, false);
-});
-
-test("status falls back to screen -ls when tmux is absent", async () => {
-  const root = agentRepo();
-  const d = deps({ exec: fakeExec({ "screen -ls": { status: 0, stdout: "There is a screen on:\n\t7001.maestro-ivy\t(Detached)\n1 Socket in /tmp/screens/S-ivy.\n" } }) });
-  const r = await run(["status", "--json"], opts(root, d));
-  const s = JSON.parse(r.lines.join("\n"));
-  assert.equal(s.mux.present, true);
-  assert.equal(s.mux.kind, "screen");
-});
-
-test("status --brief is one line and the human form says what to do next", async () => {
-  const root = agentRepo();
-  const d = deps();
-  const brief = await run(["status", "--brief"], opts(root, d));
-  assert.equal(brief.lines.length, 1);
-  assert.match(brief.lines[0], /ivy-main/);
-  assert.match(brief.lines[0], /not live|down|no heartbeat/i);
-  const full = await run(["status"], opts(root, d));
-  assert.ok(full.lines.length > 3);
-  assert.match(full.lines.join("\n"), /maestro session start/);
-  // Product-copy discipline: the persona never leaks into copy a human could
-  // paste onward, but status is an operator surface — still, no model names.
-  assert.ok(!/anthropic|opus|sonnet/i.test(full.lines.join("\n")));
-});
-
-// ---------------------------------------------------------------------------
-// attach
-// ---------------------------------------------------------------------------
-
-test("attach prints the exact command and only execs it on a TTY", async () => {
-  const root = agentRepo();
-  const noTty = deps({ exec: fakeExec({ "tmux has-session": { status: 0 } }) });
-  const r = await run(["attach"], opts(root, noTty));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  assert.match(r.lines.join("\n"), /tmux attach -t maestro-ivy/);
-  assert.equal(noTty.execInherit.calls.length, 0, "no exec without a TTY");
-
-  // attach propagates the attached session's exit status, so the inherit
-  // fake must return 0 for the ok:true assertion to be meaningful.
-  const tty = deps({ isTTY: true, execInherit: fakeExec({ screen: { status: 0 } }), exec: fakeExec({ "screen -ls": { status: 0, stdout: "\t1.maestro-ivy\t(Detached)\n" } }) });
-  const r2 = await run(["attach"], opts(root, tty));
-  assert.equal(r2.ok, true);
-  assert.deepEqual(tty.execInherit.calls, [["screen", "-r", "maestro-ivy"]]);
-  assert.match(r2.lines.join("\n"), /screen -r maestro-ivy/);
-});
-
-test("attach when no mux session exists says so and points at start", async () => {
-  const root = agentRepo();
-  const d = deps({ isTTY: true });
-  const r = await run(["attach"], opts(root, d));
-  assert.equal(r.ok, false);
-  assert.equal(d.execInherit.calls.length, 0);
-  assert.match(r.lines.join("\n"), /maestro session start/);
-});
-
-// ---------------------------------------------------------------------------
-// start / stop / restart
-// ---------------------------------------------------------------------------
-
-test("start bootstraps the plist when not loaded, then kickstarts the label", async () => {
-  const root = agentRepo();
-  const d = deps({ exec: fakeExec({ "launchctl bootstrap": { status: 0 }, "launchctl kickstart": { status: 0 } }) });
-  const plist = join(d.home, "Library", "LaunchAgents", "ai.maestro.ivy-session.plist");
-  writeFileSync(plist, "<plist/>");
-  const r = await run(["start"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  assert.deepEqual(d.exec.calls.filter((c) => c[0] === "launchctl"), [
-    ["launchctl", "list", "ai.maestro.ivy-session"],
-    ["launchctl", "bootstrap", "gui/501", plist],
-    ["launchctl", "kickstart", "gui/501/ai.maestro.ivy-session"],
-  ]);
-});
-
-test("start with no installed plist fails with the fix", async () => {
-  const root = agentRepo();
-  const d = deps();
-  const r = await run(["start"], opts(root, d));
-  assert.equal(r.ok, false);
-  assert.match(r.lines.join("\n"), /init-agent|generate-plists/);
-  assert.equal(d.exec.calls.filter((c) => c[0] === "launchctl" && c[1] !== "list").length, 0);
-});
-
-test("stop boots the label out of the gui domain", async () => {
-  const root = agentRepo();
-  const d = deps({ exec: fakeExec({ "launchctl bootout": { status: 0 } }) });
-  const r = await run(["stop"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  assert.deepEqual(d.exec.calls, [["launchctl", "bootout", "gui/501/ai.maestro.ivy-session"]]);
-});
-
-test("restart touches state/session/restart-requested then kickstarts (no -k unless --force)", async () => {
-  const root = agentRepo();
-  const d = deps({ exec: fakeExec({ "launchctl kickstart": { status: 0 }, "launchctl list": { status: 0 } }) });
-  const r = await run(["restart"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  assert.ok(existsSync(join(root, "state", "session", "restart-requested")), "marker must be written");
-  const ks = d.exec.calls.filter((c) => c[1] === "kickstart");
-  assert.deepEqual(ks, [["launchctl", "kickstart", "gui/501/ai.maestro.ivy-session"]]);
-  // --force: kill + restart via kickstart -k.
-  const d2 = deps({ exec: fakeExec({ "launchctl kickstart": { status: 0 }, "launchctl list": { status: 0 } }) });
-  await run(["restart", "--force"], opts(root, d2));
-  assert.deepEqual(d2.exec.calls.filter((c) => c[1] === "kickstart"), [["launchctl", "kickstart", "-k", "gui/501/ai.maestro.ivy-session"]]);
-});
-
-// ---------------------------------------------------------------------------
-// spawn / peers
-// ---------------------------------------------------------------------------
-
-test("spawn launches a detached tmux session running claude --name <first>-<slug> and registers the peer", async () => {
-  const root = agentRepo();
-  const prev = process.env.MAESTRO_SCOPED_PERMISSIONS;
-  delete process.env.MAESTRO_SCOPED_PERMISSIONS;
-  const d = deps({ exec: fakeExec({ "tmux -V": { status: 0, stdout: "tmux 3.4" }, "tmux new-session": { status: 0 }, "tmux has-session": { status: 0 } }) });
-  try {
-    const r = await run(["spawn", "--name", "research", "--cwd", root, "Look into X"], opts(root, d));
-    assert.equal(r.ok, true, r.lines.join("\n"));
-    assert.equal(r.data.name, "ivy-research");
-    const spawnCall = d.exec.calls.find((c) => c[0] === "tmux" && c[1] === "new-session");
-    assert.ok(spawnCall, `expected a tmux new-session; calls: ${JSON.stringify(d.exec.calls)}`);
-    assert.deepEqual(spawnCall, ["tmux", "new-session", "-d", "-s", "maestro-ivy-research", "-c", root, "--",
-      "/stub/claude", "--name", "ivy-research", "--dangerously-skip-permissions", withParallelism("Look into X")]);
-    const peers = JSON.parse(readFileSync(join(root, "state", "session", "peers.json"), "utf8"));
-    assert.equal(peers.peers.length, 1);
-    assert.equal(peers.peers[0].name, "ivy-research");
-    assert.equal(peers.peers[0].muxName, "maestro-ivy-research");
-    assert.equal(peers.peers[0].purpose, "Look into X");
-    assert.equal(peers.peers[0].startedAt, new Date(NOW).toISOString());
-    assert.equal(peers.peers[0].cwd, root);
-    // The last line is the name, so a caller can capture it.
-    assert.equal(r.lines[r.lines.length - 1], "ivy-research");
-  } finally {
-    if (prev === undefined) delete process.env.MAESTRO_SCOPED_PERMISSIONS; else process.env.MAESTRO_SCOPED_PERMISSIONS = prev;
-  }
-});
-
-test("spawn falls back to screen -dmS when tmux is absent", async () => {
-  const root = agentRepo();
-  const d = deps({ exec: fakeExec({ "screen -dmS": { status: 0 }, "screen -ls": { status: 0, stdout: "\t9.maestro-ivy-brief\t(Detached)\n" } }) });
-  const r = await run(["spawn", "--name", "brief", "Draft the brief"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  const call = d.exec.calls.find((c) => c[0] === "screen" && c[1] === "-dmS");
-  assert.ok(call, JSON.stringify(d.exec.calls));
-  assert.equal(call[2], "maestro-ivy-brief");
-  assert.ok(call.includes("/stub/claude"));
-  assert.ok(call.includes("ivy-brief"));
-});
-
-test("spawn validates the slug, requires a prompt, and refuses a duplicate live peer", async () => {
-  const root = agentRepo();
-  const d = deps({ exec: fakeExec({ "tmux -V": { status: 0 }, "tmux new-session": { status: 0 }, "tmux has-session": { status: 0 } }) });
-  assert.equal((await run(["spawn", "--name", "Bad Slug!", "x"], opts(root, d))).ok, false);
-  assert.equal((await run(["spawn", "--name", "ok-slug"], opts(root, d))).ok, false, "prompt required");
-  assert.equal((await run(["spawn", "x"], opts(root, d))).ok, false, "--name required");
-  assert.equal((await run(["spawn", "--name", "dup", "first"], opts(root, d))).ok, true);
-  const again = await run(["spawn", "--name", "dup", "second"], opts(root, d));
-  assert.equal(again.ok, false);
-  assert.match(again.lines.join("\n"), /already running/);
-  assert.equal(d.exec.calls.filter((c) => c[1] === "new-session").length, 1);
-});
-
-test("peers lists live peers and prunes dead ones from peers.json", async () => {
-  const root = agentRepo();
-  writeJson(join(root, "state", "session", "peers.json"), { peers: [
-    { name: "ivy-live", muxName: "maestro-ivy-live", startedAt: "2026-09-08T11:00:00Z", purpose: "p" },
-    { name: "ivy-dead", muxName: "maestro-ivy-dead", startedAt: "2026-09-08T10:00:00Z", purpose: "q" },
-  ] });
-  const d = deps({ exec: (cmd, args) => {
-    d.exec.calls.push([cmd, ...args]);
-    if (cmd === "tmux" && args[0] === "has-session") return { status: args[2] === "maestro-ivy-live" ? 0 : 1, stdout: "", stderr: "" };
-    return { status: 1, stdout: "", stderr: "" };
-  } });
-  d.exec.calls = [];
-  const r = await run(["peers", "--json"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  const out = JSON.parse(r.lines.join("\n"));
-  assert.deepEqual(out.map((p) => p.name), ["ivy-live"]);
-  const onDisk = JSON.parse(readFileSync(join(root, "state", "session", "peers.json"), "utf8"));
-  assert.deepEqual(onDisk.peers.map((p) => p.name), ["ivy-live"], "dead peer pruned from disk");
-  const human = await run(["peers"], opts(root, d));
-  assert.match(human.lines.join("\n"), /ivy-live/);
-});
-
-// ---------------------------------------------------------------------------
-// handoffs / ack
-// ---------------------------------------------------------------------------
-
-test("handoffs lists open handoffs (not done/) with age and deadline", async () => {
-  const root = agentRepo();
-  mkdirSync(join(root, "state", "session", "handoffs", "done"), { recursive: true });
-  writeJson(join(root, "state", "session", "handoffs", "t1.json"), { tickId: "t1", cadence: "daily-morning-brief", mode: "escalate", promptPath: "/p/t1.md", enqueuedAt: NOW - 120_000, deadlineAt: NOW + 60_000 });
-  writeJson(join(root, "state", "session", "handoffs", "t2.json"), { tickId: "t2", cadence: "inbox-processor", mode: "guarded", promptPath: "/p/t2.md", enqueuedAt: new Date(NOW - 30_000).toISOString(), deadlineAt: new Date(NOW - 1000).toISOString() });
-  writeJson(join(root, "state", "session", "handoffs", "done", "t0.json"), { tickId: "t0" });
-  writeFileSync(join(root, "state", "session", "handoffs", "garbage.json"), "{not json");
-  const d = deps();
-  const r = await run(["handoffs", "--json"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  const list = JSON.parse(r.lines.join("\n"));
-  assert.deepEqual(list.map((h) => h.tickId).sort(), ["t1", "t2"]);
-  const t1 = list.find((h) => h.tickId === "t1");
-  assert.equal(t1.ageMs, 120_000);
-  assert.equal(t1.overdue, false);
-  assert.equal(list.find((h) => h.tickId === "t2").overdue, true);
-  const human = await run(["handoffs"], opts(root, d));
-  assert.match(human.lines.join("\n"), /daily-morning-brief/);
-  assert.match(human.lines.join("\n"), /overdue/i);
-  const empty = await run(["handoffs"], opts(agentRepo(), d));
-  assert.match(empty.lines.join("\n"), /no open handoffs/i);
-});
-
-test("ack delegates to lib/cli/session-ack.mjs when present and fails clearly when absent", async () => {
-  const root = agentRepo();
-  const d = deps();
-  // Absent module → clear message, non-zero, nothing thrown.
-  const missing = await run(["ack", "t1"], opts(root, d, { ackModule: "./__no_such_session_ack__.mjs" }));
-  assert.equal(missing.ok, false);
-  assert.match(missing.lines.join("\n"), /session-ack/);
-  // Present module → called with {agentRoot, tickId, resultPath}.
-  const fake = mkdtempSync(join(tmpdir(), "ack-mod-"));
-  const modPath = join(fake, "session-ack.mjs");
-  writeFileSync(modPath, "export async function ackHandoff(a){ globalThis.__ackArgs = a; return { ok: true, tickId: a.tickId, movedTo: 'done/' + a.tickId + '.json' }; }\n");
-  const r = await run(["ack", "t1", "--result", "/tmp/r.md"], opts(root, d, { ackModule: modPath }));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  assert.equal(globalThis.__ackArgs.tickId, "t1");
-  assert.equal(globalThis.__ackArgs.agentRoot, root);
-  assert.equal(globalThis.__ackArgs.resultPath, "/tmp/r.md");
-  assert.match(r.lines.join("\n"), /t1/);
-  delete globalThis.__ackArgs;
-  assert.equal((await run(["ack"], opts(root, d, { ackModule: modPath }))).ok, false, "tickId required");
-});
-
-// ---------------------------------------------------------------------------
-// usage / unknown
-// ---------------------------------------------------------------------------
-
-test("help and unknown subcommands", async () => {
-  const root = agentRepo();
-  const d = deps();
-  const h = await run([], opts(root, d));
-  assert.equal(h.ok, true);
-  assert.equal(h.lines.join("\n"), usage());
-  for (const sub of ["status", "attach", "start", "stop", "restart", "spawn", "peers", "handoffs", "ack"]) {
-    assert.match(usage(), new RegExp(`\\b${sub}\\b`), `usage must mention ${sub}`);
-  }
-  const u = await run(["nope"], opts(root, d));
-  assert.equal(u.ok, false);
-  assert.equal(u.code, 2);
-});
-
-// ---------------------------------------------------------------------------
-// Review fixes (2026-09-08)
-// ---------------------------------------------------------------------------
-
-test("resolveFirstName falls back to config/agent.ts firstName (legacy seat) before the dir basename", () => {
-  const root = join(mkdtempSync(join(tmpdir(), "legacy-")), "assistant-ai");
-  mkdirSync(join(root, "config"), { recursive: true });
-  writeFileSync(join(root, "config", "agent.ts"), "export const agent = {\n  firstName: 'Ravi',\n  lastName: \"Patel\",\n};\n");
-  assert.equal(resolveFirstName(root), "ravi", "same chain as generate-plists.sh: agent.json → agent.ts → basename");
-  // A type-only declaration must not match.
-  writeFileSync(join(root, "config", "agent.ts"), "interface A { firstName: string; }\n");
-  assert.equal(resolveFirstName(root), "assistant");
-});
-
-test("buildSpawnArgs: a peer is interactive — scoped mode uses the configured allowlist or bypass, never the read-only --print default", () => {
-  const scoped = { MAESTRO_SCOPED_PERMISSIONS: "1" };
-  const p = withParallelism("p"); // the prompt as the peer actually receives it (WP-M7)
-  assert.deepEqual(buildSpawnArgs({ first: "ivy", slug: "fix", prompt: "p", env: scoped }),
-    ["--name", "ivy-fix", "--dangerously-skip-permissions", p]);
-  assert.deepEqual(buildSpawnArgs({ first: "ivy", slug: "fix", prompt: "p", env: scoped, allowedTools: ["Read", " Edit ", "", "Bash"] }),
-    ["--name", "ivy-fix", "--allowedTools", "Read,Edit,Bash", p]);
-  // Unscoped: the allowlist is ignored (byte-for-byte the pre-H1 posture).
-  assert.deepEqual(buildSpawnArgs({ first: "ivy", slug: "fix", prompt: "p", env: {}, allowedTools: ["Read"] }),
-    ["--name", "ivy-fix", "--dangerously-skip-permissions", p]);
-});
-
-test("spawn honours config/session.yaml `mux:` (M1 loadSessionConfig) over tmux-on-PATH and MAESTRO_SESSION_MUX", async () => {
-  const root = agentRepo();
-  const d = deps({
-    env: { MAESTRO_SESSION_MUX: "tmux" },
-    loadSessionConfig: async () => ({ mux: "screen", allowedTools: [] }),
-    exec: fakeExec({ "tmux -V": { status: 0, stdout: "tmux 3.4" }, "screen -dmS": { status: 0 }, "screen -ls": { status: 0, stdout: "\t9.maestro-ivy-brief\t(Detached)\n" } }),
-  });
-  const r = await run(["spawn", "--name", "brief", "Draft"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  assert.equal(r.data.kind, "screen");
-  assert.ok(!d.exec.calls.some((c) => c[1] === "new-session"), "must not start a tmux server when config says screen");
-  // config `auto` → env preference is consulted; a failing config loader is fail-open.
-  const d2 = deps({ env: { MAESTRO_SESSION_MUX: "screen" }, loadSessionConfig: async () => { throw new Error("boom"); },
-    exec: fakeExec({ "tmux -V": { status: 0 }, "screen -dmS": { status: 0 } }) });
-  const r2 = await run(["spawn", "--name", "two", "Draft"], opts(root, d2));
-  assert.equal(r2.ok, true, r2.lines.join("\n"));
-  assert.equal(r2.data.kind, "screen");
-});
-
-test("spawn in scoped mode passes the configured allowlist to the peer", async () => {
-  const root = agentRepo();
-  const d = deps({
-    env: { MAESTRO_SCOPED_PERMISSIONS: "1" },
-    loadSessionConfig: async () => ({ mux: "tmux", allowedTools: ["Read", "Edit", "Bash"] }),
-    exec: fakeExec({ "tmux -V": { status: 0 }, "tmux new-session": { status: 0 } }),
-  });
-  const r = await run(["spawn", "--name", "fix-ci", "Fix CI"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  const call = d.exec.calls.find((c) => c[1] === "new-session");
-  assert.ok(call.includes("--allowedTools") && call.includes("Read,Edit,Bash"), JSON.stringify(call));
-  assert.ok(!call.includes("--dangerously-skip-permissions"));
-});
-
-test("status hides an upgrade notice whose `to` is already the installed version", async () => {
-  const root = agentRepo();
-  writeJson(join(root, "state", "session", "upgrade-notice.json"), { from: "2.11.17", to: "2.12.0", at: "2026-09-08T11:59:00Z" });
-  const applied = deps({ installedVersion: "2.12.0" });
-  const s1 = JSON.parse((await run(["status", "--json"], opts(root, applied))).lines.join("\n"));
-  assert.equal(s1.upgradeNotice, null, "an applied upgrade is not pending");
-  assert.equal(s1.sdkVersion, "2.12.0");
-  const brief = await run(["status", "--brief"], opts(root, applied));
-  assert.ok(!/upgrade/.test(brief.lines[0]), brief.lines[0]);
-  const pending = deps({ installedVersion: "2.11.17" });
-  const s2 = JSON.parse((await run(["status", "--json"], opts(root, pending))).lines.join("\n"));
-  assert.equal(s2.upgradeNotice.to, "2.12.0");
-  assert.match((await run(["status", "--brief"], opts(root, pending))).lines[0], /upgrade → 2\.12\.0/);
-});
-
-test("restart on a job that is not loaded starts it WITHOUT leaving a restart marker; a missing plist writes nothing", async () => {
-  const root = agentRepo();
-  const marker = join(root, "state", "session", "restart-requested");
-  // Plist absent → fail, no marker.
-  const none = deps();
-  const r0 = await run(["restart"], opts(root, none));
-  assert.equal(r0.ok, false);
-  assert.ok(!existsSync(marker), "no marker when the command fails");
-  // Installed but not loaded → bootstrap + kickstart, no marker (nothing is running to restart).
-  const d = deps({ exec: fakeExec({ "launchctl bootstrap": { status: 0 }, "launchctl kickstart": { status: 0 } }) });
-  writeFileSync(join(d.home, "Library", "LaunchAgents", "ai.maestro.ivy-session.plist"), "<plist/>");
-  const r = await run(["restart"], opts(root, d));
-  assert.equal(r.ok, true, r.lines.join("\n"));
-  assert.ok(!existsSync(marker), "a fresh start must not carry a restart-requested marker");
-  assert.deepEqual(d.exec.calls.filter((c) => c[0] === "launchctl").map((c) => c[1]), ["list", "bootstrap", "kickstart"]);
-  assert.match(r.lines.join("\n"), /not running|started/i);
-});
-
-test("peers.json survives concurrent registration from separate processes (lock)", async () => {
-  const root = agentRepo();
-  const paths = sessionPaths(root);
-  const modUrl = new URL("./session.mjs", import.meta.url).href;
-  const script = join(root, "worker.mjs");
-  writeFileSync(script, `import { updatePeers, sessionPaths } from ${JSON.stringify(modUrl)};
-const [root, tag, n] = process.argv.slice(2);
-const paths = sessionPaths(root);
-for (let i = 0; i < Number(n); i++) {
-  const r = updatePeers(paths, (peers) => [...peers, { name: tag + "-" + i, muxName: "m-" + tag + "-" + i }]);
-  if (!r.ok) { console.error(r.error); process.exit(1); }
-}
-`);
-  const { spawn } = await import("node:child_process");
-  const runWorker = (tag) => new Promise((resolve) => {
-    const p = spawn(process.execPath, [script, root, tag, "25"], { stdio: ["ignore", "ignore", "pipe"] });
-    let err = ""; p.stderr.on("data", (c) => { err += c; });
-    p.on("exit", (code) => resolve({ code, err }));
-  });
-  const results = await Promise.all(["a", "b", "c"].map(runWorker));
-  for (const r of results) assert.equal(r.code, 0, r.err);
-  const onDisk = JSON.parse(readFileSync(paths.peers, "utf8")).peers;
-  assert.equal(onDisk.length, 75, `every registration must survive; got ${onDisk.length}`);
-  assert.ok(!existsSync(`${paths.peers}.lock`), "the lock is released");
-});
-
-test("updatePeers breaks a stale lock and reports a live one it cannot acquire", () => {
-  const root = agentRepo();
-  const paths = sessionPaths(root);
-  mkdirSync(paths.dir, { recursive: true });
-  const lock = `${paths.peers}.lock`;
-  // Stale: mtime far in the past relative to the injected clock.
-  writeFileSync(lock, "999999\n");
-  const r = updatePeers(paths, (p) => [...p, { name: "x", muxName: "m-x" }], { now: () => NOW, lockMtimeMs: () => NOW - 120_000, waitMs: 50 });
-  assert.equal(r.ok, true, r.error);
-  assert.equal(JSON.parse(readFileSync(paths.peers, "utf8")).peers.length, 1);
-  assert.ok(!existsSync(lock));
-  // Live: fresh lock held by someone else → gives up after waitMs, without clobbering.
-  // (A ticking clock: the deadline is measured on `now`, so a frozen one would spin.)
-  writeFileSync(lock, "1\n");
-  let t = NOW;
-  const r2 = updatePeers(paths, (p) => [...p, { name: "y", muxName: "m-y" }], { now: () => (t += 20), lockMtimeMs: () => NOW, waitMs: 50 });
-  assert.equal(r2.ok, false);
-  assert.match(String(r2.error), /lock/i);
-  assert.equal(JSON.parse(readFileSync(paths.peers, "utf8")).peers.length, 1, "registry untouched");
-});
-
-test("ack prints the destination path from ackHandoff ({ok, path, already}) and says when it was already acked", async () => {
-  const root = agentRepo();
-  const d = deps();
-  const fake = mkdtempSync(join(tmpdir(), "ack-mod2-"));
-  const modPath = join(fake, "session-ack.mjs");
-  writeFileSync(modPath, "let n = 0; export async function ackHandoff(a){ n++; return { ok: true, path: '/s/handoffs/done/' + a.tickId + '.json', already: n > 1 }; }\n");
-  const r1 = await run(["ack", "t1"], opts(root, d, { ackModule: modPath }));
-  assert.equal(r1.ok, true, r1.lines.join("\n"));
-  assert.match(r1.lines.join("\n"), /acked t1 → \/s\/handoffs\/done\/t1\.json/);
-  const r2 = await run(["ack", "t1"], opts(root, d, { ackModule: modPath }));
-  assert.equal(r2.ok, true);
-  assert.match(r2.lines.join("\n"), /already acked/);
-});