@theronap/agnoclast-mcp 0.9.163 → 0.9.165

package/bin/cortex-mcp.mjs

@@ -85,7 +85,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  docs-scan       detect new/changed local docs pending Agnoclast authoring (used by /cortex-author-docs)\n` +
     `  graphify-sync [path] [--brain <name-or-id>]  rebuild the local code graph + log a timeline event\n` +
     `  snapshot-context save the exact startup context Agnoclast served to a local snapshot\n` +
-  `  arrivals-notice  PostToolUse hook: print incoming-record offers so the PERSON sees them too\n` +
+  `  arrivals-notice  hook pair: detect incoming-record offers (PostToolUse) and surface them (--emit, UserPromptSubmit)\n` +
     `  hydrate         UserPromptSubmit hook — inject query-centered context on the first substantive turn\n` +
     `  migrate-key [--dry-run]  move the MCP config key to its new name, allow rules first\n` +
     `  with-token -- <cmd>    run <cmd> with your token in its environment (for cron/launchd wrappers)\n` +
@@ -198,8 +198,12 @@ if (cmd === 'login') {
   // RESULTS, which only the agent reads — and an audit on 2026-09-21 found the agent acting on it
   // once in a day. Pure text extraction from the payload it is handed: no network, no token, always
   // exit 0. It reports; it never blocks a tool call.
-  const { runArrivalsNotice } = await import('../lib/arrivals_notice.mjs')
-  process.exitCode = await runArrivalsNotice()
+  // Two halves, one subcommand. `--emit` is the UserPromptSubmit side (drain + print); without it
+  // this is the PostToolUse side (detect + spool, prints nothing). Neither can do the job alone:
+  // PostToolUse sees tool output but its stdout is not injected; UserPromptSubmit is injected but
+  // never sees tool output. See lib/arrivals_notice.mjs's header.
+  const mod = await import('../lib/arrivals_notice.mjs')
+  process.exitCode = rest.includes('--emit') ? await mod.runArrivalsDrain() : await mod.runArrivalsNotice()
 } else if (cmd === 'hydrate') {
   // UserPromptSubmit hook (① discovery): hydrate the model with query-centered Agnoclast context on the
   // FIRST substantive turn, before it answers — then never again this session (topic-shift refresh stays

package/lib/arrivals_notice.mjs

@@ -13,14 +13,29 @@
 // coverage. So this does not ask the agent to be more diligent; it removes the agent from the
 // delivery path.
 //
-// ⚠ IT IS NOT A GATE. Hook stdout is surfaced and exit is always 0: this reports, it never blocks a
-// tool call, and it never fails one. A notifier that can break the thing it observes gets disabled,
-// and then it observes nothing.
+// ⚠ IT IS NOT A GATE. Exit is always 0: this reports, it never blocks a tool call, and it never
+// fails one. A notifier that can break the thing it observes gets disabled, and then it observes
+// nothing.
+//
+// 🔴 TWO EVENTS, BECAUSE NEITHER ONE CAN DO THIS ALONE. Measured 2026-09-21, after shipping a
+// version that could not work:
+//
+//   PostToolUse       has the arrivals block   — but its stdout is NOT injected into the conversation
+//   UserPromptSubmit  IS injected (proven)     — but never receives tool output at all
+//
+// The first version wired only PostToolUse and printed to stdout. It ran perfectly: correct parse,
+// correct ids, state file written seconds after the block appeared. And NOBODY SAW ANY OF IT —
+// which is precisely the failure this file exists to fix, reproduced by the fix. The assumption came
+// from seeing SessionStart and UserPromptSubmit output every turn and generalising to all hooks;
+// those two are context-INJECTING events by design.
+//
+// So: PostToolUse DETECTS and spools. UserPromptSubmit DRAINS and surfaces. Arrivals appear at the
+// top of the person's next turn, which is when they are actually looking at the screen.
 //
 // ⚠ NO NETWORK, NO TOKEN, NO DECRYPT. Everything printed is already in the payload the hook was
 // handed. That keeps it fast enough to run after every tool call and means it cannot leak anything
 // the agent was not already shown.
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
@@ -108,6 +123,20 @@ export function formatNotice(arrivals) {
   return lines.join('\n')
 }
 
+/** The handoff between the two hook events. One file per session, drained on the next prompt. */
+function spoolPath(sessionKey) {
+  const dir = join(homedir(), '.cortex', 'arrivals-spool')
+  try { mkdirSync(dir, { recursive: true }) } catch { /* best effort */ }
+  return join(dir, `${(sessionKey || 'nosession').replace(/[^a-zA-Z0-9_-]/g, '_')}.json`)
+}
+
+/**
+ * PostToolUse: detect, de-duplicate, SPOOL. Prints nothing — its stdout goes nowhere a person reads.
+ *
+ * ⚠ The spool ACCUMULATES across tool calls rather than overwriting. Several tool calls commonly
+ * land between two prompts, and only the first carries a given arrival; overwriting would mean the
+ * last tool call before the prompt decides what the person sees, which is usually nothing.
+ */
 export async function runArrivalsNotice() {
   try {
     const raw = readStdin()
@@ -127,7 +156,21 @@ export async function runArrivalsNotice() {
     // change, so it is reported whenever present.
     if (fresh.length === 0 && !arrivals.delta) return 0
 
-    process.stdout.write(formatNotice({ delta: arrivals.delta, items: fresh }) + '\n')
+    // Merge into whatever is already spooled for this session.
+    const sp = spoolPath(sessionKey)
+    let pending = { delta: 0, items: [] }
+    try { pending = JSON.parse(readFileSync(sp, 'utf8')) } catch { /* first one this turn */ }
+    const byId = new Map((pending.items ?? []).map((it) => [it.id, it]))
+    for (const it of fresh) byId.set(it.id, it)
+    try {
+      writeFileSync(sp, JSON.stringify({
+        // The server watermarks the delta, so the freshest sighting is the right one — not a sum,
+        // which would double-count the same pile across two tool calls in one turn.
+        delta: arrivals.delta || pending.delta || 0,
+        items: [...byId.values()].slice(-40),
+      }))
+    } catch { /* best effort */ }
+
     for (const it of fresh) seen.add(it.id)
     saveSeen(p, seen)
     return 0
@@ -136,3 +179,30 @@ export async function runArrivalsNotice() {
     return 0
   }
 }
+
+/**
+ * UserPromptSubmit: DRAIN the spool and print. This is the half the person actually sees.
+ *
+ * ⚠ CLEAR THE SPOOL BEFORE PRINTING FAILS, not after. A crash between print and clear would repeat
+ * the same arrivals on every subsequent prompt forever, and a notifier that nags is one that gets
+ * removed. Losing one notice is recoverable — the record is still unclaimed and will be offered
+ * again by the server.
+ */
+export async function runArrivalsDrain() {
+  try {
+    const raw = readStdin()
+    let sessionKey = ''
+    try { sessionKey = String(JSON.parse(raw)?.session_id ?? '') } catch { /* fine */ }
+
+    const sp = spoolPath(sessionKey)
+    let pending = null
+    try { pending = JSON.parse(readFileSync(sp, 'utf8')) } catch { return 0 }
+    try { unlinkSync(sp) } catch { /* best effort */ }
+
+    if (!pending || (!pending.delta && !(pending.items ?? []).length)) return 0
+    process.stdout.write(formatNotice({ delta: pending.delta ?? 0, items: pending.items ?? [] }) + '\n')
+    return 0
+  } catch {
+    return 0
+  }
+}

package/lib/editors/claude.mjs

@@ -162,6 +162,24 @@ export function mergeClaudeSettings(existing, spec) {
   hgrp.hooks = hgrp.hooks ?? []
   hgrp.hooks.push({ type: 'command', command: hydrateCmd })
 
+  // UserPromptSubmit — arrivals-notice --emit, THE HALF THE PERSON ACTUALLY SEES.
+  //
+  // 🔴 THE POSTTOOLUSE HOOK ALONE COULD NOT WORK, and it shipped that way in 0.9.162/0.9.163.
+  // Measured 2026-09-21: it ran correctly — right parse, right ids, state file written seconds after
+  // the block appeared — and its output reached nobody, because PostToolUse stdout is NOT injected
+  // into the conversation. The assumption came from seeing SessionStart and UserPromptSubmit output
+  // every turn; those are context-INJECTING events by design and PostToolUse is not one.
+  //
+  // ⚠ So do not "move" it here — UserPromptSubmit never receives tool output, which is where the
+  // arrivals block lives. The two events hold complementary halves: PostToolUse DETECTS and spools
+  // to ~/.cortex/arrivals-spool, this one DRAINS and prints. Removing either leaves a hook that runs
+  // and reports nothing, which is the exact failure the feature exists to fix.
+  const arrivalsEmitCmd = markCommand(`npx -y @theronap/agnoclast-mcp@^${ARRIVALS_MIN_VERSION} arrivals-notice --emit`)
+  for (const ug of s.hooks.UserPromptSubmit ?? []) {
+    if (Array.isArray(ug.hooks)) ug.hooks = ug.hooks.filter((h) => !isManagedSubcommand(h.command, 'arrivals-notice'))
+  }
+  hgrp.hooks.push({ type: 'command', command: arrivalsEmitCmd })
+
   // PreCompact — REMOVED, and this block is the migration that unwires existing seats.
   //
   // The "author now" reminder wrote to stdout on the assumption the harness surfaced it as context for

package/lib/server.mjs

@@ -285,6 +285,43 @@ 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` +
+    `— Then \`intake_claim\` and \`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 ''
@@ -1389,7 +1426,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 +1735,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 +3486,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.163",
+  "version": "0.9.165",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {