@adaptic/maestro 1.10.0 → 1.10.2

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

@@ -0,0 +1,739 @@
+#!/usr/bin/env node
+// =============================================================================
+// Slack Socket Mode Listener — realtime DM + @mention ingestion
+// =============================================================================
+//
+// Replaces the 60s `slack-poller.mjs` and the 5s Railway webhook relay polling
+// for DM / @mention ingestion. Holds a persistent WebSocket to Slack's
+// Socket Mode endpoint and translates inbound message events to the same
+// inbox-item shape that `slack-poller.mjs` produces, then hands them to
+// `writeInboxItem` from `utils.mjs` (preserving the existing contract).
+//
+// Why Socket Mode over polling
+// ----------------------------
+// 1. Realtime — events arrive in <500ms instead of the 60s poll cycle.
+// 2. No rate-limit pressure — one persistent socket vs. ~25 API calls/cycle.
+// 3. No public webhook endpoint required — Slack pushes via outbound WSS.
+// 4. Aligns with Slack's recommended pattern for self-hosted agents.
+//
+// Requirements
+// ------------
+// - SLACK_APP_LEVEL_TOKEN (xapp-…) with `connections:write` scope
+// - SLACK_BOT_TOKEN (xoxb-…) for the optional API enrichment fallbacks
+// - Socket Mode enabled in the Slack app config
+// - Event subscriptions enabled with: message.channels, message.groups,
+//   message.im, message.mpim, app_mention
+//
+// Run: node scripts/poller/slack-socket-mode.mjs
+// Install: launchd plist with KeepAlive (SuccessfulExit:false, Crashed:true).
+//
+// Module exports a programmable surface (createSocketModeClient,
+// eventToInboxItem, etc.) so the test file can exercise translation +
+// reconnect logic without touching the network. The CLI invocation
+// (process.argv[1]) starts the daemon directly.
+// =============================================================================
+
+import { existsSync, readFileSync, mkdirSync, appendFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { writeInboxItem, resolvePrivilege, resolveName, AGENT_REPO_DIR } from "./utils.mjs";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Slack endpoint for opening a Socket Mode WSS connection.
+const APPS_CONNECTIONS_OPEN_URL = "https://slack.com/api/apps.connections.open";
+
+// Backoff defaults — exponential with cap. The first retry waits 1s, then
+// doubles each failure up to 60s. Reset on a clean `hello`.
+export const RECONNECT_INITIAL_MS = 1_000;
+export const RECONNECT_MAX_MS = 60_000;
+
+// How often we check .emergency-stop and refresh keep-alive state. Slack
+// sends `disconnect` (type: "disconnect") ~30 min into a session asking
+// us to reconnect; we just close + reconnect on the next tick.
+export const SUPERVISOR_INTERVAL_MS = 5_000;
+
+// Slack's recommended ping interval. The WS server sends `pings`; we
+// respond with `pong`. Most node ws implementations handle this for us,
+// but we also enqueue a heartbeat to surface stalls.
+export const HEARTBEAT_INTERVAL_MS = 30_000;
+export const HEARTBEAT_TIMEOUT_MS = 90_000;
+
+// ---------------------------------------------------------------------------
+// Env loader (mirrors slack-events-server.mjs — no dotenv dep)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read .env from the agent root and merge into process.env (existing keys
+ * win — we don't clobber values the operator deliberately set in their
+ * shell). No-op when .env is missing.
+ */
+export function loadEnvFromFile(agentRoot) {
+  const envPath = join(agentRoot, ".env");
+  if (!existsSync(envPath)) return;
+  const body = readFileSync(envPath, "utf-8");
+  for (const line of body.split("\n")) {
+    const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (!m) continue;
+    let val = m[2].trim();
+    if ((val.startsWith('"') && val.endsWith('"')) ||
+        (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    if (process.env[m[1]] === undefined || process.env[m[1]] === "") {
+      process.env[m[1]] = val;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Logging — JSONL to logs/polling/<date>-slack-socket.jsonl
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a structured log line. Best-effort; logging failures must never
+ * take the listener down. The log path mirrors the existing poller layout
+ * so downstream tooling (doctor, log rotation) keeps working unchanged.
+ */
+export function logLine(agentRoot, entry) {
+  try {
+    const dir = join(agentRoot, "logs", "polling");
+    mkdirSync(dir, { recursive: true });
+    const today = new Date().toISOString().slice(0, 10);
+    const file = join(dir, `${today}-slack-socket.jsonl`);
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n";
+    appendFileSync(file, line);
+  } catch {
+    /* logging must never propagate */
+  }
+}
+
+function info(agentRoot, message, data = {}) {
+  console.log(`[slack-socket] ${message}`);
+  logLine(agentRoot, { level: "info", message, ...data });
+}
+
+function warn(agentRoot, message, data = {}) {
+  console.warn(`[slack-socket] ${message}`);
+  logLine(agentRoot, { level: "warn", message, ...data });
+}
+
+function error(agentRoot, message, data = {}) {
+  console.error(`[slack-socket] ${message}`);
+  logLine(agentRoot, { level: "error", message, ...data });
+}
+
+// ---------------------------------------------------------------------------
+// Agent identity + known-agents registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Load `config/agent.json` and return a canonical identity object with safe
+ * defaults so callers never need to null-check.
+ */
+export function loadAgentIdentity(agentRoot) {
+  try {
+    const agent = JSON.parse(readFileSync(join(agentRoot, "config/agent.json"), "utf-8"));
+    return {
+      firstName: agent.firstName || "Agent",
+      fullName: agent.fullName || "Agent",
+      slackMemberId: agent.slackMemberId || "",
+      principalSlackId: agent.principal?.slackMemberId || "",
+    };
+  } catch {
+    return { firstName: "Agent", fullName: "Agent", slackMemberId: "", principalSlackId: "" };
+  }
+}
+
+/**
+ * Load peer agent Slack IDs from `config/known-agents.json` (or maestro
+ * install fallback). Excludes the running agent itself. Used by the
+ * filter that drops messages from other agents — so e.g. Sophie's Slack
+ * traffic doesn't trigger Ravi's daemon.
+ */
+export function loadPeerSlackIds(agentRoot, ownSlackId) {
+  const candidates = [
+    join(agentRoot, "config/known-agents.json"),
+    join(process.env.HOME || "/", "maestro/config/known-agents.json"),
+  ];
+  for (const path of candidates) {
+    try {
+      const raw = readFileSync(path, "utf-8");
+      const reg = JSON.parse(raw);
+      const ids = new Set();
+      for (const a of reg.agents || []) {
+        if (a?.slackId && a.slackId !== ownSlackId) ids.add(a.slackId);
+      }
+      if (ids.size > 0) return ids;
+    } catch {
+      /* try next */
+    }
+  }
+  return new Set();
+}
+
+// ---------------------------------------------------------------------------
+// Slack envelope filtering — DM, @mention, thread reply
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether a Slack event envelope is interesting to this agent.
+ *
+ * Returns { keep: boolean, reason: string }. The reason exists so the
+ * test suite (and ops triage) can assert exactly *why* an event was
+ * dropped or kept. Keep this function pure — no I/O, no globals beyond
+ * the identity/peers arguments.
+ */
+export function shouldKeepEvent(envelope, { ownSlackId, peerSlackIds }) {
+  if (!envelope || typeof envelope !== "object") {
+    return { keep: false, reason: "envelope-missing" };
+  }
+  if (envelope.type !== "events_api") {
+    return { keep: false, reason: `envelope-type-${envelope.type}` };
+  }
+  const event = envelope.payload?.event;
+  if (!event) return { keep: false, reason: "no-event" };
+
+  // Only message events. app_mention events come as `type: app_mention`
+  // but Slack also delivers a parallel `type: message` for the same text,
+  // so we normalise on the message handler and detect mentions inline.
+  // Allow `thread_broadcast` (a thread reply also broadcast to channel)
+  // through as a normal message; drop everything else.
+  if (event.type !== "message") return { keep: false, reason: `event-type-${event.type}` };
+  if (event.subtype && event.subtype !== "thread_broadcast" && event.subtype !== "file_share") {
+    return { keep: false, reason: `event-subtype-${event.subtype}` };
+  }
+
+  // Drop bot messages and the agent's own messages.
+  if (event.bot_id) return { keep: false, reason: "bot-message" };
+  if (event.user && ownSlackId && event.user === ownSlackId) {
+    return { keep: false, reason: "self-message" };
+  }
+
+  // Drop messages from peer agents — they're not customers and replying
+  // would loop two daemons forever.
+  if (event.user && peerSlackIds && peerSlackIds.has(event.user)) {
+    return { keep: false, reason: "peer-agent" };
+  }
+
+  // DM channels start with "D"; keep all of them.
+  const isDm = typeof event.channel === "string" && event.channel.startsWith("D");
+  if (isDm) return { keep: true, reason: "dm" };
+
+  // Channel messages — only keep if the agent is @-mentioned.
+  const text = typeof event.text === "string" ? event.text : "";
+  const mentionPattern = ownSlackId ? new RegExp(`<@${ownSlackId}(?:\\|[^>]*)?>`) : null;
+  if (mentionPattern && mentionPattern.test(text)) {
+    return { keep: true, reason: "mention" };
+  }
+
+  return { keep: false, reason: "no-mention-no-dm" };
+}
+
+// ---------------------------------------------------------------------------
+// Translation — Slack envelope → poller-compatible inbox item
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a Slack Socket Mode envelope to the same inbox-item shape that
+ * `slack-poller.mjs` produces. Pure function; all I/O happens at the caller.
+ *
+ * The output schema mirrors `slack-poller.mjs` exactly so `writeInboxItem`
+ * + the downstream daemon pipeline keep working without changes:
+ *   - `id` = ts with the dot replaced by a dash (matches poller convention)
+ *   - `service` = "slack"
+ *   - `channel` = friendly channel label ("dm/<sender-name>" for DMs,
+ *     channel id for channels — channel name resolution requires an API
+ *     call we'd rather avoid on the hot path; the daemon downstream can
+ *     fill in if needed)
+ *   - `priority_signals.mentions_agent` = true for DMs (1:1 context), true
+ *     when the regex matched, false otherwise.
+ */
+export function eventToInboxItem(envelope, { ownSlackId, principalSlackId, agentFirstName }) {
+  const event = envelope.payload.event;
+  const userId = event.user || "";
+  const text = event.text || "";
+  const ts = event.ts || "";
+  const channelId = event.channel || "";
+  const threadTs = event.thread_ts || "";
+  const isReply = !!threadTs && threadTs !== ts;
+  const isDm = typeof channelId === "string" && channelId.startsWith("D");
+
+  // Friendly labels. We can't resolve a channel name without an API call
+  // we'd rather not make per event; the agent's downstream tooling already
+  // handles channel-id → name resolution where needed.
+  const senderName = resolveName(userId);
+  const channelLabel = isDm ? `dm/${senderName}` : channelId;
+  const subject = isDm ? `DM from ${senderName}` : `#${channelLabel}`;
+
+  // Priority signal detection mirrors slack-poller.mjs.
+  const isCeo = !!principalSlackId && userId === principalSlackId;
+  const isUrgent = /\b(urgent|emergency|asap|blocker|critical)\b/i.test(text);
+  const mentionPattern = ownSlackId ? new RegExp(`<@${ownSlackId}(?:\\|[^>]*)?>`) : null;
+  const explicitlyMentioned = mentionPattern ? mentionPattern.test(text) : false;
+  const nameMention = !!agentFirstName && text.toLowerCase().includes(agentFirstName.toLowerCase());
+  const mentionsAgent = isDm || explicitlyMentioned || nameMention;
+
+  return {
+    id: ts.replace(".", "-"),
+    service: "slack",
+    channel: channelLabel,
+    channel_id: channelId,
+    sender: senderName,
+    sender_privilege: resolvePrivilege(userId),
+    timestamp: new Date(parseFloat(ts) * 1000).toISOString(),
+    subject,
+    content: text,
+    thread_id: threadTs || "",
+    thread_context: null, // Socket Mode doesn't include thread history.
+    is_reply: isReply,
+    priority_signals: {
+      from_ceo: isCeo,
+      tagged_urgent: isUrgent,
+      contains_deadline: false,
+      mentions_agent: mentionsAgent,
+    },
+    raw_ref: `slack:${channelId}:${ts}`,
+    source: "socket-mode",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Slack `apps.connections.open` — get a fresh WSS URL
+// ---------------------------------------------------------------------------
+
+/**
+ * Call apps.connections.open with the app-level token to obtain a WSS URL.
+ * Returns `{ url }` on success or `{ error }` on failure. The URL is
+ * single-use and expires quickly — call this every time we open a socket.
+ */
+export async function openSocketConnection({ appToken, fetchFn = fetch }) {
+  if (!appToken) {
+    return { error: "missing-app-token" };
+  }
+  let response;
+  try {
+    response = await fetchFn(APPS_CONNECTIONS_OPEN_URL, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${appToken}`,
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+    });
+  } catch (err) {
+    return { error: `network: ${err.message}` };
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    return { error: `parse: ${err.message}` };
+  }
+  if (!body.ok) {
+    return { error: body.error || "unknown-error" };
+  }
+  if (!body.url) {
+    return { error: "no-url-in-response" };
+  }
+  return { url: body.url };
+}
+
+// ---------------------------------------------------------------------------
+// Reconnect supervisor — exponential back-off with jitter
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the next reconnect delay using exponential back-off plus a small
+ * (0-25%) random jitter to avoid thundering-herd if multiple agents
+ * reconnect simultaneously.
+ */
+export function nextBackoffMs(currentMs, max = RECONNECT_MAX_MS) {
+  const doubled = Math.min(max, Math.max(RECONNECT_INITIAL_MS, currentMs * 2));
+  const jitter = Math.floor(Math.random() * 0.25 * doubled);
+  return Math.min(max, doubled + jitter);
+}
+
+// ---------------------------------------------------------------------------
+// Socket Mode client — the main orchestration loop
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Socket Mode client. The client is *programmable*: every external
+ * dependency (fetch, WebSocket constructor, clock, write-inbox-item) is
+ * injectable so the test suite can run end-to-end without ever touching
+ * the network or the file system.
+ *
+ * @param {object} opts
+ * @param {string} opts.agentRoot
+ * @param {string} opts.appToken          xapp-… app-level token
+ * @param {object} opts.identity          loadAgentIdentity() result
+ * @param {Set<string>} opts.peerSlackIds
+ * @param {Function} [opts.fetchFn]       defaults to global fetch
+ * @param {Function} [opts.WebSocketCtor] defaults to global WebSocket
+ * @param {Function} [opts.writeInbox]    defaults to writeInboxItem
+ * @param {Function} [opts.now]           defaults to Date.now
+ * @param {Function} [opts.setTimeout]    defaults to globalThis.setTimeout
+ * @param {Function} [opts.clearTimeout]  defaults to globalThis.clearTimeout
+ */
+export function createSocketModeClient(opts) {
+  const {
+    agentRoot,
+    appToken,
+    identity,
+    peerSlackIds,
+    fetchFn = fetch,
+    WebSocketCtor = globalThis.WebSocket,
+    writeInbox = writeInboxItem,
+    now = Date.now,
+    setTimeout: setTimeoutFn = globalThis.setTimeout,
+    clearTimeout: clearTimeoutFn = globalThis.clearTimeout,
+  } = opts;
+
+  if (!WebSocketCtor) {
+    throw new Error(
+      "Socket Mode requires a WebSocket implementation. Use Node 22+ (global WebSocket) or pass WebSocketCtor.",
+    );
+  }
+
+  const state = {
+    socket: null,
+    backoffMs: RECONNECT_INITIAL_MS,
+    stopped: false,
+    reconnectTimer: null,
+    heartbeatTimer: null,
+    lastPingAt: 0,
+    stats: {
+      connects: 0,
+      reconnects: 0,
+      eventsReceived: 0,
+      eventsKept: 0,
+      eventsDropped: 0,
+      acksSent: 0,
+      lastDisconnectReason: null,
+    },
+  };
+
+  // -------------------------------------------------------------------------
+  // ack — Slack requires every envelope to be acked back over the same socket.
+  // -------------------------------------------------------------------------
+  function ack(envelopeId, ws) {
+    if (!envelopeId || !ws || ws.readyState !== 1 /* WebSocket.OPEN */) return;
+    try {
+      ws.send(JSON.stringify({ envelope_id: envelopeId }));
+      state.stats.acksSent++;
+    } catch (err) {
+      warn(agentRoot, `ack send failed: ${err.message}`, { envelopeId });
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // handleEnvelope — translate + persist via writeInbox.
+  // -------------------------------------------------------------------------
+  function handleEnvelope(envelope, ws) {
+    state.stats.eventsReceived++;
+
+    // Slack sends multiple envelope types over the same socket: hello,
+    // disconnect, events_api, slash_commands, interactive, etc. We only
+    // care about the events_api stream for inbox ingestion.
+    if (envelope.type === "hello") {
+      info(agentRoot, "hello — connected to Slack Socket Mode", {
+        num_connections: envelope.num_connections,
+        debug_info: envelope.debug_info,
+      });
+      state.backoffMs = RECONNECT_INITIAL_MS; // reset on a clean hello
+      return;
+    }
+    if (envelope.type === "disconnect") {
+      info(agentRoot, "disconnect requested by Slack — will reconnect", {
+        reason: envelope.reason,
+      });
+      state.stats.lastDisconnectReason = envelope.reason || "slack-requested";
+      // Slack always wants an ack on this, but most importantly we should
+      // close + reconnect to pick up the new server-side endpoint.
+      try { ws.close(); } catch { /* */ }
+      return;
+    }
+
+    // Every other envelope type needs an ack — do this BEFORE any
+    // potentially-slow processing so Slack doesn't re-deliver.
+    if (envelope.envelope_id) ack(envelope.envelope_id, ws);
+
+    const decision = shouldKeepEvent(envelope, {
+      ownSlackId: identity.slackMemberId,
+      peerSlackIds,
+    });
+    if (!decision.keep) {
+      state.stats.eventsDropped++;
+      logLine(agentRoot, { level: "debug", message: "event-dropped", reason: decision.reason });
+      return;
+    }
+
+    let item;
+    try {
+      item = eventToInboxItem(envelope, {
+        ownSlackId: identity.slackMemberId,
+        principalSlackId: identity.principalSlackId,
+        agentFirstName: identity.firstName,
+      });
+    } catch (err) {
+      error(agentRoot, `translation failed: ${err.message}`, { stack: err.stack });
+      return;
+    }
+
+    try {
+      writeInbox("slack", item);
+      state.stats.eventsKept++;
+      info(agentRoot, "inbox-item-written", {
+        id: item.id,
+        channel: item.channel,
+        sender: item.sender,
+        is_reply: item.is_reply,
+        mentions_agent: item.priority_signals.mentions_agent,
+      });
+    } catch (err) {
+      error(agentRoot, `writeInbox failed: ${err.message}`, { stack: err.stack, id: item.id });
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // connect — single attempt; on close, schedule a reconnect.
+  // -------------------------------------------------------------------------
+  async function connect() {
+    if (state.stopped) return;
+    if (existsSync(join(agentRoot, ".emergency-stop"))) {
+      info(agentRoot, ".emergency-stop present — refusing to connect");
+      return;
+    }
+
+    const open = await openSocketConnection({ appToken, fetchFn });
+    if (open.error) {
+      state.stats.lastDisconnectReason = `open-failed:${open.error}`;
+      error(agentRoot, `apps.connections.open failed: ${open.error}`);
+      scheduleReconnect();
+      return;
+    }
+    info(agentRoot, "opening WebSocket", { url_prefix: open.url.slice(0, 64) });
+
+    let ws;
+    try {
+      ws = new WebSocketCtor(open.url);
+    } catch (err) {
+      error(agentRoot, `WebSocket construction failed: ${err.message}`);
+      scheduleReconnect();
+      return;
+    }
+    state.socket = ws;
+    state.stats.connects++;
+    if (state.stats.connects > 1) state.stats.reconnects++;
+
+    // Both event-emitter and addEventListener APIs work on global WebSocket;
+    // use addEventListener so a `ws` polyfill from a future test injection
+    // doesn't bite us.
+    const onOpen = () => {
+      state.lastPingAt = now();
+    };
+    const onMessage = (event) => {
+      const raw = typeof event === "string" ? event : (event?.data ?? "");
+      if (!raw) return;
+      let envelope;
+      try {
+        envelope = JSON.parse(typeof raw === "string" ? raw : raw.toString());
+      } catch (err) {
+        warn(agentRoot, `non-JSON frame: ${err.message}`, { raw_snippet: String(raw).slice(0, 200) });
+        return;
+      }
+      try {
+        handleEnvelope(envelope, ws);
+      } catch (err) {
+        error(agentRoot, `handleEnvelope threw: ${err.message}`, { stack: err.stack });
+      }
+    };
+    const onError = (event) => {
+      warn(agentRoot, `socket error: ${event?.message || "unknown"}`);
+    };
+    const onClose = (event) => {
+      const code = event?.code ?? 0;
+      const reason = event?.reason ?? "";
+      info(agentRoot, "socket closed", { code, reason });
+      state.socket = null;
+      scheduleReconnect();
+    };
+
+    ws.addEventListener?.("open", onOpen);
+    ws.addEventListener?.("message", onMessage);
+    ws.addEventListener?.("error", onError);
+    ws.addEventListener?.("close", onClose);
+    // The `ws` npm package uses Node's EventEmitter; addEventListener may
+    // be missing. Fall back to `on` if present.
+    if (typeof ws.addEventListener !== "function" && typeof ws.on === "function") {
+      ws.on("open", onOpen);
+      ws.on("message", (data) => onMessage({ data }));
+      ws.on("error", (err) => onError({ message: err?.message }));
+      ws.on("close", (code, reason) => onClose({ code, reason: String(reason ?? "") }));
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // scheduleReconnect — exponential back-off; resets on each hello.
+  // -------------------------------------------------------------------------
+  function scheduleReconnect() {
+    if (state.stopped) return;
+    if (state.reconnectTimer) return; // already scheduled
+    state.backoffMs = nextBackoffMs(state.backoffMs);
+    info(agentRoot, `reconnect in ${state.backoffMs}ms`, { backoff_ms: state.backoffMs });
+    state.reconnectTimer = setTimeoutFn(() => {
+      state.reconnectTimer = null;
+      connect().catch((err) => {
+        error(agentRoot, `connect rejected: ${err.message}`, { stack: err.stack });
+        scheduleReconnect();
+      });
+    }, state.backoffMs);
+    if (state.reconnectTimer && typeof state.reconnectTimer.unref === "function") {
+      state.reconnectTimer.unref();
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // supervisor — checks .emergency-stop, prunes stale sockets.
+  //
+  // Timers are unref()-ed so they don't pin the Node event loop alive on
+  // test exit. In production the WebSocket itself holds the loop open,
+  // and the supervisor's job is purely to detect .emergency-stop while
+  // the listener is otherwise idle.
+  // -------------------------------------------------------------------------
+  function startSupervisor() {
+    state.heartbeatTimer = setTimeoutFn(function tick() {
+      if (state.stopped) return;
+      // Emergency-stop short-circuit. Exit 0 so KeepAlive(SuccessfulExit:false)
+      // refuses to restart us.
+      if (existsSync(join(agentRoot, ".emergency-stop"))) {
+        info(agentRoot, ".emergency-stop detected — exiting 0");
+        stop();
+        process.exit(0);
+      }
+      state.heartbeatTimer = setTimeoutFn(tick, SUPERVISOR_INTERVAL_MS);
+      if (state.heartbeatTimer && typeof state.heartbeatTimer.unref === "function") {
+        state.heartbeatTimer.unref();
+      }
+    }, SUPERVISOR_INTERVAL_MS);
+    if (state.heartbeatTimer && typeof state.heartbeatTimer.unref === "function") {
+      state.heartbeatTimer.unref();
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // start / stop lifecycle
+  // -------------------------------------------------------------------------
+  async function start() {
+    state.stopped = false;
+    startSupervisor();
+    await connect();
+  }
+
+  function stop() {
+    state.stopped = true;
+    if (state.reconnectTimer) {
+      clearTimeoutFn(state.reconnectTimer);
+      state.reconnectTimer = null;
+    }
+    if (state.heartbeatTimer) {
+      clearTimeoutFn(state.heartbeatTimer);
+      state.heartbeatTimer = null;
+    }
+    if (state.socket) {
+      try { state.socket.close(); } catch { /* */ }
+      state.socket = null;
+    }
+  }
+
+  function getStats() {
+    return { ...state.stats };
+  }
+
+  function getState() {
+    return {
+      connected: !!state.socket && state.socket.readyState === 1,
+      backoffMs: state.backoffMs,
+      stopped: state.stopped,
+    };
+  }
+
+  return { start, stop, getStats, getState, _internals: { handleEnvelope, scheduleReconnect, state } };
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Boot the daemon when invoked as a script (not when imported by tests).
+ */
+async function main() {
+  const agentRoot = process.env.AGENT_ROOT || process.env.AGENT_DIR || AGENT_REPO_DIR || resolve(__dirname, "..", "..");
+
+  // Emergency-stop check before anything else (mirror maestro-daemon.mjs).
+  if (existsSync(join(agentRoot, ".emergency-stop"))) {
+    console.error("[slack-socket] .emergency-stop flag present — refusing to start.");
+    console.error("[slack-socket] Lift with: scripts/resume-operations.sh");
+    // Hold for a moment so KeepAlive's throttle has something to throttle.
+    await new Promise((r) => setTimeout(r, 30_000));
+    process.exit(0);
+  }
+
+  loadEnvFromFile(agentRoot);
+
+  const appToken = process.env.SLACK_APP_LEVEL_TOKEN || "";
+  if (!appToken || !appToken.startsWith("xapp-")) {
+    error(agentRoot, "SLACK_APP_LEVEL_TOKEN missing or malformed (must start with xapp-). " +
+                     "Run: node scripts/setup/init-slack-socket-mode.mjs");
+    process.exit(78); // EX_CONFIG
+  }
+
+  const identity = loadAgentIdentity(agentRoot);
+  const peerSlackIds = loadPeerSlackIds(agentRoot, identity.slackMemberId);
+
+  info(agentRoot, "starting Socket Mode listener", {
+    agent: identity.firstName,
+    slack_id: identity.slackMemberId || "(unset)",
+    peers: peerSlackIds.size,
+  });
+
+  const client = createSocketModeClient({ agentRoot, appToken, identity, peerSlackIds });
+  const shutdown = (signal) => {
+    info(agentRoot, `received ${signal}, shutting down`);
+    client.stop();
+    setTimeout(() => process.exit(0), 250);
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("unhandledRejection", (reason) => {
+    error(agentRoot, `unhandled rejection: ${reason?.message || reason}`, {
+      stack: reason?.stack,
+    });
+  });
+  process.on("uncaughtException", (err) => {
+    error(agentRoot, `uncaught exception: ${err.message}`, { stack: err.stack });
+    // Let launchd restart us — non-zero exit triggers KeepAlive.Crashed.
+    setTimeout(() => process.exit(1), 250);
+  });
+
+  await client.start();
+}
+
+// Only run main() when this file is executed directly (not when imported
+// as a module by the test suite). The `process.argv[1]` check matches the
+// pattern used elsewhere in the framework.
+const isDirectInvocation = process.argv[1] && resolve(process.argv[1]) === __filename;
+if (isDirectInvocation) {
+  main().catch((err) => {
+    console.error(`[slack-socket] fatal: ${err.message}`);
+    console.error(err.stack);
+    process.exit(1);
+  });
+}