@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/scripts/session/supervisor.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * scripts/session/supervisor.mjs — keeps exactly one main session alive.
+ *
+ * Launched by launchd (`ai.maestro.<first>-session`, KeepAlive
+ * {SuccessfulExit:false}, ThrottleInterval 30) through supervisor.sh. One run
+ * of this process is ONE lifetime of the main session:
+ *
+ *   1. Take the `session` singleton lock (lib/singleton.js). A second
+ *      supervisor exits 0 — clean — so launchd does not thrash.
+ *   2. Pick the multiplexer (tmux if installed, else /usr/bin/screen).
+ *   3. If a `maestro-<first>` mux session already exists with no lock holder
+ *      (an orphan from a killed supervisor), ADOPT it: block until it is gone
+ *      rather than start a duplicate.
+ *   4. Otherwise pre-answer the first-run dialogs an unattended session
+ *      cannot (lib/session/first-run.mjs seeds ~/.claude.json), then launch
+ *      `claude --name <first>-main` with the stable session id
+ *      (`--session-id` first time, `--resume` after) IN THE FOREGROUND of
+ *      the mux, so this process lives exactly as long as the session. A
+ *      watchdog flags a session that is alive but has not beaten after
+ *      HEARTBEAT_GRACE_MS (log + state/session/attention.json for doctor).
+ *   5. When the session ends: if a resume died non-zero inside 20 s, rotate
+ *      to a fresh id (max 3/hour, then sleep 10 min); then exit 75 so launchd
+ *      relaunches. No cron, no periodic kill — relaunch happens only on death.
+ *
+ * SIGTERM/SIGINT (launchd stopping the job: `kickstart -k`, `bootout`) are
+ * owned HERE, not by the singleton's default handlers: the mux session is
+ * told to quit (`screen -X quit` / `tmux kill-session`), the run then ends
+ * through the normal path with rotation suppressed (a signal-induced death
+ * inside the 20 s window is not a broken transcript), and the exit is 75.
+ * Exiting 0 at once — the singleton default — would orphan screen/claude in
+ * the supervisor's process group, which launchd then SIGKILLs, leaving the
+ * dead socket that step 3 has to wipe.
+ *
+ * Exit codes: 0 = another supervisor holds the lock (or nothing to supervise);
+ * 75 (EX_TEMPFAIL) = the session ended, relaunch me.
+ *
+ * All effects are injected (`execFile`, fs, clock, sleep, lock) so the whole
+ * lifecycle is unit-tested without a terminal, a mux or a `claude` binary.
+ * The decisions live in lib/session/*; this file sequences them.
+ *
+ * @module scripts/session/supervisor
+ */
+
+import { existsSync as fsExistsSync, readFileSync as fsReadFileSync, mkdirSync as fsMkdirSync, unlinkSync as fsUnlinkSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
+
+import { resolveAgentRoot } from "../../lib/agent-root.mjs";
+import { writeJsonAtomic as fsWriteJsonAtomic, writeFileAtomic as fsWriteFileAtomic } from "../../lib/fs-atomic.mjs";
+import { parseHeartbeat } from "../../lib/session/liveness.mjs";
+import { ensureClaudeConfig, heartbeatSilence, attentionRecord, HEARTBEAT_GRACE_MS } from "../../lib/session/first-run.mjs";
+import { acquireLock as singletonAcquireLock } from "../../lib/singleton.js";
+import { resolveClaudeBin } from "../../lib/claude-bin.mjs";
+import { sessionPermissionArgs, MAIN_SESSION_SOURCE } from "../../lib/session-permissions.mjs";
+import { loadSessionConfig, sessionPaths } from "../../lib/session/config.mjs";
+import {
+  loadMainSession, saveMainSession, newMainSession, agentFirstName, muxSessionName,
+  launchMode, recordLaunch, rotationDecision, rotateMainSession, BACKOFF_MS,
+} from "../../lib/session/identity.mjs";
+import { buildClaudeArgs, detectMux, chooseMux, buildMuxCommands, parseScreenList, parseExitFile } from "../../lib/session/launch-args.mjs";
+
+/** Another supervisor holds the lock (or the front door is not the session). Clean. */
+export const EXIT_ANOTHER_HOLDS_LOCK = 0;
+/** The session ended; launchd should relaunch (EX_TEMPFAIL). */
+export const EXIT_RELAUNCH = 75;
+/** Name of the singleton lock (state/locks/process/session.pid). */
+export const LOCK_NAME = "session";
+/** How often the tmux `has-session` probe (and the orphan probe) is polled. */
+export const DEFAULT_POLL_MS = 2_000;
+/** The signals the supervisor owns (launchd sends SIGTERM to stop a job). */
+export const OWNED_SIGNALS = Object.freeze(["SIGTERM", "SIGINT"]);
+
+/** Real signal wiring: `fn(signal)` on each owned signal. */
+function installSignalHandlers(fn) {
+  for (const sig of OWNED_SIGNALS) process.on(sig, () => fn(sig));
+}
+
+/** Real one-shot timer (unref'd: it must never keep the process alive). Returns cancel. */
+function defaultAfter(ms, fn) {
+  const t = setTimeout(fn, ms);
+  if (t && typeof t.unref === "function") t.unref();
+  return () => clearTimeout(t);
+}
+
+/**
+ * Real `execFile`: spawn without a shell, capture stdout, resolve with the
+ * exit code (never reject on a non-zero code — that is a result, not a defect).
+ * stderr is inherited so mux/claude diagnostics reach the supervisor log.
+ * @returns {Promise<{code:number|null, stdout:string, stderr:string}>}
+ */
+export function execFileResult(file, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(file, args, { cwd: opts.cwd, env: opts.env || process.env, stdio: ["ignore", "pipe", "inherit"] });
+    } catch (err) { reject(err); return; }
+    let stdout = "";
+    child.stdout.on("data", (d) => { stdout += d; });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code, stdout, stderr: "" }));
+  });
+}
+
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Block while `probe` exits 0 (tmux `has-session`); return once it does not.
+ * @param {{file:string, args:string[]}} probe
+ * @param {{execFile:Function, sleep:Function, pollMs:number}} d
+ */
+export async function waitForProbe(probe, d) {
+  for (;;) {
+    let r;
+    try { r = await d.execFile(probe.file, probe.args); } catch { return; /* probe binary gone → treat as ended */ }
+    if (!r || r.code !== 0) return;
+    await d.sleep(d.pollMs);
+  }
+}
+
+/** Does the mux session exist right now? */
+async function muxSessionExists(mux, cmds, muxName, d) {
+  let r;
+  try { r = await d.execFile(cmds.exists.file, cmds.exists.args); } catch { return false; }
+  if (mux.kind === "screen") return parseScreenList(r && r.stdout, muxName);
+  return !!r && r.code === 0;
+}
+
+/** Block until the mux session is gone. */
+async function waitForMuxSession(mux, cmds, muxName, d) {
+  if (mux.kind === "tmux") return waitForProbe(cmds.waitProbe, d);
+  while (await muxSessionExists(mux, cmds, muxName, d)) await d.sleep(d.pollMs);
+}
+
+/**
+ * One main-session lifetime. See the module docblock.
+ * @param {object} [deps] every effect, injectable; defaults are the real ones
+ * @returns {Promise<number>} exit code
+ */
+export async function runSupervisor(deps = {}) {
+  const d = {
+    agentRoot: deps.agentRoot || resolveAgentRoot(),
+    env: deps.env || process.env,
+    acquireLock: deps.acquireLock || singletonAcquireLock,
+    existsSync: deps.existsSync || fsExistsSync,
+    readFileSync: deps.readFileSync || fsReadFileSync,
+    writeJsonAtomic: deps.writeJsonAtomic || fsWriteJsonAtomic,
+    writeFileAtomic: deps.writeFileAtomic || fsWriteFileAtomic,
+    homeDir: deps.homeDir === undefined ? homedir() : deps.homeDir,
+    after: deps.after || defaultAfter,
+    heartbeatGraceMs: deps.heartbeatGraceMs ?? HEARTBEAT_GRACE_MS,
+    mkdirSync: deps.mkdirSync || fsMkdirSync,
+    unlinkSync: deps.unlinkSync || fsUnlinkSync,
+    now: deps.now || Date.now,
+    sleep: deps.sleep || defaultSleep,
+    log: deps.log || ((line) => process.stderr.write(`[session-supervisor] ${line}\n`)),
+    uuid: deps.uuid,
+    execFile: deps.execFile || execFileResult,
+    loadConfig: deps.loadConfig || ((root) => loadSessionConfig(root)),
+    claudeBin: deps.claudeBin || null,
+    permissionArgs: deps.permissionArgs || null,
+    pollMs: deps.pollMs ?? DEFAULT_POLL_MS,
+    onSignal: deps.onSignal || installSignalHandlers,
+  };
+  const fsDeps = { readFileSync: d.readFileSync, writeJsonAtomic: d.writeJsonAtomic };
+  const agentRoot = d.agentRoot;
+  const paths = sessionPaths(agentRoot);
+
+  // 1. Exactly one. The lock's own signal handlers are declined: SIGTERM is
+  //    handled below so the mux session is stopped before this process ends.
+  if (!d.acquireLock(LOCK_NAME, { signals: false })) {
+    d.log("another supervisor holds the session lock — exiting clean");
+    return EXIT_ANOTHER_HOLDS_LOCK;
+  }
+
+  // Shutdown on request. `stopCmd` is set once a mux session is ours to stop
+  // (adopted or launched); a signal before that only marks the run as
+  // stopping so nothing new is launched.
+  let stopping = null;
+  let stopCmd = null;
+  let stopIssued = null;
+  const requestStop = () => {
+    if (stopIssued || !stopCmd) return;
+    stopIssued = Promise.resolve()
+      .then(() => d.execFile(stopCmd.file, stopCmd.args))
+      .catch((err) => { d.log(`mux stop failed: ${err && err.message ? err.message : err}`); });
+  };
+  d.onSignal((sig) => {
+    if (stopping) return;
+    stopping = sig;
+    d.log(`${sig} received — stopping the session and exiting ${EXIT_RELAUNCH}`);
+    requestStop();
+  });
+
+  const cfg = await d.loadConfig(agentRoot);
+  if (cfg.frontDoor !== "session") {
+    d.log(`frontDoor is "${cfg.frontDoor}" — nothing to supervise, exiting clean`);
+    return EXIT_ANOTHER_HOLDS_LOCK;
+  }
+
+  const first = agentFirstName(agentRoot, fsDeps);
+  const muxName = muxSessionName(first);
+  try { d.mkdirSync(paths.stateDir, { recursive: true }); } catch { /* the atomic writers create it too */ }
+
+  // 2. Multiplexer.
+  const mux = chooseMux(cfg.mux, detectMux({ existsSync: d.existsSync }));
+  if (!mux) {
+    d.log(`no terminal multiplexer found (tmux or /usr/bin/screen) — backing off ${BACKOFF_MS / 60000} min`);
+    await d.sleep(BACKOFF_MS);
+    return EXIT_RELAUNCH;
+  }
+
+  // 3. Orphan adoption. We hold the lock, so an existing mux session has no
+  //    supervisor: attach to its lifetime instead of starting a second one.
+  //    First clear DEAD sockets (a SIGKILLed screen leaves `(Dead ???)` in
+  //    SCREENDIR, which `-ls` still lists): `screen -wipe` is hygiene and
+  //    parseScreenList ignores dead lines regardless, so a failing wipe costs
+  //    nothing.
+  const probeCmds = buildMuxCommands({ mux, muxName, cwd: agentRoot, claudeBin: "claude", claudeArgs: [], exitFile: paths.lastExitFile });
+  if (probeCmds.wipe) {
+    try { await d.execFile(probeCmds.wipe.file, probeCmds.wipe.args); } catch { /* nothing to wipe, or no permission — the probe decides */ }
+  }
+  if (await muxSessionExists(mux, probeCmds, muxName, d)) {
+    d.log(`adopting orphaned ${mux.kind} session ${muxName} — waiting for it to end`);
+    stopCmd = probeCmds.stop;
+    if (stopping) requestStop();
+    await waitForMuxSession(mux, probeCmds, muxName, d);
+    await stopIssued;
+    d.log(`adopted session ${muxName} ended — exit ${EXIT_RELAUNCH} for relaunch`);
+    return EXIT_RELAUNCH;
+  }
+  if (stopping) return EXIT_RELAUNCH; // asked to stop before anything was launched
+
+  // 4. Identity + argv.
+  let record = loadMainSession(agentRoot, fsDeps);
+  if (!record || cfg.resume === false) record = newMainSession({ now: d.now, uuid: d.uuid });
+  const mode = launchMode(record, cfg);
+  let permissionArgs = d.permissionArgs;
+  if (!permissionArgs) {
+    permissionArgs = sessionPermissionArgs({ source: MAIN_SESSION_SOURCE, allowedTools: cfg.allowedTools });
+    if (d.env.MAESTRO_SCOPED_PERMISSIONS === "1" && !permissionArgs.includes("--allowedTools")) {
+      d.log("MAESTRO_SCOPED_PERMISSIONS=1 but config/session.yaml has no allowedTools — the interactive main session runs with bypass (an unattended session cannot answer permission prompts)");
+    }
+  }
+  const claudeArgs = buildClaudeArgs({ first, sessionId: record.sessionId, mode, permissionArgs });
+  const cmds = buildMuxCommands({ mux, muxName, cwd: agentRoot, claudeBin: d.claudeBin || resolveClaudeBin(), claudeArgs, exitFile: paths.lastExitFile });
+
+  // 4b. First-run dialogs. Nobody is attached to press a key, so the two
+  //     one-time acknowledgements are recorded up front. Fail-open: a seat
+  //     still launches when this cannot be done — the watchdog below then
+  //     reports the blocked session instead of nothing at all.
+  const seeded = ensureClaudeConfig({
+    homeDir: d.homeDir, agentRoot, bypass: permissionArgs.includes("--dangerously-skip-permissions"),
+    readFileSync: d.readFileSync, writeFileAtomic: d.writeFileAtomic,
+  });
+  if (seeded.changed) d.log(`${seeded.path} seeded for an unattended launch: ${seeded.applied.join(", ")}`);
+  else if (!seeded.ok) d.log(`${seeded.path || "~/.claude.json"} not seeded (${seeded.error}) — a first-run dialog may block the session; the watchdog will report it`);
+
+  try { d.unlinkSync(paths.lastExitFile); } catch { /* none from a previous run */ }
+  try { d.unlinkSync(paths.attentionFile); } catch { /* none outstanding */ }
+  const launched = recordLaunch(record, { now: d.now });
+  const saved = saveMainSession(agentRoot, launched, fsDeps);
+  if (!saved.ok) d.log(`main-session.json not saved: ${saved.error}`);
+  d.log(`launching ${mux.kind} session ${muxName}: claude ${mode === "resume" ? "--resume" : "--session-id"} ${record.sessionId} (resumes=${launched.resumes})`);
+
+  // 5. Run, in the foreground of this process. The watchdog fires once,
+  //    after the grace period: a session that has not beaten by then is
+  //    almost certainly waiting on a dialog or a prompt nobody can see.
+  const startedAt = Number(d.now());
+  let launchFailed = false;
+  stopCmd = cmds.stop;
+  const cancelWatchdog = d.after(d.heartbeatGraceMs, () => {
+    let hb = null;
+    try { hb = parseHeartbeat(d.readFileSync(paths.heartbeatFile, "utf8")); } catch { hb = null; }
+    const silence = heartbeatSilence({ startedAt, heartbeat: hb, now: d.now(), graceMs: d.heartbeatGraceMs });
+    if (!silence.silent) return;
+    const rec = attentionRecord({ reason: silence.reason, mux, muxName, since: startedAt, runMs: silence.runMs });
+    try { d.writeJsonAtomic(paths.attentionFile, rec); } catch { /* the log line still says it */ }
+    d.log(`session ${muxName} has been up ${Math.round(silence.runMs / 1000)} s with no heartbeat — probably blocked on a first-run dialog or a permission prompt; attach with \`${rec.attach}\` and answer it`);
+  });
+  try {
+    const r = await d.execFile(cmds.start.file, cmds.start.args, { cwd: agentRoot, env: d.env });
+    if (r && r.code !== 0) { launchFailed = true; d.log(`${mux.kind} start exited ${r.code}${r.stderr ? `: ${String(r.stderr).trim()}` : ""}`); }
+    else if (!cmds.blocking) await waitForProbe(cmds.waitProbe, d);
+  } catch (err) {
+    launchFailed = true;
+    d.log(`${mux.kind} start failed: ${err && err.message ? err.message : err}`);
+  }
+  const endedAt = Number(d.now());
+  try { cancelWatchdog(); } catch { /* already fired */ }
+  await stopIssued;
+
+  let exitCode = null;
+  try { exitCode = parseExitFile(d.readFileSync(paths.lastExitFile, "utf8")); } catch { exitCode = null; /* never written */ }
+  if (launchFailed && exitCode === null) exitCode = 1;
+  d.log(`session ${muxName} ended after ${Math.round((endedAt - startedAt) / 1000)} s (exit ${exitCode === null ? "unknown" : exitCode})`);
+
+  // 6. Rotation — never for a death we caused.
+  if (stopping) {
+    d.log(`session ${muxName} stopped on ${stopping} — id kept, exit ${EXIT_RELAUNCH}`);
+    return EXIT_RELAUNCH;
+  }
+  const decision = rotationDecision({ record: launched, mode, exitCode, startedAt, endedAt, now: d.now });
+  if (decision.action === "rotate") {
+    const rotated = rotateMainSession(launched, { now: d.now, uuid: d.uuid });
+    const res = saveMainSession(agentRoot, rotated, fsDeps);
+    d.log(`resume of ${launched.sessionId} failed inside the failure window — rotated to ${rotated.sessionId}${res.ok ? "" : ` (not saved: ${res.error})`}`);
+  } else if (decision.action === "backoff") {
+    d.log(`rotation budget spent for this hour — sleeping ${decision.sleepMs / 60000} min before relaunch`);
+    await d.sleep(decision.sleepMs);
+  }
+  return EXIT_RELAUNCH;
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href; } catch { return false; }
+})();
+
+if (isMain) {
+  runSupervisor()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      // A defect in the supervisor itself: log it and ask launchd to try again.
+      process.stderr.write(`[session-supervisor] fatal: ${err && err.stack ? err.stack : err}\n`);
+      process.exit(EXIT_RELAUNCH);
+    });
+}

package/scripts/session/supervisor.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+# supervisor.sh — launchd wrapper for the main-session supervisor.
+#
+# Same idiom as scripts/daemon/launchd-wrapper.sh: launchd's environment is
+# bare (no HOME, PATH, AGENT_ROOT), so we set them here and exec node, rather
+# than putting them in the plist (EX_CONFIG failures seen with symlinked paths).
+#
+# What differs from the daemon wrapper: the SESSION needs the seat's `.env`
+# (CLAUDE_CODE_OAUTH_TOKEN, MAESTRO_PREFER_SUBSCRIPTION_AUTH, MAESTRO_SCOPED_
+# PERMISSIONS, …) in its environment, because `claude` is launched by the
+# supervisor inside a multiplexer and reads its auth from env. The daemon
+# loads .env in JS; the supervisor gets it from here so the same values reach
+# screen/tmux → sh → claude without any of them being written to a plist.
+#
+# .env handling mirrors what dotenv (the daemon's loader) does, so the same
+# file yields the same token here and there: only `KEY=value` lines
+# (optionally `export KEY=value`) are read; comments and malformed lines are
+# skipped; a trailing CR (CRLF file) is dropped; one layer of matching quotes
+# is stripped and a quoted `#` is data; an UNQUOTED value ends at the first
+# `#` and is trimmed; a variable ALREADY in the environment wins (so an
+# operator can override from a shell, and a launchd-provided value is never
+# clobbered). Values are never echoed.
+#
+# Exit codes are the supervisor's: 0 = another supervisor holds the lock,
+# 75 = the session ended, relaunch (KeepAlive SuccessfulExit:false does that).
+#
+# AGENT_ROOT: a value already in the environment (plist EnvironmentVariables,
+# an operator shell) wins; otherwise the agent dir is derived from this
+# script's own location, which is right for the copy `maestro upgrade` places
+# at <agent>/scripts/session/. Either way the root must BE an agent directory
+# (config/agent.json present) — running from the global npm package dir would
+# put locks, state and logs inside node_modules and start claude in the wrong
+# cwd, so that exits 78 (EX_CONFIG) with a message instead.
+#
+# This wrapper is exec'd by ai.maestro.{firstname}-session.plist.
+
+set -e
+
+if [ -z "${AGENT_ROOT:-}" ] || [ ! -d "${AGENT_ROOT:-}" ]; then
+  AGENT_ROOT="$(cd "$(dirname "$0")/../.." && pwd -P)"
+else
+  AGENT_ROOT="$(cd "$AGENT_ROOT" && pwd -P)"
+fi
+export AGENT_ROOT
+export AGENT_DIR="$AGENT_ROOT"
+
+if [ ! -f "$AGENT_ROOT/config/agent.json" ]; then
+  echo "[session-wrapper] FATAL: $AGENT_ROOT is not an agent directory (no config/agent.json) — set AGENT_ROOT or run the copy under <agent>/scripts/session/" >&2
+  exit 78
+fi
+
+# ── emergency stop ──────────────────────────────────────────────────────────
+# scripts/emergency-stop.sh drops .emergency-stop and unloads every job; the
+# daemon honours the marker and exits. The session must too — otherwise a
+# by-hand `maestro upgrade` (whose launchd step is held under the marker, but
+# a login re-bootstraps LaunchAgents regardless) would start the front-door
+# claude session under an active stop. Exit 0: KeepAlive {SuccessfulExit:
+# false} does NOT relaunch a clean exit, so launchd stays quiet until the
+# marker is gone and the job is started again (maestro session start).
+if [ -e "$AGENT_ROOT/.emergency-stop" ] || [ -e "$AGENT_ROOT/state/EMERGENCY_STOP" ]; then
+  echo "[session-wrapper] emergency stop is active ($AGENT_ROOT/.emergency-stop or state/EMERGENCY_STOP) — not starting the session; remove the marker and run: maestro session start" >&2
+  exit 0
+fi
+export HOME="${HOME:-/Users/$(whoami)}"
+export USER="${USER:-$(whoami)}"
+export PATH="$HOME/.local/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
+
+# ── .env → environment ──────────────────────────────────────────────────────
+maestro_source_env() {
+  local file="$1" line key value
+  [ -f "$file" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line="${line%$'\r'}"
+    line="${line#export }"
+    case "$line" in ''|\#*) continue ;; esac
+    case "$line" in *=*) ;; *) continue ;; esac
+    key="${line%%=*}"
+    value="${line#*=}"
+    case "$key" in ''|*[!A-Za-z0-9_]*) continue ;; esac
+    case "$value" in
+      \"*\") value="${value#\"}"; value="${value%\"}" ;;
+      \'*\') value="${value#\'}"; value="${value%\'}" ;;
+      *)
+        value="${value%%#*}"
+        value="${value%"${value##*[![:space:]]}"}"
+        value="${value#"${value%%[![:space:]]*}"}"
+        ;;
+    esac
+    if [ -z "${!key+x}" ]; then
+      export "$key=$value"
+    fi
+  done < "$file"
+}
+maestro_source_env "$AGENT_ROOT/.env"
+
+cd "$AGENT_ROOT"
+
+# ── node ────────────────────────────────────────────────────────────────────
+# NODE_BIN may be pre-set (tests, operators); otherwise prefer nvm, then
+# homebrew, then system — the daemon wrapper's order. MAESTRO_NODE_CANDIDATES
+# (colon-separated) replaces the fixed list so the search is testable and an
+# unusual install can be pointed at without editing this file.
+NODE_BIN="${NODE_BIN:-}"
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  NODE_BIN=""
+  if [ -n "${MAESTRO_NODE_CANDIDATES:-}" ]; then
+    IFS=':' read -r -a node_candidates <<< "$MAESTRO_NODE_CANDIDATES"
+  else
+    node_candidates=(
+      "$HOME/.nvm/versions/node/v24.11.1/bin/node"
+      "$HOME/.nvm/versions/node/v24/bin/node"
+      "$HOME/.nvm/versions/node/v22/bin/node"
+      "$HOME/.nvm/versions/node/v20/bin/node"
+      /opt/homebrew/bin/node
+      /usr/local/bin/node
+      /usr/bin/node
+    )
+  fi
+  for candidate in "${node_candidates[@]}"; do
+    if [ -n "$candidate" ] && [ -x "$candidate" ]; then
+      NODE_BIN="$candidate"
+      break
+    fi
+  done
+fi
+if [ -z "$NODE_BIN" ] && [ -d "$HOME/.nvm/versions/node" ]; then
+  NODE_BIN=$(ls -1d "$HOME/.nvm/versions/node"/v*/bin/node 2>/dev/null | sort -V | tail -1)
+fi
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  echo "[session-wrapper] FATAL: could not find node binary" >&2
+  exit 127
+fi
+export NODE_BIN
+
+# ── exec ────────────────────────────────────────────────────────────────────
+# The supervisor's own diagnostics go to logs/session/; the session itself
+# lives inside the multiplexer and is not captured here.
+SESSION_LOG_DIR="${MAESTRO_SESSION_LOG_DIR:-$AGENT_ROOT/logs/session}"
+mkdir -p "$SESSION_LOG_DIR" 2>/dev/null || true
+SESSION_LOG="$SESSION_LOG_DIR/supervisor-$(date +%Y-%m-%d).log"
+exec "$NODE_BIN" "$AGENT_ROOT/scripts/session/supervisor.mjs" "$@" >> "$SESSION_LOG" 2>&1