agentbox-app 0.1.7 → 0.1.12

package/main/config.mjs

@@ -11,7 +11,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { resolveClaudeBin, candidatePaths } from './claude-bin.mjs';
 import { resolveCodexBin } from './codex-bin.mjs';
-import { Name } from '../shared/product-name.mjs';
+import { defaultStoreRoot } from './store/home.mjs';
 import { readPlans, slotsForPlans } from './claude-plan.mjs';
 import { machineSlots } from './machine.mjs';
 import { effectiveProfiles } from './account-discovery.mjs';
@@ -34,14 +34,6 @@ const CONFIG_NAME = 'zero.config.json';
 export const DEFAULT_SESSIONS_AT_ONCE = 3;
 
 const DEFAULTS = {
-  // Where the inbox's own files live. WHICH FOLDER THIS SHOULD BE ON A
-  // STRANGER'S MAC IS NOT DECIDED HERE: it is the open question on.
-  //
-  // IT IS THE APP'S OWN NAME SINCE 2026-09-22, where it used to be an older
-  // product's. A real store is always named in the config, so this default is
-  // only ever the answer for an install carrying none, and renaming it moved
-  // no files: the folder it used to point at is untouched and still on disk.
-  storeRoot: path.join(os.homedir(), Name),
   // ONE ACCOUNT FOLDER PER INSTALL, AND NOBODY ELSE'S.
   //
   // This was a literal id for most of the app's life, which meant every copy
@@ -59,10 +51,30 @@ const DEFAULTS = {
   // How many sessions run at once. The queue absorbs the rest; when the plan
   // window caps out, a longer queue is the visible, benign failure mode.
   //
-  // THIS IS THE NUMBER FOR A MAX SUBSCRIPTION, which is the only kind this was
-  // ever chosen on. When nobody has set one, loadConfig below reads the plan
+  // THIS IS THE NUMBER FOR A MAX SUBSCRIPTION, the biggest plan. When nobody
+  // has set one, loadConfig below reads the plan
   // Claude Code is signed in on and lowers this for a smaller one.
   maxConcurrentSessions: DEFAULT_SESSIONS_AT_ONCE,
+  // LET AGENTBOX DECIDE HOW MANY RUN (w-e5225b62ba). On unless somebody has set
+  // a number themselves, which `loadConfig` works out below from whether one was
+  // ever written down. With it on, `maxConcurrentSessions` is not read at all:
+  // `Supervisor#_slotsPerAccount` asks main/machine.mjs for what this Mac
+  // carries and shares that out across the live accounts. `agentsNudge` is how
+  // many times "Something felt slow" has been pressed, and only ever subtracts.
+  agentsAuto: true,
+  agentsNudge: 0,
+  // HOLD HEAVY WORK WHEN MEMORY IS SHORT (w-3958c3753d). Off until somebody
+  // turns it on from the Agents page. With it on, every shell command a worker
+  // runs asks main/memory-gate-server.mjs first, and heavy ones wait their turn
+  // while the Mac is short of memory. `memoryGateSlots` is how many heavy
+  // commands may run at once; null is Auto, one per 8 GB.
+  memoryGate: false,
+  memoryGateSlots: null,
+  // STOP WHAT FINISHED AGENTS LEAVE RUNNING (main/leftovers.mjs). Its own
+  // switch, off until somebody turns it on; `cleanupLeftoversSince` is the
+  // moment they did, so nothing is stopped sooner than the idle time after it.
+  cleanupLeftovers: false,
+  cleanupLeftoversSince: null,
   // What spawned sessions are allowed to do. Left unset on purpose, because the
   // right default now depends on whether a store MCP server is present: see
   // Supervisor#sessionArgsFor. Setting it here still wins over that, which is
@@ -80,11 +92,9 @@ const DEFAULTS = {
   // PERSONAL PROJECTS AND THE DRIVE WERE BOTH DECLARED HERE AND BOTH ARE GONE
   // (w-d19d6d387c, 2026-09-22). A personal project ran its sessions on the
   // founder's message and nothing else, with no brief and no store; the drive
-  // asked "what next?" by itself on a project that had gone quiet. Hers, on
-  // the same day: "I would get rid of 'personal' as well. I think there is no
-  // case where we should ever have that", and "we should get rid of the code
-  // that self-drives the product entirely. That should never have existed
-  // anyway, especially because we're open sourcing it soon."
+  // asked "what next?" by itself on a project that had gone quiet. There is no
+  // case where a project should run without a brief and a store, and code that
+  // drives a product on its own does not belong in an open-source app.
   //
   // A config still carrying `personalProducts` or `driveEnabled` is not an
   // error; nothing reads either key now.
@@ -142,6 +152,19 @@ export function loadConfig(appDir, { home = os.homedir() } = {}) {
     else console.warn(`zero: could not read ${file}: ${err.message}`);
   }
   const config = { ...DEFAULTS, ...overrides, freshInstall: fresh };
+  // Where the inbox's own files live, when the file names no store. A path in
+  // the file always wins, including on Linux. The default is computed here, not
+  // at import: on Linux it is the XDG data directory, and on macOS a folder of
+  // the app's name. An import-time path cannot see the `home` a test passes,
+  // and it cannot see a blanked XDG_DATA_HOME.
+  //
+  // A stand-in home does not inherit this machine's XDG_DATA_HOME. That
+  // variable is an absolute path in the real home, and a throwaway asked with
+  // `{ home }` would otherwise open the real store.
+  if (typeof overrides.storeRoot !== 'string' || !overrides.storeRoot.trim()) {
+    const real = path.resolve(home) === path.resolve(os.homedir());
+    config.storeRoot = defaultStoreRoot({ home, env: real ? process.env : {} });
+  }
   // An older alias for `storeRoot` was read here until 2026-09-22. A config
   // still carrying only the old key falls through to the default now, which is
   // why the key was renamed in zero.config.json in the same step and not after
@@ -150,11 +173,20 @@ export function loadConfig(appDir, { home = os.homedir() } = {}) {
   // The account id, minted once per install. Written back immediately, because
   // a generated id that is not saved is a different id next launch and the
   // store would move out from under everything.
+  //
+  // AND A NEW INSTALL MAY CHOOSE CODEX FROM ITS FIRST LAUNCH (w-db6f5e331e).
+  // `engineChoice` is the moment from which a row may run on Codex; it exists
+  // so August rows in one old store never move engine unasked, and it could
+  // only be written by hand, so a new person with both engines never got
+  // Codex at all. A Mac with no config file has no old rows, so its first
+  // launch is that moment. An install with a config is left as it was.
+  const firstLaunch = fresh && !config.engineChoice ? new Date().toISOString() : null;
+  if (firstLaunch) config.engineChoice = firstLaunch;
   if (typeof config.accountId !== 'string' || !config.accountId) {
     config.accountId = crypto.randomUUID();
     try {
       fs.mkdirSync(path.dirname(file), { recursive: true });
-      fs.writeFileSync(file, `${JSON.stringify({ ...overrides, accountId: config.accountId }, null, 2)}\n`);
+      fs.writeFileSync(file, `${JSON.stringify({ ...overrides, accountId: config.accountId, ...(firstLaunch ? { engineChoice: firstLaunch } : {}) }, null, 2)}\n`);
     } catch (err) {
       console.warn(`zero: could not write the new account id to ${file}: ${err.message}`);
     }
@@ -205,6 +237,11 @@ export function loadConfig(appDir, { home = os.homedir() } = {}) {
   config.codexFound = codex.found;
   config.codexCertain = codex.certain !== false;
   config.codexFrom = codex.from;
+  // AND AN OLDER INSTALL WITH CODEX ON IT OPENS THE CHOICE TOO (w-d5d632e503).
+  // Only a Mac with no config file did, so a person who installed before
+  // that, or who added Codex later, never saw Codex anywhere. Written at the
+  // end, once `appDir` is on the config to save through.
+  const codexOpened = codexChoiceToOpen(config, codex.found);
   // HOW MANY AGENTS AT ONCE, WHEN NOBODY HAS SAID, IS THE PLAN AND THE MACHINE
   // TOGETHER. Somebody on a smaller plan gets several sessions started for them,
   // they all spend the same allowance, and what they see is agents that are slow
@@ -237,6 +274,16 @@ export function loadConfig(appDir, { home = os.homedir() } = {}) {
   // already in zero.config.json is untouched, for the same reason the plan cap
   // leaves it alone.
   config.machineSlots = machineSlots().slots;
+  // WHO IS DECIDING THE NUMBER, read off whether one was ever written down
+  // (w-e5225b62ba). A number in zero.config.json is somebody's own instruction
+  // about this Mac and keeps being obeyed; an install that never touched the
+  // stepper was already having its number filled in here, and Automatic is that
+  // same thing said out loud and kept up to date. An explicit `agentsAuto`
+  // outranks the guess, because turning Automatic back on after setting a number
+  // has to be possible.
+  if (typeof overrides.agentsAuto !== 'boolean') {
+    config.agentsAuto = typeof overrides.maxConcurrentSessions !== 'number';
+  }
   if (typeof overrides.maxConcurrentSessions !== 'number') {
     const plans = readPlans(effectiveProfiles(config.authProfiles, { home }), { home });
     const slots = slotsForPlans(plans, config.machineSlots);
@@ -254,9 +301,27 @@ export function loadConfig(appDir, { home = os.homedir() } = {}) {
   // Where the file is, so anything that edits a setting can write it back
   // without being handed appDir a second time.
   config.appDir = appDir;
+  if (codexOpened) {
+    try {
+      saveConfig(config, { engineChoice: codexOpened });
+    } catch (err) {
+      console.warn(`zero: could not open the Codex choice in ${file}: ${err.message}`);
+    }
+  }
   return config;
 }
 
+/**
+ * THE MOMENT TO OPEN THE CODEX CHOICE AT, OR NULL. Now, when Codex is found
+ *  and the key was never written. NOW is what keeps a row marked `codex` in
+ *  August on Claude Code: it was written before this moment, so it is stale
+ *  (`engineChoiceOnRowIsStale`). A moment already written is kept, and
+ *  `"engineChoice": false` written by hand keeps the choice shut. */
+export function codexChoiceToOpen(config, codexFound) {
+  if (!codexFound || config.engineChoice != null) return null;
+  return new Date().toISOString();
+}
+
 export function configFile(appDir) {
   return path.join(appDir, CONFIG_NAME);
 }

package/main/demo.mjs

@@ -34,9 +34,8 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { DEMO_DOCS, DEMO_ENV, DEMO_PRODUCTS, demoLedgerLines } from '../shared/demo-world.mjs';
 import { prepareHome } from '../shared/fresh-user-home.mjs';
-import { Name } from '../shared/product-name.mjs';
 import { relaunchCommand } from './fresh-user.mjs';
-import { encodeProjectPath, storeRootEnv } from './store/home.mjs';
+import { defaultStoreRoot, encodeProjectPath, storeRootEnv } from './store/home.mjs';
 import { NAME, nameSlug } from '../shared/product-name.mjs';
 
 /**
@@ -87,22 +86,21 @@ export function clearDemoHomes() {
 /**
  * Where the demo copy will keep its store, and where it will keep its own
  *  records. Both are derived from the throwaway home rather than configured,
- *  because the copy derives them the same way from the same home: `storeRoot`
- *  defaults to `<home>/<Name>` (main/config.mjs) and the app's home defaults
- *  to `<home>/.agentbox` (main/store/home.mjs).
+ *  because the copy derives them the same way from the same home. Both are
+ *  `defaultStoreRoot` for that home with no inherited data directory: on
+ *  macOS a folder of the app's name, on Linux the XDG path under the
+ *  throwaway. Passing the machine's XDG_DATA_HOME would seed the demo into
+ *  the real store.
  *
- *  THE FOLDER IS READ FROM THE SAME CONSTANT AS THAT DEFAULT, not spelled out
- *  again. It was the literal 'the app' mirroring what config.mjs then said,
- *  and when that default was renamed on 2026-09-22 this line went on pointing
- *  at the old folder: the demo copy would have written its store to one place
- *  and looked for it in another. Two literals that have to agree is the defect;
- *  one import is the fix. */
+ *  THE FOLDER IS THAT FUNCTION, not a second spelling of it. A literal next
+ *  to the default is how the demo once wrote its store in one place and
+ *  looked for it in another. */
 export function demoPaths(home) {
-  const storeRoot = path.join(home, Name);
+  const storeRoot = defaultStoreRoot({ home, env: {} });
   return {
     storeRoot,
     accountRoot: path.join(storeRoot, 'accounts', DEMO_ACCOUNT),
-    appHome: path.join(home, `.${nameSlug}`),
+    appHome: storeRoot,
   };
 }
 
@@ -192,7 +190,12 @@ export function seedDemoStore(home, { now = Date.now() } = {}) {
  *  standing in an invented store. */
 export function demoEnv(home, env = process.env) {
   const { appHome } = demoPaths(home);
-  return { ...env, HOME: home, CFFIXED_USER_HOME: home, ...storeRootEnv(appHome), [DEMO_ENV]: '1' };
+  const next = { ...env, HOME: home, CFFIXED_USER_HOME: home, ...storeRootEnv(appHome), [DEMO_ENV]: '1' };
+  // The copy's store is defaultStoreRoot of ITS home. The parent's
+  // XDG_DATA_HOME is the real data directory, and leaving it set points the
+  // demo at that directory. The other base directories go for the same reason.
+  for (const key of ['XDG_DATA_HOME', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME', 'XDG_CACHE_HOME']) delete next[key];
+  return next;
 }
 
 /**

package/main/dev-window.mjs

@@ -1,16 +1,16 @@
-// A HOT-RELOADING WINDOW MUST NOT BE THE ONE SHE WORKS IN.
+// A HOT-RELOADING WINDOW MUST NOT BE THE ONE THE USER WORKS IN.
 //
-// She was working in a window an agent had started against a vite dev server,
-// on her real store. Vite rebuilds that window whenever the source under it
-// changes, and the source under it is the checkout every agent shares: it was
-// checked out or merged five times in the eleven minutes before she wrote.
+// A window an agent starts against a vite dev server can end up running on the
+// real store. Vite rebuilds that window whenever the source under it changes,
+// and the source under it is the checkout every agent shares, which can be
+// checked out or merged several times in a few minutes.
 //
-// The one that gets her is a change to App.tsx that adds, removes or moves a
+// The change that hurts is one to App.tsx that adds, removes or moves a
 // hook, which is what a branch switch does to it. React Fast Refresh keeps a
 // component's state only while its hooks match, so App is rebuilt from nothing:
 // `snap` is null again, App.tsx draws `<div className="boot">the app</div>`, and
-// every child of App is thrown away and remade. That is the screen she means by
-// the zero loading page, and that is the artifact closing and reopening. The
+// every child of App is thrown away and remade. The window drops back to the
+// loading page, and an open artifact closes and reopens. The
 // page never navigates, which is why nothing in the dev server's log looked bad
 // enough to be it. Six triggers were measured against a real window and exactly
 // one was guilty: scripts/what-throws-her-out-of-agentbox.mjs.
@@ -25,7 +25,7 @@
 // WHAT IS STILL ALLOWED, because a guard that stops the work is a guard somebody
 // deletes:
 //
-//   Fixtures. Nothing in a fixtures window is hers, so there is nothing to be
+//   Fixtures. Nothing in a fixtures window is real, so there is nothing to be
 //   thrown out of, and this is what screenshot and proof scripts use.
 //
 //   A throwaway store. A script that points HOME at a temp directory has no

package/main/doc-scheme.mjs

@@ -124,3 +124,5 @@ export class DocGrants {
 // main/zoom-keys.mjs) scales the window, and the pane is an ordinary iframe in
 // that window, so an open file follows it like everything else. Do not put a
 // listener back into a served page: nothing is injected into a file she reads.
+// The one thing added to a page is its scrollbar's look, from outside and after
+// it is served, and frame-scrollbars.mjs says why that is not this.

package/main/engine-setup.mjs

@@ -0,0 +1,204 @@
+// SETTING UP SOMEBODY'S PLAN FOR THEM (w-9f6975906c, picked 2026-10-05).
+//
+// A person with a Claude or ChatGPT plan and no Claude Code or Codex used to
+// reach a card with a link to an install page. Now the walk asks which plan
+// they pay for and this does the rest: install the tool if it is missing, start
+// its own sign-in, and wait until the tool itself says it is signed in. The one
+// thing left for them is approving in their browser.
+//
+// EVERY COMMAND HERE IS THE TOOL'S OWN, and that is a rule, not a style.
+// Anthropic does not allow third party apps to offer claude.ai login unless
+// approved, so Agentbox never draws a sign-in of its own: it runs Claude Code's
+// `auth login`, which opens Anthropic's page, and Codex's `login`, which opens
+// OpenAI's. Measured 2026-10-05 into throwaway home folders with stdin closed:
+// both installers finish with no prompts (Claude Code 24.6 s, Codex 9.7 s) and
+// land in `~/.local/bin`, the first place each finder looks; `claude auth login
+// --claudeai` runs `open <url>` with a localhost callback, so approving in the
+// browser finishes it with nothing to paste.
+//
+// NO API KEY REACHES ANYTHING RUN HERE. An inherited ANTHROPIC_API_KEY makes
+// Claude Code report itself signed in on the key and bill it, which is the
+// opposite of setting up their plan; `terminalEnv` is the scrub the built-in
+// terminal already uses.
+
+import { spawn as nodeSpawn } from 'node:child_process';
+import { terminalEnv } from './task-terminals.mjs';
+import { codexLaunchEnv } from './codex-launch-env.mjs';
+
+const INSTALLERS = {
+  claude: { shell: '/bin/bash', url: 'https://claude.ai/install.sh', pipe: 'bash' },
+  codex: { shell: '/bin/sh', url: 'https://chatgpt.com/codex/install.sh', pipe: 'sh' },
+};
+
+export function installCommand(engine) {
+  const i = INSTALLERS[engine];
+  return { file: i.shell, args: ['-c', `curl -fsSL ${i.url} | ${i.pipe}`] };
+}
+
+/** The plan, never the API console: `--claudeai` is Claude Code's own name for it. */
+export function signInCommand(engine, bin) {
+  return engine === 'claude'
+    ? { file: bin, args: ['auth', 'login', '--claudeai'] }
+    : { file: bin, args: ['login'] };
+}
+
+/** Exit 0 is signed in and 1 is not, for both (measured 2026-10-05). */
+export function statusCommand(engine, bin) {
+  return engine === 'claude'
+    ? { file: bin, args: ['auth', 'status', '--json'] }
+    : { file: bin, args: ['login', 'status'] };
+}
+
+const LOG_LIMIT = 64 * 1024;
+const STATUS_TIMEOUT = 15_000;
+const POLL = 2_000;
+const ANSI = /\x1b\[[0-9;?]*[A-Za-z]/g;
+
+function realSpawn(file, args, { env, onData, keepStdin = false } = {}) {
+  let child;
+  try {
+    child = nodeSpawn(file, args, { env, stdio: [keepStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
+  } catch (error) {
+    onData?.(`${error.message}\n`);
+    return { exit: Promise.resolve(127), kill() {} };
+  }
+  const feed = (d) => onData?.(String(d));
+  child.stdout?.on('data', feed);
+  child.stderr?.on('data', feed);
+  const exit = new Promise((resolve) => {
+    child.on('exit', (code) => resolve(code ?? 1));
+    child.on('error', (error) => { onData?.(`${error.message}\n`); resolve(127); });
+  });
+  return { exit, kill: () => { try { child.kill('SIGTERM'); } catch { /* already gone */ } } };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * One setup per tool, held for the life of the app.
+ *
+ * `find(engine)` is the finder, looking again from scratch (the caller passes
+ * `recheckClaude` / `recheckCodex`, which also move the config so the rest of
+ * the app runs on what was just installed). `spawn` and `wait` are seams for
+ * the tests; nothing in the app passes them.
+ */
+export function createEngineSetup({ find, spawn = realSpawn, wait = sleep, env = process.env, poll = POLL, onSignIn = () => {} } = {}) {
+  const runEnv = terminalEnv(env);
+  const toolEnv = (engine, bin) => engine === 'codex' ? codexLaunchEnv(bin, runEnv) : runEnv;
+  const jobs = new Map();
+
+  const fresh = (engine) => ({ engine, phase: 'idle', error: null, log: '', running: null, login: null, run: 0 });
+  const job = (engine) => { if (!jobs.has(engine)) jobs.set(engine, fresh(engine)); return jobs.get(engine); };
+  const say = (j, text) => { j.log = (j.log + String(text).replace(ANSI, '')).slice(-LOG_LIMIT); };
+  const lastLine = (text) => text.split('\n').map((l) => l.trim()).filter(Boolean).pop() ?? '';
+
+  async function signedIn(j, bin) {
+    const { file, args } = statusCommand(j.engine, bin);
+    let output = '';
+    const p = spawn(file, args, { env: toolEnv(j.engine, bin), onData: (d) => { output = (output + String(d).replace(ANSI, '')).slice(-LOG_LIMIT); } });
+    const TIMED_OUT = Symbol('no answer');
+    const code = await Promise.race([p.exit, wait(STATUS_TIMEOUT).then(() => { p.kill(); return TIMED_OUT; })]);
+    // TOLD TO THE APP, which routes on it (w-d5d632e503): a Claude Code that
+    // is signed out beside a Codex that is signed in is a Mac that runs on
+    // Codex. Only a real yes or no; a check that never answered says nothing.
+    if (code === 0 || code === 1) onSignIn(j.engine, code === 0);
+    if (code === 0 || code === 1) return code === 0;
+    if (output) say(j, output);
+    const name = j.engine === 'codex' ? 'Codex' : 'Claude Code';
+    throw new Error(code === TIMED_OUT
+      ? `${name} did not answer the sign-in check. Try again.`
+      : `${name} could not check sign-in: ${lastLine(output) || `exit ${code}`}`);
+  }
+
+  function startLogin(j, bin) {
+    j.login?.kill();
+    const { file, args } = signInCommand(j.engine, bin);
+    const login = spawn(file, args, { env: toolEnv(j.engine, bin), keepStdin: true, onData: (d) => say(j, d) });
+    j.login = login;
+    return login;
+  }
+
+  async function go(j, run) {
+    const live = () => j.run === run;
+    let hit = find(j.engine);
+    if (!hit?.found) {
+      j.phase = 'installing';
+      const { file, args } = installCommand(j.engine);
+      const p = spawn(file, args, { env: runEnv, onData: (d) => say(j, d) });
+      j.running = p;
+      const code = await p.exit;
+      j.running = null;
+      if (!live()) return;
+      if (code !== 0) return fail(j, `The installer stopped: ${lastLine(j.log) || `exit ${code}`}`);
+      hit = find(j.engine);
+      if (!hit?.found) return fail(j, 'The installer finished, but the app still cannot find it.');
+    }
+    j.bin = hit.path;
+    j.phase = 'checking';
+    if (await signedIn(j, hit.path)) return live() && ready(j);
+    if (!live()) return;
+    j.phase = 'signing-in';
+    let login = startLogin(j, hit.path);
+    let ended = false;
+    const watchLogin = (loginProcess) => loginProcess.exit.then(() => { if (loginProcess === j.login) ended = true; });
+    watchLogin(login);
+    for (;;) {
+      await wait(poll);
+      if (!live()) return;
+      if (await signedIn(j, hit.path)) { if (live()) ready(j); return; }
+      if (j.login !== login) {
+        login = j.login;
+        ended = false;
+        watchLogin(login);
+      }
+      if (ended) return fail(j, `The sign-in was closed before it finished.${lastLine(j.log) ? ` ${lastLine(j.log)}` : ''}`);
+    }
+  }
+
+  function ready(j) { j.login?.kill(); j.login = null; j.phase = 'ready'; j.error = null; }
+  function fail(j, error) { j.login?.kill(); j.login = null; j.phase = 'failed'; j.error = error; }
+
+  return {
+    start(engine) {
+      const j = job(engine);
+      if (['installing', 'checking', 'signing-in'].includes(j.phase)) return this.status(engine);
+      j.run += 1; j.phase = 'checking'; j.error = null; j.log = '';
+      const run = j.run;
+      go(j, run).catch((e) => { if (j.run === run) fail(j, String(e?.message ?? e)); });
+      return this.status(engine);
+    },
+    /** Kill the sign-in that is waiting and start a new one, which opens the page again. */
+    signInAgain(engine) {
+      const j = job(engine);
+      if (j.phase === 'signing-in' && j.bin) startLogin(j, j.bin);
+      return this.status(engine);
+    },
+    cancel(engine) {
+      const j = job(engine);
+      j.run += 1;
+      j.running?.kill(); j.login?.kill();
+      j.running = null; j.login = null;
+      if (j.phase !== 'ready') j.phase = 'idle';
+      return this.status(engine);
+    },
+    status(engine) {
+      const j = job(engine);
+      return { engine, phase: j.phase, error: j.error, log: j.log };
+    },
+    /**
+     * WHETHER THIS TOOL CAN RUN AN AGENT RIGHT NOW: found, and signed in by its
+     *  own account. The walk asks before it asks anything, so a Mac that is
+     *  already set up never sees the plan question. */
+    async readiness(engine) {
+      const hit = find(engine);
+      if (!hit?.found) return { engine, found: false, signedIn: false };
+      try { return { engine, found: true, signedIn: await signedIn({ engine, log: '' }, hit.path) }; }
+      catch (error) { return { engine, found: true, signedIn: false, error: error.message }; }
+    },
+    /** The same question against a path already found, so asking it at
+     *  launch does not search the Mac again. */
+    signedInNow(engine, bin) {
+      return signedIn({ engine, log: '' }, bin).catch(() => false);
+    },
+  };
+}

package/main/feedback.mjs

@@ -0,0 +1,55 @@
+// SENDING FEEDBACK TO THE AGENTBOX TEAM (w-1b574413db, 2026-10-04).
+//
+// The card hands the main process what you wrote and what you attached, and
+// this file posts it to one server function. That function holds who it goes
+// to as a secret (`FEEDBACK_TO`, cloud/supabase/functions/feedback), so the
+// address is in no file of this public repository and no install can show it.
+//
+// WHERE IT GOES IS BAKED IN, like the analytics key (main/analytics.mjs): the
+// release writes `bakedFeedbackUrl` into the packaged package.json, a copy run
+// from source carries none, and a `feedbackUrl` in zero.config.json outranks
+// both. A copy with nowhere to send says so in words rather than pretending.
+//
+// It is not behind the diagnostics switch. That switch is about what Agentbox
+// sends on its own; this is something a person typed and pressed Send on.
+import { createRequire } from 'node:module';
+import { checkFeedback } from '../shared/feedback.mjs';
+import { Name, readEnv } from '../shared/product-name.mjs';
+
+function bakedUrl() {
+  try {
+    return createRequire(import.meta.url)('../package.json')?.bakedFeedbackUrl ?? null;
+  } catch {
+    return null;
+  }
+}
+
+const BAKED = bakedUrl();
+const clean = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+
+export function feedbackUrl(config, baked = BAKED, env = process.env) {
+  return clean(config?.feedbackUrl) ?? clean(readEnv('FEEDBACK_URL', env)) ?? clean(baked);
+}
+
+// Answers { ok: true } or { ok: false, error } with the error as a sentence.
+// It never throws, so the card always has something to say.
+export async function sendFeedback({ url, payload, fetchImpl = globalThis.fetch, timeoutMs = 60_000 }) {
+  if (!url) return { ok: false, error: `Feedback is not set up in this copy of ${Name}.` };
+  // Checked again here, off the bytes that would actually travel, since the
+  // renderer is not the last word on what leaves this machine.
+  const sized = (payload?.files ?? []).map((f) => ({ size: Math.floor((String(f?.data ?? '').length * 3) / 4) }));
+  const check = checkFeedback({ text: payload?.text, files: sized });
+  if (!check.ok) return { ok: false, error: check.reason };
+  try {
+    const res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (res?.ok) return { ok: true };
+    return { ok: false, error: 'It did not send. Try again in a moment.' };
+  } catch {
+    return { ok: false, error: 'It did not send. Check your connection and try again.' };
+  }
+}

package/main/folder-pictures.mjs

@@ -0,0 +1,48 @@
+// THE PICTURES IN A FOLDER A MESSAGE NAMES, newest first.
+//
+// A worker that drew several versions names their folder on a line of its own,
+// and until 2026-10-04 that line was grey text. Focus now draws the pictures
+// under it (FolderPreview), and this is the one thing the window cannot do for
+// itself: look inside a folder.
+//
+// Two rules, the same two the picture scheme enforces (./img-scheme.mjs), so a
+// folder line is never a way to list anything else: the folder is inside this
+// product's own folders or the account root, and only pictures come back. One
+// level only, because a design folder keeps old rounds in folders of their own.
+// tests/a-named-folder-shows-its-pictures.test.mjs holds every edge.
+import fsDefault from 'node:fs';
+import path from 'node:path';
+import { resolveArtifact } from './artifact-path.mjs';
+import { servable } from './img-scheme.mjs';
+
+const PICTURE = /\.(png|jpe?g|gif|webp|avif)$/i;
+
+export function folderPictures({ src, product, products = [], accountRoot, storeRoot, limit = 60, fs = fsDefault }) {
+  if (typeof src !== 'string' || !src.trim()) return { ok: false, error: 'No folder was named.' };
+  const named = src.replace(/\/+$/, '');
+  const found = resolveArtifact({ src: named, product, products, accountRoot, storeRoot, fs });
+  if (!found.ok) return { ok: false, error: found.error };
+  const own = products.find((p) => p.slug === product) ?? null;
+  const roots = [accountRoot, own?.dir, own?.repoPath].filter(Boolean);
+  let entries;
+  try {
+    if (!fs.statSync(found.path).isDirectory()) return { ok: false, error: `${src} is not a folder.` };
+    entries = fs.readdirSync(found.path, { withFileTypes: true });
+  } catch (e) {
+    return { ok: false, error: `${src} could not be read (${e.message}).` };
+  }
+  const pictures = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !PICTURE.test(entry.name)) continue;
+    const file = path.join(found.path, entry.name);
+    if (!servable(file, roots)) continue;
+    let mtime = 0;
+    try { mtime = fs.statSync(file).mtimeMs; } catch { continue; }
+    pictures.push({ file, mtime });
+  }
+  if (!pictures.length && !roots.some((r) => found.path === r || found.path.startsWith(r + path.sep))) {
+    return { ok: false, error: `${src} is not in this project.` };
+  }
+  pictures.sort((a, b) => b.mtime - a.mtime || a.file.localeCompare(b.file));
+  return { ok: true, folder: found.path, pictures: pictures.slice(0, limit).map((p) => p.file), total: pictures.length };
+}