@theronap/cortex-mcp 0.9.123 → 0.9.124

package/lib/diagnose.mjs

@@ -155,6 +155,7 @@ export function classify(status, contentType, bodyText, requestId) {
   let appHint = null
   let appMessage = null
   let appBrains = null
+  let appCandidates = null
   if (isJson) {
     try {
       const parsed = JSON.parse(bodyText)
@@ -166,6 +167,9 @@ export function classify(status, contentType, bodyText, requestId) {
       // 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
+      // ambiguous_brain carries the COLLIDING subset separately. Prefer it: listing all of
+      // someone's brains when only two share the name buries the answer in the noise.
+      appCandidates = Array.isArray(parsed?.candidates) ? parsed.candidates : 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
@@ -193,21 +197,32 @@ export function classify(status, contentType, bodyText, requestId) {
     }
   }
   // 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()
+  // code. Deliberately narrow: only these three 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) => {
+  //
+  // `ambiguous_brain` was added 2026-08-28 WITH the server change that first emits it. Shipping that
+  // server change alone would have been a net REGRESSION here: the fallthrough below renders
+  // `appError`, not `appMessage`, so a duplicate brain name would have reached the agent as the bare
+  // string "Agnoclast API 409: ambiguous_brain." — strictly less actionable than the unknown_brain it
+  // replaced, which this branch already caught. Same defect the CHANGELOG records for `brain_required`.
+  const isBrainChoice = appError === 'brain_required' || appError === 'unknown_brain' || appError === 'ambiguous_brain'
+  if (isJson && isBrainChoice && (appMessage || appBrains || appCandidates)) {
+    // `?.length`, not `??`: an empty candidates array is not nullish, so `??` would have kept it
+    // and rendered a refusal that says "the candidates below" above nothing at all.
+    const list = (appCandidates?.length ? appCandidates : (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 `  - ${b?.name ?? b?.brain ?? '(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}`,
+        `\n${appError === 'ambiguous_brain'
+          ? 'Re-run this tool with `brain` set to one of the IDS above. A name is what was ambiguous, so passing a name again cannot resolve it.'
+          : 'Re-run this tool with `brain` set to one of the names or ids above.'}${rid}`,
     }
   }
 

package/lib/resolve.mjs

@@ -31,7 +31,7 @@ export async function brainsToSweep(base, token, wanted, deps = {}) {
   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.
+  // "Personal"), and a duplicate name comes back as ambiguous_brain (409).
   return brains.filter((b) => b?.orgId).map((b) => ({ orgId: b.orgId, name: b.name ?? b.orgId }))
 }
 

package/lib/server.mjs

@@ -324,9 +324,14 @@ function renderNudge(payload) {
       }
 
       // Records are unique on the ORG-SCOPED (org_id, dedupe_key) and every segment carries this
-      // session's dedupe key. Cross-brain segments therefore never collide — that constraint is what
-      // makes the whole design work — but two aimed at the SAME brain would silently merge and lose
-      // one. Refuse instead of letting that happen quietly.
+      // session's dedupe key, so cross-brain segments never collide AS RECORDS.
+      //
+      // ⚠ That is only half the path, and reading it as the whole path is what broke segmenting for
+      // twelve days. Upstream of records sits a private-intake unit keyed per ACCOUNT, which the
+      // org-scoping does not help at all — see `segmentKey` below. Records were never the problem.
+      //
+      // Two segments aimed at the SAME brain would still silently merge and lose one, at both
+      // layers. Refuse instead of letting that happen quietly.
       const seenBrain = new Set()
       for (const s of list) {
         const k = String(s.brain ?? '').trim().toLowerCase()
@@ -371,6 +376,13 @@ function renderNudge(payload) {
               ...(seg.project ? { project: seg.project } : {}),
               ...(seg.title ? { title: seg.title } : {}),
               ...(sessionId ? { sessionId } : {}),
+              // ONE session split across brains: every segment carries the SAME `sessionId` on
+              // purpose — it is the only thing pairing them. But a private-intake unit is keyed per
+              // ACCOUNT, not per brain, so without a discriminator all segments collapse onto ONE
+              // unit: the first materializes and the rest fail `materialize_failed`. Sent ONLY when
+              // actually segmenting, so a single-brain log keeps its exact previous key and no
+              // pending unit is orphaned.
+              ...(list.length > 1 && seg.brain ? { segmentKey: String(seg.brain) } : {}),
               // ADR-0022 deleted the write pointer, so a session-class source routes ONLY by an
               // explicit brain or a sole membership — anything else STAGES. This tool never sent one,
               // so every close-out from a multi-brain member landed in staged_records instead of the
@@ -2605,6 +2617,57 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'rename_page',
+    {
+      title: 'Give a page a correct name',
+      description: "Change the TITLE of an existing page, keeping the page itself — every record, attachment, routing claim, grant and revision on it survives untouched, because they all point at the node id and nothing anywhere points at a name. Use it on the stub names automatic minting produces from an email localpart or a display-name header: `Bna2005` -> `Brandon Andersen`, `Theriv` -> `The Riviera`, `Kentgee` -> `Kent Gee`. NOT COSMETIC — a stub carrying a bad name will not dedupe against the real person when they are authored properly, so renaming it is how you PREVENT the duplicate that would otherwise have to be merged later. The old name is kept as an alias automatically, so existing [[links]] and readers who know the old name still resolve. Renaming ONTO a name another page already holds is refused, naming the holder: combining two pages is a merge decision, not a rename. `user` pages cannot be renamed (that is an account identity).",
+      inputSchema: {
+        kind: z.enum(['project', 'person', 'org']).describe('the page kind'),
+        name: z.string().optional().describe('current page title (or pass ref)'),
+        ref: z.string().optional().describe('node ref from read_page — prefer over name when available, and REQUIRED when the current name is ambiguous across brains'),
+        brain: z.string().optional().describe('brain label when the title is ambiguous across brains'),
+        new_name: z.string().describe('the correct title, written the way it should read on the page'),
+      },
+    },
+    async ({ kind, name, ref, brain, new_name }) => {
+      if (!name && !ref) return toolError('Pass the page by `name` or `ref`.')
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/rename-page`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ kind, newName: new_name, ...(name ? { name } : {}), ...(ref ? { ref } : {}), ...(brain ? { brain } : {}) }),
+        })
+      } catch (e) {
+        return toolError(`Could not rename: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        // An ambiguous name is the case most likely to hit here, because a stub name that needs
+        // fixing is exactly the kind of name that got minted more than once. Hand back the refs.
+        if (out?.error === 'ambiguous_page' && Array.isArray(out.candidates)) {
+          const rows = out.candidates.map((c) => `  • ${c.brain} — ref ${c.ref}`).join('\n')
+          return toolError(`"${name}" names a page in more than one brain. Re-run with the ref of the one you mean:\n${rows}`)
+        }
+        if (out?.error === 'name_taken') {
+          return toolError(`Not renamed — ${out.detail ?? `"${new_name}" is already held by another page`}. Renaming onto it would silently combine two pages; request a merge instead.`)
+        }
+        if (out?.error === 'unchanged') return toolError(`Not renamed — ${out.detail ?? 'that is the same name'}.`)
+        if (out?.error === 'kind_not_renamable') return toolError(`Not renamed — ${out.detail ?? 'that page kind cannot be renamed'}.`)
+        return toolError(`Could not rename: ${out?.detail ?? out?.error ?? res.status}`)
+      }
+      if (!out) return { content: [{ type: 'text', text: `Renamed to "${new_name}", but the server returned no body — re-read the page to confirm.` }] }
+      // Report what the server OBSERVED. `recordsCarried` is the number that answers the question a
+      // caller actually has about a rename ("did the page keep its stuff?"), so it is never omitted —
+      // including when it is 0, which is the truth for a freshly minted stub.
+      const lines = [`Renamed "${out.from}" -> "${out.to}" in ${out.brain} (${out.kind}, ref ${out.ref}).`]
+      lines.push(`${out.recordsCarried} record(s) came along; ${out.documentsRetitled} tier-doc(s) retitled.`)
+      lines.push(`"${out.aliasWritten}" still resolves to this page, so existing [[links]] are not broken.`)
+      return { content: [{ type: 'text', text: lines.join(' ') }] }
+    },
+  )
+
   server.registerTool(
     'unalias_page',
     {
@@ -2795,20 +2858,62 @@ function renderNudge(payload) {
         reason: z.string().describe('why these pages — recorded with the attachment'),
         park: z.boolean().optional().describe('no good home exists; leave it alone rather than guessing'),
         tier: z.number().int().optional().describe('2 when this came from the cheap sweep rather than your own context'),
+        identifierDispositions: z.array(z.any()).optional().describe(
+          'ADR-0044. REQUIRED when this record carries identifiers no page claims — the refusal names exactly which. '
+          + 'One entry per unresolved identifier, and this is a DIFFERENT question from documentIds. '
+          + '⚠ AN IDENTIFIER BELONGS ON THE PAGE WHOSE SUBJECT *HAS* IT — a person page for their address, a project '
+          + "page for that project's repo. Association is not attribution: a person who WORKS ON a repo does not get "
+          + 'the repo identifier, and a project does not get a contributor\'s email. So the right page is FREQUENTLY '
+          + 'NOT one of the pages you are routing to. Routing asks what this RECORD is about (several pages); this '
+          + 'asks what each IDENTIFIER is an attribute of (one page). '
+          + 'Forms: {identifier, page} to claim on an existing page (id or ref) · '
+          + '{identifier, createPage:{name, kind, brain}} when the thing has no page yet — the usual case for a new '
+          + 'correspondent, and brain is required because pages cannot move between brains · '
+          + '{none:true, identifiers:[...], reason} when they are attributes of nothing worth a page. '
+          + '`none` takes MANY at once by design — a mailing list can carry 190 recipients and disposing of them one '
+          + 'by one would make the record impossible to finish. It SUPPRESSES NOTHING: the same address arriving '
+          + 'tomorrow is asked about again, and the record itself is still filed either way.',
+        ),
       },
     },
-    async ({ recordId, documentIds, reason, park, tier }) => {
+    async ({ recordId, documentIds, reason, park, tier, identifierDispositions }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brain/triage`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ action: park ? 'park' : 'route', recordId, documentIds, reason, tier }),
+          body: JSON.stringify({ action: park ? 'park' : 'route', recordId, documentIds, reason, tier, identifierDispositions }),
         })
       } catch (e) {
         return toolError(`Could not route record: ${e.message}`)
       }
       const out = await res.json().catch(() => null)
+      // ADR-0044 refusal. Render it as INSTRUCTIONS, not as an error string: the agent is one call
+      // away from succeeding and needs to know which identifiers and what the rule is. A bare
+      // "identifiers_undisposed" would send it hunting through docs for a contract it was never told.
+      if (!res.ok && out?.error === 'identifiers_undisposed') {
+        const lines = [
+          'Cannot finish — this record carries identifiers that no page claims:',
+          ...(out.undisposed ?? []).map((i) => `    ${i}`),
+          '',
+          'Each needs a disposition. An identifier belongs on the page whose SUBJECT HAS it — a person',
+          'page for their address, a project page for that project\'s repo. Association is not',
+          'attribution, so this is often NOT a page you are routing the record to.',
+          '',
+          '  {identifier, page}                            claim on an existing page',
+          '  {identifier, createPage:{name, kind, brain}}  the thing has no page yet',
+          '  {none:true, identifiers:[...], reason}        attributes of nothing worth a page',
+          '',
+          '`none` takes many at once and suppresses nothing — tomorrow\'s copy is asked again.',
+        ]
+        if (out.claimedSoFar?.length) {
+          lines.push('', `Already claimed this call: ${out.claimedSoFar.map((c) => `${c.identifier} -> ${c.page}`).join(', ')}`)
+        }
+        if (out.errors?.length) {
+          lines.push('', `Refused: ${out.errors.map((e) => `${e.identifier} (${e.error})`).join(', ')}`)
+        }
+        return toolError(lines.join('\n'))
+      }
       if (!res.ok) return toolError(`Could not route record: ${out?.error ?? res.status}${out?.detail ? ` — ${out.detail}` : ''}`)
       if (park) return { content: [{ type: 'text', text: 'Parked. It stays visible and unrouted rather than badly attached.' }] }
       return { content: [{ type: 'text', text: `Routed — attached to ${out?.attached?.length ?? 0} page(s). Recorded as a session judgment, not a rule match.` }] }

package/lib/skills.mjs

@@ -320,16 +320,25 @@ export async function syncOrgSkills(opts = {}) {
 // have, or what to type next. Pure + exported so the shape is unit-testable without a network.
 export function renderPushError(body, status) {
   const lines = [body?.message ?? body?.error ?? `HTTP ${status}`]
-  const brains = Array.isArray(body?.brains) ? body.brains : []
+  const ambiguous = body?.error === 'ambiguous_brain'
+  // Prefer the COLLIDING subset. On an ambiguity the full list buries the answer: two rows reading
+  // "Personal" among five brains is not a choice anyone can make.
+  const candidates = Array.isArray(body?.candidates) ? body.candidates : []
+  const brains = candidates.length ? candidates : (Array.isArray(body?.brains) ? body.brains : [])
   if (brains.length) {
-    lines.push('', '  Your brains:')
+    lines.push('', ambiguous ? '  Brains matching that name:' : '  Your brains:')
     for (const b of brains) {
       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('; ')}` : ''
-      lines.push(`    ${b?.name ?? b?.orgId ?? '(unnamed)'}${pages}${titles}`)
+      // ALWAYS print the id. Without it an ambiguity refusal is a dead end: every row reads the same,
+      // and the only address that separates them is the one this line was omitting.
+      const id = b?.orgId ? ` [${b.orgId}]` : ''
+      lines.push(`    ${b?.name ?? b?.brain ?? '(unnamed)'}${pages}${titles}${id}`)
     }
-    lines.push('', '  Re-run with --brain "<name>".')
+    lines.push('', ambiguous
+      ? '  Re-run with --brain "<id>" — a name is what was ambiguous, so a name cannot resolve it.'
+      : '  Re-run with --brain "<name>".')
   }
   return lines.join('\n')
 }

package/package.json

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