@theronap/cortex-mcp 0.9.90 → 0.9.91

package/lib/server.mjs

@@ -40,6 +40,38 @@ async function redLinkTriage(BASE, TOKEN, name) {
 // file-request tools, and a module-level `fail` would be silently shadowed by it from that point on.
 const toolError = (text) => ({ content: [{ type: 'text', text }], isError: true })
 
+// SECTION CURRENCY (gate 3) — ONE renderer, used by BOTH read_page and project_status.
+//
+// Extracted as a PURE function on the pickBrainMatch precedent: that fix pulled a shared rule out of two
+// resolvers specifically so they could not drift, after they drifted. This is the same situation found
+// 2026-08-15. THREE surfaces render authored sections from the same server-computed fields:
+//   • renderAuthoredNodeBody (web/lib/engine/authored_page_tiers.ts) — console/web
+//   • read_page here          — printed a date and "⚠ Undated section" as two adjacent lines
+//   • project_status here     — printed NO currency at all: no as-of, no warning, nothing
+// PR #558 fixed only the first. project_status is the tool the routing docs reach for FIRST, and gate 3
+// reads "a reader can date any claim without a second query" — a reader there could date nothing.
+//
+// The two dates are DIFFERENT facts and both true: `asOf` is when the section's text last CHANGED; an
+// explicit date in the prose is when the CLAIM was true. Stated as one sentence they inform; stacked as
+// two lines they read as the page contradicting itself.
+//
+// ⚠ Do NOT "simplify" this by keying on `asOf` — it is set on every section always, so the detector
+// would go silent everywhere. The branch must key on `hasExplicitDate`, and on `=== false` rather than
+// falsy: `undefined` is an older server mid-rolling-deploy that has computed no verdict, and inventing
+// one there is the 0093 don't-impute violation.
+export const sectionCurrencyStamp = (s, day) => {
+  const on = s.asOf ? day(s.asOf) : ''
+  return s.hasExplicitDate === false
+    ? `${on ? ` · text last written ${on} —` : ' —'} ⚠ the claim itself carries no date; verify before relying on it`
+    : (on ? ` · as of ${on}` : '')
+}
+
+// ⚠ The newline is a FIX, not cosmetics. read_page's old form was `${asOf}${currency}${s.body}`, where
+// only the UNDATED branch contributed a trailing \n — so every DATED section ran its body straight onto
+// the header line ("· as of 2026-08-14Identifiers are candidates, never publication."). The defect was
+// invisible on exactly the sections that were healthy.
+export const renderSection = (s, day) => `### ${s.heading}${sectionCurrencyStamp(s, day)}\n${s.body}`
+
 // The Agnoclast MCP server (stdio). Serves the signed-in employee's scoped org
 // context to their AI assistant. CORTEX_TOKEN identifies the user + org.
 
@@ -539,7 +571,7 @@ export async function runServer(version) {
     {
       title: 'Check private intake changes',
       description:
-        'Session heartbeat for Gate 4 private intake. Returns an operational delta since your cursor (no ciphertext) plus cleanupDueCount. Call at session start, before each user turn, after long actions, and at least every two minutes while actively working. If cleanupDueCount > 0, call intake_claim with claimKind=cleanup before ordinary work.',
+        'Session heartbeat for Gate 4 private intake. Returns an operational delta since your cursor (no ciphertext) plus cleanupDueCount. Call at session start, before each user turn, after long actions, and at least every two minutes while actively working. cleanupDueCount is advisory: prefer to service it with claimKind=cleanup when you reach a natural break, but never park the work you were actually asked to do in order to drain the queue first. NOTE afterSeq is this feed\'s own sequence — the changeSeq returned by ingest is a different counter, and passing it here seeks past the end and looks like a dead feed.',
       inputSchema: {
         afterSeq: z.number().optional().describe('cursor from the previous call (default 0)'),
         limit: z.number().optional().describe('max change rows (default 100)'),
@@ -565,25 +597,66 @@ export async function runServer(version) {
     {
       title: 'Claim private intake items',
       description:
-        'Claim a lease on private intake items (relevance or cleanup). Returns decrypted payloads for the lease holder only. If cleanup is due, relevance claims return 409 — process cleanup first. Requires x-cortex-session-key (set automatically by this MCP server).',
+        'Claim a lease on private intake items (relevance or cleanup). Returns decrypted payloads for the lease holder only. Requires x-cortex-session-key (set automatically by this MCP server). Aged work never blocks a claim: the response reports cleanupDueCount and how far behind the oldest unit is, and servicing it is expected but always your call. Claiming is a commitment to process — hand back anything you will not finish with intake_release, or intake_defer if it is the owner\'s decision to make.',
       inputSchema: {
         claimKind: z.enum(['relevance', 'cleanup']).optional().describe('default relevance'),
-        limit: z.number().optional().describe('max items (default 10)'),
+        limit: z.number().optional().describe('max items (default 10). Ignored when intakeItemIds is given.'),
+        intakeItemIds: z.array(z.string()).optional().describe(
+          'claim these specific units instead of the head of the queue (max 50). Without it you get FIFO, ' +
+          'so reaching one known unit means claiming everything ahead of it. Ids come from intake_changes ' +
+          'or from an ingest response. The reply adds an `outcomes` entry per requested id — claimed, ' +
+          'held_by_you (you already hold a live lease on it — proceed, do not re-claim), ' +
+          'held (someone else has a live lease; the holder is a stable hash, never their session key), ' +
+          'ineligible (already resolved or deferred to the owner), not_found, or unavailable (a momentary ' +
+          'lock — retrying is reasonable). Outcomes are best-effort, not a snapshot you can rely on.',
+        ),
       },
     },
-    async ({ claimKind, limit }) => {
+    async ({ claimKind, limit, intakeItemIds }) => {
       const res = await fetchCortex(`${BASE}/api/intake/claim`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ claimKind: claimKind ?? 'relevance', limit, includePayload: true }),
+        body: JSON.stringify({
+          claimKind: claimKind ?? 'relevance',
+          limit,
+          includePayload: true,
+          // Forwarded only when present. An empty array is a real request to claim nothing and must
+          // survive as one; sending `[]` where the caller sent nothing would silently switch a FIFO
+          // claim into a no-op.
+          ...(intakeItemIds ? { intakeItemIds } : {}),
+        }),
       })
       if (!res.ok) {
         const body = await res.text()
         if (res.status === 403) return toolError('Private intake is not enabled for this account.')
+        // Kept deliberately after the server stopped sending it. A published MCP build outlives any
+        // one deployment, so this client will meet servers that still refuse relevance claims while
+        // cleanup is due. Surfacing that as its own message beats a generic HTTP failure.
         if (res.status === 409) return toolError(body)
         throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
       }
-      return { content: [{ type: 'text', text: JSON.stringify(await res.json(), null, 2) }] }
+
+      const j = await res.json()
+
+      // The nudge that replaced the 409. It has to be legible without doing arithmetic on a
+      // timestamp, so say how far behind rather than printing an ISO string and hoping — "6 days"
+      // is a reason to act and "2026-08-09T…" is a field to skim past.
+      let nudge = ''
+      if ((j?.cleanupDueCount ?? 0) > 0) {
+        const n = j.cleanupDueCount
+        let behind = ''
+        const oldest = j?.oldestCleanupDueAt ? Date.parse(j.oldestCleanupDueAt) : NaN
+        if (Number.isFinite(oldest)) {
+          const mins = Math.max(0, Math.floor((Date.now() - oldest) / 60000))
+          behind = mins >= 1440 ? `, oldest ${Math.floor(mins / 1440)}d overdue`
+                 : mins >= 60   ? `, oldest ${Math.floor(mins / 60)}h overdue`
+                 : `, oldest ${mins}m overdue`
+        }
+        nudge = `\n\n⏳ ${n} intake unit${n === 1 ? '' : 's'} past the cleanup deadline${behind}. `
+              + `Nothing is blocked — run intake_claim with claimKind:"cleanup" when you reach a natural break.`
+      }
+
+      return { content: [{ type: 'text', text: JSON.stringify(j, null, 2) + nudge }] }
     },
   )
 
@@ -679,15 +752,16 @@ export async function runServer(version) {
       inputSchema: {
         intakeItemId: z.string().describe('intake item uuid from intake_claim'),
         question: z.string().describe('what you need the owner to decide, in their words not yours — this is the entire message they get, so "which brain should this iMessage thread go to, if any?" beats "needs triage"'),
+        options: z.array(z.string()).optional().describe('the concrete choices, when the decision is a pick rather than an open question — e.g. ["Personal","TTO","Discard — nothing to record"]. Stored on the question and rendered by intake_cleanup_status, so the owner can answer with a choice instead of prose.'),
       },
     },
-    async ({ intakeItemId, question }) => {
+    async ({ intakeItemId, question, options }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/intake/defer`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ intakeItemId, question }),
+          body: JSON.stringify({ intakeItemId, question, ...(options?.length ? { options } : {}) }),
         })
       } catch (e) {
         return toolError(`Could not defer: ${e.message}`)
@@ -874,7 +948,11 @@ export async function runServer(version) {
             const day = (d) => (d ? String(d).slice(0, 10) : '')
             const renderMatch = (m) => {
               const blocks = m.tiers.map((t) => {
-                const secs = (t.sections ?? []).map((s) => `### ${s.heading}\n${s.body}`).join('\n\n')
+                // Was heading-then-body with NO currency at all — no as-of, no warning — while
+                // read_page showed it. project_status is what the routing docs reach for first, so a
+                // reader here could date nothing. Same renderer as read_page now, so the two cannot
+                // drift again.
+                const secs = (t.sections ?? []).map((s) => renderSection(s, day)).join('\n\n')
                 const head = `[${t.tier}${day(t.updated_at) ? ` · authored ${day(t.updated_at)}` : ''}${t.validity && t.validity !== 'current' ? ` · ${t.validity}` : ''}]`
                 return [head, t.summary, secs].filter(Boolean).join('\n')
               })
@@ -1011,13 +1089,9 @@ export async function runServer(version) {
       const renderMatch = (m, tagBrain) => {
         const blocks = m.tiers.map((t) => {
           const secs = (t.sections ?? []).map((s) => {
-            // Undefined is an older-server response during a rolling deploy: do
-            // not invent a currency verdict until this server has computed one.
-            const currency = s.hasExplicitDate === false
-              ? '\n⚠ **Undated section — verify before relying on its claims.**\n'
-              : ''
-            const asOf = s.asOf ? ` · as of ${day(s.asOf)}` : ''
-            return `### ${s.heading}${asOf}${currency}${s.body}`
+            // Shared with project_status via renderSection — see its definition for why this is one
+            // function and not two (they drifted; #558 fixed one of three surfaces).
+            return renderSection(s, day)
           }).join('\n\n')
           // ADR-0018: a null version isn't "nothing to show" — it means this variant predates content-
           // hash tracking (a 2026-06-29 import scar) and CANNOT be re-authored via base_version until an

package/package.json

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