@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/scripts/maintenance/pin-integrity.mjs

@@ -0,0 +1,364 @@
+#!/usr/bin/env node
+/**
+ * pin-integrity.mjs — did the local fixes survive, and is the daemon running
+ * them, and how far behind the release has each pin drifted?
+ *
+ * A `.maestroignore` pin is FILE-granular: `maestro upgrade` never touches a
+ * pinned path, so the seat keeps its hand-patched copy — and silently misses
+ * every upstream line that path will ever receive. Nothing alarmed on that
+ * debt, so a pin taken for a two-line fix could sit hundreds of release lines
+ * behind with no signal. This script measures it and is meant to run as a
+ * doctor check: exit 0 is "no pin is behind past the threshold".
+ *
+ * For every path listed in .maestroignore (blank lines and `#` comments
+ * skipped), report one of:
+ *   identical     the local file is byte-identical to the vendored SDK copy —
+ *                 the local fix is GONE (an upgrade/rollback rewrote it, or it
+ *                 was never applied).
+ *   not-loaded    the local file differs but its mtime post-dates the daemon
+ *                 boot (state/cadence-bus/health.json), so the RUNNING daemon
+ *                 still executes the old code. Only meaningful for
+ *                 daemon-loaded modules (scripts/daemon, scripts/collective,
+ *                 lib; never *.test.mjs).
+ *   ok            differs from vendored and predates the daemon boot.
+ *   missing-local the pin names a file that does not exist locally.
+ *   no-vendored   the SDK ships no copy under that path (nothing can clobber it).
+ *
+ * Every differing pin also carries `delta {release_only, local_only, behind}`
+ * measured by `diff`: release_only = lines the release has that we lack (the
+ * debt), local_only = the patch we keep. `behind` = release_only > 0.
+ *
+ * A third reference, upstream main, closes the gap the vendored release cannot
+ * see: a seat at exactly the current release with a pin byte-identical to that
+ * release reads `identical` (fix lost) — or `ok` — while the fix it was taken
+ * for has already merged upstream and will only arrive with the next release.
+ * When an SDK source checkout is known (`--repo DIR`, else `MAESTRO_SDK_REPO`)
+ * each pin is also compared with `git -C DIR show <ref>:<path>` (`--upstream`,
+ * default `origin/main`) and carries `upstream_state` + `delta_upstream
+ * {upstream_only, local_only}`:
+ *   identical     byte-identical to the file at <ref>.
+ *   ok            differs, but <ref> has no line we lack.
+ *   behind-main   upstream_only exceeds the threshold — main already carries
+ *                 lines this pin will never receive through an upgrade.
+ *   no-upstream   the path does not exist at <ref> (a notice, never a failure).
+ * No checkout, or a ref that does not resolve, skips the comparison with a
+ * one-line notice; the vendored report and its exit code are unaffected.
+ *
+ * The unpinned walk over scripts/daemon, scripts/collective, scripts/org,
+ * scripts/session and lib classifies every other .mjs/.js/.py/.sh file:
+ *   unpinned      differs from the vendored copy and is NOT pinned — an
+ *                 upgrade/rollback will overwrite it.
+ *   unshipped     a local file with no release twin (seat authorship). An
+ *                 upgrade cannot overwrite what it does not ship, so it needs
+ *                 no pin; listed so it is not mistaken for drift.
+ *
+ * Usage: node scripts/maintenance/pin-integrity.mjs [--json] [--root DIR] [--threshold N]
+ *                                                   [--repo DIR] [--upstream REF]
+ *   MAESTRO_PIN_BEHIND_MAX=N   allowed release-only (and upstream-only) lines per
+ *                              pin (default 0: any such line alarms). --threshold wins.
+ *   MAESTRO_SDK_REPO=DIR       SDK source checkout for the upstream comparison;
+ *                              --repo wins. Unset = comparison skipped.
+ * Exit 1 when any pin's release_only OR upstream_only exceeds the threshold;
+ * 0 otherwise.
+ * `diff` is required (macOS and Linux ship it); if it cannot be spawned the
+ * delta falls back to a line-multiset comparison so the check still runs.
+ *
+ * @module scripts/maintenance/pin-integrity
+ */
+import { readFileSync, writeFileSync, statSync, existsSync, readdirSync, mkdtempSync, rmSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, relative, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+/** Roots whose files the unpinned/unshipped walk classifies. */
+export const WALK_ROOTS = Object.freeze(["scripts/daemon", "scripts/collective", "scripts/org", "scripts/session", "lib"]);
+
+/** Paths whose code the daemon holds in memory — "not-loaded" applies only here. */
+const DAEMON_LOADED_RE = /^(scripts\/daemon|scripts\/collective|lib)\//;
+
+function sha(p) { return createHash("sha256").update(readFileSync(p)).digest("hex").slice(0, 16); }
+
+function daemonBoot(root) {
+  try {
+    const h = JSON.parse(readFileSync(join(root, "state", "cadence-bus", "health.json"), "utf8"));
+    const startedAt = h.stats && h.stats.started_at ? new Date(h.stats.started_at) : null;
+    return { pid: h.pid ?? null, startedAt: startedAt && !Number.isNaN(startedAt.getTime()) ? startedAt : null };
+  } catch { return { pid: null, startedAt: null }; }
+}
+
+/** The pinned paths from `<root>/.maestroignore` (blank + `#` lines skipped). */
+export function readPins(root) {
+  const f = join(root, ".maestroignore");
+  if (!existsSync(f)) return [];
+  return readFileSync(f, "utf8").split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+}
+
+function walk(dir, out = []) {
+  if (!existsSync(dir)) return out;
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) { if (e.name !== "node_modules") walk(p, out); }
+    else if (/\.(mjs|js|py|sh)$/.test(e.name)) out.push(p);
+  }
+  return out;
+}
+
+/** Pure-JS fallback: line multiset difference, used only when `diff` cannot spawn. */
+function lineMultisetDelta(vendText, localText) {
+  const count = (t) => { const m = new Map(); for (const l of t.split("\n")) m.set(l, (m.get(l) || 0) + 1); return m; };
+  const a = count(vendText), b = count(localText);
+  let ro = 0, lo = 0;
+  for (const [l, n] of a) ro += Math.max(0, n - (b.get(l) || 0));
+  for (const [l, n] of b) lo += Math.max(0, n - (a.get(l) || 0));
+  return { release_only: ro, local_only: lo };
+}
+
+/** Lines only in `a` / only in `b`, by `diff` (multiset fallback when it cannot spawn). */
+function countDiff(a, b) {
+  let ao = 0, bo = 0;
+  const d = spawnSync("diff", [a, b], { encoding: "utf8" });
+  if (!d.error && typeof d.stdout === "string") {
+    for (const ln of d.stdout.split("\n")) { if (ln.startsWith("< ")) ao++; else if (ln.startsWith("> ")) bo++; }
+  } else {
+    ({ release_only: ao, local_only: bo } = lineMultisetDelta(readFileSync(a, "utf8"), readFileSync(b, "utf8")));
+  }
+  return { a_only: ao, b_only: bo };
+}
+
+/** `{release_only, local_only, behind}` between the vendored and local copies. */
+export function measureDelta(vend, local) {
+  const { a_only: ro, b_only: lo } = countDiff(vend, local);
+  return { release_only: ro, local_only: lo, behind: ro > 0 };
+}
+
+/** `{upstream_only, local_only}` between the file at the upstream ref and the local copy. */
+export function measureUpstreamDelta(upstreamCopy, local) {
+  const { a_only: uo, b_only: lo } = countDiff(upstreamCopy, local);
+  return { upstream_only: uo, local_only: lo };
+}
+
+/** Default upstream ref for the third reference. */
+export const DEFAULT_UPSTREAM_REF = "origin/main";
+
+/**
+ * Resolve the SDK source checkout: explicit option → MAESTRO_SDK_REPO → null.
+ * @param {string|undefined} explicit
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null} absolute path, or null when nothing names a checkout
+ */
+export function resolveUpstreamRepo(explicit, env = process.env) {
+  const cand = explicit !== undefined && explicit !== null && explicit !== "" ? explicit : env.MAESTRO_SDK_REPO;
+  return cand && String(cand).trim() ? resolve(String(cand).trim()) : null;
+}
+
+function git(repo, args, encoding = "utf8") {
+  return spawnSync("git", ["-C", repo, ...args], { encoding, maxBuffer: 64 * 1024 * 1024 });
+}
+
+/** First non-empty stderr line, for notices and per-file reasons. */
+function firstLine(r) {
+  const t = r && r.error ? r.error.message : String((r && r.stderr) || "");
+  return (t.split("\n").map((l) => l.trim()).find(Boolean) || "").slice(0, 200);
+}
+
+/**
+ * Open the upstream reference: `{enabled, ref, repo, commit, notice}`. Never
+ * throws — a missing checkout, a non-repo or an unresolvable ref returns
+ * `enabled:false` with a one-line `notice`.
+ * @param {string|null} repo   from resolveUpstreamRepo()
+ * @param {string} ref
+ */
+export function openUpstream(repo, ref = DEFAULT_UPSTREAM_REF) {
+  const base = { enabled: false, ref, repo, commit: null, notice: null };
+  if (!repo) return { ...base, notice: "upstream comparison skipped: no --repo and MAESTRO_SDK_REPO unset" };
+  if (!existsSync(repo)) return { ...base, notice: `upstream comparison skipped: ${repo} does not exist` };
+  let rp;
+  try { rp = git(repo, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]); } catch (e) { rp = { error: e }; }
+  if (rp.error) return { ...base, notice: `upstream comparison skipped: git could not run in ${repo} (${firstLine(rp)})` };
+  if (rp.status !== 0 || !String(rp.stdout).trim()) return { ...base, notice: `upstream comparison skipped: ${ref} does not resolve in ${repo}${firstLine(rp) ? " (" + firstLine(rp) + ")" : ""}` };
+  return { ...base, enabled: true, commit: String(rp.stdout).trim() };
+}
+
+/**
+ * `git show <ref>:<path>` as a Buffer, or `{error}` when the path is absent at
+ * the ref (or git fails) — fail-open per file.
+ */
+function upstreamBlob(repo, ref, rel) {
+  let r;
+  try { r = git(repo, ["show", `${ref}:${rel}`], "buffer"); } catch (e) { r = { error: e }; }
+  if (r.error || r.status !== 0) return { error: firstLine({ ...r, stderr: r.stderr ? r.stderr.toString() : "" }) || `not at ${ref}` };
+  return { buf: r.stdout };
+}
+
+/**
+ * Resolve the behind threshold: explicit option → MAESTRO_PIN_BEHIND_MAX → 0.
+ * @param {number|string|undefined} explicit
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function resolveThreshold(explicit, env = process.env) {
+  const cand = explicit !== undefined && explicit !== null && explicit !== "" ? explicit : env.MAESTRO_PIN_BEHIND_MAX;
+  const n = Number(cand);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+/**
+ * Build the report for an agent root.
+ * @param {string} root      the agent repo
+ * @param {object} [o]
+ * @param {number} [o.threshold]   allowed release-only / upstream-only lines per pin (default env/0)
+ * @param {string} [o.repo]        SDK source checkout for the upstream reference (default env MAESTRO_SDK_REPO)
+ * @param {string} [o.upstream]    git ref in that checkout (default origin/main)
+ * @param {Date}   [o.now]         report timestamp (test seam)
+ * @returns {object} report with `.summary`, `.pinned`, `.unpinned_divergences`,
+ *          `.unshipped_local`, `.threshold`, `.over_threshold[]`, `.upstream`,
+ *          `.over_threshold_main[]`, `.exitCode`
+ */
+export function pinIntegrity(root, o = {}) {
+  const threshold = resolveThreshold(o.threshold);
+  const vendored = join(root, "node_modules", "@cohortapp", "agent-sdk");
+  const boot = daemonBoot(root);
+  const pins = readPins(root);
+  const pinSet = new Set(pins);
+  const upstream = openUpstream(resolveUpstreamRepo(o.repo), o.upstream || DEFAULT_UPSTREAM_REF);
+  const scratch = upstream.enabled ? mkdtempSync(join(tmpdir(), "pin-integrity-upstream-")) : null;
+  const rows = [];
+  try {
+    for (const rel of pins) {
+      const local = join(root, rel), vend = join(vendored, rel);
+      if (!existsSync(local)) { rows.push({ path: rel, state: "missing-local" }); continue; }
+      const localSha = sha(local);
+      const row = { path: rel };
+      if (!existsSync(vend)) { Object.assign(row, { state: "no-vendored", local_sha: localSha }); }
+      else {
+        const vendSha = sha(vend);
+        const same = localSha === vendSha;
+        const mtime = statSync(local).mtime;
+        let state = same ? "identical" : "ok";
+        if (!same && boot.startedAt && mtime > boot.startedAt && DAEMON_LOADED_RE.test(rel) && !/\.test\.mjs$/.test(rel)) state = "not-loaded";
+        const delta = same ? null : measureDelta(vend, local);
+        Object.assign(row, { state, local_sha: localSha, vendored_sha: vendSha, mtime: mtime.toISOString(), delta });
+      }
+      if (upstream.enabled) Object.assign(row, upstreamRow(upstream, scratch, rel, local, localSha, threshold));
+      rows.push(row);
+    }
+  } finally { if (scratch) rmSync(scratch, { recursive: true, force: true }); }
+
+  const unpinned = [];
+  const unshipped = [];
+  for (const sub of WALK_ROOTS) {
+    for (const p of walk(join(root, sub))) {
+      const rel = relative(root, p);
+      if (pinSet.has(rel)) continue;
+      const vend = join(vendored, rel);
+      if (!existsSync(vend)) { unshipped.push({ path: rel }); continue; }
+      if (sha(p) !== sha(vend)) unpinned.push({ path: rel, mtime: statSync(p).mtime.toISOString() });
+    }
+  }
+
+  const over = rows.filter((r) => r.delta && r.delta.release_only > threshold).map((r) => ({ path: r.path, release_only: r.delta.release_only }));
+  const overMain = rows.filter((r) => r.upstream_state === "behind-main").map((r) => ({ path: r.path, upstream_only: r.delta_upstream.upstream_only }));
+  const summary = {
+    identical: rows.filter((r) => r.state === "identical").length,
+    not_loaded: rows.filter((r) => r.state === "not-loaded").length,
+    ok: rows.filter((r) => r.state === "ok").length,
+    unpinned: unpinned.length,
+    unshipped: unshipped.length,
+    behind: rows.filter((r) => r.delta && r.delta.behind).length,
+    release_only_lines: rows.reduce((n, r) => n + (r.delta ? r.delta.release_only : 0), 0),
+  };
+  if (upstream.enabled) {
+    summary.behind_main = overMain.length;
+    summary.upstream_only_lines = rows.reduce((n, r) => n + (r.delta_upstream ? r.delta_upstream.upstream_only : 0), 0);
+  }
+  return {
+    checked_at: (o.now || new Date()).toISOString(),
+    daemon: { pid: boot.pid, started_at: boot.startedAt ? boot.startedAt.toISOString() : null },
+    threshold,
+    pinned: rows,
+    unpinned_divergences: unpinned,
+    unshipped_local: unshipped,
+    over_threshold: over,
+    upstream,
+    over_threshold_main: overMain,
+    summary,
+    exitCode: over.length || overMain.length ? 1 : 0,
+  };
+}
+
+/**
+ * The upstream columns for one pin: `upstream_state`, `upstream_sha`,
+ * `delta_upstream {upstream_only, local_only}` (null when identical), and
+ * `upstream_reason` when the path is not at the ref.
+ */
+function upstreamRow(upstream, scratch, rel, local, localSha, threshold) {
+  const blob = upstreamBlob(upstream.repo, upstream.ref, rel);
+  if (blob.error) return { upstream_state: "no-upstream", upstream_reason: blob.error, upstream_sha: null, delta_upstream: null };
+  const upSha = createHash("sha256").update(blob.buf).digest("hex").slice(0, 16);
+  if (upSha === localSha) return { upstream_state: "identical", upstream_sha: upSha, delta_upstream: null };
+  const tmp = join(scratch, upSha + "-" + rel.replace(/[^A-Za-z0-9._-]/g, "_"));
+  writeFileSync(tmp, blob.buf);
+  const delta_upstream = measureUpstreamDelta(tmp, local);
+  const upstream_state = delta_upstream.upstream_only > threshold ? "behind-main" : "ok";
+  return { upstream_state, upstream_sha: upSha, delta_upstream };
+}
+
+/** The one-line summary, in the shape the wrap log and doctor grep for. */
+export function summaryLine(report) {
+  const s = report.summary;
+  const base = `summary: identical(fix lost)=${s.identical} not-loaded=${s.not_loaded} ok=${s.ok} unpinned=${s.unpinned} unshipped=${s.unshipped} behind=${s.behind} (release-only lines ${s.release_only_lines})`;
+  if (report.upstream && report.upstream.enabled) return `${base} behind_main=${s.behind_main} (upstream-only lines ${s.upstream_only_lines})`;
+  return base;
+}
+
+/** The upstream column for one pinned row, e.g. ` / behind-main (+37 upstream-only lines)`; empty when the comparison did not run. */
+function formatUpstreamCol(r) {
+  if (!r.upstream_state) return "";
+  if (r.upstream_state === "no-upstream") return `  / no-upstream (${r.upstream_reason})`;
+  if (r.upstream_state === "identical") return "  / identical (upstream)";
+  const d = r.delta_upstream;
+  return `  / ${r.upstream_state} (+${d.upstream_only} upstream-only lines, ${d.local_only} local-only)`;
+}
+
+/** Human-readable report text (non-JSON mode). */
+export function formatReport(report) {
+  const out = [];
+  const up = report.upstream;
+  out.push(`pin-integrity ${report.checked_at}  daemon pid ${report.daemon.pid} up since ${report.daemon.started_at}  threshold ${report.threshold}`);
+  if (up && up.enabled) out.push(`  upstream reference: ${up.ref} @ ${up.commit.slice(0, 12)} (${up.repo}) — each pin reads "<vendored state> / <upstream state>"`);
+  else if (up && up.notice) out.push(`  ${up.notice}`);
+  for (const r of report.pinned) {
+    out.push(`  ${r.state.padEnd(13)} ${r.path}${r.mtime ? "  (mtime " + r.mtime + ")" : ""}${r.delta ? `  [local-only ${r.delta.local_only} / release-only ${r.delta.release_only}${r.delta.behind ? " BEHIND" : ""}]` : ""}${formatUpstreamCol(r)}`);
+  }
+  if (report.unpinned_divergences.length) {
+    out.push("  UNPINNED local divergences (an upgrade/rollback will overwrite these):");
+    for (const u of report.unpinned_divergences) out.push(`    ${u.path}  (mtime ${u.mtime})`);
+  }
+  if (report.unshipped_local.length) {
+    out.push("  unshipped local files (no release twin; nothing to pin):");
+    for (const u of report.unshipped_local) out.push(`    ${u.path}`);
+  }
+  out.push(`  ${summaryLine(report)}`);
+  if (report.over_threshold.length) {
+    out.push(`  BEHIND past threshold (${report.threshold} release-only line(s) allowed per pin):`);
+    for (const p of report.over_threshold) out.push(`    ${p.path}  release-only ${p.release_only}`);
+  }
+  if (report.over_threshold_main && report.over_threshold_main.length) {
+    out.push(`  BEHIND-MAIN past threshold (${report.threshold} upstream-only line(s) allowed per pin; fixes already on ${up.ref} that no upgrade will deliver until released):`);
+    for (const p of report.over_threshold_main) out.push(`    ${p.path}  upstream-only ${p.upstream_only}`);
+  }
+  return out.join("\n");
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  const flagVal = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+  const root = flagVal("--root") ? resolve(flagVal("--root")) : resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+  const report = pinIntegrity(root, { threshold: flagVal("--threshold"), repo: flagVal("--repo"), upstream: flagVal("--upstream") });
+  if (args.includes("--json")) console.log(JSON.stringify(report));
+  else console.log(formatReport(report));
+  process.exit(report.exitCode);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv);

package/scripts/poll-slack-events.sh

@@ -1,24 +1,56 @@
 #!/bin/bash
-# poll-slack-events.sh — Fetch buffered events from Railway relay server
-# Writes events to state/inbox/slack/ for the monitoring loop to process
-# Run via cron every 5-10 seconds for near-instant response
-set -e
+# poll-slack-events.sh — Fetch buffered events from the Railway-hosted webhook
+# relay and write them to state/inbox/slack/ for the monitoring loop to process.
+# Run by ai.maestro.<first>-poll-relay every 5 s (scripts/local-triggers/
+# generate-plists.sh §2). See docs/guides/webhook-relay-setup.md.
+#
+# A seat with NO relay configured exits 0 and does nothing. This script used to
+# default SLACK_EVENTS_RELAY_URL to a hostname that has since gone away, and to
+# run under `set -e` with a JSON parse of whatever came back — so on every seat
+# without Slack it fetched a 404 page, failed to parse it, and exited 1, every
+# five seconds, for weeks (one seat: 102,568 runs, `launchctl list` showing a
+# standing "1"). Nothing was wrong on those seats; the job simply had no relay
+# to poll. Configuration is the gate: no URL, no work, clean exit.
+#
+# The relay URL comes from the environment or from <agent>/.env
+# (SLACK_EVENTS_RELAY_URL). No hardcoded default: a URL that nobody set is not
+# a URL to poll.
+set -u
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-AGENT_REPO_DIR="${AGENT_DIR:-$(cd "$SCRIPT_DIR/.." && pwd)}"
-EVENTS_URL="${SLACK_EVENTS_RELAY_URL:-https://slack-events-server-production.up.railway.app/events}"
+AGENT_REPO_DIR="${AGENT_DIR:-${AGENT_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}}"
 INBOX_DIR="$AGENT_REPO_DIR/state/inbox/slack"
+
+# .env is the seat's configuration; launchd hands this script a bare env.
+EVENTS_URL="${SLACK_EVENTS_RELAY_URL:-}"
+if [ -z "$EVENTS_URL" ] && [ -r "$AGENT_REPO_DIR/.env" ]; then
+  EVENTS_URL="$(grep -E '^SLACK_EVENTS_RELAY_URL=' "$AGENT_REPO_DIR/.env" 2>/dev/null | tail -1 | cut -d= -f2- | tr -d "\"'[:space:]")"
+fi
+if [ -z "$EVENTS_URL" ]; then
+  # Not configured on this seat: nothing to poll, and nothing to say every 5 s.
+  exit 0
+fi
+
 mkdir -p "$INBOX_DIR"
 
-RESPONSE=$(curl -s --max-time 5 "$EVENTS_URL" 2>/dev/null)
-COUNT=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('count',0))" 2>/dev/null)
+# A relay that is down or answers with something other than JSON is a transient
+# fact about the relay, not a failure of this seat: log one line, exit 0, and
+# the next tick tries again. Under `set -e` a bad body used to be exit 1.
+RESPONSE="$(curl -s --fail --max-time 5 "$EVENTS_URL" 2>/dev/null)" || {
+  echo "[poll-slack-events $(date -u +%H:%M:%SZ)] relay unreachable or non-2xx: $EVENTS_URL" >&2
+  exit 0
+}
+COUNT="$(printf '%s' "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('count',0))" 2>/dev/null)" || {
+  echo "[poll-slack-events $(date -u +%H:%M:%SZ)] relay answered with a body that is not JSON: $EVENTS_URL" >&2
+  exit 0
+}
 
 if [ "$COUNT" = "0" ] || [ -z "$COUNT" ]; then
   exit 0
 fi
 
 # Write each event to a separate file in the inbox
-echo "$RESPONSE" | python3 -c "
+printf '%s' "$RESPONSE" | python3 -c "
 import sys, json, os
 
 data = json.load(sys.stdin)

package/scripts/poller/slack-socket-mode.mjs

@@ -423,6 +423,20 @@ export function eventToInboxItem(envelope, { ownSlackId, principalSlackId, agent
  * Returns `{ url }` on success or `{ error }` on failure. The URL is
  * single-use and expires quickly — call this every time we open a socket.
  */
+/**
+ * What the seat's SLACK_APP_LEVEL_TOKEN says about whether Socket Mode is
+ * meant to run here. "absent" is a seat without Slack (a clean no-op, exit
+ * 0); "malformed" is a configured token that cannot work (EX_CONFIG, 78);
+ * "ok" is an xapp- token.
+ * @param {string|undefined} token
+ * @returns {"absent"|"malformed"|"ok"}
+ */
+export function classifyAppToken(token) {
+  const t = typeof token === "string" ? token.trim() : "";
+  if (!t) return "absent";
+  return t.startsWith("xapp-") ? "ok" : "malformed";
+}
+
 export async function openSocketConnection({ appToken, fetchFn = fetch }) {
   if (!appToken) {
     return { error: "missing-app-token" };
@@ -883,10 +897,21 @@ async function main() {
   loadEnvFromFile(agentRoot);
 
   const appToken = process.env.SLACK_APP_LEVEL_TOKEN || "";
-  if (!appToken || !appToken.startsWith("xapp-")) {
-    error(agentRoot, "SLACK_APP_LEVEL_TOKEN missing or malformed (must start with xapp-). " +
+  const tokenState = classifyAppToken(appToken);
+  if (tokenState === "absent") {
+    // Not an error: a seat that does not use Slack has no app-level token and
+    // never will. Exiting non-zero here put every such seat into a KeepAlive
+    // crash loop — one seat logged 36,000 EX_CONFIG restarts over four weeks,
+    // one line each, and `launchctl list` showed a standing "78" beside a job
+    // that had nothing to do. A CLEAN exit is what the plist's KeepAlive
+    // {SuccessfulExit:false} does not restart: say so once and stop.
+    info(agentRoot, "Socket Mode not configured on this seat (no SLACK_APP_LEVEL_TOKEN in .env) — not starting; run scripts/setup/init-slack-socket-mode.mjs to enable it");
+    process.exit(0);
+  }
+  if (tokenState === "malformed") {
+    error(agentRoot, "SLACK_APP_LEVEL_TOKEN malformed (must start with xapp-). " +
                      "Run: node scripts/setup/init-slack-socket-mode.mjs");
-    process.exit(78); // EX_CONFIG
+    process.exit(78); // EX_CONFIG — a token IS configured and it is wrong: an operator error worth a loud, non-zero exit
   }
 
   const identity = loadAgentIdentity(agentRoot);

package/scripts/session/supervisor.mjs

@@ -42,7 +42,9 @@
  * @module scripts/session/supervisor
  */
 
-import { existsSync as fsExistsSync, readFileSync as fsReadFileSync, mkdirSync as fsMkdirSync, unlinkSync as fsUnlinkSync } from "node:fs";
+import { existsSync as fsExistsSync, readFileSync as fsReadFileSync, mkdirSync as fsMkdirSync, unlinkSync as fsUnlinkSync, writeFileSync as fsWriteFileSync, chmodSync as fsChmodSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { pathToFileURL } from "node:url";
@@ -52,14 +54,23 @@ import { writeJsonAtomic as fsWriteJsonAtomic, writeFileAtomic as fsWriteFileAto
 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 { buildSpawn } from "../../lib/runtime/adapter.mjs";
+import { resolveSeatSpawn } from "../../lib/runtime/seat-engine.mjs";
 import { sessionPermissionArgs, MAIN_SESSION_SOURCE } from "../../lib/session-permissions.mjs";
 import { loadSessionConfig, sessionPaths } from "../../lib/session/config.mjs";
+import { noticeHonouredBy } from "../../lib/session/upgrade-notice.mjs";
+import { SDK_PACKAGE } from "../daemon/sdk-version.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";
+import { detectMux, chooseMux, buildMuxCommands, parseScreenList, parseExitFile, renderEnvFile } from "../../lib/session/launch-args.mjs";
+
+/** Write a private (0600) file that must not already exist. The engine env file carries the seat token. */
+export function writePrivateFile(path, text) {
+  fsWriteFileSync(path, text, { mode: 0o600, flag: "wx" });
+  fsChmodSync(path, 0o600); // a umask cannot widen it, but be explicit
+}
 
 /** Another supervisor holds the lock (or the front door is not the session). Clean. */
 export const EXIT_ANOTHER_HOLDS_LOCK = 0;
@@ -162,6 +173,10 @@ export async function runSupervisor(deps = {}) {
     permissionArgs: deps.permissionArgs || null,
     pollMs: deps.pollMs ?? DEFAULT_POLL_MS,
     onSignal: deps.onSignal || installSignalHandlers,
+    // W4-E1: the seat's engine and its spawn fields (config/agent.json runtime.engine + seat token).
+    seatSpawn: deps.seatSpawn || ((root) => resolveSeatSpawn(root)),
+    writePrivateFile: deps.writePrivateFile || writePrivateFile,
+    envFileId: deps.envFileId || randomUUID,
   };
   const fsDeps = { readFileSync: d.readFileSync, writeJsonAtomic: d.writeJsonAtomic };
   const agentRoot = d.agentRoot;
@@ -243,26 +258,73 @@ export async function runSupervisor(deps = {}) {
       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 });
+  // Binary + argv from the runtime adapter (lib/runtime/adapter.mjs, lane
+  // "main-session"), which delegates the argv contract to launch-args.
+  // W4-E1 (row 5): the seat's engine, resolved once for this launch. A claude
+  // seat adds no fields (unchanged); an engine-cohort seat launches
+  // `cli.mjs session` with the seat token. Read on every launch, so flipping
+  // runtime.engine back to "claude" restores claude at the next relaunch.
+  let seat = { engine: "claude", fields: {} };
+  try { seat = (await d.seatSpawn(agentRoot)) || seat; } catch { seat = { engine: "claude", fields: {} }; }
+  const engineCohort = seat.engine === "cohort";
+  const spec = buildSpawn({ lane: "main-session", bin: d.claudeBin || undefined, first, sessionId: record.sessionId, resumeMode: mode, permissions: permissionArgs, env: d.env, ...seat.fields });
+  if (!spec.ok && engineCohort) {
+    // An engine-cohort seat never falls back to claude (it would spend the seat's
+    // Anthropic credential). No seat token yet: back off, then let launchd relaunch.
+    d.log(`engine cohort main session not launched: ${spec.error.message} — backing off ${BACKOFF_MS / 60000} min`);
+    await d.sleep(BACKOFF_MS);
+    return EXIT_RELAUNCH;
+  }
+  // A claude main session cannot fail to build: a failure is a defect.
+  if (!spec.ok) throw new Error(`supervisor: runtime adapter: ${spec.error.message}`);
+  const claudeArgs = spec.argv;
+  // W4-E1: an engine-cohort session takes its env from a 0600 file the session
+  // sources and deletes (launch-args ENGINE_ENV_SCRIPT), never from the mux: a
+  // tmux server that is already running would hand the session its own global
+  // env (no seat token, possibly Claude credentials) instead of ours.
+  const envFile = engineCohort ? join(paths.stateDir, `engine-env-${d.envFileId()}.env`) : null;
+  const cmds = buildMuxCommands({ mux, muxName, cwd: agentRoot, claudeBin: spec.bin, claudeArgs, exitFile: paths.lastExitFile, envFile });
 
   // 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`);
+  //     reports the blocked session instead of nothing at all. The engine has
+  //     no first-run dialogs, so an engine-cohort seat's ~/.claude.json is left alone.
+  if (!engineCohort) {
+    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 */ }
+  // 4c. An upgrade notice asking for a restart onto the version THIS launch
+  //     runs is honoured by this launch: retire it, so `maestro session
+  //     status` stops flagging a hop the session has completed (and a notice
+  //     that is still there means a restart that has not happened). A
+  //     health report ({healthy:false}) is never touched here.
+  {
+    let noticeText = null;
+    try { noticeText = d.readFileSync(paths.upgradeNoticeFile, "utf8"); } catch { noticeText = null; }
+    if (noticeText != null) {
+      let installed = "";
+      try { installed = String(JSON.parse(d.readFileSync(join(agentRoot, "node_modules", SDK_PACKAGE, "package.json"), "utf8")).version || ""); } catch { installed = ""; }
+      const h = noticeHonouredBy(noticeText, installed);
+      if (h.honoured) {
+        try { d.unlinkSync(paths.upgradeNoticeFile); d.log(`upgrade notice ${h.from || "?"} -> ${h.to} honoured: this launch runs ${h.to}; notice retired`); }
+        catch (e) { d.log(`upgrade notice ${h.from || "?"} -> ${h.to} honoured but not retired: ${e && e.message ? e.message : e}`); }
+      } else if (h.to) {
+        d.log(`upgrade notice ${h.from || "?"} -> ${h.to} left in place (${h.reason})`);
+      }
+    }
+  }
   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})`);
+  d.log(`launching ${mux.kind} session ${muxName}: ${engineCohort ? "cohort session" : "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
@@ -279,7 +341,11 @@ export async function runSupervisor(deps = {}) {
     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`);
   });
+  const dropEnvFile = () => { if (envFile) { try { d.unlinkSync(envFile); } catch { /* the session consumed it */ } } };
   try {
+    // The engine's env (seat token, every Claude credential scrubbed) rides the
+    // env file; the mux client itself gets the supervisor's env, as for claude.
+    if (envFile) d.writePrivateFile(envFile, renderEnvFile(spec.env));
     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);
@@ -287,6 +353,7 @@ export async function runSupervisor(deps = {}) {
     launchFailed = true;
     d.log(`${mux.kind} start failed: ${err && err.message ? err.message : err}`);
   }
+  dropEnvFile(); // normally already gone; left only when the session never started
   const endedAt = Number(d.now());
   try { cancelWatchdog(); } catch { /* already fired */ }
   await stopIssued;

package/scripts/spawn-session.sh

@@ -13,6 +13,19 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # alias of it), so honouring the environment first is the correct precedence.
 AGENT_DIR="${AGENT_DIR:-$(dirname "$SCRIPT_DIR")}"
 
+# Retired on engine-cohort seats (W4-E1): this lane runs claude outside the
+# runtime adapter. The guard exits 3 with the reason when runtime.engine is cohort.
+# Fail closed: when the guard cannot run (no node on PATH — launchd's
+# /usr/bin:/bin — or the guard file is missing), config/agent.json is checked
+# here and an engine-cohort seat is refused all the same.
+LEGACY_GUARD="$(dirname "$SCRIPT_DIR")/lib/runtime/legacy-shell-guard.mjs"
+if [ -f "$LEGACY_GUARD" ] && command -v node >/dev/null 2>&1; then
+    node "$LEGACY_GUARD" spawn-session.sh "$AGENT_DIR" || exit $?
+elif [ -f "$AGENT_DIR/config/agent.json" ] && grep -Eq '"engine"[[:space:]]*:[[:space:]]*"cohort"' "$AGENT_DIR/config/agent.json"; then
+    echo "spawn-session.sh is retired on this seat: runtime.engine is \"cohort\", and this legacy lane runs the claude binary directly, outside the runtime adapter (the engine guard could not run: node or $LEGACY_GUARD is unavailable)." >&2
+    exit 3
+fi
+
 # Real identity for the sub-session prompt. config/agent.env is generated from
 # config/agent.json by scripts/setup/generate-agent-env.mjs on every
 # `maestro upgrade` — it exists precisely so shell scripts can read the SOT.