@theronap/agnoclast-mcp 0.9.209 → 0.9.210

package/lib/identifier_routes.mjs

@@ -0,0 +1,81 @@
+// WHERE AN IDENTIFIER ROUTES, AND WHAT A FILING SESSION MAY CLAIM — pure renderers (ADR-0075, 2026-10-05).
+//
+// 🔴 THE LINE THIS REPLACES TOLD A SESSION SOMETHING FALSE. `read_page "file:…"` printed "Home: X" for
+// the page whose BODY carried the [[stamp]], and for an unclaimed identifier said "author its page and
+// stamp [[id]] on it (that page becomes the home)". Since ADR-0026 a body stamp routes nothing — the
+// router reads page_routing_identifiers only — so following that advice produced a page the router never
+// sends anything to, and the session was told it worked. That is the 2026-10-04 V4 email-surface
+// incident. The server now answers `homes` from CLAIMS and moves stamp pages to `mentionedOn`; this
+// prints the two apart and gives `set_routing_identifier` as the fix.
+//
+// Pure so CI can execute what each state prints.
+
+const q = (s) => `"${s}"`
+const pageLabel = (h) => `${q(h.title)} (${h.kind}, ${h.tier})`
+
+/**
+ * The read_page identifier view, as lines. Handles the pre-ADR-0075 server too (no `mentionedOn`):
+ * there `homes` are stamp pages, so they are printed as mentions, never as where anything routes.
+ */
+export function renderIdentifierResolution(out, { expand = false } = {}) {
+  const id = out.identifier
+  const lines = [`# ${id} (identifier — a join key, not a page)`]
+  const claimAware = Array.isArray(out.mentionedOn)
+  const homes = claimAware ? (out.homes ?? []) : []
+  const mentions = claimAware ? out.mentionedOn : (out.homes ?? [])
+  const catchAll = claimAware ? (out.catchAll ?? []) : []
+  const hidden = claimAware ? Number(out.hiddenClaims ?? 0) : 0
+
+  if (!claimAware) {
+    lines.push('This server cannot say where it ROUTES (it predates ADR-0075); the pages below only mention it, and a mention routes nothing. `my_routing_claims` lists the claims that do.')
+  } else if (homes.length === 1 && out.status !== 'duplicate') {
+    const h = homes[0]
+    const how = h.via === id ? 'claims it' : `claims the folder \`${h.via}\` above it`
+    lines.push(`Routes to: ${pageLabel(h)} — it ${how}. \`read_page ${q(h.title)}\` for the page.`)
+  } else if (homes.length >= 1) {
+    lines.push(out.status === 'duplicate'
+      ? `⚠ More than one page claims this at the same depth — a record carrying it is filed under all of them (and STAGES if they sit in different brains). Settle which one it belongs to:`
+      : `Routes to ${homes.length} pages, deepest claim first — a record carrying it is filed under each:`)
+    for (const h of homes) lines.push(`  - ${pageLabel(h)} via \`${h.via}\`${h.brain ? ` · ${h.brain}` : ''}`)
+  }
+  if (hidden > 0) {
+    lines.push(`${hidden} claim${hidden === 1 ? '' : 's'} on page${hidden === 1 ? '' : 's'} you cannot open — ${hidden === 1 ? 'it routes' : 'they route'} all the same.`)
+  }
+  if (claimAware && homes.length === 0 && hidden === 0) {
+    const fallback = catchAll.length
+      ? ` Records carrying it are filed only under the repo catch-all: ${catchAll.map((h) => q(h.title)).join(', ')} (via \`${catchAll[0].via}\`).`
+      : ''
+    lines.push(
+      `No page claims this, so it routes nowhere on its own.${fallback} If a page is ABOUT it, claim it there: ` +
+      `\`set_routing_identifier\` with identifier ${q(id)}${id.startsWith('file:') && !id.endsWith('/') ? ' (or the deepest folder above it, with its trailing slash)' : ''}. ` +
+      'A [[stamp]] in a page body does NOT make that page its home.',
+    )
+  } else if (catchAll.length) {
+    lines.push(`Also filed under the repo catch-all: ${catchAll.map((h) => q(h.title)).join(', ')} (via \`${catchAll[0].via}\`).`)
+  }
+  if (mentions.length) {
+    lines.push(`Mentioned on (does not route): ${mentions.map((h) => q(h.title)).join(', ')}`)
+  }
+  const ev = out.events ?? { visibleCount: 0, recent: [] }
+  lines.push(`· ${ev.visibleCount} tagged timeline event${ev.visibleCount === 1 ? '' : 's'} visible to you${ev.recent?.length ? ':' : expand ? '.' : ' — pass expand: true to list recent ones.'}`)
+  for (const e of ev.recent ?? []) lines.push(`  - ${String(e.occurredAt).slice(0, 10)} · ${e.source} · ${e.summary}`)
+  return lines
+}
+
+/** intake_materialize: the folder-claim offers, as lines. [] when the server sent none (or is older). */
+export function renderFolderClaimOffers(offers) {
+  if (!Array.isArray(offers) || offers.length === 0) return []
+  const lines = ['Folder claim offered (nothing was claimed — decide, do not just accept):']
+  for (const o of offers) if (o && typeof o.offer === 'string') lines.push(`  - ${o.offer}`)
+  return lines.length > 1 ? lines : []
+}
+
+/** author / edit_page: [[file:…]] stamps the write left that route nothing to this page, as lines. */
+export function renderUnroutedPathStamps(body) {
+  const stamps = Array.isArray(body?.unroutedPathStamps) ? body.unroutedPathStamps : []
+  if (!stamps.length) return []
+  const lines = [`⚠ ${stamps.length} [[file:…]] stamp${stamps.length === 1 ? '' : 's'} on this page route${stamps.length === 1 ? 's' : ''} nothing here: ${stamps.map((s) => `\`${s.identifier}\``).join(', ')}.`]
+  if (typeof body.unroutedPathStampsNote === 'string') lines.push(body.unroutedPathStampsNote)
+  for (const s of stamps) if (typeof s.fix === 'string') lines.push(`  - ${s.fix}`)
+  return lines
+}

package/lib/server.mjs

@@ -9,6 +9,7 @@ import { seatChargeRefusal, seatChargeQuestion } from './seat_charge.mjs'
 import { fetchCortex, classify, resolveBase, resolveEnvToken, setSessionKey, setClientVersion, runWithTool, heartbeatPolicy } from './diagnose.mjs'
 import { REPORT_KINDS, REPORT_ISSUE_DESCRIPTION, fileIssue } from './report_issue.mjs'
 import { folderClaimLine } from './folder_claims.mjs'
+import { renderFolderClaimOffers, renderIdentifierResolution, renderUnroutedPathStamps } from './identifier_routes.mjs'
 import { resolveSessionKey, resolveLogSessionId } from './session_key.mjs'
 import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.mjs'
@@ -1343,6 +1344,9 @@ function renderNudge(payload) {
       //   null/undefined  no container was ever requested (say nothing)
       // containerSkipped is the only one that needs a warning: it means a container WAS asked for and
       // did not happen, which is exactly the silence this whole path exists to remove.
+      // ADR-0075 — the deepest unclaimed folder this unit sits in, offered for the feature page it was
+      // filed onto. Never claimed by the server; the session decides.
+      lines.push(...renderFolderClaimOffers(body?.folderClaimOffers))
       if (body?.containerSkipped) {
         lines.push(`⚠ CONTAINER NOT APPLIED — ${body.containerSkipped}. The record exists but is not inside the event you named; place it with contain_record or leave it out.`)
       } else if (body?.contained === true) {
@@ -1874,7 +1878,7 @@ function renderNudge(payload) {
       description:
         'READ the full authored wiki page for one node (project/person/org/you) by its canonical name — every section you can see. This is how you READ a node; `grep` only LOCATES pages (snippets + their [[links]]), it does not read them. Navigate like a researcher: read the page you need, then FOLLOW its inline [[links]] by calling read_page on each linked name — keep following while the linked pages stay relevant, stop when they do not. You decide how deep to go. Returns only what you are permitted to see.',
       inputSchema: {
-        name: z.string().describe('the canonical node name exactly as written (e.g. "Agnoclast", "Ben", or a [[link]] target) — identifier links ([[repo:owner/name]]) resolve to their authored HOME + a visible-event count'),
+        name: z.string().describe('the canonical node name exactly as written (e.g. "Agnoclast", "Ben", or a [[link]] target) — identifier links ([[repo:owner/name]], [[file:owner/name:path]]) resolve to the page(s) that CLAIM them — where the router actually files records — plus the pages that merely mention them, and a visible-event count'),
         kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('node kind — a PREFERENCE, not a filter. The lookup matches every kind by title and only prefers this one when several share a name, so omitting it never hides a person/org/user page. Pass it to disambiguate a name that exists as more than one kind.'),
         expand: z.boolean().optional().describe('identifier names only: also list recent visible timeline events for this identifier (default: home + count)'),
         history: z.boolean().optional().describe('node names only: return the node\'s TIMELINE (events joined via its [[repo:…]] stamps, reverse-chron, viewer-visible) instead of the page body. The page is the present; this is the history.'),
@@ -1962,18 +1966,8 @@ function renderNudge(payload) {
           const r = await fetchCortex(`${BASE}/api/identifier/resolve?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
           if (r.ok) {
             const out = await r.json()
-            const lines = [`# ${out.identifier} (identifier — a join key, not a page)`]
-            if (out.status === 'unhomed') {
-              lines.push(`No authored home carries this stamp yet — data but no home. If you know what this identifies, author its page and stamp [[${out.identifier}]] on it (that page becomes the home).`)
-            } else if (out.status === 'healthy') {
-              const h = out.homes[0]
-              lines.push(`Home: "${h.title}" (${h.kind}, ${h.tier}) — \`read_page "${h.title}"\` for the full page.`)
-            } else {
-              lines.push(`⚠ ${out.homes.length} pages carry this stamp — possible duplicate homes, consider reconciling:`)
-              for (const h of out.homes) lines.push(`  - "${h.title}" (${h.kind}, ${h.tier})`)
-            }
-            lines.push(`· ${out.events.visibleCount} tagged timeline event${out.events.visibleCount === 1 ? '' : 's'} visible to you${out.events.recent.length ? ':' : expand ? '.' : ' — pass expand: true to list recent ones.'}`)
-            for (const e of out.events.recent) lines.push(`  - ${String(e.occurredAt).slice(0, 10)} · ${e.source} · ${e.summary}`)
+            // ADR-0075: `homes` are CLAIMS (where the router files it); stamp pages are `mentionedOn`.
+            const lines = renderIdentifierResolution(out, { expand })
             // KWA-28 — an identifier node is VIRTUAL: derived per read, zero stored rows, so there is no
             // as_of to fetch. The item says exactly what to do in that case: "where the object is derived
             // per-read, stamp the read itself." Note this as-of means something DIFFERENT from every
@@ -3988,7 +3982,10 @@ function renderNudge(payload) {
       const undatedNote = out?.undated === true
         ? `\n⚠ This section now carries no explicit calendar date. A reader can see WHEN the text was written but not when the claim was TRUE. If it asserts a status, add the date inline — you still hold the context. The edit already landed; this is advisory.`
         : ''
-      return { content: [{ type: 'text', text: `Edited "${name}" (${out.brain} · ${out.tier} tier) § ${out.heading}. Only that passage changed; every other section is byte-identical. New version: ${out.version}${red}${undatedNote}` }] }
+      // ADR-0075 — a [[file:…]] stamp this edit wrote that routes nothing here, with the claim that would.
+      const unroutedLines = renderUnroutedPathStamps(out)
+      const unrouted = unroutedLines.length ? `\n${unroutedLines.join('\n')}` : ''
+      return { content: [{ type: 'text', text: `Edited "${name}" (${out.brain} · ${out.tier} tier) § ${out.heading}. Only that passage changed; every other section is byte-identical. New version: ${out.version}${red}${undatedNote}${unrouted}` }] }
     },
   )
 
@@ -6067,8 +6064,11 @@ function renderNudge(payload) {
           ` can read the page. Re-send with identity_claim_ack: true only if the subject is publishing` +
           ` their own contact detail; otherwise use a confidential section or set_routing_identifier.`
         : ''
+      // ADR-0075 — [[file:…]] stamps that route nothing here, each with the claim that would. Advisory.
+      const unroutedLines = renderUnroutedPathStamps(out)
+      const unrouted = unroutedLines.length ? `\n${unroutedLines.join('\n')}` : ''
       const verb = out?.created ? 'Created + authored' : 'Authored'
-      const note = out?.built ? `${verb} "${name}" (${out.built} tier${out.built === 1 ? '' : 's'}). Links: ${blue} resolved, ${retired} retired, ${red} red.${corrections}${retiredList}${redList}${stamps}${undated}${identityRefused}`
+      const note = out?.built ? `${verb} "${name}" (${out.built} tier${out.built === 1 ? '' : 's'}). Links: ${blue} resolved, ${retired} retired, ${red} red.${corrections}${retiredList}${redList}${stamps}${undated}${identityRefused}${unrouted}`
         : `No change to "${name}"${out?.skipped?.length ? ` (${out.skipped.join(', ')})` : ''}.${corrections}`
       return { content: [{ type: 'text', text: note }] }
     },

package/package.json

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