sphinx-understand 0.1.0 → 0.1.2

package/src/change-view.js

@@ -0,0 +1,314 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { basename } from 'node:path';
+import { promisify } from 'node:util';
+import { loadIgnorePolicy } from './ignore.js';
+import { workspaceDiffText } from './review-workspace.js';
+
+const exec = promisify(execFile);
+const OID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
+const REGULAR = new Set(['100644', '100755']);
+// Display limits only. The reviewer's own evidence limits are unchanged.
+export const VIEW_LIMITS = Object.freeze({ files: 2000, rows: 3000, bytes: 2 * 1024 * 1024, evidenceBytes: 8 * 1024 * 1024 });
+export const CONTEXT_LEVELS = Object.freeze({ 3: 3, 25: 25, all: 1000000 });
+
+class ChangeViewError extends Error {
+  constructor(message) { super(message); this.code = 'CHANGE_VIEW_UNAVAILABLE'; }
+}
+const unavailable = message => { throw new ChangeViewError(message); };
+const decoder = () => new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+async function git(root, args, { env, buffer = false, maxBuffer = 16 * 1024 * 1024 } = {}) {
+  try {
+    const { stdout } = await exec('git', ['--no-pager', '--literal-pathspecs', '-c', 'core.fsmonitor=false', ...args], {
+      cwd: root, encoding: buffer ? 'buffer' : 'utf8', maxBuffer, timeout: 30000,
+      env: { ...process.env, ...env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1', GIT_TERMINAL_PROMPT: '0' },
+    });
+    return stdout;
+  } catch (error) {
+    if (error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') return null;
+    unavailable('The checkpoint’s Git objects are unavailable.');
+  }
+}
+
+function treeEntries(raw) {
+  const entries = new Map();
+  for (const row of raw.split('\0').filter(Boolean)) {
+    const match = /^(\d{6}) (?:blob|tree|commit) ([a-f0-9]+)\t([\s\S]*)$/u.exec(row);
+    if (!match || !OID.test(match[2])) unavailable('The checkpoint inventory is malformed.');
+    entries.set(match[3], { mode: match[1], oid: match[2] });
+  }
+  return entries;
+}
+
+// `git diff --raw -z -M`: rename rows carry two paths.
+function rawRows(raw) {
+  const fields = raw.split('\0'), rows = [];
+  for (let index = 0; index < fields.length - 1;) {
+    const match = /^:(\d{6}) (\d{6}) ([a-f0-9]+) ([a-f0-9]+) ([A-Z])\d*$/u.exec(fields[index++]);
+    if (!match) unavailable('The checkpoint comparison is malformed.');
+    const [, oldMode, newMode, oldOid, newOid, status] = match;
+    const first = fields[index++], second = status === 'R' || status === 'C' ? fields[index++] : undefined;
+    if (!first || (second === '' )) unavailable('The checkpoint comparison is malformed.');
+    rows.push({ status, oldMode, newMode, oldOid, newOid, oldPath: first, newPath: second ?? first });
+  }
+  return rows;
+}
+
+// `git diff --numstat -z -M`: renames use an empty path field followed by both paths.
+function numstatRows(raw) {
+  const fields = raw.split('\0'), stats = new Map();
+  for (let index = 0; index < fields.length - 1;) {
+    const row = fields[index++], first = row.indexOf('\t'), second = row.indexOf('\t', first + 1);
+    if (first < 0 || second < 0) unavailable('The checkpoint line counts are malformed.');
+    const added = row.slice(0, first), deleted = row.slice(first + 1, second);
+    let path = row.slice(second + 1);
+    if (!path) { index++; path = fields[index++]; }
+    const binary = added === '-' || deleted === '-';
+    stats.set(path, binary ? { binary: true, additions: null, deletions: null } : { binary: false, additions: Number(added), deletions: Number(deleted) });
+  }
+  return stats;
+}
+
+const kind = mode => !mode || /^0+$/u.test(mode) ? null : REGULAR.has(mode) ? 'file' : mode === '120000' ? 'symlink' : mode === '160000' ? 'submodule' : 'other';
+
+/** Parse unified diff text into hunks with old/new line numbers. */
+export function parseHunks(text) {
+  const hunks = [];
+  let hunk, oldLine = 0, newLine = 0;
+  for (const line of text.split('\n')) {
+    const header = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(.*)$/u.exec(line);
+    if (header) {
+      hunk = { oldStart: Number(header[1]), oldLines: header[2] === undefined ? 1 : Number(header[2]), newStart: Number(header[3]), newLines: header[4] === undefined ? 1 : Number(header[4]), section: header[5].trim(), rows: [] };
+      hunks.push(hunk); oldLine = hunk.oldStart; newLine = hunk.newStart; continue;
+    }
+    if (!hunk || !line) continue;
+    const sign = line[0], body = line.slice(1);
+    if (sign === ' ') hunk.rows.push({ type: 'context', old: oldLine++, new: newLine++, text: body });
+    else if (sign === '-') hunk.rows.push({ type: 'deletion', old: oldLine++, new: null, text: body });
+    else if (sign === '+') hunk.rows.push({ type: 'addition', old: null, new: newLine++, text: body });
+    else if (sign === '\\' && hunk.rows.length) hunk.rows.at(-1).noNewline = true;
+  }
+  return hunks;
+}
+
+function wholeFileHunk(text, side) {
+  const lines = text.split('\n'), noNewline = text.length > 0 && !text.endsWith('\n');
+  if (!noNewline) lines.pop();
+  if (!lines.length) return [];
+  const rows = lines.map((line, index) => side === 'new'
+    ? { type: 'addition', old: null, new: index + 1, text: line }
+    : { type: 'deletion', old: index + 1, new: null, text: line });
+  if (noNewline) rows.at(-1).noNewline = true;
+  return [side === 'new'
+    ? { oldStart: 0, oldLines: 0, newStart: 1, newLines: rows.length, section: '', rows }
+    : { oldStart: 1, oldLines: rows.length, newStart: 0, newLines: 0, section: '', rows }];
+}
+
+function mergeRanges(ranges) {
+  const merged = [];
+  for (const range of [...ranges].sort((a, b) => a.side.localeCompare(b.side) || a.start - b.start)) {
+    const last = merged.at(-1);
+    if (last && last.side === range.side && range.start <= last.end + 1) last.end = Math.max(last.end, range.end);
+    else merged.push({ ...range });
+  }
+  return merged;
+}
+
+/** A display model of exactly one frozen checkpoint comparison. Every byte comes
+ * from immutable blob IDs recorded for the checkpoint, never the working tree. */
+export async function loadChangeView(snapshot, config, { env = process.env } = {}) {
+  const root = snapshot?.repoRoot;
+  if (typeof root !== 'string' || !Array.isArray(snapshot.files)) unavailable('This checkpoint has no recorded file inventory.');
+  if (snapshot.base && !OID.test(snapshot.base)) unavailable('The checkpoint base is not an immutable Git object.');
+  const commit = snapshot.event === 'pre-commit';
+  if (commit && !Array.isArray(snapshot.indexEntries)) unavailable('This older commit checkpoint did not record its staged file inventory.');
+  if (!commit && !OID.test(snapshot.head || '')) unavailable('The checkpoint head is not an immutable Git object.');
+  const run = (args, options = {}) => git(root, args, { ...options, env });
+  const ignore = await loadIgnorePolicy(root, { env, exclude: config.exclude });
+  if (snapshot.ignoreHash && ignore.hash !== snapshot.ignoreHash) unavailable('The exclusion rules changed after this checkpoint was created.');
+  const format = (await run(['rev-parse', '--show-object-format']))?.trim();
+  const emptyTree = createHash(format === 'sha256' ? 'sha256' : 'sha1').update('tree 0\0').digest('hex');
+  const base = snapshot.base ? treeEntries(await run(['ls-tree', '-r', '-z', '--full-tree', snapshot.base]) ?? '') : new Map();
+  const head = commit
+    ? new Map(snapshot.indexEntries.map(entry => [entry.path, { mode: entry.mode, oid: entry.oid }]))
+    : treeEntries(await run(['ls-tree', '-r', '-z', '--full-tree', snapshot.head]) ?? '');
+  const comparison = ['diff', '--no-ext-diff', '--no-textconv', '--no-color', '-M', ...(commit ? ['--cached', snapshot.base || emptyTree] : [snapshot.base || emptyTree, snapshot.head])];
+  const raw = await run([...comparison, '--raw', '-z', '--no-abbrev', '--']);
+  const numstat = await run([...comparison, '--numstat', '-z', '--']);
+  if (raw === null || numstat === null) unavailable('The checkpoint comparison is too large to display.');
+  // A commit checkpoint compares against the live index. Accept it only when
+  // it still matches the pinned index entries and did not move mid-read.
+  if (commit && (await run([...comparison, '--raw', '-z', '--no-abbrev', '--'])) !== raw) unavailable('The staged changes moved while loading the checkpoint.');
+  const stats = numstatRows(numstat), files = [], seen = new Set();
+  const allowed = path => !ignore.matches(path);
+  for (const row of rawRows(raw)) {
+    const oldSide = row.status === 'A' ? null : { path: row.oldPath, mode: row.oldMode, oid: row.oldOid };
+    const newSide = row.status === 'D' ? null : { path: row.newPath, mode: row.newMode, oid: row.newOid };
+    for (const [side, tree] of [[oldSide, base], [newSide, head]]) {
+      if (side && allowed(side.path) && tree.get(side.path)?.oid !== side.oid) unavailable('The checkpoint comparison no longer matches its recorded Git objects.');
+    }
+    let from = oldSide && allowed(oldSide.path) ? oldSide : null, to = newSide && allowed(newSide.path) ? newSide : null;
+    if (!from && !to) continue;
+    // A rename across an exclusion boundary must not reveal the excluded name.
+    const split = row.status === 'R' && (!from || !to);
+    if (from) seen.add(from.path);
+    if (to) seen.add(to.path);
+    const status = from && to ? (row.status === 'R' ? 'renamed' : 'modified') : to ? 'added' : 'deleted';
+    const counted = split ? { binary: false, additions: null, deletions: null } : stats.get((to || from).path) ?? { binary: false, additions: null, deletions: null };
+    files.push({
+      path: (to || from).path, ...(status === 'renamed' ? { oldPath: from.path } : {}), status,
+      binary: counted.binary, additions: counted.additions, deletions: counted.deletions,
+      oldKind: kind(from?.mode), newKind: kind(to?.mode),
+      ...(from && to && from.mode !== to.mode ? { modeChange: { from: from.mode, to: to.mode } } : {}),
+      oldOid: from?.oid ?? null, newOid: to?.oid ?? null,
+    });
+  }
+  const recorded = new Set(snapshot.files);
+  if (seen.size !== recorded.size || [...seen].some(path => !recorded.has(path))) unavailable('The displayed comparison does not match the reviewed file list.');
+  files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const byPath = new Map(files.map(file => [file.path, file]));
+  const totals = summarize(files);
+  const header = {
+    checkpoint: snapshot.id, repository: basename(root), event: snapshot.event,
+    remote: snapshot.target?.remote ?? null, destination: snapshot.target?.ref ?? null,
+    base: snapshot.base ?? null, head: commit ? null : snapshot.head, staged: commit,
+    excludedFiles: Array.isArray(snapshot.omitted) ? snapshot.omitted.length : 0,
+  };
+
+  async function blobText(oid) {
+    const body = await run(['cat-file', 'blob', oid], { buffer: true, maxBuffer: VIEW_LIMITS.bytes });
+    if (body === null) return { note: 'too-large' };
+    if (body.includes(0)) return { note: 'binary' };
+    try { return { text: decoder().decode(body) }; } catch { return { note: 'non-utf8' }; }
+  }
+
+  async function diff(path, { context = 3 } = {}) {
+    const file = byPath.get(path);
+    if (!file) unavailable('That file is not part of this checkpoint.');
+    const level = Object.hasOwn(CONTEXT_LEVELS, context) ? context : 3;
+    const result = { path: file.path, ...(file.oldPath ? { oldPath: file.oldPath } : {}), status: file.status, binary: file.binary, additions: file.additions, deletions: file.deletions, ...(file.modeChange ? { modeChange: file.modeChange } : {}), context: String(level), hunks: [], truncated: null, note: null };
+    const kinds = [file.oldKind, file.newKind].filter(Boolean);
+    if (file.binary) return { ...result, note: 'binary' };
+    if (kinds.some(value => value !== 'file')) return { ...result, note: kinds.includes('submodule') ? 'submodule' : kinds.includes('symlink') ? 'symlink' : 'unsupported' };
+    let hunks;
+    if (file.oldOid && file.newOid) {
+      if (file.oldOid === file.newOid) return { ...result, note: file.status === 'renamed' ? 'rename-only' : 'mode-only' };
+      const body = await run(['diff', '--no-ext-diff', '--no-textconv', '--no-color', '--full-index', `--unified=${CONTEXT_LEVELS[level]}`, file.oldOid, file.newOid, '--'], { buffer: true, maxBuffer: VIEW_LIMITS.bytes });
+      if (body === null) return { ...result, note: 'too-large' };
+      let text;
+      try { text = decoder().decode(body); } catch { return { ...result, note: 'non-utf8' }; }
+      hunks = parseHunks(text);
+    } else {
+      const blob = await blobText(file.newOid || file.oldOid);
+      if (blob.note) return { ...result, note: blob.note };
+      hunks = wholeFileHunk(blob.text, file.newOid ? 'new' : 'old');
+      if (!hunks.length) return { ...result, note: 'empty' };
+    }
+    const total = hunks.reduce((sum, hunk) => sum + hunk.rows.length, 0);
+    if (total > VIEW_LIMITS.rows) {
+      let remaining = VIEW_LIMITS.rows;
+      hunks = hunks.filter(() => remaining > 0).map(hunk => {
+        const rows = hunk.rows.slice(0, remaining); remaining -= rows.length;
+        return { ...hunk, rows, ...(rows.length < hunk.rows.length ? { cut: true } : {}) };
+      });
+      result.truncated = { shownRows: VIEW_LIMITS.rows, totalRows: total };
+    }
+    return { ...result, hunks };
+  }
+
+  // Map one retained read_diff page back to file lines, after checking that its
+  // exact bytes still occur at the recorded offset of the regenerated text.
+  const diffTexts = new Map();
+  async function workspaceText(path) {
+    if (diffTexts.has(path)) return diffTexts.get(path);
+    const chunks = []; let size = 0, text = null;
+    try {
+      for await (const chunk of workspaceDiffText(root, path, base.get(path), head.get(path), env)) {
+        size += chunk.length; if (size > VIEW_LIMITS.evidenceBytes) throw new Error('too large');
+        chunks.push(chunk);
+      }
+      text = Buffer.concat(chunks);
+    } catch { text = null; }
+    diffTexts.set(path, text); return text;
+  }
+  function diffLineMap(buffer, synthetic) {
+    const lines = [], starts = [];
+    let at = 0, oldLine = 0, newLine = 0, inHunk = synthetic, header = synthetic ? 0 : -1;
+    const text = buffer.toString('utf8').split('\n');
+    for (const line of text) {
+      starts.push(at); at += Buffer.byteLength(line) + 1;
+      let mapped = null;
+      if (line.startsWith('File modes: ') && lines.length === 0) { lines.push(null); continue; }
+      if (synthetic && header < 2) { header++; lines.push(null); if (header === 2) { oldLine = 1; newLine = 1; } continue; }
+      const hunk = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/u.exec(line);
+      if (!synthetic && hunk) { inHunk = true; oldLine = Number(hunk[1]); newLine = Number(hunk[2]); lines.push(null); continue; }
+      if (inHunk && line) {
+        if (line[0] === ' ') mapped = { side: 'new', line: newLine++, oldLine: oldLine++ };
+        else if (line[0] === '+') mapped = { side: 'new', line: newLine++ };
+        else if (line[0] === '-') mapped = { side: 'old', line: oldLine++ };
+      }
+      lines.push(mapped);
+    }
+    return { lines, starts };
+  }
+  async function diffRanges(path, observation) {
+    const result = observation.result, before = base.get(path), after = head.get(path);
+    if (result.path !== path || result.binary || typeof result.text !== 'string' || !Number.isSafeInteger(result.offset)) return [];
+    if ((result.baseOid ?? null) !== (before?.oid ?? null) || (result.headOid ?? null) !== (after?.oid ?? null)) return [];
+    const buffer = await workspaceText(path);
+    if (!buffer) return [];
+    const observed = Buffer.from(result.text);
+    if (!buffer.subarray(result.offset, result.offset + observed.length).equals(observed)) return [];
+    const { lines, starts } = diffLineMap(buffer, !(before && after));
+    const end = result.offset + observed.length, ranges = [];
+    for (let index = 0; index < lines.length; index++) {
+      const lineEnd = index + 1 < starts.length ? starts[index + 1] : buffer.length;
+      if (!lines[index] || lineEnd <= result.offset || starts[index] >= end) continue;
+      ranges.push({ side: lines[index].side, start: lines[index].line, end: lines[index].line });
+    }
+    return ranges;
+  }
+
+  /** Verified locations for one question: only exact observations whose blob
+   * IDs match this checkpoint become line ranges. Model text never does. */
+  async function evidenceFor(question, review) {
+    const cited = [...new Set((question?.evidence ?? []).map(item => item?.path).filter(path => typeof path === 'string' && allowed(path)))];
+    const observations = review?.snapshotId === snapshot.id && Array.isArray(review.evidence) ? review.evidence : [];
+    const refs = [];
+    for (const path of cited) {
+      const ranges = [];
+      for (const item of observations) {
+        if (!Array.isArray(item?.paths) || !item.paths.includes(path) || !item.result || typeof item.result !== 'object') continue;
+        if (item.tool === 'read_file') {
+          const side = item.result.revision === 'base' ? 'old' : 'new', entry = (side === 'old' ? base : head).get(path);
+          if (item.result.path === path && entry && item.result.oid === entry.oid && Number.isSafeInteger(item.result.startLine) && Number.isSafeInteger(item.result.endLine) && item.result.endLine >= item.result.startLine) ranges.push({ side, start: item.result.startLine, end: item.result.endLine });
+        } else if (item.tool === 'search' && Array.isArray(item.result.matches)) {
+          for (const match of item.result.matches) {
+            const side = match?.revision === 'base' ? 'old' : 'new', entry = (side === 'old' ? base : head).get(path);
+            if (match?.path === path && entry && match.oid === entry.oid && Number.isSafeInteger(match.line)) ranges.push({ side, start: match.line, end: match.line });
+          }
+        } else if (item.tool === 'read_diff') ranges.push(...await diffRanges(path, item));
+      }
+      const file = byPath.get(path) ?? files.find(candidate => candidate.oldPath === path);
+      refs.push({ path, inChange: Boolean(file), ...(file ? { viewPath: file.path } : {}), ranges: mergeRanges(ranges) });
+    }
+    return refs;
+  }
+
+  return {
+    header, totals,
+    summary: () => ({ header, totals, files: files.slice(0, VIEW_LIMITS.files).map(({ oldOid, newOid, oldKind, newKind, ...file }) => ({ ...file, ...(oldKind && oldKind !== 'file' || newKind && newKind !== 'file' ? { special: newKind !== 'file' ? newKind : oldKind } : {}) })), listed: Math.min(files.length, VIEW_LIMITS.files) }),
+    diff, evidenceFor,
+  };
+}
+
+export function summarize(files) {
+  const totals = { files: files.length, additions: 0, deletions: 0, binaryFiles: 0, uncountedFiles: 0 };
+  for (const file of files) {
+    if (file.binary) totals.binaryFiles++;
+    else if (file.additions === null || file.deletions === null) totals.uncountedFiles++;
+    else { totals.additions += file.additions; totals.deletions += file.deletions; }
+  }
+  return totals;
+}

package/src/cli.js

@@ -1,11 +1,12 @@
 import path from 'node:path';
+import { VERSION } from './version.js';
 import { fileURLToPath } from 'node:url';
 import { lstat } from 'node:fs/promises';
 import { parseArgs, promisify } from 'node:util';
 import { execFile } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { Writable } from 'node:stream';
-import { getPaths, loadConfig, saveConfig, saveOpenRouterKey, openRouterKey, validateConfig, repositoryConfigInfo, policyHash } from './config.js';
+import { getPaths, loadConfig, saveConfig, saveOpenRouterKey, openRouterKey, saveOpenAIEndpoint, openAIEndpoint, validateConfig, repositoryConfigInfo, policyHash } from './config.js';
 import { initializeRepository } from './repo-config.js';
 import * as git from './git.js';
 import { install, uninstall, doctor, dispatchHook, installedAgents, detectAgents } from './install.js';
@@ -26,14 +27,14 @@ import { toggleYolo, yoloStatus, recentOverrides } from './overrides.js';
 
 const CLI_PATH = fileURLToPath(new URL('../bin/sphinx.js', import.meta.url));
 const POLICY_FLAGS = ['branches', 'events', 'level', 'remotes'];
-const MODEL_FLAGS = ['preset', 'provider', 'model', 'small', 'medium', 'large', 'allow-paid', 'max-model-calls', 'max-output-tokens'];
+const MODEL_FLAGS = ['preset', 'provider', 'model', 'small', 'medium', 'large', 'allow-paid', 'max-model-calls', 'max-output-tokens', 'cli-billing'];
 const OPTIONS = {
   install: ['yes', 'repo', 'agents', ...MODEL_FLAGS, 'launch', 'no-launch', ...POLICY_FLAGS],
   activate: ['agents', 'json'],
   init: ['yes', 'json', 'context', ...POLICY_FLAGS], check: ['json', 'id', 'remote', 'branch', 'staged', 'retry-review'],
   prepare: ['json', 'worker', 'retry'],
   answer: ['json', 'text'], explain: ['json'], dispute: ['json', 'text'], pending: ['json'],
-  status: ['json'], config: ['json', ...MODEL_FLAGS], doctor: ['json'], auth: [], uninstall: ['repo'],
+  status: ['json'], config: ['json', ...MODEL_FLAGS], doctor: ['json'], auth: ['provider', 'base-url'], uninstall: ['repo'],
   mcp: [], yolo: ['json', 'reason'],
 };
 const json = value => console.log(JSON.stringify(value, null, 2));
@@ -142,6 +143,7 @@ export function applyInstallOptions(current, values) {
   }
   for (const tier of ['small', 'medium', 'large']) if (values[tier] !== undefined) config.models[tier] = parseRoute(values[tier]);
   if (values['allow-paid']) config.allowPaid = true;
+  if (values['cli-billing'] !== undefined) config.cliBilling = values['cli-billing'];
   validateConfig(config);
   if (values.agents !== undefined && !['auto', 'none'].includes(values.agents)) {
     const selected = values.agents.split(',');
@@ -169,6 +171,7 @@ function printConfiguration(terminal, config, { routes = true } = {}) {
   if (routes) {
     terminal.section('Evaluator routes');
     terminal.rows(['small', 'medium', 'large'].map(tier => [tier[0].toUpperCase() + tier.slice(1), routeText(config.models[tier])]));
+    if (Object.values(config.models).some(route => ['codex', 'claude'].includes(route.provider))) terminal.rows([['Codex/Claude billing', config.cliBilling === 'api' ? 'API keys from your environment, when set' : 'Your signed-in plan; API keys in your environment are ignored']]);
     terminal.blank(); terminal.note(`Model calls: ${modelLimitText(config.maxModelCalls)}. Review, compaction, grading, learning, and failed requests stay counted. Completion lasts ${config.receiptHours} hours unless code, destination, or policy changes.`);
     terminal.note(`Review planning targets: ${reviewCapsText(config)} calls. These are soft targets; only explicitly configured request limits stop further calls. Context limits and deadlines still apply.`);
     terminal.note('A call cap is optional. Set one with sphinx config --max-model-calls 30, or clear it with --max-model-calls unlimited.');
@@ -205,6 +208,26 @@ async function activateCommand(values) {
   return result.results.some(item => item.status !== 'opened') ? 1 : 0;
 }
 
+async function readHidden(prompt) {
+  const hidden = new Writable({ write(_chunk, _encoding, callback) { callback(); } });
+  process.stdout.write(prompt);
+  try { return await withReadline(ask => ask(''), { output: hidden, terminal: true }); } finally { process.stdout.write('\n'); }
+}
+
+async function authOpenAI(baseUrlFlag) {
+  if (!process.stdin.isTTY) throw new Error('Set SPHINX_OPENAI_BASE_URL and SPHINX_OPENAI_API_KEY in noninteractive environments; sphinx auth requires a terminal.');
+  const terminal = ui();
+  terminal.section('OpenAI-compatible endpoint');
+  terminal.paragraph('Any server with an OpenAI chat-completions API: OpenAI, Groq, Together, vLLM, Ollama, LM Studio, and others. It must support tool calls and JSON-schema structured output. The key is only ever sent to this URL.');
+  const baseUrl = baseUrlFlag ?? await withReadline(ask => ask('\nBase URL [https://api.openai.com/v1]: '));
+  terminal.note('Input is hidden. Leave it empty only for a localhost server without a key.');
+  const key = await readHidden('\nAPI key: ');
+  const saved = await saveOpenAIEndpoint({ baseUrl: baseUrl.trim() || 'https://api.openai.com/v1', apiKey: key }); 
+  terminal.success(`Endpoint saved: ${saved}`); terminal.note(getPaths().credentials);
+  terminal.paragraph('Route reviews to it with a model ID your endpoint serves, for example:');
+  terminal.command('sphinx config --provider openai --model gpt-5-mini');
+}
+
 async function auth() {
   if (!process.stdin.isTTY) throw new Error('Use OPENROUTER_API_KEY in noninteractive environments; sphinx auth requires a terminal.');
   const terminal = ui();
@@ -410,6 +433,26 @@ async function statusCommand(command, values) {
   terminal.blank(); terminal.note('Status uses local Git state only. Agent hook trust is not verified here.'); return 0;
 }
 
+// Parses and validates a command line before any command runs; exported so documented commands can be checked.
+export function parseCommandLine(argv) {
+  const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
+    help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' }, json: { type: 'boolean' }, yes: { type: 'boolean' }, repo: { type: 'boolean' }, staged: { type: 'boolean' },
+    preset: { type: 'string' }, provider: { type: 'string' }, model: { type: 'string' }, small: { type: 'string' }, medium: { type: 'string' }, large: { type: 'string' }, level: { type: 'string' }, branches: { type: 'string' }, events: { type: 'string' }, agents: { type: 'string' }, remotes: { type: 'string' },
+    remote: { type: 'string' }, branch: { type: 'string' }, id: { type: 'string' }, text: { type: 'string' }, 'allow-paid': { type: 'boolean' },
+    context: { type: 'string' }, worker: { type: 'boolean' }, retry: { type: 'boolean' }, reason: { type: 'string' }, 'base-url': { type: 'string' }, 'cli-billing': { type: 'string' },
+    launch: { type: 'boolean' }, 'no-launch': { type: 'boolean' }, 'retry-review': { type: 'boolean' }, 'max-model-calls': { type: 'string' }, 'max-output-tokens': { type: 'string' },
+  } });
+  const [command, id] = positionals;
+  if (values.version || values.help || !command || command === 'help') return { values, command, id };
+  if (!HELP[command]) throw new Error(`Unknown command ${command}. Run sphinx --help.`);
+  for (const key of Object.keys(values)) if (!OPTIONS[command].includes(key)) throw new Error(`--${key} is not an option for ${command}. Run sphinx ${command} --help.`);
+  const needsId = ['answer', 'explain', 'dispute'].includes(command);
+  if (positionals.length > (needsId ? 2 : 1)) throw new Error(`Unexpected argument. Usage: ${HELP[command].usage}`);
+  if (needsId && !id) throw new Error(`An assessment ID is required. Run sphinx pending to find it. Usage: ${HELP[command].usage}`);
+  if (['answer', 'dispute'].includes(command) && !values.text?.trim()) throw new Error(`--text is required. Usage: ${HELP[command].usage}`);
+  return { values, command, id };
+}
+
 export async function main(argv) {
   if (argv[0] === 'mcp' && argv.length === 1) {
     const { runMcpServer } = await import('./mcp.js');
@@ -427,22 +470,9 @@ export async function main(argv) {
     }
     throw new Error('Unknown hook entry point.');
   }
-  const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
-    help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' }, json: { type: 'boolean' }, yes: { type: 'boolean' }, repo: { type: 'boolean' }, staged: { type: 'boolean' },
-    preset: { type: 'string' }, provider: { type: 'string' }, model: { type: 'string' }, small: { type: 'string' }, medium: { type: 'string' }, large: { type: 'string' }, level: { type: 'string' }, branches: { type: 'string' }, events: { type: 'string' }, agents: { type: 'string' }, remotes: { type: 'string' },
-    remote: { type: 'string' }, branch: { type: 'string' }, id: { type: 'string' }, text: { type: 'string' }, 'allow-paid': { type: 'boolean' },
-    context: { type: 'string' }, worker: { type: 'boolean' }, retry: { type: 'boolean' }, reason: { type: 'string' },
-    launch: { type: 'boolean' }, 'no-launch': { type: 'boolean' }, 'retry-review': { type: 'boolean' }, 'max-model-calls': { type: 'string' }, 'max-output-tokens': { type: 'string' },
-  } });
-  const [command, id] = positionals;
-  if (values.version) { if (values.json) json({ version: '0.1.0' }); else console.log('0.1.0'); return 0; }
+  const { values, command, id } = parseCommandLine(argv);
+  if (values.version) { if (values.json) json({ version: VERSION }); else console.log(VERSION); return 0; }
   if (values.help || !command || command === 'help') { printHelp(ui(), command === 'help' ? id : command, { json: values.json }); return 0; }
-  if (!HELP[command]) throw new Error(`Unknown command ${command}. Run sphinx --help.`);
-  for (const key of Object.keys(values)) if (!OPTIONS[command].includes(key)) throw new Error(`--${key} is not an option for ${command}. Run sphinx ${command} --help.`);
-  const needsId = ['answer', 'explain', 'dispute'].includes(command);
-  if (positionals.length > (needsId ? 2 : 1)) throw new Error(`Unexpected argument. Usage: ${HELP[command].usage}`);
-  if (needsId && !id) throw new Error(`An assessment ID is required. Run sphinx pending to find it. Usage: ${HELP[command].usage}`);
-  if (['answer', 'dispute'].includes(command) && !values.text?.trim()) throw new Error(`--text is required. Usage: ${HELP[command].usage}`);
   if (command === 'install') return installCommand(values);
   if (command === 'activate') return activateCommand(values);
   if (command === 'init') return initCommand(values);
@@ -460,7 +490,12 @@ export async function main(argv) {
     }
     return 0;
   }
-  if (command === 'auth') { await auth(); return 0; }
+  if (command === 'auth') {
+    if (values.provider === 'openai') { await authOpenAI(values['base-url']); return 0; }
+    if (values.provider !== undefined && values.provider !== 'openrouter') throw new Error('sphinx auth saves credentials for --provider openrouter (default) or --provider openai. Codex and Claude use their own sign-in.');
+    if (values['base-url'] !== undefined) throw new Error('--base-url applies to --provider openai.');
+    await auth(); return 0;
+  }
   if (command === 'uninstall') { printInstallationResult(ui(), await uninstall({ repo: !!values.repo })); return 0; }
   if (command === 'doctor') {
     const result = await doctor();
@@ -488,6 +523,7 @@ export async function main(argv) {
         terminal.note('Changing evaluator routes applies to fresh checkpoints. Existing checkpoints remain bound to their original assessment policy.');
       }
       terminal.note(result.path);
+      if (Object.values(config.models).some(route => route.provider === 'openai') && !(await openAIEndpoint().catch(() => null))) terminal.warning('No OpenAI-compatible endpoint is saved yet. Run sphinx auth --provider openai before the next check.');
       terminal.paragraph(`Model calls: ${modelLimitText(maxModelCalls)}. Review, compaction, grading, learning follow-ups, and failed requests stay counted. Saving configuration makes no model request.`);
       terminal.note(`Review planning targets: ${reviewCapsText(config)} calls. Explicit request caps, context limits, and deadlines still apply.`);
       return 0;
@@ -512,11 +548,12 @@ export async function main(argv) {
     const where = result.scope === 'repo' ? `for ${result.repoRoot}` : 'globally (every repository without its own setting)';
     const terminal = ui();
     if (result.enabled) { terminal.warning(`Yolo mode is ON ${where}. Git operations skip the understanding check; each skip is logged.`); terminal.command('sphinx yolo   # run again to turn it off'); }
+    else if (result.reposStillOn) { terminal.success(`Yolo mode is OFF ${where}.`); terminal.warning(`Checks are still skipped in ${result.reposStillOn.length === 1 ? 'a repository' : `${result.reposStillOn.length} repositories`} with ${result.reposStillOn.length === 1 ? 'its' : 'their'} own yolo setting: ${result.reposStillOn.join(', ')}. Run sphinx yolo inside each to turn it off.`); }
     else terminal.success(`Yolo mode is OFF ${where}. Understanding checks are back on.`);
     return 0;
   }
   if (['pending', 'status'].includes(command)) return statusCommand(command, values);
-  if (needsId) {
+  if (['answer', 'explain', 'dispute'].includes(command)) {
     const { repo, config } = await repoConfig(), existing = await store.read(id);
     if (existing.snapshot.repoRoot !== repo.root) throw new Error('This checkpoint belongs to a different repository.');
     const learn = command === 'explain', dispute = command === 'dispute';

package/src/config.js

@@ -4,12 +4,15 @@ import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { mkdir, open, writeFile, rename, chmod, lstat, unlink } from 'node:fs/promises';
 
+// openai means any OpenAI chat-completions-compatible endpoint the user saves.
+export const PROVIDERS = Object.freeze(['openrouter', 'codex', 'claude', 'openai', 'auto']);
+
 export const DEFAULT_CONFIG = {
   version: 1, enabled: true, provider: 'openrouter', model: 'openrouter/free',
   level: 'standard', mode: 'block', events: ['pre-push'],
   branches: ['main', 'master'], remotes: ['*'], exclude: [],
   maxContextBytes: 100000, timeoutSeconds: 180, receiptHours: 24,
-  maxModelCalls: null, maxOutputTokens: 4096, allowPaid: false,
+  maxModelCalls: null, maxOutputTokens: 4096, allowPaid: false, cliBilling: 'plan',
   agentMaxTurns: null, toolResultBytes: 16000,
   backgroundPreparation: true, preparationDebounceMs: 1500,
   models: {
@@ -70,7 +73,7 @@ export function validateConfig(config) {
   for (const key of Object.keys(config)) if (!allowed.has(key)) fail(`unknown setting ${key}`);
   if (config.version !== 1) fail('version must be 1');
   for (const key of ['enabled', 'allowPaid', 'backgroundPreparation']) if (typeof config[key] !== 'boolean') fail(`${key} must be boolean`);
-  for (const [key, values] of Object.entries({ provider: ['openrouter','codex','claude','auto'], level: ['relaxed','standard','thorough'], mode: ['block'] })) {
+  for (const [key, values] of Object.entries({ provider: PROVIDERS, level: ['relaxed','standard','thorough'], mode: ['block'], cliBilling: ['plan','api'] })) {
     if (key === 'mode' && config.mode === 'advisory') fail('mode "advisory" was removed. Remove mode from your configuration; use sphinx yolo to bypass checks when urgent');
     if (!values.includes(config[key])) fail(`${key} must be ${values.join(', ')}`);
   }
@@ -87,7 +90,8 @@ export function validateConfig(config) {
   if (!config.models || typeof config.models !== 'object') fail('models must define small, medium, and large routes');
   for (const tier of ['small','medium','large']) {
     const route = config.models[tier];
-    if (!route || !['openrouter','codex','claude','auto'].includes(route.provider)) fail(`models.${tier}.provider is invalid`);
+    if (!route || !PROVIDERS.includes(route.provider)) fail(`models.${tier}.provider is invalid`);
+    if (route.provider === 'openai' && !route.model) fail(`models.${tier} needs a model ID from your endpoint, for example openai:gpt-5-mini`);
     if (route.model !== null && (typeof route.model !== 'string' || !route.model.trim())) fail(`models.${tier}.model must be a string or null`);
     if (Object.keys(route).some(k => !['provider','model'].includes(k))) fail(`unexpected field in models.${tier}`);
   }
@@ -178,12 +182,21 @@ export function policyHash(config) {
   // checkpoint identity within the same assessment contract.
   // Version the contract when assessment semantics change: older questions and
   // receipts must not stand in for an assessment under the new requirements.
-  return createHash('sha256').update(stableStringify({ ...config, maxModelCalls: 10, agentMaxTurns: 8, assessmentContract: 3 })).digest('hex');
+  return createHash('sha256').update(stableStringify({ ...config, maxModelCalls: 10, agentMaxTurns: 8, cliBilling: 'plan', assessmentContract: 3 })).digest('hex');
+}
+
+const isRecord = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+// Saving one credential keeps the others.
+async function updateCredentials(env, update) {
+  const file = getPaths(env).credentials;
+  let current = {};
+  try { const value = await readJson(file, {}); if (isRecord(value)) current = value; } catch {}
+  await writeJson(file, update({ ...current }));
 }
 
 export async function saveOpenRouterKey(key, env = process.env) {
   if (typeof key !== 'string' || !key.trim() || /\s/.test(key.trim())) throw new Error('Enter a valid OpenRouter API key.');
-  await writeJson(getPaths(env).credentials, { openrouter: key.trim() });
+  await updateCredentials(env, credentials => ({ ...credentials, openrouter: key.trim() }));
 }
 export async function openRouterKey(env = process.env) {
   if (env.OPENROUTER_API_KEY) return env.OPENROUTER_API_KEY;
@@ -194,3 +207,42 @@ export async function openRouterKey(env = process.env) {
     return key || null;
   } catch { throw new Error('Could not read Sphinx credentials. Run sphinx auth to save your key again.'); }
 }
+
+// OpenAI-compatible endpoints. The URL and key are stored together, so a saved
+// key is only ever sent to the URL it was saved with. OPENAI_API_KEY is never read.
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+export function normalizeBaseUrl(value) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  let url;
+  try { url = new URL(text); } catch { throw new Error('Enter a base URL such as https://api.openai.com/v1.'); }
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOOPBACK.has(url.hostname))) throw new Error('The base URL must use https://. Plain http:// is allowed only for localhost.');
+  if (url.username || url.password || url.search || url.hash) throw new Error('Enter the base URL without credentials, a query string, or a fragment.');
+  // Accept a pasted full endpoint; requests always go to <base URL>/chat/completions.
+  return `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/u, '').replace(/\/chat\/completions$/u, '')}`;
+}
+const validKey = key => typeof key === 'string' && /^[\x21-\x7e]{1,4096}$/u.test(key);
+
+/** A key is optional only for a localhost server such as Ollama or LM Studio. */
+export async function saveOpenAIEndpoint({ baseUrl, apiKey }, env = process.env) {
+  const url = normalizeBaseUrl(baseUrl), key = typeof apiKey === 'string' && apiKey.trim() ? apiKey.trim() : null;
+  if (key && !validKey(key)) throw new Error('Enter the API key as a single token without spaces.');
+  if (!key && !LOOPBACK.has(new URL(url).hostname)) throw new Error('This endpoint needs an API key. Only localhost endpoints may omit it.');
+  await updateCredentials(env, credentials => ({ ...credentials, openai: { baseUrl: url, ...(key ? { apiKey: key } : {}) } }));
+  return url;
+}
+
+/** SPHINX_OPENAI_BASE_URL and SPHINX_OPENAI_API_KEY replace the saved endpoint as a pair. */
+export async function openAIEndpoint(env = process.env) {
+  if (env.SPHINX_OPENAI_BASE_URL || env.SPHINX_OPENAI_API_KEY) {
+    if (!env.SPHINX_OPENAI_BASE_URL) throw new Error('Set SPHINX_OPENAI_BASE_URL together with SPHINX_OPENAI_API_KEY.');
+    const key = env.SPHINX_OPENAI_API_KEY?.trim() || null;
+    if (key && !validKey(key)) throw new Error('SPHINX_OPENAI_API_KEY must be a single token without spaces.');
+    return { baseUrl: normalizeBaseUrl(env.SPHINX_OPENAI_BASE_URL), apiKey: key };
+  }
+  try {
+    const value = (await readJson(getPaths(env).credentials, {}))?.openai;
+    if (value === undefined) return null;
+    if (!isRecord(value) || (value.apiKey !== undefined && !validKey(value.apiKey))) throw new Error('invalid');
+    return { baseUrl: normalizeBaseUrl(value.baseUrl), apiKey: value.apiKey ?? null };
+  } catch { throw new Error('Could not read the saved OpenAI-compatible endpoint. Run sphinx auth --provider openai to save it again.'); }
+}