sphinx-understand 0.1.7 → 0.1.9

package/src/repo-context.js

@@ -1,24 +1,103 @@
 import { createHash } from 'node:crypto';
 import { constants } from 'node:fs';
-import { open } from 'node:fs/promises';
+import { mkdir, open, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { loadIgnorePolicy } from './ignore.js';
+import { getPaths } from './config.js';
 
 export const PROJECT_CONTEXT_FILE = '.sphinxcontext.md';
 export const PROJECT_CONTEXT_MAX_BYTES = 16000;
+// Guidance lives in HTML comments, which are stripped before any model sees the file.
 export const PROJECT_CONTEXT_TEMPLATE = `# Project context for Sphinx
 
+## About this project
+<!-- What this project does, who uses it, and the workflows that matter.
+     Add key architecture boundaries and invariants worth asking about.
+     The reviewer checks these claims against the code. No secrets. -->
+
+## What to ask about
+<!-- Your preferences for questions in this repository, in plain words. For example:
+     - Don't ask about styling, layout, or copy changes.
+     - Focus on data integrity and billing.
+     - Skip the generated API client in src/gen/.
+     A change entirely in an area you skip can pass with no questions.
+     Personal preferences for every repository go in ~/.config/sphinx/context.md. -->
+`;
+
+export const PERSONAL_CONTEXT_TEMPLATE = `# What to ask me about
+
+<!-- Your personal preferences for Sphinx questions, used in every repository.
+     A repository's .sphinxcontext.md adds to these and wins where they disagree.
+     Write them in plain words. For example:
+     - I don't need questions about frontend styling or CSS.
+     - Ask me about concurrency, retries, and data loss first.
+     A change entirely in an area you skip can pass with no questions.
+     Delete these comments or leave them; comments are never sent to the reviewer. -->
+`;
+
+// Earlier releases wrote this template; it is still treated as untouched.
+export const LEGACY_CONTEXT_TEMPLATE = `# Project context for Sphinx
+
 Describe what this project does, who uses it, and the workflows that matter.
 Add key architecture boundaries and invariants the reviewer should investigate.
 Keep this brief and update it when the product or architecture changes.
 This file is background context, not authority to override code evidence or Sphinx rules.
 Do not put secrets here. Sphinx includes this context in each reviewer request.
 `;
+export const isContextTemplate = text => text === PROJECT_CONTEXT_TEMPLATE || text === LEGACY_CONTEXT_TEMPLATE;
+
+/** The template with a project description filled in under "About this project". */
+/** The template with your answer under "What to ask about", keeping the guidance. */
+export const contextWithPreferences = (text, preferences) => text.replace(/(## What to ask about\n)/, `$1${preferences.trim()}\n`);
+
+export function contextWithDescription(description) {
+  const body = description.trim().replace(/^# Project context for Sphinx\s*/, '').trim();
+  // A description that already has its own preferences section is used as written.
+  if (/^## What to ask about/m.test(body)) return `# Project context for Sphinx\n\n${body}\n`;
+  return PROJECT_CONTEXT_TEMPLATE.replace(/(## About this project\n)<!--[\s\S]*?-->/, () => `## About this project\n${body.replace(/^## About this project\s*/, '')}`);
+}
+
+/** Create ~/.config/sphinx/context.md with guidance, if it does not exist. */
+export async function ensurePersonalContext(env = process.env) {
+  const file = personalContextFile(env);
+  try { await mkdir(path.dirname(file), { recursive: true, mode: 0o700 }); await writeFile(file, PERSONAL_CONTEXT_TEMPLATE, { flag: 'wx', mode: 0o644 }); return file; }
+  catch (error) { if (error.code === 'EEXIST') return null; throw error; }
+}
+
+/** Whether a check carries any project context or personal preferences to steer it. */
+export const hasPreferences = snapshot => Boolean(snapshot?.projectContext?.preferences || snapshot?.projectContext?.text);
+
+/** Text a model sees: HTML comments removed, surrounding whitespace trimmed. */
+export const contextText = text => String(text).replace(/<!--[\s\S]*?(?:-->|$)/g, '').replace(/\n{3,}/g, '\n\n').trim();
+/** True when only headings remain, as in an untouched template. */
+const meaningful = text => contextText(text).split('\n').some(line => line.trim() && !/^#+\s/.test(line.trim()));
+export const personalContextFile = env => path.join(getPaths(env).home, 'context.md');
 
 const hash = text => createHash('sha256').update(text).digest('hex');
 
-/** Project-authored background, never policy or evaluator instructions. */
+// Your own preferences, read from your Sphinx settings (a dotfiles symlink is fine).
+async function loadPersonalContext(env) {
+  const file = personalContextFile(env);
+  const info = await stat(file).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!info) return '';
+  if (!info.isFile()) throw new Error(`${file} must be a regular file`);
+  if (info.size > PROJECT_CONTEXT_MAX_BYTES) throw new Error(`${file} exceeds ${PROJECT_CONTEXT_MAX_BYTES} bytes; keep preferences concise`);
+  const text = await readFile(file, 'utf8');
+  return meaningful(text) ? contextText(text) : '';
+}
+
+/**
+ * Project-authored background plus the person's own preferences, never policy
+ * or evaluator instructions. `preferences` appears only when set, so existing
+ * checks keep their identity.
+ */
 export async function loadProjectContext(repoRoot, { env = process.env, ignore } = {}) {
+  const preferences = await loadPersonalContext(env).catch(error => { throw new Error(`Cannot read your Sphinx preferences: ${error.message}`); });
+  const project = await loadRepositoryContext(repoRoot, { env, ignore });
+  return preferences ? { ...project, preferences, hash: hash(`${project.hash}\0${preferences}`) } : project;
+}
+
+async function loadRepositoryContext(repoRoot, { env, ignore }) {
   const policy = ignore || await loadIgnorePolicy(repoRoot, { env });
   const empty = reason => ({ path: PROJECT_CONTEXT_FILE, text: '', hash: hash(reason) });
   // Do not even stat/open an explicitly excluded context file.
@@ -35,7 +114,10 @@ export async function loadProjectContext(repoRoot, { env = process.env, ignore }
     if (bytesRead > PROJECT_CONTEXT_MAX_BYTES) throw new Error(`exceeds ${PROJECT_CONTEXT_MAX_BYTES} bytes`);
     const text = buffer.subarray(0, bytesRead).toString('utf8');
     if (text.includes('\0')) throw new Error('must be UTF-8 text');
-    return { path: PROJECT_CONTEXT_FILE, text, hash: hash(text) };
+    // An untouched template says nothing; comments never reach a model.
+    if (!meaningful(text)) return empty('template');
+    // The identity hash stays on the file's bytes, so upgrading keeps existing checks.
+    return { path: PROJECT_CONTEXT_FILE, text: contextText(text), hash: hash(text) };
   } catch (error) {
     if (error.code === 'ENOENT') return empty('absent');
     throw new Error(`Cannot read ${PROJECT_CONTEXT_FILE}: ${error.code === 'ELOOP' ? 'symlinks are not allowed' : error.code || error.message}`);

package/src/repo-setup.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 import { loadConfig, repositoryConfigInfo, readJson, REPOSITORY_CONFIG_KEYS, stableStringify, validateRepositoryConfig } from './config.js';
 import { compileIgnore, loadIgnorePolicy } from './ignore.js';
-import { PROJECT_CONTEXT_FILE, PROJECT_CONTEXT_MAX_BYTES, PROJECT_CONTEXT_TEMPLATE } from './repo-context.js';
+import { PROJECT_CONTEXT_FILE, PROJECT_CONTEXT_MAX_BYTES, isContextTemplate, contextWithDescription } from './repo-context.js';
 import { initializeRepository } from './repo-config.js';
 
 // Agent-driven repository setup: a read-only proposal, then a validated apply.
@@ -171,7 +171,7 @@ export async function suggestRepositorySetup({ repoRoot, env = process.env }) {
   const policy = await loadIgnorePolicy(root, { env, exclude: effective.exclude });
   const branch = await detectBranch(root);
   const existingContext = await readRegular(path.join(root, PROJECT_CONTEXT_FILE));
-  const contextIsTemplate = existingContext === null || existingContext === PROJECT_CONTEXT_TEMPLATE;
+  const contextIsTemplate = existingContext === null || isContextTemplate(existingContext);
   let config = null;
   if (!info.exists || info.legacy) {
     const defaults = info.exists ? null : await loadConfig(undefined, env);
@@ -268,7 +268,7 @@ export async function applyRepositorySetup({ repoRoot, proposal, config, env = p
   const ignorePath = path.join(root, '.sphinxignore'), contextPath = path.join(root, PROJECT_CONTEXT_FILE);
   // Checks symlinks and sizes before initializeRepository makes its first write.
   const [ignoreBefore, contextBefore] = await Promise.all([readRegular(ignorePath), readRegular(contextPath)]);
-  const replaceTemplate = contextBefore === PROJECT_CONTEXT_TEMPLATE && plan.context !== null;
+  const replaceTemplate = isContextTemplate(contextBefore) && plan.context !== null;
   const missingIgnore = plan.ignore.filter(line => !new Set((ignoreBefore ?? '').split(/\r?\n/).map(value => value.trim())).has(line));
   if (Buffer.byteLength(`${ignoreBefore ?? ''}${missingIgnore.join('\n')}`) > IGNORE_MAX_BYTES) throw invalid([`.sphinxignore would exceed ${IGNORE_MAX_BYTES} bytes`]);
 
@@ -284,10 +284,10 @@ export async function applyRepositorySetup({ repoRoot, proposal, config, env = p
       if (!created.includes('.sphinxignore')) { updated.push('.sphinxignore'); preserved.splice(preserved.indexOf('.sphinxignore'), 1); }
     }
   }
-  if (replaceTemplate && await readRegular(contextPath) === PROJECT_CONTEXT_TEMPLATE) {
-    await writeRegular(contextPath, plan.context, constants.O_TRUNC);
+  if (replaceTemplate && isContextTemplate(await readRegular(contextPath))) {
+    await writeRegular(contextPath, contextWithDescription(plan.context), constants.O_TRUNC);
     updated.push(PROJECT_CONTEXT_FILE); preserved.splice(preserved.indexOf(PROJECT_CONTEXT_FILE), 1);
-  } else if (plan.context !== null && !created.includes(PROJECT_CONTEXT_FILE) && await readRegular(contextPath) !== plan.context) {
+  } else if (plan.context !== null && !created.includes(PROJECT_CONTEXT_FILE) && await readRegular(contextPath) !== contextWithDescription(plan.context)) {
     warnings.push(`${PROJECT_CONTEXT_FILE} already exists and was kept; edit it directly to change it.`);
   }
   if (plan.config && !created.includes('.sphinxconfig')) {

package/src/sessions.js

@@ -7,6 +7,7 @@ import { DEFAULT_CONFIG, getPaths, readJson, writeJson, policyHash } from './con
 import { selectRoute, evaluatorConfig, questionLimit } from './routing.js';
 import { generateAssessment, gradeAnswer } from './evaluator.js';
 import { setTimeout as delay } from 'node:timers/promises';
+import { hasPreferences } from './repo-context.js';
 
 const now = () => new Date().toISOString();
 export function sessionFile(id, env = process.env) {
@@ -281,8 +282,10 @@ export function createSessionStore({ env = process.env, generate = generateAsses
         try {
           const result = await withUsageMeter(meterFor(session), () => withUsagePurpose('review', () => generate(session.snapshot,evaluatorConfig(config,session.route),{beforeCall,signal,maxReviewerCalls,reviewerCheckpoint,onProgress,env})));
           signal?.throwIfAborted();
-          // The reviewer, confirmed by its audit, may decide a small change needs no questions.
-          if (Array.isArray(result.questions) && !result.questions.length && session.route.tier === 'small' && typeof result.noQuestionReason === 'string' && result.noQuestionReason.trim()) {
+          // The reviewer, confirmed by its audit, may decide a change needs no questions:
+          // a small one with nothing to understand, or, when the person has stated
+          // preferences, one entirely in an area they skip.
+          if (Array.isArray(result.questions) && !result.questions.length && (session.route.tier === 'small' || hasPreferences(session.snapshot)) && typeof result.noQuestionReason === 'string' && result.noQuestionReason.trim()) {
             await validate(session.snapshot, config);
             signal?.throwIfAborted();
             if (result.review) session.review = result.review;
@@ -339,7 +342,7 @@ export function createSessionStore({ env = process.env, generate = generateAsses
       // Capture after charging the grade: cancellation rolls back progress, not
       // model usage, and leaves the same question available to the human.
       const beforeAnswer = structuredClone(session);
-      session.attempts.push({questionId:question.id,answer:text.trim(),verdict:result.verdict,feedback:result.feedback,at:now()});
+      session.attempts.push({questionId:question.id,index:session.index,kind:dispute?'dispute':learn?'learn':'answer',prompt:question.prompt,answer:text.trim(),verdict:result.verdict,feedback:result.feedback,at:now()});
       // Score each question once, on its first real grade. A dispute or an
       // ambiguous grade leaves it unscored; asking for an explanation counts as a miss.
       const scoredIndex = session.index;

package/src/storage.js

@@ -40,12 +40,14 @@ export async function collectGarbage({ env = process.env, now = Date.now(), cap
       const gone = context?.repoRoot && !(await stat(context.repoRoot).catch(() => null));
       if (!context || gone || now - file.mtime > 14 * DAY) await drop(file.path);
     }
-    for (const directory of ['preparations', 'presentations', 'terminals']) {
+    for (const directory of ['preparations', 'presentations', 'terminals', 'github/jobs']) {
       for (const file of await files(path.join(home, directory))) if (now - file.mtime > 7 * DAY) await drop(file.path);
     }
+    // A branch's check records feed its pull request comment while it is active.
+    for (const file of await files(path.join(home, 'github', 'branches'))) if (now - file.mtime > 30 * DAY) await drop(file.path);
     // Size cap: drop the oldest removable data first. Hooks, settings, the
     // install manifest, and credentials are never candidates.
-    const removable = (await Promise.all(['sessions', 'context', 'preparations', 'presentations', 'terminals'].map(dir => files(path.join(home, dir))))).flat()
+    const removable = (await Promise.all(['sessions', 'context', 'preparations', 'presentations', 'terminals', 'github'].map(dir => files(path.join(home, dir))))).flat()
       .filter(file => now - file.mtime > HOUR && !removed.includes(file.path)).sort((a, b) => a.mtime - b.mtime);
     let total = await storageUsage(env);
     for (const file of removable) { if (total <= cap) break; await drop(file.path); total -= file.size; }

package/src/terminal-check.js

@@ -0,0 +1,190 @@
+import path from 'node:path';
+import { readStats, scoreSummary } from './stats.js';
+import { prepareInteractiveCheck } from './check-recovery.js';
+import { VERSION } from './version.js';
+import { wrapText, stripAnsi } from './terminal.js';
+
+// The terminal questionnaire: the same check as the browser page, laid out for
+// a terminal. Used by `sphinx check` and when Git asks inline in a headless
+// session. Model text is printed as plain text; it never sets terminal state.
+const FRAMES = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏';
+const LEARN = 'I do not know. Explain this concept and give me a different scenario to apply it to.';
+// Strip control characters from model text so it cannot move the cursor or recolor the terminal.
+const plain = text => String(text ?? '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+const PROVIDERS = { openrouter: 'OpenRouter', openai: 'Endpoint', claude: 'Claude Code', codex: 'Codex' };
+const routeText = route => route?.provider ? [PROVIDERS[route.provider] || route.provider, route.model].filter(Boolean).join(' ') : '';
+const count = n => Number(n || 0).toLocaleString('en-US');
+
+/** One status line that redraws in place on a TTY, and prints once otherwise. */
+export function createSpinner(stream, style) {
+  let timer = null, label = '', started = 0, index = 0;
+  const width = () => Math.max(20, (stream.columns || 80) - 4);
+  const draw = () => {
+    const seconds = Math.floor((Date.now() - started) / 1000);
+    const tail = seconds >= 2 ? ` · ${seconds}s` : '';
+    const room = width() - 2 - tail.length;
+    const text = label.length > room ? `${label.slice(0, room - 1)}…` : label;
+    stream.write(`\r\x1b[2K  ${style.amber(FRAMES[index++ % FRAMES.length])} ${text}${style.muted(tail)}`);
+  };
+  return {
+    start(text) {
+      this.stop(); label = plain(text); started = Date.now();
+      if (stream.isTTY) { draw(); timer = setInterval(draw, 90); timer.unref?.(); }
+      else stream.write(`  ${label}…\n`);
+    },
+    update(text) { label = plain(text); },
+    stop() { if (timer) { clearInterval(timer); timer = null; stream.write('\r\x1b[2K'); } },
+  };
+}
+
+function scoreLine(score, style) {
+  if (!score) return '';
+  const recent = score.recent || [];
+  const slots = score.calibrating ? score.answered + score.needed : Math.max(recent.length, 1);
+  const dots = Array.from({ length: slots }, (_, i) => i < recent.length ? (recent[i] ? style.green('●') : style.amber('●')) : style.muted('○')).join('');
+  const value = score.calibrating ? style.muted(`warming up · ${score.needed} to go`) : style.strong(`${score.accuracy}%`);
+  const extra = !score.calibrating && score.streak > 1 ? style.muted(` · ${score.streak} in a row`) : '';
+  return `  ${style.muted('Your understanding')}  ${dots}  ${value}${extra}`;
+}
+
+/** A quoted block with a left rule, wrapped to the terminal. */
+function block(terminal, text, rule) {
+  const { style } = terminal;
+  for (const line of wrapText(plain(text), terminal.width - 4, '').split('\n')) terminal.line(`  ${rule(style)} ${line}`);
+}
+
+export function printHeader(terminal, { session, score }) {
+  const { style } = terminal, snapshot = session.snapshot || {};
+  const repo = snapshot.repoRoot ? path.basename(snapshot.repoRoot) : '';
+  const destination = snapshot.target?.ref ? `${snapshot.target.remote ? `${snapshot.target.remote}/` : ''}${snapshot.target.ref.replace(/^refs\/heads\//, '')}` : '';
+  const stats = snapshot.stats ? `${count(snapshot.stats.files)} file${snapshot.stats.files === 1 ? '' : 's'}  ${style.green(`+${count(snapshot.stats.additions)}`)} ${style.amber(`−${count(snapshot.stats.deletions)}`)}` : '';
+  const title = `  ${style.amber('◆')} ${style.strong('sphinx')} ${style.muted(`v${VERSION}`)}`;
+  const right = style.muted('understanding check');
+  const gap = Math.max(2, terminal.width - stripAnsi(title).length - stripAnsi(right).length);
+  terminal.line('');
+  terminal.line(`${title}${' '.repeat(gap)}${right}`);
+  const facts = [[repo, destination].filter(Boolean).join(' → '), stats, routeText(session.route)].filter(Boolean);
+  if (facts.length) terminal.line(`  ${facts.join(style.muted('  ·  '))}`);
+  const line = scoreLine(score, style);
+  if (line) terminal.line(line);
+  terminal.line(style.muted(`  ${'─'.repeat(Math.max(10, terminal.width - 4))}`));
+}
+
+function printQuestion(terminal, state, { followUp }) {
+  const { style } = terminal;
+  terminal.line('');
+  const label = `Question ${state.progress.completed + 1} of ${state.progress.total}${followUp ? ' · follow-up' : ''}`;
+  terminal.line(`  ${style.strong(label)}`);
+  block(terminal, state.question.prompt, s => s.amber('┃'));
+  if (state.question.choices?.length) state.question.choices.forEach((choice, index) => terminal.line(`    ${style.muted(`${index + 1}.`)} ${plain(choice)}`));
+  terminal.line('');
+}
+
+function commandsLine(terminal, { waitingGit }) {
+  const { style } = terminal;
+  const items = ['/hint', '/learn', '/dispute <reason>', ...(waitingGit ? ['/skip'] : []), '/quit'];
+  terminal.line(style.muted(`  Enter to send · ${items.join('  ')}`));
+}
+
+/**
+ * Run the check in this terminal. Resolves 0 when passed, 1 when paused or
+ * quit, and 3 when the human skipped a waiting Git operation.
+ */
+export async function runTerminalCheck({ store, session, config, ask, terminal: base, stream = process.stdout, signal, waitingGit = false, planProviders = [], validate, choose, skip, env = process.env }) {
+  // Lines keep their own indentation; the shared helpers would rewrap it away.
+  const terminal = { ...base, line: text => stream.write(`${text}\n`), note: text => stream.write(`${base.style.muted(`  ${text}`)}\n`), warning: text => stream.write(`  ${base.style.amber('!')} ${text}\n`) };
+  const { style } = terminal;
+  const spinner = createSpinner(stream, style);
+  const repoRoot = session.snapshot.repoRoot;
+  const score = async () => scoreSummary(await readStats(repoRoot, env));
+  printHeader(terminal, { session, score: await score().catch(() => null) });
+  terminal.line(style.muted(wrapText('Open-book: look at the code whenever it helps, then explain what it does in your own words.', terminal.width, '  ')));
+
+  const withSpinner = async (label, operation) => {
+    spinner.start(label);
+    try { return await operation(); } finally { spinner.stop(); }
+  };
+  let state;
+  try {
+    state = await prepareInteractiveCheck({
+      config, signal, waitingGit, planProviders, ui: terminal, choose,
+      start: () => withSpinner(session.questions?.length ? 'Loading prepared questions' : `Reviewing the change with ${routeText(session.route)}`, () => store.start(session.id, config, {
+        signal, onProgress: text => spinner.update(`Reviewing · ${text}`),
+      })),
+      inspect: async () => store.public(await store.read(session.id)),
+      authorizeMore: () => store.retryReview(session.id, config, { signal }),
+      validate, switchRoute: provider => store.switchRoute(session.id, config, provider, { signal }),
+    });
+  } finally { spinner.stop(); }
+  signal?.throwIfAborted();
+  if (!state) return 1;
+  if (state.status === 'passed' && state.noQuestionReason) {
+    terminal.line(''); terminal.line(`  ${style.green('✓')} No questions needed: ${plain(state.noQuestionReason)}`);
+    return finish(terminal, { waitingGit });
+  }
+
+  let shownId = null, shownNumber = 0;
+  while (state.status !== 'passed') {
+    if (state.question && state.question.id !== shownId) {
+      const number = state.progress.completed + 1;
+      printQuestion(terminal, state, { followUp: number === shownNumber });
+      commandsLine(terminal, { waitingGit });
+      shownId = state.question.id; shownNumber = number;
+    }
+    const answer = plain(await ask(`  ${style.amber('›')} `)).trim();
+    signal?.throwIfAborted();
+    if (!answer) continue;
+    if (answer === '/quit') { terminal.line(''); terminal.note('Progress saved. Run sphinx check when you are ready to continue.'); return 1; }
+    if (answer === '/hint') { await printHint(terminal, store, session.id, state.question.id); continue; }
+    if (answer === '/skip') {
+      if (!waitingGit || !skip) { terminal.warning('Skipping is only available while a Git operation is waiting.'); continue; }
+      const reason = plain(await ask(`  ${style.muted('Skip this check? The push goes through and the skip is logged. Reason (optional), or n to go back:')} `)).trim();
+      if (/^n(o)?$/i.test(reason)) continue;
+      await skip(reason || undefined);
+      terminal.line(''); terminal.line(`  ${style.amber('↷')} Skipped. Git is continuing.`);
+      return 3;
+    }
+    const dispute = answer.startsWith('/dispute '), learn = answer === '/learn';
+    if (answer === '/dispute') { terminal.warning('Add a reason: /dispute <what is ambiguous or unsupported>'); continue; }
+    if (answer.startsWith('/') && !dispute && !learn) { terminal.warning('Use /hint, /learn, /dispute <reason>, /quit, or type your answer.'); continue; }
+    const previous = state;
+    state = await withSpinner(learn ? 'Preparing an explanation and a new scenario' : dispute ? 'Reviewing the question' : 'Checking your reasoning', () => store.answer(session.id, learn ? LEARN : dispute ? answer.slice(9) : answer, config, { dispute, learn, expectedQuestionId: previous.question.id, signal }));
+    signal?.throwIfAborted();
+    printVerdict(terminal, state, { learn, dispute });
+  }
+  terminal.line('');
+  terminal.line(`  ${style.green('✓')} ${style.strong('Understanding check complete.')}`);
+  const final = await score().catch(() => null);
+  const line = scoreLine(final, style);
+  if (line) terminal.line(line);
+  return finish(terminal, { waitingGit });
+}
+
+function finish(terminal, { waitingGit }) {
+  terminal.line(terminal.style.muted(waitingGit ? '  Approval saved. Git is continuing.' : '  Approval saved for this exact change and destination. A waiting Git operation can now continue.'));
+  terminal.line('');
+  return 0;
+}
+
+function printVerdict(terminal, state, { learn, dispute }) {
+  const { style } = terminal;
+  terminal.line('');
+  if (state.verdict === 'correct') { terminal.line(`  ${style.green('✓')} Got it.`); if (state.feedback) block(terminal, state.feedback, s => s.muted('│')); return; }
+  const heading = learn ? `${style.amber('◇')} Here's how it works` : dispute ? `${style.amber('◇')} About that question` : state.verdict === 'ambiguous' ? `${style.amber('?')} Needs a little more` : `${style.amber('✗')} Not quite`;
+  terminal.line(`  ${heading}`);
+  if (state.feedback) block(terminal, state.feedback, s => s.muted('│'));
+}
+
+async function printHint(terminal, store, id, questionId) {
+  const { style } = terminal;
+  // Only the cited file paths: evidence reasons can give the answer away.
+  const session = await store.read(id).catch(() => null);
+  const question = session?.questions?.find(item => item.id === questionId);
+  const paths = [...new Set((question?.evidence || []).map(item => item.path).filter(Boolean))];
+  terminal.line('');
+  if (!paths.length) { terminal.note('No specific files are cited for this question. Start from the diff.'); return; }
+  terminal.line(`  ${style.muted('Look at')}`);
+  for (const file of paths) terminal.line(`    ${style.amber(plain(file))}`);
+  terminal.line('');
+}
+

package/src/terminal-launch.js

@@ -10,7 +10,7 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { getPaths, readJson, writeJson } from './config.js';
 
 const WORKER = fileURLToPath(new URL('./terminal-worker.js', import.meta.url));
-const CLI = fileURLToPath(new URL('../bin/sphinx.js', import.meta.url));
+export const CLI = fileURLToPath(new URL('../bin/sphinx.js', import.meta.url));
 const ID = /^[a-f0-9]{64}$/;
 const TOKEN = /^[a-f0-9-]{36}$/;
 const STARTUP_MS = 30000;
@@ -282,7 +282,7 @@ export async function runCheckpointTerminal({ recordFile, token, env = process.e
     if (Number.isInteger(child.pid)) { running.childPid = child.pid; childWrite = writeJson(recordFile, running).catch(() => {}); }
   });
   await childWrite;
-  const result = { ...running, status: code === 0 ? 'passed' : 'pending', updatedAt: Date.now(), finishedAt: Date.now() };
+  const result = { ...running, status: code === 0 ? 'passed' : code === 3 ? 'skipped' : 'pending', updatedAt: Date.now(), finishedAt: Date.now() };
   if ((await readJson(recordFile, null))?.token === token) await writeJson(recordFile, result);
   return { status: result.status, code };
 }

package/src/update.js

@@ -0,0 +1,72 @@
+import { spawn } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getPaths, readJson, writeJson } from './config.js';
+import { VERSION } from './version.js';
+
+// The questionnaire shows the installed version and, when npm has a newer one,
+// offers a one-click update. The update waits until this Sphinx process exits,
+// so a check in progress never runs on half-replaced files.
+export const PACKAGE = 'sphinx-understand';
+const CACHE_MS = 12 * 3600 * 1000;
+const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const cacheFile = env => path.join(getPaths(env).home, 'version.json');
+const parts = version => String(version).split('-')[0].split('.').map(Number);
+
+/** True when `latest` is a higher x.y.z release than `current`. */
+export function isNewer(latest, current) {
+  if (!/^\d+\.\d+\.\d+$/.test(String(latest))) return false;
+  const [a, b] = [parts(latest), parts(current)];
+  for (let index = 0; index < 3; index++) if (a[index] !== b[index]) return a[index] > (b[index] || 0);
+  return false;
+}
+
+/** The latest published version, cached for 12 hours. Never throws; null when unknown. */
+export async function latestVersion({ env = process.env, fetchImpl = globalThis.fetch, now = Date.now() } = {}) {
+  if (env.SPHINX_UPDATE_CHECK === '0') return null;
+  const cached = await readJson(cacheFile(env), null).catch(() => null);
+  if (cached && now - Date.parse(cached.checkedAt) < CACHE_MS) return cached.latest ?? null;
+  try {
+    const response = await fetchImpl(`https://registry.npmjs.org/${PACKAGE}/latest`, { signal: AbortSignal.timeout(4000), headers: { accept: 'application/json' } });
+    const latest = response.ok ? (await response.json())?.version : null;
+    if (typeof latest !== 'string') return null;
+    await writeJson(cacheFile(env), { latest, checkedAt: new Date(now).toISOString() }).catch(() => {});
+    return latest;
+  } catch { return null; }
+}
+
+/** How this copy was installed, and so how to update it. Linked checkouts update with git. */
+export async function updatePlan({ root = PACKAGE_ROOT } = {}) {
+  const real = await realpath(root).catch(() => root);
+  if (!real.split(path.sep).includes('node_modules')) return { manager: null, note: 'This is a linked development copy. Update it with git pull.' };
+  if (/[\\/](?:\.pnpm|pnpm)[\\/]/.test(real)) return { manager: 'pnpm', command: ['pnpm', 'add', '-g', `${PACKAGE}@latest`] };
+  if (/[\\/]\.bun[\\/]/.test(real)) return { manager: 'bun', command: ['bun', 'add', '-g', `${PACKAGE}@latest`] };
+  return { manager: 'npm', command: ['npm', 'install', '-g', `${PACKAGE}@latest`] };
+}
+
+/** What the questionnaire shows. Never throws. */
+export async function updateStatus({ env = process.env, fetchImpl, root } = {}) {
+  const latest = await latestVersion({ env, fetchImpl });
+  const available = !!latest && isNewer(latest, VERSION);
+  const plan = available ? await updatePlan({ root }).catch(() => ({ manager: null })) : null;
+  return { current: VERSION, latest, available, ...(plan ? { command: plan.command?.join(' ') ?? null, note: plan.note ?? null } : {}) };
+}
+
+const shellQuote = value => `'${String(value).replace(/'/g, `'\\''`)}'`;
+
+/**
+ * Install the latest version once process `waitFor` exits. Output goes to
+ * update.log in Sphinx's data directory. Resolves false if it cannot start.
+ */
+export async function scheduleUpdate({ command, waitFor = process.pid, env = process.env, spawnImpl = spawn } = {}) {
+  if (!Array.isArray(command) || !command.length) return false;
+  const log = path.join(getPaths(env).home, 'update.log');
+  const script = `while kill -0 ${Number(waitFor)} 2>/dev/null; do sleep 1; done; { date; ${command.map(shellQuote).join(' ')}; echo "exit $?"; } >> ${shellQuote(log)} 2>&1`;
+  try {
+    const child = spawnImpl('/bin/sh', ['-c', script], { env, detached: true, stdio: 'ignore' });
+    await new Promise((resolve, reject) => { child.once('error', reject); child.once('spawn', resolve); });
+    child.unref();
+    return true;
+  } catch { return false; }
+}