@theronap/cortex-mcp 0.9.162 → 0.9.164

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

@@ -114,7 +114,25 @@ export function mergeClaudeSettings(existing, spec) {
   // ⚠ Matcher is '' (every tool). The block only appears on three surfaces, so the filtering is
   // server-side and this stays a cheap no-op elsewhere: it reads its stdin, finds no marker, exits 0.
   s.hooks.PostToolUse = Array.isArray(s.hooks.PostToolUse) ? s.hooks.PostToolUse : []
-  const arrivalsCmd = markCommand(`npx -y ${spec} arrivals-notice`)
+  // 🔴 THIS HOOK DOES NOT FOLLOW `spec`, AND THE REASON IS A DEFECT THIS FILE SHIPPED ONCE.
+  //
+  // `spec` pins @stable, which is what desktop-wired seats deliberately follow. But a hook wired at
+  // a version that does not HAVE its subcommand does not fail quietly: an older client given an
+  // unknown subcommand falls through to the MCP-server default and prints
+  // `cortex-mcp: CORTEX_TOKEN is required`. Wired under `spec` on 2026-09-21, when @stable was
+  // 0.9.156 and this subcommand landed in 0.9.162, that meant an ERROR after EVERY TOOL CALL —
+  // noise rather than silence, which is worse than the feature simply being absent.
+  //
+  // So the rule, stated because it generalises to the next hook somebody adds: A HOOK MUST NEVER BE
+  // WIRED AT A SPEC THAT CANNOT EXECUTE IT. A version floor is the narrowest way to hold that, and
+  // npx resolves a semver range (verified 2026-09-21 against a real invocation, not assumed).
+  //
+  // ⚠ And it uses the CANONICAL name. Every other command here carries `cortex-mcp` for
+  // compatibility with frozen launchd/cron scripts on unreachable machines (ADR-0033) — but a
+  // BRAND-NEW hook has no frozen scripts to be compatible with, so there is no reason to mint more
+  // references to the retiring name. New wiring uses the name the product actually has.
+  const ARRIVALS_MIN_VERSION = '0.9.162'
+  const arrivalsCmd = markCommand(`npx -y @theronap/agnoclast-mcp@^${ARRIVALS_MIN_VERSION} arrivals-notice`)
   for (const pg of s.hooks.PostToolUse) {
     if (Array.isArray(pg.hooks)) pg.hooks = pg.hooks.filter((h) => !isManagedSubcommand(h.command, 'arrivals-notice'))
   }
@@ -144,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/package.json

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