@cosmovex/agentpager 0.1.0

package/dist/awake.js

@@ -0,0 +1,73 @@
+// Keep this computer awake while an agent is actually working.
+//
+// The whole promise is "walk away and it keeps going". A laptop that naps ten minutes after you
+// leave the desk breaks it in the most confusing way possible: the phone says the computer went
+// offline, the run is frozen mid-task, and nothing explains why.
+//
+// So while a session is running — and only then — we hold an idle-sleep inhibitor. It is the same
+// thing a video call or a long download does. It does NOT fight a closed lid or a deliberate sleep,
+// and it releases the moment the last agent goes idle, so an idle bridge never keeps a laptop up.
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+export class AwakeLock {
+    enabled;
+    log;
+    child;
+    holders = 0;
+    announced = false;
+    constructor(enabled, log) {
+        this.enabled = enabled;
+        this.log = log;
+    }
+    /** Something started working. Balanced by release(). */
+    acquire() {
+        this.holders++;
+        if (!this.enabled || this.child || this.holders === 0)
+            return;
+        const cmd = this.command();
+        if (!cmd)
+            return;
+        try {
+            this.child = spawn(cmd[0], cmd.slice(1), { stdio: 'ignore' });
+            this.child.on('error', () => (this.child = undefined)); // tool missing: not worth a word
+            this.child.on('exit', () => (this.child = undefined));
+            if (!this.announced) {
+                this.announced = true;
+                this.log('keeping this computer awake while an agent is working');
+            }
+        }
+        catch {
+            this.child = undefined;
+        }
+    }
+    release() {
+        this.holders = Math.max(0, this.holders - 1);
+        if (this.holders === 0)
+            this.stop();
+    }
+    stop() {
+        this.child?.kill();
+        this.child = undefined;
+    }
+    command() {
+        switch (platform()) {
+            case 'darwin':
+                // -i: no idle sleep. Not -d/-s, so the screen still sleeps and a closed lid still wins.
+                return ['caffeinate', '-i'];
+            case 'linux':
+                return ['systemd-inhibit', '--what=idle', '--who=AgentPager', '--why=an agent is running', 'sleep', 'infinity'];
+            case 'win32':
+                // ES_CONTINUOUS | ES_SYSTEM_REQUIRED is held by the calling thread for as long as this
+                // PowerShell lives, and is dropped when we kill it. No native module needed.
+                return [
+                    'powershell',
+                    '-NoProfile',
+                    '-NonInteractive',
+                    '-Command',
+                    "Add-Type -Namespace AP -Name K -MemberDefinition '[DllImport(\"kernel32.dll\")] public static extern uint SetThreadExecutionState(uint f);'; [AP.K]::SetThreadExecutionState(2147483649) | Out-Null; Start-Sleep -Seconds 2147483",
+                ];
+            default:
+                return null;
+        }
+    }
+}

package/dist/cli.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+// agentpager — keep your coding agents one tap away on your phone.
+//   agentpager            pair if needed, then stay connected
+//   agentpager pair       pair another phone
+//   agentpager devices    list paired phones
+//   agentpager unpair ID  remove a phone
+//   agentpager doctor     check which agents this computer can drive
+//   agentpager guard      PreToolUse hook: asks before anything irreversible, denies past a budget
+//   agentpager notify "<text>"   page your phone from any script
+//   agentpager ask "<question>"  ask your phone: exit 0 approved · 1 denied · 2 nobody answered
+//   agentpager service install|uninstall   start automatically at login
+//   --no-keep-awake              let this computer idle-sleep even while an agent is working
+import qrcode from 'qrcode-terminal';
+import { ACP_AGENTS, AcpAgent, userAgents } from './agents/acp.js';
+import { ClaudeAgent } from './agents/claude.js';
+import { CodexAgent } from './agents/codex.js';
+import { BRIDGE_VERSION, Hub } from './hub.js';
+import { offerPairing } from './pair.js';
+import { callControl, serveControl } from './control.js';
+import { staleBuildWarning } from './freshness.js';
+import { runRuleCommand, USAGE as GUARD_USAGE } from './guard/cli.js';
+import { install as guardInstall, runDeskHook, runHook, status as guardStatus, uninstall as guardUninstall } from './guard/index.js';
+import { Channel } from './relay.js';
+import { installService, uninstallService } from './service.js';
+import { loadState, saveState, updateState } from './store.js';
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const log = (line) => console.log(`${dim(new Date().toLocaleTimeString())}  ${line}`);
+/** `--timeout 90s | 10m | 2h | 600` (bare numbers are seconds). */
+function duration(v) {
+    const m = /^(\d+)(s|m|h)?$/.exec((v ?? '').trim());
+    if (!m)
+        return undefined;
+    const n = Number(m[1]);
+    return n * (m[2] === 'h' ? 3600_000 : m[2] === 'm' ? 60_000 : 1000);
+}
+async function pair(state) {
+    const offer = offerPairing(state);
+    console.log(`\n${bold('Pair your phone')}  — in the AgentPager app tap "Scan the code" (or point your phone camera here):\n`);
+    qrcode.generate(offer.link, { small: true });
+    console.log(dim(`Can't scan? Paste this into the app:\n${offer.link}\n`));
+    const device = await offer.wait;
+    // Not `state.devices.push(...)`: this snapshot is as old as the QR code on screen, and anything
+    // that changed the device list while we waited would be silently undone.
+    updateState((s) => s.devices.push(device));
+    state.devices.push(device); // keep the in-memory copy usable for a caller that goes on to serve
+    console.log(`\n✅ Paired with ${bold(device.name)}.\n`);
+    // Pairing does not make this computer reachable — serving does. Standalone `agentpager pair`
+    // printed this tick and exited, leaving the phone attached to nothing: it showed "waiting for the
+    // computer to say which agents it has", then "computer is offline". Both were true, and neither
+    // was the phone's fault. Say what is missing, and only when it is actually missing.
+    if (!(await bridgeRunning())) {
+        console.log(`${bold('One more step:')} run ${bold('agentpager')} to keep this computer reachable.`);
+        console.log(dim('Until something is serving, your phone has nothing to talk to.\n'));
+    }
+}
+/** Is a bridge already serving on this machine? The control socket is the cheapest honest answer. */
+async function bridgeRunning() {
+    try {
+        await callControl({ kind: 'ping', title: '', text: '' }, 1500);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Claude and Codex natively; everything else through ACP, if it's installed. */
+async function buildAgents() {
+    const codex = new CodexAgent();
+    const agents = new Map([
+        ['claude', new ClaudeAgent()],
+        ['codex', codex],
+    ]);
+    const acp = [...ACP_AGENTS, ...userAgents()].map((spec) => new AcpAgent(spec));
+    const present = await Promise.all(acp.map(async (a) => ((await a.status()).available ? a : null)));
+    for (const a of present)
+        if (a)
+            agents.set(a.id, a);
+    return { agents, codex };
+}
+async function serve(state, keepAwake) {
+    // Native agents are cheap to construct; ACP agents are PROBED, and a probe can hang without a
+    // terminal (it did, as a login service) — so the relay must come up first, never behind them.
+    const codex = new CodexAgent();
+    const agents = new Map([
+        ['claude', new ClaudeAgent()],
+        ['codex', codex],
+    ]);
+    const hub = new Hub(agents, state.machineName, log, keepAwake);
+    const persist = () => saveState(state);
+    const channels = state.devices.map((d) => new Channel(d, persist, (msg, ch) => hub.handle(msg, ch)));
+    for (const c of channels) {
+        hub.attach(c);
+        c.start();
+    }
+    const stopControl = serveControl((req) => hub.job(req));
+    // Detect the ACP agents in the background and announce them as they appear.
+    void (async () => {
+        for (const spec of [...ACP_AGENTS, ...userAgents(log)]) {
+            const agent = new AcpAgent(spec);
+            if ((await agent.status()).available) {
+                await hub.addAgent(agent);
+                log(`${agent.name} available`);
+            }
+        }
+    })();
+    const statuses = await Promise.all([...agents.values()].map((a) => a.status()));
+    console.log(`\n${bold('AgentPager bridge')} ${BRIDGE_VERSION} · ${state.machineName}`);
+    const stale = staleBuildWarning();
+    if (stale)
+        console.log(`  ⚠️  ${stale}`);
+    for (const s of statuses)
+        console.log(`  ${s.available ? '●' : '○'} ${s.name}${s.version ? ` ${dim(s.version)}` : ''}${s.available ? '' : dim(`  ${s.reason}`)}`);
+    console.log(`  ${state.devices.length} phone${state.devices.length === 1 ? '' : 's'} paired`);
+    console.log(dim('\nKeep this running (or run `agentpager service install` to start it at login).'));
+    // Someone who reinstalls the app, or picks up a second phone, reasonably runs `agentpager` again
+    // and waits for a code that never comes — this is the only place they will look for why.
+    console.log(dim('Pairing another phone (or the same one after a reinstall)? Run `agentpager pair`.'));
+    console.log(dim('Your sessions stay on this computer; the relay only sees encrypted bytes.\n'));
+    const quit = async () => {
+        console.log(dim('\nDisconnecting…'));
+        hub.shutdown();
+        stopControl();
+        codex.shutdown();
+        await Promise.all(channels.map((c) => c.stop()));
+        process.exit(0);
+    };
+    process.on('SIGINT', quit);
+    process.on('SIGTERM', quit);
+}
+async function main() {
+    const [cmd, arg] = process.argv.slice(2);
+    // Before anything else: the guard runs once per tool call, so it must not pay for loading state,
+    // reading the keychain, or touching the relay. Bare `guard` is the hook itself and speaks only
+    // JSON on stdout — nothing else may print to stdout on that path.
+    if (cmd === 'guard') {
+        // Every branch must exit: Firebase is loaded by this file and keeps the loop alive.
+        if (arg === undefined)
+            await runHook();
+        else if (arg === 'desk')
+            await runDeskHook();
+        else if (arg === 'install')
+            guardInstall();
+        else if (arg === 'uninstall')
+            guardUninstall();
+        else if (arg === 'status')
+            await guardStatus();
+        else if (!runRuleCommand(arg, process.argv.slice(4)))
+            console.log(GUARD_USAGE);
+        return process.exit(process.exitCode ?? 0);
+    }
+    const state = loadState();
+    switch (cmd ?? 'start') {
+        case 'start': {
+            // Two bridges on one computer answer the same phone twice. Notice, and say so.
+            const running = await callControl({ kind: 'ping', title: '', text: '' }, 2000).catch(() => null);
+            if (running) {
+                console.log(`AgentPager is already running on this computer (${running.phones} phone${running.phones === 1 ? '' : 's'} paired).`);
+                console.log(dim('Use that window, or stop it before starting another.'));
+                process.exit(0);
+            }
+            if (!state.devices.length)
+                await pair(state);
+            await serve(state, !process.argv.includes('--no-keep-awake'));
+            break;
+        }
+        case 'pair':
+            await pair(state);
+            process.exit(0);
+        case 'devices':
+            if (!state.devices.length)
+                console.log('No phones paired. Run `agentpager pair`.');
+            for (const d of state.devices)
+                console.log(`${d.id}  ${d.name}  ${dim(`paired ${new Date(d.pairedAt).toLocaleDateString()}`)}`);
+            process.exit(0);
+        case 'unpair': {
+            const before = state.devices.length;
+            const after = updateState((s) => {
+                s.devices = s.devices.filter((d) => d.id !== arg);
+            });
+            state.devices = after.devices;
+            console.log(before === state.devices.length ? `No phone with id ${arg}.` : 'Removed. That phone can no longer reach this computer.');
+            process.exit(0);
+        }
+        case 'notify':
+        case 'ask': {
+            // Parse flags properly: a flag's VALUE must not leak into the message body.
+            const argv = process.argv.slice(3);
+            const words = [];
+            let title = '';
+            let danger = false;
+            let json = false;
+            let timeoutMs;
+            for (let i = 0; i < argv.length; i++) {
+                if (argv[i] === '--title')
+                    title = argv[++i] ?? '';
+                else if (argv[i] === '--danger')
+                    danger = true;
+                else if (argv[i] === '--timeout')
+                    timeoutMs = duration(argv[++i]);
+                else if (argv[i] === '--json')
+                    json = true;
+                else
+                    words.push(argv[i]);
+            }
+            const text = words.join(' ').trim();
+            if (!text) {
+                console.log(`Usage: agentpager ${cmd} "<text>" [--title "<short title>"] [--json]` +
+                    (cmd === 'ask' ? ' [--timeout 10m] [--danger]' : ''));
+                process.exit(1);
+            }
+            const res = await callControl({
+                kind: cmd,
+                title: title || (cmd === 'ask' ? text.slice(0, 60) : 'Job finished'),
+                text,
+                risk: danger ? 'danger' : undefined,
+                cwd: process.cwd(),
+                timeoutMs,
+            });
+            // A workflow step needs to record WHO approved and WHY it stopped, not just an exit code.
+            // Exit codes stay exactly as they were — 0 approve, 1 deny, 2 could-not-ask — because they are
+            // what every `if` in every pipeline is already written against.
+            const report = (outcome, extra = {}) => {
+                if (!json)
+                    return;
+                console.log(JSON.stringify({
+                    outcome,
+                    phone: res.phone ?? null,
+                    phones: res.phones,
+                    pushable: res.pushable,
+                    ...extra,
+                }));
+            };
+            // Say what actually happened. "Sent to your phone" when no phone is paired is how a script
+            // ends up trusting a message nobody could ever have seen.
+            if (!res.phones) {
+                report('no_phone');
+                if (!json)
+                    console.error('✖ No phone is paired with this computer. Run `agentpager pair` first.');
+                process.exit(2);
+            }
+            const where = res.phone ? ` (${res.phone})` : '';
+            const deaf = res.pushable === 0 ? `\n${dim('Notifications are off in the app, so this only shows while the app is open.')}` : '';
+            if (cmd === 'notify') {
+                report('sent');
+                if (!json)
+                    console.log(`sent to your phone${where}${deaf}`);
+                process.exit(0);
+            }
+            if (res.decision === 'timeout') {
+                report('timeout');
+                if (!json)
+                    console.error(`⏳ Nobody answered on your phone${where} in time — nothing was approved.${deaf}`);
+                process.exit(2);
+            }
+            report(res.decision === 'allow' ? 'approved' : 'denied');
+            if (!json) {
+                console.log(res.decision === 'allow' ? `✅ approved on your phone${where}` : `⛔️ denied on your phone${where}`);
+            }
+            process.exit(res.decision === 'allow' ? 0 : 1);
+        }
+        case 'doctor': {
+            const staleDoctor = staleBuildWarning();
+            if (staleDoctor)
+                console.log(`⚠️  ${staleDoctor}\n`);
+            const codex = new CodexAgent();
+            const native = [new ClaudeAgent(), codex];
+            for (const a of native) {
+                const s = await a.status();
+                console.log(`${s.available ? '●' : '○'} ${s.name} ${dim(s.version ?? s.reason ?? '')}`);
+                if (s.available) {
+                    const list = await a.list().catch((e) => (console.log(dim(`   can't list sessions: ${e.message}`)), []));
+                    console.log(dim(`   ${list.length} recent sessions`));
+                }
+            }
+            // Every ACP candidate, including the ones that are not here — "why isn't my agent showing up"
+            // is unanswerable when the tool only prints what worked.
+            const specs = [...ACP_AGENTS, ...userAgents((l) => console.log(dim(l)))];
+            const missing = [];
+            for (const spec of specs) {
+                const s = await new AcpAgent(spec).status();
+                if (s.available) {
+                    console.log(`● ${s.name} ${dim(s.version ?? '')}`);
+                }
+                else if (s.reason?.includes('did not answer')) {
+                    console.log(`○ ${s.name} ${dim(s.reason)}`); // installed but not speaking ACP: worth saying
+                }
+                else {
+                    missing.push(`${spec.name} (${spec.command})`);
+                }
+            }
+            if (missing.length) {
+                console.log(dim(`\nNot installed here: ${missing.join(' · ')}`));
+                console.log(dim('Any other ACP agent: add it to ~/.agentpager/agents.json'));
+                console.log(dim('  [{ "id": "mine", "name": "My Agent", "command": "my-agent", "args": ["acp"] }]'));
+            }
+            codex.shutdown();
+            process.exit(0);
+        }
+        case 'service': {
+            if (arg === 'install') {
+                if (!state.devices.length)
+                    throw new Error('Pair your phone first: run `agentpager`, scan the code, then install the service.');
+                console.log(installService());
+            }
+            else if (arg === 'uninstall') {
+                console.log(uninstallService());
+            }
+            else {
+                console.log('Usage: agentpager service install | uninstall');
+            }
+            process.exit(0);
+        }
+        default:
+            console.log('Usage: agentpager [start | pair | devices | unpair <id> | doctor | guard install|status|rules|test | notify <text> | ask <text> | service install|uninstall]');
+            process.exit(1);
+    }
+}
+main().catch((e) => {
+    // 🧨 Exit 1 means DENIED. A pipeline that cannot reach the bridge was not denied by anybody, and
+    // treating the two the same is how a workflow decides a human said no when nothing ever asked.
+    // `ask` and `notify` are the commands whose exit code something else branches on, so a failure
+    // there is 2 — could-not-ask — exactly like a timeout.
+    const cmd = process.argv[2];
+    const couldNotAsk = cmd === 'ask' || cmd === 'notify';
+    if (process.argv.includes('--json')) {
+        console.log(JSON.stringify({ outcome: 'unreachable', error: `${e?.message ?? e}` }));
+    }
+    else {
+        console.error(`✖ ${e?.message ?? e}`);
+    }
+    process.exit(couldNotAsk ? 2 : 1);
+});

package/dist/control.js

@@ -0,0 +1,110 @@
+// Local control socket: lets ANY script on this computer page the phone.
+//   agentpager notify "AAB built"              → a notification
+//   agentpager ask "Deploy to prod?"           → exit 0 if you approve, 1 if you deny
+// Only processes on this machine can reach it (unix socket in ~/.agentpager, mode 600;
+// a named pipe on Windows). Nothing is exposed to the network.
+import { createServer, connect } from 'node:net';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, rmSync } from 'node:fs';
+import { platform, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { stateDir } from './store.js';
+/**
+ * Unix sockets have a ~104-character path limit, and a long state dir silently breaks
+ * bind(). Fall back to a short, deterministic path in the temp dir when that would happen.
+ */
+export const socketPath = () => {
+    if (platform() === 'win32')
+        return '\\\\.\\pipe\\agentpager';
+    const preferred = join(stateDir, 'control.sock');
+    if (preferred.length <= 100)
+        return preferred;
+    const tag = createHash('sha256').update(stateDir).digest('hex').slice(0, 10);
+    return join(tmpdir(), `agentpager-${tag}.sock`);
+};
+export function serveControl(handle) {
+    const path = socketPath();
+    if (platform() !== 'win32') {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        if (existsSync(path))
+            rmSync(path);
+    }
+    const open = new Set();
+    const server = createServer((socket) => {
+        open.add(socket);
+        socket.on('close', () => open.delete(socket));
+        let data = '';
+        socket.on('data', (d) => {
+            data += d.toString();
+            const line = data.indexOf('\n');
+            if (line < 0)
+                return;
+            let req;
+            try {
+                req = JSON.parse(data.slice(0, line));
+            }
+            catch {
+                socket.end(JSON.stringify({ error: 'bad request' }) + '\n');
+                return;
+            }
+            handle(req).then((res) => socket.end(JSON.stringify(res) + '\n'), (e) => socket.end(JSON.stringify({ error: String(e?.message ?? e) }) + '\n'));
+        });
+        socket.on('error', () => { });
+    });
+    server.listen(path, () => {
+        if (platform() !== 'win32')
+            chmodSync(path, 0o600);
+    });
+    // A second bridge instance simply doesn't take the socket — but say so, because a silent
+    // failure here means `agentpager notify|ask` stops working with no explanation.
+    server.on('error', (e) => {
+        if (e.code !== 'EADDRINUSE')
+            console.error(`notify/ask socket unavailable (${e.code ?? e.message}) at ${path}`);
+    });
+    // Resolves once the address is really free. A Windows named pipe has a fixed name and is not
+    // released until close() completes, so a caller that restarts straight after stop() would fail
+    // with EADDRINUSE and silently lose the socket.
+    return () => new Promise((done) => {
+        server.close(() => {
+            if (platform() !== 'win32' && existsSync(path))
+                rmSync(path);
+            done();
+        });
+        for (const s of open)
+            s.destroy();
+    });
+}
+/** Client side of the socket, used by the `notify` / `ask` commands. */
+export function callControl(req, timeoutMs = 3600_000) {
+    return new Promise((resolve, reject) => {
+        const socket = connect(socketPath());
+        // The bridge applies the real deadline and withdraws the card from the phone when it passes;
+        // this one is only a backstop for a bridge that stopped answering at all.
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error('The AgentPager bridge stopped responding.'));
+        }, timeoutMs + 15_000);
+        let data = '';
+        socket.on('connect', () => socket.write(JSON.stringify(req) + '\n'));
+        socket.on('data', (d) => {
+            data += d.toString();
+            if (!data.includes('\n'))
+                return;
+            clearTimeout(timer);
+            socket.end();
+            try {
+                const res = JSON.parse(data.trim());
+                if (res.error)
+                    return reject(new Error(res.error));
+                resolve(res);
+            }
+            catch (e) {
+                reject(new Error('Unreadable reply from the bridge.'));
+            }
+        });
+        socket.on('error', () => {
+            clearTimeout(timer);
+            reject(new Error('AgentPager is not running on this computer. Start it with `agentpager`.'));
+        });
+    });
+}

package/dist/crypto.js

@@ -0,0 +1,65 @@
+// End-to-end crypto shared with the phone (lib/remote/remote_crypto.dart).
+// X25519 key agreement, HKDF-SHA256, ChaCha20-Poly1305 (IETF, 12-byte nonce).
+// The relay only ever stores {n, c}; it can neither read nor forge messages.
+import { createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, } from 'node:crypto';
+export const b64u = (b) => Buffer.from(b).toString('base64url');
+export const unb64u = (s) => new Uint8Array(Buffer.from(s, 'base64url'));
+export const utf8 = (s) => new Uint8Array(Buffer.from(s, 'utf8'));
+export const random = (n) => new Uint8Array(randomBytes(n));
+export function generateKeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync('x25519');
+    const jwk = privateKey.export({ format: 'jwk' });
+    void publicKey;
+    return { pub: jwk.x, priv: jwk.d };
+}
+export function sharedSecret(own, peerPub) {
+    const privateKey = createPrivateKey({
+        key: { kty: 'OKP', crv: 'X25519', d: own.priv, x: own.pub },
+        format: 'jwk',
+    });
+    const publicKey = createPublicKey({ key: { kty: 'OKP', crv: 'X25519', x: peerPub }, format: 'jwk' });
+    return new Uint8Array(diffieHellman({ privateKey, publicKey }));
+}
+export function hkdf(ikm, salt, info) {
+    return new Uint8Array(hkdfSync('sha256', ikm, salt, utf8(info), 32));
+}
+export function seal(key, plaintext, aad) {
+    const nonce = random(12);
+    const cipher = createCipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 });
+    cipher.setAAD(utf8(aad), { plaintextLength: plaintext.length });
+    const body = Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+    return { n: b64u(nonce), c: b64u(body) };
+}
+/** Returns null when the message was not produced by the holder of `key`. */
+export function open(key, sealed, aad) {
+    try {
+        const body = unb64u(sealed.c);
+        if (body.length < 16)
+            return null;
+        const decipher = createDecipheriv('chacha20-poly1305', key, unb64u(sealed.n), { authTagLength: 16 });
+        decipher.setAAD(utf8(aad), { plaintextLength: body.length - 16 });
+        decipher.setAuthTag(body.subarray(body.length - 16));
+        return new Uint8Array(Buffer.concat([decipher.update(body.subarray(0, body.length - 16)), decipher.final()]));
+    }
+    catch {
+        return null;
+    }
+}
+export const sealJson = (key, value, aad) => seal(key, utf8(JSON.stringify(value)), aad);
+export function openJson(key, sealed, aad) {
+    const plain = open(key, sealed, aad);
+    if (!plain)
+        return null;
+    try {
+        return JSON.parse(Buffer.from(plain).toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Keys for one paired phone. Separate keys per direction so nonces never collide across them. */
+export function deriveChannelKeys(shared, otk) {
+    const root = hkdf(shared, otk, 'mdpilot-root-v1');
+    return { b2p: hkdf(root, new Uint8Array(0), 'b2p'), p2b: hkdf(root, new Uint8Array(0), 'p2b') };
+}
+export const pairKey = (otk) => hkdf(otk, new Uint8Array(0), 'mdpilot-pair-v1');

package/dist/freshness.js

@@ -0,0 +1,60 @@
+// Is the code running the one that was written?
+//
+// The bridge runs from `dist/`, and `agentpager` is not on npm yet, so everyone — including us —
+// launches a locally compiled copy. A `dist/` built before the last edit to `src/` is invisible:
+// it starts, pairs, says "AgentPager bridge", and simply behaves like an older program. That is
+// what made a phone show Codex alone with Claude Code missing, and no amount of reading the
+// current source could explain it.
+import { readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Newest mtime under a directory tree, or 0 if it cannot be read. */
+function newest(dir) {
+    let latest = 0;
+    const walk = (d, depth) => {
+        if (depth > 6)
+            return;
+        let names;
+        try {
+            names = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name === 'node_modules' || name.startsWith('.'))
+                continue;
+            const p = join(d, name);
+            let st;
+            try {
+                st = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory())
+                walk(p, depth + 1);
+            else if (/\.(ts|js|json)$/.test(name))
+                latest = Math.max(latest, st.mtimeMs);
+        }
+    };
+    walk(dir, 0);
+    return latest;
+}
+/**
+ * Returns a warning when the compiled bridge is older than its sources, or null when it is current.
+ * Never throws and never blocks startup: a packaged install has no `src/` and must stay silent.
+ */
+export function staleBuildWarning(distFile = fileURLToPath(import.meta.url)) {
+    const distDir = dirname(distFile);
+    const root = dirname(distDir);
+    const srcAt = newest(join(root, 'src'));
+    if (!srcAt)
+        return null; // published package: sources aren't shipped, nothing to compare
+    const distAt = newest(distDir);
+    if (!distAt || distAt >= srcAt)
+        return null;
+    const behind = Math.round((srcAt - distAt) / 1000);
+    const ago = behind > 86400 ? `${Math.round(behind / 86400)}d` : behind > 3600 ? `${Math.round(behind / 3600)}h` : `${Math.round(behind / 60)}m`;
+    return `This bridge was built ${ago} BEFORE the last source change — you are running old code. Run \`npm run build\` in bridge/ and start again.`;
+}