@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/scripts/session/supervisor.test.mjs

@@ -0,0 +1,482 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { join } from "node:path";
+
+import { runSupervisor, EXIT_ANOTHER_HOLDS_LOCK, EXIT_RELAUNCH, waitForProbe } from "./supervisor.mjs";
+import { sessionPaths } from "../../lib/session/config.mjs";
+import { BOOTSTRAP_PROMPT, SESSION_EXIT_SCRIPT } from "../../lib/session/launch-args.mjs";
+import { BACKOFF_MS, MAX_ROTATIONS_PER_HOUR } from "../../lib/session/identity.mjs";
+
+const ROOT = "/agent";
+const P = sessionPaths(ROOT);
+const T0 = Date.parse("2026-09-08T10:00:00Z");
+const UUID = "11111111-2222-4333-8444-555555555555";
+const UUID2 = "22222222-3333-4444-8555-666666666666";
+
+/**
+ * A fake world: in-memory files, a scripted execFile, a controllable clock.
+ * `script` maps `<file> <args[0]>` → handler({file,args}) returning {code, stdout}
+ * (or a number code). Every call is recorded in `calls`.
+ */
+function world(opts = {}) {
+  const files = { [join(ROOT, "config", "agent.json")]: JSON.stringify({ firstName: "Olivia" }), ...(opts.files || {}) };
+  const calls = [];
+  const logs = [];
+  const sleeps = [];
+  const timers = [];
+  let t = T0;
+  const deps = {
+    agentRoot: ROOT,
+    env: opts.env || {},
+    acquireLock: opts.acquireLock || (() => true),
+    existsSync: (p) => (opts.exists ? opts.exists(p) : p === "/usr/bin/screen"),
+    readFileSync: (p) => { if (!(p in files)) { const e = new Error(`ENOENT ${p}`); e.code = "ENOENT"; throw e; } return files[p]; },
+    writeJsonAtomic: (p, obj) => { files[p] = JSON.stringify(obj); },
+    mkdirSync: () => {},
+    unlinkSync: (p) => { delete files[p]; },
+    now: () => t,
+    advance: (ms) => { t += ms; },
+    sleep: async (ms) => { sleeps.push(ms); t += ms; },
+    log: (line) => logs.push(line),
+    uuid: opts.uuid || (() => UUID2),
+    claudeBin: "/Users/o/.local/bin/claude",
+    permissionArgs: ["--dangerously-skip-permissions"],
+    pollMs: 0,
+    homeDir: opts.homeDir === undefined ? "/Users/o" : opts.homeDir,
+    writeFileAtomic: (p, data) => { files[p] = String(data); },
+    after: (ms, fn) => { const entry = { ms, fn }; timers.push(entry); return () => { const i = timers.indexOf(entry); if (i >= 0) timers.splice(i, 1); }; },
+    execFile: async (file, args) => {
+      calls.push({ file, args });
+      const key = `${file} ${args[0]}`;
+      const h = opts.script && opts.script[key];
+      const r = typeof h === "function" ? await h({ file, args, world: w }) : h;
+      if (typeof r === "number") return { code: r, stdout: "", stderr: "" };
+      return r || { code: 0, stdout: "", stderr: "" };
+    },
+    loadConfig: async () => ({ frontDoor: "session", mux: "auto", resume: true, services: ["cohort"], ...(opts.config || {}) }),
+  };
+  const w = { deps, files, calls, logs, sleeps, timers, get t() { return t; } };
+  return w;
+}
+
+const record = (over = {}) => JSON.stringify({ sessionId: UUID, createdAt: "2026-09-08T09:00:00Z", resumes: 1, rotations: [], ...over });
+
+test("exit 0 when another supervisor holds the lock — nothing is executed", async () => {
+  const w = world({ acquireLock: () => false });
+  assert.equal(await runSupervisor(w.deps), EXIT_ANOTHER_HOLDS_LOCK);
+  assert.equal(EXIT_ANOTHER_HOLDS_LOCK, 0);
+  assert.deepEqual(w.calls, []);
+});
+
+test("exit 0 when the front door is the daemon (nothing to supervise)", async () => {
+  const w = world({ config: { frontDoor: "daemon" } });
+  assert.equal(await runSupervisor(w.deps), 0);
+  assert.deepEqual(w.calls, []);
+  assert.ok(w.logs.some((l) => /frontDoor/.test(l)));
+});
+
+test("screen, first launch: --session-id with a fresh id, foreground -D -m, exit 75 when the session ends", async () => {
+  const w = world({
+    uuid: () => UUID,
+    script: {
+      "/usr/bin/screen -ls": { code: 1, stdout: "No Sockets found in /tmp/.screen.\n" },
+      "/usr/bin/screen -D": ({ world }) => { world.deps.advance(3_600_000); world.files[P.lastExitFile] = "0\n"; return 0; },
+    },
+  });
+  assert.equal(await runSupervisor(w.deps), EXIT_RELAUNCH);
+  assert.equal(EXIT_RELAUNCH, 75);
+  const start = w.calls.find((c) => c.args[0] === "-D");
+  assert.deepEqual(start.args, [
+    "-D", "-m", "-S", "maestro-olivia",
+    "/bin/sh", "-c", SESSION_EXIT_SCRIPT, "maestro-session", P.lastExitFile,
+    "/Users/o/.local/bin/claude", "--name", "olivia-main", "--session-id", UUID, "--dangerously-skip-permissions", BOOTSTRAP_PROMPT,
+  ]);
+  const saved = JSON.parse(w.files[P.mainSessionFile]);
+  assert.equal(saved.sessionId, UUID);
+  assert.equal(saved.resumes, 1);
+  assert.equal(saved.lastLaunchAt, "2026-09-08T10:00:00.000Z");
+});
+
+test("permission args come from sessionPermissionArgs({source:'main-session', allowedTools: cfg.allowedTools}) when not injected", async () => {
+  const prev = process.env.MAESTRO_SCOPED_PERMISSIONS;
+  try {
+    process.env.MAESTRO_SCOPED_PERMISSIONS = "1";
+    const run = async (config) => {
+      const w = world({
+        files: { [P.mainSessionFile]: record() },
+        config,
+        env: process.env, // sessionPermissionArgs reads the switch from process.env
+        script: {
+          "/usr/bin/screen -ls": { code: 1, stdout: "No Sockets found\n" },
+          "/usr/bin/screen -D": ({ world }) => { world.deps.advance(60_000); world.files[P.lastExitFile] = "0\n"; return 0; },
+        },
+      });
+      w.deps.permissionArgs = null; // use the real resolver
+      assert.equal(await runSupervisor(w.deps), 75);
+      return w;
+    };
+    // Scoped mode with no main-session allowlist: bypass (an unattended
+    // interactive session must never block on a permission prompt), logged.
+    let w = await run({});
+    let start = w.calls.find((c) => c.args[0] === "-D");
+    assert.ok(start.args.includes("--dangerously-skip-permissions"));
+    assert.ok(!start.args.includes("--allowedTools"));
+    assert.ok(w.logs.some((l) => /MAESTRO_SCOPED_PERMISSIONS/.test(l) && /allowedTools/.test(l)));
+    // An operator-defined allowlist in config/session.yaml is honoured.
+    w = await run({ allowedTools: ["Read", "Monitor", "mcp__cohort__*"] });
+    start = w.calls.find((c) => c.args[0] === "-D");
+    const i = start.args.indexOf("--allowedTools");
+    assert.ok(i > 0);
+    assert.equal(start.args[i + 1], "Read,Monitor,mcp__cohort__*");
+    assert.ok(!start.args.includes("--dangerously-skip-permissions"));
+  } finally {
+    if (prev === undefined) delete process.env.MAESTRO_SCOPED_PERMISSIONS; else process.env.MAESTRO_SCOPED_PERMISSIONS = prev;
+  }
+});
+
+test("screen, relaunch: --resume with the stable id; a clean end after a long run keeps the id", async () => {
+  const w = world({
+    files: { [P.mainSessionFile]: record({ resumes: 3 }) },
+    script: {
+      "/usr/bin/screen -ls": { code: 1, stdout: "No Sockets found\n" },
+      "/usr/bin/screen -D": ({ world }) => { world.deps.advance(60_000); world.files[P.lastExitFile] = "0\n"; return 0; },
+    },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  const start = w.calls.find((c) => c.args[0] === "-D");
+  assert.ok(start.args.includes("--resume"));
+  assert.ok(start.args.includes(UUID));
+  assert.ok(!start.args.includes("--session-id"));
+  const saved = JSON.parse(w.files[P.mainSessionFile]);
+  assert.equal(saved.sessionId, UUID);
+  assert.equal(saved.resumes, 4);
+  assert.deepEqual(w.sleeps, []);
+});
+
+test("resume dies non-zero inside 20 s → rotate to a fresh id, then exit 75", async () => {
+  const w = world({
+    files: { [P.mainSessionFile]: record() },
+    script: {
+      "/usr/bin/screen -ls": { code: 1, stdout: "" },
+      "/usr/bin/screen -D": ({ world }) => { world.deps.advance(4_000); world.files[P.lastExitFile] = "1\n"; return 0; },
+    },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  const saved = JSON.parse(w.files[P.mainSessionFile]);
+  assert.equal(saved.sessionId, UUID2);
+  assert.equal(saved.resumes, 0);
+  assert.equal(saved.rotatedFrom, UUID);
+  assert.equal(saved.rotations.length, 1);
+  assert.ok(w.logs.some((l) => /rotat/i.test(l)));
+  assert.deepEqual(w.sleeps, []);
+});
+
+test("resume dies inside 20 s with no exit file at all → still treated as a failure (rotate)", async () => {
+  const w = world({
+    files: { [P.mainSessionFile]: record() },
+    script: { "/usr/bin/screen -ls": { code: 1, stdout: "" }, "/usr/bin/screen -D": ({ world }) => { world.deps.advance(1_000); return 0; } },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.equal(JSON.parse(w.files[P.mainSessionFile]).sessionId, UUID2);
+});
+
+test("a stale exit file from a previous run is removed before launch", async () => {
+  const w = world({
+    files: { [P.mainSessionFile]: record(), [P.lastExitFile]: "1\n" },
+    script: { "/usr/bin/screen -ls": { code: 1, stdout: "" }, "/usr/bin/screen -D": ({ world }) => { world.deps.advance(600_000); return 0; } },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  // Long-lived + unknown code = relaunch, not rotate; and the stale "1" must not have been read.
+  assert.equal(JSON.parse(w.files[P.mainSessionFile]).sessionId, UUID);
+});
+
+test("rotation budget spent (3 in the last hour) → sleep 10 min, exit 75, id unchanged", async () => {
+  const recent = Array.from({ length: MAX_ROTATIONS_PER_HOUR }, (_, i) => new Date(T0 - (i + 1) * 60_000).toISOString());
+  const w = world({
+    files: { [P.mainSessionFile]: record({ rotations: recent }) },
+    script: { "/usr/bin/screen -ls": { code: 1, stdout: "" }, "/usr/bin/screen -D": ({ world }) => { world.deps.advance(2_000); world.files[P.lastExitFile] = "1\n"; return 0; } },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.deepEqual(w.sleeps, [BACKOFF_MS]);
+  assert.equal(JSON.parse(w.files[P.mainSessionFile]).sessionId, UUID);
+});
+
+test("resume:false → every launch is a fresh --session-id", async () => {
+  const w = world({
+    config: { resume: false },
+    files: { [P.mainSessionFile]: record({ resumes: 5 }) },
+    script: { "/usr/bin/screen -ls": { code: 1, stdout: "" }, "/usr/bin/screen -D": ({ world }) => { world.deps.advance(1_000); world.files[P.lastExitFile] = "1\n"; return 0; } },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  const start = w.calls.find((c) => c.args[0] === "-D");
+  assert.ok(start.args.includes("--session-id"));
+  assert.ok(start.args.includes(UUID2));
+  // A fresh-id launch never rotates, whatever its exit.
+  assert.equal(JSON.parse(w.files[P.mainSessionFile]).sessionId, UUID2);
+  assert.equal(JSON.parse(w.files[P.mainSessionFile]).resumes, 1);
+});
+
+test("an orphaned screen session (no lock holder) is adopted: no new launch, block until it is gone, exit 75", async () => {
+  let polls = 0;
+  const w = world({
+    files: { [P.mainSessionFile]: record() },
+    script: {
+      "/usr/bin/screen -ls": () => {
+        polls++;
+        return polls <= 3 ? { code: 0, stdout: "There is a screen on:\n\t4242.maestro-olivia\t(Detached)\n1 Socket in /tmp/.screen.\n" } : { code: 1, stdout: "No Sockets found in /tmp/.screen.\n" };
+      },
+    },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.ok(!w.calls.some((c) => c.args[0] === "-D"), "must not launch a second session");
+  assert.equal(polls, 4);
+  assert.ok(w.logs.some((l) => /adopt/i.test(l)));
+});
+
+test("a DEAD screen socket (SIGKILLed screen) is wiped, not adopted: a new session is launched", async () => {
+  let lsCalls = 0;
+  const w = world({
+    files: { [P.mainSessionFile]: record() },
+    script: {
+      "/usr/bin/screen -wipe": { code: 0, stdout: "There is a screen on:\n\t82332.maestro-olivia\t(Removed)\n1 socket wiped out.\nNo Sockets found in /tmp/.screen.\n" },
+      "/usr/bin/screen -ls": () => {
+        lsCalls++;
+        // Even if -wipe did nothing (old screen, EPERM), -ls still says Dead.
+        return { code: 0, stdout: "There is a screen on:\n\t82332.maestro-olivia\t(Dead ???)\nRemove dead screens with 'screen -wipe'.\n1 Socket in /tmp/.screen.\n" };
+      },
+      "/usr/bin/screen -D": ({ world }) => { world.deps.advance(60_000); world.files[P.lastExitFile] = "0\n"; return 0; },
+    },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  const order = w.calls.filter((c) => c.file === "/usr/bin/screen").map((c) => c.args[0]);
+  assert.deepEqual(order, ["-wipe", "-ls", "-D"], "wipe dead sockets, probe once, then launch");
+  assert.equal(lsCalls, 1, "must not poll a dead socket");
+  assert.ok(!w.logs.some((l) => /adopt/i.test(l)));
+});
+
+test("a failing/throwing `screen -wipe` is ignored (fail-open): the orphan probe and launch still run", async () => {
+  const w = world({
+    files: { [P.mainSessionFile]: record() },
+    script: {
+      "/usr/bin/screen -wipe": () => { throw new Error("EACCES"); },
+      "/usr/bin/screen -ls": { code: 1, stdout: "No Sockets found in /tmp/.screen.\n" },
+      "/usr/bin/screen -D": ({ world }) => { world.deps.advance(60_000); world.files[P.lastExitFile] = "0\n"; return 0; },
+    },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.ok(w.calls.some((c) => c.args[0] === "-D"));
+});
+
+const CLAUDE_JSON = join("/Users/o", ".claude.json");
+const quietRun = (over = {}) => ({
+  files: { [P.mainSessionFile]: record(), ...(over.files || {}) },
+  script: {
+    "/usr/bin/screen -ls": { code: 1, stdout: "No Sockets found\n" },
+    "/usr/bin/screen -D": ({ world }) => { world.deps.advance(60_000); world.files[P.lastExitFile] = "0\n"; return 0; },
+    ...(over.script || {}),
+  },
+  ...over,
+});
+
+test("first-run dialogs are pre-answered: ~/.claude.json gets the bypass acknowledgement and the trust flag for the agent dir before launch", async () => {
+  const w = world(quietRun());
+  assert.equal(await runSupervisor(w.deps), 75);
+  const cfg = JSON.parse(w.files[CLAUDE_JSON]);
+  assert.equal(cfg.bypassPermissionsModeAccepted, true);
+  assert.equal(cfg.projects[ROOT].hasTrustDialogAccepted, true);
+  assert.ok(w.logs.some((l) => /claude\.json/.test(l) && /seeded/.test(l)));
+  // Seeding happens BEFORE the launch.
+  const seededAt = w.logs.findIndex((l) => /seeded/.test(l));
+  const launchedAt = w.logs.findIndex((l) => /^launching/.test(l));
+  assert.ok(seededAt >= 0 && seededAt < launchedAt);
+});
+
+test("an already-seeded ~/.claude.json is not rewritten; a malformed one is left alone (logged) and the launch proceeds", async () => {
+  const seeded = JSON.stringify({ theme: "dark", bypassPermissionsModeAccepted: true, projects: { [ROOT]: { hasTrustDialogAccepted: true } } });
+  let w = world(quietRun({ files: { [CLAUDE_JSON]: seeded } }));
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.equal(w.files[CLAUDE_JSON], seeded, "byte-identical: no write");
+  assert.ok(!w.logs.some((l) => /seeded/.test(l)));
+
+  w = world(quietRun({ files: { [CLAUDE_JSON]: "{oops" } }));
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.equal(w.files[CLAUDE_JSON], "{oops");
+  assert.ok(w.logs.some((l) => /claude\.json/.test(l) && /malformed/.test(l)));
+  assert.ok(w.calls.some((c) => c.args[0] === "-D"), "still launched");
+});
+
+test("the bypass acknowledgement is seeded only when the launch actually bypasses; the trust flag always", async () => {
+  const w = world(quietRun());
+  w.deps.permissionArgs = ["--allowedTools", "Read,Monitor"];
+  assert.equal(await runSupervisor(w.deps), 75);
+  const cfg = JSON.parse(w.files[CLAUDE_JSON]);
+  assert.equal("bypassPermissionsModeAccepted" in cfg, false);
+  assert.equal(cfg.projects[ROOT].hasTrustDialogAccepted, true);
+});
+
+test("a session alive past the grace period with no heartbeat is flagged: log line + state/session/attention.json with the attach command", async () => {
+  const w = world(quietRun({
+    script: {
+      "/usr/bin/screen -D": ({ world }) => {
+        // 120 s in, the watchdog fires; nothing has beaten.
+        world.deps.advance(120_000);
+        assert.equal(world.timers.length, 1);
+        assert.equal(world.timers[0].ms, 120_000);
+        world.timers[0].fn();
+        world.deps.advance(3_600_000);
+        world.files[P.lastExitFile] = "0\n";
+        return 0;
+      },
+    },
+  }));
+  assert.equal(await runSupervisor(w.deps), 75);
+  const att = JSON.parse(w.files[P.attentionFile]);
+  assert.equal(att.reason, "no-heartbeat");
+  assert.equal(att.attach, "screen -r maestro-olivia");
+  assert.equal(att.since, "2026-09-08T10:00:00.000Z");
+  assert.ok(w.logs.some((l) => /no heartbeat/i.test(l) && /screen -r maestro-olivia/.test(l)));
+});
+
+test("a session that beats is not flagged, a stale marker from a previous run is cleared at launch, and the timer is cancelled at the end", async () => {
+  const w = world(quietRun({
+    files: { [P.attentionFile]: JSON.stringify({ reason: "no-heartbeat" }), [P.heartbeatFile]: JSON.stringify({ ts: "2026-09-08T09:00:00.000Z" }) },
+    script: {
+      "/usr/bin/screen -D": ({ world }) => {
+        assert.equal(P.attentionFile in world.files, false, "cleared before the session starts");
+        world.deps.advance(15_000);
+        world.files[P.heartbeatFile] = JSON.stringify({ ts: new Date(world.t).toISOString(), pid: 1 });
+        world.deps.advance(105_000);
+        world.timers[0].fn();
+        world.deps.advance(3_600_000);
+        world.files[P.lastExitFile] = "0\n";
+        return 0;
+      },
+    },
+  }));
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.equal(P.attentionFile in w.files, false);
+  assert.ok(!w.logs.some((l) => /no heartbeat/i.test(l)));
+  assert.equal(w.timers.length, 0, "watchdog cancelled once the session ended");
+});
+
+test("SIGTERM while the session runs: the mux is told to quit, a death inside the window is NOT a rotation, exit 75", async () => {
+  let signal = null;
+  const w = world({
+    files: { [P.mainSessionFile]: record() },
+    script: {
+      "/usr/bin/screen -ls": { code: 1, stdout: "No Sockets found\n" },
+      "/usr/bin/screen -D": async ({ world }) => {
+        signal("SIGTERM"); // launchd stopping the job (kickstart -k / bootout)
+        world.deps.advance(3_000); // claude gets SIGHUP from screen and dies at once
+        world.files[P.lastExitFile] = "129\n";
+        return 0;
+      },
+      "/usr/bin/screen -S": 0,
+    },
+  });
+  w.deps.onSignal = (fn) => { signal = fn; };
+  assert.equal(await runSupervisor(w.deps), 75);
+  const stop = w.calls.find((c) => c.args[0] === "-S" && c.args.includes("-X"));
+  assert.deepEqual(stop.args, ["-S", "maestro-olivia", "-X", "quit"]);
+  assert.equal(JSON.parse(w.files[P.mainSessionFile]).sessionId, UUID, "a signal-induced death must not rotate the id");
+  assert.ok(w.logs.some((l) => /SIGTERM/.test(l)));
+  assert.ok(!w.logs.some((l) => /rotat/i.test(l)));
+});
+
+test("SIGTERM while adopting an orphan: the orphan is told to quit and the supervisor exits 75 once it is gone", async () => {
+  let signal = null;
+  let stopped = false;
+  const w = world({
+    files: { [P.mainSessionFile]: record() },
+    script: {
+      "/usr/bin/screen -ls": () => {
+        if (stopped) return { code: 1, stdout: "No Sockets found\n" };
+        if (signal) signal("SIGTERM");
+        return { code: 0, stdout: "There is a screen on:\n\t4242.maestro-olivia\t(Detached)\n" };
+      },
+      "/usr/bin/screen -S": () => { stopped = true; return 0; },
+    },
+  });
+  w.deps.onSignal = (fn) => { signal = fn; };
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.ok(w.calls.some((c) => c.args[0] === "-S" && c.args[3] === "quit"));
+  assert.ok(!w.calls.some((c) => c.args[0] === "-D"));
+});
+
+test("the singleton lock is taken WITHOUT its signal handlers (the supervisor owns SIGTERM)", async () => {
+  let lockOpts = null;
+  const w = world({ acquireLock: (name, opts) => { lockOpts = { name, opts }; return false; } });
+  await runSupervisor(w.deps);
+  assert.deepEqual(lockOpts, { name: "session", opts: { signals: false } });
+});
+
+test("tmux preferred when present: detached new-session, then has-session polled until the session ends", async () => {
+  let probes = 0;
+  const w = world({
+    files: { [P.mainSessionFile]: record() },
+    exists: (p) => p === "/opt/homebrew/bin/tmux" || p === "/usr/bin/screen",
+    script: {
+      "/opt/homebrew/bin/tmux has-session": ({ world }) => {
+        probes++;
+        if (probes === 1) return 1; // pre-launch orphan check: none
+        world.deps.advance(30_000);
+        if (probes < 4) return 0;
+        world.files[P.lastExitFile] = "0\n";
+        return 1;
+      },
+      "/opt/homebrew/bin/tmux new-session": 0,
+    },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  const start = w.calls.find((c) => c.args[0] === "new-session");
+  assert.deepEqual(start.args.slice(0, 6), ["new-session", "-d", "-s", "maestro-olivia", "-c", ROOT]);
+  assert.ok(start.args.includes("--resume"));
+  assert.equal(probes, 4);
+  assert.ok(!w.calls.some((c) => c.file === "/usr/bin/screen"));
+});
+
+test("tmux new-session itself failing is a failed launch (rotation rules apply)", async () => {
+  const w = world({
+    files: { [P.mainSessionFile]: record() },
+    exists: (p) => p === "/opt/homebrew/bin/tmux",
+    script: { "/opt/homebrew/bin/tmux has-session": 1, "/opt/homebrew/bin/tmux new-session": { code: 1, stdout: "", stderr: "server exited" } },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.equal(JSON.parse(w.files[P.mainSessionFile]).sessionId, UUID2);
+});
+
+test("config mux: screen wins over an installed tmux", async () => {
+  const w = world({
+    config: { mux: "screen" },
+    files: { [P.mainSessionFile]: record() },
+    exists: (p) => p === "/opt/homebrew/bin/tmux" || p === "/usr/bin/screen",
+    script: { "/usr/bin/screen -ls": { code: 1, stdout: "" }, "/usr/bin/screen -D": ({ world }) => { world.deps.advance(60_000); world.files[P.lastExitFile] = "0\n"; return 0; } },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.ok(w.calls.every((c) => c.file === "/usr/bin/screen"));
+});
+
+test("no multiplexer installed → log, back off, exit 75 (self-heals once one is installed)", async () => {
+  const w = world({ exists: () => false });
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.deepEqual(w.sleeps, [BACKOFF_MS]);
+  assert.deepEqual(w.calls, []);
+  assert.ok(w.logs.some((l) => /multiplexer/i.test(l)));
+});
+
+test("a throwing execFile is a failed launch, never an unhandled rejection", async () => {
+  const w = world({
+    files: { [P.mainSessionFile]: record() },
+    script: { "/usr/bin/screen -ls": { code: 1, stdout: "" }, "/usr/bin/screen -D": () => { throw new Error("spawn EACCES"); } },
+  });
+  assert.equal(await runSupervisor(w.deps), 75);
+  assert.ok(w.logs.some((l) => /EACCES/.test(l)));
+});
+
+test("waitForProbe: polls until the probe exits non-zero, sleeping pollMs between polls", async () => {
+  let n = 0;
+  const sleeps = [];
+  await waitForProbe({ file: "t", args: ["has-session"] }, { execFile: async () => ({ code: ++n < 3 ? 0 : 1 }), sleep: async (ms) => sleeps.push(ms), pollMs: 2_000 });
+  assert.equal(n, 3);
+  assert.deepEqual(sleeps, [2_000, 2_000]);
+});