@theronap/cortex-mcp 0.9.48 → 0.9.50

package/lib/diagnose.mjs

@@ -69,7 +69,19 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 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 appHint = null
+  if (isJson) {
+    try {
+      const parsed = JSON.parse(bodyText)
+      appError = parsed?.error ?? null
+      // `hint` carries the RECOVERY instruction for the errors an agent is meant to act on, not
+      // just report: 409 would_drop ("re-author including the dropped sections…") and 413 too_large
+      // ("split the section…"). It used to be dropped here — only `error` survived — so the agent
+      // saw a bare code like "would_drop_sections" and had no idea what to do with it. The routes
+      // were writing careful self-heal guidance that never reached anyone.
+      appHint = typeof parsed?.hint === 'string' && parsed.hint.trim() ? parsed.hint.trim() : null
+    } catch { /* not json after all */ }
+  }
   const rid = requestId ? ` [request id: ${requestId}]` : ''
 
   if (status === 401 || (isJson && appError === 'invalid token')) {
@@ -90,7 +102,7 @@ export function classify(status, contentType, bodyText, requestId) {
   }
   return {
     kind: 'app', retriable: status >= 500,
-    message: `Cortex API ${status}: ${appError ?? 'unknown error'}.${rid}`,
+    message: `Cortex API ${status}: ${appError ?? 'unknown error'}.${appHint ? ` ${appHint}` : ''}${rid}`,
   }
 }
 
@@ -104,8 +116,22 @@ export function classify(status, contentType, bodyText, requestId) {
 // WORSE — 3 unbounded attempts stacked. Now worst case = (retries+1) * timeoutMs + backoff, and a
 // timed-out attempt is treated as transient (retried, then surfaced as the reach error the callers
 // already swallow). Tunable via CORTEX_HTTP_TIMEOUT_MS; per-call override via opts.timeoutMs.
+// ADR-0020 Stage 2 — this process's session identity, stamped on every request so the server can
+// resolve THIS session's write pointer instead of the person-wide one. Set once by the MCP server at
+// startup (setSessionKey); left null in the one-shot hook processes (capture, context_log), which
+// have no session of their own and correctly fall back to the account pointer.
+//
+// Injected HERE rather than at each call site because fetchCortex is the single chokepoint every
+// caller already funnels through — ~30 call sites pass their own `headers` object, and a header this
+// load-bearing must not depend on remembering it at each one.
+let SESSION_KEY = null
+export function setSessionKey(key) { SESSION_KEY = key || null }
+
 export async function fetchCortex(url, opts = {}, { retries = 2, baseDelayMs = 400 } = {}) {
-  const { timeoutMs: optTimeout, signal: callerSignal, ...fetchOpts } = opts
+  const { timeoutMs: optTimeout, signal: callerSignal, ...rest } = opts
+  const fetchOpts = SESSION_KEY
+    ? { ...rest, headers: { ...(rest.headers ?? {}), 'x-cortex-session-key': SESSION_KEY } }
+    : rest
   const timeoutMs = optTimeout ?? (Number(process.env.CORTEX_HTTP_TIMEOUT_MS) || 15_000)
   let lastErr
   for (let attempt = 0; attempt <= retries; attempt++) {

package/lib/red_link_triage.mjs

@@ -0,0 +1,30 @@
+// Red-link triage rendering (Mechanism 2) — the text an agent sees on a read_page miss.
+//
+// Standalone + dependency-free (like grep_cli.mjs) so it unit-tests without pulling the MCP SDK in.
+// server.mjs owns the fetch; this owns the wording.
+//
+// The demoted arm is the one that matters. A superseded/historical page stays greppable
+// (grep_brain_sections applies no validity filter) but read_page won't serve it (authored_page_tiers
+// filters validity='current'), so an agent that greps a hit and then read_page's it lands here — and
+// used to be told "no page yet, author it now". Authoring is pre-authorized, so the compliant next step
+// was to overwrite a page a human deliberately retired, with nothing to catch it. Absence invites
+// authoring; a demotion forbids it.
+//
+// Keyed off the ADDITIVE `t.demoted` flag, checked BEFORE category — never off a new category value. A
+// server predating the flag omits it and every arm behaves exactly as before, so client and server can
+// ship in either order.
+
+// PURE: triage payload → miss text.
+export function renderTriage(t, name) {
+  const refs = t.tracked
+    ? ` It's referenced by ${t.refCount} page${t.refCount === 1 ? '' : 's'}${t.isSteward ? ' and is routed to YOU as its most-likely steward' : ''}.`
+    : ''
+  const aliasHint = `if it's really an existing page under another title, \`grep "${name}"\` to find it, then \`alias_page name="${name}" target_name="<that page>"\``
+  if (t.demoted) {
+    return `\n\n[[${name}]] EXISTS but is marked ${t.validity ?? 'superseded'} — it was authored and then deliberately retired, so read_page (which serves only current pages) will not show it. It is NOT missing.${refs} Do NOT author over it: that would silently overwrite a decision someone made on purpose. Read it with \`page_history "${name}"\` then \`read_page "${name}"\` with a version. If it genuinely should be live again, revive it deliberately with \`set_page_validity\`.`
+  }
+  if (t.category === 'node') {
+    return `\n\n[[${name}]] is a wanted page — a ${t.isPerson ? 'person' : 'node'} exists but has no page yet.${refs} Either author it now with \`author\`, or ${aliasHint}.`
+  }
+  return `\n\n"${name}" isn't authored anywhere yet.${refs} Either author a new page with \`author\`, or ${aliasHint}.`
+}

package/lib/server.mjs

@@ -5,29 +5,23 @@ import { writeFileSync, mkdirSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { createHash, randomUUID } from 'crypto'
-import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase, setSessionKey } from './diagnose.mjs'
 import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.mjs'
+import { renderTriage } from './red_link_triage.mjs'
 import { runCodeGraphQuery } from './code_graph_cli.mjs'
 
 // Reactive red-link triage (Mechanism 2). On a read_page miss, ask the server whether the name is a
-// tracked wanted page and whether a bare node exists for it, and turn that into an actionable 3-way
-// prompt (author-for-node / author-new / alias). Returns '' on any error so a miss never gets worse.
+// tracked wanted page, whether a bare node exists for it, and whether it's a deliberately demoted page,
+// and turn that into an actionable prompt. Wording lives in ./red_link_triage.mjs (pure + tested).
+// Returns '' on any error so a miss never gets worse.
 async function redLinkTriage(BASE, TOKEN, name) {
   try {
     const r = await fetchCortex(`${BASE}/api/brain/red-link?name=${encodeURIComponent(name)}`, {
       headers: { Authorization: `Bearer ${TOKEN}` },
     })
     if (!r.ok) return ''
-    const t = await r.json()
-    const refs = t.tracked
-      ? ` It's referenced by ${t.refCount} page${t.refCount === 1 ? '' : 's'}${t.isSteward ? ' and is routed to YOU as its most-likely steward' : ''}.`
-      : ''
-    const aliasHint = `if it's really an existing page under another title, \`grep "${name}"\` to find it, then \`alias_page name="${name}" target_name="<that page>"\``
-    if (t.category === 'node') {
-      return `\n\n[[${name}]] is a wanted page — a ${t.isPerson ? 'person' : 'node'} exists but has no page yet.${refs} Either author it now with \`author\`, or ${aliasHint}.`
-    }
-    return `\n\n"${name}" isn't authored anywhere yet.${refs} Either author a new page with \`author\`, or ${aliasHint}.`
+    return renderTriage(await r.json(), name)
   } catch {
     return ''
   }
@@ -49,6 +43,10 @@ export async function runServer(version) {
   // 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()
+  // 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.
+  setSessionKey(SESSION_KEY)
   async function pingSession() {
     try {
       await fetchCortex(`${BASE}/api/session-ping`, {
@@ -652,10 +650,26 @@ export async function runServer(version) {
         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 list brains: ${d.message}` }] }
       }
-      const { brains, activeIsExplicit } = await res.json()
+      const { brains, activeIsExplicit, activeSource, sessionOrgId, accountOrgId } = await res.json()
       if (!brains?.length) return { content: [{ type: 'text', text: 'You have no brains.' }] }
-      const lines = brains.map((b) => `${b.isActive ? '▶' : ' '} ${b.name}  (${b.role}${b.status !== 'active' ? `, ${b.status}` : ''})  [${b.orgId}]`)
-      const note = activeIsExplicit ? '' : '\n(active brain is the default — you have one brain; set_active_brain once you hold more.)'
+      // Show CONTENTS, not just the name (ADR-0020 §7 corollary): a brain named TTO that holds 4
+      // pages while the real TTO inventory sits in Personal reads as correct and is exactly
+      // backwards. The page count and a couple of titles make that visible at the moment of choosing.
+      const lines = brains.map((b) => {
+        const inv = b.pageCount === 0
+          ? 'EMPTY'
+          : `${b.pageCount} page${b.pageCount === 1 ? '' : 's'}${b.sampleTitles?.length ? `: ${b.sampleTitles.slice(0, 2).join(', ')}` : ''}`
+        return `${b.isActive ? '▶' : ' '} ${b.name}  (${b.role}${b.status !== 'active' ? `, ${b.status}` : ''})  — ${inv}  [${b.orgId}]`
+      })
+      // 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.)'
+        : 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}` }] }
     },
   )
@@ -664,16 +678,20 @@ export async function runServer(version) {
     '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). Sticky — it stays until you change it. Pass org_id = null to clear it and fall back to the default. You can only select a brain you are a member of.',
-      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') },
+      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.",
+      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()
+          .describe("'session' (default) = this window only; 'account' = person-wide, affects your other open sessions too"),
+      },
     },
-    async ({ org_id }) => {
+    async ({ org_id, scope }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brains`, {
           method: 'PUT',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ orgId: org_id ?? null }),
+          body: JSON.stringify({ orgId: org_id ?? null, scope: scope ?? 'session' }),
         })
       } catch (e) {
         return { content: [{ type: 'text', text: `Could not set active brain: ${e.message}` }] }
@@ -683,7 +701,15 @@ export async function runServer(version) {
         return { content: [{ type: 'text', text: `Could not set active brain: ${d.message}` }] }
       }
       const r = await res.json()
-      return { content: [{ type: 'text', text: r.activeOrgId ? `Writes now land in brain ${r.activeOrgId}.` : 'Cleared your active-brain pointer (writes fall back to your default brain).' }] }
+      // Always say WHICH scope changed. The default is session-only, so a caller expecting the old
+      // person-wide stickiness must be able to see that it did NOT change their other windows.
+      const where = r.scope === 'session' ? 'this session only' : 'ALL your sessions (person-wide)'
+      if (!r.activeOrgId) {
+        return { content: [{ type: 'text', text: r.scope === 'session'
+          ? 'Cleared this session\'s brain override — writes fall back to your account pointer.'
+          : 'Cleared your account-wide active-brain pointer (writes fall back to your default brain).' }] }
+      }
+      return { content: [{ type: 'text', text: `Writes now land in brain ${r.activeOrgId} — ${where}.` }] }
     },
   )
 

package/package.json

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