@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/scripts/poller-launchd/install.test.mjs

@@ -0,0 +1,243 @@
+/**
+ * install.test.mjs — scripts/poller-launchd/{install.sh, poller.plist.template,
+ * launchd-poller-wrapper.sh}
+ *
+ * Audit F6: install.sh used to grep SLACK_USER_TOKEN out of .env and `sed` it
+ * into the rendered plist — an unescaped substitution that left the secret in
+ * a 0644 file under ~/Library/LaunchAgents. Now the plist runs
+ * launchd-poller-wrapper.sh, which sources .env (0600) at start and execs
+ * node; the plist carries no secret and is chmod 600 regardless.
+ *
+ * install.sh calls launchctl; the tests stub it. The wrapper resolves node
+ * via MAESTRO_NODE_BIN first so a stub node can prove .env reached the child.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, statSync, copyFileSync, rmSync, realpathSync } 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 installSrc = readFileSync(join(__dirname, "install.sh"), "utf8");
+const templateSrc = readFileSync(join(__dirname, "poller.plist.template"), "utf8");
+
+const SECRET = "xoxp-not-a-real-token-0123456789";
+
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), "poller-launchd-test-"));
+  const agent = join(root, "agent");
+  const home = join(root, "home");
+  const bin = join(root, "bin");
+  const log = join(root, "calls.log");
+  mkdirSync(join(agent, "scripts", "poller-launchd"), { recursive: true });
+  mkdirSync(join(agent, "scripts", "poller"), { recursive: true });
+  mkdirSync(join(agent, "config"), { recursive: true });
+  mkdirSync(join(agent, "logs", "polling"), { recursive: true });
+  mkdirSync(join(home, "Library", "LaunchAgents"), { recursive: true });
+  mkdirSync(bin, { recursive: true });
+  for (const f of ["install.sh", "poller.plist.template", "launchd-poller-wrapper.sh"]) {
+    if (existsSync(join(__dirname, f))) copyFileSync(join(__dirname, f), join(agent, "scripts", "poller-launchd", f));
+  }
+  for (const f of ["install.sh", "launchd-poller-wrapper.sh"]) {
+    const p = join(agent, "scripts", "poller-launchd", f);
+    if (existsSync(p)) chmodSync(p, 0o755);
+  }
+  writeFileSync(join(agent, "config", "agent.json"), JSON.stringify({ firstName: "Ivy" }));
+  // dotenv-shaped, deliberately awkward: an unquoted value with spaces (legal
+  // for Node's dotenv, fatal under `source`), an inline comment, a quoted
+  // value containing `#`, an `export` prefix, and a `$` that must NOT expand.
+  writeFileSync(join(agent, ".env"), [
+    "# agent env",
+    `SLACK_USER_TOKEN=${SECRET}`,
+    "OTHER_VALUE=with spaces   # trailing comment",
+    'QUOTED="a # not a comment"',
+    "export EXPORTED=yes",
+    "LITERAL='$HOME stays literal'",
+    "",
+  ].join("\n"));
+  chmodSync(join(agent, ".env"), 0o600);
+  writeFileSync(join(bin, "launchctl"), `#!/bin/bash\necho "launchctl $*" >> "${log}"\nexit 0\n`);
+  chmodSync(join(bin, "launchctl"), 0o755);
+  return { root, agent, home, bin, log };
+}
+
+const env = (fx, extra = {}) => ({ HOME: fx.home, PATH: `${fx.bin}:/usr/bin:/bin`, ...extra });
+const plistPath = (fx) => join(fx.home, "Library", "LaunchAgents", "ai.maestro.ivy-poller.plist");
+
+// --- static ------------------------------------------------------------------
+
+test("install.sh no longer greps SLACK_USER_TOKEN nor seds XML", () => {
+  assert.ok(!/SLACK_USER_TOKEN/.test(installSrc), "install.sh must not read the Slack token");
+  assert.ok(!/sed -i/.test(installSrc), "install.sh must not edit the rendered plist in place");
+  assert.match(installSrc, /chmod 600/, "the plist must be chmod 600");
+});
+
+test("the template runs the wrapper, not node directly, and carries no env secrets", () => {
+  assert.match(templateSrc, /launchd-poller-wrapper\.sh/);
+  assert.ok(!/SLACK_USER_TOKEN/.test(templateSrc));
+  assert.ok(!/\{\{NODE_BIN\}\}/.test(templateSrc), "node is resolved by the wrapper, not templated into the plist");
+});
+
+// --- install.sh --------------------------------------------------------------
+
+test("install.sh renders a 0600 plist running the wrapper with no secret in it", () => {
+  const fx = fixture();
+  try {
+    const r = spawnSync("/bin/bash", [join(fx.agent, "scripts", "poller-launchd", "install.sh")], { encoding: "utf8", env: env(fx) });
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    const p = plistPath(fx);
+    assert.ok(existsSync(p), "plist must be installed under ~/Library/LaunchAgents");
+    const body = readFileSync(p, "utf8");
+    assert.ok(!body.includes(SECRET), "the Slack token must not be in the plist");
+    assert.ok(!/SLACK_USER_TOKEN/.test(body));
+    assert.match(body, /<string>ai\.maestro\.ivy-poller<\/string>/);
+    assert.match(body, new RegExp(`<string>${fx.agent.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/scripts/poller-launchd/launchd-poller-wrapper\\.sh</string>`));
+    assert.ok(!/\{\{[A-Z_]+\}\}/.test(body), `unresolved template tokens:\n${body}`);
+    assert.equal(statSync(p).mode & 0o777, 0o600, "plist must be 0600");
+    const calls = readFileSync(fx.log, "utf8");
+    assert.match(calls, /launchctl load .*ai\.maestro\.ivy-poller\.plist/);
+    assert.ok(!/SLACK_USER_TOKEN|Injected/.test(r.stdout), "install output must not mention the token");
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("install.sh is idempotent (re-run replaces the plist, still 0600)", () => {
+  const fx = fixture();
+  try {
+    const script = join(fx.agent, "scripts", "poller-launchd", "install.sh");
+    assert.equal(spawnSync("/bin/bash", [script], { encoding: "utf8", env: env(fx) }).status, 0);
+    // Simulate a previously-installed world-readable plist.
+    chmodSync(plistPath(fx), 0o644);
+    assert.equal(spawnSync("/bin/bash", [script], { encoding: "utf8", env: env(fx) }).status, 0);
+    assert.equal(statSync(plistPath(fx)).mode & 0o777, 0o600);
+    assert.match(readFileSync(fx.log, "utf8"), /launchctl unload/);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+// --- wrapper -----------------------------------------------------------------
+
+test("launchd-poller-wrapper.sh sources .env and execs node on scripts/poller/index.mjs", () => {
+  const fx = fixture();
+  try {
+    const wrapper = join(fx.agent, "scripts", "poller-launchd", "launchd-poller-wrapper.sh");
+    assert.ok(existsSync(wrapper), "wrapper must exist");
+    // A stub node that reports what reached it.
+    const stubNode = join(fx.bin, "node");
+    writeFileSync(stubNode, `#!/bin/bash\necho "ARGV=$*"\necho "TOKEN=$SLACK_USER_TOKEN"\necho "OTHER=[$OTHER_VALUE]"\necho "QUOTED=[$QUOTED]"\necho "EXPORTED=[$EXPORTED]"\necho "LITERAL=[$LITERAL]"\necho "AGENT_ROOT=$AGENT_ROOT"\n`);
+    chmodSync(stubNode, 0o755);
+    const r = spawnSync("/bin/bash", [wrapper], { encoding: "utf8", env: env(fx, { MAESTRO_NODE_BIN: stubNode }) });
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    assert.match(r.stdout, new RegExp(`ARGV=.*scripts/poller/index\\.mjs`), `stdout:\n${r.stdout}`);
+    assert.match(r.stdout, new RegExp(`TOKEN=${SECRET}`), ".env must be sourced so the token reaches the poller");
+    assert.match(r.stdout, /OTHER=\[with spaces\]/, "unquoted value with spaces survives; inline comment stripped");
+    assert.match(r.stdout, /QUOTED=\[a # not a comment\]/, "a quoted value keeps its #");
+    assert.match(r.stdout, /EXPORTED=\[yes\]/, "`export KEY=` lines are accepted");
+    assert.match(r.stdout, /LITERAL=\[\$HOME stays literal\]/, "no expansion of $ inside values");
+    // The wrapper resolves AGENT_ROOT with `pwd -P` (macOS: /var → /private/var).
+    assert.match(r.stdout, new RegExp(`AGENT_ROOT=${realpathSync(fx.agent).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`));
+    // The secret must never be echoed by the wrapper itself.
+    assert.ok(!r.stderr.includes(SECRET));
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("launchd-poller-wrapper.sh runs without a .env (fail-open)", () => {
+  const fx = fixture();
+  try {
+    rmSync(join(fx.agent, ".env"));
+    const stubNode = join(fx.bin, "node");
+    writeFileSync(stubNode, "#!/bin/bash\necho ok\n");
+    chmodSync(stubNode, 0o755);
+    const wrapper = join(fx.agent, "scripts", "poller-launchd", "launchd-poller-wrapper.sh");
+    const r = spawnSync("/bin/bash", [wrapper], { encoding: "utf8", env: env(fx, { MAESTRO_NODE_BIN: stubNode }) });
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+// --- review fixes (2026-09-08) ---------------------------------------------
+
+test("launchd-poller-wrapper.sh strips a trailing CR (CRLF .env) and never overrides a variable already in the environment (dotenv semantics)", () => {
+  const fx = fixture();
+  try {
+    writeFileSync(join(fx.agent, ".env"), `SLACK_USER_TOKEN=${SECRET}\r\nPRESET=from-dotenv\r\nOTHER_VALUE=plain\r\n`);
+    const stubNode = join(fx.bin, "node");
+    writeFileSync(stubNode, `#!/bin/bash\nprintf 'TOKEN=[%s]\\n' "$SLACK_USER_TOKEN"\nprintf 'PRESET=[%s]\\n' "$PRESET"\nprintf 'OTHER=[%s]\\n' "$OTHER_VALUE"\n`);
+    chmodSync(stubNode, 0o755);
+    const wrapper = join(fx.agent, "scripts", "poller-launchd", "launchd-poller-wrapper.sh");
+    const r = spawnSync("/bin/bash", [wrapper], { encoding: "utf8", env: env(fx, { MAESTRO_NODE_BIN: stubNode, PRESET: "from-env" }) });
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    assert.match(r.stdout, new RegExp(`TOKEN=\\[${SECRET}\\]`), `CR must be stripped:\n${JSON.stringify(r.stdout)}`);
+    assert.match(r.stdout, /PRESET=\[from-env\]/, "a variable already set in the environment wins (dotenv does not override)");
+    assert.match(r.stdout, /OTHER=\[plain\]/);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+// migrate.sh — audit F6 follow-through for plists installed by the OLD install.sh
+// (SLACK_USER_TOKEN inline, mode 644). Re-renders the agent's own poller plist
+// through install.sh; a foreign agent's plist is only tightened to 0600.
+
+const migratePath = join(__dirname, "migrate.sh");
+const oldPlist = (label, secret) => `<?xml version="1.0" encoding="UTF-8"?>
+<plist version="1.0"><dict>
+  <key>Label</key><string>${label}</string>
+  <key>EnvironmentVariables</key><dict><key>SLACK_USER_TOKEN</key><string>${secret}</string></dict>
+</dict></plist>
+`;
+
+function migrateFixture() {
+  const fx = fixture();
+  copyFileSync(migratePath, join(fx.agent, "scripts", "poller-launchd", "migrate.sh"));
+  chmodSync(join(fx.agent, "scripts", "poller-launchd", "migrate.sh"), 0o755);
+  return fx;
+}
+
+test("migrate.sh re-renders an installed poller plist that carries SLACK_USER_TOKEN at 0644 — secret gone, 0600, job reloaded", () => {
+  const fx = migrateFixture();
+  try {
+    writeFileSync(plistPath(fx), oldPlist("ai.maestro.ivy-poller", SECRET));
+    chmodSync(plistPath(fx), 0o644);
+    const r = spawnSync("/bin/bash", [join(fx.agent, "scripts", "poller-launchd", "migrate.sh")], { encoding: "utf8", env: env(fx) });
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    const body = readFileSync(plistPath(fx), "utf8");
+    assert.ok(!body.includes(SECRET) && !/SLACK_USER_TOKEN/.test(body), "the secret must be gone from the plist");
+    assert.match(body, /launchd-poller-wrapper\.sh/, "must be the wrapper-based render");
+    assert.equal(statSync(plistPath(fx)).mode & 0o777, 0o600);
+    assert.match(readFileSync(fx.log, "utf8"), /launchctl load .*ai\.maestro\.ivy-poller\.plist/, "the job is reloaded on the new render");
+    assert.ok(!(r.stdout + r.stderr).includes(SECRET), "the migration must never echo the secret");
+    assert.match(r.stdout, /migrated|re-rendered/i);
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("migrate.sh is a no-op on a clean seat (no poller plist, or a wrapper-based 0600 one) and idempotent", () => {
+  const fx = migrateFixture();
+  try {
+    const script = join(fx.agent, "scripts", "poller-launchd", "migrate.sh");
+    // No poller plist at all.
+    let r = spawnSync("/bin/bash", [script], { encoding: "utf8", env: env(fx) });
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    assert.ok(!existsSync(fx.log), `nothing to do → no launchctl calls; got:\n${existsSync(fx.log) ? readFileSync(fx.log, "utf8") : ""}`);
+    // A current render.
+    assert.equal(spawnSync("/bin/bash", [join(fx.agent, "scripts", "poller-launchd", "install.sh")], { encoding: "utf8", env: env(fx) }).status, 0);
+    rmSync(fx.log, { force: true });
+    r = spawnSync("/bin/bash", [script], { encoding: "utf8", env: env(fx) });
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    assert.ok(!existsSync(fx.log), "a clean plist is left alone (no unload/load churn)");
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});
+
+test("migrate.sh tightens a foreign agent's leaking poller plist to 0600 without re-rendering it", () => {
+  const fx = migrateFixture();
+  try {
+    const foreign = join(fx.home, "Library", "LaunchAgents", "ai.maestro.zed-poller.plist");
+    writeFileSync(foreign, oldPlist("ai.maestro.zed-poller", SECRET));
+    chmodSync(foreign, 0o644);
+    const r = spawnSync("/bin/bash", [join(fx.agent, "scripts", "poller-launchd", "migrate.sh")], { encoding: "utf8", env: env(fx) });
+    assert.equal(r.status, 0, r.stderr + r.stdout);
+    assert.equal(statSync(foreign).mode & 0o777, 0o600, "at least no longer world-readable");
+    assert.ok(readFileSync(foreign, "utf8").includes(SECRET), "not ours to re-render (its agent dir is unknown)");
+    assert.match(r.stdout, /zed-poller/);
+    assert.match(r.stdout, /install\.sh/, "must say how to finish the migration from that agent's dir");
+    assert.ok(!(r.stdout + r.stderr).includes(SECRET));
+  } finally { rmSync(fx.root, { recursive: true, force: true }); }
+});

package/scripts/poller-launchd/launchd-poller-wrapper.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# launchd-poller-wrapper.sh — Bootstraps env for the legacy poller under launchd.
+#
+# Exec'd by ai.maestro.{firstname}-poller.plist (rendered from
+# poller.plist.template by install.sh). launchd's environment is bare, so we
+# set HOME/PATH/USER/AGENT_ROOT here — the same idiom as
+# scripts/daemon/launchd-wrapper.sh — and, unlike that wrapper, SOURCE the
+# agent's .env (0600) so SLACK_USER_TOKEN & co. reach the poller.
+#
+# Audit F6: install.sh used to copy SLACK_USER_TOKEN out of .env into the plist
+# via an unescaped `sed`, leaving the secret in a 0644 file. The secret now
+# lives only in .env; the plist names this wrapper and nothing else.
+#
+# MAESTRO_NODE_BIN overrides node resolution (tests / non-standard installs).
+
+set -e
+
+AGENT_ROOT="$(cd "$(dirname "$0")/../.." && pwd -P)"
+export AGENT_ROOT
+export HOME="${HOME:-/Users/$(whoami)}"
+export USER="${USER:-$(whoami)}"
+export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
+export NODE_ENV="${NODE_ENV:-production}"
+
+cd "$AGENT_ROOT"
+
+# ── .env ────────────────────────────────────────────────────────────────────
+# Read with dotenv semantics rather than `source`: the file is written for
+# Node's dotenv, where `KEY=Ivy Tester` is legal, but under `source` + set -e
+# that line runs `Tester` as a command and kills the job. Rules: skip blanks
+# and comments, accept `export KEY=…`, strip matching surrounding quotes, strip
+# an inline ` # comment` from an UNQUOTED value, never expand `$` or backticks,
+# strip a trailing CR (a .env pasted from a CRLF editor would otherwise hand
+# the poller a token ending in `\r` → invalid_auth with no hint), and never
+# override a variable that is already in the environment (dotenv semantics:
+# the environment wins over the file).
+# Fail-open: no .env → the poller starts with launchd's env and reports its own
+# missing-token error. Nothing from the file is ever echoed.
+load_dotenv() {
+  local line key val
+  while IFS= read -r line || [ -n "$line" ]; do
+    line="${line%$'\r'}"
+    line="${line#"${line%%[![:space:]]*}"}"
+    case "$line" in ''|'#'*) continue ;; esac
+    line="${line#export }"
+    case "$line" in *=*) ;; *) continue ;; esac
+    key="${line%%=*}"
+    val="${line#*=}"
+    key="${key%"${key##*[![:space:]]}"}"
+    case "$key" in ''|*[!A-Za-z0-9_]*|[0-9]*) continue ;; esac
+    if [ -n "${!key+x}" ]; then continue; fi
+    case "$val" in
+      \"*\") val="${val#\"}"; val="${val%\"}" ;;
+      \'*\') val="${val#\'}"; val="${val%\'}" ;;
+      *)     val="${val%%[[:space:]]#*}"; val="${val%"${val##*[![:space:]]}"}" ;;
+    esac
+    case "$val" in
+      *$'\r') val="${val%$'\r'}" ;;
+    esac
+    export "$key=$val"
+  done < "$1"
+}
+if [ -f "$AGENT_ROOT/.env" ]; then
+  load_dotenv "$AGENT_ROOT/.env"
+fi
+
+# ── node ────────────────────────────────────────────────────────────────────
+NODE_BIN="${MAESTRO_NODE_BIN:-}"
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  NODE_BIN=""
+  for candidate in \
+    "$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; do
+    if [ -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" ]; then
+  NODE_BIN="$(command -v node 2>/dev/null || true)"
+fi
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  echo "[poller-wrapper] FATAL: could not find node binary" >&2
+  exit 127
+fi
+
+exec "$NODE_BIN" "$AGENT_ROOT/scripts/poller/index.mjs" "$@"

package/scripts/poller-launchd/migrate.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# migrate.sh — audit F6 follow-through for poller plists installed BEFORE the
+# wrapper-based render.
+#
+# The old install.sh copied SLACK_USER_TOKEN out of .env into
+# ~/Library/LaunchAgents/ai.maestro.<first>-poller.plist at mode 644. The new
+# install.sh never does, but nothing else on a seat rewrites an already
+# installed plist — autoupdate, `maestro upgrade`, init-agent Step 5 and
+# doctor all leave it alone — so the secret stays world-readable until this
+# runs. Called from init-agent Step 5 and from autoupdate.sh after a healthy
+# upgrade; safe to run any time.
+#
+#   own label   (ai.maestro.<this agent's first>-poller): re-rendered through
+#               install.sh (secret gone, 0600, job reloaded)
+#   other label: chmod 600 only — its agent dir is unknown here; say how to
+#               finish from there
+#   clean plist (no token, 0600): untouched — no unload/load churn
+#
+# Never prints a plist's contents. Exit 0 unless the re-render itself fails.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+AGENT_JSON="$AGENT_DIR/config/agent.json"
+LAUNCH_AGENTS="$HOME/Library/LaunchAgents"
+
+# Same first-name chain as install.sh, so "own label" means the same thing.
+AGENT_FIRST=""
+if [ -f "$AGENT_JSON" ]; then
+    if command -v jq >/dev/null 2>&1; then
+        AGENT_FIRST=$(jq -r '.firstName // empty' "$AGENT_JSON" | tr '[:upper:]' '[:lower:]')
+    else
+        AGENT_FIRST=$(awk -F'"' '/"firstName"[[:space:]]*:/ { print tolower($4); exit }' "$AGENT_JSON")
+    fi
+fi
+[ -z "$AGENT_FIRST" ] && AGENT_FIRST=$(basename "$AGENT_DIR" | sed 's/-ai$//')
+[ -z "$AGENT_FIRST" ] && AGENT_FIRST="agent"
+OWN_LABEL="ai.maestro.${AGENT_FIRST}-poller"
+
+file_mode() { stat -f '%Lp' "$1" 2>/dev/null || stat -c '%a' "$1" 2>/dev/null || echo ""; }
+
+rc=0
+for plist in "$LAUNCH_AGENTS"/ai.maestro.*-poller.plist; do
+    [ -f "$plist" ] || continue
+    label="$(basename "$plist" .plist)"
+    reason=""
+    if grep -q "SLACK_USER_TOKEN" "$plist" 2>/dev/null; then reason="carries SLACK_USER_TOKEN"; fi
+    mode="$(file_mode "$plist")"
+    if [ -n "$mode" ] && [ "$mode" != "600" ]; then reason="${reason:+$reason, }mode $mode"; fi
+    [ -z "$reason" ] && continue
+
+    if [ "$label" = "$OWN_LABEL" ]; then
+        echo "[poller-migrate] $label $reason — re-rendering via install.sh (secret stays in .env, plist 0600)"
+        if bash "$SCRIPT_DIR/install.sh" >/dev/null; then
+            echo "[poller-migrate] migrated $label"
+        else
+            echo "[poller-migrate] FAILED to re-render $label — run: bash $SCRIPT_DIR/install.sh" >&2
+            rc=1
+        fi
+    else
+        chmod 600 "$plist" 2>/dev/null || true
+        echo "[poller-migrate] $label $reason — tightened to 0600; finish from its own agent dir: bash scripts/poller-launchd/install.sh"
+    fi
+done
+exit "$rc"

package/scripts/poller-launchd/poller.plist.template

@@ -5,10 +5,12 @@
     <key>Label</key>
     <string>ai.maestro.{{FIRSTNAME}}-poller</string>
 
+    <!-- The wrapper sources the agent's .env (0600) and execs node on
+         scripts/poller/index.mjs. No secret is ever rendered into this file
+         (audit F6); install.sh chmods the installed copy to 600 regardless. -->
     <key>ProgramArguments</key>
     <array>
-        <string>{{NODE_BIN}}</string>
-        <string>{{AGENT_ROOT}}/scripts/poller/index.mjs</string>
+        <string>{{AGENT_ROOT}}/scripts/poller-launchd/launchd-poller-wrapper.sh</string>
     </array>
 
     <key>StartInterval</key>

package/scripts/session/feed.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * scripts/session/feed.mjs — the main session's event intake (runner).
+ *
+ * Runs INSIDE the main Claude session under `Monitor({persistent:true})`:
+ * every line it prints to stdout is one JSON object the session treats as a
+ * unit of work. NOTHING ELSE goes to stdout — diagnostics go to stderr.
+ *
+ * Responsibilities, all fail-open (a broken probe degrades one line, never the
+ * loop):
+ *
+ *   heartbeat  every 15 s → state/session/heartbeat.json (tmp + rename), which
+ *              is how the daemon measures that the front door is open.
+ *   inbox      state/inbox/<service>/*.yaml for every configured service
+ *              (default ["cohort"]) — polled every second, plus fs.watch where
+ *              the platform provides it, so a new item is emitted promptly.
+ *   handoffs   state/session/handoffs/*.json written by the cadence consumer.
+ *   signals    restart-requested marker, upgrade-notice.json, stale daemon.
+ *   seen-set   state/session/feed-seen.json so a Monitor restart replays nothing.
+ *
+ * The decision logic is lib/session/feed-core.mjs (pure); this file is the
+ * I/O shell. `createFeed` is exported so the runner is testable with an
+ * injected clock and emitter; `--once` runs a single tick + beat and exits.
+ *
+ * Usage: node scripts/session/feed.mjs [--once]
+ * Env:   AGENT_ROOT (or AGENT_DIR) — the agent directory.
+ *
+ * @module scripts/session/feed
+ */
+
+import { readdirSync, readFileSync, statSync, mkdirSync, watch as fsWatch } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { resolveAgentRoot } from "../../lib/agent-root.mjs";
+import { writeJsonAtomic } from "../../lib/fs-atomic.mjs";
+import { loadSessionConfig, sessionPaths } from "../../lib/session/config.mjs";
+import { loadMainSession, agentFirstName, mainSessionName } from "../../lib/session/identity.mjs";
+import { buildHeartbeat, writeHeartbeat, HEARTBEAT_INTERVAL_MS } from "../../lib/session/liveness.mjs";
+import { computeFeedEvents, parseSeen, emptySeen, isLiveInboxFile, isHandoffFile } from "../../lib/session/feed-core.mjs";
+
+/** Inbox / handoff poll cadence. */
+export const POLL_INTERVAL_MS = 1_000;
+
+/** @param {string[]} argv */
+export function parseFeedArgs(argv) {
+  return { once: argv.includes("--once") };
+}
+
+function pidAliveDefault(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+/**
+ * Build a feed bound to one agent root.
+ *
+ * @param {{agentRoot:string, config:{services:string[]}, now?:Function, emit?:(obj:object)=>void, log?:(line:string)=>void, pid?:number, ppid?:number, pidAlive?:(pid:number)=>boolean, fs?:object}} a
+ */
+export function createFeed(a) {
+  const agentRoot = a.agentRoot;
+  const paths = sessionPaths(agentRoot);
+  const now = a.now || Date.now;
+  const emit = a.emit || ((obj) => process.stdout.write(JSON.stringify(obj) + "\n"));
+  const log = a.log || ((line) => process.stderr.write(`[feed] ${line}\n`));
+  const pidAlive = a.pidAlive || pidAliveDefault;
+  const fs = { readdirSync, readFileSync, statSync, mkdirSync, writeJsonAtomic, ...(a.fs || {}) };
+  const services = Array.isArray(a.config && a.config.services) && a.config.services.length ? a.config.services : ["cohort"];
+
+  const first = agentFirstName(agentRoot, fs);
+  const name = mainSessionName(first);
+
+  let seen = null;
+  function loadSeen() {
+    if (seen) return seen;
+    try { seen = parseSeen(fs.readFileSync(paths.feedSeenFile, "utf8")); } catch { seen = emptySeen(); /* first run */ }
+    return seen;
+  }
+
+  /**
+   * The files in `dir` that `keep` accepts. A file the seen-set already holds
+   * is listed WITHOUT its body (feed-core carries a seen key forward without
+   * looking at the body), so a tick costs one readdir plus one read per NEW
+   * file rather than one read per backlog item per second.
+   */
+  function listDir(dir, keep, isSeen) {
+    let names;
+    try { names = fs.readdirSync(dir); } catch { return []; /* dir absent until the first item lands */ }
+    const out = [];
+    for (const file of names) {
+      if (!keep(file)) continue;
+      const path = join(dir, file);
+      if (isSeen && isSeen(file)) { out.push({ file, path, body: null }); continue; }
+      let body = null;
+      try { body = fs.readFileSync(path, "utf8"); } catch { continue; /* raced a rename; next tick */ }
+      out.push({ file, path, body });
+    }
+    return out;
+  }
+
+  function mtimeOf(path) {
+    try { return fs.statSync(path).mtimeMs; } catch { return null; }
+  }
+
+  function daemonPidAlive() {
+    try {
+      const pid = parseInt(fs.readFileSync(paths.daemonPidFile, "utf8"), 10);
+      return Number.isFinite(pid) && pid > 0 ? pidAlive(pid) : null;
+    } catch {
+      return null; // no pidfile → let the health-file age decide
+    }
+  }
+
+  function snapshot() {
+    const prev = loadSeen();
+    const inbox = {};
+    for (const service of services) {
+      const seenInbox = prev.inbox || {};
+      inbox[service] = listDir(paths.inboxDir(service), isLiveInboxFile, (file) => seenInbox[`${service}/${file}`] != null);
+    }
+    const seenHandoffs = prev.handoffs || {};
+    const upgradeMtime = mtimeOf(paths.upgradeNoticeFile);
+    let upgradeNotice = null;
+    if (upgradeMtime != null) {
+      let body = "";
+      try { body = fs.readFileSync(paths.upgradeNoticeFile, "utf8"); } catch { body = ""; }
+      upgradeNotice = { mtimeMs: upgradeMtime, body };
+    }
+    return {
+      inbox,
+      handoffs: listDir(paths.handoffsDir, isHandoffFile, (file) => seenHandoffs[file] != null),
+      signals: {
+        restartRequestedMtimeMs: mtimeOf(paths.restartRequestedFile),
+        upgradeNotice,
+        daemonHealthMtimeMs: mtimeOf(paths.daemonHealthFile),
+        daemonPidAlive: daemonPidAlive(),
+      },
+    };
+  }
+
+  /** One scan: emit new lines, persist the seen-set when it changed. */
+  function tick() {
+    const prev = loadSeen();
+    const { events, seen: next } = computeFeedEvents(snapshot(), prev, { now });
+    for (const ev of events) emit(ev);
+    if (JSON.stringify(next) !== JSON.stringify(prev)) {
+      seen = next;
+      try { fs.writeJsonAtomic(paths.feedSeenFile, next); } catch (err) {
+        // An unwritable seen-set costs a replay after a restart, not a dropped event.
+        log(`seen-set not persisted: ${err && err.message ? err.message : err}`);
+      }
+    }
+    return events;
+  }
+
+  /**
+   * `tick`, but a throw (an emitter whose stdout is gone, a defect in a
+   * future parser) costs this tick and one stderr line — never the loop.
+   */
+  function tickSafely() {
+    try { return tick(); } catch (err) {
+      log(`tick failed: ${err && err.message ? err.message : err}`);
+      return [];
+    }
+  }
+
+  /** One heartbeat. */
+  function beat() {
+    const rec = loadMainSession(agentRoot, fs);
+    const hb = buildHeartbeat({
+      pid: a.pid ?? process.pid,
+      ppid: a.ppid ?? process.ppid,
+      sessionId: rec ? rec.sessionId : null,
+      name,
+      now,
+    });
+    const res = writeHeartbeat(agentRoot, hb, fs);
+    if (!res.ok) log(`heartbeat not written: ${res.error}`);
+    return res;
+  }
+
+  /** Directories worth an fs.watch (only those that exist right now). */
+  function watchDirs() {
+    return [...services.map((s) => paths.inboxDir(s)), paths.handoffsDir, paths.stateDir];
+  }
+
+  return { tick, tickSafely, beat, snapshot, watchDirs, name, services, paths };
+}
+
+/**
+ * Run forever: beat now and every 15 s; tick now, every second, and on any
+ * fs.watch event (debounced to the next macrotask). Resolves only on `--once`.
+ * @param {{agentRoot:string, once?:boolean}} a
+ */
+export async function runFeed(a) {
+  const agentRoot = a.agentRoot;
+  const config = await loadSessionConfig(agentRoot);
+  const feed = createFeed({ agentRoot, config });
+  try { mkdirSync(feed.paths.stateDir, { recursive: true }); } catch { /* beat() reports it */ }
+
+  feed.beat();
+  feed.tickSafely(); // the first snapshot is guarded like every later one
+  if (a.once) return 0;
+
+  const beatTimer = setInterval(() => feed.beat(), HEARTBEAT_INTERVAL_MS);
+  let pending = false;
+  const scheduleTick = () => {
+    if (pending) return;
+    pending = true;
+    setImmediate(() => { pending = false; feed.tickSafely(); });
+  };
+  const pollTimer = setInterval(scheduleTick, POLL_INTERVAL_MS);
+
+  // fs.watch is a fast path, never a dependency: the 1 s poll is the guarantee.
+  const watchers = [];
+  for (const dir of feed.watchDirs()) {
+    try { watchers.push(fsWatch(dir, { persistent: false }, scheduleTick)); } catch { /* dir absent or watch unsupported — the poll covers it */ }
+  }
+
+  await new Promise((resolve) => {
+    const stop = () => { clearInterval(beatTimer); clearInterval(pollTimer); for (const w of watchers) { try { w.close(); } catch { /* already closed */ } } resolve(); };
+    process.once("SIGTERM", stop);
+    process.once("SIGINT", stop);
+    process.stdout.once("close", stop); // the Monitor went away
+  });
+  return 0;
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href; } catch { return false; }
+})();
+
+if (isMain) {
+  const { once } = parseFeedArgs(process.argv.slice(2));
+  runFeed({ agentRoot: resolveAgentRoot(), once })
+    .then((code) => process.exit(code))
+    .catch((err) => { process.stderr.write(`[feed] fatal: ${err && err.stack ? err.stack : err}\n`); process.exit(1); });
+}