@theronap/agnoclast-mcp 0.9.208 → 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}` }] }
     },
   )
 
@@ -5515,9 +5512,10 @@ function renderNudge(payload) {
         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.'),
         to: z.string().describe('who becomes the owner — an org member\'s email, or their user id. Must be an ACTIVE member of the same brain as the page. Pass your own address to take ownership yourself.'),
         confirm_audience: z.string().optional().describe('ONLY after a refusal that lists who would start reading the page. A reports / peers / down page is addressed to its OWNER\'s team, so a new owner means a new audience; the first call is refused with the names and a confirm token. Pass that token here once the person asking has seen the list and means it. The token covers exactly that list — if the page or the org chart changed since, it is refused again with the new one. Never guess it and never send it on a first call.'),
+        tier_decision: z.enum(['keep', 'delegate', 'accessible', 'down', 'reports', 'peers', 'scoped', 'confidential']).optional().describe('REQUIRED for a reports / peers / down page (Theron, 2026-10-03: whoever hands one over re-evaluates its tier then and there). "keep" = same tier, re-aimed at the new owner\'s team; a tier = owner and tier change together; "delegate" = the new owner decides, and until they do NOTHING about the page changes — same owner, same readers — while they may read it to decide. Ask the person which they want; never pick one for them. Omit it for any other tier (it transfers as before).'),
       },
     },
-    async ({ kind, name, ref, to, confirm_audience }) => {
+    async ({ kind, name, ref, to, confirm_audience, tier_decision }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brain/node-policy`, {
@@ -5525,7 +5523,7 @@ function renderNudge(payload) {
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
           // No `tier`: a node has exactly one page (ADR-0064 §4), and the route resolves it. Sending a
           // guessed tier is how this used to 404 on precisely the scoped/confidential pages it matters for.
-          body: JSON.stringify({ kind, ...(name ? { name } : {}), ...(ref ? { ref } : {}), transfer_to: to, ...(confirm_audience ? { confirm_audience } : {}) }),
+          body: JSON.stringify({ kind, ...(name ? { name } : {}), ...(ref ? { ref } : {}), transfer_to: to, ...(confirm_audience ? { confirm_audience } : {}), ...(tier_decision ? { tier_decision } : {}) }),
         })
       } catch (e) {
         return toolError(`Could not transfer ownership: ${e.message}`)
@@ -5538,10 +5536,21 @@ function renderNudge(payload) {
         const d = classify(res.status, res.headers.get('content-type'), '', res.headers.get('x-vercel-id'))
         return toolError(`Could not transfer ownership: ${d.message}`)
       }
+      if (out?.pending_for) {
+        return {
+          content: [{
+            type: 'text',
+            text: `Handed over for re-evaluation — ${to} decides this page's tier. Nothing about the page has changed: it is still ${out.tier}, owned and read exactly as before, until they choose.${out.reader_granted ? ' They were given read access so they can decide.' : ''} They see it at their next session start and complete it with confirm_page_ownership.`,
+          }],
+        }
+      }
+      const retier = out?.retiered
+        ? ` It moved from ${out.retiered.from} to ${out.retiered.to} in the same step${out.retiered.cascaded_records ? `; ${out.retiered.cascaded_records} record(s) filed under it followed the narrowing` : ''}.`
+        : ` The page is still ${out.tier}${tier_decision === 'keep' ? ', now addressed to its new owner\'s team' : '; transferring at this tier does not re-tier, so check that its audience is still right'}.`
       return {
         content: [{
           type: 'text',
-          text: `Done — ${name ?? out.ref} now belongs to ${to}. The page is still ${out.tier}; transferring never re-tiers, so check that its audience is still right.${renderAudienceChange(out.audience_change)}`,
+          text: `Done — ${name ?? out.ref} now belongs to ${to}.${retier}${renderAudienceChange(out.audience_change)}`,
         }],
       }
     },
@@ -5555,13 +5564,39 @@ function renderNudge(payload) {
     'confirm_page_ownership',
     {
       title: 'Confirm pages handed to you',
-      description: 'When someone hands you a page — a colleague using transfer_page_ownership, or a steward rehoming a departed member\'s page — your session start lists it under "Pages handed to you" until you confirm it. Pass the page `refs` (as listed there) to confirm those, or `all: true` for every open one. Confirming only clears the notice: the page is already yours. To pass one on instead, use transfer_page_ownership.',
+      description: 'When someone hands you a page — a colleague using transfer_page_ownership, or a steward rehoming a departed member\'s page — your session start lists it under "Pages handed to you" until you confirm it. Pass the page `refs` (as listed there) to confirm those, or `all: true` for every open one. Confirming only clears the notice: the page is already yours. To pass one on instead, use transfer_page_ownership. A page listed under "Pages waiting on your tier decision" is DIFFERENT: it is not yours yet, and stays exactly as it was until you choose. Take it with `ref` + `tier_decision` ("keep" its tier, re-aimed at your team, or a tier); `all` never takes those.',
       inputSchema: {
         refs: z.array(z.string()).optional().describe('page refs, as listed under "Pages handed to you"'),
-        all: z.boolean().optional().describe('true = confirm every open notice'),
+        all: z.boolean().optional().describe('true = confirm every open notice (never takes a page waiting on your tier decision)'),
+        ref: z.string().optional().describe('ONE page waiting on your tier decision, as listed under "Pages waiting on your tier decision"'),
+        tier_decision: z.enum(['keep', 'accessible', 'down', 'reports', 'peers', 'scoped', 'confidential']).optional().describe('with `ref`: "keep" its tier (re-aimed at your team) or the tier it should have. Ask the person; never choose for them.'),
+        confirm_audience: z.string().optional().describe('ONLY after a refusal listing who would start reading the page — the token from it, once the person has seen the list and means it.'),
       },
     },
-    async ({ refs, all }) => {
+    async ({ refs, all, ref, tier_decision, confirm_audience }) => {
+      if (ref || tier_decision) {
+        if (!ref || !tier_decision) return toolError('To take a page waiting on your tier decision, pass both `ref` and `tier_decision`.')
+        let res
+        try {
+          res = await fetchCortex(`${BASE}/api/brain/ownership-notices`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ref, tier_decision, ...(confirm_audience ? { confirm_audience } : {}) }),
+          })
+        } catch (e) {
+          return toolError(`Could not take the page: ${e.message}`)
+        }
+        const out = await res.json().catch(() => null)
+        if (!res.ok) {
+          if (out?.error) return toolError(`Could not take the page: ${out.error}`)
+          const d = classify(res.status, res.headers.get('content-type'), '', res.headers.get('x-vercel-id'))
+          return toolError(`Could not take the page: ${d.message}`)
+        }
+        const moved = out?.from_tier && out.from_tier !== out.tier
+          ? ` It moved from ${out.from_tier} to ${out.tier}${out.cascaded_records ? `; ${out.cascaded_records} record(s) filed under it followed the narrowing` : ''}.`
+          : ` It stays ${out?.tier}, now addressed to your team.`
+        return { content: [{ type: 'text', text: `Done — the page is yours.${moved}${renderAudienceChange(out?.audience_change)}` }] }
+      }
       if (!all && !(refs && refs.length)) return toolError('Pass `refs` (the pages to confirm) or `all: true`.')
       let res
       try {
@@ -6029,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.208",
+  "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": {