agentbox-app 0.1.7 → 0.1.11

package/main/codex-threads.mjs

@@ -14,11 +14,11 @@
 //                                       events, of which `user_message` and
 //                                       `agent_message` are the two this reads.
 //
-// WHICH THREADS ARE HERS. `thread_source` is `user` for one she typed into,
-// `guardian_review` for Codex's own reviewer of a turn, and `subagent` for a
-// helper a thread spawned. 247 transcripts were touched in the seven days to
-// 09-14; 158 of them were guardians. Without this filter the inbox would offer
-// her four rows for every conversation she had.
+// WHICH THREADS ARE THE USER'S. `thread_source` is `user` for one a person typed
+// into, `guardian_review` for Codex's own reviewer of a turn, and `subagent` for
+// a helper a thread spawned. Guardians are the majority of transcripts, so
+// without this filter the inbox would offer several rows for every real
+// conversation.
 //
 // There is also `~/.codex/state_5.sqlite`, which has everything above in one
 // table. It is not read: Electron ships no sqlite, the file is written live
@@ -26,9 +26,12 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { isScratchFolder, shortFolder, threadTitle } from './agent-sessions.mjs';
+import { RECENT_DAYS, isScratchFolder, shortFolder, threadTitle } from './agent-sessions.mjs';
+import { WAS_SLUGS, nameSlug } from '../shared/product-name.mjs';
 
-export const CODEX_RECENT_DAYS = 7;
+export const CODEX_RECENT_DAYS = RECENT_DAYS;
+/** The originator Codex records for a run this app started (CLIENT_INFO.name), now and before. */
+const OUR_ORIGINATORS = new Set([nameSlug, ...WAS_SLUGS]);
 /** How many day folders the walk opens at most, whatever `days` says. */
 const MAX_DAY_FOLDERS = 40;
 /**
@@ -62,22 +65,38 @@ const numericDesc = (dir) => {
   return names.filter((n) => /^\d+$/.test(n)).sort((a, b) => Number(b) - Number(a));
 };
 
-/** Every transcript in the newest `days` day folders, newest folder first. */
-export function listRolloutFiles(codexDir = codexHome(), { days = CODEX_RECENT_DAYS } = {}) {
+/**
+ * Every transcript in the newest `days` day folders, newest folder first.
+ *
+ *  AND, WITH `since`, EVERY OLDER ONE WRITTEN TO SINCE THEN. Codex files a
+ *  conversation under the day it STARTED, so a thread begun two weeks ago and
+ *  worked in yesterday sits in a folder the newest-`days` walk never opens
+ *  (w-db6f5e331e). Past those folders only a stat is paid per file, and the
+ *  walk still stops at MAX_DAY_FOLDERS. */
+export function listRolloutFiles(codexDir = codexHome(), { days = CODEX_RECENT_DAYS, since = null } = {}) {
   const root = path.join(codexDir, 'sessions');
   const out = [];
   let looked = 0;
   const limit = Math.min(Math.max(1, Number(days) || 1), MAX_DAY_FOLDERS);
+  const reach = since == null ? limit : MAX_DAY_FOLDERS;
   for (const year of numericDesc(root)) {
     for (const month of numericDesc(path.join(root, year))) {
       for (const day of numericDesc(path.join(root, year, month))) {
-        if (looked >= limit) return out;
+        if (looked >= reach) return out;
+        const older = looked >= limit;
         looked += 1;
         const dir = path.join(root, year, month, day);
         let names = [];
         try { names = fs.readdirSync(dir); } catch { names = []; }
         for (const name of names) {
-          if (/^rollout-.*\.jsonl$/.test(name)) out.push(path.join(dir, name));
+          if (!/^rollout-.*\.jsonl$/.test(name)) continue;
+          const file = path.join(dir, name);
+          if (older) {
+            let mtime = 0;
+            try { mtime = fs.statSync(file).mtimeMs; } catch { continue; }
+            if (mtime < since) continue;
+          }
+          out.push(file);
         }
       }
     }
@@ -103,17 +122,17 @@ export function cleanPrompt(text) {
  * WHAT CODEX PUTS IN HER MOUTH. In paginated history mode the user turn is a
  * `response_item` with several `<recommended_plugins>…`,
  * `<environment_context>…`, `<user_instructions>…`. Every one of those opens
- * with an angle-bracket tag on its first line, and nothing she types does.
- * Measured on the thread she screenshotted (2026-09-15): three parts, the
+ * with an angle-bracket tag on its first line, and nothing a person types does.
+ * Measured on a real thread: three parts, the
  * first two injected. */
 export function isInjected(text) {
   const t = String(text ?? '').trimStart();
   const first = t.split('\n')[0] ?? '';
   if (/^<[a-z_]+[^>]*>/i.test(first)) return true;
   // The folder's AGENTS.md, pasted in as "# AGENTS.md instructions for
-  // /path" followed by an <INSTRUCTIONS> block. Measured on the thread she
-  // screenshotted (2026-09-15): it was the second part of her first turn, and
-  // the first read of it printed it as what she asked.
+  // /path" followed by an <INSTRUCTIONS> block. Measured on a real thread: it
+  // was the second part of the first turn, and the first read of it printed it
+  // as what the user asked.
   if (/^#\s*AGENTS\.md instructions/i.test(first)) return true;
   return /^\s*<INSTRUCTIONS>/i.test(t.slice(first.length, first.length + 200));
 }
@@ -142,9 +161,8 @@ const partsOf = (payload) => (Array.isArray(payload?.content) ? payload.content
  *  lines of type `user_message` / `agent_message` with a `message` string.
  *  Paginated writes none of those: the turns are `response_item` lines of type
  *  `message` with a `role` and a `content` array of `input_text`, `input_image`
- *  and `output_text` parts. Measured 2026-09-15 across the seven days before:
- *  all 61 of her own threads were paginated, and the first build read only
- *  legacy, which is why her row said "Codex has not answered yet." */
+ *  and `output_text` parts. Current Codex threads are paginated, and a build
+ *  that read only legacy showed "Codex has not answered yet." on every row. */
 export function readRollout(file) {
   let text = '';
   try {
@@ -177,7 +195,12 @@ export function readRollout(file) {
       meta = {
         id: String(p.session_id ?? p.id ?? '').trim(),
         cwd: String(p.cwd ?? '').trim(),
-        threadSource: typeof p.thread_source === 'string' ? p.thread_source : (typeof p.source === 'string' ? 'user' : 'other'),
+        // A RUN THIS APP STARTED IS NOT HERS TO IMPORT (w-db6f5e331e). Codex
+        // 0.160.0 writes no thread_source, so the line after this would call
+        // every run a person's; its originator is the clientInfo name we hand
+        // Codex, under this name or one the app had before.
+        threadSource: OUR_ORIGINATORS.has(String(p.originator ?? '').toLowerCase()) ? 'agentbox'
+          : typeof p.thread_source === 'string' ? p.thread_source : (typeof p.source === 'string' ? 'user' : 'other'),
         startedAt: Number.isFinite(startedAt) ? startedAt : 0,
       };
       continue;
@@ -227,15 +250,15 @@ export const LIVE_MS = 2 * 60_000;
 export const isLive = (mtime, now = Date.now()) => Number(mtime) > 0 && now - Number(mtime) < LIVE_MS;
 
 /**
- * HER CONVERSATIONS, newest first, in the shape the import card and the
- *  import row both read. One entry per thread she typed into, in a real folder,
+ * THE USER'S CONVERSATIONS, newest first, in the shape the import card and the
+ *  import row both read. One entry per thread a person typed into, in a real folder,
  *  touched in the last `days` days. */
 export function readCodexThreads({ home = os.homedir(), codexDir = codexHome(home), days = CODEX_RECENT_DAYS, now = Date.now() } = {}) {
   const index = readCodexIndex(codexDir);
   const cutoff = now - Math.max(0, Number(days) || 0) * 86400 * 1000;
   const out = [];
   const skipped = { notHers: 0, scratch: 0, old: 0, empty: 0, unreadable: 0 };
-  for (const file of listRolloutFiles(codexDir, { days })) {
+  for (const file of listRolloutFiles(codexDir, { days, since: cutoff })) {
     const r = readRollout(file);
     if (!r) { skipped.unreadable += 1; continue; }
     if (r.threadSource !== 'user') { skipped.notHers += 1; continue; }

package/main/codex-usage-file.mjs

@@ -4,17 +4,17 @@
 // and it is a good one: never spawn anything and never ask OpenAI anything to
 // draw a picture. Codex's figures ride the app-server the fleet is already
 // running and arrive unprompted during a turn. The unstated cost of that rule is
-// that the app only ever learns a number for work POWERUP ITSELF RAN. She runs
-// Codex in its own app all day, so on her Mac the push had never arrived and the
-// panel was empty while her weekly limit sat at 100% used.
+// that the app only ever learns a number for work POWERUP ITSELF RAN. Someone
+// who runs Codex in its own app all day never gets the push, so the panel sits
+// empty while their weekly limit is at 100% used.
 //
 // SO THERE IS A THIRD SOURCE, AND IT BREAKS NEITHER HALF OF THAT RULE. Codex
 // writes every rate-limit report it receives into its own session log under
 // CODEX_HOME, as a `rate_limits` object on the `token_count` events. Reading it
 // starts no process, sends nothing anywhere, and touches no credential: it is a
-// file on her disk that Codex put there. Measured on her Mac 2026-09-18: 1,140
-// such records across her twenty-five most recent sessions, the newest written
-// the same minute she filed the row.
+// file on the disk that Codex put there. A busy Codex home holds hundreds of
+// such records across its most recent sessions, the newest written within
+// the minute.
 //
 // THE PUSH STILL WINS. A live notification is this second's truth and a log is
 // the last thing anybody wrote down, so main/codex-usage.mjs reads this only when
@@ -111,7 +111,7 @@ function tail(file, bytes = TAIL_BYTES) {
  *
  * Lines are walked backwards because the last report is the one that is true. A
  * report carrying no usable window is skipped rather than accepted: Codex emits
- * an all-null snapshot for limit families that do not apply to the account (her
+ * an all-null snapshot for limit families that do not apply to the account (a
  * `premium` family, every field null), and taking one of those would blank a
  * panel that had a real figure a moment earlier.
  */

package/main/codex-usage.mjs

@@ -11,7 +11,7 @@
 // Codex's figures ride the `codex app-server` THE FLEET IS ALREADY RUNNING:
 // they arrive unprompted as `account/rateLimits/updated` during a turn.
 //
-// AND NEVER ASK FOR ONE EITHER (the founder, 2026-09-05). This reader briefly
+// AND NEVER ASK FOR ONE EITHER. This reader briefly
 // also sent an explicit rate-limits read down that pipe whenever its figure
 // went stale. It is deliberately gone, and this paragraph is here so the next
 // reader does not put it back as an obvious improvement.
@@ -96,9 +96,9 @@ export class CodexUsage {
     const limits = codexLimits(this._snapshot);
     if (limits.length) return { limits, at: this._at };
     // NOTHING HAS PUSHED, SO ASK WHAT CODEX ALREADY WROTE DOWN. This is the
-    // whole of: the push only ever arrives for work the app itself ran, and she
-    // runs Codex in its own app, so on her Mac the panel stayed empty while her
-    // weekly limit was full. main/codex-usage-file.mjs is a read of a file
+    // whole of: the push only ever arrives for work the app itself ran, and a
+    // person who runs Codex in its own app would see the panel stay empty
+    // while their weekly limit was full. main/codex-usage-file.mjs is a read of a file
     // under this same CODEX_HOME. It starts no process and sends nothing
     // anywhere, so neither rule above is bent.
     return this._logged();

package/main/codex-watch.mjs

@@ -1,25 +1,25 @@
-// THE WATCH THAT NOTICES A CODEX CONVERSATION AND ASKS.
+// THE WATCH THAT KEEPS AN IMPORTED CODEX CONVERSATION CURRENT.
 //
-// Her pick on 19:53: "ask first". So every minute this reads the conversations
-// she had in Codex this week, and for each one that runs in a folder one of her
-// projects points at and has no row anywhere yet, it files the asking row in
-// that project. It also keeps the rows she said yes to current: when Codex
-// writes another answer, the row's result follows it.
+// Every minute this reads the user's recent Codex conversations and, for each
+// one they already brought in, makes the row follow Codex: when Codex writes
+// another answer, the row's result follows it. An asking row filed before this
+// change is kept true the same way.
 //
-// A conversation in a folder no project points at gets no row here. It is
-// still on the ⌘K import card, under a section that makes the project on the
-// press, which is the card's own way of handling a new folder.
+// IT NO LONGER ASKS ABOUT NEW ONES (w-db6f5e331e, 2026-10-05). It used to file
+// an "Import into ...?" row for every new conversation in a project's folder.
+// The founder, before launch: "after onboarding for both anthropic and openai
+// harnesses, it should only import on command, not continuously". Importing is
+// now the walk's last card and ⌘K import, for Claude Code and Codex alike.
 import { readCodexThreads } from './codex-threads.mjs';
 
 export const CODEX_POLL_MS = 60_000;
 
 export function scanCodex({ store, readThreads = readCodexThreads, now = Date.now() } = {}) {
   let threads = [];
-  try { ({ threads } = readThreads({ now })); } catch { return { asked: 0, refreshed: 0, retold: 0, threads: 0 }; }
-  const asked = store.askAboutCodexThreads(threads, { now });
+  try { ({ threads } = readThreads({ now })); } catch { return { refreshed: 0, retold: 0, threads: 0 }; }
   const refreshed = store.refreshCodexMirrors(threads, { now });
   const retold = store.refreshCodexAsks(threads, { now });
-  return { asked, refreshed, retold, threads: threads.length };
+  return { refreshed, retold, threads: threads.length };
 }
 
 export function startCodexWatch({ store, readThreads = readCodexThreads, pollMs = CODEX_POLL_MS, firstDelayMs = 8_000 } = {}) {

package/main/config.mjs

@@ -59,10 +59,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 +100,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.
@@ -150,11 +168,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 +232,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 +269,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 +296,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/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,193 @@
+// 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';
+
+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 {
+    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', () => 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 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);
+    const p = spawn(file, args, { env: runEnv });
+    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);
+    return code === 0;
+  }
+
+  function startLogin(j, bin) {
+    j.login?.kill();
+    const { file, args } = signInCommand(j.engine, bin);
+    const login = spawn(file, args, { env: runEnv, 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 gaveUp = false;
+    login.exit.then((code) => { if (login === j.login && code !== 0) gaveUp = true; });
+    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;
+        gaveUp = false;
+        login.exit.then((code) => { if (login === j.login && code !== 0) gaveUp = true; });
+      }
+      if (gaveUp) return fail(j, 'The sign-in was closed before it finished.');
+    }
+  }
+
+  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 };
+      return { engine, found: true, signedIn: await signedIn({ engine }, hit.path) };
+    },
+    /** 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 }, bin);
+    },
+  };
+}