@theronap/cortex-mcp 0.9.65 → 0.9.66

package/lib/server.mjs

@@ -557,6 +557,12 @@ export async function runServer(version) {
         // word "today" from sections it was never meant to touch. This footer renders on EVERY
         // page read in the system, so it was the single widest surface pointing the wrong way.
         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 — fix just that passage with \`edit_page\`: quote the wrong text as old_string and pass this page's \`version\` as base_version (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). If the save comes back stale the page changed under you — the conflict hands back what changed, so re-anchor from that instead of re-reading. Reading a stale page you can fix IS the trigger to fix it. Editing is pre-authorized — do NOT ask the user before updating (edits are versioned + reversible via page_history/rollback_page); update, then briefly report it. Use \`author\` only to CREATE a page or rewrite one wholesale: it re-emits every section, so untouched sections get retyped on the way through and drift.\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.`
+        // ADDRESSING (2026-08-04). The server accepts `ref` on every page/node route and its ambiguity
+        // 409s hand refs back — but read_page never PRINTED one, so the only way to obtain a ref was to
+        // trigger the error first. That made ID addressing reachable in principle and unusable in
+        // practice. The ref is per-NODE (engram_ref) while `version` is per-TIER, which is why it rides
+        // on the page header rather than inside a tier block.
+        if (m.ref) footer += `\n— \`ref:\` above is this page's stable id. Pass it as \`ref\` to any page tool (set_page_privacy, page grants, node policy, author, rollback, node timeline) to address THIS page: refs are unique across brains, so two pages sharing a name in different brains cannot collide and no active-brain guess is involved. Prefer it over \`name\` whenever you already hold one.`
         // 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()))]
@@ -568,7 +574,10 @@ export async function runServer(version) {
         // saw the footer, and repaired the page. A dashboard nobody opens would not have.
         if (m.backlog?.nudge) footer += `\n— ${m.backlog.nudge}`
         const brainTag = tagBrain ? `  ·  brain: ${m.brain}` : ''
-        return `# ${m.title ?? name} (full authored page${brainTag})\n\n${blocks.join('\n\n---\n\n')}\n\n${footer}`
+        // Always emitted, not only in the multi-brain case: the ref is what makes the brain question
+        // moot, so withholding it until brains collide is exactly backwards.
+        const refLine = m.ref ? `\nref: ${m.ref}` : ''
+        return `# ${m.title ?? name} (full authored page${brainTag})${refLine}\n\n${blocks.join('\n\n---\n\n')}\n\n${footer}`
       }
       if (matches.length === 1) {
         return { content: [{ type: 'text', text: renderMatch(matches[0], false) }] }
@@ -1400,20 +1409,21 @@ export async function runServer(version) {
       description: 'Re-tier a wiki page you own or may edit: "accessible" (anyone in the org), "scoped" (owner + their management chain), or "confidential" (owner only, plus explicit grants). Demoting a PROJECT page also demotes its evidence records (demote-only; each record\'s owner is notified and can revert). Promotions never touch records. If the target tier already has a page, merge your content into it via `author` FIRST, then read_page the target again to get its fresh version, then re-run this with absorb=true and target_version=<that version> — absorb will REJECT (not silently drop content) if target_version doesn\'t match what\'s actually there, so a merge that didn\'t really land can\'t destroy your source page. Org admins may demote any page, never promote.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
-        name: z.string().describe('the exact page name'),
+        name: z.string().optional().describe('the exact page name (or pass `ref` instead — one of the two is required)'),
+        ref: z.string().optional().describe('the page\'s stable id, printed as `ref:` by read_page. PREFER THIS over name when you have it: a ref is unique across brains, so it addresses exactly one page and never needs a brain to disambiguate it.'),
         tier: z.enum(['accessible', 'scoped', 'confidential']).describe('the new visibility tier'),
         source_tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('when the node has multiple tier variants: which one to move'),
         absorb: z.boolean().optional().describe('after merging your content into an existing target-tier page via author: true removes your now-absorbed source variant. Requires target_version.'),
         target_version: z.string().optional().describe('REQUIRED with absorb=true — the target page\'s version, read via read_page AFTER your author() merge landed. Proves the merge actually happened before your source page is deleted; a stale or guessed value is rejected, not silently accepted.'),
       },
     },
-    async ({ kind, name, tier, source_tier, absorb, target_version }) => {
+    async ({ kind, name, ref, tier, source_tier, absorb, target_version }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brain/page-privacy`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ kind, name, tier, ...(source_tier ? { source_tier } : {}), ...(absorb ? { absorb: true } : {}), ...(target_version ? { target_version } : {}) }),
+          body: JSON.stringify({ kind, ...(name ? { name } : {}), ...(ref ? { ref } : {}), tier, ...(source_tier ? { source_tier } : {}), ...(absorb ? { absorb: true } : {}), ...(target_version ? { target_version } : {}) }),
         })
       } catch (e) {
         return toolError(`Could not set page privacy: ${e.message}`)
@@ -1445,19 +1455,20 @@ export async function runServer(version) {
       description: 'Share one of YOUR non-accessible wiki pages with a specific org member (or take that access back). A grant lets exactly that person read the page even though its tier would hide it — the escape hatch for "confidential, but Dana needs it". Owner-only. Grants survive re-tiering: revoke them when they should end.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
-        name: z.string().describe('the exact page name'),
-        grantee: z.string().describe('the org member\'s display name or email (must resolve uniquely — use email if ambiguous)'),
+        name: z.string().optional().describe('the exact page name (or pass `ref` instead — one of the two is required)'),
+        ref: z.string().optional().describe('the page\'s stable id, printed as `ref:` by read_page. Prefer this over name: unique across brains, so it addresses exactly one page.'),
+        grantee: z.string().describe('display name or email of a member OF THE PAGE\'S BRAIN (must resolve uniquely — use email if ambiguous)'),
         action: z.enum(['grant', 'revoke']).describe('grant or revoke'),
         tier: z.enum(['scoped', 'confidential']).optional().describe('which variant (default: the most restrictive one)'),
       },
     },
-    async ({ kind, name, grantee, action, tier }) => {
+    async ({ kind, name, ref, grantee, action, tier }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brain/page-grants`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ kind, name, grantee, action, ...(tier ? { tier } : {}) }),
+          body: JSON.stringify({ kind, ...(name ? { name } : {}), ...(ref ? { ref } : {}), grantee, action, ...(tier ? { tier } : {}) }),
         })
       } catch (e) {
         return toolError(`Could not ${action}: ${e.message}`)
@@ -1476,13 +1487,15 @@ export async function runServer(version) {
       description: 'Show every explicit access grant on YOUR page\'s tier variants (owner-only). Use after re-tiering a page — grants survive tier changes and keep granting until revoked.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
-        name: z.string().describe('the exact page name'),
+        name: z.string().optional().describe('the exact page name (or pass `ref` instead — one of the two is required)'),
+        ref: z.string().optional().describe('the page\'s stable id, printed as `ref:` by read_page. Prefer this over name: unique across brains, so it addresses exactly one page.'),
       },
     },
-    async ({ kind, name }) => {
+    async ({ kind, name, ref }) => {
       let res
+      const addr = ref ? `ref=${encodeURIComponent(ref)}` : `name=${encodeURIComponent(name ?? '')}`
       try {
-        res = await fetchCortex(`${BASE}/api/brain/page-grants?kind=${encodeURIComponent(kind)}&name=${encodeURIComponent(name)}`, {
+        res = await fetchCortex(`${BASE}/api/brain/page-grants?kind=${encodeURIComponent(kind)}&${addr}`, {
           headers: { Authorization: `Bearer ${TOKEN}` },
         })
       } catch (e) {

package/package.json

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