@cosmovex/agentpager 0.1.0

package/dist/hub.js

@@ -0,0 +1,558 @@
+// Routes phone messages to agents and agent events back to every paired phone.
+// Margin rules live here: stream text only to a phone someone is looking at; approvals and
+// "done" always go out (those are what make the app worth having), and they are tiny.
+import { platform } from 'node:os';
+import { basename } from 'node:path';
+import { random, b64u } from './crypto.js';
+import { record as recordLimits } from './guard/limits.js';
+import { PROTOCOL } from './protocol.js';
+import { addRoot, allowedCwd, browseFolders, discoverProjects } from './projects.js';
+import { AwakeLock } from './awake.js';
+import { deskActive, pruneDesk } from './guard/desk.js';
+import { loadRules, PRESETS, saveRules, validateRules } from './guard/rules.js';
+export const BRIDGE_VERSION = '0.1.0';
+const FLUSH_MS = 400;
+// A script that asks and is never answered must give up on its own. Ten minutes is long enough to
+// walk back from the kitchen and short enough that a CI job doesn't sit on a runner all night.
+const DEFAULT_ASK_MS = 10 * 60_000;
+export class Hub {
+    agents;
+    machine;
+    log;
+    channels = [];
+    live = new Map();
+    known = new Map(); // last list, for cwd lookups
+    projects = new Set();
+    discovered; // git repos on this computer; scanned once, on the first hello
+    projectCache;
+    statusCache;
+    jobs = new Map(); // `agentpager notify|ask` from any script
+    constructor(agents, machine, log, keepAwake = true) {
+        this.agents = agents;
+        this.machine = machine;
+        this.log = log;
+        this.awake = new AwakeLock(keepAwake, log);
+        pruneDesk();
+    }
+    awake;
+    attach(channel) {
+        this.channels.push(channel);
+    }
+    /** Agents detected after startup (probing them must never delay the relay). */
+    async addAgent(agent) {
+        this.agents.set(agent.id, agent);
+        this.statusCache = undefined;
+        for (const c of this.channels)
+            await this.hello(c);
+    }
+    notify(kind, note) {
+        for (const c of this.channels)
+            c.notify(kind, note);
+    }
+    label(live) {
+        const cwd = this.known.get(live.sid)?.cwd ?? '';
+        const project = cwd.split(/[\\/]/).filter(Boolean).pop();
+        return project ? `${live.agent.name} · ${project}` : live.agent.name;
+    }
+    broadcast(msg, onlyActive = false) {
+        for (const c of this.channels)
+            if (!onlyActive || c.phoneActive)
+                c.send(msg);
+    }
+    async handle(msg, from) {
+        try {
+            switch (msg.type) {
+                case 'hello':
+                    return await this.hello(from);
+                case 'list':
+                    return from.send({ type: 'sessions', items: await this.list() });
+                case 'open':
+                    await this.open(msg.sid, from);
+                    return;
+                case 'new':
+                    return await this.startNew(msg.agent, msg.cwd, from, msg.ref);
+                case 'rules_get':
+                    return from.send(this.rulesReply());
+                case 'rules_set':
+                    return this.setRules(msg, from);
+                case 'testpush': {
+                    const wait = Math.min(Math.max(msg.delayMs ?? 5000, 0), 30_000);
+                    this.log('test page queued — the phone asked us to prove notifications arrive');
+                    setTimeout(() => {
+                        from.notify('done', { sid: 'test', title: 'AgentPager', body: 'Notifications are working on this phone.' }, true);
+                    }, wait);
+                    return;
+                }
+                case 'browse':
+                    return from.send({ type: 'folders', ...browseFolders(msg.path) });
+                case 'prompt': {
+                    // Two processes writing one Claude session corrupt it. If the desk touched this session in
+                    // the last 20 s (the guard's heartbeat), refuse — never touch a session with no heartbeat.
+                    const { agent: target, id: sessionId } = this.split(msg.sid);
+                    if (target?.id === 'claude' && deskActive(sessionId)) {
+                        this.log(`prompt refused: the desk is active in ${msg.sid}`);
+                        return from.send({
+                            type: 'error',
+                            sid: msg.sid,
+                            code: 'desk_busy',
+                            message: 'You are active on this computer in that session. Try again when it is idle.',
+                        });
+                    }
+                    const live = this.live.get(msg.sid) ?? (await this.open(msg.sid, from));
+                    if (!live?.session)
+                        return from.send({ type: 'error', sid: msg.sid, code: 'not_open', message: 'That session could not be opened.' });
+                    this.log(`${msg.voice ? '🎙 ' : ''}prompt → ${msg.sid}`);
+                    live.session.send(msg.text);
+                    return;
+                }
+                case 'decide': {
+                    const live = this.live.get(msg.sid);
+                    const ask = live?.asks.get(msg.reqId);
+                    if (!live || !ask)
+                        return from.send({ type: 'asked', sid: msg.sid, reqId: msg.reqId });
+                    live.asks.delete(msg.reqId);
+                    this.log(`${msg.decision} → ${ask.msg.summary}`);
+                    ask.resolve({ decision: msg.decision, message: msg.message });
+                    this.broadcast({ type: 'asked', sid: msg.sid, reqId: msg.reqId });
+                    this.setState(live, live.asks.size ? 'needs_you' : 'running');
+                    return;
+                }
+                case 'interrupt':
+                    await this.live.get(msg.sid)?.session?.interrupt();
+                    return;
+                case 'push':
+                    from.setPushToken(typeof msg.token === 'string' && msg.token.length < 4096 ? msg.token : null);
+                    this.log(msg.token ? 'notifications on for this phone' : 'notifications off for this phone');
+                    return;
+                case 'close': {
+                    const live = this.live.get(msg.sid);
+                    if (live)
+                        this.drop(live);
+                    return;
+                }
+            }
+        }
+        catch (e) {
+            from.send({ type: 'error', code: 'bridge', message: String(e?.message ?? e) });
+        }
+    }
+    rulesReply(reqId, error) {
+        return { type: 'rules', rules: loadRules(), presets: PRESETS, ...(reqId ? { reqId } : {}), ...(error ? { error } : {}) };
+    }
+    /** Validate, write atomically, answer. A bad request is answered with `error`, never thrown. */
+    setRules(msg, from) {
+        const reqId = typeof msg.reqId === 'string' && msg.reqId.length <= 64 ? msg.reqId : undefined;
+        const v = validateRules(msg.rules);
+        if (!v.ok) {
+            this.log(`rules refused: ${v.error}`);
+            return from.send(this.rulesReply(reqId, v.error));
+        }
+        try {
+            saveRules(v.rules);
+        }
+        catch (e) {
+            this.log(`rules could not be saved: ${e?.message ?? e}`);
+            return from.send(this.rulesReply(reqId, 'This computer could not save the rules file. Check that ~/.agentpager is writable.'));
+        }
+        this.log('guard rules updated from the phone');
+        from.send(this.rulesReply(reqId));
+        // Any other paired phone should see the change without asking.
+        for (const c of this.channels)
+            if (c !== from)
+                c.send(this.rulesReply());
+    }
+    /**
+     * Spend so far for one session: Claude's own transcript, priced; Codex/ACP tokens when they report
+     * them (no dollars — there is no honest per-token price for a plan). `silent` only sets the
+     * warning baseline, so re-opening an old expensive session does not page anyone.
+     */
+    async sendUsage(live, to, silent = false) {
+        let spend = null;
+        try {
+            spend = (await live.agent.usage?.(this.split(live.sid).id)) ?? null;
+        }
+        catch {
+            /* unreadable transcript: fall back to what the agent reported */
+        }
+        if (!spend && live.reported)
+            spend = { tokens: live.reported.tokens, usd: live.reported.usd, turns: live.turns };
+        if (!spend)
+            return;
+        const rules = loadRules();
+        const usd = spend.usd === undefined ? undefined : Math.round(spend.usd * 10_000) / 10_000;
+        const msg = {
+            type: 'usage',
+            sid: live.sid,
+            ...(usd === undefined ? {} : { usd, estimated: true }),
+            tokens: spend.tokens,
+            turns: spend.turns,
+            budgetUsd: rules.budgetUsd,
+        };
+        if (to)
+            to.send(msg);
+        else
+            this.broadcast(msg);
+        if (usd === undefined || rules.budgetUsd <= 0)
+            return;
+        const level = usd >= rules.budgetUsd ? 2 : usd >= rules.budgetUsd * rules.warnAt ? 1 : 0;
+        if (level <= live.warned)
+            return;
+        live.warned = level;
+        if (silent)
+            return;
+        const money = (n) => `$${n.toFixed(2)}`;
+        this.notify(level === 2 ? 'error' : 'done', {
+            sid: live.sid,
+            title: level === 2 ? `${this.label(live)} reached its budget` : `${this.label(live)} is spending`,
+            body: level === 2
+                ? `About ${money(usd)} of the ${money(rules.budgetUsd)} budget. ${live.agent.id === 'claude' ? 'The guard now refuses further tool calls.' : 'Consider stopping it.'}`
+                : `About ${money(usd)} so far — ${Math.round(rules.warnAt * 100)}% of the ${money(rules.budgetUsd)} budget.`,
+        });
+    }
+    async statuses() {
+        if (this.statusCache && Date.now() - this.statusCache.at < 60_000)
+            return this.statusCache.items;
+        const items = await Promise.all([...this.agents.values()].map((a) => a.status()));
+        this.statusCache = { at: Date.now(), items };
+        return items;
+    }
+    /** Folders to offer the phone: where you already have sessions, then the repos on this computer. */
+    async offerProjects() {
+        // `hello` fires on every foreground and reconnect. Listing every agent's sessions each time made
+        // the phone wait on a Codex thread/list before it could show anything — and list() clears the
+        // known-session map while it rebuilds, which briefly strips project names off notifications.
+        if (this.projectCache && Date.now() - this.projectCache.at < 60_000)
+            return this.projectCache.items;
+        await this.list().catch(() => { });
+        // Learn where this computer keeps its work before scanning for repos.
+        addRoot(process.cwd());
+        for (const p of this.projects)
+            addRoot(p);
+        if (!this.discovered)
+            this.discovered = discoverProjects();
+        const out = [];
+        for (const p of [...this.projects, ...this.discovered])
+            if (!out.includes(p))
+                out.push(p);
+        const items = out.slice(0, 40);
+        this.projectCache = { at: Date.now(), items };
+        return items;
+    }
+    async hello(from) {
+        from.send({
+            type: 'hello',
+            machine: this.machine,
+            os: platform(),
+            bridge: BRIDGE_VERSION,
+            protocol: PROTOCOL,
+            agents: await this.statuses(),
+            projects: await this.offerProjects(),
+        });
+        // A phone that reconnects must see every approval still waiting — never miss one.
+        for (const live of this.live.values()) {
+            from.send({ type: 'state', sid: live.sid, state: live.state });
+            for (const ask of live.asks.values())
+                from.send(ask.msg);
+        }
+    }
+    async list() {
+        const statuses = await this.statuses();
+        const results = await Promise.all([...this.agents.values()]
+            .filter((a) => statuses.find((s) => s.id === a.id)?.available)
+            .map(async (a) => {
+            try {
+                return (await a.list()).map((s) => ({ agent: a.id, ...s }));
+            }
+            catch (e) {
+                this.log(`${a.name}: could not list sessions (${e?.message ?? e})`);
+                return [];
+            }
+        }));
+        const items = results.flat().map((s) => {
+            const sid = `${s.agent}:${s.id}`;
+            const live = this.live.get(sid);
+            return { sid, agent: s.agent, title: s.title, cwd: s.cwd, updatedAt: s.updatedAt, live: !!live, state: live?.state ?? 'idle' };
+        });
+        items.push(...this.jobs.values());
+        items.sort((a, b) => Number(b.live) - Number(a.live) || b.updatedAt - a.updatedAt);
+        this.known.clear();
+        for (const s of items) {
+            this.known.set(s.sid, s);
+            if (s.cwd)
+                this.projects.add(s.cwd);
+        }
+        return items.slice(0, 60);
+    }
+    /**
+     * A script on this computer paging you: `agentpager notify` (tell me) or
+     * `agentpager ask` (wait for my answer). Same queue, same notifications as an agent.
+     */
+    async job(req) {
+        const reach = {
+            phones: this.channels.length,
+            pushable: this.channels.filter((c) => c.canPush).length,
+            phone: this.channels.find((c) => c.canPush)?.deviceName ?? this.channels[0]?.deviceName,
+        };
+        if (req.kind === 'ping')
+            return { decision: 'allow', ...reach };
+        // Nobody to ask is not a denial and not a wait — it's a setup problem, and the script must
+        // learn that in milliseconds, not after an hour of blocking a deploy.
+        if (!reach.phones)
+            return { decision: 'timeout', ...reach };
+        const sid = `job:${b64u(random(6))}`;
+        const title = req.title?.trim() || (req.kind === 'ask' ? 'A script needs your OK' : 'A script finished');
+        const cwd = req.cwd;
+        const summary = { sid, agent: 'job', title, cwd, updatedAt: Date.now(), live: true, state: 'idle' };
+        this.jobs.set(sid, summary);
+        this.known.set(sid, summary);
+        const live = { sid, agent: { id: 'job', name: 'Job' }, state: 'idle', asks: new Map(), buffer: [], turns: 0, warned: 0 };
+        this.live.set(sid, live);
+        const sink = this.sink(live);
+        try {
+            if (req.kind === 'notify') {
+                this.log(`notify → ${title}`);
+                sink.done(true, req.text.slice(0, 1200));
+                return { decision: 'allow', ...reach };
+            }
+            summary.state = 'needs_you';
+            const answer = await this.askWithDeadline(live, sink, {
+                tool: 'job',
+                summary: title,
+                detail: req.text.slice(0, 2000),
+                risk: req.risk ?? 'shell',
+            }, req.timeoutMs);
+            if (answer === 'timeout') {
+                sink.done(false, 'Nobody answered in time, so nothing was run.');
+                this.log(`no answer in time · ${title}`);
+                return { decision: 'timeout', ...reach };
+            }
+            sink.done(answer !== 'deny', answer === 'deny' ? 'You denied it.' : 'You approved it.');
+            return { decision: answer, ...reach };
+        }
+        finally {
+            setTimeout(() => {
+                this.jobs.delete(sid);
+                this.live.delete(sid);
+            }, 60_000);
+        }
+    }
+    /**
+     * Ask, but never forever. When the deadline passes the card is WITHDRAWN from the phone with a
+     * reason — otherwise the user taps Allow on a deploy an hour later and believes it happened.
+     */
+    async askWithDeadline(live, sink, req, timeoutMs) {
+        const ms = Math.min(Math.max(timeoutMs ?? DEFAULT_ASK_MS, 5_000), 24 * 3600_000);
+        let timer;
+        const before = new Set(live.asks.keys());
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                for (const reqId of live.asks.keys())
+                    if (!before.has(reqId))
+                        this.withdraw(live, reqId, 'timeout');
+                resolve('timeout');
+            }, ms);
+        });
+        const answered = sink.ask(req).then((a) => (a.decision === 'deny' ? 'deny' : 'allow'));
+        const result = await Promise.race([answered, timeout]);
+        if (timer)
+            clearTimeout(timer);
+        return result;
+    }
+    /** Take a pending request off the phone and say why it is gone. */
+    withdraw(live, reqId, reason) {
+        const ask = live.asks.get(reqId);
+        if (!ask)
+            return;
+        live.asks.delete(reqId);
+        this.broadcast({ type: 'asked', sid: live.sid, reqId, reason });
+        ask.resolve({ decision: 'deny', message: reason === 'timeout' ? 'Nobody answered in time.' : 'Withdrawn.' });
+    }
+    split(sid) {
+        const i = sid.indexOf(':');
+        return { agent: this.agents.get(sid.slice(0, i)), id: sid.slice(i + 1) };
+    }
+    async open(sid, from) {
+        const existing = this.live.get(sid);
+        const { agent, id } = this.split(sid);
+        if (!agent) {
+            from.send({ type: 'error', sid, code: 'unknown_agent', message: 'This computer does not have that agent.' });
+            return;
+        }
+        if (!this.known.has(sid))
+            await this.list().catch(() => { });
+        const history = await agent.history(id).catch(() => []);
+        if (existing) {
+            from.send({ type: 'opened', sid });
+            from.send({ type: 'history', sid, items: history });
+            if (existing.session)
+                void this.sendUsage(existing, from, true);
+            return existing;
+        }
+        const live = { sid, agent, state: 'idle', asks: new Map(), buffer: [], turns: 0, warned: 0 };
+        this.live.set(sid, live);
+        live.session = await agent.open(id, this.known.get(sid)?.cwd, this.sink(live));
+        this.log(`opened ${agent.name} · ${this.known.get(sid)?.title ?? id}`);
+        from.send({ type: 'opened', sid });
+        from.send({ type: 'history', sid, items: history });
+        void this.sendUsage(live, from, true);
+        return live;
+    }
+    async startNew(agentId, cwd, from, ref) {
+        const agent = this.agents.get(agentId);
+        // Every failure carries `ref`, or the phone shows a row that starts nothing and says nothing.
+        if (!agent) {
+            return from.send({ type: 'error', ref, code: 'unknown_agent', message: 'This computer does not have that agent.' });
+        }
+        // Your home folder, or any folder you already have a session in. Not the whole disk.
+        if (!allowedCwd(cwd, this.projects)) {
+            return from.send({ type: 'error', ref, code: 'unknown_project', message: 'That folder is not on this computer, or is outside your home folder.' });
+        }
+        const sid = `${agentId}:new-${b64u(random(6))}`;
+        const live = { sid, agent, state: 'idle', asks: new Map(), buffer: [], turns: 0, warned: 0 };
+        this.live.set(sid, live);
+        try {
+            live.session = await agent.open(null, cwd, this.sink(live));
+        }
+        catch (e) {
+            this.live.delete(sid);
+            return from.send({ type: 'error', ref, code: 'agent', message: `${agent.name} could not start here: ${String(e?.message ?? e)}` });
+        }
+        // Codex and every ACP agent call sink.identified() SYNCHRONOUSLY inside open(), so by now the
+        // session has its real id — sending the temporary one hands the phone a row that never receives
+        // anything, and typing into it starts a second session.
+        const realSid = live.sid;
+        this.known.set(realSid, { sid: realSid, agent: agentId, title: basename(cwd) || cwd, cwd, updatedAt: Date.now(), live: true, state: 'idle' });
+        this.projects.add(cwd);
+        from.send({ type: 'opened', sid: realSid, ref });
+        this.log(`new ${agent.name} session in ${cwd}`);
+    }
+    /** Working, or waiting for an answer that can still arrive — both mean "don't nap". */
+    static busy(state) {
+        return state === 'running' || state === 'needs_you';
+    }
+    setState(live, state) {
+        if (live.state === state)
+            return;
+        const was = Hub.busy(live.state);
+        const now = Hub.busy(state);
+        if (!was && now)
+            this.awake.acquire();
+        if (was && !now)
+            this.awake.release();
+        live.state = state;
+        // needs_you/failed matter even when nobody is looking; running/idle only to a watching phone.
+        this.broadcast({ type: 'state', sid: live.sid, state }, !(state === 'needs_you' || state === 'failed'));
+    }
+    flush(live) {
+        if (live.flush)
+            clearTimeout(live.flush);
+        live.flush = undefined;
+        if (!live.buffer.length)
+            return;
+        // Complete messages are separate paragraphs; deltas are one message still being written, so
+        // they are joined with nothing at all or the seams show up as blank lines mid-sentence.
+        const text = live.buffer.join(live.streaming ? '' : '\n\n');
+        live.buffer = [];
+        const streaming = live.streaming;
+        live.streaming = false;
+        this.broadcast({ type: 'text', sid: live.sid, text, ...(streaming ? { delta: true } : {}) }, true);
+    }
+    sink(live) {
+        return {
+            identified: (id) => {
+                const newSid = `${live.agent.id}:${id}`;
+                if (newSid === live.sid)
+                    return;
+                const previousSid = live.sid;
+                this.live.delete(previousSid);
+                live.sid = newSid;
+                this.live.set(newSid, live);
+                this.broadcast({ type: 'opened', sid: newSid, previousSid });
+            },
+            text: (text) => {
+                // A complete message. Anything still growing belongs to the previous one, so close it first
+                // or the two run together in a single bubble.
+                if (live.streaming)
+                    this.flush(live);
+                live.buffer.push(text);
+                if (!live.flush)
+                    live.flush = setTimeout(() => this.flush(live), FLUSH_MS);
+            },
+            delta: (text) => {
+                if (!live.streaming && live.buffer.length)
+                    this.flush(live); // a finished message first
+                live.streaming = true;
+                live.buffer.push(text);
+                if (!live.flush)
+                    live.flush = setTimeout(() => this.flush(live), FLUSH_MS);
+            },
+            tool: (tool, detail) => {
+                this.flush(live);
+                this.broadcast({ type: 'tool', sid: live.sid, tool, detail: detail.slice(0, 300) }, true);
+            },
+            state: (state) => this.setState(live, state),
+            limits: (l) => {
+                // The guard is a hook with no access to the SDK stream, and the transcript carries no
+                // rate-limit field at all. This is the only place the real numbers exist, so write them
+                // down for it — a cap in dollars is meaningless to somebody on a subscription.
+                recordLimits({ plan: l.plan, fiveHour: l.fiveHour ?? null, sevenDay: l.sevenDay ?? null });
+                // Not onlyActive: knowing you have 6% of the week left matters most when the app is closed,
+                // and it is a tiny message.
+                this.broadcast({ type: 'limits', sid: live.sid, plan: l.plan, fiveHour: l.fiveHour, sevenDay: l.sevenDay });
+            },
+            commands: (items) => {
+                this.flush(live);
+                this.broadcast({ type: 'commands', sid: live.sid, items: items.slice(0, 120) }, true);
+            },
+            suggestion: (text) => {
+                this.flush(live);
+                this.broadcast({ type: 'suggestion', sid: live.sid, text: text.slice(0, 300) }, true);
+            },
+            ask: (req) => new Promise((resolve) => {
+                this.flush(live);
+                const reqId = b64u(random(8));
+                const msg = { type: 'ask', sid: live.sid, reqId, ...req };
+                live.asks.set(reqId, { reqId, msg, resolve });
+                this.setState(live, 'needs_you');
+                this.broadcast(msg);
+                // For commands, the command itself is the useful line — "Run a command" says nothing.
+                const what = (req.risk === 'shell' || req.risk === 'danger') && req.detail ? req.detail.slice(0, 160) : req.summary;
+                this.notify('ask', { sid: live.sid, reqId, title: `${this.label(live)} needs your OK`, body: req.risk === 'danger' ? `⚠️ ${what}` : what });
+                this.log(`waiting for you: ${req.summary} ${req.risk === 'danger' ? '⚠️' : ''}`);
+            }),
+            usage: (u) => {
+                live.reported = u;
+            },
+            done: (ok, summary) => {
+                live.turns += 1;
+                this.flush(live);
+                this.setState(live, ok ? 'idle' : 'failed');
+                this.broadcast({ type: 'done', sid: live.sid, ok, summary });
+                this.notify(ok ? 'done' : 'error', { sid: live.sid, title: `${this.label(live)} ${ok ? 'finished' : 'stopped with a problem'}`, body: summary.slice(0, 300) });
+                this.log(`${ok ? 'done' : 'failed'} · ${live.sid}`);
+                if (live.session)
+                    void this.sendUsage(live);
+            },
+            error: (message, code) => {
+                this.flush(live);
+                this.setState(live, 'failed');
+                this.broadcast({ type: 'error', sid: live.sid, code: code ?? 'agent', message });
+                this.notify('error', { sid: live.sid, title: `${this.label(live)} hit a problem`, body: message.slice(0, 300) });
+                this.log(`error · ${message}`);
+            },
+        };
+    }
+    drop(live) {
+        if (Hub.busy(live.state))
+            this.awake.release();
+        for (const ask of live.asks.values())
+            ask.resolve({ decision: 'deny', message: 'Session closed from AgentPager.' });
+        live.session?.close();
+        this.live.delete(live.sid);
+    }
+    shutdown() {
+        this.awake.stop();
+        for (const live of [...this.live.values()])
+            this.drop(live);
+    }
+}

package/dist/pair.js

@@ -0,0 +1,51 @@
+// Pairing: the QR code is the trusted channel. It carries this computer's public key and a
+// one-time secret, so the relay can neither read the exchange nor slip in its own phone.
+import { platform } from 'node:os';
+import { onValue, ref, remove, set } from 'firebase/database';
+import { b64u, deriveChannelKeys, openJson, pairKey, random, sealJson, sharedSecret, } from './crypto.js';
+import { db } from './relay.js';
+const PAIR_TIMEOUT_MS = 10 * 60_000;
+export function offerPairing(state) {
+    const pairId = b64u(random(16));
+    const otk = random(32);
+    const link = `agentpager://pair?v=1&p=${pairId}&k=${state.identity.pub}&s=${b64u(otk)}` +
+        `&m=${encodeURIComponent(state.machineName)}`;
+    const node = ref(db, `pair/${pairId}`);
+    let stop = () => { };
+    const wait = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            stop();
+            reject(new Error('Pairing timed out. Run `agentpager pair` again.'));
+        }, PAIR_TIMEOUT_MS);
+        const unsub = onValue(node, async (snap) => {
+            const v = snap.val();
+            if (!v?.pk || v.ok)
+                return;
+            const info = openJson(pairKey(otk), { n: v.n, c: v.c }, `pair|${pairId}`);
+            if (!info)
+                return; // someone without the QR code
+            const keys = deriveChannelKeys(sharedSecret(state.identity, v.pk), otk);
+            const device = {
+                id: b64u(random(9)),
+                name: String(info.device || 'Phone').slice(0, 60),
+                channel: b64u(random(18)),
+                kB2P: b64u(keys.b2p),
+                kP2B: b64u(keys.p2b),
+                sendSeq: 0,
+                recvSeq: 0,
+                pairedAt: Date.now(),
+            };
+            await set(ref(db, `pair/${pairId}/ok`), sealJson(keys.b2p, { channel: device.channel, deviceId: device.id, machine: state.machineName, os: platform() }, `pairok|${pairId}`));
+            clearTimeout(timer);
+            unsub();
+            setTimeout(() => remove(node).catch(() => { }), 60_000);
+            resolve(device);
+        });
+        stop = () => {
+            clearTimeout(timer);
+            unsub();
+            remove(node).catch(() => { });
+        };
+    });
+    return { link, wait, cancel: () => stop() };
+}