@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/scripts/setup/configure-macos.test.mjs

@@ -0,0 +1,306 @@
+/**
+ * configure-macos.test.mjs — scripts/setup/configure-macos.sh
+ *
+ * Covers the 2026-09-08 front-door-session changes (design §6 WP-M3):
+ *   - the Terminal.app `ai.maestro.boot-claude-session` job is RETIRED: the
+ *     script unloads + removes it if present and never writes it again;
+ *   - `--tailscale-ssh` advertises Tailscale SSH and turns Remote Login on,
+ *     then prints the tailnet ACL reminder (audit F4: 0/41 peers reachable);
+ *   - `--check` reports both Tailscale SSH and Remote Login.
+ *
+ * The script talks to real macOS tooling (launchctl, tailscale, systemsetup,
+ * pmset, defaults …), so every test runs it with a PATH of STUB binaries that
+ * append their argv to a log file. Nothing here touches the real machine.
+ * Functions are exercised by sourcing the script with
+ * MAESTRO_CONFIGURE_MACOS_NO_MAIN=1 (main() is skipped), the same seam the
+ * script exposes for exactly this purpose.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, rmSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(__dirname, "configure-macos.sh");
+const scriptSrc = readFileSync(SCRIPT, "utf8");
+
+/**
+ * Build a stub-binary directory. Every named stub appends `<name> <argv>` to
+ * `calls.log` and prints `stdoutByName[name]` (if any), exiting 0. `sudo` is
+ * special: it logs then re-execs the rest of its argv so `sudo systemsetup …`
+ * still reaches the systemsetup stub.
+ */
+function makeStubs(dir, names, stdoutByName = {}) {
+  const bin = join(dir, "bin");
+  mkdirSync(bin, { recursive: true });
+  const log = join(dir, "calls.log");
+  // osascript is ALWAYS stubbed: the real one can pop a System Events
+  // permission prompt or edit the developer's Login Items.
+  for (const name of new Set([...names, "osascript"])) {
+    const out = stdoutByName[name] ? `printf '%s\\n' ${JSON.stringify(stdoutByName[name])}\n` : "";
+    const body = name === "sudo"
+      ? `#!/bin/bash\necho "sudo $*" >> "${log}"\n# drop sudo flags (-n, -u user) then exec the real command (a sibling stub)\nwhile [ "$1" = "-n" ] || [ "$1" = "-u" ]; do if [ "$1" = "-u" ]; then shift 2; else shift; fi; done\nexec "$@"\n`
+      : `#!/bin/bash\necho "${name} $*" >> "${log}"\n${out}exit 0\n`;
+    writeFileSync(join(bin, name), body);
+    chmodSync(join(bin, name), 0o755);
+  }
+  return { bin, log };
+}
+
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), "configure-macos-test-"));
+  const home = join(root, "home");
+  mkdirSync(join(home, "Library", "LaunchAgents"), { recursive: true });
+  // The script derives AGENT_DIR from its own location (scripts/setup/../..),
+  // so copy it into a fixture agent dir.
+  const agent = join(root, "agent");
+  mkdirSync(join(agent, "scripts", "setup"), { recursive: true });
+  writeFileSync(join(agent, "scripts", "setup", "configure-macos.sh"), scriptSrc);
+  chmodSync(join(agent, "scripts", "setup", "configure-macos.sh"), 0o755);
+  return { root, home, agent, script: join(agent, "scripts", "setup", "configure-macos.sh") };
+}
+
+function run(fx, stubs, args, extraEnv = {}) {
+  return spawnSync("/bin/bash", [fx.script, ...args], {
+    encoding: "utf8",
+    cwd: fx.agent,
+    env: {
+      HOME: fx.home,
+      // Stubs FIRST so the script can never reach the real launchctl/tailscale.
+      PATH: `${stubs.bin}:/usr/bin:/bin`,
+      TERM: "dumb",
+      ...extraEnv,
+    },
+  });
+}
+
+/** Source the script without running main(), then run `snippet` in that shell. */
+function runFn(fx, stubs, snippet, extraEnv = {}) {
+  return spawnSync("/bin/bash", ["-c", `source "${fx.script}" && ${snippet}`], {
+    encoding: "utf8",
+    cwd: fx.agent,
+    env: {
+      HOME: fx.home,
+      PATH: `${stubs.bin}:/usr/bin:/bin`,
+      MAESTRO_CONFIGURE_MACOS_NO_MAIN: "1",
+      TERM: "dumb",
+      ...extraEnv,
+    },
+  });
+}
+
+const calls = (stubs) => (existsSync(stubs.log) ? readFileSync(stubs.log, "utf8") : "");
+
+// --- static guards on the script source ------------------------------------
+
+test("configure-macos.sh never writes the boot-claude-session plist again", () => {
+  // The Terminal.app boot job (F15: no KeepAlive, no lock, needs a GUI) is
+  // replaced by the launchd `ai.maestro.<first>-session` supervisor job that
+  // generate-plists.sh emits. This script must only ever REMOVE it.
+  assert.ok(!/boot-claude-session\.sh/.test(scriptSrc),
+    "must not reference boot-claude-session.sh at all (the script is retired)");
+  assert.ok(!/<string>\$\{BOOT_SCRIPT\}<\/string>/.test(scriptSrc),
+    "the boot-claude-session plist heredoc must be gone");
+  assert.ok(/retire_boot_claude_session\(\)/.test(scriptSrc), "a retire function must exist");
+});
+
+test("configure-macos.sh exposes a source-only seam and documents --tailscale-ssh", () => {
+  assert.ok(scriptSrc.includes("MAESTRO_CONFIGURE_MACOS_NO_MAIN"), "sourcing seam missing");
+  assert.ok(/--tailscale-ssh/.test(scriptSrc), "--tailscale-ssh flag missing");
+  assert.match(scriptSrc, /tailscale set --ssh/, "must advertise SSH via `tailscale set --ssh`");
+  assert.match(scriptSrc, /systemsetup -setremotelogin on/, "must turn Remote Login on");
+});
+
+// --- retire the legacy boot session job -------------------------------------
+
+test("retire_boot_claude_session unloads and removes a present legacy plist", () => {
+  const fx = fixture();
+  const stubs = makeStubs(fx.root, ["launchctl"]);
+  const plist = join(fx.home, "Library", "LaunchAgents", "ai.maestro.boot-claude-session.plist");
+  writeFileSync(plist, "<plist/>");
+  try {
+    const r = runFn(fx, stubs, "retire_boot_claude_session");
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    assert.ok(!existsSync(plist), "legacy plist must be removed");
+    const c = calls(stubs);
+    assert.match(c, /launchctl (unload|bootout) .*boot-claude-session/, `expected an unload; calls:\n${c}`);
+    assert.match(r.stdout, /boot-claude-session/);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("retire_boot_claude_session is a no-op when the legacy plist is absent (idempotent)", () => {
+  const fx = fixture();
+  const stubs = makeStubs(fx.root, ["launchctl"]);
+  try {
+    const r = runFn(fx, stubs, "retire_boot_claude_session");
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    // Second run identical.
+    const r2 = runFn(fx, stubs, "retire_boot_claude_session");
+    assert.equal(r2.status, 0, r2.stderr + r2.stdout);
+    assert.ok(!existsSync(join(fx.home, "Library", "LaunchAgents", "ai.maestro.boot-claude-session.plist")));
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+// --- --tailscale-ssh ---------------------------------------------------------
+
+test("--tailscale-ssh advertises SSH, enables Remote Login and prints the ACL reminder", () => {
+  const fx = fixture();
+  const stubs = makeStubs(fx.root, ["tailscale", "sudo", "systemsetup", "launchctl"]);
+  try {
+    const r = run(fx, stubs, ["--tailscale-ssh"]);
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    const c = calls(stubs);
+    assert.match(c, /^tailscale set --ssh$/m, `expected tailscale set --ssh; calls:\n${c}`);
+    assert.match(c, /^sudo (-n )?systemsetup -setremotelogin on$/m, `expected sudo systemsetup -setremotelogin on; calls:\n${c}`);
+    assert.match(c, /^systemsetup -setremotelogin on$/m, "sudo must pass through to systemsetup");
+    // The ACL reminder: SSH is only reachable once the tailnet ACL grants it.
+    assert.match(r.stdout, /ACL/i, "must print the tailnet ACL reminder");
+    assert.match(r.stdout, /"ssh"/, "the reminder should show the ACL `ssh` rule shape");
+    assert.match(r.stdout, /login\.tailscale\.com\/admin\/acls|admin\/acls/, "the reminder should point at the ACL editor");
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("--tailscale-ssh fails clearly when the tailscale CLI is absent", () => {
+  const fx = fixture();
+  const stubs = makeStubs(fx.root, ["sudo", "systemsetup", "launchctl"]);
+  try {
+    const r = run(fx, stubs, ["--tailscale-ssh"], { MAESTRO_TAILSCALE_BIN: "/nonexistent/tailscale" });
+    assert.notEqual(r.status, 0, "must exit non-zero without tailscale");
+    assert.match(r.stdout + r.stderr, /tailscale/i);
+    const c = calls(stubs);
+    assert.ok(!/setremotelogin/.test(c), "must not touch Remote Login when tailscale is missing");
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+// --- --check reports both ----------------------------------------------------
+
+test("--check reports Tailscale SSH and Remote Login state", () => {
+  const fx = fixture();
+  const stubs = makeStubs(
+    fx.root,
+    ["tailscale", "sudo", "systemsetup", "launchctl", "pmset", "defaults", "pgrep", "curl", "fdesetup", "sysadminctl"],
+    {
+      tailscale: '{"RunSSH": true}',
+      systemsetup: "Remote Login: On",
+      launchctl: "-\t0\tai.maestro.ivy-session",
+    },
+  );
+  try {
+    const r = run(fx, stubs, ["--check"]);
+    // verify_all returns the issue count; other checks (Parsec etc.) will
+    // legitimately fail under stubs, so only the report lines matter here.
+    assert.match(r.stdout, /Tailscale SSH: (on|advertised)/i, `stdout:\n${r.stdout}`);
+    assert.match(r.stdout, /Remote Login: on/i, `stdout:\n${r.stdout}`);
+    assert.match(r.stdout, /session/i, "the check should mention the front-door session job");
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("--check flags Tailscale SSH off and Remote Login off", () => {
+  const fx = fixture();
+  const stubs = makeStubs(
+    fx.root,
+    ["tailscale", "sudo", "systemsetup", "launchctl", "pmset", "defaults", "pgrep", "curl", "fdesetup", "sysadminctl"],
+    { tailscale: '{"RunSSH": false}', systemsetup: "Remote Login: Off" },
+  );
+  try {
+    const r = run(fx, stubs, ["--check"]);
+    assert.match(r.stdout, /Tailscale SSH: off/i, `stdout:\n${r.stdout}`);
+    assert.match(r.stdout, /Remote Login: off/i, `stdout:\n${r.stdout}`);
+    assert.match(r.stdout, /--tailscale-ssh/, "must point the operator at the fix");
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+// --- Tailscale variant (review: F4 on the GUI app) ---------------------------
+//
+// The Tailscale SSH server exists only in the open-source `tailscaled` variant.
+// The fleet runs Tailscale.app (GUI), whose /usr/local/bin/tailscale is a
+// 68-byte shim onto /Applications/Tailscale.app/Contents/MacOS/tailscale and
+// whose daemon cannot honour RunSSH. `--tailscale-ssh` must say so and print
+// the real remedy instead of `tailscale up --ssh`.
+
+function guiShim(fx) {
+  // Same shape as the real shim: a two-line sh script naming Tailscale.app.
+  const shim = join(fx.root, "gui-tailscale");
+  writeFileSync(shim, '#!/bin/sh\n/Applications/Tailscale.app/Contents/MacOS/tailscale "$@"\n');
+  chmodSync(shim, 0o755);
+  return shim;
+}
+
+test("tailscale_variant: GUI shim / Tailscale.app path → gui; tailscaled on PATH → open-source; else unknown", () => {
+  const fx = fixture();
+  const stubs = makeStubs(fx.root, ["tailscale", "launchctl"]);
+  try {
+    const shim = guiShim(fx);
+    assert.equal(runFn(fx, stubs, `tailscale_variant "${shim}"`).stdout.trim(), "gui");
+    assert.equal(runFn(fx, stubs, 'tailscale_variant "/Applications/Tailscale.app/Contents/MacOS/Tailscale"').stdout.trim(), "gui");
+    assert.equal(runFn(fx, stubs, `tailscale_variant "${join(stubs.bin, "tailscale")}"`).stdout.trim(), "unknown");
+    // With a tailscaled next to it, the CLI is the open-source variant.
+    writeFileSync(join(stubs.bin, "tailscaled"), "#!/bin/bash\nexit 0\n"); chmodSync(join(stubs.bin, "tailscaled"), 0o755);
+    assert.equal(runFn(fx, stubs, `tailscale_variant "${join(stubs.bin, "tailscale")}"`).stdout.trim(), "open-source");
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("--tailscale-ssh on the GUI app: no `tailscale set --ssh`, the real remedy is printed, Remote Login is still enabled", () => {
+  const fx = fixture();
+  const stubs = makeStubs(fx.root, ["tailscale", "sudo", "systemsetup", "launchctl"], { tailscale: "100.95.116.68" });
+  try {
+    const r = run(fx, stubs, ["--tailscale-ssh"], { MAESTRO_TAILSCALE_BIN: guiShim(fx) });
+    const c = calls(stubs);
+    assert.ok(!/tailscale (set|up) --ssh/.test(c), `must not try to enable SSH on the GUI daemon; calls:\n${c}`);
+    assert.match(r.stdout, /GUI|Tailscale\.app/i, "must name the variant");
+    assert.match(r.stdout, /brew install tailscale/, "must print the open-source remedy");
+    assert.match(r.stdout, /tailscaled/, "must name the daemon that carries the SSH server");
+    assert.match(r.stdout, /Remote Login|ssh .*@100\.95\.116\.68/, "must offer the sshd-over-tailnet-IP fallback");
+    assert.ok(!/is the node up and signed in/.test(r.stdout), "the misleading 'is the node up? try tailscale up --ssh' hint must be gone");
+    assert.match(c, /^systemsetup -setremotelogin on$/m, "Remote Login is the fallback access path and must still be enabled");
+    assert.equal(r.status, 0, "an honest limitation is not a script failure");
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("--check on the GUI app reports Tailscale SSH as unavailable (not a fail-forever 'off') when Remote Login is on", () => {
+  const fx = fixture();
+  const stubs = makeStubs(
+    fx.root,
+    ["tailscale", "sudo", "systemsetup", "launchctl", "pmset", "defaults", "pgrep", "curl", "fdesetup", "sysadminctl"],
+    { tailscale: '{"RunSSH": false}', systemsetup: "Remote Login: On" },
+  );
+  try {
+    const r = run(fx, stubs, ["--check"], { MAESTRO_TAILSCALE_BIN: guiShim(fx) });
+    assert.match(r.stdout, /Tailscale SSH: unavailable/i, `stdout:\n${r.stdout}`);
+    assert.match(r.stdout, /brew install tailscale/, "the check must carry the real remedy too");
+    assert.ok(!/Tailscale SSH: off/.test(r.stdout));
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+// --- --check under sudo: launchctl must look in the user's gui domain ---------
+
+test("gui_launchctl_list uses the caller's domain as a user and `launchctl asuser <uid>` under sudo", () => {
+  const fx = fixture();
+  const stubs = makeStubs(fx.root, ["launchctl"], { launchctl: "-\t0\tai.maestro.ivy-session" });
+  try {
+    // Not root: plain `launchctl list`.
+    const asUser = runFn(fx, stubs, "gui_launchctl_list");
+    assert.match(asUser.stdout, /ai\.maestro\.ivy-session/);
+    assert.match(calls(stubs), /^launchctl list$/m);
+    rmSync(stubs.log, { force: true });
+    // Root via sudo: `id -u` → 0, `id -u <SUDO_USER>` → 501. Stub `id` so the
+    // test never needs real root.
+    writeFileSync(join(stubs.bin, "id"), '#!/bin/bash\nif [ "$1" = "-u" ] && [ -n "$2" ]; then echo 501; else echo 0; fi\n');
+    chmodSync(join(stubs.bin, "id"), 0o755);
+    const asRoot = runFn(fx, stubs, "gui_launchctl_list", { SUDO_USER: "ivy" });
+    assert.match(asRoot.stdout, /ai\.maestro\.ivy-session/);
+    assert.match(calls(stubs), /^launchctl asuser 501 launchctl list$/m, `calls:\n${calls(stubs)}`);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("--check probes the session and daemon jobs through gui_launchctl_list (never a bare `launchctl list`)", () => {
+  const verify = scriptSrc.slice(scriptSrc.indexOf("verify_all()"), scriptSrc.indexOf("main()"));
+  assert.ok(!/(^|[^_])launchctl list/m.test(verify.replace(/gui_launchctl_list/g, "")),
+    "verify_all must go through gui_launchctl_list so `sudo … --check` sees gui/<uid> jobs");
+  const status = scriptSrc.slice(scriptSrc.indexOf("show_status()"), scriptSrc.indexOf("verify_all()"));
+  assert.ok(!/(^|[^_])launchctl list/m.test(status.replace(/gui_launchctl_list/g, "")), "same for show_status");
+});

package/scripts/setup/init-agent.sh

@@ -114,6 +114,67 @@ else
     ok "jq $(jq --version 2>/dev/null)"
 fi
 
+# --- BEGIN maestro global-sdk check (kept testable; do not edit markers) ---
+# Front-door session prerequisites (design §3.7 / audit F17): every Claude Code
+# session on this machine — not just the daemon's children — must find
+# `maestro` and `cohort-mcp` on PATH, so the SDK is installed GLOBALLY and kept
+# at @latest. MAESTRO_SKIP_GLOBAL_INSTALL=1 verifies only (tests, air-gapped
+# seats). A failed install is a warning: the agent-local copy still works.
+# init-agent.test.mjs extracts and exercises this exact block.
+SDK_PKG="@cohortapp/agent-sdk"
+SDK_GLOBAL="$(npm ls -g "$SDK_PKG" --depth=0 2>/dev/null | grep -o "$SDK_PKG@[0-9][^[:space:]]*" | head -1 || true)"
+SDK_GLOBAL_VER="${SDK_GLOBAL#*@*@}"
+SDK_WANT_INSTALL=""
+if [ -z "$SDK_GLOBAL" ]; then
+    SDK_WANT_INSTALL="missing"
+else
+    # Compare against npm latest; a failed `npm view` (offline) means "keep it".
+    # Bounded: an offline seat must not sit in npm's default retry/backoff for minutes.
+    SDK_LATEST="$(npm view "$SDK_PKG" version --fetch-timeout=15000 --fetch-retries=1 2>/dev/null || true)"
+    if [ -n "$SDK_LATEST" ] && [ "$SDK_GLOBAL_VER" != "$SDK_LATEST" ] \
+       && [ "$(printf '%s\n%s\n' "$SDK_GLOBAL_VER" "$SDK_LATEST" | sort -V | tail -1)" = "$SDK_LATEST" ]; then
+        SDK_WANT_INSTALL="outdated ($SDK_GLOBAL_VER < $SDK_LATEST)"
+    fi
+fi
+if [ -z "$SDK_WANT_INSTALL" ]; then
+    ok "Global SDK: $SDK_GLOBAL (current)"
+elif [ "${MAESTRO_SKIP_GLOBAL_INSTALL:-0}" = "1" ]; then
+    warn "Global SDK $SDK_WANT_INSTALL — MAESTRO_SKIP_GLOBAL_INSTALL=1, not running: npm install -g $SDK_PKG@latest"
+else
+    log "Global SDK $SDK_WANT_INSTALL — installing: npm install -g $SDK_PKG@latest"
+    if npm install -g "$SDK_PKG@latest" >/dev/null 2>&1; then
+        ok "Global SDK installed ($SDK_PKG@latest)"
+    else
+        warn "npm install -g $SDK_PKG@latest failed — run it by hand (sudo may be needed for the global prefix)"
+    fi
+fi
+
+# A global install is only useful if its bins resolve from a bare session's
+# PATH (design §3.7(6)): the `cohort` MCP server is registered by the bare name
+# `cohort-mcp`, and the SessionStart primer calls `maestro`. An install into a
+# prefix that launchd/zsh never see (an nvm shim, a custom prefix) passes
+# `npm ls -g` and still ENOENTs at session start.
+SDK_GLOBAL_BIN="$(npm prefix -g 2>/dev/null)/bin"
+for sdk_bin in maestro cohort-mcp; do
+    if command -v "$sdk_bin" >/dev/null 2>&1; then
+        ok "$sdk_bin on PATH: $(command -v "$sdk_bin")"
+    else
+        warn "$sdk_bin not on PATH — add the global npm bin dir ($SDK_GLOBAL_BIN) to PATH in ~/.zprofile so every session finds it"
+    fi
+done
+
+# Terminal multiplexer for the front-door session supervisor: tmux when
+# present, else /usr/bin/screen (ships with macOS). Neither is fatal — the
+# supervisor reports it — but say what to install.
+if command -v tmux >/dev/null 2>&1; then
+    ok "Multiplexer: tmux ($(tmux -V 2>/dev/null))"
+elif [ -x "${MAESTRO_SCREEN_BIN:-/usr/bin/screen}" ]; then
+    ok "Multiplexer: screen (${MAESTRO_SCREEN_BIN:-/usr/bin/screen})"
+else
+    warn "No terminal multiplexer found — the front-door session needs one: brew install tmux"
+fi
+# --- END maestro global-sdk check ---
+
 echo ""
 
 # ---------------------------------------------------------------------------
@@ -253,6 +314,8 @@ DIRS=(
     "state/indexes"
     "state/rag"
     "state/sessions"
+    "state/session"
+    "state/session/handoffs/done"
     "state/slack-responded"
     "state/slack-thread-tracker"
     "state/tmp"
@@ -270,6 +333,7 @@ DIRS=(
     "logs/evolution"
     "logs/huddle"
     "logs/daemon"
+    "logs/session"
     "logs/infra"
     "logs/monitor"
     "logs/phone"
@@ -444,24 +508,65 @@ else
     warn "Plist generator not found at $PLIST_GENERATOR — using existing plists"
 fi
 
+# --- BEGIN maestro launchd install (kept testable; do not edit markers) ---
+# Re-running init-agent must never kill the live front-door session or the
+# daemon: `launchctl unload` SIGTERMs the supervisor, the multiplexer and the
+# interactive session mid-turn (in-flight work and unacked handoffs are lost),
+# and `maestro session status` itself points operators at this command. So
+# the -session and -daemon labels are only REWRITTEN when loaded and loaded
+# only when they are not (the WP-M6 reconcile rule: never bootout). Every
+# other job keeps today's unload + load — its script may have changed and a
+# trigger has no state to lose. init-agent.test.mjs extracts this block.
 if [ -d "$PLIST_DIR" ] && ls "$PLIST_DIR"/*.plist &>/dev/null; then
     for plist in "$PLIST_DIR"/*.plist; do
         PLIST_NAME=$(basename "$plist")
         LABEL=$(basename "$plist" .plist)
         DST="$LAUNCH_AGENTS_DIR/$PLIST_NAME"
 
-        # Unload if already loaded
-        launchctl unload "$DST" 2>/dev/null || true
-
-        # Copy and load
-        cp "$plist" "$DST"
-        launchctl load "$DST"
-        ok "Loaded: $LABEL"
+        case "$LABEL" in
+            *-session)
+                # The supervisor ships with the SDK (WP-M1). A KeepAlive plist
+                # whose program is missing makes launchd retry every 30 s into
+                # logs/session/launchd-stderr.log forever — do not install it.
+                if [ ! -f "$AGENT_DIR/scripts/session/supervisor.sh" ]; then
+                    warn "Skipped $LABEL — scripts/session/supervisor.sh is not present (upgrade the SDK, then re-run)"
+                    continue
+                fi
+                ;;
+        esac
+
+        case "$LABEL" in
+            *-session|*-daemon)
+                cp "$plist" "$DST"
+                chmod 600 "$DST"
+                if launchctl list "$LABEL" >/dev/null 2>&1; then
+                    ok "Updated (kept running): $LABEL — launchd keeps the loaded definition; reload when convenient: launchctl bootout gui/$(id -u)/$LABEL && launchctl bootstrap gui/$(id -u) $DST"
+                else
+                    launchctl load "$DST"
+                    ok "Loaded: $LABEL"
+                fi
+                ;;
+            *)
+                # Unload if already loaded, then copy and load
+                launchctl unload "$DST" 2>/dev/null || true
+                cp "$plist" "$DST"
+                launchctl load "$DST"
+                ok "Loaded: $LABEL"
+                ;;
+        esac
     done
 else
     warn "No plist files found in $PLIST_DIR — skipping launchd setup"
 fi
 
+# Audit F6 follow-through: a poller plist installed by an older install.sh
+# carries SLACK_USER_TOKEN inline at mode 644. Nothing else ever rewrites it,
+# so the migration runs here (and after every autoupdate). No-op when clean.
+if [ -f "$AGENT_DIR/scripts/poller-launchd/migrate.sh" ]; then
+    bash "$AGENT_DIR/scripts/poller-launchd/migrate.sh" || warn "poller plist migration reported a problem (see above)"
+fi
+# --- END maestro launchd install ---
+
 echo ""
 
 # ---------------------------------------------------------------------------