sphinx-understand 0.1.5 → 0.1.7

package/README.md

@@ -2,7 +2,7 @@
 
 <h1 align="center">Sphinx</h1>
 
-<p align="center"><em>Outsource your thinking, not your understanding.</em></p>
+<p align="center"><em>You can outsource your thinking, but not your understanding.</em></p>
 
 <p align="center"><img src="docs/demo.gif" width="860" alt="A git push pauses while Sphinx asks a question about the change in a local browser page; after a correct answer the push continues."></p>
 
@@ -144,7 +144,7 @@ Your answers go straight from the page to Sphinx. Your coding agent sees only th
 
 ## Limits and cost
 
-Question count depends on the size of the change and the depth you choose. Small changes get one question, and large ones get up to three at the default depth. After commits, Sphinx prepares questions in the background, so they are often ready by the time you push. Calls, tokens, and (when reported) cost appear in the questionnaire.
+Question count depends on the size of the change and the depth you choose: small changes get up to one question (none for documentation or trivial edits), and large ones up to three at the default depth. Understanding distance sets how close to the code questions get: `high` (default) asks what your change does and affects, `low` asks about its specific logic and edge cases. Set it in setup, with `sphinx config --distance low`, or per repository in `.sphinxconfig`. After commits, Sphinx prepares questions in the background, so they are often ready by the time you push. Calls, tokens, and (when reported) cost appear in the questionnaire.
 
 ```sh
 sphinx config --max-model-calls 30        # optional cap per check (1–100)

package/bin/sphinx.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { main } from '../src/cli.js';
 import { formatError } from '../src/terminal.js';
+import { withUsageLedger } from '../src/usage.js';
 
-try { process.exitCode = await main(process.argv.slice(2)); }
+// Only the real CLI process records model usage to the on-disk ledger.
+try { process.exitCode = await withUsageLedger(process.env, () => main(process.argv.slice(2))); }
 catch (error) {
   formatError(error, { plain: process.argv.includes('--json') || ['hook', 'mcp'].includes(process.argv[2]) });
   process.exitCode = error.exitCode || 1;

package/docs/architecture.md

@@ -146,7 +146,7 @@ The existing line, file-count, and consequential-path rules deterministically se
 | Medium | 2 | 2 | 3 |
 | Large | 2 | 3 | 5 |
 
-The evaluator must return at least one question and may use fewer than the ceiling when fewer distinct behaviors are supported. It must not invent extra concerns to fill the budget. Model routes remain independent of depth. `maxOutputTokens` is preserved across all tiers; OpenRouter enforces it, while CLI evaluators receive concise-output instructions and local process limits.
+The evaluator may use fewer questions than the ceiling when fewer distinct behaviors are supported. Medium and large changes get at least one; a small change may get none when the audited review finds nothing a developer must understand, and documentation-only changes pass without a model call. The configured understanding distance (`high` or `low`) sets whether questions address the change's behavior and effects or its specific implementation logic. It must not invent extra concerns to fill the budget. Model routes remain independent of depth. `maxOutputTokens` is preserved across all tiers; OpenRouter enforces it, while CLI evaluators receive concise-output instructions and local process limits.
 
 The economy CLI presets select `codex:gpt-6-luna` or `claude:haiku` for all tiers, preserving the cheaper model while effort and review planning targets scale. The paid OpenRouter value preset selects `anthropic/claude-haiku-5.5` for every tier and sets an 8,192-token output ceiling; an explicit output flag takes precedence. Applying the preset preserves the total call limit. The experimental open-weight alternative selects `deepseek/deepseek-v3.2`. Existing routes are never migrated implicitly. See [the evaluation record](../eval/RESULTS.md) for measured results and failures; these starting configurations are not guarantees of assessment quality. OpenRouter routes consume API credits separately from coding-agent plans; Codex and Claude routes consume the selected CLI account's allowance. Pi, Cursor, and OpenCode client integrations do not supply a model transport or reuse those clients' credentials.
 

package/docs/configuration.md

@@ -165,6 +165,7 @@ Call caps bound requests and byte limits bound evidence. Neither is a dollar or
   "events": ["pre-push"],
   "branches": ["main", "release/*"],
   "level": "standard",
+  "distance": "high",
   "exclude": ["vendor/**"]
 }
 ```
@@ -176,6 +177,7 @@ Call caps bound requests and byte limits bound evidence. Neither is a dollar or
 | `branches` | Push policies match the **destination** branch; commit policies match the current local branch |
 | `remotes` | Remote name patterns for pushes; default `*` |
 | `level` | `relaxed`, `standard`, or `thorough` |
+| `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 |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sphinx-understand",
-  "version": "0.1.5",
-  "description": "Outsource your thinking, not your understanding. A comprehension checkpoint for agent-assisted development.",
+  "version": "0.1.7",
+  "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": {
     "type": "git",

package/src/agent.js

@@ -1,6 +1,7 @@
 import { constants } from 'node:fs';
 import { browserHandoff } from './lifecycle-integrations.js';
 import { open } from 'node:fs/promises';
+import { setupNudge } from './repo-setup.js';
 
 /** Session setup only. Git and native lifecycle hooks control the actual checkpoint. */
 export async function agentHook({ agent, event, input = '', env = process.env }) {
@@ -30,6 +31,7 @@ export async function agentHook({ agent, event, input = '', env = process.env })
     try { await file.writeFile(`\nexport SPHINX_CLAUDE_SESSION='${payload.session_id}'\n`); }
     finally { await file.close(); }
   }
+  const nudge = await setupNudge(payload?.cwd);
   return {
     exitCode: 0,
     output: {
@@ -48,6 +50,7 @@ export async function agentHook({ agent, event, input = '', env = process.env })
           'After a fallback questionnaire passes, verify that the original Git operation has exited with a Sphinx blocking failure before retrying it. Never duplicate a waiting operation or repeat a successful operation. A changed commit or destination may require another assessment. Reopen a paused blocking checkpoint only when the human asks and the previous Git process has exited.',
           'If neither the local page nor native forms are available, report the integration issue and use sphinx doctor to diagnose it. The human can run sphinx check in their own terminal. Do not substitute a chat-based questionnaire or submit answers yourself.',
           'The assessment is open-book. Helping the human inspect code is encouraged. The coding agent must not grade the response itself.',
+          ...(nudge ? [nudge] : []),
         ].join('\n'),
       },
     },

package/src/browser-interview.js

@@ -1,4 +1,5 @@
 import { createServer } from 'node:http';
+import { readStats, scoreSummary } from './stats.js';
 import { planProviders } from './evaluator.js';
 import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { spawn } from 'node:child_process';
@@ -6,7 +7,7 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { loadConfig, policyHash } from './config.js';
 import { revalidateSnapshot } from './git.js';
 import { createSessionStore } from './sessions.js';
-import { prepareInteractiveCheck, isRateLimit, switchChoices, PLAN_NAMES } from './check-recovery.js';
+import { prepareInteractiveCheck, isRateLimit, isCliFailure, switchChoices, PLAN_NAMES } from './check-recovery.js';
 import { claimCheckpointDialog, finishCheckpointDialog, waitForCheckpointTerminal } from './terminal-launch.js';
 import { browserPage } from './browser-page.js';
 import { recordOverride } from './overrides.js';
@@ -58,12 +59,14 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
   const token = randomBytes(32).toString('base64url'), nonce = randomBytes(24).toString('base64');
   let server, origin, url, opened = false, closed = false, active, skip, resolver, sequence = 0, waitingGit = false;
   const pauseMessage = () => waitingGit
-    ? 'Paused. Progress is saved; the waiting Git operation was stopped.'
-    : 'Paused. Your progress and completed checkpoints are saved.';
+    ? 'Paused. Progress is saved; the waiting Git operation was stopped. You can close this tab.'
+    : 'Paused. Your progress and completed checkpoints are saved. You can close this tab.';
   let state = { phase: 'waiting', operationClosed: false, revision: randomUUID(), sequence, message: 'Waiting for the checkpoint.', messages: [] };
   // The chat transcript for the current checkpoint lives only in this process.
   // It contains public questions, feedback, and the human's own text.
-  let transcript = [], turns = 0;
+  let transcript = [], turns = 0, score = 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
   // beside the questionnaire and can never block, grade, or approve it.
   let view, evidence, evidenceKey;
@@ -91,7 +94,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, 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 } : {}), 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);
   };
@@ -150,7 +153,7 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
       // Available at any step, including while the review is still running.
       skip = { reason: data.response };
       active.abort(cancelled());
-      publish({ ...publicFields(state), phase: 'skipped', message: waitingGit ? 'Skipped. Git is continuing.' : 'Skipped.' });
+      publish({ ...publicFields(state), phase: 'skipped', message: waitingGit ? 'Skipped. Git is continuing; you can close this tab.' : 'Skipped. You can close this tab.' });
       return send(res, 200, state);
     }
     if (data.action === 'pause') {
@@ -255,6 +258,7 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
       if (session.snapshot.repoRoot !== request.repoRoot) throw new Error('This checkpoint belongs to another repository.');
       await validate(session.snapshot, config);
       startView(request, session.snapshot, config, operationEnv, store);
+      await refreshScore(request.repoRoot, operationEnv).catch(() => {});
       let visible = store.public(session);
       publish({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'working', message: 'Preparing your understanding check…' });
       await ensureServer(operationEnv);
@@ -277,7 +281,7 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
         },
         choose: async prompt => {
           const current = store.public(await store.read(request.id));
-          const action = await waitForAction({ ...publicFields(current), repoRoot: request.repoRoot, phase: 'recovery', message: prompt.title, error: notes.join('\n'), choices: prompt.choices }, prompt.choices.map(choice => choice.value));
+          const action = await waitForAction({ ...publicFields(current), repoRoot: request.repoRoot, phase: 'recovery', message: prompt.title, error: [prompt.description, ...notes].filter(Boolean).join('\n'), choices: prompt.choices }, prompt.choices.map(choice => choice.value));
           return action.action;
         },
       });
@@ -306,15 +310,16 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
             learn: action.action === 'learn', dispute: action.action === 'dispute', expectedQuestionId: action.questionId, signal: localSignal,
           })).finally(dropDraft);
           settle('graded');
+          await refreshScore(request.repoRoot, operationEnv).catch(() => {});
           if (visible.feedback) say({ role: 'sphinx', kind: 'feedback', text: visible.feedback });
         } catch (error) {
           settle('not-graded');
           localSignal.throwIfAborted(); await validate(session.snapshot, config);
           visible = store.public(await store.read(request.id));
           // A rate-limited API route can hand grading to the user's coding-agent plan.
-          if (isRateLimit(error, visible.route) && plans.length) {
+          if ((isRateLimit(error, visible.route) || isCliFailure(error, visible.route)) && switchChoices(plans, visible.route.provider).length) {
             const choices = [...switchChoices(plans, visible.route.provider), { value: 'back', label: 'Back to the question', description: 'Keep the current model and try again later. Your draft answer is kept.' }];
-            const picked = await waitForAction({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'recovery', message: 'Grading was rate limited', error: error.message, choices }, choices.map(choice => choice.value));
+            const picked = await waitForAction({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'recovery', message: isRateLimit(error, visible.route) ? 'Grading was rate limited' : `${PLAN_NAMES[visible.route.provider][0]} could not grade this answer`, error: error.message, choices }, choices.map(choice => choice.value));
             if (picked.action.startsWith('switch-')) {
               const provider = picked.action.slice('switch-'.length);
               visible = await store.switchRoute(request.id, config, provider, { signal: localSignal });
@@ -329,7 +334,7 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
       }
       localSignal.throwIfAborted(); await validate(session.snapshot, config);
       finalStatus = 'passed';
-      publish({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'passed', message: waitingGit ? 'You passed. You can close this tab; Git is finishing the push on its own.\nThis records your answers, not a review of every changed line.' : 'You passed. You can close this tab.\nThis records your answers, not a review of every changed line.' });
+      publish({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'passed', message: visible.noQuestionReason ? `No questions needed: ${visible.noQuestionReason} You can close this tab${waitingGit ? '; Git is finishing the push on its own' : ''}.` : waitingGit ? 'You passed. You can close this tab; Git is finishing the push on its own.\nThis records your answers, not a review of every changed line.' : 'You passed. You can close this tab.\nThis records your answers, not a review of every changed line.' });
       return { status: 'passed', id: request.id };
     } catch (error) {
       settle('not-graded');

package/src/browser-page.js

@@ -17,7 +17,7 @@ header{min-height:52px;border-bottom:1px solid var(--line);padding:8px 24px;disp
 .facts .mono{font:600 12.5px var(--mono)}.scope-note{margin:2px 0 0;color:var(--muted);font-size:12px}#usage{color:var(--muted);font-weight:400;font-variant-numeric:tabular-nums}
 .tabs{display:none}.scope-short{display:none}
 .workspace{flex:1;min-height:0;display:grid;grid-template-columns:minmax(400px,46%) minmax(0,1fr);grid-template-rows:minmax(0,auto) minmax(0,1fr);grid-template-areas:"q files" "q diff"}
-#question-pane{grid-area:q;border-right:1px solid var(--line)!important}#files-pane{grid-area:files;max-height:30vh;border-right:0;border-bottom:1px solid var(--line)}#diff-pane{grid-area:diff;border-right:0}
+#question-pane{grid-area:q;border-right:1px solid var(--line)!important}#files-pane{grid-area:files;max-height:30vh;overflow:hidden;border-right:0;border-bottom:1px solid var(--line)}#diff-pane{grid-area:diff;border-right:0}
 .pane{min-width:0;min-height:0;display:flex;flex-direction:column;border-right:1px solid var(--line)}.pane:last-child{border-right:0}
 .pane h2{font-size:13px;font-weight:600;margin:0;overflow-wrap:anywhere;line-height:1.4}.pane-note{font-size:12px;color:var(--muted);margin:0;padding:8px 14px;overflow-wrap:anywhere}
 .filters{display:grid;grid-template-columns:1fr 1fr;gap:6px;padding:10px 12px 6px}.filters button{min-height:44px;font-size:12.5px;line-height:1.25;padding:4px 8px}
@@ -61,8 +61,17 @@ button.primary{background:var(--amber);color:#fff;border-color:var(--amber);marg
 button:hover:not(:disabled){background:#eee7dc}button.primary:hover:not(:disabled){background:#8b4208}
 .disputing textarea{border-color:#8d271e}.disputing #submit{background:#8d271e;border-color:#8d271e}
 button.quiet{border-color:transparent;color:var(--muted)}button.quiet:hover:not(:disabled){color:var(--ink)}
-.hint{font-size:12px;color:var(--muted);margin:10px 0 0}.recovery{display:grid;gap:12px;margin:0 0 20px}.recovery button{text-align:left;width:100%}.recovery p{margin:4px 0 0;font-size:13px;color:var(--muted)}
+.hint{font-size:12px;color:var(--muted);margin:10px 0 0}.recovery-reason{margin:-8px 0 18px;padding:10px 14px;border-left:2px solid #8d271e;background:#f8ece9;color:#6f1f18;font-size:13.5px;white-space:pre-wrap;overflow-wrap:anywhere}.recovery{display:grid;gap:12px;margin:0 0 20px}.recovery button{text-align:left;width:100%}.recovery p{margin:4px 0 0;font-size:13px;color:var(--muted)}
 header .tools{display:flex;gap:4px}
+.score{display:grid;grid-template-columns:auto auto;grid-template-rows:auto auto;column-gap:14px;align-items:center;margin-left:auto;margin-right:14px;padding:6px 16px;border:1px solid var(--line);border-radius:12px;background:#fff}
+.score-head{display:flex;flex-direction:column;line-height:1.15;grid-row:1/3}.score-label{font-size:11.5px;color:var(--muted)}.score-value{font:600 20px/1.1 var(--mono);font-variant-numeric:tabular-nums}
+.score-value.pending{font-family:inherit;font-size:13px;font-weight:500;line-height:1.6;color:var(--muted)}
+.score-dots{display:flex;gap:4px}.score-dots i{width:11px;height:11px;border-radius:50%;border:1.5px solid #cfc4b6;background:transparent}
+.score-dots i.hit{background:var(--pass);border-color:var(--pass)}.score-dots i.miss{border-color:#c0574a;background:#f6e2df}
+.score-dots i.fresh{animation:pop .5s ease}@keyframes pop{0%{transform:scale(.3)}70%{transform:scale(1.25)}100%{transform:scale(1)}}
+.score-meta{font-size:11px;color:var(--muted);white-space:nowrap}
+@media(prefers-reduced-motion:reduce){.score-dots i.fresh{animation:none}}
+@media(max-width:600px){.score{margin-right:4px;padding:4px 10px}.score-meta{display:none}}
 .skipbar{display:flex;flex-wrap:wrap;align-items:center;gap:8px;padding:12px 0;border-bottom:1px solid var(--line);font-size:14px}.skipbar p{flex-basis:100%;margin:0;color:var(--muted);font-size:13px}
 .skipbar input{flex:1;min-width:180px;font:inherit;font-size:14px;padding:6px 10px;border:1px solid #b9afa3;border-radius:6px;background:#fff;color:var(--ink)}
 button.danger{background:#8d271e;border-color:#8d271e;color:#fff}button.danger:hover:not(:disabled){background:#6f1f18}
@@ -81,7 +90,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 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><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>
@@ -102,7 +111,7 @@ footer{flex-shrink:0;display:flex;flex-wrap:wrap;gap:2px 8px;padding:0 0 14px;co
 <div id="conversation" class="conversation" aria-label="Understanding check conversation">
 <ol id="messages" aria-label="Conversation"></ol>
 <p id="feedback" class="feedback" hidden></p><section id="question" hidden><p id="prompt" class="question"></p><ul id="choices" hidden></ul></section>
-<p id="message" class="message" role="status" hidden></p><div id="status" class="status" role="status" aria-live="polite">Connecting to your local checkpoint…</div><div id="recovery" class="recovery" hidden></div>
+<p id="message" class="message" role="status" hidden></p><div id="status" class="status" role="status" aria-live="polite">Connecting to your local checkpoint…</div><p id="recovery-reason" class="recovery-reason" hidden></p><div id="recovery" class="recovery" hidden></div>
 </div>
 <section id="evidence" class="evidence" aria-labelledby="evidence-title" hidden><h2 id="evidence-title">Code behind this question</h2><ul id="evidence-list"></ul><p id="evidence-note" class="pane-note"></p></section>
 <div id="composer" class="composer"><p id="error" class="error" role="alert" hidden></p>
@@ -118,6 +127,26 @@ const text=(id,value)=>{$(id).textContent=value||'';$(id).hidden=!value;};
 const compact=n=>n>=1e6?(n/1e6).toFixed(1)+'M':n>=1e3?(n/1e3).toFixed(1)+'k':String(n);
 const usageText=(u,t)=>{if(!t)return '';const total=(t.input||0)+(t.output||0);if(!total&&t.cost==null)return '';
  return [compact(total)+' tokens',...(t.cost!=null?[t.cost===0?'$0':t.cost<0.0001?'<$0.0001':t.cost<0.01?'$'+t.cost.toFixed(4):'$'+t.cost.toFixed(2)]:[]),...(u?.limit!=null?[u.calls+'/'+u.limit+' calls']:[])].join(' · ');};
+const PROVIDERS={openrouter:'OpenRouter',openai:'Endpoint',claude:'Claude Code',codex:'Codex'};
+const routeText=r=>r?.provider?[PROVIDERS[r.provider]||r.provider,r.model].filter(Boolean).join(' '):'';
+// The repository's understanding score, shown rather than explained: one dot
+// per recent answer (green = right first time), filling empty slots while calibrating.
+let lastScored=-1;
+function scoreView(sc){
+ $('score').hidden=!sc;if(!sc)return;
+ const recent=sc.recent||[],slots=sc.calibrating?sc.answered+sc.needed:Math.max(recent.length,1);
+ const dots=[];
+ for(let i=0;i<slots;i++){const dot=document.createElement('i'),hit=recent[i];
+  if(i<recent.length){dot.className=hit?'hit':'miss';dot.title=hit?'Right first time':'Needed another try';}else dot.title='Not answered yet';
+  if(i===recent.length-1&&lastScored!==-1&&sc.answered>lastScored)dot.className+=' fresh';
+  dots.push(dot);}
+ $('score-dots').replaceChildren(...dots);
+ $('score-dots').setAttribute('aria-label',recent.filter(Boolean).length+' of the last '+recent.length+' answers right first time');
+ $('score-value').textContent=sc.calibrating?'warming up':sc.accuracy+'%';$('score-value').className='score-value'+(sc.calibrating?' pending':'');
+ $('score').title=sc.calibrating?'Answer '+sc.needed+' more question'+(sc.needed===1?'':'s')+' in this repository to get a score.':'Share of questions in this repository you answered right on the first try.';
+ 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;
+}
 const resize=()=>{$('response').style.height='auto';$('response').style.height=Math.min($('response').scrollHeight||76,180)+'px';};
 function controls(){
  if(!current)return;
@@ -167,11 +196,11 @@ 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',usageText(state.usage,state.tokens));const messages=state.messages||[];
+ text('usage',[routeText(state.route),usageText(state.usage,state.tokens)].filter(Boolean).join(' · '));scoreView(state.score);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;
- text('status',label+(retry?' · Needs another answer':''));$('message').className='message'+(state.phase==='passed'?' passed':'');scope(state,branch,label);$('status').className='status phase-'+state.phase+(state.phase==='working'?' busy':'')+(retry?' retry':'');if(state.phase==='question'&&!retry)$('status').hidden=true;text('message',state.message);text('error',state.error); if(state.phase==='passed'&&String(state.message||'').includes('\\n')){const [lead,...rest]=state.message.split('\\n');text('message',lead);text('status',rest.join(' '));$('status').className='status passed-note';}
+ text('status',label+(retry?' · Needs another answer':''));$('message').className='message'+(state.phase==='passed'?' passed':'');scope(state,branch,label);$('status').className='status phase-'+state.phase+(state.phase==='working'?' busy':'')+(retry?' retry':'');if(state.phase==='question'&&!retry)$('status').hidden=true;text('message',state.message);text('error',state.phase==='recovery'?'':state.error);text('recovery-reason',state.phase==='recovery'?state.error:''); if(state.phase==='passed'&&String(state.message||'').includes('\\n')){const [lead,...rest]=state.message.split('\\n');text('message',lead);text('status',rest.join(' '));$('status').className='status passed-note';}
  history(messages);
  // Live activity already shows progress; avoid stacking generic spinners under it.
  if(state.phase==='working'&&(messages.at(-1)?.kind==='activity'||messages.at(-1)?.streaming)){$('status').hidden=true;$('message').hidden=true;}

package/src/check-recovery.js

@@ -9,10 +9,14 @@ export const isRateLimit = (error, route) => ['openrouter', 'openai'].includes(r
   && (error?.status === 429 || error?.errorType === 'rate_limit_exceeded');
 
 export const PLAN_NAMES = { claude: ['Claude Code', 'Claude'], codex: ['Codex', 'ChatGPT'] };
-export const switchChoices = (providers, from) => providers.map(provider => ({
+const ROUTE_NAMES = { openrouter: 'OpenRouter', openai: 'your API endpoint', claude: 'Claude Code', codex: 'Codex' };
+export const switchChoices = (providers, from) => providers.filter(provider => provider !== from).map(provider => ({
   value: `switch-${provider}`, label: `Switch this check to ${PLAN_NAMES[provider][0]}`,
-  description: `Continue on your signed-in ${PLAN_NAMES[provider][1]} plan instead of ${from === 'openai' ? 'your API endpoint' : 'OpenRouter'}. Only this check changes; your saved model settings stay the same.`,
+  description: `Continue on your signed-in ${PLAN_NAMES[provider][1]} plan instead of ${ROUTE_NAMES[from] ?? from}. Only this check changes; your saved model settings stay the same.`,
 }));
+/** A coding-agent CLI that failed to run; another plan can take over. */
+export const isCliFailure = (error, route) => ['claude', 'codex'].includes(route?.provider)
+  && ['PROVIDER_FAILED', 'PROVIDER_NO_OUTPUT', 'PROVIDER_AUTH', 'EVALUATOR_TIMEOUT'].includes(error?.code);
 
 function retryable(error, before, state, minimum) {
   if (setupCodes.has(error.code) || setupTypes.has(error.errorType)) return false;
@@ -75,13 +79,19 @@ export async function prepareInteractiveCheck({ start, inspect, authorizeMore, v
         });
       }
       // Offer the user's own coding-agent plan first when an API route is rate limited.
-      const switches = switchRoute && isRateLimit(error, state.route) ? switchChoices(planProviders, state.route.provider) : [];
+      const switches = switchRoute && (isRateLimit(error, state.route) || isCliFailure(error, state.route)) ? switchChoices(planProviders, state.route.provider) : [];
       choices.unshift(...switches);
       if (!choices.length) ui.note('Resolve the reported setup or evidence problem before resuming. Repeating this attempt is not offered here.');
+      const failedCli = isCliFailure(error, state.route) ? PLAN_NAMES[state.route.provider][0] : null;
       choices.push({ value: 'pause', label: 'Pause this check', description: 'Save progress without making another model request. The Git operation remains unapproved.' });
       const action = await choose({
-        title: 'Review did not finish',
-        description: waitingGit
+        // Lead with the cause when it is a rate limit, so the choices make sense.
+        title: isRateLimit(error, state.route) ? `${state.route.provider === 'openai' ? 'Your API endpoint' : 'OpenRouter'} is rate limiting this review`
+          : failedCli ? `${failedCli} could not run this review` : 'Review did not finish',
+        description: isRateLimit(error, state.route)
+          ? `It returned too many requests (HTTP 429). ${switches.length ? 'Switch this check to your coding plan, or wait and continue.' : 'Wait a moment, then continue.'}`
+          : failedCli ? `${switches.length ? `Switch this check to ${PLAN_NAMES[switches[0].value.slice(7)][0]}, or pause and` : 'Pause and'} check that ${failedCli} is installed, signed in, and up to date. The details are below.`
+          : waitingGit
           ? 'The original Git operation is waiting while this terminal stays open, subject to its time limit. Choose how to continue.'
           : 'Choose how to continue. Nothing is retried automatically.',
         choices, current: 'pause',

package/src/cli.js

@@ -1,14 +1,16 @@
 import path from 'node:path';
+import { readStats, scoreSummary } from './stats.js';
 import { planProviders } from './evaluator.js';
 import { VERSION } from './version.js';
 import { fileURLToPath } from 'node:url';
-import { lstat } from 'node:fs/promises';
+import { lstat, readFile } from 'node:fs/promises';
 import { parseArgs, promisify } from 'node:util';
 import { execFile } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { Writable } from 'node:stream';
 import { getPaths, loadConfig, saveConfig, saveOpenRouterKey, openRouterKey, saveOpenAIEndpoint, openAIEndpoint, validateConfig, repositoryConfigInfo, policyHash } from './config.js';
 import { initializeRepository } from './repo-config.js';
+import { applyRepositorySetup, suggestRepositorySetup } from './repo-setup.js';
 import * as git from './git.js';
 import { install, uninstall, doctor, dispatchHook, installedAgents, detectAgents } from './install.js';
 import { activateIntegrations } from './activation.js';
@@ -23,20 +25,20 @@ import { askInstall, askPolicy, createPrompts, questionCapsText, reviewCapsText,
 import { runGitGate } from './git-gate.js';
 import { loadProjectContext } from './repo-context.js';
 import { REVIEWER_PRESETS, presetOptions } from './model-presets.js';
-import { modelUsageText, modelLimitText } from './usage.js';
+import { modelUsageText, modelLimitText, readUsage, summarizeUsage, printUsage, usageDir } from './usage.js';
 import { toggleYolo, yoloStatus, recentOverrides } from './overrides.js';
 
 const CLI_PATH = fileURLToPath(new URL('../bin/sphinx.js', import.meta.url));
-const POLICY_FLAGS = ['branches', 'events', 'level', 'remotes'];
+const POLICY_FLAGS = ['branches', 'events', 'level', 'distance', 'remotes'];
 const MODEL_FLAGS = ['preset', 'provider', 'model', 'small', 'medium', 'large', 'allow-paid', 'max-model-calls', 'max-output-tokens', 'cli-billing'];
 const OPTIONS = {
   install: ['yes', 'repo', 'agents', ...MODEL_FLAGS, 'launch', 'no-launch', ...POLICY_FLAGS],
   activate: ['agents', 'json'],
-  init: ['yes', 'json', 'context', ...POLICY_FLAGS], check: ['json', 'id', 'remote', 'branch', 'staged', 'retry-review'],
+  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', ...MODEL_FLAGS], doctor: ['json'], auth: ['provider', 'base-url'], uninstall: ['repo'],
-  mcp: [], yolo: ['json', 'reason'],
+  status: ['json'], config: ['json', 'distance', ...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));
 const ui = () => createTerminal();
@@ -133,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', 'mode']) if (values[key] !== undefined) config[key] = values[key];
+  for (const key of ['provider', 'model', 'level', 'distance', '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) {
@@ -162,6 +164,7 @@ function policyRows(config) {
     ['Push checkpoints', enabled && config.events.includes('pre-push') ? `Destination branches: ${config.branches.join(', ') || 'none'}. Remotes: ${config.remotes.join(', ') || 'none'}.` : 'Off. Local pushes are not checked by this policy.'],
     ['Commit checkpoints', enabled && config.events.includes('pre-commit') ? `Staged changes on local branches: ${config.branches.join(', ') || 'none'}.` : 'Off. Local commits are not checked by this policy.'],
     ['Depth', `${config.level} · question caps: ${questionCapsText(config.level)}`],
+    ['Distance', config.distance === 'low' ? 'low · implementation details: specific logic, conditions, and edge cases' : 'high · behavior and consequences of the change as a whole'],
     ['Preparation', config.backgroundPreparation ? 'Background review after commits and branch updates' : 'On demand when the understanding check starts'],
     ['Behavior', !enabled ? 'Disabled for this repository' : 'The Git operation only goes through after you answer the understanding questions correctly'],
   ];
@@ -267,9 +270,10 @@ async function installCommand(initial) {
   const launch = !initial['no-launch'] && (initial.launch || !initial.yes);
   if (launch) terminal.paragraph('After setup, Sphinx opens selected installed clients in fresh sessions. Existing sessions stay open. Use --no-launch to defer this step.');
   const detected = !initial.yes && (initial.agents === undefined || initial.agents === 'auto') ? await detectAgents() : [];
+  const installedPlans = initial.yes ? [] : await planProviders().catch(() => []);
   const values = initial.yes ? initial : await withReadline(ask => askInstall(current, initial, createPrompts({ ask, ui: terminal,
     select: process.stdin.isTTY && process.stdout.isTTY && process.env.TERM !== 'dumb' ? ask.checkbox : undefined,
-  }), { detectedAgents: detected, hasExistingConfig }));
+  }), { detectedAgents: detected, hasExistingConfig, installedPlans }));
   const config = applyInstallOptions(current, values);
   terminal.section('Machine-wide defaults');
   terminal.paragraph('Each repository can override these branches and remotes in .sphinxconfig to match its own production setup.');
@@ -295,7 +299,36 @@ async function installCommand(initial) {
   terminal.blank(); terminal.note(`Global settings: ${getPaths().config}`); return 0;
 }
 
+async function readProposal(source) {
+  let text = '';
+  if (source === '-') { for await (const chunk of process.stdin) { text += chunk; if (text.length > 1e6) throw new Error('Proposal exceeds 1 MB.'); } }
+  else text = await readFile(path.resolve(source), 'utf8');
+  try { return JSON.parse(text); } catch (error) { throw new Error(`Proposal is not valid JSON: ${error.message}`); }
+}
+
+// Agent setup: a read-only proposal, then a validated, idempotent apply.
+async function agentSetupCommand(values) {
+  const extra = Object.keys(values).filter(key => !['suggest', 'apply', 'json'].includes(key));
+  if (extra.length || (values.suggest && values.apply !== undefined)) throw new Error('Use either --suggest or --apply <file|->, optionally with --json, and no other init options.');
+  const { repo, config } = await repoConfig();
+  if (values.suggest) { json(await suggestRepositorySetup({ repoRoot: repo.root })); return 0; }
+  let result;
+  try { result = await applyRepositorySetup({ repoRoot: repo.root, proposal: await readProposal(values.apply), config }); }
+  catch (error) {
+    if (!values.json || error.code !== 'SPHINX_INVALID_PROPOSAL') throw error;
+    json({ ok: false, errors: error.errors }); return 1;
+  }
+  if (values.json) { json(result); return 0; }
+  const terminal = ui();
+  for (const file of result.created) terminal.success(`Created ${file}`);
+  for (const file of result.updated) terminal.success(`Updated ${file}`);
+  for (const file of result.preserved) terminal.note(`Preserved ${file}`);
+  for (const line of result.warnings) terminal.warning(line);
+  return 0;
+}
+
 async function initCommand(initial) {
+  if (initial.suggest || initial.apply !== undefined) return agentSetupCommand(initial);
   const { repo, config } = await repoConfig(), info = await repositoryConfigInfo(repo.root), terminal = ui();
   let values = initial;
   if (!initial.json) { terminal.banner(); terminal.section('Repository setup'); terminal.note(repo.root); }
@@ -308,7 +341,7 @@ async function initCommand(initial) {
     }
   }
   const overrides = {};
-  for (const key of ['level']) if (values[key] !== undefined) overrides[key] = values[key];
+  for (const key of ['level', 'distance']) if (values[key] !== undefined) overrides[key] = values[key];
   for (const key of ['branches', 'events', 'remotes']) if (values[key] !== undefined) overrides[key] = splitList(values[key]);
   let context = values.context;
   if (context === undefined && !initial.yes && !initial.json && process.stdin.isTTY && !(await loadProjectContext(repo.root)).text) {
@@ -430,6 +463,8 @@ async function statusCommand(command, values) {
   terminal.section('Configured checkpoints'); printConfiguration(terminal, config, { routes: false });
   if (preparation) terminal.rows([['Background review', preparation.status], ...(preparation.error ? [['Details', preparation.error]] : [])]);
   if (!active) { terminal.blank(); terminal.warning('Policy alone does not install hooks. Use sphinx install, or sphinx install --repo when this repository overrides core.hooksPath.'); }
+  const score = scoreSummary(await readStats(repo.root));
+  terminal.rows([['Understanding', score.calibrating ? `Calibrating · ${score.answered} of ${score.answered + score.needed} answers` : `${score.accuracy}% first try · ${score.answered} questions${score.streak > 1 ? ` · ${score.streak} in a row` : ''}${score.skipRate !== null ? ` · skipped ${score.skipRate}% of checks` : ''}`]]);
   if (yolo) { terminal.blank(); terminal.warning(`Yolo mode is on ${yolo.scope === 'repo' ? 'for this repository' : 'globally'} since ${yolo.since}: checks are skipped. Run sphinx yolo${yolo.scope === 'global' ? ' outside a repository' : ''} to turn it off.`); }
   terminal.section('Pending assessments'); printPending(terminal, pending);
   if (overrides.length) { terminal.section('Recent overrides'); terminal.rows(overrides.map(row => [row.at, `${row.kind}${row.target ? ` · ${row.target}` : ''}${row.reason ? ` · ${row.reason}` : ''}`])); }
@@ -440,9 +475,9 @@ 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' }, 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' }, 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' }, worker: { type: 'boolean' }, retry: { type: 'boolean' }, reason: { type: 'string' }, 'base-url': { type: 'string' }, 'cli-billing': { type: 'string' },
+    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' },
   } });
   const [command, id] = positionals;
@@ -513,7 +548,7 @@ export async function main(argv) {
     return result.checks.every(check => check.ok) ? 0 : 1;
   }
   if (command === 'config') {
-    if (MODEL_FLAGS.some(key => values[key] !== undefined)) {
+    if ([...MODEL_FLAGS, 'distance'].some(key => values[key] !== undefined)) {
       const current = await loadConfig(), previousMaxModelCalls = current.maxModelCalls;
       const config = applyInstallOptions(current, values), maxModelCalls = config.maxModelCalls;
       await saveConfig(config);
@@ -546,6 +581,11 @@ export async function main(argv) {
     terminal.blank(); terminal.note('Use sphinx config --preset <name> to choose evaluator models, or --max-model-calls <1-100|unlimited> to set or clear an optional call cap. See sphinx config --help for tier overrides and paid routes.'); return 0;
   }
   if (command === 'check') return checkCommand(values);
+  if (command === 'usage') {
+    const summary = { ledger: usageDir(process.env), ...summarizeUsage(readUsage()) };
+    if (values.json) json(summary); else printUsage(ui(), summary, { ledgerPath: summary.ledger });
+    return 0;
+  }
   if (command === 'yolo') {
     const repo = await git.repository(process.cwd()).catch(() => null);
     const result = await toggleYolo({ repoRoot: repo?.root ?? null, reason: values.reason });

package/src/config.js

@@ -9,12 +9,12 @@ export const PROVIDERS = Object.freeze(['openrouter', 'codex', 'claude', 'openai
 
 export const DEFAULT_CONFIG = {
   version: 1, enabled: true, provider: 'openrouter', model: 'openrouter/free',
-  level: 'standard', mode: 'block', events: ['pre-push'],
+  level: 'standard', distance: 'high', mode: 'block', 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,
+  backgroundPreparation: true, preparationDebounceMs: 1500, workingContext: true,
   models: {
     small: { provider: 'openrouter', model: 'openrouter/free' },
     medium: { provider: 'openrouter', model: 'openrouter/free' },
@@ -72,8 +72,8 @@ export function validateConfig(config) {
   const allowed = new Set(Object.keys(DEFAULT_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']) if (typeof config[key] !== 'boolean') fail(`${key} must be boolean`);
-  for (const [key, values] of Object.entries({ provider: PROVIDERS, level: ['relaxed','standard','thorough'], mode: ['block'], cliBilling: ['plan','api'] })) {
+  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'] })) {
     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(', ')}`);
   }
@@ -110,7 +110,7 @@ function merged(base, overrides) {
   return { ...base, ...overrides, models: { ...base.models, ...overrides?.models }, routing: { ...base.routing, ...overrides?.routing } };
 }
 
-export const REPOSITORY_CONFIG_KEYS = Object.freeze(['version','enabled','level','mode','events','branches','remotes','exclude','backgroundPreparation']);
+export const REPOSITORY_CONFIG_KEYS = Object.freeze(['version','enabled','level','distance','mode','events','branches','remotes','exclude','backgroundPreparation']);
 
 export function validateRepositoryConfig(local, { env = process.env, source = '.sphinxconfig' } = {}) {
   if (!local || typeof local !== 'object' || Array.isArray(local)
@@ -182,7 +182,7 @@ export function policyHash(config) {
   // checkpoint identity within the same assessment contract.
   // Version the contract when assessment semantics change: older questions and
   // receipts must not stand in for an assessment under the new requirements.
-  return createHash('sha256').update(stableStringify({ ...config, maxModelCalls: 10, agentMaxTurns: 8, cliBilling: 'plan', assessmentContract: 3 })).digest('hex');
+  return createHash('sha256').update(stableStringify({ ...config, maxModelCalls: 10, agentMaxTurns: 8, cliBilling: 'plan', workingContext: true, assessmentContract: 3 })).digest('hex');
 }
 
 const isRecord = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value);

package/src/cursor-hook.js

@@ -11,8 +11,8 @@ try {
     input += chunk;
   }
   const payload = JSON.parse(input || '{}');
-  const { hook_event_name, session_id, conversation_id, cwd, tool_name, tool_output, error_message } = payload;
-  process.stdout.write(`${JSON.stringify(await cursorAgentHook({ input: { hook_event_name, session_id, conversation_id, cwd, tool_name, tool_output, error_message } }))}\n`);
+  const { hook_event_name, session_id, conversation_id, cwd, workspace_roots, tool_name, tool_output, error_message } = payload;
+  process.stdout.write(`${JSON.stringify(await cursorAgentHook({ input: { hook_event_name, session_id, conversation_id, cwd, workspace_roots, tool_name, tool_output, error_message } }))}\n`);
 } catch {
   process.stdout.write(`${JSON.stringify({ additional_context: 'Sphinx could not inspect this hook event. The human can run sphinx doctor and sphinx check in their own terminal.' })}\n`);
 }