@theronap/cortex-mcp 0.9.52 → 0.9.54

package/lib/diagnose.mjs

@@ -36,6 +36,26 @@ export function readWiredToken() {
   return null
 }
 
+// Pure: pull the cortex-mcp dist-tag / version out of a wired command line. Exported for tests.
+// Returns 'latest' | 'stable' | a version string (e.g. '0.9.4') | null (no cortex-mcp spec present).
+export function parseDistTag(line) {
+  const m = String(line || '').match(/@theronap\/cortex-mcp@(latest|stable|[0-9][^\s"']*)/)
+  return m ? m[1] : null
+}
+
+// Read the dist-tag / version this machine is currently wired to (from the ~/.claude.json cortex MCP
+// command), so a re-run of setup/repair can PRESERVE an intentional channel instead of forcing @stable
+// every time — that silently knocks a dogfooder on @latest back to the pilot channel (bit Theron
+// 2026-07-24). Returns 'latest' | 'stable' | a version string | null (nothing wired yet).
+export function wiredDistTag() {
+  try {
+    const cfg = JSON.parse(readFileSync(join(homedir(), '.claude.json'), 'utf8'))
+    const c = cfg?.mcpServers?.cortex
+    return parseDistTag([c?.command, ...(c?.args ?? [])].filter(Boolean).join(' '))
+  } catch { /* fall through */ }
+  return null
+}
+
 // The production alias — exempt from Vercel Deployment Protection.
 export const CANONICAL_BASE = 'https://cortex-console.vercel.app'
 

package/lib/editors/claude.mjs

@@ -28,7 +28,7 @@ export function mergeClaudeMcp(existing, spec, token) {
 export const CORTEX_ALLOWED_TOOLS = [
   // read surface
   'grep', 'read_page', 'my_context', 'project_status', 'session_context', 'search_org',
-  'list_records', 'page_history', 'timeline_pull', 'my_brains', 'my_sessions', 'writing_style',
+  'list_records', 'page_history', 'page_diff', 'timeline_pull', 'my_brains', 'my_sessions', 'writing_style',
   'code_graph_query', 'my_retier_notices', 'list_page_grants', 'file_requests', 'page_merge_requests',
   // live authoring core
   'authoring_context', 'author', 'log_session',

package/lib/install.mjs

@@ -7,7 +7,7 @@ import { homedir } from 'node:os'
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { ADAPTERS, resolveEditors } from './editors/index.mjs'
-import { checkToken, resolveBase, readWiredToken } from './diagnose.mjs'
+import { checkToken, resolveBase, readWiredToken, wiredDistTag } from './diagnose.mjs'
 
 const PKG = '@theronap/cortex-mcp'
 export const MANIFEST_PATH = join(homedir(), '.cortex', 'editors.json')
@@ -68,7 +68,9 @@ export function writeManifest(manifest, { path = MANIFEST_PATH } = {}) {
 export async function runInstall(argv, version) {
   const { token: argToken, editor } = parseInstallArgs(argv)
   const token = argToken || readWiredToken()
-  const spec = `${PKG}@stable`
+  // Preserve an intentional @latest (dogfood) pin across re-runs; fresh installs + existing @stable
+  // get @stable. See wiredDistTag — forcing @stable here silently demoted a dogfooder (2026-07-24).
+  const spec = wiredDistTag() === 'latest' ? `${PKG}@latest` : `${PKG}@stable`
   const home = homedir()
   const log = (m) => process.stdout.write(m + '\n')
 

package/lib/server.mjs

@@ -6,6 +6,7 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { createHash, randomUUID } from 'crypto'
 import { fetchCortex, classify, resolveBase, setSessionKey } from './diagnose.mjs'
+import { resolveSessionKey } from './session_key.mjs'
 import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.mjs'
 import { renderTriage } from './red_link_triage.mjs'
@@ -42,7 +43,18 @@ export async function runServer(version) {
   // Self active-sessions (ADR-0017): one MCP process = one AI session. A stable per-process key + the
   // working dir identify this session; we heartbeat /api/session-ping while alive so the user can see
   // all THEIR sessions via my_sessions. Self-only on the server; best-effort (never breaks serving).
-  const SESSION_KEY = randomUUID()
+  //
+  // PGL-21 fix: "one MCP process = one AI session" is an assumption, not a guarantee — the HOST
+  // (Claude Code) can restart this stdio process mid-conversation (reconnects, tool-loading events),
+  // and a fresh randomUUID() on every restart silently orphaned the PRIOR process's session-scoped
+  // write-pointer row (session_write_pointers): an explicit set_active_brain(scope:'session') would
+  // stop taking effect one restart later, falling back to the account pointer with no visible cause
+  // — reproduced live 2026-07-27. Claude Code sets CLAUDE_CODE_SESSION_ID for the lifetime of one
+  // logical conversation across any number of subprocess restarts, so prefer it as the session key;
+  // fall back to a fresh randomUUID() for any other MCP host that doesn't set it (unchanged behavior
+  // there — no host that never had continuity loses anything). Bonus: my_sessions / session_presence
+  // (also keyed on SESSION_KEY, ADR-0017) stop fragmenting one conversation into several "sessions" too.
+  const SESSION_KEY = resolveSessionKey(process.env, randomUUID)
   // ADR-0020 Stage 2: stamp this key on every outbound request (fetchCortex injects it) so writes
   // resolve THIS session's brain pointer. Must be set BEFORE the first fetchCortex call below —
   // otherwise the opening requests of a session would silently resolve by the account pointer.
@@ -498,7 +510,7 @@ export async function runServer(version) {
           const head = `[${t.tier}${day(t.updated_at) ? ` · authored ${day(t.updated_at)}` : ''}${t.validity && t.validity !== 'current' ? ` · ${t.validity}` : ''}${versionLine}]`
           return [head, t.summary, secs].filter(Boolean).join('\n')
         })
-        let footer = `— Follow any [[links]] above with read_page to go deeper.\n— If you hold fresher FIRST-HAND truth than this page — something you established THIS session (ran the command, made the change, hold the artifact) that a section here gets concretely wrong — re-author just those sections now with \`author\` (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). Pass this page's \`version\` as base_version when you re-author — if the save comes back stale, the page changed under you: re-read, then re-author. Reading a stale page you can fix IS the trigger to fix it. Re-authoring is pre-authorized — do NOT ask the user before updating (edits are versioned + reversible via page_history/rollback_page); update, then briefly report it.`
+        let footer = `— Follow any [[links]] above with read_page to go deeper.\n— If you hold fresher FIRST-HAND truth than this page — something you established THIS session (ran the command, made the change, hold the artifact) that a section here gets concretely wrong — re-author just those sections now with \`author\` (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). Pass this page's \`version\` as base_version when you re-author — if the save comes back stale, the page changed under you: re-read, then re-author. Reading a stale page you can fix IS the trigger to fix it. Re-authoring is pre-authorized — do NOT ask the user before updating (edits are versioned + reversible via page_history/rollback_page); update, then briefly report it.\n— Citing code? Use a SYMBOL and file (\`formConnections\` in \`web/app/api/ingest/route.ts\`), never a line number — line numbers drift with every commit above them. And cite only what you opened THIS session; re-emitting a reference you read on another page is how a stale claim gains a second source and starts looking corroborated.`
         // slice 4: when the page carries identifier stamps, the history projection is one flag away.
         const allBody = m.tiers.flatMap((t) => (t.sections ?? []).map((s) => s.body)).join('\n')
         const stamps = [...new Set((allBody.match(/\[\[repo:[a-z0-9][a-z0-9-]*\/[a-z0-9_.-]+\]\]/gi) ?? []).map((s) => s.toLowerCase()))]
@@ -544,10 +556,78 @@ export async function runServer(version) {
       if (!revs.length) return { content: [{ type: 'text', text: `"${name}" (${k}) has no recorded version history yet.` }] }
       const lines = revs.map((r) => {
         const who = r.actor_name ? ` · ${r.actor_name}` : ''
+        // change_kind first and bracketed so a column of [correct] is scannable — the whole point is
+        // that a page with repeated corrections looks different at a glance from one that only grew.
+        const what = r.change_kind ? ` · [${r.change_kind}]` : ''
         const why = r.reason ? ` — ${r.reason}` : ''
-        return `- rev ${r.rev_no} · ${String(r.created_at).slice(0, 10)} · ${r.op} · ${r.tier}${who}${why}\n    version: ${r.content_hash}`
+        // Session keys run up to 200 chars; a short prefix is enough to group a session's edits and to
+        // hand to a human. Null on every pre-2026-07-27 revision — render nothing rather than "none",
+        // so "not recorded" never reads as "recorded as empty".
+        const sess = r.session_key ? `\n    session: ${String(r.session_key).slice(0, 24)}` : ''
+        return `- rev ${r.rev_no} · ${String(r.created_at).slice(0, 10)} · ${r.op}${what} · ${r.tier}${who}${why}\n    version: ${r.content_hash}${sess}`
       })
-      return { content: [{ type: 'text', text: `# ${name} — page history (newest first)\n${lines.join('\n')}\n\n— \`read_page "${name}"\` with version:<rev_no|version> to view an old body; \`rollback_page\` to restore one.` }] }
+      const anyKind = revs.some((r) => r.change_kind)
+      const hint = anyKind
+        ? `\n— \`page_diff "${name}"\` to see exactly what a revision changed.`
+        : `\n— Revisions written before 2026-07-27 carry no reason/change_kind — that is "not recorded", not "no reason".`
+      return { content: [{ type: 'text', text: `# ${name} — page history (newest first)\n${lines.join('\n')}\n\n— \`read_page "${name}"\` with version:<rev_no|version> to view an old body; \`rollback_page\` to restore one.${hint}` }] }
+    },
+  )
+
+  server.registerTool(
+    'page_diff',
+    {
+      title: 'See exactly what an edit changed',
+      description: 'Show WHAT CHANGED between two versions of an authored wiki page — which sections were added, removed or rewritten, plus the reason and change_kind recorded for the edit. Use it when page_history tells you an edit happened and you need to know what it actually did: before trusting a claim that was recently rewritten, when auditing whether a "correct" edit really fixed something, or before rollback_page so you know what you would be undoing. `from` defaults to the version immediately before `to`, so passing just `to` answers "what did this one edit change?". RLS-scoped: you can diff only pages you may read.',
+      inputSchema: {
+        name: z.string().describe('the canonical node name exactly as written (e.g. "Agnoclast")'),
+        kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('node kind (default project)'),
+        to: z.string().describe('the NEWER version: a rev_no (e.g. "6") or a content_hash, from page_history'),
+        from: z.string().optional().describe('the OLDER version to compare against. Omit to use the revision immediately before `to` — which is what you want for "what did this edit change?"'),
+        lines: z.boolean().optional().describe('also show line-level +/- within each changed section. Off by default: the section-level answer is usually what you want and is far shorter.'),
+      },
+    },
+    async ({ name, kind, to, from, lines }) => {
+      const k = kind ?? 'project'
+      let res
+      try {
+        const qs = new URLSearchParams({
+          kind: k, key: name, to,
+          ...(from ? { from } : {}), ...(lines ? { lines: '1' } : {}),
+        })
+        res = await fetchCortex(`${BASE}/api/brain/page-diff?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not diff "${name}": ${e.message}` }] }
+      }
+      if (res.status === 404) return { content: [{ type: 'text', text: `No ${k} named "${name}", or it has no version "${to}". Run \`page_history "${name}"\` to list its versions.` }] }
+      if (!res.ok) {
+        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        return { content: [{ type: 'text', text: `Could not diff "${name}": ${d.message}` }] }
+      }
+      const out = await res.json()
+      const d = out.diff
+      const head = d.from.revNo === 0
+        ? `# ${name} — rev ${d.to.revNo} (first version)`
+        : `# ${name} — rev ${d.from.revNo} → rev ${d.to.revNo}`
+      const meta = []
+      meta.push(`${String(d.to.createdAt).slice(0, 10)} · ${d.to.op}${d.to.changeKind ? ` · [${d.to.changeKind}]` : ''}${d.to.actorName ? ` · ${d.to.actorName}` : ''}`)
+      if (d.to.reason) meta.push(`reason: ${d.to.reason}`)
+      if (d.to.sessionKey) meta.push(`session: ${String(d.to.sessionKey).slice(0, 24)}`)
+      const body = []
+      if (d.summaryChanged) body.push('- summary: CHANGED')
+      for (const h of d.sections.added) body.push(`- + added section: ${h}`)
+      for (const h of d.sections.removed) body.push(`- − removed section: ${h}`)
+      for (const c of d.sections.changed) {
+        body.push(`- ~ changed section: ${c.heading}`)
+        // Cap the rendered hunk. A section body can be 65k chars; dumping a full rewrite into a tool
+        // result buries the signal and burns the reader's context for no gain.
+        for (const l of (c.lines ?? []).slice(0, 40)) body.push(`    ${l.kind === 'add' ? '+' : '−'} ${l.line}`)
+        if ((c.lines?.length ?? 0) > 40) body.push(`    … ${c.lines.length - 40} more changed lines`)
+      }
+      if (!body.length) body.push('- no section or summary changes (metadata-only revision, e.g. a re-tier)')
+      const tail = d.sections.unchangedCount ? `\n\n${d.sections.unchangedCount} section(s) unchanged.` : ''
+      const hint = lines ? '' : '\n— Pass `lines: true` to see the actual changed lines within each section.'
+      return { content: [{ type: 'text', text: `${head}\n${meta.join(' · ')}\n\n${body.join('\n')}${tail}${hint}` }] }
     },
   )
 
@@ -636,7 +716,7 @@ export async function runServer(version) {
     'my_brains',
     {
       title: 'List your brains + which one writes land in',
-      description: 'List the brains (orgs/workspaces) you belong to and show which one is your ACTIVE WRITE brain — where author/log_session/capture currently land. Reads span all your brains; writes go to the active one. Use this to see your options before set_active_brain, or when a session seems to belong to a different brain than the one you are writing to.',
+      description: 'List the brains (orgs/workspaces) you belong to. Reads span ALL of them, and writes to an EXISTING page now resolve to the brain that holds it — you do NOT need to check or switch anything before authoring, and you should not. The active brain is only a default for creating a page that exists nowhere yet. Use this when you genuinely need to see what brains exist or how they are populated.',
       inputSchema: {},
     },
     async () => {
@@ -664,13 +744,13 @@ export async function runServer(version) {
       // Which layer is deciding, and what clearing it would fall back to — otherwise the pointer
       // confusion simply reappears one level down.
       const note = !activeIsExplicit
-        ? '\n(active brain is the default — you have one brain; set_active_brain once you hold more.)'
+        ? '\n(you have one brain; nothing to choose.)'
         : activeSource === 'session'
           ? `\n(this SESSION's override — your other sessions are unaffected${accountOrgId && accountOrgId !== sessionOrgId ? `; clearing it falls back to ${accountOrgId}` : ''}.)`
           : activeSource === 'account'
             ? '\n(account-wide pointer — shared by every session that has not set its own.)'
             : ''
-      return { content: [{ type: 'text', text: `Your brains (▶ = writes land here):\n${lines.join('\n')}${note}` }] }
+      return { content: [{ type: 'text', text: `Your brains (▶ = default for NEW pages only — edits to existing pages route themselves):\n${lines.join('\n')}${note}` }] }
     },
   )
 
@@ -712,8 +792,8 @@ export async function runServer(version) {
   server.registerTool(
     'set_active_brain',
     {
-      title: 'Choose the brain your writes go to',
-      description: "Point your writes (author / log_session / capture) at one of your brains, by its org id (from my_brains). Pass org_id = null to clear it. You can only select a brain you are a member of. SCOPE: 'session' (default) changes ONLY this session — other windows you have open keep writing where they were, which is almost always what you want. 'account' changes the sticky person-wide pointer, which redirects every other session that has not set its own.",
+      title: 'Set the default brain for NEW pages',
+      description: "RARELY NEEDED — do not reach for this reflexively. Editing an EXISTING page routes itself: author/set_page_validity/rollback resolve the brain from the page (via base_version, ref, or name), so switching first is unnecessary and switching WRONG is now impossible to cause. This only sets the default for creating a page that exists in NO brain yet, and for log_session/capture. If you find yourself about to call this so an edit lands correctly, don't — just author; it will find the page. Pass org_id = null to clear. SCOPE: 'session' (default) changes ONLY this session; 'account' changes the person-wide pointer and redirects every other open session that has not set its own.",
       inputSchema: {
         org_id: z.string().nullable().describe('the org id of the brain to write to (from my_brains), or null to clear the pointer'),
         scope: z.enum(['session', 'account']).optional()
@@ -752,7 +832,7 @@ export async function runServer(version) {
     'create_brain',
     {
       title: 'Create a new brain under your existing account',
-      description: 'Create a brand-new brain (org/workspace) — a fully independent knowledge graph — under your EXISTING account. No new login, no new email/password: this adds a second membership to the account you are already using. Reads never cross brains; use set_active_brain afterward to point writes at it (creating it does not switch your active write brain automatically).',
+      description: 'Create a brand-new brain (org/workspace) — a fully independent knowledge graph — under your EXISTING account. No new login, no new email/password: this adds a second membership to the account you are already using. Reads never cross brains; new pages default to your active brain, so use set_active_brain if you want NEW pages to land in this one; edits to existing pages always route to whichever brain holds them.',
       inputSchema: { name: z.string().describe('display name for the new brain, e.g. "Cortex Codebase"') },
     },
     async ({ name }) => {
@@ -771,7 +851,7 @@ export async function runServer(version) {
         return { content: [{ type: 'text', text: `Could not create brain: ${d.message}` }] }
       }
       const r = await res.json()
-      return { content: [{ type: 'text', text: `Created brain "${name}" [${r.orgId}]. Run set_active_brain with this org_id to start writing to it — reads already span it automatically.` }] }
+      return { content: [{ type: 'text', text: `Created brain "${name}" [${r.orgId}]. Reads already span it. Edits to pages in it route themselves; set_active_brain only if you want NEW pages to default here.` }] }
     },
   )
 
@@ -1340,9 +1420,11 @@ export async function runServer(version) {
         })).describe('3-5 sections; the page body'),
         tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('visibility tier. Omit for the safe default: scoped (you + your management chain) on nodes that support it — your user page, projects you own-scope — and accessible elsewhere (person/org pages are the shared wiki). Pass accessible explicitly when the page is meant for the whole org.'),
         base_version: z.string().optional().describe('the `version` hash shown when you read this page (read_page) — REQUIRED when updating an existing page, so a concurrent edit is caught instead of clobbered. Omit only for a brand-new node. If the save returns "stale" or "read first", read_page again and retry with the fresh version.'),
+        reason: z.string().describe('WHY you are making this edit, in one short phrase — recorded permanently in page_history so a later reader can tell a routine addition from a correction. Say what CHANGED and what prompted it ("Ben pilot abandoned per Theron 07-17", "corrected: 0069 already widened the CHECK"), not what you did ("updated page"). This is the field that makes staleness auditable.'),
+        change_kind: z.enum(['add', 'correct', 'supersede', 'expand', 'retire']).optional().describe('what KIND of edit: "add" (new information), "correct" (the page said something FALSE — the currency-critical one), "supersede" (was true, now outdated by events), "expand" (elaborates, no claim changed), "retire" (putting the page or a section to rest). Be honest with "correct" — a page whose history shows repeated corrections is a page whose claims need checking, and that signal is the point.'),
       },
     },
-    async ({ kind, name, summary, sections, tier, base_version }) => {
+    async ({ kind, name, summary, sections, tier, base_version, reason, change_kind }) => {
       // No client-side tier default — the server computes the per-kind safe default (page-privacy
       // T4/D10) so version-pinned installs can't bake a stale policy.
       const pages = [{ ...(tier ? { tier } : {}), summary, base_version, sections: Array.isArray(sections) ? sections : [] }]
@@ -1351,7 +1433,7 @@ export async function runServer(version) {
         res = await fetchCortex(`${BASE}/api/brain/author`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ kind, name, pages }),
+          body: JSON.stringify({ kind, name, pages, reason, change_kind }),
         })
       } catch (e) {
         return { content: [{ type: 'text', text: `Could not author "${name}": ${e.message}` }] }

package/lib/session_key.mjs

@@ -0,0 +1,13 @@
+// PGL-21: derive the AI session's stable identity key. Pure — see session_key.test.mjs.
+//
+// Claude Code sets CLAUDE_CODE_SESSION_ID for the lifetime of one logical conversation, surviving
+// any number of MCP subprocess restarts (reconnects, tool-loading events) within it. Prefer it so a
+// session-scoped set_active_brain (ADR-0020 Stage 2) keeps pointing at the right brain across a
+// restart instead of silently falling back to the account pointer on a brand-new randomUUID() —
+// reproduced live 2026-07-27: an explicit set_active_brain(scope:'session') stopped taking effect
+// one restart later, with no visible cause, because the new process minted an unrelated session key
+// with no session_write_pointers row of its own. Any other MCP host that doesn't set the var gets
+// today's unchanged per-process-random behavior.
+export function resolveSessionKey(env, randomUUID) {
+  return env.CLAUDE_CODE_SESSION_ID || randomUUID()
+}

package/lib/setup.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from 'fs'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
-import { checkToken, resolveBase, readWiredToken } from './diagnose.mjs'
+import { checkToken, resolveBase, readWiredToken, wiredDistTag } from './diagnose.mjs'
 import { installSkills } from './skills.mjs'
 // Pure config-merge functions live in the editor adapters; setup imports (and re-exports) THE SAME
 // functions the `cortex install` path uses, so both write byte-identical config.
@@ -48,12 +48,14 @@ export async function runSetup(argv, version) {
     )
     process.exit(1)
   }
-  // Wire the moving `stable` dist-tag — NOT a frozen version. A bare spec lets npx reuse a stale
-  // cached build; a frozen `@x.y.z` freezes the machine on that version forever (the 0.9.5→0.9.6
-  // freeze that stranded a pilot install). A tag is re-resolved by npx against the registry, so
-  // machines pick up promoted releases on next launch without re-running setup. Promote a
-  // validated build with:  npm dist-tag add @theronap/cortex-mcp@<version> stable
-  const spec = `${PKG}@stable`
+  // Wire a moving dist-tag — NOT a frozen version. A bare spec lets npx reuse a stale cached build; a
+  // frozen `@x.y.z` freezes the machine on that version forever (the 0.9.5→0.9.6 freeze that stranded a
+  // pilot install). A tag is re-resolved by npx against the registry, so machines pick up promoted
+  // releases on next launch without re-running setup. Promote a validated build with:
+  //   npm dist-tag add @theronap/cortex-mcp@<version> stable
+  // PRESERVE an intentional @latest (dogfood) pin across re-runs (repair/setup) — otherwise this
+  // silently knocks a dogfooder back to @stable. Fresh installs and existing @stable get @stable.
+  const spec = wiredDistTag() === 'latest' ? `${PKG}@latest` : `${PKG}@stable`
   const base = resolveBase(process.env.CORTEX_URL)
   const home = homedir()
   const claudeJson = join(home, '.claude.json')

package/package.json

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