agentbox-app 0.1.12 → 0.1.16

package/main/cloud/account.mjs

@@ -0,0 +1,179 @@
+// SIGNING IN TO AGENTBOX CLOUD FROM THIS MAC.
+//
+// A Google sign-in, through the database's own page, is traded once with the
+// cloud server (cloud/gateway/) for a cloud key, kept beside cloud.json; the
+// Mac's cloud.json then names the server, so its runs go there
+// (main/cloud/clients.mjs). The database session itself is not kept. A Mac
+// set up on its owner's own AWS account is never moved onto the server.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { cloudConfigPath, readCloudConfig, readCloudKey, writeCloudKey, cloudKeyPath, cloudAccountConfig, forgetCloudKey } from './config.mjs';
+import { withDeadline, plainAuthError } from '../team/session.mjs';
+import { signInWithGoogle, cancelGoogleSignIn } from '../team/sign-in.mjs';
+import { Name } from '../../shared/product-name.mjs';
+
+const CALL_MS = 30_000;
+const RETURN_URL = 'http://127.0.0.1:54783/auth/callback';
+
+export { cloudAccountConfig };
+
+async function ask(gateway, route, { method = 'GET', key, body } = {}) {
+  const init = { method, headers: { ...(key ? { authorization: `Bearer ${key}` } : {}), ...(body ? { 'content-type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined };
+  const res = await fetch(`${gateway.replace(/\/+$/, '')}${route}`, { ...init, signal: AbortSignal.timeout(CALL_MS) });
+  return { status: res.status, body: await res.json().catch(() => ({})) };
+}
+
+/** The version of the terms a person accepts now. */
+export async function currentCloudTerms(config) {
+  return (await ask(config.gateway, '/v1/terms')).body.terms ?? null;
+}
+
+/**
+ * The ways in that the app's sign-in page offers (team/SignInPage.tsx):
+ * Google, an email and a password, or a new account. Each gives the access
+ * token of a fresh sign-in, held in memory only: the cloud key is what this
+ * Mac keeps, so nothing asks the keychain.
+ */
+export function cloudAccountSession({ config, openExternal, log = () => {}, createClient = null }) {
+  let lastUrl = null;
+  const client = async () => {
+    const make = createClient || (await import('@supabase/supabase-js')).createClient;
+    const mem = new Map();
+    return make(config.supabaseUrl, config.anonKey, {
+      auth: { flowType: 'pkce', persistSession: true, autoRefreshToken: false, storage: { getItem: (k) => mem.get(k) ?? null, setItem: (k, v) => mem.set(k, v), removeItem: (k) => mem.delete(k) } },
+      global: { fetch: withDeadline() },
+    });
+  };
+  const tokenOf = (data) => {
+    if (!data?.session?.access_token) throw new Error('Signing in came back without a session. Try again.');
+    return data.session.access_token;
+  };
+  return {
+    async google() {
+      const c = await client();
+      await signInWithGoogle({ client: c, openExternal, returnUrl: config.signInReturn || RETURN_URL, log, onUrl: (u) => { lastUrl = u; } });
+      return tokenOf((await c.auth.getSession()).data);
+    },
+    async email(email, password) {
+      const { data, error } = await (await client()).auth.signInWithPassword({ email: String(email ?? '').trim(), password: String(password ?? '') });
+      if (error) throw new Error(plainAuthError(error.message));
+      return tokenOf(data);
+    },
+    // With confirmation on, a new account has no session until its email's
+    // link is followed: null, and the page says to check the inbox.
+    async signUp({ name, email, password }) {
+      const { data, error } = await (await client()).auth.signUp({
+        email: String(email ?? '').trim(), password: String(password ?? ''),
+        options: { data: { full_name: String(name ?? '').trim() || undefined } },
+      });
+      if (error) throw new Error(plainAuthError(error.message));
+      return data?.session?.access_token ?? null;
+    },
+    cancel: () => cancelGoogleSignIn(),
+    reopen: () => (lastUrl ? openExternal(lastUrl) : null),
+  };
+}
+
+/**
+ * One press on the sign-in page, to a cloud key. It agrees to the current
+ * terms only when the page showed them (`acceptTerms`, and every new account);
+ * otherwise a person who never agreed gets `needsTerms`, and `agree` finishes
+ * that same sign-in once they do.
+ */
+export async function cloudSignIn({ config, session, method, email, password, name, acceptTerms = false, env = process.env, home = os.homedir() }) {
+  let token;
+  let agreeing = acceptTerms;
+  try {
+    if (method === 'google') token = await session.google();
+    else if (method === 'email') token = await session.email(email, password);
+    else if (method === 'sign-up') {
+      agreeing = true;
+      token = await session.signUp({ name, email, password });
+      if (!token) return { ok: true, confirm: true };
+    } else if (method === 'agree') {
+      token = session.held;
+      agreeing = true;
+      if (!token) return { ok: false, error: 'Sign in again to finish.' };
+    } else return { ok: false, error: 'No such way to sign in.' };
+  } catch (err) {
+    return { ok: false, error: err?.message || String(err), ...(err?.cancelled ? { cancelled: true } : {}) };
+  }
+  session.held = token;
+  const acceptedTerms = agreeing ? await currentCloudTerms(config) : undefined;
+  const out = await signInToCloud({ config, acceptedTerms, googleSignIn: async () => token, env, home });
+  if (out.ok) { session.held = null; return out; }
+  if (out.error === 'terms' && !agreeing) return { ok: false, needsTerms: true, terms: out.terms ?? null };
+  return { ok: false, error: out.message || out.error };
+}
+
+// `googleSignIn` gives the access token of whichever sign-in the page made.
+export async function signInToCloud({ config, acceptedTerms, name = os.hostname(), env = process.env, home = os.homedir(), googleSignIn }) {
+  const now = readCloudConfig(env, home);
+  if (now?.bucket) return { ok: false, error: 'own-aws', message: 'This Mac runs the cloud in its own AWS account.' };
+  let token;
+  try { token = await googleSignIn(); } catch (err) { return { ok: false, error: 'google', message: err?.message || String(err) }; }
+  const made = await ask(config.gateway, '/v1/devices', { method: 'POST', key: token, body: { acceptedTerms, name: String(name).slice(0, 80) } });
+  if (made.status !== 200 || !made.body.key) return { ok: false, error: made.body.error || 'refused', message: made.body.message || `the cloud said ${made.status}`, ...(made.body.terms ? { terms: made.body.terms } : {}) };
+  writeCloudKey(made.body.key, env, home);
+  const file = cloudConfigPath(env, home);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ gateway: config.gateway }, null, 2) + '\n', { mode: 0o600 });
+  const me = await ask(config.gateway, '/v1/me', { key: made.body.key });
+  return { ok: true, ...(me.status === 200 ? me.body : {}) };
+}
+
+// The server's cloud and this Mac's key for it, or null when signed out.
+function signedIn(env, home) {
+  const gateway = readCloudConfig(env, home)?.gateway;
+  const key = gateway ? readCloudKey(env, home) : null;
+  return key ? { gateway, key } : null;
+}
+
+/** The plan, its agents and hours, and what is used, as the server counts them. */
+export async function cloudPlan({ env = process.env, home = os.homedir() } = {}) {
+  const at = signedIn(env, home);
+  if (!at) return { signedIn: false };
+  const me = await ask(at.gateway, '/v1/me', { key: at.key });
+  if (me.status === 401) forgetCloudKey(at.key, env, home);
+  return me.status === 200 ? { signedIn: true, ...me.body } : { signedIn: me.status !== 401, error: me.body.error || 'refused', message: me.body.message };
+}
+
+/** End every other Mac's cloud key, for a Mac that was lost; this one stays signed in. */
+export async function signOutOtherMacs({ env = process.env, home = os.homedir() } = {}) {
+  const at = signedIn(env, home);
+  if (!at) return { ok: false, error: 'signed-out', message: `Sign in to ${Name} Cloud first.` };
+  const out = await ask(at.gateway, '/v1/devices', { method: 'DELETE', key: at.key, body: { others: true } });
+  if (out.status === 401) forgetCloudKey(at.key, env, home);
+  return out.status === 200 ? { ok: true } : { ok: false, error: out.body.error || 'refused', message: out.body.message || `the cloud said ${out.status}` };
+}
+
+// Only Stripe's own two pages are opened: whatever else a server answers stays shut.
+const STRIPE_PAGE = /^https:\/\/(checkout|billing)\.stripe\.com\//;
+
+async function openStripe(route, body, openExternal, env, home) {
+  const at = signedIn(env, home);
+  if (!at) return { ok: false, error: 'signed-out', message: `Sign in to ${Name} Cloud first.` };
+  const out = await ask(at.gateway, route, { method: 'POST', key: at.key, body });
+  if (out.status !== 200) return { ok: false, error: out.body.error || 'refused', message: out.body.message || `the cloud said ${out.status}` };
+  if (typeof out.body.url !== 'string' || !STRIPE_PAGE.test(out.body.url)) return { ok: false, error: 'not-stripe', message: 'The cloud answered with a page that is not Stripe\'s.' };
+  await openExternal(out.body.url);
+  return { ok: true, ...(out.body.where ? { where: out.body.where } : {}) };
+}
+
+/** Stripe's checkout for a plan, in the browser; the billing page for someone already paying. */
+export const payForCloud = ({ plan, openExternal, env = process.env, home = os.homedir() }) => openStripe('/v1/checkout', { plan }, openExternal, env, home);
+
+/** Stripe's billing page: change plan, cancel, the card, invoices. */
+export const openCloudBilling = ({ openExternal, env = process.env, home = os.homedir() }) => openStripe('/v1/billing', {}, openExternal, env, home);
+
+/** Let this Mac's cloud key go, there and here. An own-AWS setup is left alone. */
+export async function signOutOfCloud({ env = process.env, home = os.homedir() } = {}) {
+  const now = readCloudConfig(env, home);
+  if (!now?.gateway) return { ok: true };
+  const key = readCloudKey(env, home);
+  if (key) await ask(now.gateway, '/v1/devices', { method: 'DELETE', key }).catch(() => {});
+  fs.rmSync(cloudKeyPath(env, home), { force: true });
+  fs.rmSync(cloudConfigPath(env, home), { force: true });
+  return { ok: true };
+}

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`;