@theronap/agnoclast-mcp 0.9.164 → 0.9.166

package/lib/server.mjs

@@ -285,6 +285,48 @@ function renderArrival(payload) {
     ` — \`staged_records\` lists them. Not offered to you, just counted; \`ignore_arrivals\` if this is noise right now.`
 }
 
+function renderSettling(payload) {
+  const feed = payload?.settling
+  const offers = Array.isArray(feed?.offers) ? feed.offers : []
+  if (!offers.length) return ''
+  const total = Number(feed?.total ?? offers.length)
+
+  const lines = offers.map((x) => {
+    const why = x.via?.length ? ` — matches ${x.via.map((v) => `\`${v}\``).join(', ')}` : ''
+    // Looks without claims is evidence about the UNIT, not about the sessions that walked away.
+    const looked = x.looks > 0 ? `  [looked at ${x.looks}x, still unclaimed]` : ''
+    return `    - ${x.source} · ${x.hoursAgo}h ago · ${x.intakeItemId}${why}${looked}`
+  })
+
+  // ⚠ SAY THE TRUE TOTAL, NOT THE PAGE SIZE. Measured 2026-09-22: one identifier matched 113 settling
+  // units against a cap of 12. A block that says "here are 12" when there are 113 is claiming
+  // certainty it does not have — and renders identically every turn, which teaches the reader that
+  // it never changes and can be skipped.
+  const more = total > offers.length
+    ? `\n— Showing ${offers.length} of ${total}. \`intake_changes\` lists the rest; this is a sample, not the queue.`
+    : ''
+
+  // ⚠ CONTENTION IS STATED, exactly as the record nudge states `k`. Measured the same day: THREE live
+  // sessions each matched the SAME 113 units on one identifier. Silent about that, each would claim
+  // the same units and learn about the race from a failed lease.
+  const maxHolders = offers.reduce((m, x) => Math.max(m, Number(x.holders ?? 1)), 1)
+  const who = maxHolders > 1
+    ? `\n— ⚠ ${maxHolders} live sessions of yours hold a matching identifier, so these are offered to all of them. \`intake_claim\` takes a lease — claim before you work, not after, or two sessions judge the same arrival.`
+    : `\n— No other live session of yours holds a matching identifier, so nobody else is looking at these.`
+
+  return `\n\n⚡ ARRIVALS SETTLING — yours alone, and no one else can see these yet:\n${lines.join('\n')}\n` +
+    `— These are unjudged ARRIVALS, not records. Since automatic materialization was deleted, nothing files them for you.\n` +
+    `— \`intake_look <id>\` reads the full body without claiming it — looking is free, non-exclusive and logged, so look rather than guess from the headline.\n` +
+    // ⚠ NAME THE EXACT CALL, INCLUDING THE ARRAY. This line used to read "Then `intake_claim` and
+    // `intake_materialize`" straight after a list of ids, which reads as `intake_claim <id>`. It is not:
+    // the parameter is `intakeItemIds`, an ARRAY, and on 2026-09-22 following this very sentence took a
+    // lease on ten unrelated units. The singular is accepted now, but an offer must still state the call
+    // that acts on the thing being offered — a reader should not have to consult a schema to use a nudge.
+    `— Then \`intake_claim {intakeItemIds: ["<id>"]}\` to take a lease on THAT unit (the array is required; without an id you claim the head of the queue instead), then \`intake_materialize\` into the brain and pages it belongs to — or \`intake_discard\`, or \`intake_defer\` with a question when only the owner can decide.` +
+    more + who +
+    `\n— If none are yours, leave them: they stay settling for your other sessions, and become everyone's business once the window closes.`
+}
+
 function renderNudge(payload) {
   const n = Array.isArray(payload?.nudge) ? payload.nudge : []
   if (!n.length) return ''
@@ -945,6 +987,17 @@ function renderNudge(payload) {
         claimKind: z.enum(['relevance', 'cleanup']).optional().describe('default relevance'),
         limit: z.number().optional().describe('max items (default 10). Ignored when intakeItemIds is given.'),
         leaseMinutes: z.number().optional().describe('lease length in minutes, 5-60 (default 30). Prefer intake_look for read-only inspection — a short lease is only for briefly exclusive work.'),
+        // 🔴 SINGULAR ACCEPTED, AND NOT AS A CONVENIENCE. Every sibling verb takes `intakeItemId`:
+        // intake_look, intake_materialize, intake_release, intake_defer, intake_discard. This one
+        // alone was plural, so the natural singular was NOT IN THE SCHEMA and was silently dropped
+        // — and the fallback is not an error, it is claiming the head of the queue. On 2026-09-22 a
+        // session offered one unit by the settling block called `intake_claim {intakeItemId}` and
+        // took a 30-minute lease on TEN unrelated units belonging to other sessions' work. A typo
+        // that becomes a side effect is worse than a typo that fails.
+        intakeItemId: z.string().optional().describe(
+          'a single unit to claim — the same thing as intakeItemIds with one element. Accepted because ' +
+          'every other intake verb spells it this way.',
+        ),
         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 ' +
@@ -956,7 +1009,11 @@ function renderNudge(payload) {
         ),
       },
     },
-    async ({ claimKind, limit, intakeItemIds, leaseMinutes }) => {
+    async ({ claimKind, limit, intakeItemId, intakeItemIds, leaseMinutes }) => {
+      // Merge the two spellings before anything else looks at them. Passing both is not an error —
+      // the union is what the caller plainly meant.
+      const ids = [...new Set([...(intakeItemIds ?? []), ...(intakeItemId ? [intakeItemId] : [])])]
+      intakeItemIds = ids.length ? ids : undefined
       const res = await fetchCortex(`${BASE}/api/intake/claim`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
@@ -1389,7 +1446,7 @@ function renderNudge(payload) {
         throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
       }
       const payload = await res.json()
-      return { content: [{ type: 'text', text: formatGrepHits(payload, query) + renderArrival(payload) + renderNudge(payload) }] }
+      return { content: [{ type: 'text', text: formatGrepHits(payload, query) + renderArrival(payload) + renderNudge(payload) + renderSettling(payload) }] }
     },
   )
 
@@ -1698,7 +1755,7 @@ function renderNudge(payload) {
       // `k` is stated rather than hidden. "Only you" and "you and two others" call for different
       // behaviour, and a nudge that claimed certainty it did not have is how an agent learns to stop
       // reading them.
-      const nudgeBlock = renderArrival(page) + renderNudge(page)
+      const nudgeBlock = renderArrival(page) + renderNudge(page) + renderSettling(page)
 
       if (matches.length === 1) {
         return { content: [{ type: 'text', text: renderMatch(matches[0], false) + nudgeBlock }] }
@@ -3449,7 +3506,7 @@ function renderNudge(payload) {
         return toolError(`Could not list records: ${d.message}`)
       }
       const payload = await res.json()
-      return { content: [{ type: 'text', text: (payload?.text ?? '') + renderArrival(payload) + renderNudge(payload) }] }
+      return { content: [{ type: 'text', text: (payload?.text ?? '') + renderArrival(payload) + renderNudge(payload) + renderSettling(payload) }] }
     },
   )
 

package/package.json

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