@adaptic/maestro 1.10.8 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptic/maestro",
-  "version": "1.10.8",
+  "version": "1.11.0",
   "description": "Maestro — Autonomous AI agent operating system. Deploy AI employees on dedicated Mac minis.",
   "type": "module",
   "bin": {

package/scripts/cadence/launchd-cloud-relay-wrapper.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# launchd-socket-mode-wrapper.sh — Bootstraps env for slack-cloud-relay-client.mjs
+# under launchd.
+#
+# Mirrors launchd-wrapper.sh exactly: launchd's bare env doesn't include
+# HOME, PATH, or AGENT_ROOT, so we hydrate them before exec'ing the
+# Socket Mode listener. Logs land on the external SSD when available
+# (same fallback semantics as the main daemon wrapper).
+#
+# This wrapper is exec'd by ai.adaptic.{firstname}-slack-cloud-relay.plist.
+
+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"
+
+# ── SSD redirect ────────────────────────────────────────────────────────────
+# If an external SSD is mounted at /Volumes/{name}, redirect:
+#   - Claude Code per-cwd temp (CLAUDE_CODE_TMPDIR)
+#   - Listener stdout/stderr (via shell redirection at exec time)
+#
+# Detection mirrors launchd-wrapper.sh — first volume under /Volumes that's
+# not a system mount; MAESTRO_SSD_VOLUME env var overrides if multiple SSDs.
+
+SSD_VOLUME="${MAESTRO_SSD_VOLUME:-}"
+if [ -z "$SSD_VOLUME" ]; then
+  for v in /Volumes/*-SSD /Volumes/*SSD* /Volumes/maestro-data; do
+    if [ -d "$v" ] && [ "$v" != "/Volumes/Macintosh HD" ]; then
+      SSD_VOLUME="$v"
+      break
+    fi
+  done
+fi
+
+AGENT_NAME="$(basename "$AGENT_ROOT" | sed 's/-ai$//')"
+SSD_AGENT_ROOT=""
+SSD_WRITABLE=0
+if [ -n "$SSD_VOLUME" ] && [ -d "$SSD_VOLUME" ]; then
+  SSD_AGENT_ROOT="$SSD_VOLUME/maestro/$AGENT_NAME"
+  if mkdir -p "$SSD_AGENT_ROOT/claude-tmp" "$SSD_AGENT_ROOT/logs/slack-cloud-relay" 2>/dev/null && \
+     touch "$SSD_AGENT_ROOT/.write-test-$$" 2>/dev/null; then
+    rm -f "$SSD_AGENT_ROOT/.write-test-$$"
+    SSD_WRITABLE=1
+    export CLAUDE_CODE_TMPDIR="$SSD_AGENT_ROOT/claude-tmp"
+  fi
+fi
+
+cd "$AGENT_ROOT"
+
+# Resolve node binary — prefer nvm, fall back to homebrew, then system.
+NODE_BIN=""
+for candidate in \
+  "$HOME/.nvm/versions/node/v24.11.1/bin/node" \
+  "$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
+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" ] || [ ! -x "$NODE_BIN" ]; then
+  echo "[slack-cloud-relay-wrapper] FATAL: could not find node binary" >&2
+  exit 127
+fi
+
+# Node 22.4+ is required for the global WebSocket. Warn (don't fail) on
+# older versions — the user might have polyfilled via `--experimental-websocket`
+# or installed the `ws` package as a fallback.
+NODE_VERSION="$("$NODE_BIN" --version 2>/dev/null || echo 'v0.0.0')"
+NODE_MAJOR="$(echo "$NODE_VERSION" | sed -E 's/^v([0-9]+).*/\1/')"
+if [ "$NODE_MAJOR" -lt 22 ] 2>/dev/null; then
+  echo "[slack-cloud-relay-wrapper] WARNING: Node $NODE_VERSION is older than v22 — global WebSocket may be missing." >&2
+fi
+
+# Exec the listener. Prefer SSD log path if writable, otherwise fall back
+# to internal disk so the listener stays up even when macOS denies launchd
+# write access to /Volumes/{name}.
+if [ "$SSD_WRITABLE" = "1" ]; then
+  LISTENER_LOG="$SSD_AGENT_ROOT/logs/slack-cloud-relay/listener-$(date +%Y-%m-%d).log"
+  exec "$NODE_BIN" "$AGENT_ROOT/scripts/poller/slack-cloud-relay-client.mjs" >> "$LISTENER_LOG" 2>&1
+else
+  LISTENER_LOG="$AGENT_ROOT/logs/polling/slack-cloud-relay-$(date +%Y-%m-%d).log"
+  mkdir -p "$(dirname "$LISTENER_LOG")" 2>/dev/null || true
+  exec "$NODE_BIN" "$AGENT_ROOT/scripts/poller/slack-cloud-relay-client.mjs" >> "$LISTENER_LOG" 2>&1
+fi

package/scripts/cloud-relay/README.md

@@ -0,0 +1,59 @@
+# Cloud Relay — Slack Events to Mac mini
+
+Public HTTPS service that proxies Slack Events API webhooks into a
+Mac-mini-resident maestro daemon over Server-Sent Events.
+
+## Why
+
+Slack Socket Mode only delivers events for the **bot user** that owns the
+app. DMs sent to the agent's underlying **user account** (e.g.,
+`U099N1JE0LA` for Ravi) are invisible to Socket Mode — the bot is not a
+member of those conversations. To get real-time push for those DMs we
+need user-scope event subscriptions, which require an HTTPS endpoint, and
+Mac minis don't have public IPs. This relay closes the gap.
+
+## Architecture
+
+```
+  Slack ──HTTPS POST──▶ Railway (this relay) ──SSE──▶ Mac mini (slack-cloud-relay-client.mjs)
+                              │                          │
+                              │                          └──▶ writeInboxItem() → state/inbox/slack/
+                              │
+                              └── verifies x-slack-signature, fans events to all SSE clients
+```
+
+## Deploy
+
+```
+cd scripts/cloud-relay
+railway init
+railway up
+railway variables set \
+  SLACK_SIGNING_SECRET=<from Slack app Basic Information> \
+  RELAY_SHARED_SECRET=<long random string, share with Mac mini>
+railway domain          # → returns https://<project>.up.railway.app
+```
+
+Then in the Slack app config:
+1. Event Subscriptions → Enable Events → set Request URL to
+   `https://<project>.up.railway.app/slack/events`.
+2. Subscribe to **User events** (`message.im`, `message.mpim`,
+   `message.channels`, `message.groups`, `app_mention`).
+3. Save changes and reinstall the app.
+
+Set the Mac mini's `.env`:
+```
+CLOUD_RELAY_URL=https://<project>.up.railway.app
+RELAY_SHARED_SECRET=<same string as on Railway>
+```
+
+## Endpoints
+
+- `POST /slack/events` — Slack Events API. Verifies `x-slack-signature`
+  using `SLACK_SIGNING_SECRET`; responds to `url_verification` challenges;
+  fans event callbacks out to connected SSE clients.
+- `GET /events/stream` — SSE stream. Requires
+  `Authorization: Bearer <RELAY_SHARED_SECRET>`. New connections receive
+  the last 100 events as catch-up; heartbeats every 25 s keep the stream
+  alive through proxies.
+- `GET /health` — Liveness probe (returns connection + queue counts).

package/scripts/cloud-relay/index.mjs

@@ -0,0 +1,233 @@
+/**
+ * Maestro — Slack Events Cloud Relay
+ *
+ * Public HTTPS service (deployed on Railway) that bridges Slack user-scope
+ * Events API webhooks into a Mac-mini-resident maestro daemon over SSE.
+ *
+ * Why this exists: Socket Mode is bot-scoped, so DMs sent to the agent's
+ * USER account (not its bot user) are invisible to a Socket Mode listener.
+ * To get real-time push for those DMs, the Slack app needs user-scope event
+ * subscriptions, which require an HTTPS webhook URL — and Mac minis don't
+ * have public IPs. This relay sits in front: Slack POSTs events here, the
+ * Mac mini holds an authenticated SSE connection, and events get pushed
+ * back over the open stream in milliseconds.
+ *
+ * Endpoints:
+ *   POST /slack/events     — Slack Events API receiver. Verifies the v0
+ *                            HMAC signature, handles url_verification on
+ *                            registration, fans event_callback envelopes
+ *                            out to every connected SSE client.
+ *   GET  /events/stream    — Server-Sent Events feed for Mac-mini clients
+ *                            holding an open connection. Bearer-token
+ *                            authenticated against RELAY_SHARED_SECRET.
+ *                            New connections receive the last ~100 events
+ *                            so a brief disconnect doesn't drop messages.
+ *   GET  /health           — Liveness probe used by Railway / external
+ *                            uptime monitors.
+ *
+ * Env (all required):
+ *   PORT                   — provided by Railway
+ *   SLACK_SIGNING_SECRET   — from Slack app "Basic Information" page
+ *   RELAY_SHARED_SECRET    — operator-chosen long random string; the Mac
+ *                            mini client must send the same value in its
+ *                            Authorization: Bearer <...> header
+ */
+
+import http from "node:http";
+import crypto from "node:crypto";
+
+const PORT = parseInt(process.env.PORT || "3100", 10);
+const SIGNING_SECRET = process.env.SLACK_SIGNING_SECRET || "";
+const RELAY_SHARED_SECRET = process.env.RELAY_SHARED_SECRET || "";
+
+if (!SIGNING_SECRET) {
+  console.error("FATAL: SLACK_SIGNING_SECRET env var is required");
+  process.exit(78);
+}
+if (!RELAY_SHARED_SECRET) {
+  console.error("FATAL: RELAY_SHARED_SECRET env var is required");
+  process.exit(78);
+}
+
+// Connected Mac-mini SSE clients (typically 1, but designed for fan-out).
+const sseClients = new Set();
+
+// Bounded ring buffer of recent events for reconnect replay. Slack-side
+// "retry on 5xx" already gives us at-least-once delivery, so this is just
+// for the case where the Mac mini's SSE connection drops between an event
+// arriving and being acked: when it reconnects within ~5 minutes it gets
+// the missing events replayed instead of waiting for Slack's next retry.
+const REPLAY_CAPACITY = 100;
+const eventQueue = [];
+
+function log(level, message, data) {
+  const ts = new Date().toISOString();
+  const line = JSON.stringify({ ts, level, message, ...(data || {}) });
+  if (level === "error") console.error(line);
+  else console.log(line);
+}
+
+/**
+ * Verify Slack's v0 HMAC signature. Per Slack docs:
+ *   sig_basestring = "v0:" + timestamp + ":" + raw_body
+ *   expected       = "v0=" + hex(hmac_sha256(SIGNING_SECRET, sig_basestring))
+ * Also enforce the 5-minute timestamp window to block replay attacks.
+ */
+function verifySlackSignature(timestamp, body, signature) {
+  if (!timestamp || !signature) return false;
+  const tsNum = parseInt(timestamp, 10);
+  if (!Number.isFinite(tsNum)) return false;
+  const ageSec = Math.abs(Date.now() / 1000 - tsNum);
+  if (ageSec > 5 * 60) return false;
+  const basestring = `v0:${timestamp}:${body}`;
+  const expected = `v0=${crypto.createHmac("sha256", SIGNING_SECRET).update(basestring).digest("hex")}`;
+  if (expected.length !== signature.length) return false;
+  try {
+    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
+  } catch {
+    return false;
+  }
+}
+
+function fanOut(envelope) {
+  eventQueue.push(envelope);
+  if (eventQueue.length > REPLAY_CAPACITY) eventQueue.shift();
+  const data = `data: ${JSON.stringify(envelope)}\n\n`;
+  const dead = [];
+  for (const client of sseClients) {
+    try {
+      client.write(data);
+    } catch {
+      dead.push(client);
+    }
+  }
+  for (const c of dead) sseClients.delete(c);
+  log("info", "fanned-out", { sse_clients: sseClients.size, queue_size: eventQueue.length });
+}
+
+const server = http.createServer((req, res) => {
+  // Health probe
+  if (req.method === "GET" && req.url === "/health") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+      ok: true,
+      sse_clients: sseClients.size,
+      queue_size: eventQueue.length,
+      uptime_s: Math.round(process.uptime()),
+    }));
+    return;
+  }
+
+  // Slack Events API endpoint
+  if (req.method === "POST" && req.url === "/slack/events") {
+    let body = "";
+    req.on("data", (chunk) => { body += chunk; });
+    req.on("end", () => {
+      const ts = req.headers["x-slack-request-timestamp"];
+      const sig = req.headers["x-slack-signature"];
+
+      if (!verifySlackSignature(ts, body, sig)) {
+        log("warn", "rejected-bad-signature", { ts_header: !!ts });
+        res.writeHead(401, { "Content-Type": "text/plain" });
+        res.end("invalid signature");
+        return;
+      }
+
+      let payload;
+      try {
+        payload = JSON.parse(body);
+      } catch {
+        res.writeHead(400, { "Content-Type": "text/plain" });
+        res.end("bad json");
+        return;
+      }
+
+      // One-time URL verification when the operator first registers the
+      // webhook in the Slack app config. Slack expects an echo of the
+      // `challenge` field within 3 seconds.
+      if (payload.type === "url_verification") {
+        log("info", "url-verification-challenge", { challenge_len: (payload.challenge || "").length });
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ challenge: payload.challenge }));
+        return;
+      }
+
+      // Event callback. Slack requires a 200 within 3 seconds or it
+      // retries, so ack immediately and fan out after.
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.end("ok");
+      if (payload.type === "event_callback") {
+        fanOut(payload);
+      } else {
+        log("info", "ignored-envelope-type", { type: payload.type });
+      }
+    });
+    req.on("error", (err) => {
+      log("error", "request-error", { error: err.message });
+    });
+    return;
+  }
+
+  // SSE stream to Mac mini
+  if (req.method === "GET" && req.url === "/events/stream") {
+    const auth = req.headers.authorization || "";
+    const want = `Bearer ${RELAY_SHARED_SECRET}`;
+    if (auth.length !== want.length || !crypto.timingSafeEqual(Buffer.from(auth), Buffer.from(want))) {
+      res.writeHead(401, { "Content-Type": "text/plain" });
+      res.end("unauthorized");
+      return;
+    }
+
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no",
+    });
+    res.write(": connected\n\n");
+    sseClients.add(res);
+    log("info", "sse-client-connected", { sse_clients: sseClients.size, remote: req.socket.remoteAddress });
+
+    // Replay the recent backlog so a brief disconnect doesn't drop events.
+    for (const ev of eventQueue) {
+      try { res.write(`data: ${JSON.stringify(ev)}\n\n`); } catch { /* */ }
+    }
+
+    // Heartbeat — many proxies idle-timeout long-lived streams; a comment
+    // line every 25s keeps the connection visibly alive without polluting
+    // the event payloads.
+    const hb = setInterval(() => {
+      try {
+        res.write(": hb\n\n");
+      } catch {
+        clearInterval(hb);
+      }
+    }, 25_000);
+
+    req.on("close", () => {
+      sseClients.delete(res);
+      clearInterval(hb);
+      log("info", "sse-client-disconnected", { sse_clients: sseClients.size });
+    });
+    return;
+  }
+
+  res.writeHead(404, { "Content-Type": "text/plain" });
+  res.end("not found");
+});
+
+server.listen(PORT, () => {
+  log("info", "cloud-relay-listening", { port: PORT });
+});
+
+// Graceful shutdown on SIGTERM (Railway sends this on redeploy / scale-down).
+const shutdown = (signal) => {
+  log("info", "shutdown-requested", { signal });
+  for (const client of sseClients) {
+    try { client.end(); } catch { /* */ }
+  }
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(0), 5_000).unref();
+};
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));

package/scripts/cloud-relay/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@adaptic/maestro-cloud-relay",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Public HTTPS relay that proxies Slack Events API into a Mac-mini-resident maestro daemon over SSE.",
+  "main": "index.mjs",
+  "scripts": {
+    "start": "node index.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}

package/scripts/cloud-relay/railway.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "NIXPACKS"
+  },
+  "deploy": {
+    "startCommand": "node index.mjs",
+    "healthcheckPath": "/health",
+    "healthcheckTimeout": 100,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 10
+  }
+}

package/scripts/poller/slack-cloud-relay-client.mjs

@@ -0,0 +1,326 @@
+/**
+ * Maestro — Slack Cloud-Relay Client
+ *
+ * Persistent SSE consumer that connects to the Railway-hosted cloud-relay
+ * (scripts/cloud-relay/) and turns the Slack user-scope event stream into
+ * inbox YAML files via writeInboxItem. Drop-in replacement for the
+ * bot-scoped Socket Mode listener when the agent's primary message
+ * surface is the agent's USER account rather than a bot user.
+ *
+ * Lifecycle:
+ *   1. Honour .emergency-stop before any I/O.
+ *   2. Open an HTTPS SSE connection to CLOUD_RELAY_URL/events/stream with
+ *      a Bearer header containing RELAY_SHARED_SECRET.
+ *   3. Parse `data:` lines as event_callback envelopes; reuse the
+ *      shouldKeepEvent + eventToInboxItem helpers from slack-socket-mode
+ *      so the inbox YAML shape is identical to what Socket Mode produces.
+ *   4. On disconnect, reconnect with exponential back-off + jitter.
+ *
+ * Env (read from .env):
+ *   CLOUD_RELAY_URL           — Railway service base URL (https://...)
+ *   RELAY_SHARED_SECRET       — auth bearer; must match Railway env var
+ *   SLACK_BOT_TOKEN           — used by shouldKeepEvent for own/peer
+ *                               filtering (no requests made on this path)
+ */
+
+import { config as loadEnv } from "dotenv";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync, appendFileSync, mkdirSync } from "node:fs";
+
+import {
+  shouldKeepEvent,
+  eventToInboxItem,
+} from "./slack-socket-mode.mjs";
+import { writeInboxItem } from "./utils.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_REPO_DIR = process.env.AGENT_DIR || resolve(__dirname, "../..");
+loadEnv({ path: join(AGENT_REPO_DIR, ".env") });
+
+const CLOUD_RELAY_URL = (process.env.CLOUD_RELAY_URL || "").replace(/\/$/, "");
+const RELAY_SHARED_SECRET = process.env.RELAY_SHARED_SECRET || "";
+
+const RECONNECT_INITIAL_MS = 2_000;
+const RECONNECT_MAX_MS = 60_000;
+const HEARTBEAT_GRACE_MS = 90_000; // SSE heartbeat is 25s — be generous before declaring dead
+
+// ---------------------------------------------------------------------------
+// Identity loading (mirrors slack-socket-mode)
+// ---------------------------------------------------------------------------
+
+function loadAgent() {
+  const path = join(AGENT_REPO_DIR, "config", "agent.json");
+  if (!existsSync(path)) return { firstName: "Agent" };
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return { firstName: "Agent" };
+  }
+}
+
+function loadPeerSlackIds() {
+  // Read agents/index.json if present; otherwise empty set (lone agent).
+  const peers = new Set();
+  const idxPath = join(AGENT_REPO_DIR, "agents", "index.json");
+  if (!existsSync(idxPath)) return peers;
+  try {
+    const idx = JSON.parse(readFileSync(idxPath, "utf-8"));
+    for (const a of idx.agents || []) {
+      if (a.slackMemberId) peers.add(a.slackMemberId);
+    }
+  } catch { /* */ }
+  return peers;
+}
+
+// ---------------------------------------------------------------------------
+// Logging
+// ---------------------------------------------------------------------------
+
+const LOG_DIR = join(AGENT_REPO_DIR, "logs", "polling");
+try { mkdirSync(LOG_DIR, { recursive: true }); } catch { /* */ }
+
+function log(level, message, data) {
+  const ts = new Date().toISOString();
+  const line = { ts, level, message, ...(data || {}) };
+  if (level === "error") console.error(`[slack-cloud-relay] ${message}`, data || "");
+  else console.log(`[slack-cloud-relay] ${message}`, data || "");
+  try {
+    appendFileSync(
+      join(LOG_DIR, `${ts.slice(0, 10)}-slack-cloud-relay.jsonl`),
+      JSON.stringify(line) + "\n",
+    );
+  } catch { /* best-effort */ }
+}
+
+// ---------------------------------------------------------------------------
+// SSE parser — robust to multi-line `data:` and `:` comment heartbeats
+// ---------------------------------------------------------------------------
+
+/**
+ * Push raw bytes from the relay into a stateful parser. Yields complete
+ * event payloads (the JSON in each `data:` block) as strings. Per the SSE
+ * spec, events are terminated by a blank line; `data:` may appear on
+ * multiple lines and concatenate with newlines, `:` lines are comments.
+ */
+function createSseParser() {
+  let buffer = "";
+  let dataLines = [];
+  return {
+    push(chunk) {
+      buffer += chunk;
+      const out = [];
+      let nlIdx;
+      while ((nlIdx = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, nlIdx).replace(/\r$/, "");
+        buffer = buffer.slice(nlIdx + 1);
+        if (line === "") {
+          // End of event — flush
+          if (dataLines.length > 0) {
+            out.push(dataLines.join("\n"));
+            dataLines = [];
+          }
+          continue;
+        }
+        if (line.startsWith(":")) continue; // comment (heartbeat)
+        if (line.startsWith("data:")) {
+          dataLines.push(line.slice(5).replace(/^ /, ""));
+        }
+        // We ignore "event:" / "id:" / "retry:" lines — the relay
+        // doesn't emit them.
+      }
+      return out;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exponential back-off (mirrors slack-socket-mode)
+// ---------------------------------------------------------------------------
+
+function nextBackoffMs(currentMs) {
+  const doubled = Math.min(RECONNECT_MAX_MS, Math.max(RECONNECT_INITIAL_MS, currentMs * 2));
+  const jitter = Math.floor(Math.random() * 0.25 * doubled);
+  return Math.min(RECONNECT_MAX_MS, doubled + jitter);
+}
+
+// ---------------------------------------------------------------------------
+// Main loop
+// ---------------------------------------------------------------------------
+
+let stopped = false;
+let backoffMs = RECONNECT_INITIAL_MS;
+
+async function connect(identity, peerSlackIds) {
+  if (stopped) return;
+  if (existsSync(join(AGENT_REPO_DIR, ".emergency-stop"))) {
+    log("info", ".emergency-stop present — refusing to connect");
+    return;
+  }
+  if (!CLOUD_RELAY_URL || !RELAY_SHARED_SECRET) {
+    log("error", "CLOUD_RELAY_URL or RELAY_SHARED_SECRET not set — cannot connect");
+    return;
+  }
+
+  const url = `${CLOUD_RELAY_URL}/events/stream`;
+  log("info", "connecting", { url });
+
+  let response;
+  try {
+    response = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${RELAY_SHARED_SECRET}`,
+        Accept: "text/event-stream",
+      },
+    });
+  } catch (err) {
+    log("error", `connect failed: ${err.message}`);
+    scheduleReconnect(identity, peerSlackIds);
+    return;
+  }
+
+  if (!response.ok) {
+    log("error", `relay rejected: HTTP ${response.status}`);
+    scheduleReconnect(identity, peerSlackIds);
+    return;
+  }
+
+  log("info", "connected");
+  backoffMs = RECONNECT_INITIAL_MS; // reset on a successful connect
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const parser = createSseParser();
+  let lastByteAt = Date.now();
+
+  // Heartbeat watchdog — if we haven't seen ANY bytes in HEARTBEAT_GRACE_MS,
+  // declare the connection dead and reconnect. Relay sends `: hb\n\n` every
+  // 25s, so a 90s grace catches both true silence and a proxy that froze.
+  const watchdog = setInterval(() => {
+    if (Date.now() - lastByteAt > HEARTBEAT_GRACE_MS) {
+      log("warn", "watchdog tripped — no bytes from relay", {
+        silent_ms: Date.now() - lastByteAt,
+      });
+      clearInterval(watchdog);
+      try { reader.cancel(); } catch { /* */ }
+    }
+  }, 30_000);
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        log("info", "stream closed by relay");
+        break;
+      }
+      lastByteAt = Date.now();
+      const chunk = decoder.decode(value, { stream: true });
+      const events = parser.push(chunk);
+      for (const raw of events) {
+        try {
+          const webhook = JSON.parse(raw);
+          handleWebhook(webhook, identity, peerSlackIds);
+        } catch (err) {
+          log("warn", `bad event JSON: ${err.message}`, { sample: raw.slice(0, 200) });
+        }
+      }
+    }
+  } catch (err) {
+    log("warn", `stream error: ${err.message}`);
+  } finally {
+    clearInterval(watchdog);
+  }
+
+  scheduleReconnect(identity, peerSlackIds);
+}
+
+function scheduleReconnect(identity, peerSlackIds) {
+  if (stopped) return;
+  const delay = backoffMs;
+  backoffMs = nextBackoffMs(backoffMs);
+  log("info", "reconnect scheduled", { delay_ms: delay, next_backoff_ms: backoffMs });
+  setTimeout(() => connect(identity, peerSlackIds), delay);
+}
+
+/**
+ * Translate a Slack Events API webhook envelope into the shape that
+ * eventToInboxItem expects (Socket Mode-style `{payload: {event: ...}}`)
+ * then write it to the inbox.
+ *
+ * Events API payload shape:
+ *   { token, team_id, api_app_id, type: "event_callback", event: {...}, event_id, event_time }
+ *
+ * Socket Mode payload shape that eventToInboxItem reads:
+ *   envelope.payload.event
+ *
+ * We adapt by wrapping: { type: "events_api", payload: webhook }.
+ */
+function handleWebhook(webhook, identity, peerSlackIds) {
+  if (!webhook || webhook.type !== "event_callback") {
+    log("info", "ignored-non-event-callback", { type: webhook?.type });
+    return;
+  }
+
+  const envelope = { type: "events_api", payload: webhook };
+  const decision = shouldKeepEvent(envelope, {
+    ownSlackId: identity.slackMemberId,
+    peerSlackIds,
+  });
+  if (!decision.keep) {
+    log("info", "event-dropped", { reason: decision.reason, event_id: webhook.event_id });
+    return;
+  }
+
+  let item;
+  try {
+    item = eventToInboxItem(envelope, {
+      ownSlackId: identity.slackMemberId,
+      principalSlackId: identity.principalSlackId,
+      agentFirstName: identity.firstName,
+    });
+  } catch (err) {
+    log("error", `translation failed: ${err.message}`);
+    return;
+  }
+  // Stamp the source so audit can tell relay-delivered events apart from
+  // poller- or socket-mode-delivered ones.
+  item.source = "cloud-relay";
+
+  try {
+    writeInboxItem("slack", item);
+    log("info", "inbox-item-written", {
+      id: item.id,
+      channel: item.channel,
+      sender: item.sender,
+      event_id: webhook.event_id,
+    });
+  } catch (err) {
+    log("error", `writeInboxItem failed: ${err.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Bootstrap
+// ---------------------------------------------------------------------------
+
+const identity = loadAgent();
+const peerSlackIds = loadPeerSlackIds();
+
+const shutdown = (signal, code) => {
+  log("info", `received ${signal}, shutting down (exit ${code})`);
+  stopped = true;
+  // Match the slack-socket-mode pattern: SIGTERM signals a respawn from
+  // launchd (exit 143), SIGINT is human-initiated stop (exit 0).
+  setTimeout(() => process.exit(code), 250);
+};
+process.on("SIGTERM", () => shutdown("SIGTERM", 143));
+process.on("SIGINT", () => shutdown("SIGINT", 0));
+process.on("unhandledRejection", (reason) => {
+  log("error", `unhandled rejection: ${reason?.message || reason}`);
+});
+process.on("uncaughtException", (err) => {
+  log("error", `uncaught exception: ${err.message}`);
+  setTimeout(() => process.exit(1), 250);
+});
+
+connect(identity, peerSlackIds);