@theronap/agnoclast-mcp 0.9.171 → 0.9.173

package/lib/diagnose.mjs

@@ -12,6 +12,8 @@
 import { readFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { spoolReport, flush as flushReportSpool, readEntries as readReportSpool, spoolDir as reportSpoolDir } from './report_spool.mjs'
 
 export const isUuid = (s) =>
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s ?? '')
@@ -281,9 +283,12 @@ export function setSessionKey(key) { SESSION_KEY = key || null }
 // blind. A one-shot hook process legitimately has no session and IS still cortex-mcp — it should
 // say so, and be visible as one, not disguise itself as a script.
 let CLIENT_ID = 'cortex-mcp/unknown'
+let CLIENT_VERSION = null
 export function setClientVersion(version) {
   CLIENT_ID = `cortex-mcp/${version || 'unknown'}`
+  CLIENT_VERSION = version || null
 }
+export const clientVersion = () => CLIENT_VERSION
 
 // ── Retries (D9, eng review 2026-09-11) ──────────────────────────────────────────────────────────
 //
@@ -402,7 +407,7 @@ export function mayRetry(klass, { idempotent, retryOnTimeout = true, requireRetr
  *   baseDelayMs, maxDelayMs   full-jitter backoff parameters
  *   sleep, random, now        injectable for tests
  */
-export async function fetchCortex(url, opts = {}, policy = {}) {
+async function fetchCortexOnce(url, opts = {}, policy = {}) {
   const {
     retries = 2, baseDelayMs = 400, maxDelayMs = 8_000,
     retryOnTimeout = true, requireRetryAfter = false,
@@ -474,6 +479,147 @@ export async function fetchCortex(url, opts = {}, policy = {}) {
   }
 }
 
+// ── ADR-0070 §1/§5: outage auto-file ─────────────────────────────────────────────────────────────
+//
+// An agent files only what the SERVER CANNOT SEE: failures that never reached the app. Everything the
+// app answered in JSON, the server already knows about (Sentry, §7), and a 429 is our own limiter
+// telling this seat to slow down — filing about it would be the seat arguing with the limiter.
+//
+//   connect / DNS / timeout             → outage   (failure_class 'connect')
+//   non-JSON 4xx/5xx (not 401, not 429)  → outage   (failure_class 'infra' — firewall / protection)
+//   503                                 → outage   (failure_class 'refused', or 'infra' when non-JSON)
+//   429, JSON app errors, 401           → never
+//
+// ⚠ STRUCTURED FIELDS ONLY. classify()'s message carries brain names and sample page titles, so it is
+// never read here. The one body field taken is the machine `error` code of a JSON 503, and only when it
+// is a bare snake_case token.
+//
+// The report POST itself passes `policy.skipAutofile`, so a failed report never files a report about
+// itself; the spool flush POSTs the same way.
+
+const toolContext = new AsyncLocalStorage()
+/** Run `fn` with `tool` as the name any outage filed during it is attributed to (server.mjs wraps every tool). */
+export const runWithTool = (tool, fn) => toolContext.run(tool, fn)
+
+// For callers outside a tool call (hooks, doctor). Unknown paths are 'other' — the server coerces too.
+const PATH_TOOLS = {
+  'mcp-context': 'my_context', 'session-context': 'session_context', 'grep': 'grep', 'search': 'search_org',
+  'brain/page': 'read_page', 'brain/author': 'author', 'brain/edit-page': 'edit_page', 'records/capture': 'capture_record',
+  'intake/claim': 'intake_claim', 'intake/materialize': 'intake_materialize', 'staged': 'staged_records', 'brains': 'my_brains',
+}
+
+/** PURE. The tool an outage on `url` belongs to: the running tool if known, else a path mapping, else 'other'. */
+export function toolForUrl(url, running = toolContext.getStore()) {
+  if (running) return running
+  let path = ''
+  try { path = new URL(url).pathname } catch { return 'other' }
+  const m = path.match(/\/api\/(.+?)\/?$/)
+  return (m && PATH_TOOLS[m[1]]) || 'other'
+}
+
+const ERROR_CODE_RE = /^[a-z_]{1,40}$/
+
+/**
+ * PURE. Should this outcome be auto-filed, and with which fields? `outcome` is either
+ * { status, contentType, errorCode } for a response, or { thrownClass } for a thrown failure.
+ * Returns the structured report, or null.
+ */
+export function outageReport(outcome, { tool, requestId = null, version = CLIENT_VERSION } = {}) {
+  const base = { kind: 'outage', tool: tool ?? 'other', request_id: requestId ?? null, client_version: version ?? null }
+  if (outcome.thrownClass) {
+    if (outcome.thrownClass === 'connect') return { ...base, status: null, error_code: null, failure_class: 'connect' }
+    if (outcome.thrownClass === 'timeout') return { ...base, status: null, error_code: 'timeout', failure_class: 'connect' }
+    return null
+  }
+  const { status, contentType } = outcome
+  if (!(status >= 400) || status === 429 || status === 401) return null
+  const isJson = String(contentType ?? '').includes('application/json')
+  if (!isJson) return { ...base, status, error_code: null, failure_class: 'infra' }
+  if (status === 503) {
+    const code = typeof outcome.errorCode === 'string' && ERROR_CODE_RE.test(outcome.errorCode) ? outcome.errorCode : null
+    return { ...base, status, error_code: code, failure_class: 'refused' }
+  }
+  return null
+}
+
+/** Auto-filing is off under `bun test` unless the test points the spool somewhere (never the real home). */
+function autofileEnabled(env = process.env) {
+  if (env.CORTEX_AUTOFILE === '0') return false
+  return env.NODE_ENV !== 'test' || Boolean(env.CORTEX_REPORT_SPOOL_DIR)
+}
+
+const authOf = (opts) => {
+  const h = opts?.headers ?? {}
+  return h.Authorization ?? h.authorization ?? null
+}
+
+/** The API base a URL was sent to — everything before `/api/`. */
+const baseOf = (url) => { const i = String(url).indexOf('/api/'); return i > 0 ? String(url).slice(0, i) : null }
+
+export const BUG_REPORTS_PATH = '/api/ops/bug-reports'
+
+/** POST one report body. Never auto-files, never retries a non-idempotent write it cannot see land. */
+export function postBugReport(base, authorization, body) {
+  return fetchCortex(`${base}${BUG_REPORTS_PATH}`, {
+    method: 'POST',
+    headers: { Authorization: authorization, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  }, { skipAutofile: true, retries: 0 })
+}
+
+let flushing = null
+/** Non-blocking flush of the report spool after a 2xx. At most one at a time per process. */
+function triggerFlush(url, authorization) {
+  if (flushing) return flushing
+  const base = baseOf(url)
+  if (!base) return null
+  try { if (!readReportSpool(reportSpoolDir()).length) return null } catch { return null }
+  flushing = flushReportSpool(async (body) => {
+    const r = await postBugReport(base, authorization, body)
+    try { await r.body?.cancel() } catch { /* already consumed */ }
+    return r
+  })
+    .catch(() => null)
+    .finally(() => { flushing = null })
+  return flushing
+}
+/** Tests: await the in-flight flush, if any. */
+export const pendingFlush = () => flushing
+
+/**
+ * fetch with the D9 retry policy (see fetchCortexOnce), plus the ADR-0070 outage hook. Returns the
+ * Response (possibly a non-OK one, after retries are exhausted or refused); throws a clear "Could not
+ * reach" error when no response was ever obtained.
+ *
+ * policy.skipAutofile  never auto-file this call's failure, and never flush from it (the report POSTs).
+ */
+export async function fetchCortex(url, opts = {}, policy = {}) {
+  const hook = !policy.skipAutofile && autofileEnabled() && authOf(opts)
+  let res
+  try {
+    res = await fetchCortexOnce(url, opts, policy)
+  } catch (e) {
+    if (hook && e?.retryClass) {
+      const r = outageReport({ thrownClass: e.retryClass }, { tool: toolForUrl(url) })
+      if (r) spoolReport(r)
+    }
+    throw e
+  }
+  if (!hook) return res
+  if (res.ok) { void triggerFlush(url, authOf(opts)); return res }
+  try {
+    const contentType = res.headers.get('content-type')
+    let errorCode = null
+    if (res.status === 503 && String(contentType ?? '').includes('application/json')) {
+      try { errorCode = JSON.parse(await res.clone().text())?.error ?? null } catch { /* not json after all */ }
+    }
+    const r = outageReport({ status: res.status, contentType, errorCode },
+      { tool: toolForUrl(url), requestId: res.headers.get('x-vercel-id') })
+    if (r) spoolReport(r)
+  } catch { /* filing must never change what the caller gets */ }
+  return res
+}
+
 // Live health probe: hit /api/mcp-context with the token and classify the result.
 // Returns { ok, status, projectCount?, requestId?, diagnosis? }.
 export async function checkToken(token, base) {

package/lib/doctor.mjs

@@ -5,6 +5,14 @@ import { checkToken, checkSkills, resolveBase, resolveTokenSource } from './diag
 import { renderRenameNotice } from './rename_notice.mjs'
 import { detectSurface, renderSurface } from './surface.mjs'
 import { queueDir, queueStatus, renderQueueNotice } from './capture_queue.mjs'
+import { pendingNotice, renderReportNotice } from './report_spool.mjs'
+
+/** ADR-0070 §5: issue reports filed in the BACKGROUND since the last session start. A background
+ *  auto-file had no turn to tell anyone in, so this is where the person hears about it. Consumes the
+ *  notice (each filing is reported once). Local, synchronous, never throws. */
+function reportNotice(dir) {
+  try { return renderReportNotice(pendingNotice(dir ? { dir } : {})) } catch { return [] }
+}
 
 /** The capture-queue lines, or [] — local, synchronous, and never throws (a status line must not break). */
 function queueNotice(dir) {
@@ -38,14 +46,17 @@ export const resolveToken = resolveTokenSource
 // succeeds — most of all when it does not. They are read FIRST, locally, so the happy line can stop
 // claiming "sessions on this machine are captured" while some demonstrably are not.
 //
-// `opts.queueDir` exists for tests only (bun's os.homedir() ignores HOME, so a test cannot redirect it).
+// `opts.queueDir` / `opts.reportSpoolDir` exist for tests only (bun's os.homedir() ignores HOME, so a
+// test cannot redirect it).
 export async function runStatus(opts = {}) {
   const out = (m) => process.stdout.write(m + '\n')
   const queueLines = queueNotice(opts.queueDir)
+  const reportLines = reportNotice(opts.reportSpoolDir)
   try {
     await statusLine(out, { capturesStuck: queueLines.length > 0 })
   } finally {
     for (const line of queueLines) out(line)
+    for (const line of reportLines) out(line)
     const surface = renderSurface(detectSurface(process.env), 'status')
     if (surface) out(surface)
   }

package/lib/report_issue.mjs

@@ -0,0 +1,71 @@
+// ADR-0070 — the `report_issue` tool's logic, kept out of server.mjs so it can be exercised directly.
+//
+// The agent is the right reporter: it saw the tool, the status and the error code, where the person
+// saw "it didn't work". But two of the four kinds are JUDGMENTS about the person's own data or
+// experience, so they need the person's yes (Theron, 2026-09-24) — enforced here, not only asked for
+// in the description.
+
+import { postBugReport, clientVersion } from './diagnose.mjs'
+import { spoolReport } from './report_spool.mjs'
+
+export const REPORT_KINDS = ['outage', 'bug', 'data_wrong', 'confusing']
+export const ASK_FIRST_KINDS = new Set(['bug', 'data_wrong', 'confusing'])
+export const FREE_TEXT_MAX = 500
+
+export const REPORT_ISSUE_DESCRIPTION =
+  'File a structured issue report with the Agnoclast team. ' +
+  'WHEN: an Agnoclast tool failed in a way that looks like the product\'s fault, returned data the user says is wrong, or behaved confusingly. ' +
+  'OUTAGES (Agnoclast unreachable, timing out, 503, or blocked by infrastructure): file WITHOUT asking — most are already filed automatically. ' +
+  'For data_wrong, bug or confusing: ASK THE USER FIRST, and set user_approved=true ONLY if they agreed; without it the report is refused. ' +
+  'ALWAYS tell the user you filed it, in the same turn. ' +
+  'NEVER put page content, record content, names, or error message text in ANY field — use the tool name, HTTP status and the machine error code (e.g. `brain_required`) only. `summary`/`expected` describe the behaviour in generic words ("search returned a page from the wrong brain"), never the data itself.'
+
+/** PURE. Validate + shape the report. Returns { report } or { error }. */
+export function buildReport(args, version = clientVersion()) {
+  const kind = args?.kind
+  if (!REPORT_KINDS.includes(kind)) return { error: `kind must be one of ${REPORT_KINDS.join(', ')}` }
+  const approved = args?.user_approved === true
+  if (ASK_FIRST_KINDS.has(kind) && !approved) {
+    return { error: `NOT FILED. A ${kind} report needs the user's agreement first: ask them, and call again with user_approved=true only if they said yes.` }
+  }
+  const status = Number.isInteger(args?.status) ? args.status : null
+  const code = typeof args?.error_code === 'string' && /^[a-z_]{1,40}$/.test(args.error_code) ? args.error_code : (args?.error_code ? 'other' : null)
+  const report = {
+    kind, tool: typeof args?.tool === 'string' && /^[a-z0-9_]{1,64}$/.test(args.tool) ? args.tool : 'other',
+    status, error_code: code, failure_class: null, request_id: null, client_version: version ?? null,
+  }
+  // Free text travels only on a user-approved judged kind. An outage is fields, never prose.
+  if (ASK_FIRST_KINDS.has(kind) && approved) {
+    report.user_approved = true
+    const cap = (s) => (typeof s === 'string' && s.trim() ? s.trim().slice(0, FREE_TEXT_MAX) : undefined)
+    if (cap(args.summary)) report.summary = cap(args.summary)
+    if (cap(args.expected)) report.expected = cap(args.expected)
+  }
+  return { report }
+}
+
+/**
+ * File it now; on failure spool it (it is then sent after the next successful call). Returns the tool
+ * result text and whether it is an error. `post` is injectable for tests.
+ */
+export async function fileIssue(args, { base, token, version, post = postBugReport, spool = spoolReport } = {}) {
+  const built = buildReport(args, version)
+  if (built.error) return { isError: true, text: built.error }
+  const { report } = built
+  const body = { surface: 'agent', ...report }
+  let res = null
+  try { res = await post(base, `Bearer ${token}`, body) } catch { res = null }
+  if (res && res.status >= 200 && res.status < 300) {
+    let j = {}
+    try { j = await res.json() } catch { /* shape drift — still filed */ }
+    const count = Number(j?.count) > 1 ? ` It has now been reported ${j.count} times.` : ''
+    return { isError: false, text: `✓ Filed ${report.kind} report${j?.id ? ` ${j.id}` : ''} for \`${report.tool}\`.${count} Tell the user you filed it, now.` }
+  }
+  if (res && res.status >= 400 && res.status < 500 && res.status !== 429) {
+    return { isError: true, text: `NOT FILED — Agnoclast rejected the report (HTTP ${res.status}). Tell the user it could not be filed.` }
+  }
+  const saved = spool(report)
+  return saved
+    ? { isError: false, text: `Agnoclast could not take the report right now (${res ? `HTTP ${res.status}` : 'unreachable'}), so it was SAVED on this machine and will be sent automatically after the next successful call. Tell the user it is saved, not yet filed.` }
+    : { isError: true, text: 'NOT FILED — Agnoclast was unreachable and the report could not be saved locally either. Tell the user.' }
+}

package/lib/report_spool.mjs

@@ -0,0 +1,176 @@
+// ADR-0070 §5 — the local spool for bug reports an agent files, most of all the OUTAGE reports that
+// fetchCortex files on its own when Agnoclast cannot be reached at all.
+//
+// 🔴 WHY A SPOOL. An outage report is, by construction, filed at the moment the API is unreachable, so
+// the POST that would carry it fails for the same reason. It waits here and is sent after the next 2xx
+// from any call (fetchCortex triggers flush()).
+//
+// STANDALONE ON PURPOSE. It borrows capture_queue.mjs's RULES — dir 0700, files 0600, every write
+// tmp+rename, a drop ledger, nothing leaves silently — but not its code, which is bound to session
+// generations and protects session capture. A defect here must never be able to cost a capture.
+//
+// Layout — ~/.cortex/report-spool/:
+//   <dedup key>.json  one entry per failure SIGNATURE (kind, tool, status, error_code). A repeat
+//                     increments `count` and moves `last_seen`, so a flapping API is one report.
+//   _dropped.json     what the cap or a final server rejection forced out, for 7 days.
+//   _filed.json       what flush() sent in the background, until the next session start reports it.
+//   _notice.json      when that report was last made (pendingNotice's watermark).
+//
+// ⚠ STRUCTURED FIELDS ONLY. Nothing here ever holds an error MESSAGE — classify()'s text carries brain
+// names and page titles. Only an interactive, user-approved report_issue may carry summary/expected.
+
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createHash, randomBytes } from 'node:crypto'
+
+export const SPOOL_MAX_ENTRIES = 50
+export const DROPPED_WINDOW_DAYS = 7
+const DAY_MS = 24 * 60 * 60_000
+const LEDGER_MAX = 100
+
+/** The spool directory. CORTEX_REPORT_SPOOL_DIR exists for tests (bun's os.homedir() ignores HOME), and
+ *  under `bun test` without it the real home is never touched — a test must not consume a real notice. */
+export function spoolDir(env = process.env) {
+  if (env.CORTEX_REPORT_SPOOL_DIR) return env.CORTEX_REPORT_SPOOL_DIR
+  if (env.NODE_ENV === 'test') return join(tmpdir(), `cortex-report-spool-test-${process.pid}`)
+  return join(homedir(), '.cortex', 'report-spool')
+}
+
+/** PURE. The dedup key: kind, tool, status, error_code — NOT version (one outage spans releases). */
+export function reportKey({ kind, tool, status, error_code }) {
+  const sig = JSON.stringify([kind ?? null, tool ?? null, status ?? null, error_code ?? null])
+  return createHash('sha256').update(sig).digest('hex').slice(0, 32)
+}
+
+function atomicWrite(dir, name, value) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const file = join(dir, name)
+  const tmp = `${file}.${process.pid}.${randomBytes(3).toString('hex')}.tmp`
+  writeFileSync(tmp, JSON.stringify(value), { mode: 0o600 })
+  renameSync(tmp, file) // a concurrent reader never sees half a file
+}
+
+const readJson = (file, fallback) => { try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return fallback } }
+
+/** Every readable entry. An unreadable one is removed AND recorded — never skipped forever. */
+export function readEntries(dir = spoolDir()) {
+  let names
+  try { names = readdirSync(dir) } catch { return [] }
+  const out = []
+  for (const n of names) {
+    if (!n.endsWith('.json') || n.startsWith('_')) continue
+    const e = readJson(join(dir, n), null)
+    if (e && typeof e === 'object' && e.key) { out.push(e); continue }
+    try { unlinkSync(join(dir, n)) } catch { /* raced */ }
+    ledgerAppend(dir, '_dropped.json', { at: Date.now(), kind: null, tool: null, reason: 'unreadable spool file' })
+  }
+  return out
+}
+
+function ledgerRead(dir, name, now = Date.now()) {
+  const list = readJson(join(dir, name), [])
+  return Array.isArray(list) ? list.filter((d) => now - (d?.at ?? 0) <= DROPPED_WINDOW_DAYS * DAY_MS) : []
+}
+
+function ledgerAppend(dir, name, item, now = Date.now()) {
+  try { atomicWrite(dir, name, [...ledgerRead(dir, name, now), item].slice(-LEDGER_MAX)) } catch { /* never throw from a ledger */ }
+}
+
+export const readDropped = (dir = spoolDir(), now = Date.now()) => ledgerRead(dir, '_dropped.json', now)
+
+const dropRow = (e, reason, at) => ({ at, kind: e.kind, tool: e.tool, status: e.status ?? null, count: e.count ?? 1, reason })
+
+/**
+ * Spool one report. A repeat of the same signature increments `count`; a NEW signature past the cap
+ * evicts the oldest (by last_seen) into the drop ledger. Returns the entry written, or null. Never throws.
+ */
+export function spoolReport(report, { dir = spoolDir(), now = Date.now() } = {}) {
+  try {
+    const key = reportKey(report)
+    const cur = readJson(join(dir, `${key}.json`), null)
+    const entry = cur?.key
+      ? { ...cur, ...report, key, rev: randomBytes(6).toString('hex'), count: (cur.count ?? 1) + (report.count ?? 1), last_seen: now }
+      : { ...report, key, rev: randomBytes(6).toString('hex'), count: report.count ?? 1, first_seen: now, last_seen: now, attempts: 0 }
+    if (!cur?.key) {
+      const others = readEntries(dir).sort((a, b) => (a.last_seen ?? 0) - (b.last_seen ?? 0))
+      while (others.length >= SPOOL_MAX_ENTRIES) {
+        const old = others.shift()
+        try { unlinkSync(join(dir, `${old.key}.json`)) } catch { /* raced */ }
+        ledgerAppend(dir, '_dropped.json', dropRow(old, 'spool full', now), now)
+      }
+    }
+    atomicWrite(dir, `${key}.json`, entry)
+    return entry
+  } catch { return null }
+}
+
+/** PURE. The wire body for one entry — the §2 contract, and nothing else. */
+export function wireBody(e) {
+  const body = {
+    surface: 'agent', kind: e.kind, tool: e.tool ?? 'other', status: e.status ?? null, error_code: e.error_code ?? null,
+    failure_class: e.failure_class ?? null, request_id: e.request_id ?? null, client_version: e.client_version ?? null,
+    count: e.count ?? 1,
+  }
+  if (e.user_approved === true) {
+    body.user_approved = true
+    if (e.summary) body.summary = e.summary
+    if (e.expected) body.expected = e.expected
+  }
+  return body
+}
+
+/**
+ * Send every entry via `postFn(body)` → { status } (or throws). 2xx removes it (any repeats spooled
+ * meanwhile stay); a final 4xx (not 429) moves it to the drop ledger; 429/5xx/network keep it with
+ * attempts+1. Returns { sent, kept, dropped }.
+ */
+export async function flush(postFn, { dir = spoolDir(), now = Date.now } = {}) {
+  const out = { sent: 0, kept: 0, dropped: 0 }
+  for (const e of readEntries(dir)) {
+    let status = 0
+    try { status = Number((await postFn(wireBody(e)))?.status) || 0 } catch { status = 0 }
+    const file = join(dir, `${e.key}.json`)
+    const cur = readJson(file, null)
+    if (status >= 200 && status < 300) {
+      out.sent++
+      ledgerAppend(dir, '_filed.json', { at: now(), kind: e.kind, tool: e.tool, status: e.status ?? null, count: e.count ?? 1 }, now())
+      if (cur?.rev && cur.rev !== e.rev && (cur.count ?? 1) > (e.count ?? 1)) {
+        atomicWrite(dir, `${e.key}.json`, { ...cur, count: cur.count - (e.count ?? 1) })
+      } else { try { unlinkSync(file) } catch { /* raced */ } }
+    } else if (status >= 400 && status < 500 && status !== 429) {
+      out.dropped++
+      try { unlinkSync(file) } catch { /* raced */ }
+      ledgerAppend(dir, '_dropped.json', dropRow(e, `rejected ${status}`, now()), now())
+    } else {
+      out.kept++
+      if (cur?.key) atomicWrite(dir, `${e.key}.json`, { ...cur, attempts: (cur.attempts ?? 0) + 1 })
+    }
+  }
+  return out
+}
+
+/**
+ * What was filed in the BACKGROUND (and what was dropped) since the last notice, then move the
+ * watermark — so each is reported at exactly one session start. Returns { filed, dropped }.
+ */
+export function pendingNotice({ dir = spoolDir(), now = Date.now() } = {}) {
+  try {
+    const since = Number(readJson(join(dir, '_notice.json'), {})?.at) || 0
+    const filed = ledgerRead(dir, '_filed.json', now).filter((x) => x.at > since)
+    const dropped = ledgerRead(dir, '_dropped.json', now).filter((x) => x.at > since)
+    if (filed.length || dropped.length) atomicWrite(dir, '_notice.json', { at: now })
+    return { filed, dropped }
+  } catch { return { filed: [], dropped: [] } }
+}
+
+/** PURE. The session-start lines for pendingNotice()'s result — empty when there is nothing to say. */
+export function renderReportNotice({ filed = [], dropped = [] } = {}) {
+  const lines = []
+  const outages = filed.filter((x) => x.kind === 'outage').length
+  const other = filed.length - outages
+  if (outages) lines.push(`Agnoclast: ${outages} outage report(s) were filed automatically while you were away — tell the user.`)
+  if (other) lines.push(`Agnoclast: ${other} saved issue report(s) were sent once Agnoclast was reachable again — tell the user.`)
+  if (dropped.length) lines.push(`Agnoclast: ⚠ ${dropped.length} issue report(s) could not be sent and were dropped (${dropped[0].reason}).`)
+  return lines
+}

package/lib/server.mjs

@@ -5,7 +5,8 @@ import { writeFileSync, mkdirSync, readFileSync, statSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { createHash, randomUUID } from 'crypto'
-import { fetchCortex, classify, resolveBase, resolveEnvToken, setSessionKey, setClientVersion } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase, resolveEnvToken, setSessionKey, setClientVersion, runWithTool } from './diagnose.mjs'
+import { REPORT_KINDS, REPORT_ISSUE_DESCRIPTION, fileIssue } from './report_issue.mjs'
 import { folderClaimLine } from './folder_claims.mjs'
 import { resolveSessionKey, resolveLogSessionId } from './session_key.mjs'
 import { runSendImessage } from './imessage_send.mjs'
@@ -247,6 +248,11 @@ export async function runServer(version) {
   }
 
   const server = new McpServer({ name: 'cortex', version })
+  // ADR-0070: every tool runs with its NAME in async context, so an outage fetchCortex auto-files is
+  // attributed to the tool that hit it rather than guessed from a URL shared by several tools.
+  const registerTool = server.registerTool.bind(server)
+  server.registerTool = (name, config, handler) =>
+    registerTool(name, config, (...args) => runWithTool(name, () => handler(...args)))
 
 
 // ── THE PRE-CLAIM NUDGE, rendered ───────────────────────────────────────────────────────────────
@@ -362,8 +368,12 @@ function renderNudge(payload) {
         const body = await res.text()
         throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
       }
-      const { context } = await res.json()
-      return { content: [{ type: 'text', text: context }] }
+      const ctx = await res.json()
+      // ⭐ RENDER THE ARRIVALS DELTA HERE TOO. It was wired to grep / read_page / list_records only,
+      // so a session doing pipeline work never saw it — measured 2026-09-24, eighteen hours with a
+      // stale watermark while three arrivals landed unannounced. This is the tool an agent calls at
+      // session start and on every topic shift, which is when "mail arrived" is worth knowing.
+      return { content: [{ type: 'text', text: (ctx?.context ?? '') + renderArrival(ctx) }] }
     },
   )
 
@@ -855,8 +865,12 @@ function renderNudge(payload) {
         const body = await res.text()
         throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
       }
-      const { context } = await res.json()
-      return { content: [{ type: 'text', text: context }] }
+      const ctx = await res.json()
+      // ⭐ RENDER THE ARRIVALS DELTA HERE TOO. It was wired to grep / read_page / list_records only,
+      // so a session doing pipeline work never saw it — measured 2026-09-24, eighteen hours with a
+      // stale watermark while three arrivals landed unannounced. This is the tool an agent calls at
+      // session start and on every topic shift, which is when "mail arrived" is worth knowing.
+      return { content: [{ type: 'text', text: (ctx?.context ?? '') + renderArrival(ctx) }] }
     },
   )
 
@@ -4106,6 +4120,81 @@ function renderNudge(payload) {
     },
   )
 
+  // ⭐ THE OTHER HALF OF set_routing_identifier (2026-09-24). A claim was ONE CALL to create and,
+  // through this server, impossible to remove — so a wrong brain decision was permanent. That
+  // contradicts the thing ADR-0066 is built on: filing is a judgment, and judgments get revised.
+  //
+  // ⚠ THE ENGINE AND THE ENDPOINT BOTH ALREADY EXISTED. `clearPageRoutingIdentifier` and the DELETE
+  // on /api/brain/routing-identifiers have been there the whole time; only the agent-facing verb was
+  // missing, so the capability was real and unreachable. Ninth instance of that shape this week.
+  server.registerTool(
+    'unclaim_routing_identifier',
+    {
+      title: 'Remove a routing claim from a page',
+      description:
+        'Remove an identifier claim from a page — the counterpart to `set_routing_identifier`. Use it when a claim sends mail to the wrong brain, when a page was claimed by mistake, or when TWO brains claim the same key and you want one of them to stop (that is the case where nothing routes at all, because a split stages rather than picking). ' +
+        '⭐ THE RESPONSE TELLS YOU WHAT ROUTING DOES NOW, which is the reason to call it: removing a claim moves the identifier between "routes", "stages because nothing claims it" and "stages because several do", and the delete count alone cannot tell you which. Computed with the router\'s own logic. ' +
+        '⚠ HISTORY IS NOT UNDONE BY DEFAULT. `set_routing_identifier` HEALS history — it attaches every record already carrying the identifier — but removing the claim leaves those attachments in place, and the response says how many. That asymmetry is deliberate: a claim is a ROUTING RULE, an attachment is a RECORD\'S PLACEMENT, and one such claim was measured accounting for 1,271 attachments on a single page. Pass `detach: true` only when you mean to unfile them too; it never touches a governing attachment, or one a person or an LLM made rather than this claim. ' +
+        '⚠ REVERSIBLE BY CONSTRUCTION: `set_routing_identifier` puts it back in one call and re-heals history. No content is destroyed here, which is why this needs no dry run.',
+      inputSchema: {
+        kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
+        name: z.string().optional().describe('page title (or pass ref)'),
+        ref: z.string().optional().describe('node ref from read_page — prefer over name when available'),
+        brain: z.string().optional().describe('brain label when the title is ambiguous across brains — REQUIRED in practice when two brains hold a page of the same name, which is the usual reason you are here'),
+        identifier: z.string().describe('the claim to remove, e.g. email:someone@example.com or repo:owner/name. See `my_routing_claims` for what is claimed where'),
+        detach: z.boolean().optional().describe('also remove the attachments this claim made (default false). Leaves governing attachments and anything a person or LLM attached'),
+      },
+    },
+    async ({ kind, name, ref, brain, identifier, detach }) => {
+      if (!name && !ref) return toolError('Pass name or ref')
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/routing-identifiers`, {
+          method: 'DELETE',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ kind, name, ref, brain, identifier, detach: detach === true }),
+        })
+      } catch (e) {
+        return toolError(`Could not remove the routing claim: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        if (out?.candidates?.length) {
+          return toolError(`That page title is ambiguous across brains — pass \`brain\`. Candidates: ${out.candidates.join(', ')}`)
+        }
+        return toolError(`Could not remove the routing claim: ${out?.error ?? res.status}`)
+      }
+      // A ZERO IS A VERDICT, NOT AN ERROR — the same convention my_routing_claims states. "No such
+      // claim" is worth saying plainly, because the usual cause is that the claim is on a DIFFERENT
+      // page (or in a different brain) than the caller assumed, and retrying the same call will not
+      // find it either.
+      if (!out?.removed) {
+        return {
+          content: [{
+            type: 'text',
+            text: `No claim on ${identifier} was found on that page, so nothing changed. That usually means the claim lives on a different page or in another brain — \`my_routing_claims ${identifier}\` shows every page that claims it.`,
+          }],
+        }
+      }
+      const left = typeof out?.attachmentsLeft === 'number' ? out.attachmentsLeft : null
+      const historyLine = out?.detached
+        ? `\n  ${out.detached} attachment(s) this claim had made were also removed; governing attachments and anything a person or an LLM attached were left alone.`
+        : left
+          ? `\n  ⚠ ${left} record(s) this claim previously attached to that page are STILL attached — removing the rule does not unfile history. Re-run with \`detach: true\` if they should come off too.`
+          : ''
+      return {
+        content: [{
+          type: 'text',
+          text:
+            `Removed the claim on ${out?.identifier ?? identifier}.\n` +
+            `  ➜ ${out?.routing?.verdict ?? '(routing outcome unavailable)'}` +
+            historyLine +
+            `\n  Reversible: \`set_routing_identifier\` puts it back and re-attaches history.`,
+        }],
+      }
+    },
+  )
+
   // ── Gate 4 record triage, over timeline_claims ────────────────────────────────────────────
   // A connector event materializes in seconds and has no idea what the work WAS. The session that
   // did the work knows exactly, and arrives later. These three tools are that handoff: look at what
@@ -4184,7 +4273,10 @@ function renderNudge(payload) {
 
       const records = out?.records ?? []
       if (records.length === 0) {
-        return { content: [{ type: 'text', text: 'Nothing waiting for a home.' }] }
+        // ⚠ THE DELTA STILL SHIPS ON THE EMPTY PATH. "Nothing waiting for a home" and "nothing has
+        // arrived" are different facts, and an empty digest is exactly when a silent counter reads
+        // as all-clear.
+        return { content: [{ type: 'text', text: 'Nothing waiting for a home.' + renderArrival(out) }] }
       }
       const lines = records.map((r) => {
         const homes = r.currentHomes?.length ? r.currentHomes.join(', ') : 'nothing'
@@ -4194,7 +4286,7 @@ function renderNudge(payload) {
       return {
         content: [{
           type: 'text',
-          text: `${records.length} record(s) waiting for a home:\n\n${lines.join('\n\n')}\n\nRecognize any as your own work? claim_record it now, then route_record once you know where it belongs.`,
+          text: `${records.length} record(s) waiting for a home:\n\n${lines.join('\n\n')}\n\nRecognize any as your own work? claim_record it now, then route_record once you know where it belongs.` + renderArrival(out),
         }],
       }
     },
@@ -5102,5 +5194,28 @@ function renderNudge(payload) {
     },
   )
 
+  // ADR-0070 — the agent files the bug report. Outages are filed without asking (and most already are,
+  // by fetchCortex); the three JUDGED kinds need the user's yes, enforced in report_issue.mjs.
+  server.registerTool(
+    'report_issue',
+    {
+      title: 'Report an Agnoclast issue',
+      description: REPORT_ISSUE_DESCRIPTION,
+      inputSchema: {
+        kind: z.enum(REPORT_KINDS).describe('outage = Agnoclast unreachable/timing out/503/blocked; bug = a tool misbehaved; data_wrong = the user says the data shown is wrong; confusing = a tool\'s behaviour or wording confused you or the user'),
+        tool: z.string().describe('the Agnoclast tool name involved, e.g. `grep` or `read_page`; `other` if none'),
+        status: z.number().int().optional().describe('the HTTP status you saw, if any'),
+        error_code: z.string().optional().describe('the machine error code only (e.g. `brain_required`) — NEVER the error message text'),
+        summary: z.string().optional().describe('bug/data_wrong/confusing only, ≤500 chars: the behaviour in generic words. NO page content, record content, names or error text'),
+        expected: z.string().optional().describe('bug/data_wrong/confusing only, ≤500 chars: what should have happened, in generic words'),
+        user_approved: z.boolean().describe('true ONLY if you asked the user and they agreed to file this. Required true for bug, data_wrong and confusing; ignored for outage'),
+      },
+    },
+    async (args) => {
+      const r = await fileIssue(args, { base: BASE, token: TOKEN, version })
+      return r.isError ? toolError(r.text) : { content: [{ type: 'text', text: r.text }] }
+    },
+  )
+
   await server.connect(new StdioServerTransport())
 }

package/package.json

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