@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/cli/session.mjs

@@ -0,0 +1,760 @@
+/**
+ * lib/cli/session.mjs — backs `maestro session <sub>` (front-door session,
+ * design §3.1 / §3.6 / §6 WP-M3).
+ *
+ * WHY A LIBRARY AND NOT A `case` BLOCK IN bin/maestro.mjs. Same reason as
+ * lib/subagents/cli.mjs: the dispatcher cannot be imported without executing,
+ * so a verb surface that reads state and drives launchctl/tmux/screen would be
+ * untestable there. `run()` returns `{ok, code, lines, data?}` and only PRINTS
+ * when asked; every process boundary (execs, TTY, uid, HOME, clock, pid
+ * liveness, the claude binary) is injected via `deps`, so the tests never
+ * touch launchd or a multiplexer. bin/maestro.mjs keeps a one-line `case`.
+ *
+ * Commands:
+ *
+ *   status [--brief|--json]   lock holder · heartbeat age · main session id ·
+ *                             mux session · plist installed/loaded · peers ·
+ *                             open handoffs · restart/upgrade flags
+ *   attach                    print the exact `tmux attach` / `screen -r` line;
+ *                             exec it when stdin+stdout are a TTY
+ *   start                     bootstrap the plist if not loaded, then kickstart
+ *   stop                      bootout the label from the gui domain
+ *   restart [--force]         touch state/session/restart-requested, then
+ *                             kickstart (the session exits itself at an idle
+ *                             moment and the supervisor relaunches on the new
+ *                             code); --force = kickstart -k
+ *   spawn --name <slug> [--cwd <dir>] "<prompt>"
+ *                             detached mux session running the CLI as
+ *                             <first>-<slug> with lib/session-permissions args;
+ *                             registers state/session/peers.json; prints the name
+ *   peers [--json]            list peers, pruning dead ones from the registry
+ *   handoffs [--json]         open cadence handoffs (state/session/handoffs/*.json)
+ *   ack <tickId> [--result p] delegates to lib/cli/session-ack.mjs (WP-M2) when
+ *                             present; a clear failure when it is not
+ *
+ * State it reads (all written by the supervisor / feed / daemon, never here
+ * except peers.json and the restart marker):
+ *   state/locks/process/session.pid    lib/singleton.js acquireLock("session")
+ *   state/session/heartbeat.json       {pid, ppid, sessionId, name, ts, feedVersion}
+ *   state/session/main-session.json    {sessionId, createdAt, resumes}
+ *   state/session/peers.json           {peers:[{name, muxName, startedAt, purpose, cwd}]}
+ *                                      (read-modify-written ONLY through updatePeers(),
+ *                                      under the O_EXCL sidecar peers.json.lock)
+ *   config/session.yaml                mux + allowedTools via lib/session/config.mjs
+ *                                      (WP-M1) — one source of truth with the supervisor
+ *   state/session/handoffs/<tick>.json {tickId, cadence, mode, promptPath, enqueuedAt, deadlineAt}
+ *   state/session/restart-requested    marker
+ *   state/session/upgrade-notice.json  {from, to, at}  (autoupdate.sh) — reported only
+ *                                      while `to` differs from the running SDK version
+ *
+ * Everything is fail-open: unreadable state reads as absent. `now` is a
+ * parameter wherever it changes the answer. Node builtins only. ESM.
+ *
+ * @module lib/cli/session
+ */
+
+"use strict";
+
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import { writeJsonAtomic } from "../fs-atomic.mjs";
+import { resolveAgentRoot } from "../agent-root.mjs";
+import { resolveClaudeBin } from "../claude-bin.mjs";
+import { sessionPermissionArgs } from "../session-permissions.mjs";
+import { withParallelism } from "../prompts/parallelism.mjs";
+
+/** The SDK's own package.json version — what "installed" means for an upgrade notice. */
+function ownVersion() {
+  try { return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version || null; } catch { return null; }
+}
+
+/** Heartbeat older than this is "not live" (design §3.2: 90 s). */
+export const STALE_MS = 90_000;
+
+/** A peer slug: lower-case, digits, hyphens; short. */
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,40}$/;
+
+// ---------------------------------------------------------------------------
+// Names and paths (pure)
+// ---------------------------------------------------------------------------
+
+/**
+ * The agent's first name, lower-cased. The chain is EXACTLY generate-plists.sh's,
+ * so the CLI and the plist can never disagree on the label:
+ *   1. config/agent.json `firstName` (SOT)
+ *   2. config/agent.ts inline `firstName: 'X'` (legacy seats; a type-only
+ *      `firstName: string;` must not match)
+ *   3. directory basename minus a `-ai` suffix
+ * @param {string} agentRoot
+ * @returns {string}
+ */
+export function resolveFirstName(agentRoot) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(agentRoot, "config", "agent.json"), "utf8"));
+    const f = typeof cfg.firstName === "string" ? cfg.firstName.trim().toLowerCase() : "";
+    if (f && f !== "unconfigured") return f;
+  } catch {
+    // no/invalid agent.json — fall through (fail-open)
+  }
+  try {
+    const ts = readFileSync(join(agentRoot, "config", "agent.ts"), "utf8");
+    const m = ts.match(/firstName:\s*['"]([^'"]+)['"]/);
+    const f = m ? m[1].trim().toLowerCase() : "";
+    if (f && f !== "unconfigured") return f;
+  } catch {
+    // no agent.ts — fall through
+  }
+  return basename(agentRoot).toLowerCase().replace(/-ai$/, "");
+}
+
+/** @param {string} first @returns {string} launchd label */
+export function sessionLabel(first) { return `ai.maestro.${first}-session`; }
+
+/** @param {string} first @returns {string} the main session's mux name */
+export function muxSessionName(first) { return `maestro-${first}`; }
+
+/** @param {string} first @param {string} slug @returns {string} a peer's mux name */
+export function peerMuxName(first, slug) { return `maestro-${first}-${slug}`; }
+
+/**
+ * Every state path the CLI touches, in one place.
+ * @param {string} agentRoot
+ */
+export function sessionPaths(agentRoot) {
+  const dir = join(agentRoot, "state", "session");
+  return {
+    dir,
+    heartbeat: join(dir, "heartbeat.json"),
+    mainSession: join(dir, "main-session.json"),
+    peers: join(dir, "peers.json"),
+    handoffsDir: join(dir, "handoffs"),
+    handoffsDone: join(dir, "handoffs", "done"),
+    restartRequested: join(dir, "restart-requested"),
+    upgradeNotice: join(dir, "upgrade-notice.json"),
+    lock: join(agentRoot, "state", "locks", "process", "session.pid"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pure decisions
+// ---------------------------------------------------------------------------
+
+/** ms or ISO → epoch ms, else null. */
+function toMs(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v) { const t = Date.parse(v); return Number.isFinite(t) ? t : null; }
+  return null;
+}
+
+/**
+ * Age of a heartbeat record at `now`, or null when there is none.
+ * @param {{ts?: number|string}|null} hb
+ * @param {number} now epoch ms
+ * @returns {number|null}
+ */
+export function heartbeatAgeMs(hb, now) {
+  if (!hb || typeof hb !== "object") return null;
+  const ts = toMs(hb.ts);
+  if (ts === null) return null;
+  return Math.max(0, now - ts);
+}
+
+/**
+ * Is the front-door session live at `now`? Liveness is MEASURED (a fresh
+ * heartbeat), never assumed from a lock or a plist.
+ * @param {{ts?: number|string}|null} hb
+ * @param {number} now
+ * @param {{staleMs?: number}} [o]
+ */
+export function isLive(hb, now, o = {}) {
+  const age = heartbeatAgeMs(hb, now);
+  return age !== null && age < (o.staleMs ?? STALE_MS);
+}
+
+/**
+ * The exact attach command for the main session.
+ * @param {string} first
+ * @param {"tmux"|"screen"} kind
+ * @returns {string[]} argv
+ */
+export function attachCommand(first, kind) {
+  const name = muxSessionName(first);
+  return kind === "tmux" ? ["tmux", "attach", "-t", name] : ["screen", "-r", name];
+}
+
+/**
+ * Permission args for an INTERACTIVE peer session. Same rule as the front-door
+ * supervisor's main-session posture (lib/session-permissions.mjs, WP-M1): the
+ * `MAESTRO_SCOPED_PERMISSIONS=1` switch is honoured, but a peer runs inside a
+ * multiplexer with nobody attached, so the conservative read-only `--print`
+ * allowlist would only wedge it on its first prompt. Scoped mode therefore
+ * uses the operator's explicit allowlist (config/session.yaml `allowedTools`)
+ * or bypass; unscoped is byte-for-byte the pre-H1 posture.
+ *
+ * `sessionPermissionArgs` is still the source of the unscoped default so the
+ * two lanes cannot drift on it.
+ * @param {{env?:object, allowedTools?:string[]}} [o]
+ * @returns {string[]}
+ */
+export function peerPermissionArgs({ env = process.env, allowedTools } = {}) {
+  if (!env || env.MAESTRO_SCOPED_PERMISSIONS !== "1") {
+    const prev = process.env.MAESTRO_SCOPED_PERMISSIONS;
+    // Ask the shared module for the unscoped default without mutating the
+    // caller's env for longer than the call.
+    if (prev !== undefined) delete process.env.MAESTRO_SCOPED_PERMISSIONS;
+    try { return sessionPermissionArgs({}); } finally { if (prev !== undefined) process.env.MAESTRO_SCOPED_PERMISSIONS = prev; }
+  }
+  const explicit = Array.isArray(allowedTools) ? allowedTools.filter((t) => typeof t === "string" && t.trim()).map((t) => t.trim()) : [];
+  return explicit.length ? ["--allowedTools", explicit.join(",")] : ["--dangerously-skip-permissions"];
+}
+
+/**
+ * CLI args for a spawned peer: `--name <first>-<slug>`, the interactive
+ * permission posture ({@link peerPermissionArgs}), then the prompt. The binary
+ * itself is prepended by the caller.
+ *
+ * THE PROMPT IS LED BY THE PARALLELISM DIRECTIVE (WP-M7 mechanic 5). A peer is
+ * spawned precisely when there is more work than one session can hold, so it is
+ * the one lane where "dispatch the independent tasks together" pays every time
+ * — and the directive carries the file-scope rule that makes that safe on a
+ * shared checkout. `withParallelism` is idempotent, so a caller that already
+ * led its prompt with it (a daemon prompt handed on to `session spawn`) does
+ * not get it twice; the peers registry still records the OPERATOR's prompt as
+ * the peer's purpose, not the directive.
+ * @param {{first:string, slug:string, prompt:string, env?:object, allowedTools?:string[]}} o
+ * @returns {string[]}
+ */
+export function buildSpawnArgs({ first, slug, prompt, env, allowedTools }) {
+  return ["--name", `${first}-${slug}`, ...peerPermissionArgs({ env, allowedTools }), withParallelism(prompt)];
+}
+
+/**
+ * Split a peer registry into live and dead, given a mux-presence probe.
+ * @param {Array<{muxName:string}>} peers
+ * @param {(muxName:string)=>boolean} present
+ */
+export function prunePeers(peers, present) {
+  const live = [], dead = [];
+  for (const p of Array.isArray(peers) ? peers : []) {
+    if (p && typeof p.muxName === "string" && present(p.muxName)) live.push(p); else dead.push(p);
+  }
+  return { live, dead };
+}
+
+// ---------------------------------------------------------------------------
+// Effects (all behind `deps`)
+// ---------------------------------------------------------------------------
+
+/** Real process boundaries. Tests replace every one of these. */
+function defaultDeps() {
+  return {
+    /** execFile-style, no shell. ENOENT → status 127. */
+    exec(cmd, args = [], o = {}) {
+      const r = spawnSync(cmd, args, { encoding: "utf8", cwd: o.cwd, env: o.env, stdio: ["ignore", "pipe", "pipe"] });
+      if (r.error) return { status: 127, stdout: "", stderr: r.error.message };
+      return { status: r.status ?? 1, stdout: r.stdout || "", stderr: r.stderr || "" };
+    },
+    /** Foreground, inheriting the terminal (attach). */
+    execInherit(cmd, args = []) {
+      const r = spawnSync(cmd, args, { stdio: "inherit" });
+      if (r.error) return { status: 127, stdout: "", stderr: r.error.message };
+      return { status: r.status ?? 1, stdout: "", stderr: "" };
+    },
+    now: () => Date.now(),
+    uid: () => (typeof process.getuid === "function" ? process.getuid() : 501),
+    home: homedir(),
+    isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    isAlive(pid) { try { process.kill(pid, 0); return true; } catch { return false; } },
+    claudeBin: null, // resolved lazily via resolveClaudeBin()
+    env: process.env,
+    /** config/session.yaml via lib/session/config.mjs (WP-M1); {} when that module is absent (fail-open). */
+    async loadSessionConfig(agentRoot) {
+      try {
+        const m = await import("../session/config.mjs");
+        return await m.loadSessionConfig(agentRoot);
+      } catch { return {}; }
+    },
+    /** The version the running SDK reports — an upgrade notice for it is already applied. */
+    installedVersion: ownVersion(),
+  };
+}
+
+function readJson(p) {
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } // absent/corrupt → null (fail-open)
+}
+
+/** peers.json accepts a bare array or {peers:[…]}; returns the array. */
+function readPeers(paths) {
+  const j = readJson(paths.peers);
+  if (Array.isArray(j)) return j;
+  if (j && Array.isArray(j.peers)) return j.peers;
+  return [];
+}
+
+function writePeers(paths, peers) {
+  writeJsonAtomic(paths.peers, { peers });
+}
+
+/** Sync sleep without a busy loop. */
+function sleepMs(ms) {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* best effort */ }
+}
+
+/** How long an untouched peers.json.lock is trusted before it is broken. */
+const PEERS_LOCK_STALE_MS = 30_000;
+
+/**
+ * Read-modify-write peers.json under an O_EXCL sidecar lock, so two `spawn`s
+ * (or a `spawn` racing a pruning `status`) from separate processes cannot drop
+ * a registration. The lock is `<peers.json>.lock` holding the pid; a lock
+ * older than 30 s is treated as abandoned and broken. Fail-open on the
+ * registry read (absent/corrupt → []), never on the lock: a caller that cannot
+ * get the lock within `waitMs` is told so and leaves the file alone.
+ *
+ * @param {ReturnType<typeof sessionPaths>} paths
+ * @param {(peers:object[])=>object[]} mutate  pure: current list → new list
+ * @param {{now?:()=>number, waitMs?:number, lockMtimeMs?:(lock:string)=>number|null}} [o]
+ * @returns {{ok:true, peers:object[]}|{ok:false, error:string}}
+ */
+export function updatePeers(paths, mutate, o = {}) {
+  const now = o.now || (() => Date.now());
+  const waitMs = o.waitMs ?? 3000;
+  const lock = `${paths.peers}.lock`;
+  const mtime = o.lockMtimeMs || ((p) => { try { return statSync(p).mtimeMs; } catch { return null; } });
+  try { mkdirSync(dirname(paths.peers), { recursive: true }); } catch { /* reported below by the open */ }
+  const deadline = now() + waitMs;
+  let fd = null;
+  for (;;) {
+    try { fd = openSync(lock, "wx"); break; } catch (e) {
+      if (!e || e.code !== "EEXIST") return { ok: false, error: `peers lock: ${e && e.message ? e.message : e}` };
+      const m = mtime(lock);
+      if (m !== null && now() - m > PEERS_LOCK_STALE_MS) { try { unlinkSync(lock); } catch { /* raced; loop */ } continue; }
+      if (now() >= deadline) return { ok: false, error: `peers lock held by another process (${lock})` };
+      sleepMs(15);
+    }
+  }
+  try {
+    try { writeFileSync(fd, `${process.pid}\n`); } catch { /* the lock's existence is what matters */ }
+    const peers = mutate(readPeers(paths));
+    writePeers(paths, peers);
+    return { ok: true, peers };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  } finally {
+    try { closeSync(fd); } catch { /* already closed */ }
+    try { unlinkSync(lock); } catch { /* already gone */ }
+  }
+}
+
+/** Is a mux session with this name present? tmux first, then screen -ls. */
+function muxPresence(d, name) {
+  const t = d.exec("tmux", ["has-session", "-t", name]);
+  if (t.status === 0) return { present: true, kind: "tmux" };
+  const s = d.exec("screen", ["-ls"]);
+  if (s.status === 0 || /Socket/.test(s.stdout)) {
+    const re = new RegExp(`\\.${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\s|$)`, "m");
+    if (re.test(s.stdout)) return { present: true, kind: "screen" };
+  }
+  return { present: false, kind: null };
+}
+
+/**
+ * Which multiplexer a new peer should use. ONE source of truth with the
+ * supervisor (WP-M1): config/session.yaml `mux:` first; `MAESTRO_SESSION_MUX`
+ * only when the config is absent or `auto`; then tmux-if-installed, else
+ * screen — so `attach`/`peers` never span two multiplexers.
+ * @param {object} d deps
+ * @param {{mux?:string}} cfg loaded session config (may be {})
+ */
+function chooseMux(d, cfg = {}) {
+  const fromCfg = cfg && (cfg.mux === "screen" || cfg.mux === "tmux") ? cfg.mux : null;
+  const pref = fromCfg || (d.env && d.env.MAESTRO_SESSION_MUX) || "auto";
+  if (pref === "screen") return "screen";
+  if (pref === "tmux") return "tmux";
+  return d.exec("tmux", ["-V"]).status === 0 ? "tmux" : "screen";
+}
+
+/** Session config, fail-open to {} (a broken loader must not stop a spawn). */
+async function loadCfg(ctx) {
+  try { const c = await ctx.d.loadSessionConfig(ctx.agentRoot); return c && typeof c === "object" ? c : {}; } catch { return {}; }
+}
+
+function lockState(paths, d) {
+  let raw = null;
+  try { raw = readFileSync(paths.lock, "utf8"); } catch { return { held: false, pid: null }; }
+  const pid = parseInt((raw.split("\n")[0] || "").trim(), 10) || 0;
+  if (!pid) return { held: false, pid: null };
+  // Best-effort liveness (pid only). The identity-aware check lives in
+  // lib/singleton.js and runs at acquire time; a status read must not evict.
+  return { held: d.isAlive(pid), pid };
+}
+
+function listHandoffs(paths, now) {
+  let names = [];
+  try { names = readdirSync(paths.handoffsDir); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    if (!n.endsWith(".json")) continue;
+    const p = join(paths.handoffsDir, n);
+    try { if (!statSync(p).isFile()) continue; } catch { continue; }
+    const h = readJson(p);
+    if (!h || typeof h !== "object") continue; // corrupt handoff: skipped, never fatal
+    const enq = toMs(h.enqueuedAt);
+    const dl = toMs(h.deadlineAt);
+    out.push({
+      tickId: h.tickId || n.replace(/\.json$/, ""),
+      cadence: h.cadence || null,
+      mode: h.mode || null,
+      promptPath: h.promptPath || null,
+      enqueuedAt: h.enqueuedAt ?? null,
+      deadlineAt: h.deadlineAt ?? null,
+      ageMs: enq === null ? null : Math.max(0, now - enq),
+      overdue: dl !== null && now > dl,
+      path: p,
+    });
+  }
+  return out.sort((a, b) => (toMs(a.enqueuedAt) ?? 0) - (toMs(b.enqueuedAt) ?? 0));
+}
+
+/** Everything `status` reports, as data. */
+function snapshot(ctx) {
+  const { agentRoot, first, d, paths } = ctx;
+  const now = d.now();
+  const label = sessionLabel(first);
+  const hb = readJson(paths.heartbeat);
+  const ageMs = heartbeatAgeMs(hb, now);
+  const live = isLive(hb, now);
+  const mux = muxPresence(d, muxSessionName(first));
+  const plistPath = join(d.home, "Library", "LaunchAgents", `${label}.plist`);
+  const plistInstalled = existsSync(plistPath);
+  const loaded = d.exec("launchctl", ["list", label]).status === 0;
+  const { live: peers, dead } = prunePeers(readPeers(paths), (n) => muxPresence(d, n).present);
+  if (dead.length) {
+    // Prune under the registry lock, dropping only what THIS read saw dead —
+    // a peer registered in between survives. A status read never fails on it.
+    const gone = new Set(dead.map((p) => p && p.name));
+    updatePeers(paths, (cur) => cur.filter((p) => !(p && gone.has(p.name))), { now: d.now, waitMs: 500 });
+  }
+  const handoffs = listHandoffs(paths, now);
+  const main = readJson(paths.mainSession);
+  const notice = readJson(paths.upgradeNotice);
+  const installed = typeof d.installedVersion === "string" && d.installedVersion ? d.installedVersion : null;
+  // An upgrade notice whose target is what is already running was applied by
+  // a session restart; it is not pending and must not be surfaced (it stays
+  // on disk — the feed keys it by mtime — until the next release overwrites it).
+  const upgradeNotice = notice && typeof notice === "object" && !(installed && notice.to === installed) ? notice : null;
+  return {
+    first,
+    name: `${first}-main`,
+    label,
+    agentRoot,
+    live,
+    lock: lockState(paths, d),
+    heartbeat: {
+      live, ageMs,
+      ts: hb && hb.ts != null ? hb.ts : null,
+      pid: hb && hb.pid != null ? hb.pid : null,
+      sessionId: hb && hb.sessionId ? hb.sessionId : null,
+      feedVersion: hb && hb.feedVersion != null ? hb.feedVersion : null,
+    },
+    mainSession: main && typeof main === "object"
+      ? { sessionId: main.sessionId || null, createdAt: main.createdAt || null, resumes: main.resumes ?? 0 }
+      : null,
+    mux: { present: mux.present, kind: mux.kind, name: muxSessionName(first) },
+    plist: { installed: plistInstalled, loaded, path: plistPath },
+    peers,
+    handoffs: { open: handoffs.length, overdue: handoffs.filter((h) => h.overdue).length },
+    restartRequested: existsSync(paths.restartRequested),
+    upgradeNotice,
+    sdkVersion: installed,
+    ts: new Date(now).toISOString(),
+  };
+}
+
+const fmtAge = (ms) => {
+  if (ms === null || ms === undefined) return "none";
+  const s = Math.round(ms / 1000);
+  if (s < 90) return `${s}s`;
+  const m = Math.round(s / 60);
+  if (m < 90) return `${m}m`;
+  return `${Math.round(m / 60)}h`;
+};
+
+function briefLine(s) {
+  const bits = [];
+  bits.push(s.heartbeat.ageMs === null ? "no heartbeat" : `hb ${fmtAge(s.heartbeat.ageMs)}`);
+  bits.push(s.lock.held ? `lock pid ${s.lock.pid}` : "no lock");
+  bits.push(s.mux.present ? `${s.mux.kind} ${s.mux.name}` : "no mux session");
+  bits.push(s.plist.installed ? (s.plist.loaded ? "plist loaded" : "plist not loaded") : "plist not installed");
+  bits.push(`${s.peers.length} peer${s.peers.length === 1 ? "" : "s"}`);
+  bits.push(`${s.handoffs.open} handoff${s.handoffs.open === 1 ? "" : "s"}${s.handoffs.overdue ? ` (${s.handoffs.overdue} overdue)` : ""}`);
+  if (s.restartRequested) bits.push("restart requested");
+  if (s.upgradeNotice && s.upgradeNotice.to) bits.push(`upgrade → ${s.upgradeNotice.to}`);
+  return `${s.name}: ${s.live ? "live" : "not live"} (${bits.join(", ")})`;
+}
+
+function humanStatus(s) {
+  const L = [];
+  L.push(`Front-door session: ${s.name} (${s.label}) — ${s.live ? "LIVE" : "NOT LIVE"}`);
+  L.push(`  supervisor lock:  ${s.lock.held ? `held by pid ${s.lock.pid}` : "not held"}`);
+  L.push(`  heartbeat:        ${s.heartbeat.ageMs === null ? "none" : `${fmtAge(s.heartbeat.ageMs)} ago${s.live ? "" : " (stale)"}`}${s.heartbeat.sessionId ? ` · session ${s.heartbeat.sessionId}` : ""}`);
+  L.push(`  main session:     ${s.mainSession ? `${s.mainSession.sessionId || "?"} (resumes: ${s.mainSession.resumes})` : "none recorded"}`);
+  L.push(`  mux:              ${s.mux.present ? `${s.mux.kind} ${s.mux.name}` : `none (${s.mux.name})`}`);
+  L.push(`  launchd:          ${s.plist.installed ? (s.plist.loaded ? "installed, loaded" : "installed, NOT loaded") : "not installed"}`);
+  L.push(`  peers:            ${s.peers.length ? s.peers.map((p) => p.name).join(", ") : "none"}`);
+  L.push(`  handoffs open:    ${s.handoffs.open}${s.handoffs.overdue ? ` (${s.handoffs.overdue} overdue)` : ""}`);
+  const flags = [];
+  if (s.restartRequested) flags.push("restart requested");
+  if (s.upgradeNotice && s.upgradeNotice.to) flags.push(`upgrade available ${s.upgradeNotice.from || "?"} → ${s.upgradeNotice.to}`);
+  if (flags.length) L.push(`  flags:            ${flags.join("; ")}`);
+  if (!s.plist.installed) L.push("Next: npm run init-agent (generates + loads the session plist), then: maestro session start");
+  else if (!s.live) L.push("Next: maestro session start   (then: maestro session attach)");
+  else L.push("Attach: maestro session attach");
+  return L;
+}
+
+/** Ensure the label is loaded (bootstrap the plist if needed). */
+function ensureLoaded(ctx, say) {
+  const { d, first } = ctx;
+  const label = sessionLabel(first);
+  const target = `gui/${d.uid()}`;
+  if (d.exec("launchctl", ["list", label]).status === 0) return { ok: true, target, wasLoaded: true };
+  const plistPath = join(d.home, "Library", "LaunchAgents", `${label}.plist`);
+  if (!existsSync(plistPath)) {
+    say(`session: ${label} is not installed (${plistPath}).`);
+    say("  Fix: npm run init-agent   — or: bash scripts/local-triggers/generate-plists.sh, then copy + launchctl load the session plist.");
+    return { ok: false, target, wasLoaded: false };
+  }
+  const b = d.exec("launchctl", ["bootstrap", target, plistPath]);
+  if (b.status !== 0) say(`session: launchctl bootstrap returned ${b.status}${b.stderr ? `: ${b.stderr.trim()}` : ""} — continuing to kickstart`);
+  else say(`session: bootstrapped ${label}`);
+  return { ok: true, target, wasLoaded: false };
+}
+
+// ---------------------------------------------------------------------------
+// run()
+// ---------------------------------------------------------------------------
+
+export function usage() {
+  return `maestro session <command>
+
+  status [--brief|--json]      lock holder, heartbeat age, mux session, plist, peers, handoffs
+  attach                       print the attach command (tmux attach / screen -r); exec it on a TTY
+  start                        load the launchd job if needed, then kickstart it
+  stop                         launchctl bootout the session job
+  restart [--force]            ask the session to restart itself at an idle moment (--force: kickstart -k)
+  spawn --name <slug> [--cwd <dir>] "<prompt>"
+                               run a peer as <first>-<slug> in its own detached mux session; prints the name
+  peers [--json]               list peers (dead ones are pruned from state/session/peers.json)
+  handoffs [--json]            list open cadence handoffs
+  ack <tickId> [--result <p>]  mark a handoff done (moves it to handoffs/done/)`;
+}
+
+const FLAGS = {
+  json: { type: "boolean", default: false },
+  brief: { type: "boolean", default: false },
+  force: { type: "boolean", default: false },
+  name: { type: "string" },
+  cwd: { type: "string" },
+  result: { type: "string" },
+};
+
+/**
+ * @param {string[]} argv
+ * @param {{agentRoot?:string, print?:boolean, deps?:object, ackModule?:string}} [opts]
+ * @returns {Promise<{ok:boolean, code:number, lines:string[], data?:any}>}
+ */
+export async function run(argv = [], opts = {}) {
+  const agentRoot = opts.agentRoot || resolveAgentRoot();
+  const d = { ...defaultDeps(), ...(opts.deps || {}) };
+  const lines = [];
+  const say = (s) => { lines.push(s); if (opts.print !== false) console.log(s); };
+  const fail = (msg, code = 1) => { say(msg); return { ok: false, code, lines }; };
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: FLAGS, allowPositionals: true, strict: false });
+  } catch (e) {
+    return fail(`session: ${e && e.message ? e.message : e}`, 2);
+  }
+  const [sub, ...rest] = parsed.positionals;
+  const flags = parsed.values;
+  const first = resolveFirstName(agentRoot);
+  const paths = sessionPaths(agentRoot);
+  const ctx = { agentRoot, first, d, paths };
+
+  switch (sub) {
+    case undefined:
+    case "help":
+    case "--help":
+      say(usage());
+      return { ok: true, code: 0, lines };
+
+    case "status": {
+      const s = snapshot(ctx);
+      if (flags.json) say(JSON.stringify(s, null, 2));
+      else if (flags.brief) say(briefLine(s));
+      else for (const l of humanStatus(s)) say(l);
+      return { ok: true, code: 0, lines, data: s };
+    }
+
+    case "attach": {
+      const mux = muxPresence(d, muxSessionName(first));
+      if (!mux.present) {
+        return fail(`session: no ${muxSessionName(first)} multiplexer session is running. Start it with: maestro session start`);
+      }
+      const cmd = attachCommand(first, mux.kind);
+      say(`Attach: ${cmd.join(" ")}`);
+      if (!d.isTTY) { say("(not a TTY — run that command from a terminal)"); return { ok: true, code: 0, lines, data: { command: cmd } }; }
+      const r = d.execInherit(cmd[0], cmd.slice(1));
+      return { ok: r.status === 0, code: r.status, lines, data: { command: cmd } };
+    }
+
+    case "start": {
+      const l = ensureLoaded(ctx, say);
+      if (!l.ok) return { ok: false, code: 1, lines };
+      const label = sessionLabel(first);
+      const k = d.exec("launchctl", ["kickstart", `${l.target}/${label}`]);
+      if (k.status !== 0) return fail(`session: launchctl kickstart ${label} returned ${k.status}${k.stderr ? `: ${k.stderr.trim()}` : ""}`);
+      say(`session: started ${label} (launchd keeps it alive; attach with: maestro session attach)`);
+      return { ok: true, code: 0, lines };
+    }
+
+    case "stop": {
+      const label = sessionLabel(first);
+      const r = d.exec("launchctl", ["bootout", `gui/${d.uid()}/${label}`]);
+      if (r.status !== 0 && !/not find|No such|not loaded|3: /i.test(r.stderr || "")) {
+        return fail(`session: launchctl bootout ${label} returned ${r.status}${r.stderr ? `: ${r.stderr.trim()}` : ""}`);
+      }
+      say(r.status === 0 ? `session: stopped ${label} (launchd will not relaunch it until: maestro session start)` : `session: ${label} was not loaded`);
+      return { ok: true, code: 0, lines };
+    }
+
+    case "restart": {
+      // The marker is what the session's feed turns into a `restart` directive;
+      // the session finishes its turn, exits, and the supervisor relaunches on
+      // whatever code is on disk now. It is written ONLY once the job is known
+      // to be loaded: a job that is not running has nothing to restart, and a
+      // marker left behind would fire spuriously on its next first boot.
+      // kickstart without -k only starts a job that is not running; --force
+      // kills and restarts immediately.
+      const l = ensureLoaded(ctx, say);
+      if (!l.ok) return { ok: false, code: 1, lines };
+      const label = sessionLabel(first);
+      if (l.wasLoaded) {
+        try {
+          mkdirSync(paths.dir, { recursive: true });
+          writeFileSync(paths.restartRequested, `${new Date(d.now()).toISOString()}\n`);
+        } catch (e) {
+          return fail(`session: could not write ${paths.restartRequested}: ${e && e.message ? e.message : e}`);
+        }
+      }
+      const args = flags.force ? ["kickstart", "-k", `${l.target}/${label}`] : ["kickstart", `${l.target}/${label}`];
+      const k = d.exec("launchctl", args);
+      if (k.status !== 0) return fail(`session: launchctl ${args.join(" ")} returned ${k.status}${k.stderr ? `: ${k.stderr.trim()}` : ""}`);
+      if (!l.wasLoaded) say(`session: ${label} was not running — started it (no restart marker written)`);
+      else say(flags.force ? `session: ${label} killed and restarted` : `session: restart requested — ${label} will relaunch at its next idle moment (use --force to restart now)`);
+      return { ok: true, code: 0, lines };
+    }
+
+    case "spawn": {
+      const slug = typeof flags.name === "string" ? flags.name.trim() : "";
+      if (!slug) return fail("session spawn: --name <slug> is required", 2);
+      if (!SLUG_RE.test(slug)) return fail(`session spawn: invalid --name "${slug}" (use lower-case letters, digits and hyphens)`, 2);
+      const prompt = rest.join(" ").trim();
+      if (!prompt) return fail("session spawn: a prompt is required: maestro session spawn --name <slug> \"<prompt>\"", 2);
+      const cwd = flags.cwd ? String(flags.cwd) : agentRoot;
+      if (!existsSync(cwd)) return fail(`session spawn: --cwd ${cwd} does not exist`, 2);
+      const name = `${first}-${slug}`;
+      const muxName = peerMuxName(first, slug);
+
+      const registered = readPeers(paths).find((p) => p && p.name === name);
+      if (registered && muxPresence(d, registered.muxName || muxName).present) {
+        return fail(`session spawn: ${name} is already running (${registered.muxName || muxName}); pick another --name or wait for it to finish`);
+      }
+
+      const cfg = await loadCfg(ctx);
+      const kind = chooseMux(d, cfg);
+      const bin = d.claudeBin || resolveClaudeBin();
+      const args = buildSpawnArgs({ first, slug, prompt, env: d.env, allowedTools: cfg.allowedTools });
+      const r = kind === "tmux"
+        ? d.exec("tmux", ["new-session", "-d", "-s", muxName, "-c", cwd, "--", bin, ...args], { cwd, env: d.env })
+        : d.exec("screen", ["-dmS", muxName, bin, ...args], { cwd, env: d.env });
+      if (r.status !== 0) return fail(`session spawn: ${kind} returned ${r.status}${r.stderr ? `: ${r.stderr.trim()}` : ""}`);
+
+      const startedAt = new Date(d.now()).toISOString();
+      const reg = updatePeers(paths, (cur) => [
+        ...cur.filter((p) => p && p.name !== name),
+        { name, muxName, startedAt, purpose: prompt.slice(0, 200), cwd, mux: kind },
+      ], { now: d.now });
+      if (!reg.ok) say(`session spawn: warning — peers.json not updated: ${reg.error}`);
+      const attach = kind === "tmux" ? `tmux attach -t ${muxName}` : `screen -r ${muxName}`;
+      say(`session: spawned ${name} in ${kind} session ${muxName} (attach: ${attach})`);
+      say(name);
+      return { ok: true, code: 0, lines, data: { name, muxName, kind, startedAt } };
+    }
+
+    case "peers": {
+      const { live, dead } = prunePeers(readPeers(paths), (n) => muxPresence(d, n).present);
+      if (dead.length) {
+        const gone = new Set(dead.map((p) => p && p.name));
+        updatePeers(paths, (cur) => cur.filter((p) => !(p && gone.has(p.name))), { now: d.now, waitMs: 500 }); // listing never fails on a registry write
+      }
+      if (flags.json) { say(JSON.stringify(live, null, 2)); return { ok: true, code: 0, lines, data: live }; }
+      if (!live.length) say(`session: no peers running${dead.length ? ` (${dead.length} finished, pruned)` : ""}`);
+      else {
+        say(`Peers (${live.length})${dead.length ? ` — ${dead.length} finished, pruned` : ""}:`);
+        for (const p of live) say(`  ${String(p.name).padEnd(28)} ${p.mux || "mux"} ${p.muxName}  since ${p.startedAt || "?"}${p.purpose ? `  — ${p.purpose}` : ""}`);
+      }
+      return { ok: true, code: 0, lines, data: live };
+    }
+
+    case "handoffs": {
+      const list = listHandoffs(paths, d.now());
+      if (flags.json) { say(JSON.stringify(list, null, 2)); return { ok: true, code: 0, lines, data: list }; }
+      if (!list.length) say("session: no open handoffs");
+      else {
+        say(`Open handoffs (${list.length}):`);
+        for (const h of list) say(`  ${String(h.tickId).padEnd(24)} ${String(h.cadence || "?").padEnd(26)} ${String(h.mode || "").padEnd(9)} age ${fmtAge(h.ageMs)}${h.overdue ? "  OVERDUE" : ""}`);
+        say("Ack one with: maestro session ack <tickId> [--result <path>]");
+      }
+      return { ok: true, code: 0, lines, data: list };
+    }
+
+    case "ack": {
+      const tickId = rest[0];
+      if (!tickId) return fail("session ack: <tickId> is required", 2);
+      const spec = opts.ackModule || "./session-ack.mjs";
+      const url = spec.startsWith("/") ? pathToFileURL(spec).href : new URL(spec, import.meta.url).href;
+      let mod;
+      try {
+        mod = await import(url);
+      } catch (e) {
+        if (e && (e.code === "ERR_MODULE_NOT_FOUND" || /Cannot find module/.test(String(e.message)))) {
+          return fail("session ack: not available in this install — lib/cli/session-ack.mjs is missing (it ships with the daemon-integration package; upgrade the SDK).");
+        }
+        return fail(`session ack: could not load session-ack: ${e && e.message ? e.message : e}`);
+      }
+      if (typeof mod.ackHandoff !== "function") return fail("session ack: lib/cli/session-ack.mjs does not export ackHandoff()");
+      let r;
+      try {
+        r = await mod.ackHandoff({ agentRoot, tickId, resultPath: flags.result ? String(flags.result) : null, now: d.now() });
+      } catch (e) {
+        return fail(`session ack: ${e && e.message ? e.message : e}`);
+      }
+      if (!r || r.ok === false) return fail(`session ack: ${(r && r.error) || "failed"}`);
+      // WP-M2's ackHandoff returns {ok, path, already}; older shapes used movedTo.
+      const dest = r.path || r.movedTo || "";
+      if (r.already) say(`session: ${tickId} was already acked${dest ? ` (${dest})` : ""}`);
+      else say(`session: acked ${tickId}${dest ? ` → ${dest}` : ""}`);
+      return { ok: true, code: 0, lines, data: r };
+    }
+
+    default:
+      return fail(`session: unknown command "${sub}"\n\n${usage()}`, 2);
+  }
+}