secure-agents 0.0.0-stage → 0.7.0

package/dist/link.js

@@ -0,0 +1,964 @@
+// The daemon's rules: who may pair, what reaches the agent, and what needs a human's yes before it leaves this computer.
+import { spawnSync } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Brain, search } from './brain.js';
+import { file, readJson, writeJson } from './config.js';
+import { checkFile, checkOwnFile, hashFile } from './guard.js';
+import { loadOrCreateIdentity, safetyNumber, sign, verify } from './identity.js';
+import { decodeInvite, encodeInvite, newSecret, sameSecret } from './invite.js';
+import { Net } from './net.js';
+import { clean, desktopNotify, Notifier } from './notify.js';
+import { mb } from './guard.js';
+import { blockSecrets, secretsIn, steeringIn, warningsIn } from './scan.js';
+import { CHUNK_BYTES } from './protocol.js';
+import { audit, newId, Store } from './store.js';
+import { describeWake, readLog, readWake, saveWake, Waker } from './waker.js';
+import { checkUpdate, installVersion, RUNNING_VERSION, runningAs } from './update.js';
+const INVITE_HOURS = 24;
+const LABEL = { pair: 'pairing', ask: 'question', reply: 'answer', file_request: 'file request', file: 'file', task: 'task', task_update: 'task result', brain_query: 'brain search', brain_result: 'brain results', task_reply: 'answer to task question', notice: 'notice' };
+const receiptPayload = (task, state, note, artifacts, at) => JSON.stringify({ task, state, note, artifacts, at });
+const isMac = process.platform === 'darwin', isWin = process.platform === 'win32';
+export class Link extends EventEmitter {
+    settings;
+    store;
+    brain = new Brain();
+    keys = loadOrCreateIdentity();
+    me = this.keys.publicKey.toString('hex');
+    net;
+    waker;
+    incoming = new Map();
+    streaming = new Set();
+    rate = new Map();
+    sweeper = null;
+    updater = null;
+    update = null;
+    lastUpdateCheck = 0;
+    notifier;
+    alerted = new Set();
+    constructor(settings) {
+        super();
+        this.settings = settings;
+        this.store = new Store(settings.limits.maxItems);
+        this.waker = new Waker(readWake(), (it) => this.access(it.peer), (it) => this.reported(it), (it, slice, session) => {
+            const cur = this.store.item(it.id);
+            if (cur)
+                this.store.setStatus(cur.id, cur.status, undefined, { agentLog: [...(cur.data?.agentLog ?? []), slice] });
+            const t = this.store.item(it.kind === 'task' ? it.id : String(it.data?.thread ?? ''));
+            if (session && t?.kind === 'task')
+                this.store.setStatus(t.id, t.status, undefined, { session });
+        }, () => this.settings.limits.wakeMinutes);
+        this.net = new Net(this.keys, (pk) => this.mayConnect(pk), { relay: settings.relay, mustDial: (pk) => this.store.joins.some((j) => j.publicKey === pk && j.approved) });
+        this.net.on('message', (peer, msg) => this.onMessage(peer, msg));
+        this.net.on('online', (peer) => this.onOnline(peer));
+        this.net.on('offline', (peer) => this.dropIncoming(peer));
+        this.notifier = new Notifier(() => this.settings.notify, settings.limits.notifyGroupSeconds, settings.port, (id) => this.store.item(id)?.status === 'awaiting_human');
+    }
+    async start() {
+        this.expireWaiting();
+        this.sweeper = setInterval(() => this.expireWaiting(), 60_000);
+        this.sweeper.unref();
+        void this.lookForUpdate();
+        this.updater = setInterval(() => void this.lookForUpdate(), this.settings.limits.updateCheckHours * 3600_000);
+        this.updater.unref();
+        await this.net.start([...this.store.peers.map((p) => p.publicKey), ...this.store.joins.map((j) => j.publicKey)]);
+    }
+    stop() { if (this.sweeper)
+        clearInterval(this.sweeper); if (this.updater)
+        clearInterval(this.updater); return this.net.stop(); }
+    /** Only the pinned app copy updates itself; a source folder updates with git pull. */
+    async lookForUpdate() {
+        if (runningAs() !== 'app')
+            return null;
+        this.lastUpdateCheck = Date.now();
+        this.update = await checkUpdate();
+        if (this.update)
+            audit('update_available', { ...this.update });
+        return this.update;
+    }
+    /** The page asks on every refresh; this looks on npm at most once per updateCheckOnOpenMinutes. */
+    lookForUpdateSoon() {
+        if (Date.now() - this.lastUpdateCheck > this.settings.limits.updateCheckOnOpenMinutes * 60_000)
+            void this.lookForUpdate();
+    }
+    /** Called only through a passkey-approved action on the page. */
+    installUpdate(version) {
+        if (runningAs() !== 'app')
+            throw new Error('This Secure runs from a source folder: update it with git pull and npm run build.');
+        if (!this.update || this.update.latest !== version)
+            throw new Error('That version is not the update on offer. Reload the page.');
+        installVersion(version);
+        audit('update_installed', { from: this.update.current, to: version });
+        this.update = null;
+        setTimeout(() => this.emit('restart'), 300);
+        return { installed: version, restarting: true, next: 'Secure is restarting with the new version in the same window. This page reconnects by itself.' };
+    }
+    /** Declines anything that waited for the person longer than the limit, so old requests don't pile up. */
+    expireWaiting() {
+        const cutoff = Date.now() - this.settings.limits.pendingHours * 3600_000;
+        for (const it of this.pending().filter((i) => Date.parse(i.createdAt) < cutoff)) {
+            this.deny(it.id);
+            this.store.setStatus(it.id, 'denied', `Expired: nobody approved it within ${this.settings.limits.pendingHours} hours.`);
+            audit('expired', { id: it.id, kind: it.kind, direction: it.direction, peer: it.peer });
+        }
+    }
+    status() {
+        return {
+            name: this.settings.name,
+            publicKey: this.me,
+            version: RUNNING_VERSION,
+            update_available: this.update ? { ...this.update, how: 'Your user installs it on the Secure page (it needs their passkey), then restarts the Secure window.' } : null,
+            relay: this.settings.relay ? `${this.settings.relay.slice(0, 16)}… (peers can't see this computer's IP)` : 'none: direct connection, paired peers can see this computer\'s IP',
+            wake: describeWake(readWake()),
+            peers: this.store.peers.map((p) => ({ name: p.name, publicKey: p.publicKey, online: this.net.isOnline(p.publicKey), permissions: p.permissions, shared: p.shared, reach: p.reach, tools: p.tools, fileLimit: this.fileLimitWith(p), pairedAt: p.pairedAt, brainCopy: this.brain.copyOf(p.publicKey)?.syncedAt ?? null })),
+            pendingApprovals: this.pending().length,
+            decisions: this.brain.mine.length,
+        };
+    }
+    // ── pairing ──────────────────────────────────────────────────────────────
+    createInvite() {
+        this.store.pruneInvites();
+        const secret = newSecret();
+        const expiresAt = new Date(Date.now() + INVITE_HOURS * 3600_000).toISOString();
+        this.store.invites.push({ secret, createdAt: new Date().toISOString(), expiresAt });
+        this.store.save();
+        audit('invite_created', { expiresAt });
+        return { code: encodeInvite(this.me, secret, this.settings.relay), expiresAt };
+    }
+    join(code) {
+        const { publicKey, secret, relay } = decodeInvite(code);
+        if (relay !== this.settings.relay)
+            throw new Error(relay
+                ? `This invite connects through relay ${relay}. Ask your user to run "secure use-relay ${relay}" and restart the daemon, then join again.`
+                : 'This invite is for a direct connection, but this computer uses a relay. Both computers must use the same relay (or both none).');
+        if (publicKey === this.me)
+            throw new Error('That invite was created on this computer. Use it on the other one.');
+        if (this.store.peer(publicKey))
+            throw new Error('You are already paired with that agent.');
+        this.store.joins = this.store.joins.filter((j) => j.publicKey !== publicKey);
+        this.store.joins.push({ publicKey, secret, createdAt: new Date().toISOString(), approved: false });
+        const number = safetyNumber(this.me, publicKey);
+        const it = this.store.addItem({ id: newId(), kind: 'pair', direction: 'out', peer: publicKey, peerName: 'invite from another computer', text: `Safety number ${number}`, status: 'awaiting_human' });
+        audit('join_started', { id: it.id, peer: publicKey });
+        this.changed(it);
+        return { peer: publicKey, safetyNumber: number, status: 'Waiting for your user to approve joining on the Secure page, then for the other person to approve.' };
+    }
+    unpair(name) {
+        const p = this.requirePeer(name);
+        this.store.removePeer(p.publicKey);
+        this.brain.dropCopy(p.publicKey);
+        this.net.forget(p.publicKey);
+        audit('unpaired', { peer: p.publicKey, name: p.name });
+    }
+    setWake(w) {
+        saveWake(w);
+        this.waker.set(w);
+        audit('wake_changed', { preset: w?.preset ?? null });
+        return describeWake(w);
+    }
+    setRule(name, key, rule) {
+        const p = this.requirePeer(name);
+        if (key === 'tasks' && rule === 'auto')
+            throw new Error('Tasks can change files, so they always wait for your review. Choose "Ask me" or "Never".');
+        p.permissions[key] = rule;
+        this.store.save();
+        audit('rule_changed', { peer: p.publicKey, key, rule });
+        if (key === 'brain')
+            this.syncBrain(p.publicKey);
+    }
+    /** How far my agent may reach for this peer: the shared folders or the whole computer, and file reading only or all its tools. */
+    setAccess(name, reach, tools) {
+        const p = this.requirePeer(name);
+        p.reach = reach;
+        p.tools = tools;
+        this.store.save();
+        audit('access_changed', { peer: p.publicKey, reach, tools });
+        return { reach, tools };
+    }
+    /** What my agent may read and use when it works for this peer. */
+    access(peer) {
+        const p = this.store.peer(peer);
+        return { reach: p?.reach ?? 'folders', tools: p?.tools ?? 'files', folders: p?.shared ?? [] };
+    }
+    /** Where files for this peer may come from. */
+    fileRoots(p) { return p.reach === 'computer' ? [...new Set([os.homedir(), ...p.shared])] : p.shared; }
+    /** Everything sent and received, newest first, optionally for one peer. */
+    history(peer = '') {
+        const p = peer ? this.store.peerByName(peer) : undefined;
+        return this.store.items.filter((i) => !p || i.peer === p.publicKey).slice(-500).reverse()
+            .map((i) => ({ ...i, data: i.data ? { ...i.data, heldAt: undefined, agentLog: undefined } : i.data, hasLog: Array.isArray(i.data?.agentLog) && i.data.agentLog.length > 0 }));
+    }
+    /** What my agent printed while it checked or worked on this item. */
+    agentLog(id) {
+        const it = this.store.item(id);
+        const slices = it?.data?.agentLog ?? [];
+        if (!slices.length)
+            return 'Your agent was not woken for this.';
+        try {
+            return slices.map((s) => readLog(s, this.settings.limits.historyLogBytes)).join('\n');
+        }
+        catch {
+            return 'The log for this was removed.';
+        }
+    }
+    shareFolder(name, folder, remove = false) {
+        const p = this.requirePeer(name);
+        const abs = path.resolve(folder);
+        if (!remove && !fs.statSync(abs).isDirectory())
+            throw new Error('That is not a folder.');
+        p.shared = remove ? p.shared.filter((f) => f !== abs) : [...new Set([...p.shared, abs])];
+        this.store.save();
+        audit(remove ? 'folder_unshared' : 'folder_shared', { peer: p.publicKey, folder: abs });
+        return p.shared;
+    }
+    // ── questions and replies ────────────────────────────────────────────────
+    /** A question; with thread, a follow-up about a task that computer did for me, answered in the same agent session. */
+    ask(peerName, text, thread) {
+        if (thread) {
+            const t = this.store.item(thread);
+            if (!t || t.kind !== 'task' || t.direction !== 'out')
+                throw new Error('about_task must be the id of a task you sent.');
+        }
+        return this.outgoing(peerName, 'ask', text, thread ? { data: { thread } } : {});
+    }
+    /** Answers the question a task's agent asked while working; its session carries on with the answer. */
+    replyToTask(id, text) {
+        const t = this.store.item(id);
+        if (!t || t.kind !== 'task' || t.direction !== 'out')
+            throw new Error('There is no task you sent with that id.');
+        if (t.data?.state !== 'waiting')
+            throw new Error('That task is not waiting for an answer.');
+        const r = this.outgoing(t.peer, 'task_reply', text, { inReplyTo: t.id });
+        this.store.setStatus(t.id, t.status, undefined, { state: 'running' });
+        return r;
+    }
+    /** Whether my agent answered or reported on this, after it was woken for it. */
+    reported(it) {
+        if (it.kind !== 'task_reply')
+            return this.store.items.some((i) => i.direction === 'out' && i.inReplyTo === it.id);
+        return this.store.items.some((i) => i.direction === 'out' && i.kind === 'task_update' && i.inReplyTo === it.inReplyTo && i.createdAt >= it.createdAt);
+    }
+    // ── file size limit ──────────────────────────────────────────────────────
+    /** The largest file this computer sends or accepts; paired computers are told, since a transfer works only up to the smaller limit. */
+    setFileLimit(mbs) {
+        if (!Number.isInteger(mbs) || mbs < 1 || mbs > this.settings.limits.fileLimitMaxMB)
+            throw new Error(`Choose a whole number of MB from 1 to ${this.settings.limits.fileLimitMaxMB}.`);
+        const bytes = mbs * 1048576;
+        writeJson('settings.json', { ...readJson('settings.json', {}), maxFileBytes: bytes });
+        this.settings.maxFileBytes = bytes;
+        audit('file_limit_changed', { maxFileBytes: bytes });
+        for (const p of this.store.peers)
+            if (this.net.isOnline(p.publicKey))
+                this.net.send(p.publicKey, { type: 'limits', maxFileBytes: bytes });
+        return { maxFileBytes: bytes };
+    }
+    /** What can move between me and this computer: the smaller of the two limits. */
+    fileLimitWith(p) {
+        const theirs = p.theirMaxFileBytes ?? null, mine = this.settings.maxFileBytes;
+        return { mine, theirs, between: theirs === null ? mine : Math.min(mine, theirs), setBy: theirs !== null && theirs < mine ? p.name : 'this computer' };
+    }
+    notices() { return this.store.items.filter((i) => i.kind === 'notice' && !i.data?.dismissed).slice(-20); }
+    dismiss(id) {
+        const it = this.store.item(id);
+        if (!it || it.kind !== 'notice')
+            throw new Error('No notice with that id.');
+        return this.store.setStatus(id, it.status, undefined, { dismissed: true });
+    }
+    wakeInternet() { return this.waker.current?.internet === true; }
+    wakeCommands() { return !!this.waker.current && (this.waker.current.allowCommands ?? false); }
+    reply(id, text, sources = []) {
+        const q = this.requireInbox(id, 'ask');
+        const r = this.outgoing(q.peer, 'reply', text, { inReplyTo: q.id, data: { sources } });
+        this.store.setStatus(q.id, 'answered');
+        return r;
+    }
+    /** Questions, approved tasks and received files my agent can act on now; questions carry related decisions from my brain. */
+    inbox() {
+        const open = this.store.items.filter((i) => i.direction === 'in' && i.status === 'delivered' && (i.kind === 'ask' || i.kind === 'task' || i.kind === 'task_reply' || i.kind === 'file'));
+        return open.map((i) => i.kind === 'ask' ? { ...i, related: search(this.brain.mine, i.text, 3) } : i);
+    }
+    /** Waits until something I sent is resolved: an answer, a file, a finished task, brain results, or a refusal. */
+    waitFor(id, timeoutMs) {
+        const mine = this.store.item(id);
+        if (!mine || mine.direction !== 'out')
+            return Promise.reject(new Error('Nothing sent from here with that id.'));
+        const held = () => this.store.items.some((i) => i.direction === 'in' && i.inReplyTo === id && i.status === 'awaiting_human');
+        const result = () => {
+            const r = this.store.items.filter((i) => i.direction === 'in' && i.inReplyTo === id && i.status !== 'awaiting_human' && i.status !== 'denied');
+            if (mine.kind === 'task')
+                return r.filter((i) => i.kind === 'task_update' && ['done', 'failed', ...(this.store.item(id)?.data?.state === 'waiting' ? ['waiting'] : [])].includes(String(i.data?.state))).at(-1) ?? null;
+            if (mine.kind === 'file_request')
+                return r.find((i) => i.kind === 'file' && i.status === 'delivered') ?? null;
+            return r.at(-1) ?? null;
+        };
+        const settled = () => { const m = this.store.item(id); return result() ?? (m.status === 'failed' || m.status === 'denied' ? null : undefined); };
+        const now = settled();
+        if (now !== undefined || timeoutMs <= 0)
+            return Promise.resolve({ item: this.store.item(id), result: now ?? null, held: held() });
+        return new Promise((resolve) => {
+            const done = () => { clearTimeout(t); this.off('item', on); resolve({ item: this.store.item(id), result: settled() ?? null, held: held() }); };
+            const t = setTimeout(done, timeoutMs);
+            const heldThere = () => this.store.item(id)?.data?.remote === 'held' && mine.data?.remote !== 'held';
+            const on = () => { if (settled() !== undefined || heldThere())
+                done(); };
+            this.on('item', on);
+        });
+    }
+    // ── files ────────────────────────────────────────────────────────────────
+    requestFile(peerName, filePath, reason) {
+        return this.outgoing(peerName, 'file_request', `${filePath}${reason ? ` (${reason})` : ''}`, { data: { path: filePath, reason } });
+    }
+    offerFile(peerName, filePath, note) {
+        const p = this.requirePeer(peerName);
+        if (p.permissions.files === 'never')
+            throw new Error(`Sending files to ${p.name} is turned off on this computer.`);
+        const c = checkOwnFile(filePath, this.settings.maxFileBytes);
+        if (!c.ok)
+            throw new Error(c.reason);
+        const lim = this.fileLimitWith(p);
+        if (c.bytes > lim.between)
+            throw new Error(`That file is ${mb(c.bytes)}; files between you and ${p.name} can be at most ${mb(lim.between)} (set by ${lim.setBy}). Ask the person there to raise "Largest file" in Secure's Settings.`);
+        return this.addOutgoingFile(p, c.abs, c.bytes, c.sha256, note, undefined, c.flags);
+    }
+    received() { return this.store.items.filter((i) => i.kind === 'file' && i.direction === 'in' && i.status !== 'awaiting_human'); }
+    /** A secret-looking file always waits for the person, even when files are Automatic. */
+    addOutgoingFile(p, abs, bytes, sha256, note, requestId, warnings = []) {
+        const it = this.store.addItem({ id: newId(), kind: 'file', direction: 'out', peer: p.publicKey, peerName: p.name, text: `${abs} (${(bytes / 1024).toFixed(1)} KB)${note ? ` · ${note}` : ''}`,
+            status: p.permissions.files === 'auto' && !warnings.length ? 'queued' : 'awaiting_human', data: { abs, name: path.basename(abs), bytes, sha256, note, requestId, ...(warnings.length ? { warnings, sensitive: true } : {}) } });
+        audit('file_prepared', { id: it.id, peer: p.publicKey, file: abs, bytes, sha256, needsApproval: it.status === 'awaiting_human' });
+        this.flush(p.publicKey);
+        this.changed(it);
+        return it;
+    }
+    async streamFile(it) {
+        if (this.streaming.has(it.id))
+            return;
+        this.streaming.add(it.id);
+        const d = it.data;
+        try {
+            if (hashFile(d.abs) !== d.sha256)
+                throw new Error('The file changed after it was approved; approve it again.');
+            const ok = await this.net.sendDrained(it.peer, { type: 'file_start', id: it.id, inReplyTo: d.requestId, name: d.name, bytes: d.bytes, sha256: d.sha256, note: d.note ?? '' });
+            if (!ok)
+                throw new Error('offline');
+            const fd = fs.openSync(d.abs, 'r');
+            try {
+                const buf = Buffer.alloc(CHUNK_BYTES);
+                for (let seq = 0, n; (n = fs.readSync(fd, buf, 0, CHUNK_BYTES, null)) > 0; seq++) {
+                    if (!(await this.net.sendDrained(it.peer, { type: 'file_chunk', id: it.id, seq, data: buf.subarray(0, n).toString('base64') })))
+                        throw new Error('offline');
+                }
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            await this.net.sendDrained(it.peer, { type: 'file_end', id: it.id });
+            this.store.setStatus(it.id, 'sent');
+            audit('file_sent', { id: it.id, peer: it.peer, file: d.abs, bytes: d.bytes, sha256: d.sha256 });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            if (msg === 'offline')
+                this.store.setStatus(it.id, 'queued', 'Connection dropped; it resends when the peer is back.');
+            else {
+                this.store.setStatus(it.id, 'failed', msg);
+                if (d.requestId)
+                    this.net.send(it.peer, { type: 'refused', inReplyTo: d.requestId, reason: msg });
+            }
+        }
+        finally {
+            this.streaming.delete(it.id);
+            this.changed(this.store.item(it.id));
+        }
+    }
+    // ── tasks ────────────────────────────────────────────────────────────────
+    requestTask(peerName, text) { return this.outgoing(peerName, 'task', text); }
+    updateTask(id, note) {
+        const t = this.requireInbox(id, 'task');
+        return this.outgoing(t.peer, 'task_update', note, { inReplyTo: t.id, data: { state: 'running' } });
+    }
+    completeTask(id, note, artifactPaths, failed = false, needsInput = false) {
+        const t = this.requireInbox(id, 'task');
+        const replies = () => { for (const r of this.store.items.filter((i) => i.kind === 'task_reply' && i.inReplyTo === t.id && i.status === 'delivered'))
+            this.store.setStatus(r.id, 'answered'); };
+        if (needsInput) {
+            const q = this.outgoing(t.peer, 'task_update', note, { inReplyTo: t.id, data: { state: 'waiting' } });
+            this.store.setStatus(t.id, 'delivered', undefined, { state: 'waiting' });
+            replies();
+            audit('task_waiting', { id: t.id });
+            return q;
+        }
+        replies();
+        const artifacts = artifactPaths.map((p) => {
+            const abs = path.resolve(p);
+            if (!fs.existsSync(abs) || !fs.statSync(abs).isFile())
+                throw new Error(`Listed result file does not exist: ${abs}. A task is only done when its files exist.`);
+            return { path: abs, bytes: fs.statSync(abs).size, sha256: hashFile(abs) };
+        });
+        const state = failed ? 'failed' : 'done';
+        const at = new Date().toISOString();
+        const signature = sign(this.keys, receiptPayload(t.id, state, note, artifacts, at));
+        const u = this.outgoing(t.peer, 'task_update', note, { inReplyTo: t.id, data: { state, receipt: { artifacts, at, signature } } });
+        this.store.setStatus(t.id, 'answered');
+        audit('task_completed', { id: t.id, state, artifacts: artifacts.length });
+        return u;
+    }
+    // ── brain ────────────────────────────────────────────────────────────────
+    recordDecision(input) {
+        if (input.shared !== false)
+            blockSecrets(JSON.stringify(input), 'shared decision (save it with shared=false to keep it on this computer only)');
+        const d = this.brain.record(input);
+        audit('decision_recorded', { id: d.id, shared: d.shared });
+        if (d.shared)
+            this.syncAll();
+        return d;
+    }
+    setDecisionShared(id, shared) {
+        const d = this.brain.setShared(id, shared);
+        audit('decision_sharing', { id, shared });
+        this.syncAll();
+        return d;
+    }
+    searchMine(query) { return search(this.brain.mine, query, 10); }
+    /** Searches a peer's shared decisions: live when it's online, otherwise from the copy it last synced here. */
+    askBrain(peerName, query) {
+        const p = this.requirePeer(peerName);
+        if (!this.net.isOnline(p.publicKey))
+            return { item: null, offline: this.searchCopy(p.publicKey, query) };
+        return { item: this.outgoing(p.publicKey, 'brain_query', query), offline: null };
+    }
+    searchCopy(peer, query) {
+        const c = this.brain.copyOf(peer);
+        return c ? { syncedAt: c.syncedAt, results: search(c.decisions, query, 10) } : null;
+    }
+    syncBrain(peer) {
+        const p = this.store.peer(peer);
+        if (!p || !this.net.isOnline(peer))
+            return;
+        const decisions = p.permissions.brain === 'auto' ? this.brain.syncPayload() : [];
+        this.net.send(peer, { type: 'brain_sync', decisions, at: new Date().toISOString() });
+    }
+    syncAll() { for (const p of this.store.peers)
+        this.syncBrain(p.publicKey); }
+    answerBrain(peer, queryId, query) {
+        const results = search(this.brain.shared(), query, 10);
+        this.net.send(peer, { type: 'brain_result', id: newId(), inReplyTo: queryId, results });
+        audit('brain_answered', { peer, queryId, results: results.length });
+    }
+    // ── human approvals (never exposed to the agent) ─────────────────────────
+    pending() { return this.store.items.filter((i) => i.status === 'awaiting_human'); }
+    approve(id) {
+        const it = this.requirePending(id);
+        audit('approved', { id, kind: it.kind, direction: it.direction, peer: it.peer });
+        if (it.kind === 'pair' && it.direction === 'out') {
+            const j = this.store.joins.find((x) => x.publicKey === it.peer);
+            if (j)
+                j.approved = true;
+            this.store.setStatus(id, 'sent');
+            if (this.net.isOnline(it.peer))
+                this.sendPairRequest(it.peer);
+            else
+                this.net.dial(it.peer);
+        }
+        else if (it.kind === 'pair') {
+            this.store.addPeer(it.peer, it.peerName);
+            this.store.setStatus(id, 'sent');
+            this.net.send(it.peer, { type: 'pair_accepted', name: this.settings.name });
+            this.net.send(it.peer, { type: 'limits', maxFileBytes: this.settings.maxFileBytes });
+            this.net.dial(it.peer);
+        }
+        else if (it.direction === 'in' && it.kind === 'brain_query') {
+            this.store.setStatus(id, 'answered');
+            this.answerBrain(it.peer, it.id, it.text);
+        }
+        else if (it.direction === 'in') {
+            this.deliverIn(it);
+        }
+        else {
+            this.store.setStatus(id, 'queued');
+            this.flush(it.peer);
+        }
+        this.notice(it, 'approved');
+        const out = this.store.item(id);
+        this.changed(out);
+        return out;
+    }
+    deliverIn(it) {
+        const t = this.store.item(String(it.kind === 'task_reply' ? it.inReplyTo : it.data?.thread ?? ''));
+        this.store.setStatus(it.id, 'delivered', undefined, t?.kind === 'task' && t.data?.session ? { resume: t.data.session } : undefined);
+        if (it.kind === 'task_reply' && t)
+            this.store.setStatus(t.id, t.status, undefined, { state: 'running' });
+        it = this.store.item(it.id);
+        if (it.kind === 'file')
+            this.releaseFile(it);
+        if (it.kind === 'task')
+            this.net.send(it.peer, { type: 'task_update', id: newId(), inReplyTo: it.id, state: 'accepted', note: 'Approved; the agent will start it.' });
+        if (it.kind === 'task' || it.kind === 'ask' || it.kind === 'task_reply')
+            this.waker.ring(it);
+    }
+    /** Automatic questions: my own agent first checks, in any language, whether it asks for a change or a secret. Those wait for the person. */
+    async precheckThenDeliver(it) {
+        const v = await this.waker.precheck(it, this.settings.limits.precheckSeconds);
+        const cur = this.store.item(it.id);
+        if (!cur || cur.status !== 'awaiting_human')
+            return;
+        const warnings = !v ? ['could not be checked by your agent, so it waits for you']
+            : [...(v.changes ? [`asks to change something${v.reason ? ` (${v.reason})` : ''}`] : []), ...(v.secrets ? [`asks for secrets${v.reason && !v.changes ? ` (${v.reason})` : ''}`] : [])];
+        audit('precheck', { id: it.id, changes: v?.changes ?? null, secrets: v?.secrets ?? null, reason: v?.reason });
+        if (!warnings.length) {
+            this.store.setStatus(it.id, 'awaiting_human', undefined, { checking: undefined, checked: v?.reason || 'no change or secret asked' });
+            return this.autoAccept(this.store.item(it.id));
+        }
+        this.store.setStatus(it.id, 'awaiting_human', undefined, { checking: undefined, warnings, sensitive: true });
+        this.changed(this.store.item(it.id));
+    }
+    /** The person set this kind to "Automatic" and nothing in it was flagged. */
+    autoAccept(it) {
+        audit('auto_approved', { id: it.id, kind: it.kind, peer: it.peer });
+        this.deliverIn(it);
+        this.changed(this.store.item(it.id));
+    }
+    deny(id) {
+        const it = this.requirePending(id);
+        audit('denied', { id, kind: it.kind, direction: it.direction, peer: it.peer });
+        this.store.setStatus(id, 'denied');
+        if (it.kind === 'pair' && it.direction === 'out') {
+            this.store.joins = this.store.joins.filter((j) => j.publicKey !== it.peer);
+            this.store.save();
+            this.changed(it);
+            return it;
+        }
+        if (it.kind === 'file' && it.direction === 'in')
+            fs.rmSync(String(it.data?.heldAt ?? ''), { force: true });
+        const requestId = it.data?.requestId;
+        if (it.kind === 'pair')
+            this.net.send(it.peer, { type: 'pair_denied' });
+        else if (it.direction === 'in' && (it.kind === 'reply' || it.kind === 'task_update' || it.kind === 'brain_result' || it.kind === 'file')) { /* their answer stays here, unread */ }
+        else if (it.direction === 'in')
+            this.net.send(it.peer, { type: 'refused', inReplyTo: it.id, reason: 'The person on that computer declined it.' });
+        else if (requestId)
+            this.net.send(it.peer, { type: 'refused', inReplyTo: requestId, reason: 'The person on that computer declined to send the file.' });
+        const out = this.store.item(id);
+        this.changed(out);
+        return out;
+    }
+    // ── network ──────────────────────────────────────────────────────────────
+    mayConnect(pk) {
+        this.store.pruneInvites();
+        return !!this.store.peer(pk) || this.store.joins.some((j) => j.publicKey === pk) || this.store.invites.length > 0;
+    }
+    onOnline(peer) {
+        if (this.store.joins.some((j) => j.publicKey === peer))
+            this.sendPairRequest(peer);
+        this.flush(peer);
+        this.syncBrain(peer);
+        this.net.send(peer, { type: 'limits', maxFileBytes: this.settings.maxFileBytes });
+        for (const it of this.pending().filter((i) => i.peer === peer && !i.data?.checking))
+            this.notice(it, 'held');
+    }
+    /** The other computer's request that this item makes wait for my person: their question, task or search, or my answer to it. */
+    requestOf(it) {
+        if (it.direction === 'in')
+            return ['ask', 'task', 'task_reply', 'brain_query'].includes(it.kind) ? it.id : undefined;
+        if (it.kind === 'reply' || it.kind === 'task_update')
+            return it.inReplyTo;
+        return it.kind === 'file' ? it.data?.requestId : undefined;
+    }
+    /** Tells the asking computer where its request stands here, so its agent can tell its person. */
+    notice(it, state) {
+        const r = this.requestOf(it);
+        if (r && this.net.isOnline(it.peer))
+            this.net.send(it.peer, { type: 'status', inReplyTo: r, state });
+    }
+    sendPairRequest(peer) {
+        const j = this.store.joins.find((x) => x.publicKey === peer);
+        if (j?.approved)
+            this.net.send(peer, { type: 'pair_request', secret: j.secret, name: this.settings.name });
+    }
+    /** Any text my agent sends goes through my "send" rule; anything that looks like a secret always waits for my review. */
+    outgoing(peerName, kind, text, extra = {}) {
+        const p = this.requirePeer(peerName);
+        if (p.permissions.send === 'never')
+            throw new Error(`Sending to ${p.name} is turned off on this computer.`);
+        const secrets = secretsIn(`${text}\n${JSON.stringify(extra.data ?? {})}`);
+        const data = secrets.length ? { ...extra.data, warnings: [`contains what looks like a secret (${secrets.join(', ')})`], sensitive: true } : extra.data;
+        const it = this.store.addItem({ id: newId(), kind, direction: 'out', peer: p.publicKey, peerName: p.name, text, inReplyTo: extra.inReplyTo, data, status: p.permissions.send === 'auto' && !secrets.length ? 'queued' : 'awaiting_human' });
+        audit(`${kind}_created`, { id: it.id, peer: p.publicKey, bytes: text.length, needsApproval: it.status === 'awaiting_human' });
+        this.flush(p.publicKey);
+        this.changed(it);
+        return it;
+    }
+    wire(it) {
+        const d = (it.data ?? {});
+        switch (it.kind) {
+            case 'ask': return { type: 'ask', id: it.id, text: it.text, ...(d.thread ? { thread: d.thread } : {}) };
+            case 'task_reply': return { type: 'task_reply', id: it.id, inReplyTo: it.inReplyTo, text: it.text };
+            case 'reply': return { type: 'reply', id: it.id, inReplyTo: it.inReplyTo, text: it.text, sources: d.sources ?? [] };
+            case 'file_request': return { type: 'file_request', id: it.id, path: d.path, reason: d.reason ?? '' };
+            case 'task': return { type: 'task', id: it.id, text: it.text };
+            case 'task_update': return { type: 'task_update', id: it.id, inReplyTo: it.inReplyTo, state: d.state, note: it.text, receipt: d.receipt };
+            case 'brain_query': return { type: 'brain_query', id: it.id, query: it.text };
+            default: return null;
+        }
+    }
+    /** Sends everything approved that was waiting for this peer to come online. */
+    flush(peer) {
+        if (!this.net.isOnline(peer))
+            return;
+        for (const it of this.store.items.filter((i) => i.peer === peer && i.direction === 'out' && i.status === 'queued')) {
+            if (it.kind === 'file') {
+                void this.streamFile(it);
+                continue;
+            }
+            const msg = this.wire(it);
+            if (msg && this.net.send(peer, msg)) {
+                this.store.setStatus(it.id, 'sent');
+                audit('sent', { id: it.id, kind: it.kind, peer, bytes: it.text.length });
+                this.changed(it);
+            }
+        }
+    }
+    onMessage(peer, msg) {
+        const known = this.store.peer(peer);
+        if (msg.type === 'pair_request' || msg.type === 'pair_accepted' || msg.type === 'pair_denied')
+            return this.onPairing(peer, msg, known);
+        if (!known)
+            return;
+        if (msg.type !== 'file_chunk' && !this.withinRate(peer)) {
+            audit('rate_limited', { peer, type: msg.type });
+            return;
+        }
+        const exists = (id) => !!this.store.item(id);
+        const full = () => this.store.pendingFrom(peer) >= this.settings.limits.maxPendingPerPeer;
+        const hold = (text) => { const w = steeringIn(text); return w.length ? { warnings: w } : undefined; };
+        const refuse = (inReplyTo, reason) => { this.net.send(peer, { type: "refused", inReplyTo, reason: reason.slice(0, 500) }); };
+        const mineOut = (id, kind) => { const m = this.store.item(id); return m && m.direction === 'out' && m.peer === peer && (!kind || m.kind === kind) ? m : undefined; };
+        switch (msg.type) {
+            case 'ask': {
+                if (exists(msg.id))
+                    return;
+                if (known.permissions.ask === 'never')
+                    return refuse(msg.id, 'Questions from you are turned off on that computer.');
+                const warnings = warningsIn(msg.text);
+                if (full())
+                    return refuse(msg.id, 'Too many of your requests are waiting on that computer; try later.');
+                const auto = known.permissions.ask === 'auto' && !warnings.length;
+                const checking = auto && this.waker.preset !== null && this.waker.preset !== 'custom';
+                const t = msg.thread ? this.store.item(msg.thread) : undefined;
+                const thread = t && t.kind === 'task' && t.direction === 'in' && t.peer === peer ? { thread: t.id } : {};
+                const it = this.store.addItem({ id: msg.id, kind: 'ask', direction: 'in', peer, peerName: known.name, text: msg.text, status: 'awaiting_human', data: { ...thread, ...(warnings.length ? { warnings, sensitive: true } : checking ? { checking: true } : {}) } });
+                audit('ask_received', { id: it.id, peer, bytes: msg.text.length, warnings: warnings.length ? warnings : undefined });
+                if (checking) {
+                    this.changed(it);
+                    return void this.precheckThenDeliver(it);
+                }
+                if (auto)
+                    return this.autoAccept(it);
+                return this.changed(it);
+            }
+            case 'reply': {
+                const mine = mineOut(msg.inReplyTo);
+                if (!mine || exists(msg.id))
+                    return;
+                const flagged = hold(`${msg.text}\n${(msg.sources ?? []).join('\n')}`);
+                const it = this.store.addItem({ id: msg.id, kind: 'reply', direction: 'in', peer, peerName: known.name, text: msg.text, inReplyTo: msg.inReplyTo, status: flagged ? 'awaiting_human' : 'delivered', data: { sources: msg.sources ?? [], ...flagged } });
+                this.store.setStatus(mine.id, 'answered');
+                audit('reply_received', { id: it.id, inReplyTo: msg.inReplyTo, peer, bytes: msg.text.length, heldForYou: !!flagged, warnings: flagged?.warnings });
+                return this.changed(it);
+            }
+            case 'status': {
+                const mine = mineOut(msg.inReplyTo);
+                if (!mine || ['answered', 'failed', 'denied'].includes(mine.status))
+                    return;
+                this.store.setStatus(mine.id, mine.status, undefined, { remote: msg.state, remoteAt: new Date().toISOString() });
+                return this.changed(this.store.item(mine.id));
+            }
+            case 'refused': {
+                const mine = mineOut(msg.inReplyTo);
+                if (!mine)
+                    return;
+                this.store.setStatus(mine.id, 'failed', msg.reason);
+                return this.changed(this.store.item(mine.id));
+            }
+            case 'file_request': {
+                if (exists(msg.id))
+                    return;
+                const req = this.store.addItem({ id: msg.id, kind: 'file_request', direction: 'in', peer, peerName: known.name, text: `${msg.path}${msg.reason ? ` (${msg.reason})` : ''}`, status: 'answered', data: { path: msg.path, reason: msg.reason } });
+                if (known.permissions.files === 'never') {
+                    this.store.setStatus(req.id, 'failed', 'files off');
+                    return refuse(msg.id, 'Sending files to you is turned off on that computer.');
+                }
+                const c = checkFile(msg.path, this.fileRoots(known), this.settings.maxFileBytes, known.reach === 'computer');
+                audit('file_requested', { id: msg.id, peer, path: msg.path, allowed: c.ok, reason: c.reason, warnings: c.flags.length ? c.flags : undefined });
+                if (!c.ok) {
+                    this.store.setStatus(req.id, 'failed', c.reason);
+                    return refuse(msg.id, c.reason);
+                }
+                if (known.theirMaxFileBytes && c.bytes > known.theirMaxFileBytes) {
+                    const why = `The file is ${mb(c.bytes)}; your computer accepts files up to ${mb(known.theirMaxFileBytes)}. Raise "Largest file" in your Secure Settings, then ask again.`;
+                    this.store.setStatus(req.id, 'failed', why);
+                    return refuse(msg.id, why);
+                }
+                this.addOutgoingFile(known, c.abs, c.bytes, c.sha256, msg.reason, msg.id, c.flags);
+                return;
+            }
+            case 'file_start': {
+                if (exists(msg.id))
+                    return;
+                if (msg.bytes > this.settings.maxFileBytes)
+                    return refuse(msg.id, `The file is bigger than that computer accepts (${Math.round(this.settings.maxFileBytes / 1048576)} MB).`);
+                if (!msg.inReplyTo && full())
+                    return;
+                if (msg.inReplyTo && !mineOut(msg.inReplyTo, 'file_request'))
+                    return;
+                const dir = path.join(file('received'), known.name.replace(/[^a-z0-9-]/gi, '_'));
+                fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+                const disk = fs.statfsSync(dir);
+                if (disk.bavail * disk.bsize - msg.bytes < this.settings.limits.minFreeDiskMB * 1048576) {
+                    audit('file_refused_disk', { id: msg.id, peer, bytes: msg.bytes });
+                    return refuse(msg.id, 'That computer does not have enough free disk space for this file.');
+                }
+                const dest = uniquePath(dir, path.basename(msg.name).replace(/[^\w.\- ]/g, '_') || 'file');
+                const tmp = `${dest}.part`;
+                const it = this.store.addItem({ id: msg.id, kind: 'file', direction: 'in', peer, peerName: known.name, text: `${path.basename(dest)} (${(msg.bytes / 1024).toFixed(1)} KB)${msg.note ? ` · ${msg.note}` : ''}`, inReplyTo: msg.inReplyTo, status: 'queued', note: 'receiving', data: { name: msg.name, bytes: msg.bytes, sha256: msg.sha256, ...hold(msg.note) } });
+                this.incoming.set(msg.id, { fd: fs.openSync(tmp, 'w', 0o600), tmp, dest, item: it.id, bytes: 0, expected: msg.bytes, sha256: msg.sha256 });
+                return this.changed(it);
+            }
+            case 'file_chunk': {
+                const f = this.incoming.get(msg.id);
+                if (!f || this.store.item(f.item)?.peer !== peer)
+                    return;
+                const data = Buffer.from(msg.data, 'base64');
+                f.bytes += data.length;
+                if (f.bytes > f.expected)
+                    return this.failIncoming(msg.id, 'The file was bigger than announced.');
+                fs.writeSync(f.fd, data);
+                return;
+            }
+            case 'file_end': {
+                const f = this.incoming.get(msg.id);
+                if (!f || this.store.item(f.item)?.peer !== peer)
+                    return;
+                fs.closeSync(f.fd);
+                this.incoming.delete(msg.id);
+                if (f.bytes !== f.expected || hashFile(f.tmp) !== f.sha256) {
+                    fs.rmSync(f.tmp, { force: true });
+                    this.store.setStatus(f.item, 'failed', 'The file arrived damaged (checksum mismatch), so it was discarded.');
+                    return this.changed(this.store.item(f.item));
+                }
+                const asked = !!this.store.item(f.item)?.inReplyTo;
+                if (asked) {
+                    this.releaseFile(this.store.item(f.item), f.tmp, f.dest);
+                    this.store.setStatus(f.item, 'delivered', 'verified');
+                }
+                else
+                    this.store.setStatus(f.item, 'awaiting_human', 'verified; your agent sees it after you accept it', { heldAt: f.tmp, dest: f.dest, verified: true });
+                const it = this.store.item(f.item);
+                if (it.inReplyTo)
+                    this.store.setStatus(it.inReplyTo, 'answered');
+                audit('file_received', { id: it.id, peer, savedTo: f.dest, bytes: f.bytes, sha256: f.sha256, heldForYou: !asked });
+                return this.changed(it);
+            }
+            case 'task': {
+                if (exists(msg.id))
+                    return;
+                if (known.permissions.tasks === 'never')
+                    return refuse(msg.id, 'Tasks from you are turned off on that computer.');
+                if (full())
+                    return refuse(msg.id, 'Too many of your requests are waiting on that computer; try later.');
+                // Tasks can change things, so they always wait for the person's review and passkey.
+                const warnings = warningsIn(msg.text);
+                const it = this.store.addItem({ id: msg.id, kind: 'task', direction: 'in', peer, peerName: known.name, text: msg.text, status: 'awaiting_human', data: warnings.length ? { warnings, sensitive: true } : undefined });
+                audit('task_received', { id: it.id, peer, bytes: msg.text.length, warnings: warnings.length ? warnings : undefined });
+                return this.changed(it);
+            }
+            case 'task_update': {
+                const mine = mineOut(msg.inReplyTo, 'task');
+                if (!mine || exists(msg.id))
+                    return;
+                const verified = msg.receipt ? verify(peer, receiptPayload(msg.inReplyTo, msg.state, msg.note, msg.receipt.artifacts, msg.receipt.at), msg.receipt.signature) : null;
+                const flagged = hold(msg.note);
+                const it = this.store.addItem({ id: msg.id, kind: 'task_update', direction: 'in', peer, peerName: known.name, text: msg.note, inReplyTo: msg.inReplyTo, status: flagged ? 'awaiting_human' : 'delivered', data: { state: msg.state, receipt: msg.receipt, receiptVerified: verified, ...flagged } });
+                this.store.setStatus(mine.id, msg.state === 'done' || msg.state === 'failed' ? 'answered' : 'sent', undefined, { state: msg.state });
+                audit('task_update_received', { id: it.id, task: msg.inReplyTo, state: msg.state, receiptVerified: verified });
+                return this.changed(it);
+            }
+            case 'task_reply': {
+                if (exists(msg.id))
+                    return;
+                const t = this.store.item(msg.inReplyTo);
+                if (!t || t.kind !== 'task' || t.direction !== 'in' || t.peer !== peer || t.data?.state !== 'waiting')
+                    return refuse(msg.id, 'That task is not waiting for an answer on that computer.');
+                if (known.permissions.tasks === 'never')
+                    return refuse(msg.id, 'Tasks from you are turned off on that computer.');
+                // Part of a task the person already approved: it goes on unless it tries to take over the agent.
+                const warnings = steeringIn(msg.text);
+                const it = this.store.addItem({ id: msg.id, kind: 'task_reply', direction: 'in', peer, peerName: known.name, text: msg.text, inReplyTo: t.id, status: 'awaiting_human', data: { thread: t.id, ...(warnings.length ? { warnings, sensitive: true } : {}) } });
+                audit('task_reply_received', { id: it.id, task: t.id, peer, bytes: msg.text.length, warnings: warnings.length ? warnings : undefined });
+                if (warnings.length)
+                    return this.changed(it);
+                return this.autoAccept(it);
+            }
+            case 'limits': {
+                const before = known.theirMaxFileBytes;
+                if (before === msg.maxFileBytes)
+                    return;
+                known.theirMaxFileBytes = msg.maxFileBytes;
+                this.store.save();
+                audit('peer_file_limit', { peer, maxFileBytes: msg.maxFileBytes });
+                if (msg.maxFileBytes > this.settings.maxFileBytes && before !== undefined) {
+                    const text = `${clean(known.name)} now accepts files up to ${mb(msg.maxFileBytes)}. Yours is ${mb(this.settings.maxFileBytes)}, so files between you stay at ${mb(this.settings.maxFileBytes)} until you raise "Largest file" in Settings.`;
+                    const n = this.store.addItem({ id: newId(), kind: 'notice', direction: 'in', peer, peerName: known.name, text, status: 'delivered' });
+                    if (this.settings.notify)
+                        desktopNotify(text);
+                    return this.changed(n);
+                }
+                return;
+            }
+            case 'brain_query': {
+                if (exists(msg.id))
+                    return;
+                if (known.permissions.brain === 'never')
+                    return refuse(msg.id, 'That computer does not share its decisions with you.');
+                if (known.permissions.brain === 'ask') {
+                    if (full())
+                        return refuse(msg.id, 'Too many of your requests are waiting on that computer; try later.');
+                    const it = this.store.addItem({ id: msg.id, kind: 'brain_query', direction: 'in', peer, peerName: known.name, text: msg.query, status: 'awaiting_human' });
+                    return this.changed(it);
+                }
+                this.store.addItem({ id: msg.id, kind: 'brain_query', direction: 'in', peer, peerName: known.name, text: msg.query, status: 'answered' });
+                return this.answerBrain(peer, msg.id, msg.query);
+            }
+            case 'brain_result': {
+                const mine = mineOut(msg.inReplyTo, 'brain_query');
+                if (!mine || exists(msg.id))
+                    return;
+                const flagged = hold(JSON.stringify(msg.results));
+                const it = this.store.addItem({ id: msg.id, kind: 'brain_result', direction: 'in', peer, peerName: known.name, text: `${msg.results.length} decision(s)`, inReplyTo: msg.inReplyTo, status: flagged ? 'awaiting_human' : 'delivered', data: { results: msg.results, ...flagged } });
+                this.store.setStatus(mine.id, 'answered');
+                return this.changed(it);
+            }
+            case 'brain_sync': {
+                const clean = msg.decisions.filter((d) => !steeringIn(JSON.stringify(d)).length);
+                this.brain.storeCopy(peer, known.name, clean);
+                audit('brain_copy_synced', { peer, decisions: clean.length, droppedAsInstructions: msg.decisions.length - clean.length });
+                return;
+            }
+        }
+    }
+    onPairing(peer, msg, known) {
+        if (msg.type === 'pair_request') {
+            if (known) {
+                this.net.send(peer, { type: 'pair_accepted', name: this.settings.name });
+                return;
+            }
+            this.store.pruneInvites();
+            const inv = this.store.invites.find((i) => sameSecret(i.secret, msg.secret));
+            if (!inv) {
+                audit('pair_rejected', { peer, reason: 'unknown or expired invite' });
+                this.net.send(peer, { type: 'pair_denied' });
+                return;
+            }
+            this.store.invites = this.store.invites.filter((i) => i !== inv);
+            const it = this.store.addItem({ id: newId(), kind: 'pair', direction: 'in', peer, peerName: msg.name, text: `Safety number ${safetyNumber(this.me, peer)}`, status: 'awaiting_human' });
+            audit('pair_requested', { id: it.id, peer, name: msg.name });
+            this.changed(it);
+        }
+        else if (msg.type === 'pair_accepted') {
+            if (!this.store.joins.some((j) => j.publicKey === peer) && !known)
+                return;
+            this.store.joins = this.store.joins.filter((j) => j.publicKey !== peer);
+            const p = this.store.addPeer(peer, msg.name);
+            audit('paired', { peer, name: p.name });
+            this.flush(peer);
+            this.syncBrain(peer);
+            this.net.send(peer, { type: 'limits', maxFileBytes: this.settings.maxFileBytes });
+        }
+        else {
+            if (!this.store.joins.some((j) => j.publicKey === peer))
+                return;
+            this.store.joins = this.store.joins.filter((j) => j.publicKey !== peer);
+            this.store.save();
+            audit('pair_denied_by_peer', { peer });
+        }
+    }
+    /** Moves a received file into place: never executable, marked as downloaded from elsewhere so the OS warns before opening it. */
+    releaseFile(it, tmp = String(it.data?.heldAt ?? ''), dest = String(it.data?.dest ?? '')) {
+        fs.renameSync(tmp, dest);
+        fs.chmodSync(dest, 0o600);
+        if (isMac)
+            spawnSync('xattr', ['-w', 'com.apple.quarantine', `0081;${Math.floor(Date.now() / 1000).toString(16)};Secure;`, dest]);
+        if (isWin) {
+            try {
+                fs.writeFileSync(`${dest}:Zone.Identifier`, '[ZoneTransfer]\r\nZoneId=3\r\n');
+            }
+            catch { /* not NTFS */ }
+        }
+        this.store.setStatus(it.id, it.status, undefined, { savedTo: dest, verified: true, untrusted: true, heldAt: undefined });
+    }
+    withinRate(peer) {
+        const t = Date.now(), r = this.rate.get(peer);
+        if (!r || t - r.start > 60_000) {
+            this.rate.set(peer, { start: t, count: 1 });
+            return true;
+        }
+        return ++r.count <= this.settings.limits.messagesPerMinute;
+    }
+    failIncoming(id, reason) {
+        const f = this.incoming.get(id);
+        if (!f)
+            return;
+        try {
+            fs.closeSync(f.fd);
+        }
+        catch { /* already closed */ }
+        fs.rmSync(f.tmp, { force: true });
+        this.incoming.delete(id);
+        this.store.setStatus(f.item, 'failed', reason);
+        this.changed(this.store.item(f.item));
+    }
+    dropIncoming(peer) {
+        for (const [id, f] of this.incoming)
+            if (this.store.item(f.item)?.peer === peer)
+                this.failIncoming(id, 'The connection dropped during the transfer; ask for the file again.');
+    }
+    // ── helpers ──────────────────────────────────────────────────────────────
+    requirePeer(nameOrKey) {
+        const p = this.store.peerByName(nameOrKey);
+        if (!p)
+            throw new Error(`No paired agent called "${nameOrKey}". Paired: ${this.store.peers.map((x) => x.name).join(', ') || 'none yet'}.`);
+        return p;
+    }
+    requireInbox(id, kind) {
+        const it = this.store.item(id);
+        if (!it || it.direction !== 'in' || it.kind !== kind)
+            throw new Error(`There is no ${kind === 'ask' ? 'question' : kind} with that id in the inbox.`);
+        if (it.status !== 'delivered')
+            throw new Error(`That ${kind === 'ask' ? 'question' : kind} is ${it.status.replace('_', ' ')}; it can't be answered now.`);
+        return it;
+    }
+    requirePending(id) {
+        const it = this.store.item(id);
+        if (!it || it.status !== 'awaiting_human')
+            throw new Error('Nothing waiting for approval with that id.');
+        return it;
+    }
+    changed(it) {
+        if (it.status === 'awaiting_human' && !it.data?.checking && !this.alerted.has(it.id)) {
+            this.alerted.add(it.id);
+            this.notifier.add(it);
+            this.notice(it, 'held');
+        }
+        this.emit('item', it);
+    }
+}
+function uniquePath(dir, name) {
+    const ext = path.extname(name), base = path.basename(name, ext);
+    for (let i = 0;; i++) {
+        const p = path.join(dir, i ? `${base} (${i})${ext}` : name);
+        if (!fs.existsSync(p) && !fs.existsSync(`${p}.part`))
+            return p;
+    }
+}