sphinx-understand 0.0.0-stage → 0.1.0

package/eval/fixtures/known-false-negatives.json

@@ -0,0 +1,115 @@
+{
+  "version": 1,
+  "scope": "Synthetic fixture questions and authored answers only. These are known failures, not passing model assertions.",
+  "cases": [
+    {
+      "id": "v18-cosmetic-sufficient-qualitative-answer",
+      "source": {
+        "caseId": "cosmetic",
+        "requiredPaths": [
+          "styles.css",
+          "index.html"
+        ],
+        "definition": {
+          "context": "A task application shares the button class between task-card actions and toolbar actions. This patch should change only card buttons, without changing toolbar controls or click behavior.",
+          "before": {
+            "styles.css": ".button { padding-block: 4px; padding-inline: 12px; }\n",
+            "index.html": "<main><nav class=\"toolbar\"><button class=\"button\">Refresh</button></nav><article class=\"card\"><button class=\"button\">Complete task</button></article></main>\n"
+          },
+          "after": {
+            "styles.css": ".button { padding-block: 4px; padding-inline: 12px; }\n.card .button { padding-block: 8px; }\n"
+          }
+        },
+        "definitionSha256": "50723ddddf259d210e5ce53f4c64bfdf4a0cbc7df6e656aafa0b897da3332085"
+      },
+      "question": {
+        "id": "card-button-padding-scope-qual",
+        "concept": "Scoped descendant selector overriding a shared class across two surfaces",
+        "prompt": "The styles.css diff adds a `.card .button` rule after the base `.button` rule, which sets padding on both axes. index.html has a `.button` inside `nav.toolbar` (Refresh) and a `.button` inside `article.card` (Complete task). For each button, predict whether its vertical padding and its horizontal padding change compared with before the patch, then briefly explain which selector and markup facts determine each outcome.",
+        "choices": [],
+        "evidence": [
+          {
+            "path": "styles.css",
+            "reason": "The diff adds a `.card .button` rule after the base `.button` rule and declares only the block-direction padding in the new rule, so overriding applies to one axis only."
+          },
+          {
+            "path": "index.html",
+            "reason": "Refresh is inside nav.toolbar, outside article.card, so the descendant selector cannot match it; Complete task is inside article.card, so it matches."
+          }
+        ],
+        "acceptance": {
+          "prediction": "Complete task's block-direction (vertical) padding changes while its inline-direction (horizontal) padding stays the same, and Refresh's padding changes on neither axis.",
+          "causalReason": "The .card .button rule matches only the button inside article.card and sets only block-direction padding, so it overrides the base .button value on that axis while the base rule still supplies inline padding."
+        },
+        "expectedAnswer": "Complete task (inside .card): its vertical padding changes, and its horizontal padding does not. The later .card .button rule matches it and has higher specificity than .button, so it wins for the block axis; that rule sets only padding-block, so the inline axis still comes from the base .button rule. Refresh (in nav.toolbar, outside .card): neither axis changes, because .card .button requires a .card ancestor and only the base .button rule matches it.",
+        "rationale": "Causal claims: (1) the new rule is scoped by the .card ancestor, so the toolbar button outside article.card does not match; (2) the descendant selector's higher specificity beats the base .button rule for padding-block where both apply; (3) padding-inline is unchanged because the new rule declares only padding-block, so the base rule still supplies it for the card button. The question asks for a qualitative per-axis prediction and cause, not exact values or specificity numbers. Evidence: the styles.css diff adds the .card .button rule after the base .button rule and sets only padding-block in the new rule; index.html places Refresh in nav.toolbar and Complete task inside article.card."
+      },
+      "answer": "Only buttons inside a card receive the new padding because the new selector requires a card ancestor. The toolbar button shares the button class but is outside a card, so its styling stays unchanged. The base button rule, horizontal padding, and click behavior remain unchanged.",
+      "expectedVerdict": "correct",
+      "observedVerdict": "ambiguous",
+      "observedFeedback": "The question, criteria, and sourceKey match the source: .card .button sets only padding-block, so Complete task's vertical padding changes while its horizontal padding stays from the base rule, and Refresh is unaffected. The answer correctly says the toolbar button and horizontal padding are unchanged and that the new selector needs a card ancestor. It never states that the vertical (block-direction) padding is what changes for Complete task, so the required per-axis prediction is missing. Please state which axis changes for the card button and why.",
+      "independentFinding": "New card padding together with unchanged horizontal padding communicates the vertical change. The answer also explains the card ancestor and unchanged toolbar boundary; requiring the literal word vertical is a false negative.",
+      "provenance": {
+        "run": "V18",
+        "artifact": "sphinx-eval-acceptance-haiku-v18.json",
+        "completedAt": "2026-10-15T23:22:29.682Z",
+        "model": "anthropic/claude-haiku-5.5",
+        "maxOutputTokens": 8192,
+        "sourceSha256": "9bbcff04e1281c1178ce44f14def6f2c7e26b739abd632489060009cf7b65eaf",
+        "note": "Exact legacy V16 candidate after the V18 minimum-criteria audit; not replaced with the later fresh V19 question."
+      }
+    },
+    {
+      "id": "v20-auth-sufficient-response-equivalence",
+      "source": {
+        "caseId": "auth",
+        "requiredPaths": [
+          "auth/document.js"
+        ],
+        "definition": {
+          "context": "A multi-tenant document service. A signed-in user may read only documents belonging to their tenant. Missing documents and denied documents share a 404 response.",
+          "before": {
+            "auth/document.js": "export function getDocument(user, id, documents) { if (!user) return { status: 401 }; const doc = documents.get(id); return doc ? { status: 200, body: doc.text } : { status: 404 }; }\n"
+          },
+          "after": {
+            "auth/document.js": "export function getDocument(user, id, documents) { if (!user) return { status: 401 }; const doc = documents.get(id); if (!doc || doc.tenantId !== user.tenantId) return { status: 404 }; return { status: 200, body: doc.text }; }\n"
+          }
+        },
+        "definitionSha256": "4ed2d01d0cf01d73223c0d35d52961e954818a6394605c1dd78cc0ad886da846"
+      },
+      "question": {
+        "id": "missing-vs-denied-indistinguishable",
+        "concept": "Missing vs. denied response equivalence",
+        "prompt": "Can a signed-in user tell a nonexistent document ID apart from an existing document owned by another tenant by the getDocument response? Answer yes or no and give a short reason.",
+        "choices": [],
+        "expectedAnswer": "No. Both produce the identical { status: 404 } object with no body, because the missing-document case (!doc) and the cross-tenant case (doc.tenantId !== user.tenantId) are combined in one condition and return the same value.",
+        "rationale": "The combined condition returns the same { status: 404 } for both cases, matching the project context that missing and denied documents share a 404. The 401 check runs before the lookup, so unauthenticated callers get 401 regardless of whether the ID exists; that boundary is not asked here.",
+        "evidence": [
+          {
+            "path": "auth/document.js",
+            "reason": "The combined `!doc || doc.tenantId !== user.tenantId` condition returns the same { status: 404 } for both cases."
+          }
+        ],
+        "acceptance": {
+          "prediction": "No, both cases return the same 404 response.",
+          "causalReason": "The single combined condition returns the same { status: 404 } for a missing doc and a tenant mismatch."
+        }
+      },
+      "answer": "A signed-in user can read only a document with the same tenantId. A different tenant gets 404 without document contents, just like a missing id. A caller without a user gets 401 before any document lookup or tenant comparison, because the missing-user guard returns first. Knowing an id or being authenticated is not enough to cross the tenant boundary.",
+      "expectedVerdict": "correct",
+      "observedVerdict": "ambiguous",
+      "observedFeedback": "The source supports the question and its criteria. The combined condition returns the same { status: 404 } for a missing document and a cross-tenant document, so the response does not distinguish them. The answer states that a different tenant gets 404 \"just like a missing id,\" which conveys the outcome, but it never gives an explicit yes or no and does not explain the causal mechanism: that one combined check (!doc || doc.tenantId !== user.tenantId) returns the same value for both cases. Please clarify whether the answer is no and why the single combined condition produces identical responses.",
+      "independentFinding": "A bodyless 404 for a different tenant just like a missing id communicates response equivalence and its causal basis. Naming one combined if statement or adding an explicit no is unnecessary.",
+      "provenance": {
+        "run": "V20",
+        "artifact": "sphinx-eval-live-remaining-haiku-v20.json",
+        "completedAt": "2026-10-15T23:34:17.636Z",
+        "model": "anthropic/claude-haiku-5.5",
+        "maxOutputTokens": 8192,
+        "assessmentContract": 3,
+        "sourceSha256": "d7d13eeafc213420d9f2d999c11a98751613e015eb5556a826920e98eb514661",
+        "note": "Freshly generated and source-audited question with minimum acceptance criteria; failure occurred on the current contract."
+      }
+    }
+  ]
+}

package/examples/browser-demo.mjs

@@ -0,0 +1,28 @@
+// Local UI fixture only: no real Git operation, provider, credentials, or home edits.
+import { mkdtemp, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { createBrowserInterview } from '../src/browser-interview.js';
+import { createSessionStore } from '../src/sessions.js';
+import { DEFAULT_CONFIG } from '../src/config.js';
+
+const home = await mkdtemp(path.join(tmpdir(), 'sphinx-browser-demo-'));
+const repoRoot = path.join(home, 'example-project'); await mkdir(repoRoot);
+const env = { SPHINX_HOME: path.join(home, 'state'), SPHINX_USER_HOME: home }, config = structuredClone(DEFAULT_CONFIG);
+const snapshot = { id: 'd'.repeat(64), repoRoot, event: 'pre-push', target: { ref: 'refs/heads/main' }, files: ['src/queue.js'], stats: { additions: 23, deletions: 0, files: 1 } };
+const question = { id: 'duplicate', concept: 'Duplicate requests', prompt: 'A job finishes successfully, but the caller times out before receiving the response. If the caller retries with the same job ID in the same process, will this change prevent the job from running twice? Explain why.', choices: [], expectedAnswer: 'The process-local set rejects a duplicate until the process restarts.', rationale: 'The set is held in memory.', evidence: [{ path: 'src/queue.js', reason: 'Process-local membership is checked before execution.' }] };
+const store = createSessionStore({ env,
+  generate: async (_snapshot, _config, { beforeCall }) => { await beforeCall(); await delay(300); return { questions: [question] }; },
+  grade: async request => { await request.beforeCall(); await delay(500); return request.learn || request.dispute || /wrong/i.test(request.answer)
+    ? { verdict: request.dispute ? 'ambiguous' : 'incorrect', feedback: 'This set lives in one process. It remembers IDs while that process is running; a restart creates an empty set.', followUp: { ...question, id: randomUUID(), prompt: 'The process restarts after completing a job. The caller retries that job ID. Can the same job run again, and why?' } }
+    : { verdict: 'correct', feedback: 'You connected the behavior to the lifetime of the stored IDs.', followUp: null }; },
+});
+await store.ensure(snapshot, config);
+const controller = new AbortController();
+process.on('SIGINT', () => controller.abort()); process.on('SIGTERM', () => controller.abort());
+const interview = createBrowserInterview({ env, signal: controller.signal, store, readConfig: async () => config, revalidate: async () => true, openBrowser: async () => false, output: console.log });
+console.log('Sphinx browser UI fixture. No real repository, model, or Git approval is involved.');
+try { console.log(await interview.present({ request: { id: snapshot.id, repoRoot, token: randomUUID(), createdAt: Date.now(), delivery: 'hook' } })); }
+finally { await delay(500); await interview.close(); await rm(home, { recursive: true, force: true }); }

package/examples/config.json

@@ -0,0 +1,59 @@
+{
+  "version": 1,
+  "enabled": true,
+  "provider": "openrouter",
+  "model": "anthropic/claude-haiku-5.5",
+  "level": "standard",
+  "mode": "block",
+  "events": [
+    "pre-push"
+  ],
+  "branches": [
+    "main",
+    "master"
+  ],
+  "remotes": [
+    "*"
+  ],
+  "exclude": [],
+  "maxContextBytes": 100000,
+  "timeoutSeconds": 180,
+  "receiptHours": 24,
+  "maxModelCalls": null,
+  "maxOutputTokens": 8192,
+  "allowPaid": true,
+  "agentMaxTurns": null,
+  "toolResultBytes": 16000,
+  "backgroundPreparation": true,
+  "preparationDebounceMs": 1500,
+  "models": {
+    "small": {
+      "provider": "openrouter",
+      "model": "anthropic/claude-haiku-5.5"
+    },
+    "medium": {
+      "provider": "openrouter",
+      "model": "anthropic/claude-haiku-5.5"
+    },
+    "large": {
+      "provider": "openrouter",
+      "model": "anthropic/claude-haiku-5.5"
+    }
+  },
+  "routing": {
+    "smallMaxLines": 80,
+    "smallMaxFiles": 3,
+    "largeMinLines": 400,
+    "largeMinFiles": 12,
+    "riskPatterns": [
+      "auth",
+      "permission",
+      "migration",
+      "billing",
+      "payment",
+      "crypto",
+      "security",
+      "terraform"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "sphinx-understand",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Outsource your thinking, not your understanding. A comprehension checkpoint for agent-assisted development.",
+  "homepage": "https://github.com/parthh01/sphinx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/parthh01/sphinx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/parthh01/sphinx/issues"
+  },
+  "type": "module",
+  "bin": {
+    "sphinx": "bin/sphinx.js"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node scripts/run-suite.mjs",
+    "check": "node --check bin/sphinx.js && node scripts/run-suite.mjs",
+    "start": "node bin/sphinx.js",
+    "eval": "node eval/run.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "eval/RESULTS.md",
+    "eval/fixtures/known-false-negatives.json",
+    "examples",
+    ".sphinxconfig.example",
+    ".sphinxignore.example",
+    "README.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "git",
+    "hooks",
+    "codex",
+    "claude-code",
+    "learning",
+    "code-review"
+  ],
+  "dependencies": {
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0"
+  }
+}

package/src/activation-worker.js

@@ -0,0 +1,10 @@
+import { runActivationTerminal } from './activation.js';
+
+try {
+  const result = await runActivationTerminal({ recordFile: process.argv[2], token: process.argv[3] });
+  process.exitCode = result.code;
+  if (result.status === 'failed') process.stderr.write('Sphinx could not start this coding client. Open it manually in this repository.\n');
+} catch {
+  process.stderr.write('Sphinx could not start this coding client. Run sphinx activate to try again.\n');
+  process.exitCode = 1;
+}

package/src/activation.js

@@ -0,0 +1,187 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { access, lstat, mkdir, open, rm, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { spawn, execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { getPaths, readJson, writeJson } from './config.js';
+import { terminalCommand, spawnTerminal, createTerminalEnvironmentBridge, readTerminalEnvironment } from './terminal-launch.js';
+
+const WORKER = fileURLToPath(new URL('./activation-worker.js', import.meta.url));
+const AGENTS = ['codex', 'claude', 'pi', 'cursor', 'opencode'];
+const TOKEN = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const SESSION_ENV = ['CODEX_THREAD_ID', 'CLAUDECODE', 'CLAUDE_CODE_SESSION_ID', 'CLAUDE_CODE_ENTRYPOINT', 'PI_SESSION_ID', 'SPHINX_CLAUDE_SESSION', 'SPHINX_CURSOR_SESSION', 'SPHINX_OPENCODE_SESSION'];
+const LABELS = { codex: 'Codex', claude: 'Claude Code', pi: 'Pi', cursor: 'Cursor', opencode: 'OpenCode' };
+const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+const desktop = (env, platform) => !env.SSH_CONNECTION && !env.SSH_TTY && !(env.CI && env.CI !== 'false' && env.CI !== '0') && (platform === 'darwin' || (platform === 'linux' && !!(env.DISPLAY || env.WAYLAND_DISPLAY)));
+const freshEnvironment = env => Object.fromEntries(Object.entries(env).filter(([key]) => !SESSION_ENV.includes(key)));
+const fileFor = (home, token) => path.join(home, 'activations', `${token}.json`);
+
+function clientEnvironment(env) {
+  const fresh = freshEnvironment(env);
+  if (!env.SPHINX_USER_HOME) return fresh;
+  const paths = getPaths(env);
+  return { ...fresh, HOME: paths.userHome, CODEX_HOME: paths.codexHome, CLAUDE_CONFIG_DIR: paths.claudeHome, PI_CODING_AGENT_DIR: path.join(paths.userHome, '.pi', 'agent'), OPENCODE_CONFIG_DIR: path.join(paths.userHome, '.config', 'opencode'), XDG_CONFIG_HOME: path.join(paths.userHome, '.config'), XDG_DATA_HOME: path.join(paths.userHome, '.local', 'share'), XDG_STATE_HOME: path.join(paths.userHome, '.local', 'state'), XDG_CACHE_HOME: path.join(paths.userHome, '.cache') };
+}
+
+async function executable(name, env) {
+  for (const directory of (env.PATH || '').split(path.delimiter)) {
+    if (!directory) continue;
+    const file = path.resolve(directory, name);
+    try { if ((await stat(file)).isFile()) { await access(file, constants.X_OK); return file; } } catch {}
+  }
+  return null;
+}
+
+async function cursorExecutable(env, platform, findExecutable) {
+  const fromPath = await findExecutable('cursor', env);
+  if (fromPath || platform !== 'darwin') return fromPath;
+  // Use the editor's own launcher when "Install cursor command" was not run.
+  // Test homes must never fall through to the real machine's Applications.
+  const roots = env.SPHINX_USER_HOME ? [path.join(getPaths(env).userHome, 'Applications')] : ['/Applications', path.join(getPaths(env).userHome, 'Applications')];
+  for (const root of roots) {
+    const file = path.join(root, 'Cursor.app', 'Contents', 'Resources', 'app', 'bin', 'code');
+    try { if ((await stat(file)).isFile()) { await access(file, constants.X_OK); return file; } } catch {}
+  }
+  return null;
+}
+
+async function clientVersion(binary, env) {
+  return new Promise(resolve => {
+    execFile(binary, ['--version'], { env, timeout: 2000, maxBuffer: 4096, encoding: 'utf8' }, (error, stdout) => {
+      if (error) { resolve(null); return; }
+      const match = /^(?:Cursor\s+)?(\d+)\.(\d+)(?:\.(\d+))?(?:[-+][^\s]*)?\s*$/im.exec(stdout);
+      resolve(match ? `${match[1]}.${match[2]}.${match[3] || 0}` : null);
+    });
+  });
+}
+
+async function activationDirectory(home) {
+  const directory = path.join(home, 'activations');
+  const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (info && (info.isSymbolicLink() || !info.isDirectory())) throw new Error('Refusing an unsafe client activation directory.');
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  return directory;
+}
+
+/** Instructions stay in the terminal; they are never submitted as a model prompt. */
+export function activationGuidance(agent) {
+  const steps = {
+    codex: 'In Codex, open /hooks to review and trust the Sphinx hooks.',
+    claude: 'Respond to any Claude setup or MCP permission prompts. Use /mcp to inspect Sphinx.',
+    pi: 'Blocking Git checks use a local browser page. Pi dialogs handle fallback checkpoints.',
+    opencode: 'When Git requires a checkpoint, Sphinx serves a local browser questionnaire without moving your coding window.',
+  };
+  return `Sphinx · ${LABELS[agent]}\n${steps[agent]}\nStarting a fresh session in this repository. No prompt has been submitted.\n\n`;
+}
+
+/** Open configured clients only; the caller supplies the installed selection. */
+export async function activateIntegrations({ agents = [], cwd = process.cwd(), env = process.env, platform = process.platform, findExecutable = executable, readClientVersion = clientVersion, launch = spawnTerminal, environmentBridge = createTerminalEnvironmentBridge, timeoutMs = 20000, pollMs = 50, wait = delay } = {}) {
+  if (!Array.isArray(agents) || agents.some(agent => !AGENTS.includes(agent))) throw new Error('Choose codex, claude, pi, cursor, or opencode for activation.');
+  if (typeof cwd !== 'string' || cwd.includes('\0') || !path.isAbsolute(cwd)) throw new Error('Client activation needs an absolute repository directory.');
+  if (!(await stat(cwd)).isDirectory()) throw new Error('Client activation needs an existing directory.');
+  const home = getPaths(env).home;
+  const results = await Promise.all([...new Set(agents)].map(async agent => {
+    const command = agent === 'cursor' ? `cursor --new-window ${quote(cwd)}` : agent;
+    const result = (status, detail) => ({ agent, status, detail, command, cwd });
+    if (env.SPHINX_EVALUATOR === '1') return result('unavailable', 'Client activation is disabled inside an evaluator.');
+    if (!desktop(env, platform)) return result('unavailable', `No local desktop is available. Open a terminal in this repository and run ${command}.`);
+    let binary;
+    try { binary = agent === 'cursor' ? await cursorExecutable(env, platform, findExecutable) : await findExecutable(agent, env); }
+    catch { return result('unavailable', `Could not locate ${LABELS[agent]}. Open it manually in this repository.`); }
+    if (binary && (!path.isAbsolute(binary) || binary.includes('\0'))) return result('unavailable', `Could not locate a valid ${LABELS[agent]} executable.`);
+    if (!binary) return result('unavailable', `${LABELS[agent]} is configured but its executable is not on PATH. Open it manually in this repository.`);
+    if (agent === 'cursor') {
+      // The editor CLI has this spelling; never substitute cursor-agent or agent.
+      try {
+        const version = await readClientVersion(binary, clientEnvironment(env));
+        if (/^\d+\.\d+\.\d+$/.test(version || '')) {
+          const [major, minor] = version.split('.').map(Number);
+          // Hooks first appeared in Cursor 1.7. Passing this floor does not
+          // certify support for every current hook event or verify permissions.
+          if (major < 1 || (major === 1 && minor < 7)) return result('unavailable', `Cursor ${version} predates hook support. Update Cursor, then run sphinx activate --agents cursor.`);
+        }
+        const opened = await launch({ command: binary, args: ['--new-window', cwd], waitForExit: true }, { env: clientEnvironment(env) });
+        return opened ? result('opened', 'Opened a new Cursor editor window. Start a new agent chat there; hook loading and permissions remain controlled by Cursor.') : result('failed', 'Cursor did not accept the window launch. Open the editor manually in this repository.');
+      } catch { return result('failed', 'Cursor could not be opened. Open the editor manually in this repository.'); }
+    }
+    let bridge, recordFile, claimFile;
+    try {
+      await activationDirectory(home);
+      const token = randomUUID();
+      recordFile = fileFor(home, token); claimFile = `${recordFile}.claim`;
+      const terminal = await terminalCommand({ recordFile, token, home, platform, env, findExecutable, workerPath: WORKER });
+      if (!terminal) return result('unavailable', `No supported desktop terminal was found. Open a terminal in this repository and run ${command}.`);
+      bridge = await environmentBridge(clientEnvironment(env), token);
+      await writeJson(recordFile, { version: 1, token, home, agent, command: binary, cwd, envSocket: bridge.socketPath, status: 'starting', createdAt: Date.now() });
+      const accepted = await launch(terminal, { env: clientEnvironment(env) });
+      if (!accepted) return result('failed', `Could not open a terminal for ${LABELS[agent]}. Run ${command} in this repository.`);
+      // Keep the one-shot IPC alive until the worker has received the environment
+      // and its interactive client emits spawn. Never wait for the session to end.
+      const deadline = Date.now() + timeoutMs;
+      do {
+        const current = await readJson(recordFile, null);
+        if (current?.token !== token) return result('failed', `The ${LABELS[agent]} launch could not be confirmed. Open it manually.`);
+        if (current.status === 'opened') return result('opened', agent === 'codex' ? 'Started a fresh Codex session. Open /hooks there to review and trust Sphinx hooks.' : `Started a fresh ${LABELS[agent]} session. Complete any setup or permissions in that terminal.`);
+        if (current.status === 'failed') return result('failed', `${LABELS[agent]} could not start in the terminal. Run ${command} in this repository.`);
+        if (Date.now() >= deadline) break;
+        await wait(Math.min(pollMs, deadline - Date.now()));
+      } while (true);
+      return result('failed', `The terminal opened, but ${LABELS[agent]} startup was not confirmed. Check that terminal or run ${command} manually.`);
+    } catch { return result('failed', `Could not start ${LABELS[agent]}. Run ${command} in this repository.`); }
+    finally {
+      await bridge?.close().catch(() => {});
+      if (recordFile) await rm(recordFile, { force: true }).catch(() => {});
+      if (claimFile) await rm(claimFile, { force: true }).catch(() => {});
+    }
+  }));
+  return { results };
+}
+
+/** Runs in the opened terminal, never in the installing coding-agent session. */
+export async function runActivationTerminal({ recordFile, token, env = process.env, isTTY = !!process.stdin.isTTY, spawnImpl = spawn, write = text => process.stdout.write(text), startupGraceMs = 300 } = {}) {
+  const home = getPaths(env).home;
+  if (!TOKEN.test(token) || recordFile !== fileFor(home, token)) throw new Error('Invalid client activation worker.');
+  await activationDirectory(home);
+  let claim;
+  try { claim = await open(`${recordFile}.claim`, 'wx', 0o600); }
+  catch (error) { if (error.code === 'EEXIST') return { status: 'ignored', code: 1 }; throw error; }
+  try {
+    const record = await readJson(recordFile, null);
+    if (!record || record.version !== 1 || record.token !== token || record.home !== home || !AGENTS.filter(agent => agent !== 'cursor').includes(record.agent) || record.status !== 'starting' || !path.isAbsolute(record.command || '') || record.command.includes('\0') || !path.isAbsolute(record.cwd || '') || record.cwd.includes('\0')) return { status: 'ignored', code: 1 };
+    const status = async value => {
+      // Installation can time out or finish while this worker remains alive.
+      // It owns cleanup; do not recreate an already removed launch record.
+      try {
+        if ((await readJson(recordFile, null))?.token === token) await writeJson(recordFile, { ...record, status: value });
+      } catch { /* The parent reports unconfirmed startup if acknowledgment fails. */ }
+    };
+    if (!isTTY) { await status('failed'); return { status: 'failed', code: 1 }; }
+    let providerEnv;
+    try { providerEnv = await readTerminalEnvironment(record.envSocket, token); }
+    catch { await status('failed'); return { status: 'failed', code: 1 }; }
+    if (!(await readJson(recordFile, null))) return { status: 'ignored', code: 1 };
+    write(activationGuidance(record.agent));
+    let opened = false, stateWrite = Promise.resolve();
+    const code = await new Promise(resolve => {
+      let child, timer;
+      try { child = spawnImpl(record.command, [], { cwd: record.cwd, env: { ...freshEnvironment(env), ...providerEnv, SPHINX_HOME: home }, stdio: 'inherit' }); }
+      catch { stateWrite = status('failed'); resolve(1); return; }
+      child.once('spawn', () => {
+        timer = setTimeout(() => { opened = true; stateWrite = stateWrite.then(() => status('opened')); }, startupGraceMs);
+      });
+      child.once('error', () => { clearTimeout(timer); stateWrite = stateWrite.then(() => status('failed')); resolve(1); });
+      child.once('exit', code => {
+        clearTimeout(timer);
+        if (!opened) stateWrite = stateWrite.then(() => status('failed'));
+        resolve(code ?? 1);
+      });
+    });
+    await stateWrite;
+    return { status: opened ? 'closed' : 'failed', code };
+  } finally {
+    await claim.close();
+    await rm(`${recordFile}.claim`, { force: true }).catch(() => {});
+  }
+}