sphinx-understand 0.0.0-stage → 0.1.1

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/check-recovery.js

@@ -0,0 +1,92 @@
+import { questionLimit } from './routing.js';
+import { modelUsageText } from './usage.js';
+
+const setupCodes = new Set(['INVALID_CONFIG', 'INVALID_SNAPSHOT', 'STALE_SNAPSHOT', 'CONTEXT_LIMIT', 'TOOL_RESULT_LIMIT', 'OUTPUT_LIMIT', 'PROVIDER_NOT_FOUND', 'PROVIDER_START_FAILED', 'PROVIDER_FAILED']);
+const setupTypes = new Set(['authentication', 'permission_denied', 'payment_required', 'context_length_exceeded', 'max_tokens_exceeded', 'token_limit_exceeded', 'string_too_long', 'invalid_request', 'invalid_prompt', 'not_found', 'precondition_failed', 'payload_too_large', 'unprocessable', 'content_policy_violation', 'refusal']);
+
+function retryable(error, before, state, minimum) {
+  if (setupCodes.has(error.code) || setupTypes.has(error.errorType)) return false;
+  if (error.code === 'OPENROUTER_PROVIDER_ERROR' && [400, 401, 402, 403, 404, 413, 422].includes(error.status)) return false;
+  // A failed preflight cannot improve by spending more. Budget exhaustion is
+  // different: an explicit human choice can authorize a new allowance.
+  if (state.usage.calls === before.usage.calls) {
+    return state.usage.limit !== null && state.usage.limit - state.usage.calls < minimum
+      && (error.code === 'REVIEWER_BUDGET' || /^Assessment call limit \(/u.test(error.message));
+  }
+  return !/API key|sign.in|model access|output (?:token )?limit|finish_reason: length|refused or filtered/iu.test(error.message);
+}
+
+function diagnostic(error, state) {
+  // The interactive menu replaces only Sphinx's own appended command advice;
+  // the underlying failure and its sanitized provider diagnostics stay visible.
+  const hints = [
+    ` Run sphinx check --id ${state.id} --retry-review to explicitly authorize a fresh review allowance; prior usage will be retained.`,
+    ` ${state.usage.limit - state.usage.calls} model calls remain in the existing assessment allowance (${state.usage.calls}/${state.usage.limit} used). When ready, retry within that allowance: sphinx check --id ${state.id}.`,
+    ` When ready, continue the check: sphinx check --id ${state.id}.`,
+  ];
+  let message = error.message || String(error);
+  for (const hint of hints) if (message.endsWith(hint)) message = message.slice(0, -hint.length);
+  return message;
+}
+
+/** Keep a human-owned terminal open after review failure. This function never
+ * chooses to retry, expands a budget, changes a route, or awards completion on
+ * its own. inspect() exposes public state only; validate() checks current Git
+ * content and policy before a recovery choice is shown. */
+export async function prepareInteractiveCheck({ start, inspect, authorizeMore, validate, config, choose, ui, waitingGit = false, signal }) {
+  for (;;) {
+    signal?.throwIfAborted();
+    const before = await inspect();
+    signal?.throwIfAborted();
+    try { const result = await start(); signal?.throwIfAborted(); return result; }
+    catch (error) {
+      signal?.throwIfAborted();
+      if (error.name === 'AbortError' || ['SPHINX_CANCELLED', 'EVALUATOR_CANCELLED'].includes(error.code)) throw error;
+      const state = await inspect();
+      signal?.throwIfAborted();
+      if (state.status !== 'pending' || state.preparation?.status !== 'failed' || state.progress.total !== 0) throw error;
+      await validate();
+      signal?.throwIfAborted();
+      const reserve = questionLimit(config.level, state.route.tier);
+      const reviewMinimum = state.preparation.minimumReviewerCalls === 1 ? 1 : 2, minimum = reserve + reviewMinimum;
+      const unlimited = state.usage.limit === null;
+      const remaining = unlimited ? Infinity : state.usage.limit - state.usage.calls;
+      const choices = [];
+      ui.warning(diagnostic(error, state));
+      ui.note(`Used so far: ${modelUsageText(state.usage, state.tokens)}. No questions or approval were recorded.`);
+      if (retryable(error, before, state, minimum)) {
+        if (remaining >= minimum) choices.push({
+          value: 'retry', label: state.preparation.resumable ? 'Continue the saved review' : unlimited ? 'Retry the review' : 'Retry within the remaining allowance',
+          description: `${unlimited ? 'All usage so far is kept.' : `${remaining} calls remain, including ${reserve} reserved for grading.`} ${state.preparation.resumable ? 'Reuse the evidence and investigation already saved.' : 'Keep the same evaluator route and spending settings.'}`,
+        });
+        else if (config.maxModelCalls >= minimum) choices.push({
+          value: 'extend', label: `Allow up to ${config.maxModelCalls} more calls and retry`,
+          description: `${remaining} calls remain; review needs at least ${reviewMinimum} plus ${reserve} reserved for grading. Keep all ${state.usage.calls} used calls counted and record this new allowance.`,
+        });
+      }
+      if (!choices.length) ui.note('Resolve the reported setup or evidence problem before resuming. Repeating this attempt is not offered here.');
+      choices.push({ value: 'pause', label: 'Pause this check', description: 'Save progress without making another model request. The Git operation remains unapproved.' });
+      const action = await choose({
+        title: 'Review did not finish',
+        description: waitingGit
+          ? 'The original Git operation is waiting while this terminal stays open, subject to its time limit. Choose how to continue.'
+          : 'Choose how to continue. Nothing is retried automatically.',
+        choices, current: 'pause',
+      });
+      signal?.throwIfAborted();
+      if (action === 'pause') {
+        ui.note('Progress saved. No approval was recorded.');
+        ui.command(`sphinx check --id ${state.id}`);
+        return null;
+      }
+      if (!choices.some(choice => choice.value === action)) throw new Error('Invalid review recovery choice. No additional model request was made.');
+      if (action === 'extend') {
+        await authorizeMore();
+        signal?.throwIfAborted();
+        ui.note(`Authorized up to ${config.maxModelCalls} additional model calls, including grading. Earlier usage remains counted.`);
+      }
+      // The next start still performs the store's locked policy/snapshot and
+      // budget checks. A new failure always returns to the human, never a retry loop.
+    }
+  }
+}

package/src/checkbox.js

@@ -0,0 +1,148 @@
+import { StringDecoder } from 'node:string_decoder';
+import { createTerminal, colorEnabled, wrapText } from './terminal.js';
+
+const CLEAR = '\r\x1b[J';
+const NAVIGATION = new Map([
+  ['\x1b[A', 'up'], ['\x1bOA', 'up'], ['\x1b[B', 'down'], ['\x1bOB', 'down'],
+  ['\x1b[H', 'home'], ['\x1bOH', 'home'], ['\x1b[1~', 'home'], ['\x1b[7~', 'home'],
+  ['\x1b[F', 'end'], ['\x1bOF', 'end'], ['\x1b[4~', 'end'], ['\x1b[8~', 'end'],
+]);
+
+function cancelled() {
+  const error = new Error('Selection cancelled.');
+  error.code = 'SPHINX_CANCELLED'; error.exitCode = 130;
+  return error;
+}
+
+/** A small inline checkbox prompt. The caller must close its readline first. */
+export async function checkbox({ choices, current = [], title = 'Connect your coding agents', description, ui, input = process.stdin, output = process.stdout, env = process.env, escapeTimeoutMs = 50, signalSource = process } = {}) {
+  if (!Array.isArray(choices) || choices.some(choice => !choice || typeof choice.value !== 'string' || !choice.value || typeof choice.label !== 'string' || !choice.label) || new Set(choices.map(choice => choice.value)).size !== choices.length || !Array.isArray(current)) throw new Error('Checkbox choices need unique values, labels, and an array of selected values.');
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function' || env.TERM === 'dumb') {
+    const error = new Error('Checkbox selection requires an interactive terminal.'); error.code = 'SPHINX_TTY_REQUIRED'; throw error;
+  }
+  if (input.destroyed || input.readableEnded) throw cancelled();
+  const terminal = ui || createTerminal({ stream: output, env });
+  const style = colorEnabled({ stream: output, env }) ? terminal.style : { strong: String, amber: String, green: String, muted: String };
+  const selected = new Set(current.filter(value => choices.some(choice => choice.value === value)));
+  const rows = [{ label: 'All supported agents', description: 'Select or clear every supported agent. Leave everything unchecked for Git and terminal only.' }, ...choices];
+  // Untouched stdin has readableFlowing=null while isPaused() is false. Resume
+  // only a stream that was actually flowing; otherwise the prompt keeps Node
+  // alive after installation when it was the first interactive question.
+  const wasRaw = !!input.isRaw, wasPaused = input.readableFlowing !== true;
+  let focus = 0, renderedLines = 0, escapeTimer, pending = '', finished = false, rawChanged = false, cursorHidden = false;
+  const decoder = new StringDecoder('utf8');
+  const width = () => Math.max(10, Math.min(Number(output.columns) || terminal.width || 80, terminal.width || 100) - 1);
+  const clearFrame = () => {
+    if (renderedLines) output.write(`\x1b[${renderedLines}A${CLEAR}`);
+    renderedLines = 0;
+  };
+  const render = () => {
+    clearFrame();
+    const columns = width(), height = Math.max(5, (Number(output.rows) || 24) - 1);
+    const fullHint = 'Arrows move · Space toggles · A all · Enter confirms · Esc cancels';
+    let hint = wrapText(fullHint, columns).split('\n');
+    if (hint.length + rows.length + 3 > height) hint = wrapText('↑↓ move  Space toggle  Enter done  Esc cancel', columns).split('\n');
+    const renderedRows = rows.map((row, index) => {
+      const check = index === 0 ? selected.size === 0 ? ' ' : selected.size === choices.length ? 'x' : '-' : selected.has(choices[index - 1].value) ? 'x' : ' ';
+      const prefix = `${index === focus ? '>' : ' '} [${check}] `;
+      return wrapText(row.label, Math.max(1, columns - prefix.length)).split('\n').map((line, part) => {
+        const text = (part ? ' '.repeat(prefix.length) : prefix) + line;
+        return index === focus ? style.amber(text) : text;
+      });
+    });
+    const rowRoom = Math.max(1, height - hint.length - 2);
+    let first = 0;
+    while (first < focus && renderedRows.slice(first, focus + 1).reduce((count, row) => count + row.length, 0) > rowRoom) first++;
+    const lines = [];
+    for (let index = first; index < renderedRows.length; index++) {
+      if (lines.length && lines.length + renderedRows[index].length > rowRoom) break;
+      lines.push(...renderedRows[index].slice(0, rowRoom - lines.length));
+    }
+    const detailRoom = Math.max(0, height - lines.length - hint.length - 1);
+    const detail = wrapText(rows[focus].description || '', columns).split('\n').slice(0, Math.min(3, detailRoom));
+    if (detail.length && detail.some(Boolean)) lines.push('', ...detail.map(style.muted));
+    lines.push(...hint.map(style.muted));
+    renderedLines = lines.length;
+    output.write(`${lines.join('\n')}\n`);
+  };
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      clearTimeout(escapeTimer);
+      input.removeListener('data', onData); input.removeListener('end', onEnd); input.removeListener('close', onEnd); input.removeListener('error', onError);
+      output.removeListener('resize', onResize); signalSource.removeListener('SIGINT', onInterrupt);
+      try { if (rawChanged) input.setRawMode(wasRaw); } catch {}
+      try { if (wasPaused) input.pause(); else input.resume(); } catch {}
+      try { if (cursorHidden) output.write('\x1b[?25h'); } catch {}
+    };
+    const finish = error => {
+      if (finished) return;
+      finished = true;
+      let failure = error;
+      const values = choices.filter(choice => selected.has(choice.value)).map(choice => choice.value);
+      try {
+        clearFrame();
+        if (!failure) {
+          const summary = values.length ? `Selected: ${choices.filter(choice => selected.has(choice.value)).map(choice => choice.label).join(', ')}` : 'Git and terminal only.';
+          output.write(`${wrapText(summary, width())}\n`);
+        }
+      } catch (error) { failure ||= error; }
+      cleanup();
+      if (failure) reject(failure); else resolve(values);
+    };
+    const toggleAll = () => {
+      if (selected.size === choices.length) selected.clear();
+      else for (const choice of choices) selected.add(choice.value);
+    };
+    const key = name => {
+      if (finished) return;
+      if (name === 'cancel') { finish(cancelled()); return; }
+      if (name === 'enter') { finish(); return; }
+      if (name === 'up') focus = (focus - 1 + rows.length) % rows.length;
+      else if (name === 'down') focus = (focus + 1) % rows.length;
+      else if (name === 'home') focus = 0;
+      else if (name === 'end') focus = rows.length - 1;
+      else if (name === 'all' || (name === 'space' && focus === 0)) toggleAll();
+      else if (name === 'space') {
+        const value = choices[focus - 1].value;
+        if (selected.has(value)) selected.delete(value); else selected.add(value);
+      } else return;
+      render();
+    };
+    const parse = () => {
+      clearTimeout(escapeTimer);
+      while (pending && !finished) {
+        if (pending[0] === '\x1b') {
+          const complete = [...NAVIGATION].find(([sequence]) => pending.startsWith(sequence));
+          if (complete) { pending = pending.slice(complete[0].length); key(complete[1]); continue; }
+          if ([...NAVIGATION.keys()].some(sequence => sequence.startsWith(pending))) {
+            escapeTimer = setTimeout(() => { pending = ''; key('cancel'); }, escapeTimeoutMs);
+            return;
+          }
+          // Ignore complete unrecognized CSI keys, such as Delete or PageDown.
+          const other = /^\x1b\[[0-?]*[ -/]*[@-~]/.exec(pending);
+          if (other) { pending = pending.slice(other[0].length); continue; }
+          key('cancel'); return;
+        }
+        const character = pending[0]; pending = pending.slice(1);
+        if (character === '\x03' || character === '\x04') key('cancel');
+        else if (character === '\r' || character === '\n') key('enter');
+        else if (character === ' ') key('space');
+        else if (character === 'a' || character === 'A') key('all');
+      }
+    };
+    const onData = chunk => { try { pending += typeof chunk === 'string' ? chunk : decoder.write(chunk); parse(); } catch (error) { finish(error); } };
+    const onEnd = () => finish(cancelled());
+    const onError = error => finish(error);
+    const onInterrupt = () => finish(cancelled());
+    const onResize = () => { try { render(); } catch (error) { finish(error); } };
+    try {
+      if (title) output.write(`${wrapText(style.strong(title), width())}\n`);
+      if (description) output.write(`${wrapText(description, width())}\n`);
+      output.write('\n\x1b[?25l'); cursorHidden = true;
+      input.setRawMode(true); rawChanged = true;
+      input.on('data', onData); input.on('end', onEnd); input.on('close', onEnd); input.on('error', onError);
+      output.on('resize', onResize); signalSource.on('SIGINT', onInterrupt);
+      render(); input.resume();
+    } catch (error) { finish(error); }
+  });
+}