@theronap/cortex-mcp 0.9.38 → 0.9.40

package/bin/cortex-mcp.mjs

@@ -43,6 +43,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `Subcommands:\n` +
     `  setup <token>   wire MCP server + capture hook into ~/.claude config\n` +
     `  repair          re-run setup at the latest version using your existing token (no token needed)\n` +
+    `  uninstall       remove ALL Cortex wiring (MCP, hooks, skills, launchd, cron). --dry-run to preview, --purge to also wipe ~/.cortex + npx cache\n` +
     `  doctor          live health check — confirm your token works (no restart needed)\n` +
     `  status          one-line connected/not-connected check (used by the SessionStart hook)\n` +
     `  skills          install/repair the managed Cortex skills — bundled + org-published (also wired by setup)\n` +
@@ -69,6 +70,12 @@ if (cmd === 'setup') {
   await runSetup(rest, VERSION)
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'uninstall' || cmd === 'remove') {
+  // Full reverse of setup: strip every Cortex touch-point (MCP entries, hooks, skills, launchd, cron).
+  // --dry-run prints the plan and changes nothing; --purge also removes ~/.cortex, the npx cache, and
+  // backups. No network — safe to run even when the token is dead or the server is unreachable.
+  const { runUninstall } = await import('../lib/uninstall.mjs')
+  runUninstall(rest)
 } else if (cmd === 'repair' || cmd === 'update') {
   // Re-run setup at THIS version using the already-wired token (no token arg needed). Fixes a
   // machine set up with an older version: re-pins MCP + hooks, reinstalls skills to the flat path.

package/lib/capture.mjs

@@ -1,6 +1,8 @@
 import { readFileSync } from 'fs'
+import { spawn } from 'child_process'
 import { homedir } from 'os'
-import { resolve } from 'path'
+import { resolve, dirname, join } from 'path'
+import { fileURLToPath } from 'url'
 import { createHash } from 'crypto'
 import { fetchCortex, classify, resolveBase, readWiredToken } from './diagnose.mjs'
 import { extractSession } from './edge_extract.mjs'
@@ -80,12 +82,51 @@ function transcriptTail(path) {
     : tail
 }
 
+// Stop-hook entry point. The Stop hook fires after EVERY assistant turn, and Claude Code BLOCKS the
+// input box until this returns — so the heavy work (a synchronous `claude -p` edge summary, up to
+// tens of seconds, and worse when it hangs under concurrent sessions) must NEVER run in-band here.
+// Instead we read the (small) stdin payload, hand it to a DETACHED background worker, and return in
+// ~milliseconds. The worker does the extraction + ingest out of band; the user's next prompt is never
+// held. Set CORTEX_CAPTURE_SYNC=1 to force the old in-band behavior (tests / debugging).
 export async function runCapture() {
-  // Recursion guard: edge extraction below shells out to `claude --print` with CORTEX_SUMMARIZING=1.
-  // That headless session fires its own Stop hook → this same capture command. Without this guard it
-  // would recurse (and re-ingest the summarizer's prompt as a phantom session). Bail immediately.
+  // Recursion guard: edge extraction shells out to `claude --print` with CORTEX_SUMMARIZING=1. That
+  // headless session fires its own Stop hook → this same capture command. Without this guard it would
+  // recurse (and re-ingest the summarizer's prompt as a phantom session). Bail immediately.
   if (process.env.CORTEX_SUMMARIZING) { process.stderr.write('cortex: summarizer subprocess, skipping\n'); return }
 
+  const stdinRaw = readStdin()
+
+  // Detach the slow work unless we ARE the detached worker (or a caller forced sync). A spawn failure
+  // falls through to the in-band path so a session is never dropped just because fork() failed.
+  if (!process.env.CORTEX_CAPTURE_DETACHED && !process.env.CORTEX_CAPTURE_SYNC) {
+    if (spawnDetachedWorker(stdinRaw)) return
+  }
+  await captureWork(stdinRaw)
+}
+
+// Re-invoke this same CLI as `capture` in a fully detached child (own session, stdio ignored) and
+// feed it the hook payload on its stdin. Returns true if the child was launched (parent may return
+// immediately), false if spawning failed (caller then does the work in-band). The child sees
+// CORTEX_CAPTURE_DETACHED=1 so it runs captureWork() directly instead of forking again.
+function spawnDetachedWorker(stdinRaw) {
+  try {
+    const bin = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'cortex-mcp.mjs')
+    const child = spawn(process.execPath, [bin, 'capture'], {
+      env: { ...process.env, CORTEX_CAPTURE_DETACHED: '1' },
+      detached: true,
+      stdio: ['pipe', 'ignore', 'ignore'],
+    })
+    child.on('error', () => {}) // never let an async spawn error crash the hook
+    child.stdin.on('error', () => {})
+    child.stdin.end(stdinRaw)
+    child.unref()
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function captureWork(stdinRaw) {
   // Env first (explicit override / legacy inlined hooks), else the token wired into this machine's
   // MCP config — so hook commands carry no secret (token-hygiene, 2026-07-02).
   const token = process.env.CORTEX_TOKEN || readWiredToken()
@@ -93,7 +134,7 @@ export async function runCapture() {
   const base = resolveBase(process.env.CORTEX_URL)
 
   let hook = {}
-  try { hook = JSON.parse(readStdin()) } catch { /* no/invalid stdin */ }
+  try { hook = JSON.parse(stdinRaw) } catch { /* no/invalid stdin */ }
   const repo = projectFrom(hook.cwd)
   // Redact credential-shaped strings BEFORE anything leaves the machine — this `transcript`
   // feeds local edge/typed extraction AND the fallback POST to the org. A secret in a

package/lib/diagnose.mjs

@@ -68,10 +68,20 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 //         'app'   → a real Cortex API error with a JSON message (retriable only if 5xx)
 export function classify(status, contentType, bodyText, requestId) {
   const isJson = (contentType ?? '').includes('application/json')
-  let appError = null
-  if (isJson) { try { appError = JSON.parse(bodyText)?.error ?? null } catch { /* not json after all */ } }
+  let body = null
+  if (isJson) { try { body = JSON.parse(bodyText) } catch { /* not json after all */ } }
+  const appError = body?.error ?? null
   const rid = requestId ? ` [request id: ${requestId}]` : ''
 
+  // Multi-brain: 409 no_active_brain means the caller belongs to >1 brain and hasn't chosen one. It is
+  // NOT an auth failure — surface the action (set_active_brain) directly, not a "Cortex API 409:" wrapper.
+  if (status === 409 && body?.code === 'no_active_brain') {
+    return {
+      kind: 'app', retriable: false,
+      message: `${appError ?? 'You belong to more than one brain — call set_active_brain to choose where your writes land.'} (see my_brains for your options)${rid}`,
+    }
+  }
+
   if (status === 401 || (isJson && appError === 'invalid token')) {
     return {
       kind: 'auth', retriable: false,

package/lib/edge_extract.mjs

@@ -1,4 +1,58 @@
 import { spawnSync } from 'child_process'
+import { openSync, closeSync, writeSync, unlinkSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// Single-flight lock so at most ONE edge summarizer (`claude -p`) runs on this machine at a time.
+// Without it, N concurrent Claude sessions all fire their Stop hook at once → N simultaneous headless
+// `claude --print` calls that contend on the same subscription-OAuth refresh and can deadlock (the
+// "prompts hang forever" incident, 2026-07-08). If the lock is already held by a live, recent holder,
+// the caller skips extraction and ships the transcript tail instead (the server summarizes async) —
+// no session is dropped, just summarized server-side that turn. A stale lock (older than the summary
+// timeout + grace, or whose PID is dead) is reclaimed.
+const LOCK_PATH = join(homedir(), '.cortex', 'summarize.lock')
+
+function summaryTimeoutMs() {
+  const n = Number(process.env.CORTEX_SUMMARY_TIMEOUT_MS)
+  return Number.isFinite(n) && n > 0 ? n : 45_000
+}
+
+// Try to acquire the lock. Returns true if acquired (caller must call releaseSummaryLock in a finally),
+// false if another live holder has it. O_CREAT|O_EXCL is the atomic "create only if absent" primitive.
+function acquireSummaryLock(_retried = false) {
+  try {
+    const fd = openSync(LOCK_PATH, 'wx') // wx = O_CREAT|O_EXCL|O_WRONLY — fails if it exists
+    try { writeSync(fd, String(process.pid)) } catch { /* PID write is best-effort */ }
+    closeSync(fd)
+    return true
+  } catch (e) {
+    if (e && e.code === 'EEXIST') {
+      // Someone holds it — reclaim only if it's stale (older than timeout + 15s grace, or PID dead).
+      if (_retried) return false // one reclaim attempt only; a live race means "ship the tail"
+      try {
+        const age = Date.now() - statSync(LOCK_PATH).mtimeMs
+        const holderDead = !pidAlive(readFileSync(LOCK_PATH, 'utf8').trim())
+        if (age > summaryTimeoutMs() + 15_000 || holderDead) {
+          try { unlinkSync(LOCK_PATH) } catch { /* raced with another reclaimer */ }
+          return acquireSummaryLock(true)
+        }
+      } catch { /* unreadable lock — treat as held; ship the tail this turn */ }
+      return false
+    }
+    // Any other error (e.g. ~/.cortex missing): don't block extraction, just run without the lock.
+    return true
+  }
+}
+
+function pidAlive(pid) {
+  const n = Number(pid)
+  if (!Number.isInteger(n) || n <= 0) return false
+  try { process.kill(n, 0); return true } catch (e) { return e && e.code === 'EPERM' }
+}
+
+function releaseSummaryLock() {
+  try { unlinkSync(LOCK_PATH) } catch { /* already gone */ }
+}
 
 // Edge session extractor (slice 2c) — ONE `claude --print` call on the user's SUBSCRIPTION that
 // produces summary + people + non-person entities LOCALLY, so the cloud receives only the derived
@@ -62,16 +116,21 @@ export function extractSession(transcript) {
     PEOPLE_FRAGMENT + ',\n' +
     ENTITY_FRAGMENT +
     '\n\n--- SESSION ---\n' + text.slice(0, 12000) + '\n--- END ---'
+  // Single-flight: if another session already has a summarizer running, skip (caller ships the tail;
+  // server summarizes). Prevents the concurrent-`claude -p` stampede that deadlocks the OAuth refresh.
+  if (!acquireSummaryLock()) return null
   try {
     const r = spawnSync(
       'claude',
       ['--print', '--model', process.env.CORTEX_SUMMARY_MODEL ?? 'claude-haiku-4-5', prompt],
-      { env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }), encoding: 'utf8', timeout: 90_000, maxBuffer: 4 * 1024 * 1024 },
+      { env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }), encoding: 'utf8', timeout: summaryTimeoutMs(), maxBuffer: 4 * 1024 * 1024 },
     )
     if (r.status !== 0 || !r.stdout) return null
     return parseEdgeJson(r.stdout.trim())
   } catch {
     return null
+  } finally {
+    releaseSummaryLock()
   }
 }
 

package/lib/uninstall.mjs

@@ -0,0 +1,190 @@
+import { readFileSync, writeFileSync, existsSync, copyFileSync, rmSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { execFileSync } from 'child_process'
+
+// Full uninstall — the reverse of setup.mjs. Removes EVERY touch-point Cortex writes onto a machine:
+//   1. ~/.claude.json          → mcpServers.cortex
+//   2. ~/.claude/settings.json → Stop/SessionStart/PreCompact cortex hooks
+//   3. ~/.codex/config.toml    → [mcp_servers.cortex] + [mcp_servers.cortex.env]
+//   4. ~/.codex/hooks.json     → cortex capture Stop hook
+//   5. managed skills          → ~/.claude/skills/cortex* + ~/.codex/skills/cortex*
+//   6. launchd agent           → ~/Library/LaunchAgents/com.cortex.*.plist (unload + remove)
+//   7. crontab                 → lines tagged "# cortex ..."
+//   8. off-switch env          → launchctl unsetenv CORTEX_SUMMARIZE_DISABLED (macOS)
+//   --purge also removes: ~/.cortex state dir, the npx cache, and every .cortex-bak backup.
+//
+// Safe by construction: --dry-run prints the plan and changes nothing; every JSON/TOML file is backed
+// up to <file>.cortex-uninstall-bak before edit; JSON surgery filters only cortex-tagged entries and
+// leaves every other MCP server / hook untouched. Idempotent — re-running is a no-op.
+
+const HOME = homedir()
+const CLAUDE_JSON = join(HOME, '.claude.json')
+const SETTINGS = join(HOME, '.claude', 'settings.json')
+const CODEX_TOML = join(HOME, '.codex', 'config.toml')
+const CODEX_HOOKS = join(HOME, '.codex', 'hooks.json')
+const CORTEX_DIR = join(HOME, '.cortex')
+const LAUNCH_AGENTS = join(HOME, 'Library', 'LaunchAgents')
+const CORTEX_RE = /cortex-mcp|capture-session-cloud|@theronap\/cortex/
+
+export function runUninstall(argv = []) {
+  const dry = argv.includes('--dry-run') || argv.includes('-n')
+  const purge = argv.includes('--purge')
+  const plan = [] // human-readable action log
+  const act = (msg) => plan.push(msg)
+  const write = (path, data) => { if (!dry) { backup(path); writeFileSync(path, data) } }
+
+  process.stdout.write(dry ? '\nCortex uninstall — DRY RUN (nothing will change):\n\n' : '\nCortex uninstall — removing all wiring…\n\n')
+
+  // 1. MCP server out of ~/.claude.json
+  editJson(CLAUDE_JSON, (cfg) => {
+    if (cfg.mcpServers && cfg.mcpServers.cortex) { delete cfg.mcpServers.cortex; act(`  - mcpServers.cortex  ← ${CLAUDE_JSON}`); return true }
+    return false
+  }, write)
+
+  // 2. Hooks out of ~/.claude/settings.json (Stop, SessionStart, PreCompact)
+  editJson(SETTINGS, (s) => {
+    let changed = false
+    for (const evt of ['Stop', 'SessionStart', 'PreCompact']) {
+      if (!Array.isArray(s.hooks?.[evt])) continue
+      for (const grp of s.hooks[evt]) {
+        if (!Array.isArray(grp.hooks)) continue
+        const before = grp.hooks.length
+        grp.hooks = grp.hooks.filter((h) => !CORTEX_RE.test(h?.command ?? ''))
+        if (grp.hooks.length !== before) changed = true
+      }
+      // drop groups we emptied
+      s.hooks[evt] = s.hooks[evt].filter((g) => !Array.isArray(g.hooks) || g.hooks.length > 0)
+      if (s.hooks[evt].length === 0) delete s.hooks[evt]
+    }
+    if (changed) act(`  - Stop/SessionStart/PreCompact cortex hooks  ← ${SETTINGS}`)
+    return changed
+  }, write)
+
+  // 3. Codex MCP tables (strip [mcp_servers.cortex] + [mcp_servers.cortex.env])
+  if (existsSync(CODEX_TOML)) {
+    const text = readFileSync(CODEX_TOML, 'utf8')
+    const stripped = stripCodexCortexTables(text)
+    if (stripped !== text) { write(CODEX_TOML, stripped); act(`  - [mcp_servers.cortex] tables  ← ${CODEX_TOML}`) }
+  }
+
+  // 4. Codex capture hook
+  editJson(CODEX_HOOKS, (h) => {
+    let changed = false
+    if (Array.isArray(h.hooks?.Stop)) {
+      for (const grp of h.hooks.Stop) {
+        if (!Array.isArray(grp.hooks)) continue
+        const before = grp.hooks.length
+        grp.hooks = grp.hooks.filter((c) => !CORTEX_RE.test(c?.command ?? ''))
+        if (grp.hooks.length !== before) changed = true
+      }
+      h.hooks.Stop = h.hooks.Stop.filter((g) => !Array.isArray(g.hooks) || g.hooks.length > 0)
+    }
+    if (changed) act(`  - cortex capture hook  ← ${CODEX_HOOKS}`)
+    return changed
+  }, write)
+
+  // 5. Managed skills
+  for (const skillsRoot of [join(HOME, '.claude', 'skills'), join(HOME, '.codex', 'skills')]) {
+    for (const name of ['cortex', 'cortex-author-docs', 'cortex-context', 'cortex-log']) {
+      const p = join(skillsRoot, name)
+      if (existsSync(p)) { act(`  - skill ${p}`); if (!dry) rmSync(p, { recursive: true, force: true }) }
+    }
+  }
+
+  // 6. launchd agents (com.cortex.*)
+  if (existsSync(LAUNCH_AGENTS)) {
+    for (const f of safeReaddir(LAUNCH_AGENTS)) {
+      if (!/^com\.cortex\..*\.plist$/.test(f)) continue
+      const p = join(LAUNCH_AGENTS, f)
+      act(`  - launchd agent ${p} (unload + remove)`)
+      if (!dry) {
+        tryExec('launchctl', ['bootout', `gui/${process.getuid?.() ?? ''}/${f.replace(/\.plist$/, '')}`])
+        tryExec('launchctl', ['unload', p])
+        rmSync(p, { force: true })
+      }
+    }
+  }
+
+  // 7. crontab — drop cortex-tagged lines
+  const cron = tryExecOut('crontab', ['-l'])
+  if (cron != null) {
+    const kept = cron.split('\n').filter((l) => !CORTEX_RE.test(l) && !/\.cortex\//.test(l))
+    if (kept.join('\n') !== cron) {
+      act('  - crontab cortex entries')
+      if (!dry) tryExecIn('crontab', ['-'], kept.join('\n').replace(/\n+$/, '') + '\n')
+    }
+  }
+
+  // 8. off-switch env var (macOS launchd session env)
+  act('  - launchctl unsetenv CORTEX_SUMMARIZE_DISABLED')
+  if (!dry) tryExec('launchctl', ['unsetenv', 'CORTEX_SUMMARIZE_DISABLED'])
+
+  // --purge: state dir + npx cache + backups
+  if (purge) {
+    if (existsSync(CORTEX_DIR)) { act(`  - PURGE state dir ${CORTEX_DIR}`); if (!dry) rmSync(CORTEX_DIR, { recursive: true, force: true }) }
+    for (const cache of npxCacheDirs()) { act(`  - PURGE npx cache ${cache}`); if (!dry) rmSync(cache, { recursive: true, force: true }) }
+    for (const bak of [CLAUDE_JSON, SETTINGS, CODEX_TOML, CODEX_HOOKS]) {
+      for (const suffix of ['.cortex-bak', '.cortex-uninstall-bak']) {
+        const b = bak + suffix
+        if (existsSync(b)) { act(`  - PURGE backup ${b}`); if (!dry) rmSync(b, { force: true }) }
+      }
+    }
+  }
+
+  if (plan.length === 0) { process.stdout.write('  Nothing to remove — this machine has no Cortex wiring.\n\n'); return }
+  process.stdout.write(plan.join('\n') + '\n\n')
+  if (dry) {
+    process.stdout.write('DRY RUN — nothing changed. Re-run without --dry-run to apply.\n')
+    process.stdout.write('  Full wipe (state dir + npx cache + backups too):  add --purge\n\n')
+  } else {
+    process.stdout.write('Done. Fully quit and reopen Claude Code (and Codex) to drop the server.\n')
+    if (!purge) process.stdout.write('  State dir ~/.cortex and .cortex-bak backups were KEPT. Remove them too with --purge.\n')
+    process.stdout.write('\n')
+  }
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+function backup(path) {
+  if (!existsSync(path)) return
+  copyFileSync(path, `${path}.cortex-uninstall-bak`)
+}
+
+// Read JSON, run mutator (returns true if it changed anything), write back via `write` if so.
+// Malformed JSON is left untouched (never risk corrupting a file we can't parse).
+function editJson(path, mutate, write) {
+  if (!existsSync(path)) return
+  let obj
+  try { obj = JSON.parse(readFileSync(path, 'utf8') || '{}') } catch { process.stderr.write(`  ! ${path} is not valid JSON — skipped (left as-is)\n`); return }
+  if (mutate(obj)) write(path, JSON.stringify(obj, null, 2) + '\n')
+}
+
+// Strip [mcp_servers.cortex] and [mcp_servers.cortex.env] tables from a Codex config.toml.
+// Same table-skip logic as setup.mergeCodexToml, in reverse.
+export function stripCodexCortexTables(text) {
+  const targets = new Set(['[mcp_servers.cortex]', '[mcp_servers.cortex.env]'])
+  const kept = []
+  let skipping = false
+  for (const line of (text || '').split('\n')) {
+    const t = line.trim()
+    if (t.startsWith('[') && t.endsWith(']')) skipping = targets.has(t)
+    if (!skipping) kept.push(line)
+  }
+  return kept.join('\n').replace(/\n{3,}/g, '\n\n')
+}
+
+function safeReaddir(dir) {
+  try { return execFileSync('ls', ['-1', dir], { encoding: 'utf8' }).split('\n').filter(Boolean) } catch { return [] }
+}
+function npxCacheDirs() {
+  const base = join(HOME, '.npm', '_npx')
+  const out = []
+  for (const d of safeReaddir(base)) {
+    const dir = join(base, d)
+    try { if (execFileSync('grep', ['-rl', '@theronap/cortex-mcp', join(dir, 'package.json')], { encoding: 'utf8' }).trim()) out.push(dir) } catch { /* not a cortex cache */ }
+  }
+  return out
+}
+function tryExec(cmd, args) { try { execFileSync(cmd, args, { stdio: 'ignore' }) } catch { /* best-effort */ } }
+function tryExecOut(cmd, args) { try { return execFileSync(cmd, args, { encoding: 'utf8' }) } catch { return null } }
+function tryExecIn(cmd, args, input) { try { execFileSync(cmd, args, { input }) } catch { /* best-effort */ } }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.38",
+  "version": "0.9.40",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {