auxilo-mcp 0.9.12 → 0.9.13

package/scripts/providers/codex-cli.js

@@ -0,0 +1,358 @@
+'use strict';
+/*
+ * scripts/providers/codex-cli.js — Codex CLI provider adapter
+ * (EXTRACT-PER-CLIENT W1 PART B).
+ *
+ * Same runModel/detect shape as claude-code.js (this dir's other provider):
+ * spawns `codex exec` with the transcript+prompt on stdin, reads the model's
+ * answer back out, and never bills Auxilo — the child runs under the
+ * builder's own `codex` login (or their own OPENAI_API_KEY, see detect()
+ * below), scrubbed of every var that could redirect billing elsewhere.
+ *
+ * Flags verified live against `codex exec --help` (codex-cli 0.144.5) before
+ * this module was written — see BUILD-SPEC-EXTRACT-PER-CLIENT-W1 §1/§6:
+ *   -s, --sandbox <read-only|workspace-write|danger-full-access>
+ *   --skip-git-repo-check   (codex refuses to run outside a git repo otherwise)
+ *   --ephemeral              (no session file left behind)
+ *   --ignore-user-config     (don't load ~/.codex/config.toml — auth still
+ *                             comes from CODEX_HOME/auth.json regardless)
+ *   --output-schema <FILE>   (a JSON-Schema HINT, not a hard parser — see
+ *                             schemas/*.schema.json for the shapes)
+ *   -o, --output-last-message <FILE>  (where the final answer lands)
+ *   [PROMPT] — `-` reads the prompt from stdin instead of argv.
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const { SCRUBBED_CLIENT_ENV_VARS } = require('./claude-code.js');
+
+const EXTRACTION_SCHEMA_PATH = path.join(__dirname, 'schemas', 'extraction-envelope.schema.json');
+const JUDGE_SCHEMA_PATH = path.join(__dirname, 'schemas', 'judge-decisions.schema.json');
+
+/** Resolve the `codex` binary — hook/launchd env may have a minimal PATH. */
+function resolveCodexBin(opts = {}) {
+  const homeDir = typeof opts.homeDir === 'string' ? opts.homeDir : os.homedir();
+  const existsSync = typeof opts.existsSync === 'function' ? opts.existsSync : fs.existsSync;
+  const candidates = [
+    path.join(homeDir, '.npm-global', 'bin', 'codex'),
+    '/usr/local/bin/codex',
+    '/opt/homebrew/bin/codex',
+    path.join(homeDir, '.local', 'bin', 'codex'),
+  ];
+  for (const c of candidates) {
+    try {
+      if (existsSync(c)) return c;
+    } catch (_) { /* ignore */ }
+  }
+  // No explicit filesystem candidate — let PATH resolve the final option.
+  return 'codex';
+}
+
+/**
+ * Build the subscription/login-only environment for the codex child — the
+ * SAME 28-name scrub PART A's claude-code.js established (imported, not
+ * duplicated: one list, no drift between providers), PLUS this module never
+ * reads or forwards OPENAI_API_KEY itself, even though its presence in the
+ * builder's own ~/.codex/auth.json is not disqualifying for detect() (see
+ * detect() below) — an env-level OPENAI_API_KEY could silently redirect
+ * billing to a DIFFERENT account than the one auth.json names, so it is
+ * scrubbed here regardless of source.
+ */
+function codexChildEnv() {
+  const childEnv = { ...process.env, AUXILO_EXTRACTING: '1' };
+  for (const key of SCRUBBED_CLIENT_ENV_VARS) delete childEnv[key];
+  delete childEnv.OPENAI_API_KEY;
+  return childEnv;
+}
+
+/**
+ * Read ~/.codex/auth.json and return its `auth_mode` string, or null when the
+ * file is missing, unreadable, malformed, or auth_mode is absent/falsy. Never
+ * throws. A truthy `OPENAI_API_KEY` alongside a truthy auth_mode is fine and
+ * not inspected here — that key bills the BUILDER's own account if codex ever
+ * uses it, which zero-inference does not forbid (it forbids Auxilo billing);
+ * codexChildEnv() above still scrubs it from what our own child sees.
+ */
+function readAuthMode(opts = {}) {
+  const homeDir = typeof opts.homeDir === 'string' ? opts.homeDir : os.homedir();
+  const readFileSyncImpl = typeof opts.readFileSyncImpl === 'function' ? opts.readFileSyncImpl : fs.readFileSync;
+  try {
+    const raw = readFileSyncImpl(path.join(homeDir, '.codex', 'auth.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && typeof parsed.auth_mode === 'string' && parsed.auth_mode) {
+      return parsed.auth_mode;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * detect(): true iff BOTH (a) the `codex` binary resolves — an explicit
+ * filesystem candidate, or (failing that) a cheap `codex --version` probe
+ * confirming PATH actually resolves it — AND (b) ~/.codex/auth.json exists,
+ * parses, and has a truthy auth_mode. Both legs required: a binary with no
+ * login, or a login with no binary, both mean extraction cannot run.
+ */
+function detect(opts = {}) {
+  if (!readAuthMode(opts)) return false;
+  const bin = typeof opts.codexBin === 'string' ? opts.codexBin : resolveCodexBin(opts);
+  if (bin !== 'codex') return true; // explicit filesystem candidate found
+  const spawnSyncImpl = typeof opts.spawnSyncImpl === 'function' ? opts.spawnSyncImpl : spawnSync;
+  try {
+    const res = spawnSyncImpl(bin, ['--version'], { encoding: 'utf8', timeout: 5000, maxBuffer: 65536 });
+    return Boolean(res && !res.error && res.status === 0);
+  } catch {
+    return false;
+  }
+}
+
+// ─── codex --version capture (extraction_model.version) ───────────────────
+//
+// codex exposes no per-call model identifier (no --json event stream is
+// requested here, and -o's last-message file carries prose/schema-shaped
+// output only) — the CLI build version is the honest proxy for "which codex
+// build ran this extraction". Captured once per process and cached: every
+// runModel() call after the first reuses the cached value, so a session that
+// calls runModel() twice (extract, then judge) only pays for one version
+// probe. `undefined` = not yet probed; `null` = probed, could not determine.
+let cachedVersion;
+
+function getCodexVersion(opts = {}) {
+  if (cachedVersion !== undefined) return cachedVersion;
+  const spawnSyncImpl = typeof opts.spawnSyncImpl === 'function' ? opts.spawnSyncImpl : spawnSync;
+  const bin = typeof opts.codexBin === 'string' ? opts.codexBin : resolveCodexBin(opts);
+  try {
+    const res = spawnSyncImpl(bin, ['--version'], { encoding: 'utf8', timeout: 5000, maxBuffer: 65536 });
+    cachedVersion = (res && !res.error && res.status === 0) ? String(res.stdout || '').trim() || null : null;
+  } catch {
+    cachedVersion = null;
+  }
+  return cachedVersion;
+}
+
+/** Test-only: reset the module-level version cache between fixtures. */
+function _resetVersionCacheForTests() {
+  cachedVersion = undefined;
+}
+
+/**
+ * Where the `-o` output file lives (GOV-3 should-fix item 11). The old
+ * default dropped it straight into `os.tmpdir()` — a WORLD-READABLE
+ * directory on every POSIX system — at codex's own umask, holding
+ * extracted-learning text (which may itself contain scrubbed-but-sensitive
+ * transcript fragments) until the best-effort unlink below runs. Now it
+ * lands in a PRIVATE 0700 subdirectory this process creates and owns,
+ * `auxilo-<pid>-<rand>/`, so nothing but this user can even list the
+ * directory to find the file, let alone read it before the chmod below
+ * lands. A caller-supplied `opts.outputPath` (every test in this repo)
+ * bypasses directory creation entirely — that path is the caller's to
+ * manage, and `cleanupDir` comes back null so invoke()'s finally block does
+ * not try to rmdir something it did not create.
+ */
+function makeOutputLocation(opts, mode) {
+  if (typeof opts.outputPath === 'string') return { outputPath: opts.outputPath, cleanupDir: null };
+  const mkdirSyncImpl = typeof opts.mkdirSyncImpl === 'function' ? opts.mkdirSyncImpl : fs.mkdirSync;
+  const rand = crypto.randomBytes(6).toString('hex');
+  const dir = path.join(os.tmpdir(), `auxilo-${process.pid}-${rand}`);
+  mkdirSyncImpl(dir, { recursive: true, mode: 0o700 });
+  return { outputPath: path.join(dir, `${mode}.txt`), cleanupDir: dir };
+}
+
+function classifySpawnError(error, bin) {
+  if (error && error.code === 'ENOENT') {
+    return { reasonCode: 'cli-not-installed', reason: `codex binary not found (${bin}) — run \`npm install -g @openai/codex\` or the platform's install path` };
+  }
+  if (error && (error.code === 'ETIMEDOUT' || error.code === 'ETIMEOUT')) {
+    return { reasonCode: 'cli-timeout', reason: `codex exec timed out (${bin}): ${error.message}` };
+  }
+  return { reasonCode: 'unknown', reason: `spawn failed (${bin}): ${error ? error.message : 'no process result'}` };
+}
+
+/**
+ * Shared invocation for both modes: builds argv, spawns, reads the answer
+ * back from the `-o` file (falling back to stdout only if that file cannot
+ * be read — see module comment on why: --output-last-message's own docs
+ * promise a file is written on a normal completion, but say nothing about a
+ * crash/timeout/schema-rejection path, so a defensive stdout fallback covers
+ * the cases where no file ever landed; text as documented is the file's
+ * content and stdout is treated as the exception path, never the default).
+ *
+ * The `-o` file's private-dir creation, 0600 chmod, and cleanup (GOV-3
+ * should-fix item 11) are handled by an outer try/finally so EVERY exit
+ * path — auth-not-configured, every spawn-error/timeout classification,
+ * non-zero exit, empty output, and the normal success path — cleans up the
+ * same way. `cleanupDir` is null (nothing to remove) when the caller
+ * supplied its own `opts.outputPath`.
+ */
+function invoke(opts, mode) {
+  const spawnSyncImpl = typeof opts.spawnSyncImpl === 'function' ? opts.spawnSyncImpl : spawnSync;
+  const readFileSyncImpl = typeof opts.readFileSyncImpl === 'function' ? opts.readFileSyncImpl : fs.readFileSync;
+  const unlinkSyncImpl = typeof opts.unlinkSyncImpl === 'function' ? opts.unlinkSyncImpl : fs.unlinkSync;
+  const rmdirSyncImpl = typeof opts.rmdirSyncImpl === 'function' ? opts.rmdirSyncImpl : fs.rmdirSync;
+  const chmodSyncImpl = typeof opts.chmodSyncImpl === 'function' ? opts.chmodSyncImpl : fs.chmodSync;
+  const bin = typeof opts.codexBin === 'string' ? opts.codexBin : resolveCodexBin(opts);
+
+  const authMode = readAuthMode(opts);
+  if (!authMode) {
+    return {
+      ok: false,
+      text: '',
+      usage: null,
+      reason: 'codex CLI is not authenticated in this context (run `codex login` once); skipping deterministic extraction',
+      reasonCode: 'cli-unauthenticated',
+      authStatus: 'logged-out',
+    };
+  }
+
+  const { outputPath, cleanupDir } = makeOutputLocation(opts, mode);
+  try {
+    const schemaFile = mode === 'judge' ? JUDGE_SCHEMA_PATH : EXTRACTION_SCHEMA_PATH;
+    const prompt = typeof opts.prompt === 'string' ? opts.prompt : '';
+    const stdin = prompt + String(opts.input || '');
+    const args = [
+      'exec',
+      '-s', 'read-only',
+      '--skip-git-repo-check',
+      '--ephemeral',
+      '--ignore-user-config',
+      '--output-schema', schemaFile,
+      '-o', outputPath,
+      '-',
+    ];
+
+    let res;
+    try {
+      res = spawnSyncImpl(bin, args, {
+        input: stdin,
+        encoding: 'utf-8',
+        env: codexChildEnv(),
+        timeout: opts.timeoutMs || 120000,
+        maxBuffer: 20 * 1024 * 1024,
+      });
+    } catch (error) {
+      const classified = classifySpawnError(error, bin);
+      return { ok: false, text: '', usage: null, authStatus: 'unknown', ...classified };
+    }
+    if (!res) {
+      return { ok: false, text: '', usage: null, reason: `spawn failed (${bin}): no process result`, reasonCode: 'unknown', authStatus: 'unknown' };
+    }
+    if (res.error) {
+      const classified = classifySpawnError(res.error, bin);
+      return { ok: false, text: '', usage: null, authStatus: 'unknown', ...classified };
+    }
+    // spawnSync signals a timeout via `signal` (no `error`) when the child was
+    // killed for exceeding `timeout` and didn't set its own exit code.
+    if (res.signal && res.status === null) {
+      return { ok: false, text: '', usage: null, reason: `codex exec timed out (${bin}), signal ${res.signal}`, reasonCode: 'cli-timeout', authStatus: 'unknown' };
+    }
+
+    const stdout = String(res.stdout || '');
+    if (/not authenticated|not logged in|codex login/i.test(stdout) || /not authenticated|not logged in|codex login/i.test(String(res.stderr || ''))) {
+      return { ok: false, text: '', usage: null, reason: 'codex CLI reported it is not authenticated', reasonCode: 'cli-unauthenticated', authStatus: 'unknown' };
+    }
+    if (res.status !== 0) {
+      return {
+        ok: false,
+        text: '',
+        usage: null,
+        reason: `codex exec exited ${res.status}: ${(stdout || String(res.stderr || '')).slice(0, 160)}`,
+        reasonCode: 'model-error',
+        authStatus: 'unknown',
+      };
+    }
+
+    // Force 0600 before reading — codex writes this file itself, under its
+    // own umask, which may not match. Best-effort: a file that doesn't
+    // exist (never written) or can't be chmod'd fails silently here and the
+    // read attempt right below reports the real failure.
+    try { chmodSyncImpl(outputPath, 0o600); } catch { /* best-effort only */ }
+
+    let text;
+    let usedStdoutFallback = false;
+    try {
+      text = String(readFileSyncImpl(outputPath, 'utf8'));
+    } catch {
+      // --output-last-message's own docs make no promise about a file existing
+      // outside a normal completion — fall back to stdout rather than
+      // reporting a false failure when codex exited 0 but the file is absent.
+      text = stdout;
+      usedStdoutFallback = true;
+    }
+
+    if (!text.trim()) {
+      return {
+        ok: false,
+        text: '',
+        usage: null,
+        reason: usedStdoutFallback
+          ? 'codex exec produced no output-last-message file and stdout was empty'
+          : 'codex exec produced an empty output-last-message file',
+        reasonCode: 'cli-bad-output',
+        authStatus: 'unknown',
+      };
+    }
+
+    // extraction_model kept as a DEPRECATED ALIAS of `identity` for one
+    // release (GATE-A item a) — resolveExtractionModelIdentity
+    // (scripts/extract-local.js) reads `identity`, per the
+    // provider.interface.js contract every other provider follows
+    // (byo-key.js always set `identity`; this field name mismatch was the
+    // bug — codex's real version never reached the stamp, falling back to
+    // the generic {provider,model:null,version:null,vendor:null} instead).
+    // test/codex-cli-provider.test.js still reads `.extraction_model`
+    // directly against this module's own runModel(), so the alias stays
+    // until that test (and any external consumer) moves to `.identity`.
+    const identity = {
+      provider: 'codex-cli',
+      model: null, // codex exposes no per-call model id without --json (not requested)
+      version: getCodexVersion(opts),
+      vendor: null,
+    };
+    return {
+      ok: true,
+      text,
+      usage: null, // the -o file carries no token counts; caller estimates from text length
+      reason: null,
+      authStatus: 'unknown',
+      identity,
+      extraction_model: identity, // deprecated alias — remove after one release
+    };
+  } finally {
+    // Unlink the output file unconditionally (matches the pre-existing
+    // contract exercised by test/codex-cli-provider.test.js even for a
+    // caller-supplied opts.outputPath); rmdir the private directory ONLY
+    // when this call created it — a caller-supplied path is the caller's
+    // directory to manage, never ours to remove.
+    try { unlinkSyncImpl(outputPath); } catch { /* best-effort cleanup only */ }
+    if (cleanupDir) {
+      try { rmdirSyncImpl(cleanupDir); } catch { /* best-effort cleanup only */ }
+    }
+  }
+}
+
+/** runModel(opts) — the provider.interface.js contract. */
+async function runModel(opts = {}) {
+  const mode = opts.mode === 'judge' ? 'judge' : 'extract';
+  return invoke(opts, mode);
+}
+
+module.exports = {
+  runModel,
+  detect,
+  resolveCodexBin,
+  readAuthMode,
+  codexChildEnv,
+  getCodexVersion,
+  EXTRACTION_SCHEMA_PATH,
+  JUDGE_SCHEMA_PATH,
+  _resetVersionCacheForTests,
+  // Exported for direct unit coverage (test/extract-w1-fix2.test.js, GOV-3
+  // should-fix item 11 — private-dir + 0600 output file).
+  makeOutputLocation,
+};

package/scripts/providers/index.js

@@ -0,0 +1,316 @@
+'use strict';
+/*
+ * scripts/providers/index.js — provider registry + selection
+ * (EXTRACT-PER-CLIENT W1 PART A; selection fall-through added in the W1 P1
+ * fix — PUNCH-LIST).
+ *
+ * resolveProvider(): which ONE provider to try first. Selection order:
+ * AUXILO_EXTRACTION_PROVIDER env override (wins unconditionally, never
+ * persisted — "wins, never writes") → else the persisted `selected` choice
+ * from ~/.auxilo/providers.json if it is STILL usable (re-verified via its
+ * own detect() every call, never trusted blindly — a stale persisted choice
+ * falls through to a full re-scan rather than failing) → else the first
+ * provider whose detect() is true, in fixed order (claude-code → codex-cli →
+ * byo-key) → else ok:false, with a reason naming every provider tried.
+ *
+ * runModel(): resolves via resolveProvider(), then actually RUNS it. A
+ * non-override resolution that fails with a reasonCode meaning "this
+ * provider cannot run at all" (NON_RETRYABLE_FOR_THIS_PROVIDER — e.g.
+ * unauthenticated, not installed, a billing helper is configured) falls
+ * through to the next provider in PROVIDER_ORDER rather than reporting a
+ * hard failure; a working provider that merely failed once (timeout, model
+ * error) does not fall through — that is still the builder's chosen
+ * provider having a bad run, not a reason to switch under them. An explicit
+ * env override never falls through, honoring the operator's explicit
+ * choice. Every provider exhausted → reasonCode 'no-usable-provider' with
+ * every attempt's reason summarized in `reason`.
+ *
+ * codex-cli.js and byo-key.js don't exist yet (PART B/C). loadOptionalProvider()
+ * degrades a missing module into a "not installed yet" stub so this file — and
+ * everything that calls into it — never throws on a fresh PART A checkout; PART
+ * B/C only need to add their files, not touch this registration.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const claudeCode = require('./claude-code.js');
+
+function notInstalledProvider(id) {
+  return {
+    id,
+    detect() {
+      return false;
+    },
+    async runModel() {
+      return {
+        ok: false,
+        text: '',
+        usage: null,
+        reasonCode: 'provider-not-installed',
+        reason: `${id} support is not installed yet`,
+        authStatus: 'unknown',
+      };
+    },
+  };
+}
+
+function loadOptionalProvider(id, modulePath) {
+  try {
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    return require(modulePath);
+  } catch (err) {
+    if (err && err.code === 'MODULE_NOT_FOUND') {
+      return notInstalledProvider(id);
+    }
+    throw err;
+  }
+}
+
+const codexCli = loadOptionalProvider('codex-cli', './codex-cli.js');
+const byoKey = loadOptionalProvider('byo-key', './byo-key.js');
+
+const PROVIDER_ORDER = Object.freeze(['claude-code', 'codex-cli', 'byo-key']);
+const PROVIDERS = {
+  'claude-code': claudeCode,
+  'codex-cli': codexCli,
+  'byo-key': byoKey,
+};
+
+const PROVIDERS_STATE_PATH = path.join(os.homedir(), '.auxilo', 'providers.json');
+
+function readProvidersState(statePath) {
+  try {
+    const raw = fs.readFileSync(statePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Persist the auto-detected choice into ~/.auxilo/providers.json's `selected`
+ * key — the SAME file PART C's BYO-key store uses (one file, not two). Never
+ * called for an env-override selection (item 7: "env override always wins,
+ * never writes"). Persisting is a convenience for `auxilo status`, not a
+ * correctness requirement — failure here is swallowed.
+ *
+ * Routes through byo-key.js's writeProvidersStateAtomic — GOV-3 item 1's
+ * "ONE writer" for every providers.json write, so this call gets the exact
+ * same tmp+wx+rename+POST-RENAME-chmod discipline byo-key.js's own writers
+ * use, instead of a second, independently-drifted copy that (as found)
+ * omitted the post-rename chmod. It merges only the `selected` field — the
+ * `byo` object (and anything else already in the file) is read back and
+ * passed through UNCHANGED, never reconstructed or re-derived here, so this
+ * function cannot corrupt or partially rewrite credential fields it did not
+ * itself validate.
+ */
+function persistSelected(providerId, opts) {
+  const statePath = opts.providersStatePath || PROVIDERS_STATE_PATH;
+  try {
+    if (typeof byoKey.writeProvidersStateAtomic !== 'function') return; // PART C not installed yet
+    const state = readProvidersState(statePath);
+    state.selected = providerId; // merge only this field — `byo` (if present) passes through as-read
+    byoKey.writeProvidersStateAtomic(state, opts);
+  } catch {
+    // Best-effort — selection still works in-process even if the write fails.
+  }
+}
+
+/**
+ * Resolve which provider should run this call. Auto-detect results are cached
+ * (per the supplied `opts.providerCache` object, or a module-level default for
+ * real production runs) so a single extraction session detects once and reuses
+ * the choice across both the extraction call and the judge call — mirrors the
+ * one-call-per-session runner pattern (runner.js calls postExtractDetailed once
+ * per session; extractLocally's extract call and its anchored-judge call are the
+ * two runModel invocations within that one session that must agree).
+ * An env override is re-evaluated every call (cheap: no detect() needed) and is
+ * never cached or persisted.
+ */
+const defaultCache = {};
+
+async function resolveProvider(opts = {}) {
+  const env = opts.env || process.env;
+  const override = env.AUXILO_EXTRACTION_PROVIDER;
+  if (override) {
+    if (!Object.prototype.hasOwnProperty.call(PROVIDERS, override)) {
+      return {
+        ok: false,
+        reason: `AUXILO_EXTRACTION_PROVIDER="${override}" is not a known provider (expected one of: ${PROVIDER_ORDER.join(', ')})`,
+      };
+    }
+    return { ok: true, id: override, module: PROVIDERS[override] };
+  }
+
+  const cache = opts.providerCache || defaultCache;
+  if (cache.resolved) return cache.resolved;
+
+  // Fast path (EXTRACT-PER-CLIENT W1 FIX, PUNCH-LIST P1, item 3): the
+  // persisted `selected` choice — written by a prior successful resolution,
+  // possibly in an earlier process — skips re-probing every provider ahead
+  // of it in PROVIDER_ORDER when it is STILL usable (the common
+  // steady-state case: same builder, same login, repeated extraction
+  // calls). "Usable" is re-verified via that provider's own detect() every
+  // time, never trusted blindly from the file alone. A stale persisted
+  // choice does NOT fail — it logs one line and falls through to the full
+  // ordered scan below, which re-detects from scratch and persists (and
+  // caches) whatever wins.
+  //
+  // GOV-3 item 2 ("checked on WRITE only, never on READ") is satisfied HERE
+  // by delegation, not by a duplicate check: `persistedMod.detect(opts)`
+  // below, when the persisted choice is 'byo-key', IS byo-key.js's own
+  // detect() — which (post-fix) checks isProvidersFileModeUnsafe before
+  // trusting anything on disk and returns false on an unsafe file. That
+  // reads as "no longer usable" through the EXACT SAME stale-selection path
+  // already below (log one line, fall through to the full ordered scan,
+  // where byo-key's own detect() applies the identical check again on its
+  // turn). A second, generic mode check gated on the `selected` string
+  // alone was tried and reverted here — it broke the legitimate steady-state
+  // fast path for claude-code/codex-cli selections (neither of which reads
+  // this file's contents at all, so an insecure-mode providers.json is not
+  // their concern) whenever the fixture file wasn't deliberately chmod'd
+  // 0600 (e.g. a plain `fs.writeFileSync` at the OS umask). Gating strictly
+  // on "is the persisted provider byo-key" would be correct but is also a
+  // no-op — byo-key.detect() already returns false in that case, which is
+  // exactly what the fast path's existing fallthrough handles.
+  const log = typeof opts.log === 'function' ? opts.log : console.error;
+  const statePath = opts.providersStatePath || PROVIDERS_STATE_PATH;
+  const persistedState = readProvidersState(statePath);
+  const persistedId = persistedState.selected;
+  if (typeof persistedId === 'string' && Object.prototype.hasOwnProperty.call(PROVIDERS, persistedId)) {
+    const persistedMod = PROVIDERS[persistedId];
+    let stillUsable = false;
+    try {
+      stillUsable = await persistedMod.detect(opts);
+    } catch {
+      stillUsable = false;
+    }
+    if (stillUsable) {
+      const resolved = { ok: true, id: persistedId, module: persistedMod };
+      cache.resolved = resolved;
+      return resolved;
+    }
+    log(`[providers] persisted selection "${persistedId}" is no longer usable; re-detecting`);
+  }
+
+  const tried = [];
+  for (const id of PROVIDER_ORDER) {
+    const mod = PROVIDERS[id];
+    tried.push(id);
+    let available = false;
+    try {
+      available = await mod.detect(opts);
+    } catch {
+      available = false;
+    }
+    if (available) {
+      const resolved = { ok: true, id, module: mod };
+      cache.resolved = resolved;
+      persistSelected(id, opts);
+      return resolved;
+    }
+  }
+  return { ok: false, reason: `no extraction model provider available — tried: ${tried.join(', ')}` };
+}
+
+/**
+ * reasonCodes meaning "this provider cannot run at all right now" — safe to
+ * try the NEXT provider in PROVIDER_ORDER rather than reporting a hard
+ * failure (EXTRACT-PER-CLIENT W1 FIX, PUNCH-LIST P1, item 2). Everything
+ * else (timeouts, model errors, malformed output, rate limits) means the
+ * chosen provider DID run and failed on THIS call — that is not a signal to
+ * silently switch providers out from under the builder, so those propagate
+ * as-is (a working provider that failed once is still the builder's chosen
+ * provider).
+ */
+const NON_RETRYABLE_FOR_THIS_PROVIDER = new Set([
+  'cli-unauthenticated',
+  'cli-not-installed',
+  'cli-billing-helper-configured',
+  'provider-not-configured',
+  'providers-file-mode-unsafe',
+]);
+
+/**
+ * runModel(opts) — resolve a starting provider via resolveProvider(), then
+ * walk PROVIDER_ORDER from there, calling each candidate's OWN runModel()
+ * (never a separate detect() pre-check — a provider's runModel() already
+ * performs the equivalent authoritative check internally and returns a
+ * specific, accurate reason, so a second detect() call would only add a
+ * redundant probe without adding information). Falls through to the next
+ * provider when the current one's failure reasonCode is in
+ * NON_RETRYABLE_FOR_THIS_PROVIDER; when resolveProvider itself found no
+ * usable provider at all, the walk starts at PROVIDER_ORDER's beginning so
+ * every provider still gets an actual runModel() call and contributes its
+ * own reason (not just a single generic "no provider available"). An
+ * explicit AUXILO_EXTRACTION_PROVIDER override never falls through — it is
+ * the operator's explicit choice, so its own failure reason is reported
+ * as-is. When every provider tried is exhausted, returns reasonCode
+ * 'no-usable-provider' with a bounded summary of every provider's reason in
+ * `reason` (no secrets — each provider's own reason string is already
+ * secret-free by contract). Never throws.
+ */
+async function runModel(opts = {}) {
+  const mode = opts.mode === 'judge' ? 'judge' : 'extract';
+  const env = opts.env || process.env;
+  const override = env.AUXILO_EXTRACTION_PROVIDER;
+
+  if (override) {
+    const resolved = await resolveProvider(opts);
+    if (!resolved.ok) {
+      return {
+        ok: false,
+        text: '',
+        usage: null,
+        reasonCode: 'no-model-provider-available',
+        reason: resolved.reason,
+        authStatus: 'unknown',
+      };
+    }
+    return resolved.module.runModel({ ...opts, mode });
+  }
+
+  const log = typeof opts.log === 'function' ? opts.log : console.error;
+  const resolved = await resolveProvider(opts);
+  const startIdx = resolved.ok ? PROVIDER_ORDER.indexOf(resolved.id) : -1;
+  const order = startIdx === -1 ? PROVIDER_ORDER.slice() : PROVIDER_ORDER.slice(startIdx);
+
+  const attempts = [];
+  for (const id of order) {
+    const mod = PROVIDERS[id];
+    // eslint-disable-next-line no-await-in-loop
+    const result = await mod.runModel({ ...opts, mode });
+    if (result.ok) return result;
+    attempts.push({ id, reasonCode: result.reasonCode, reason: result.reason });
+    if (!NON_RETRYABLE_FOR_THIS_PROVIDER.has(result.reasonCode)) {
+      return result;
+    }
+    log(`[providers] ${id} unusable (${result.reasonCode}); trying next provider`);
+  }
+
+  const summary = attempts
+    .map((a) => `${a.id}=${a.reasonCode || 'unknown'}`)
+    .join('; ')
+    .slice(0, 480);
+  const lastAttempt = attempts[attempts.length - 1];
+  const lastReason = (lastAttempt && lastAttempt.reason) || resolved.reason || 'no provider available';
+  return {
+    ok: false,
+    text: '',
+    usage: null,
+    reasonCode: 'no-usable-provider',
+    reason: `${lastReason} (tried: ${summary})`.slice(0, 600),
+    authStatus: 'unknown',
+  };
+}
+
+module.exports = {
+  runModel,
+  resolveProvider,
+  PROVIDER_ORDER,
+  PROVIDERS_STATE_PATH,
+  NON_RETRYABLE_FOR_THIS_PROVIDER,
+};