sphinx-understand 0.1.4 → 0.1.5

package/README.md

@@ -4,6 +4,11 @@
 
 <p align="center"><em>Outsource your thinking, 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>
+
+<p align="center"><b>Works with</b> Claude Code · Codex · Cursor · OpenCode · Pi · or a plain <code>git push</code><br>
+<b>Reviews run on</b> your Claude Code or Codex plan · OpenRouter · any OpenAI-compatible endpoint</p>
+
 Sphinx adds an understanding check to agent-assisted development. When you push to a protected branch, Git waits while Sphinx asks you to predict what your change will do. If you miss something, it explains and gives you a new scenario to try. Once you pass, the same push continues. This works whether you or a coding agent ran `git push`.
 
 The questions come from a separate reviewer model. It reads the committed change through read-only Git tools and does not see the conversation that produced the code.
@@ -56,6 +61,8 @@ You should see:
 
 Use `--preset codex-economy` for Codex, or `--agents none` if you don't use a coding agent. Other presets, OpenRouter, OpenAI-compatible endpoints, and custom routes are covered in [configuration](docs/configuration.md#reviewer-models).
 
+Settings files symlinked into a dotfiles repository (Stow, Dotbot, chezmoi, home-manager) are supported: Sphinx edits the link's target in place and keeps the link. Hooks call the `sphinx` command your package manager installed (npm, pnpm, yarn, or Bun), so upgrading the package keeps them working.
+
 ### 2. Load Sphinx in your coding agent (required if you use one)
 
 Guided setup opens your selected agents in fresh sessions. Then:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphinx-understand",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Outsource your thinking, not your understanding. A comprehension checkpoint for agent-assisted development.",
   "homepage": "https://github.com/parthh01/sphinx#readme",
   "repository": {
@@ -29,6 +29,7 @@
     "src",
     "scripts/postinstall.js",
     "docs",
+    "!docs/demo.gif",
     "eval/RESULTS.md",
     "eval/fixtures/known-false-negatives.json",
     "examples",

package/src/agent-settings.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { settingsTarget } from './user-file.js';
 import { lstat, readFile, mkdir, writeFile, rename, rm, stat } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 
@@ -8,8 +9,7 @@ const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 
 async function readText(file) {
   try {
-    if ((await lstat(file)).isSymbolicLink()) throw new Error(`Refusing to replace symlink: ${file}`);
-    return await readFile(file, 'utf8');
+    return await readFile((await settingsTarget(file)).path, 'utf8');
   } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
 }
 
@@ -22,8 +22,11 @@ function parseJson(text, file) {
   } catch { throw new Error(`Cannot read ${file}: invalid JSON object. Fix the file and try again.`); }
 }
 
-async function writeText(file, text) {
-  if (text === null) { await rm(file, { force: true }); return; }
+async function writeText(link, text) {
+  const { path: file, linked } = await settingsTarget(link);
+  // Never delete a dotfiles target through its link; leave it empty instead.
+  if (text === null && !linked) { await rm(file, { force: true }); return; }
+  text ??= '';
   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`;

package/src/browser-interview.js

@@ -1,11 +1,12 @@
 import { createServer } from 'node:http';
+import { planProviders } from './evaluator.js';
 import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { spawn } from 'node:child_process';
 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 } from './check-recovery.js';
+import { prepareInteractiveCheck, isRateLimit, 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';
@@ -51,7 +52,7 @@ function publicFields(state) {
 export function createBrowserInterview({ env = process.env, signal, timeoutMs = 25 * 60 * 1000,
   store: providedStore, readConfig = loadConfig, revalidate = revalidateSnapshot,
   reserve = claimCheckpointDialog, release = finishCheckpointDialog, waitForExisting = waitForCheckpointTerminal,
-  openBrowser = openQuestionnaireBrowser, output = line => process.stderr.write(`${line}\n`), logOverride = recordOverride,
+  openBrowser = openQuestionnaireBrowser, output = line => process.stderr.write(`${line}\n`), logOverride = recordOverride, findPlans = planProviders,
   loadView = loadChangeView,
 } = {}) {
   const token = randomBytes(32).toString('base64url'), nonce = randomBytes(24).toString('base64');
@@ -259,7 +260,9 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
       await ensureServer(operationEnv);
       const notes = [];
       const recoveryUI = { warning: text => notes.push(text), note: text => notes.push(text), command: () => {} };
+      const plans = await findPlans(operationEnv).catch(() => []);
       visible = await prepareInteractiveCheck({ config, signal: localSignal, waitingGit: request.delivery === 'hook', ui: recoveryUI,
+        planProviders: plans, switchRoute: provider => store.switchRoute(request.id, config, provider, { signal: localSignal }),
         inspect: async () => store.public(await store.read(request.id)),
         validate: () => validate(session.snapshot, config),
         authorizeMore: () => store.retryReview(request.id, config, { signal: localSignal }),
@@ -308,6 +311,17 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
           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) {
+            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));
+            if (picked.action.startsWith('switch-')) {
+              const provider = picked.action.slice('switch-'.length);
+              visible = await store.switchRoute(request.id, config, provider, { signal: localSignal });
+              say({ role: 'sphinx', kind: 'notice', text: `Switched this check to ${PLAN_NAMES[provider][0]}. Send your answer again.` });
+              continue;
+            }
+          }
           publish({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'question', error: error.message, message: 'Your response was not accepted. Review the error before submitting again.' });
           // Re-display through waitForAction on the next iteration; never resend.
           visible = { ...visible, browserError: error.message };

package/src/check-recovery.js

@@ -4,6 +4,16 @@ import { modelUsageText } from './usage.js';
 const setupCodes = new Set(['INVALID_CONFIG', 'INVALID_SNAPSHOT', 'STALE_SNAPSHOT', 'CONTEXT_LIMIT', 'TOOL_RESULT_LIMIT', 'OUTPUT_LIMIT', 'PROVIDER_NOT_FOUND', 'PROVIDER_START_FAILED', 'PROVIDER_FAILED']);
 const setupTypes = new Set(['authentication', 'permission_denied', 'payment_required', 'context_length_exceeded', 'max_tokens_exceeded', 'token_limit_exceeded', 'string_too_long', 'invalid_request', 'invalid_prompt', 'not_found', 'precondition_failed', 'payload_too_large', 'unprocessable', 'content_policy_violation', 'refusal']);
 
+/** A rate limit from an API route that a signed-in coding-agent plan could take over. */
+export const isRateLimit = (error, route) => ['openrouter', 'openai'].includes(route?.provider)
+  && (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 => ({
+  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.`,
+}));
+
 function retryable(error, before, state, minimum) {
   if (setupCodes.has(error.code) || setupTypes.has(error.errorType)) return false;
   if (error.code === 'OPENROUTER_PROVIDER_ERROR' && [400, 401, 402, 403, 404, 413, 422].includes(error.status)) return false;
@@ -33,7 +43,7 @@ function diagnostic(error, state) {
  * chooses to retry, expands a budget, changes a route, or awards completion on
  * its own. inspect() exposes public state only; validate() checks current Git
  * content and policy before a recovery choice is shown. */
-export async function prepareInteractiveCheck({ start, inspect, authorizeMore, validate, config, choose, ui, waitingGit = false, signal }) {
+export async function prepareInteractiveCheck({ start, inspect, authorizeMore, validate, config, choose, ui, waitingGit = false, signal, planProviders = [], switchRoute }) {
   for (;;) {
     signal?.throwIfAborted();
     const before = await inspect();
@@ -64,6 +74,9 @@ export async function prepareInteractiveCheck({ start, inspect, authorizeMore, v
           description: `${remaining} calls remain; review needs at least ${reviewMinimum} plus ${reserve} reserved for grading. Keep all ${state.usage.calls} used calls counted and record this new allowance.`,
         });
       }
+      // 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) : [];
+      choices.unshift(...switches);
       if (!choices.length) ui.note('Resolve the reported setup or evidence problem before resuming. Repeating this attempt is not offered here.');
       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({
@@ -80,6 +93,13 @@ export async function prepareInteractiveCheck({ start, inspect, authorizeMore, v
         return null;
       }
       if (!choices.some(choice => choice.value === action)) throw new Error('Invalid review recovery choice. No additional model request was made.');
+      if (action.startsWith('switch-')) {
+        const provider = action.slice('switch-'.length);
+        await switchRoute(provider);
+        signal?.throwIfAborted();
+        ui.note(`Switched this check to ${PLAN_NAMES[provider][0]}. Your saved model settings are unchanged.`);
+        continue;
+      }
       if (action === 'extend') {
         await authorizeMore();
         signal?.throwIfAborted();

package/src/cli.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { planProviders } from './evaluator.js';
 import { VERSION } from './version.js';
 import { fileURLToPath } from 'node:url';
 import { lstat } from 'node:fs/promises';
@@ -381,6 +382,8 @@ async function checkCommand(values) {
       validate: () => validateCheckpoint(session.snapshot, config), config,
       choose: createPrompts({ ask, ui: terminal }).choose, ui: terminal,
       waitingGit: process.env.SPHINX_WAITING_GIT === '1', signal,
+      planProviders: await planProviders().catch(() => []),
+      switchRoute: provider => store.switchRoute(session.id, config, provider, { signal }),
     });
     signal.throwIfAborted();
     if (!state) return 1;
@@ -468,6 +471,8 @@ export async function main(argv) {
       const result = await agentHook({ agent: argv[2], input: await readStdin(), cwd: process.cwd(), env: process.env });
       if (result.output) console.log(JSON.stringify(result.output)); return result.exitCode;
     }
+    // Cursor's command hook protocol lives in its own module and runs on import.
+    if (argv[1] === 'cursor') { await import('./cursor-hook.js'); return 0; }
     throw new Error('Unknown hook entry point.');
   }
   const { values, command, id } = parseCommandLine(argv);

package/src/evaluator.js

@@ -227,6 +227,13 @@ async function planSignInProblem(provider, { runner, cwd, env, signal }) {
   return 'Codex is not signed in with a ChatGPT plan, and Sphinx ignores API keys in your environment so reviews bill your plan. Run codex login, or run sphinx config --cli-billing api to use API keys instead.';
 }
 
+/** Coding-agent CLIs installed on PATH that can take over a check on the user's plan. */
+export async function planProviders(env = process.env) {
+  const found = [];
+  for (const name of ['claude', 'codex']) if (await findExecutable(name, env)) found.push(name);
+  return found;
+}
+
 async function findExecutable(command, env) {
   for (const directory of (env.PATH ?? '').split(delimiter).filter(Boolean)) {
     const candidate = resolve(directory, command);

package/src/git-gate.js

@@ -106,7 +106,8 @@ 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.');
     return 0;
   } finally {
     // A paused or cancelled batch must not reopen from an after-tool callback.

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,4 +1,5 @@
 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';
@@ -36,9 +37,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 +56,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 +80,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$' } },

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.',
 };
 

package/src/sessions.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { REVIEWER_PRESETS } from './model-presets.js';
 import { withUsageMeter, addUsage } from './usage.js';
 import { mkdir, open, readdir, stat, unlink } from 'node:fs/promises';
 import { DEFAULT_CONFIG, getPaths, readJson, writeJson, policyHash } from './config.js';
@@ -373,5 +374,29 @@ export function createSessionStore({ env = process.env, generate = generateAsses
       return true;
     });
   }
-  return {ensure,approved,prepare,start,retryReview,refreshBudget,answer,pending,read,skip,discard,public:publicSession};
+  /**
+   * Move one check to a coding agent's signed-in plan, for example after an
+   * OpenRouter rate limit. Only this check changes; saved routes stay as they
+   * are. Unanswered investigation is dropped because its conversation belongs
+   * to the previous transport; existing questions and progress are kept.
+   */
+  async function switchRoute(id, config, provider, { signal } = {}) {
+    if (!['claude', 'codex'].includes(provider)) throw new Error('Only Claude Code or Codex can take over a check on your plan.');
+    return withLock(id, env, async () => {
+      signal?.throwIfAborted();
+      const session = await read(id);
+      if (session.policy !== policyHash(config)) throw new Error('Sphinx settings changed. Start a fresh check.');
+      if (!['pending', 'active'].includes(session.status)) throw new Error('Only an unfinished check can switch models.');
+      const preset = REVIEWER_PRESETS.find(item => item.id === `${provider}-economy`);
+      const model = preset?.models[session.route.tier]?.model ?? null;
+      const at = now();
+      session.routeChanges = [...(session.routeChanges || []), { at, calls: session.calls, from: { provider: session.route.provider, model: session.route.model }, to: { provider, model } }];
+      session.route = { ...session.route, provider, model };
+      if (!session.questions.length) delete session.reviewerCheckpoint;
+      session.updatedAt = at;
+      await save(session);
+      return publicSession(session);
+    });
+  }
+  return {ensure,approved,prepare,start,retryReview,refreshBudget,answer,pending,read,skip,discard,switchRoute,public:publicSession};
 }

package/src/user-file.js

@@ -0,0 +1,23 @@
+import { lstat, realpath, stat } from 'node:fs/promises';
+
+/**
+ * Agent settings are often symlinks into a dotfiles repository (Stow, Dotbot,
+ * chezmoi, home-manager). Resolve a symlink to the user's own regular file so
+ * Sphinx edits that target in place and the link stays intact. A missing file
+ * resolves to itself; anything else that is not the user's regular file fails.
+ */
+export async function settingsTarget(file) {
+  let info;
+  try { info = await lstat(file); } catch (error) { if (error.code === 'ENOENT') return { path: file, linked: false }; throw error; }
+  if (!info.isSymbolicLink()) return { path: file, linked: false };
+  let target;
+  try { target = await realpath(file); }
+  catch (error) {
+    if (error.code === 'ENOENT') throw new Error(`${file} is a symlink to a missing file. Create the target or remove the link, then retry.`);
+    throw error;
+  }
+  const resolved = await stat(target);
+  if (!resolved.isFile()) throw new Error(`${file} links to ${target}, which is not a regular file.`);
+  if (typeof process.getuid === 'function' && resolved.uid !== process.getuid()) throw new Error(`${file} links to ${target}, which you do not own. Sphinx only edits your own files.`);
+  return { path: target, linked: true };
+}