@nopeek/agent-bridge 0.1.0 → 0.2.0

package/README.md

@@ -4,13 +4,27 @@ Run your own AI agents as **end-to-end-encrypted NoPeek bots** — from your Mac
 
 The bridge is a small always-on process that:
 
-1. **Pairs** with your NoPeek account using a one-time pairing code (`npr_…`) from the NoPeek app ("Connect your computer").
+1. **Pairs** with your NoPeek account — one tap in the NoPeek app ("Connect this computer"), or a one-time pairing code (`npr_…`) if you prefer the terminal.
 2. **Runs every bot you own** — each bot connects as a real NoPeek user with its own server device, publishes MLS key packages, and decrypts messages locally like any other client. The server never sees plaintext.
 3. **Pipes each incoming message to your "brain"** — any shell command (message on stdin, reply on stdout) or any HTTP webhook — and sends the reply back into the encrypted channel.
 
 When you create a new bot in the NoPeek app, the bridge adopts it live over its control connection. No restart, no redeploy.
 
-## Quick start
+## Quick start — one command, then the app
+
+```bash
+npm install -g @nopeek/agent-bridge && nopeek-agent-bridge install
+```
+
+That installs the bridge as a background service (launchd on macOS, `systemd --user` on Linux) that starts at login and waits, **unpaired**. Then, in the NoPeek app on the same computer:
+
+1. **Contacts → My Bots → Connect this computer** — one tap. The app mints the pairing secret and hands it straight to the local bridge; you never see or paste it.
+2. Create bots; each one starts on your computer within seconds.
+3. Per bot: **⋯ → Choose brain…** — pick a detected agent (Hermes, Claude Code, `llm`, Ollama), a custom command, a webhook, or echo. Changes apply to the next message, no restart.
+
+Every bot you own answers in every chat it's a member of. Add a bot to a group in the NoPeek app and it just starts working.
+
+## Quick start — terminal-only (no app steps)
 
 ```bash
 # Zero config: bots run in echo mode ("You said: …") — a smoke test
@@ -23,7 +37,22 @@ npx @nopeek/agent-bridge \
   --brain-cmd 'HERMES_HOME=/Volumes/x10drive/hermes hermes --profile nopeek chat -Q -q "$(cat)"'
 ```
 
-That's it. Every bot you own answers in every chat it's a member of. Add a bot to a group in the NoPeek app and it just starts working.
+The `npr_…` code comes from Settings → Connect your computer (bots) in the app. `install` also accepts `--pair`/`--app-id` to pre-pair the service from the terminal.
+
+## Local control API
+
+The bridge serves a loopback-only HTTP API on `127.0.0.1:8790` — this is what the NoPeek app uses; you can script it too.
+
+| Endpoint | Auth | Purpose |
+| --- | --- | --- |
+| `GET /` | none | Minimal status: `{ok, service, version, paired, machine, uptime}` |
+| `POST /pair` | the `npr_…` secret itself; only accepted while **unpaired** | `{pairingSecret, appId, apiUrl?}` — validate, persist, start bots |
+| `GET /status` | `x-nopeek-runtime: rt_…` | Full status: bots, brains, runtime id |
+| `GET /detect` | `x-nopeek-runtime` | Agent runtimes found on PATH (hermes, claude, llm, ollama) with suggested commands |
+| `PUT /brains` | `x-nopeek-runtime` | `{brainCmd?, brainUrl?, map?: {"<handle>": {cmd|url|echo}|null}}` — applies live, persists |
+| `DELETE /pair` | `x-nopeek-runtime` | Unpair: stop bots, forget the secret (device keys kept) |
+
+The `x-nopeek-runtime` header is the runtime id — a capability only the owner's logged-in app can fetch from the NoPeek server, so a random webpage poking `127.0.0.1` can't read your bot list or change brain commands. Everything the app configures persists to `~/.nopeek-bridge/settings.json` (mode 600).
 
 ## How the brain works
 
@@ -118,17 +147,20 @@ Everything can be set three ways, highest precedence first: **CLI flag → envir
 
 | Flag | Env var | Default | Meaning |
 | --- | --- | --- | --- |
-| `--pair` | `NOPEEK_PAIRING_CODE` | *(required)* | One-time pairing code from the NoPeek app (`npr_…`) |
-| `--app-id` | `NOPEEK_APP_ID` | *(required)* | Your NoPeek app id (shown with the pairing code) |
+| `--pair` | `NOPEEK_PAIRING_CODE` | — | Pairing code (`npr_…`); optional — pairing from the app is easier |
+| `--app-id` | `NOPEEK_APP_ID` | — | Your NoPeek app id (set automatically when pairing from the app) |
 | `--api-url` | `NOPEEK_API_URL` | `https://d3qweh72vesa98.cloudfront.net` | NoPeek API base |
 | `--brain-cmd` | `BRAIN_CMD` | — | Global command brain |
 | `--brain-url` | `BRAIN_URL` | — | Global webhook brain |
 | `--brain-map` | `BRAIN_MAP` | `{}` | Per-handle overrides (JSON) |
 | `--brain-timeout-ms` | `BRAIN_TIMEOUT_MS` | `180000` | Brain timeout (generous: agent runtimes think slowly) |
-| `--port` | `NOPEEK_BRIDGE_PORT` | `8790` | Health endpoint port |
-| `--data-dir` | `NOPEEK_BRIDGE_DATA_DIR` | `./data` | Per-bot device-key store directory |
+| `--port` | `NOPEEK_BRIDGE_PORT` | `8790` | Local control API port (loopback only) |
+| `--data-dir` | `NOPEEK_BRIDGE_DATA_DIR` | `<home>/data` (legacy `./data` honored) | Per-bot device-key store directory |
+| `--home` | `NOPEEK_BRIDGE_HOME` | `~/.nopeek-bridge` | Settings, default data dir, service logs |
 | `--config` | — | `./nopeek-bridge.config.json` | Config file path |
 
+Precedence: CLI flag → env var → `nopeek-bridge.config.json` → `<home>/settings.json` (written when you pair or set brains from the app).
+
 Example config file:
 
 ```json
@@ -174,7 +206,7 @@ Example config file:
 
 ## Running it long-term
 
-Anything that keeps a process alive works. For example, on Linux:
+`nopeek-agent-bridge install` does this for you (launchd LaunchAgent on macOS, systemd user unit on Linux; `uninstall` removes it, `status` queries the running bridge). If you'd rather manage the process yourself, anything that keeps it alive works. For example, on Linux:
 
 ```ini
 # /etc/systemd/system/nopeek-bridge.service

package/dist/bot.d.ts

@@ -12,12 +12,14 @@ export declare class BotRunner {
     handled: number;
     brainKind: string;
     private cfg;
-    private brain;
     private np;
     private stopped;
     private refreshTimer;
     private seen;
     private channelCache;
+    private allowed;
+    private accessLoaded;
+    private declined;
     private log;
     private logErr;
     constructor(info: BotInfo, cfg: BridgeConfig);
@@ -25,6 +27,13 @@ export declare class BotRunner {
     start(): void;
     stop(): void;
     private mintSession;
+    /** Fetch (or refresh) the set of users allowed to talk to this bot. Called on
+     *  connect and whenever a grant changes. Best-effort: on failure we keep the
+     *  last-known set, and if we've never loaded one we FAIL CLOSED (owner-only)
+     *  rather than open. */
+    refreshAccess(): Promise<void>;
+    /** Sender permitted to talk to this bot? Fail closed if access never loaded. */
+    private isAllowed;
     private run;
     private connectOnce;
     /** Runtime sessions expire; reconnect with a fresh one shortly before that. */

package/dist/bot.js

@@ -16,20 +16,24 @@ export class BotRunner {
     handled = 0;
     brainKind;
     cfg;
-    brain;
     np = null;
     stopped = false;
     refreshTimer = null;
     seen = new Set();
     channelCache = new Map();
+    // Access control: bots are PRIVATE by default. `allowed` is the set of user
+    // ids permitted to talk to this bot (owner + workspace members + granted
+    // users), fetched from the server. A sender NOT in this set never reaches the
+    // brain — so a stranger who finds the @handle can't drive the owner's agent.
+    allowed = new Set();
+    accessLoaded = false;
+    declined = new Set(); // (senderId) already told "not authorized" once
     log;
     logErr;
     constructor(info, cfg) {
         this.info = info;
         this.cfg = cfg;
-        const resolved = resolveBrain(cfg, info.handle);
-        this.brain = resolved.brain;
-        this.brainKind = resolved.kind;
+        this.brainKind = resolveBrain(cfg, info.handle).kind;
         const tag = `[bot:@${info.handle}]`;
         this.log = (m) => console.log(`${tag} ${m}`);
         this.logErr = (m) => console.error(`${tag} ${m}`);
@@ -67,6 +71,32 @@ export class BotRunner {
         }
         return (await res.json());
     }
+    /** Fetch (or refresh) the set of users allowed to talk to this bot. Called on
+     *  connect and whenever a grant changes. Best-effort: on failure we keep the
+     *  last-known set, and if we've never loaded one we FAIL CLOSED (owner-only)
+     *  rather than open. */
+    async refreshAccess() {
+        try {
+            const res = await fetch(`${this.cfg.apiUrl}/v1/apps/${this.cfg.appId}/bots/${this.info.userId}/access`, { headers: { authorization: `Bearer ${this.cfg.pairingCode}` } });
+            if (!res.ok)
+                throw new Error(`access HTTP ${res.status}`);
+            const j = (await res.json());
+            this.allowed = new Set(j.allowedUserIds ?? []);
+            this.accessLoaded = true;
+            this.log(`access: policy=${j.policy ?? "private"}, ${this.allowed.size} allowed sender(s)`);
+        }
+        catch (err) {
+            this.logErr(`access refresh failed: ${err.message} (keeping last-known allow list)`);
+        }
+    }
+    /** Sender permitted to talk to this bot? Fail closed if access never loaded. */
+    isAllowed(senderUserId) {
+        if (senderUserId === this.info.ownerId)
+            return true; // owner always
+        if (!this.accessLoaded)
+            return false; // fail closed until we know the list
+        return this.allowed.has(senderUserId);
+    }
     async run() {
         this.log(`starting (${this.info.userId}) brain=${this.brainKind}`);
         let delay = 2_000;
@@ -92,7 +122,7 @@ export class BotRunner {
         const np = await NoPeek.connect({
             apiUrl: this.cfg.apiUrl,
             sessionToken: session.sessionToken,
-            appId: this.cfg.appId,
+            appId: this.cfg.appId ?? "", // runners only exist while paired
             userId: this.info.userId,
             platform: "server",
             storage: store,
@@ -121,6 +151,7 @@ export class BotRunner {
                 this.logErr(`handler error for ${m.messageId}: ${err.message}`);
             });
         }));
+        await this.refreshAccess(); // load the allow list before we answer anyone
         this.scheduleRefresh(session.expiresAt);
     }
     /** Runtime sessions expire; reconnect with a fresh one shortly before that. */
@@ -193,9 +224,22 @@ export class BotRunner {
         }
         if (m.body?.type !== "text" || typeof m.body.text !== "string" || !m.body.text.trim())
             return;
-        // TODO(grants): enforce per-channel grants once bot_grant_changed carries
-        // enough to build an allowlist. v1 answers everyone in any channel the bot
-        // is a member of; the control socket already logs grant changes.
+        // ACCESS CONTROL: a bot is private. If the sender isn't authorized (owner,
+        // workspace member, or explicitly granted), the brain is NEVER invoked — so
+        // a stranger who found the @handle can't make the owner's agent do anything.
+        if (!this.isAllowed(m.senderUserId)) {
+            this.log(`${m.channelId} <- ${m.senderUserId}: BLOCKED (not authorized) — brain not invoked`);
+            if (this.cfg.declineMessage && !this.declined.has(m.senderUserId)) {
+                this.declined.add(m.senderUserId);
+                try {
+                    await (await this.getChannel(m.channelId)).send({ text: this.cfg.declineMessage });
+                }
+                catch {
+                    /* best-effort decline notice */
+                }
+            }
+            return;
+        }
         const text = m.body.text;
         this.log(`${m.channelId} <- ${m.senderUserId}: ${text.slice(0, 120)}`);
         const ch = await this.getChannel(m.channelId);
@@ -206,9 +250,13 @@ export class BotRunner {
         catch {
             /* typing is best-effort */
         }
+        // Resolve the brain PER MESSAGE: the NoPeek app can change it live over the
+        // local API (PUT /brains) and the very next message uses the new one.
+        const resolved = resolveBrain(this.cfg, this.info.handle);
+        this.brainKind = resolved.kind;
         let reply = "";
         try {
-            reply = await this.brain(text, {
+            reply = await resolved.brain(text, {
                 botHandle: this.info.handle,
                 botUserId: this.info.userId,
                 channelId: m.channelId,

package/dist/brain.d.ts

@@ -15,6 +15,6 @@ export interface ResolvedBrain {
 }
 /**
  * Pick the brain for one bot:
- * BRAIN_MAP[handle] (cmd beats url within an entry) > BRAIN_CMD > BRAIN_URL > echo.
+ * BRAIN_MAP[handle] (cmd beats url beats echo within an entry) > BRAIN_CMD > BRAIN_URL > echo.
  */
 export declare function resolveBrain(cfg: BridgeConfig, handle: string): ResolvedBrain;

package/dist/brain.js

@@ -117,7 +117,7 @@ function urlBrain(url, timeoutMs) {
 const echoBrain = async (text) => `You said: ${text}`;
 /**
  * Pick the brain for one bot:
- * BRAIN_MAP[handle] (cmd beats url within an entry) > BRAIN_CMD > BRAIN_URL > echo.
+ * BRAIN_MAP[handle] (cmd beats url beats echo within an entry) > BRAIN_CMD > BRAIN_URL > echo.
  */
 export function resolveBrain(cfg, handle) {
     const override = cfg.brainMap[handle.replace(/^@/, "")];
@@ -125,6 +125,8 @@ export function resolveBrain(cfg, handle) {
         return { brain: cmdBrain(override.cmd, cfg.brainTimeoutMs), kind: "cmd (per-bot)" };
     if (override?.url)
         return { brain: urlBrain(override.url, cfg.brainTimeoutMs), kind: "url (per-bot)" };
+    if (override?.echo)
+        return { brain: echoBrain, kind: "echo (per-bot)" };
     if (cfg.brainCmd)
         return { brain: cmdBrain(cfg.brainCmd, cfg.brainTimeoutMs), kind: "cmd" };
     if (cfg.brainUrl)

package/dist/bridge.d.ts

@@ -1,5 +1,50 @@
-import type { BridgeConfig } from "./config.js";
-export interface Bridge {
+import type { BridgeConfig, BrainSpec } from "./config.js";
+export declare const VERSION = "0.2.0";
+export interface PairRequest {
+    pairingSecret: string;
+    appId: string;
+    apiUrl?: string;
+}
+export interface BrainsPatch {
+    /** Global command brain; null clears it. */
+    brainCmd?: string | null;
+    /** Global webhook brain; null clears it. */
+    brainUrl?: string | null;
+    /** Per-handle entries; a null value removes that bot's override. */
+    map?: Record<string, BrainSpec | null>;
+}
+export declare class PairError extends Error {
+    readonly code: "ALREADY_PAIRED" | "PAIR_REJECTED" | "PAIR_UNREACHABLE" | "BAD_REQUEST";
+    constructor(code: "ALREADY_PAIRED" | "PAIR_REJECTED" | "PAIR_UNREACHABLE" | "BAD_REQUEST", message: string);
+}
+export declare class BridgeApp {
+    readonly cfg: BridgeConfig;
+    readonly startedAt: number;
+    private bots;
+    private control;
+    private stopped;
+    constructor(cfg: BridgeConfig);
+    get paired(): boolean;
+    /** Known once the control socket has authenticated at least once. */
+    get runtimeId(): string | null;
+    get controlConnected(): boolean;
+    start(): void;
     stop(): void;
+    /**
+     * Pair this bridge from the NoPeek app. Only accepted while UNPAIRED (an
+     * attacker on a webpage can't silently re-point an already-working bridge).
+     * The secret is validated against the API before anything is persisted.
+     */
+    pair(req: PairRequest): Promise<void>;
+    /** Undo pairing: stop everything, forget the credential (device keys stay). */
+    unpair(): void;
+    /** Apply a brain change live (next message uses it) and persist it. */
+    setBrains(patch: BrainsPatch): void;
+    statusMinimal(): Record<string, unknown>;
+    statusFull(): Record<string, unknown>;
+    private startBot;
+    /** Fetch the authoritative bot list and start anything we're missing. */
+    private syncBots;
+    private startCore;
+    private stopCore;
 }
-export declare function runBridge(cfg: BridgeConfig): Promise<Bridge>;

package/dist/bridge.js

@@ -1,24 +1,173 @@
-// Orchestrator: pairs this machine as a NoPeek runtime, discovers every bot it
-// owns (GET /runtime/bots), runs each as an isolated BotRunner, and keeps the
-// fleet current via the control WebSocket (adopt_bot arrives live — no restart).
-import { createServer } from "node:http";
+// Orchestrator. A bridge has two states:
+//   unpaired — local control API up, waiting for the NoPeek app to POST /pair
+//   paired   — runs every bot the runtime owns (GET /runtime/bots), keeps the
+//              fleet current via the control WebSocket (adopt_bot arrives live),
+//              and still serves the local API for status + live brain changes.
+// Pairing, unpairing and brain config all happen at runtime (from the app) and
+// persist to <home>/settings.json — no restart, no terminal.
+import { hostname } from "node:os";
+import { saveSettings } from "./config.js";
 import { BotRunner } from "./bot.js";
 import { ControlSocket } from "./control.js";
-export async function runBridge(cfg) {
-    const startedAt = Date.now();
-    const bots = new Map(); // botUserId -> runner
-    // ------------------------------------------------------------- bot fleet --
-    const startBot = (info) => {
-        if (bots.has(info.userId))
+import { resolveBrain } from "./brain.js";
+export const VERSION = "0.2.0";
+export class PairError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class BridgeApp {
+    cfg;
+    startedAt = Date.now();
+    bots = new Map(); // botUserId -> runner
+    control = null;
+    stopped = false;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    get paired() {
+        return Boolean(this.cfg.pairingCode && this.cfg.appId);
+    }
+    /** Known once the control socket has authenticated at least once. */
+    get runtimeId() {
+        return this.control?.runtimeId ?? null;
+    }
+    get controlConnected() {
+        return this.control?.connected ?? false;
+    }
+    start() {
+        if (this.paired)
+            this.startCore();
+        else
+            console.log(`[bridge] not paired yet — open the NoPeek app: Bots -> Connect this computer`);
+    }
+    stop() {
+        this.stopped = true;
+        this.stopCore();
+    }
+    // ------------------------------------------------------------- pairing ----
+    /**
+     * Pair this bridge from the NoPeek app. Only accepted while UNPAIRED (an
+     * attacker on a webpage can't silently re-point an already-working bridge).
+     * The secret is validated against the API before anything is persisted.
+     */
+    async pair(req) {
+        if (this.paired) {
+            throw new PairError("ALREADY_PAIRED", "This bridge is already paired. Unpair it first (from the NoPeek app) or revoke the runtime.");
+        }
+        const pairingSecret = typeof req.pairingSecret === "string" ? req.pairingSecret.trim() : "";
+        const appId = typeof req.appId === "string" ? req.appId.trim() : "";
+        if (!pairingSecret || !appId) {
+            throw new PairError("BAD_REQUEST", "pairingSecret and appId are required.");
+        }
+        const apiUrl = (typeof req.apiUrl === "string" && req.apiUrl.trim() ? req.apiUrl.trim() : this.cfg.apiUrl).replace(/\/+$/, "");
+        // Validate before persisting: the bot list doubles as an auth probe.
+        let res;
+        try {
+            res = await fetch(`${apiUrl}/v1/apps/${appId}/runtime/bots`, {
+                headers: { authorization: `Bearer ${pairingSecret}` },
+                signal: AbortSignal.timeout(15_000),
+            });
+        }
+        catch (err) {
+            throw new PairError("PAIR_UNREACHABLE", `could not reach ${apiUrl}: ${err.message}`);
+        }
+        if (!res.ok) {
+            throw new PairError("PAIR_REJECTED", `the API rejected this pairing secret (HTTP ${res.status}).`);
+        }
+        this.cfg.apiUrl = apiUrl;
+        this.cfg.appId = appId;
+        this.cfg.pairingCode = pairingSecret;
+        saveSettings(this.cfg);
+        console.log(`[bridge] paired with app ${appId} — starting bots`);
+        this.startCore();
+    }
+    /** Undo pairing: stop everything, forget the credential (device keys stay). */
+    unpair() {
+        console.log(`[bridge] unpairing — stopping bots and forgetting the pairing secret`);
+        this.stopCore();
+        this.cfg.pairingCode = null;
+        this.cfg.appId = null;
+        saveSettings(this.cfg);
+    }
+    // -------------------------------------------------------------- brains ----
+    /** Apply a brain change live (next message uses it) and persist it. */
+    setBrains(patch) {
+        if (patch.brainCmd !== undefined)
+            this.cfg.brainCmd = patch.brainCmd || null;
+        if (patch.brainUrl !== undefined)
+            this.cfg.brainUrl = patch.brainUrl || null;
+        if (patch.map) {
+            for (const [rawHandle, spec] of Object.entries(patch.map)) {
+                const handle = rawHandle.replace(/^@/, "");
+                if (spec === null) {
+                    delete this.cfg.brainMap[handle];
+                }
+                else if (typeof spec.cmd === "string" && spec.cmd.trim()) {
+                    this.cfg.brainMap[handle] = { cmd: spec.cmd.trim() };
+                }
+                else if (typeof spec.url === "string" && spec.url.trim()) {
+                    this.cfg.brainMap[handle] = { url: spec.url.trim() };
+                }
+                else if (spec.echo === true) {
+                    this.cfg.brainMap[handle] = { echo: true };
+                }
+                else {
+                    delete this.cfg.brainMap[handle];
+                }
+            }
+        }
+        saveSettings(this.cfg);
+        console.log(`[bridge] brains updated: default=${this.cfg.brainCmd ? "cmd" : this.cfg.brainUrl ? "url" : "echo"}, ${Object.keys(this.cfg.brainMap).length} per-bot override(s)`);
+    }
+    // -------------------------------------------------------------- status ----
+    statusMinimal() {
+        return {
+            ok: this.paired ? this.controlConnected : true,
+            service: "nopeek-agent-bridge",
+            version: VERSION,
+            paired: this.paired,
+            machine: hostname(),
+            uptime: Math.round((Date.now() - this.startedAt) / 1000),
+        };
+    }
+    statusFull() {
+        return {
+            ...this.statusMinimal(),
+            runtime: this.runtimeId,
+            apiUrl: this.cfg.apiUrl,
+            appId: this.cfg.appId,
+            brains: {
+                default: this.cfg.brainCmd
+                    ? { cmd: this.cfg.brainCmd }
+                    : this.cfg.brainUrl
+                        ? { url: this.cfg.brainUrl }
+                        : { echo: true },
+                map: this.cfg.brainMap,
+            },
+            bots: [...this.bots.values()].map((b) => ({
+                handle: b.info.handle,
+                userId: b.info.userId,
+                connected: b.connected,
+                handled: b.handled,
+                brain: resolveBrain(this.cfg, b.info.handle).kind,
+            })),
+        };
+    }
+    // ---------------------------------------------------------------- core ----
+    startBot(info) {
+        if (this.bots.has(info.userId))
             return; // already running
-        const runner = new BotRunner(info, cfg);
-        bots.set(info.userId, runner);
+        const runner = new BotRunner(info, this.cfg);
+        this.bots.set(info.userId, runner);
         runner.start(); // background; failures are isolated inside the runner
-    };
+    }
     /** Fetch the authoritative bot list and start anything we're missing. */
-    const syncBots = async () => {
-        const res = await fetch(`${cfg.apiUrl}/v1/apps/${cfg.appId}/runtime/bots`, {
-            headers: { authorization: `Bearer ${cfg.pairingCode}` },
+    async syncBots() {
+        const res = await fetch(`${this.cfg.apiUrl}/v1/apps/${this.cfg.appId}/runtime/bots`, {
+            headers: { authorization: `Bearer ${this.cfg.pairingCode}` },
         });
         if (!res.ok) {
             const body = await res.text().catch(() => "");
@@ -27,58 +176,42 @@ export async function runBridge(cfg) {
         const { bots: list } = (await res.json());
         console.log(`[bridge] runtime owns ${list.length} bot(s): ${list.map((b) => `@${b.handle}`).join(", ") || "(none yet)"}`);
         for (const info of list)
-            startBot(info);
-    };
-    // ---------------------------------------------------------- control sock --
-    const control = new ControlSocket(cfg, {
-        onAuthed: () => {
-            // Initial connect AND every reconnect: catch up on bots created while
-            // we were away (adopt_bot frames we may have missed).
-            void syncBots().catch((err) => {
-                console.error(`[bridge] bot sync failed: ${err.message}`);
-            });
-        },
-        onAdoptBot: (f) => {
-            startBot({ userId: f.botUserId, handle: f.handle, ownerId: f.ownerUserId });
-        },
-        onGrantChanged: () => {
-            // v1: logged by ControlSocket. TODO(grants): pass down to the affected
-            // BotRunner and enforce an allowlist before answering.
-        },
-    });
-    // ---------------------------------------------------------------- health --
-    const health = createServer((_req, res) => {
-        res.setHeader("content-type", "application/json");
-        res.end(JSON.stringify({
-            ok: control.connected,
-            runtime: control.runtimeId,
-            bots: [...bots.values()].map((b) => ({
-                handle: b.info.handle,
-                userId: b.info.userId,
-                connected: b.connected,
-                handled: b.handled,
-            })),
-            uptime: Math.round((Date.now() - startedAt) / 1000),
-        }));
-    });
-    health.listen(cfg.port, () => console.log(`[health] http://localhost:${cfg.port}/ -> {ok, runtime, bots, uptime}`));
-    // ----------------------------------------------------------------- start --
-    // Bots first (so a control-socket hiccup doesn't delay serving), then the
-    // control socket, whose auth.ok triggers a redundant-but-safe re-sync.
-    try {
-        await syncBots();
-    }
-    catch (err) {
-        // Non-fatal: the control socket's onAuthed will retry the sync.
-        console.error(`[bridge] initial bot sync failed (will retry on control auth): ${err.message}`);
-    }
-    control.start();
-    return {
-        stop() {
-            control.stop();
-            for (const b of bots.values())
-                b.stop();
-            health.close();
-        },
-    };
+            this.startBot(info);
+    }
+    startCore() {
+        if (this.stopped || this.control)
+            return;
+        this.control = new ControlSocket(this.cfg, {
+            onAuthed: () => {
+                // Initial connect AND every reconnect: catch up on bots created while
+                // we were away (adopt_bot frames we may have missed).
+                void this.syncBots().catch((err) => {
+                    console.error(`[bridge] bot sync failed: ${err.message}`);
+                });
+            },
+            onAdoptBot: (f) => {
+                this.startBot({ userId: f.botUserId, handle: f.handle, ownerId: f.ownerUserId });
+            },
+            onGrantChanged: (f) => {
+                // Access changed for a bot — re-pull its allow list so enforcement is
+                // live (a revoked user stops being answered within seconds).
+                const runner = this.bots.get(f.botUserId);
+                if (runner)
+                    void runner.refreshAccess();
+            },
+        });
+        // Bots first (so a control-socket hiccup doesn't delay serving), then the
+        // control socket, whose auth.ok triggers a redundant-but-safe re-sync.
+        void this.syncBots().catch((err) => {
+            console.error(`[bridge] initial bot sync failed (will retry on control auth): ${err.message}`);
+        });
+        this.control.start();
+    }
+    stopCore() {
+        this.control?.stop();
+        this.control = null;
+        for (const b of this.bots.values())
+            b.stop();
+        this.bots.clear();
+    }
 }