@theronap/agnoclast-mcp 0.9.172 → 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) }] }
     },
   )
 
@@ -4259,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'
@@ -4269,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),
         }],
       }
     },
@@ -5177,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.172",
+  "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": {