@amenophis1er/foreman 0.1.0

package/src/cli.ts

@@ -0,0 +1,297 @@
+/**
+ * The subcommands behind `foreman` that are not "start the server".
+ *
+ *  doctor   The preflight, and nothing else: what this machine can run, what
+ *           is missing, how to fix it. Exit 0 when nothing blocks.
+ *  open     The dashboard, in the default browser.
+ *  up/down  A background server without registering anything: a detached
+ *           child, a pid file and a log under ~/.foreman. For "just run it";
+ *           `service install` is for "always run it".
+ *  service  Keep Foreman up without a terminal: a launchd agent on macOS, a
+ *           systemd user unit on Linux. Start at login, restart on crash,
+ *           log to ~/.foreman/logs. Foreman on the move needs the server to
+ *           be up when the laptop lid is closed; this is that.
+ */
+import { execFile, spawn } from 'node:child_process';
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { openSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { preflight, reportPreflight } from './preflight.js';
+import { detectTailscale } from './tailscale.js';
+
+const PORT = Number(process.env.PORT ?? 4177);
+const HOME_DIR = process.env.FOREMAN_HOME || path.join(os.homedir(), '.foreman');
+const LABEL = 'dev.foreman.server';
+const PID_FILE = path.join(HOME_DIR, 'foreman.pid');
+const LOG_FILE = path.join(HOME_DIR, 'logs', 'server.log');
+
+function sh(cmd: string, args: string[]): Promise<{ code: number; out: string; err: string }> {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: 20_000 }, (e, out, err) => {
+      const code = e ? (typeof (e as { code?: unknown }).code === 'number' ? (e as { code: number }).code : 1) : 0;
+      resolve({ code, out: String(out), err: String(err) });
+    });
+  });
+}
+
+/** The PATH a login agent gets is thin; node's own dir and the usual prefixes are added so `claude`, `tailscale`, `ollama` resolve. */
+export function servicePath(execPath: string, current = process.env.PATH ?? ''): string {
+  const parts = [path.dirname(execPath), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin', ...current.split(':')];
+  return [...new Set(parts.filter(Boolean))].join(':');
+}
+
+/** The launchd property list for the agent. Pure, so it can be read in a test and by a human. */
+export function launchdPlist(opts: { label: string; node: string; bin: string; home: string; logDir: string; env: Record<string, string> }): string {
+  const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  const envXml = Object.entries(opts.env).map(([k, v]) => `    <key>${esc(k)}</key><string>${esc(v)}</string>`).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${esc(opts.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${esc(opts.node)}</string>
+    <string>${esc(opts.bin)}</string>
+    <string>start</string>
+  </array>
+  <key>WorkingDirectory</key><string>${esc(opts.home)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>StandardOutPath</key><string>${esc(path.join(opts.logDir, 'server.log'))}</string>
+  <key>StandardErrorPath</key><string>${esc(path.join(opts.logDir, 'server.log'))}</string>
+</dict>
+</plist>
+`;
+}
+
+/** The systemd user unit. Same shape as the plist: start at login, restart on failure, one log. */
+export function systemdUnit(opts: { node: string; bin: string; home: string; env: Record<string, string> }): string {
+  const envLines = Object.entries(opts.env).map(([k, v]) => `Environment=${k}=${v.replace(/"/g, '\\"')}`).join('\n');
+  return `[Unit]
+Description=Foreman — autonomous mission runner
+After=network-online.target
+
+[Service]
+ExecStart=${opts.node} ${opts.bin} start
+WorkingDirectory=${opts.home}
+Restart=always
+RestartSec=5
+${envLines}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function serviceEnv(): Record<string, string> {
+  const env: Record<string, string> = { PATH: servicePath(process.execPath), HOME: os.homedir(), FOREMAN_HOME: HOME_DIR, PORT: String(PORT) };
+  for (const k of ['FOREMAN_BIND', 'FOREMAN_BROWSER', 'FOREMAN_CLAUDE_CONFIG_DIR', 'FOREMAN_CLAUDE_EXECUTABLE', 'FOREMAN_AUTH_MODE', 'CLAUDE_CONFIG_DIR']) {
+    if (process.env[k]) env[k] = process.env[k]!;
+  }
+  return env;
+}
+
+async function serviceInstall(bin: string): Promise<number> {
+  const logDir = path.join(HOME_DIR, 'logs');
+  await mkdir(logDir, { recursive: true });
+  const env = serviceEnv();
+  if (process.platform === 'darwin') {
+    const dir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+    const file = path.join(dir, `${LABEL}.plist`);
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, launchdPlist({ label: LABEL, node: process.execPath, bin, home: HOME_DIR, logDir, env }));
+    await chmod(file, 0o644);
+    const uid = String(os.userInfo().uid);
+    await sh('launchctl', ['bootout', `gui/${uid}/${LABEL}`]); // replace a previous registration quietly
+    const r = await sh('launchctl', ['bootstrap', `gui/${uid}`, file]);
+    if (r.code !== 0) { console.error(`launchctl bootstrap failed: ${r.err.trim() || r.out.trim()}`); return 1; }
+    console.log(`Installed ${file}\nForeman starts at login and restarts if it dies. Logs: ${path.join(logDir, 'server.log')}\nDashboard: http://localhost:${PORT}`);
+    return 0;
+  }
+  if (process.platform === 'linux') {
+    // A container, a minimal server, WSL without systemd: no user manager to
+    // talk to. Say that, and point at the way that still works.
+    const probe = await sh('systemctl', ['--user', 'is-system-running']);
+    const noManager = probe.code !== 0 && !/degraded|running|starting/.test(probe.out);
+    if (noManager) {
+      console.error('No systemd user session here (a container, or WSL without systemd). Use `foreman up`, or run `foreman` under your own supervisor.');
+      return 2;
+    }
+    const dir = path.join(os.homedir(), '.config', 'systemd', 'user');
+    const file = path.join(dir, 'foreman.service');
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, systemdUnit({ node: process.execPath, bin, home: HOME_DIR, env }));
+    for (const args of [['--user', 'daemon-reload'], ['--user', 'enable', '--now', 'foreman']]) {
+      const r = await sh('systemctl', args);
+      if (r.code !== 0) { console.error(`systemctl ${args.join(' ')} failed: ${(r.err.trim() || r.out.trim()) || 'no output — is a systemd user session running?'}`); return 1; }
+    }
+    console.log(`Installed ${file}\nForeman starts at login and restarts if it dies. Logs: journalctl --user -u foreman -f\nTip: \`loginctl enable-linger $USER\` keeps it up when you are logged out.\nDashboard: http://localhost:${PORT}`);
+    return 0;
+  }
+  console.error(`No service integration for ${process.platform} yet. \`foreman up\` runs it in the background; on Windows, Task Scheduler or WSL2 with systemd keeps it up.`);
+  return 2;
+}
+
+async function serviceUninstall(): Promise<number> {
+  if (process.platform === 'darwin') {
+    const file = path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+    await sh('launchctl', ['bootout', `gui/${os.userInfo().uid}/${LABEL}`]);
+    await rm(file, { force: true });
+    console.log('Removed. Foreman no longer starts at login.');
+    return 0;
+  }
+  if (process.platform === 'linux') {
+    await sh('systemctl', ['--user', 'disable', '--now', 'foreman']);
+    await rm(path.join(os.homedir(), '.config', 'systemd', 'user', 'foreman.service'), { force: true });
+    await sh('systemctl', ['--user', 'daemon-reload']);
+    console.log('Removed. Foreman no longer starts at login.');
+    return 0;
+  }
+  return 2;
+}
+
+async function serviceStatus(): Promise<number> {
+  if (process.platform === 'darwin') {
+    const r = await sh('launchctl', ['print', `gui/${os.userInfo().uid}/${LABEL}`]);
+    if (r.code !== 0) { console.log('Not installed. `foreman service install` keeps Foreman running.'); return 1; }
+    const state = /state = (\w+)/.exec(r.out)?.[1] ?? 'unknown';
+    const pid = /pid = (\d+)/.exec(r.out)?.[1];
+    console.log(`Installed · ${state}${pid ? ` · pid ${pid}` : ''} · http://localhost:${PORT}`);
+    return 0;
+  }
+  if (process.platform === 'linux') {
+    const r = await sh('systemctl', ['--user', 'is-active', 'foreman']);
+    console.log(r.out.trim() === 'active' ? `Installed · active · http://localhost:${PORT}` : `Installed? ${r.out.trim() || 'no'} — \`foreman service install\``);
+    return r.out.trim() === 'active' ? 0 : 1;
+  }
+  return 2;
+}
+
+async function serviceLogs(): Promise<number> {
+  if (process.platform === 'linux') {
+    const child = spawn('journalctl', ['--user', '-u', 'foreman', '-f', '-n', '100'], { stdio: 'inherit' });
+    return new Promise((r) => child.on('exit', (c) => r(c ?? 0)));
+  }
+  const file = path.join(HOME_DIR, 'logs', 'server.log');
+  const child = spawn('tail', ['-n', '100', '-f', file], { stdio: 'inherit' });
+  return new Promise((r) => child.on('exit', (c) => r(c ?? 0)));
+}
+
+async function doctor(): Promise<number> {
+  const tailnet = await detectTailscale();
+  const distDir = fileURLToPath(new URL('../ui/dist', import.meta.url));
+  const checks = await preflight({ port: PORT, foremanHome: HOME_DIR, distDir, tailnet });
+  // Port-in-use is an error for `start` and a fact for `doctor`: it usually means Foreman is already up.
+  for (const c of checks) {
+    if (c.name.startsWith('Port') && c.status === 'error') { c.status = 'warn'; c.detail = 'in use — Foreman is probably already running'; c.fix = `foreman open · or PORT=${PORT + 1} foreman`; }
+  }
+  const ok = reportPreflight(checks);
+  return ok ? 0 : 1;
+}
+
+async function open(): Promise<number> {
+  const url = `http://localhost:${PORT}`;
+  // `start` is a cmd builtin, not a program; xdg-open covers the Linux desktops.
+  const r = process.platform === 'win32'
+    ? await sh('cmd', ['/c', 'start', '', url])
+    : await sh(process.platform === 'darwin' ? 'open' : 'xdg-open', [url]);
+  if (r.code !== 0) console.log(url);
+  return 0;
+}
+
+async function listening(port: number): Promise<boolean> {
+  try { const r = await fetch(`http://127.0.0.1:${port}/projects`, { signal: AbortSignal.timeout(1500) }); return r.ok; }
+  catch { return false; }
+}
+
+async function readPid(): Promise<number | null> {
+  try { const n = Number((await readFile(PID_FILE, 'utf8')).trim()); return Number.isInteger(n) && n > 0 ? n : null; }
+  catch { return null; }
+}
+
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+async function up(bin: string): Promise<number> {
+  if (await listening(PORT)) { console.log(`Already up at http://localhost:${PORT}`); return 0; }
+  await mkdir(path.dirname(LOG_FILE), { recursive: true });
+  const out = openSync(LOG_FILE, 'a');
+  const child = spawn(process.execPath, [bin, 'start'], {
+    detached: true, stdio: ['ignore', out, out],
+    env: { ...process.env, FOREMAN_HOME: HOME_DIR },
+  });
+  child.unref();
+  await writeFile(PID_FILE, `${child.pid}\n`);
+  for (let i = 0; i < 40; i++) {
+    await new Promise((r) => setTimeout(r, 250));
+    if (await listening(PORT)) {
+      console.log(`Foreman is up at http://localhost:${PORT} (pid ${child.pid}) · log: ${LOG_FILE} · stop with: foreman down`);
+      return 0;
+    }
+    if (child.pid && !alive(child.pid)) break;
+  }
+  console.error(`Foreman did not come up. The preflight may have refused — see ${LOG_FILE}`);
+  await rm(PID_FILE, { force: true });
+  return 1;
+}
+
+async function down(): Promise<number> {
+  const pid = await readPid();
+  if (!pid || !alive(pid)) {
+    await rm(PID_FILE, { force: true });
+    if (await listening(PORT)) { console.log(`Something answers on :${PORT} but it was not started with \`foreman up\` (a terminal, or the service). Stop it there.`); return 1; }
+    console.log('Not up.'); return 0;
+  }
+  process.kill(pid, 'SIGTERM');
+  for (let i = 0; i < 40 && alive(pid); i++) await new Promise((r) => setTimeout(r, 250));
+  if (alive(pid)) process.kill(pid, 'SIGKILL');
+  await rm(PID_FILE, { force: true });
+  console.log('Stopped.');
+  return 0;
+}
+
+async function status(): Promise<number> {
+  const pid = await readPid();
+  const isUp = await listening(PORT);
+  if (isUp) {
+    const how = pid && alive(pid) ? `background, pid ${pid}` : 'a terminal or the service';
+    console.log(`Up at http://localhost:${PORT} (${how})`);
+    return 0;
+  }
+  if (pid) await rm(PID_FILE, { force: true });
+  console.log(`Not up. \`foreman up\` starts it in the background, \`foreman\` in this terminal.`);
+  return 1;
+}
+
+export async function runCli(command: string, rest: string[], ctx: { version: string; bin: URL }): Promise<number> {
+  const bin = fileURLToPath(ctx.bin);
+  switch (command) {
+    case 'up': return up(bin);
+    case 'down': return down();
+    case 'status': return status();
+    case 'doctor': return doctor();
+    case 'open': return open();
+    case 'service': {
+      const sub = rest[0];
+      if (sub === 'install') return serviceInstall(bin);
+      if (sub === 'uninstall') return serviceUninstall();
+      if (sub === 'status') return serviceStatus();
+      if (sub === 'logs') return serviceLogs();
+      console.error('foreman service <install|uninstall|status|logs>');
+      return 1;
+    }
+    default: return 1;
+  }
+}
+
+/** For a test: where the plist would go. */
+export function plistPathFor(home = os.homedir()): string { return path.join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`); }

package/src/codex.test.ts

@@ -0,0 +1,328 @@
+/**
+ * Codex credential tests.
+ *
+ * Everything here uses a temp CODEX_HOME with fixture files — the real
+ * `~/.codex` is never touched, and no test hits `auth.openai.com`: the
+ * refresh test injects a stub `fetch`.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdtemp, mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import {
+  codexHome, readCodexAuth, isStale, refreshCodexAuth, codexModels,
+} from './codex.js';
+
+async function tmpHome(): Promise<string> {
+  return mkdtemp(path.join(os.tmpdir(), 'foreman-codex-test-'));
+}
+
+function fixtureAuth(overrides: Record<string, unknown> = {}) {
+  return {
+    auth_mode: 'chatgpt',
+    OPENAI_API_KEY: null,
+    tokens: {
+      id_token: 'id-token-value',
+      access_token: 'access-token-value',
+      refresh_token: 'refresh-token-value',
+      account_id: 'acct-123',
+    },
+    last_refresh: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// codexHome
+// ---------------------------------------------------------------------------
+
+test('codexHome honours CODEX_HOME override before the env var, then falls back to ~/.codex', async () => {
+  const saved = process.env.CODEX_HOME;
+  try {
+    delete process.env.CODEX_HOME;
+    assert.equal(codexHome(), path.join(os.homedir(), '.codex'));
+
+    process.env.CODEX_HOME = '/from/env';
+    assert.equal(codexHome(), '/from/env');
+
+    assert.equal(codexHome('/explicit'), '/explicit');
+  } finally {
+    if (saved === undefined) delete process.env.CODEX_HOME;
+    else process.env.CODEX_HOME = saved;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// readCodexAuth
+// ---------------------------------------------------------------------------
+
+test('readCodexAuth returns null when auth.json is missing — no install is ordinary, not an error', async () => {
+  const home = await tmpHome();
+  try {
+    assert.equal(await readCodexAuth(home), null);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('readCodexAuth returns null on malformed JSON', async () => {
+  const home = await tmpHome();
+  try {
+    await writeFile(path.join(home, 'auth.json'), '{ not json');
+    assert.equal(await readCodexAuth(home), null);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('readCodexAuth returns null when there is no usable credential', async () => {
+  const home = await tmpHome();
+  try {
+    await writeFile(
+      path.join(home, 'auth.json'),
+      JSON.stringify({ auth_mode: 'chatgpt', OPENAI_API_KEY: null, tokens: {} }),
+    );
+    assert.equal(await readCodexAuth(home), null);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('readCodexAuth parses a well-formed file', async () => {
+  const home = await tmpHome();
+  try {
+    const fixture = fixtureAuth();
+    await writeFile(path.join(home, 'auth.json'), JSON.stringify(fixture));
+    const auth = await readCodexAuth(home);
+    assert.ok(auth);
+    assert.equal(auth?.tokens?.access_token, 'access-token-value');
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('readCodexAuth prefers OPENAI_API_KEY over the OAuth access_token', async () => {
+  const home = await tmpHome();
+  try {
+    await writeFile(
+      path.join(home, 'auth.json'),
+      JSON.stringify(fixtureAuth({ OPENAI_API_KEY: 'sk-plain-api-key' })),
+    );
+    const auth = await readCodexAuth(home);
+    assert.ok(auth);
+    // readCodexAuth returns the whole record; the caller (provider.ts, out of
+    // scope for this module) is expected to prefer OPENAI_API_KEY when
+    // present. Assert the fixture round-trips both fields so that contract is
+    // checkable at the call site.
+    assert.equal(auth?.OPENAI_API_KEY, 'sk-plain-api-key');
+    assert.equal(auth?.tokens?.access_token, 'access-token-value');
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// isStale
+// ---------------------------------------------------------------------------
+
+test('isStale: boundary either side of the default 25-minute threshold', () => {
+  const now = Date.now();
+  const justUnder = new Date(now - (25 * 60 * 1000 - 1000)).toISOString();
+  const justOver = new Date(now - (25 * 60 * 1000 + 1000)).toISOString();
+
+  assert.equal(isStale(fixtureAuth({ last_refresh: justUnder }) as any), false);
+  assert.equal(isStale(fixtureAuth({ last_refresh: justOver }) as any), true);
+});
+
+test('isStale: a custom max age is honoured', () => {
+  const tenMinAgo = new Date(Date.now() - 10 * 60 * 1000).toISOString();
+  assert.equal(isStale(fixtureAuth({ last_refresh: tenMinAgo }) as any, 5 * 60 * 1000), true);
+  assert.equal(isStale(fixtureAuth({ last_refresh: tenMinAgo }) as any, 15 * 60 * 1000), false);
+});
+
+test('isStale: no last_refresh at all is treated as stale', () => {
+  const { last_refresh, ...rest } = fixtureAuth();
+  assert.equal(isStale(rest as any), true);
+});
+
+// ---------------------------------------------------------------------------
+// refreshCodexAuth
+// ---------------------------------------------------------------------------
+
+test('refreshCodexAuth writes the rotated token atomically and preserves unrelated fields', async () => {
+  const home = await tmpHome();
+  try {
+    const fixture = fixtureAuth();
+    await writeFile(path.join(home, 'auth.json'), JSON.stringify(fixture));
+
+    let calledUrl: string | undefined;
+    let calledBody: any;
+    const stubFetch = (async (url: string, init: any) => {
+      calledUrl = url;
+      calledBody = JSON.parse(init.body);
+      return {
+        ok: true,
+        json: async () => ({
+          access_token: 'new-access-token',
+          id_token: 'new-id-token',
+          refresh_token: 'new-refresh-token-single-use',
+        }),
+      };
+    }) as any;
+
+    const auth = await readCodexAuth(home);
+    assert.ok(auth);
+    const result = await refreshCodexAuth(home, auth!, stubFetch);
+    assert.ok(result);
+
+    assert.equal(calledUrl, 'https://auth.openai.com/oauth/token');
+    assert.equal(calledBody.grant_type, 'refresh_token');
+    assert.equal(calledBody.client_id, 'app_EMoamEEZ73f0CkXaXp7hrann');
+    assert.equal(calledBody.refresh_token, 'refresh-token-value');
+
+    // Unrelated top-level fields survive.
+    assert.equal(result?.auth_mode, 'chatgpt');
+    assert.equal(result?.OPENAI_API_KEY, null);
+
+    // Tokens are rotated.
+    assert.equal(result?.tokens?.access_token, 'new-access-token');
+    assert.equal(result?.tokens?.refresh_token, 'new-refresh-token-single-use');
+    assert.equal(result?.tokens?.account_id, 'acct-123'); // preserved, not part of the response
+
+    // The write actually landed on disk, and no .tmp file was left behind.
+    const onDisk = JSON.parse(await readFile(path.join(home, 'auth.json'), 'utf8'));
+    assert.equal(onDisk.tokens.access_token, 'new-access-token');
+    assert.equal(onDisk.tokens.refresh_token, 'new-refresh-token-single-use');
+
+    const { readdir } = await import('node:fs/promises');
+    const files = await readdir(home);
+    assert.ok(!files.some((f) => f.endsWith('.tmp')), 'no leftover tmp file');
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('refreshCodexAuth returns null when there is no refresh token to send', async () => {
+  const home = await tmpHome();
+  try {
+    const auth = fixtureAuth({ tokens: { access_token: 'a' } });
+    const stubFetch = (async () => {
+      throw new Error('must not be called');
+    }) as any;
+    const result = await refreshCodexAuth(home, auth as any, stubFetch);
+    assert.equal(result, null);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('refreshCodexAuth returns null on a non-2xx response rather than throwing', async () => {
+  const home = await tmpHome();
+  try {
+    await writeFile(path.join(home, 'auth.json'), JSON.stringify(fixtureAuth()));
+    const auth = await readCodexAuth(home);
+    const stubFetch = (async () => ({ ok: false, json: async () => ({}) })) as any;
+    const result = await refreshCodexAuth(home, auth!, stubFetch);
+    assert.equal(result, null);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('refreshCodexAuth returns null when the network call throws', async () => {
+  const home = await tmpHome();
+  try {
+    await writeFile(path.join(home, 'auth.json'), JSON.stringify(fixtureAuth()));
+    const auth = await readCodexAuth(home);
+    const stubFetch = (async () => {
+      throw new Error('ECONNREFUSED');
+    }) as any;
+    const result = await refreshCodexAuth(home, auth!, stubFetch);
+    assert.equal(result, null);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('refreshCodexAuth never calls the real network (no fetch arg reaches auth.openai.com in this suite)', async () => {
+  // Sanity check on the test design itself: every refresh test above passes
+  // an explicit stub. This test just documents that refreshCodexAuth accepts
+  // one rather than always using the global fetch.
+  const home = await tmpHome();
+  try {
+    await writeFile(path.join(home, 'auth.json'), JSON.stringify(fixtureAuth()));
+    const auth = await readCodexAuth(home);
+    let called = false;
+    const stubFetch = (async () => {
+      called = true;
+      return { ok: true, json: async () => ({ access_token: 'x' }) };
+    }) as any;
+    await refreshCodexAuth(home, auth!, stubFetch);
+    assert.equal(called, true);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// codexModels
+// ---------------------------------------------------------------------------
+
+test('codexModels returns [] when models_cache.json is absent', async () => {
+  const home = await tmpHome();
+  try {
+    assert.deepEqual(await codexModels(home), []);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('codexModels returns [] on malformed JSON', async () => {
+  const home = await tmpHome();
+  try {
+    await writeFile(path.join(home, 'models_cache.json'), 'not json');
+    assert.deepEqual(await codexModels(home), []);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('codexModels returns [] when the models field is missing or the wrong shape', async () => {
+  const home = await tmpHome();
+  try {
+    await writeFile(path.join(home, 'models_cache.json'), JSON.stringify({ fetched_at: 'x' }));
+    assert.deepEqual(await codexModels(home), []);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('codexModels reads slugs faithfully from a real-shaped fixture', async () => {
+  const home = await tmpHome();
+  try {
+    // Shaped after the actual ~/.codex/models_cache.json on a machine with
+    // Codex installed: an array of model objects keyed by `slug`, with a lot
+    // of other per-model metadata this module has no business parsing.
+    await writeFile(
+      path.join(home, 'models_cache.json'),
+      JSON.stringify({
+        fetched_at: '2026-09-04T02:56:08.542652Z',
+        etag: 'W/"1e10c2927ad7b0d7cddc841252b75cb1"',
+        client_version: '0.147.0',
+        models: [
+          { slug: 'gpt-reserve', display_name: 'GPT-Reserve', visibility: 'hide' },
+          { slug: 'gpt-5.6-sol', display_name: 'GPT-5.6 Sol', visibility: 'list' },
+          { slug: 'gpt-5.6-terra' },
+          { display_name: 'no slug here', visibility: 'list' },
+        ],
+      }),
+    );
+    // `gpt-reserve` is real and the API would accept it, which is exactly why
+    // it must not reach a picker: Codex marks it `visibility: hide` because it
+    // is not a thing to offer. An entry with no visibility at all is shown.
+    assert.deepEqual(await codexModels(home), ['gpt-5.6-sol', 'gpt-5.6-terra']);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});