@theronap/agnoclast-mcp 0.9.187 → 0.9.188

package/lib/diagnose.mjs

@@ -485,7 +485,8 @@ async function fetchCortexOnce(url, opts = {}, policy = {}) {
 // 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')
+//   connect / DNS                       → outage   (failure_class 'connect')
+//   timeout                             → outage   (failure_class 'timeout' — it ANSWERED too slowly, it did not refuse)
 //   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
@@ -501,11 +502,19 @@ 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.
+// For callers outside a tool call (hooks, doctor, the heartbeat). Unknown paths are 'other' — the server
+// coerces too.
+//
+// ⚠ 'other' IS WHERE A REPORT GOES TO BE UNREADABLE. The first ×3 `other` timeout (2026-09-28) took an
+// agent a transcript-and-log dig to identify as the session-ping heartbeat, because every call made
+// outside a tool — the heartbeat, capture, the arrivals hook, skill sync — landed in the same bucket.
+// Each now carries a name the server's KNOWN_TOOLS accepts (web/lib/engine/bug_reports.ts).
 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',
+  'session-ping': 'session_ping', 'session-signals': 'session_signals', 'skills': 'skills',
+  'ingest': 'capture', 'node-types': 'capture', 'obligations/candidates': 'capture',
 }
 
 /** PURE. The tool an outage on `url` belongs to: the running tool if known, else a path mapping, else 'other'. */
@@ -528,7 +537,9 @@ export function outageReport(outcome, { tool, requestId = null, version = CLIENT
   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' }
+    // A timeout is its own class: the server was reached and was SLOW. Filing it as 'connect' told the
+    // reader "could not reach" about a request that may well have completed after we gave up.
+    if (outcome.thrownClass === 'timeout') return { ...base, status: null, error_code: 'timeout', failure_class: 'timeout' }
     return null
   }
   const { status, contentType } = outcome
@@ -606,20 +617,36 @@ function triggerFlush(url, authorization) {
 /** Tests: await the in-flight flush, if any. */
 export const pendingFlush = () => flushing
 
+// ⚠ A HEARTBEAT IS A NOISY OUTAGE SENSOR. session-ping fires every 60s per open session, best-effort,
+// never retried after a timeout — so one slow request on one instance filed an outage, and two MCP
+// servers flushing the same entry counted it twice (2026-09-28: ×3 reports for two failures, laptop
+// awake and online both times). A missed beat is harmless by design; the next one refreshes presence.
+// So a heartbeat files only when it has failed this many times IN A ROW — a real outage does that, a
+// blip does not.
+export const HEARTBEAT_OUTAGE_AFTER = 3
+/** PURE. The fetchCortex policy for a heartbeat that has already failed `consecutiveFailures` times in a row. */
+export function heartbeatPolicy(consecutiveFailures) {
+  return { fileOutage: consecutiveFailures + 1 >= HEARTBEAT_OUTAGE_AFTER }
+}
+
 /**
  * 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).
+ * policy.fileOutage    false = do not file THIS call's failure, but DO still flush the spool on success.
+ *                      Distinct from skipAutofile on purpose: the heartbeat is the call most likely to
+ *                      be the next 2xx after an outage, so it must keep carrying the spool out.
  */
 export async function fetchCortex(url, opts = {}, policy = {}) {
   const hook = !policy.skipAutofile && autofileEnabled() && authOf(opts)
+  const file = hook && policy.fileOutage !== false
   let res
   try {
     res = await fetchCortexOnce(url, opts, policy)
   } catch (e) {
-    if (hook && e?.retryClass) {
+    if (file && e?.retryClass) {
       const r = outageReport({ thrownClass: e.retryClass }, { tool: toolForUrl(url) })
       // Awaited, not fire-and-forget: hook processes are short-lived and would exit before a detached
       // probe answered. Bounded by REACHABILITY_TIMEOUT_MS, and only on a path that is already failing.
@@ -629,6 +656,7 @@ export async function fetchCortex(url, opts = {}, policy = {}) {
   }
   if (!hook) return res
   if (res.ok) { void triggerFlush(url, authOf(opts)); return res }
+  if (!file) return res
   try {
     const contentType = res.headers.get('content-type')
     let errorCode = null

package/lib/report_spool.mjs

@@ -19,7 +19,7 @@
 // ⚠ 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 { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, statSync, openSync, closeSync } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { createHash, randomBytes } from 'node:crypto'
@@ -81,6 +81,32 @@ export const readDropped = (dir = spoolDir(), now = Date.now()) => ledgerRead(di
 
 const dropRow = (e, reason, at) => ({ at, kind: e.kind, tool: e.tool, status: e.status ?? null, count: e.count ?? 1, reason })
 
+// ⚠ ONE WRITER PER KEY AT A TIME. spoolReport, the flush claim and releaseClaim each READ an entry and
+// then WRITE it. Without a lock, a spoolReport that read `<key>.json` just before a flush renamed it
+// away would write the old count back into a fresh file — re-sending what had just been sent — and a
+// releaseClaim racing a spoolReport could overwrite a repeat (Codex review of the claim design,
+// 2026-09-29). An O_EXCL lock file per key serialises those three; the POST itself stays OUTSIDE it,
+// so a slow server never holds a writer up. A lock older than LOCK_STALE_MS belongs to a dead process.
+const LOCK_STALE_MS = 5_000
+const LOCK_WAIT_MS = 250
+function withKeyLock(dir, key, fn) {
+  const lock = join(dir, `_lock.${key}`)
+  const deadline = Date.now() + LOCK_WAIT_MS
+  for (;;) {
+    try {
+      mkdirSync(dir, { recursive: true, mode: 0o700 })
+      closeSync(openSync(lock, 'wx', 0o600))
+      break
+    } catch (e) {
+      if (e?.code !== 'EEXIST') return undefined
+      try { if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) { unlinkSync(lock); continue } } catch { continue }
+      if (Date.now() > deadline) return undefined // contended: the caller skips, it never blocks a session
+      const until = Date.now() + 5; while (Date.now() < until) { /* brief spin: these sections are sub-ms */ }
+    }
+  }
+  try { return fn() } finally { try { unlinkSync(lock) } catch { /* already gone */ } }
+}
+
 /**
  * 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.
@@ -88,6 +114,12 @@ const dropRow = (e, reason, at) => ({ at, kind: e.kind, tool: e.tool, status: e.
 export function spoolReport(report, { dir = spoolDir(), now = Date.now() } = {}) {
   try {
     const key = reportKey(report)
+    return withKeyLock(dir, key, () => spoolLocked(report, key, dir, now)) ?? null
+  } catch { return null }
+}
+
+function spoolLocked(report, key, dir, now) {
+  try {
     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 }
@@ -120,31 +152,77 @@ export function wireBody(e) {
   return body
 }
 
+// ⚠ CLAIM BEFORE SENDING. Every MCP server and hook process flushes after its own next 2xx, and nothing
+// stopped two of them reading the same entry and both POSTing it — the server dedupes onto one open row
+// per signature and ADDS the count, so one failure was reported twice. Measured 2026-09-28: two POSTs of
+// one entry 183 ms apart, which is how two heartbeat timeouts became "×3". A rename is atomic, so of any
+// number of concurrent flushes exactly one takes a given entry; the rest skip it. While it is claimed, a
+// repeat of the same failure lands in a FRESH <key>.json, so nothing spooled mid-send is lost or re-sent.
+const CLAIM_MARK = '.json.sending.'
+export const STALE_CLAIM_MS = 10 * 60_000
+
+/** Put a claimed entry back (a send that must be retried, or a claim its process abandoned), merging any
+ *  repeats spooled while it was out. Never throws. */
+function releaseClaim(dir, claimedPath, entry, { attempted }) {
+  withKeyLock(dir, entry.key, () => releaseLocked(dir, claimedPath, entry, { attempted }))
+}
+
+function releaseLocked(dir, claimedPath, entry, { attempted }) {
+  try {
+    const file = join(dir, `${entry.key}.json`)
+    const fresh = readJson(file, null)
+    const attempts = (entry.attempts ?? 0) + (attempted ? 1 : 0)
+    const merged = fresh?.key
+      ? { ...fresh, count: (fresh.count ?? 1) + (entry.count ?? 1), first_seen: Math.min(fresh.first_seen ?? Infinity, entry.first_seen ?? Infinity), attempts }
+      : { ...entry, attempts }
+    atomicWrite(dir, `${entry.key}.json`, merged)
+    unlinkSync(claimedPath)
+  } catch { /* the claim file stays and is recovered as stale */ }
+}
+
+/** Claims older than STALE_CLAIM_MS belong to a process that died mid-send: return them to the spool. */
+function recoverStaleClaims(dir, now) {
+  let names
+  try { names = readdirSync(dir) } catch { return }
+  for (const n of names) {
+    if (!n.includes(CLAIM_MARK)) continue
+    const p = join(dir, n)
+    try {
+      if (now - statSync(p).mtimeMs < STALE_CLAIM_MS) continue
+      const e = readJson(p, null)
+      if (e?.key) releaseClaim(dir, p, e, { attempted: false })
+      else unlinkSync(p)
+    } catch { /* raced with another recoverer */ }
+  }
+}
+
 /**
- * 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 }.
+ * Send every entry via `postFn(body)` → { status } (or throws). 2xx removes it; a final 4xx (not 429)
+ * moves it to the drop ledger; 429/5xx/network put it back with attempts+1. Each entry is CLAIMED first
+ * (see CLAIM_MARK), so concurrent flushes never send one entry twice. Returns { sent, kept, dropped }.
  */
 export async function flush(postFn, { dir = spoolDir(), now = Date.now } = {}) {
   const out = { sent: 0, kept: 0, dropped: 0 }
+  recoverStaleClaims(dir, now())
   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)
+    const claimed = `${file}${CLAIM_MARK.slice('.json'.length)}${process.pid}.${randomBytes(3).toString('hex')}`
+    const took = withKeyLock(dir, e.key, () => { try { renameSync(file, claimed); return true } catch { return false } })
+    if (!took) continue // another flush took it, or a writer holds the key right now — next flush gets it
+    const mine = readJson(claimed, null) ?? e // what we actually own — repeats may have landed since readEntries
+    let status = 0
+    try { status = Number((await postFn(wireBody(mine)))?.status) || 0 } catch { status = 0 }
     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 */ } }
+      ledgerAppend(dir, '_filed.json', { at: now(), kind: mine.kind, tool: mine.tool, status: mine.status ?? null, count: mine.count ?? 1 }, now())
+      try { unlinkSync(claimed) } 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())
+      try { unlinkSync(claimed) } catch { /* raced */ }
+      ledgerAppend(dir, '_dropped.json', dropRow(mine, `rejected ${status}`, now()), now())
     } else {
       out.kept++
-      if (cur?.key) atomicWrite(dir, `${e.key}.json`, { ...cur, attempts: (cur.attempts ?? 0) + 1 })
+      releaseClaim(dir, claimed, mine, { attempted: true })
     }
   }
   return out

package/lib/server.mjs

@@ -5,7 +5,7 @@ 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, runWithTool } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase, resolveEnvToken, setSessionKey, setClientVersion, runWithTool, heartbeatPolicy } 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'
@@ -253,9 +253,12 @@ export async function runServer(version) {
   function currentAuthored() {
     try { return workedFiles ? workedFiles.authored(100) : [] } catch { return [] }
   }
+  // Consecutive heartbeat failures. A lone slow beat is not an outage (see HEARTBEAT_OUTAGE_AFTER);
+  // three in a row is, and that beat files through fetchCortex's normal path, probe included.
+  let pingFailures = 0
   async function pingSession() {
     try {
-      await fetchCortex(`${BASE}/api/session-ping`, {
+      const res = await fetchCortex(`${BASE}/api/session-ping`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
         // mcpVersion (ADR-0033 T9): the fleet currently has NO way to report which client build a
@@ -286,8 +289,10 @@ export async function runServer(version) {
           // YOURS; a shared changed file is not (see authoredInCall in working_files.mjs).
           authored: currentAuthored(),
         }),
-      })
-    } catch { /* best-effort heartbeat — never disrupt the session */ }
+      }, heartbeatPolicy(pingFailures))
+      pingFailures = res.ok ? 0 : pingFailures + 1
+      try { await res.body?.cancel() } catch { /* nothing to drain */ }
+    } catch { pingFailures++ /* best-effort heartbeat — never disrupt the session */ }
   }
   void pingSession()
   const _hb = setInterval(() => void pingSession(), 60_000)

package/package.json

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