@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/scripts/hooks/pre-send-audit.test.mjs

@@ -13,7 +13,7 @@ import assert from "node:assert/strict";
 import { execFile, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -213,3 +213,142 @@ test("daily cap blocks once exceeded (exit 2)", { skip: JQ ? false : "jq not on
   assert.equal(r2.code, 2, `send 2 expected 2 (daily cap), got ${r2.code}`);
   assert.match(r2.stderr, /Daily send limit/);
 });
+
+// ── WP-M4: persona-leak patterns (front-door session §3.6) ─────────────────
+//
+// Outbound text may never expose the machinery: "Claude Code", "Claude
+// session", "sub-session", a subagent that "said/reported", "workflow agent",
+// "as an AI" / "language model", or an internal session name (<first>-main,
+// <first>-<purpose>). The hook returns the offending phrase so the session can
+// rewrite in its own voice.
+
+const PERSONA_ENV = { MAESTRO_AGENT_FIRST: "alex" };
+
+for (const [label, text] of [
+  ["Claude Code", "I'll have Claude Code pick that up this afternoon."],
+  ["Claude session", "A separate claude session is running the numbers."],
+  ["sub-session", "I kicked off a sub-session for the deck."],
+  ["subagent said", "The subagent said the deploy finished."],
+  ["sub-agent reported", "My sub-agent reported two blockers."],
+  ["subagent session", "The subagent session is still going."],
+  ["workflow agent", "The workflow agent will file the summary."],
+  ["language model", "Every language model has limits, mine included."],
+  ["<first>-main", "Check with alex-main for the latest."],
+]) {
+  test(`persona leak "${label}" blocks (exit 2) and names the phrase`, { skip: JQ ? false : "jq not on PATH" }, async () => {
+    const payload = JSON.stringify({ tool_name: "mcp__cohort__messaging_send", tool_input: { channelId: "C1", body: text } });
+    const { code, stderr } = await runHook(payload, { channel: "cohort", env: PERSONA_ENV });
+    assert.equal(code, 2, `expected exit 2 for "${label}", got ${code}`);
+    assert.match(stderr, /BLOCKED/);
+    assert.match(stderr, /persona/i);
+  });
+}
+
+test("persona: the leak line names the offending phrase so the session can rewrite", { skip: JQ ? false : "jq not on PATH" }, async () => {
+  const payload = JSON.stringify({ tool_input: { channelId: "C1", body: "I'll have Claude Code pick that up." } });
+  const { stderr } = await runHook(payload, { channel: "cohort", env: PERSONA_ENV });
+  assert.match(stderr, /claude code/i);
+});
+
+test("persona: colleague phrasing passes; bare 'subagent' without said/reported/session passes; mid-word matches ignored", { skip: JQ ? false : "jq not on PATH" }, async () => {
+  for (const text of [
+    "One of my analysts is on it; I'll have the numbers by 3.",
+    "My team has the deck in review — sending the draft after lunch.",
+    "We use subagents internally for the heavy lifting.",
+    "Alexandra-Maine sent the invoice.",
+    "The session on Thursday (the board session) starts at 9.",
+  ]) {
+    const payload = JSON.stringify({ tool_input: { channelId: "C1", body: text } });
+    const { code, stderr } = await runHook(payload, { channel: "cohort", env: PERSONA_ENV });
+    assert.equal(code, 0, `expected exit 0 for "${text}", got ${code}: ${stderr}`);
+  }
+});
+
+test("persona: session-name pattern reads the first name from AGENT_ROOT/config/agent.json when the env is unset", { skip: JQ ? false : "jq not on PATH" }, async () => {
+  const dir = mkdtempSync(join(tmpdir(), "presend-agent-"));
+  try {
+    const cfg = join(dir, "config");
+    mkdirSyncP(cfg);
+    writeFileSync(join(cfg, "agent.json"), JSON.stringify({ firstName: "Robin", fullName: "Robin Park" }));
+    const payload = JSON.stringify({ tool_input: { channelId: "C1", body: "robin-main will chase it." } });
+    const { code, stderr } = await runHook(payload, { channel: "cohort", env: { AGENT_ROOT: dir } });
+    assert.equal(code, 2, `expected exit 2, got ${code}: ${stderr}`);
+    assert.match(stderr, /robin-main/);
+    // No first name resolvable anywhere → the name pattern is skipped (fail-open on that one check), the rest still applies.
+    const { code: c2 } = await runHook(payload, { channel: "cohort", env: {} });
+    assert.equal(c2, 0);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+// ── Review fix: session names are BOUNDED (spec §3.6 gap) ──────────────────
+// `<first>-main` is always internal; any other `<first>-<x>` is internal only
+// when it is a registered peer (state/session/peers.json under AGENT_ROOT) or
+// listed in MAESTRO_SESSION_NAMES. A colleague's hyphenated name, a URL slug or
+// an email local part that happens to start with the first name must pass.
+
+test("persona: an unregistered <first>-<x> is ordinary text; a registered peer name (peers.json) or MAESTRO_SESSION_NAMES entry blocks", { skip: JQ ? false : "jq not on PATH" }, async () => {
+  const dir = mkdtempSync(join(tmpdir(), "presend-peers-"));
+  try {
+    const payload = JSON.stringify({ tool_input: { channelId: "C1", body: "alex-research has the draft ready." } });
+    const { code: c0, stderr: e0 } = await runHook(payload, { channel: "cohort", env: PERSONA_ENV });
+    assert.equal(c0, 0, `unregistered alex-research must pass: ${e0}`);
+
+    mkdirSyncP(join(dir, "state", "session"));
+    writeFileSync(join(dir, "state", "session", "peers.json"), JSON.stringify([{ name: "alex-research", muxName: "maestro-alex-research", purpose: "research" }]));
+    const { code: c1, stderr: e1 } = await runHook(payload, { channel: "cohort", env: { ...PERSONA_ENV, AGENT_ROOT: dir } });
+    assert.equal(c1, 2, `registered peer must block, got ${c1}: ${e1}`);
+    assert.match(e1, /alex-research/);
+
+    // {peers:[…]} shape is accepted too.
+    writeFileSync(join(dir, "state", "session", "peers.json"), JSON.stringify({ peers: [{ name: "alex-deck" }] }));
+    const deck = JSON.stringify({ tool_input: { channelId: "C1", body: "alex-deck is nearly done." } });
+    assert.equal((await runHook(deck, { channel: "cohort", env: { ...PERSONA_ENV, AGENT_ROOT: dir } })).code, 2);
+    assert.equal((await runHook(payload, { channel: "cohort", env: { ...PERSONA_ENV, AGENT_ROOT: dir } })).code, 0, "alex-research is no longer registered");
+
+    // A corrupt registry is an empty one — never a fail-closed on the whole send.
+    writeFileSync(join(dir, "state", "session", "peers.json"), "{nope");
+    assert.equal((await runHook(deck, { channel: "cohort", env: { ...PERSONA_ENV, AGENT_ROOT: dir } })).code, 0);
+
+    // Env override (comma-separated), no files needed.
+    const { code: c2, stderr: e2 } = await runHook(payload, { channel: "cohort", env: { ...PERSONA_ENV, MAESTRO_SESSION_NAMES: "alex-research, alex-ops" } });
+    assert.equal(c2, 2, `MAESTRO_SESSION_NAMES must block, got ${c2}: ${e2}`);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("persona: a colleague's hyphenated name, a URL slug and an email local part starting with the first name all pass", { skip: JQ ? false : "jq not on PATH" }, async () => {
+  for (const [first, text] of [
+    ["marc", "Marc-Antoine confirmed the numbers."],
+    ["james", "See https://os.cohortapp.com/spaces/james-kirkland for the thread."],
+    ["ethan", "Loop in ethan-miller@example.com on the invoice."],
+    ["alex", "alex-mainland is the venue; alex-main-street too."],
+  ]) {
+    const payload = JSON.stringify({ tool_input: { channelId: "C1", body: text } });
+    const { code, stderr } = await runHook(payload, { channel: "cohort", env: { MAESTRO_AGENT_FIRST: first } });
+    assert.equal(code, 0, `expected exit 0 for "${text}" (first=${first}), got ${code}: ${stderr}`);
+  }
+  // …while the real session name still blocks, whatever the case.
+  const { code } = await runHook(JSON.stringify({ tool_input: { channelId: "C1", body: "Ask ALEX-MAIN." } }), { channel: "cohort", env: PERSONA_ENV });
+  assert.equal(code, 2);
+});
+
+// ── Review fix: the hook now fronts every mcp__cohort outbound tool ──────────
+// org_rpc carries the body under tool_input.params; email_send under text (+
+// subject); email_draft_send under bodyText (+ subject). All must be screened.
+
+test("persona: org_rpc (params.body), email_send (subject+text) and email_draft_send (bodyText) payload shapes are screened", { skip: JQ ? false : "jq not on PATH" }, async () => {
+  const cases = [
+    ["org_rpc", { tool_name: "mcp__cohort__org_rpc", tool_input: { method: "messaging.send", params: { channelId: "C1", body: "My sub-session is on it." } } }],
+    ["email_send text", { tool_name: "mcp__cohort__email_send", tool_input: { to: ["a@b.com"], subject: "Update", text: "Claude Code finished the deploy." } }],
+    ["email_send subject", { tool_name: "mcp__cohort__email_send", tool_input: { to: ["a@b.com"], subject: "From alex-main", text: "Deploy finished." } }],
+    ["email_draft_send bodyText", { tool_name: "mcp__cohort__email_draft_send", tool_input: { to: ["a@b.com"], subject: "Update", bodyText: "The workflow agent will send the summary." } }],
+  ];
+  for (const [label, payload] of cases) {
+    const { code, stderr } = await runHook(JSON.stringify(payload), { channel: "cohort", env: PERSONA_ENV });
+    assert.equal(code, 2, `expected exit 2 for ${label}, got ${code}: ${stderr}`);
+    assert.match(stderr, /persona/i);
+  }
+  const clean = { tool_name: "mcp__cohort__org_rpc", tool_input: { method: "messaging.send", params: { channelId: "C1", body: "Numbers are in; deck by 3." } } };
+  assert.equal((await runHook(JSON.stringify(clean), { channel: "cohort", env: PERSONA_ENV })).code, 0);
+});
+
+function mkdirSyncP(p) { mkdirSync(p, { recursive: true }); }

package/scripts/local-triggers/autoupdate.sh

@@ -4,9 +4,11 @@
 # =============================================================================
 # Runs hourly via the ai.maestro.<first>-autoupdate launchd job. Policy is
 # "auto to @latest": whenever npm's latest is a strictly-greater semver than the
-# installed SDK, this installs it, smart-merges the copied framework files
-# (`maestro upgrade`), restarts the daemon, and VERIFIES the daemon comes back
-# healthy — rolling back to the prior version if it does not.
+# installed SDK, this installs it, runs the NEW package's `maestro upgrade`
+# (which smart-merges the framework files AND reconciles the seat: plists,
+# launchd jobs, global-setup, the global npm install — see
+# lib/upgrade/post-steps.mjs), restarts the daemon, and VERIFIES the daemon
+# comes back healthy — rolling back to the prior version if it does not.
 #
 # Safety rails:
 #   - kill-switch: `touch ~/.maestro-no-autoupdate` (or $AGENT_DIR/.no-autoupdate)
@@ -14,17 +16,64 @@
 #   - jitter 0-600s so 15 machines don't hit npm / restart in lockstep.
 #   - re-exec from a /tmp copy so `maestro upgrade` overwriting THIS file
 #     mid-run cannot corrupt the running shell.
-#   - health-gate + automatic rollback to the previous version on a bad release.
+#   - overlap lock: state/locks/autoupdate/ (mkdir, pid inside; stale after 2 h)
+#     so a slow npm on one tick cannot race the next tick.
+#   - npm view / install retried 3x with backoff (--no-audit --no-fund --prefer-online).
+#   - health-gate + automatic rollback to the previous version on a bad release;
+#     the rollback also puts the global install back to the previous version
+#     and reverts the -session job IF THIS RUN installed it (never a
+#     pre-existing one). What a rollback does NOT undo: files the new version
+#     added that the old manifest never listed stay on disk, and the old
+#     upgrade rewrites the manifest without sdkVersion — `maestro doctor` /
+#     `upgrade --verify` on the next healthy hop report both.
+#   - a version that failed the health gate here is NOT retried every hour:
+#     state/autoupdate/last.json remembers it and the run holds for 24 h
+#     (MAESTRO_AUTOUPDATE_FAILED_HOLD_S; delete last.json to retry now).
+#
+# The health gate is the DAEMON: alive + a fresh "org-mesh connected" /
+# "[daemon] Running" line. When the generated plist set carries a -session
+# job, the gate ALSO checks the session label is loaded and a supervisor is
+# alive — but a missing session is logged as `reconcile-failed` and does NOT
+# roll back (the daemon's --print lane is the front door meanwhile; doctor
+# and `maestro upgrade --verify` say what to do).
+#
+# The front-door session (ai.maestro.<first>-session) is NEVER restarted or
+# killed here: after a HEALTHY upgrade this writes
+# state/session/upgrade-notice.json {from,to,at}; the session's feed surfaces
+# it as an `upgrade-available` directive and the session restarts itself at an
+# idle moment via `maestro session restart` (the supervisor relaunches on the
+# new code). A rollback leaves no notice. Every attempt also writes
+# state/autoupdate/last.json {from,to,at,ok,healthy,reason}, which the beat
+# reports as machine.upgrade. See
+# docs/superpowers/specs/2026-09-08-front-door-session-design.md §3.10 + WP-M6.
+#
+# Every launchd / pgrep question is scoped to THIS agent (its first name from
+# config/agent.json, else its own generated plist set): two seats on one Mac
+# must not gate on — or kickstart — each other's jobs.
+#
+# Test knobs (scripts/local-triggers/autoupdate.test.mjs): MAESTRO_AUTOUPDATE_JITTER_MAX
+# (default 600) and MAESTRO_AUTOUPDATE_HEALTH_WAIT (default 30), both seconds;
+# MAESTRO_AUTOUPDATE_RETRY_SLEEP (default 20 s, ×attempt); MAESTRO_AUTOUPDATE_LOCK_STALE_S
+# (default 7200); MAESTRO_AUTOUPDATE_FAILED_HOLD_S (default 86400);
+# MAESTRO_AUTOUPDATE_PATH_PREFIX (a stub-binary dir that wins over PATH);
+# MAESTRO_SKIP_GLOBAL_INSTALL=1 (never touch the global install).
 # =============================================================================
 set -uo pipefail
-export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:${PATH:-}"
+# MAESTRO_AUTOUPDATE_PATH_PREFIX: a dir that wins over the standard prepend
+# (the test puts its npm/launchctl/pgrep stubs there so a run never reaches
+# the real registry or launchd).
+export PATH="${MAESTRO_AUTOUPDATE_PATH_PREFIX:+$MAESTRO_AUTOUPDATE_PATH_PREFIX:}/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:${PATH:-}"
 
 # Re-exec from a stable copy: `maestro upgrade` may overwrite this very file.
+# The copy removes itself on exit (REEXEC_COPY is only ever a mktemp'd
+# maestro-autoupdate.* file — never the agent dir's script).
 if [ "${MAESTRO_AUTOUPDATE_REEXEC:-}" != "1" ]; then
   _tmp="$(mktemp "${TMPDIR:-/tmp}/maestro-autoupdate.XXXXXX")" || exit 0
   cp "${BASH_SOURCE[0]}" "$_tmp" 2>/dev/null || exit 0
   MAESTRO_AUTOUPDATE_REEXEC=1 exec /bin/bash "$_tmp" "$@"
 fi
+REEXEC_COPY=""
+case "${BASH_SOURCE[0]}" in */maestro-autoupdate.??????) REEXEC_COPY="${BASH_SOURCE[0]}" ;; esac
 
 AGENT_DIR="${AGENT_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 cd "$AGENT_DIR" 2>/dev/null || exit 0
@@ -38,46 +87,221 @@ if [ -e "$HOME/.maestro-no-autoupdate" ] || [ -e "$AGENT_DIR/.no-autoupdate" ];
   log "SKIP: kill-switch present"; exit 0
 fi
 
+# ── overlap lock ─────────────────────────────────────────────────────────────
+# mkdir is atomic; the pid inside says who holds it. A holder that is dead, or
+# older than LOCK_STALE_S (a wedged npm), is reclaimed rather than honoured.
+LOCK_DIR="$AGENT_DIR/state/locks/autoupdate"
+LOCK_STALE_S="${MAESTRO_AUTOUPDATE_LOCK_STALE_S:-7200}"
+take_lock(){
+  mkdir -p "$AGENT_DIR/state/locks" 2>/dev/null
+  if mkdir "$LOCK_DIR" 2>/dev/null; then echo $$ > "$LOCK_DIR/pid"; return 0; fi
+  local pid mtime now age
+  pid="$(cat "$LOCK_DIR/pid" 2>/dev/null)"
+  mtime="$(stat -f %m "$LOCK_DIR" 2>/dev/null || stat -c %Y "$LOCK_DIR" 2>/dev/null || echo 0)"
+  now="$(date +%s)"; age=$(( now - mtime ))
+  if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null && [ "$age" -lt "$LOCK_STALE_S" ]; then
+    log "SKIP: another autoupdate (pid $pid) holds $LOCK_DIR (${age}s old)"; return 1
+  fi
+  log "reclaiming stale autoupdate lock (pid ${pid:-?}, ${age}s old)"
+  rm -rf "$LOCK_DIR" 2>/dev/null
+  mkdir "$LOCK_DIR" 2>/dev/null || return 1
+  echo $$ > "$LOCK_DIR/pid"; return 0
+}
+release_lock(){ rm -rf "$LOCK_DIR" 2>/dev/null; }
+remove_reexec_copy(){ [ -n "$REEXEC_COPY" ] && rm -f "$REEXEC_COPY" 2>/dev/null; return 0; }
+cleanup(){ release_lock; remove_reexec_copy; }
+trap remove_reexec_copy EXIT   # a run that yields to another holder must not release THAT holder's lock
+take_lock || exit 0
+trap cleanup EXIT
+
 # ── jitter ───────────────────────────────────────────────────────────────────
-J=$(( RANDOM % 601 )); log "wake; jitter ${J}s"; sleep "$J"
+JITTER_MAX="${MAESTRO_AUTOUPDATE_JITTER_MAX:-600}"
+J=$(( RANDOM % (JITTER_MAX + 1) )); log "wake; jitter ${J}s"; [ "$J" -gt 0 ] && sleep "$J"
+
+# ── retry helper (npm view / install) ────────────────────────────────────────
+RETRIES=3
+RETRY_SLEEP="${MAESTRO_AUTOUPDATE_RETRY_SLEEP:-20}"
+retry(){ # $1 = label; rest = command (stdout+stderr → LOG)
+  local label="$1"; shift
+  local attempt=1 wait
+  while :; do
+    if "$@" >> "$LOG" 2>&1; then return 0; fi
+    if [ "$attempt" -ge "$RETRIES" ]; then log "$label: failed after $attempt attempt(s)"; return 1; fi
+    wait=$(( RETRY_SLEEP * attempt ))
+    log "$label: attempt $attempt failed; retrying in ${wait}s"
+    sleep "$wait"; attempt=$(( attempt + 1 ))
+  done
+}
+npm_view_latest(){ # prints the latest version, or nothing after RETRIES attempts
+  local attempt=1 out wait
+  while :; do
+    out="$(npm view "$PKG" version --no-audit --no-fund --prefer-online 2>>"$LOG" | tail -1)"
+    if [ -n "$out" ]; then printf '%s' "$out"; return 0; fi
+    if [ "$attempt" -ge "$RETRIES" ]; then return 1; fi
+    wait=$(( RETRY_SLEEP * attempt ))
+    log "npm view: attempt $attempt failed; retrying in ${wait}s"
+    sleep "$wait"; attempt=$(( attempt + 1 ))
+  done
+}
 
 # ── version check ────────────────────────────────────────────────────────────
 CUR="$(node -p "require('$AGENT_DIR/node_modules/$PKG/package.json').version" 2>/dev/null || echo 0.0.0)"
-LATEST="$(npm view "$PKG" version 2>/dev/null || echo '')"
-[ -z "$LATEST" ] && { log "npm view failed; skip (still $CUR)"; exit 0; }
+LATEST="$(npm_view_latest)" || LATEST=""
+[ -z "$LATEST" ] && { log "npm view failed after $RETRIES attempts; skip (still $CUR)"; exit 0; }
 if [ "$CUR" = "$LATEST" ] || [ "$(printf '%s\n%s\n' "$CUR" "$LATEST" | sort -V | tail -1)" != "$LATEST" ]; then
   log "up to date ($CUR)"; exit 0
 fi
+
+# ── failed-target hold ───────────────────────────────────────────────────────
+# last.json is the memory of the health gate: a LATEST that was installed here
+# and rolled back (or could not even be rolled back) is not retried every hour
+# — that would be two installs, two global refreshes and two daemon restarts an
+# hour until someone touched the kill-switch. An install-failed (network) entry
+# does not hold. Fail-open: an unreadable last.json holds nothing.
+FAILED_HOLD_S="${MAESTRO_AUTOUPDATE_FAILED_HOLD_S:-86400}"
+failed_hold_reason(){ # prints "<reason> at <at>" when LATEST failed health within FAILED_HOLD_S
+  node -e '
+    const [file, latest, holdS] = process.argv.slice(1);
+    try {
+      const j = JSON.parse(require("fs").readFileSync(file, "utf8"));
+      const at = Date.parse(j.at);
+      if (j.to === latest && j.ok === false && /unhealthy/.test(String(j.reason)) && Number.isFinite(at) && Date.now() - at < Number(holdS) * 1000) process.stdout.write(`${j.reason} at ${j.at}`);
+    } catch {}
+  ' "$AGENT_DIR/state/autoupdate/last.json" "$LATEST" "$FAILED_HOLD_S" 2>/dev/null
+}
+HOLD="$(failed_hold_reason)"
+if [ -n "$HOLD" ]; then
+  log "SKIP: $LATEST already failed the health gate here ($HOLD); holding ${FAILED_HOLD_S}s (still $CUR) — rm state/autoupdate/last.json to retry now"
+  exit 0
+fi
 log "UPDATE $CUR -> $LATEST"
 
-DAEMON_PLIST="$(ls "$HOME"/Library/LaunchAgents/ai.maestro.*-daemon.plist 2>/dev/null | head -1)"
-DAEMON_LABEL="$(basename "$DAEMON_PLIST" .plist 2>/dev/null)"
 UID_="$(id -u)"
+AGENT_FIRST="$(node -p "String(require('$AGENT_DIR/config/agent.json').firstName || '').toLowerCase()" 2>/dev/null)"
+[ -n "$AGENT_FIRST" ] && log "agent: $AGENT_FIRST (launchd/pgrep questions are scoped to ai.maestro.$AGENT_FIRST-*)"
 DLOG="$AGENT_DIR/logs/daemon/daemon-$(date +%Y-%m-%d).log"
+HEALTH_WAIT="${MAESTRO_AUTOUPDATE_HEALTH_WAIT:-30}"
+DAEMON_LABEL=""
+SESSION_LABEL=""
 
-restart_daemon(){ [ -n "$DAEMON_LABEL" ] && launchctl kickstart -k "gui/$UID_/$DAEMON_LABEL" >> "$LOG" 2>&1; }
-apply_version(){ # $1 = version spec
-  npm install "$PKG@$1" --save >> "$LOG" 2>&1 || return 1
+first_plist(){ # $1 = suffix, $2 = dir — this agent's plist for that suffix, or nothing (unquoted so `*` globs when no name is known)
+  ls "$2"/ai.maestro.${AGENT_FIRST:-*}-"$1".plist 2>/dev/null | head -1
+}
+resolve_labels(){ # AFTER the upgrade: its reconcile may have just installed these
+  local p
+  # This agent's generated set names the daemon label; ~/Library/LaunchAgents
+  # is the fallback for a seat with no generated dir. Either way the label only
+  # counts when its plist is actually installed.
+  p="$(first_plist daemon "$AGENT_DIR/scripts/local-triggers/plists")"
+  [ -n "$p" ] || p="$(first_plist daemon "$HOME/Library/LaunchAgents")"
+  DAEMON_LABEL="$(basename "$p" .plist 2>/dev/null)"
+  [ -n "$DAEMON_LABEL" ] && [ -f "$HOME/Library/LaunchAgents/$DAEMON_LABEL.plist" ] || DAEMON_LABEL=""
+  p="$(first_plist session "$AGENT_DIR/scripts/local-triggers/plists")"
+  SESSION_LABEL="$(basename "$p" .plist 2>/dev/null)"
+}
+label_loaded(){ # $1 = label — measured in the gui domain (right from ssh too); `launchctl list <label>` only when print could not answer
+  local out rc
+  out="$(launchctl print "gui/$UID_/$1" 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] && return 0
+  case "$out" in *"Could not find service"*) return 1 ;; esac
+  launchctl list "$1" >/dev/null 2>&1
+}
+restart_daemon(){
+  resolve_labels
+  if [ -z "$DAEMON_LABEL" ]; then log "no -daemon plist under ~/Library/LaunchAgents — nothing to kickstart (maestro upgrade installs it; doctor will say)"; return 0; fi
+  launchctl kickstart -k "gui/$UID_/$DAEMON_LABEL" >> "$LOG" 2>&1 || log "WARN: kickstart $DAEMON_LABEL nonzero"
+}
+# What -session plists THIS agent had installed BEFORE this run. A rollback
+# reverts only a session job this run's upgrade installed — never one that
+# was already there (that one is the operator's, and `maestro session stop`
+# is how an operator stops it).
+PRE_SESSION_PLISTS="$(ls "$HOME"/Library/LaunchAgents/ai.maestro.${AGENT_FIRST:-*}-session.plist 2>/dev/null)"
+revert_session_install(){ # rollback only
+  local p label
+  ls "$HOME"/Library/LaunchAgents/ai.maestro.${AGENT_FIRST:-*}-session.plist 2>/dev/null | while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    case "$PRE_SESSION_PLISTS" in *"$p"*) continue ;; esac
+    label="$(basename "$p" .plist)"
+    launchctl bootout "gui/$UID_/$label" >> "$LOG" 2>&1 || log "WARN: bootout $label nonzero (not loaded?)"
+    rm -f "$p" 2>/dev/null
+    log "rollback: reverted session job $label — this run installed it and $CUR has no front-door session"
+  done
+  return 0
+}
+apply_version(){ # $1 = version spec — install locally, then run THAT package's upgrade
+  retry "npm install $PKG@$1" npm install "$PKG@$1" --save --no-audit --no-fund --prefer-online || return 1
   node "$AGENT_DIR/node_modules/$PKG/bin/maestro.mjs" upgrade --force-overwrite >> "$LOG" 2>&1 || log "WARN: upgrade nonzero for $1"
   return 0
 }
-is_healthy(){ # daemon process alive AND a fresh boot/connect line
+refresh_global(){ # $1 = version — the rollback's counterpart of upgrade() step 4
+  if [ "${MAESTRO_SKIP_GLOBAL_INSTALL:-}" = "1" ]; then
+    log "global refresh skipped (MAESTRO_SKIP_GLOBAL_INSTALL=1): npm install -g $PKG@$1 --no-audit --no-fund"; return 0
+  fi
+  retry "npm install -g $PKG@$1" npm install -g "$PKG@$1" --no-audit --no-fund || log "WARN: global refresh to $1 failed — run: npm install -g $PKG@$1"
+  return 0
+}
+is_healthy(){ # THIS agent's daemon process alive AND a fresh boot/connect line
   pgrep -f "$AGENT_DIR/scripts/daemon/maestro-daemon.mjs" >/dev/null 2>&1 || return 1
   tail -80 "$DLOG" 2>/dev/null | grep -qE "org-mesh connected|daemon\] Running" || return 1
   return 0
 }
+session_reconciled(){ # only asked when a -session plist was generated; never a rollback reason
+  label_loaded "$SESSION_LABEL" || { log "reconcile-failed: session job $SESSION_LABEL is not loaded (maestro session start)"; return 1; }
+  pgrep -f "$AGENT_DIR/scripts/session/supervisor" >/dev/null 2>&1 || { log "reconcile-failed: $SESSION_LABEL is loaded but no supervisor process is alive for $AGENT_DIR (maestro session status)"; return 1; }
+  return 0
+}
+write_upgrade_notice(){ # $1 = from, $2 = to — tell the front-door session; never restart it here
+  local dir="$AGENT_DIR/state/session" tmp
+  mkdir -p "$dir" 2>/dev/null || return 0
+  tmp="$(mktemp "$dir/.upgrade-notice.XXXXXX" 2>/dev/null)" || return 0
+  printf '{\n  "from": "%s",\n  "to": "%s",\n  "at": "%s"\n}\n' "$1" "$2" "$(date -u +%FT%TZ)" > "$tmp" \
+    && mv -f "$tmp" "$dir/upgrade-notice.json" \
+    && log "session notified: upgrade-notice.json $1 -> $2 (session restarts itself when idle)"
+  rm -f "$tmp" 2>/dev/null
+  return 0
+}
+write_last(){ # $1 from, $2 to, $3 ok, $4 healthy, $5 reason — state/autoupdate/last.json (→ beat machine.upgrade)
+  local dir="$AGENT_DIR/state/autoupdate" tmp
+  mkdir -p "$dir" 2>/dev/null || return 0
+  tmp="$(mktemp "$dir/.last.XXXXXX" 2>/dev/null)" || return 0
+  printf '{\n  "from": "%s",\n  "to": "%s",\n  "at": "%s",\n  "ok": %s,\n  "healthy": %s,\n  "reason": "%s"\n}\n' \
+    "$1" "$2" "$(date -u +%FT%TZ)" "$3" "$4" "$5" > "$tmp" && mv -f "$tmp" "$dir/last.json"
+  rm -f "$tmp" 2>/dev/null
+  return 0
+}
+migrate_poller_plist(){ # audit F6 follow-through: an older install left SLACK_USER_TOKEN in a 0644 poller plist; nothing else rewrites it
+  [ -f "$AGENT_DIR/scripts/poller-launchd/migrate.sh" ] || return 0
+  bash "$AGENT_DIR/scripts/poller-launchd/migrate.sh" >> "$LOG" 2>&1 || log "WARN: poller plist migration nonzero (see above)"
+  return 0
+}
 
 if ! apply_version "$LATEST"; then
-  log "npm install FAILED; aborting, staying on $CUR"; exit 1
+  log "npm install FAILED; aborting, staying on $CUR"
+  write_last "$CUR" "$LATEST" false false "install-failed"
+  exit 1
 fi
 restart_daemon
-sleep 30
+[ "$HEALTH_WAIT" -gt 0 ] && sleep "$HEALTH_WAIT"
+
 if is_healthy; then
-  log "OK: healthy on $LATEST"
+  REASON=""
+  if [ -n "$SESSION_LABEL" ] && ! session_reconciled; then REASON="session-reconcile-failed"; fi
+  log "OK: healthy on $LATEST${REASON:+ ($REASON)}"
+  write_upgrade_notice "$CUR" "$LATEST"
+  write_last "$CUR" "$LATEST" true true "$REASON"
+  migrate_poller_plist
 else
   log "UNHEALTHY on $LATEST -> ROLLBACK to $CUR"
   apply_version "$CUR" || log "WARN: rollback install nonzero"
+  refresh_global "$CUR"
+  revert_session_install
   restart_daemon
-  sleep 20
-  is_healthy && log "rolled back to $CUR (healthy)" || log "ROLLBACK health still failing on $CUR — needs operator"
+  [ "$HEALTH_WAIT" -gt 0 ] && sleep 20
+  if is_healthy; then
+    log "rolled back to $CUR (healthy)"
+    write_last "$CUR" "$LATEST" false true "unhealthy-rolled-back"
+  else
+    log "ROLLBACK health still failing on $CUR — needs operator"
+    write_last "$CUR" "$LATEST" false false "rollback-unhealthy"
+  fi
 fi