@cohortapp/agent-sdk 2.3.0

package/lib/channels/pairing.mjs

@@ -0,0 +1,363 @@
+/**
+ * Maestro — Cross-channel DM pairing gate (default-DENY)
+ *
+ * WS2 (design §5) makes every channel default-deny for *unknown DM senders*:
+ * a stranger who DMs the agent on Telegram/WhatsApp/Slack is dropped (with a
+ * one-time pairing prompt) unless their peer id is on the allowlist. Pairing
+ * is the bootstrap: the operator runs `maestro pair` (or the agent emits a
+ * code), the human replies `pair <code>` in the DM, and that peer id is
+ * appended to `config/allowlist.yaml` for the channel.
+ *
+ * This module is enforced by `BaseAdapter.start`'s onInbound wrapper, so every
+ * channel inherits the same policy. Three concerns live here so the existing
+ * Slack self-message / peer-agent drops fold into one place:
+ *
+ *   - `checkAllowed(ev, { agentRoot })` → { allowed, reason, isPairingCommand }
+ *       The gate. Returns allowed=false for unknown DM senders (reason
+ *       "not-paired"), self-messages ("self-message"), peer agents
+ *       ("peer-agent"). Non-DM/group traffic bypasses pairing (membership +
+ *       directed-gate govern it instead) → allowed=true, reason "non-dm".
+ *       `^pair <code>$` is flagged isPairingCommand so the caller intercepts
+ *       it before the classifier ever sees it.
+ *   - `startPairing(channel, { agentRoot, ttlMs })` → { code, expiresAt }
+ *       Mints a short unambiguous code, persists it under
+ *       state/channels/pairing/<code>.json (chmod 0600) with a TTL.
+ *   - `redeemPairing(channel, peerId, code, { agentRoot })` → { ok, reason? }
+ *       Validates an unexpired code and appends the peer to the allowlist.
+ *
+ * Allowlist format (config/allowlist.yaml) — intentionally a tiny, explicit
+ * YAML map parsed/written by a built-in mini-parser so the hot
+ * `checkAllowed` path needs no dynamic js-yaml import and the module stays
+ * fully hermetic:
+ *
+ *   slack:
+ *     - U0123ABC
+ *   telegram:
+ *     - "987654321"   # paired 2026-06-09 via code 7Q4K
+ *
+ * @module lib/channels/pairing
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  unlinkSync,
+  rmSync,
+  chmodSync,
+} from "node:fs";
+import { randomInt } from "node:crypto";
+
+const PAIRING_DIR = "state/channels/pairing";
+const ALLOWLIST_FILE = "config/allowlist.yaml";
+const DEFAULT_TTL_MS = 15 * 60 * 1000; // 15 minutes
+
+// Unambiguous alphabet: no 0/O, 1/I/L — avoids transcription errors when a
+// human reads a code off a screen and types it into a chat.
+const CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+const CODE_LENGTH = 6;
+
+// ---------------------------------------------------------------------------
+// Allowlist (config/allowlist.yaml) — tiny, dependency-free YAML map.
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the minimal allowlist YAML into `{ channel: Set<peerId> }`. Tolerant:
+ * unknown lines are ignored, ids may be quoted, inline `#` comments stripped.
+ * Returns an empty map when the file is missing or malformed (default-deny).
+ *
+ * @param {string} agentRoot
+ * @returns {Record<string, Set<string>>}
+ */
+export function readAllowlist(agentRoot) {
+  const path = join(agentRoot, ALLOWLIST_FILE);
+  const out = {};
+  if (!existsSync(path)) return out;
+  let body;
+  try {
+    body = readFileSync(path, "utf-8");
+  } catch {
+    return out;
+  }
+  let currentChannel = null;
+  for (const raw of body.split("\n")) {
+    const line = raw.replace(/\t/g, "  ");
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    // Top-level key: "<channel>:" (no leading whitespace).
+    const keyMatch = line.match(/^([A-Za-z][\w-]*):\s*(.*)$/);
+    if (keyMatch && !/^\s/.test(line)) {
+      currentChannel = keyMatch[1];
+      if (!out[currentChannel]) out[currentChannel] = new Set();
+      // Inline `[a, b]` flow list support (rare, but cheap).
+      const inline = keyMatch[2].trim();
+      if (inline.startsWith("[") && inline.endsWith("]")) {
+        for (const tok of inline.slice(1, -1).split(",")) {
+          const id = stripIdToken(tok);
+          if (id) out[currentChannel].add(id);
+        }
+        currentChannel = null; // inline list closes the key
+      }
+      continue;
+    }
+    // List item: "- <id>" under the current channel.
+    const itemMatch = line.match(/^\s*-\s*(.+)$/);
+    if (itemMatch && currentChannel) {
+      const id = stripIdToken(itemMatch[1]);
+      if (id) out[currentChannel].add(id);
+    }
+  }
+  return out;
+}
+
+function stripIdToken(tok) {
+  let t = String(tok).trim();
+  // Quoted value (possibly followed by a trailing comment): capture the quoted
+  // span and discard everything after the closing quote.
+  const q = t.match(/^(['"])(.*?)\1/);
+  if (q) return q[2].trim();
+  // Unquoted: a `#` starts an inline comment.
+  const hash = t.indexOf("#");
+  if (hash >= 0) t = t.slice(0, hash).trim();
+  return t.trim();
+}
+
+/**
+ * Append a peer id to a channel's allowlist (idempotent). Creates the file +
+ * the channel key if absent. Returns true when a new id was added, false when
+ * it was already present.
+ *
+ * @param {string} agentRoot
+ * @param {string} channel
+ * @param {string} peerId
+ * @returns {boolean} whether the id was newly added
+ */
+export function appendToAllowlist(agentRoot, channel, peerId, note) {
+  const path = join(agentRoot, ALLOWLIST_FILE);
+  const current = readAllowlist(agentRoot);
+  if (current[channel] && current[channel].has(String(peerId))) return false;
+
+  mkdirSync(join(agentRoot, "config"), { recursive: true });
+  let body = existsSync(path) ? readFileSync(path, "utf-8") : "";
+  if (body && !body.endsWith("\n")) body += "\n";
+
+  const quoted = /^\d+$/.test(String(peerId)) ? `"${peerId}"` : String(peerId);
+  const comment = note ? `   # ${note}` : "";
+
+  // If the channel key already exists, insert the item right after it;
+  // otherwise append a new key block at the end.
+  const keyLine = new RegExp(`^${escapeRegExp(channel)}:\\s*$`, "m");
+  if (keyLine.test(body)) {
+    body = body.replace(keyLine, (m) => `${m}\n  - ${quoted}${comment}`);
+  } else {
+    body += `${channel}:\n  - ${quoted}${comment}\n`;
+  }
+  writeFileSync(path, body);
+  return true;
+}
+
+function escapeRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ---------------------------------------------------------------------------
+// Pairing-command detection.
+// ---------------------------------------------------------------------------
+
+const PAIR_COMMAND_RE = /^\s*pair\s+([A-Za-z0-9]{4,12})\s*$/i;
+
+/** Extract a pairing code from a message body, or null. */
+export function parsePairCommand(text) {
+  if (typeof text !== "string") return null;
+  const m = text.match(PAIR_COMMAND_RE);
+  return m ? m[1].toUpperCase() : null;
+}
+
+// ---------------------------------------------------------------------------
+// checkAllowed — the gate.
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {import("./contract.mjs").MessageEvent & Record<string,any>} ev
+ * @param {object} opts
+ * @param {string} opts.agentRoot
+ * @param {string} [opts.ownId]        the agent's own peer id on this channel (drop self)
+ * @param {Set<string>|string[]} [opts.peerAgentIds] peer-agent ids to drop
+ * @returns {{ allowed: boolean, reason: string, isPairingCommand: boolean, code?: string }}
+ */
+export function checkAllowed(ev, opts = {}) {
+  const agentRoot = opts.agentRoot;
+  const source = ev?.source || {};
+  const scope = source.userScope || (isDmEvent(ev) ? "dm" : "group");
+  const senderId = String(ev?.from?.id ?? source.peerId ?? "");
+
+  // A pairing command is always recognised (even from an unknown sender) so
+  // the adapter can intercept + redeem it before the classifier.
+  const code = parsePairCommand(ev?.text);
+  const isPairingCommand = !!code;
+
+  // Self-message: the agent's own outbound echoed back.
+  if (opts.ownId && senderId && senderId === String(opts.ownId)) {
+    return { allowed: false, reason: "self-message", isPairingCommand, code: code || undefined };
+  }
+
+  // Peer agent: another maestro agent — never converse (loops two daemons).
+  const peers = toSet(opts.peerAgentIds);
+  if (senderId && peers.has(senderId)) {
+    return { allowed: false, reason: "peer-agent", isPairingCommand, code: code || undefined };
+  }
+
+  // Non-DM (group/channel) traffic bypasses pairing — membership + the
+  // directed-gate decide there.
+  if (scope !== "dm") {
+    return { allowed: true, reason: "non-dm", isPairingCommand, code: code || undefined };
+  }
+
+  // DM path: default-DENY unless the sender is on the allowlist.
+  const allow = readAllowlist(agentRoot || ".");
+  const channel = source.channel || ev?.channel || "unknown";
+  const paired = !!(allow[channel] && allow[channel].has(senderId));
+  if (paired) {
+    return { allowed: true, reason: "paired", isPairingCommand, code: code || undefined };
+  }
+
+  // Unknown DM sender. The command itself is allowed to *reach the adapter*
+  // (so it can redeem), but it is NOT a normal allowed message.
+  return { allowed: false, reason: "not-paired", isPairingCommand, code: code || undefined };
+}
+
+function isDmEvent(ev) {
+  const ch = ev?.channel_label || ev?.channel || "";
+  const cid = ev?.channel_id || ev?.source?.chatId || "";
+  return (typeof ch === "string" && ch.startsWith("dm/")) || (typeof cid === "string" && cid.startsWith("D"));
+}
+
+function toSet(v) {
+  if (v instanceof Set) return v;
+  if (Array.isArray(v)) return new Set(v.map(String));
+  return new Set();
+}
+
+// ---------------------------------------------------------------------------
+// startPairing / redeemPairing.
+// ---------------------------------------------------------------------------
+
+/** Mint a random unambiguous pairing code. */
+export function mintCode() {
+  let s = "";
+  for (let i = 0; i < CODE_LENGTH; i++) s += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
+  return s;
+}
+
+/**
+ * Start a pairing for `channel`: mint a code, persist it (0600) with a TTL.
+ *
+ * @param {string} channel
+ * @param {object} opts
+ * @param {string} opts.agentRoot
+ * @param {number} [opts.ttlMs]
+ * @param {()=>number} [opts.now]
+ * @returns {{ code: string, expiresAt: number }}
+ */
+export function startPairing(channel, opts = {}) {
+  const agentRoot = opts.agentRoot || ".";
+  const ttlMs = typeof opts.ttlMs === "number" && opts.ttlMs > 0 ? opts.ttlMs : DEFAULT_TTL_MS;
+  const now = (opts.now || Date.now)();
+  const dir = join(agentRoot, PAIRING_DIR);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const code = mintCode();
+  const expiresAt = now + ttlMs;
+  const file = join(dir, `${code}.json`);
+  const payload = JSON.stringify({ channel, code, createdAt: now, expiresAt }, null, 2) + "\n";
+  // Write then chmod 0600 (the code is a short-lived shared secret). The mode
+  // arg on writeFileSync only applies on create; chmod enforces it even when
+  // the file pre-existed or umask widened it.
+  writeFileSync(file, payload, { mode: 0o600 });
+  try { chmodSync(file, 0o600); } catch { /* best-effort */ }
+  return { code, expiresAt };
+}
+
+/**
+ * Redeem a pairing code for a peer id on a channel. Validates the code exists,
+ * is unexpired, and (when stored) matches the channel; then appends the peer to
+ * the allowlist and consumes the code file.
+ *
+ * @param {string} channel
+ * @param {string} peerId
+ * @param {string} code
+ * @param {object} opts
+ * @param {string} opts.agentRoot
+ * @param {()=>number} [opts.now]
+ * @returns {{ ok: boolean, reason?: string, added?: boolean }}
+ */
+export function redeemPairing(channel, peerId, code, opts = {}) {
+  const agentRoot = opts.agentRoot || ".";
+  const now = (opts.now || Date.now)();
+  const normalized = String(code || "").toUpperCase();
+  if (!normalized) return { ok: false, reason: "no-code" };
+  if (!peerId) return { ok: false, reason: "no-peer" };
+
+  const file = join(agentRoot, PAIRING_DIR, `${normalized}.json`);
+  if (!existsSync(file)) return { ok: false, reason: "unknown-code" };
+
+  let rec;
+  try {
+    rec = JSON.parse(readFileSync(file, "utf-8"));
+  } catch {
+    return { ok: false, reason: "corrupt-code" };
+  }
+  if (typeof rec.expiresAt === "number" && now > rec.expiresAt) {
+    try { unlinkSync(file); } catch { /* */ }
+    return { ok: false, reason: "expired" };
+  }
+  if (rec.channel && rec.channel !== channel) {
+    return { ok: false, reason: "channel-mismatch" };
+  }
+
+  const added = appendToAllowlist(agentRoot, channel, peerId, `paired ${new Date(now).toISOString().slice(0, 10)} via code ${normalized}`);
+  // Consume the code (single-use).
+  try { unlinkSync(file); } catch { /* */ }
+  return { ok: true, added };
+}
+
+/**
+ * Sweep expired pairing codes. Returns the number removed. Best-effort.
+ * @param {string} agentRoot
+ * @param {()=>number} [now]
+ */
+export function sweepExpiredCodes(agentRoot, now = Date.now) {
+  const dir = join(agentRoot, PAIRING_DIR);
+  if (!existsSync(dir)) return 0;
+  let removed = 0;
+  const t = now();
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    const file = join(dir, f);
+    try {
+      const rec = JSON.parse(readFileSync(file, "utf-8"));
+      if (typeof rec.expiresAt === "number" && t > rec.expiresAt) {
+        rmSync(file, { force: true });
+        removed++;
+      }
+    } catch {
+      /* leave unreadable files for the operator */
+    }
+  }
+  return removed;
+}
+
+export default {
+  readAllowlist,
+  appendToAllowlist,
+  parsePairCommand,
+  checkAllowed,
+  mintCode,
+  startPairing,
+  redeemPairing,
+  sweepExpiredCodes,
+};

package/lib/channels/pairing.test.mjs

@@ -0,0 +1,270 @@
+/**
+ * pairing.test.mjs — node:test coverage for lib/channels/pairing.mjs
+ *
+ * Covers: default-deny for unknown DM senders, self/peer drops, non-DM bypass,
+ * pair-command interception, startPairing TTL + 0600 perms, redeemPairing
+ * (happy path, expired, unknown, channel-mismatch, single-use), allowlist
+ * read/append round-trip. Hermetic — uses an injectable `now` and tmpdirs.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { statSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  checkAllowed,
+  startPairing,
+  redeemPairing,
+  parsePairCommand,
+  readAllowlist,
+  appendToAllowlist,
+  sweepExpiredCodes,
+  mintCode,
+} from "./pairing.mjs";
+
+async function makeRoot() {
+  const p = join(tmpdir(), `pairing-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 { /* */ } }
+
+function dmEvent(channel, senderId, text = "hello") {
+  return {
+    channel,
+    text,
+    from: { id: senderId },
+    source: { channel, chatId: senderId, userScope: "dm", peerId: senderId },
+  };
+}
+function groupEvent(channel, senderId, text = "hello team") {
+  return {
+    channel,
+    text,
+    from: { id: senderId },
+    source: { channel, chatId: "G1", userScope: "group", peerId: senderId },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// checkAllowed — default-DENY
+// ---------------------------------------------------------------------------
+
+test("unknown DM sender is denied with reason not-paired", async () => {
+  const root = await makeRoot();
+  try {
+    const res = checkAllowed(dmEvent("telegram", "987"), { agentRoot: root });
+    assert.equal(res.allowed, false);
+    assert.equal(res.reason, "not-paired");
+    assert.equal(res.isPairingCommand, false);
+  } finally { await rmRoot(root); }
+});
+
+test("paired DM sender is allowed", async () => {
+  const root = await makeRoot();
+  try {
+    appendToAllowlist(root, "telegram", "987");
+    const res = checkAllowed(dmEvent("telegram", "987"), { agentRoot: root });
+    assert.equal(res.allowed, true);
+    assert.equal(res.reason, "paired");
+  } finally { await rmRoot(root); }
+});
+
+test("self-message is dropped", async () => {
+  const root = await makeRoot();
+  try {
+    const res = checkAllowed(dmEvent("slack", "UAGENT"), { agentRoot: root, ownId: "UAGENT" });
+    assert.equal(res.allowed, false);
+    assert.equal(res.reason, "self-message");
+  } finally { await rmRoot(root); }
+});
+
+test("peer-agent message is dropped", async () => {
+  const root = await makeRoot();
+  try {
+    const res = checkAllowed(dmEvent("slack", "UPEER"), { agentRoot: root, peerAgentIds: ["UPEER", "UPEER2"] });
+    assert.equal(res.allowed, false);
+    assert.equal(res.reason, "peer-agent");
+  } finally { await rmRoot(root); }
+});
+
+test("non-DM (group) traffic bypasses pairing", async () => {
+  const root = await makeRoot();
+  try {
+    // Unknown sender, but in a group → allowed (membership + directed-gate govern).
+    const res = checkAllowed(groupEvent("slack", "USTRANGER"), { agentRoot: root });
+    assert.equal(res.allowed, true);
+    assert.equal(res.reason, "non-dm");
+  } finally { await rmRoot(root); }
+});
+
+test("pair command is flagged isPairingCommand even from an unknown DM sender", async () => {
+  const root = await makeRoot();
+  try {
+    const res = checkAllowed(dmEvent("telegram", "987", "pair 7Q4KMN"), { agentRoot: root });
+    assert.equal(res.isPairingCommand, true);
+    assert.equal(res.code, "7Q4KMN");
+    // Still not a normal allowed message until redeemed.
+    assert.equal(res.allowed, false);
+    assert.equal(res.reason, "not-paired");
+  } finally { await rmRoot(root); }
+});
+
+test("parsePairCommand matches ^pair <code>$ only", () => {
+  assert.equal(parsePairCommand("pair ABCD"), "ABCD");
+  assert.equal(parsePairCommand("PAIR abcd23"), "ABCD23");
+  assert.equal(parsePairCommand("  pair 7q4k  "), "7Q4K");
+  assert.equal(parsePairCommand("please pair ABCD now"), null);
+  assert.equal(parsePairCommand("pairing"), null);
+  assert.equal(parsePairCommand(""), null);
+  assert.equal(parsePairCommand(undefined), null);
+});
+
+// ---------------------------------------------------------------------------
+// startPairing — code + TTL + 0600
+// ---------------------------------------------------------------------------
+
+test("startPairing mints a code, persists it 0600, with a TTL", async () => {
+  const root = await makeRoot();
+  try {
+    const t0 = 1_000_000;
+    const { code, expiresAt } = startPairing("telegram", { agentRoot: root, ttlMs: 60_000, now: () => t0 });
+    assert.match(code, /^[A-Z0-9]{6}$/);
+    assert.equal(expiresAt, t0 + 60_000);
+    const file = join(root, "state/channels/pairing", `${code}.json`);
+    assert.ok(existsSync(file));
+    // POSIX perms: 0600 (owner rw only). Mask to the permission bits.
+    const mode = statSync(file).mode & 0o777;
+    assert.equal(mode, 0o600, `expected 0600, got ${mode.toString(8)}`);
+  } finally { await rmRoot(root); }
+});
+
+test("mintCode uses an unambiguous alphabet (no 0/O/1/I/L)", () => {
+  for (let i = 0; i < 50; i++) {
+    const c = mintCode();
+    assert.doesNotMatch(c, /[01OIL]/, `code ${c} contains an ambiguous char`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// redeemPairing
+// ---------------------------------------------------------------------------
+
+test("redeemPairing: happy path adds the peer and consumes the code", async () => {
+  const root = await makeRoot();
+  try {
+    const t0 = 5_000;
+    const { code } = startPairing("telegram", { agentRoot: root, ttlMs: 60_000, now: () => t0 });
+    const res = redeemPairing("telegram", "987", code, { agentRoot: root, now: () => t0 + 1000 });
+    assert.equal(res.ok, true);
+    assert.equal(res.added, true);
+    // Peer is now on the allowlist.
+    const allow = readAllowlist(root);
+    assert.ok(allow.telegram.has("987"));
+    // Code file consumed (single-use).
+    assert.ok(!existsSync(join(root, "state/channels/pairing", `${code}.json`)));
+    // A now-allowed DM passes the gate.
+    const gate = checkAllowed(dmEvent("telegram", "987"), { agentRoot: root });
+    assert.equal(gate.allowed, true);
+  } finally { await rmRoot(root); }
+});
+
+test("redeemPairing: expired code is rejected and cleaned up", async () => {
+  const root = await makeRoot();
+  try {
+    const t0 = 10_000;
+    const { code } = startPairing("telegram", { agentRoot: root, ttlMs: 1000, now: () => t0 });
+    const res = redeemPairing("telegram", "987", code, { agentRoot: root, now: () => t0 + 5000 });
+    assert.equal(res.ok, false);
+    assert.equal(res.reason, "expired");
+    assert.ok(!existsSync(join(root, "state/channels/pairing", `${code}.json`)));
+    // Not added.
+    assert.equal(readAllowlist(root).telegram, undefined);
+  } finally { await rmRoot(root); }
+});
+
+test("redeemPairing: unknown code rejected", async () => {
+  const root = await makeRoot();
+  try {
+    const res = redeemPairing("telegram", "987", "ZZZZZZ", { agentRoot: root });
+    assert.equal(res.ok, false);
+    assert.equal(res.reason, "unknown-code");
+  } finally { await rmRoot(root); }
+});
+
+test("redeemPairing: channel mismatch rejected, code not consumed", async () => {
+  const root = await makeRoot();
+  try {
+    const t0 = 1000;
+    const { code } = startPairing("telegram", { agentRoot: root, ttlMs: 60_000, now: () => t0 });
+    const res = redeemPairing("slack", "987", code, { agentRoot: root, now: () => t0 + 100 });
+    assert.equal(res.ok, false);
+    assert.equal(res.reason, "channel-mismatch");
+    // Still present (so the right channel can redeem it).
+    assert.ok(existsSync(join(root, "state/channels/pairing", `${code}.json`)));
+  } finally { await rmRoot(root); }
+});
+
+test("redeemPairing is single-use: a second redeem fails", async () => {
+  const root = await makeRoot();
+  try {
+    const t0 = 1000;
+    const { code } = startPairing("telegram", { agentRoot: root, ttlMs: 60_000, now: () => t0 });
+    assert.equal(redeemPairing("telegram", "987", code, { agentRoot: root, now: () => t0 + 1 }).ok, true);
+    const second = redeemPairing("telegram", "654", code, { agentRoot: root, now: () => t0 + 2 });
+    assert.equal(second.ok, false);
+    assert.equal(second.reason, "unknown-code");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// allowlist read/append + sweep
+// ---------------------------------------------------------------------------
+
+test("appendToAllowlist is idempotent and groups under the channel key", async () => {
+  const root = await makeRoot();
+  try {
+    assert.equal(appendToAllowlist(root, "slack", "U1"), true);
+    assert.equal(appendToAllowlist(root, "slack", "U1"), false, "duplicate should not re-add");
+    assert.equal(appendToAllowlist(root, "slack", "U2"), true);
+    assert.equal(appendToAllowlist(root, "telegram", "987"), true);
+    const allow = readAllowlist(root);
+    assert.deepEqual([...allow.slack].sort(), ["U1", "U2"]);
+    assert.ok(allow.telegram.has("987"));
+  } finally { await rmRoot(root); }
+});
+
+test("readAllowlist tolerates comments, quotes, and inline flow lists", async () => {
+  const root = await makeRoot();
+  try {
+    await fsp.mkdir(join(root, "config"), { recursive: true });
+    await fsp.writeFile(join(root, "config/allowlist.yaml"),
+      [
+        "# cross-channel DM allowlist",
+        "slack:",
+        "  - U1   # casey",
+        '  - "U2"',
+        "telegram: [ \"987\", 654 ]",
+        "",
+      ].join("\n"));
+    const allow = readAllowlist(root);
+    assert.deepEqual([...allow.slack].sort(), ["U1", "U2"]);
+    assert.deepEqual([...allow.telegram].sort(), ["654", "987"]);
+  } finally { await rmRoot(root); }
+});
+
+test("sweepExpiredCodes removes only expired codes", async () => {
+  const root = await makeRoot();
+  try {
+    const t0 = 1000;
+    const fresh = startPairing("telegram", { agentRoot: root, ttlMs: 100_000, now: () => t0 });
+    const stale = startPairing("slack", { agentRoot: root, ttlMs: 10, now: () => t0 });
+    const removed = sweepExpiredCodes(root, () => t0 + 5000);
+    assert.equal(removed, 1);
+    assert.ok(existsSync(join(root, "state/channels/pairing", `${fresh.code}.json`)));
+    assert.ok(!existsSync(join(root, "state/channels/pairing", `${stale.code}.json`)));
+  } finally { await rmRoot(root); }
+});