agentbox-app 0.1.12 → 0.1.13

package/main/claude-models.mjs

@@ -39,8 +39,35 @@
 // at all.
 
 import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { CLAUDE_MODELS, READ_FROM } from '../shared/claude-models.generated.mjs';
 
+// WHAT THE LAST BUILD ON THIS MACHINE READ, which is a better floor than the
+// committed table and is not a file anybody edits.
+//
+// The committed table is tracked, so a build that wrote over it made every
+// folder that had run the app look like it held work (w-6bbb709b1f, 2026-10-07).
+// The build writes this instead. It is gitignored, it is absent on a machine
+// that has never built, and it is read with `fs` rather than imported, for the
+// one reason that decides the whole shape: this module is node, but
+// shared/claude-commands.mjs next door is shared with the renderer, where an
+// import of a file that may not exist cannot be made to resolve. A read is a
+// read in node and nothing at all in a bundle.
+const LOCAL = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'shared', 'claude-models.local.json');
+
+/** The table this machine read at build time, or null if there is none to trust. */
+function readLocal(at) {
+  try {
+    const table = JSON.parse(fs.readFileSync(at, 'utf8'));
+    if (!Array.isArray(table.models) || !table.models.length) return null;
+    // Every row has to carry what the picker draws. A half-written file is a
+    // worse answer than the committed table, not a better one.
+    if (!table.models.every((m) => m && typeof m.alias === 'string' && typeof m.label === 'string')) return null;
+    return table;
+  } catch { return null; }
+}
+
 /**
  * HER ORDER, AND ONLY HER ORDER. Not a filter: an alias missing from this list
  * is still offered, after these. Her three are from and Fable is the one she
@@ -203,8 +230,10 @@ function stampOf(binPath) {
  * WHAT MAY SHE BE OFFERED FOR CLAUDE CODE, and what version said so.
  *
  * `{ models: [{ alias, id, label }], readFrom, source }` where `source` is
- * `'cli'` when it came off this Mac's Claude Code and `'built'` when it is the
- * table committed at build time. Never empty: the committed table is the floor.
+ * `'cli'` when it came off this Mac's Claude Code at the moment it was asked,
+ * `'read'` when it is what the last build on this machine read out of it, and
+ * `'built'` when it is the table committed to the repository. Never empty: the
+ * committed table is the floor under both of them.
  *
  * THE PATH IS HANDED IN, NEVER SEARCHED FOR HERE. `config.claudeBin` is already
  * resolved once at startup (main/config.mjs), and `findClaudeBin` falls back to
@@ -216,15 +245,18 @@ function stampOf(binPath) {
  * `--version` so the Settings screen could say which one it read. That is one
  * `execFileSync` on the path a settings read takes, and no label on a screen is
  * worth a process started while she waits. `readFrom` is the committed table's
- * version, and it is meaningful only when `source` is `'built'`.
+ * version, and it is meaningful whenever `source` is not `'cli'`.
  */
-export function claudeModels({ bin = null } = {}) {
+export function claudeModels({ bin = null, local = LOCAL } = {}) {
+  // THE FLOOR IS THE FRESHER OF THE TWO TABLES NOBODY HAS TO ASK FOR: what the
+  // last build on this machine read, and the one committed to the repository.
+  const read = readLocal(local);
   const built = {
-    models: CLAUDE_MODELS.map((m) => ({
+    models: (read?.models ?? CLAUDE_MODELS).map((m) => ({
       alias: m.alias, id: m.id, label: m.label, defaultLevel: m.defaultLevel ?? null,
     })),
-    readFrom: READ_FROM,
-    source: 'built',
+    readFrom: read ? read.readFrom ?? null : READ_FROM,
+    source: read ? 'read' : 'built',
   };
   if (!bin) return built;
   const stamp = stampOf(bin);

package/main/claude-plan.mjs

@@ -71,6 +71,9 @@ export function planLabel(raw) {
   if (!s) return null;
   const bare = s.replace(/^default_/, '').replace(/^claude_/, '');
   if (!bare) return null;
+  // Claude's saved Enterprise tier includes an internal name. Keep the raw
+  // tier for capacity decisions, but show only the subscription name.
+  if (bare === 'raven_enterprise') return 'Enterprise';
   return bare
     .split('_')
     .filter(Boolean)
@@ -95,25 +98,13 @@ export function isMaxTier(raw) {
  *  as it was". */
 export function readPlan(profile, { home = os.homedir(), file = null } = {}) {
   const at = file ?? planFile(profile, home);
+  const none = { known: false, max: false, label: null, tier: null, from: null, file: at };
   let account = null;
   try {
     account = JSON.parse(fs.readFileSync(at, 'utf8'))?.oauthAccount ?? null;
   } catch {
-    return planOfAccount(null, at);
+    return none;
   }
-  return planOfAccount(account, at);
-}
-
-/**
- * THE SAME ANSWER OFF AN `oauthAccount` SOMEBODY ALREADY HAS IN HAND.
- *
- *  Lifted out of `readPlan` so a caller that has read the file for its own
- *  reasons (main/runs-on.mjs, which also wants to know whether there is a login
- *  in there at all) does not carry a second copy of the tier ordering. One copy
- *  of that rule, and the file read stays in one place per caller.
- */
-export function planOfAccount(account, at = null) {
-  const none = { known: false, max: false, label: null, tier: null, from: null, file: at };
   if (!account || typeof account !== 'object') return none;
   // THE ORDER IS MOST SPECIFIC FIRST. A rate limit tier names the plan AND its
   // size (`max_20x` against `max_5x`), which is the thing worth showing; the
@@ -126,7 +117,15 @@ export function planOfAccount(account, at = null) {
   const from = tier === account.organizationRateLimitTier
     ? 'org-tier'
     : tier === account.userRateLimitTier ? 'user-tier' : 'org-type';
-  return { known: true, max: isMaxTier(tier), label: planLabel(tier), tier, from, file: at };
+  // A SUBSCRIPTION THAT HAS ENDED STILL NAMES ITS OLD TIER. Measured
+  // 2026-10-11 on a lapsed personal Max login: `billingType` had gone to
+  // "none" (a paying one says "stripe_subscription") while the tier still said
+  // `default_claude_max_20x`, so the page went on saying "Max 20x". Only the
+  // exact word counts; a file that names no billing at all is read as before.
+  if (account.billingType === 'none') {
+    return { known: true, ended: true, max: false, label: 'Subscription ended', tier, from, file: at };
+  }
+  return { known: true, ended: false, max: isMaxTier(tier), label: planLabel(tier), tier, from, file: at };
 }
 
 /**
@@ -154,7 +153,8 @@ export function readPlans(profiles, { home = os.homedir() } = {}) {
  *  AND AN UNREADABLE ACCOUNT NEVER LOWERS IT. Somebody whose config file we
  *  cannot parse gets exactly the app they had before this existed. */
 export function slotsForPlans(plans, fallback = 3) {
-  const known = (plans ?? []).filter((p) => p.known);
+  // An ended subscription runs nothing, so it has no say in how many run.
+  const known = (plans ?? []).filter((p) => p.known && !p.ended);
   if (!known.length) return fallback;
   return known.every((p) => p.max) ? fallback : 1;
 }

package/main/claude-usage.mjs

@@ -10,7 +10,8 @@
 // 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, and never a call anything awaits:
+// 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.
@@ -33,7 +34,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { readUsage } from '../shared/claude-usage.mjs';
-import { localZone } from '../shared/usage.mjs';
+import { localZone, USAGE_UNREADABLE } from '../shared/usage.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
@@ -76,20 +77,36 @@ export class ClaudeUsage {
    * is, asked each time rather than captured: it can be installed while the
    * app is running, and the settings screen already promises that works.
    * @param { => void} [how.onChange] Told when a new reading lands, so the
-   * window redraws. Never called for a refresh that changed nothing.
+   * window redraws, including a new checked time on unchanged percentages.
+   * @param { => { profile: string, env?: object }} [how.account] WHOSE LIMIT
+   * IS READ, asked each time. It used to be nobody's in particular: the
+   * command ran with the app's own environment, which is the default login,
+   * so a Mac with a second account picked as In use showed "No usage reading
+   * yet" for good, because the default one was at its limit and Claude Code
+   * printed no limits for it (2026-10-08, Claude Code 2.1.293). `profile` is
+   * 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 } = {}) {
+  constructor({ bin, onChange = () => {}, run = execFile, now = () => Date.now(), where = usageCwd, account = () => ({ profile: 'default' }) } = {}) {
     this._bin = bin;
+    this._selectedProfile = null;
+    this._generation = 0;
+    this._pending = null;
     this._onChange = onChange;
     this._run = run;
     this._now = now;
     this._where = where;
-    /** @type {{ limits: any[], at: number, zone: string|null }|null} */
+    this._account = account;
+    /** @type {{ limits: any[], at: number, zone: string|null, profile: string }|null} */
     this._last = null;
     this._busy = false;
     this._missedUntil = 0;
   }
 
+  _who() {
+    try { return this._account() ?? { profile: 'default' }; } catch { return { profile: 'default' }; }
+  }
+
   /**
    * THE LAST READING, INSTANTLY, and a refresh started if it has gone stale.
    *
@@ -98,13 +115,28 @@ export class ClaudeUsage {
    * than a pill full of dashes.
    */
   read() {
+    this._syncProfile();
     this._maybeRefresh();
-    return this._last ? { limits: this._last.limits, at: this._last.at } : null;
+    return this.peek();
   }
 
   // The secondary subscription can show its last reading without starting
   // another coding process merely to populate the sidebar.
-  peek() { return this._last ? { limits: this._last.limits, at: this._last.at } : null; }
+  peek() {
+    this._syncProfile();
+    return this._last ? { limits: this._last.limits, at: this._last.at, profile: this._last.profile } : null;
+  }
+
+  _syncProfile() {
+    const account = this._who().profile || 'default';
+    if (account !== this._selectedProfile) {
+      this._selectedProfile = account;
+      this._generation++;
+      this._last = null;
+      this._missedUntil = 0;
+    }
+    return account;
+  }
 
   _maybeRefresh() {
     const now = this._now();
@@ -114,33 +146,58 @@ export class ClaudeUsage {
   }
 
   /** Ask again now, whatever the cache says. The settings screen's own button. */
-  refreshNow() {
+  async refreshNow() {
+    this._syncProfile();
     this._missedUntil = 0;
-    if (!this._busy) this._refresh();
+    // Join an existing reading, including one begun by the background poll.
+    // If it belongs to the previous login, wait for it and then ask this one.
+    const generation = this._generation;
+    const pendingGeneration = this._pendingGeneration;
+    const result = await (this._pending ?? this._refresh());
+    this._syncProfile();
+    if (generation !== this._generation) return { ok: false, error: 'The account changed. Refresh usage again.' };
+    if (pendingGeneration != null && pendingGeneration !== generation) return this.refreshNow();
+    return result;
   }
 
   _refresh() {
+    const profile = this._syncProfile();
+    const generation = this._generation;
     const bin = (() => { try { return this._bin(); } catch { return null; } })();
-    if (!bin) { this._missed(); return; }
+    const failure = () => ({ ok: false, error: USAGE_UNREADABLE });
+    if (!bin) { this._missed(); return Promise.resolve(failure()); }
     this._busy = true;
-    this._run(
+    this._pendingGeneration = generation;
+    let resolve;
+    const pending = new Promise(done => { resolve = done; });
+    this._pending = pending;
+    const finish = (err, stdout) => {
+      this._busy = false;
+      this._pending = null;
+      this._pendingGeneration = null;
+      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; }
+      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.
+      this._onChange();
+    };
+    const env = { ...(this._who().env ?? process.env) };
+    for (const key of Object.keys(env)) {
+      if (/^ANTHROPIC_|^CLAUDE_CODE_/.test(key) || ['CLAUDECODE', 'CLAUDE_PID', 'CLAUDE_EFFORT', 'CLAUDE_CONFIG_DIR'].includes(key)) delete env[key];
+    }
+    if (profile !== 'default') env.CLAUDE_CONFIG_DIR = profile;
+    try { this._run(
       bin,
       ['-p', '/usage', '--output-format', 'text'],
       // `cwd` is the whole fix for the permission panels; see usageCwd above.
-      { cwd: this._where(), timeout: TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024, encoding: 'utf8' },
-      (err, stdout) => {
-        this._busy = false;
-        // A COMMAND THAT FAILED LEAVES THE OLD READING ALONE. It is stale rather
-        // than wrong, and a corner that empties itself every time the network
-        // hiccups is worse than one that is five minutes behind.
-        if (err && !stdout) { this._missed(); return; }
-        const limits = readUsage(stdout, this._now(), localZone());
-        if (!limits.length) { this._missed(); return; }
-        const before = JSON.stringify(this._last?.limits ?? null);
-        this._last = { limits, at: this._now(), zone: localZone() };
-        if (JSON.stringify(limits) !== before) this._onChange();
-      },
-    );
+      { cwd: this._where(), env, timeout: TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024, encoding: 'utf8' },
+      finish,
+    ); } catch (err) { finish(err, ''); }
+    return pending;
   }
 
   _missed() {

package/main/codex-bin.mjs

@@ -1,279 +1,81 @@
 // Where Codex actually is, and whether we are entitled to say it is not here.
 //
-// The sibling of main/claude-bin.mjs, and it keeps that file's rule rather than
-// re-arguing it.
+// THIS FILE IS NOW THE NAMES AND NOTHING ELSE. The search, the registry entry
+// that declares Codex, and every measurement behind its paths live in
+// main/engine-bin.mjs, which does the same job for every coding agent the app
+// can run. Until 2026-10-08 this was 279 lines beside main/claude-bin.mjs's 338,
+// and the two were copies of one idea: three of the seven commits they ever had
+// are literally "one more install location".
 //
-// So `found` decides which binary would be spawned and `certain` decides
-// whether a screen may SAY there is nothing here, and they are never the same
-// value.
+// WHAT IS KEPT HERE is the vocabulary the rest of the app already imports --
+// main/config.mjs, main/settings.mjs and main/codex-launch-env.mjs, which builds
+// the PATH a Codex opened from the desktop needs out of `candidatePaths` and
+// `versionedPaths`.
+//
+// `found` decides which binary would be spawned and `certain` decides whether a
+// screen may SAY there is nothing here, and they are never the same value.
 //
 // ONE DIFFERENCE FROM CLAUDE CODE, AND IT CHANGES THE SCREEN. Claude Code is
-// required: the app will not open an inbox without it. Codex is optional, and
-// an absence is the ordinary case rather than a fault. So nothing here ever
-// produces a warning. All a missing Codex does is leave the second engine out
-// of the map that shared/engines.mjs reads, which is silence rather than a
-// sentence about software she never asked for.
+// required: the app will not open an inbox without it. Codex is optional, and an
+// absence is the ordinary case rather than a fault. So nothing here ever produces
+// a warning. All a missing Codex does is leave the second engine out of the map
+// that shared/engines.mjs reads, which is silence rather than a sentence about
+// software nobody asked for.
 //
 // NOTHING HERE SPAWNS ANYTHING, AND main/config.mjs IS WHAT CALLS IT.
+// `resolveCodexBin` is what answers "is there a Codex on this machine", and its
+// answer is the fact `engineFor` refuses on. Before it was wired in, a `codexBin`
+// in zero.config.json arrived on `config` through the unknown-key spread and went
+// to `spawn` with no finder and no existence check behind it.
 //
-// It was inert when it was written -- "no config key, no snapshot field, no
-// Settings row" -- and that stopped being true the moment the supervisor
-// started spawning `config.codexBin`. Until this was wired in, that path
-// arrived on `config` through the unknown-key spread in main/config.mjs and
-// went to `spawn` with no finder and no existence check behind it, which is the
-// one path in the second engine that becomes a process and was the only one
-// with no guard on it. `resolveCodexBin` is now what answers "is there a Codex
-// on this Mac", and its answer is the fact `engineFor` refuses on.
-//
-// There is still no Settings row, which is a real gap and not a claim of one:
-// she can set `codexBin` in zero.config.json and nothing on screen says whether
-// it was found.
-//
-// ------------------------------------------------------------------------
-// MEASURED ON THIS MAC 2026-09-04, BECAUSE THE 2026-08-25 ORIGINAL WAS WRITTEN
-// AGAINST codex-cli 0.144.0 AND SIX OF ITS ASSUMPTIONS HAVE MOVED SINCE.
-//
-// Installed here: codex-cli 0.148.0 at /opt/homebrew/bin/codex. That is a
-// Homebrew CASK, not a formula as the original said, and the bin entry is a
-// SYMLINK into /opt/homebrew/Caskroom/codex/0.148.0/bin/codex. `brew info
-// --cask codex` the same minute reports 0.148.0 installed against 0.152.1
-// available, so the moment mid-upgrade where that link points at nothing is a
-// live state on this machine and not a hypothetical. It is the same shape the
-// dangling-symlink rule was written for in the sibling file.
-//
-// THE INSTALL METHOD THE DOCS NOW LEAD WITH DID NOT EXIST IN THE ORIGINAL.
-// `https://chatgpt.com/codex/install.sh`, read 2026-09-04:
-//
-//   BIN_DIR="${CODEX_INSTALL_DIR:-$HOME/.local/bin}"
-//   CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
-//   STANDALONE_ROOT="$CODEX_HOME_DIR/packages/standalone"
-//
-// It links ~/.local/bin/codex at a versioned file under that root and swaps the
-// file on every update. Three things follow, and all three are changes from the
-// original: that path goes FIRST (the tool's own answer settles a machine set
-// up the documented way in one stat call, exactly as ~/.local/bin/claude does
-// next door), the standalone store's own bin is worth listing for the case
-// where CODEX_INSTALL_DIR put the link somewhere no list covers, and CODEX_HOME
-// can move every trace below out from under us.
-//
-// AND THE STORE KEEPS THE BINARY IN TWO PLACES, WHICH THE FIRST VERSION OF THIS
-// FILE MISSED. Same script, read the same day:
-//
-//   line  951:  ln -sf "bin/codex" "$stage_release/codex"
-//   line 1021:  version_from_binary "$release_dir/bin/codex" \
-//                 || version_from_binary "$release_dir/codex"
-//
-// Every staged release carries the binary at `<release>/bin/codex` AND at
-// `<release>/codex`, and the installer accepts either when it goes looking for
-// a version. `current` is a symlink at the live release, so BOTH
-// `current/bin/codex` and `current/codex` resolve on a machine set up the
-// documented way. Each is one stat call, so listing both costs nothing, and
-// listing only one is how the app tells somebody their Codex is missing while
-// they are looking at it.
-//
-// WHAT ~/.codex REALLY HOLDS NOW: 38 entries. auth.json, config.toml, sessions/
-// and history.jsonl are all still there, so the original's evidence list is not
-// wrong. It is INCOMPLETE, and it is aging in a specific way. The directory
-// also holds state_5.sqlite, thread_history_1.sqlite, logs_2.sqlite,
-// memories_1.sqlite, queue_1.sqlite, goals_1.sqlite, models_cache.json,
-// installation_id and shell_snapshots/, and the split matters: sessions/ holds
-// 1691 rollout files with the newest written 2026-09-03, while history.jsonl
-// has not been touched since 2026-06-03. The live record moved into sqlite
-// files whose names carry a schema number that increments, which is a name no
-// list can hold. That is why the directory itself stays on the list, last and
-// broad, and why nothing below tries to enumerate what is inside it.
-//
-// AND THE LINK MOVED. The original's install URL, developers.openai.com/codex/
-// cli, answers 308 to learn.chatgpt.com/docs/codex/cli.
-//
-// The npm package is unchanged and still real (@openai/codex, 0.153.0 on
-// 2026-09-04), so the package-manager paths and the per-Node directories below
-// are carried over exactly as they were.
+// AND THERE IS A SETTINGS ROW NOW (w-ce8c1a9275): somebody whose Codex the
+// search misses can point the app at the binary themselves, which is written
+// back as `codexBin` and wins over everything below.
 
-import fs from 'node:fs';
 import os from 'node:os';
-import path from 'node:path';
-import { askShell } from './claude-bin.mjs';
+import {
+  ENGINES, findEngine, resolveEngine, forgetEngine, installEvidence as evidenceFor,
+  versionedBinPaths,
+} from './engine-bin.mjs';
 
-// In order, and the first that exists wins. The shell installer's own path is
-// first for the same reason its sibling's is: it is the answer the tool itself
-// produces. Everything after it is a package manager's default bin directory,
-// because Codex ships as a Homebrew cask and as an npm package rather than with
-// an installer that owns a folder.
-export function candidatePaths(home = os.homedir()) {
-  return [
-    path.join(home, '.local/bin/codex'),      // the shell installer's link
-    path.join(home, '.codex/packages/standalone/current/bin/codex'),
-    path.join(home, '.codex/packages/standalone/current/codex'),
-    '/opt/homebrew/bin/codex',                // the Homebrew cask, Apple Silicon
-    '/usr/local/bin/codex',                   // Homebrew on Intel, and npm -g
-    path.join(home, '.bun/bin/codex'),
-    path.join(home, '.volta/bin/codex'),
-    path.join(home, '.asdf/shims/codex'),
-    path.join(home, '.npm-global/bin/codex'),   // the two npm prefixes people
-    path.join(home, '.npm-packages/bin/codex'), // actually write in a guide
-    path.join(home, '.yarn/bin/codex'),
-    path.join(home, 'Library/pnpm/codex'),    // pnpm's own bin on macOS
-    path.join(home, '.local/share/pnpm/codex'), // pnpm's own bin on Linux
-    path.join(home, '.deno/bin/codex'),
-    path.join(home, 'bin/codex'),             // a hand-rolled ~/bin on PATH
-    '/opt/local/bin/codex',                   // MacPorts
-    '/usr/bin/codex',
-  ];
-}
+const CODEX = ENGINES.codex;
 
-// One bin directory per installed Node, under a name no list can hold. A global
-// npm install under nvm, fnm, n or asdf lands there and nowhere else, and a
-// double-clicked Electron app inherits launchd's PATH, which has never heard of
-// any of them.
-export function versionedPaths(home = os.homedir(), readdir = defaultReaddir) {
-  const under = (dir, tail) => readdir(path.join(home, dir)).map((v) => path.join(home, dir, v, tail));
-  return [
-    ...under('.nvm/versions/node', 'bin/codex'),
-    ...under('.local/share/fnm/node-versions', 'installation/bin/codex'),
-    ...under('Library/Application Support/fnm/node-versions', 'installation/bin/codex'),
-    ...under('n/versions/node', 'bin/codex'),
-    ...under('.asdf/installs/nodejs', 'bin/codex'),
-  ];
+export const INSTALL_URL = CODEX.installUrl;
+
+/** Every normal home for this binary, in order; the first that exists wins. */
+export function candidatePaths(home = os.homedir()) {
+  return CODEX.candidates(home, () => []);
 }
 
-function defaultReaddir(dir) {
-  try { return fs.readdirSync(dir); } catch { return []; }
+/** One bin directory per installed Node, read rather than guessed. */
+export function versionedPaths(home = os.homedir(), readdir = undefined) {
+  return versionedBinPaths('codex', home, readdir);
 }
 
-// THE COPY THE CHATGPT APP CARRIES INSIDE ITSELF. Somebody who has only ever
-// used Codex in the ChatGPT app has this and nothing else (w-9f6975906c,
-// measured 2026-10-05: codex-cli 0.158.0-alpha.2, sharing the CLI's sign-in).
-// Searched LAST, after the shell, because it moves with the app's releases.
-//
-// AND THE ONE THE CODEX DESKTOP APP CARRIES (w-d5d632e503). Its reported place,
-// not measured on a Mac here: none of the Macs this was written on had the app.
-// A path that is not there costs one missed `exists`.
+/** The copies the ChatGPT and Codex desktop apps carry inside themselves. */
 export function appCopyPaths(home = os.homedir()) {
-  const inside = ['ChatGPT.app/Contents/Resources/codex-cli/bin/codex', 'Codex.app/Contents/Resources/codex'];
-  return inside.flatMap((p) => [path.join('/Applications', p), path.join(home, 'Applications', p)]);
+  return CODEX.appCopies(home);
 }
 
-// WHAT CODEX LEAVES BEHIND. None of these is a binary and none is ever spawned.
-// They exist only to stop the app claiming an absence it has not established.
-//
-// Both homes are looked in when CODEX_HOME is set, and that is on purpose: a
-// CODEX_HOME inherited from somewhere else is not proof the ordinary directory
-// is gone, and the whole job of this list is to make an absence hard to claim
-// rather than easy.
+/** What Codex leaves behind. None of it is ever spawned. */
 export function evidencePaths(home = os.homedir(), env = process.env) {
-  const homes = [env?.CODEX_HOME, path.join(home, '.codex')].filter(Boolean);
-  const out = [];
-  for (const dir of new Set(homes)) {
-    out.push(
-      path.join(dir, 'auth.json'),                    // it has been logged in
-      path.join(dir, 'config.toml'),
-      path.join(dir, 'sessions'),                     // one folder tree of past runs
-      path.join(dir, 'history.jsonl'),
-      path.join(dir, 'packages/standalone/releases'), // the installer's version store
-      dir,                                            // and the directory itself, last
-    );
-  }
-  return out;
+  return CODEX.evidence(home, env);
 }
 
-// A path that is a symlink to nothing. `existsSync` follows the link and says
-// false, which is indistinguishable from nothing being there at all, and the
-// two mean opposite things. Both of Codex's normal installs are a symlink into
-// a versioned directory that gets swapped on every update, so this is the
-// ordinary shape of a Codex that is being upgraded rather than an odd one.
-function defaultDangles(p) {
-  try { return !!fs.lstatSync(p) && !fs.existsSync(p); } catch { return false; }
+export function installEvidence({ home = os.homedir(), env = process.env, exists, dangles } = {}) {
+  return evidenceFor('codex', { home, env, exists, dangles });
 }
 
-export function installEvidence({
-  home = os.homedir(), env = process.env, exists = fs.existsSync, dangles = defaultDangles,
-} = {}) {
-  for (const p of evidencePaths(home, env)) if (exists(p)) return p;
-  for (const p of candidatePaths(home)) if (dangles(p)) return p;
-  return null;
+/** The whole search. See main/engine-bin.mjs for what each answer means. */
+export function findCodexBin(where = {}) {
+  return findEngine('codex', where);
 }
 
-export const INSTALL_URL = 'https://learn.chatgpt.com/docs/codex/cli';
-
-/**
- * The whole search, a pure function of its inputs so a test can put Codex
- * anywhere without touching the machine it runs on.
- *
- * Returns the same shape its sibling does: { path, found, certain, from,
- * searched, evidence }, so a caller can hold the two side by side without
- * learning two vocabularies.
- */
-export function findCodexBin({
-  configured = null,
-  home = os.homedir(),
-  env = process.env,
-  exists = fs.existsSync,
-  shellLookup = () => askShell({ bin: 'codex' }),
-  readdir = defaultReaddir,
-  dangles = defaultDangles,
-} = {}) {
-  if (configured) {
-    return {
-      path: configured, found: exists(configured), certain: true, from: 'settings',
-      searched: [], evidence: null,
-    };
-  }
-
-  const searched = [...candidatePaths(home), ...versionedPaths(home, readdir)];
-  for (const candidate of searched) {
-    if (exists(candidate)) return { path: candidate, found: true, certain: true, from: 'disk', searched, evidence: null };
-  }
-
-  const fromShell = shellSaid(shellLookup());
-  if (fromShell.path) return { path: fromShell.path, found: true, certain: true, from: 'shell', searched, evidence: null };
-
-  for (const candidate of appCopyPaths(home)) {
-    if (exists(candidate)) return { path: candidate, found: true, certain: true, from: 'app', searched, evidence: null };
-  }
-
-  // NOT FOUND, AND WHETHER THAT IS KNOWN. Every cheap path missed and every
-  // shell we could reach missed, so the last question is whether this Mac shows
-  // any sign of Codex anyway.
-  const evidence = installEvidence({ home, env, exists, dangles });
-  return {
-    path: null,
-    found: false,
-    certain: fromShell.answered && !evidence,
-    from: null,
-    searched,
-    evidence,
-  };
-}
-
-// askShell used to answer with a path or null. Anything handing back the old
-// shape is read as an answer, because that is what it always meant.
-function shellSaid(result) {
-  if (typeof result === 'string') return { path: result, answered: true };
-  if (!result || typeof result !== 'object') return { path: null, answered: true };
-  return { path: result.path ?? null, answered: result.answered !== false };
-}
-
-/* ------------------------------- the cache -------------------------------- */
-// Only the SHELL step is remembered, for the same thirty seconds and the same
-// reason: the path checks are stat calls, and caching those is how a settings
-// screen ends up still saying "not found" after somebody has installed it.
-
-const SHELL_TTL = 30_000;
-let shellAnswer = null;
-let shellAskedAt = 0;
-
-export function resolveCodexBin(configured = null, { now = Date.now(), shellLookup = () => askShell({ bin: 'codex' }), ...where } = {}) {
-  const remembered = () => {
-    if (shellAskedAt && now - shellAskedAt < SHELL_TTL) return shellAnswer;
-    shellAnswer = shellLookup();
-    shellAskedAt = now;
-    return shellAnswer;
-  };
-  return findCodexBin({ ...where, configured, shellLookup: remembered });
+/** The same search with the shell step held for thirty seconds. */
+export function resolveCodexBin(configured = null, where = {}) {
+  return resolveEngine('codex', configured, where);
 }
 
 export function forgetCodexBin() {
-  shellAnswer = null;
-  shellAskedAt = 0;
+  forgetEngine('codex');
 }