@theronap/cortex-mcp 0.9.159 → 0.9.161

package/bin/cortex-mcp.mjs

@@ -52,7 +52,7 @@ const rest = process.argv.slice(3)
 //
 // ⚠ NOT guarded: `capture` (has its own, with a diagnostic), and anything a human might run by hand
 // while this var happens to be set. Only the ambient context commands are listed.
-const CONTEXT_HOOK_COMMANDS = new Set(['snapshot-context', 'status', 'hydrate', 'skills'])
+const CONTEXT_HOOK_COMMANDS = new Set(['snapshot-context', 'status', 'hydrate', 'skills', 'arrivals-notice'])
 if (process.env.CORTEX_SUMMARIZING && CONTEXT_HOOK_COMMANDS.has(cmd)) {
   process.stderr.write(`cortex: ${cmd} skipped — summarizer subprocess (CORTEX_SUMMARIZING)\n`)
   process.exit(0)
@@ -85,6 +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` +
     `  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` +
@@ -192,6 +193,13 @@ if (cmd === 'login') {
   process.exitCode = await runSnapshotContext()
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'arrivals-notice') {
+  // PostToolUse hook: surface the arrivals offer to the PERSON. The ⚡ block is appended to TOOL
+  // 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()
 } 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

@@ -0,0 +1,138 @@
+// PostToolUse hook — make the arrivals offer visible to the PERSON, not just the agent.
+//
+// 🔴 WHY THIS EXISTS, and it is not a nicety. The `⚡ ARRIVED WHILE YOU WERE WORKING` block and the
+// per-turn delta line are appended to TOOL RESULTS, which only the agent reads. Measured on
+// 2026-09-21 against a single session's own record: the block fired repeatedly through the day and
+// the agent acted on it ONCE, and only because the user asked it to prove the mechanism existed. An
+// audit of the four records it named found one that plainly belonged to that session's own work and
+// had simply been let pass.
+//
+// The failure is structural rather than a lapse: the offer arrives MID-TASK, inside a result the
+// agent requested for an unrelated reason, and nothing forces a decision. A signal that only the
+// agent can see, and that the agent reliably scrolls past, is worse than no signal — it LOOKS like
+// 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.
+//
+// ⚠ 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 { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const MATCHED = '⚡ ARRIVED WHILE YOU WERE WORKING'
+const DELTA_RE = /⚡ (\d+) new arrivals? in your pile/
+// The listing lines look like:  - Title  (email · 5.1h ago · id <uuid>) — …
+const ITEM_RE = /^\s*-\s+(.*?)\s+\((\S+)\s+·\s+([^·]+?)\s+·\s+id\s+([0-9a-f-]{36})\)/gmu
+
+function readStdin() {
+  try { return readFileSync(0, 'utf8') } catch { return '' }
+}
+
+/** Every string in the payload, so this does not depend on which key holds the tool's text. */
+function* strings(v, depth = 0) {
+  if (depth > 8 || v == null) return
+  if (typeof v === 'string') { yield v; return }
+  if (Array.isArray(v)) { for (const x of v) yield* strings(x, depth + 1); return }
+  if (typeof v === 'object') { for (const x of Object.values(v)) yield* strings(x, depth + 1) }
+}
+
+/**
+ * Pull the arrivals offer out of a PostToolUse payload.
+ *
+ * Exported for tests: the parsing is the part that can silently rot when the server changes the
+ * block's wording, and a hook that stops matching fails SILENTLY — it just prints nothing forever,
+ * which is indistinguishable from "nothing arrived".
+ */
+export function extractArrivals(payloadText) {
+  let blob = payloadText
+  try {
+    const parsed = JSON.parse(payloadText)
+    blob = [...strings(parsed)].join('\n')
+  } catch {
+    // Not JSON — scan the raw text. Fail open toward reporting rather than staying silent.
+  }
+  if (!blob) return null
+
+  const deltaMatch = blob.match(DELTA_RE)
+  const delta = deltaMatch ? Number(deltaMatch[1]) : 0
+
+  const items = []
+  if (blob.includes(MATCHED)) {
+    // Only the section AFTER the marker, so an unrelated bulleted list earlier in a page read is
+    // not mistaken for arrivals.
+    const section = blob.slice(blob.indexOf(MATCHED))
+    for (const m of section.matchAll(ITEM_RE)) {
+      items.push({ title: m[1].trim(), source: m[2], age: m[3].trim(), id: m[4] })
+    }
+  }
+  if (!delta && items.length === 0) return null
+  return { delta, items }
+}
+
+/** Ids already announced, so the same arrival is not re-reported on every tool call until claimed. */
+function seenPath(sessionKey) {
+  const dir = join(homedir(), '.cortex', 'arrivals-announced')
+  try { mkdirSync(dir, { recursive: true }) } catch { /* best effort */ }
+  return join(dir, `${(sessionKey || 'nosession').replace(/[^a-zA-Z0-9_-]/g, '_')}.json`)
+}
+
+function loadSeen(p) {
+  try { return new Set(JSON.parse(readFileSync(p, 'utf8'))) } catch { return new Set() }
+}
+
+function saveSeen(p, set) {
+  // Bounded: a long session must not grow this file without limit.
+  try { writeFileSync(p, JSON.stringify([...set].slice(-500))) } catch { /* best effort */ }
+}
+
+export function formatNotice(arrivals) {
+  const lines = []
+  if (arrivals.items.length) {
+    lines.push(`⚡ ${arrivals.items.length} record${arrivals.items.length === 1 ? '' : 's'} offered to this session:`)
+    for (const it of arrivals.items.slice(0, 6)) {
+      lines.push(`   · ${it.title.slice(0, 92)}  (${it.source} · ${it.age})`)
+      lines.push(`     ${it.id}`)
+    }
+    if (arrivals.items.length > 6) lines.push(`   … and ${arrivals.items.length - 6} more`)
+  }
+  if (arrivals.delta) {
+    lines.push(`⚡ ${arrivals.delta} new arrival${arrivals.delta === 1 ? '' : 's'} in the pile since this session was last told.`)
+  }
+  // Said plainly, because the whole point is that the person can tell whether anything happened.
+  if (arrivals.items.length) lines.push(`   (Claim + route them, or say they are not yours — they stay unclaimed until someone decides.)`)
+  return lines.join('\n')
+}
+
+export async function runArrivalsNotice() {
+  try {
+    const raw = readStdin()
+    if (!raw) return 0
+
+    let sessionKey = ''
+    try { sessionKey = String(JSON.parse(raw)?.session_id ?? '') } catch { /* fine */ }
+
+    const arrivals = extractArrivals(raw)
+    if (!arrivals) return 0
+
+    const p = seenPath(sessionKey)
+    const seen = loadSeen(p)
+    const fresh = arrivals.items.filter((it) => !seen.has(it.id))
+
+    // Nothing new to say. The delta line is server-side watermarked and already fires once per
+    // 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')
+    for (const it of fresh) seen.add(it.id)
+    saveSeen(p, seen)
+    return 0
+  } catch {
+    // ⚠ ALWAYS 0. This observes; it must never be the reason a tool call failed.
+    return 0
+  }
+}

package/lib/editors/claude.mjs

@@ -98,6 +98,31 @@ export function mergeClaudeSettings(existing, spec) {
   }
   sgrp.hooks.push({ type: 'command', command: snapshotCmd })
 
+  // PostToolUse — arrivals-notice.
+  //
+  // 🔴 THE ARRIVALS OFFER WAS INVISIBLE TO THE PERSON. `⚡ ARRIVED WHILE YOU WERE WORKING` and the
+  // per-turn delta are appended to TOOL RESULTS, which only the agent reads. Measured 2026-09-21
+  // against one session's own record: the block fired repeatedly through the day, the agent acted on
+  // it once, and an audit of the records it named found one belonging to that session's own work
+  // that had simply been let pass. A signal only the agent sees, and reliably scrolls past, LOOKS
+  // like coverage while providing none.
+  //
+  // ⚠ SO THIS IS WIRED AS SOFTWARE, NOT LEFT TO INSTRUCTION. Asking the agent to relay arrivals is
+  // asking it to be reliable at exactly the thing it was just measured failing at; a hook takes the
+  // agent out of the delivery path entirely.
+  //
+  // ⚠ 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`)
+  for (const pg of s.hooks.PostToolUse) {
+    if (Array.isArray(pg.hooks)) pg.hooks = pg.hooks.filter((h) => !isManagedSubcommand(h.command, 'arrivals-notice'))
+  }
+  let pgrp = s.hooks.PostToolUse.find((g) => (g.matcher ?? '') === '')
+  if (!pgrp) { pgrp = { matcher: '', hooks: [] }; s.hooks.PostToolUse.push(pgrp) }
+  pgrp.hooks = pgrp.hooks ?? []
+  pgrp.hooks.push({ type: 'command', command: arrivalsCmd })
+
   // UserPromptSubmit — hydrate (① discovery). Makes the FIRST context load of a session
   // non-discretionary: without it, hydration is a skill the agent may simply forget, and an agent
   // that never reads the wiki never triggers a currency update — it re-derives design that is

package/lib/server.mjs

@@ -2151,6 +2151,51 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'staged_look',
+    {
+      title: 'Read a staged arrival before deciding where it goes',
+      description: 'Read ONE staged arrival\'s envelope — sender, subject, recipients, thread, the generated summary, and the identifiers holding it — without claiming or changing anything. Use it before `place_staged_record` whenever the subject alone does not tell you WHAT KIND of thing this is. ⚠ THE SUBJECT LIES MORE OFTEN THAN YOU WOULD THINK: `staged_records` lists subjects only, and a message reading `Re: [owner/repo] fix(triage)…` is as likely to be a bot\'s deployment-status comment as a human discussing the PR — measured 2026-09-21, `vercel[bot]` accounts for 26 of the pending arrivals whose subject names that repo. The `from` header settles it in one look. ⚠ THIS IS THE ENVELOPE, NOT THE LETTER. A staged arrival stores headers and a generated summary; the message BODY is not persisted, so `bodyStored` is always false. Do not describe an arrival as something you READ — you saw who sent it and what it was titled. Looking is free, changes nothing, and needs no release.',
+      inputSchema: {
+        stagedId: z.string().describe('staged arrival id, from `staged_records` or the session-start arrivals block'),
+      },
+    },
+    async ({ stagedId }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/staged/look?stagedId=${encodeURIComponent(stagedId)}`, {
+          headers: { Authorization: `Bearer ${TOKEN}` },
+        })
+      } catch (e) {
+        return toolError(`Could not read that staged arrival: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (res.status === 404) {
+        return toolError(`No staged arrival ${stagedId} of yours. Staged rows are per-person and in no brain, so this means it is not yours or does not exist — the two are deliberately indistinguishable.`)
+      }
+      if (!res.ok) return toolError(`Could not read staged arrival ${stagedId}: ${out?.error ?? res.status}`)
+
+      const l = out?.look ?? {}
+      const line = (label, v) => (v ? `  ${label.padEnd(9)} ${v}\n` : '')
+      const held = Array.isArray(l.blockingIdentifiers) && l.blockingIdentifiers.length
+        ? `\n⚠ HELD ON UNCLAIMED IDENTIFIERS — no page claims these, so it cannot finish until they are dispositioned:\n${l.blockingIdentifiers.map((i) => `  · ${i}`).join('\n')}\n`
+        : ''
+      return {
+        content: [{
+          type: 'text',
+          text:
+            `${l.title ?? '(untitled)'}\n` +
+            `  ${l.sourceType} · arrived ${l.receivedAt ?? '?'} · occurred ${l.occurredAt ?? '?'}\n\n` +
+            line('from', l.from) + line('subject', l.subject) + line('to', l.to) +
+            line('account', l.account) + line('thread', l.threadId) +
+            (l.summary ? `\n  summary  ${l.summary}\n` : '') +
+            held +
+            `\n⚠ This is the ENVELOPE. The message body was never stored (bodyStored: ${l.bodyStored === true}), so you have seen who sent it and what it was called — not what it says. Judge accordingly, and do not report having read it.`,
+        }],
+      }
+    },
+  )
+
   server.registerTool(
     'discard_staged',
     {

package/package.json

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