agentbox-app 0.1.13 → 0.1.16

package/main/artifact-path.mjs

@@ -66,28 +66,55 @@ export function artifactRoots(prod) {
 // now resolves by exact path or not at all.
 const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'sessions', 'runs', 'pending-writes', 'checkpoints']);
 
-// Hunt the file down by NAME inside one product's trees, newest match wins.
-// Workers write links relative to whatever directory they were standing in, so
-// a fixed root list will always miss some of them, and every miss cost her a
-// 10-minute detour (2026-08-05). Bounded: six levels, own product only.
-function huntByName(base, roots, fs) {
-  let best = null;
-  const walk = (dir, depth) => {
+// How long one walk of a tree answers for it. A thread asks for every name it
+// mentions the moment it opens, so the walk has to outlive that burst; a
+// picture that lands later is found by the next look, which comes after this.
+export const HUNT_FRESH_MS = 5000;
+const walks = new Map();
+
+// Every file name in one tree, read without holding the main process.
+async function walkNames(tree, fs) {
+  const names = new Map();
+  const walk = async (dir, depth) => {
     if (depth > 6) return;
     let entries;
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    try { entries = await fs.promises.readdir(dir, { withFileTypes: true }); } catch { return; }
+    const below = [];
     for (const e of entries) {
       if (e.name.startsWith('.')) continue;
       const full = path.join(dir, e.name);
-      if (e.isDirectory()) { if (!SKIP.has(e.name)) walk(full, depth + 1); }
-      else if (e.name === base) {
-        let m = 0;
-        try { m = fs.statSync(full).mtimeMs; } catch {}
-        if (!best || m > best.m) best = { full, m };
-      }
+      if (e.isDirectory()) { if (!SKIP.has(e.name)) below.push(walk(full, depth + 1)); }
+      else if (names.has(e.name)) names.get(e.name).push(full);
+      else names.set(e.name, [full]);
     }
+    await Promise.all(below);
   };
-  for (const root of roots) walk(root, 0);
+  await walk(tree, 0);
+  return names;
+}
+
+function namesIn(tree, fs, now) {
+  const kept = walks.get(tree);
+  if (kept && kept.fs === fs && now - kept.at < HUNT_FRESH_MS) return kept.names;
+  const names = walkNames(tree, fs);
+  walks.set(tree, { at: now, fs, names });
+  if (walks.size > 32) walks.delete(walks.keys().next().value);
+  return names;
+}
+
+// Hunt the file down by NAME inside one product's trees, newest match wins.
+// Workers write links relative to whatever directory they were standing in, so
+// a fixed root list will always miss some of them, and every miss cost her a
+// 10-minute detour (2026-08-05). Bounded: six levels, own product only.
+async function huntByName(base, trees, fs, now) {
+  let best = null;
+  for (const tree of trees) {
+    for (const full of (await namesIn(tree, fs, now)).get(base) ?? []) {
+      let m;
+      try { m = (await fs.promises.stat(full)).mtimeMs; } catch { continue; }
+      if (!best || m > best.m) best = { full, m };
+    }
+  }
   return best?.full ?? null;
 }
 
@@ -104,7 +131,7 @@ export function notFoundMessage(raw, own, product) {
 //
 // `products` is the whole list only so the card's own product can be found in
 // it. Nothing in here reads another entry.
-export function resolveArtifact({ src, product, products = [], accountRoot, storeRoot, fs = fsDefault }) {
+export async function resolveArtifact({ src, product, products = [], accountRoot, storeRoot, fs = fsDefault, now = Date.now() }) {
   if (typeof src !== 'string' || !src) return { ok: false, error: 'No file was named.' };
   const raw = decodeURIComponent(src.replace(/^file:\/\//, '')).replace(/^\.\//, '');
   const own = products.find((x) => x.slug === product) ?? null;
@@ -144,10 +171,12 @@ export function resolveArtifact({ src, product, products = [], accountRoot, stor
 
   // The hunt takes the two TREES, not the root list: designs/ and attachments/
   // sit inside the docs dir already, and walking them twice finds nothing new.
+  // A run's change record is never hunted for: `runs` is skipped, so the walk
+  // could not find it, and the open thread asks for it on every refresh.
   const base = path.basename(raw);
   const trees = own ? [own.dir, own.repoPath].filter(Boolean) : [];
-  if (base && trees.length) {
-    const found = huntByName(base, trees, fs);
+  if (base && trees.length && raw.split('/')[0] !== 'runs') {
+    const found = await huntByName(base, trees, fs, now);
     if (found) return { ok: true, path: found };
   }
 

package/main/claude-input.mjs

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { Name } from '../shared/product-name.mjs';
 
 // THE SESSION STOPPED LISTENING BEFORE IT TOOK THIS MESSAGE. Not a refusal:
 // the turn closed, or the process went, in the seconds between her pressing
@@ -16,6 +17,17 @@ function turnClosed(message) {
 // before the session is closed anyway. Measured wakes arrive in about a second.
 const WAKE_GRACE_MS = 2 * 60 * 1000;
 
+// Said to the agent, never shown to the person: the trace keeps no user turns.
+// Paths are cut to their last part: a cloud run's relay uploads any file its
+// input names outside the task folder (main/cloud/run.mjs `filesNamedIn`).
+export function stillRunningNote(tasks) {
+  const plain = (text) => String(text).replace(/(^|[\s"'`(=:])\/(?:[^\s"'`<>()[\]{},;\\]*\/)+/g, '$1');
+  const names = tasks.map((t) => `"${plain(t.description || t.task_id).slice(0, 120)}"`).join(', ');
+  return `This is ${Name}, not the person. Your turn ended with ${tasks.length === 1 ? 'this' : 'these'} still running in the background: ${names}. `
+    + 'Your run stays open, and your answer is not delivered, until nothing you started is still running. '
+    + 'Stop any you no longer need. If you are waiting on one, say what for in one line and end your turn.';
+}
+
 // THE PROMPT LEAVES THE LINE WHEN REPLIES ARRIVE ON STDIN. Both the print flag
 // and the input-format flags are read off the engine's `run` definition, so an
 // engine of this family that spells either of them differently is a definition
@@ -45,13 +57,35 @@ export function attachClaudeInput(child) {
   // end of the run, and closing there killed the suite it was waiting on
   // (tests/an-agent-waiting-on-its-own-tests-does-not-come-back-to-you).
   let waiting = [], wakeTimer = null;
+  // Jobs the agent has been told are still out, and the messages that told it.
+  // A forgotten job holds a finished answer until Claude Code's own limit
+  // stops it, thirty minutes and more
+  // (tests/a-command-an-agent-left-running-does-not-hold-its-answer-back).
+  const named = new Set(), ours = new Set();
   // Input only ever closes at a result with nothing out, so a closed input is
   // the one proof the run reached its end. A session that exits with input
   // still open was stopped part-way, whatever its last turn said
   // (tests/a-worker-whose-helpers-are-still-working-does-not-come-back-to-you).
   let ended = false;
+  // A TURN IS RUNNING between its `system/init` and its result. A message
+  // written while none is starts the next one, and a turn that starts while
+  // one waits takes it with it, so either way it is being answered, though
+  // Claude replays it only when that turn first speaks. Send now must not cut
+  // that turn: it was the answer (w-0202576e73).
+  let inTurn = false;
   const closeInput = () => { closed = true; ended = true; clearTimeout(wakeTimer); child.stdin.end(); };
   const mayClose = () => !held && atResult && !pending.size && !waiting.length;
+  // Not into a session she is driving, and not when her own message is about
+  // to start the next turn. Kept out of `pending`, so it never holds input open.
+  const nameWhatIsStillOut = () => {
+    if (closed || held || pending.size || !waiting.some((t) => t?.task_id && !named.has(t.task_id))) return;
+    for (const t of waiting) if (t?.task_id) named.add(t.task_id);
+    const uuid = randomUUID();
+    ours.add(uuid);
+    try {
+      child.stdin.write(JSON.stringify({ type: 'user', uuid, message: { role: 'user', content: stillRunningNote(waiting) }, parent_tool_use_id: null, session_id: '' }) + '\n');
+    } catch { /* the input is gone; `fail` hears it */ }
+  };
   const fail = reason => {
     closed = true;
     for (const request of pending.values()) {
@@ -81,12 +115,20 @@ export function attachClaudeInput(child) {
         }
       }
       if (event.type === 'system' && event.subtype === 'bridge_state') child.emit('bridge-state', event);
-      if (event.type === 'assistant') atResult = false;
+      // A cloud run whose input the sandbox closed at the end of its turn
+      // while this Mac slept (main/cloud/run.mjs): the end of the run, as if
+      // closed here. A reply still waiting is kept for the next run.
+      if (event.type === 'system' && event.subtype === 'agentbox_input_closed_in_cloud' && !closed) closeInput();
+      if (event.type === 'system' && event.subtype === 'init') {
+        inTurn = true;
+        for (const request of pending.values()) request.taken = true;
+      }
+      if (event.type === 'assistant') { atResult = false; inTurn = true; }
       if (event.type === 'user' && !event.parent_tool_use_id && typeof event.uuid === 'string' && !seenUsers.has(event.uuid)) {
         seenUsers.add(event.uuid);
         const content = event.message?.content;
         const text = typeof content === 'string' ? content : Array.isArray(content) ? content.filter(b => b.type === 'text').map(b => b.text).join('\n') : '';
-        if (held && !pending.has(event.uuid) && text && !event.isMeta) child.emit('remote-user', event);
+        if (held && !pending.has(event.uuid) && !ours.has(event.uuid) && text && !event.isMeta) child.emit('remote-user', event);
         if (text) { atResult = false; child.emit('input-turn', event); }
       }
       if (event.type === 'user' && pending.has(event.uuid)) {
@@ -109,7 +151,9 @@ export function attachClaudeInput(child) {
       }
       if (event.type === 'result') {
         atResult = true;
+        inTurn = false;
         if (mayClose()) closeInput();
+        else if (waiting.length) nameWhatIsStillOut();
       }
     }
   });
@@ -136,7 +180,7 @@ export function attachClaudeInput(child) {
   // ONLY WHILE A MESSAGE OF HERS IS WAITING. The cut turn ends in a result,
   // and with nothing pending that result closes the input and ends the run.
   child.interrupt = () => {
-    if (closed || !pending.size) return Promise.resolve({ interrupted: false });
+    if (closed || ![...pending.values()].some(request => !request.taken)) return Promise.resolve({ interrupted: false });
     child.lastInterruptAt = Date.now();
     return child.control({ subtype: 'interrupt' }).then(() => ({ interrupted: true }));
   };
@@ -153,7 +197,7 @@ export function attachClaudeInput(child) {
   child.steer = text => new Promise((resolve, reject) => {
     if (closed || !child.stdin.writable) return reject(turnClosed('The turn has ended. Send the message again to continue it.'));
     const uuid = randomUUID();
-    pending.set(uuid, { resolve, reject });
+    pending.set(uuid, { resolve, reject, taken: !inTurn });
     try {
       child.stdin.write(JSON.stringify({ type: 'user', uuid, message: { role: 'user', content: text }, parent_tool_use_id: null, session_id: '' }) + '\n');
     } catch (error) {

package/main/claude-plan.mjs

@@ -96,8 +96,28 @@ export function isMaxTier(raw) {
  *  Claude Code has not fetched a profile for yet: all of them come back
  *  `known: false`, which every caller here treats as "leave everything exactly
  *  as it was". */
+const planCache = new Map();
+
 export function readPlan(profile, { home = os.homedir(), file = null } = {}) {
   const at = file ?? planFile(profile, home);
+  // Keyed on the file's mtime AND its size, as accountIdentity is keyed on the
+  // mtime alone: the cloud tiles ask on every snapshot.
+  //
+  // THE SIZE IS THERE BECAUSE AN MTIME CAN STAND STILL (w-dac993a554). Two
+  // writes inside one tick of the filesystem's clock carry the same mtime, and
+  // the cache then served the first one's plan for ever. A subscription
+  // renewed in that window read as ended until the file was written again, so
+  // `Supervisor#_forgetRenewedSubscriptions` never let the account back in.
+  let stat = null;
+  try { stat = fs.statSync(at); } catch { /* read below says none */ }
+  const hit = planCache.get(at);
+  if (stat && hit?.mtime === stat.mtimeMs && hit?.size === stat.size) return hit.plan;
+  const plan = readPlanNow(at);
+  if (stat) planCache.set(at, { mtime: stat.mtimeMs, size: stat.size, plan });
+  return plan;
+}
+
+function readPlanNow(at) {
   const none = { known: false, max: false, label: null, tier: null, from: null, file: at };
   let account = null;
   try {
@@ -128,6 +148,34 @@ export function readPlan(profile, { home = os.homedir(), file = null } = {}) {
   return { known: true, ended: false, max: isMaxTier(tier), label: planLabel(tier), tier, from, file: at };
 }
 
+/**
+ * WHICH ACCOUNT AND PLAN ONE LOGIN IS ON, as a string that changes only when
+ *  one of them does: an upgrade, extra usage switched on, a renewal, or a
+ *  /login as somebody else. Claude Code rewrites this file all day for other
+ *  reasons, so only these fields count (named as Claude Code 2.1.305 writes
+ *  them). Null when the file names no account or cannot be read.
+ */
+const PLAN_FIELDS = ['accountUuid', 'organizationUuid', 'organizationType', 'organizationRateLimitTier',
+  'userRateLimitTier', 'seatTier', 'billingType', 'hasExtraUsageEnabled', 'planDisplayName', 'subscriptionCreatedAt'];
+const stampCache = new Map();
+
+export function planStamp(profile, { home = os.homedir(), file = null } = {}) {
+  const at = file ?? planFile(profile, home);
+  let mtime;
+  try { mtime = fs.statSync(at).mtimeMs; } catch { return null; }
+  const hit = stampCache.get(at);
+  if (hit?.mtime === mtime) return hit.stamp;
+  let stamp = null;
+  try {
+    const account = JSON.parse(fs.readFileSync(at, 'utf8'))?.oauthAccount;
+    if (account?.accountUuid) {
+      stamp = JSON.stringify(PLAN_FIELDS.map((k) => (k === 'hasExtraUsageEnabled' ? account[k] === true : account[k] ?? null)));
+    }
+  } catch { /* half written: the next write has a new mtime and is read again */ }
+  stampCache.set(at, { mtime, stamp });
+  return stamp;
+}
+
 /**
  * THE PLAN ON EVERY ACCOUNT AGENTBOX IS CONFIGURED TO RUN ON, in the same order
  *  the supervisor round-robins them. */

package/main/claude-session-open.mjs

@@ -0,0 +1,28 @@
+// Whether Claude Code still has a session open somewhere, read off the state
+// file it keeps for each open session (`<home>/sessions/<pid>.json`, with the
+// session id and the pid holding it). A state file whose process has gone is a
+// session somebody closed.
+import fs from 'node:fs';
+import path from 'node:path';
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (err) { return err?.code === 'EPERM'; }
+}
+
+export function claudeSessionOpen(sessionId, homes = []) {
+  const id = String(sessionId ?? '').trim();
+  if (!id) return false;
+  for (const home of new Set(homes.filter(Boolean))) {
+    const dir = path.join(home, 'sessions');
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { continue; }
+    for (const name of names) {
+      if (!name.endsWith('.json')) continue;
+      let rec = null;
+      try { rec = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8')); } catch { continue; }
+      const pid = Number(rec?.pid);
+      if (rec?.sessionId === id && pid > 0 && alive(pid)) return true;
+    }
+  }
+  return false;
+}

package/main/claude-usage-process.mjs

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process';
+import { attachClaudeInput } from './claude-input.mjs';
+
+// No user message is submitted. The CLI owns authentication and the provider request.
+export function runClaudeUsage(bin, args, opts, done) {
+  let child, timer, killTimer, finished = false, bytes = 0;
+  const finish = (error, report = '') => {
+    if (finished) return;
+    finished = true;
+    clearTimeout(timer);
+    if (child?.exitCode == null && child?.pid) {
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), 1000);
+      killTimer.unref();
+    }
+    done(error, report);
+  };
+  try {
+    child = attachClaudeInput(spawn(bin, args, { cwd: opts.cwd, env: opts.env, stdio: ['pipe', 'pipe', 'ignore'] }));
+    child.holdInput(true);
+    child.once('error', error => finish(error));
+    child.once('exit', () => {
+      clearTimeout(killTimer);
+      finish(Error('Claude Code closed before reporting usage.'));
+    });
+    child.stdout.on('data', data => {
+      bytes += data.length;
+      if (bytes > opts.maxBuffer) finish(Error('Claude Code sent too much usage output.'));
+    });
+    timer = setTimeout(() => finish(Error('Claude Code did not report usage in time.')), opts.timeout);
+    void (async () => {
+      try {
+        await child.control({ subtype: 'initialize' }, opts.timeout);
+        const report = await child.control({ subtype: 'get_usage', skip_behaviors: true }, opts.timeout);
+        finish(null, JSON.stringify(report));
+      } catch (error) { finish(error); }
+    })();
+  } catch (error) { finish(error); }
+  return child;
+}

package/main/claude-usage.mjs

@@ -1,40 +1,13 @@
-// RUNNING `/usage`, WHICH TAKES TWENTY-FIVE SECONDS AND MUST NEVER BE WAITED ON.
-//
-// The pure half is shared/claude-usage.mjs: the text in, the limits out, the
-// words the pill prints. This is the half that shells out, and everything about
-// its shape comes from one measurement.
-//
-// TIMED TWICE ON HER MAC, 2026-08-31: 23.2s and 28.0s for `claude -p '/usage'`.
-// The percentage did not move between the two, which is the other half of the
-// answer: this is not a number that changes second to second, so nothing is lost
-// by reading it every few minutes and everything is lost by reading it on a
-// timer the window waits for.
-//
-// SO IT IS A CACHE WITH A BACKGROUND REFRESH. Only the explicit Settings
-// refresh waits for a result; snapshots always return immediately:
-//
-//   - `read` answers instantly, always, from the last measurement or with null.
-//     It never blocks and never throws.
-//   - A refresh is kicked off when the cached figure is older than STALE_MS,
-//     and only ever one at a time.
-//   - The window is told when a new one lands, the same way everything else in
-//     this app tells it: a push.
-//
-// WHY NOT A SESSION. Agentbox spawns real workers through the supervisor and could
-// have asked one of them. It must not: a worker is a unit of her work, it lands
-// in her inbox and burns a slot in the fleet, and this is a status reading. It
-// gets its own short-lived child process with no store, no brief and no row.
-//
-// WHAT IS NOT SENT ANYWHERE. The output carries her usage figures and nothing
-// else leaves this machine because of it; `main/analytics.mjs` is the only file
-// that sends, and none of its eight counts is fed from here.
+// Cached provider usage, read through Claude Code without starting a model turn.
+// Snapshots never wait; only an explicit refresh waits for the CLI's answer.
 
-import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { readUsage } from '../shared/claude-usage.mjs';
+import { readUsageReport } from '../shared/claude-usage.mjs';
 import { localZone, USAGE_UNREADABLE } from '../shared/usage.mjs';
+import { runClaudeUsage } from './claude-usage-process.mjs';
+import { NO_METERED_KEY } from './harnesses/claude.mjs';
 
 // WHERE THE READING RUNS, AND WHY IT IS NOT "WHEREVER THE APP IS". An app
 // opened from Finder has `/` as its working directory, and this used to spawn
@@ -62,9 +35,7 @@ export function usageCwd() {
 // than the number itself is reported to.
 export const STALE_MS = 5 * 60_000;
 
-// Long enough for the slowest run measured plus most of the same again. Past
-// this the reading is not late, it is not coming.
-const TIMEOUT_MS = 90_000;
+const TIMEOUT_MS = 30_000;
 
 // After a failure, how long before it is worth trying again. A machine that is
 // signed out, rate limited, or has no Claude Code at all would otherwise be
@@ -87,7 +58,7 @@ export class ClaudeUsage {
    * the account's name ('default' or its CLAUDE_CONFIG_DIR) and `env` is the
    * environment to run it in. Supervisor.usageAccount is the real one.
    */
-  constructor({ bin, onChange = () => {}, run = execFile, now = () => Date.now(), where = usageCwd, account = () => ({ profile: 'default' }) } = {}) {
+  constructor({ bin, onChange = () => {}, run = runClaudeUsage, now = () => Date.now(), where = usageCwd, account = () => ({ profile: 'default' }) } = {}) {
     this._bin = bin;
     this._selectedProfile = null;
     this._generation = 0;
@@ -164,7 +135,7 @@ export class ClaudeUsage {
     const profile = this._syncProfile();
     const generation = this._generation;
     const bin = (() => { try { return this._bin(); } catch { return null; } })();
-    const failure = () => ({ ok: false, error: USAGE_UNREADABLE });
+    const failure = (error = USAGE_UNREADABLE) => ({ ok: false, error });
     if (!bin) { this._missed(); return Promise.resolve(failure()); }
     this._busy = true;
     this._pendingGeneration = generation;
@@ -178,8 +149,13 @@ export class ClaudeUsage {
       this._syncProfile();
       if (generation !== this._generation) { resolve(failure()); this._onChange(); return; }
       // Failed or unreadable output cannot acquire a fresh checked time.
-      const limits = err ? [] : readUsage(stdout, this._now(), localZone());
-      if (!limits.length) { this._missed(); resolve(failure()); return; }
+      const limits = err ? [] : readUsageReport(stdout, this._now());
+      if (!limits.length) {
+        this._missed();
+        const unsupported = /get_usage.*(?:not supported|unknown)|unknown.*get_usage/i.test(err?.message ?? '');
+        resolve(failure(unsupported ? 'Update Claude Code to read usage for this account.' : USAGE_UNREADABLE));
+        return;
+      }
       this._last = { limits, at: this._now(), zone: localZone(), profile };
       resolve({ ok: true, reading: this.peek() });
       // Even unchanged percentages now have a newly checked time to draw.
@@ -192,7 +168,9 @@ export class ClaudeUsage {
     if (profile !== 'default') env.CLAUDE_CONFIG_DIR = profile;
     try { this._run(
       bin,
-      ['-p', '/usage', '--output-format', 'text'],
+      ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
+        '--no-session-persistence', '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}', '--tools', '',
+        '--settings', JSON.stringify({ ...NO_METERED_KEY, disableAllHooks: true })],
       // `cwd` is the whole fix for the permission panels; see usageCwd above.
       { cwd: this._where(), env, timeout: TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024, encoding: 'utf8' },
       finish,

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 };
+}