@cosmovex/agentpager 0.1.2 → 0.1.3

package/dist/cli.js

@@ -22,7 +22,8 @@ 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';
+import { loadState, updateState } from './store.js';
+import { isNewer, latestVersion, UPDATE_COMMAND } from './update.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}`);
@@ -34,7 +35,22 @@ function duration(v) {
     const n = Number(m[1]);
     return n * (m[2] === 'h' ? 3600_000 : m[2] === 'm' ? 60_000 : 1000);
 }
+/** One line per paired phone, with the id `unpair` wants. Never leaves someone guessing what is paired. */
+function printPhones(devices, indent = '  ') {
+    for (const d of devices) {
+        console.log(`${indent}${bold(d.name)}  ${dim(`id ${d.id} · paired ${new Date(d.pairedAt).toLocaleDateString()}`)}`);
+    }
+}
+const UNPAIR_HINT = 'Remove a phone: `agentpager unpair <id>` (or `agentpager unpair --all`). List them: `agentpager devices`.';
 async function pair(state) {
+    // Re-read: this snapshot may be as old as the terminal. "Paired" with no way to see what, or to
+    // undo it, is what made setup feel like a trap.
+    const current = loadState().devices;
+    if (current.length) {
+        console.log(`\n${bold(`Already paired on ${state.machineName}:`)}`);
+        printPhones(current);
+        console.log(dim(`${UNPAIR_HINT}\nContinuing adds one more phone.`));
+    }
     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 });
@@ -45,6 +61,10 @@ async function pair(state) {
     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`);
+    const all = loadState().devices;
+    console.log(`${bold(`Paired phones (${all.length}):`)}`);
+    printPhones(all);
+    console.log(dim(`${UNPAIR_HINT}\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
@@ -87,37 +107,78 @@ async function serve(state, keepAwake) {
         ['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();
-    }
-    // `agentpager pair` (a SEPARATE process, e.g. re-pairing after a reinstall while this one keeps
-    // running) writes the new device straight to disk. Without this, that pairing succeeds — the phone
-    // gets its "ok" — and then never connects, because this process's channel list was built once at
-    // startup and nothing ever told it a new device exists. The phone just sits on "Connecting…"
-    // forever with no way to know a restart was the missing step. Poll instead of a restart: cheap,
-    // and it means pairing a second (or reinstalled) phone never requires touching this window.
-    setInterval(() => {
-        let onDisk;
-        try {
-            onDisk = loadState();
+    // Persist only what THIS process owns (sequence numbers, push tokens) and merge it into the file
+    // as it is now. Saving our startup snapshot would resurrect a phone that `agentpager unpair`
+    // just removed — a revoked credential coming back to life.
+    const channels = new Map();
+    let dirty = false;
+    const flush = () => {
+        if (!dirty)
+            return;
+        dirty = false;
+        updateState((s) => {
+            for (const d of s.devices) {
+                const live = channels.get(d.id)?.device;
+                if (live)
+                    Object.assign(d, { sendSeq: live.sendSeq, recvSeq: live.recvSeq, pushToken: live.pushToken });
+            }
+        });
+    };
+    let flushTimer;
+    const persist = () => {
+        dirty = true;
+        flushTimer ??= setTimeout(() => {
+            flushTimer = undefined;
+            flush();
+        }, 250);
+    };
+    const connect = (d) => {
+        if (channels.has(d.id))
+            return;
+        const ch = new Channel(d, persist, (msg, c) => hub.handle(msg, c));
+        channels.set(d.id, ch);
+        hub.attach(ch);
+        ch.start();
+    };
+    const disconnect = async (id, told) => {
+        const ch = channels.get(id);
+        if (!ch)
+            return;
+        channels.delete(id);
+        hub.detach(ch);
+        if (told) {
+            ch.send({ type: 'unpaired', machine: state.machineName });
+            await new Promise((r) => setTimeout(r, 1500)); // let the message leave before the channel closes
         }
-        catch {
-            return; // mid-write on another process; try again next tick
+        await ch.stop();
+    };
+    for (const d of state.devices)
+        connect(d);
+    // `agentpager unpair` / `agentpager pair` in ANOTHER terminal edit the file. Without this, an
+    // unpaired phone stayed connected (and showed "online") until this window was restarted, and a
+    // newly paired one got nothing until then too.
+    const watch = setInterval(() => {
+        const now = loadState().devices;
+        for (const id of [...channels.keys()]) {
+            if (!now.some((d) => d.id === id)) {
+                log(`unpaired: ${channels.get(id)?.deviceName}`);
+                void disconnect(id, true);
+            }
         }
-        const known = new Set(state.devices.map((d) => d.id));
-        for (const d of onDisk.devices) {
-            if (known.has(d.id))
-                continue;
-            state.devices.push(d);
-            const c = new Channel(d, persist, (msg, ch) => hub.handle(msg, ch));
-            hub.attach(c);
-            c.start();
-            log(`paired while running: ${d.name}`);
+        for (const d of now) {
+            if (!channels.has(d.id)) {
+                log(`paired while running: ${d.name}`);
+                connect(d);
+            }
         }
-    }, 5000);
+    }, 2000);
+    hub.onUnpair = (ch) => {
+        // The phone forgot us in the app: drop it from disk first, then close the channel.
+        updateState((s) => {
+            s.devices = s.devices.filter((d) => d.id !== ch.device.id);
+        });
+        void disconnect(ch.device.id, false);
+    };
     const stopControl = serveControl((req) => hub.job(req));
     // Detect the ACP agents in the background and announce them as they appear.
     void (async () => {
@@ -136,18 +197,33 @@ async function serve(state, keepAwake) {
         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(`  ${state.devices.length} phone${state.devices.length === 1 ? '' : 's'} paired:`);
+    printPhones(state.devices, '    ');
     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(UNPAIR_HINT));
     console.log(dim('Your sessions stay on this computer; the relay only sees encrypted bytes.\n'));
+    // Tell the terminal AND the phone when a newer AgentPager is out.
+    const checkUpdate = async () => {
+        const latest = await latestVersion();
+        if (latest && isNewer(latest, BRIDGE_VERSION)) {
+            console.log(`\n⬆️  ${bold(`AgentPager ${latest} is available`)} (you have ${BRIDGE_VERSION}). Update: ${bold(UPDATE_COMMAND)}, then restart.\n`);
+            await hub.setLatest(latest);
+        }
+    };
+    void checkUpdate();
+    const updateTimer = setInterval(() => void checkUpdate(), 12 * 3600_000);
     const quit = async () => {
         console.log(dim('\nDisconnecting…'));
         hub.shutdown();
         stopControl();
         codex.shutdown();
-        await Promise.all(channels.map((c) => c.stop()));
+        clearInterval(watch);
+        clearInterval(updateTimer);
+        flush();
+        await Promise.all([...channels.values()].map((c) => c.stop()));
         process.exit(0);
     };
     process.on('SIGINT', quit);
@@ -195,16 +271,36 @@ async function main() {
         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()}`)}`);
+            else {
+                console.log(bold(`${state.devices.length} phone${state.devices.length === 1 ? '' : 's'} paired with ${state.machineName}:`));
+                printPhones(state.devices);
+                console.log(dim(`\n${UNPAIR_HINT}`));
+            }
             process.exit(0);
         case 'unpair': {
-            const before = state.devices.length;
-            const after = updateState((s) => {
-                s.devices = s.devices.filter((d) => d.id !== arg);
+            if (!arg) {
+                console.log('Usage: agentpager unpair <id | name> | --all\n');
+                if (state.devices.length)
+                    printPhones(state.devices, '');
+                else
+                    console.log('No phones are paired.');
+                process.exit(1);
+            }
+            const q = arg.toLowerCase();
+            const hit = (d) => arg === '--all' || d.id === arg || d.name.toLowerCase() === q;
+            const removed = state.devices.filter(hit);
+            if (!removed.length) {
+                console.log(`No phone matches "${arg}". Paired phones:`);
+                printPhones(state.devices, '  ');
+                process.exit(1);
+            }
+            updateState((s) => {
+                s.devices = s.devices.filter((d) => !hit(d));
             });
-            state.devices = after.devices;
-            console.log(before === state.devices.length ? `No phone with id ${arg}.` : 'Removed. That phone can no longer reach this computer.');
+            for (const d of removed)
+                console.log(`Removed ${bold(d.name)}. It can no longer reach this computer.`);
+            const running = await bridgeRunning();
+            console.log(dim(running ? 'The running AgentPager drops it within a couple of seconds and tells the phone.' : 'Nothing is running here, so it is gone for good.'));
             process.exit(0);
         }
         case 'notify':

package/dist/guard/index.js

@@ -204,7 +204,7 @@ function HEADLESS_WAYS_OUT(rule) {
 /**
  * Running from npx's throwaway cache?
  *
- * `npx agentpager` is the right way to try this — it needs no commitment and leaves nothing behind.
+ * `npx @cosmovex/agentpager` is the right way to try this — it needs no commitment and leaves nothing behind.
  * But "leaves nothing behind" is fatal for a hook: the absolute path we register would point into a
  * directory npx is free to delete, and the guard would stop running without ever saying so. Rules
  * need the package to still exist tomorrow.
@@ -217,7 +217,7 @@ export function install() {
         console.log('✖ This copy is running from npx\u2019s temporary cache, which gets deleted.');
         console.log('  A hook pointing there would stop working silently, so it is not written.');
         console.log('  Install it properly first, then rules will stick:');
-        console.log('     npm install -g agentpager');
+        console.log('     npm install -g @cosmovex/agentpager');
         console.log('     agentpager-guard install');
         process.exitCode = 1;
         return;

package/dist/hub.js

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 // 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.
@@ -7,10 +9,21 @@ import { random, b64u } from './crypto.js';
 import { record as recordLimits } from './guard/limits.js';
 import { PROTOCOL } from './protocol.js';
 import { addRoot, allowedCwd, browseFolders, discoverProjects, MAX_PHONE_FILE_BYTES, readFileForPhone, writeUploadedFile } from './projects.js';
+import { isNewer } from './update.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';
+// Read from package.json, never typed twice: this constant sat at 0.1.0 while npm had 0.1.2, and
+// the update check would have told every user, for ever, that the version they run is out of date.
+export const BRIDGE_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
+        return String(pkg.version);
+    }
+    catch {
+        return '0.0.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.
@@ -43,6 +56,21 @@ export class Hub {
     attach(channel) {
         this.channels.push(channel);
     }
+    /** Stop talking to a phone. Anything it still has pending stays pending; it can no longer answer. */
+    detach(channel) {
+        this.channels = this.channels.filter((c) => c !== channel);
+    }
+    /** Called with the phone that asked to be unpaired; the CLI owns the state file. */
+    onUnpair;
+    /** Newest version on npm, once known. Sent with every hello so the phone can say "update". */
+    latest;
+    async setLatest(v) {
+        if (!v || v === this.latest)
+            return;
+        this.latest = v;
+        for (const c of this.channels)
+            await this.hello(c);
+    }
     /** Agents detected after startup (probing them must never delay the relay). */
     async addAgent(agent) {
         this.agents.set(agent.id, agent);
@@ -69,6 +97,9 @@ export class Hub {
             switch (msg.type) {
                 case 'hello':
                     return await this.hello(from);
+                case 'unpair':
+                    this.log(`${from.deviceName} unpaired itself from the app`);
+                    return this.onUnpair?.(from);
                 case 'list':
                     return from.send({ type: 'sessions', items: await this.list() });
                 case 'open':
@@ -263,6 +294,7 @@ export class Hub {
             protocol: PROTOCOL,
             agents: await this.statuses(),
             projects: await this.offerProjects(),
+            ...(this.latest && isNewer(this.latest, BRIDGE_VERSION) ? { latest: this.latest } : {}),
         });
         // A phone that reconnects must see every approval still waiting — never miss one.
         for (const live of this.live.values()) {

package/dist/service.js

@@ -16,14 +16,14 @@ function run(cmd, args) {
 /** 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');
+        throw new Error('Install it permanently first:  npm install -g @cosmovex/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');
+            'Install it on the internal disk instead:  npm install -g @cosmovex/agentpager   then:  agentpager service install');
     }
 }
 export function installService() {

package/dist/update.js

@@ -0,0 +1,52 @@
+// Is there a newer AgentPager on npm? The phone can only say "update" if the computer knows.
+// One small GET, cached on disk for 12 hours, and every failure means "no news" — an update
+// check must never be able to slow down or break a bridge that is otherwise working.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateDir } from './store.js';
+const REGISTRY = 'https://registry.npmjs.org/@cosmovex%2Fagentpager/latest';
+const CACHE_MS = 12 * 3600_000;
+const cacheFile = () => join(stateDir, 'update.json');
+/** True when `latest` is a strictly newer x.y.z than `current`. Pre-release tags are ignored. */
+export function isNewer(latest, current) {
+    const parse = (v) => v.split('-')[0].split('.').map((n) => parseInt(n, 10) || 0);
+    const a = parse(latest);
+    const b = parse(current);
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    }
+    return false;
+}
+/** The newest published version, or undefined when we cannot tell. */
+export async function latestVersion(fetchImpl = fetch) {
+    try {
+        if (existsSync(cacheFile())) {
+            const c = JSON.parse(readFileSync(cacheFile(), 'utf8'));
+            if (Date.now() - c.at < CACHE_MS && c.latest)
+                return c.latest;
+        }
+    }
+    catch {
+        /* unreadable cache: ask again */
+    }
+    try {
+        const res = await fetchImpl(REGISTRY, { signal: AbortSignal.timeout(5000) });
+        if (!res.ok)
+            return undefined; // 404 until the first publish
+        const latest = String((await res.json()).version ?? '');
+        if (!/^\d+\.\d+\.\d+/.test(latest))
+            return undefined;
+        try {
+            writeFileSync(cacheFile(), JSON.stringify({ at: Date.now(), latest }));
+        }
+        catch {
+            /* read-only home: fine, we just ask again next time */
+        }
+        return latest;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const UPDATE_COMMAND = 'npm install -g @cosmovex/agentpager@latest';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cosmovex/agentpager",
-  "version": "0.1.2",
-  "description": "Pager for your AI coding agents \u2014 approve, reply and hear results on your phone. End-to-end encrypted.",
+  "version": "0.1.3",
+  "description": "Pager for your AI coding agents — 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)\"",