switchroom 0.21.17 → 0.21.18

package/dist/host-control/main.js

@@ -21598,7 +21598,7 @@ function allocateAgentUid(name) {
 }
 
 // src/build-info.ts
-var VERSION = "0.21.17";
+var VERSION = "0.21.18";
 
 // src/setup/hindsight-recall-passthrough.ts
 var HINDSIGHT_RECALL_TAG_WEIGHT_SEED = Object.freeze({ sidechain: 0.8 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.21.17",
+  "version": "0.21.18",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -105876,10 +105876,10 @@ function startOutboxSweep(deps) {
 }
 
 // ../src/build-info.ts
-var VERSION2 = "0.21.17";
-var COMMIT_SHA = "ac61272c";
-var COMMIT_DATE = "2026-08-17T16:42:58Z";
-var LATEST_PR = 4768;
+var VERSION2 = "0.21.18";
+var COMMIT_SHA = "ae063418";
+var COMMIT_DATE = "2026-08-18T03:14:53Z";
+var LATEST_PR = 4772;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts

package/telegram-plugin/scripts/bun-test-ci.sh

@@ -82,6 +82,12 @@ else
     uat/load-env.test.ts
     uat/uat-driver.test.ts
     uat/runners/
+    # M3 directive-flip UAT — deterministic (no-model, no-network) gate half.
+    # Same rationale as uat/runners/: vitest excludes all of uat/**, and these
+    # import `vitest` (bun runs them via its vitest-compat shim) — so they run
+    # on the BUN side. Directory match (trailing slash) never widens into
+    # uat/scenarios/. Fenced by scripts/check-test-runner-coverage.mjs.
+    uat/flip/
   )
 fi
 

package/telegram-plugin/uat/flip/allowlist.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Unit suite for the UAT allowlist add/remove helper. Runs under `bun test`
+ * (this tree is vitest-excluded) via the `uat/flip/` entry in
+ * telegram-plugin/scripts/bun-test-ci.sh.
+ *
+ * Everything is hermetic: a tmp `agentsDir` is built per-test and torn down,
+ * and the clock is injected so `expiresAt`/`--expired` are deterministic. No
+ * real ~/.switchroom is touched.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  addToAllowlist,
+  removeFromAllowlist,
+  sweepAllowlist,
+  runAllowlistCli,
+  accessFilePath,
+  receiptPath,
+  DEFAULT_TTL_MS,
+  type AllowlistReceipt,
+} from "./allowlist.js";
+
+let agentsDir: string;
+let root: string;
+
+function seedAccess(agent: string, obj: unknown): void {
+  const p = accessFilePath(agentsDir, agent);
+  mkdirSync(join(p, ".."), { recursive: true });
+  writeFileSync(p, JSON.stringify(obj, null, 2) + "\n");
+}
+
+function readAccess(agent: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(accessFilePath(agentsDir, agent), "utf8"));
+}
+
+function readReceipt(agent: string): AllowlistReceipt {
+  return JSON.parse(readFileSync(receiptPath(agentsDir, agent), "utf8"));
+}
+
+function mkAgentDir(agent: string): void {
+  mkdirSync(join(agentsDir, agent, "telegram"), { recursive: true });
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "sr-uat-allowlist-"));
+  agentsDir = join(root, "agents");
+  mkdirSync(agentsDir, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("addToAllowlist", () => {
+  it("appends the id, preserves sibling keys, and writes a receipt first", () => {
+    seedAccess("ziggy", {
+      dmPolicy: "allowlist",
+      allowFrom: ["111"],
+      groups: { "-100": { allowFrom: ["222"] } },
+      voice_in: true,
+    });
+    const now = Date.parse("2026-08-18T00:00:00.000Z");
+    const r = addToAllowlist("ziggy", "999", { agentsDir, now: () => now });
+
+    expect(r.added).toBe(true);
+    expect(r.preexisting).toBe(false);
+
+    const access = readAccess("ziggy");
+    expect(access.allowFrom).toEqual(["111", "999"]);
+    // sibling keys survive the whole-object rewrite.
+    expect(access.groups).toEqual({ "-100": { allowFrom: ["222"] } });
+    expect(access.voice_in).toBe(true);
+    expect(access.dmPolicy).toBe("allowlist");
+
+    const rcpt = readReceipt("ziggy");
+    expect(rcpt).toMatchObject({ agent: "ziggy", userId: "999", preexisting: false });
+    expect(rcpt.addedAt).toBe("2026-08-18T00:00:00.000Z");
+    expect(Date.parse(rcpt.expiresAt) - now).toBe(DEFAULT_TTL_MS);
+  });
+
+  it("creates access.json when none exists yet", () => {
+    mkAgentDir("newbie");
+    const r = addToAllowlist("newbie", "42", { agentsDir });
+    expect(r.added).toBe(true);
+    expect(readAccess("newbie").allowFrom).toEqual(["42"]);
+  });
+
+  it("is a no-op with preexisting:true when the id is already allowlisted", () => {
+    seedAccess("ziggy", { allowFrom: ["999"] });
+    const r = addToAllowlist("ziggy", "999", { agentsDir });
+    expect(r.added).toBe(false);
+    expect(r.preexisting).toBe(true);
+    // access.json unchanged; receipt records preexisting so revert won't strip it.
+    expect(readAccess("ziggy").allowFrom).toEqual(["999"]);
+    expect(readReceipt("ziggy").preexisting).toBe(true);
+  });
+
+  it("a second add is a no-op preserving the original receipt", () => {
+    seedAccess("ziggy", { allowFrom: [] });
+    const first = addToAllowlist("ziggy", "999", { agentsDir, now: () => 1000 });
+    const second = addToAllowlist("ziggy", "999", { agentsDir, now: () => 5000 });
+    expect(first.added).toBe(true);
+    expect(second.added).toBe(false);
+    // original addedAt preserved (not re-stamped to 5000).
+    expect(readReceipt("ziggy").addedAt).toBe(new Date(1000).toISOString());
+  });
+});
+
+describe("removeFromAllowlist", () => {
+  it("reverts an id the UAT added and clears the receipt", () => {
+    seedAccess("ziggy", { allowFrom: ["111"] });
+    addToAllowlist("ziggy", "999", { agentsDir });
+    expect(readAccess("ziggy").allowFrom).toEqual(["111", "999"]);
+
+    const r = removeFromAllowlist("ziggy", { agentsDir });
+    expect(r.reverted).toBe(true);
+    expect(r.receiptCleared).toBe(true);
+    expect(readAccess("ziggy").allowFrom).toEqual(["111"]);
+    expect(existsSync(receiptPath(agentsDir, "ziggy"))).toBe(false);
+  });
+
+  it("does NOT strip a preexisting id, but clears the receipt", () => {
+    seedAccess("ziggy", { allowFrom: ["999"] });
+    addToAllowlist("ziggy", "999", { agentsDir }); // preexisting
+    const r = removeFromAllowlist("ziggy", { agentsDir });
+    expect(r.reverted).toBe(false);
+    expect(r.reason).toBe("preexisting");
+    expect(r.receiptCleared).toBe(true);
+    expect(readAccess("ziggy").allowFrom).toEqual(["999"]);
+    expect(existsSync(receiptPath(agentsDir, "ziggy"))).toBe(false);
+  });
+
+  it("no-ops with no-receipt when there is nothing to revert", () => {
+    seedAccess("ziggy", { allowFrom: ["111"] });
+    const r = removeFromAllowlist("ziggy", { agentsDir });
+    expect(r.reverted).toBe(false);
+    expect(r.reason).toBe("no-receipt");
+    expect(readAccess("ziggy").allowFrom).toEqual(["111"]);
+  });
+
+  it("is idempotent — a second remove after revert is a no-op", () => {
+    seedAccess("ziggy", { allowFrom: [] });
+    addToAllowlist("ziggy", "999", { agentsDir });
+    removeFromAllowlist("ziggy", { agentsDir });
+    const second = removeFromAllowlist("ziggy", { agentsDir });
+    expect(second.reverted).toBe(false);
+    expect(second.reason).toBe("no-receipt");
+  });
+
+  it("handles a receipt whose id was already manually removed", () => {
+    seedAccess("ziggy", { allowFrom: [] });
+    addToAllowlist("ziggy", "999", { agentsDir });
+    // someone else stripped the id out of band.
+    seedAccess("ziggy", { allowFrom: [] });
+    const r = removeFromAllowlist("ziggy", { agentsDir });
+    expect(r.reverted).toBe(false);
+    expect(r.reason).toBe("not-present");
+    expect(r.receiptCleared).toBe(true);
+  });
+});
+
+describe("sweepAllowlist", () => {
+  it("reverts every agent's receipt and is idempotent on a clean second pass", () => {
+    seedAccess("a", { allowFrom: [] });
+    seedAccess("b", { allowFrom: ["7"] });
+    addToAllowlist("a", "999", { agentsDir });
+    addToAllowlist("b", "888", { agentsDir });
+
+    const first = sweepAllowlist({ agentsDir });
+    expect(first.map((r) => r.agent).sort()).toEqual(["a", "b"]);
+    expect(first.every((r) => r.reverted)).toBe(true);
+    expect(readAccess("a").allowFrom).toEqual([]);
+    expect(readAccess("b").allowFrom).toEqual(["7"]);
+
+    const second = sweepAllowlist({ agentsDir });
+    expect(second).toEqual([]);
+  });
+
+  it("with expiredOnly, leaves un-expired receipts alone", () => {
+    seedAccess("a", { allowFrom: [] });
+    seedAccess("b", { allowFrom: [] });
+    const t0 = Date.parse("2026-08-18T00:00:00.000Z");
+    addToAllowlist("a", "111", { agentsDir, now: () => t0, ttlMs: 1000 });
+    addToAllowlist("b", "222", { agentsDir, now: () => t0, ttlMs: 60 * 60 * 1000 });
+
+    // 2s later: a's receipt (ttl 1s) is expired, b's (ttl 1h) is not.
+    const swept = sweepAllowlist({ agentsDir, expiredOnly: true, now: () => t0 + 2000 });
+    expect(swept.map((r) => r.agent)).toEqual(["a"]);
+    expect(readAccess("a").allowFrom).toEqual([]);
+    // b untouched.
+    expect(readAccess("b").allowFrom).toEqual(["222"]);
+    expect(existsSync(receiptPath(agentsDir, "b"))).toBe(true);
+  });
+
+  it("returns empty on a missing agents dir", () => {
+    expect(sweepAllowlist({ agentsDir: join(root, "nope") })).toEqual([]);
+  });
+});
+
+describe("runAllowlistCli", () => {
+  it("add then remove --sweep round-trips to zero residue", () => {
+    seedAccess("ziggy", { allowFrom: ["1"] });
+    expect(runAllowlistCli(["add", "ziggy", "999", "--agents-dir", agentsDir])).toBe(0);
+    expect(readAccess("ziggy").allowFrom).toEqual(["1", "999"]);
+
+    expect(runAllowlistCli(["remove", "--sweep", "--agents-dir", agentsDir])).toBe(0);
+    expect(readAccess("ziggy").allowFrom).toEqual(["1"]);
+    expect(existsSync(receiptPath(agentsDir, "ziggy"))).toBe(false);
+  });
+
+  it("add without a userId is a usage error (exit 1)", () => {
+    expect(runAllowlistCli(["add", "ziggy", "--agents-dir", agentsDir])).toBe(1);
+  });
+
+  it("unknown command is exit 1; bare invocation is exit 0", () => {
+    expect(runAllowlistCli(["frobnicate"])).toBe(1);
+    expect(runAllowlistCli([])).toBe(0);
+  });
+});

package/telegram-plugin/uat/flip/allowlist.ts

@@ -0,0 +1,349 @@
+/**
+ * Allowlist add/remove helper for the Memory v2 M3 directive-flip UAT.
+ *
+ * The flip UAT needs a throwaway probe user temporarily on an agent's DM
+ * allowlist so the (later) Tier-2 mtcute probe can talk to it, then removed
+ * again with zero residue — even if the runner crashes mid-flight. This module
+ * is that add/remove half, and NOTHING else: it does not run probes, flip
+ * agents, or touch bank state.
+ *
+ * The file it edits is `~/.switchroom/agents/<agent>/telegram/access.json` —
+ * the gateway's DM allowlist (`allowFrom: string[]`, see
+ * `telegram-plugin/gateway/access-store.ts`). Two invariants make it
+ * crash-safe:
+ *
+ *   1. WHOLE-OBJECT parse → modify → serialize, written atomically (temp file
+ *      + `rename`), mode 0600. We never hand-edit a field in place, so a
+ *      concurrent gateway reader never sees a half-written file and no sibling
+ *      key (`groups`, `pending`, telegram feature flags) is dropped.
+ *
+ *   2. A sidecar RECEIPT (`access.json.uat-allowlist-receipt.json`) is written
+ *      BEFORE `access.json` is mutated on `add`. The receipt records whether
+ *      the id was already present (`preexisting`) and a +4h `expiresAt`. Revert
+ *      is driven off the receipt, so:
+ *        - `remove` reverts iff a receipt exists AND `preexisting` was false
+ *          (an id the UAT itself added). If the id was already there before the
+ *          UAT touched it, revert leaves it and just clears the receipt.
+ *        - `remove --sweep` scans every agent dir and reverts any receipt it
+ *          finds — the idempotent crash-recovery path. `--sweep --expired`
+ *          restricts that to receipts past their `expiresAt`.
+ *
+ * Because the receipt is the source of truth for "did WE add this", the tool
+ * is safe to run repeatedly: a second `add` for an id already added is a no-op
+ * that leaves the original receipt (and its original `addedAt`) intact, and a
+ * `remove`/`sweep` with no receipt does nothing.
+ */
+
+import {
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  existsSync,
+  rmSync,
+  readdirSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Default allowlist TTL: the probe window before a sweep should reclaim. */
+export const DEFAULT_TTL_MS = 4 * 60 * 60 * 1000; // 4h
+
+/** The sidecar receipt written next to access.json. */
+export interface AllowlistReceipt {
+  agent: string;
+  userId: string;
+  /** ISO timestamp the receipt was written (the add moment). */
+  addedAt: string;
+  /** ISO timestamp after which a `--sweep --expired` will reclaim this id. */
+  expiresAt: string;
+  /** True when `userId` was ALREADY on the allowlist before the UAT ran — in
+   *  that case revert must NOT remove it. */
+  preexisting: boolean;
+}
+
+/** Minimal shape of access.json we touch. All other keys pass through
+ *  untouched via the parsed object (we serialize the whole thing). */
+interface AccessFile {
+  allowFrom?: string[];
+  [k: string]: unknown;
+}
+
+export interface AllowlistDeps {
+  /** Root agents dir. Defaults to `~/.switchroom/agents`. Injected in tests. */
+  agentsDir?: string;
+  /** Clock seam for deterministic tests. */
+  now?: () => number;
+  /** TTL override (ms) for the receipt `expiresAt`. */
+  ttlMs?: number;
+}
+
+export interface AddResult {
+  agent: string;
+  userId: string;
+  /** True when this call actually appended the id. */
+  added: boolean;
+  /** True when the id was already on the allowlist before this call. */
+  preexisting: boolean;
+  receiptPath: string;
+}
+
+export interface RemoveResult {
+  agent: string;
+  userId: string | null;
+  /** True when the id was removed from the allowlist by this call. */
+  reverted: boolean;
+  /** Why nothing was reverted, when `reverted` is false. */
+  reason?: "no-receipt" | "preexisting" | "not-present";
+  receiptCleared: boolean;
+}
+
+function resolveAgentsDir(deps: AllowlistDeps): string {
+  return deps.agentsDir ?? join(homedir(), ".switchroom", "agents");
+}
+
+/** Absolute path to an agent's access.json. */
+export function accessFilePath(agentsDir: string, agent: string): string {
+  return join(agentsDir, agent, "telegram", "access.json");
+}
+
+/** Absolute path to an agent's UAT allowlist receipt. */
+export function receiptPath(agentsDir: string, agent: string): string {
+  return accessFilePath(agentsDir, agent) + ".uat-allowlist-receipt.json";
+}
+
+/** Read + parse access.json, or `{}` when absent. Throws on malformed JSON —
+ *  the UAT must NOT silently clobber a file it can't parse. */
+function readAccess(path: string): AccessFile {
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, "utf8");
+  const parsed = JSON.parse(raw) as AccessFile;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`access.json at ${path} is not a JSON object`);
+  }
+  return parsed;
+}
+
+/** Atomic whole-object write: temp file + rename, mode 0600, dir 0700. */
+function atomicWriteJson(path: string, value: unknown): void {
+  const dir = join(path, "..");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+function readReceipt(path: string): AllowlistReceipt | null {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as AllowlistReceipt;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Add `userId` to `<agent>`'s DM allowlist, writing the receipt FIRST.
+ *
+ * Crash-safety ordering: the receipt lands before access.json is mutated, so a
+ * crash between the two leaves a receipt whose `preexisting` correctly records
+ * the pre-mutation state — a later sweep reverts exactly what it should.
+ *
+ * Idempotent: if a receipt already exists for this agent (a prior add), this is
+ * a no-op that preserves the original receipt (and its `preexisting`/`addedAt`),
+ * so a double-add can't overwrite the truth about whether WE added the id.
+ */
+export function addToAllowlist(agent: string, userId: string, deps: AllowlistDeps = {}): AddResult {
+  const agentsDir = resolveAgentsDir(deps);
+  const nowMs = (deps.now ?? Date.now)();
+  const ttlMs = deps.ttlMs ?? DEFAULT_TTL_MS;
+  const accessPath = accessFilePath(agentsDir, agent);
+  const rcptPath = receiptPath(agentsDir, agent);
+
+  const access = readAccess(accessPath);
+  const allowFrom = Array.isArray(access.allowFrom) ? access.allowFrom.map(String) : [];
+  const preexisting = allowFrom.includes(userId);
+
+  const existingReceipt = readReceipt(rcptPath);
+  if (existingReceipt) {
+    // A prior add already recorded the truth — do not re-mutate or re-stamp.
+    return {
+      agent,
+      userId,
+      added: false,
+      preexisting: existingReceipt.preexisting,
+      receiptPath: rcptPath,
+    };
+  }
+
+  // Receipt FIRST, before any mutation — the crash-safety invariant.
+  const receipt: AllowlistReceipt = {
+    agent,
+    userId,
+    addedAt: new Date(nowMs).toISOString(),
+    expiresAt: new Date(nowMs + ttlMs).toISOString(),
+    preexisting,
+  };
+  atomicWriteJson(rcptPath, receipt);
+
+  if (preexisting) {
+    // Already allowlisted — nothing to add, receipt records preexisting:true.
+    return { agent, userId, added: false, preexisting: true, receiptPath: rcptPath };
+  }
+
+  access.allowFrom = [...allowFrom, userId];
+  atomicWriteJson(accessPath, access);
+  return { agent, userId, added: true, preexisting: false, receiptPath: rcptPath };
+}
+
+/**
+ * Revert an agent's allowlist add. Only removes the id when a receipt exists
+ * AND `preexisting` was false; always clears the receipt when one exists.
+ */
+export function removeFromAllowlist(agent: string, deps: AllowlistDeps = {}): RemoveResult {
+  const agentsDir = resolveAgentsDir(deps);
+  const accessPath = accessFilePath(agentsDir, agent);
+  const rcptPath = receiptPath(agentsDir, agent);
+
+  const receipt = readReceipt(rcptPath);
+  if (!receipt) {
+    return { agent, userId: null, reverted: false, reason: "no-receipt", receiptCleared: false };
+  }
+
+  // Clear the receipt regardless of the branch below — it is single-use.
+  const clearReceipt = () => {
+    rmSync(rcptPath, { force: true });
+  };
+
+  if (receipt.preexisting) {
+    // The id was there before the UAT — leave the allowlist, drop the receipt.
+    clearReceipt();
+    return {
+      agent,
+      userId: receipt.userId,
+      reverted: false,
+      reason: "preexisting",
+      receiptCleared: true,
+    };
+  }
+
+  const access = readAccess(accessPath);
+  const allowFrom = Array.isArray(access.allowFrom) ? access.allowFrom.map(String) : [];
+  if (!allowFrom.includes(receipt.userId)) {
+    // Already gone (idempotent re-run) — just clear the receipt.
+    clearReceipt();
+    return {
+      agent,
+      userId: receipt.userId,
+      reverted: false,
+      reason: "not-present",
+      receiptCleared: true,
+    };
+  }
+
+  access.allowFrom = allowFrom.filter((id) => id !== receipt.userId);
+  atomicWriteJson(accessPath, access);
+  clearReceipt();
+  return { agent, userId: receipt.userId, reverted: true, receiptCleared: true };
+}
+
+export interface SweepOptions extends AllowlistDeps {
+  /** When true, only revert receipts whose `expiresAt` is in the past. */
+  expiredOnly?: boolean;
+}
+
+/**
+ * Scan every agent dir under `agentsDir` and revert any UAT allowlist receipt.
+ * Idempotent — safe to run on a clean fleet (returns an empty result set). With
+ * `expiredOnly`, only receipts past their `expiresAt` are reverted.
+ */
+export function sweepAllowlist(opts: SweepOptions = {}): RemoveResult[] {
+  const agentsDir = resolveAgentsDir(opts);
+  const nowMs = (opts.now ?? Date.now)();
+  const results: RemoveResult[] = [];
+  if (!existsSync(agentsDir)) return results;
+
+  for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const agent = entry.name;
+    const rcptPath = receiptPath(agentsDir, agent);
+    const receipt = readReceipt(rcptPath);
+    if (!receipt) continue;
+    if (opts.expiredOnly) {
+      const expiresMs = Date.parse(receipt.expiresAt);
+      if (!Number.isNaN(expiresMs) && expiresMs > nowMs) continue; // not yet expired
+    }
+    results.push(removeFromAllowlist(agent, opts));
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function usage(): string {
+  return [
+    "usage: allowlist <command> [args]",
+    "",
+    "  add <agent> <userId>      add userId to <agent>'s DM allowlist (writes receipt first)",
+    "  remove <agent>            revert the receipted add for <agent>",
+    "  remove --sweep            revert every agent's receipt (idempotent)",
+    "  remove --sweep --expired  revert only receipts past their expiresAt",
+    "",
+    "  --agents-dir <path>       override the agents root (default ~/.switchroom/agents)",
+  ].join("\n");
+}
+
+/** Parse argv (sans node/script) and dispatch. Returns process exit code.
+ *  Exported for direct unit testing of the arg surface. */
+export function runAllowlistCli(argv: string[]): number {
+  const args = [...argv];
+  let agentsDir: string | undefined;
+  const dirIdx = args.indexOf("--agents-dir");
+  if (dirIdx !== -1) {
+    agentsDir = args[dirIdx + 1];
+    args.splice(dirIdx, 2);
+  }
+  const deps: AllowlistDeps = agentsDir ? { agentsDir } : {};
+
+  const cmd = args[0];
+  if (cmd === "add") {
+    const [, agent, userId] = args;
+    if (!agent || !userId) {
+      process.stderr.write("add requires <agent> <userId>\n" + usage() + "\n");
+      return 1;
+    }
+    const r = addToAllowlist(agent, userId, deps);
+    process.stdout.write(JSON.stringify(r) + "\n");
+    return 0;
+  }
+  if (cmd === "remove") {
+    if (args.includes("--sweep")) {
+      const expiredOnly = args.includes("--expired");
+      const rs = sweepAllowlist({ ...deps, expiredOnly });
+      process.stdout.write(JSON.stringify(rs) + "\n");
+      return 0;
+    }
+    const agent = args[1];
+    if (!agent) {
+      process.stderr.write("remove requires <agent> (or --sweep)\n" + usage() + "\n");
+      return 1;
+    }
+    const r = removeFromAllowlist(agent, deps);
+    process.stdout.write(JSON.stringify(r) + "\n");
+    return 0;
+  }
+
+  process.stderr.write(usage() + "\n");
+  return cmd ? 1 : 0;
+}
+
+// Direct-exec entry (bun/node run this file). Guarded so imports don't run it.
+if (
+  typeof process !== "undefined" &&
+  process.argv[1] &&
+  (process.argv[1].endsWith("allowlist.ts") || process.argv[1].endsWith("allowlist.js"))
+) {
+  process.exit(runAllowlistCli(process.argv.slice(2)));
+}