sphinx-understand 0.0.0-stage → 0.1.0

package/src/agent-settings.js

@@ -0,0 +1,206 @@
+import path from 'node:path';
+import { lstat, readFile, mkdir, writeFile, rename, rm, stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+
+const START = '# >>> Sphinx managed MCP server';
+const END = '# <<< Sphinx managed MCP server';
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+async function readText(file) {
+  try {
+    if ((await lstat(file)).isSymbolicLink()) throw new Error(`Refusing to replace symlink: ${file}`);
+    return await readFile(file, 'utf8');
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+function parseJson(text, file) {
+  if (text === null) return {};
+  try {
+    const value = JSON.parse(text);
+    if (!value || Array.isArray(value) || typeof value !== 'object') throw new Error();
+    return value;
+  } catch { throw new Error(`Cannot read ${file}: invalid JSON object. Fix the file and try again.`); }
+}
+
+async function writeText(file, text) {
+  if (text === null) { await rm(file, { force: true }); return; }
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const mode = await stat(file).then(s => s.mode & 0o777).catch(() => 0o600);
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try { await writeFile(temporary, text, { mode, flag: 'wx' }); await rename(temporary, file); }
+  finally { await rm(temporary, { force: true }); }
+}
+
+// Read TOML key paths without rewriting TOML or interpreting any setting values.
+function keyPath(text) {
+  const keys = []; let position = 0;
+  while (position < text.length) {
+    while (/\s/.test(text[position] || '')) position++;
+    if (text[position] === '"') {
+      const match = text.slice(position).match(/^"(?:[^"\\]|\\.)*"/);
+      if (!match) return null;
+      try { keys.push(JSON.parse(match[0])); } catch { return null; }
+      position += match[0].length;
+    } else if (text[position] === "'") {
+      const end = text.indexOf("'", position + 1); if (end < 0) return null;
+      keys.push(text.slice(position + 1, end)); position = end + 1;
+    } else {
+      const match = text.slice(position).match(/^[\w-]+/); if (!match) return null;
+      keys.push(match[0]); position += match[0].length;
+    }
+    while (/\s/.test(text[position] || '')) position++;
+    if (position === text.length) return keys;
+    if (text[position++] !== '.') return null;
+  }
+  return keys;
+}
+
+function tomlLines(text, file) {
+  let mode = null, line = '', escaped = false;
+  const lines = [];
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i], triple = text.slice(i, i + 3);
+    if (char === '\n') { lines.push(line); line = ''; if (mode === '"' || mode === "'") throw new Error(`Cannot safely update malformed TOML: ${file}`); continue; }
+    if (mode === '"""' || mode === "'''") {
+      if (triple === mode && !escaped) { mode = null; i += 2; }
+      escaped = char === '\\' && !escaped && mode === '"""'; continue;
+    }
+    if (mode) {
+      line += char;
+      if (char === mode && !escaped) mode = null;
+      escaped = char === '\\' && !escaped && mode === '"'; continue;
+    }
+    if (char === '#') { while (i + 1 < text.length && text[i + 1] !== '\n') i++; continue; }
+    if (triple === '"""' || triple === "'''") { mode = triple; line += '""'; i += 2; continue; }
+    if (char === '"' || char === "'") mode = char;
+    line += char;
+  }
+  if (mode) throw new Error(`Cannot safely update malformed TOML: ${file}`);
+  lines.push(line); return lines;
+}
+
+function assertNoCodexConflict(text, file) {
+  let table = [];
+  for (const line of tomlLines(text, file)) {
+    const header = line.match(/^\s*\[\[?(.+?)\]\]?\s*$/);
+    if (header) {
+      table = keyPath(header[1]);
+      if (!table) throw new Error(`Cannot safely inspect TOML table names in ${file}. Configure the Sphinx MCP server manually.`);
+      if (table[0] === 'mcp_servers' && table[1] === 'sphinx') throw new Error(`An existing sphinx MCP server is defined in ${file}. Rename or remove that entry before installing Sphinx.`);
+      continue;
+    }
+    const assignment = line.match(/^\s*((?:"(?:[^"\\]|\\.)*"|'[^']*'|[\w.-]|\s)+)=/);
+    if (!assignment) continue;
+    const keys = keyPath(assignment[1].trim());
+    if (!keys) continue;
+    const full = [...table, ...keys];
+    if (full[0] === 'mcp_servers' && (full.length === 1 || full[1] === 'sphinx')) throw new Error(`An existing or inline MCP definition in ${file} conflicts with sphinx. Move it to separate server tables before installing.`);
+  }
+}
+
+export function nativeHookSpecs(name, sessionHandler) {
+  const handler = {
+    type: 'mcp_tool', server: 'sphinx', tool: 'sphinx_checkpoint',
+    input: { cwd: '${cwd}', host: name, hookEvent: '${hook_event_name}', hostSession: '${session_id}' },
+    timeout: 1800, statusMessage: 'Sphinx understanding check',
+  };
+  return [
+    // Codex uses the handler's statusMessage as its /hooks display name too.
+    { event: 'SessionStart', group: { hooks: [{ ...sessionHandler, statusMessage: 'Sphinx session setup' }] } },
+    { event: 'PostToolUse', group: { matcher: 'Bash', hooks: [handler] } },
+    ...(name === 'claude' ? [{ event: 'PostToolUseFailure', group: { matcher: 'Bash', hooks: [handler] } }] : []),
+  ];
+}
+
+export const installedHookSpecs = installed => installed.hooks || [{ event: 'SessionStart', group: { hooks: [installed.handler] } }];
+
+export function hasHook(document, spec) {
+  return !!document.hooks?.[spec.event]?.some(group => {
+    const { hooks, ...metadata } = group;
+    const { hooks: expected, ...expectedMetadata } = spec.group;
+    return same(metadata, expectedMetadata) && hooks?.some(handler => same(handler, expected[0]));
+  });
+}
+
+export function addHook(document, spec) {
+  document.hooks ??= {}; document.hooks[spec.event] ??= [];
+  if (!hasHook(document, spec)) document.hooks[spec.event].push(spec.group);
+}
+
+export function removeHook(document, spec) {
+  let removed = false;
+  const groups = document.hooks?.[spec.event];
+  if (!Array.isArray(groups)) return false;
+  document.hooks[spec.event] = groups.flatMap(group => {
+    const { hooks, ...metadata } = group;
+    const { hooks: expected, ...expectedMetadata } = spec.group;
+    if (!same(metadata, expectedMetadata) || !Array.isArray(hooks)) return [group];
+    const filtered = hooks.filter(handler => { if (!same(handler, expected[0])) return true; removed = true; return false; });
+    return filtered.length ? [{ ...group, hooks: filtered }] : [];
+  });
+  if (!document.hooks[spec.event].length) delete document.hooks[spec.event];
+  if (!Object.keys(document.hooks).length) delete document.hooks;
+  return removed;
+}
+
+export async function prepareMcp({ name, paths, env, cliPath, previous }) {
+  const file = name === 'codex' ? path.join(paths.codexHome, 'config.toml')
+    : path.join(!env.SPHINX_USER_HOME && env.CLAUDE_CONFIG_DIR ? paths.claudeHome : paths.userHome, '.claude.json');
+  if (previous && previous.file !== file) throw new Error(`The ${name} MCP configuration path changed. Uninstall using the previous environment before reinstalling.`);
+  const before = await readText(file), existed = previous?.existed ?? before !== null;
+  if (name === 'claude') {
+    const document = parseJson(before, file);
+    if (document.mcpServers !== undefined && (!document.mcpServers || Array.isArray(document.mcpServers) || typeof document.mcpServers !== 'object')) throw new Error(`Invalid mcpServers object in ${file}`);
+    const existing = document.mcpServers?.sphinx;
+    if (Object.hasOwn(document.mcpServers || {}, 'sphinx') && (!previous || !same(existing, previous.entry))) throw new Error(`Refusing to replace an existing or edited sphinx MCP server in ${file}. Remove or rename that entry first.`);
+    const entry = { type: 'stdio', command: process.execPath, args: [cliPath, 'mcp'], env: { SPHINX_HOME: paths.home }, timeout: 1800000 };
+    document.mcpServers ??= {}; document.mcpServers.sphinx = entry;
+    return { before, after: `${JSON.stringify(document, null, 2)}\n`, record: { kind: 'json', file, existed, entry } };
+  }
+  let base = before || '';
+  if (previous) {
+    if (base.includes(previous.block)) base = base.replace(previous.block, '');
+    else if (before !== null) throw new Error(`Refusing to replace an edited Sphinx MCP block in ${file}. Uninstall first to preserve your edits.`);
+  }
+  if (base.includes(START) || base.includes(END)) throw new Error(`Untracked Sphinx MCP block in ${file}. Remove or rename it before installing.`);
+  assertNoCodexConflict(base, file);
+  const separator = base ? base.endsWith('\n') ? '\n' : '\n\n' : '';
+  const block = `${separator}${START}\n[mcp_servers.sphinx]\ncommand = ${JSON.stringify(process.execPath)}\nargs = ${JSON.stringify([cliPath, 'mcp'])}\ntool_timeout_sec = 1800\nenv = { SPHINX_HOME = ${JSON.stringify(paths.home)} }\n${END}\n`;
+  return { before, after: base + block, record: { kind: 'toml', file, existed, block } };
+}
+
+export async function commitMcp(plan) {
+  if (await readText(plan.record.file) !== plan.before) throw new Error(`Settings changed during installation: ${plan.record.file}. Retry installation.`);
+  await writeText(plan.record.file, plan.after);
+}
+
+export async function rollbackMcp(plan) {
+  if (await readText(plan.record.file) === plan.after) await writeText(plan.record.file, plan.before);
+}
+
+export async function removeMcp(record) {
+  if (!record) return { removed: false, missing: true };
+  const text = await readText(record.file);
+  if (text === null) return { removed: false, missing: true };
+  if (record.kind === 'toml') {
+    if (!text.includes(record.block)) return { removed: false, edited: true };
+    const after = text.replace(record.block, '');
+    await writeText(record.file, !record.existed && !after.trim() ? null : after);
+  } else {
+    const document = parseJson(text, record.file);
+    if (!same(document.mcpServers?.sphinx, record.entry)) return { removed: false, edited: true };
+    delete document.mcpServers.sphinx;
+    if (!Object.keys(document.mcpServers).length) delete document.mcpServers;
+    await writeText(record.file, !record.existed && !Object.keys(document).length ? null : `${JSON.stringify(document, null, 2)}\n`);
+  }
+  return { removed: true };
+}
+
+export async function inspectMcp(record) {
+  if (!record) return false;
+  try {
+    const text = await readText(record.file);
+    if (text === null) return false;
+    return record.kind === 'toml' ? text.includes(record.block) : same(parseJson(text, record.file).mcpServers?.sphinx, record.entry);
+  } catch { return false; }
+}

package/src/agent.js

@@ -0,0 +1,45 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+
+/** Session setup only. Git and native lifecycle hooks control the actual checkpoint. */
+export async function agentHook({ agent, event, input = '', env = process.env }) {
+  if (env.SPHINX_EVALUATOR === '1') return { output: null, exitCode: 0 };
+  if (!['codex', 'claude'].includes(agent)) throw new Error(`Unsupported agent: ${agent}`);
+  let payload;
+  try {
+    payload = typeof input === 'object' && !Buffer.isBuffer(input) ? input : JSON.parse(String(input || '{}'));
+  } catch {
+    throw new Error('Agent hook input must be valid JSON.');
+  }
+  const name = payload?.hook_event_name || event;
+  if (name !== 'SessionStart') return { output: null, exitCode: 0 };
+  if (agent === 'claude' && env.CLAUDE_ENV_FILE && /^[A-Za-z0-9_-]{1,200}$/.test(payload?.session_id || '')) {
+    // Claude's documented SessionStart environment channel tags later Bash calls,
+    // including `git -C` and `cd`, without reading the command or its output.
+    const file = await open(env.CLAUDE_ENV_FILE, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW || 0), 0o600);
+    try { await file.writeFile(`\nexport SPHINX_CLAUDE_SESSION='${payload.session_id}'\n`); }
+    finally { await file.close(); }
+  }
+  return {
+    exitCode: 0,
+    output: {
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: [
+          'Sphinx is installed to help the human retain understanding of agent-assisted changes.',
+          'Repository branch and event policy lives in .sphinxconfig (with .sphinx.json as a legacy fallback). Use `sphinx status --json` to inspect effective policy and pending assessments; do not change policy to avoid a checkpoint.',
+          'Git deterministically requires a checkpoint when repository policy matches a push or commit. For blocking checkpoints it serves a local browser questionnaire and keeps the original Git operation waiting. On macOS the page opens in the background without activating or minimizing the coding window; other environments print the local URL. After the human passes and Git verifies the exact change and policy, that same operation continues automatically. Do not start a duplicate Git operation while it waits.',
+          'Allow enough shell execution time for the human questionnaire. Sphinx waits up to 25 minutes, but the host may cancel the shell sooner. Keep the original process running using the host\'s supported yielding or background execution; do not terminate or duplicate it while the human answers.',
+          'If a local browser questionnaire is unavailable, the installed PostToolUse / PostToolUseFailure MCP hook offers a native questionnaire after Git exits. These fallback forms do not resume an exited Git process; you do not initiate or conduct the interview.',
+          'Sphinx collects the human\'s answers directly in its local browser page, explicit terminal check, or fallback native forms and grades them using an independent evaluator. Only the outcome is returned to you. Do not relay questions through chat, call sphinx answer/explain/dispute for the human, or open its local URL or automate the questionnaire UI.',
+          'Never answer on the human\'s behalf, fabricate a response, read private Sphinx session files or answer keys, or bypass the Git hook to finish the task.',
+          'Respect .sphinxignore and configured exclusions: do not read excluded files to supplement an assessment or send them to the evaluator.',
+          'The form offers learning, dispute, and pause actions. The human chooses them directly. A paused or cancelled check remains incomplete; do not repeatedly retry the Git operation to force another prompt.',
+          'After a fallback questionnaire passes, verify that the original Git operation has exited with a Sphinx blocking failure before retrying it. Never duplicate a waiting operation or repeat a successful operation. A changed commit or destination may require another assessment. Reopen a paused blocking checkpoint only when the human asks and the previous Git process has exited.',
+          'If neither the local page nor native forms are available, report the integration issue and use sphinx doctor to diagnose it. The human can run sphinx check in their own terminal. Do not substitute a chat-based questionnaire or submit answers yourself.',
+          'The assessment is open-book. Helping the human inspect code is encouraged. The coding agent must not grade the response itself.',
+        ].join('\n'),
+      },
+    },
+  };
+}

package/src/browser-interview.js

@@ -0,0 +1,278 @@
+import { createServer } from 'node:http';
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { loadConfig, policyHash } from './config.js';
+import { revalidateSnapshot } from './git.js';
+import { createSessionStore } from './sessions.js';
+import { prepareInteractiveCheck } from './check-recovery.js';
+import { claimCheckpointDialog, finishCheckpointDialog, waitForCheckpointTerminal } from './terminal-launch.js';
+import { browserPage } from './browser-page.js';
+import { recordOverride } from './overrides.js';
+
+const ID = /^[a-f0-9]{64}$/u;
+const cancelled = () => Object.assign(new Error('Check paused. Progress is saved.'), { code: 'SPHINX_CANCELLED' });
+const equal = (a, b) => typeof a === 'string' && Buffer.byteLength(a) === Buffer.byteLength(b) && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+const offLimits = env => env.SPHINX_EVALUATOR === '1' || (env.CI && !['false', '0'].includes(env.CI));
+
+/** macOS has an explicit background-open flag. Elsewhere print the local URL;
+ * do not guess at window-manager focus rules or invoke a foreground opener. */
+export async function openQuestionnaireBrowser(url, { env = process.env, platform = process.platform, spawnImpl = spawn } = {}) {
+  if (offLimits(env) || env.SSH_CONNECTION || env.SSH_TTY || platform !== 'darwin') return false;
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'http:' || parsed.hostname !== '127.0.0.1' || !parsed.port) throw new Error('Invalid local questionnaire URL.');
+  return new Promise(resolve => {
+    let child, timer, settled = false;
+    const finish = value => { if (!settled) { settled = true; clearTimeout(timer); resolve(value); } };
+    try { child = spawnImpl('/usr/bin/open', ['-g', url], { env, stdio: 'ignore' }); }
+    catch { finish(false); return; }
+    child.once('error', () => finish(false));
+    child.once('exit', code => finish(code === 0));
+    timer = setTimeout(() => { child.kill(); finish(false); }, 5000);
+  });
+}
+
+function publicFields(state) {
+  if (!state) return {};
+  return {
+    id: state.id, target: state.target,
+    route: state.route && { provider: state.route.provider, model: state.route.model, tier: state.route.tier },
+    progress: state.progress, usage: state.usage, tokens: state.tokens,
+    ...(state.question ? { question: { id: state.question.id, prompt: state.question.prompt, choices: state.question.choices || [] } } : {}),
+    ...(state.feedback ? { feedback: state.feedback } : {}),
+  };
+}
+
+/** One loopback page for a whole Git batch. The caller closes it after Git has
+ * independently verified the receipt. All form inputs come from the browser,
+ * never from tool arguments; no private evaluator data enters HTTP responses. */
+export function createBrowserInterview({ env = process.env, signal, timeoutMs = 25 * 60 * 1000,
+  store: providedStore, readConfig = loadConfig, revalidate = revalidateSnapshot,
+  reserve = claimCheckpointDialog, release = finishCheckpointDialog, waitForExisting = waitForCheckpointTerminal,
+  openBrowser = openQuestionnaireBrowser, output = line => process.stderr.write(`${line}\n`), logOverride = recordOverride,
+} = {}) {
+  const token = randomBytes(32).toString('base64url'), nonce = randomBytes(24).toString('base64');
+  let server, origin, url, opened = false, closed = false, active, skip, resolver, sequence = 0, waitingGit = false;
+  const pauseMessage = () => waitingGit
+    ? 'Paused. Progress is saved; the waiting Git operation was stopped.'
+    : 'Paused. Your progress and completed checkpoints are saved.';
+  let state = { phase: 'waiting', operationClosed: false, revision: randomUUID(), sequence, message: 'Waiting for the checkpoint.', messages: [] };
+  // The chat transcript for the current checkpoint lives only in this process.
+  // It contains public questions, feedback, and the human's own text.
+  let transcript = [], turns = 0;
+  const say = item => { transcript = [...transcript, { id: `m${++turns}`, ...item }]; };
+  const settle = status => { transcript = transcript.map(item => item.role === 'human' && item.status === 'checking' ? { ...item, status } : item); };
+  const showQuestion = visible => {
+    const question = visible?.question;
+    if (!question || transcript.some(item => item.kind === 'question' && item.questionId === question.id)) return;
+    const number = visible.progress.completed + 1;
+    say({ role: 'sphinx', kind: 'question', questionId: question.id, number, followUp: transcript.some(item => item.kind === 'question' && item.number === number), text: question.prompt, choices: question.choices || [] });
+  };
+  const streams = new Set();
+  const writeEvent = (stream, event) => {
+    if (stream.destroyed || stream.writableEnded) { streams.delete(stream); return; }
+    try {
+      // A disconnected or stalled page must not retain an ever-growing buffer
+      // or interrupt the assessment. EventSource reconnects with current state.
+      if (stream.writableLength > 256 * 1024) stream.destroy();
+      else stream.write(event);
+    } catch { stream.destroy(); streams.delete(stream); }
+  };
+  const publish = next => {
+    state = { ...next, messages: transcript, waitingGit, operationClosed: closed, revision: randomUUID(), sequence: ++sequence };
+    const event = `data: ${JSON.stringify(state)}\n\n`;
+    for (const stream of streams) writeEvent(stream, event);
+  };
+  const waitForAction = (next, allowed) => new Promise((resolve, reject) => {
+    active.signal.throwIfAborted();
+    const onAbort = () => { resolver = undefined; reject(active.signal.reason || cancelled()); };
+    const cleanup = () => active?.signal.removeEventListener('abort', onAbort);
+    resolver = { allowed, resolve: value => { cleanup(); resolver = undefined; resolve(value); }, reject: error => { cleanup(); resolver = undefined; reject(error); } };
+    active.signal.addEventListener('abort', onAbort, { once: true });
+    publish(next);
+  });
+  const headers = {
+    'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer',
+    'Content-Security-Policy': `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`,
+  };
+  const send = (res, status, value) => {
+    if (res.destroyed || res.writableEnded) return;
+    res.writeHead(status, { ...headers, 'Content-Type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(value));
+  };
+  async function handle(req, res) {
+    if (req.headers.host !== new URL(origin).host || (req.headers['sec-fetch-site'] && !['same-origin', 'none'].includes(req.headers['sec-fetch-site']))) return send(res, 403, { error: 'Forbidden request.' });
+    const route = req.url?.split('?')[0];
+    const segments = route?.split('/') || [];
+    if (!equal(segments[1], token) || segments.length > 3 || (segments[2] && !['state', 'events', 'action'].includes(segments[2]))) return send(res, 404, { error: 'Not found.' });
+    if (req.method === 'GET' && !segments[2]) {
+      res.writeHead(200, { ...headers, 'Content-Type': 'text/html; charset=utf-8' }); res.end(browserPage({ token, nonce })); return;
+    }
+    if (req.method === 'GET' && segments[2] === 'state') return send(res, 200, state);
+    if (req.method === 'GET' && segments[2] === 'events') {
+      if (streams.size >= 8) return send(res, 429, { error: 'Too many open questionnaire pages.' });
+      res.writeHead(200, { ...headers, 'Content-Type': 'text/event-stream; charset=utf-8', Connection: 'keep-alive' });
+      streams.add(res); writeEvent(res, `data: ${JSON.stringify(state)}\n\n`);
+      const heartbeat = setInterval(() => writeEvent(res, ': keep-alive\n\n'), 10000); heartbeat.unref();
+      res.once('close', () => { clearInterval(heartbeat); streams.delete(res); }); return;
+    }
+    if (req.method !== 'POST' || segments[2] !== 'action') return send(res, 405, { error: 'Unsupported method.' });
+    if (req.headers.origin !== origin || !equal(req.headers['x-sphinx-token'], token) || req.headers['content-type']?.split(';')[0] !== 'application/json') return send(res, 403, { error: 'Forbidden request.' });
+    let bytes = 0; const chunks = [];
+    // 8,000 characters can occupy 24KB in UTF-8 or 48KB when JSON-escaped.
+    for await (const chunk of req) { bytes += chunk.length; if (bytes > 64 * 1024) { send(res, 413, { error: 'Keep your response below 8,000 characters.' }); req.destroy(); return; } chunks.push(chunk); }
+    let data; try { data = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { return send(res, 400, { error: 'Invalid response.' }); }
+    if (!data || typeof data !== 'object' || Array.isArray(data) || Object.keys(data).some(key => !['id', 'revision', 'action', 'response', 'questionId'].includes(key))
+      || typeof data.action !== 'string' || (data.response !== undefined && (typeof data.response !== 'string' || data.response.length > 8000))) return send(res, 400, { error: 'Invalid response.' });
+    // Live progress changes the revision often; Pause and Skip only need the checkpoint.
+    if (!active || active.signal.aborted || data.id !== state.id || (!['pause', 'skip'].includes(data.action) && data.revision !== state.revision)) return send(res, 409, { error: 'This checkpoint changed. Use the current question.' });
+    if (data.action === 'skip') {
+      // Available at any step, including while the review is still running.
+      skip = { reason: data.response };
+      active.abort(cancelled());
+      publish({ ...publicFields(state), phase: 'skipped', message: waitingGit ? 'Skipped. Git is continuing.' : 'Skipped.' });
+      return send(res, 200, state);
+    }
+    if (data.action === 'pause') {
+      active.abort(cancelled());
+      publish({ ...publicFields(state), phase: 'paused', message: pauseMessage() });
+      return send(res, 200, state);
+    }
+    if (!resolver || !resolver.allowed.includes(data.action)) return send(res, 409, { error: 'Wait for the current step to finish.' });
+    if (['answer', 'learn', 'dispute'].includes(data.action) && data.questionId !== state.question?.id) return send(res, 409, { error: 'The question changed. Use the current question.' });
+    if (['answer', 'dispute'].includes(data.action) && !data.response?.trim()) return send(res, 400, { error: 'Enter an answer or a dispute reason first.' });
+    const current = resolver;
+    if (data.action === 'answer') say({ role: 'human', kind: 'answer', text: data.response.trim(), status: 'checking' });
+    else if (data.action === 'dispute') say({ role: 'human', kind: 'dispute', text: `Dispute: ${data.response.trim()}`, status: 'checking' });
+    else if (data.action === 'learn') say({ role: 'human', kind: 'learn', text: 'Explain this concept.', status: 'checking' });
+    publish({ ...publicFields(state), phase: 'working', message: data.action === 'answer' ? 'Checking your reasoning…' : data.action === 'learn' ? 'Preparing an explanation and a new scenario…' : data.action === 'dispute' ? 'Reviewing the question…' : 'Continuing the review…' });
+    send(res, 202, state); current.resolve(data);
+  }
+  async function ensureServer(operationEnv) {
+    if (server) return;
+    server = createServer((req, res) => {
+      res.on('error', () => res.destroy());
+      handle(req, res).catch(() => { if (!res.headersSent) send(res, 400, { error: 'Could not process this response.' }); else res.destroy(); });
+    });
+    server.requestTimeout = 15000; server.headersTimeout = 10000; server.maxHeadersCount = 32;
+    // Port 0 asks the OS for a free ephemeral loopback port, so an occupied
+    // port cannot collide. If binding still fails, forget the half-made server
+    // so a later checkpoint retries instead of serving with no origin.
+    try { await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); }); }
+    catch (error) { server = undefined; throw error; }
+    origin = `http://127.0.0.1:${server.address().port}`; url = `${origin}/${token}`;
+    output(`Sphinx questionnaire: ${url}`);
+    if (!opened) {
+      opened = true;
+      const automatic = await Promise.resolve().then(() => openBrowser(url, { env: operationEnv })).catch(() => false);
+      output(automatic ? 'Sphinx: questionnaire opened in a background browser tab. Your coding window stays in place.' : 'Sphinx: open the local URL above to answer. No application was brought to the foreground.');
+    }
+  }
+  async function present({ request, env: operationEnv = env, signal: requestSignal = signal } = {}) {
+    if (offLimits(operationEnv)) return { status: 'unavailable', reason: 'noninteractive', id: request?.id };
+    if (closed || active) return { status: 'unavailable', id: request?.id };
+    if (!request || !ID.test(request.id) || typeof request.repoRoot !== 'string') throw new Error('Invalid browser checkpoint request.');
+    const controller = new AbortController(); active = controller; skip = undefined; waitingGit = request.delivery === 'hook';
+    transcript = [];
+    const cancel = () => controller.abort(requestSignal?.reason || cancelled());
+    requestSignal?.addEventListener('abort', cancel, { once: true });
+    if (requestSignal?.aborted) cancel();
+    const timer = setTimeout(() => controller.abort(cancelled()), timeoutMs);
+    let reservation, finalStatus = 'pending';
+    const skipped = async () => {
+      // A human chose to let Git continue. Close the check and log it; never write a receipt.
+      await store.skip?.(request.id).catch(() => {});
+      await logOverride({ kind: 'skip', repoRoot: request.repoRoot, target: state.target, id: request.id, reason: skip.reason }, operationEnv).catch(() => {});
+      return { status: 'skipped', id: request.id };
+    };
+    const localSignal = controller.signal;
+    const validate = async (snapshot, expected) => {
+      localSignal.throwIfAborted();
+      const current = await readConfig(snapshot.repoRoot, operationEnv);
+      if (policyHash(current) !== policyHash(expected) || !(await revalidate(snapshot, current, { env: operationEnv }))) throw new Error('The code or settings changed. Start a new Git operation for the updated change.');
+      localSignal.throwIfAborted();
+    };
+    const store = providedStore || createSessionStore({ env: operationEnv, validate });
+    try {
+      localSignal.throwIfAborted();
+      reservation = await reserve({ request, env: operationEnv, kind: 'browser' });
+      if (reservation?.status !== 'claimed') {
+        const status = await waitForExisting({ id: request.id, env: operationEnv, timeoutMs, signal: localSignal });
+        return { status: status === 'passed' ? 'passed' : 'pending', id: request.id };
+      }
+      const session = await store.read(request.id), config = await readConfig(request.repoRoot, operationEnv);
+      if (session.snapshot.repoRoot !== request.repoRoot) throw new Error('This checkpoint belongs to another repository.');
+      await validate(session.snapshot, config);
+      let visible = store.public(session);
+      publish({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'working', message: 'Preparing your understanding check…' });
+      await ensureServer(operationEnv);
+      const notes = [];
+      const recoveryUI = { warning: text => notes.push(text), note: text => notes.push(text), command: () => {} };
+      visible = await prepareInteractiveCheck({ config, signal: localSignal, waitingGit: request.delivery === 'hook', ui: recoveryUI,
+        inspect: async () => store.public(await store.read(request.id)),
+        validate: () => validate(session.snapshot, config),
+        authorizeMore: () => store.retryReview(request.id, config, { signal: localSignal }),
+        start: async () => {
+          notes.length = 0;
+          publish({ ...publicFields(store.public(await store.read(request.id))), repoRoot: request.repoRoot, phase: 'working', message: 'Reviewing the change…' });
+          return store.start(request.id, config, { signal: localSignal, onProgress: text => {
+            say({ role: 'sphinx', kind: 'activity', text }); publish(state);
+            // Refresh tokens and cost from the per-call save without blocking review.
+            store.read(request.id).then(saved => { if (active === controller && state.id === request.id) { const fresh = store.public(saved); publish({ ...state, usage: fresh.usage, tokens: fresh.tokens }); } }, () => {});
+          } });
+        },
+        choose: async prompt => {
+          const current = store.public(await store.read(request.id));
+          const action = await waitForAction({ ...publicFields(current), repoRoot: request.repoRoot, phase: 'recovery', message: prompt.title, error: notes.join('\n'), choices: prompt.choices }, prompt.choices.map(choice => choice.value));
+          return action.action;
+        },
+      });
+      if (!visible) return skip ? skipped() : { status: 'pending', id: request.id };
+      while (visible.status !== 'passed') {
+        localSignal.throwIfAborted();
+        showQuestion(visible);
+        const action = await waitForAction({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'question', ...(visible.browserError ? { error: visible.browserError } : {}) }, ['answer', 'learn', 'dispute']);
+        try {
+          await validate(session.snapshot, config);
+          visible = await store.answer(request.id, action.action === 'learn' ? 'I do not know. Explain this concept and give me a different scenario to apply it to.' : action.response.trim(), config, {
+            learn: action.action === 'learn', dispute: action.action === 'dispute', expectedQuestionId: action.questionId, signal: localSignal,
+          });
+          settle('graded');
+          if (visible.feedback) say({ role: 'sphinx', kind: 'feedback', text: visible.feedback });
+        } catch (error) {
+          settle('not-graded');
+          localSignal.throwIfAborted(); await validate(session.snapshot, config);
+          visible = store.public(await store.read(request.id));
+          publish({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'question', error: error.message, message: 'Your response was not accepted. Review the error before submitting again.' });
+          // Re-display through waitForAction on the next iteration; never resend.
+          visible = { ...visible, browserError: error.message };
+        }
+      }
+      localSignal.throwIfAborted(); await validate(session.snapshot, config);
+      finalStatus = 'passed';
+      publish({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'passed', message: 'Understanding check complete. Return to the original Git output for the operation’s result.' });
+      return { status: 'passed', id: request.id };
+    } catch (error) {
+      settle('not-graded');
+      if (skip) return skipped();
+      publish({ ...publicFields(state), repoRoot: request.repoRoot, phase: localSignal.aborted ? 'paused' : 'error', message: localSignal.aborted ? pauseMessage() : 'The check could not finish. Saved progress and completed checkpoints are retained.', ...(localSignal.aborted ? {} : { error: error.message }) });
+      return { status: 'pending', id: request.id };
+    } finally {
+      clearTimeout(timer); requestSignal?.removeEventListener('abort', cancel); resolver?.reject(cancelled()); resolver = undefined;
+      if (reservation?.status === 'claimed') await release({ id: request.id, token: reservation.token, status: finalStatus, env: operationEnv });
+      active = undefined;
+    }
+  }
+  async function close() {
+    closed = true; active?.abort(cancelled()); resolver?.reject(cancelled()); resolver = undefined;
+    if (server) {
+      // A passed checkpoint may be followed by another destination. Only this
+      // explicit end-of-operation update tells the page to stop reconnecting.
+      publish(state);
+      // Flush the final SSE update before closing the per-operation listener.
+      await delay(40);
+      for (const stream of streams) stream.end(); streams.clear();
+      await new Promise(resolve => { server.close(resolve); server.closeAllConnections(); });
+    }
+  }
+  return { present, close, get url() { return url; }, get state() { return structuredClone(state); } };
+}