sphinx-understand 0.1.6 → 0.1.8

package/src/prompts.js

@@ -94,10 +94,14 @@ export async function askPolicy(config, initial, prompts, { scope = 'repository'
     { value: 'standard', label: 'Standard', description: `Caps: ${questionCapsText('standard')}. Behavior, failures, and system interactions.` },
     { value: 'thorough', label: 'Thorough', description: `Caps: ${questionCapsText('thorough')}. Also consider rollout, rollback, and compatibility.` },
   ] });
+  if (values.distance === undefined) values.distance = await prompts.choose({ title: 'How close to the code should questions get?', current: config.distance ?? 'high', choices: [
+    { value: 'high', label: 'High level', description: 'What the change does and what it affects.' },
+    { value: 'low', label: 'Low level', description: 'The specific logic, conditions, and edge cases.' },
+  ] });
   return values;
 }
 
-export async function askInstall(config, initial, prompts, { detectedAgents = [], hasExistingConfig = true } = {}) {
+export async function askInstall(config, initial, prompts, { detectedAgents = [], hasExistingConfig = true, installedPlans = [] } = {}) {
   let values = { ...initial };
   if (values.agents === undefined) {
     const selected = await prompts.multiselect({ title: 'Which coding agents do you use?', description: 'Connect any combination. Detected agents are preselected; clear all for Git-only use. Previously connected agents remain installed.', current: detectedAgents, choices: [
@@ -115,7 +119,10 @@ export async function askInstall(config, initial, prompts, { detectedAgents = []
     || explicitTiers.length === tiers.length || (hasExistingConfig && explicitTiers.length > 0);
   if (!explicitRoute) {
     const agents = values.agents === 'auto' ? detectedAgents : splitList(values.agents);
-    const recommended = agents.includes('codex') ? 'codex-economy' : agents.includes('claude') ? 'claude-economy' : undefined;
+    // A coding plan reviews far faster than OpenRouter's free router. Prefer the
+    // agent the user works in, then any Codex or Claude Code CLI installed here.
+    const plan = ['codex', 'claude'].find(name => agents.includes(name)) ?? ['claude', 'codex'].find(name => installedPlans.includes(name));
+    const recommended = plan ? `${plan}-economy` : undefined;
     const current = hasExistingConfig ? 'keep' : recommended;
     for (;;) {
       const choice = await prompts.choose({
@@ -124,7 +131,7 @@ export async function askInstall(config, initial, prompts, { detectedAgents = []
         current, requireSelection: !current,
         choices: [
           ...(hasExistingConfig ? [{ value: 'keep', label: 'Keep current model routes', description: `Small: ${routeText(config.models.small)}. Medium: ${routeText(config.models.medium)}. Large: ${routeText(config.models.large)}.` }] : []),
-          ...REVIEWER_PRESETS.map(preset => ({ value: preset.id, label: preset.label, description: preset.description })),
+          ...[...REVIEWER_PRESETS].sort((a, b) => (b.id === recommended) - (a.id === recommended)).map(preset => ({ value: preset.id, label: preset.id === recommended ? `${preset.label} (recommended)` : preset.label, description: preset.description })),
           { value: 'custom', label: 'Choose by change size', description: 'Set separate provider:model routes for small, medium, and large changes.' },
         ],
       });
@@ -154,7 +161,7 @@ export async function askInstall(config, initial, prompts, { detectedAgents = []
     }
   }
   // Offer the saved (or default) policy as one choice; branch, remote, and depth details stay optional.
-  if (['events', 'branches', 'remotes', 'level'].every(key => values[key] === undefined)) {
+  if (['events', 'branches', 'remotes', 'level', 'distance'].every(key => values[key] === undefined)) {
     const policy = await prompts.choose({
       title: 'When should Sphinx check your understanding?',
       description: 'Each repository can override this later with sphinx init.',
@@ -177,5 +184,5 @@ export function policyText(config) {
   if (config.events.includes('pre-push')) parts.push(`before pushes to ${branches} on ${remotes}`);
   if (config.events.includes('pre-commit')) parts.push(`before commits on ${branches}`);
   const text = parts.join(' and ');
-  return `${text[0].toUpperCase()}${text.slice(1)}, at ${config.level} depth.`;
+  return `${text[0].toUpperCase()}${text.slice(1)}, at ${config.level} depth, ${config.distance === 'low' ? 'low' : 'high'} level.`;
 }

package/src/sessions.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { REVIEWER_PRESETS } from './model-presets.js';
+import { recordAnswer, recordCheck } from './stats.js';
 import { withUsageMeter, withUsagePurpose, addUsage } from './usage.js';
 import { mkdir, open, readdir, stat, unlink } from 'node:fs/promises';
 import { DEFAULT_CONFIG, getPaths, readJson, writeJson, policyHash } from './config.js';
@@ -338,7 +339,12 @@ 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;
+      const scoreThis = !dispute && result.verdict !== 'ambiguous' && !(session.scored || []).includes(scoredIndex);
+      if (scoreThis) session.scored = [...(session.scored || []), scoredIndex];
       // The grader is asked to skip feedback on a correct answer; if it wrote some anyway, show it.
       session.lastFeedback = result.feedback;
       if (result.verdict === 'correct') {
@@ -370,6 +376,8 @@ export function createSessionStore({ env = process.env, generate = generateAsses
         }
         throw error;
       }
+      if (scoreThis) await recordAnswer({ repoRoot: session.snapshot.repoRoot, correct: result.verdict === 'correct' && !learn, env });
+      if (session.status === 'passed') await recordCheck({ repoRoot: session.snapshot.repoRoot, outcome: 'completed', env });
       return {...publicSession(session), verdict:result.verdict};
     });
   }
@@ -389,6 +397,7 @@ export function createSessionStore({ env = process.env, generate = generateAsses
       if (session.status === 'passed') return publicSession(session);
       session.status = 'skipped'; session.updatedAt = now();
       await save(session);
+      await recordCheck({ repoRoot: session.snapshot.repoRoot, outcome: 'skipped', env });
       return publicSession(session);
     });
   }
@@ -426,7 +435,10 @@ export function createSessionStore({ env = process.env, generate = generateAsses
     });
   }
   /** Pass a documentation-only change before any page or model is involved. */
-  async function passTrivial(id, config) {
+  async function passTrivial(id, config, snapshot) {
+    // Decide from the file list without the lock; a check that background
+    // preparation is holding is simply not passed here and follows the normal flow.
+    if (snapshot && !documentationOnly(snapshot.files)) return false;
     return withLock(id, env, async () => {
       const session = await read(id);
       if (session.status !== 'pending' || session.questions.length || !documentationOnly(session.snapshot.files)) return false;
@@ -434,7 +446,7 @@ export function createSessionStore({ env = process.env, generate = generateAsses
       passWithoutQuestions(session, config, 'Documentation-only change.');
       await save(session);
       return true;
-    });
+    }).catch(error => { if (error.code === 'SPHINX_SESSION_BUSY') return false; throw error; });
   }
   return {passTrivial,ensure,approved,prepare,start,retryReview,refreshBudget,answer,pending,read,skip,discard,switchRoute,public:publicSession};
 }

package/src/stats.js

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { getPaths, readJson, writeJson } from './config.js';
+
+// A small per-repository understanding score. Checks are cleaned up after a
+// day, so the score keeps its own counters: questions answered correctly on
+// the first try, questions answered, the current first-try streak, and how
+// many checks were completed or skipped. Updates are best-effort.
+export const CALIBRATION_QUESTIONS = 5;
+const RECENT = 10;
+const digest = value => createHash('sha256').update(value).digest('hex');
+export const statsFile = (repoRoot, env = process.env) => path.join(getPaths(env).home, 'stats', `${digest(repoRoot)}.json`);
+const count = value => Number.isSafeInteger(value) && value >= 0 ? value : 0;
+
+export async function readStats(repoRoot, env = process.env) {
+  const stored = await readJson(statsFile(repoRoot, env), null).catch(() => null);
+  return {
+    version: 1, repoRoot,
+    answered: count(stored?.answered), firstTry: count(stored?.firstTry), streak: count(stored?.streak), bestStreak: count(stored?.bestStreak),
+    completed: count(stored?.completed), skipped: count(stored?.skipped), updatedAt: stored?.updatedAt ?? null,
+    recent: Array.isArray(stored?.recent) ? stored.recent.filter(item => typeof item === 'boolean').slice(-RECENT) : [],
+  };
+}
+
+async function update(repoRoot, env, change) {
+  try {
+    const stats = change(await readStats(repoRoot, env));
+    await writeJson(statsFile(repoRoot, env), { ...stats, updatedAt: new Date().toISOString() });
+  } catch { /* The score never affects a check. */ }
+}
+
+/** One question's first graded answer: correct on the first try, or not. */
+export const recordAnswer = ({ repoRoot, correct, env = process.env }) => update(repoRoot, env, stats => {
+  const streak = correct ? stats.streak + 1 : 0;
+  return { ...stats, answered: stats.answered + 1, firstTry: stats.firstTry + (correct ? 1 : 0), streak, bestStreak: Math.max(stats.bestStreak, streak), recent: [...stats.recent, Boolean(correct)].slice(-RECENT) };
+});
+
+/** A check that asked questions was completed, or the human skipped it. */
+export const recordCheck = ({ repoRoot, outcome, env = process.env }) => update(repoRoot, env, stats => ({
+  ...stats, completed: stats.completed + (outcome === 'completed' ? 1 : 0), skipped: stats.skipped + (outcome === 'skipped' ? 1 : 0),
+}));
+
+/** What the questionnaire and CLI show. Accuracy stays hidden while calibrating. */
+export function scoreSummary(stats) {
+  const calibrating = stats.answered < CALIBRATION_QUESTIONS;
+  const checks = stats.completed + stats.skipped;
+  return {
+    calibrating, answered: stats.answered, needed: Math.max(0, CALIBRATION_QUESTIONS - stats.answered),
+    accuracy: calibrating ? null : Math.round((stats.firstTry / stats.answered) * 100),
+    streak: stats.streak, bestStreak: stats.bestStreak,
+    skipRate: checks ? Math.round((stats.skipped / checks) * 100) : null, checks,
+    recent: stats.recent,
+  };
+}

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; }
+}