@theronap/cortex-mcp 0.9.76 → 0.9.77

package/bin/cortex-mcp.mjs

@@ -52,7 +52,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  skills          install/repair the managed Agnoclast skills — bundled + org-published (also wired by setup)\n` +
     `  skills push <file>     publish a SKILL.md to your org (owner/manager/admin)\n` +
     `  docs-scan       detect new/changed local docs pending Agnoclast authoring (used by /cortex-author-docs)\n` +
-    `  graphify-sync [path]  rebuild the local code graph (graphify) + log an evidence-tier timeline event\n` +
+    `  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` +
     `  statusline      ambient presence line for the Claude Code statusline (local read only)\n` +
@@ -122,7 +122,7 @@ if (cmd === 'login') {
 } else if (cmd === 'resolve') {
   // Entity identity dedup: judge the server-flagged fuzzy duplicate pairs locally via `claude -p`.
   const { runResolve } = await import('../lib/resolve.mjs')
-  await runResolve()
+  await runResolve(rest)
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
 } else if (cmd === 'materialize') {

package/lib/diagnose.mjs

@@ -90,10 +90,19 @@ export function classify(status, contentType, bodyText, requestId) {
   const isJson = (contentType ?? '').includes('application/json')
   let appError = null
   let appHint = null
+  let appMessage = null
+  let appBrains = null
   if (isJson) {
     try {
       const parsed = JSON.parse(bodyText)
       appError = parsed?.error ?? null
+      // Same lesson as `hint`, one layer up. brain_choice_response.ts writes a full explanation to
+      // `message` and every brain's NAME / PAGE COUNT / SAMPLE TITLES to `brains` — its comment says
+      // "THE BODY IS THE ANSWER TO ITS OWN QUESTION", precisely so a model can pick a brain from what
+      // each one HOLDS. Only `error` survived here, so the agent got the bare code `brain_required`
+      // and could not answer it. Measured on the CLI twin of this bug: `✗ brain_required`, full stop.
+      appMessage = typeof parsed?.message === 'string' && parsed.message.trim() ? parsed.message.trim() : null
+      appBrains = Array.isArray(parsed?.brains) ? parsed.brains : 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
@@ -120,6 +129,25 @@ export function classify(status, contentType, bodyText, requestId) {
         `Vercel firewall / deployment protection on the API route. Re-running setup will not help.${rid}`,
     }
   }
+  // A brain-choice refusal is ANSWERABLE, so it must arrive as the question it is rather than as a
+  // code. Deliberately narrow: only these two errors reshape the message, so every other classify()
+  // output keeps its existing wording (and its tests).
+  if (isJson && (appError === 'brain_required' || appError === 'unknown_brain') && (appMessage || appBrains)) {
+    const list = (appBrains ?? []).map((b) => {
+      const pages = typeof b?.pageCount === 'number' ? ` — ${b.pageCount} page${b.pageCount === 1 ? '' : 's'}` : ''
+      const titles = Array.isArray(b?.sampleTitles) && b.sampleTitles.length
+        ? `: ${b.sampleTitles.slice(0, 2).join('; ')}` : ''
+      // Name AND id: brain names are NOT unique (one account holds two called "Personal"), so a name
+      // alone can come back as unknown_brain. The id always resolves.
+      return `  - ${b?.name ?? '(unnamed)'}${pages}${titles}${b?.orgId ? ` [${b.orgId}]` : ''}`
+    })
+    return {
+      kind: 'app', retriable: false,
+      message: `Agnoclast API ${status}: ${appMessage ?? appError}${list.length ? `\n${list.join('\n')}` : ''}` +
+        `\nRe-run this tool with \`brain\` set to one of the names or ids above.${rid}`,
+    }
+  }
+
   return {
     kind: 'app', retriable: status >= 500,
     message: `Agnoclast API ${status}: ${appError ?? 'unknown error'}.${appHint ? ` ${appHint}` : ''}${rid}`,

package/lib/graphify_sync.mjs

@@ -26,8 +26,42 @@ function repoFullNameFromRemote(cwd) {
   return m ? `${m[1]}/${m[2]}` : null
 }
 
+// `--brain <name-or-org-id>` — which brain an UNROUTED repo's graph event lands in.
+//
+// Deliberately a flag and nothing cleverer. /api/timeline/graphify routes deterministically by repo
+// (resolveSourceRoute) and only asks when the repo has no route; its comment is blunt about why it
+// must not be guessed: this writes a `records` row unique on (org_id, dedupe_key), so "a repo whose
+// graph updates land in two brains becomes two record sets that never reconcile, and re-pointing
+// later converges on nothing (ADR-0020). It is the one write class where a wrong answer is genuinely
+// unrecoverable." So: no sweep (unlike `resolve`, which is a maintenance pass over everything) and
+// no auto-pick.
+//
+// It does NOT create a source route as a side effect, though that would stop the question recurring:
+// routes are append-only precisely because "re-pointing a live source splits its history
+// irreparably", and a near-irreversible write should not fall out of a CLI flag. This command runs
+// from a per-repo cron/launchd job, so the flag lives in that job's definition — answered once,
+// where it is visible. (Route creation currently has NO client on any surface; that is a separate
+// gap, not this command's to paper over.)
+// Split argv into { cwd, brain }. Pure + exported so the ordering trap below is unit-testable
+// without a git repo, a graphify binary or a network.
+//
+// THE TRAP: argv[0] doubles as the optional repo path, and `--brain`'s VALUE has no leading '-'.
+// Parsed naively, `graphify-sync --brain Personal` reads "Personal" as the path and syncs whatever
+// happens to be there. So the flag and its value are stripped BEFORE the positional check.
+export function parseGraphifyArgs(argv = [], fallbackCwd = process.cwd()) {
+  const bIdx = argv.indexOf('--brain')
+  const brain = bIdx === -1 ? null : argv[bIdx + 1]
+  if (bIdx !== -1 && (!brain || brain.startsWith('-'))) {
+    return { error: 'Usage: graphify-sync [path] [--brain <name-or-org-id>]' }
+  }
+  const rest = bIdx === -1 ? argv : argv.filter((_, i) => i !== bIdx && i !== bIdx + 1)
+  return { cwd: rest[0] && !rest[0].startsWith('-') ? rest[0] : fallbackCwd, brain }
+}
+
 export async function runGraphifySync(argv = []) {
-  const cwd = argv[0] && !argv[0].startsWith('-') ? argv[0] : process.cwd()
+  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 BASE = resolveBase(process.env.CORTEX_URL)
   if (!TOKEN) {
@@ -73,11 +107,22 @@ export async function runGraphifySync(argv = []) {
   const res = await fetchCortex(`${BASE}/api/timeline/graphify`, {
     method: 'POST',
     headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-    body: JSON.stringify({ repo, commitSha, nodeCount, edgeCount, communityCount }),
+    body: JSON.stringify({ repo, commitSha, nodeCount, edgeCount, communityCount, ...(brain ? { brain } : {}) }),
   })
   if (!res.ok) {
     const body = await res.text()
-    process.stderr.write(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message + '\n')
+    const d = classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id'))
+    process.stderr.write(d.message + '\n')
+    // classify names the brains but speaks in MCP terms ("re-run this tool with `brain`"). Say the
+    // actual flag, and where to put it — this runs unattended from cron, so the person reading this
+    // is looking at a log after the fact, not a prompt.
+    if (res.status === 409 && !brain) {
+      process.stderr.write(
+        `\n${repo} has no routing decision yet, so it cannot be filed without one.\n` +
+        `Re-run with:  cortex-mcp graphify-sync ${cwd === process.cwd() ? '' : `${cwd} `}--brain "<name-or-org-id>"\n` +
+        `and add that flag to this repo's cron/launchd job so it stops asking.\n`,
+      )
+    }
     return 1
   }
   const payload = await res.json()

package/lib/resolve.mjs

@@ -8,47 +8,97 @@ import { edgeSafeEnv } from './edge_extract.mjs'
 // and pushes decisions back (POST /api/resolve-apply): confident-same → entity_merges, else → rejected
 // so the pair never re-flags. Conservative by construction. Always exits cleanly.
 
-export async function runResolve() {
+// Which brains to sweep. BOTH endpoints require the brain to be NAMED (ADR-0022 requireBrain —
+// answering a scoped read out of an ARBITRARY brain is the defect that whole class exists to
+// prevent). Until 2026-08-09 this command named none, so a multi-brain caller got 409 on step 1 and
+// the dedup sweep did nothing at all, silently, forever.
+//
+// Naming ONE brain would have been the smaller fix and the wrong one: `resolve` is a MAINTENANCE
+// SWEEP over the user's entities, so doing one brain and reporting success is ADR-0022's other
+// failure — "silently truncating a result set and presenting it as complete". With no --brain we
+// enumerate the caller's brains and sweep EACH, naming it explicitly. Not a guess: every request
+// still names exactly one brain, and all of them actually get done.
+//
+// A sole-brain caller sees today's behaviour: one pass, no flag, no prompt.
+export async function brainsToSweep(base, token, wanted, deps = {}) {
+  const fetchFn = deps.fetchCortex ?? fetchCortex
+  if (wanted) return [{ orgId: wanted, name: wanted }] // explicit: pass through (name or org id)
+  const res = await fetchFn(`${base}/api/brains`, { headers: { Authorization: `Bearer ${token}` } })
+  if (!res.ok) {
+    const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+    throw new Error(`could not list your brains — ${d.message}`)
+  }
+  const j = await res.json().catch(() => ({}))
+  const brains = Array.isArray(j.brains) ? j.brains : []
+  // Carry the ORG ID, never the name: brain names are NOT unique (this account holds two called
+  // "Personal"), and a duplicate name comes back as unknown_brain.
+  return brains.filter((b) => b?.orgId).map((b) => ({ orgId: b.orgId, name: b.name ?? b.orgId }))
+}
+
+export async function runResolve(argv = []) {
   // recursion guard (we spawn `claude --print`; if its Stop hook fires capture, that no-ops on this flag)
   if (process.env.CORTEX_SUMMARIZING) { process.stderr.write('cortex: summarizer subprocess, skipping\n'); return }
   const token = process.env.CORTEX_TOKEN
   if (!token) { process.stderr.write('cortex: CORTEX_TOKEN not set, skipping\n'); return }
   const base = resolveBase(process.env.CORTEX_URL)
 
+  const bIdx = argv.indexOf('--brain')
+  const wanted = bIdx === -1 ? null : argv[bIdx + 1]
+  if (bIdx !== -1 && (!wanted || wanted.startsWith('-'))) {
+    process.stderr.write('Usage: resolve [--brain <name-or-org-id>]\n'); return
+  }
+
+  let targets
+  try {
+    targets = await brainsToSweep(base, token, wanted)
+  } catch (e) { process.stderr.write(`cortex: resolve — ${e.message}\n`); return }
+  if (!targets.length) { process.stderr.write('cortex: no brains to sweep\n'); return }
+
+  for (const t of targets) {
+    // Label each line with the brain when sweeping several: an unlabelled "merged 3" cannot be acted
+    // on, because you cannot tell WHERE three entities just merged.
+    await resolveOneBrain(base, token, t, targets.length > 1)
+  }
+}
+
+async function resolveOneBrain(base, token, brain, labelled) {
+  const tag = labelled ? `[${brain.name}] ` : ''
+  const qs = `?brain=${encodeURIComponent(brain.orgId)}`
+
   // 1. pull the flagged candidate pairs
   let candidates = []
   try {
-    const res = await fetchCortex(`${base}/api/resolve-candidates`, { headers: { Authorization: `Bearer ${token}` } })
+    const res = await fetchCortex(`${base}/api/resolve-candidates${qs}`, { headers: { Authorization: `Bearer ${token}` } })
     if (!res.ok) {
       const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-      process.stderr.write(`cortex: resolve-candidates failed — ${d.message}\n`); return
+      process.stderr.write(`cortex: ${tag}resolve-candidates failed — ${d.message}\n`); return
     }
     const j = await res.json().catch(() => ({}))
     candidates = Array.isArray(j.candidates) ? j.candidates : []
-  } catch (e) { process.stderr.write(`cortex: resolve fetch failed — ${e.message}\n`); return }
+  } catch (e) { process.stderr.write(`cortex: ${tag}resolve fetch failed — ${e.message}\n`); return }
 
-  if (!candidates.length) { process.stderr.write('cortex: no duplicate candidates to judge\n'); return }
-  process.stderr.write(`cortex: judging ${candidates.length} candidate pair(s) locally…\n`)
+  if (!candidates.length) { process.stderr.write(`cortex: ${tag}no duplicate candidates to judge\n`); return }
+  process.stderr.write(`cortex: ${tag}judging ${candidates.length} candidate pair(s) locally…\n`)
 
   // 2. judge locally on the subscription
   const decisions = judgeCandidates(candidates)
-  if (decisions === null) { process.stderr.write('cortex: judge unavailable (is `claude` on PATH?) — skipping\n'); return }
+  if (decisions === null) { process.stderr.write(`cortex: ${tag}judge unavailable (is \`claude\` on PATH?) — skipping\n`); return }
 
-  // 3. apply judged decisions
+  // 3. apply — SAME brain the candidates came from, or the merges land in the wrong graph
   try {
-    const res = await fetchCortex(`${base}/api/resolve-apply`, {
+    const res = await fetchCortex(`${base}/api/resolve-apply${qs}`, {
       method: 'POST',
       headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
       body: JSON.stringify({ decisions }),
     })
     if (res.ok) {
       const j = await res.json().catch(() => ({}))
-      process.stderr.write(`cortex: dedup — merged ${j.merged ?? 0}, rejected ${j.rejected ?? 0}, skipped ${j.skipped ?? 0}\n`)
+      process.stderr.write(`cortex: ${tag}dedup — merged ${j.merged ?? 0}, rejected ${j.rejected ?? 0}, skipped ${j.skipped ?? 0}\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: resolve-apply failed — ${d.message}\n`)
+      process.stderr.write(`cortex: ${tag}resolve-apply failed — ${d.message}\n`)
     }
-  } catch (e) { process.stderr.write(`cortex: resolve-apply failed — ${e.message}\n`) }
+  } catch (e) { process.stderr.write(`cortex: ${tag}resolve-apply failed — ${e.message}\n`) }
 }
 
 // ONE `claude --print` call judges every pair. Returns DedupDecision[] for the apply endpoint, or null

package/lib/server.mjs

@@ -892,13 +892,15 @@ export async function runServer(version) {
     'writing_style',
     {
       title: 'How the user writes (for drafting in their voice)',
-      description: 'Returns the user\'s saved writing-style profile so you can DRAFT in their voice (email, message, doc). Call this right before composing anything on their behalf. Self-only — it is always the calling user\'s own profile. If none is saved, it tells you to derive one and save it with set_writing_style.',
-      inputSchema: {},
+      description: 'Returns the user\'s saved writing-style profile so you can DRAFT in their voice (email, message, doc). Call this right before composing anything on their behalf. Self-only — it is always the calling user\'s own profile. If none is saved, it tells you to derive one and save it with set_writing_style. A profile is stored per (user, BRAIN) — it is injected into authoring IN a brain — so if you hold several, name the one you are drafting in.',
+      inputSchema: {
+        brain: z.string().optional().describe('which brain\'s style profile, by name or org id. Unnecessary when you only have one brain; pass the org id when a name matches more than one of yours'),
+      },
     },
-    async () => {
+    async ({ brain } = {}) => {
       let res
       try {
-        res = await fetchCortex(`${BASE}/api/style`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+        res = await fetchCortex(`${BASE}/api/style${brain ? `?brain=${encodeURIComponent(brain)}` : ''}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
         return toolError(`Could not load writing style: ${e.message}`)
       }
@@ -916,12 +918,15 @@ export async function runServer(version) {
     {
       title: 'Save the user\'s writing-style profile',
       description: 'Save (or update) a description of HOW the user writes — tone, sentence rhythm, structure, formatting habits, signature quirks — derived from prose you have seen them write this session. Store the STYLE, never their private content. Self-only: it always updates the calling user\'s own profile. Pass an empty string to clear it.',
-      inputSchema: { style_md: z.string().describe('a concise markdown description of the user\'s writing voice (tone/structure/quirks), ~1-2 paragraphs') },
+      inputSchema: {
+        style_md: z.string().describe('a concise markdown description of the user\'s writing voice (tone/structure/quirks), ~1-2 paragraphs'),
+        brain: z.string().optional().describe('which brain to save the profile in, by name or org id. A profile is stored per (user, brain), so this is a real choice when you hold several; pass the org id when a name matches more than one of yours'),
+      },
     },
-    async ({ style_md }) => {
+    async ({ style_md, brain }) => {
       let res
       try {
-        res = await fetchCortex(`${BASE}/api/style`, {
+        res = await fetchCortex(`${BASE}/api/style${brain ? `?brain=${encodeURIComponent(brain)}` : ''}`, {
           method: 'PUT',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
           body: JSON.stringify({ style_md }),
@@ -1159,7 +1164,7 @@ export async function runServer(version) {
     'list_brain_pages',
     {
       title: 'List every authored page in one brain',
-      description: 'Enumerate ALL authored pages in ONE brain, by its org id (from my_brains). Unlike my_brains — which ships only a count plus a few sample titles — this returns the FULL page list: one row per node with its kind, validity, tier(s), last-updated date and content hash. Use it to audit a brain, or to VERIFY a brain-to-brain migration — list BOTH brains, diff the page sets, and compare freshness before retiring any original. You can only list a brain you are a member of; reads never widen past your own brains.',
+      description: 'Enumerate ALL authored pages in ONE brain, by its org id (from my_brains). Unlike my_brains — which ships only a count plus a few sample titles — this returns the FULL page list: one row per node with its kind, validity, tier(s), last-updated date and content hash. Use it to audit a brain, or to VERIFY a brain-to-brain migration — list BOTH brains, diff the page sets, and compare freshness before retiring any original. You can only list a brain you are a member of, and within it you see only the pages you are cleared to read — a confidential page owned by someone else is not listed, not even by title.',
       inputSchema: {
         org_id: z.string().describe('the org id of the brain to enumerate (from my_brains)'),
       },

package/package.json

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