@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/session/inbox-claims.test.mjs

@@ -0,0 +1,286 @@
+/**
+ * inbox-claims.test.mjs — session claims on inbox items + the assurance
+ * reopen sweep (design §3.3).
+ *
+ * `maestro inbox claim <id>` parks the item at `.yaml.dispatched` (the same
+ * durable-admission marker the daemon uses) and stamps `claimed_by: session`
+ * into the YAML. A claim neither replied nor done within 20 min is reopened
+ * (`.dispatched` → `.yaml`) by the daemon sweep; a `--until` deferral is
+ * reopened once its time passes. Clock injected; real fs on a tmp root.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, utimesSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  SESSION_CLAIM_STALE_MS,
+  sessionMarkerLines,
+  parseSessionMarkers,
+  stripSessionMarkers,
+  findInboxFile,
+  markSessionClaim,
+  markSessionDeferral,
+  markSessionReplied,
+  sweepSessionInbox,
+  sweepSessionInboxForDaemon,
+  DAEMON_ORPHAN_RECLAIM_MS,
+  REPLIED_RETIRE_MS,
+} from "./inbox-claims.mjs";
+
+const T0 = Date.parse("2026-09-08T10:00:00.000Z");
+const ITEM = `id: "cohort-abc123"
+service: "cohort"
+channel: "dm/olivia"
+channel_id: "ch_1"
+sender: "Olivia Chen"
+timestamp: "2026-09-08T09:59:00.000Z"
+subject: ""
+content: |
+  can you send me the deck?
+raw_ref: "cohort-abc123"
+`;
+
+function root() {
+  const dir = mkdtempSync(join(tmpdir(), "maestro-inbox-claims-"));
+  mkdirSync(join(dir, "state", "inbox", "cohort"), { recursive: true });
+  return dir;
+}
+function rm(dir) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* */ } }
+function plant(dir, name = "2026-09-08T09-59-00-000Z-cohort-abc123.yaml", body = ITEM) {
+  const p = join(dir, "state", "inbox", "cohort", name);
+  writeFileSync(p, body);
+  return p;
+}
+function ls(dir) { return readdirSync(join(dir, "state", "inbox", "cohort")).sort(); }
+
+test("markers: lines round-trip through parse and strip without touching the item", () => {
+  const lines = sessionMarkerLines({ claimedBy: "session", now: T0 });
+  const body = ITEM + lines;
+  assert.deepEqual(parseSessionMarkers(body), {
+    claimedBy: "session", claimedAt: new Date(T0).toISOString(), deferredUntil: null, deferredReason: null, repliedAt: null,
+  });
+  assert.equal(stripSessionMarkers(body), ITEM);
+  // Markers must be TOP-LEVEL keys: an indented look-alike inside a body block is ignored.
+  const forged = ITEM.replace("can you send me the deck?", "claimed_by: \"session\"\n  x");
+  assert.equal(parseSessionMarkers(forged).claimedBy, null);
+  assert.equal(stripSessionMarkers(forged), forged);
+  assert.deepEqual(parseSessionMarkers(""), { claimedBy: null, claimedAt: null, deferredUntil: null, deferredReason: null, repliedAt: null });
+});
+
+test("findInboxFile: locates an item by id in any state, reports the state; null when absent", () => {
+  const dir = root();
+  try {
+    plant(dir);
+    const f = findInboxFile(dir, "cohort-abc123");
+    assert.equal(f.service, "cohort");
+    assert.equal(f.state, "new");
+    assert.ok(f.path.endsWith(".yaml"));
+    assert.equal(findInboxFile(dir, "nope"), null);
+    // A specific service narrows the search; a wrong one finds nothing.
+    assert.equal(findInboxFile(dir, "cohort-abc123", { service: "slack" }), null);
+    plant(dir, "2026-09-08T09-59-00-000Z-cohort-abc123.yaml.dispatched");
+    rmSync(f.path);
+    assert.equal(findInboxFile(dir, "cohort-abc123").state, "claimed");
+  } finally { rm(dir); }
+});
+
+test("markSessionClaim: renames to .dispatched and stamps claimed_by/claimed_at; not claimable twice", () => {
+  const dir = root();
+  try {
+    plant(dir);
+    const r = markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 });
+    assert.equal(r.ok, true);
+    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-cohort-abc123.yaml.dispatched"]);
+    const body = readFileSync(r.path, "utf-8");
+    const m = parseSessionMarkers(body);
+    assert.equal(m.claimedBy, "session");
+    assert.equal(m.claimedAt, new Date(T0).toISOString());
+    assert.ok(body.startsWith(ITEM), "the item body is untouched above the markers");
+    const again = markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 + 1 });
+    assert.equal(again.ok, false);
+    assert.equal(again.error, "not-claimable");
+  } finally { rm(dir); }
+});
+
+test("markSessionDeferral: parks the item as .deferred with deferred_until/reason (from new or claimed)", () => {
+  const dir = root();
+  try {
+    plant(dir);
+    markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 });
+    const r = markSessionDeferral(dir, "cohort", { id: "cohort-abc123" }, { until: T0 + 30 * 60_000, reason: "waiting on finance", now: T0 });
+    assert.equal(r.ok, true);
+    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-cohort-abc123.yaml.deferred"]);
+    const m = parseSessionMarkers(readFileSync(r.path, "utf-8"));
+    assert.equal(m.deferredUntil, new Date(T0 + 30 * 60_000).toISOString());
+    assert.equal(m.deferredReason, "waiting on finance");
+    // The claim marker is replaced, not stacked.
+    assert.equal(m.claimedBy, null);
+    assert.equal(markSessionDeferral(dir, "cohort", { id: "ghost" }, { until: T0, now: T0 }).ok, false);
+  } finally { rm(dir); }
+});
+
+test("sweepSessionInbox: a session claim older than 20 min is reopened to .yaml with markers stripped; fresh stays", () => {
+  const dir = root();
+  try {
+    plant(dir);
+    markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 });
+    // A daemon-dispatched (no marker) .dispatched file is NOT the sweep's to reopen.
+    plant(dir, "2026-09-08T09-58-00-000Z-cohort-daemon1.yaml.dispatched", ITEM.replace(/cohort-abc123/g, "cohort-daemon1"));
+
+    const fresh = sweepSessionInbox(dir, { now: T0 + SESSION_CLAIM_STALE_MS - 1 });
+    assert.deepEqual(fresh.reopened, []);
+    assert.equal(fresh.scanned >= 2, true);
+
+    const r = sweepSessionInbox(dir, { now: T0 + SESSION_CLAIM_STALE_MS + 1 });
+    assert.deepEqual(r.reopened.map((x) => [x.id, x.service, x.reason]), [["cohort-abc123", "cohort", "claim-stale"]]);
+    assert.deepEqual(ls(dir), [
+      "2026-09-08T09-58-00-000Z-cohort-daemon1.yaml.dispatched",
+      "2026-09-08T09-59-00-000Z-cohort-abc123.yaml",
+    ]);
+    assert.equal(readFileSync(join(dir, "state/inbox/cohort/2026-09-08T09-59-00-000Z-cohort-abc123.yaml"), "utf-8"), ITEM);
+  } finally { rm(dir); }
+});
+
+test("sweepSessionInbox: a deferral whose time has passed is reopened; a future one stays; unmarked .deferred untouched", () => {
+  const dir = root();
+  try {
+    plant(dir);
+    markSessionDeferral(dir, "cohort", { id: "cohort-abc123" }, { until: T0 + 10_000, reason: "later", now: T0 });
+    // Legacy daemon deferral (thread-lock park) carries no marker — promoteDeferred owns it.
+    plant(dir, "2026-09-08T09-58-00-000Z-cohort-legacy.yaml.deferred", ITEM.replace(/cohort-abc123/g, "cohort-legacy"));
+    assert.deepEqual(sweepSessionInbox(dir, { now: T0 + 9_999 }).reopened, []);
+    const r = sweepSessionInbox(dir, { now: T0 + 10_000 });
+    assert.deepEqual(r.reopened.map((x) => [x.id, x.reason]), [["cohort-abc123", "deferral-due"]]);
+    assert.deepEqual(ls(dir), [
+      "2026-09-08T09-58-00-000Z-cohort-legacy.yaml.deferred",
+      "2026-09-08T09-59-00-000Z-cohort-abc123.yaml",
+    ]);
+  } finally { rm(dir); }
+});
+
+test("sweepSessionInbox: a claim with an unparsable claimed_at falls back to the file mtime; missing inbox dir → nothing", () => {
+  const dir = root();
+  try {
+    const p = plant(dir, "2026-09-08T09-59-00-000Z-cohort-abc123.yaml.dispatched", ITEM + 'claimed_by: "session"\nclaimed_at: "garbage"\n');
+    const old = new Date(T0 - SESSION_CLAIM_STALE_MS - 1000);
+    utimesSync(p, old, old);
+    const r = sweepSessionInbox(dir, { now: T0 });
+    assert.deepEqual(r.reopened.map((x) => x.id), ["cohort-abc123"]);
+    assert.deepEqual(sweepSessionInbox(join(dir, "nope"), { now: T0 }), { reopened: [], scanned: 0 });
+  } finally { rm(dir); }
+});
+
+// ── review fixes ─────────────────────────────────────────────────────────────
+
+test("findInboxFile: an exact id wins over substring look-alikes; a truncated id that matches several is refused", () => {
+  const dir = root();
+  try {
+    for (const id of ["cohort-m1", "cohort-m10", "cohort-m11"]) {
+      plant(dir, `2026-09-08T09-59-00-000Z-${id}.yaml`, ITEM.replace(/cohort-abc123/g, id));
+    }
+    assert.ok(findInboxFile(dir, "cohort-m1").file.endsWith("-cohort-m1.yaml"));
+    assert.ok(findInboxFile(dir, "cohort-m10").file.endsWith("-cohort-m10.yaml"));
+    // "m1" is a substring of all three and the exact id of none → ambiguous, not a guess.
+    assert.equal(findInboxFile(dir, "m1"), null);
+    // A unique substring (a raw_ref fragment) still resolves.
+    assert.ok(findInboxFile(dir, "m11").file.endsWith("-cohort-m11.yaml"));
+  } finally { rm(dir); }
+});
+
+test("markSessionClaim: renames ONLY the claimed item — look-alike ids stay live", () => {
+  const dir = root();
+  try {
+    for (const id of ["cohort-m1", "cohort-m10", "cohort-m11"]) {
+      plant(dir, `2026-09-08T09-59-00-000Z-${id}.yaml`, ITEM.replace(/cohort-abc123/g, id));
+    }
+    const r = markSessionClaim(dir, "cohort", { id: "cohort-m1" }, { now: T0 });
+    assert.equal(r.ok, true);
+    assert.deepEqual(ls(dir), [
+      "2026-09-08T09-59-00-000Z-cohort-m1.yaml.dispatched",
+      "2026-09-08T09-59-00-000Z-cohort-m10.yaml",
+      "2026-09-08T09-59-00-000Z-cohort-m11.yaml",
+    ]);
+  } finally { rm(dir); }
+});
+
+test("sweepSessionInbox: reopen never recreates the path — the reopened file is the SAME inode, and a vanished claim is not resurrected", () => {
+  const dir = root();
+  try {
+    plant(dir);
+    const claim = markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 });
+    const ino = statSync(claim.path).ino;
+    const r = sweepSessionInbox(dir, { now: T0 + SESSION_CLAIM_STALE_MS + 1 });
+    assert.equal(r.reopened.length, 1);
+    const live = join(dir, "state/inbox/cohort/2026-09-08T09-59-00-000Z-cohort-abc123.yaml");
+    assert.equal(statSync(live).ino, ino, "markers are stripped in place, not via tmp+rename over the claim path");
+    assert.equal(readFileSync(live, "utf-8"), ITEM);
+    // A claim that was finished (renamed away) between the readdir and the reopen is left alone.
+    const p2 = plant(dir, "2026-09-08T09-58-00-000Z-cohort-gone.yaml.dispatched", ITEM.replace(/cohort-abc123/g, "cohort-gone") + sessionMarkerLines({ claimedBy: "session", now: T0 }));
+    rmSync(p2);
+    const r2 = sweepSessionInbox(dir, { now: T0 + SESSION_CLAIM_STALE_MS + 1 });
+    assert.equal(r2.reopened.length, 0);
+    assert.equal(existsSync(join(dir, "state/inbox/cohort/2026-09-08T09-58-00-000Z-cohort-gone.yaml")), false);
+  } finally { rm(dir); }
+});
+
+test("sweepSessionInbox: a claim that was REPLIED is not reopened at 20 min; it is retired to .processed once past the retire window", () => {
+  const dir = root();
+  try {
+    plant(dir);
+    markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 });
+    const rep = markSessionReplied(dir, "cohort", { id: "cohort-abc123" }, { now: T0 + 60_000 });
+    assert.equal(rep.ok, true);
+    const m = parseSessionMarkers(readFileSync(rep.path, "utf-8"));
+    assert.equal(m.claimedBy, "session", "the claim marker survives the reply stamp");
+    assert.equal(m.repliedAt, new Date(T0 + 60_000).toISOString());
+
+    const at20 = sweepSessionInbox(dir, { now: T0 + SESSION_CLAIM_STALE_MS + 1 });
+    assert.deepEqual(at20.reopened, [], "a replied item must never be re-answered");
+    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-cohort-abc123.yaml.dispatched"]);
+
+    const late = sweepSessionInbox(dir, { now: T0 + 60_000 + REPLIED_RETIRE_MS + 1 });
+    assert.deepEqual(late.reopened.map((x) => [x.id, x.reason]), [["cohort-abc123", "replied-retired"]]);
+    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-cohort-abc123.yaml.processed"]);
+    // Replying to an item that is not in flight (new / processed) is refused, never a throw.
+    assert.equal(markSessionReplied(dir, "cohort", { id: "cohort-abc123" }, { now: T0 }).ok, false);
+  } finally { rm(dir); }
+});
+
+test("sweepSessionInbox: a daemon-owned .dispatched orphan is reopened for a LIVE session once past the daemon reclaim window; never while the session is not live", () => {
+  const dir = root();
+  try {
+    const p = plant(dir, "2026-09-08T09-58-00-000Z-cohort-daemon1.yaml.dispatched", ITEM.replace(/cohort-abc123/g, "cohort-daemon1"));
+    const old = new Date(T0 - DAEMON_ORPHAN_RECLAIM_MS - 1000);
+    utimesSync(p, old, old);
+    // Not live → the scanner's own reclaim owns it; the sweep does nothing.
+    assert.deepEqual(sweepSessionInbox(dir, { now: T0 }).reopened, []);
+    assert.deepEqual(sweepSessionInbox(dir, { now: T0, sessionLive: false }).reopened, []);
+    // Live but the file is still inside the window → in flight, untouched.
+    const fresh = plant(dir, "2026-09-08T09-58-30-000Z-cohort-daemon2.yaml.dispatched", ITEM.replace(/cohort-abc123/g, "cohort-daemon2"));
+    utimesSync(fresh, new Date(T0 - 1000), new Date(T0 - 1000));
+    const r = sweepSessionInbox(dir, { now: T0, sessionLive: true });
+    assert.deepEqual(r.reopened.map((x) => [x.id, x.reason]), [["cohort-daemon1", "daemon-orphan"]]);
+    assert.deepEqual(ls(dir), [
+      "2026-09-08T09-58-00-000Z-cohort-daemon1.yaml",
+      "2026-09-08T09-58-30-000Z-cohort-daemon2.yaml.dispatched",
+    ]);
+  } finally { rm(dir); }
+});
+
+test("sweepSessionInboxForDaemon: reads liveness through the front-door reader; a throwing reader means not live (scanner keeps its reclaim)", () => {
+  const dir = root();
+  try {
+    const p = plant(dir, "2026-09-08T09-58-00-000Z-cohort-daemon1.yaml.dispatched", ITEM.replace(/cohort-abc123/g, "cohort-daemon1"));
+    const old = new Date(T0 - DAEMON_ORPHAN_RECLAIM_MS - 1000);
+    utimesSync(p, old, old);
+    const dead = sweepSessionInboxForDaemon(dir, { now: T0, readState: () => { throw new Error("boom"); } });
+    assert.equal(dead.sessionLive, false);
+    assert.deepEqual(dead.reopened, []);
+    const live = sweepSessionInboxForDaemon(dir, { now: T0, readState: () => ({ frontDoor: "session", sessionLive: true }) });
+    assert.equal(live.sessionLive, true);
+    assert.deepEqual(live.reopened.map((x) => x.reason), ["daemon-orphan"]);
+  } finally { rm(dir); }
+});

package/lib/session/launch-args.mjs

@@ -0,0 +1,161 @@
+/**
+ * lib/session/launch-args.mjs — the exact argv the supervisor runs. Pure.
+ *
+ * Three things are decided here and nowhere else:
+ *
+ *   1. The `claude` argv for the main session — `--name <first>-main`, the
+ *      stable id (`--session-id` on the first launch of an id, `--resume`
+ *      after), the permission posture the caller resolved via
+ *      `lib/session-permissions.mjs`, and the bootstrap prompt.
+ *   2. Which multiplexer runs it. macOS ships `/usr/bin/screen`; `tmux` is
+ *      preferred when installed (`mux: auto`). Both run in the FOREGROUND of
+ *      the supervisor so the supervisor lives exactly as long as the session:
+ *      `screen -D -m` blocks until the session ends; tmux `new-session -d`
+ *      returns at once, so the supervisor blocks on a `has-session` probe
+ *      (`=name` is tmux's exact-match form) until the session is gone.
+ *   3. How the session's exit code reaches the supervisor. Neither mux
+ *      propagates the child's status, so `claude` is wrapped in
+ *      {@link SESSION_EXIT_SCRIPT}: a `/bin/sh -c` whose script takes the exit
+ *      file and the command as POSITIONAL parameters — nothing user-controlled
+ *      is ever interpolated into shell text.
+ *
+ * No I/O. `detectMux` is the one probe and takes `existsSync` injected.
+ *
+ * @module lib/session/launch-args
+ */
+
+"use strict";
+
+import { mainSessionName } from "./identity.mjs";
+
+/** The prompt every (re)launch of the main session starts with. */
+export const BOOTSTRAP_PROMPT =
+  "You are resuming as the main session for this seat. Load the maestro main-session skill " +
+  "(~/.claude/skills/maestro-main-session/SKILL.md or /maestro:main-session) and follow it.";
+
+/**
+ * `sh -c` body that runs `"$@"` and records its exit code. Positional only:
+ * `$0` is a label, `$1` the exit file, the rest the command. The exit file's
+ * parent must already exist (the supervisor creates `state/session/`).
+ */
+export const SESSION_EXIT_SCRIPT =
+  'exit_file="$1"; shift; "$@"; rc=$?; printf \'%s\\n\' "$rc" > "$exit_file" 2>/dev/null; exit "$rc"';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Where the multiplexers live on a Mac (nvm-free, launchd-safe, in order). */
+export const MUX_CANDIDATES = Object.freeze({
+  tmux: Object.freeze(["/opt/homebrew/bin/tmux", "/usr/local/bin/tmux", "/usr/bin/tmux"]),
+  screen: Object.freeze(["/usr/bin/screen", "/opt/homebrew/bin/screen", "/usr/local/bin/screen"]),
+});
+
+/**
+ * Pure: the `claude` argv (without the binary).
+ * @param {{first:string, sessionId:string, mode:"session-id"|"resume", permissionArgs?:string[], extraArgs?:string[], prompt?:string}} a
+ * @returns {string[]}
+ */
+export function buildClaudeArgs(a) {
+  if (!UUID_RE.test(String(a.sessionId || ""))) throw new Error(`buildClaudeArgs: session id must be a uuid, got ${JSON.stringify(a.sessionId)}`);
+  if (a.mode !== "session-id" && a.mode !== "resume") throw new Error(`buildClaudeArgs: unknown mode ${JSON.stringify(a.mode)}`);
+  return [
+    "--name", mainSessionName(a.first),
+    a.mode === "resume" ? "--resume" : "--session-id", a.sessionId,
+    ...(a.permissionArgs || []),
+    ...(a.extraArgs || []),
+    a.prompt || BOOTSTRAP_PROMPT,
+  ];
+}
+
+/**
+ * Which multiplexers are installed, by fixed path. A throwing probe reads as
+ * absent — the supervisor then reports "no multiplexer" rather than crashing.
+ * @param {{existsSync:(p:string)=>boolean}} deps
+ * @returns {{tmux:string|null, screen:string|null}}
+ */
+export function detectMux(deps) {
+  const probe = (p) => { try { return !!deps.existsSync(p); } catch { return false; } };
+  const first = (list) => list.find(probe) || null;
+  return { tmux: first(MUX_CANDIDATES.tmux), screen: first(MUX_CANDIDATES.screen) };
+}
+
+/**
+ * Pure: pick the multiplexer. `auto` prefers tmux; an explicit preference that
+ * is not installed falls back to whatever is, because a seat with a wrong
+ * `mux:` line should still come up.
+ * @param {"auto"|"screen"|"tmux"} pref
+ * @param {{tmux:string|null, screen:string|null}} found
+ * @returns {{kind:"tmux"|"screen", bin:string}|null}
+ */
+export function chooseMux(pref, found) {
+  const order = pref === "screen" ? ["screen", "tmux"] : ["tmux", "screen"];
+  for (const kind of order) if (found[kind]) return { kind, bin: found[kind] };
+  return null;
+}
+
+/**
+ * Pure: the commands the supervisor runs for one session lifetime.
+ *
+ *   start      the command that launches the session (blocking for screen).
+ *   waitProbe  tmux only — exits 0 while the session exists; the supervisor
+ *              polls it to block. null for screen.
+ *   exists     the probe used to detect an orphaned session before launch.
+ *   wipe       screen only — `screen -wipe` removes DEAD sockets (a SIGKILLed
+ *              screen leaves `name (Dead ???)` behind, which `-ls` still lists).
+ *              null for tmux, whose server owns its sockets.
+ *   stop       ends the session on request (SIGTERM to the supervisor):
+ *              `screen -S name -X quit` / `tmux kill-session -t =name`.
+ *
+ * @param {{mux:{kind:string, bin:string}, muxName:string, cwd:string, claudeBin:string, claudeArgs:string[], exitFile:string}} a
+ */
+export function buildMuxCommands(a) {
+  const wrapped = ["/bin/sh", "-c", SESSION_EXIT_SCRIPT, "maestro-session", a.exitFile, a.claudeBin, ...a.claudeArgs];
+  if (a.mux.kind === "screen") {
+    return {
+      blocking: true,
+      start: { file: a.mux.bin, args: ["-D", "-m", "-S", a.muxName, ...wrapped] },
+      waitProbe: null,
+      exists: { file: a.mux.bin, args: ["-ls"] },
+      wipe: { file: a.mux.bin, args: ["-wipe"] },
+      stop: { file: a.mux.bin, args: ["-S", a.muxName, "-X", "quit"] },
+    };
+  }
+  if (a.mux.kind === "tmux") {
+    const probe = { file: a.mux.bin, args: ["has-session", "-t", `=${a.muxName}`] };
+    return {
+      blocking: false,
+      start: { file: a.mux.bin, args: ["new-session", "-d", "-s", a.muxName, "-c", a.cwd, ...wrapped] },
+      waitProbe: probe,
+      exists: probe,
+      wipe: null,
+      stop: { file: a.mux.bin, args: ["kill-session", "-t", `=${a.muxName}`] },
+    };
+  }
+  throw new Error(`buildMuxCommands: unknown mux kind ${JSON.stringify(a.mux && a.mux.kind)}`);
+}
+
+/**
+ * Pure: does `screen -ls` output list a LIVE session named exactly `name`?
+ * Lines look like `\t48213.maestro-olivia\t(Detached)`. A `(Dead ???)` line
+ * is a socket whose screen process was killed (SIGKILL from a watchdog, an
+ * OOM, launchd's process-group kill): nothing is running behind it, so it
+ * must not be adopted — adopting it would block until someone ran
+ * `screen -wipe` by hand.
+ * @param {string|null|undefined} out @param {string} name
+ */
+export function parseScreenList(out, name) {
+  if (typeof out !== "string") return false;
+  const re = new RegExp(`^\\s*\\d+\\.${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\s|$)`);
+  return out.split(/\r?\n/).some((line) => re.test(line) && !/\(Dead\b/.test(line));
+}
+
+/** Pure: the recorded exit code, or null when unreadable. */
+export function parseExitFile(text) {
+  if (typeof text !== "string") return null;
+  const m = text.trim().match(/^\d{1,3}$/);
+  return m ? Number(m[0]) : null;
+}
+
+export default {
+  BOOTSTRAP_PROMPT, SESSION_EXIT_SCRIPT, MUX_CANDIDATES,
+  buildClaudeArgs, detectMux, chooseMux, buildMuxCommands, parseScreenList, parseExitFile,
+};

package/lib/session/launch-args.test.mjs

@@ -0,0 +1,157 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  BOOTSTRAP_PROMPT,
+  SESSION_EXIT_SCRIPT,
+  buildClaudeArgs,
+  detectMux,
+  chooseMux,
+  buildMuxCommands,
+  parseScreenList,
+  parseExitFile,
+} from "./launch-args.mjs";
+
+const UUID = "11111111-2222-4333-8444-555555555555";
+
+test("BOOTSTRAP_PROMPT is the exact resume prompt from the design", () => {
+  assert.equal(
+    BOOTSTRAP_PROMPT,
+    "You are resuming as the main session for this seat. Load the maestro main-session skill (~/.claude/skills/maestro-main-session/SKILL.md or /maestro:main-session) and follow it.",
+  );
+});
+
+test("buildClaudeArgs: fresh id → --session-id; relaunch → --resume; permissions spliced; prompt last", () => {
+  const fresh = buildClaudeArgs({ first: "olivia", sessionId: UUID, mode: "session-id", permissionArgs: ["--dangerously-skip-permissions"] });
+  assert.deepEqual(fresh, ["--name", "olivia-main", "--session-id", UUID, "--dangerously-skip-permissions", BOOTSTRAP_PROMPT]);
+  const resume = buildClaudeArgs({ first: "olivia", sessionId: UUID, mode: "resume", permissionArgs: ["--allowedTools", "Read"], extraArgs: ["--model", "opus"] });
+  assert.deepEqual(resume, ["--name", "olivia-main", "--resume", UUID, "--allowedTools", "Read", "--model", "opus", BOOTSTRAP_PROMPT]);
+});
+
+test("buildClaudeArgs: a non-uuid session id or unknown mode is a defect", () => {
+  assert.throws(() => buildClaudeArgs({ first: "o", sessionId: "nope", mode: "resume" }), /session id/);
+  assert.throws(() => buildClaudeArgs({ first: "o", sessionId: UUID, mode: "attach" }), /mode/);
+});
+
+test("detectMux: probes the fixed candidate paths through injected existsSync", () => {
+  const found = detectMux({ existsSync: (p) => p === "/opt/homebrew/bin/tmux" || p === "/usr/bin/screen" });
+  assert.deepEqual(found, { tmux: "/opt/homebrew/bin/tmux", screen: "/usr/bin/screen" });
+  assert.deepEqual(detectMux({ existsSync: () => false }), { tmux: null, screen: null });
+  // A throwing probe is treated as absent.
+  assert.deepEqual(detectMux({ existsSync: () => { throw new Error("boom"); } }), { tmux: null, screen: null });
+});
+
+test("chooseMux: auto prefers tmux, falls back to screen, null when neither; explicit choice must exist", () => {
+  const both = { tmux: "/opt/homebrew/bin/tmux", screen: "/usr/bin/screen" };
+  assert.deepEqual(chooseMux("auto", both), { kind: "tmux", bin: "/opt/homebrew/bin/tmux" });
+  assert.deepEqual(chooseMux("auto", { tmux: null, screen: "/usr/bin/screen" }), { kind: "screen", bin: "/usr/bin/screen" });
+  assert.equal(chooseMux("auto", { tmux: null, screen: null }), null);
+  assert.deepEqual(chooseMux("screen", both), { kind: "screen", bin: "/usr/bin/screen" });
+  assert.deepEqual(chooseMux("tmux", both), { kind: "tmux", bin: "/opt/homebrew/bin/tmux" });
+  // An explicit mux that is not installed falls back rather than failing the seat.
+  assert.deepEqual(chooseMux("tmux", { tmux: null, screen: "/usr/bin/screen" }), { kind: "screen", bin: "/usr/bin/screen" });
+});
+
+test("SESSION_EXIT_SCRIPT records the wrapped command's exit code without interpolating any argument", () => {
+  assert.match(SESSION_EXIT_SCRIPT, /"\$@"/);
+  assert.match(SESSION_EXIT_SCRIPT, /exit "\$rc"/);
+  assert.doesNotMatch(SESSION_EXIT_SCRIPT, /\$\{?[A-Z_]+\}?/); // no env expansion — everything is positional
+});
+
+test("buildMuxCommands (screen): one FOREGROUND command, -D -m -S <name>, claude wrapped by the exit-recording sh", () => {
+  const c = buildMuxCommands({
+    mux: { kind: "screen", bin: "/usr/bin/screen" },
+    muxName: "maestro-olivia",
+    cwd: "/agent",
+    claudeBin: "/Users/o/.local/bin/claude",
+    claudeArgs: ["--name", "olivia-main", "--resume", UUID, "prompt with spaces"],
+    exitFile: "/agent/state/session/last-exit",
+  });
+  assert.equal(c.blocking, true);
+  assert.equal(c.waitProbe, null);
+  assert.equal(c.start.file, "/usr/bin/screen");
+  assert.deepEqual(c.start.args, [
+    "-D", "-m", "-S", "maestro-olivia",
+    "/bin/sh", "-c", SESSION_EXIT_SCRIPT, "maestro-session", "/agent/state/session/last-exit",
+    "/Users/o/.local/bin/claude", "--name", "olivia-main", "--resume", UUID, "prompt with spaces",
+  ]);
+  assert.deepEqual(c.exists, { file: "/usr/bin/screen", args: ["-ls"] });
+});
+
+test("buildMuxCommands (tmux): detached new-session, then a has-session probe the supervisor blocks on", () => {
+  const c = buildMuxCommands({
+    mux: { kind: "tmux", bin: "/opt/homebrew/bin/tmux" },
+    muxName: "maestro-olivia",
+    cwd: "/agent",
+    claudeBin: "claude",
+    claudeArgs: ["--name", "olivia-main"],
+    exitFile: "/agent/state/session/last-exit",
+  });
+  assert.equal(c.blocking, false);
+  assert.equal(c.start.file, "/opt/homebrew/bin/tmux");
+  assert.deepEqual(c.start.args, [
+    "new-session", "-d", "-s", "maestro-olivia", "-c", "/agent",
+    "/bin/sh", "-c", SESSION_EXIT_SCRIPT, "maestro-session", "/agent/state/session/last-exit",
+    "claude", "--name", "olivia-main",
+  ]);
+  assert.deepEqual(c.waitProbe, { file: "/opt/homebrew/bin/tmux", args: ["has-session", "-t", "=maestro-olivia"] });
+  assert.deepEqual(c.exists, c.waitProbe);
+});
+
+test("buildMuxCommands: unknown mux kind is a defect", () => {
+  assert.throws(() => buildMuxCommands({ mux: { kind: "zellij", bin: "z" }, muxName: "m", cwd: "/", claudeBin: "c", claudeArgs: [], exitFile: "/e" }), /mux/);
+});
+
+test("parseScreenList: finds an exact session name in `screen -ls` output, not a prefix", () => {
+  const out = [
+    "There are screens on:",
+    "\t48213.maestro-olivia\t(Detached)",
+    "\t48214.maestro-olivia-old\t(Attached)",
+    "2 Sockets in /var/folders/xx/.screen.",
+    "",
+  ].join("\n");
+  assert.equal(parseScreenList(out, "maestro-olivia"), true);
+  assert.equal(parseScreenList(out, "maestro-oliv"), false);
+  assert.equal(parseScreenList("No Sockets found in /var/folders/xx/.screen.\n", "maestro-olivia"), false);
+  assert.equal(parseScreenList(null, "maestro-olivia"), false);
+});
+
+test("parseScreenList: a `(Dead ???)` socket is NOT a live session (a SIGKILLed screen leaves one behind)", () => {
+  // Verbatim shape of `screen -ls` after the screen process was kill -9'd.
+  const dead = [
+    "There is a screen on:",
+    "\t82332.maestro-olivia\t(Dead ???)",
+    "Remove dead screens with 'screen -wipe'.",
+    "1 Socket in /var/folders/xx/.screen.",
+    "",
+  ].join("\n");
+  assert.equal(parseScreenList(dead, "maestro-olivia"), false);
+  // A dead socket next to a live one with the same name: the live one counts.
+  const mixed = [
+    "There are screens on:",
+    "\t82332.maestro-olivia\t(Dead ???)",
+    "\t90001.maestro-olivia\t(Detached)",
+    "2 Sockets in /var/folders/xx/.screen.",
+    "",
+  ].join("\n");
+  assert.equal(parseScreenList(mixed, "maestro-olivia"), true);
+});
+
+test("buildMuxCommands: screen has a `wipe` (dead-socket cleanup) and both muxes a `stop`; tmux has no wipe", () => {
+  const base = { muxName: "maestro-olivia", cwd: "/agent", claudeBin: "claude", claudeArgs: [], exitFile: "/e" };
+  const s = buildMuxCommands({ ...base, mux: { kind: "screen", bin: "/usr/bin/screen" } });
+  assert.deepEqual(s.wipe, { file: "/usr/bin/screen", args: ["-wipe"] });
+  assert.deepEqual(s.stop, { file: "/usr/bin/screen", args: ["-S", "maestro-olivia", "-X", "quit"] });
+  const t = buildMuxCommands({ ...base, mux: { kind: "tmux", bin: "/opt/homebrew/bin/tmux" } });
+  assert.equal(t.wipe, null);
+  assert.deepEqual(t.stop, { file: "/opt/homebrew/bin/tmux", args: ["kill-session", "-t", "=maestro-olivia"] });
+});
+
+test("parseExitFile: integer or null", () => {
+  assert.equal(parseExitFile("0\n"), 0);
+  assert.equal(parseExitFile(" 1 "), 1);
+  assert.equal(parseExitFile("137"), 137);
+  assert.equal(parseExitFile(""), null);
+  assert.equal(parseExitFile("abc"), null);
+  assert.equal(parseExitFile(null), null);
+});