@cosmovex/agentpager 0.1.0

package/dist/projects.js

@@ -0,0 +1,195 @@
+// Which folders the phone may start a session in, and how it finds them.
+//
+// The first version only offered folders that ALREADY had a session on this computer. Walk that as
+// the user: you install AgentPager because you want to start work from your phone, you pair, and
+// the Start button is disabled until you go back to your desk and start a session by hand. The
+// product was unusable on a fresh machine.
+//
+// So we discover the projects you actually work in (git repos) and let the phone browse for
+// anything else — but only inside a few ROOTS, and never into hidden directories, so "the phone can
+// pick a folder" never becomes "the phone can roam the disk".
+//
+// Roots are your home folder, the folder you started the bridge in, and the parent of any folder
+// you already have a session in. That last one matters: this machine keeps its projects on an
+// external drive, where a home-folder-only scan finds nothing at all.
+import { readdirSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+// The REAL path of the home folder: every check below compares against realpath()s, so a home that
+// sits behind a symlink (macOS /tmp, Fedora Silverblue's /home -> /var/home) would otherwise reject
+// its own owner's home folder as "outside your home folder".
+const HOME = (() => {
+    const h = resolve(homedir());
+    try {
+        return realpathSync.native(h);
+    }
+    catch {
+        return h;
+    }
+})();
+/** Big, uninteresting trees that a scan must not walk into. */
+const SKIP = new Set([
+    'node_modules',
+    'Library',
+    'Applications',
+    'Pictures',
+    'Music',
+    'Movies',
+    'build',
+    'dist',
+    'vendor',
+    'target',
+    'Pods',
+    '__pycache__',
+    'venv',
+    'go',
+]);
+const MAX_DEPTH = 3;
+const MAX_RESULTS = 40;
+const hidden = (name) => name.startsWith('.');
+/** Extra roots, learned from the sessions this computer already has. */
+const extraRoots = new Set();
+export function addRoot(dir) {
+    const full = real(resolve(dir));
+    if (!full)
+        return;
+    // The PARENT of a project, so its siblings are reachable — but never a whole drive: a session in
+    // /Volumes/DRIVE/proj must not make every folder on that disk browsable.
+    const parent = resolve(full, '..');
+    const depth = parent.split(sep).filter(Boolean).length;
+    const mountish = /^\/(Volumes|mnt|media|run\/media)(\/[^/]+)?$/.test(parent);
+    const root = depth >= 2 && !mountish ? parent : full;
+    if (root === HOME || root.startsWith(HOME + sep))
+        return;
+    // Never keep a root that sits inside another one — nested roots make "up one level" nonsense.
+    for (const existing of extraRoots) {
+        if (root === existing || root.startsWith(existing + sep))
+            return;
+    }
+    for (const existing of [...extraRoots]) {
+        if (existing.startsWith(root + sep))
+            extraRoots.delete(existing);
+    }
+    extraRoots.add(root);
+}
+/** Every folder tree the phone may see, home first. */
+export function roots() {
+    return [HOME, ...extraRoots];
+}
+/**
+ * The folder rules are a promise we print in the store listing, so they are checked against the REAL
+ * path: a symlink in your home folder pointing at /tmp would otherwise walk straight out of it.
+ */
+const real = (p) => {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return null; // unreadable or dangling: refuse, never assume
+    }
+};
+const isDir = (p) => {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const entries = (p) => {
+    try {
+        return readdirSync(p, { withFileTypes: true })
+            .filter((e) => e.isDirectory() || e.isSymbolicLink())
+            .map((e) => e.name);
+    }
+    catch {
+        return []; // unreadable folder: not an error, just nothing to offer
+    }
+};
+/**
+ * A folder the phone is allowed to start an agent in: inside your home folder, visible, real.
+ * Anything already known to the hub (a folder you have a session in) is allowed even if it sits
+ * elsewhere on the disk — you opened it yourself.
+ */
+export function allowedCwd(p, known = []) {
+    const asked = resolve(p);
+    for (const k of known)
+        if (resolve(k) === asked)
+            return true;
+    const full = real(asked);
+    if (!full || !isDir(full))
+        return false;
+    const root = roots().find((r) => full === r || full.startsWith(r + sep));
+    if (!root)
+        return false;
+    return !full
+        .slice(root.length)
+        .split(sep)
+        .some((part) => part && (hidden(part) || SKIP.has(part)));
+}
+/** Git repositories in your roots, most recently touched first. */
+export function discoverProjects() {
+    const found = [];
+    const seen = new Set();
+    const walk = (dir, depth) => {
+        if (found.length >= MAX_RESULTS * 3 || depth > MAX_DEPTH)
+            return;
+        for (const name of entries(dir)) {
+            if (hidden(name) || SKIP.has(name))
+                continue;
+            const child = join(dir, name);
+            if (!isDir(child))
+                continue;
+            // Symlinked folders are followed by isDir, so a link back into home (or a loop) would list the
+            // same repo several times and eat the 40 slots the phone's list is built from.
+            const truePath = real(child);
+            if (!truePath || seen.has(truePath))
+                continue;
+            seen.add(truePath);
+            if (isDir(join(child, '.git'))) {
+                let at = 0;
+                try {
+                    at = statSync(child).mtimeMs;
+                }
+                catch {
+                    /* keep it, just unranked */
+                }
+                found.push({ path: truePath, at });
+                continue; // a repo's own subfolders are not separate projects
+            }
+            walk(child, depth + 1);
+        }
+    };
+    for (const root of roots())
+        walk(root, 1);
+    return found
+        .sort((a, b) => b.at - a.at)
+        .slice(0, MAX_RESULTS)
+        .map((f) => f.path);
+}
+/**
+ * One level of folders, for the phone's folder picker. With no path it lists the roots themselves
+ * when there is more than one — otherwise a user whose work lives on another drive would be
+ * dropped into a home folder that has none of it.
+ */
+export function browseFolders(path) {
+    const all = roots();
+    if (!path && all.length > 1) {
+        return {
+            path: '',
+            dirs: all.map((r) => ({ name: r === HOME ? 'Home' : r.split(sep).pop() || r, path: r, git: isDir(join(r, '.git')) })),
+        };
+    }
+    const at = path && allowedCwd(path) ? resolve(path) : HOME;
+    const dirs = entries(at)
+        .filter((name) => !hidden(name) && !SKIP.has(name))
+        .map((name) => ({ name, path: join(at, name) }))
+        .filter((d) => isDir(d.path))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .slice(0, 200)
+        .map((d) => ({ ...d, git: isDir(join(d.path, '.git')) }));
+    // No parent once you are at a root: the picker must not walk up out of what you allowed.
+    const atRoot = all.includes(at);
+    return { path: at, parent: atRoot ? (all.length > 1 ? '' : undefined) : resolve(at, '..'), dirs };
+}
+export const homeFolder = () => HOME;

package/dist/protocol.js

@@ -0,0 +1 @@
+export const PROTOCOL = 1;

package/dist/relay.js

@@ -0,0 +1,134 @@
+// Firebase Realtime Database as a dumb, encrypted mailbox. It stores {n, c, t} and nothing else.
+//   ch/{channel}/p2b/{push}  phone → computer (deleted once read)
+//   ch/{channel}/b2p/{push}  computer → phone (deleted by the phone once read)
+//   ch/{channel}/hb          computer heartbeat {t, on} — lets the phone say "last heard from 3 min ago"
+//   ch/{channel}/phb         phone heartbeat {t} — lets us skip streaming to a phone nobody is looking at
+import { initializeApp } from 'firebase/app';
+import { child, endAt, get, getDatabase, orderByChild, query, onChildAdded, onDisconnect, onValue, push, ref, remove, serverTimestamp, set, } from 'firebase/database';
+import { openJson, sealJson, unb64u } from './crypto.js';
+const FIREBASE = {
+    apiKey: 'AIzaSyBJ8xQRZ9lE7mApTO8rgwiJoBAsVO1DwFM',
+    projectId: 'mdpilot-proto',
+    databaseURL: 'https://mdpilot-proto-default-rtdb.firebaseio.com',
+};
+export const db = getDatabase(initializeApp(FIREBASE));
+let serverOffset = 0;
+onValue(ref(db, '.info/serverTimeOffset'), (s) => {
+    serverOffset = Number(s.val() ?? 0);
+});
+export const serverNow = () => Date.now() + serverOffset;
+const PHONE_ACTIVE_MS = 45_000;
+const PUSH_URL = process.env.AGENTPAGER_PUSH_URL ?? process.env.MDPILOT_PUSH_URL ?? 'https://mdpilot-push.vercel.app/api/push';
+const HEARTBEAT_MS = 30_000;
+const STALE_MS = 7 * 24 * 3600_000;
+export class Channel {
+    device;
+    persist;
+    onMessage;
+    unsubs = [];
+    timer;
+    phoneSeen = 0;
+    phoneAway = true;
+    kB2P;
+    kP2B;
+    constructor(device, persist, onMessage) {
+        this.device = device;
+        this.persist = persist;
+        this.onMessage = onMessage;
+        this.kB2P = unb64u(device.kB2P);
+        this.kP2B = unb64u(device.kP2B);
+    }
+    path(leaf) {
+        return ref(db, `ch/${this.device.channel}/${leaf}`);
+    }
+    start() {
+        this.unsubs.push(onChildAdded(this.path('p2b'), (snap) => {
+            const raw = snap.val();
+            if (snap.key)
+                remove(child(this.path('p2b'), snap.key)).catch(() => { }); // exactly this message
+            if (!raw)
+                return;
+            const env = openJson(this.kP2B, raw, `${this.device.channel}|p2b`);
+            if (!env)
+                return; // not from our phone
+            if (env.seq <= this.device.recvSeq)
+                return; // replay
+            this.device.recvSeq = env.seq;
+            this.persist();
+            this.onMessage(env.body, this);
+        }));
+        this.unsubs.push(onValue(this.path('phb'), (snap) => {
+            this.phoneSeen = Number(snap.val()?.t ?? 0);
+            this.phoneAway = snap.val()?.away === true;
+        }));
+        this.sweep();
+        const hb = this.path('hb');
+        onDisconnect(hb).set({ t: serverTimestamp(), on: false }).catch(() => { });
+        const beat = () => set(hb, { t: serverTimestamp(), on: true }).catch(() => { });
+        beat();
+        this.timer = setInterval(beat, HEARTBEAT_MS);
+    }
+    /** Messages a phone never collected (uninstalled, lost) don't live in the relay forever. */
+    sweep() {
+        const cutoff = serverNow() - STALE_MS;
+        for (const dir of ['b2p', 'p2b']) {
+            get(query(this.path(dir), orderByChild('t'), endAt(cutoff)))
+                .then((snap) => snap.forEach((child) => void remove(child.ref).catch(() => { })))
+                .catch(() => { });
+        }
+    }
+    /** Is someone looking at the app right now? */
+    get phoneActive() {
+        return !this.phoneAway && serverNow() - this.phoneSeen < PHONE_ACTIVE_MS;
+    }
+    /**
+     * Wake the phone when nobody is looking: approvals, results, failures only.
+     * The payload is sealed with this phone's key; the push service and Google see ciphertext.
+     */
+    notify(kind, note, force = false) {
+        const token = this.device.pushToken;
+        if (!token)
+            return;
+        // Normally we don't buzz a phone someone is already looking at. A test is the exception: its
+        // whole purpose is to travel the real path while the screen is locked.
+        if (this.phoneActive && !force)
+            return;
+        const sealed = sealJson(this.kB2P, { kind, ...note }, `push|${this.device.id}`);
+        fetch(PUSH_URL, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ token, d: this.device.id, kind, ...sealed }),
+        })
+            .then((r) => {
+            if (r.status === 410) {
+                this.device.pushToken = undefined; // app uninstalled or token rotated
+                this.persist();
+            }
+        })
+            .catch(() => { });
+    }
+    /** Can this phone be buzzed while the app is closed? False = it will only see this if it's open. */
+    get canPush() {
+        return !!this.device.pushToken;
+    }
+    get deviceName() {
+        return this.device.name;
+    }
+    setPushToken(token) {
+        this.device.pushToken = token ?? undefined;
+        this.persist();
+    }
+    send(body) {
+        const seq = ++this.device.sendSeq;
+        this.persist();
+        const sealed = sealJson(this.kB2P, { seq, ts: Date.now(), body }, `${this.device.channel}|b2p`);
+        push(this.path('b2p'), { ...sealed, t: serverTimestamp() }).catch(() => { });
+    }
+    async stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        for (const u of this.unsubs.splice(0))
+            u();
+        await set(this.path('hb'), { t: serverTimestamp(), on: false }).catch(() => { });
+    }
+}

package/dist/risk.js

@@ -0,0 +1,78 @@
+const READ_ONLY = new Set(['Read', 'Glob', 'Grep', 'LS', 'WebSearch', 'WebFetch', 'TodoWrite', 'NotebookRead']);
+const EDITS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'edit']);
+const DANGER = [
+    /\brm\s+(-[a-z]*[rf]|--recursive|--force)/i,
+    /\bgit\s+push\b/i,
+    /\bgit\s+(reset\s+--hard|clean\s+-[a-z]*f|checkout\s+--\s|branch\s+-D)/i,
+    /--force\b|\s-f\s.*\bpush\b/i,
+    /\bsudo\b/i,
+    /\b(mkfs|dd\s+if=|shutdown|reboot)\b/i,
+    /\bchmod\s+-R\b|\bchown\s+-R\b/i,
+    /\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba|z)?sh\b/i,
+    /\bdrop\s+(table|database)\b|\btruncate\s+table\b/i,
+    /\b(firebase|vercel|netlify|fly|heroku)\s+deploy\b|\bdeploy\b/i,
+    /\b(npm|pnpm|yarn|cargo|twine|gem)\s+publish\b/i,
+    /\bgh\s+(release|pr\s+merge|repo\s+delete)\b/i,
+    /\bkubectl\s+(delete|apply)\b|\bterraform\s+(apply|destroy)\b/i,
+    /\bdocker\s+(system\s+prune|rm\s+-f|volume\s+rm)\b/i,
+];
+export function classify(tool, input) {
+    if (READ_ONLY.has(tool))
+        return 'low';
+    if (EDITS.has(tool))
+        return 'edit';
+    const command = String(input.command ?? input.cmd ?? '');
+    if (command && DANGER.some((re) => re.test(command)))
+        return 'danger';
+    return 'shell';
+}
+/** One short line a person can read at a glance (or hear): never a whole file. */
+export function describe(tool, input) {
+    const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+    const path = String(input.file_path ?? input.path ?? input.notebook_path ?? '');
+    switch (tool) {
+        case 'Bash':
+        case 'shell':
+            return { summary: 'Run a command', detail: clip(String(input.command ?? ''), 2000) };
+        case 'Edit':
+        case 'MultiEdit':
+        case 'edit':
+            return { summary: `Edit ${basename(path) || 'files'}`, detail: clip(String(input.detail ?? '') || path, 2000) };
+        case 'Write':
+            return { summary: `Write ${basename(path)}`, detail: clip(path, 2000) };
+        case 'WebFetch':
+            return { summary: 'Fetch a web page', detail: clip(String(input.url ?? ''), 500) };
+        default:
+            // 🧨 A JSON.stringify dump is what a phone screen CANNOT read — it is the single most-hated
+            // thing about the competing clients, and it is what an unknown tool used to produce here.
+            // Pull out the fields that actually mean something, and only fall back to raw JSON when the
+            // payload is genuinely unrecognisable.
+            return { summary: `Use ${tool}`, detail: clip(readable(input), 1500) };
+    }
+}
+/** The human-meaningful parts of an arbitrary tool payload, largest-signal first. */
+export function readable(input) {
+    const lines = [];
+    const seen = new Set();
+    // The keys agents actually use for the thing a person needs to see before saying yes.
+    for (const key of ['command', 'cmd', 'script', 'file_path', 'path', 'url', 'pattern', 'query', 'prompt', 'description', 'reason', 'content', 'new_string', 'detail']) {
+        const v = input[key];
+        if (v == null)
+            continue;
+        const text = typeof v === 'string' ? v : JSON.stringify(v);
+        if (!text || text === '{}' || text === '[]' || seen.has(text))
+            continue;
+        seen.add(text);
+        lines.push(lines.length === 0 && (key === 'command' || key === 'cmd' || key === 'script') ? text : `${key}: ${text}`);
+    }
+    if (lines.length)
+        return lines.join('\n');
+    // Nothing recognisable: show the shape rather than a wall of braces and quotes.
+    const entries = Object.entries(input).filter(([, v]) => v != null);
+    if (!entries.length)
+        return '';
+    return entries
+        .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
+        .join('\n');
+}
+const basename = (p) => p.split(/[\\/]/).filter(Boolean).pop() ?? '';

package/dist/service.js

@@ -0,0 +1,117 @@
+// `agentpager service install|uninstall` — keep the bridge running across reboots, as the user
+// (it must see the agents' own logins in the user's keychain/config, so never as root/SYSTEM).
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, platform, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { stateDir } from './store.js';
+const LABEL = 'com.cosmovex.agentpager';
+const cli = fileURLToPath(new URL('./cli.js', import.meta.url));
+const node = process.execPath;
+const logFile = join(stateDir, 'bridge.log');
+function run(cmd, args) {
+    execFileSync(cmd, args, { stdio: 'inherit' });
+}
+/** npx runs from a throwaway cache; a service pointing there breaks on the next cache clean. */
+function assertStableInstall() {
+    if (/[\\/]_npx[\\/]/.test(cli)) {
+        throw new Error('Install it permanently first:  npm install -g agentpager   then run:  agentpager service install');
+    }
+    // A macOS LaunchAgent cannot read an external/removable volume: the job starts and hangs before
+    // the first line of code, with no error anywhere. Measured 2026-09-23.
+    if (platform() === 'darwin' && cli.startsWith('/Volumes/')) {
+        throw new Error(`This copy lives on an external volume (${cli}).\n` +
+            'macOS login items cannot read those, so the service would start and hang silently.\n' +
+            'Install it on the internal disk instead:  npm install -g agentpager   then:  agentpager service install');
+    }
+}
+export function installService() {
+    assertStableInstall();
+    mkdirSync(stateDir, { recursive: true });
+    const os = platform();
+    if (os === 'darwin') {
+        const dir = join(homedir(), 'Library', 'LaunchAgents');
+        mkdirSync(dir, { recursive: true });
+        const plist = join(dir, `${LABEL}.plist`);
+        const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;');
+        writeFileSync(plist, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key><array><string>${esc(node)}</string><string>${esc(cli)}</string><string>start</string></array>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${esc(process.env.PATH ?? '')}</string></dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${esc(logFile)}</string>
+  <key>StandardErrorPath</key><string>${esc(logFile)}</string>
+</dict></plist>
+`);
+        const domain = `gui/${userInfo().uid}`;
+        try {
+            execFileSync('launchctl', ['bootout', domain, plist], { stdio: 'ignore' });
+        }
+        catch { }
+        run('launchctl', ['bootstrap', domain, plist]);
+        return `Running now and at every login (LaunchAgent). Log: ${logFile}\nNote: if Node or your agents live on an external drive, macOS may block a login item from reading it — install them on the main disk.`;
+    }
+    if (os === 'linux') {
+        const dir = join(homedir(), '.config', 'systemd', 'user');
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, 'agentpager.service'), `[Unit]
+Description=AgentPager bridge (phone remote for coding agents)
+After=network-online.target
+
+[Service]
+ExecStart=${node} ${cli} start
+Environment=PATH=${process.env.PATH ?? ''}
+Restart=always
+RestartSec=5
+StandardOutput=append:${logFile}
+StandardError=append:${logFile}
+
+[Install]
+WantedBy=default.target
+`);
+        run('systemctl', ['--user', 'daemon-reload']);
+        run('systemctl', ['--user', 'enable', '--now', 'agentpager.service']);
+        return `Running now and at every login (systemd user service). Log: ${logFile}\nTo keep it running while you're logged out:  loginctl enable-linger ${userInfo().username}`;
+    }
+    if (os === 'win32') {
+        run('schtasks', ['/Create', '/F', '/SC', 'ONLOGON', '/RL', 'LIMITED', '/TN', 'AgentPager', '/TR', `"${node}" "${cli}" start`]);
+        run('schtasks', ['/Run', '/TN', 'AgentPager']);
+        return 'Running now and at every sign-in (Scheduled Task "AgentPager").';
+    }
+    throw new Error(`Automatic start isn't supported on ${os} yet. Keep \`agentpager\` running in a terminal.`);
+}
+export function uninstallService() {
+    const os = platform();
+    if (os === 'darwin') {
+        const plist = join(homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+        try {
+            execFileSync('launchctl', ['bootout', `gui/${userInfo().uid}`, plist], { stdio: 'ignore' });
+        }
+        catch { }
+        if (existsSync(plist))
+            rmSync(plist);
+        return 'Stopped and removed from login items.';
+    }
+    if (os === 'linux') {
+        try {
+            execFileSync('systemctl', ['--user', 'disable', '--now', 'agentpager.service'], { stdio: 'ignore' });
+        }
+        catch { }
+        const unit = join(homedir(), '.config', 'systemd', 'user', 'agentpager.service');
+        if (existsSync(unit))
+            rmSync(unit);
+        return 'Stopped and removed.';
+    }
+    if (os === 'win32') {
+        try {
+            execFileSync('schtasks', ['/Delete', '/F', '/TN', 'AgentPager'], { stdio: 'ignore' });
+        }
+        catch { }
+        return 'Removed the "AgentPager" scheduled task.';
+    }
+    return 'Nothing to remove.';
+}

package/dist/store.js

@@ -0,0 +1,83 @@
+// Local state in ~/.mdpilot/state.json (mode 600): this computer's identity and paired phones.
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+import { statSync } from 'node:fs';
+import { generateKeyPair } from './crypto.js';
+export const stateDir = process.env.AGENTPAGER_HOME ?? join(homedir(), '.agentpager');
+const stateFile = join(stateDir, 'state.json');
+export function loadState() {
+    if (!existsSync(stateDir))
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    if (existsSync(stateFile))
+        return JSON.parse(readFileSync(stateFile, 'utf8'));
+    const fresh = {
+        identity: generateKeyPair(),
+        machineName: hostname().replace(/\.local$/, ''),
+        devices: [],
+    };
+    saveState(fresh);
+    return fresh;
+}
+/**
+ * Change the devices list without losing somebody else's change.
+ *
+ * `main()` loads state once at startup, and long-lived commands then save that snapshot minutes
+ * later. `agentpager pair` sits waiting for a QR scan the whole time. So unpairing two phones in
+ * another terminal, watching `devices` confirm they were gone, and then completing a pair brought
+ * both of them back — with their original timestamps — because pair wrote its stale copy over the
+ * top. That is not untidiness: a device entry is a live credential, so **unpair was not actually
+ * revoking access.**
+ *
+ * Re-reading inside a lock at the moment of writing is what makes a deletion stick.
+ */
+export function updateState(mutate) {
+    const release = lock();
+    try {
+        const fresh = loadState();
+        mutate(fresh);
+        saveState(fresh);
+        return fresh;
+    }
+    finally {
+        release();
+    }
+}
+/** Crude on purpose: one writer at a time, and never wedged by a crash that left the file behind. */
+function lock() {
+    const path = `${stateFile}.lock`;
+    const deadline = Date.now() + 5000;
+    for (;;) {
+        try {
+            closeSync(openSync(path, 'wx')); // O_EXCL: fails if another process holds it
+            return () => {
+                try {
+                    rmSync(path);
+                }
+                catch {
+                    /* already gone */
+                }
+            };
+        }
+        catch {
+            // Stale lock from a process that died mid-write: take it rather than block for ever.
+            try {
+                if (Date.now() - statSync(path).mtimeMs > 30_000)
+                    rmSync(path);
+            }
+            catch {
+                /* raced with the owner releasing it */
+            }
+            if (Date.now() > deadline)
+                return () => { }; // never make a write impossible
+            sleepSync(25);
+        }
+    }
+}
+const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+export function saveState(state) {
+    const tmp = `${stateFile}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+    renameSync(tmp, stateFile);
+    chmodSync(stateFile, 0o600);
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@cosmovex/agentpager",
+  "version": "0.1.0",
+  "description": "Pager for your AI coding agents \u2014 approve, reply and hear results on your phone. End-to-end encrypted.",
+  "main": "dist/cli.js",
+  "scripts": {
+    "build": "tsc && node -e \"const fs=require('fs');for(const f of ['dist/cli.js','dist/guard/bin.js'])fs.chmodSync(f,0o755)\"",
+    "dev": "tsx src/cli.ts",
+    "test": "tsx --test --test-force-exit --test-concurrency=1 src/guard/*.test.ts src/agents/*.test.ts src/*.test.ts && tsx src/selftest.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.278",
+    "@zed-industries/agent-client-protocol": "^0.4.5",
+    "firebase": "^12.19.0",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  },
+  "bin": {
+    "agentpager": "dist/cli.js",
+    "agentpager-guard": "dist/guard/bin.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude-code",
+    "codex",
+    "acp",
+    "agent",
+    "remote",
+    "mobile",
+    "approval",
+    "notifications",
+    "voice",
+    "agentpager",
+    "gemini-cli",
+    "opencode",
+    "qwen-code",
+    "goose",
+    "deepseek",
+    "agent-client-protocol",
+    "hands-free"
+  ],
+  "homepage": "https://play.google.com/store/apps/details?id=com.cosmovex.agentpager"
+}