sphinx-understand 0.1.4 → 0.1.6

package/src/git-gate.js

@@ -5,6 +5,8 @@ import { createSessionStore } from './sessions.js';
 import { queuePresentation, claimPresentation, listPresentations } from './presentations.js';
 import { createBrowserInterview } from './browser-interview.js';
 import { yoloStatus, recordOverride } from './overrides.js';
+import { dropContext } from './working-context.js';
+import { collectGarbage } from './storage.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 });
@@ -35,6 +37,11 @@ export async function runGitGate({ event, args = [], input = '', cwd = process.c
   const config = await readConfig(repo.root, env);
   const snapshots = await collectSnapshots({ event, args, input, cwd, config, env });
   if (!snapshots.length) return 0;
+  // Once Git continues, the branch's working context has served its purpose.
+  const finished = async () => {
+    for (const snapshot of snapshots) if (snapshot.event === 'pre-push') await dropContext({ repoRoot: snapshot.repoRoot, sourceRef: snapshot.sourceRef, env }).catch(() => {});
+    await collectGarbage({ env });
+  };
   const validate = async (snapshot, expected) => {
     signal?.throwIfAborted();
     const current = await readConfig(snapshot.repoRoot, env);
@@ -48,6 +55,7 @@ export async function runGitGate({ event, args = [], input = '', cwd = process.c
   if (yolo) {
     for (const snapshot of snapshots) await logOverride({ kind: 'yolo', repoRoot: repo.root, target: snapshot.target.ref, id: snapshot.id, head: snapshot.head, reason: yolo.reason }, env);
     output(`Sphinx: yolo mode is on ${yolo.scope === 'repo' ? 'for this repository' : 'globally'}; skipping the understanding check. Run sphinx yolo${yolo.scope === 'global' ? ' outside a repository' : ''} to turn it off.`);
+    await finished();
     return 0;
   }
   const store = providedStore ?? createSessionStore({ env, validate });
@@ -56,6 +64,7 @@ export async function runGitGate({ event, args = [], input = '', cwd = process.c
     signal?.throwIfAborted();
     if (await store.approved(snapshot, config)) continue;
     const session = await store.ensure(snapshot, config);
+    if (await store.passTrivial?.(session.id, config)) { output(`Sphinx: documentation-only change to ${snapshot.target.ref}; no questions needed.`); continue; }
     pending.push({ snapshot, session });
     output(`Sphinx: understanding check needed for ${snapshot.target.ref} (${session.route.tier} change).`);
   }
@@ -106,7 +115,9 @@ export async function runGitGate({ event, args = [], input = '', cwd = process.c
       }
     }
     signal?.throwIfAborted();
-    if (requests.length) output('Sphinx: understanding check complete. Continuing this Git operation.');
+    // 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.');
+    await finished();
     return 0;
   } finally {
     // A paused or cancelled batch must not reopen from an after-tool callback.

package/src/help.js

@@ -68,8 +68,8 @@ export const HELP = {
     summary: 'Set up a repository policy and content exclusions.',
     usage: 'sphinx init [options]',
     paragraphs: ['Creates .sphinxconfig (JSON policy), .sphinxignore, and .sphinxcontext.md (project purpose, workflows, and architecture). The reviewer receives project context every time. Existing files are preserved. Defaults inherit your effective global policy, not the current checkout branch.', 'Legacy .sphinx.json policy is copied into a new .sphinxconfig when needed; the original remains. This command does not install hooks, change global settings, or call a model.'],
-    groups: [['Setup', [['--yes', 'Accept inherited defaults without prompts.'], ['--context <description>', 'Initial project context when .sphinxcontext.md does not exist. Otherwise the existing file is preserved.'], ...policy]], ['Output', common]],
-    examples: ['sphinx init', 'sphinx init --yes --branches main', 'sphinx init --events pre-push,pre-commit --level thorough', 'sphinx init --yes --json'],
+    groups: [['Setup', [['--yes', 'Accept inherited defaults without prompts.'], ['--context <description>', 'Initial project context when .sphinxcontext.md does not exist. Otherwise the existing file is preserved.'], ...policy]], ['For coding agents', [['--suggest', 'Print a JSON proposal (branches, ignore paths, context stub) from the repository. Writes nothing.'], ['--apply <file|->', 'Validate a reviewed proposal and write it. Keeps existing files, merges ignore lines, and is safe to rerun.']]], ['Output', common]],
+    examples: ['sphinx init', 'sphinx init --yes --branches main', 'sphinx init --events pre-push,pre-commit --level thorough', 'sphinx init --yes --json', 'sphinx init --suggest --json > proposal.json', 'sphinx init --apply proposal.json --json'],
     footer: 'Destination branches are where a push lands: pushing feature:main matches main. Add sensitive project paths to .sphinxignore before your first assessment.',
   },
   check: {
@@ -92,13 +92,14 @@ export const HELP = {
   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'] },
   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.' },
   auth: { summary: 'Save an OpenRouter key or an OpenAI-compatible endpoint.', usage: 'sphinx auth [--provider openrouter|openai] [--base-url <url>]', paragraphs: ['Prompts for a key with hidden input. The key is stored in a user-only credentials.json file outside repositories; this is a local file, not an OS keychain.', 'For scripts, set OPENROUTER_API_KEY instead. Free models also require a key. Codex/Claude use their own CLI authentication.'], groups: [['Provider', [['--provider openai', 'Save a base URL and API key for any OpenAI chat-completions-compatible server (OpenAI, Groq, Together, vLLM, Ollama, LM Studio). The key is only sent to that URL. For scripts, set SPHINX_OPENAI_BASE_URL and SPHINX_OPENAI_API_KEY.'], ['--base-url <url>', 'Endpoint base URL, e.g. https://api.openai.com/v1. https only, except localhost.']]], ['Output', [common[0]]]], examples: ['sphinx auth'], footer: 'Create a key at https://openrouter.ai/settings/keys. Never put it in .sphinxconfig or commit it to Git.' },
   uninstall: { summary: 'Remove Sphinx integrations and restore previous hooks.', usage: 'sphinx uninstall [--repo]', paragraphs: ['Removes unchanged Sphinx files and agent handlers, preserving unrelated settings and later user edits. Configuration, credentials, and assessment state remain for you to keep or delete.', 'Global uninstall leaves explicit repository integrations in place. Remove those in each repository before removing the npm package.'], groups: [['Scope', [['--repo', 'Remove only this repository’s explicit hook integration.']]], ['Output', [common[0]]]], examples: ['sphinx uninstall --repo', 'sphinx uninstall', 'npm uninstall -g sphinx-understand'], footer: 'Run Sphinx uninstall before npm uninstall. Resolve warnings about preserved handlers that still refer to Sphinx before removing its executable.' },
 };
 
 export function printHelp(ui, command, { json = false } = {}) {
   if (command && !HELP[command]) throw new Error(`Unknown command ${command}. Run sphinx --help.`);
-  const data = command ? { command, ...HELP[command] } : { command: 'sphinx', summary: 'Outsource your thinking, not your understanding.', commands: Object.fromEntries(Object.entries(HELP).map(([name, help]) => [name, help.summary])) };
+  const data = command ? { command, ...HELP[command] } : { command: 'sphinx', summary: 'You can outsource your thinking, but not your understanding.', commands: Object.fromEntries(Object.entries(HELP).map(([name, help]) => [name, help.summary])) };
   if (json) { console.log(JSON.stringify(data, null, 2)); return; }
   if (!command) {
     ui.banner();
@@ -108,7 +109,7 @@ export function printHelp(ui, command, { json = false } = {}) {
     ui.section('At a checkpoint');
     ui.rows([['sphinx check', 'Start or resume the interview.'], ['sphinx pending', 'List unfinished checks.'], ['sphinx explain <id>', 'Get a walkthrough and a new scenario.']]);
     ui.section('Settings and troubleshooting');
-    ui.rows([['sphinx activate', 'Open fresh coding-agent sessions with Sphinx.'], ['sphinx config', 'Inspect effective policy, model routes, and file paths.'], ['sphinx doctor', 'Check Git and agent integrations.'], ['sphinx auth', 'Save an OpenRouter key with hidden input.'], ['sphinx uninstall', 'Restore previous hooks and remove integrations.']]);
+    ui.rows([['sphinx activate', 'Open fresh coding-agent sessions with Sphinx.'], ['sphinx config', 'Inspect effective policy, model routes, and file paths.'], ['sphinx doctor', 'Check Git and agent integrations.'], ['sphinx usage', 'See tokens and spend by model type and purpose.'], ['sphinx auth', 'Save an OpenRouter key with hidden input.'], ['sphinx uninstall', 'Restore previous hooks and remove integrations.']]);
     ui.blank(); ui.paragraph('Use sphinx <command> --help for options and examples. Git uses a local browser questionnaire; client adapters provide native fallback dialogs where supported. Terminal commands also include answer and dispute; use --json for structured output.');
     ui.blank(); ui.note(`Default policy: pushes to main/master · question caps: ${questionCapsText('standard')}. Guided setup helps you choose economical evaluator models.`);
     return;

package/src/install.js

@@ -1,4 +1,5 @@
-import { access, chmod, lstat, mkdir, readFile, readdir, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
+import { access, chmod, lstat, mkdir, readFile, readdir, realpath, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
+import { settingsTarget } from './user-file.js';
 import { constants } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
@@ -22,6 +23,29 @@ const GATED = new Set(['pre-push', 'pre-commit']);
 const PREPARED = new Set(['post-commit', 'post-merge', 'post-rewrite', 'post-checkout']);
 const hash = value => createHash('sha256').update(value).digest('hex');
 const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+/**
+ * The shell command hooks use to run Sphinx. Prefer the package manager's own
+ * `sphinx` on PATH (an npm/yarn symlink or a pnpm/bun shim): it survives
+ * upgrades, unlike a versioned store path. Node's directory is put first on
+ * PATH so GUI-launched agents without a login PATH still find node. A checkout
+ * without such a shim falls back to absolute node and CLI paths.
+ * Returns shell `env` assignments (placed before any exec) and the `command`.
+ */
+export async function sphinxLauncher(cliPath, env = process.env, execPath = process.execPath) {
+  const real = await realpath(cliPath).catch(() => cliPath);
+  for (const directory of String(env.PATH || '').split(path.delimiter).filter(dir => path.isAbsolute(dir))) {
+    const candidate = path.join(directory, 'sphinx');
+    try {
+      const info = await stat(candidate);
+      if (!info.isFile() || !(info.mode & 0o111)) continue;
+      const matches = await realpath(candidate) === real
+        || (info.size < 64 * 1024 && (await readFile(candidate, 'utf8')).includes('sphinx-understand/bin/sphinx.js'));
+      if (matches) return { env: `PATH=${quote(path.dirname(execPath))}:"$PATH" `, command: quote(candidate) };
+    } catch { /* Not a usable shim. */ }
+  }
+  return { env: '', command: `${quote(execPath)} ${quote(cliPath)}` };
+}
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const AGENTS = ['codex', 'claude', 'pi', 'cursor', 'opencode'];
 
@@ -55,8 +79,7 @@ async function exists(file) {
 
 async function readJson(file, fallback) {
   try {
-    if ((await lstat(file)).isSymbolicLink()) throw new Error(`Refusing to replace symlink: ${file}`);
-    const value = JSON.parse(await readFile(file, 'utf8'));
+    const value = JSON.parse(await readFile((await settingsTarget(file)).path, 'utf8'));
     if (!value || Array.isArray(value) || typeof value !== 'object') throw new Error('expected an object');
     return value;
   } catch (error) {
@@ -66,7 +89,9 @@ async function readJson(file, fallback) {
   }
 }
 
-async function writeJson(file, value) {
+async function writeJson(link, value) {
+  // Write through a dotfiles symlink to its target, atomically, keeping the link.
+  const file = (await settingsTarget(link)).path;
   await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
   const mode = await stat(file).then(s => s.mode & 0o777).catch(() => 0o600);
   const temporary = `${file}.${randomUUID()}.tmp`;
@@ -119,15 +144,15 @@ function sourceShell(source) {
     : 'if ! hook_dir=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null); then\n  if [ -z "${GIT_DIR:-}" ] || [ ! -d "$GIT_DIR" ]; then\n    git rev-parse --git-common-dir >/dev/null\n    exit 128\n  fi\n  hook_dir=$GIT_DIR\nfi\nhook_dir="$hook_dir/hooks"\n';
 }
 
-function hookScript({ event, source, cliPath, home, id }) {
+function hookScript({ event, source, launcher, home, id }) {
   const header = '#!/bin/sh\n# Managed by Sphinx. Existing hooks remain in their original directory.\n';
   if (GATED.has(event)) {
-    return `${header}SPHINX_HOME=${quote(home)} SPHINX_INSTALL_ID=${quote(id)} exec ${quote(process.execPath)} ${quote(cliPath)} hook git ${quote(event)} "$@"\n`;
+    return `${header}SPHINX_HOME=${quote(home)} SPHINX_INSTALL_ID=${quote(id)} ${launcher.env}exec ${launcher.command} hook git ${quote(event)} "$@"\n`;
   }
   if (PREPARED.has(event)) {
     // The existing hook retains streaming stdin and its exit status. Scheduling
     // has no terminal, runs asynchronously, and never gates the Git operation.
-    return `${header}${sourceShell(source)}hook="$hook_dir/${event}"\nstatus=0\nif [ -x "$hook" ]; then\n  "$hook" "$@"\n  status=$?\nfi\nif [ "\${SPHINX_EVALUATOR:-}" != "1" ]; then\n  SPHINX_HOME=${quote(home)} ${quote(process.execPath)} ${quote(cliPath)} prepare </dev/null >/dev/null 2>&1 &\nfi\nexit "$status"\n`;
+    return `${header}${sourceShell(source)}hook="$hook_dir/${event}"\nstatus=0\nif [ -x "$hook" ]; then\n  "$hook" "$@"\n  status=$?\nfi\nif [ "\${SPHINX_EVALUATOR:-}" != "1" ]; then\n  SPHINX_HOME=${quote(home)} ${launcher.env}${launcher.command} prepare </dev/null >/dev/null 2>&1 &\nfi\nexit "$status"\n`;
   }
   // Protocol hooks such as proc-receive must retain streaming stdin/stdout.
   // They exec the prior hook directly rather than buffering input in Node.
@@ -169,7 +194,7 @@ export async function detectAgents({ env = process.env } = {}) {
   return detectedAgents({ paths, env, manifest });
 }
 
-async function prepareAgents({ agents, paths, env, cliPath, manifest }) {
+async function prepareAgents({ agents, paths, env, cliPath, launcher, manifest }) {
   const selected = agents === 'auto'
     ? await detectedAgents({ paths, env, manifest })
     : agents === 'none' ? [] : Array.isArray(agents) ? agents : agents.split(',').map(x => x.trim());
@@ -178,13 +203,13 @@ async function prepareAgents({ agents, paths, env, cliPath, manifest }) {
   for (const name of new Set(selected)) {
     if (['pi', 'cursor', 'opencode'].includes(name)) {
       const prepare = name === 'pi' ? preparePiIntegration : name === 'cursor' ? prepareCursorIntegration : prepareOpenCodeIntegration;
-      result.push(await prepare(paths, { env, cliPath, previous: manifest.agents[name] }));
+      result.push(await prepare(paths, { env, cliPath, launcher, previous: manifest.agents[name] }));
       continue;
     }
     const file = path.join(paths[`${name}Home`], name === 'codex' ? 'hooks.json' : 'settings.json');
     const document = await readJson(file, {});
     if (document.hooks !== undefined && (!document.hooks || typeof document.hooks !== 'object' || Array.isArray(document.hooks))) throw new Error(`Invalid hooks object in ${file}`);
-    const command = `SPHINX_HOME=${quote(paths.home)} ${quote(process.execPath)} ${quote(cliPath)} hook agent ${name}`;
+    const command = `SPHINX_HOME=${quote(paths.home)} ${launcher.env}${launcher.command} hook agent ${name}`;
     const handler = { type: 'command', command, timeout: 10 };
     const hooks = nativeHookSpecs(name, handler);
     for (const { event } of hooks) {
@@ -218,7 +243,8 @@ export async function install({ config, agents = 'auto', repo = false, cwd = pro
   const id = info.id;
   const previous = manifest.installs[id];
   // Validate every selected settings file before mutating any integration.
-  const agentPlans = await prepareAgents({ agents, paths, env, cliPath, manifest });
+  const launcher = await sphinxLauncher(cliPath, env);
+  const agentPlans = await prepareAgents({ agents, paths, env, cliPath, launcher, manifest });
   const scopeValues = await currentConfig(info.scope, cwd, env);
   if (previous && scopeValues.at(-1) !== previous.hookDir) {
     throw new Error('Git hooks changed since Sphinx was installed. Run sphinx uninstall first; your current configuration will be preserved.');
@@ -235,7 +261,7 @@ export async function install({ config, agents = 'auto', repo = false, cwd = pro
   });
   if (directoryState?.isSymbolicLink()) throw new Error(`Refusing to replace a symlinked hook directory: ${entry.hookDir}`);
   const names = await hookNames(entry.source, cwd, env);
-  const scripts = names.map(event => ({ event, content: hookScript({ event, source: entry.source, cliPath, home: paths.home, id }) }));
+  const scripts = names.map(event => ({ event, content: hookScript({ event, source: entry.source, launcher, home: paths.home, id }) }));
   for (const { event, content } of scripts) {
     const file = path.join(entry.hookDir, event);
     const fileState = await lstat(file).catch(error => {

package/src/lifecycle-integrations.js

@@ -1,10 +1,12 @@
 import path from 'node:path';
+import { settingsTarget } from './user-file.js';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { lstat, readFile, mkdir, writeFile, rename, rm, stat } from 'node:fs/promises';
 import { createHash, randomUUID } from 'node:crypto';
 import { listPresentations, claimPresentation } from './presentations.js';
 import { launchCheckpointTerminal, waitForCheckpointTerminal } from './terminal-launch.js';
 import { createBrowserInterview } from './browser-interview.js';
+import { setupNudge } from './repo-setup.js';
 
 const hash = value => createHash('sha256').update(value).digest('hex');
 const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
@@ -36,9 +38,9 @@ export function lifecycleHome(name, paths, env = process.env) {
 
 async function text(file) {
   try {
-    const info = await lstat(file);
-    if (!info.isFile() || info.isSymbolicLink() || info.size > 4 * 1024 * 1024) throw new Error(`Refusing to replace a symlink, non-file, or oversized integration: ${file}`);
-    return await readFile(file, 'utf8');
+    const target = (await settingsTarget(file)).path, info = await lstat(target);
+    if (!info.isFile() || info.size > 4 * 1024 * 1024) throw new Error(`Refusing to replace a non-file or oversized integration: ${file}`);
+    return await readFile(target, 'utf8');
   } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
 }
 
@@ -55,8 +57,10 @@ function json(content, file) {
   catch { throw new Error(`Cannot read ${file}: invalid JSON object. Fix the file and try again.`); }
 }
 
-async function write(file, content) {
-  if (content === null) { await rm(file, { force: true }); return; }
+async function write(link, content) {
+  const { path: file, linked } = await settingsTarget(link);
+  if (content === null && !linked) { await rm(file, { force: true }); return; }
+  content ??= '';
   await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
   const mode = await stat(file).then(info => info.mode & 0o777).catch(() => 0o600);
   const temporary = `${file}.${randomUUID()}.tmp`;
@@ -77,14 +81,17 @@ function plan({ name, file, before, after, record }) {
 }
 
 /** Cursor exposes command hooks, but no documented hook that invokes MCP forms. */
-export async function prepareCursorIntegration(paths, { env = process.env, previous } = {}) {
+export async function prepareCursorIntegration(paths, { env = process.env, previous, launcher } = {}) {
   const home = lifecycleHome('cursor', paths, env), file = path.join(home, 'hooks.json');
   await checkDirectories(home, file);
   if (previous && previous.file !== file) throw new Error('Cursor integration home changed. Uninstall from the original home before reinstalling.');
   const before = await text(file), document = json(before, file);
   if (document.version !== undefined && document.version !== 1) throw new Error(`Unsupported Cursor hooks version in ${file}`);
   if (document.hooks !== undefined && !object(document.hooks)) throw new Error(`Invalid hooks object in ${file}`);
-  const command = `SPHINX_HOME=${quote(paths.home)} ${quote(process.execPath)} ${quote(fileURLToPath(new URL('./cursor-hook.js', import.meta.url)))}`;
+  // Through the stable sphinx launcher when available, so package upgrades keep working.
+  const command = launcher
+    ? `SPHINX_HOME=${quote(paths.home)} ${launcher.env}${launcher.command} hook cursor`
+    : `SPHINX_HOME=${quote(paths.home)} ${quote(process.execPath)} ${quote(fileURLToPath(new URL('./cursor-hook.js', import.meta.url)))}`;
   const hooks = [
     { event: 'sessionStart', handler: { command, timeout: 10 } },
     { event: 'postToolUse', handler: { command, timeout: 1800, matcher: '^Shell$' } },
@@ -226,7 +233,10 @@ export async function browserHandoff({ cwd, host, hostSession, checkpointIds, en
 export async function cursorAgentHook({ input = {}, env = process.env, handoff = browserHandoff } = {}) {
   if (env.SPHINX_EVALUATOR === '1') return {};
   const event = input.hook_event_name;
-  if (event === 'sessionStart') return { additional_context: TERMINAL_GUIDANCE, ...(sessionId(input.session_id || input.conversation_id) ? { env: { SPHINX_CURSOR_SESSION: sessionId(input.session_id || input.conversation_id) } } : {}) };
+  if (event === 'sessionStart') {
+    const nudge = await setupNudge(typeof input.cwd === 'string' ? input.cwd : input.workspace_roots?.[0]);
+    return { additional_context: nudge ? `${TERMINAL_GUIDANCE}\n${nudge}` : TERMINAL_GUIDANCE, ...(sessionId(input.session_id || input.conversation_id) ? { env: { SPHINX_CURSOR_SESSION: sessionId(input.session_id || input.conversation_id) } } : {}) };
+  }
   if (!['postToolUse', 'postToolUseFailure'].includes(event) || input.tool_name !== 'Shell') return {};
   try {
     const checkpointIds = cursorCheckpointIds(input);

package/src/openrouter.js

@@ -14,7 +14,7 @@ const failureAdvice = {
   401: 'API key was rejected. Run sphinx auth.',
   402: 'OpenRouter account has insufficient credits.',
   404: 'No compatible provider was available for this request. Select a route supporting JSON schema or retry later.',
-  429: 'Provider or account rate limit reached. Wait before retrying; Sphinx will not switch models.',
+  429: 'Provider or account rate limit reached. Wait before retrying, or switch this check to your Claude Code or Codex plan when offered.',
   503: 'Selected model is unavailable. Retry later or explicitly select another route.',
 };
 
@@ -226,7 +226,7 @@ async function requestOpenRouter({messages, schema, tools, toolChoice, config, e
   if (!data || typeof data!=='object' || Array.isArray(data)) throw new Error(`${name} returned an invalid response object.`);
   requestSignal.throwIfAborted();
   // Billed even when the choice is later rejected, so record it first.
-  reportUsage({ inputTokens: data.usage?.prompt_tokens, outputTokens: data.usage?.completion_tokens, cost: data.usage?.cost });
+  reportUsage({ inputTokens: data.usage?.prompt_tokens, outputTokens: data.usage?.completion_tokens, cost: data.usage?.cost, provider: openai ? 'openai' : 'openrouter', model });
   return requireFinishedChoice(data, config, Boolean(tools), response.headers);
 }
 

package/src/preparation.js

@@ -8,6 +8,8 @@ import { getPaths, loadConfig, policyHash, readJson, writeJson } from './config.
 import { matches, pushSnapshots, repository, revalidateSnapshot } from './git.js';
 import { yoloStatus } from './overrides.js';
 import { createSessionStore } from './sessions.js';
+import { curateQuietly } from './working-context.js';
+import { collectGarbage } from './storage.js';
 
 const exec = promisify(execFile);
 const digest = value => createHash('sha256').update(value).digest('hex');
@@ -196,7 +198,7 @@ export async function schedulePreparation({ cwd = process.cwd(), env = process.e
   });
 }
 
-export async function runPreparation({ cwd = process.cwd(), env = process.env, config, store, generate, wait = delay } = {}) {
+export async function runPreparation({ cwd = process.cwd(), env = process.env, config, store, generate, wait = delay, curate } = {}) {
   if (env.SPHINX_EVALUATOR === '1') return { status: 'skipped', prepared: [], reason: 'Evaluator subprocesses do not prepare assessments.' };
   const repo = await repository(cwd), files = filesFor(repo.root, env);
   const latest = await readJson(files.latest, null);
@@ -219,6 +221,7 @@ export async function runPreparation({ cwd = process.cwd(), env = process.env, c
     claimed.status = status; claimed.updatedAt = new Date().toISOString();
     if (errorCode) claimed.errorCode = errorCode;
     await locked(files, () => writeJson(files.job(id), claimed));
+    await collectGarbage({ env });
     return { status, prepared: claimed.prepared, ...(errorCode ? { error: errors[errorCode] } : {}) };
   };
   // Yolo can be turned on while this worker runs. Every reviewer request
@@ -237,6 +240,10 @@ export async function runPreparation({ cwd = process.cwd(), env = process.env, c
       const effective = await loadConfig(snapshot.repoRoot, env);
       if (policyHash(effective) !== policyHash(currentConfig) || !await revalidateSnapshot(snapshot, effective, { env })) throw new Error('The snapshot or policy changed before preparation.');
     } });
+    // One cheap free-model call keeps the branch's working context current, so
+    // the review below and the one at push time start already oriented.
+    const lead = plan.snapshots[0];
+    await curateQuietly({ repoRoot: repo.root, sourceRef: lead.sourceRef, base: lead.base, head: lead.head, config: plan.config, env, wait, call: curate });
     for (const snapshot of plan.snapshots) {
       const current = await readJson(files.latest, null);
       if (current?.id !== id) return finish('stale');