@theronap/cortex-mcp 0.9.95 → 0.9.96

package/bin/cortex-mcp.mjs

@@ -56,6 +56,8 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  graphify-sync [path] [--brain <name-or-id>]  rebuild the local code graph + log a timeline event\n` +
     `  snapshot-context save the exact startup context Agnoclast served to a local snapshot\n` +
     `  hydrate         UserPromptSubmit hook — inject query-centered context on the first substantive turn\n` +
+    `  migrate-key [--dry-run]  move the MCP config key to its new name, allow rules first\n` +
+    `  with-token -- <cmd>    run <cmd> with your token in its environment (for cron/launchd wrappers)\n` +
     `  statusline      ambient presence line for the Claude Code statusline (local read only)\n` +
     `  capture         Stop-hook capturer (invoked by Claude Code)\n` +
     `  ingest-folder <path>   ingest a local markdown folder as your authored records\n` +
@@ -161,6 +163,21 @@ if (cmd === 'login') {
   process.exitCode = await runHydrate()
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'migrate-key') {
+  // ADR-0033 §5 C2. Guarded: adds the new namespace's allow rules and VERIFIES them from disk
+  // before flipping mcpServers.cortex -> .agnoclast, so a seat that never received C1 cannot end up
+  // with renamed tools and no permissions. Idempotent; --dry-run reports the plan and changes
+  // nothing. NOT wired into any hook yet — activating it is the C2 release itself.
+  const { runKeyMigration } = await import('../lib/migrate_key.mjs')
+  const res = runKeyMigration({ dryRun: rest.includes('--dry-run') })
+  process.stdout.write(JSON.stringify(res, null, 2) + '\n')
+  process.exitCode = res.status === 'aborted' ? 1 : 0
+} else if (cmd === 'with-token') {
+  // Run a command with the resolved token in its environment. Exists so generated helper scripts
+  // (launchd/cron wrappers) never inline their own config parse — those files are frozen on disk and
+  // a config change strands them silently. See lib/with_token.mjs.
+  const { runWithToken } = await import('../lib/with_token.mjs')
+  process.exitCode = runWithToken(rest)
 } else if (cmd === 'statusline') {
   // Ambient presence: read one local breadcrumb and print a line. No network, no auth — it redraws
   // constantly, so anything more expensive than a file read does not belong here.

package/lib/capture.mjs

@@ -1,10 +1,10 @@
-import { readFileSync, accessSync, constants } from 'fs'
+import { readFileSync, accessSync, constants, openSync, mkdirSync } from 'fs'
 import { spawn, execFileSync } from 'child_process'
 import { homedir } from 'os'
 import { resolve, dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { createHash } from 'crypto'
-import { fetchCortex, classify, resolveBase, readWiredToken } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase, resolveTokenSource } from './diagnose.mjs'
 import { extractSession } from './edge_extract.mjs'
 import { extractTyped } from './extract_typed.mjs'
 import { redactSecrets } from './redact.mjs'
@@ -244,7 +244,31 @@ export async function runCapture() {
   await captureWork(stdinRaw)
 }
 
-// Re-invoke this same CLI as `capture` in a fully detached child (own session, stdio ignored) and
+// Where a DETACHED worker's stdout/stderr go. Returns a writable fd, or 'ignore' if the log cannot be
+// opened — a capture must never fail because a log file could not be created.
+//
+// WHY THIS EXISTS. The worker previously ran with `stdio: ['pipe', 'ignore', 'ignore']`, so every
+// diagnostic capture prints — `no CORTEX_TOKEN`, `transcript_path unreadable`, `no-op session,
+// skipping`, `ingest failed — <reason>` — was written to a discarded stream. In production that is
+// EVERY capture: the sync path only runs under CORTEX_CAPTURE_SYNC, which nothing sets. So the
+// messages carefully added at each failure branch have never once been readable by anyone.
+//
+// Measured 2026-08-19: session-record writes fell from 107/day (08-10) to 1/day (08-13) and stayed
+// at 0-3/day for six days with no error surfacing anywhere. The failure was found only by forcing
+// CORTEX_CAPTURE_SYNC=1 by hand and watching stderr — which is not a thing anyone will think to do
+// about a subsystem that reports success. Append-only, one line per capture; the file is the only
+// place a silent worker can leave a trace.
+function captureLogFd() {
+  try {
+    const dir = join(homedir(), '.cortex')
+    mkdirSync(dir, { recursive: true })
+    return openSync(join(dir, 'capture.log'), 'a')
+  } catch {
+    return 'ignore'
+  }
+}
+
+// Re-invoke this same CLI as `capture` in a fully detached child (own session, output to capture.log) 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.
@@ -254,7 +278,7 @@ function spawnDetachedWorker(stdinRaw) {
     const child = spawn(process.execPath, [bin, 'capture'], {
       env: { ...process.env, CORTEX_CAPTURE_DETACHED: '1' },
       detached: true,
-      stdio: ['pipe', 'ignore', 'ignore'],
+      stdio: ['pipe', captureLogFd(), captureLogFd()],
     })
     child.on('error', () => {}) // never let an async spawn error crash the hook
     child.stdin.on('error', () => {})
@@ -269,7 +293,7 @@ function spawnDetachedWorker(stdinRaw) {
 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()
+  const token = resolveTokenSource().token
   if (!token) { process.stderr.write('cortex: no CORTEX_TOKEN in env or wired config, skipping\n'); return }
   const base = resolveBase(process.env.CORTEX_URL)
 
@@ -364,6 +388,12 @@ async function captureWork(stdinRaw) {
     } catch { /* best-effort — never block capture */ }
   }
 
+  // Defined before the fetch so the throw path below can stamp its line the same way. Every line in
+  // capture.log carries an ISO timestamp and the session id, so a silent day can be reconstructed
+  // afterwards and matched against `records` / `page_revisions.session_key`.
+  const stamp = new Date().toISOString()
+  const sid = hook.session_id ?? '(no session_id)'
+
   let res
   try {
     // Best-effort background ingest: bound it tight and retry once so a hanging/504-ing server
@@ -375,17 +405,63 @@ async function captureWork(stdinRaw) {
       timeoutMs: 10_000,
     }, { retries: 1 })
   } catch (e) {
-    // Never break a session — just report and move on.
-    process.stderr.write(`cortex: ${e.message}\n`)
+    // Never break a session — just report and move on. This is where a 10s timeout against a slow
+    // /api/ingest lands, and with the old discarded stdio it was completely invisible: the session
+    // simply never appeared and nothing anywhere said why. The endpoint is measurably flaky — a
+    // SessionStart context fetch timed out at 09:54 and again at 11:59 on 2026-08-19 while direct
+    // curls answered in ~150ms, so intermittent timeouts here are a live hypothesis for the
+    // 2026-08-13 collapse, not a theoretical one.
+    process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — ${e.message}\n`)
     return
   }
 
-  if (res.ok) {
-    const j = await res.json().catch(() => ({}))
-    process.stderr.write(`cortex: ${j.inserted ? 'captured' : 'updated'} "${j.title ?? repo}" → ${repo}\n`)
+  // A 2xx FROM /api/ingest DOES NOT MEAN A RECORD EXISTS. The route answers `ok: true` on at least
+  // six outcomes and only one of them writes a session record:
+  //
+  //   { ok: true, id, inserted, title }            -> RECORDED (the only success)
+  //   { ok: true, staged: true, id, reason }       -> held in staged_records, NOT recorded
+  //   { ok: true, skipped: '<why>' }               -> no-op session / past the ingest horizon
+  //   { ok: false, skipped: '<why>' }              -> connector excluded from this brain
+  //   { ok: true, discarded: true }                -> tombstoned by private intake
+  //   { ok: true, queued: true }                   -> accepted for later work
+  //   { ok: true, via: 'private_intake', intakeItemId } -> an intake unit, not a session record
+  //
+  // The old line read `j.inserted ? 'captured' : 'updated'`, so EVERY one of the six non-writing
+  // outcomes printed "updated" — the word for a successful upsert. Worse, `.json().catch(() => ({}))`
+  // means an unparseable body also yields `{}` and therefore also printed "updated". Verified against
+  // prod 2026-08-19: a capture printed `cortex: updated "general" → general` for a session that has no
+  // row in `records` and none in `staged_records` either.
+  //
+  // NOTE `staged` CARRIES AN `id`, so testing for an id alone is not enough — that id is the
+  // staged_records row, not a record. This is the same false-success defect already fixed once in
+  // log_session ("`inserted` is merely falsy when nothing is recorded — an agent reported a session as
+  // saved when it was not"); the fix was applied there and not here. The server route already knew:
+  // its own comment at the no_route_for_source branch says "`{ok: true}` reads as success to
+  // everything that is not looking closely" and notes 84 rows accumulating behind that wording.
+  if (res.ok || res.status === 200) {
+    const raw = await res.text()
+    let j
+    try { j = JSON.parse(raw) } catch { j = null }
+    if (j && j.id && !j.staged) {
+      process.stderr.write(`cortex: ${stamp} ${sid} ${j.inserted ? 'captured' : 'updated'} "${j.title ?? repo}" → ${repo}\n`)
+    } else if (j && j.staged) {
+      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — staged (${j.reason ?? 'no reason given'}); staged session logs are not drainable by /api/staged/promote\n`)
+    } else if (j && j.skipped) {
+      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — server skipped: ${j.skipped}\n`)
+    } else if (j && j.discarded) {
+      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — discarded by private intake\n`)
+    } else if (j && j.queued) {
+      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — queued for later processing\n`)
+    } else if (j && j.intakeItemId) {
+      process.stderr.write(`cortex: ${stamp} ${sid} not a session record — filed as private intake unit ${j.intakeItemId}\n`)
+    } else {
+      // Unparseable or unrecognised 2xx. Deliberately NOT reported as success: an unknown shape is
+      // exactly the case the old code laundered into "updated".
+      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — unrecognised 2xx response: ${raw.slice(0, 200)}\n`)
+    }
   } else {
     const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-    process.stderr.write(`cortex: ingest failed — ${d.message}\n`)
+    process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — ingest failed: ${d.message}\n`)
   }
 
   // The post-capture edge-materialize batch (CORTEX_MATERIALIZE → runMaterialize) was EXCISED

package/lib/context_log.mjs

@@ -1,19 +1,12 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
-import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase, resolveTokenSource } from './diagnose.mjs'
 
-function resolveToken() {
-  if (process.env.CORTEX_TOKEN) return process.env.CORTEX_TOKEN
-  const claudeJson = join(homedir(), '.claude.json')
-  if (!existsSync(claudeJson)) return null
-  try {
-    const cfg = JSON.parse(readFileSync(claudeJson, 'utf8'))
-    return cfg?.mcpServers?.cortex?.env?.CORTEX_TOKEN ?? null
-  } catch {
-    return null
-  }
-}
+// The private third copy of this lived here until 2026-08-19. doctor.mjs:14 warned that a third
+// copy is how a machine ends up connected to one command and 'no token found' to another; it also
+// missed Codex entirely, so a Codex-only seat WAS in exactly that state. Shared resolver now.
+const resolveToken = () => resolveTokenSource().token
 
 function ensureDir(path) {
   if (!existsSync(path)) mkdirSync(path, { recursive: true })

package/lib/diagnose.mjs

@@ -22,18 +22,81 @@ export const isUuid = (s) =>
 // `CORTEX_TOKEN=…` in hooks.json shows the secret to anything that reads or greps the file, and
 // from there to captured transcripts); `capture` resolves the token itself from the same config
 // the MCP server already holds.
-export function readWiredToken() {
+// ── Token resolution ─────────────────────────────────────────────────────────
+// TWO resolvers, deliberately. An audit of all twelve call sites (ADR-0033 T1) found they are NOT
+// semantically interchangeable: five REQUIRE an explicit token and five may fall back to the wired
+// config. Collapsing both into one function would have silently granted config-based auth to the
+// five that deliberately demand it — the failure the independent review flagged.
+//
+//   resolveEnvToken()    env only          → server, graphify-sync, grep, ingest-folder, resolve
+//   resolveTokenSource() env, then wired   → capture, hydrate, skills×2, context_log, doctor
+//
+// Precedence is PRESENCE-based, not validity-based: the first variable that is set wins, so a stale
+// AGNOCLAST_TOKEN shadows a working CORTEX_TOKEN. Validity-based precedence would need a network
+// round-trip on every resolution, which this path cannot afford. Instead the winner is REPORTED in
+// `source`, so `doctor` shows which variable was used and a shadow is visible rather than silent.
+
+/** In precedence order. Additive only — never drop a name a machine may still be wired with. */
+export const TOKEN_ENV_VARS = ['AGNOCLAST_TOKEN', 'CORTEX_TOKEN']
+const CONFIG_KEYS = ['agnoclast', 'cortex']
+
+/** Environment only. For call sites where an explicit token is the point. */
+export function resolveEnvToken(env = process.env) {
+  for (const name of TOKEN_ENV_VARS) {
+    if (env?.[name]) return { token: env[name], source: `${name} env`, key: null }
+  }
+  return { token: null, source: null, key: null }
+}
+
+// Positive results only, keyed by home. A miss re-reads, so a token wired mid-process (setup, then
+// a hook in the same run) is still picked up; a hit is stable because a token cannot change while a
+// process lives.
+//
+// `home` is an explicit parameter rather than always homedir() because BUN'S os.homedir() IGNORES
+// the HOME variable (verified 2026-08-19: node honours it, bun returns the real home regardless),
+// so a bun test cannot redirect it. editors/*.mjs already take `home` for the same reason.
+const _wiredCache = new Map()
+
+/** Reset the wired-token memo. Tests only. */
+export function resetWiredTokenCache() { _wiredCache.clear() }
+
+/** The wired config: ~/.claude.json first, then Codex config.toml. Memoized because this parses a
+ *  ~117KB JSON file and the twelve call sites above are reached from per-prompt hooks. */
+export function readWiredTokenSource(home = homedir()) {
+  if (_wiredCache.has(home)) return _wiredCache.get(home)
+  const claudeJson = join(home, '.claude.json')
   try {
-    const cfg = JSON.parse(readFileSync(join(homedir(), '.claude.json'), 'utf8'))
-    const t = cfg?.mcpServers?.cortex?.env?.CORTEX_TOKEN
-    if (t) return t
-  } catch { /* fall through */ }
+    const cfg = JSON.parse(readFileSync(claudeJson, 'utf8'))
+    for (const key of CONFIG_KEYS) {
+      const env = cfg?.mcpServers?.[key]?.env
+      for (const name of TOKEN_ENV_VARS) {
+        if (env?.[name]) { const r = { token: env[name], source: `${claudeJson} (mcpServers.${key})`, key }; _wiredCache.set(home, r); return r }
+      }
+    }
+  } catch { /* malformed or absent — fall through */ }
+  const codexToml = join(home, '.codex', 'config.toml')
   try {
-    const toml = readFileSync(join(homedir(), '.codex', 'config.toml'), 'utf8')
-    const m = toml.match(/\[mcp_servers\.cortex\.env\][\s\S]*?CORTEX_TOKEN\s*=\s*"([^"]+)"/)
-    if (m) return m[1]
+    const toml = readFileSync(codexToml, 'utf8')
+    for (const key of CONFIG_KEYS) {
+      for (const name of TOKEN_ENV_VARS) {
+        const m = toml.match(new RegExp(`\\[mcp_servers\\.${key}\\.env\\][\\s\\S]*?${name}\\s*=\\s*"([^"]+)"`))
+        if (m) { const r = { token: m[1], source: `${codexToml} ([mcp_servers.${key}])`, key }; _wiredCache.set(home, r); return r }
+      }
+    }
   } catch { /* fall through */ }
-  return null
+  return { token: null, source: null, key: null }
+}
+
+/** Environment, then wired config. The canonical resolver for background/hook work. */
+export function resolveTokenSource(env = process.env, home = homedir()) {
+  const fromEnv = resolveEnvToken(env)
+  return fromEnv.token ? fromEnv : readWiredTokenSource(home)
+}
+
+/** Bare-token form of the WIRED lookup only — deliberately NOT env-aware, because install.mjs:70
+ *  calls it as `argToken || readWiredToken()` where the whole point is "what is already wired". */
+export function readWiredToken(home = homedir()) {
+  return readWiredTokenSource(home).token
 }
 
 // Pure: pull the cortex-mcp dist-tag / version out of a wired command line. Exported for tests.

package/lib/doctor.mjs

@@ -1,7 +1,8 @@
 import { readFileSync, existsSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
-import { checkToken, checkSkills, resolveBase } from './diagnose.mjs'
+import { checkToken, checkSkills, resolveBase, resolveTokenSource } from './diagnose.mjs'
+import { renderRenameNotice } from './rename_notice.mjs'
 
 // `npx @theronap/cortex-mcp doctor` — a live, one-command health check.
 //
@@ -14,18 +15,7 @@ import { checkToken, checkSkills, resolveBase } from './diagnose.mjs'
 // Exported so `use-brain` resolves the token EXACTLY as doctor/status do. There is already a second,
 // subtly different copy of this in context_log.mjs (returns a bare token, not {token, source}); a
 // third copy is how a machine ends up "connected" to one command and "no token found" to another.
-export function resolveToken() {
-  if (process.env.CORTEX_TOKEN) return { token: process.env.CORTEX_TOKEN, source: 'CORTEX_TOKEN env' }
-  const claudeJson = join(homedir(), '.claude.json')
-  if (existsSync(claudeJson)) {
-    try {
-      const cfg = JSON.parse(readFileSync(claudeJson, 'utf8'))
-      const t = cfg?.mcpServers?.cortex?.env?.CORTEX_TOKEN
-      if (t) return { token: t, source: `${claudeJson} (mcpServers.cortex)` }
-    } catch { /* malformed config — fall through to "not found" */ }
-  }
-  return { token: null, source: null }
-}
+export const resolveToken = resolveTokenSource
 
 // `status` — the one-line SessionStart variant of doctor: a visible "is Agnoclast capturing?"
 // signal inside Claude Code itself (three-machine dry-run finding 2026-06-09: with no
@@ -54,6 +44,14 @@ export async function runStatus() {
       }
       const n = typeof r.projectCount === 'number' ? ` · ${r.projectCount} project${r.projectCount === 1 ? '' : 's'} visible` : ''
       out(`Agnoclast: connected — sessions on this machine are captured to your org${n}.`)
+      // TEMPORARY (ADR-0033 T7) — delete with lib/rename_notice.mjs a release after C2.
+      // This one FOLLOWS the happy line rather than replacing it, unlike captureNotice above. The
+      // rule there exists because captureNotice CONTRADICTS the reassurance ("connected" was true
+      // while the work was landing nowhere). This does not contradict anything: the connection is
+      // genuinely fine and a rename is separately scheduled. Replacing the status line with it would
+      // hide a fact the reader needs in order to report a real problem.
+      const notice = renderRenameNotice(resolveToken().key)
+      if (notice) out(notice)
     } else {
       out(`Agnoclast: NOT connected — ${r.diagnosis?.message ?? 'check failed'}. Run: npx -y @theronap/cortex-mcp doctor`)
     }

package/lib/editors/antigravity.mjs

@@ -57,23 +57,30 @@ export function renderAntigravitySyncSh() {
   return `#!/bin/bash
 # Agnoclast ⇄ Antigravity one-shot sync, triggered by launchd WatchPaths on the Antigravity
 # trajectory store. There is no resident daemon — launchd wakes this on change and it exits.
-# Token is resolved from the wired MCP config at runtime (never stored in plist/script).
+# Token is resolved by 'cortex-mcp with-token' at runtime (never stored in plist/script, and
+# never parsed here -- see ADR-0033 D9 on frozen generated scripts).
 # ⚠ AGENT_DIR points at a local dev checkout — see antigravity.mjs BLOCKER note (not coworker-portable).
 set -o pipefail
 LOG="$HOME/.cortex/antigravity-sync.log"
-NODE="/usr/local/bin/node"
+NPX="/usr/local/bin/npx"
 BUN="$HOME/.bun/bin/bun"
 AGENT_DIR="$HOME/dev/cortex/packages/cortex-agent"
 
 stamp() { date -u +%FT%TZ; }
 
-TOKEN="$("$NODE" -e "try{console.log(JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude.json','utf8'))?.mcpServers?.cortex?.env?.CORTEX_TOKEN||'')}catch(e){process.exit(0)}" 2>/dev/null)"
-if [ -z "$TOKEN" ]; then echo "$(stamp) no CORTEX_TOKEN wired, skipping" >> "$LOG"; exit 0; fi
 if [ ! -d "$AGENT_DIR" ]; then echo "$(stamp) agent dir missing: $AGENT_DIR" >> "$LOG"; exit 0; fi
 
+# The token is resolved by the package, not parsed here. This script is written once and never
+# rewritten by an upgrade, so an inlined config read would silently stop working the moment the
+# config shape changed -- and its own error handling would swallow that. with-token also keeps the
+# secret out of this shell entirely: it goes from the resolver straight into the child environment.
+# Exit 3 means "nothing wired", which is a skip rather than a failure.
 cd "$AGENT_DIR" || exit 0
-CORTEX_TOKEN="$TOKEN" CORTEX_WATCH="$HOME/.cortex-agent" "$BUN" run src/index.ts antigravity-sync >> "$LOG" 2>&1
-echo "$(stamp) exit=$?" >> "$LOG"
+CORTEX_WATCH="$HOME/.cortex-agent" "$NPX" -y @theronap/cortex-mcp@stable with-token -- \
+  "$BUN" run src/index.ts antigravity-sync >> "$LOG" 2>&1
+CODE=$?
+if [ "$CODE" = "3" ]; then echo "$(stamp) no token wired, skipping" >> "$LOG"; exit 0; fi
+echo "$(stamp) exit=$CODE" >> "$LOG"
 exit 0
 `
 }

package/lib/editors/claude.mjs

@@ -5,6 +5,7 @@ import { homedir } from 'node:os'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { readJson, backupFile, ensureDir, writeJson } from './_fsutil.mjs'
+import { markCommand, isManagedSubcommand } from '../managed.mjs'
 
 /** Merge the Agnoclast MCP server into a ~/.claude.json object. Pure + idempotent: sets only the
  *  `cortex` entry (type:'stdio'), preserves every other server. `spec` = the package@dist-tag string. */
@@ -27,7 +28,7 @@ export function mergeClaudeMcp(existing, spec, token) {
  *  lossy at the row level, so the prompt IS the guard D1 argued for), rollback_page, decide_page_merge /
  *  decide_file_request / request_file / get_file, create_brain / set_active_brain, alias_page,
  *  set_writing_style. */
-export const CORTEX_ALLOWED_TOOLS = [
+export const ALLOWED_TOOL_NAMES = [
   // read surface
   'grep', 'read_page', 'my_context', 'project_status', 'session_context', 'search_org',
   'list_records', 'page_history', 'page_diff', 'timeline_pull', 'my_brains', 'my_sessions', 'writing_style',
@@ -36,7 +37,14 @@ export const CORTEX_ALLOWED_TOOLS = [
   'authoring_context', 'author', 'log_session',
   // routine, reversible maintenance
   'set_page_validity', 'snooze_red_link', 'attribute_thread',
-].map((t) => `mcp__cortex__${t}`)
+]
+
+/** The same allowlist, rendered for a given tool namespace. ONE source of names, so the cortex and
+ *  agnoclast lists cannot drift apart during the migration — C2 adds the new namespace's rules
+ *  before flipping the config key, and it derives them from here rather than a second copy. */
+export const allowedToolsFor = (namespace) => ALLOWED_TOOL_NAMES.map((t) => `mcp__${namespace}__${t}`)
+
+export const CORTEX_ALLOWED_TOOLS = allowedToolsFor('cortex')
 
 /** Merge Agnoclast's Claude Code hooks into a ~/.claude/settings.json object. Pure + idempotent: drops
  *  any prior cortex entry (old token/path/version) from each hook array before appending the current
@@ -53,9 +61,9 @@ export function mergeClaudeSettings(existing, spec) {
 
   // Stop — capture.
   s.hooks.Stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : []
-  const captureCmd = `npx -y ${spec} capture`
+  const captureCmd = markCommand(`npx -y ${spec} capture`)
   for (const grp of s.hooks.Stop) {
-    if (Array.isArray(grp.hooks)) grp.hooks = grp.hooks.filter((h) => !/cortex-mcp.*capture|capture-session-cloud/.test(h.command ?? ''))
+    if (Array.isArray(grp.hooks)) grp.hooks = grp.hooks.filter((h) => !isManagedSubcommand(h.command, 'capture'))
   }
   let grp = s.hooks.Stop.find((g) => (g.matcher ?? '') === '')
   if (!grp) { grp = { matcher: '', hooks: [] }; s.hooks.Stop.push(grp) }
@@ -64,24 +72,24 @@ export function mergeClaudeSettings(existing, spec) {
 
   // SessionStart — status, then skills self-heal, then snapshot-context (order matters: matches setup).
   s.hooks.SessionStart = Array.isArray(s.hooks.SessionStart) ? s.hooks.SessionStart : []
-  const statusCmd = `npx -y ${spec} status`
+  const statusCmd = markCommand(`npx -y ${spec} status`)
   for (const sg of s.hooks.SessionStart) {
-    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? status/.test(h.command ?? ''))
+    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !isManagedSubcommand(h.command, 'status'))
   }
   let sgrp = s.hooks.SessionStart.find((g) => (g.matcher ?? '') === '')
   if (!sgrp) { sgrp = { matcher: '', hooks: [] }; s.hooks.SessionStart.push(sgrp) }
   sgrp.hooks = sgrp.hooks ?? []
   sgrp.hooks.push({ type: 'command', command: statusCmd })
 
-  const skillsCmd = `npx -y ${spec} skills --repair --quiet`
+  const skillsCmd = markCommand(`npx -y ${spec} skills --repair --quiet`)
   for (const sg of s.hooks.SessionStart) {
-    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? skills/.test(h.command ?? ''))
+    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !isManagedSubcommand(h.command, 'skills'))
   }
   sgrp.hooks.push({ type: 'command', command: skillsCmd })
 
-  const snapshotCmd = `npx -y ${spec} snapshot-context`
+  const snapshotCmd = markCommand(`npx -y ${spec} snapshot-context`)
   for (const sg of s.hooks.SessionStart) {
-    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? snapshot-context/.test(h.command ?? ''))
+    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !isManagedSubcommand(h.command, 'snapshot-context'))
   }
   sgrp.hooks.push({ type: 'command', command: snapshotCmd })
 
@@ -97,9 +105,9 @@ export function mergeClaudeSettings(existing, spec) {
   // dead for five days when its worktree was deleted — the `-f` guard fails open, so the hook silently
   // became a no-op with the config still looking wired. Re-running setup should heal that, not skip it.
   s.hooks.UserPromptSubmit = Array.isArray(s.hooks.UserPromptSubmit) ? s.hooks.UserPromptSubmit : []
-  const hydrateCmd = `npx -y ${spec} hydrate`
+  const hydrateCmd = markCommand(`npx -y ${spec} hydrate`)
   for (const hg of s.hooks.UserPromptSubmit) {
-    if (Array.isArray(hg.hooks)) hg.hooks = hg.hooks.filter((h) => !/cortex-mcp.*hydrate/.test(h.command ?? ''))
+    if (Array.isArray(hg.hooks)) hg.hooks = hg.hooks.filter((h) => !isManagedSubcommand(h.command, 'hydrate'))
   }
   let hgrp = s.hooks.UserPromptSubmit.find((g) => (g.matcher ?? '') === '')
   if (!hgrp) { hgrp = { matcher: '', hooks: [] }; s.hooks.UserPromptSubmit.push(hgrp) }

package/lib/graphify_sync.mjs

@@ -1,7 +1,7 @@
 import { spawnSync } from 'child_process'
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
-import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase, resolveEnvToken } from './diagnose.mjs'
 
 // `cortex-mcp graphify-sync [path]` — local producer: incrementally rebuild a repo's structural
 // code graph (graphify — tree-sitter AST, no LLM) and log an evidence-tier timeline event via
@@ -62,7 +62,7 @@ export async function runGraphifySync(argv = []) {
   const parsed = parseGraphifyArgs(argv)
   if (parsed.error) { process.stderr.write(parsed.error + '\n'); return 1 }
   const { cwd, brain } = parsed
-  const TOKEN = process.env.CORTEX_TOKEN
+  const TOKEN = resolveEnvToken().token
   const BASE = resolveBase(process.env.CORTEX_URL)
   if (!TOKEN) {
     process.stderr.write('cortex-mcp graphify-sync: CORTEX_TOKEN is required.\n')

package/lib/grep_cli.mjs

@@ -1,4 +1,4 @@
-import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase, resolveEnvToken } from './diagnose.mjs'
 
 // `cortex grep` CLI + shared formatting for the MCP grep tool (Lane B / T6). Thin client of
 // GET /api/grep — the server runs the RLS-INVOKER RPC AS the viewer, so no DB credentials live here.
@@ -53,7 +53,7 @@ export function formatGrepHits(payload, query) {
 
 // Effectful: run the CLI subcommand. Returns an exit code.
 export async function runGrep(rest = []) {
-  const TOKEN = process.env.CORTEX_TOKEN
+  const TOKEN = resolveEnvToken().token
   const BASE = resolveBase(process.env.CORTEX_URL)
   if (!TOKEN) {
     process.stderr.write('cortex grep: CORTEX_TOKEN is required (get yours from the Agnoclast console).\n')

package/lib/hydrate.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSync, unlinkSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
-import { fetchCortex, classify, resolveBase, readWiredToken } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase, resolveTokenSource } from './diagnose.mjs'
 import { redactSecrets } from './redact.mjs'
 import { formatReceipt, renderUncounted, subjectOf } from './presence.mjs'
 import { writePresence } from './statusline.mjs'
@@ -114,7 +114,7 @@ export async function runHydrate() {
   })
   if (action !== 'go') return 0
 
-  const token = process.env.CORTEX_TOKEN || readWiredToken()
+  const token = resolveTokenSource().token
   if (!token) return 0 // not wired → silent no-op (don't mark done; a later session may be wired)
   const base = resolveBase(process.env.CORTEX_URL)
 

package/lib/ingest_folder.mjs

@@ -1,6 +1,6 @@
 import { readFileSync, readdirSync, statSync } from 'node:fs'
 import { join, relative, basename, extname } from 'node:path'
-import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase, resolveEnvToken } from './diagnose.mjs'
 
 // `cortex-mcp ingest-folder <path>` — walk a local markdown folder and upsert each file as an
 // AUTHORED record in Agnoclast (source='brain'), so a user's personal digest is built from THEIR
@@ -105,7 +105,7 @@ export async function runIngestFolder(argv) {
     return
   }
 
-  const token = process.env.CORTEX_TOKEN
+  const token = resolveEnvToken().token
   if (!token) {
     process.stderr.write(
       'cortex: CORTEX_TOKEN not set. Run setup first, or export CORTEX_TOKEN=<your-token>.\n',

package/lib/managed.mjs

@@ -0,0 +1,49 @@
+// Identity for the entries we write onto a machine — hooks in settings.json, crontab lines.
+//
+// The problem this exists to solve: uninstall used to find our entries by matching the product
+// name (`CORTEX_RE = /cortex-mcp|.../`). That works only until the product is renamed, at which
+// point uninstall removes the OLD entries, reports success, and leaves the NEW ones wired —
+// firing on every session against a possibly revoked token. `67920bd` caught the same class of
+// bug from the other side (renamed skills left uninstall unable to find the skills on disk).
+// The installer had it too: its dedup filters matched `cortex-mcp.*capture`, so after a rename
+// a `repair` run would fail to recognize its own previous hooks and APPEND duplicates rather
+// than replace them.
+//
+// So identity stops depending on what the product is called. Every command we write carries an
+// inert marker flag that is stable across renames. Name matching stays as a LEGACY fallback only, because machines wired
+// before the marker existed can be found no other way — it can never be deleted, only demoted.
+
+/** Inert flag appended to every command we write. Never change this string: it is the only thing
+ *  that lets a future version recognize entries written by this one.
+ *
+ *  Why a FLAG and not a trailing `# comment`: a comment is only inert if the hook command is run
+ *  through a shell, and whether Claude Code does that is not something this package can verify.
+ *  An argv token is inert either way — with a shell it is an argument, without one it is still an
+ *  argument. The only requirement is that our own CLI ignore it, which holds because bin dispatches
+ *  on argv[2] and every subcommand parses `rest` with `.includes()` (verified 2026-08-19:
+ *  `uninstall --dry-run` and `uninstall --dry-run --agnoclast-managed` produce identical output).
+ *  Do not move it before the subcommand — it must land in `rest`, not in argv[2]. */
+export const MANAGED_MARKER = '--agnoclast-managed'
+
+/** Names we shipped under, for machines predating MANAGED_MARKER. Additive only — a name that
+ *  ever appeared in a written command must stay here forever. `capture-session-cloud` is an
+ *  early Stop-hook command that predates the npx form. */
+const LEGACY_NAME_RE = /cortex-mcp|agnoclast-mcp|capture-session-cloud|@theronap\/(cortex|agnoclast)/
+
+/** Stamp a command as ours. Appended, never substituted, so the command still runs unchanged. */
+export function markCommand(command) {
+  const c = String(command ?? '')
+  return c.includes(MANAGED_MARKER) ? c : `${c} ${MANAGED_MARKER}`
+}
+
+/** True if we wrote this command — by marker (rename-proof) or by legacy name (pre-marker seats). */
+export function isManagedCommand(command) {
+  const c = String(command ?? '')
+  return c.includes(MANAGED_MARKER) || LEGACY_NAME_RE.test(c)
+}
+
+/** True if this is one of ours AND runs the named subcommand. Used by the installer to replace
+ *  its own prior entry for a given hook rather than appending a duplicate beside it. */
+export function isManagedSubcommand(command, subcommand) {
+  return isManagedCommand(command) && new RegExp(`\\b${subcommand}\\b`).test(String(command ?? ''))
+}