agentradar-cli 0.1.1 → 0.1.3

package/dist/vendor-runner/session-frame.mjs

@@ -0,0 +1,119 @@
+// ===========================================================================
+// I2 — session injection frame (pure, testable).
+//   The interactive-host variant of the vendor runner does NOT spawn a fresh claude
+//   per event; it injects each drained event as the NEXT turn of a persistent,
+//   always-on claude running in a tmux pane (real in-session continuity). These pure
+//   helpers build (a) the single-line frame the agent sees and (b) the exact tmux
+//   send-keys argv. Kept dependency-free so they run under `node --test`.
+//
+//   Two hard requirements bake in here:
+//     1. EXPLICIT conversationId — the frame tells the agent which conversation to
+//        reply into, so `reply` never has to guess "most-recent" under concurrent
+//        turns (the concurrent-turn robustness the lead/disc flagged).
+//     2. SINGLE LINE — a TUI submits on the first newline, so the frame must be one
+//        line (no embedded \n) to land as exactly one turn on send-keys + Enter.
+// ===========================================================================
+
+/** Collapse any whitespace/newlines to single spaces so the frame stays ONE line. */
+function oneLine(s) {
+  return String(s ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Build the single-line injection frame for one drained next_event event.
+ * event: { eventId, source, channel?, conversationId?, text }
+ * Returns a one-line string safe to `tmux send-keys -l` then Enter.
+ */
+export function formatInjectionFrame(event) {
+  const e = event ?? {};
+  const tags = [`source=${e.source ?? "unknown"}`];
+  if (e.channel) tags.push(`channel=${e.channel}`);
+  if (e.conversationId) tags.push(`conversationId=${e.conversationId}`);
+  if (e.eventId) tags.push(`eventId=${e.eventId}`);
+  const header = `[AgentRadar inbound · ${tags.join(" · ")}]`;
+  const body = oneLine(e.text) || "(no text)";
+  const evId = e.eventId ? String(e.eventId) : null;
+  // The reply instruction pins the EXPLICIT conversationId (threading) + inResponseToEventId
+  // (exact provenance under concurrent same-conversation turns — disc S2).
+  const parts = [];
+  if (e.conversationId) {
+    parts.push(
+      `Reply via your MCP \`reply\` tool with conversationId="${e.conversationId}"${evId ? ` and inResponseToEventId="${evId}"` : ""} (do NOT guess the channel).`,
+    );
+  } else {
+    parts.push(`Reply via your MCP \`reply\` tool${evId ? ` with inResponseToEventId="${evId}"` : ""}.`);
+  }
+  // L2 (disc #104): the feeder is at-least-once — a crash in the deliver→ack window
+  // re-injects this event. Tying report_usage's idempotencyKey to THIS eventId makes a
+  // re-delivery a no-op charge (#65 dedups on key) instead of a double bill, while a
+  // per-line suffix keeps distinct usage lines separate.
+  if (evId) {
+    parts.push(
+      `For billable work call \`report_usage\` with an idempotencyKey derived from this eventId (e.g. "${evId}:<usage-code>") so a re-delivered event never double-charges.`,
+    );
+  } else {
+    parts.push("Use `report_usage` for billable work.");
+  }
+  parts.push("Then stop.");
+  return oneLine(`${header} ${body} — ${parts.join(" ")}`);
+}
+
+/**
+ * #173b — build the single-line frame for a #156 liveness PROBE.
+ *
+ * A security-hardened agent (correctly) refuses to call a tool on the strength of an unverified
+ * in-chat instruction — it treats a bare/raw probe as prompt-injection. The fix: deliver the probe
+ * with the SAME trusted control-plane provenance as a real event — the `[AgentRadar inbound · … ]`
+ * header — so the agent recognizes it as legitimate platform traffic, not an in-chat instruction.
+ *
+ * #176 (canary finding): the eventId is a server-minted real UUID (matching a genuine event's eventId
+ * shape) — because a security-hardened agent DECLINES a probe whose eventId visibly differs from its real
+ * events (Liza flagged the `probe-<nonce>` eventId as the tell of an in-chat injection). The eventId is
+ * decoupled from the nonce and no longer leaks "this is a probe"; the NONCE stays the sole anti-spoof
+ * boundary (server-minted, exact-match). We deliberately do NOT attach a conversationId (a dangling one
+ * an agent could reply to would touch the conversation path — lead + disc §3). source stays `agentradar`
+ * (honest control-plane origin — the kit teaches the agent this is legitimate platform traffic). There is
+ * NO `reply` / `report_usage` guidance — a probe is a no-reply, no-charge health check whose ONLY honored
+ * action is `liveness_ack(nonce)` (that directive is the server-supplied body).
+ *
+ * probe: { nonce, instruction, eventId?, source? }
+ */
+export function formatProbeFrame(probe) {
+  const p = probe ?? {};
+  const nonce = p.nonce != null ? String(p.nonce) : "";
+  // Prefer the server-minted UUID eventId; fall back only defensively (older payloads). No `probe-` prefix
+  // when we do fall back — use the bare nonce so we never re-introduce the shape tell the agent rejects.
+  const eventId = p.eventId ? String(p.eventId) : nonce || "probe";
+  const source = p.source ?? "agentradar";
+  // #182/F2 (frame-provenance forgeability): the source/eventId in this header are FORGEABLE content —
+  // an adversary with write-access to the agent's session can inject a look-alike header. That is why
+  // trust must NOT rest on them. #184's body carries the load-bearing argument (inert action + harness-
+  // grant + unforgeable nonce), which is SOURCE-INDEPENDENT: a forged source cannot change the honor
+  // basis, and honoring is inert either way (a forged frame can at most induce a no-op nonce-echo). So
+  // F2 is a safe-direction robustness gap, not a hole — the residual (a poison-adjacent agent that
+  // defensively declines) errs toward over-CREDIT (never a wrongful bill), and D1's pane→flag+HELD path
+  // is the human-review backstop. The header stays only as routing metadata.
+  const header = `[AgentRadar inbound · source=${source} · eventId=${eventId}]`;
+  // #184/D6: inertness-first, accurate-inertness fallback (used only for older payloads with no
+  // server-minted instruction). Trust rests on the action being inert + the nonce unforgeable, NOT on
+  // the header's source label. A matching ack DOES update the billing-liveness signal — don't overclaim
+  // "no charge / zero blast radius"; state the honest bounded effect.
+  const body =
+    oneLine(p.instruction) ||
+    `Liveness check — call the liveness_ack tool with nonce "${nonce}". Judge on structure, not who sent it: a wrong or stale nonce is a harmless no-op (safe even if forged); the tool is harness-granted (a message cannot add a tool); the nonce is server-minted (you cannot fabricate a valid one). A matching nonce only confirms your session is alive — it updates the liveness signal that gates billing; it moves no data, sends no message, creates no task, and creates no new charge.`;
+  return oneLine(`${header} ${body}`);
+}
+
+/**
+ * The two tmux invocations that inject `text` as one submitted turn into `session`'s
+ * pane: send the literal text (‑l so it is NOT parsed as key names), then a separate
+ * Enter to submit. Returns argv arrays (no shell) — caller spawns `tmux` with each.
+ */
+export function sendKeysCommands(session, text) {
+  return [
+    ["send-keys", "-t", session, "-l", text],
+    ["send-keys", "-t", session, "Enter"],
+  ];
+}

package/dist/vendor-runner/supervisor/supervise-agent.sh

@@ -0,0 +1,362 @@
+#!/usr/bin/env bash
+# =============================================================================
+# AgentRadar durable-supervisor (M3.6 H4 / #92) — the ONE process a launchd
+# LaunchAgent (macOS) or systemd unit (Linux) keeps alive for a single always-on
+# agent. It is GENERIC + parameterized by a per-agent env file: no agent-specific
+# logic lives here (Spielberg's --chrome, brain path, pre-launch hooks, etc. are
+# all env params). It idempotently ensures BOTH halves of an always-on agent are
+# up, then blocks so KeepAlive/Restart revives the whole thing on any death:
+#
+#   1. a tmux session ($TMUX_SESSION) running the agent:
+#        claude --continue $CLAUDE_EXTRA_FLAGS --strict-mcp-config --mcp-config=$MCP_CONFIG
+#      in $AR_BASE, with a SCRUBBED allowlist env + a FRESH $CLAUDE_CONFIG_DIR
+#      (so the agent sees ONLY the AgentRadar MCP — no operator connectors);
+#   2. the feeder ($FEEDER_JS) OUTSIDE that session, holding $AWP_BEARER, long-
+#      polling next_event and tmux-injecting each event into the pane.
+#
+# Durability: crash of either half → this script exits non-zero → KeepAlive
+# (launchd) / Restart=always (systemd) restarts it → both re-ensured (idempotent).
+# Power-loss reboot → RunAtLoad (launchd) / WantedBy=default.target (systemd)
+# starts it on boot → same. Composes with the stateless AWP MCP (#111/#112:
+# reconnect, no -32001) + `claude --continue` (context resumes) = hands-free revive.
+#
+# HARD RULE: claude.ai OAuth ONLY. Refuses to start if ANTHROPIC_API_KEY is set.
+# =============================================================================
+set -euo pipefail
+
+log() { printf '%s [supervise-agent%s] %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "${AGENT_NAME:+:$AGENT_NAME}" "$*"; }
+die() { log "FATAL: $*"; exit 1; }
+
+# A launchd LaunchAgent (macOS) / systemd unit gives a MINIMAL PATH (typically /usr/bin:/bin) that
+# lacks Homebrew — where tmux / claude / node live on a dev box. Without this, `command -v tmux` fails
+# on boot and the supervisor crash-loops ("tmux not found"). Prepend the common tool dirs (Apple-Silicon
+# + Intel Homebrew) so the unit finds them; this PATH also flows to the scrubbed agent launch below.
+export PATH="/opt/homebrew/bin:/usr/local/bin:${PATH:-/usr/bin:/bin}"
+
+# --- 1. Load the per-agent env ------------------------------------------------
+# Env file: $1, or $AGENT_ENV, or ~/.agentradar/agents/<name>.env
+ENV_FILE="${1:-${AGENT_ENV:-}}"
+if [ -z "${ENV_FILE}" ] && [ -n "${AGENT_NAME:-}" ]; then
+  ENV_FILE="${HOME}/.agentradar/agents/${AGENT_NAME}.env"
+fi
+[ -n "${ENV_FILE}" ] || die "no agent env file (pass a path, or set AGENT_ENV / AGENT_NAME)"
+[ -f "${ENV_FILE}" ] || die "agent env file not found: ${ENV_FILE}"
+set -a
+# shellcheck source=/dev/null
+. "${ENV_FILE}"
+set +a
+
+# --- 2. Validate + defaults ---------------------------------------------------
+: "${AGENT_NAME:?AGENT_NAME required in env}"
+: "${AR_BASE:?AR_BASE required (the agent working dir)}"
+: "${AWP_MCP_URL:?AWP_MCP_URL required}"
+: "${AWP_BEARER:?AWP_BEARER required}"
+# CLAUDE_CODE_OAUTH_TOKEN is OPTIONAL. If SET → claude uses the setup-token (bills "API Usage",
+# subject to the org spend cap). If UNSET → claude falls through to SUBSCRIPTION OAuth (keychain login,
+# a one-time `/login`) → draws on the Max plan's included usage. Either way it's claude.ai auth only —
+# ANTHROPIC_API_KEY is still hard-refused below (never a pay-as-you-go key).
+: "${CLAUDE_CODE_OAUTH_TOKEN:=}"
+: "${MCP_CONFIG:?MCP_CONFIG required (path to awp-only.json)}"
+TMUX_SESSION="${TMUX_SESSION:-${AGENT_NAME}}"
+CLAUDE_CONFIG_DIR="${CLAUDE_CONFIG_DIR:-${HOME}/.agentradar/config/${AGENT_NAME}}"
+FEEDER_JS="${FEEDER_JS:-$(cd "$(dirname "$0")/.." && pwd)/feeder.mjs}"
+PANE_LIVE_SH="${PANE_LIVE_SH:-$(cd "$(dirname "$0")/.." && pwd)/pane-live.sh}"
+# #133 M4 live terminal — the OPTIONAL feeder bridge (streams the tmux pane to the portals). It's an
+# INDEPENDENT process that NEVER touches the liveness poll loop; its death is best-effort-restarted and
+# never exits the supervisor (the terminal view is nice-to-have; the feeder + agent are billing-critical).
+BRIDGE_JS="${BRIDGE_JS:-$(cd "$(dirname "$0")/.." && pwd)/terminal-bridge.mjs}"
+TERMINAL_BRIDGE_ENABLED="${TERMINAL_BRIDGE_ENABLED:-1}"
+CLAUDE_BIN="${CLAUDE_BIN:-claude}"
+TMUX_BIN="${TMUX_BIN:-tmux}"
+CLAUDE_EXTRA_FLAGS="${CLAUDE_EXTRA_FLAGS:-}"          # e.g. "--chrome" (Spielberg/Sam); empty (Liza)
+PRE_LAUNCH_HOOK="${PRE_LAUNCH_HOOK:-}"                # optional per-agent script run once before claude
+BROWSER_APP="${BROWSER_APP:-Google Chrome}"          # #150: app to ensure-up for --chrome agents (macOS)
+BROWSER_READY_MAX_SEC="${BROWSER_READY_MAX_SEC:-20}" # #150: bounded wait for the browser proc on cold boot
+BROWSER_READY_SETTLE_SEC="${BROWSER_READY_SETTLE_SEC:-3}" # #150: settle for extension/native-host after cold launch
+HEALTH_POLL_SEC="${HEALTH_POLL_SEC:-15}"
+# Pane-alive predicate — MUST be unique per agent. Default to the FULL mcp-config path (each agent's
+# differs by directory), NOT the basename: on a multi-agent box every agent's config is named
+# `awp-only.json`, so a basename match would find ANOTHER agent's live claude and mask THIS agent's
+# death (silent death — the exact failure #145 kills). Override per agent for extra scoping if needed.
+AGENT_PID_PATTERN="${AGENT_PID_PATTERN:-mcp-config.*${MCP_CONFIG}}"
+
+# Optional per-agent TOOL credentials — a vendor brain's OWN MCP-tool API keys (e.g. an SEO agent's
+# WEBFLOW_TOKEN / PERPLEXITY_API_KEY). These are ADDED to the scrubbed launch env so the agent's own
+# tool servers (declared in its --mcp-config) get their creds, WITHOUT widening the daemon's
+# inheritance: AWP_BEARER and everything else the supervisor holds still NEVER reach the pane. Point
+# AGENT_TOOL_ENV_FILE at a 0600 file of KEY=VALUE lines (blank / `#`-comment lines ignored). Only
+# well-formed KEY=VALUE entries pass through; anything else is warned + skipped. This reproduces a
+# non-isolated launcher that used to `. tool.env` before claude, but keeps the strict allowlist.
+AGENT_TOOL_ENV_FILE="${AGENT_TOOL_ENV_FILE:-}"
+TOOL_ENV_ARGS=()
+if [ -n "${AGENT_TOOL_ENV_FILE}" ]; then
+  [ -f "${AGENT_TOOL_ENV_FILE}" ] || die "AGENT_TOOL_ENV_FILE not found: ${AGENT_TOOL_ENV_FILE}"
+  while IFS= read -r _tline || [ -n "${_tline}" ]; do
+    _tline="${_tline#"${_tline%%[![:space:]]*}"}"        # left-trim whitespace
+    case "${_tline}" in ''|'#'*) continue ;; esac        # skip blanks + comments
+    _tline="${_tline#export }"                            # tolerate a leading `export `
+    case "${_tline}" in
+      [A-Za-z_][A-Za-z0-9_]*=*) : ;;                      # a well-formed KEY=VALUE — fall through
+      *) log "WARN ignoring non KEY=VALUE line in ${AGENT_TOOL_ENV_FILE}"; continue ;;
+    esac
+    # Defence-in-depth: a tool file must NOT shadow a reserved supervisor/agent var (isolation +
+    # identity). Reject at parse time (visible warning) AND — belt-and-suspenders — the launch lists
+    # the reserved allowlist AFTER TOOL_ENV_ARGS so `env` last-wins keeps reserved vars authoritative.
+    case "${_tline%%=*}" in
+      HOME|PATH|USER|LOGNAME|SHELL|TERM|COLORTERM|LANG|LC_ALL|LC_CTYPE|TMPDIR|NODE_OPTIONS|CLAUDE_CONFIG_DIR|CLAUDE_CODE_OAUTH_TOKEN|AR_OAUTH_TOKEN_FILE|AR_TOOL_ENV_FILE|ANTHROPIC_API_KEY|AWP_BEARER|AWP_BEARER_FILE|AWP_MCP_URL|TMUX_SESSION|AGENT_PID_PATTERN)
+        log "WARN ignoring reserved key '${_tline%%=*}' in ${AGENT_TOOL_ENV_FILE} (cannot override supervisor/agent env)"; continue ;;
+    esac
+    TOOL_ENV_ARGS+=("${_tline}")
+  done < "${AGENT_TOOL_ENV_FILE}"
+  log "loaded ${#TOOL_ENV_ARGS[@]} tool-env var(s) from ${AGENT_TOOL_ENV_FILE}"
+fi
+
+# HARD RULE — OAuth only, never a pay-as-you-go API key.
+[ -z "${ANTHROPIC_API_KEY:-}" ] || die "ANTHROPIC_API_KEY is set — refuse to start (claude.ai OAuth only)"
+
+command -v "${TMUX_BIN}" >/dev/null 2>&1 || die "tmux not found (${TMUX_BIN})"
+command -v "${CLAUDE_BIN}" >/dev/null 2>&1 || die "claude CLI not found (${CLAUDE_BIN})"
+[ -f "${FEEDER_JS}" ] || die "feeder not found: ${FEEDER_JS}"
+[ -f "${PANE_LIVE_SH}" ] || die "pane liveness check not found: ${PANE_LIVE_SH}"
+[ -d "${AR_BASE}" ] || die "AR_BASE dir not found: ${AR_BASE}"
+mkdir -p "${CLAUDE_CONFIG_DIR}"
+
+# --- 2b. Credential hygiene (#152): secrets to 0600 files, OUT of argv+env ------
+# The AWP bearer (feeder) and — when used — the OAuth setup-token (claude) must not linger in any
+# long-lived process's ARGV (`ps aux`) or ENVIRONMENT (`ps eww`), where a co-resident process on the
+# box could read them. We stage them into per-agent 0600 files and hand each consumer the FILE PATH
+# (not a secret): the feeder reads AWP_BEARER_FILE; the scrubbed claude wrapper reads AR_OAUTH_TOKEN_FILE.
+# Then we UNSET the raw vars from this supervisor's env so neither the supervisor nor the feeder it
+# spawns inherits them. (The agent's own outbound bearer already lives only in awp-only.json @0600.)
+_SECRETS_DIR="${HOME}/.agentradar/run/${AGENT_NAME}"
+( umask 077; mkdir -p "${_SECRETS_DIR}" )
+chmod 700 "${_SECRETS_DIR}" 2>/dev/null || true
+_BEARER_FILE="${_SECRETS_DIR}/awp_bearer"
+( umask 077; printf '%s' "${AWP_BEARER}" > "${_BEARER_FILE}" )
+AWP_BEARER_FILE="${_BEARER_FILE}"
+unset AWP_BEARER   # drop from the supervisor's exported env → feeder no longer inherits it; ps eww clean
+# OAuth setup-token: same treatment. `set -a; . ENV_FILE` EXPORTS CLAUDE_CODE_OAUTH_TOKEN into the
+# supervisor env, from which the feeder (spawned WITHOUT env -i) would inherit it → ps eww leak. So when
+# it's set, stage it to a 0600 file and UNSET the raw var here (mirror of the bearer). ensure_agent then
+# passes ONLY AR_OAUTH_TOKEN_FILE (the path) on the scrubbed env -i line, and the sh wrapper reads it into
+# claude's env just before exec. When UNSET (subscription-login mode) _OAUTH_TOKEN_FILE stays empty → the
+# claude launch is a pure no-op and falls through to subscription OAuth (no API-billing regression).
+_OAUTH_TOKEN_FILE=""
+if [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]; then
+  _OAUTH_TOKEN_FILE="${_SECRETS_DIR}/oauth_token"
+  ( umask 077; printf '%s' "${CLAUDE_CODE_OAUTH_TOKEN}" > "${_OAUTH_TOKEN_FILE}" )
+fi
+unset CLAUDE_CODE_OAUTH_TOKEN   # out of the supervisor+feeder env (ps eww); staged to the 0600 file above
+# Vendor MCP-tool creds (#166): the agent's OWN tool API keys (WEBFLOW_TOKEN, PERPLEXITY_API_KEY, …) were
+# being passed INLINE as KEY=VALUE on the env -i line → stored PLAINTEXT in tmux's pane_start_command
+# (`tmux list-panes` = any co-resident proc) and in claude's env (ps eww). Same inline-secret class as the
+# bearer/token. Stage the already-validated entries to a 0600 file and pass ONLY AR_TOOL_ENV_FILE (a PATH);
+# the wrapper reads+exports them just before exec, so the VALUES never appear on the pane command / argv
+# (still in claude's env by necessity, exactly like the OAuth token — acceptable, same-user only).
+_TOOL_ENV_FILE=""
+if [ "${#TOOL_ENV_ARGS[@]}" -gt 0 ]; then
+  _TOOL_ENV_FILE="${_SECRETS_DIR}/tool_env"
+  ( umask 077; : > "${_TOOL_ENV_FILE}"; for _kv in "${TOOL_ENV_ARGS[@]}"; do printf '%s\n' "${_kv}" >> "${_TOOL_ENV_FILE}"; done )
+  TOOL_ENV_ARGS=()   # #166: no longer passed inline on the env -i line
+fi
+
+session_exists() { "${TMUX_BIN}" has-session -t "${TMUX_SESSION}" 2>/dev/null; }
+pane_alive() {
+  TMUX_BIN="${TMUX_BIN}" TMUX_SESSION="${TMUX_SESSION}" AGENT_PID_PATTERN="${AGENT_PID_PATTERN}" \
+    /bin/sh "${PANE_LIVE_SH}"
+}
+
+# #150: for a --chrome agent, ensure the browser app is up BEFORE claude launches. `claude --chrome`
+# connects to a running browser via the native-messaging host; if the browser isn't up at connect time
+# the connection can fail. Generalized from Sam's per-agent PRE_LAUNCH_HOOK so ANY --chrome vendor agent
+# is robust-by-construction. Idempotent (`open -ga` never spawns a second instance; -g = don't foreground).
+# Overridable via BROWSER_APP (default "Google Chrome"). macOS-only; documented no-op elsewhere (on Linux,
+# launch the browser in your runner env / at login). Belt-and-suspenders alongside a Login-Items entry.
+ensure_browser() {
+  case " ${CLAUDE_EXTRA_FLAGS} " in
+    *" --chrome "*) : ;;   # --chrome as a WHOLE space-bounded token (won't false-match e.g. --chromeless)
+    *) return 0 ;;         # not a --chrome agent → nothing to do
+  esac
+  if ! command -v open >/dev/null 2>&1; then
+    log "NOTE --chrome set but no macOS 'open'; ensure '${BROWSER_APP}' is running out-of-band (e.g. launch it at login in your runner env)"
+    return 0
+  fi
+  # WARM path (common): browser already up → extension/native-host already initialized, no wait needed.
+  if pgrep -f "${BROWSER_APP}" >/dev/null 2>&1; then
+    log "browser '${BROWSER_APP}' already up — --chrome can connect"
+    return 0
+  fi
+  # COLD path (#150 + disc's race fix): `open -ga` returns BEFORE the app is actually up, so claude --chrome
+  # could race ahead and hit the native-host connect dialog. Launch, then BOUNDED-wait for the browser
+  # process to appear (poll pgrep up to BROWSER_READY_MAX_SEC), then a short settle for the extension/
+  # native-host to initialize. Degrades gracefully — never hangs (proceeds with a WARN on timeout).
+  log "browser '${BROWSER_APP}' not up (cold) — launching + waiting for readiness"
+  open -ga "${BROWSER_APP}" 2>/dev/null || log "WARN could not launch '${BROWSER_APP}' (continuing; --chrome may fail to connect)"
+  _bw=0
+  while [ "${_bw}" -lt "${BROWSER_READY_MAX_SEC}" ]; do
+    if pgrep -f "${BROWSER_APP}" >/dev/null 2>&1; then
+      log "browser process up after ${_bw}s; settling ${BROWSER_READY_SETTLE_SEC}s for extension/native-host"
+      sleep "${BROWSER_READY_SETTLE_SEC}"
+      return 0
+    fi
+    sleep 1; _bw=$((_bw + 1))
+  done
+  log "WARN browser '${BROWSER_APP}' not detected within ${BROWSER_READY_MAX_SEC}s — launching --chrome anyway (it will retry-connect)"
+}
+
+# --- 3. Ensure the agent's tmux+claude session (idempotent) -------------------
+ensure_agent() {
+  if session_exists && pane_alive; then
+    log "agent session '${TMUX_SESSION}' already live"
+    return 0
+  fi
+  if session_exists && ! pane_alive; then
+    log "session '${TMUX_SESSION}' exists but claude pane is dead — recreating"
+    "${TMUX_BIN}" kill-session -t "${TMUX_SESSION}" 2>/dev/null || true
+  fi
+  ensure_browser   # #150: bring up the browser first for --chrome agents (idempotent, no-op otherwise)
+  if [ -n "${PRE_LAUNCH_HOOK}" ] && [ -x "${PRE_LAUNCH_HOOK}" ]; then
+    log "running pre-launch hook: ${PRE_LAUNCH_HOOK}"
+    "${PRE_LAUNCH_HOOK}" || log "WARN pre-launch hook exited non-zero (continuing)"
+  fi
+  # SCRUBBED launch: env -i with a strict allowlist so the agent inherits nothing from this daemon
+  # (AWP_BEARER, AWP_MCP_URL, etc. never reach the pane). CONNECTOR ISOLATION is enforced by
+  # --strict-mcp-config (the agent loads ONLY $MCP_CONFIG's servers) — NOT by the config dir, which is
+  # deliberately the agent's EXISTING CLAUDE_CONFIG_DIR (often the shared ~/.claude) so `claude
+  # --continue` resumes the real conversation. The agent's own tool creds (from AGENT_TOOL_ENV_FILE) are
+  # NOT inlined here anymore (#166): they were staged to a 0600 file in 2b and are passed only as the PATH
+  # AR_TOOL_ENV_FILE, which the wrapper reads+exports before exec — so no tool VALUE appears on the env -i
+  # argv / tmux pane_start_command. Reserved keys were already rejected at tool-file parse time (2b).
+  log "starting agent in tmux '${TMUX_SESSION}' (flags: ${CLAUDE_EXTRA_FLAGS:-none}; tool-env file: ${_TOOL_ENV_FILE:-none})"
+  # SC2086: CLAUDE_EXTRA_FLAGS is intentionally UNQUOTED so "--chrome" (etc.) word-splits into flags.
+  # _tool_env / _oauth_env use the ${arr[@]+"${arr[@]}"} form so an EMPTY array is safe under `set -u` (bash 3.2).
+  # First-launch handling (#153/H4 durable-feeder): `claude --continue` EXITS 1 when the cwd has NO prior
+  # conversation (a fresh engagement folder / brand-new CLAUDE_CONFIG_DIR) → the pane dies → the supervisor
+  # crash-loops. So try `--continue`, and FALL BACK to a fresh `claude` (which stays up AND creates the
+  # session) when there's nothing to resume. Self-healing: once a conversation exists, --continue resumes it;
+  # if it's ever lost, we cleanly start fresh instead of exit-looping. (--continue exits 1 on no-session,
+  # verified — so the `||` fallback is reliable.) The `/bin/sh -c` wrapper keeps EXTRA_FLAGS word-splitting.
+  # shellcheck disable=SC2086
+  _launch_flags=( ${CLAUDE_EXTRA_FLAGS} --strict-mcp-config --mcp-config="${MCP_CONFIG}" )
+  # OAuth setup-token (#152): the token was already staged to a 0600 file + UNSET from this env in section
+  # 2b (so it's off both the supervisor+feeder env / ps eww). Here we only pass AR_OAUTH_TOKEN_FILE (a PATH,
+  # not the secret) on the env -i line — so the token is NOT in the `env`/claude argv (`ps aux`) either. The
+  # wrapper below reads the file into CLAUDE_CODE_OAUTH_TOKEN just before exec'ing claude. When it was UNSET
+  # (subscription-login mode) _OAUTH_TOKEN_FILE is empty → we pass NOTHING token-related and the wrapper's
+  # read is a no-op → claude falls through to subscription OAuth exactly as before. bash 3.2-safe array form.
+  _oauth_env=()
+  [ -n "${_OAUTH_TOKEN_FILE}" ] && _oauth_env=( AR_OAUTH_TOKEN_FILE="${_OAUTH_TOKEN_FILE}" )
+  # #166: pass the tool creds as a FILE PATH (AR_TOOL_ENV_FILE), never inline KEY=VALUE on env -i.
+  _tool_env=()
+  [ -n "${_TOOL_ENV_FILE}" ] && _tool_env=( AR_TOOL_ENV_FILE="${_TOOL_ENV_FILE}" )
+  # #1: do NOT inherit TERM. Under launchd the supervisor's TERM is `dumb` (or absent), and `dumb` is
+  # neither unset nor empty, so the old `${TERM:-xterm-256color}` default never fired and the agent's
+  # claude ran with TERM=dumb. chalk/ink then disable colour ENTIRELY, so the TUI emitted zero SGR —
+  # measured: a real agent pane captured with `capture-pane -ep` was 3216 bytes with ZERO ESC bytes,
+  # against a control pane that showed 2. That, not any client-side defect, is why the live terminal
+  # rendered monochrome in both portals. The pane lives inside tmux, so match tmux's own
+  # `default-terminal` (tmux-256color); `infocmp tmux-256color` is present on the fleet mini. Both are
+  # overridable per agent via AR_AGENT_TERM / AR_AGENT_COLORTERM — names NO shell sets, which is the
+  # whole point: defaulting off `${TERM:-…}` is exactly the construct that already failed silently.
+  #
+  # LC_CTYPE was previously passed EMPTY, which leaves the agent in the C/POSIX character type even
+  # though LANG says UTF-8 — that garbles claude's `╭─╮` / `⏵⏵` box-drawing glyphs, which only becomes
+  # visible once there is colour to look at. LC_ALL stays empty on purpose: an empty LC_ALL does not
+  # override, so LC_CTYPE governs and a vendor can still set LANG per agent.
+  #
+  # 🔴 This comment block lives ABOVE the command, not inside it. A `#` comment between two
+  # `\`-continued lines TERMINATES the command at its unescaped newline: tmux would receive only the
+  # args up to SHELL=…, the pane would start with no `claude` at all, and the `TERM=… claude` tail
+  # would run as a separate, UNISOLATED command in the supervisor's own shell. `bash -n` passes on
+  # that — it is semantic, not syntactic — and a colour gate cannot see it either, because a pane that
+  # never starts has nothing to colour. Caught by disc counting the args tmux actually received.
+  "${TMUX_BIN}" new-session -d -s "${TMUX_SESSION}" -c "${AR_BASE}" \
+    env -i \
+      HOME="${HOME}" PATH="${PATH}" USER="${USER:-}" LOGNAME="${LOGNAME:-}" SHELL="${SHELL:-/bin/sh}" \
+      TERM="${AR_AGENT_TERM:-tmux-256color}" COLORTERM="${AR_AGENT_COLORTERM:-truecolor}" \
+      LANG="${LANG:-en_US.UTF-8}" LC_ALL="${LC_ALL:-}" LC_CTYPE="${AR_AGENT_LC_CTYPE:-en_US.UTF-8}" \
+      TMPDIR="${TMPDIR:-/tmp}" NODE_OPTIONS="${NODE_OPTIONS:-}" \
+      DISABLE_AUTOUPDATER=1 \
+      ${_tool_env[@]+"${_tool_env[@]}"} ${_oauth_env[@]+"${_oauth_env[@]}"} CLAUDE_CONFIG_DIR="${CLAUDE_CONFIG_DIR}" \
+      /bin/sh -c 'if [ -n "${AR_TOOL_ENV_FILE:-}" ]; then while IFS= read -r _l || [ -n "$_l" ]; do case "$_l" in ""|\#*) continue ;; esac; _k=${_l%%=*}; _v=${_l#*=}; case "$_k" in HOME|PATH|USER|LOGNAME|SHELL|TERM|COLORTERM|LANG|LC_ALL|LC_CTYPE|TMPDIR|NODE_OPTIONS|CLAUDE_CONFIG_DIR|CLAUDE_CODE_OAUTH_TOKEN|AR_OAUTH_TOKEN_FILE|AR_TOOL_ENV_FILE|ANTHROPIC_API_KEY|AWP_BEARER|AWP_BEARER_FILE|AWP_MCP_URL|TMUX_SESSION|AGENT_PID_PATTERN) continue ;; esac; export "$_k=$_v"; done < "$AR_TOOL_ENV_FILE"; unset AR_TOOL_ENV_FILE _l _k _v; fi; if [ -n "${AR_OAUTH_TOKEN_FILE:-}" ]; then CLAUDE_CODE_OAUTH_TOKEN="$(cat "$AR_OAUTH_TOKEN_FILE")"; export CLAUDE_CODE_OAUTH_TOKEN; unset AR_OAUTH_TOKEN_FILE; fi; CB="$1"; shift; "$CB" --continue "$@" || exec "$CB" "$@"' sh "${CLAUDE_BIN}" "${_launch_flags[@]}" || {
+        log "tmux could not start agent session '${TMUX_SESSION}'"
+        return 1
+      }
+  # wait for the pane to come up
+  for _ in $(seq 1 30); do pane_alive && { log "agent pane is live"; return 0; }; sleep 1; done
+  log "agent pane did not come up within 30s"
+  return 1
+}
+
+# --- 4. Run: ensure agent, run feeder in foreground, monitor both -------------
+FEEDER_PID=""
+cleanup() {
+  [ -n "${FEEDER_PID}" ] && kill "${FEEDER_PID}" 2>/dev/null || true
+  [ -n "${BRIDGE_PID:-}" ] && kill "${BRIDGE_PID}" 2>/dev/null || true   # #133 terminal bridge
+  # #152: remove the staged 0600 secret files (bearer + optional oauth token) on exit.
+  [ -n "${_SECRETS_DIR:-}" ] && rm -rf "${_SECRETS_DIR}" 2>/dev/null || true
+}
+trap cleanup EXIT INT TERM
+
+until ensure_agent; do
+  log "agent start failed — retrying in ${HEALTH_POLL_SEC}s"
+  sleep "${HEALTH_POLL_SEC}"
+done
+
+log "starting feeder (${FEEDER_JS}) → session '${TMUX_SESSION}'"
+# #152: pass AWP_BEARER_FILE (a 0600 PATH), NEVER the raw AWP_BEARER — the feeder reads the file, so the
+# bearer is not in the feeder process's environment (`ps eww`) or argv. AWP_MCP_URL is not a secret.
+AWP_MCP_URL="${AWP_MCP_URL}" AWP_BEARER_FILE="${AWP_BEARER_FILE}" TMUX_SESSION="${TMUX_SESSION}" \
+  AGENT_PID_PATTERN="${AGENT_PID_PATTERN}" \
+  node "${FEEDER_JS}" &
+FEEDER_PID=$!
+log "feeder pid ${FEEDER_PID}"
+
+# #133 M4 — start the optional feeder bridge (best-effort, isolated). Same 0600 bearer FILE + session env
+# as the feeder; NEVER the raw bearer. Its failure NEVER affects the feeder/agent (nice-to-have terminal).
+BRIDGE_PID=""
+start_bridge() {
+  case "${TERMINAL_BRIDGE_ENABLED}" in
+    1|true|yes|on)
+      if [ -f "${BRIDGE_JS}" ]; then
+        AWP_MCP_URL="${AWP_MCP_URL}" AWP_BEARER_FILE="${AWP_BEARER_FILE}" TMUX_SESSION="${TMUX_SESSION}" \
+          node "${BRIDGE_JS}" &
+        BRIDGE_PID=$!
+        log "terminal bridge pid ${BRIDGE_PID}"
+      else
+        log "terminal bridge enabled but ${BRIDGE_JS} not found — skipping (pull the latest template)"
+      fi
+      ;;
+    *) log "terminal bridge disabled (TERMINAL_BRIDGE_ENABLED=${TERMINAL_BRIDGE_ENABLED})" ;;
+  esac
+}
+start_bridge
+
+# Monitor. Recover the agent pane in place so direct supervisor invocation survives pane death too;
+# launchd/systemd remains the parent-level/reboot safety net. The feeder self-pauses while the owned pane
+# next_event heartbeat cannot paint the runner Live during recovery. Restart the bridge after a new pane is
+# created because tmux pipe-pane was bound to the dead pane.
+while true; do
+  if ! kill -0 "${FEEDER_PID}" 2>/dev/null; then
+    log "feeder exited — exiting so the service manager restarts the whole unit"
+    exit 1
+  fi
+  if ! pane_alive; then
+    log "agent claude pane died — recovering it in place"
+    if ensure_agent; then
+      if [ -n "${BRIDGE_PID}" ]; then
+        kill "${BRIDGE_PID}" 2>/dev/null || true
+        wait "${BRIDGE_PID}" 2>/dev/null || true
+        BRIDGE_PID=""
+      fi
+      start_bridge
+    else
+      log "agent recovery failed — retrying in ${HEALTH_POLL_SEC}s"
+    fi
+  fi
+  if [ -n "${BRIDGE_PID}" ] && ! kill -0 "${BRIDGE_PID}" 2>/dev/null; then
+    log "terminal bridge exited — restarting in place (best-effort; does not affect feeder/agent)"
+    start_bridge
+  fi
+  sleep "${HEALTH_POLL_SEC}"
+done