@theronap/cortex-mcp 0.9.123 → 0.9.125

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
@@ -1871,13 +1883,70 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'staged_records',
+    {
+      title: 'List staged arrivals — the ones in no brain yet, with their ids',
+      description: "List arrivals that are STAGED: held in no brain at all, because nothing could decide which brain they belong to, or because they carry identifiers the graph has never seen. This is the ONLY way to obtain a `staged_id`. `pending_records` structurally cannot see these (it reads records, and a staged row is not one); `intake_changes` returns ids from a different queue that `place_staged_record` rejects; and the session-start block prints titles without ids. Until this existed, placing a staged arrival required a human to read a uuid off a screen. Returns each arrival's id, title, age and the identifiers BLOCKING it, plus `blocking_summary` — the unclaimed identifiers ranked by how many arrivals each one holds, so you can see which single `set_routing_identifier` releases the most. ⚠ Claiming an identifier UNBLOCKS but does not place: which pages an arrival lands on decides its brain, and therefore who can read it, so that stays a decision someone makes.",
+      inputSchema: {
+        limit: z.number().optional().describe('max arrivals to return (default 50, max 200). `total` always reports the WHOLE queue regardless.'),
+        source: z.string().optional().describe("narrow to one connector kind, e.g. 'email' or 'github'"),
+      },
+    },
+    async ({ limit, source }) => {
+      const qs = new URLSearchParams()
+      if (limit) qs.set('limit', String(limit))
+      if (source) qs.set('source', source)
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/staged${qs.toString() ? `?${qs}` : ''}`, {
+          headers: { Authorization: `Bearer ${TOKEN}` },
+        })
+      } catch (e) {
+        return toolError(`Could not list staged arrivals: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return toolError(`Could not list staged arrivals: ${out?.error ?? res.status}`)
+      if (!out) return toolError('The server returned no body.')
+
+      if (!out.total) {
+        return { content: [{ type: 'text', text: 'Nothing staged — every arrival has reached a brain.' }] }
+      }
+      const lines = [`${out.total} staged arrival(s) — in NO brain yet:`, '']
+      for (const a of out.arrivals ?? []) {
+        // The id goes FIRST on its own line. It is the argument place_staged_record needs and the
+        // entire reason this tool exists; burying it after prose is how the session-start block
+        // managed to list these rows for weeks without making one of them actionable.
+        lines.push(`  ${a.stagedId}`)
+        lines.push(`    ${a.title ?? '(no subject)'}  ·  ${a.sourceType}  ·  ${a.occurredAt?.slice(0, 10) ?? ''}`)
+        if (a.blockingIdentifiers?.length) {
+          lines.push(`    blocked by: ${a.blockingIdentifiers.join(', ')}`)
+        } else {
+          lines.push('    held because no brain could be determined (no unknown identifiers)')
+        }
+      }
+      if ((out.arrivals ?? []).length < out.total) {
+        lines.push('', `  … ${out.total - out.arrivals.length} more not shown — raise \`limit\` to see them.`)
+      }
+      if (out.blockingSummary?.length) {
+        lines.push('', 'Unclaimed identifiers holding the most arrivals — claim one and that many unblock:')
+        for (const b of out.blockingSummary.slice(0, 10)) {
+          lines.push(`  ${b.arrivals}x  ${b.identifier}`)
+        }
+        lines.push('', 'Claim with set_routing_identifier on the page whose subject HAS that identifier.')
+      }
+      lines.push('', 'Place one with place_staged_record (staged_id + pages). The pages decide the brain, which decides who can read it.')
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    },
+  )
+
   server.registerTool(
     'place_staged_record',
     {
       title: 'Place a staged arrival onto pages — the pages decide its brain',
       description: "Place a STAGED arrival — one that is in no brain at all — onto the pages it belongs to, which is also what decides its brain. Session-start lists these separately as `[staged]`, and they are the only rows route_record CANNOT take, because there is no record yet to route: nothing upstream chose a brain for them, deliberately. That is the point (ADR-0038) — the connector used to pick the brain from which mailbox the message arrived through, which is a fact about your email plumbing rather than about the message, and it decided WHO COULD READ IT before anyone had read it. Here the pages decide instead. ⚠ PLACING IS A DISCLOSURE DECISION, not just filing: a brain is the confidentiality boundary, so putting a staged message into a shared brain makes it readable by every member of that brain. Say so when you offer, and never place a personal message into a shared brain without the owner\'s explicit answer. All the pages must live in ONE brain — a record exists in exactly one — and pages spanning two brains are refused by name rather than resolved by picking. On success the content is replayed through the real ingest pipeline into that brain, so the record it produces is identical to one that had landed there directly, and then it is attached.",
       inputSchema: {
-        staged_id: z.string().describe('the staged id, as the [staged] rows at session start show it'),
+        staged_id: z.string().describe('the staged id — get it from `staged_records`, which is the only surface that prints one (session-start lists these arrivals but not their ids)'),
         pages: z.array(z.string()).describe("pages to place it on — a brain_documents id or the `ref:` read_page prints. They must all be in ONE brain; that brain is where the record lands."),
         reason: z.string().describe('WHY these pages — recorded with the attachment, and the one thing that cannot be inferred later'),
       },
@@ -2605,6 +2674,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 +2915,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.125",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {