@cohortapp/agent-sdk 2.3.0

package/scripts/poller/inbox-scan-poller.test.mjs

@@ -0,0 +1,231 @@
+/**
+ * inbox-scan-poller.test.mjs — node:test coverage for inbox-scan-poller.mjs
+ *
+ * Verifies the scanner is the faithful inverse of the inbox YAML writer for the
+ * fields the daemon needs, and that it skips already-processed items. Drives
+ * the real writer (writeInboxItem) under an injected AGENT_DIR so the round-trip
+ * is end-to-end. Hermetic.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { parseInboxItemYaml, scanInbox } from "./inbox-scan-poller.mjs";
+import { markDispatched, markInboxProcessed, writeInboxItem } from "./utils.mjs";
+import { eventToInboxItem } from "../../lib/channels/inbox-item.mjs";
+
+async function makeRoot() {
+  const p = join(tmpdir(), `inbox-scan-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(p, { recursive: true });
+  return p;
+}
+async function rmRoot(p) { try { await fsp.rm(p, { recursive: true, force: true }); } catch { /* */ } }
+
+test("parseInboxItemYaml recovers the daemon-relevant fields", () => {
+  const item = eventToInboxItem({
+    channel: "telegram",
+    message_id: "4242",
+    from: { id: "987", name: "casey" },
+    text: "ping the build please",
+    timestamp: "2026-06-09T10:00:00.000Z",
+    kind: "message",
+    sender: "casey",
+    sender_privilege: "unknown",
+    subject: "DM from casey",
+    channel_id: "987",
+    channel_label: "dm/casey",
+    is_reply: false,
+    priority_signals: { from_ceo: false, tagged_urgent: false, contains_deadline: false, mentions_agent: true },
+    raw_ref: "telegram:987:4242",
+    ingest_source: "telegram",
+  });
+
+  const yaml = renderViaWriter(item);
+  const parsed = parseInboxItemYaml(yaml);
+  assert.equal(parsed.id, item.id);
+  assert.equal(parsed.service, "telegram");
+  assert.equal(parsed.channel, "dm/casey");
+  assert.equal(parsed.channel_id, "987");
+  assert.equal(parsed.sender, "casey");
+  assert.equal(parsed.content, "ping the build please");
+  assert.equal(parsed.raw_ref, "telegram:987:4242");
+  assert.equal(parsed.priority_signals.mentions_agent, true);
+});
+
+test("scanInbox reads written items and skips processed siblings", async () => {
+  const root = await makeRoot();
+  try {
+    // Use the real writer against this tmp root via AGENT_DIR.
+    const prev = process.env.AGENT_DIR;
+    process.env.AGENT_DIR = root;
+    // Fresh import so utils.mjs picks up AGENT_DIR=root.
+    const utils = await import(`./utils.mjs?scan=${Date.now()}`);
+    const mkItem = (id, text) => eventToInboxItem({
+      channel: "telegram", message_id: id, from: { id: "987", name: "casey" }, text,
+      timestamp: `2026-06-09T10:00:0${id}.000Z`, sender: "casey", channel_id: "987",
+      channel_label: "dm/casey", raw_ref: `telegram:987:${id}`, ingest_source: "telegram",
+      priority_signals: { mentions_agent: true },
+    });
+    utils.writeInboxItem("telegram", mkItem("1", "first"));
+    utils.writeInboxItem("telegram", mkItem("2", "second"));
+
+    let res = scanInbox("telegram", { agentRoot: root });
+    assert.equal(res.items.length, 2);
+    const texts = res.items.map((i) => i.content).sort();
+    assert.deepEqual(texts, ["first", "second"]);
+
+    // Mark one processed (rename) — scanner must skip it.
+    const dir = join(root, "state/inbox/telegram");
+    const files = (await fsp.readdir(dir)).filter((f) => f.endsWith(".yaml"));
+    await fsp.rename(join(dir, files[0]), join(dir, files[0] + ".processed"));
+    res = scanInbox("telegram", { agentRoot: root });
+    assert.equal(res.items.length, 1, "processed item must not be re-emitted");
+
+    if (prev === undefined) delete process.env.AGENT_DIR; else process.env.AGENT_DIR = prev;
+  } finally { await rmRoot(root); }
+});
+
+test("scanInbox returns empty for a missing inbox dir", () => {
+  const res = scanInbox("nope", { agentRoot: "/no/such/root" });
+  assert.deepEqual(res, { items: [], errors: [] });
+});
+
+test("parseInboxItemYaml preserves multi-line content + thread_context", () => {
+  const item = eventToInboxItem({
+    channel: "telegram", message_id: "9", from: { id: "1", name: "x" },
+    text: "line one\nline two", timestamp: "2026-06-09T10:00:00.000Z",
+    sender: "x", channel_id: "1", channel_label: "dm/x", raw_ref: "telegram:1:9",
+    thread_context: "prev: hi there", ingest_source: "telegram",
+    priority_signals: { mentions_agent: true },
+  });
+  const yaml = renderViaWriter(item);
+  const parsed = parseInboxItemYaml(yaml);
+  assert.match(parsed.content, /line one/);
+  assert.match(parsed.content, /line two/);
+  assert.match(parsed.thread_context, /prev: hi there/);
+});
+
+// ── F1/H2: durable admission — crash mid-flight must leave the item re-deliverable ──
+
+function mkItem(id, text) {
+  return eventToInboxItem({
+    channel: "telegram", message_id: id, from: { id: "987", name: "casey" }, text,
+    timestamp: `2026-06-09T10:00:0${id}.000Z`, sender: "casey", channel_id: "987",
+    channel_label: "dm/casey", raw_ref: `telegram:987:${id}`, ingest_source: "telegram",
+    priority_signals: { mentions_agent: true },
+  });
+}
+
+test("markDispatched parks an admitted item as .dispatched so a fresh scan does NOT re-deliver it", async () => {
+  const root = await makeRoot();
+  try {
+    writeInboxItem("telegram", mkItem("1", "hello"), root);
+    const renamed = markDispatched(mkItem("1", "hello"), "telegram", root);
+    assert.equal(renamed, 1, "the live .yaml must be renamed to .dispatched");
+
+    // Happy path: a freshly-dispatched item is in-flight; the scanner must NOT
+    // re-emit it (otherwise we double-deliver the same message every poll).
+    const res = scanInbox("telegram", { agentRoot: root });
+    assert.equal(res.items.length, 0, "fresh .dispatched item must not be re-emitted");
+  } finally { await rmRoot(root); }
+});
+
+test("scanInbox RECLAIMS a stale .dispatched item (crash mid-flight) so it is re-delivered", async () => {
+  const root = await makeRoot();
+  try {
+    writeInboxItem("telegram", mkItem("1", "did you get this?"), root);
+    markDispatched(mkItem("1", "did you get this?"), "telegram", root);
+
+    // Simulate a daemon crash AFTER admission but BEFORE session close: the
+    // in-memory queue is gone, the file sits at .dispatched. Advancing the clock
+    // past the reclaim window must make the scanner treat it as stale and
+    // re-deliver it. (`now` injected to avoid mtime/clock-granularity flake.)
+    const res = scanInbox("telegram", { agentRoot: root, reclaimMs: 1000, now: Date.now() + 5000 });
+    assert.equal(res.items.length, 1, "stale .dispatched item must be reclaimed for redelivery");
+    assert.equal(res.items[0].content, "did you get this?");
+
+    // And within the window it must NOT be reclaimed (no double-delivery).
+    const fresh = scanInbox("telegram", { agentRoot: root, reclaimMs: 60_000, now: Date.now() });
+    assert.equal(fresh.items.length, 0, "an in-flight .dispatched item within the window must not be re-delivered");
+  } finally { await rmRoot(root); }
+});
+
+test("markInboxProcessed retires a .dispatched item to .processed (no redelivery on success)", async () => {
+  const root = await makeRoot();
+  try {
+    writeInboxItem("telegram", mkItem("1", "all done"), root);
+    markDispatched(mkItem("1", "all done"), "telegram", root);
+    const retired = markInboxProcessed(mkItem("1", "all done"), "telegram", root);
+    assert.equal(retired, 1, "the .dispatched file must be renamed to .processed on session close");
+
+    // Even with a 0ms reclaim window, a .processed item is terminal — never re-emitted.
+    const res = scanInbox("telegram", { agentRoot: root, reclaimMs: 0 });
+    assert.equal(res.items.length, 0, "processed item is terminal and must not be reclaimed");
+  } finally { await rmRoot(root); }
+});
+
+test("markInboxProcessed also retires a live .yaml (item never reached dispatch)", async () => {
+  const root = await makeRoot();
+  try {
+    writeInboxItem("telegram", mkItem("1", "ignored item"), root);
+    const retired = markInboxProcessed(mkItem("1", "ignored item"), "telegram", root);
+    assert.equal(retired, 1, "a live .yaml must also be retirable directly to .processed");
+    const res = scanInbox("telegram", { agentRoot: root, reclaimMs: 0 });
+    assert.equal(res.items.length, 0);
+  } finally { await rmRoot(root); }
+});
+
+test("writeInboxItem dedupe treats a .dispatched sibling as already-present (no re-create on thread lookback)", async () => {
+  const root = await makeRoot();
+  try {
+    writeInboxItem("telegram", mkItem("1", "v1"), root);
+    markDispatched(mkItem("1", "v1"), "telegram", root);
+    // The 30-min thread lookback would re-write the same message; dedupe must
+    // suppress it because a .dispatched sibling exists (else the in-flight item
+    // gets re-created as a fresh .yaml and double-delivered).
+    writeInboxItem("telegram", mkItem("1", "v1"), root);
+    const dir = join(root, "state/inbox/telegram");
+    const files = await fsp.readdir(dir);
+    const live = files.filter((f) => f.endsWith(".yaml"));
+    assert.equal(live.length, 0, "no fresh .yaml may be created while a .dispatched sibling exists");
+    assert.equal(files.filter((f) => f.endsWith(".dispatched")).length, 1);
+  } finally { await rmRoot(root); }
+});
+
+// Render an item to YAML exactly as writeInboxItem would, without touching disk
+// for the field-parse tests. We re-implement the tiny call by writing to a temp
+// dir via the real writer and reading it back.
+function renderViaWriter(item) {
+  // Inline minimal renderer mirroring scripts/poller/utils.mjs inboxItemToYaml
+  // for the fields under test (the real writer is exercised in scanInbox test).
+  const content = (item.content || "").replace(/\n/g, "\n  ");
+  let yaml = `id: "${item.id}"
+service: "${item.service}"
+channel: "${item.channel}"
+sender: "${item.sender}"
+sender_privilege: "${item.sender_privilege}"
+timestamp: "${item.timestamp}"
+subject: "${item.subject || ""}"
+content: |
+  ${content}
+thread_id: "${item.thread_id || ""}"
+is_reply: ${item.is_reply || false}
+is_voice_transcript: false
+priority_signals:
+  from_ceo: ${item.priority_signals?.from_ceo || false}
+  tagged_urgent: ${item.priority_signals?.tagged_urgent || false}
+  contains_deadline: ${item.priority_signals?.contains_deadline || false}
+  mentions_agent: ${item.priority_signals?.mentions_agent || false}
+raw_ref: "${item.raw_ref || ""}"
+`;
+  if (item.thread_context) {
+    const tc = item.thread_context.replace(/\n/g, "\n  ");
+    yaml += `thread_context: |\n  ${tc}\n`;
+  }
+  if (item.channel_id) yaml += `channel_id: "${item.channel_id}"\n`;
+  if (item.kind) yaml += `kind: "${item.kind}"\n`;
+  return yaml;
+}

package/scripts/poller/index.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Agent Poller — Lightweight event detection daemon
+// Runs every 60 seconds via macOS launchd
+// Polls Slack, Gmail, Calendar for new items
+// Writes to state/inbox/ for the agent daemon to process
+
+import { pollSlack } from "./slack-poller.mjs";
+import { pollGmail } from "./gmail-poller.mjs";
+import { pollCalendar } from "./calendar-poller.mjs";
+import { pollSecondaryGmail } from "./secondary-gmail-poller.mjs";
+import { triggerAgent } from "./trigger.mjs";
+import { isPriorityItem, AGENT_REPO_DIR } from "./utils.mjs";
+import { appendFileSync, mkdirSync } from "fs";
+import { join } from "path";
+
+async function main() {
+  const timestamp = new Date().toISOString();
+  const logDir = join(AGENT_REPO_DIR, "logs", "polling");
+  mkdirSync(logDir, { recursive: true });
+  const logFile = join(logDir, `${timestamp.split("T")[0]}-poller.jsonl`);
+
+  let totalItems = 0;
+  let totalErrors = 0;
+  let priorityTriggered = false;
+
+  const services = [
+    { name: "slack", fn: pollSlack },
+    { name: "gmail", fn: pollGmail },
+    { name: "calendar", fn: pollCalendar },
+    { name: "alex-gmail", fn: pollSecondaryGmail },
+  ];
+
+  for (const svc of services) {
+    try {
+      const result = await svc.fn();
+      totalItems += result.items.length;
+      totalErrors += result.errors.length;
+
+      for (const item of result.items) {
+        if (isPriorityItem(item) && !priorityTriggered) {
+          triggerAgent(item);
+          priorityTriggered = true;
+        }
+      }
+
+      if (result.errors.length > 0) {
+        console.error(`[${svc.name}] Errors:`, result.errors);
+      }
+    } catch (err) {
+      totalErrors++;
+      console.error(`[${svc.name}] Poll failed:`, err.message);
+    }
+  }
+
+  appendFileSync(
+    logFile,
+    JSON.stringify({
+      timestamp,
+      items_found: totalItems,
+      errors: totalErrors,
+      priority_triggered: priorityTriggered,
+    }) + "\n",
+  );
+
+  if (totalItems > 0) {
+    console.log(`[poller] Found ${totalItems} new items`);
+  }
+}
+
+main().catch((err) => {
+  console.error("[poller] Fatal error:", err);
+  process.exit(1);
+});

package/scripts/poller/intra-session-check.mjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+// Intra-Session Inbox Check — Lightweight poll for use within active Claude Code sessions
+// Called every 2 minutes via CronCreate during a session
+// Focuses on:
+//   1. CEO DM channel (D099N1JGKRQ) for immediate-priority messages
+//   2. Critical channels (ceo-office, engineering)
+//   3. Unprocessed inbox items
+//   4. Writing priority triggers when CEO messages detected
+//
+// This complements the 60s launchd poller — it ensures the agent doesn't
+// miss messages while deep in tasks within a session.
+
+import { readdirSync, writeFileSync, mkdirSync, appendFileSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_REPO_DIR = process.env.AGENT_DIR || join(__dirname, "../..");
+
+const SLACK_TOKEN = process.env.SLACK_USER_TOKEN || process.env.SLACK_TOKEN;
+
+// Identity loaded from canonical SOT so principal/agent user IDs aren't
+// hardcoded. The CEO_DM_CHANNEL is detected dynamically (channels starting
+// with "D" are IMs); the previous hardcoded value worked only for Robin.
+function loadAgentIdentity() {
+  try {
+    return JSON.parse(readFileSync(join(AGENT_REPO_DIR, "config/agent.json"), "utf-8"));
+  } catch {
+    return { slackMemberId: "", firstName: "Agent", principal: {} };
+  }
+}
+const _agent = loadAgentIdentity();
+const AGENT_USER_ID = _agent.slackMemberId || "";
+const CEO_USER_ID = _agent.principal?.slackMemberId || "";
+// CEO_DM_CHANNEL is agent-specific (Slack assigns IM channel IDs dynamically).
+// Provide it via env var, otherwise the CEO-DM hot path is skipped on this
+// poll cycle and we rely on the normal channel scan + Slack Events API to
+// catch principal messages.
+const CEO_DM_CHANNEL = process.env.CEO_DM_CHANNEL || "";
+
+// Critical channels to check during intra-session polls
+const CRITICAL_CHANNELS = [
+  { id: "C0ARASMQE1W", name: "ceo-office" },
+  { id: "C099NT6NKK7", name: "engineering" },
+  { id: "C097N5R8HUJ", name: "all-company" },
+];
+
+const TRIGGER_DIR = join(AGENT_REPO_DIR, "state", "triggers", "priority");
+const INBOX_DIRS = ["slack", "gmail", "calendar", "sms", "internal"].map((s) =>
+  join(AGENT_REPO_DIR, "state", "inbox", s),
+);
+const LOG_DIR = join(AGENT_REPO_DIR, "logs", "polling");
+
+async function slackApi(method, params = {}) {
+  const url = new URL(`https://slack.com/api/${method}`);
+  Object.entries(params).forEach(([k, v]) =>
+    url.searchParams.set(k, String(v)),
+  );
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${SLACK_TOKEN}` },
+  });
+  return res.json();
+}
+
+function countFiles(dir, ext = ".yaml") {
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith(ext)).length;
+  } catch {
+    return 0;
+  }
+}
+
+function writePriorityTrigger(source, sender, channel, content, reason) {
+  mkdirSync(TRIGGER_DIR, { recursive: true });
+  const ts = Date.now();
+  const triggerFile = join(TRIGGER_DIR, `ceo-dm-${ts}.yaml`);
+  const triggerContent = `type: priority_trigger
+reason: "${reason}"
+source: "${source}"
+sender: "${sender}"
+channel: "${channel}"
+timestamp: "${new Date().toISOString()}"
+detected_by: intra-session-check
+content: |
+  ${(content || "").replace(/\n/g, "\n  ")}
+`;
+  writeFileSync(triggerFile, triggerContent);
+  return triggerFile;
+}
+
+async function checkCeoDm() {
+  if (!SLACK_TOKEN) return { found: false, error: "SLACK_TOKEN not set" };
+  if (!CEO_DM_CHANNEL) return { found: false, error: "CEO_DM_CHANNEL not configured" };
+
+  // Check last 5 minutes of CEO DM channel
+  const oldest = String((Date.now() - 5 * 60 * 1000) / 1000);
+  try {
+    const result = await slackApi("conversations.history", {
+      channel: CEO_DM_CHANNEL,
+      oldest,
+      limit: 10,
+    });
+
+    if (!result.ok) {
+      return { found: false, error: result.error };
+    }
+
+    const ceoMessages = (result.messages || []).filter(
+      (m) => m.user === CEO_USER_ID && !m.bot_id,
+    );
+
+    if (ceoMessages.length > 0) {
+      const latest = ceoMessages[0];
+      const principalSlug = (_agent.principal?.fullName || "principal").toLowerCase().replace(/\s+/g, "-");
+      const triggerFile = writePriorityTrigger(
+        `slack:${CEO_DM_CHANNEL}:${latest.ts}`,
+        principalSlug,
+        `dm/${principalSlug}`,
+        latest.text,
+        "CEO DM detected during intra-session poll",
+      );
+      return {
+        found: true,
+        count: ceoMessages.length,
+        triggerFile,
+        latestText: (latest.text || "").substring(0, 100),
+      };
+    }
+
+    return { found: false };
+  } catch (err) {
+    return { found: false, error: err.message };
+  }
+}
+
+async function checkCriticalChannels() {
+  if (!SLACK_TOKEN) return [];
+
+  const oldest = String((Date.now() - 3 * 60 * 1000) / 1000);
+  const newMessages = [];
+
+  for (const ch of CRITICAL_CHANNELS) {
+    try {
+      const result = await slackApi("conversations.history", {
+        channel: ch.id,
+        oldest,
+        limit: 5,
+      });
+
+      if (!result.ok) continue;
+
+      const relevant = (result.messages || []).filter(
+        (m) => !m.bot_id && m.user !== AGENT_USER_ID,
+      );
+
+      const agentNameLower = (_agent.firstName || "").toLowerCase();
+      if (relevant.length > 0) {
+        newMessages.push({
+          channel: ch.name,
+          count: relevant.length,
+          hasCeo: relevant.some((m) => m.user === CEO_USER_ID),
+          hasUrgent: relevant.some((m) =>
+            /\b(urgent|emergency|asap|blocker|critical)\b/i.test(m.text || ""),
+          ),
+          hasAgentMention: agentNameLower
+            ? relevant.some((m) => (m.text || "").toLowerCase().includes(agentNameLower))
+            : false,
+        });
+
+        // If the principal posted in a critical channel, also create a trigger.
+        const ceoMsgs = relevant.filter((m) => m.user === CEO_USER_ID);
+        if (ceoMsgs.length > 0) {
+          const principalSlug = (_agent.principal?.fullName || "principal").toLowerCase().replace(/\s+/g, "-");
+          writePriorityTrigger(
+            `slack:${ch.id}:${ceoMsgs[0].ts}`,
+            principalSlug,
+            ch.name,
+            ceoMsgs[0].text,
+            `Principal message in #${ch.name} during intra-session poll`,
+          );
+        }
+      }
+    } catch {
+      // Non-fatal — skip channel
+    }
+  }
+
+  return newMessages;
+}
+
+function checkInbox() {
+  let total = 0;
+  const breakdown = {};
+  for (const dir of INBOX_DIRS) {
+    const count = countFiles(dir);
+    if (count > 0) {
+      const svc = dir.split("/").pop();
+      breakdown[svc] = count;
+      total += count;
+    }
+  }
+  return { total, breakdown };
+}
+
+function checkTriggers() {
+  return countFiles(TRIGGER_DIR);
+}
+
+async function main() {
+  const timestamp = new Date().toISOString();
+  const results = {
+    timestamp,
+    type: "intra_session_check",
+    ceo_dm: null,
+    critical_channels: [],
+    inbox: null,
+    triggers: 0,
+  };
+
+  // 1. Check CEO DM — highest priority
+  results.ceo_dm = await checkCeoDm();
+
+  // 2. Check critical channels
+  results.critical_channels = await checkCriticalChannels();
+
+  // 3. Check unprocessed inbox
+  results.inbox = checkInbox();
+
+  // 4. Check existing triggers
+  results.triggers = checkTriggers();
+
+  // Log the check
+  mkdirSync(LOG_DIR, { recursive: true });
+  const logFile = join(LOG_DIR, `${timestamp.split("T")[0]}-poller.jsonl`);
+  appendFileSync(logFile, JSON.stringify(results) + "\n");
+
+  // Output summary for Claude Code session
+  const parts = [];
+
+  if (results.ceo_dm?.found) {
+    parts.push(
+      `CEO DM: ${results.ceo_dm.count} new message(s) — PRIORITY TRIGGER CREATED`,
+    );
+  }
+
+  if (results.critical_channels.length > 0) {
+    const chSummary = results.critical_channels
+      .map((c) => {
+        const flags = [];
+        if (c.hasCeo) flags.push("CEO");
+        if (c.hasUrgent) flags.push("URGENT");
+        if (c.hasAgentMention) flags.push(`@${_agent.firstName || "Agent"}`);
+        const flagStr = flags.length > 0 ? ` [${flags.join(",")}]` : "";
+        return `#${c.channel}(${c.count})${flagStr}`;
+      })
+      .join(", ");
+    parts.push(`Channels: ${chSummary}`);
+  }
+
+  if (results.inbox.total > 0) {
+    parts.push(`Inbox: ${results.inbox.total} unprocessed`);
+  }
+
+  if (results.triggers > 0) {
+    parts.push(`Triggers: ${results.triggers} pending`);
+  }
+
+  if (parts.length === 0) {
+    console.log(
+      `[inbox-poll] ${timestamp.split("T")[1].split(".")[0]} — Clear`,
+    );
+  } else {
+    console.log(`[inbox-poll] ${parts.join(" | ")}`);
+  }
+
+  // Exit with code 2 if CEO message found (allows caller to detect priority)
+  if (results.ceo_dm?.found) {
+    process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  console.error("[inbox-poll] Error:", err.message);
+  process.exit(1);
+});

package/scripts/poller/lib/cloud-relay-dedup.mjs

@@ -0,0 +1,88 @@
+/**
+ * cloud-relay-dedup.mjs — pure payload-parsing + dedup helpers for the Slack
+ * cloud-relay client (audit L30).
+ *
+ * Extracted from scripts/poller/slack-cloud-relay-client.mjs so the parse/dedup
+ * logic can be unit-tested in isolation. The client module imports `dotenv` and
+ * opens a live SSE connection at load, neither of which a test wants; these two
+ * functions are pure (no I/O, no env, no network), so they live here and the
+ * client imports them back. The reconnect-replay filesystem dedup this guards
+ * was a production fix (commit ccfbaed) — see isReplayInSiblings.
+ *
+ * Node builtins only (maestro is "type":"module", near-zero-dep by design).
+ *
+ * @module scripts/poller/lib/cloud-relay-dedup
+ */
+
+/**
+ * Create a stateful Server-Sent-Events parser. Push raw bytes from the relay
+ * into `push(chunk)`; it returns an array of complete event payloads (the JSON
+ * text from each `data:` block) discovered in that chunk. Per the SSE spec:
+ *   - an event is terminated by a blank line,
+ *   - `data:` lines may repeat and are concatenated with newlines,
+ *   - a single leading space after the colon is stripped,
+ *   - lines beginning with `:` are comments (the relay uses these as
+ *     heartbeats) and are ignored,
+ *   - `event:` / `id:` / `retry:` lines are ignored (the relay never sends
+ *     them).
+ *
+ * The parser buffers across chunk boundaries, so an event split mid-line over
+ * two `push` calls is still parsed correctly.
+ *
+ * @returns {{ push(chunk: string): string[] }}
+ */
+export 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;
+    },
+  };
+}
+
+/**
+ * Decide whether an event with the given Slack timestamp key has already been
+ * written to the inbox, based on the existing inbox filenames.
+ *
+ * Cloud-relay reconnects replay the same event after a process restart (the
+ * in-memory seenEventIds Set is reset on restart), so we gate on filesystem
+ * state: if any sibling file for this (ts, cloud-relay) tuple already exists —
+ * pending OR `.processed` — the event is a replay and must be discarded. This
+ * pins the regression fixed in commit ccfbaed (event_id=Ev0B4MAFCX62 replayed
+ * 13x across restart cycles).
+ *
+ * Pure: takes the directory listing as input so it can be tested without I/O.
+ *
+ * @param {string[]} siblings  filenames currently in the inbox directory
+ * @param {string}   tsKey     Slack ts with "." replaced by "-"
+ *                             (e.g. "1700000000-001000")
+ * @returns {boolean} true if a matching sibling (pending or processed) exists
+ */
+export function isReplayInSiblings(siblings, tsKey) {
+  const replaySuffix = `-${tsKey}-cloud-relay.json`;
+  return siblings.some(
+    (f) => f.endsWith(replaySuffix) || f.endsWith(`${replaySuffix}.processed`),
+  );
+}