@theronap/cortex-mcp 0.9.91 → 0.9.92

package/lib/red_link_triage.mjs

@@ -21,7 +21,14 @@ export function renderTriage(t, name) {
     : ''
   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\`.`
+    // KWA-28 — `red_link_targets` is a graph-side object and must carry an as-of. The server ALREADY
+    // sends `updatedAt` on this arm (the retirement's own timestamp) and this renderer was dropping it,
+    // so "deliberately retired" read as timeless. WHEN it was retired is the load-bearing fact here:
+    // the whole point of the arm is to stop an agent authoring over a human decision, and a decision
+    // from yesterday and one from eight months ago warrant different confidence about whether it still
+    // holds. Explicitly undated rather than silent when the server predates the field.
+    const when = t.updatedAt ? ` on ${String(t.updatedAt).slice(0, 10)}` : ' (retirement date not recorded)'
+    return `\n\n[[${name}]] EXISTS but is marked ${t.validity ?? 'superseded'} — it was authored and then deliberately retired${when}, 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}.`

package/lib/server.mjs

@@ -358,14 +358,20 @@ export async function runServer(version) {
             m = await fetchCortex(`${BASE}/api/intake/materialize`, {
               method: 'POST',
               headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+              // NESTED under `record`, and snake_case inside it. The route reads the record body
+              // from `body.record` and ignores top-level title/summary entirely — a flat body still
+              // answers `ok` with a recordId, having written a record with no content. Four such
+              // records exist in the corpus from exactly this mistake, and this call was the fifth
+              // until 2026-08-15: the close-out reported success while changing nothing.
               body: JSON.stringify({
                 intakeItemId: j.intakeItemId,
                 orgId,
-                title: seg.title,
-                summary: seg.summary,
-                source: 'claude-code',
-                recordType: 'ai_session',
-                origin: 'session',
+                record: {
+                  title: seg.title,
+                  summary: seg.summary,
+                  source: 'claude-code',
+                  record_type: 'ai_session',
+                },
               }),
             })
           } catch (e) {
@@ -1049,6 +1055,14 @@ export async function runServer(version) {
             }
             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}`)
+            // 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
+            // other one in gate 3 — "this answer was computed now", not "this claim was true then" — and
+            // the wording says so, because collapsing the two under one word is how a resolution that is
+            // merely FRESH gets read as a claim that is VERIFIED. The home and the count are both live
+            // computations over data that can change between two reads a minute apart.
+            lines.push(`· Resolved ${new Date().toISOString().slice(0, 16).replace('T', ' ')}Z — this node is derived per read (no stored row), so this is when the answer was COMPUTED, not when anything was verified.`)
             return { content: [{ type: 'text', text: lines.join('\n') }] }
           }
           if (r.status === 400) {
@@ -1438,7 +1452,13 @@ export async function runServer(version) {
       }
       const red = Array.isArray(out.redLinks) && out.redLinks.length
         ? `\nRed-links now on this page: ${out.redLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
-      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}` }] }
+      // KWA-26 — same advisory flag as `author`, on the path that actually gets used. Absent (not
+      // false) from an older server means "no verdict computed", so say nothing rather than imply the
+      // section is dated — the 0093 don't-impute rule.
+      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}` }] }
     },
   )
 
@@ -1718,15 +1738,34 @@ export async function runServer(version) {
     'list_brain_pages',
     {
       title: 'List every authored page in one brain',
-      description: 'Enumerate ALL authored pages in ONE brain, by its org id (from my_brains). Unlike my_brains — which ships only a count plus a few sample titles — this returns the FULL page list: one row per node with its kind, validity, tier(s), last-updated date and content hash. Use it to audit a brain, or to VERIFY a brain-to-brain migration — list BOTH brains, diff the page sets, and compare freshness before retiring any original. You can only list a brain you are a member of, and within it you see only the pages you are cleared to read — a confidential page owned by someone else is not listed, not even by title.',
+      description: 'QUERY the authored pages in ONE brain, by its org id (from my_brains) — filter by owner, recency, tier, kind or name, and sort. Returns one row per node with its kind, validity, tier(s), owner(s), last-updated date and content hash. This is the structural counterpart to `grep`: use it when the question is a FILTER-AND-SORT ("what has X written this week", "which pages are confidential", "what is stale") and grep when you need to match WORDS inside page text. ⚠ `validity` defaults to `current`, so superseded pages are EXCLUDED unless you ask for them — a stale page presented as live is a failure this system keeps hitting. Also use it to VERIFY a brain-to-brain migration: list BOTH brains, diff the page sets, compare freshness before retiring any original. You can only list a brain you are a member of, and within it you see only the pages you are cleared to read — a confidential page owned by someone else is not listed, not even by title, and that holds for every filter combination including `owner`.',
       inputSchema: {
         org_id: z.string().describe('the org id of the brain to enumerate (from my_brains)'),
+        owner: z.string().optional().describe('only pages owned by this person — a user id or an EXACT display name. A name matching no member of the brain is an error, never a silently empty list. Owner applies to scoped/confidential pages; accessible pages have no owner.'),
+        updated_within_days: z.number().optional().describe('only pages touched in the last N days'),
+        tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('only nodes that have a row at this tier. The row still reports every tier you can see, so a multi-tier page does not come back describing itself as single-tier.'),
+        kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('only nodes of this kind'),
+        validity: z.enum(['current', 'superseded', 'all']).optional().describe("default 'current'. Pass 'all' for the pre-2026-08 behavior, which mixed superseded pages in with nothing marking them."),
+        name_contains: z.string().optional().describe('case-insensitive substring match on the node name or page title'),
+        sort: z.enum(['recent', 'name']).optional().describe("default 'recent' (newest first). Ties break deterministically, so repeat calls are stable."),
+        limit: z.number().optional().describe('default 50, capped at 500'),
       },
     },
-    async ({ org_id }) => {
+    async ({ org_id, owner, updated_within_days, tier, kind, validity, name_contains, sort, limit }) => {
+      // Only send params the caller actually set: an omitted filter and an empty one are different
+      // requests, and the route validates enums strictly rather than ignoring unknown values.
+      const qs = new URLSearchParams({ orgId: org_id })
+      if (owner) qs.set('owner', owner)
+      if (updated_within_days != null) qs.set('updated_within_days', String(updated_within_days))
+      if (tier) qs.set('tier', tier)
+      if (kind) qs.set('kind', kind)
+      if (validity) qs.set('validity', validity)
+      if (name_contains) qs.set('name_contains', name_contains)
+      if (sort) qs.set('sort', sort)
+      if (limit != null) qs.set('limit', String(limit))
       let res
       try {
-        res = await fetchCortex(`${BASE}/api/brains/pages?orgId=${encodeURIComponent(org_id)}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+        res = await fetchCortex(`${BASE}/api/brains/pages?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
         return toolError(`Could not list pages: ${e.message}`)
       }
@@ -2696,7 +2735,7 @@ export async function runServer(version) {
     {
       title: 'Author a wiki node (live, while it is hot)',
       description:
-        'Write your CURRENT understanding of a project/person/org/you into the org wiki as a maintained page. Call `authoring_context` FIRST. Author from your own synthesis of the session — the compiled mental model, not a transcript dump: what it IS, where it stands, dated decisions, open threads, key people. Weave inline [[links]] to other nodes (canonical names from the namespace; red-links for wanted-but-absent nodes). The server re-authorizes the tier and resolves links. CREATES the node if it does not exist yet (project/person/org) — the conversation IS the evidence, so a brand-new entity that surfaced only in this session is authorable on the spot; you do NOT need prior records. Because such a node has nothing external to corroborate it, author it DELIBERATELY: only when you genuinely understand it is a real, distinct entity, and use its exact canonical name so it does not duplicate one already in the namespace (`user` nodes are never created). Use this continuously whenever your understanding of a node meaningfully advanced, and at session end (/log). Authoring is PRE-AUTHORIZED — never ask the user "should I update the page?" before calling this (every edit is versioned + reversible via page_history/rollback_page); update, then briefly report what you updated. ⚠ WHICH BRAIN A NEW PAGE GOES IN IS A CONTENT DECISION, SO MAKE IT FROM THE CONTENT. Only a page that exists in NO brain needs this — an update resolves its brain from the page itself. If you hold more than one brain, the server REFUSES a create it cannot attribute (409 `create_needs_brain`) rather than letting the write pointer decide — the pointer is stale out-of-band state that knows nothing about what you are writing. So call `my_brains` (it returns each brain\'s name, page count and sample titles, which is enough to tell what each one is FOR) and pass `brain` up front; that turns a refused round trip into a single call. State which brain you picked and why in one short line, then proceed — do NOT ask when the answer is obvious from the content. DO ask when it is genuinely ambiguous: brains are a confidentiality boundary, so a page born in the wrong one can expose private work to a teammate, and that is not a filing error you can quietly fix later.',
+        'Write your CURRENT understanding of a project/person/org/you into the org wiki as a maintained page. Call `authoring_context` FIRST. Author from your own synthesis of the session — the compiled mental model, not a transcript dump: what it IS, where it stands, dated decisions, open threads, key people. ⚠ EVERY STATUS CLAIM CARRIES AN EXPLICIT INLINE DATE (KWA-26): a sentence asserting what IS or IS NOT true right now — "X is live", "Y is not merged", "Z is blocked" — must say WHEN, in the prose, the way PRD items do. Section-level stamps are NOT enough: they record when the TEXT was written, so a section authored today can carry a six-week-old status claim and still read as current — exactly what made KWA-24 and TML-18 wrong. The response names any section that landed undated so you can fix it in-turn; it never blocks the write. Weave inline [[links]] to other nodes (canonical names from the namespace; red-links for wanted-but-absent nodes). The server re-authorizes the tier and resolves links. CREATES the node if it does not exist yet (project/person/org) — the conversation IS the evidence, so a brand-new entity that surfaced only in this session is authorable on the spot; you do NOT need prior records. Because such a node has nothing external to corroborate it, author it DELIBERATELY: only when you genuinely understand it is a real, distinct entity, and use its exact canonical name so it does not duplicate one already in the namespace (`user` nodes are never created). Use this continuously whenever your understanding of a node meaningfully advanced, and at session end (/log). Authoring is PRE-AUTHORIZED — never ask the user "should I update the page?" before calling this (every edit is versioned + reversible via page_history/rollback_page); update, then briefly report what you updated. ⚠ WHICH BRAIN A NEW PAGE GOES IN IS A CONTENT DECISION, SO MAKE IT FROM THE CONTENT. Only a page that exists in NO brain needs this — an update resolves its brain from the page itself. If you hold more than one brain, the server REFUSES a create it cannot attribute (409 `create_needs_brain`) rather than letting the write pointer decide — the pointer is stale out-of-band state that knows nothing about what you are writing. So call `my_brains` (it returns each brain\'s name, page count and sample titles, which is enough to tell what each one is FOR) and pass `brain` up front; that turns a refused round trip into a single call. State which brain you picked and why in one short line, then proceed — do NOT ask when the answer is obvious from the content. DO ask when it is genuinely ambiguous: brains are a confidentiality boundary, so a page born in the wrong one can expose private work to a teammate, and that is not a filing error you can quietly fix later.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the node type'),
         name: z.string().describe('the canonical node name — an EXACT existing name from the namespace to update it, or a new name to create the node (project/person/org). e.g. "Agnoclast" or "Theron Peterson"'),
@@ -2772,8 +2811,27 @@ export async function runServer(version) {
           ` If that is not the tier you meant, read_page and check which copy you just changed —` +
           ` a page can exist at several tiers and they drift apart independently.`
         : ''
+      // KWA-26 — the advisory undated flag. The server has computed `undatedSections` since #558 and
+      // the route has returned it ever since; NOTHING PRINTED IT, so the one consumer the item names
+      // never saw it: "the author path returns a flag naming undated status claims SO THE AGENT FIXES
+      // THEM IN-TURN." A flag the agent cannot see does not exist. Same shape as tierCorrections
+      // directly above — computed, returned, and silently dropped at the client — and the fourth
+      // instance of it in this subsystem.
+      //
+      // Advisory by DESIGN, not by omission: the write has already landed by the time this prints
+      // (2026-07-28, option (b) "make this blocking" was weighed and rejected — rejecting the write
+      // would lose the session's understanding, the more expensive failure). So this is phrased as
+      // work the agent can do NOW, while the context is still hot, which is the only moment the fix
+      // is cheap.
+      const undated = Array.isArray(out?.undatedSections) && out.undatedSections.length
+        ? `\n⚠ Undated (${out.undatedSections.length}): ${out.undatedSections.map((h) => `"${h}"`).join(', ')}.` +
+          ` These landed with no explicit calendar date in the heading or body, so a reader cannot tell` +
+          ` WHEN the claim was true — only when the text was last written. If any of them assert a` +
+          ` STATUS ("X is live", "Y is not merged"), add the date inline with edit_page while you still` +
+          ` hold the context. The write already landed; this is advisory.`
+        : ''
       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}`
+      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}`
         : `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/cortex-mcp",
-  "version": "0.9.91",
+  "version": "0.9.92",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {