agentbox-app 0.1.13 → 0.1.16

package/main/cloud/aws.mjs

@@ -0,0 +1,127 @@
+// THE TWO THINGS A CLOUD RUN NEEDS FROM AWS, AND NOTHING ELSE.
+//
+// main/cloud/run.mjs is written against two small interfaces so a test can
+// run it against the real sandbox server on this machine (see
+// tests/a-cloud-run-brings-the-agents-work-home.test.mjs). These are the real
+// ones: the AgentCore session (invoke, stop) and the S3 bucket (put, get, and
+// the presigned links the sandbox uses, so it holds no AWS rights of its own).
+//
+// They sign as the `agentbox-cloud` profile that scripts/cloud-setup.mjs made:
+// an IAM user that may only start and stop sessions on one runtime and read
+// and write one bucket's `runs/`. Never the 12-hour admin sign-in.
+import { BedrockAgentCoreClient, InvokeAgentRuntimeCommand, StopRuntimeSessionCommand } from '@aws-sdk/client-bedrock-agentcore';
+import {
+  S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, HeadObjectCommand,
+  CreateMultipartUploadCommand, UploadPartCopyCommand, UploadPartCommand, CompleteMultipartUploadCommand,
+} from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import fs from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+
+// A link the sandbox uses must outlive the longest run (8 hours) plus the
+// upload at its end, with room to spare.
+const LINK_SECONDS = 12 * 60 * 60;
+
+// A request that hangs is retried by the caller; one that never returns would
+// freeze the run. The SDK only warns at its request timeout unless told to
+// throw. Minutes, not seconds: sending a run's code up and a cold start both
+// take longer than a minute, and a minute's limit killed every such run.
+const TIMEOUT_MS = 5 * 60_000;
+const COPY_PIECE_BYTES = 32 * 1024 * 1024;
+
+// The byte ranges `extend` copies a `size`-byte base in: each at least `piece`
+// long, so never under S3's 5 MiB, and together exactly the base.
+export function copyRanges(size, piece = COPY_PIECE_BYTES) {
+  const pieces = Math.max(1, Math.floor(size / piece));
+  const each = Math.ceil(size / pieces);
+  return Array.from({ length: pieces }, (_, i) => `bytes=${i * each}-${Math.min(size, (i + 1) * each) - 1}`);
+}
+
+const http = (timeoutMs = TIMEOUT_MS) => ({ requestTimeout: timeoutMs, connectionTimeout: Math.min(10_000, timeoutMs), throwOnRequestTimeout: true });
+// `endpoint` and `credentials` are for tests, which stand in for AWS.
+const where = ({ endpoint, credentials }) => ({ ...(endpoint ? { endpoint } : {}), ...(credentials ? { credentials } : {}) });
+
+export function awsTransport({ region, runtimeArn, profile, endpoint, credentials, timeoutMs }) {
+  const client = new BedrockAgentCoreClient({ region, profile, requestHandler: http(timeoutMs), ...where({ endpoint, credentials }) });
+  return {
+    async invoke(sessionId, payload) {
+      const out = await client.send(new InvokeAgentRuntimeCommand({
+        agentRuntimeArn: runtimeArn,
+        runtimeSessionId: sessionId,
+        payload: Buffer.from(JSON.stringify(payload)),
+        contentType: 'application/json',
+        accept: 'application/json',
+      }));
+      const text = await out.response.transformToString();
+      return JSON.parse(text);
+    },
+    async stop(sessionId) {
+      await client.send(new StopRuntimeSessionCommand({ agentRuntimeArn: runtimeArn, runtimeSessionId: sessionId }));
+    },
+  };
+}
+
+export function awsStorage({ region, bucket, profile, endpoint, credentials, timeoutMs }) {
+  // WHEN_REQUIRED: by default the SDK now signs a checksum of the body into
+  // every upload link, which a link made before the body exists cannot match,
+  // so every upload from the sandbox would be refused.
+  const s3 = new S3Client({ region, profile, requestHandler: http(timeoutMs), requestChecksumCalculation: 'WHEN_REQUIRED', responseChecksumValidation: 'WHEN_REQUIRED', ...where({ endpoint, credentials }), ...(endpoint ? { forcePathStyle: true } : {}) });
+  return {
+    async put(key, body) {
+      await s3.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: body }));
+    },
+    async get(key) {
+      try {
+        const o = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+        return Buffer.from(await o.Body.transformToByteArray());
+      } catch (err) {
+        if (err?.name === 'NoSuchKey' || err?.$metadata?.httpStatusCode === 404) return null;
+        throw err;
+      }
+    },
+    // Straight to a file, a piece at a time; false when it is not there.
+    async getToFile(key, file) {
+      let o;
+      try { o = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })); } catch (err) {
+        if (err?.name === 'NoSuchKey' || err?.$metadata?.httpStatusCode === 404) return false;
+        throw err;
+      }
+      await pipeline(o.Body, fs.createWriteStream(file));
+      return true;
+    },
+    async putFile(key, file) {
+      await s3.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: fs.createReadStream(file), ContentLength: fs.statSync(file).size }));
+    },
+    // `key` made in the bucket as `base` (which is `start` bytes long)
+    // followed by `file` from byte `start`, so only that tail leaves this Mac.
+    // The base is copied in pieces at once: as one piece, 400 MiB took 11 s.
+    // An upload that fails part-way is cleared by the bucket's lifecycle rule
+    // (scripts/cloud-setup.mjs), as this login may not abort one.
+    async extend(key, base, file, start) {
+      const { UploadId } = await s3.send(new CreateMultipartUploadCommand({ Bucket: bucket, Key: key }));
+      const copied = await Promise.all(copyRanges(start).map((range, i) => s3.send(new UploadPartCopyCommand({
+        Bucket: bucket, Key: key, UploadId, PartNumber: i + 1, CopySource: `${bucket}/${base}`, CopySourceRange: range,
+      })).then((r) => ({ PartNumber: i + 1, ETag: r.CopyPartResult?.ETag }))));
+      const last = copied.length + 1;
+      const length = fs.statSync(file).size - start;
+      const tail = await s3.send(new UploadPartCommand({ Bucket: bucket, Key: key, UploadId, PartNumber: last, Body: fs.createReadStream(file, { start }), ContentLength: length }));
+      await s3.send(new CompleteMultipartUploadCommand({
+        Bucket: bucket, Key: key, UploadId,
+        MultipartUpload: { Parts: [...copied, { PartNumber: last, ETag: tail.ETag }] },
+      }));
+    },
+    // Whether an object is there, without reading it.
+    async exists(key) {
+      try { await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key })); return true; } catch (err) {
+        if (err?.name === 'NotFound' || err?.$metadata?.httpStatusCode === 404) return false;
+        throw err;
+      }
+    },
+    async del(key) {
+      await s3.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+    },
+    getUrl: (key, seconds = LINK_SECONDS) => getSignedUrl(s3, new GetObjectCommand({ Bucket: bucket, Key: key }), { expiresIn: seconds }),
+    putUrl: (key, seconds = LINK_SECONDS) => getSignedUrl(s3, new PutObjectCommand({ Bucket: bucket, Key: key }), { expiresIn: seconds }),
+    headUrl: (key, seconds = LINK_SECONDS) => getSignedUrl(s3, new HeadObjectCommand({ Bucket: bucket, Key: key }), { expiresIn: seconds }),
+  };
+}

package/main/cloud/browser-return.mjs

@@ -0,0 +1,58 @@
+// THE BROWSER'S WAY BACK FROM OPENAI, TAKEN ON THIS COMPUTER FOR A CODEX
+// SIGN-IN THAT RUNS IN THE CLOUD.
+//
+// Codex's browser sign-in sends the browser back to the machine running
+// `codex login`, at 127.0.0.1:1455. The browser is here and the command is in
+// the cloud, so this listens on that address while she signs in and hands the
+// query on: what OpenAI documents doing over SSH for a remote machine. The
+// query is a one-time code only the cloud's Codex can spend (it alone holds
+// the PKCE secret); no login passes through here.
+import http from 'node:http';
+import { NAME } from '../../shared/product-name.mjs';
+
+// Where an OpenAI sign-in link sends the browser back, when that is this
+// computer's own address; null otherwise.
+export function wayBack(link) {
+  try {
+    const back = new URL(new URL(link).searchParams.get('redirect_uri') || '');
+    const port = Number(back.port);
+    if (back.protocol !== 'http:' || !['127.0.0.1', 'localhost'].includes(back.hostname) || !(port > 0)) return null;
+    return { port, path: back.pathname };
+  } catch {
+    return null;
+  }
+}
+
+const page = (ok) => {
+  const line = ok ? 'Signed in to Codex. You can close this tab.' : `That didn’t finish. Go back to ${NAME} and try again.`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${ok ? 'Signed in to Codex' : 'Codex sign-in'}</title>`
+    + '<style>:root{color-scheme:light dark}body{margin:0;min-height:100vh;display:grid;place-items:center;background:Canvas;color:CanvasText;font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",system-ui,sans-serif}p{margin:0 24px;text-align:center}</style>'
+    + `</head><body><p>${line}</p></body></html>`;
+};
+
+// Listens at `port` until closed; anything but `path` is not found, including
+// the /cancel a local `codex login` sends whatever holds its port.
+// `onReturn(query)` says whether the cloud took it, and the browser is told.
+export function listenForWayBack({ port, path, onReturn }) {
+  // Every answer closes its connection, so closing the server lets the port
+  // go at once and still lets a page being answered reach the browser.
+  const server = http.createServer(async (req, res) => {
+    const u = new URL(req.url || '/', 'http://127.0.0.1');
+    if (req.method !== 'GET' || u.pathname !== path) {
+      res.writeHead(404, { 'content-type': 'text/plain', connection: 'close' });
+      res.end('Not Found');
+      return;
+    }
+    let ok = false;
+    try { ok = !!(await onReturn(u.search.slice(1))); } catch { /* told as not finished */ }
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', connection: 'close' });
+    res.end(page(ok));
+  });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve({ close() { server.close(); server.closeIdleConnections?.(); } });
+    });
+  });
+}

package/main/cloud/clients.mjs

@@ -0,0 +1,15 @@
+// The session and bucket clients a cloud run uses: the owner's own AWS
+// account, or the managed cloud's server. Loaded only when a run needs them,
+// so a Mac that never uses the cloud never loads AWS.
+import { readCloudKey, forgetCloudKey } from './config.mjs';
+
+export async function cloudClients(config, { env = process.env, home } = {}) {
+  if (typeof config?.gateway === 'string') {
+    const key = readCloudKey(env, home);
+    if (!key) throw new Error('this Mac has no cloud key yet; sign in for the cloud');
+    const { managedClients } = await import('./managed.mjs');
+    return managedClients({ url: config.gateway, key, onSignedOut: () => forgetCloudKey(key, env, home) });
+  }
+  const { awsTransport, awsStorage } = await import('./aws.mjs');
+  return { transport: awsTransport(config), storage: awsStorage(config) };
+}

package/main/cloud/codex-cloud.mjs

@@ -0,0 +1,53 @@
+// A CODEX WORKER WHOSE APP-SERVER IS IN THE CLOUD (docs/cloud/PLAN.md).
+//
+// On the Mac a Codex worker ends when its turn ends, and the folder already
+// holds its work. A cloud worker's turn ends in the sandbox, and its work
+// reaches the folder only after the proxy (main/cloud/run-cli.mjs) has
+// stopped the remote app-server, collected and imported. Everything that
+// reads the folder on exit (the change card, the ship queue, the next run)
+// must wait for that, so the worker's `exit` is held here until the proxy
+// process itself has exited (Codex's review, 2026-10-13, finding 1):
+//
+//   - the turn's own ending is kept, and the moment it happens the worker's
+//     input closes, its cards close (`onTurnEnd`), and the connection is
+//     closed, which stops the proxy and starts the homecoming;
+//   - a reply that arrives in that gap is refused as TURN_CLOSED, which is
+//     the contract main/live-replies.mjs already has for "too late for this
+//     turn": it is saved as an ordinary reply and carried by the next run;
+//   - when the proxy exits, the held ending goes out, unless the proxy said
+//     the work could not be brought home (75), or the account's cloud sign-in
+//     was missing, refused or ran out (77), each of which goes out as a
+//     transport fault: not a delivered reply, not an attempt spent.
+import { TURN_CLOSED } from '../claude-input.mjs';
+
+export const IMPORT_FAILED = 75;
+export const LOGIN_TROUBLE = 77;
+
+export function holdUntilHome({ worker, client, procExit, onTurnEnd = () => {} }) {
+  const realEmit = worker.emit.bind(worker);
+  let held = null;
+  worker.emit = (event, ...args) => {
+    if (event !== 'exit') return realEmit(event, ...args);
+    if (held) return true;
+    held = args; // [code, signal, how]
+    worker.steer = () => {
+      const err = new Error('The turn has ended; this reply will start the next one.');
+      err.code = TURN_CLOSED;
+      return Promise.reject(err);
+    };
+    try { onTurnEnd(); } catch { /* cards already gone */ }
+    try { client.close('the cloud run finished its turn'); } catch { /* already closed */ }
+    // A proxy that exits with a code finished: the code is the remote's, or
+    // 75 for work it could not bring home. One that was killed, or exited with
+    // no code at all, never said, so the work is not known to be home.
+    const notHome = (extra = {}) => realEmit('exit', IMPORT_FAILED, null, { ...(held[2] || {}), transportFault: true, ...extra });
+    Promise.resolve(procExit).then((out) => {
+      const code = out?.code;
+      if (code === LOGIN_TROUBLE) notHome({ cloudLoginTrouble: true });
+      else if (code === IMPORT_FAILED || !Number.isInteger(code) || out?.signal) notHome();
+      else realEmit('exit', ...held);
+    }, notHome);
+    return true;
+  };
+  return worker;
+}

package/main/cloud/config.mjs

@@ -0,0 +1,107 @@
+// WHERE A MAC'S CLOUD RUNS ARE SET UP, AND WHETHER THEY CAN RUN AT ALL.
+//
+// scripts/cloud-setup.mjs writes ~/.agentbox/cloud.json (the bucket, the
+// runtime, the profile it signs as); it is never in git, because it names an
+// AWS account. Each account's sign-in for the cloud is made and kept in the
+// cloud, never on this Mac (main/cloud/logins.mjs).
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Name } from '../../shared/product-name.mjs';
+
+// `home` is the supervisor's own idea of the home folder (config.home), so a
+// supervisor built for a test, with a home that is not the developer's, never
+// reads the developer's real setup.
+export function cloudConfigPath(env = process.env, home = os.homedir()) {
+  return env.AGENTBOX_CLOUD_CONFIG || path.join(home || os.homedir(), '.agentbox', 'cloud.json');
+}
+
+// Either the owner's own AWS account (bucket, runtime, region), or the
+// managed cloud's server (`gateway`, its address), whose key sits beside it.
+export function readCloudConfig(env = process.env, home = os.homedir()) {
+  try {
+    const c = JSON.parse(fs.readFileSync(cloudConfigPath(env, home), 'utf8'));
+    return (c?.bucket && c?.runtimeArn && c?.region) || typeof c?.gateway === 'string' ? c : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Where Agentbox Cloud is: the server's address and the database's public
+ * address and key. A checkout keeps it in cloud/, a Mac may keep its own
+ * copy, and a release build carries it baked into its package.json
+ * (scripts/release.mjs). All of them are out of git.
+ */
+export function cloudAccountConfig(appDir, { home = os.homedir() } = {}) {
+  const whole = (c) => typeof c?.gateway === 'string' && typeof c.supabaseUrl === 'string' && typeof c.anonKey === 'string';
+  for (const file of [path.join(appDir, 'cloud', 'cloud.public.json'), path.join(home, '.agentbox', 'cloud.public.json')]) {
+    try {
+      const c = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (whole(c)) return c;
+    } catch { /* try the next */ }
+  }
+  try {
+    const baked = JSON.parse(fs.readFileSync(path.join(appDir, 'package.json'), 'utf8')).bakedCloud;
+    if (whole(baked)) return baked;
+  } catch { /* none */ }
+  return null;
+}
+
+export const cloudKeyPath =(env = process.env, home = os.homedir()) => path.join(path.dirname(cloudConfigPath(env, home)), 'cloud-key');
+
+// WHAT THE CLOUD IMAGE SAID IT CAN DO at its last start, per cloud. A run can
+// only learn it from a start, so the next run reads what the last one heard;
+// an image rebuilt without something says so at its first start.
+const capsPath = (env, home) => path.join(path.dirname(cloudConfigPath(env, home)), 'cloud-image.json');
+const cloudId = (config) => String(config?.runtimeArn || config?.gateway || '');
+
+export function imageCaps(config, env = process.env, home = os.homedir()) {
+  try {
+    const caps = JSON.parse(fs.readFileSync(capsPath(env, home), 'utf8'))[cloudId(config)]?.caps;
+    return Array.isArray(caps) ? caps.filter((c) => typeof c === 'string') : [];
+  } catch { return []; }
+}
+
+export function noteImageCaps(config, caps, env = process.env, home = os.homedir()) {
+  const file = capsPath(env, home);
+  let all = {};
+  try { all = JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch { /* first */ }
+  const id = cloudId(config);
+  const now = [...new Set(caps)].sort();
+  if (JSON.stringify(all[id]?.caps) === JSON.stringify(now)) return;
+  all[id] = { caps: now, at: Date.now() };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(all, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+export function readCloudKey(env = process.env, home = os.homedir()) {
+  try { return fs.readFileSync(cloudKeyPath(env, home), 'utf8').trim() || null; } catch { return null; }
+}
+
+/**
+ * The server said this key is not known (it went unused, or another Mac
+ * signed this one out): this Mac is signed out of the cloud, as if by its own
+ * hand, so nothing keeps sending threads there with it. A key a newer sign-in
+ * put in its place is left alone.
+ */
+export function forgetCloudKey(key, env = process.env, home = os.homedir()) {
+  if (!key || readCloudKey(env, home) !== key) return false;
+  fs.rmSync(cloudKeyPath(env, home), { force: true });
+  if (typeof readCloudConfig(env, home)?.gateway === 'string') fs.rmSync(cloudConfigPath(env, home), { force: true });
+  return true;
+}
+
+export function writeCloudKey(key, env = process.env, home = os.homedir()) {
+  const file = cloudKeyPath(env, home);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, key, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+// The keychain service the first cloud build kept its own Claude tokens
+// under. Nothing writes it now; main/cloud/logins.mjs deletes what is left.
+export const OLD_TOKEN_SERVICE = `${Name} cloud: Claude sign-in`;

package/main/cloud/docs.mjs

@@ -0,0 +1,219 @@
+// THE PROJECT'S DOCUMENTS FOLDER, FOR A CLOUD RUN.
+//
+// A worker on this Mac reads the plans and notes in the project's documents
+// folder and writes its designs and reports there, where the app draws them.
+// A cloud run gets a copy at the same path: everything small, and this
+// thread's own designs folder, newest first, as much as fits. What it writes
+// there comes back while it works and once more at the end
+// (main/cloud/run.mjs), and is laid in here. Never a deletion, never over a
+// file someone changed on this Mac while the run was away, and never over one
+// the run did not take with it: those are kept, and the run's copy goes beside.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { run } from './exec.mjs';
+
+// The folders that hold pictures by the gigabyte. Only this thread's own
+// designs go up from them; the rest of the folder is small.
+const HEAVY = new Set(['designs', 'attachments']);
+export const DOCS_LIMITS = {
+  file: 256 * 1024,
+  ownFile: 25 * 1024 * 1024,
+  own: 50 * 1024 * 1024,
+  total: 100 * 1024 * 1024,
+  files: 5000,
+};
+
+const inside = (p, root) => p === root || p.startsWith(root + path.sep);
+
+/** The files, by path inside `dir`, that go up with a cloud run for `item`. */
+export function docsToSend(dir, { item = null, limits = DOCS_LIMITS } = {}) {
+  const own = item && /^[A-Za-z0-9_-]+$/.test(item) ? `designs/${item}` : null;
+  const picked = [];
+  let total = 0;
+  let ownTotal = 0;
+  const walk = (rel) => {
+    let entries = [];
+    try { entries = fs.readdirSync(path.join(dir, rel), { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (picked.length >= limits.files) return;
+      if (e.name.startsWith('.')) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (/[\n\r]/.test(r)) continue;
+      if (e.isDirectory()) {
+        if (!rel && HEAVY.has(e.name)) { if (own && e.name === 'designs') walkOwn(); continue; }
+        walk(r);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      let size;
+      try { size = fs.statSync(path.join(dir, r)).size; } catch { continue; }
+      if (size > limits.file || total + size > limits.total) continue;
+      picked.push(r);
+      total += size;
+    }
+  };
+  // Newest first: a thread whose designs do not all fit takes its latest
+  // work, and the rest stays on this Mac.
+  const walkOwn = () => {
+    const found = [];
+    const stack = [own];
+    while (stack.length) {
+      const rel = stack.shift();
+      let entries = [];
+      try { entries = fs.readdirSync(path.join(dir, rel), { withFileTypes: true }); } catch { continue; }
+      for (const e of entries) {
+        if (e.name.startsWith('.')) continue;
+        const r = `${rel}/${e.name}`;
+        if (/[\n\r]/.test(r)) continue;
+        if (e.isDirectory()) { stack.push(r); continue; }
+        if (!e.isFile()) continue;
+        let st;
+        try { st = fs.statSync(path.join(dir, r)); } catch { continue; }
+        if (st.size <= limits.ownFile) found.push({ r, size: st.size, at: st.mtimeMs });
+      }
+    }
+    found.sort((a, b) => b.at - a.at || a.r.localeCompare(b.r));
+    for (const f of found) {
+      if (picked.length >= limits.files) return;
+      if (ownTotal + f.size > limits.own) continue;
+      picked.push(f.r);
+      ownTotal += f.size;
+    }
+  };
+  walk('');
+  return picked;
+}
+
+/** Those files as one gzipped tar, paths inside `dir`. */
+export function tarDocs(dir, files) {
+  return run('tar', ['-czf', '-', '-C', dir, '--null', '-T', '-'], { input: files.join('\0') + '\0', encoding: null, env: { ...process.env, COPYFILE_DISABLE: '1' } });
+}
+
+const stampOf = (st) => `${st.size}:${Math.round(st.mtimeMs)}`;
+const hashOf = (body) => crypto.createHash('sha256').update(body).digest('hex');
+
+// `notes.md` -> `notes (cloud).md`, then `notes (cloud 2).md`, and so on.
+function besideName(file) {
+  const ext = path.extname(file);
+  const base = file.slice(0, file.length - ext.length);
+  for (let i = 1; ; i += 1) {
+    const p = `${base} (cloud${i > 1 ? ` ${i}` : ''})${ext}`;
+    if (!fs.existsSync(p)) return p;
+  }
+}
+
+/**
+ * Lay an archive of documents the run wrote into `dir`.
+ *
+ * `sentAt` is when the run left with the folder; `laid` is what earlier calls
+ * for the same run wrote, path -> { stamp, hash }, and is updated in place. A
+ * version this run already laid is never laid again: the run sends a file
+ * until the Mac confirms it, so the same one can arrive twice. Otherwise a file
+ * is written over only if it is missing here, unchanged here since the run
+ * left, or is still exactly what this run itself laid. Anything else is a
+ * change made on this Mac, and the run's copy goes beside it.
+ *
+ * `sent` is every path the run took with it. A file here that is not one of
+ * them was never the run's to change, however old it is, so its copy goes
+ * beside it too. A run recorded before the list was kept passes none.
+ */
+export async function layDocs({ tgz, dir, sentAt = 0, laid = {}, sent = null }) {
+  const took = sent ? new Set(sent) : null;
+  const out = { written: [], beside: [], moved: [] };
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agentbox-docs-'));
+  try {
+    // From a file, not a pipe: tar may stop reading at the archive's end
+    // marker, and a pipe it stopped reading fails the write (EPIPE) on a busy Mac.
+    const file = path.join(tmp, '.agentbox-docs.tgz');
+    fs.writeFileSync(file, tgz);
+    const into = path.join(tmp, 'docs');
+    fs.mkdirSync(into);
+    await run('tar', ['-xzf', file, '-C', into]);
+    fs.mkdirSync(dir, { recursive: true });
+    const root = fs.realpathSync(dir);
+    const files = [];
+    const walk = (rel) => {
+      for (const e of fs.readdirSync(path.join(into, rel), { withFileTypes: true })) {
+        const r = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory()) walk(r);
+        else if (e.isFile()) files.push(r);
+      }
+    };
+    walk('');
+    // The nearest folder that exists, after links, must be this one or in
+    // it: a link inside the folder never carries a file out of it.
+    const safeParent = (file) => {
+      let parent = path.dirname(file);
+      while (!fs.existsSync(parent)) parent = path.dirname(parent);
+      if (!inside(fs.realpathSync(parent), root)) return false;
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      return inside(fs.realpathSync(path.dirname(file)), root);
+    };
+    for (const rel of files) {
+      const asIs = path.join(root, rel);
+      let target = asIs;
+      const body = fs.readFileSync(path.join(into, rel));
+      const hash = hashOf(body);
+      if (laid[rel]?.hash === hash) continue;
+      // A file whose folder here is a link out of it is not dropped: it lands
+      // in a folder of its own, and the run's work is all still home.
+      if (!safeParent(target)) {
+        target = path.join(root, 'from-the-cloud', rel);
+        if (!safeParent(target)) throw new Error(`nowhere safe to put ${rel}`);
+        out.moved.push(path.relative(root, target));
+      }
+      let here = null;
+      try { here = fs.lstatSync(target); } catch { /* new */ }
+      // A link or a folder where the file goes is left as it is, and the
+      // run's copy goes beside it.
+      if (here && !here.isFile()) {
+        target = besideName(target);
+        out.beside.push(path.relative(root, target));
+        here = null;
+      }
+      if (here) {
+        // The same bytes already here: nothing to write. It becomes the run's
+        // only if the run took it or wrote it before, never a file left here.
+        if (here.size === body.length && fs.readFileSync(target).equals(body)) {
+          const owned = !took || took.has(rel) || !!laid[rel]?.stamp;
+          laid[rel] = { stamp: owned ? stampOf(here) : null, hash };
+          continue;
+        }
+        const mine = laid[rel]?.stamp === stampOf(here);
+        // Whole milliseconds on both sides: `sentAt` is a Date.now() and counts
+        // them, an mtime does not, so a file saved 0.7 ms before the run left
+        // read as newer than it and the run's own edit went beside a file
+        // nobody had touched.
+        const untouched = mine || (Math.floor(here.mtimeMs) <= sentAt && (!took || took.has(rel)));
+        if (!untouched) {
+          target = besideName(target);
+          out.beside.push(path.relative(root, target));
+        }
+      }
+      // A fresh name, made only if nothing is there: a link left at a name
+      // this could guess would otherwise be written through.
+      const part = path.join(path.dirname(target), `.agentbox-${crypto.randomUUID()}.part`);
+      fs.writeFileSync(part, body, { flag: 'wx' });
+      fs.renameSync(part, target);
+      if (target === asIs) out.written.push(rel);
+      laid[rel] = { stamp: target === asIs ? stampOf(fs.statSync(target)) : laid[rel]?.stamp ?? null, hash };
+    }
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+  return out;
+}
+
+/** The documents folder a run may take, or null: it must exist and must not hold, or sit in, the task folder. */
+export function docsFolderFor(docs, cwd) {
+  if (!docs || !path.isAbsolute(docs)) return null;
+  let real;
+  let realCwd;
+  try { real = fs.realpathSync(docs); realCwd = fs.realpathSync(cwd); } catch { return null; }
+  if (!fs.statSync(real).isDirectory()) return null;
+  if (inside(real, realCwd) || inside(realCwd, real)) return null;
+  return docs;
+}

package/main/cloud/exec.mjs

@@ -0,0 +1,27 @@
+// A command run without holding up this process, which every cloud run's relay
+// shares (./host.mjs): one run's git or tar must not stop the others.
+import { spawn } from 'node:child_process';
+
+// Resolves to stdout (a string, or a Buffer when `encoding` is null); rejects,
+// as execFileSync throws, with "Command failed: <command>" and its stderr.
+export function run(cmd, args, { cwd, env = process.env, input = null, encoding = 'utf8' } = {}) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try { child = spawn(cmd, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] }); } catch (err) { reject(err); return; }
+    const out = [];
+    const err = [];
+    child.stdout.on('data', (d) => out.push(d));
+    child.stderr.on('data', (d) => err.push(d));
+    child.on('error', reject);
+    child.on('close', (code, signal) => {
+      const stdout = Buffer.concat(out);
+      if (code === 0) { resolve(encoding ? stdout.toString(encoding) : stdout); return; }
+      const stderr = Buffer.concat(err).toString('utf8');
+      const e = new Error(`Command failed: ${cmd} ${args.join(' ')}\n${stderr}`);
+      Object.assign(e, { status: code, signal, stderr });
+      reject(e);
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(input ?? undefined);
+  });
+}