@theronap/cortex-mcp 0.9.48 → 0.9.49

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

@@ -8,26 +8,20 @@ import { createHash, randomUUID } from 'crypto'
 import { fetchCortex, classify, resolveBase } 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 ''
   }

package/package.json

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