agentbox-app 0.1.6

package/main/claude-bin.mjs

@@ -0,0 +1,311 @@
+// Where Claude Code actually is, on a machine that is not hers.
+//
+// Agentbox assumed one path, `~/.local/bin/claude`, which is where Claude Code's
+// own installer puts it. That is one of several normal answers: install through
+// npm or Homebrew and the binary is somewhere else entirely. For those people
+// the app found nothing, said "missing" on a grey dot in Settings, and gave no
+// sentence and no next step. It read as broken rather than as unfinished.
+//
+// HER RULE, 2026-08-23, and it is the one this file exists to keep:
+//
+// So there are two different questions here and they must never be answered by
+// the same value. `found` is whether a runnable file is really there, and it
+// decides which path gets spawned. `certain` is whether we are entitled to SAY
+// it is missing, and everything below exists to make `certain` hard to earn.
+//
+// Four steps before an absence is ever claimed, cheapest first.
+//
+// KNOWN PATHS. A filesystem check is instant, spawns nothing, and is the right
+// answer for most machines. The list is every normal home for this binary: the
+// installer's own directory, Claude Code's local install (what
+// `claude migrate-installer` leaves behind), Homebrew on Apple Silicon and on
+// Intel, MacPorts, and the default bin of every package manager that is not npm.
+//
+// VERSION MANAGER DIRECTORIES. nvm, fnm, n and asdf each keep one bin directory
+// PER INSTALLED NODE, under a name nobody can guess, so they are read rather
+// than listed. A global npm install under any of them lands there and nowhere
+// else, and this is the case the shell step used to be the only cover for.
+//
+// THE SHELL. The catch-all for installs no list can enumerate: volta, bun, a
+// custom npm prefix. It must be a LOGIN, INTERACTIVE shell, because those
+// managers put themselves on PATH from `.zprofile` and `.zshrc` and nowhere
+// else. And it is needed at all because a double-clicked Electron app inherits
+// launchd's PATH, which is /usr/bin:/bin:/usr/sbin:/sbin and has never heard of
+// any of them. That is the whole reason an npm install is obvious in a terminal
+// and invisible to the app. It is asked more than once now, because ONE probe
+// that fails to start is not a fact about anybody's Mac.
+//
+// EVIDENCE THAT IT LIVES HERE ANYWAY. Last, and it decides nothing about which
+// binary to run: it only takes away our right to announce an absence. Claude
+// Code leaves a home folder, a settings file and a projects directory behind
+// the moment it is used once. If those are on this Mac then Claude Code is on
+// this Mac, whatever our search of PATH did or did not manage, and the honest
+// thing on the screen is silence rather than a sentence telling somebody to
+// install software they are already running. A dangling `claude` symlink counts
+// the same way, and it is a real state: the installer points ~/.local/bin/claude
+// at a versioned file and swaps that file on every update.
+//
+// Nothing here overrides her file. An explicit `claudeBin` in zero.config.json
+// wins untouched and is never searched around, because that file's first line
+// is "all paths explicit, no discovery magic" and a search that second-guesses
+// a setting she wrote is exactly that.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// In order. The first that exists wins, so the installer's path stays first and
+// a machine that has always worked keeps resolving exactly as it did.
+export function candidatePaths(home = os.homedir()) {
+  return [
+    path.join(home, '.local/bin/claude'),    // the installer
+    path.join(home, '.claude/local/claude'), // claude migrate-installer
+    '/opt/homebrew/bin/claude',              // Homebrew, Apple Silicon
+    '/usr/local/bin/claude',                 // Homebrew on Intel, and npm -g
+    path.join(home, '.bun/bin/claude'),      // bun
+    path.join(home, '.volta/bin/claude'),    // volta
+    path.join(home, '.asdf/shims/claude'),   // asdf, through its shims
+    path.join(home, '.npm-global/bin/claude'), // the two npm prefixes people
+    path.join(home, '.npm-packages/bin/claude'), // actually write in a guide
+    path.join(home, '.yarn/bin/claude'),     // yarn global
+    path.join(home, 'Library/pnpm/claude'),  // pnpm's own bin on macOS
+    path.join(home, '.deno/bin/claude'),     // deno
+    path.join(home, 'bin/claude'),           // a hand-rolled ~/bin on PATH
+    '/opt/local/bin/claude',                 // MacPorts
+    '/usr/bin/claude',                       // packaged by something system-wide
+  ];
+}
+
+// One bin directory per installed Node, under a name no list can hold. Read
+// rather than guessed, and a directory that is not there just contributes
+// nothing. This is where a global npm install under nvm, fnm, n or asdf ends
+// up, and until now only the shell could reach it.
+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/claude'),
+    ...under('.local/share/fnm/node-versions', 'installation/bin/claude'),
+    ...under('Library/Application Support/fnm/node-versions', 'installation/bin/claude'),
+    ...under('n/versions/node', 'bin/claude'),
+    ...under('.asdf/installs/nodejs', 'bin/claude'),
+  ];
+}
+
+function defaultReaddir(dir) {
+  try { return fs.readdirSync(dir); } catch { return []; }
+}
+
+// WHAT CLAUDE CODE LEAVES BEHIND. Any one of these means it has run on this
+// Mac. None of them is a binary and none of them is ever spawned; they exist
+// only to stop the app announcing an absence it cannot support.
+export function evidencePaths(home = os.homedir()) {
+  return [
+    path.join(home, '.claude.json'),               // its own config file
+    path.join(home, '.claude/settings.json'),
+    path.join(home, '.claude/projects'),           // one folder per project it has opened
+    path.join(home, '.claude/statsig'),
+    path.join(home, '.claude/.credentials.json'),  // it has been logged in
+    path.join(home, '.claude/history.jsonl'),
+    path.join(home, '.local/share/claude'),        // the installer's version store
+  ];
+}
+
+// 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: an update that has swapped the versioned file out
+// from under ~/.local/bin/claude leaves exactly this for a moment.
+function defaultDangles(p) {
+  try { return !!fs.lstatSync(p) && !fs.existsSync(p); } catch { return false; }
+}
+
+export function installEvidence({ home = os.homedir(), exists = fs.existsSync, dangles = defaultDangles } = {}) {
+  for (const p of evidencePaths(home)) if (exists(p)) return p;
+  for (const p of candidatePaths(home)) if (dangles(p)) return p;
+  return null;
+}
+
+export const INSTALL_URL = 'https://code.claude.com/docs/en/setup';
+
+// The shells worth asking, in order, and never the same one twice. Hers first
+// because it is the one that has her PATH in it; the other two because a
+// $SHELL that will not start is a fact about $SHELL and not about Claude Code.
+export function shellProbes(env = process.env) {
+  const preferred = env.SHELL || '/bin/zsh';
+  const out = [[preferred, '-lic', 4000], [preferred, '-lc', 2500]];
+  for (const other of ['/bin/zsh', '/bin/bash']) {
+    if (other !== preferred) out.push([other, '-lic', 2500]);
+  }
+  return out;
+}
+
+// Ask the user's own login shell, and go on asking until one of them answers.
+// Anything that is not an absolute path to a file that exists is treated as no
+// path: `command -v` also prints shell functions and aliases, and a function
+// name handed to spawn is a crash with a worse message than "not found".
+//
+// `answered` is the strict half. It is true only when every probe that ran came
+// back with a real exit status, and at least one did. One shell that timed out
+// alongside one that said no is not a machine we know anything about.
+//
+// `bin` is a parameter rather than the word `claude` baked into the command
+// because Codex is a second engine (her ask, 2026-08-25) and it is found in the
+// same way: same shells, same "two different silences" rule, same refusal to
+// read a shell function name as a path. It is DEFAULTED, so every existing
+// caller and every existing test asks about Claude Code as it always did, and
+// that matters more here than it would anywhere else: this is the binary the
+// app will not open an inbox without.
+/**
+ * WHAT MAY BE HANDED TO A LOGIN SHELL, AND WHY THIS IS CHECKED AT ALL.
+ *
+ * The probe below interpolates `bin` into a string a LOGIN, INTERACTIVE shell
+ * executes, with her profile loaded, as her. Both callers today pass a literal
+ * ('claude' here, 'codex' in main/codex-bin.mjs), so nothing is exploitable
+ * now. But the entire direction of the second-engine work is a binary somebody
+ * can configure, and a `codexBin` read out of zero.config.json reaching this
+ * argument is one plausible slice away; at that point `command -v x; curl | sh`
+ * is a string in a file that runs itself.
+ *
+ * This function looks up program NAMES, so a name is all it takes. An allowlist
+ * rather than quoting, because quoting is a thing a later edit can undo without
+ * noticing and a shape check is not.
+ */
+const PROGRAM_NAME = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+
+export function askShell({ env = process.env, exists = fs.existsSync, run = defaultRun, bin = 'claude' } = {}) {
+  if (typeof bin !== 'string' || !PROGRAM_NAME.test(bin)) {
+    throw new Error(`askShell looks up a program name, and ${JSON.stringify(bin)} is not one`);
+  }
+  let said = false;
+  let inconclusive = false;
+  for (const [shell, flags, timeout] of shellProbes(env)) {
+    let out = '';
+    try {
+      out = run(shell, [flags, `command -v ${bin}`], timeout);
+    } catch (e) {
+      // TWO DIFFERENT SILENCES, AND ONLY ONE OF THEM IS AN ANSWER.A shell that
+      // ran and exited non-zero has told us claude is not on PATH, and that is
+      // an answer. A shell that could not be started, or that ran past the
+      // timeout, has told us nothing at all, and reporting nothing as "not
+      // installed" is what put a line about missing software on the screen of
+      // people who have it.
+      if (exitedSayingNo(e)) said = true; else inconclusive = true;
+      continue;
+    }
+    const line = String(out).split('\n').map((s) => s.trim()).filter(Boolean).pop();
+    if (line && line.startsWith('/') && exists(line)) return { path: line, answered: true };
+    said = true;
+  }
+  return { path: null, answered: said && !inconclusive };
+}
+
+// The shell ran to completion and returned a non-zero exit code, which for
+// `command -v` is how "not on PATH" is spelt. A timeout (SIGTERM, ETIMEDOUT)
+// and a shell that does not exist (ENOENT) both arrive here too, and neither
+// of them is a fact about Claude Code.
+function exitedSayingNo(e) {
+  if (!e || typeof e !== 'object') return false;
+  if (e.signal || e.code === 'ETIMEDOUT' || e.code === 'ENOENT') return false;
+  return typeof e.status === 'number';
+}
+
+// askShell used to answer with a path or null, and both a real answer and a
+// failed probe were null. Anything still 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 };
+}
+
+function defaultRun(shell, args, timeout = 4000) {
+  return execFileSync(shell, args, {
+    encoding: 'utf8',
+    // stdin ignored on purpose: an interactive shell handed a live terminal can
+    // sit waiting for input, and this runs on the boot path.
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout,
+  });
+}
+
+// The whole search, as a pure function of its inputs so a test can put Claude
+// Code anywhere without touching the machine it runs on.
+//
+// Returns { path, found, certain, from, searched, evidence }. `found` is the
+// only claim about the world: it means a file is really there. `certain` says
+// whether we are allowed to tell somebody it is NOT there, so a screen can stay
+// quiet rather than announce an absence it has not established. They come apart
+// in exactly one case that is not a failure, and it is the case worth keeping
+// honest: she has set `claudeBin` to a path that does not exist, so the path
+// stays HERS (anything that spawns it should fail naming the path she chose,
+// not one we picked) while the screen says it was not found and offers the
+// install link, the same as any other machine.
+export function findClaudeBin({
+  configured = null,
+  home = os.homedir(),
+  exists = fs.existsSync,
+  shellLookup = askShell,
+  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 };
+
+  // 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 Claude Code anyway. If it does, we looked in the wrong places
+  // rather than at an empty machine, and nothing may be said out loud.
+  const evidence = installEvidence({ home, exists, dangles });
+  return {
+    path: null,
+    found: false,
+    certain: fromShell.answered && !evidence,
+    from: null,
+    searched,
+    evidence,
+  };
+}
+
+/* ------------------------------- the cache -------------------------------- */
+// Only the SHELL step is remembered, and only briefly. Nothing else is: the
+// path checks are stat calls, and caching them is how the settings screen ends
+// up telling someone to install Claude Code and then still saying "not found"
+// after they have. The sentence on that screen makes a promise and a cached
+// answer breaks it.
+//
+// The shell is the one part worth holding, because it is up to three
+// subprocesses and a screen she toggles a switch on reads settings again on
+// every write. Thirty seconds is long enough that a burst of writes pays for it
+// once, and short enough that it is never the reason someone is still stuck.
+
+const SHELL_TTL = 30_000;
+let shellAnswer = null;
+let shellAskedAt = 0;
+
+function rememberedShellLookup(now, lookup) {
+  if (shellAskedAt && now - shellAskedAt < SHELL_TTL) return shellAnswer;
+  shellAnswer = lookup();
+  shellAskedAt = now;
+  return shellAnswer;
+}
+
+export function resolveClaudeBin(configured = null, { now = Date.now(), shellLookup = askShell, ...where } = {}) {
+  return findClaudeBin({ ...where, configured, shellLookup: () => rememberedShellLookup(now, shellLookup) });
+}
+
+export function forgetClaudeBin() {
+  shellAnswer = null;
+  shellAskedAt = 0;
+}

package/main/claude-input.mjs

@@ -0,0 +1,117 @@
+import { randomUUID } from 'node:crypto';
+
+// THE SESSION STOPPED LISTENING BEFORE IT TOOK THIS MESSAGE. Not a refusal:
+// the turn closed, or the process went, in the seconds between her pressing
+// send and the line reaching it. `submitReply` saves such a message as an
+// ordinary reply, which the next run picks up, instead of throwing it back
+// at her with "The turn has ended" (w-12730c6506).
+export const TURN_CLOSED = 'TURN_CLOSED';
+function turnClosed(message) {
+  const error = Error(message);
+  error.code = TURN_CLOSED;
+  return error;
+}
+
+export function claudeStreamArgs(args) {
+  const copy = [...args];
+  const index = copy.indexOf('-p');
+  if (index < 0) throw Error('Missing print prompt');
+  copy.splice(index + 1, 1);
+  return [...copy, '--input-format', 'stream-json', '--replay-user-messages'];
+}
+
+// Replay-user-messages acknowledges the exact UUID when Claude consumes it.
+// A result for earlier work must not close stdin over queued corrections.
+export function attachClaudeInput(child) {
+  let closed = false, buffer = '', atResult = false, held = false;
+  const controls = new Map();
+  const seenUsers = new Set();
+  const pending = new Map();
+  const closeInput = () => { closed = true; child.stdin.end(); };
+  const fail = reason => {
+    closed = true;
+    for (const request of pending.values()) {
+      clearTimeout(request.timer);
+      request.reject(turnClosed(reason));
+    }
+    pending.clear();
+    for (const request of controls.values()) { clearTimeout(request.timer); request.reject(Error(reason)); }
+    controls.clear();
+  };
+  child.on('exit', () => fail('The agent exited before confirming this correction.'));
+  child.on('error', () => fail('The agent could not receive this correction.'));
+  child.stdin.on('error', () => fail('The agent input connection closed.'));
+  child.stdout.on('data', data => {
+    buffer += String(data);
+    let index;
+    while ((index = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, index);
+      buffer = buffer.slice(index + 1);
+      let event;
+      try { event = JSON.parse(line); } catch { continue; }
+      if (event.type === 'control_response') {
+        const response = event.response, request = controls.get(response?.request_id);
+        if (request) { controls.delete(response.request_id); clearTimeout(request.timer);
+          if (response.subtype === 'success') request.resolve(response.response ?? {});
+          else request.reject(Error(response.error || 'The provider rejected this operation.'));
+        }
+      }
+      if (event.type === 'system' && event.subtype === 'bridge_state') child.emit('bridge-state', event);
+      if (event.type === 'assistant') atResult = false;
+      if (event.type === 'user' && !event.parent_tool_use_id && typeof event.uuid === 'string' && !seenUsers.has(event.uuid)) {
+        seenUsers.add(event.uuid);
+        const content = event.message?.content;
+        const text = typeof content === 'string' ? content : Array.isArray(content) ? content.filter(b => b.type === 'text').map(b => b.text).join('\n') : '';
+        if (held && !pending.has(event.uuid) && text && !event.isMeta) child.emit('remote-user', event);
+        if (text) { atResult = false; child.emit('input-turn', event); }
+      }
+      if (event.type === 'user' && pending.has(event.uuid)) {
+        const request = pending.get(event.uuid);
+        pending.delete(event.uuid);
+        clearTimeout(request.timer);
+        atResult = false;
+        request.resolve({ accepted: true });
+      }
+      if (event.type === 'result') {
+        atResult = true;
+        if (!held && !pending.size) closeInput();
+      }
+    }
+  });
+  child.holdInput = value => {
+    if (closed && value) throw Error('This session has ended. Open remote control again to resume it.');
+    held = !!value;
+    if (!held && atResult && !pending.size) closeInput();
+  };
+  child.control = (request, timeoutMs = 30000) => new Promise((resolve, reject) => {
+    if (closed || !child.stdin.writable) return reject(Error('The agent connection is closed.'));
+    const request_id = randomUUID();
+    const timer = setTimeout(() => { controls.delete(request_id); reject(Error('The provider did not confirm the remote-control operation.')); }, timeoutMs);
+    timer.unref?.();
+    controls.set(request_id, { resolve, reject, timer });
+    try { child.stdin.write(JSON.stringify({ type:'control_request', request_id, request }) + '\n'); }
+    catch(error) { clearTimeout(timer); controls.delete(request_id); reject(error); }
+  });
+  // NO CLOCK ON THE ACKNOWLEDGEMENT. Claude replays a queued message at its next
+  // break, and a break can be minutes away: a worker inside one long command
+  // (a render poll, `sleep 12` fifty times) holds it until the command returns.
+  // This used to reject at 120s with "delivery is uncertain", which the
+  // renderer read as a failed send: it pulled her back to the row, put her
+  // words back in the box, and the agent then took the ORIGINAL anyway, so the
+  // one she re-sent arrived twice (w-d92559b84f: queued 22:21:00, taken
+  // 22:24:10, re-sent 22:24:34). Once the line is on stdin the CLI owns it, so
+  // the only real failures are the ones `fail` already hears: exit, error,
+  // stdin closing.
+  child.steer = text => new Promise((resolve, reject) => {
+    if (closed || !child.stdin.writable) return reject(turnClosed('The turn has ended. Send the message again to continue it.'));
+    const uuid = randomUUID();
+    pending.set(uuid, { resolve, reject });
+    try {
+      child.stdin.write(JSON.stringify({ type: 'user', uuid, message: { role: 'user', content: text }, parent_tool_use_id: null, session_id: '' }) + '\n');
+    } catch (error) {
+      pending.delete(uuid);
+      reject(turnClosed(error?.message || 'The agent input connection closed.'));
+    }
+  });
+  return child;
+}

package/main/claude-models.mjs

@@ -0,0 +1,244 @@
+// WHICH MODELS CLAUDE CODE CAN BE ASKED FOR, READ OFF THIS MAC AT THE MOMENT
+// IT IS ASKED, RATHER THAN AT THE MOMENT AGENTBOX WAS BUILT.
+//
+// WHAT WAS ALREADY RIGHT, AND IS NOT CHANGED HERE. Agentbox sends the CLI an
+// ALIAS (`--model opus`), never a version, so the RUN is already on whatever
+// Opus is on the day it spawns. Nothing about that needed fixing, and this file
+// does not touch it.
+//
+// WHAT WAS WRONG IS THE WORD ON THE SCREEN. The picker's labels came out of
+// `shared/claude-models.generated.mjs`, written by
+// `scripts/read-claude-models.mjs` at BUILD time. That was built to stop a
+// typed label drifting from the model that runs, and it does. But a table
+// frozen at build time drifts from the model that runs in the other direction:
+// she updates Claude Code, the alias starts resolving somewhere newer, and her
+// picker keeps printing the old name until somebody rebuilds Agentbox. MEASURED
+// 2026-09-22 and this is exactly what happened: her Claude Code 2.1.270
+// resolves `opus` to `claude-opus-5`; 2.1.280, published the same week,
+// resolves it to `claude-opus-5-5` ("Opus 5.5"). The build table could not have
+// known.
+//
+// SO IT IS READ AT THE MOMENT IT IS ASKED FOR, which is the stance
+// main/codex-models.mjs already takes beside this one for the same reason, and
+// hers is the same question both times. One `statSync` decides whether the
+// answer is still good; a `claude update` changes the binary's size and mtime,
+// so the next read is a fresh one and her picker says the new name with no
+// rebuild and no release.
+//
+// AND THE FAMILIES ARE READ TOO, NOT LISTED. The build script carries a typed
+// `WANTED = ['opus','sonnet','haiku','fable']`, which is her order and is also
+// the reason a brand new family could never appear on its own. Here, her four
+// come first in her order and EVERY OTHER ALIAS THE CLI RESOLVES follows them.
+// If Anthropic ships a fifth family tomorrow, it is in her picker the moment she
+// updates Claude Code, labelled with Claude Code's own name for it.
+//
+// THE COMMITTED TABLE IS STILL THE FLOOR. A Mac with no Claude Code on it, or a
+// Claude Code whose catalog this can no longer read, answers with the generated
+// list rather than with nothing. An empty picker is a worse answer than a
+// slightly old one, and it is the one failure that would stop her sending a task
+// at all.
+
+import fs from 'node:fs';
+import { CLAUDE_MODELS, READ_FROM } from '../shared/claude-models.generated.mjs';
+
+/**
+ * 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
+ * added on. */
+export const HER_ORDER = ['opus', 'sonnet', 'haiku', 'fable'];
+
+// The binary is ~200 MB, so it is read in chunks with an overlap longer than the
+// longest record we care about, exactly as scripts/read-claude-commands.mjs does.
+const CHUNK = 8 * 1024 * 1024;
+const OVERLAP = 64 * 1024;
+
+/** The alias table: which model id each family word resolves to. */
+export function readAliases(text) {
+  const m = text.match(/latest_per_family:\{([^}]*)\}/);
+  if (!m) return null;
+  const out = {};
+  for (const [, alias, id] of m[1].matchAll(/([a-z_]+):"([^"]+)"/g)) out[alias] = id;
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * Every model in the catalog that carries a display name of its own, IN THE
+ * ORDER THE CATALOG LISTS THEM.
+ *
+ * The order is load-bearing now and it was not before. Her pick on this item is
+ * that the drawer names the model before the newest one as well, and "the one
+ * before" has to come from somewhere. Parsing a version out of the id cannot do
+ * it: the ids are not one shape, since `claude-3-5-haiku` and `claude-haiku-4-5`
+ * are both real and sit on either side of a naming change, so a comparator over
+ * them is a guess that will one day sort a newer model as older and quietly
+ * offer the wrong one.
+ *
+ * The catalog is already ascending within each family, and it is the same order
+ * Claude Code's own picker uses. MEASURED against 2.1.270 and 2.1.280 on
+ * 2026-09-22: haiku 3.5 then 4.5; sonnet 3.5, 3.7, 4, 4.5, 4.6, 5; opus 4, 4.1,
+ * 4.5, 4.6, 4.7, 4.8, 5, 5.5; fable 5 then 5.1. So "the one before" is the entry
+ * immediately before the alias's own, inside its family, and no version number
+ * is ever read by us.
+ */
+export function readNames(text) {
+  const out = [];
+  for (const m of text.matchAll(/id:"(claude-[a-z0-9-]+)",family:"([a-z]+)",display_name:"([^"]+)"(.{0,1200}?)(?=id:"claude-|$)/gs)) {
+    const [, id, family, label, rest] = m;
+    out.push({ id, family, label, defaultLevel: rest.match(/default_effort:"([a-z]+)"/)?.[1] ?? null });
+  }
+  return out;
+}
+
+/** The catalog's own name for one id, or undefined if it names none. */
+export const nameOf = (names, id) => names.find((n) => n.id === id)?.label;
+
+// AND HOW HARD THAT MODEL THINKS WHEN NOBODY SAYS.
+//
+// The strip drew nothing lit because this app genuinely did not know the answer,
+// and shared/effort-levels.mjs says so in as many words: "a level nobody picked
+// is the engine's own choice for the model... and this app does not know what
+// that is per model, so it does not claim to." That was true and it is not any
+// more. Claude Code's catalog carries `default_effort` on each model, beside the
+// display name this file already reads, exactly as Codex's cache carries
+// `default_reasoning_level` (main/codex-models.mjs reads that one already).
+//
+// AND IT REALLY IS PER MODEL, which is why a single typed word would have been
+// wrong. MEASURED out of 2.1.280 on 2026-09-22: Opus 5.5 medium, Opus 5 high,
+// Opus 4.8 high, Opus 4.7 xhigh, Sonnet 5 high, Fable 5.1 high. So the word the
+// strip lights changes when she changes model, and it is read rather than
+// guessed, for the same reason the label beside it is.
+//
+// NULL IS A REAL ANSWER. A model the catalog gives no default_effort for, such
+// as Haiku 4.5 in 2.1.280, lights nothing, which is exactly what the strip did
+// before. Nothing here invents a level.
+
+/**
+ * Walk the binary once for both halves of the catalog.
+ *
+ * IT STOPS EARLY ON PURPOSE. Claude Code keeps its catalog as one object
+ * literal, so the alias table and every display name sit inside a few hundred
+ * kilobytes of each other, and reading the remaining ~190 MB to find nothing is
+ * time she spends waiting for a picker to open. Measured on her Mac against
+ * 2.1.270: 82 ms for the whole file, 8 ms stopping at the alias table.
+ */
+export function scan(binPath, { chunk = CHUNK } = {}) {
+  let aliases = null;
+  const names = [];
+  const seen = new Set();
+  const fd = fs.openSync(binPath, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const buf = Buffer.alloc(chunk + OVERLAP);
+    for (let at = 0; at < size; at += chunk) {
+      const read = fs.readSync(fd, buf, 0, chunk + OVERLAP, at);
+      if (read <= 0) break;
+      const text = buf.toString('latin1', 0, read);
+      aliases = aliases ?? readAliases(text);
+      // The chunks overlap, so the same record is read twice at every seam and
+      // the second copy must not become a second row in a list whose ORDER is
+      // now what decides which model is offered as the previous one.
+      for (const m of readNames(text)) {
+        if (seen.has(m.id)) continue;
+        seen.add(m.id);
+        names.push(m);
+      }
+      // Both halves are in hand and they agree: there is nothing left to find.
+      if (aliases && Object.values(aliases).every((id) => seen.has(id))) break;
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return { aliases, names };
+}
+
+/* A family with only one model in the * catalog contributes one row, not a duplicate.
+*/
+export function rowsFrom({ aliases, names }) {
+  if (!aliases) return null;
+  const order = [...HER_ORDER, ...Object.keys(aliases).filter((a) => !HER_ORDER.includes(a)).sort()];
+  const rows = [];
+  for (const alias of order) {
+    const id = aliases[alias];
+    const self = names.find((x) => x.id === id);
+    const label = self?.label;
+    if (!id || !label) continue;
+    // `defaultLevel` travels beside the name rather than as a list of its own,
+    // the way main/codex-models.mjs carries its models' levels: it is per model,
+    // so a table of its own could disagree with the row it belongs to.
+    rows.push({ alias, id, label, defaultLevel: self.defaultLevel ?? null });
+    // The entry immediately before this one inside its own family. The catalog
+    // is ascending, so that is the model she was on before the newest shipped.
+    const family = names.filter((n) => n.family === self.family);
+    const before = family[family.findIndex((n) => n.id === id) - 1];
+    if (before) {
+      rows.push({ alias: before.id, id: before.id, label: before.label, defaultLevel: before.defaultLevel ?? null });
+    }
+  }
+  return rows.length ? rows : null;
+}
+
+/* --------------------------------- caching -------------------------------- */
+// KEYED ON THE BINARY ITSELF, NOT ON A CLOCK. main/codex-models.mjs refuses to
+// cache at all, and says why: caching a cheap read is how a screen ends up still
+// saying the old answer after the thing changed underneath it. Its read is one
+// 199 KB parse. This one is a walk through a 200 MB file, which is not cheap
+// enough to repeat on every settings read while she is typing, so it is cached
+// against the one fact that decides whether the answer can still be right: the
+// path, size and mtime of the binary that produced it. `claude update` replaces
+// that file, so the very next read is a fresh one. There is no staleness window
+// and no interval to tune.
+let memo = null;
+
+/** Exported for the tests, and for anything that has a reason to force a re-read. */
+export function forget() { memo = null; }
+
+function stampOf(binPath) {
+  try {
+    const s = fs.statSync(binPath);
+    return `${binPath}:${s.size}:${s.mtimeMs}`;
+  } catch { return null; }
+}
+
+/**
+ * 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.
+ *
+ * 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
+ * asking a login shell when the known folders miss. main/codex-models.mjs states
+ * the rule this follows: a picker must never be the reason a shell is spawned
+ * while she is typing.
+ *
+ * AND NOTHING HERE SPAWNS ANYTHING EITHER. An earlier draft asked the CLI its
+ * `--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'`.
+ */
+export function claudeModels({ bin = null } = {}) {
+  const built = {
+    models: CLAUDE_MODELS.map((m) => ({
+      alias: m.alias, id: m.id, label: m.label, defaultLevel: m.defaultLevel ?? null,
+    })),
+    readFrom: READ_FROM,
+    source: 'built',
+  };
+  if (!bin) return built;
+  const stamp = stampOf(bin);
+  if (!stamp) return built;
+  if (memo?.stamp === stamp) return memo.value;
+  let rows = null;
+  try { rows = rowsFrom(scan(bin)); } catch { rows = null; }
+  // A CLI WE CANNOT READ IS NOT A REASON TO DRAW AN EMPTY PICKER, and it is not
+  // a reason to stop either: this is the labelling, not the spawn, and the alias
+  // Agentbox sends works whether or not this file could find the table it is in.
+  const value = rows ? { models: rows, readFrom: null, source: 'cli' } : built;
+  memo = { stamp, value };
+  return value;
+}
+
+/** Just the rows, for the callers that do not care where they came from. */
+export function claudeModelRows(opts = {}) { return claudeModels(opts).models; }