agentbox-app 0.1.12 → 0.1.13

package/main/relay-client.mjs

@@ -0,0 +1,246 @@
+// THE MAC'S END OF THE RELAY (relay/worker.mjs is the middle, relay/phone/ the
+// far end). With phones let in from "Anywhere", the Mac holds one socket open
+// out to the relay, so nothing has to reach in to it: no port opened, no
+// router touched, nothing installed on the phone.
+//
+// Each request that arrives is opened with the key only the Mac and the phone
+// have (shared/relay-crypto.mjs), checked for a replay, and then asked of this
+// Mac's own phone server on 127.0.0.1, exactly as a phone on the Wi-Fi would
+// ask it. So the token, the files and every channel are guarded by the same
+// code either way. The answer goes back sealed, a frame at a time, so the
+// live event stream and a large picture both work.
+import {
+  relayIds, relayKeys, open, seal, unpackRequest, FRAME, frameAad, TO_MAC, FROM_MAC, ID_BYTES, tag,
+} from '../shared/relay-crypto.mjs';
+
+/** How far a phone's clock may be from this Mac's before a request is stale. */
+const SKEW_MS = 5 * 60_000;
+/** One sealed frame's most. Cloudflare takes up to 1MB per socket message. */
+const CHUNK = 256 * 1024;
+/** The most one request may carry, as the relay allows (relay/worker.mjs). */
+const MAX_REQUEST = 32 * 1024 * 1024;
+/** What a phone's request may carry on to the phone server. */
+const PASS = ['accept', 'content-type', 'range', 'user-agent', 'if-none-match', 'x-agentbox-token', 'x-agentbox-device'];
+/**
+ * How often a slow answer says "still working" (FRAME.WAIT), well inside the
+ * 30 s the room gives a Mac to start answering (relay/room.mjs).
+ */
+const WAIT_MS = 10_000;
+/** What the phone does not want back: the relay's stream is its own framing. */
+const DROP = new Set(['connection', 'keep-alive', 'transfer-encoding', 'content-length', 'content-encoding']);
+
+const enc = new TextEncoder();
+const hex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+
+export function createRelayClient({
+  relayUrl, key, port, WebSocketImpl = globalThis.WebSocket, fetchImpl = (...a) => globalThis.fetch(...a),
+  log = console, onChange = () => {}, waitMs = WAIT_MS,
+}) {
+  let ws = null;
+  let want = false;
+  let connected = false;
+  let error = null;
+  let retry = 1000;
+  let timer = null;
+  let gen = 0;
+  let forKey = null;
+  let ids = null;
+  let keys = null;
+  /** Requests answered lately, by nonce, so a recorded one sent again is refused. */
+  const answered = new Map();
+  /** Answers being sent, so a phone that gives up stops them. */
+  const live = new Map();
+  /** Pieces of requests too big for one message, until their last piece. */
+  const parts = new Map();
+
+  async function ready() {
+    const k = key();
+    if (k === forKey) return;
+    ids = await relayIds(k);
+    keys = await relayKeys(k);
+    forKey = k;
+    answered.clear();
+  }
+
+  function fresh(head) {
+    const now = Date.now();
+    for (const [n, at] of answered) if (now - at > 2 * SKEW_MS) answered.delete(n);
+    if (typeof head?.nonce !== 'string' || head.nonce.length < 16) return false;
+    if (!Number.isFinite(head.ts) || Math.abs(now - head.ts) > SKEW_MS) return false;
+    if (answered.has(head.nonce)) return false;
+    answered.set(head.nonce, now);
+    return true;
+  }
+
+  const send = (sock, bytes) => { try { sock.send(bytes); } catch { /* the socket went; the phone hears from the relay */ } };
+
+  async function answer(sock, id, sealed) {
+    const k = keys;
+    let head;
+    let body;
+    try {
+      ({ head, body } = unpackRequest(await open(k.up, sealed, 'req')));
+    } catch {
+      send(sock, tag(FROM_MAC.REFUSED, id));
+      return;
+    }
+    if (!fresh(head) || typeof head.path !== 'string' || !head.path.startsWith('/')) {
+      send(sock, tag(FROM_MAC.REFUSED, id));
+      return;
+    }
+    const ctl = new AbortController();
+    const idh = hex(id);
+    live.set(idh, ctl);
+    let seq = 0;
+    // One at a time, in order: each frame's number is sealed into it, and a
+    // "still working" frame from the timer must not overtake the head.
+    let queue = Promise.resolve();
+    const frame = (type, payload) => (queue = queue.then(async () => {
+      const plain = new Uint8Array(1 + payload.length);
+      plain[0] = type;
+      plain.set(payload, 1);
+      send(sock, tag(FROM_MAC.FRAME, id, await seal(k.down, plain, frameAad(head.nonce, seq++))));
+    }));
+    // Until the answer starts, a phone that asked for it hears "still working".
+    let waiting = head.wait ? setInterval(() => { frame(FRAME.WAIT, new Uint8Array(0)).catch(() => {}); }, waitMs) : null;
+    const answering = () => { if (waiting) clearInterval(waiting); waiting = null; };
+    let sentHead = false;
+    try {
+      const headers = { 'x-agentbox-relay': '1', 'x-forwarded-for': 'relay' };
+      for (const name of PASS) if (head.headers?.[name]) headers[name] = String(head.headers[name]);
+      const method = String(head.method || 'GET').toUpperCase();
+      const res = await fetchImpl(`http://127.0.0.1:${port()}${head.path}`, {
+        method, headers, body: method === 'GET' || method === 'HEAD' ? undefined : body, signal: ctl.signal,
+      });
+      answering();
+      const out = {};
+      res.headers.forEach((v, name) => { if (!DROP.has(name)) out[name] = v; });
+      sentHead = true;
+      await frame(FRAME.HEAD, enc.encode(JSON.stringify({ status: res.status, headers: out })));
+      if (res.body) {
+        const reader = res.body.getReader();
+        for (;;) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          for (let i = 0; i < value.length; i += CHUNK) await frame(FRAME.DATA, value.subarray(i, i + CHUNK));
+        }
+      }
+      await frame(FRAME.END, new Uint8Array(0));
+      send(sock, tag(FROM_MAC.DONE, id));
+    } catch (err) {
+      answering();
+      if (ctl.signal.aborted) return;
+      log.warn?.('[relay] answering failed:', err?.message ?? err);
+      try {
+        await queue.catch(() => {});
+        if (!sentHead) {
+          await frame(FRAME.HEAD, enc.encode(JSON.stringify({ status: 502, headers: { 'content-type': 'application/json' } })));
+          await frame(FRAME.DATA, enc.encode(JSON.stringify({ error: 'Your computer could not answer that.' })));
+        }
+        await frame(FRAME.END, new Uint8Array(0));
+      } catch { /* nothing more to say */ }
+      send(sock, tag(FROM_MAC.DONE, id));
+    } finally {
+      answering();
+      live.delete(idh);
+    }
+  }
+
+  async function onMessage(sock, data) {
+    const bytes = data instanceof ArrayBuffer ? new Uint8Array(data)
+      : data instanceof Uint8Array ? data
+        : new Uint8Array(await data.arrayBuffer());
+    if (bytes.length < 1 + ID_BYTES) return;
+    const id = bytes.slice(1, 1 + ID_BYTES);
+    const idh = hex(id);
+    if (bytes[0] === TO_MAC.CANCEL) {
+      live.get(idh)?.abort();
+      live.delete(idh);
+      parts.delete(idh);
+    } else if (bytes[0] === TO_MAC.PART) {
+      // A big request comes in pieces (relay/room.mjs); keep them until the
+      // last, within a limit, so a stream of pieces cannot fill memory.
+      const held = parts.get(idh) ?? { chunks: [], size: 0 };
+      held.chunks.push(bytes.slice(1 + ID_BYTES));
+      held.size += bytes.length - 1 - ID_BYTES;
+      if (held.size > MAX_REQUEST) { parts.delete(idh); send(sock, tag(FROM_MAC.REFUSED, id)); return; }
+      parts.set(idh, held);
+    } else if (bytes[0] === TO_MAC.REQUEST) {
+      const held = parts.get(idh);
+      parts.delete(idh);
+      const last = bytes.slice(1 + ID_BYTES);
+      if (!held) { await answer(sock, id, last); return; }
+      const whole = new Uint8Array(held.size + last.length);
+      let at = 0;
+      for (const c of held.chunks) { whole.set(c, at); at += c.length; }
+      whole.set(last, at);
+      await answer(sock, id, whole);
+    }
+  }
+
+  function schedule() {
+    if (!want || timer) return;
+    timer = setTimeout(() => { timer = null; void connect(); }, retry);
+    retry = Math.min(retry * 2, 30_000);
+  }
+
+  async function connect() {
+    const mine = ++gen;
+    try { await ready(); } catch (err) { error = String(err?.message ?? err); onChange(); schedule(); return; }
+    if (!want || mine !== gen) return;
+    const url = `${relayUrl.replace(/^http/, 'ws').replace(/\/+$/, '')}/mac/${ids.room}?proof=${encodeURIComponent(ids.proof)}`;
+    let sock;
+    try { sock = new WebSocketImpl(url); } catch (err) { error = `Could not reach the relay: ${err?.message ?? err}`; onChange(); schedule(); return; }
+    ws = sock;
+    sock.binaryType = 'arraybuffer';
+    sock.onopen = () => {
+      if (ws !== sock) return;
+      connected = true;
+      error = null;
+      retry = 1000;
+      onChange();
+    };
+    sock.onmessage = (event) => { if (ws === sock) void onMessage(sock, event.data); };
+    sock.onerror = () => { if (ws === sock && !connected) error = 'Could not reach the relay.'; };
+    sock.onclose = (event) => {
+      if (ws !== sock) return;
+      ws = null;
+      const was = connected;
+      connected = false;
+      for (const c of live.values()) c.abort();
+      live.clear();
+      if (event?.code === 4001) error = 'The relay turned this computer away.';
+      else if (was) error = null;
+      onChange();
+      schedule();
+    };
+  }
+
+  return {
+    start() {
+      if (want) return;
+      want = true;
+      retry = 1000;
+      void connect();
+    },
+    stop() {
+      want = false;
+      gen += 1;
+      if (timer) { clearTimeout(timer); timer = null; }
+      const sock = ws;
+      ws = null;
+      connected = false;
+      for (const c of live.values()) c.abort();
+      live.clear();
+      try { sock?.close(1000, 'Phones from anywhere turned off.'); } catch { /* already */ }
+      onChange();
+    },
+    /** The key was reset: the room is a new one. */
+    restart() {
+      if (!want) return;
+      this.stop();
+      this.start();
+    },
+    state: () => ({ connected, error, connecting: want && !connected && !error }),
+  };
+}

package/main/row-label.mjs

@@ -1,3 +1,4 @@
+import { harnessFor } from './harnesses.mjs';
 // THE NAME ON THE ROW, WRITTEN RATHER THAN TAKEN FROM THE FIRST SENTENCE.
 //
 // A dictated message keeps its first line as its title, verbatim and forever
@@ -188,10 +189,7 @@ export function codexNameArgs(item) {
 }
 
 function codexArgs(prompt) {
-  return [
-    'exec', '--skip-git-repo-check', '--ephemeral', '--ignore-user-config', '--ignore-rules',
-    '-s', 'read-only', '-c', 'model_reasoning_effort=low', prompt,
-  ];
+  return harnessFor('codex').smallModelArgs(prompt);
 }
 
 /**
@@ -218,11 +216,13 @@ export function nameRow(item, opts = {}) {
  */
 export function askSmallModel(prompt, clean, { claudeBin, codexBin = null, engine = 'claude', model = NAME_MODEL, timeoutMs = NAME_TIMEOUT_MS, env } = {}) {
   return new Promise((resolve) => {
-    const bin = engine === 'codex' ? codexBin : claudeBin;
+    let harness;
+    try { harness = harnessFor(engine); } catch { return resolve(''); }
+    const bin = harness.binary({ claudeBin, codexBin });
     if (!bin) return resolve('');
     let child;
     try {
-      child = spawn(bin, engine === 'codex' ? codexArgs(prompt) : ['-p', prompt, '--model', model], {
+      child = spawn(bin, harness.smallModelArgs(prompt, model), {
         // Somewhere that is nobody's project. A naming call must not pick up a
         // CLAUDE.md, a settings file or a hook from whatever folder it lands in.
         cwd: '/tmp',

package/main/runs-on.mjs

@@ -1,21 +1,23 @@
-// WHICH ACCOUNT THE AGENTS ARE ACTUALLY RUNNING ON, read off this Mac.
+// WHETHER THIS MAC IS ALREADY SIGNED INTO A CODING AGENT, AND WHICH ONE.
 //
-// w-e217e577e5, 2026-10-07, from a session with a new user: "He didn't realize
-// it auto-connected to Claude/Codex; he wasn't sure how it was even running."
+// w-e217e577e5, 2026-10-07. A new user ran an agent and, in her words, was
+// "like, 'Oh my God, where are the tokens coming from? I didn't even connect my
+// account.'" The app finds whichever coding agent is already signed in on the
+// Mac and spends that subscription without ever saying so.
 //
-// Every fact here was already on the disk and already being read, each by the
-// screen that needed it: main/claude-plan.mjs for the Claude plan (the Accounts
-// page), main/codex-account.mjs for the ChatGPT one (the Codex card). What did
-// not exist was ONE answer to "what is powering this", in a shape small enough
-// to ride the snapshot and be drawn in a corner. That is all this is: the two
-// readers, asked about the one account the fleet is spending, and null whenever
-// the answer would be a guess.
+// WHICH ENGINE, AND NOTHING ELSE. This read the plan tier too for a few hours,
+// so a row in the sidebar's foot could say "Claude · Max 20x"; that row came
+// out the same day and the tier came out with it ("very critically, I want to
+// get rid of that Claude Max 20x plan"). The question the walk answers is "did
+// it connect to something of mine", and the engine is the whole of that answer.
+// What somebody is paying for is on each agent's own page in Settings, which is
+// where you go when you actually want it (main/settings.mjs reads
+// main/claude-plan.mjs and main/codex-account.mjs for exactly that).
 //
-// NULL IS AN ORDINARY ANSWER AND IT MEANS DRAW NOTHING. A Mac mid-setup, a
-// config file being rewritten under us, a login that exists with no plan string
-// in it: the first two are null, the third is the name with no plan. Nothing
-// here ever reports an account that is not there, because the corner it feeds
-// is read by somebody deciding whose money this is spending.
+// NULL IS AN ORDINARY ANSWER AND IT MEANS SAY NOTHING. A Mac mid-setup, a config
+// file being rewritten under us, a login that is not there: all null, and the
+// walk then says nothing at all rather than guessing. That Mac is also the one
+// that gets the plan question instead, which says all of this out loud already.
 //
 // IT IS CACHED ON THE LOGIN FILES' OWN TIMES, NOT ON A CLOCK. The snapshot is
 // built every ten seconds and `~/.claude.json` is 148 KB on the machine this was
@@ -30,11 +32,11 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { planFile, planOfAccount } from './claude-plan.mjs';
+import { planFile } from './claude-plan.mjs';
 import { codexAccount, codexAuthFile } from './codex-account.mjs';
 import { signInFiles, signInStamp } from './sign-in-files.mjs';
 
-/** keyed by engine and folder, valued by the stamp it was read at. */
+/** keyed by engine, home and folder, valued by the stamp it was read at. */
 const remembered = new Map();
 
 /**
@@ -43,12 +45,11 @@ const remembered = new Map();
  * @param {object} facts
  * @param {string} facts.engine Which coding agent the workspace runs on, which
  *   the supervisor has already decided (`Supervisor#engineFacts`). Never worked
- *   out here: the capability gate lives there, and a corner that guessed could
+ *   out here: the capability gate lives there, and a line that guessed could
  *   name the subscription the fleet is not spending.
  * @param {string} [facts.claudeProfile] The Claude login, `default` or a folder.
  * @param {string} [facts.codexHome] The CODEX_HOME this workspace runs on.
- * @returns {{ engine: string, plan: string|null }|null} `plan` is the words the
- *   tool itself reports, never a label of ours.
+ * @returns {{ engine: string }|null}
  */
 export function runsOn({ engine = null, home = os.homedir(), claudeProfile = 'default', codexHome = null } = {}) {
   if (engine !== 'claude' && engine !== 'codex') return null;
@@ -63,28 +64,24 @@ export function runsOn({ engine = null, home = os.homedir(), claudeProfile = 'de
   const stamp = signInStamp(signInFiles({ engine, folder, home }));
   const seen = remembered.get(key);
   if (seen && seen.stamp === stamp) return seen.value;
-  const value = stamp ? read(engine, { home, claudeProfile, folder }) : null;
+  const value = stamp && signedIn(engine, { home, claudeProfile, folder }) ? { engine } : null;
   remembered.set(key, { stamp, value });
   return value;
 }
 
-function read(engine, { home, claudeProfile, folder }) {
-  if (engine === 'codex') {
-    const id = codexAccount(null, { file: codexAuthFile(folder) });
-    return id ? { engine: 'codex', plan: id.plan ?? null } : null;
-  }
-  // THE LOGIN AND THE PLAN COME OUT OF ONE READ. `readPlan` answers only the
-  // second, and "not signed in" and "signed in with no plan string" are two
-  // different screens: the first draws nothing, the second draws the name.
-  let account = null;
+/** Whether there is a login in there at all. Never throws, never guesses. */
+function signedIn(engine, { home, claudeProfile, folder }) {
+  if (engine === 'codex') return !!codexAccount(null, { file: codexAuthFile(folder) });
+  // `oauthAccount` is the object Claude Code writes when somebody signs in, and
+  // its absence is the honest "nobody is". A file with no account in it is an
+  // ordinary thing: `~/.claude.json` also holds project history, so it exists on
+  // plenty of Macs nobody has logged in on.
   try {
-    account = JSON.parse(fs.readFileSync(planFile(claudeProfile, home), 'utf8'))?.oauthAccount ?? null;
+    const account = JSON.parse(fs.readFileSync(planFile(claudeProfile, home), 'utf8'))?.oauthAccount;
+    return !!account && typeof account === 'object';
   } catch {
-    return null;
+    return false;
   }
-  if (!account || typeof account !== 'object') return null;
-  const plan = planOfAccount(account);
-  return { engine: 'claude', plan: plan.known ? plan.label : null };
 }
 
 /** Forgets every cached reading. For tests, and for a sign-out that lands. */

package/main/serve.mjs

@@ -29,6 +29,8 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 import { spawn } from 'node:child_process';
+import { Readable } from 'node:stream';
+import { mediaResponse, mediaType } from './img-scheme.mjs';
 import { loadConfig } from './config.mjs';
 import { Store } from './store.mjs';
 import { Supervisor } from './supervisor.mjs';
@@ -136,11 +138,14 @@ function readVersion() {
  *  same scrubbed path as the desktop's, which writes nothing until crash
  *  reports are set up for this process.
  */
-function answerWhatOnlyTheWindowAnswered(ipcMain) {
+export function answerWhatOnlyTheWindowAnswered(ipcMain) {
   ipcMain.handle('zero:badge', () => null);
+  ipcMain.handle('zero:corner-tag', () => null);
   ipcMain.handle('zero:notify', () => null);
   ipcMain.handle('zero:boot-info', () => ({ reloaded: false, builtAt: null, recovered: null }));
   ipcMain.handle('zero:crash', (_e, payload) => { reportFromRenderer(payload ?? {}); return null; });
+  // The phone door belongs to the desktop app (main/phone-link.mjs); a tab is told there is none.
+  ipcMain.handle('zero:phone-link', () => null);
 }
 
 /**
@@ -192,6 +197,13 @@ export async function bootHeadless({ dataDir = repoRoot, appDir = repoRoot, user
     stateFile: teamStateFile(config.storeRoot),
     onChange: () => ipc?.push?.(),
   }) : null;
+  // AND IT STOPS ITS OWN WORKERS ON THE WAY OUT, as main/main.mjs does for the
+  // desktop. Control-C reaches the whole process group, so without this each
+  // worker died of the signal itself and was written down as a run that failed
+  // on its own: a Claude task stopped that way read "it will keep failing the
+  // same way until this is fixed" and rested 15 minutes after the copy came
+  // back (tests/control-c-on-the-browser-copy-does-not-fail-its-agents).
+  host.app.on('before-quit', () => supervisor.killAll());
   ipc = registerIpc({ store, supervisor, config, window, host, team });
   answerWhatOnlyTheWindowAnswered(host.ipcMain);
   return { config, store, supervisor, window, host, ipc, team, channels: host.ipcMain.handlers };
@@ -200,18 +212,71 @@ export async function bootHeadless({ dataDir = repoRoot, appDir = repoRoot, user
 /** A token in the url, because the port alone is not a door key. */
 export const newToken = () => crypto.randomBytes(24).toString('base64url');
 
+/**
+ * THE KEY THAT ONLY READS FILES. A design page runs its own scripts and can
+ * read its own address, so the address a phone loads it from must not carry
+ * the phone's key, which starts agents and approves their requests. This is
+ * made from that key, changes when it is reset, and opens nothing but /f/.
+ */
+export const fileKey = (token) => crypto.createHmac('sha256', String(token ?? '')).update('agentbox-files').digest('base64url').slice(0, 32);
+
 const MIME = {
   '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
   '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
   '.css': 'text/css; charset=utf-8',
   '.json': 'application/json; charset=utf-8',
   '.svg': 'image/svg+xml',
   '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
   '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.bmp': 'image/bmp',
+  '.ico': 'image/x-icon',
+  '.pdf': 'application/pdf',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/plain; charset=utf-8',
   '.woff2': 'font/woff2',
+  '.woff': 'font/woff',
+  '.ttf': 'font/ttf',
   '.map': 'application/json; charset=utf-8',
 };
 
+/**
+ * One file off this computer, for the phone: /f/<file key>/<doc|img>/<path>.
+ * `files.allows(kind, file)` is the same rule the desktop's two schemes use
+ * (main/main.mjs passes it in), checked after the path is made whole, so a
+ * `..` cannot climb out of what it allows. Never from memory, for the reason
+ * the desktop's schemes give: a picture an agent redraws keeps its name.
+ */
+async function answerFile(req, res, url, { token, files }) {
+  const [, , key, kind, ...rest] = url.pathname.split('/');
+  if (kind !== 'doc' && kind !== 'img') { res.writeHead(404).end('No such kind of file.'); return; }
+  if (!sameKey(key, fileKey(typeof token === 'function' ? token() : token))) { res.writeHead(403).end('Wrong key.'); return; }
+  let file;
+  try { file = path.normalize('/' + rest.map(decodeURIComponent).join('/')); } catch { res.writeHead(400).end('Bad path.'); return; }
+  if (!path.isAbsolute(file) || !files.allows(kind, file)) { res.writeHead(403).end('Not available.'); return; }
+  let stat;
+  try { stat = await fs.promises.stat(file); } catch { res.writeHead(404).end('Not there.'); return; }
+  if (!stat.isFile()) { res.writeHead(404).end('Not there.'); return; }
+  const media = mediaType(file);
+  if (media) {
+    const out = await mediaResponse(file, req.headers.range);
+    res.writeHead(out.status, { ...Object.fromEntries(out.headers), 'cache-control': 'no-store' });
+    if (out.body) Readable.fromWeb(out.body).pipe(res); else res.end();
+    return;
+  }
+  res.writeHead(200, {
+    'content-type': MIME[path.extname(file).toLowerCase()] ?? 'application/octet-stream',
+    'content-length': String(stat.size),
+    'cache-control': 'no-store',
+  });
+  fs.createReadStream(file).pipe(res);
+}
+
 /**
  * Serve one built renderer and one channel endpoint.
  *
@@ -222,10 +287,27 @@ const MIME = {
  *  `listeners` is the Set off `broadcastingWindow`, which is where the pushes
  *  going the other way are waiting for somewhere to go.
  */
-export function createServer({ channels, token, listeners = new Set(), dist = path.join(repoRoot, 'renderer', 'dist') }) {
-  return http.createServer(async (req, res) => {
+export function createServer(options) {
+  return http.createServer(createHandler(options));
+}
+
+/**
+ * The same door as a bare request handler, so main/phone-link.mjs can put its
+ * own server in front of it. `token` may be a function, read on every request,
+ * so a key that is reset stops working at once.
+ */
+export function createHandler({ channels, token, listeners = new Set(), dist = path.join(repoRoot, 'renderer', 'dist'), files = null }) {
+  return async (req, res) => {
     const url = new URL(req.url, 'http://127.0.0.1');
 
+    // A file for the phone, behind the file key rather than the phone's own.
+    // Only a server that was handed `files` has any to give.
+    if (url.pathname.startsWith('/f/')) {
+      if (!files) { res.writeHead(404).end('No files here.'); return; }
+      await answerFile(req, res, url, { token, files });
+      return;
+    }
+
     // The token rides in a header on api calls and in the query on the event
     // stream, because a browser cannot put a header on either a navigation or
     // an EventSource. It guards the two doors that reach the store. The built
@@ -234,14 +316,21 @@ export function createServer({ channels, token, listeners = new Set(), dist = pa
     // NOR DOES THE PAGE ITSELF ASK: the tab takes the token out of its address
     // bar on load, so a reload asks for `/` bare, and refusing that drew
     // "Wrong or missing token" on every reload (tests/a-browser-tab-survives-a-reload).
-    const guarded = url.pathname === '/events' || url.pathname.startsWith('/api/');
+    const guarded = url.pathname === '/events' || url.pathname.startsWith('/api/') || url.pathname === '/file-key';
     const given = req.headers['x-agentbox-token'] || url.searchParams.get('token');
-    if (guarded && given !== token) {
+    if (guarded && !sameKey(given, typeof token === 'function' ? token() : token)) {
       res.writeHead(403, { 'content-type': 'text/plain' });
       res.end('Wrong or missing token. Use the url the terminal printed.');
       return;
     }
 
+    // The phone asks for its file key once, with its own key.
+    if (url.pathname === '/file-key') {
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      res.end(JSON.stringify({ key: fileKey(typeof token === 'function' ? token() : token) }));
+      return;
+    }
+
     // The phone line left open. Seven channels talk the other way, main to
     // screen, and every one of them is one-way, so this is an event stream
     // rather than a websocket: the same job with no dependency to add.
@@ -316,7 +405,19 @@ export function createServer({ channels, token, listeners = new Set(), dist = pa
       res.writeHead(200, { 'content-type': MIME[path.extname(file)] ?? 'application/octet-stream' });
       res.end(buf);
     });
-  });
+  };
+}
+
+/**
+ * The key a request carries against the real one, in the same time whatever
+ * it gets right, so nobody can learn the key a character at a time by timing
+ * the refusals. Both sides are hashed first because a length that differs is
+ * itself a thing `timingSafeEqual` would refuse at once.
+ */
+export function sameKey(given, key) {
+  if (typeof given !== 'string' || typeof key !== 'string' || !given || !key) return false;
+  const digest = (s) => crypto.createHash('sha256').update(s).digest();
+  return crypto.timingSafeEqual(digest(given), digest(key));
 }
 
 function readBody(req) {
@@ -324,9 +425,12 @@ function readBody(req) {
     let body = '';
     req.on('data', (c) => {
       body += c;
-      // A screen never posts anything large; the uploads go through their own
-      // channels. This is here so a stuck client cannot eat the process.
-      if (body.length > 8 * 1024 * 1024) reject(new Error('Body too large'));
+      // This is here so a stuck client cannot eat the process. A PHONE'S
+      // UPLOADS DO COME THROUGH HERE, though: it has no file paths, so a
+      // picture is posted whole, as base64, to zero:stage-attachment. 8 MB of
+      // that was a 6 MB photo; an iPhone's is often more (2026-10-12). The
+      // relay passes up to 32 MB (relay/worker.mjs).
+      if (body.length > 32 * 1024 * 1024) reject(new Error('Body too large'));
     });
     req.on('end', () => resolve(body));
     req.on('error', reject);