sphinx-understand 0.1.7 → 0.1.8

package/README.md

@@ -137,6 +137,8 @@ Pushing the same change again does not ask again. A pass lasts 24 hours, unless
 - **Skip this time.** Lets the push through immediately, even while the review is still running. Skips never count as passing.
 - **`sphinx yolo`** turns checks off for the current repository, or globally when run outside one. Run it again to turn checks back on. A repository's own setting wins over the global one, so turning yolo off inside a repository keeps checks on there even while global yolo is on. `--reason "prod hotfix"` is optional.
 - **`sphinx check`** runs the same check in your terminal instead of the browser.
+- **Headless or terminal-first.** Over SSH, or anywhere Sphinx can't open the browser in the background, the questions appear right in the terminal where you ran `git push`. Type `/hint`, `/learn`, `/dispute <reason>`, `/skip`, or `/quit` there. To always use the terminal, run `sphinx config --interface terminal`; to always use the browser, use `--interface browser`.
+- **On GitHub.** If the GitHub CLI (`gh`) is signed in, a pass marks the pushed commit with a `sphinx/understanding` status. You can also opt in to a summary comment on the pull request. This never blocks a push. See [GitHub commit status and pull requests](docs/configuration.md#github-commit-status-and-pull-requests).
 
 Every skip and yolo toggle is logged with its reason, and `sphinx status` lists recent ones. If Git exited before you finished, for example because your agent's shell timed out, run the push once more. Never start a second copy while one is still waiting. For more cases, see [troubleshooting](docs/integrations.md#troubleshooting).
 

package/docs/configuration.md

@@ -10,6 +10,8 @@ This page is the reference for reviewer models, usage limits, repository policy,
 - [Project context](#project-context)
 - [Files Sphinx never reads](#files-sphinx-never-reads)
 - [Background preparation](#background-preparation)
+- [GitHub commit status and pull requests](#github-commit-status-and-pull-requests)
+- [Browser or terminal](#browser-or-terminal)
 
 ## Settings locations
 
@@ -180,6 +182,7 @@ Call caps bound requests and byte limits bound evidence. Neither is a dollar or
 | `distance` | `high` (default): questions about what the change does and affects; `low`: questions about its specific logic, conditions, and edge cases |
 | `exclude` | Extra ignore patterns, added to machine-wide ones |
 | `backgroundPreparation` | `false` opts this repository out |
+| `github` | GitHub stamps; see [below](#github-commit-status-and-pull-requests) |
 
 Branch defaults come from machine-wide settings (initially `main` and `master`), not from the branch you happen to have checked out. Without prompts:
 
@@ -193,6 +196,8 @@ If both `.sphinxconfig` and legacy `.sphinx.json` exist, `.sphinxconfig` wins an
 
 **Manual push checks.** `sphinx check --remote origin --branch main` selects the destination; otherwise Sphinx uses the upstream. Multiple destination refs are assessed separately. Tag-only pushes and deletions do not trigger checks in v0.1.
 
+**Pull request branches.** Set `"branches": ["*"]` to check pushes to every branch. The first push of a new branch is checked from where it left the remote's default branch (the same range the pull request shows), using local remote-tracking refs; later pushes check only the new commits.
+
 ## Project context
 
 `.sphinxcontext.md` describes what the project does, who uses it, important workflows, and architecture boundaries. It is included in every reviewer, compaction, and grading request.
@@ -241,3 +246,35 @@ After commits, merges, rewrites, and checkouts, Sphinx schedules a detached revi
 - Set `backgroundPreparation: false` in `config.json` or `.sphinxconfig` to opt out. A repository cannot re-enable preparation disabled machine-wide.
 - While yolo is on, preparation is paused: no new model request starts, although one already in progress may finish.
 - A first push, a branch without local tracking history, or a push to an unexpected destination needs a cold review at push time. Pre-commit checks always review on demand. Run `git fetch` if remote history is missing.
+
+## GitHub commit status and pull requests
+
+When you push to GitHub and a check passes, Sphinx marks the pushed commit with a `sphinx/understanding` commit status, for example "Understood: 3 questions, 2 first try". It shows next to the commit and in the pull request's checks. A skipped check is marked as a failure ("Understanding check skipped"). Yolo pushes and commit checkpoints are not marked.
+
+```json
+{ "github": { "status": true, "comment": false, "answers": false } }
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `status` | `true` | Post the commit status |
+| `comment` | `false` | Keep one comment on the branch's open pull request listing every check on that branch: questions, first-try results, and the model. It is edited in place on later pushes |
+| `answers` | `false` | Also include your answers in that comment |
+
+Set these in `config.json` for yourself or in `.sphinxconfig` for a repository. Private answer keys are never posted.
+
+It uses the [GitHub CLI](https://cli.github.com) and its existing login, in a detached process after Git continues, so it never slows or blocks a push. If `gh` is missing or not signed in, the remote isn't GitHub, or any request fails, nothing is posted and nothing else changes. The worker waits a few minutes for the push to land and up to 15 minutes for a pull request to be opened; the result of the last run is in `github/last.json` in Sphinx's data directory.
+
+**Requiring it for a team.** In the repository's branch protection or ruleset, add `sphinx/understanding` as a required status check. Pull requests whose head commit was not pushed through a passing check then cannot merge. The status is self-reported by the pusher's machine: it shows the check happened, but it is not a cryptographic proof, and anyone with write access can set a commit status.
+
+## Browser or terminal
+
+`interface` in `config.json` chooses where a push's questions appear. Set it with `sphinx config --interface <auto|browser|terminal>`.
+
+| Value | Behavior |
+| --- | --- |
+| `auto` (default) | The browser on a local Mac, where Sphinx can open it in the background. Elsewhere (SSH, Linux, WSL), inline in the terminal you ran Git from |
+| `terminal` | Always the terminal |
+| `browser` | Always the browser (on Linux and over SSH, open the printed local URL) |
+
+Inline questions need a terminal a person is looking at. When Git runs from a coding agent's shell there isn't one, so Sphinx opens a terminal window on a desktop instead, and falls back to the browser when it can't do either. `interface` is a personal setting; it can't be set in `.sphinxconfig` and doesn't change what a check asks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphinx-understand",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "You can outsource your thinking, but not your understanding. A comprehension checkpoint for agent-assisted development.",
   "homepage": "https://github.com/parthh01/sphinx#readme",
   "repository": {

package/src/browser-interview.js

@@ -13,6 +13,7 @@ import { browserPage } from './browser-page.js';
 import { recordOverride } from './overrides.js';
 import { withTextStream, partialField } from './stream.js';
 import { loadChangeView } from './change-view.js';
+import { updateStatus, updatePlan, scheduleUpdate } from './update.js';
 
 const ID = /^[a-f0-9]{64}$/u;
 const cancelled = () => Object.assign(new Error('Check paused. Progress is saved.'), { code: 'SPHINX_CANCELLED' });
@@ -54,7 +55,7 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
   store: providedStore, readConfig = loadConfig, revalidate = revalidateSnapshot,
   reserve = claimCheckpointDialog, release = finishCheckpointDialog, waitForExisting = waitForCheckpointTerminal,
   openBrowser = openQuestionnaireBrowser, output = line => process.stderr.write(`${line}\n`), logOverride = recordOverride, findPlans = planProviders,
-  loadView = loadChangeView,
+  loadView = loadChangeView, checkUpdate = updateStatus, planUpdate = updatePlan, startUpdate = scheduleUpdate,
 } = {}) {
   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;
@@ -65,6 +66,8 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
   // 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, score = null;
+  // The installed version and whether npm has a newer one. Display only.
+  let update = null;
   // The repository's understanding score, refreshed after every graded answer.
   const refreshScore = async (repoRoot, operationEnv) => { score = scoreSummary(await readStats(repoRoot, operationEnv)); };
   // Read-only display of the checkpoint's frozen comparison. It is loaded
@@ -94,7 +97,7 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
   // Display-only updates (change view, evidence) keep the revision, so they
   // never turn an answer already in flight into a stale submission.
   const publish = (next, { display = false } = {}) => {
-    state = { ...next, messages: transcript, ...(score ? { score } : {}), change: viewState(), evidence: evidence && evidence.checkpoint === next.id ? { questionId: evidence.questionId, refs: evidence.refs } : undefined, waitingGit, operationClosed: closed, revision: display ? next.revision : randomUUID(), sequence: ++sequence };
+    state = { ...next, messages: transcript, ...(score ? { score } : {}), ...(update ? { update } : {}), change: viewState(), evidence: evidence && evidence.checkpoint === next.id ? { questionId: evidence.questionId, refs: evidence.refs } : undefined, waitingGit, operationClosed: closed, revision: display ? next.revision : randomUUID(), sequence: ++sequence };
     const event = `data: ${JSON.stringify(state)}\n\n`;
     for (const stream of streams) writeEvent(stream, event);
   };
@@ -141,6 +144,15 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
     }
     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.' });
+    if (new URL(req.url, origin).searchParams.get('update') === '1') {
+      // Independent of the check: the install runs only after this process exits.
+      if (!update?.available || update.status === 'scheduled') return send(res, 409, { error: 'No update to install.' });
+      const plan = await planUpdate().catch(() => null);
+      const started = !!plan?.command && await startUpdate({ command: plan.command, env });
+      update = { ...update, status: started ? 'scheduled' : 'failed' };
+      publish(state, { display: true });
+      return send(res, 200, { update });
+    }
     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); }
@@ -184,6 +196,7 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
     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}`;
+    Promise.resolve().then(() => checkUpdate({ env: operationEnv })).then(result => { update = result; publish(state, { display: true }); }).catch(() => {});
     output(`Sphinx questionnaire: ${url}`);
     if (!opened) {
       opened = true;

package/src/browser-page.js

@@ -1,4 +1,5 @@
 import { sphinxMark } from './logo.js';
+import { VERSION } from './version.js';
 /** Static UI only. Model-authored content always enters the DOM as textContent. */
 export function browserPage({ token, nonce }) {
   return `<!doctype html>
@@ -11,6 +12,7 @@ button:focus-visible,textarea:focus-visible,input:focus-visible,[tabindex]:focus
 .shell{height:100vh;height:100dvh;display:flex;flex-direction:column}
 header{min-height:52px;border-bottom:1px solid var(--line);padding:8px 24px;display:flex;align-items:center;justify-content:space-between;gap:16px}
 .brand{display:flex;align-items:center;gap:14px}.brand strong{display:flex;align-items:center;gap:9px;font:600 19px ui-monospace,SFMono-Regular,Menlo,monospace}.brand svg{color:var(--amber);flex-shrink:0}.brand span{color:var(--muted);font-size:14px}
+.brand small{font:12px var(--mono);color:var(--muted);margin-left:-8px}.update{font-size:12px;padding:2px 10px;border:1px solid var(--line);border-radius:999px;background:transparent;color:var(--amber);cursor:pointer;white-space:nowrap}.update:hover:not(:disabled){border-color:var(--amber)}.update:disabled{color:var(--muted);cursor:default}
 .scope{border-bottom:1px solid var(--line);padding:7px 24px;font-size:13px;line-height:1.45;color:var(--muted)}
 .facts dt{display:none}.facts dd{font-weight:400!important}.facts div:has(#scope-range){display:none}.facts div+div::before{content:"·";margin-right:8px;color:#b7ab9c}.facts #meta{color:var(--ink);font-weight:600!important}.scope-note{display:none!important}
 .facts{display:flex;flex-wrap:wrap;gap:2px 20px;margin:0;align-items:baseline}.facts div{display:flex;gap:6px;min-width:0}.facts dt{color:var(--muted)}.facts dd{margin:0;font-weight:600;overflow-wrap:anywhere;font-variant-numeric:tabular-nums}
@@ -90,7 +92,7 @@ footer{flex-shrink:0;display:flex;flex-wrap:wrap;gap:2px 8px;padding:0 0 14px;co
 #question-pane{overflow-y:auto}.conversation{flex:none;overflow:visible;padding-right:0}.evidence{max-height:none;overflow:visible}}
 @media(max-width:600px){header{padding:8px 12px}.brand{gap:8px}.brand span{display:none}.scope{padding:6px 12px 7px;font-size:12.5px}.facts{gap:0 12px}.facts .mono{font-size:12px}#scope-note{display:none}.scope-short{display:block}.hint,footer{font-size:11.5px}main{padding:0 14px}.conversation{padding-top:16px}.turn.human{margin-left:16px}.actions{gap:4px}button{padding:7px 10px}.hint{max-width:34em}.diffhead{padding:8px 12px}.legend{padding:6px 12px}}
 </style></head><body><div class="shell">
-<header><div class="brand"><strong>${sphinxMark({ size: 26, id: 'brand-mark' })}sphinx</strong><span>Understanding check</span></div><div id="score" class="score" hidden><span class="score-head"><span class="score-label">Your understanding</span><strong id="score-value" class="score-value"></strong></span><span id="score-dots" class="score-dots" role="img"></span><span id="score-meta" class="score-meta"></span></div><div class="tools"><button id="skip" class="quiet" type="button">Skip this time</button><button id="pause" class="quiet" type="button">Pause check</button></div></header>
+<header><div class="brand"><strong>${sphinxMark({ size: 26, id: 'brand-mark' })}sphinx</strong><small id="version">v${VERSION}</small><button id="update" class="update" type="button" hidden></button><span>Understanding check</span></div><div id="score" class="score" hidden><span class="score-head"><span class="score-label">Your understanding</span><strong id="score-value" class="score-value"></strong></span><span id="score-dots" class="score-dots" role="img"></span><span id="score-meta" class="score-meta"></span></div><div class="tools"><button id="skip" class="quiet" type="button">Skip this time</button><button id="pause" class="quiet" type="button">Pause check</button></div></header>
 <section class="scope" aria-label="Change under review"><dl class="facts"><div><dt>Repository</dt><dd id="meta"></dd></div><div><dt id="scope-op-label">Operation</dt><dd id="scope-op">Loading…</dd></div><div><dt>Comparison</dt><dd id="scope-range" class="mono">Loading…</dd></div><div><dt>Changed</dt><dd id="scope-stats">Loading…</dd></div><div id="scope-excluded-row" hidden><dt>Excluded</dt><dd id="scope-excluded"></dd></div><div><dt>Progress</dt><dd id="scope-progress">Connecting…</dd></div><div><dd id="usage"></dd></div></dl>
 <p id="scope-note" class="scope-note">Checkpoint changes: the exact range Sphinx froze for this check, not necessarily an entire pull request.</p><p class="scope-note scope-short">Checkpoint range only — not necessarily a whole pull request.</p></section>
 <nav class="tabs" role="tablist" aria-label="Questionnaire views"><button id="tab-question" role="tab" type="button" aria-controls="question-pane" aria-selected="true">Question</button><button id="tab-files" role="tab" type="button" aria-controls="files-pane" aria-selected="false">Files</button><button id="tab-diff" role="tab" type="button" aria-controls="diff-pane" aria-selected="false">Diff</button></nav>
@@ -147,6 +149,14 @@ function scoreView(sc){
  const meta=[];if(sc.streak>1)meta.push(sc.streak+' in a row');if(sc.skipRate!=null)meta.push('skipped '+sc.skipRate+'%');
  $('score-meta').textContent=meta.join(' · ');lastScored=sc.answered;
 }
+// A newer release is offered quietly; installing waits until this check ends.
+function updateView(u){const b=$('update');if(!u?.available){b.hidden=true;return;}b.hidden=false;
+ if(u.status==='scheduled'){b.textContent='Updating to v'+u.latest+' after this check';b.disabled=true;b.title='';}
+ else if(u.status==='failed'){b.textContent='Update could not start';b.disabled=true;b.title='Run '+(u.command||'npm install -g sphinx-understand@latest')+' in a terminal.';}
+ else if(!u.command){b.textContent='v'+u.latest+' available';b.disabled=true;b.title=u.note||'';}
+ else{b.textContent='v'+u.latest+' available · Update';b.disabled=false;b.title='Runs '+u.command+' once this check finishes. Your settings are kept.';}}
+$('update').onclick=async()=>{const b=$('update');b.disabled=true;b.textContent='Scheduling update…';
+ try{const res=await fetch(base+'/action?update=1',{method:'POST',headers:{'Content-Type':'application/json','X-Sphinx-Token':token},body:'{}'});const data=await res.json();updateView(data.update||{available:true,status:'failed'});}catch{updateView({available:true,status:'failed'});}};
 const resize=()=>{$('response').style.height='auto';$('response').style.height=Math.min($('response').scrollHeight||76,180)+'px';};
 function controls(){
  if(!current)return;
@@ -196,7 +206,7 @@ function render(state){
  const previous=current;current=state;finished=state.operationClosed||['passed','paused','error','skipped'].includes(state.phase);
  const repo=state.repoRoot?.split(/[\\\\/]/).filter(Boolean).at(-1),branch=state.target?.replace(/^refs\\/heads\\//,'');
  text('meta',repo||state.change?.header?.repository||'');$('meta').title=state.repoRoot||'';
- text('usage',[routeText(state.route),usageText(state.usage,state.tokens)].filter(Boolean).join(' · '));scoreView(state.score);const messages=state.messages||[];
+ text('usage',[routeText(state.route),usageText(state.usage,state.tokens)].filter(Boolean).join(' · '));scoreView(state.score);updateView(state.update);const messages=state.messages||[];
  text('waiting',finished?'':state.waitingGit?'Git continues after you pass. Closing this tab leaves it waiting; Pause check stops it.':'Closing this tab leaves the check waiting. Use Pause check to stop.');
  const label=state.phase==='question'?'Question '+(state.progress.completed+1)+' of '+state.progress.total:state.phase==='working'?'Reviewing…':state.phase==='recovery'?'Review needs your decision':state.phase==='passed'?'Passed':state.phase==='paused'?'Paused':state.phase==='skipped'?'Skipped':state.phase==='error'?'Check stopped':'Waiting…';
  const retry=state.phase==='question'&&[...messages].reverse().find(item=>item.kind==='question')?.followUp;

package/src/cli.js

@@ -17,7 +17,6 @@ import { activateIntegrations } from './activation.js';
 import { checkbox } from './checkbox.js';
 import { agentHook } from './agent.js';
 import { createSessionStore } from './sessions.js';
-import { prepareInteractiveCheck } from './check-recovery.js';
 import { parseRoute } from './routing.js';
 import { createTerminal, withProgress } from './terminal.js';
 import { HELP, printHelp } from './help.js';
@@ -26,7 +25,8 @@ import { runGitGate } from './git-gate.js';
 import { loadProjectContext } from './repo-context.js';
 import { REVIEWER_PRESETS, presetOptions } from './model-presets.js';
 import { modelUsageText, modelLimitText, readUsage, summarizeUsage, printUsage, usageDir } from './usage.js';
-import { toggleYolo, yoloStatus, recentOverrides } from './overrides.js';
+import { toggleYolo, yoloStatus, recentOverrides, recordOverride } from './overrides.js';
+import { runTerminalCheck } from './terminal-check.js';
 
 const CLI_PATH = fileURLToPath(new URL('../bin/sphinx.js', import.meta.url));
 const POLICY_FLAGS = ['branches', 'events', 'level', 'distance', 'remotes'];
@@ -37,7 +37,7 @@ const OPTIONS = {
   init: ['yes', 'json', 'context', 'suggest', 'apply', ...POLICY_FLAGS], check: ['json', 'id', 'remote', 'branch', 'staged', 'retry-review'],
   prepare: ['json', 'worker', 'retry'],
   answer: ['json', 'text'], explain: ['json'], dispute: ['json', 'text'], pending: ['json'],
-  status: ['json'], config: ['json', 'distance', ...MODEL_FLAGS], doctor: ['json'], auth: ['provider', 'base-url'], uninstall: ['repo'],
+  status: ['json'], config: ['json', 'distance', 'interface', ...MODEL_FLAGS], doctor: ['json'], auth: ['provider', 'base-url'], uninstall: ['repo'],
   mcp: [], yolo: ['json', 'reason'], usage: ['json'],
 };
 const json = value => console.log(JSON.stringify(value, null, 2));
@@ -135,7 +135,7 @@ export function applyInstallOptions(current, values) {
   }
   if (values['max-model-calls'] !== undefined) config.maxModelCalls = parseModelCalls(values['max-model-calls']);
   if (values['max-output-tokens'] !== undefined) config.maxOutputTokens = parseOutputTokens(values['max-output-tokens']);
-  for (const key of ['provider', 'model', 'level', 'distance', 'mode']) if (values[key] !== undefined) config[key] = values[key];
+  for (const key of ['provider', 'model', 'level', 'distance', 'interface', 'mode']) if (values[key] !== undefined) config[key] = values[key];
   for (const key of ['branches', 'events', 'remotes']) if (values[key] !== undefined) config[key] = splitList(values[key]);
   if (values.provider !== undefined || values.model !== undefined) {
     if (values.provider !== undefined && values.model === undefined) {
@@ -399,9 +399,10 @@ async function checkCommand(values) {
     if (values['retry-review']) await store.retryReview(session.id, config);
     json(await start()); return 0;
   }
-  const terminal = ui(); terminal.section('Understanding check'); terminal.paragraph('This is open-book. Inspect the code when useful; explain the behavior in your own words.');
   const controller = new AbortController(), { signal } = controller;
+  const waitingGit = process.env.SPHINX_WAITING_GIT === '1';
   return withReadline(async ask => {
+    const terminal = ui();
     if (values['retry-review']) {
       await store.retryReview(session.id, config, { signal });
       signal.throwIfAborted();
@@ -409,29 +410,17 @@ async function checkCommand(values) {
         ? 'Resuming the review with no model-call limit. Previous usage remains counted.'
         : `Starting a new review attempt with up to ${config.maxModelCalls} additional model calls, including grading. Previous usage remains counted.`);
     }
-    let state = await prepareInteractiveCheck({
-      start: () => start(signal), inspect: async () => store.public(await store.read(session.id)),
-      authorizeMore: () => store.retryReview(session.id, config, { signal }),
-      validate: () => validateCheckpoint(session.snapshot, config), config,
-      choose: createPrompts({ ask, ui: terminal }).choose, ui: terminal,
-      waitingGit: process.env.SPHINX_WAITING_GIT === '1', signal,
+    return runTerminalCheck({
+      store, session: await store.read(session.id), config, ask, terminal, signal, waitingGit,
+      choose: createPrompts({ ask, ui: terminal }).choose,
+      validate: () => validateCheckpoint(session.snapshot, config),
       planProviders: await planProviders().catch(() => []),
-      switchRoute: provider => store.switchRoute(session.id, config, provider, { signal }),
+      // A skip lets the waiting Git operation through; it is logged like the browser's.
+      skip: async reason => {
+        await store.skip(session.id);
+        await recordOverride({ kind: 'skip', repoRoot: repo.root, target: session.snapshot.target.ref, id: session.id, reason });
+      },
     });
-    signal.throwIfAborted();
-    if (!state) return 1;
-    while (state.status !== 'passed') {
-      printSession(state, terminal);
-      const answer = (await ask('\nYour answer: ')).trim();
-      if (answer === '/quit') { terminal.note('Progress saved. Run sphinx check when you are ready to continue.'); return 1; }
-      if (!answer) continue;
-      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 /learn, /dispute <reason>, or /quit; otherwise enter your answer.'); continue; }
-      state = await withProgress(learn ? 'Preparing an explanation and new scenario' : dispute ? 'Reviewing the question' : 'Checking your reasoning', () => store.answer(session.id, learn ? 'I do not know. Explain this concept and give me a different scenario to apply it to.' : dispute ? answer.slice(9) : answer, config, { dispute, learn, expectedQuestionId: state.question.id, signal }));
-      signal.throwIfAborted();
-    }
-    signal.throwIfAborted(); printSession(state, terminal); return 0;
   }, { controller });
 }
 
@@ -475,7 +464,7 @@ async function statusCommand(command, values) {
 export function parseCommandLine(argv) {
   const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
     help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' }, json: { type: 'boolean' }, yes: { type: 'boolean' }, repo: { type: 'boolean' }, staged: { type: 'boolean' },
-    preset: { type: 'string' }, provider: { type: 'string' }, model: { type: 'string' }, small: { type: 'string' }, medium: { type: 'string' }, large: { type: 'string' }, level: { type: 'string' }, distance: { type: 'string' }, branches: { type: 'string' }, events: { type: 'string' }, agents: { type: 'string' }, remotes: { type: 'string' },
+    preset: { type: 'string' }, provider: { type: 'string' }, model: { type: 'string' }, small: { type: 'string' }, medium: { type: 'string' }, large: { type: 'string' }, level: { type: 'string' }, distance: { type: 'string' }, interface: { type: 'string' }, branches: { type: 'string' }, events: { type: 'string' }, agents: { type: 'string' }, remotes: { type: 'string' },
     remote: { type: 'string' }, branch: { type: 'string' }, id: { type: 'string' }, text: { type: 'string' }, 'allow-paid': { type: 'boolean' },
     context: { type: 'string' }, suggest: { type: 'boolean' }, apply: { type: 'string' }, worker: { type: 'boolean' }, retry: { type: 'boolean' }, reason: { type: 'string' }, 'base-url': { type: 'string' }, 'cli-billing': { type: 'string' },
     launch: { type: 'boolean' }, 'no-launch': { type: 'boolean' }, 'retry-review': { type: 'boolean' }, 'max-model-calls': { type: 'string' }, 'max-output-tokens': { type: 'string' },
@@ -548,13 +537,14 @@ export async function main(argv) {
     return result.checks.every(check => check.ok) ? 0 : 1;
   }
   if (command === 'config') {
-    if ([...MODEL_FLAGS, 'distance'].some(key => values[key] !== undefined)) {
+    if ([...MODEL_FLAGS, 'distance', 'interface'].some(key => values[key] !== undefined)) {
       const current = await loadConfig(), previousMaxModelCalls = current.maxModelCalls;
       const config = applyInstallOptions(current, values), maxModelCalls = config.maxModelCalls;
       await saveConfig(config);
       const result = { scope: 'global', path: getPaths().config, previousMaxModelCalls, maxModelCalls, config };
       if (values.json) { json(result); return 0; }
       const terminal = ui();
+      if (values.interface !== undefined) terminal.success(`Questions appear ${config.interface === 'terminal' ? 'in the terminal (the browser is the fallback)' : config.interface === 'browser' ? 'in the browser' : 'in the browser on a local Mac, otherwise in the terminal'}.`);
       if (values['max-model-calls'] !== undefined) terminal.success(`Saved machine-wide limit: ${modelLimitText(maxModelCalls)} (previously ${modelLimitText(previousMaxModelCalls)}).`);
       if (values['max-output-tokens'] !== undefined) terminal.success(`Saved output allowance: ${config.maxOutputTokens} tokens per request, including model reasoning. Model calls: ${modelLimitText(maxModelCalls)}.`);
       if (MODEL_FLAGS.some(key => !['max-model-calls', 'max-output-tokens'].includes(key) && values[key] !== undefined)) {

package/src/config.js

@@ -9,12 +9,14 @@ export const PROVIDERS = Object.freeze(['openrouter', 'codex', 'claude', 'openai
 
 export const DEFAULT_CONFIG = {
   version: 1, enabled: true, provider: 'openrouter', model: 'openrouter/free',
-  level: 'standard', distance: 'high', mode: 'block', events: ['pre-push'],
+  level: 'standard', distance: 'high', mode: 'block', interface: 'auto', events: ['pre-push'],
   branches: ['main', 'master'], remotes: ['*'], exclude: [],
   maxContextBytes: 100000, timeoutSeconds: 180, receiptHours: 24,
   maxModelCalls: null, maxOutputTokens: 4096, allowPaid: false, cliBilling: 'plan',
   agentMaxTurns: null, toolResultBytes: 16000,
   backgroundPreparation: true, preparationDebounceMs: 1500, workingContext: true,
+  // GitHub stamps never affect a check; see src/github.js.
+  github: { status: true, comment: false, answers: false },
   models: {
     small: { provider: 'openrouter', model: 'openrouter/free' },
     medium: { provider: 'openrouter', model: 'openrouter/free' },
@@ -73,7 +75,7 @@ export function validateConfig(config) {
   for (const key of Object.keys(config)) if (!allowed.has(key)) fail(`unknown setting ${key}`);
   if (config.version !== 1) fail('version must be 1');
   for (const key of ['enabled', 'allowPaid', 'backgroundPreparation', 'workingContext']) if (typeof config[key] !== 'boolean') fail(`${key} must be boolean`);
-  for (const [key, values] of Object.entries({ provider: PROVIDERS, level: ['relaxed','standard','thorough'], distance: ['high','low'], mode: ['block'], cliBilling: ['plan','api'] })) {
+  for (const [key, values] of Object.entries({ provider: PROVIDERS, level: ['relaxed','standard','thorough'], distance: ['high','low'], interface: ['auto','browser','terminal'], mode: ['block'], cliBilling: ['plan','api'] })) {
     if (key === 'mode' && config.mode === 'advisory') fail('mode "advisory" was removed. Remove mode from your configuration; use sphinx yolo to bypass checks when urgent');
     if (!values.includes(config[key])) fail(`${key} must be ${values.join(', ')}`);
   }
@@ -96,6 +98,8 @@ export function validateConfig(config) {
     if (Object.keys(route).some(k => !['provider','model'].includes(k))) fail(`unexpected field in models.${tier}`);
   }
   if (Object.keys(config.models).some(k => !['small','medium','large'].includes(k))) fail('unknown model tier');
+  if (!config.github || typeof config.github !== 'object' || Array.isArray(config.github)) fail('github must be an object');
+  for (const key of Object.keys(config.github)) if (!Object.hasOwn(DEFAULT_CONFIG.github, key) || typeof config.github[key] !== 'boolean') fail(`github.${key} must be one of status, comment, answers set to true or false`);
   if (!config.routing || typeof config.routing !== 'object') fail('routing is required');
   for (const key of Object.keys(config.routing)) if (!Object.hasOwn(DEFAULT_CONFIG.routing,key)) fail(`unknown routing setting ${key}`);
   for (const k of ['smallMaxLines','smallMaxFiles','largeMinLines','largeMinFiles']) {
@@ -107,10 +111,10 @@ export function validateConfig(config) {
 }
 
 function merged(base, overrides) {
-  return { ...base, ...overrides, models: { ...base.models, ...overrides?.models }, routing: { ...base.routing, ...overrides?.routing } };
+  return { ...base, ...overrides, models: { ...base.models, ...overrides?.models }, routing: { ...base.routing, ...overrides?.routing }, github: { ...base.github, ...overrides?.github } };
 }
 
-export const REPOSITORY_CONFIG_KEYS = Object.freeze(['version','enabled','level','distance','mode','events','branches','remotes','exclude','backgroundPreparation']);
+export const REPOSITORY_CONFIG_KEYS = Object.freeze(['version','enabled','level','distance','mode','events','branches','remotes','exclude','backgroundPreparation','github']);
 
 export function validateRepositoryConfig(local, { env = process.env, source = '.sphinxconfig' } = {}) {
   if (!local || typeof local !== 'object' || Array.isArray(local)
@@ -122,7 +126,7 @@ export function validateRepositoryConfig(local, { env = process.env, source = '.
       throw new Error(`Repository ${source} cannot set ${key}; configure model routes and budgets in ${getPaths(env).config}.`);
     }
   }
-  validateConfig({ ...structuredClone(DEFAULT_CONFIG), ...local });
+  validateConfig(merged(structuredClone(DEFAULT_CONFIG), local));
   return local;
 }
 
@@ -176,7 +180,8 @@ export function stableStringify(value) {
   if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
   return JSON.stringify(value);
 }
-export function policyHash(config) {
+export function policyHash({ github, interface: _interface, ...config }) {
+  // GitHub stamps and where the questions appear are not part of the check.
   // The call ceiling controls spending, not what the human must understand.
   // Normalize it independently of DEFAULT_CONFIG so allowance edits preserve
   // checkpoint identity within the same assessment contract.

package/src/git-gate.js

@@ -7,6 +7,8 @@ import { createBrowserInterview } from './browser-interview.js';
 import { yoloStatus, recordOverride } from './overrides.js';
 import { dropContext } from './working-context.js';
 import { collectGarbage } from './storage.js';
+import { scheduleStamp } from './github.js';
+import { prefersTerminal, runGitTerminalCheck } from './git-interview.js';
 
 async function snapshotsFor({ event, args, input, cwd, config, env }) {
   if (event === 'pre-push') return pushSnapshots({ cwd, remote: args[0], remoteUrl: args[1], input, config, env });
@@ -29,7 +31,7 @@ export async function runGitGate({ event, args = [], input = '', cwd = process.c
   store: providedStore, readConfig = loadConfig, snapshotsFor: collectSnapshots = snapshotsFor,
   revalidate = revalidateSnapshot, present, readYolo = yoloStatus, logOverride = recordOverride,
   queue = queuePresentation, claim = claimPresentation, listRequests = listPresentations,
-  output = line => process.stderr.write(`${line}\n`),
+  output = line => process.stderr.write(`${line}\n`), stamp = scheduleStamp, askInTerminal = runGitTerminalCheck,
 } = {}) {
   if (env.SPHINX_EVALUATOR === '1') return 0;
   signal?.throwIfAborted();
@@ -85,7 +87,9 @@ export async function runGitGate({ event, args = [], input = '', cwd = process.c
     const interviewEnv = interviewEnvironment(cwd, env);
     for (let index = 0; index < requests.length; index++) {
       signal?.throwIfAborted();
-      const result = await (present || browser.present)({ request: requests[index], env: interviewEnv, signal });
+      // Headless sessions (or interface: terminal) ask in the terminal first; the browser is the fallback.
+      let result = !present && prefersTerminal(config, { env }) ? await askInTerminal({ request: requests[index], env: interviewEnv, signal, cwd }) : null;
+      if (!result || result.status === 'unavailable') result = await (present || browser.present)({ request: requests[index], env: interviewEnv, signal });
       signal?.throwIfAborted();
       if (result?.status === 'unavailable') {
         // Native callbacks only run after Git exits. Keep that explicit fallback
@@ -117,6 +121,13 @@ export async function runGitGate({ event, args = [], input = '', cwd = process.c
     signal?.throwIfAborted();
     // Skipped checks already reported themselves; only a pass is a completed check.
     if (requests.length > skipped.size) output('Sphinx: understanding check complete. Continuing this Git operation.');
+    // GitHub stamps run detached after Git continues; they can never fail this push.
+    for (const snapshot of snapshots) {
+      try {
+        const session = await Promise.resolve(store.read?.(snapshot.id)).catch(() => null);
+        await stamp({ snapshot, session, outcome: skipped.has(snapshot.id) ? 'skipped' : 'passed', config, env });
+      } catch { /* Best-effort only. */ }
+    }
     await finished();
     return 0;
   } finally {

package/src/git-interview.js

@@ -1,5 +1,7 @@
 import { setTimeout as delay } from 'node:timers/promises';
-import { launchCheckpointTerminal, waitForCheckpointTerminal } from './terminal-launch.js';
+import { spawn } from 'node:child_process';
+import { openSync, closeSync } from 'node:fs';
+import { CLI, launchCheckpointTerminal, waitForCheckpointTerminal } from './terminal-launch.js';
 
 /** Collect human input in a separate terminal while the original Git hook waits.
  * The caller owns queue cleanup and must validate the receipt before returning 0.
@@ -38,7 +40,7 @@ export async function runGitCheckpointTerminal({ request, env = process.env, sig
       controller.signal.throwIfAborted();
       const status = await waitForResult({ id: request.id, env, timeoutMs: Math.max(1, deadline - Date.now()), signal: controller.signal });
       controller.signal.throwIfAborted();
-      return result(['passed', 'pending', 'unavailable', 'interrupted'].includes(status) ? status : 'interrupted');
+      return result(['passed', 'skipped', 'pending', 'unavailable', 'interrupted'].includes(status) ? status : 'interrupted');
     } catch { return stopped ? result('pending', stopped) : result('interrupted'); }
   };
   try { return await Promise.race([operation(), interrupted]); }
@@ -49,3 +51,40 @@ export async function runGitCheckpointTerminal({ request, env = process.env, sig
     controller.abort();
   }
 }
+
+/** Whether to ask in the terminal instead of the browser. `auto` uses the
+ * browser only where Sphinx can open it in the background (local macOS). */
+export function prefersTerminal(config, { env = process.env, platform = process.platform } = {}) {
+  if (config.interface === 'terminal') return true;
+  if (config.interface === 'browser') return false;
+  return !!(env.SSH_CONNECTION || env.SSH_TTY) || platform !== 'darwin';
+}
+
+// The terminal Git was run from, if a person is looking at it. A coding
+// agent's shell has no visible terminal, so its pipes never qualify.
+function openVisibleTerminal(stderr = process.stderr) {
+  if (!stderr.isTTY) return null;
+  try { return openSync('/dev/tty', 'r+'); } catch { return null; }
+}
+
+/**
+ * Ask in the terminal: inline in Git's own terminal when a person is there,
+ * otherwise in a new terminal window. Resolves { status: 'unavailable' } when
+ * neither is possible, so the caller can fall back to the browser.
+ */
+export async function runGitTerminalCheck({ request, env = process.env, signal, cwd = process.cwd(), openTty = openVisibleTerminal, spawnImpl = spawn, openWindow = runGitCheckpointTerminal } = {}) {
+  const tty = openTty();
+  if (tty === null) return openWindow({ request, env, signal });
+  try {
+    const code = await new Promise(resolve => {
+      let child;
+      try { child = spawnImpl(process.execPath, [CLI, 'check', '--id', request.id], { cwd, env: { ...env, SPHINX_WAITING_GIT: '1' }, stdio: [tty, tty, tty] }); }
+      catch { resolve(null); return; }
+      const onAbort = () => child.kill('SIGINT');
+      signal?.addEventListener('abort', onAbort, { once: true });
+      child.once('error', () => resolve(null));
+      child.once('exit', exit => { signal?.removeEventListener('abort', onAbort); resolve(exit); });
+    });
+    return { id: request.id, status: code === 0 ? 'passed' : code === 3 ? 'skipped' : code === null ? 'unavailable' : 'pending' };
+  } finally { try { closeSync(tty); } catch { /* Already closed. */ } }
+}

package/src/git.js

@@ -191,6 +191,22 @@ export async function revalidateSnapshot(snapshot, config, { env = process.env }
   return true;
 }
 
+// A new branch is checked from where it left the remote's default branch, the
+// same range a pull request shows, instead of from an empty tree. That only
+// holds when the policy also checks the default branch; otherwise code that
+// reached it unchecked would be skipped, so the whole tree is assessed.
+async function branchPoint(root, remote, head, config) {
+  if (!remote || remote === '.' || !/^[\w.-]+$/.test(remote)) return null;
+  const named = (await git(root, ['symbolic-ref', '--quiet', `refs/remotes/${remote}/HEAD`], { allowFailure: true }))?.trim();
+  for (const ref of [named, `refs/remotes/${remote}/main`, `refs/remotes/${remote}/master`].filter(Boolean)) {
+    if (!(await git(root, ['rev-parse', '--verify', '--quiet', ref], { allowFailure: true }))) continue;
+    if (!triggered(config, 'pre-push', ref.slice(`refs/remotes/${remote}/`.length), remote)) return null;
+    const base = (await git(root, ['merge-base', head, ref], { allowFailure: true }))?.trim();
+    if (base && OID.test(base)) return base; // Equal to head: nothing new to check.
+  }
+  return null;
+}
+
 export async function pushSnapshots({ cwd = process.cwd(), remote, remoteUrl, input, config, env = process.env }) {
   if (!config.enabled || !config.events.includes('pre-push')) return [];
   const repo = await repository(cwd);
@@ -203,7 +219,7 @@ export async function pushSnapshots({ cwd = process.cwd(), remote, remoteUrl, in
     if (ZERO.test(head) || head === old || !ref.startsWith('refs/heads/')) continue;
     if (!triggered(config, 'pre-push', ref.slice('refs/heads/'.length), remote)) continue;
     await ensureCommit(repo.root, head, remote);
-    const base = ZERO.test(old) ? null : old;
+    const base = ZERO.test(old) ? await branchPoint(repo.root, remote, head, config) : old;
     if (base) await ensureCommit(repo.root, base, remote, true);
     const tree = (await git(repo.root, ['rev-parse', `${head}^{tree}`])).trim();
     const snapshot = await buildSnapshot({ repo, event: 'pre-push', target: { remote, url: remoteUrl || '', ref }, base, head, tree, sourceRef, config, env });

package/src/github-worker.js

@@ -0,0 +1,4 @@
+import { runStampWorker } from './github.js';
+
+// Detached from Git's hook so pushes never wait on GitHub.
+await runStampWorker(process.argv[2]);

package/src/github.js

@@ -0,0 +1,174 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getPaths, readJson, writeJson } from './config.js';
+
+// After Git continues, a detached worker marks the pushed commit on GitHub with
+// a `sphinx/understanding` commit status and, if the user opts in, keeps one
+// summary comment on the branch's open pull request. All of it is best-effort:
+// no GitHub remote, no gh CLI, no login, or any API error just means no stamp.
+export const STATUS_CONTEXT = 'sphinx/understanding';
+export const COMMENT_MARKER = '<!-- sphinx-understanding -->';
+const RECORDS_KEPT = 20;
+const WORKER = fileURLToPath(new URL('./github-worker.js', import.meta.url));
+const digest = value => createHash('sha256').update(value).digest('hex');
+const githubDirectory = env => path.join(getPaths(env).home, 'github');
+const branchFile = (repoRoot, ref, env) => path.join(githubDirectory(env), 'branches', `${digest(`${repoRoot}\0${ref}`)}.json`);
+
+/** owner/repo on a GitHub host from an https, ssh, or scp-style remote URL. */
+export function githubRepository(url) {
+  const match = /^(?:https?:\/\/(?:[^@/]+@)?|ssh:\/\/(?:[^@/]+@)?|[^@/\s]+@)([^/:\s]+)(?::\d+)?[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec(String(url || '').trim());
+  if (!match || !/(^|\.)github\.com$|^github\./.test(match[1])) return null;
+  return { host: match[1], owner: match[2], repo: match[3] };
+}
+
+/** What one check means for the stamp. Never includes private answer keys. */
+export function checkRecord({ session, snapshot, outcome, includeAnswers = false, at = new Date().toISOString() }) {
+  const questions = [];
+  const attempts = session?.attempts || [];
+  // Attempts carry their question slot from 0.1.8; older records only know the final prompts.
+  const tracked = attempts.length && attempts.every(item => Number.isInteger(item.index));
+  for (const [index, question] of (session?.questions || []).entries()) {
+    // Matches the understanding score: disputes and ambiguous grades don't count; asking for an explanation is a miss.
+    const graded = tracked ? attempts.filter(item => item.index === index && item.kind !== 'dispute' && item.verdict !== 'ambiguous') : [];
+    const first = attempts.find(item => tracked && item.index === index);
+    questions.push({
+      prompt: first?.prompt || question.prompt,
+      ...(tracked ? { tries: graded.length, firstTry: graded[0]?.kind === 'answer' && graded[0]?.verdict === 'correct' } : {}),
+      ...(includeAnswers && tracked ? { answers: attempts.filter(item => item.index === index).map(item => ({ kind: item.kind, prompt: item.prompt, answer: item.answer, verdict: item.verdict })) } : {}),
+    });
+  }
+  return {
+    at, outcome, head: snapshot.head, base: snapshot.base, ref: snapshot.target.ref,
+    stats: snapshot.stats, level: session?.config?.level ?? null, distance: session?.config?.distance ?? null,
+    model: session?.route ? [session.route.provider, session.route.model].filter(Boolean).join(' ') : null,
+    noQuestionReason: session?.noQuestionReason || null, questions,
+  };
+}
+
+export function statusFor(record) {
+  if (record.outcome === 'skipped') return { state: 'failure', description: 'Understanding check skipped' };
+  const asked = record.questions.length;
+  if (!asked) return { state: 'success', description: 'Passed without questions' };
+  const first = record.questions.filter(item => item.firstTry).length;
+  const known = record.questions.every(item => typeof item.firstTry === 'boolean');
+  return { state: 'success', description: `Understood: ${asked} question${asked === 1 ? '' : 's'}${known ? `, ${first} first try` : ''}` };
+}
+
+const quote = text => String(text).trim().split('\n').map(line => `> ${line}`).join('\n');
+const short = sha => String(sha || '').slice(0, 7);
+
+/** One PR comment covering every check recorded for the branch, newest first. */
+export function commentBody(records) {
+  const lines = [COMMENT_MARKER, '### Sphinx understanding checks', ''];
+  for (const record of [...records].reverse()) {
+    const status = statusFor(record);
+    const range = record.base ? `${short(record.base)}..${short(record.head)}` : short(record.head);
+    lines.push(`<details><summary>${status.state === 'success' ? '✅' : '⚠️'} <code>${range}</code> · ${status.description}${record.model ? ` · ${record.model}` : ''}</summary>`, '');
+    if (record.stats) lines.push(`${record.stats.files} files, +${record.stats.additions} −${record.stats.deletions}. Depth ${record.level}, distance ${record.distance}. ${record.at.slice(0, 16).replace('T', ' ')} UTC.`, '');
+    if (record.noQuestionReason) lines.push(`No questions: ${record.noQuestionReason}`, '');
+    for (const [index, question] of record.questions.entries()) {
+      const tries = typeof question.tries === 'number' ? ` _(${question.firstTry ? 'first try' : `${question.tries} tries`})_` : '';
+      lines.push(`**Q${index + 1}.**${tries}`, quote(question.prompt), '');
+      for (const item of question.answers || []) {
+        if (item.prompt && item.prompt !== question.prompt) lines.push(`Follow-up:`, quote(item.prompt), '');
+        lines.push(`${item.kind === 'answer' ? `Answer (${item.verdict})` : item.kind === 'dispute' ? 'Dispute' : 'Asked for an explanation'}:`, quote(item.answer || '(empty)'), '');
+      }
+    }
+    lines.push('</details>', '');
+  }
+  lines.push('<sub>Recorded by <a href="https://github.com/parthh01/sphinx">Sphinx</a> on the pusher\'s machine. Self-reported, not a cryptographic attestation.</sub>');
+  return lines.join('\n');
+}
+
+/**
+ * Record the check and hand GitHub work to a detached worker so Git never
+ * waits on the network. Never throws.
+ */
+export async function scheduleStamp({ snapshot, session, outcome, config, env = process.env, spawnImpl = spawn }) {
+  try {
+    const settings = config.github || {};
+    if (snapshot.event !== 'pre-push' || (!settings.status && !settings.comment)) return false;
+    const repo = githubRepository(snapshot.target.url);
+    if (!repo) return false;
+    const file = branchFile(snapshot.repoRoot, snapshot.target.ref, env);
+    const stored = await readJson(file, null).catch(() => null);
+    const record = checkRecord({ session, snapshot, outcome, includeAnswers: !!settings.answers });
+    const records = [...(Array.isArray(stored?.records) ? stored.records : []).filter(item => item.head !== record.head), record].slice(-RECORDS_KEPT);
+    await writeJson(file, { version: 1, repoRoot: snapshot.repoRoot, ref: snapshot.target.ref, records });
+    const job = path.join(githubDirectory(env), 'jobs', `${randomUUID()}.json`);
+    await writeJson(job, { version: 1, repo, sha: snapshot.head, branch: snapshot.target.ref.replace(/^refs\/heads\//, ''), branchFile: file, status: !!settings.status, comment: !!settings.comment });
+    const child = spawnImpl(process.execPath, [WORKER, job], { 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; }
+}
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+/** gh with an optional JSON body on stdin. Resolves { ok, stdout }; never rejects. */
+export function ghCli(args, { env = process.env, host, input, timeoutMs = 30000 } = {}) {
+  return new Promise(resolve => {
+    let child, stdout = '';
+    try { child = spawn('gh', args, { env: { ...env, GH_HOST: host, GH_PROMPT_DISABLED: '1', NO_COLOR: '1' }, stdio: ['pipe', 'pipe', 'ignore'] }); }
+    catch { resolve({ ok: false, stdout: '' }); return; }
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.stdout.on('data', chunk => { if (stdout.length < 4 * 1024 * 1024) stdout += chunk; });
+    child.once('error', () => { clearTimeout(timer); resolve({ ok: false, stdout: '' }); });
+    child.once('close', code => { clearTimeout(timer); resolve({ ok: code === 0, stdout }); });
+    child.stdin.on('error', () => {});
+    child.stdin.end(input === undefined ? '' : JSON.stringify(input));
+  });
+}
+
+/** The worker body: wait for the push to land, stamp it, then update the PR comment. */
+export async function runStampJob(job, { gh = ghCli, env = process.env, wait = sleep, landTries = 36, landEveryMs = 5000, prTries = 30, prEveryMs = 30000 } = {}) {
+  const { host, owner, repo } = job.repo;
+  const api = (args, input) => gh(['api', ...args, ...(input ? ['--input', '-'] : [])], { env, host, input });
+  if (!(await gh(['auth', 'status', '--hostname', host], { env, host })).ok) return 'not-signed-in';
+  // The hook runs before Git uploads, so the commit appears on GitHub a little later.
+  let landed = false;
+  for (let attempt = 0; attempt < landTries && !landed; attempt++) {
+    if (attempt) await wait(landEveryMs);
+    landed = (await api([`repos/${owner}/${repo}/commits/${job.sha}`, '--jq', '.sha'])).ok;
+  }
+  if (!landed) return 'not-pushed';
+  const records = (await readJson(job.branchFile, null).catch(() => null))?.records || [];
+  const record = records.find(item => item.head === job.sha);
+  if (!record) return 'no-record';
+  const status = statusFor(record);
+  const postStatus = targetUrl => api([`repos/${owner}/${repo}/statuses/${job.sha}`, '--method', 'POST'], { state: status.state, context: STATUS_CONTEXT, description: status.description, ...(targetUrl ? { target_url: targetUrl } : {}) });
+  if (job.status) await postStatus();
+  if (!job.comment) return 'done';
+
+  // A pull request is usually opened right after the first push of a branch.
+  let pull = null;
+  for (let attempt = 0; attempt < prTries && !pull; attempt++) {
+    if (attempt) await wait(prEveryMs);
+    const listed = await gh(['pr', 'list', '--repo', `${owner}/${repo}`, '--head', job.branch, '--state', 'open', '--json', 'number', '--limit', '1'], { env, host });
+    try { pull = listed.ok ? JSON.parse(listed.stdout || '[]')[0] || null : null; } catch { pull = null; }
+  }
+  if (!pull) return 'no-pull-request';
+  const body = commentBody((await readJson(job.branchFile, null).catch(() => null))?.records || records);
+  const existing = await api([`repos/${owner}/${repo}/issues/${pull.number}/comments`, '--paginate', '--jq', `.[] | select(.body | startswith("${COMMENT_MARKER}")) | .id`]);
+  const id = existing.ok ? existing.stdout.split('\n').find(Boolean) : null;
+  const written = id
+    ? await api([`repos/${owner}/${repo}/issues/comments/${id}`, '--method', 'PATCH', '--jq', '.html_url'], { body })
+    : await api([`repos/${owner}/${repo}/issues/${pull.number}/comments`, '--method', 'POST', '--jq', '.html_url'], { body });
+  if (written.ok && job.status) await postStatus(written.stdout.trim());
+  return written.ok ? 'done' : 'comment-failed';
+}
+
+export async function runStampWorker(jobFile, { env = process.env } = {}) {
+  let result = 'failed';
+  try {
+    const job = await readJson(jobFile, null);
+    if (job) result = await runStampJob(job, { env });
+  } catch { /* Best-effort only. */ }
+  finally { await unlink(jobFile).catch(() => {}); }
+  await writeJson(path.join(githubDirectory(env), 'last.json'), { result, at: new Date().toISOString() }).catch(() => {});
+  return result;
+}

package/src/help.js

@@ -90,7 +90,7 @@ export const HELP = {
   dispute: { summary: 'Challenge an ambiguous or unsupported question.', usage: 'sphinx dispute <assessment-id> --text <reason> [--json]', paragraphs: ['Explain the missing assumption or conflicting evidence. The independent evaluator reviews the question and may replace it. A dispute never awards completion. Uses one model call, plus one independent audit if a replacement is proposed. Both count toward the same allowance.'], groups: [['Reason', [['--text <reason>', 'What is ambiguous or contradicted by the evidence?']]], ['Output', common]], examples: ["sphinx dispute <assessment-id> --text 'The question assumes retries, but this path does not retry.' --json"] },
   pending: { summary: 'List unfinished checkpoints for this repository.', usage: 'sphinx pending [--json]', paragraphs: ['Shows valid pending and active checks, progress, selected route, counted calls, and any configured call limit. Stale snapshots are filtered out. Makes no model calls.'], groups: [['Output', common]], examples: ['sphinx pending', 'sphinx pending --json'] },
   status: { summary: 'See repository coverage, effective policy, and pending checks.', usage: 'sphinx status [--json]', paragraphs: ['Shows whether Git is using a Sphinx hook dispatcher and which events, destinations, and remotes the current policy covers. It does not contact remotes, call a model, or establish Codex hook trust.'], groups: [['Output', common]], examples: ['sphinx status', 'sphinx status --json'] },
-  config: { summary: 'Inspect effective settings or change evaluator models and call limits.', usage: 'sphinx config [--preset <name>] [--small <provider:model>] [--max-model-calls <1-100|unlimited>] [--json]', paragraphs: ['Without a setter, this command only displays effective configuration. Repository .sphinxconfig overrides supported global policy fields; legacy .sphinx.json is used only when the canonical file is absent. Model routes, credentials, and optional call caps remain machine-wide.', 'Save evaluator models or the total assessment allowance without reinstalling or invoking a model. This works outside a Git repository and preserves unrelated global settings. With --json, a save reports the global path, previous and new limit, and resulting global configuration. Size-based planning targets do not impose a hidden request cap. Existing explicitly configured limits are preserved unless changed.', 'Evaluator changes apply to fresh checkpoints; existing checkpoints are bound to their original route and policy. Budget-only changes preserve their usage and questions. OpenRouter presets require a saved key or OPENROUTER_API_KEY before the next assessment.'], groups: [['Evaluators and usage', evaluatorOptions], ['Output', common]], examples: ['sphinx config', 'sphinx config --json', 'sphinx config --preset openrouter-value --allow-paid', 'sphinx config --preset claude-economy --large claude:sonnet', 'sphinx config --max-model-calls unlimited', 'sphinx config --max-model-calls 30 --json'] },
+  config: { summary: 'Inspect effective settings or change evaluator models and call limits.', usage: 'sphinx config [--preset <name>] [--small <provider:model>] [--max-model-calls <1-100|unlimited>] [--json]', paragraphs: ['Without a setter, this command only displays effective configuration. Repository .sphinxconfig overrides supported global policy fields; legacy .sphinx.json is used only when the canonical file is absent. Model routes, credentials, and optional call caps remain machine-wide.', 'Save evaluator models or the total assessment allowance without reinstalling or invoking a model. This works outside a Git repository and preserves unrelated global settings. With --json, a save reports the global path, previous and new limit, and resulting global configuration. Size-based planning targets do not impose a hidden request cap. Existing explicitly configured limits are preserved unless changed.', 'Evaluator changes apply to fresh checkpoints; existing checkpoints are bound to their original route and policy. Budget-only changes preserve their usage and questions. OpenRouter presets require a saved key or OPENROUTER_API_KEY before the next assessment.'], groups: [['Evaluators and usage', evaluatorOptions], ['Questionnaire', [['--interface <auto|browser|terminal>', 'Where questions appear. auto (default): the browser on a local Mac, otherwise inline in the terminal you ran Git from. terminal: always the terminal, falling back to the browser when no terminal is visible. browser: always the browser.']]], ['Output', common]], examples: ['sphinx config', 'sphinx config --interface terminal', 'sphinx config --json', 'sphinx config --preset openrouter-value --allow-paid', 'sphinx config --preset claude-economy --large claude:sonnet', 'sphinx config --max-model-calls unlimited', 'sphinx config --max-model-calls 30 --json'] },
   yolo: { summary: 'Toggle skipping understanding checks when something is urgent.', usage: 'sphinx yolo [--reason <text>] [--json]', paragraphs: ['Run inside a Git repository to toggle yolo mode for that repository only; turning it off there keeps checks on even while global yolo is on. Run outside a repository to toggle it globally. Run the same command again to turn it off.', 'While on, Git operations continue without a questionnaire and background review is paused: no new model request starts, although one already in progress when yolo is turned on may finish. It is a straight bypass: no check is created. Each skip is logged with an optional reason; sphinx status shows recent overrides. For a one-off, use Skip this time in the questionnaire instead.'], groups: [['Reason', [['--reason <text>', 'Optional note recorded with the toggle, e.g. a hotfix ticket.']]], ['Output', common]], examples: ['sphinx yolo --reason "prod hotfix"', 'sphinx yolo', 'cd ~ && sphinx yolo'] },
   doctor: { summary: 'Check Git dispatchers and coding-agent integration settings.', usage: 'sphinx doctor [--json]', paragraphs: ['Finds local hook overrides, missing dispatchers, and edited integration settings. Optional agents that were not selected do not count as failures. Codex trust must be reviewed in /hooks; Sphinx cannot verify it.'], groups: [['Output', common]], examples: ['sphinx doctor', 'sphinx install --repo'], footer: 'Exit status is 0 when checks pass and 1 when something needs attention. No model calls or configuration changes.' },
   usage: { summary: 'See tokens and spend from Sphinx model calls.', usage: 'sphinx usage [--json]', paragraphs: ['Shows tokens and cost for today, the last 7 and 30 days, and all recorded history, split into free OpenRouter models, paid OpenRouter models, OpenAI-compatible endpoints, and Claude Code or Codex coding plans, then by purpose such as review, grading, and context.', 'Coding-plan routes show tokens only: they count against your Claude or ChatGPT plan, not a per-call bill. Endpoints show cost only when they report it.'], groups: [['Output', common]], examples: ['sphinx usage', 'sphinx usage --json'], footer: 'Each model call appends one small line to usage/YYYY-MM.jsonl in your Sphinx home. Only the last 12 monthly files are kept; older months are deleted automatically. Reading usage makes no model calls.' },

package/src/sessions.js

@@ -339,7 +339,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; }
+}