@cosmovex/agentpager 0.1.1 → 0.1.3

package/dist/agents/claude.js

@@ -7,6 +7,40 @@ import { findTranscript, spendOf } from '../guard/spend.js';
 import { classify, describe } from '../risk.js';
 import { SHELL, clip, withDeadline } from './types.js';
 const run = promisify(execFile);
+/**
+ * Claude's own multi-question tool (up to 4 questions, single- or multi-select each), driven
+ * headlessly: there is no terminal here to prompt, so `canUseTool`'s `updatedInput` — whatever
+ * effect it has on this ONE tool's own execution — is unverified territory. `deny` + a message the
+ * model reads as data is not a guess: it is the exact mechanism every OTHER denial in this file
+ * already relies on, so the model already knows to treat it as an answer, not a rejection.
+ */
+export async function askUserQuestion(sink, input) {
+    const raw = Array.isArray(input.questions) ? (input.questions) : [];
+    const questions = raw.slice(0, 4).map((q) => {
+        const qq = q;
+        const opts = Array.isArray(qq.options) ? qq.options : [];
+        return {
+            question: String(qq.question ?? '').slice(0, 300),
+            header: String(qq.header ?? '').slice(0, 20),
+            multiSelect: qq.multiSelect === true,
+            options: opts.slice(0, 4).map((o) => {
+                const oo = o;
+                return { label: String(oo.label ?? '').slice(0, 80), description: oo.description ? String(oo.description).slice(0, 300) : undefined };
+            }),
+        };
+    });
+    if (!questions.length)
+        return { behavior: 'deny', message: 'No questions were readable.' };
+    const summary = questions.length === 1 ? questions[0].question : `${questions.length} questions for you`;
+    const answer = await sink.ask({ tool: 'AskUserQuestion', summary, detail: '', risk: 'low', questions });
+    if (answer.decision === 'deny' || !answer.answers) {
+        return { behavior: 'deny', message: answer.message || 'The user closed this without answering.' };
+    }
+    const said = Object.entries(answer.answers)
+        .map(([q, a]) => `${q} ${a}`)
+        .join('\n');
+    return { behavior: 'deny', message: `The user answered:\n${said}` };
+}
 /** An async queue the SDK reads prompts from, so one live query takes many turns. */
 class PromptQueue {
     items = [];
@@ -187,6 +221,8 @@ export class ClaudeAgent {
                 promptSuggestions: true,
                 systemPrompt: { type: 'preset', preset: 'claude_code' },
                 canUseTool: async (tool, input, opts) => {
+                    if (tool === 'AskUserQuestion')
+                        return askUserQuestion(sink, input);
                     const { summary, detail } = describe(tool, input);
                     const answer = await sink.ask({ tool, summary, detail, risk: classify(tool, input) });
                     if (answer.decision === 'deny') {
@@ -232,6 +268,18 @@ export class ClaudeAgent {
                     else if (msg.type === 'system' && msg.subtype === 'session_state_changed') {
                         sink.state(msg.state === 'requires_action' ? 'needs_you' : msg.state === 'running' ? 'running' : 'idle');
                     }
+                    else if (msg.type === 'system' && msg.subtype === 'compact_boundary') {
+                        // The SDK auto-summarizes older turns to keep going near the context limit — silently,
+                        // until now. "I lose context when I come back" (Sumanth's survey, 2026-09-28) is partly
+                        // THIS: the agent's own memory of earlier turns just became a summary, and nothing said
+                        // so. pre/post_tokens are on the message itself; no hook needed for that much.
+                        const meta = msg.compact_metadata ?? {};
+                        const auto = meta.trigger !== 'manual';
+                        const pre = typeof meta.pre_tokens === 'number' ? meta.pre_tokens : null;
+                        const post = typeof meta.post_tokens === 'number' ? meta.post_tokens : null;
+                        const shrink = pre != null && post != null ? ` (${pre.toLocaleString()} → ${post.toLocaleString()} tokens)` : '';
+                        sink.tool('Context', `${auto ? 'Auto-compacted' : 'Compacted'} — older turns summarized to keep working${shrink}.`);
+                    }
                     else if (msg.type === 'prompt_suggestion' || msg.subtype === 'prompt_suggestion') {
                         const t = String(msg.suggestion ?? msg.text ?? msg.prompt ?? '').trim();
                         if (t)
@@ -264,8 +312,10 @@ export class ClaudeAgent {
                         }
                         if (Array.isArray(content)) {
                             for (const b of content) {
-                                if (b?.type === 'tool_use')
-                                    sink.tool(b.name, describe(b.name, b.input ?? {}).detail);
+                                if (b?.type === 'tool_use') {
+                                    const d = describe(b.name, b.input ?? {});
+                                    sink.tool(b.name, d.detail, d.path);
+                                }
                             }
                         }
                     }

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.
@@ -6,11 +8,22 @@ 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 { 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.
@@ -22,6 +35,11 @@ export class Hub {
     channels = [];
     live = new Map();
     known = new Map(); // last list, for cwd lookups
+    // In-flight uploads FROM the phone, keyed by reqId — the mirror of `sendFile`'s chunking, going
+    // the other way. Cleared on completion or error; a reqId that never completes just ages out with
+    // the process (no size cap consequence: file_put_start's own `size` already came from
+    // MAX_PHONE_FILE_BYTES-checked FilePicker output on the phone, not from anything the bridge trusts blindly here — see receiveUploadChunk).
+    uploads = new Map();
     projects = new Set();
     discovered; // git repos on this computer; scanned once, on the first hello
     projectCache;
@@ -38,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);
@@ -64,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':
@@ -87,6 +123,15 @@ export class Hub {
                 }
                 case 'browse':
                     return from.send({ type: 'folders', ...browseFolders(msg.path) });
+                case 'file_get':
+                    return this.sendFile(msg.reqId, msg.path, from);
+                case 'file_put_start':
+                    // `.fill(undefined)`, not a bare `new Array(n)`: a sparse array's holes are invisible to
+                    // `.some()`/`.reduce()` below, so a 2-chunk upload looked "complete" after just chunk 0.
+                    this.uploads.set(msg.reqId, { sid: msg.sid, name: msg.name, size: msg.size, chunks: msg.chunks, received: new Array(msg.chunks).fill(undefined) });
+                    return;
+                case 'file_put_chunk':
+                    return this.receiveUploadChunk(msg.reqId, msg.index, msg.data, from);
                 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.
@@ -114,7 +159,7 @@ export class Hub {
                         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 });
+                    ask.resolve({ decision: msg.decision, message: msg.message, answers: msg.answers });
                     this.broadcast({ type: 'asked', sid: msg.sid, reqId: msg.reqId });
                     this.setState(live, live.asks.size ? 'needs_you' : 'running');
                     return;
@@ -249,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()) {
@@ -360,6 +406,63 @@ export class Hub {
             clearTimeout(timer);
         return result;
     }
+    /**
+     * "Claude made a PDF, how do I read it" — one named file, base64-chunked over the same small
+     * encrypted channel everything else uses (the relay's own rules cap one message's ciphertext at
+     * 24,000 chars; 10,000 raw bytes per chunk leaves room for the base64 + encryption overhead on
+     * top of that, twice — once for the chunk data, once for the envelope). Fire-and-forget: the
+     * phone reassembles by `index`, and a chunk arriving out of order costs nothing to wait for.
+     */
+    sendFile(reqId, path, from) {
+        const CHUNK_BYTES = 10_000;
+        const file = readFileForPhone(path);
+        if (!file.ok) {
+            from.send({ type: 'file_error', reqId, message: file.message });
+            return;
+        }
+        const chunks = Math.max(1, Math.ceil(file.bytes.length / CHUNK_BYTES));
+        from.send({ type: 'file_start', reqId, name: file.name, mime: file.mime, size: file.bytes.length, chunks });
+        for (let i = 0; i < chunks; i++) {
+            const slice = file.bytes.subarray(i * CHUNK_BYTES, (i + 1) * CHUNK_BYTES);
+            from.send({ type: 'file_chunk', reqId, index: i, data: slice.toString('base64') });
+        }
+        this.log(`sent ${file.name} (${(file.bytes.length / 1024).toFixed(0)} KB, ${chunks} chunk${chunks === 1 ? '' : 's'})`);
+    }
+    /** One chunk of a phone upload. Never trusts the phone's own claimed `size` for enforcement —
+     * counts real received bytes against the same cap `readFileForPhone` uses the other way. */
+    receiveUploadChunk(reqId, index, data, from) {
+        const up = this.uploads.get(reqId);
+        if (!up || index < 0 || index >= up.chunks)
+            return; // unknown or stale transfer: say nothing, ask nothing
+        up.received[index] = Buffer.from(data, 'base64');
+        const soFar = up.received.reduce((n, b) => n + (b?.length ?? 0), 0);
+        if (soFar > MAX_PHONE_FILE_BYTES) {
+            this.uploads.delete(reqId);
+            from.send({ type: 'file_put_error', reqId, message: 'That file is too big to send this way.' });
+            return;
+        }
+        if (up.received.some((b) => !b))
+            return; // still waiting on other chunks
+        this.uploads.delete(reqId);
+        const cwd = this.known.get(up.sid)?.cwd;
+        if (!cwd) {
+            from.send({ type: 'file_put_error', reqId, message: 'That session is not open on this computer right now.' });
+            return;
+        }
+        const bytes = Buffer.concat(up.received);
+        const result = writeUploadedFile(cwd, up.name, bytes);
+        if (!result.ok) {
+            from.send({ type: 'file_put_error', reqId, message: result.message });
+            return;
+        }
+        this.log(`received ${up.name} from the phone (${(bytes.length / 1024).toFixed(0)} KB) → ${result.path}`);
+        from.send({ type: 'file_put_done', reqId, sid: up.sid, path: result.path });
+        // Tell the agent, if one is actually running here — a file sitting on disk it was never told
+        // about is indistinguishable from a file that does not exist.
+        const live = this.live.get(up.sid);
+        if (live?.session)
+            void live.session.send(`[The user sent a file from their phone: ${result.path}]`);
+    }
     /** Take a pending request off the phone and say why it is gone. */
     withdraw(live, reqId, reason) {
         const ask = live.asks.get(reqId);
@@ -488,9 +591,9 @@ export class Hub {
                 if (!live.flush)
                     live.flush = setTimeout(() => this.flush(live), FLUSH_MS);
             },
-            tool: (tool, detail) => {
+            tool: (tool, detail, path) => {
                 this.flush(live);
-                this.broadcast({ type: 'tool', sid: live.sid, tool, detail: detail.slice(0, 300) }, true);
+                this.broadcast({ type: 'tool', sid: live.sid, tool, detail: detail.slice(0, 300), path }, true);
             },
             state: (state) => this.setState(live, state),
             limits: (l) => {

package/dist/projects.js

@@ -12,9 +12,9 @@
 // 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 { mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, resolve, sep } from 'node:path';
+import { extname, 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".
@@ -127,6 +127,24 @@ export function allowedCwd(p, known = []) {
         .split(sep)
         .some((part) => part && (hidden(part) || SKIP.has(part)));
 }
+/**
+ * A file the phone may read (not browse — a specific path, e.g. one it just watched an agent
+ * write): not a directory, and its own folder inside the same roots and hidden/SKIP rules as
+ * `allowedCwd`. One promise, checked one way, so the two can never quietly drift apart.
+ */
+export function allowedFile(p) {
+    const full = real(resolve(p));
+    if (!full)
+        return false;
+    try {
+        if (!statSync(full).isFile())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return allowedCwd(resolve(full, '..'));
+}
 /** Git repositories in your roots, most recently touched first. */
 export function discoverProjects() {
     const found = [];
@@ -193,3 +211,80 @@ export function browseFolders(path) {
     return { path: at, parent: atRoot ? (all.length > 1 ? '' : undefined) : resolve(at, '..'), dirs };
 }
 export const homeFolder = () => HOME;
+/** "Claude made a PDF, how do I read it" (real request, 2026-09-29) — not a file browser, one
+ * named file at a time, and never bigger than what the relay's small encrypted messages can carry
+ * chunked. Bump this only alongside the chunk math in hub.ts; they are the same promise. */
+export const MAX_PHONE_FILE_BYTES = 4 * 1024 * 1024;
+const MIME_BY_EXT = {
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.md': 'text/markdown',
+    '.txt': 'text/plain',
+    '.json': 'application/json',
+    '.csv': 'text/csv',
+    '.html': 'text/html',
+    '.svg': 'image/svg+xml',
+};
+/** The file behind a "get this file" tap. Never anything `allowedFile` refuses — checked the same
+ * way as every other path this bridge reads, not a second guess at the rule. */
+export function readFileForPhone(p) {
+    if (!allowedFile(p)) {
+        return { ok: false, reason: 'not_allowed', message: "That file is outside what this computer lets the phone reach." };
+    }
+    const full = real(resolve(p));
+    let bytes;
+    try {
+        bytes = readFileSync(full);
+    }
+    catch {
+        return { ok: false, reason: 'unreadable', message: 'Could not read that file.' };
+    }
+    if (bytes.length > MAX_PHONE_FILE_BYTES) {
+        const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+        return {
+            ok: false,
+            reason: 'too_big',
+            message: `That file is ${mb(bytes.length)} MB — too big to send this way (limit ${mb(MAX_PHONE_FILE_BYTES)} MB).`,
+        };
+    }
+    const ext = extname(full).toLowerCase();
+    return { ok: true, name: full.split(sep).pop() || full, mime: MIME_BY_EXT[ext] ?? 'application/octet-stream', bytes };
+}
+/**
+ * The other direction: a file the phone picked, landed where the agent can actually find it.
+ * `cwd` is the session's own folder — never chosen by the phone — so this can only ever write
+ * inside a folder that folder's own session already had. `name` is untrusted input from the phone;
+ * `basename()`-only strips any `../` before it ever touches a path.
+ */
+export function writeUploadedFile(cwd, name, bytes) {
+    const full = real(cwd);
+    if (!full || !isDir(full))
+        return { ok: false, message: 'That session has no folder to put a file into.' };
+    const safeName = (name.split(/[\\/]/).pop() || 'file').replace(/^\.+/, '') || 'file';
+    const dir = join(full, '.agentpager-uploads');
+    try {
+        mkdirSync(dir, { recursive: true });
+        // Never silently overwrite: two screenshots named the same thing an hour apart are both real.
+        let path = join(dir, safeName);
+        if (entries(dir).includes(safeName) || (() => { try {
+            statSync(path);
+            return true;
+        }
+        catch {
+            return false;
+        } })()) {
+            const dot = safeName.lastIndexOf('.');
+            const stamp = Date.now();
+            path = join(dir, dot > 0 ? `${safeName.slice(0, dot)}-${stamp}${safeName.slice(dot)}` : `${safeName}-${stamp}`);
+        }
+        writeFileSync(path, bytes);
+        return { ok: true, path };
+    }
+    catch (e) {
+        return { ok: false, message: `Could not save that file: ${String(e?.message ?? e)}` };
+    }
+}

package/dist/risk.js

@@ -68,6 +68,9 @@ export function describe(tool, input) {
                 // What the edit actually changes, not just which file it lands in. Approving a change you
                 // cannot see is a tap, not a decision.
                 detail: clip(String(input.detail ?? '') || diffOf(input) || path, 2000),
+                // "Claude made a PDF, how do I read it" — a real path, not re-parsed out of `detail` later,
+                // is what lets the phone offer "Get file" on the row that actually produced one.
+                path: path || undefined,
             };
         }
         case 'Write': {
@@ -78,6 +81,7 @@ export function describe(tool, input) {
                 // The path alone was the whole detail here, so the card named a file and showed nothing of
                 // what was going into it.
                 detail: clip(body ? `${path}\n\n${body}` : path, 2000),
+                path: path || undefined,
             };
         }
         case 'WebFetch':

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.1",
-  "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)\"",