@theronap/cortex-mcp 0.9.149 → 0.9.150

package/lib/diagnose.mjs

@@ -242,16 +242,6 @@ export function classify(status, contentType, bodyText, requestId) {
   }
 }
 
-// fetch with retry on TRANSIENT responses only (429, 5xx, and infra-style non-JSON 403).
-// App-level 401/403-with-JSON are returned immediately (retrying won't change the verdict).
-// Throws a clear network error if the host is unreachable after retries.
-//
-// PER-ATTEMPT TIMEOUT (added 2026-07-08): every attempt is bounded by an AbortSignal so a
-// HANGING server (not a fast 5xx — an ingest endpoint that just never responds, observed this day)
-// can't stall a hook indefinitely. Without it, `fetch` waits forever and the retry loop made it
-// WORSE — 3 unbounded attempts stacked. Now worst case = (retries+1) * timeoutMs + backoff, and a
-// timed-out attempt is treated as transient (retried, then surfaced as the reach error the callers
-// already swallow). Tunable via CORTEX_HTTP_TIMEOUT_MS; per-call override via opts.timeoutMs.
 // ADR-0020 Stage 2 — this process's session identity, stamped on every request so the server can
 // resolve THIS session's write pointer instead of the person-wide one. Set once by the MCP server at
 // startup (setSessionKey); left null in the one-shot hook processes (capture, context_log), which
@@ -280,39 +270,193 @@ export function setClientVersion(version) {
   CLIENT_ID = `cortex-mcp/${version || 'unknown'}`
 }
 
-export async function fetchCortex(url, opts = {}, { retries = 2, baseDelayMs = 400 } = {}) {
+// ── Retries (D9, eng review 2026-09-11) ──────────────────────────────────────────────────────────
+//
+// 🔴 WHY THIS WAS REWRITTEN. The old loop retried 3× at a fixed 400/800 ms on ANY 429 or 5xx, POSTs
+// included, with no jitter and no regard for Retry-After. Once the server started answering 429, every
+// client retried immediately and in lockstep — tripling the load on a server that had just said it was
+// overloaded — and after an outage the synchronized reconnects knocked it over again. A retry policy is
+// load the CLIENT decides to add, so it has to be decided per failure, not per status range.
+//
+// What a failure MEANS decides whether it may be retried:
+//
+//   refused  429, 503, or a non-JSON 403 (an infrastructure block in front of the app). The request
+//            was NOT processed, so retrying is safe for any method. Retry-After is honored.
+//   connect  the connection was never made (refused, DNS). Nothing reached the server: safe for any
+//            method, and it costs the server nothing.
+//   server   any other 5xx. The request MAY have been processed. Retried only when idempotent.
+//   network  the connection broke mid-flight. Same ambiguity as `server`: idempotent only.
+//   timeout  our per-attempt timer fired — the server is SLOW, not absent. Idempotent only, and at
+//            most ONCE per call, whatever `retries` says: re-asking a server that is too slow to answer
+//            is how a slow server becomes a down one. Callers can refuse even that one (hydrate does).
+//
+// "Idempotent" defaults to GET/HEAD. A POST the server dedupes may opt in (capture's /api/ingest does;
+// its conclusion is written where it opts in, in capture.mjs).
+//
+// Waits: Retry-After when the server sends it (delay-seconds or HTTP-date), plus a small spread so a
+// fleet told "10 s" does not come back in the same millisecond. A Retry-After beyond RETRY_AFTER_CAP_MS
+// is NOT shortened — retrying before the server asked defeats the limit — the call simply stops and
+// returns that response. Otherwise exponential backoff with FULL jitter (uniform in [0, ceiling)).
+//
+// And one overall budget per call, so a hook can never hang: no retry starts if its wait plus a minimum
+// useful attempt would overrun it, and every attempt's timeout is clipped to what is left. The first
+// attempt always gets its full timeout, so a caller's CORTEX_HTTP_TIMEOUT_MS is never cut short.
+//
+// PER-ATTEMPT TIMEOUT (added 2026-07-08, kept): every attempt is bounded by an AbortSignal so a
+// HANGING server can't stall a hook indefinitely. Tunable via CORTEX_HTTP_TIMEOUT_MS; per-call override
+// via opts.timeoutMs. A caller's own signal aborting is never retried — they asked to stop.
+
+/** The longest Retry-After this client will wait out in-process. Longer asks are honored by NOT
+ *  retrying (the capture queue then schedules its next attempt no earlier than the ask). */
+export const RETRY_AFTER_CAP_MS = 30_000
+/** Added on top of a Retry-After so clients told the same delay do not return in lockstep. */
+export const RETRY_AFTER_SPREAD_MS = 1_000
+/** Beyond the first attempt's own timeout, how long retries may add (default overall budget). */
+export const DEFAULT_RETRY_BUDGET_MS = 30_000
+
+const CONNECT_ERROR_CODES = new Set([
+  // node / undici — carried on err.cause.code (an AggregateError carries it too, when happy-eyeballs
+  // tried both address families; verified 2026-09-11 against a closed port on node 24)
+  'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'ENETDOWN', 'EHOSTDOWN',
+  'UND_ERR_CONNECT_TIMEOUT',
+  // bun — carried on err.code; bun reports a DNS failure as ConnectionRefused too (verified, bun 1.3)
+  'ConnectionRefused', 'FailedToOpenSocket',
+])
+
+/**
+ * PURE. A Retry-After header value → milliseconds to wait, or null when absent or unparseable.
+ * Accepts both RFC 9110 forms: delay-seconds ("120") and an HTTP-date. A date in the past is 0.
+ * Deliberately UNCAPPED — the cap is a decision about whether to retry, made by the caller.
+ */
+export function parseRetryAfter(value, nowMs = Date.now()) {
+  if (value === null || value === undefined) return null
+  const s = String(value).trim()
+  if (!s) return null
+  if (/^\d+$/.test(s)) return Number(s) * 1000
+  if (/^[+-]?[\d.]+$/.test(s)) return null // "-5", "1.5": not a valid delay-seconds, not a date either
+  const at = Date.parse(s)
+  if (!Number.isFinite(at)) return null
+  return Math.max(0, at - nowMs)
+}
+
+/** PURE. Full-jitter exponential backoff: uniform in [0, min(maxDelayMs, baseDelayMs·2^attempt)). */
+export function backoffDelayMs(attempt, { baseDelayMs = 400, maxDelayMs = 8_000, random = Math.random } = {}) {
+  const ceiling = Math.min(maxDelayMs, baseDelayMs * 2 ** Math.max(0, attempt))
+  return Math.floor(random() * ceiling)
+}
+
+/** PURE. The retry class of a response, or null when it is not a transient failure at all. */
+export function responseRetryClass(status, contentType) {
+  if (status === 429 || status === 503) return 'refused'
+  if (status === 403 && !String(contentType ?? '').includes('application/json')) return 'refused'
+  if (status >= 500) return 'server'
+  return null
+}
+
+/** PURE. Did this error happen before a connection existed — i.e. nothing reached the server? */
+export function isConnectError(err) {
+  const codes = [err?.code, err?.cause?.code, ...(Array.isArray(err?.cause?.errors) ? err.cause.errors.map((x) => x?.code) : [])]
+  return codes.some((c) => typeof c === 'string' && CONNECT_ERROR_CODES.has(c))
+}
+
+/**
+ * PURE. May a failure of this class be retried? `timeouts` counts the timeouts seen so far in this call,
+ * INCLUDING the one being decided — so the first timeout may be retried once and the second may not.
+ */
+export function mayRetry(klass, { idempotent, retryOnTimeout = true, requireRetryAfter = false, retryAfterMs = null, timeouts = 0 }) {
+  switch (klass) {
+    case 'refused': return requireRetryAfter ? retryAfterMs !== null : true
+    case 'connect': return true
+    case 'server':
+    case 'network': return Boolean(idempotent)
+    case 'timeout': return Boolean(idempotent) && retryOnTimeout && timeouts <= 1
+    default: return false
+  }
+}
+
+/**
+ * fetch with the D9 retry policy. 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 (third argument, all optional):
+ *   retries            max retries after the first attempt (default 2)
+ *   idempotent         allow retrying `server`/`network` failures and one timeout (default: GET/HEAD)
+ *   retryOnTimeout     set false to never retry a timeout, even when idempotent
+ *   requireRetryAfter  retry `refused` responses only when they carry a Retry-After
+ *   budgetMs           overall wall-clock cap (default: first attempt's timeout + DEFAULT_RETRY_BUDGET_MS)
+ *   baseDelayMs, maxDelayMs   full-jitter backoff parameters
+ *   sleep, random, now        injectable for tests
+ */
+export async function fetchCortex(url, opts = {}, policy = {}) {
+  const {
+    retries = 2, baseDelayMs = 400, maxDelayMs = 8_000,
+    retryOnTimeout = true, requireRetryAfter = false,
+    sleep: sleepFn = sleep, random = Math.random, now = Date.now,
+  } = policy
   const { timeoutMs: optTimeout, signal: callerSignal, ...rest } = opts
   const baseHeaders = { ...(rest.headers ?? {}), 'x-cortex-client': CLIENT_ID }
   const fetchOpts = SESSION_KEY
     ? { ...rest, headers: { ...baseHeaders, 'x-cortex-session-key': SESSION_KEY } }
     : { ...rest, headers: baseHeaders }
+  const method = String(rest.method ?? 'GET').toUpperCase()
+  const idempotent = policy.idempotent ?? (method === 'GET' || method === 'HEAD')
   const timeoutMs = optTimeout ?? (Number(process.env.CORTEX_HTTP_TIMEOUT_MS) || 15_000)
-  let lastErr
-  for (let attempt = 0; attempt <= retries; attempt++) {
+  const budgetMs = policy.budgetMs ?? timeoutMs + DEFAULT_RETRY_BUDGET_MS
+  const minAttemptMs = Math.min(1_000, timeoutMs)
+  const startedAt = now()
+  let lastErr = null
+  let lastKlass = null
+  let lastAttemptMs = timeoutMs
+  let timeouts = 0
+
+  for (let attempt = 0; ; attempt++) {
+    const remaining = budgetMs - (now() - startedAt)
+    // Fresh timeout signal per attempt, clipped to the budget; composed with any caller signal.
+    lastAttemptMs = Math.max(1, Math.min(timeoutMs, remaining))
+    const timeoutSignal = AbortSignal.timeout(lastAttemptMs)
+    const signal = callerSignal ? AbortSignal.any([callerSignal, timeoutSignal]) : timeoutSignal
+    let res = null
+    let klass
+    let retryAfterMs = null
     try {
-      // Fresh timeout signal per attempt; compose with any caller-supplied signal.
-      const timeoutSignal = AbortSignal.timeout(timeoutMs)
-      const signal = callerSignal ? AbortSignal.any([callerSignal, timeoutSignal]) : timeoutSignal
-      const res = await fetch(url, { ...fetchOpts, signal })
-      const ct = res.headers.get('content-type') ?? ''
-      const transient =
-        res.status === 429 ||
-        res.status >= 500 ||
-        (res.status === 403 && !ct.includes('application/json')) // infra block, not app authz
-      if (transient && attempt < retries) {
-        await sleep(baseDelayMs * 2 ** attempt)
-        continue
-      }
-      return res
+      res = await fetch(url, { ...fetchOpts, signal })
+      klass = responseRetryClass(res.status, res.headers.get('content-type'))
+      if (!klass) return res
+      retryAfterMs = parseRetryAfter(res.headers.get('retry-after'), now())
     } catch (e) {
+      if (callerSignal?.aborted) throw e // the caller cancelled: never retry that
       lastErr = e
-      if (attempt < retries) { await sleep(baseDelayMs * 2 ** attempt); continue }
+      klass = timeoutSignal.aborted ? 'timeout' : isConnectError(e) ? 'connect' : 'network'
+      if (klass === 'timeout') timeouts += 1
+    }
+    lastKlass = klass
+
+    let delay = null
+    if (attempt < retries && mayRetry(klass, { idempotent, retryOnTimeout, requireRetryAfter, retryAfterMs, timeouts })) {
+      if (retryAfterMs !== null) {
+        delay = retryAfterMs > RETRY_AFTER_CAP_MS ? null : retryAfterMs + Math.floor(random() * RETRY_AFTER_SPREAD_MS)
+      } else {
+        delay = backoffDelayMs(attempt, { baseDelayMs, maxDelayMs, random })
+      }
+      if (delay !== null && now() - startedAt + delay + minAttemptMs > budgetMs) delay = null
+    }
+
+    if (delay === null) {
+      if (res) return res
+      const why = lastKlass === 'timeout'
+        ? `timed out after ${lastAttemptMs} ms (${lastErr?.message ?? 'timeout'})`
+        : (lastErr?.message ?? 'network error')
+      // `retryClass` says whether the request could have reached the server ('connect' = it did not),
+      // which the capture queue needs in order to decide whether a later replay is safe.
+      throw Object.assign(new Error(
+        `Could not reach Agnoclast at ${url} — ${why}. ` +
+        `Check your connection (and CORTEX_URL if you set it).`,
+      ), { retryClass: lastKlass })
     }
+    // Release the discarded response's socket before waiting.
+    if (res) { try { await res.body?.cancel() } catch { /* already consumed or closed */ } }
+    await sleepFn(delay)
   }
-  throw new Error(
-    `Could not reach Agnoclast at ${url} — ${lastErr?.message ?? 'network error'}. ` +
-    `Check your connection (and CORTEX_URL if you set it).`,
-  )
 }
 
 // Live health probe: hit /api/mcp-context with the token and classify the result.

package/lib/doctor.mjs

@@ -4,6 +4,12 @@ import { join } from 'path'
 import { checkToken, checkSkills, resolveBase, resolveTokenSource } from './diagnose.mjs'
 import { renderRenameNotice } from './rename_notice.mjs'
 import { detectSurface, renderSurface } from './surface.mjs'
+import { queueDir, queueStatus, renderQueueNotice } from './capture_queue.mjs'
+
+/** The capture-queue lines, or [] — local, synchronous, and never throws (a status line must not break). */
+function queueNotice(dir) {
+  try { return renderQueueNotice(queueStatus(dir ?? queueDir())) } catch { return [] }
+}
 
 // `npx @theronap/cortex-mcp doctor` — a live, one-command health check.
 //
@@ -26,18 +32,27 @@ export const resolveToken = resolveTokenSource
 // The surface line is printed from a `finally` so no branch below can skip it. That includes the
 // early returns and the "connected" line, which a person in Claude's Home tab also sees: the token is
 // fine there, and the app they are looking at still cannot use it. See surface.mjs.
-export async function runStatus() {
+//
+// The capture-queue lines (capture_queue.mjs) print from the same `finally`, for the same reason: a
+// session this machine could not capture must be reported whether or not the network check below
+// 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).
+export async function runStatus(opts = {}) {
   const out = (m) => process.stdout.write(m + '\n')
+  const queueLines = queueNotice(opts.queueDir)
   try {
-    await statusLine(out)
+    await statusLine(out, { capturesStuck: queueLines.length > 0 })
   } finally {
+    for (const line of queueLines) out(line)
     const surface = renderSurface(detectSurface(process.env), 'status')
     if (surface) out(surface)
   }
   return 0
 }
 
-async function statusLine(out) {
+async function statusLine(out, { capturesStuck = false } = {}) {
   const base = resolveBase(process.env.CORTEX_URL)
   const { token } = resolveToken()
   if (!token) {
@@ -58,7 +73,12 @@ async function statusLine(out) {
         return
       }
       const n = typeof r.projectCount === 'number' ? ` · ${r.projectCount} project${r.projectCount === 1 ? '' : 's'} visible` : ''
-      out(`Agnoclast: connected — sessions on this machine are captured to your org${n}.`)
+      // Same rule as captureNotice above, applied locally: with sessions stuck in the capture queue,
+      // "sessions on this machine are captured" is false for exactly those sessions. The token is
+      // still fine, so say that — and let the ⚠ lines printed after this one say the rest.
+      out(capturesStuck
+        ? `Agnoclast: connected${n}.`
+        : `Agnoclast: connected — sessions on this machine are captured to your org${n}.`)
       // TEMPORARY (ADR-0033 T7) — delete with lib/rename_notice.mjs a release after C2.
       // This one FOLLOWS the happy line rather than replacing it, unlike captureNotice above. The
       // rule there exists because captureNotice CONTRADICTS the reassurance ("connected" was true
@@ -97,6 +117,14 @@ async function doctorChecks(out) {
   const { token, source } = resolveToken()
   out(`  token source: ${source ?? 'NONE FOUND'}`)
   out(`  endpoint:     ${base}`)
+  // Local: captures on this machine that have not landed yet (capture_queue.mjs). Informational — it
+  // does not change the verdict below, which is about whether each surface ANSWERS — but it is printed
+  // before that verdict so a PASS can never sit alone above sessions that were not captured.
+  const q = (() => { try { return queueStatus(queueDir()) } catch { return null } })()
+  if (q) {
+    out(`  capture queue: ${q.pending ? `${q.pending} capture${q.pending === 1 ? '' : 's'} waiting on this machine (~/.cortex/capture-queue)` : 'empty'}`)
+    for (const line of renderQueueNotice(q)) out(`    ${line.replace(/^Agnoclast: /, '')}`)
+  }
   out('')
 
   const r = await checkToken(token, base)

package/lib/edge_extract.mjs

@@ -7,8 +7,8 @@ import { homedir } from 'os'
 // Without it, N concurrent Claude sessions all fire their Stop hook at once → N simultaneous headless
 // `claude --print` calls that contend on the same subscription-OAuth refresh and can deadlock (the
 // "prompts hang forever" incident, 2026-07-08). If the lock is already held by a live, recent holder,
-// the caller skips extraction and ships the transcript tail instead (the server summarizes async) —
-// no session is dropped, just summarized server-side that turn. A stale lock (older than the summary
+// the caller skips extraction and QUEUES the turn on this machine (capture_queue.mjs; D8 — nothing is
+// sent) — no session is dropped, just summarized by a later run. A stale lock (older than the summary
 // timeout + grace, or whose PID is dead) is reclaimed.
 const LOCK_PATH = join(homedir(), '.cortex', 'summarize.lock')
 
@@ -16,8 +16,8 @@ const LOCK_PATH = join(homedir(), '.cortex', 'summarize.lock')
 // timed 2026-09-10 on two real transcripts: 56, 68, 77, 86, 93, 102s — and one run that exceeded 150s
 // and was killed. The old 45s default was below nearly all of them; a first raise to 150s still sat
 // inside the tail. A killed call returns null, which skips EVERYTHING downstream: the summary, people,
-// entities, ADR-0055's `pages`, and ADR-0059's `obligations`. The fallback then ships the transcript
-// tail and the server writes a summary, so the record lands and nothing looks broken — a green outcome
+// entities, ADR-0055's `pages`, and ADR-0059's `obligations`. Until D8 the fallback then shipped the
+// transcript tail and the server wrote a summary, so the record landed and nothing looked broken — a green outcome
 // over a dead mechanism, which is this file's own recorded failure family (see edgeSkip's header).
 //
 // ⚠ LATENCY TRACKS OUTPUT, NOT INPUT — measured, and it is why length is a poor predictor. A plain
@@ -29,9 +29,9 @@ const LOCK_PATH = join(homedir(), '.cortex', 'summarize.lock')
 //
 // ⚠ RAISING IT COSTS THE USER NOTHING. capture.mjs re-invokes itself as a fully DETACHED child
 // (`detached: true`, `child.unref()`), so nobody waits on this call. The one real cost is the
-// single-flight lock held longer, during which a concurrent session ships its tail instead — the
-// existing graceful fallback. Too short loses the whole extraction; too long only degrades a neighbour
-// to the fallback it already has. The stale-lock reclaim scales off this same value.
+// single-flight lock held longer, during which a concurrent session's turn waits in the local queue
+// instead. Too short loses the whole extraction; too long only delays a neighbour to a later run. The
+// stale-lock reclaim scales off this same value.
 //
 // ⚠ Its effect on capture_route (1 attachment in its first two days) is a candidate, NOT proven.
 function summaryTimeoutMs() {
@@ -39,6 +39,18 @@ function summaryTimeoutMs() {
   return Number.isFinite(n) && n > 0 ? n : 300_000
 }
 
+/**
+ * PURE. How long THIS call may spend, which is the configured ceiling unless the caller has less time
+ * than that. The queue drain does: it holds a wall-clock budget and must not be blocked for 300 s by a
+ * spawnSync inside it (the whole reason this parameter exists). A caller passing 0 or less is saying
+ * "no time left" — `extractSession` then skips without spawning anything.
+ */
+export function effectiveSummaryTimeoutMs(opts = {}) {
+  const ceiling = summaryTimeoutMs()
+  const asked = Number(opts?.timeoutMs)
+  return Number.isFinite(asked) ? Math.min(ceiling, asked) : ceiling
+}
+
 // Try to acquire the lock. Returns true if acquired (caller must call releaseSummaryLock in a finally),
 // false if another live holder has it. O_CREAT|O_EXCL is the atomic "create only if absent" primitive.
 function acquireSummaryLock(_retried = false) {
@@ -50,7 +62,7 @@ function acquireSummaryLock(_retried = false) {
   } catch (e) {
     if (e && e.code === 'EEXIST') {
       // Someone holds it — reclaim only if it's stale (older than timeout + 15s grace, or PID dead).
-      if (_retried) return false // one reclaim attempt only; a live race means "ship the tail"
+      if (_retried) return false // one reclaim attempt only; a live race means "queue this turn"
       try {
         const age = Date.now() - statSync(LOCK_PATH).mtimeMs
         const holderDead = !pidAlive(readFileSync(LOCK_PATH, 'utf8').trim())
@@ -58,7 +70,7 @@ function acquireSummaryLock(_retried = false) {
           try { unlinkSync(LOCK_PATH) } catch { /* raced with another reclaimer */ }
           return acquireSummaryLock(true)
         }
-      } catch { /* unreadable lock — treat as held; ship the tail this turn */ }
+      } catch { /* unreadable lock — treat as held; queue this turn */ }
       return false
     }
     // Any other error (e.g. ~/.cortex missing): don't block extraction, just run without the lock.
@@ -91,7 +103,8 @@ function releaseSummaryLock() {
 // CONTRACT: people[] / namedEntities[] shapes MUST stay compatible with the server validators
 // web/lib/engine/extract_people.ts (parsePeople) + extract_entities.ts (parseEntities). The prompt
 // fragments are copied from there; the SERVER validator is the enforced source of truth — the edge
-// is never trusted. Returns null on any failure → caller falls back to shipping the transcript tail.
+// is never trusted. Returns null on any failure → the caller queues the turn locally and retries later
+// (D8: the transcript is never sent to be summarized server-side).
 
 export function edgeSafeEnv(base = process.env, extra = {}) {
   const env = {}
@@ -427,10 +440,14 @@ const scheduledTaskFragment = (name) =>
   'INCLUDING one mentioned only in passing at the very end of an otherwise routine report. ' +
   'One genuine finding outweighs an otherwise unremarkable run; summarize the FINDING, not the run.'
 
-export function extractSession(transcript) {
+export function extractSession(transcript, opts = {}) {
   LAST_SKIP = null
   const raw = (transcript ?? '').trim()
   if (!raw || process.env.CORTEX_SUMMARIZE_DISABLED) return null
+  // The caller's remaining time, if it has less than the configured ceiling. Checked BEFORE the lock so
+  // a caller with no time left neither spawns anything nor takes the machine-wide summarizer lock.
+  const timeoutMs = effectiveSummaryTimeoutMs(opts)
+  if (timeoutMs <= 0) return edgeSkip('timeout', 'the caller had no time left to summarize; left for a later run')
   const task = scheduledTaskName(raw)
   // Strip instructions only for scheduled runs; a human transcript has no such blocks and is passed
   // through untouched, so this cannot change how ordinary sessions are summarized.
@@ -466,9 +483,9 @@ export function extractSession(transcript) {
     OBLIGATIONS_FRAGMENT +
     (task ? scheduledTaskFragment(task) : '') +
     '\n\n--- SESSION ---\n' + shown + '\n--- END ---'
-  // Single-flight: if another session already has a summarizer running, skip (caller ships the tail;
-  // server summarizes). Prevents the concurrent-`claude -p` stampede that deadlocks the OAuth refresh.
-  if (!acquireSummaryLock()) return edgeSkip('busy', 'another session is summarizing; the tail ships instead')
+  // Single-flight: if another session already has a summarizer running, skip (the caller queues this
+  // turn locally). Prevents the concurrent-`claude -p` stampede that deadlocks the OAuth refresh.
+  if (!acquireSummaryLock()) return edgeSkip('busy', 'another session is summarizing; this turn waits in the local queue')
   try {
     // ⚠ THE PROMPT GOES ON STDIN, NOT ARGV — AND THE WINDOW BELOW DEPENDS ON IT. A command-line
     // argument has an OS size limit: Linux caps a SINGLE argument at 131,072 bytes (MAX_ARG_STRLEN)
@@ -479,9 +496,9 @@ export function extractSession(transcript) {
     const r = spawnSync(
       'claude',
       ['--print', '--model', process.env.CORTEX_SUMMARY_MODEL ?? 'claude-haiku-4-5'],
-      { input: prompt, env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }), encoding: 'utf8', timeout: summaryTimeoutMs(), maxBuffer: 4 * 1024 * 1024 },
+      { input: prompt, env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }), encoding: 'utf8', timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 },
     )
-    const why = classifyEdgeFailure(r)
+    const why = classifyEdgeFailure(r, timeoutMs)
     if (why) return edgeSkip(why.reason, why.detail)
     const parsed = parseEdgeJson(r.stdout.trim())
     if (!parsed) return edgeSkip('unparseable', 'the model returned output that is not the expected JSON')
@@ -497,9 +514,9 @@ export function extractSession(transcript) {
 
 // ── WHY THE EXTRACTION DID NOT RUN ───────────────────────────────────────────────────────────────
 //
-// Every failure path here returns null, and the caller correctly treats null as "ship the transcript
-// tail and let the server summarize". That fallback is right. What was wrong is that FIVE different
-// failures were indistinguishable, and one of them never fixes itself.
+// Every failure path here returns null. The caller treated null as "ship the transcript tail and let
+// the server summarize" until D8 (2026-09-11); it now queues the turn locally and retries. Either way,
+// what was wrong is that FIVE different failures were indistinguishable, and one of them never fixes itself.
 //
 // 🔴 THE EVIDENCE. Found 2026-09-08: `claude --print` had been exiting 1 with
 // "Failed to authenticate: OAuth session expired and could not be refreshed" — so edge extraction
@@ -539,7 +556,7 @@ function edgeSkip(reason, detail) {
  * Exported so the failure taxonomy is testable without spawning anything — the auth case in
  * particular could not otherwise be covered, and it is the one that matters most.
  */
-export function classifyEdgeFailure(r) {
+export function classifyEdgeFailure(r, timeoutMs = summaryTimeoutMs()) {
   if (!r) return { reason: 'no-result', detail: 'spawn returned nothing' }
   // spawn itself failed — almost always ENOENT, i.e. `claude` is not on the hook's PATH. A Stop hook
   // runs with a login shell's PATH, which is not always the interactive one.
@@ -552,12 +569,12 @@ export function classifyEdgeFailure(r) {
     // which reads as "the spawn broke" when the truth is "it ran and was too slow". Checking the
     // signal alone missed it, so both are checked; this classifier's own first outing found this.
     if (r.error.code === 'ETIMEDOUT') {
-      return { reason: 'timeout', detail: `exceeded ${summaryTimeoutMs()}ms` }
+      return { reason: 'timeout', detail: `exceeded ${timeoutMs}ms` }
     }
     return { reason: 'spawn-failed', detail: r.error.message }
   }
   // The other shape of the same event: spawnSync killed the child, so status is null and signal set.
-  if (r.signal) return { reason: 'timeout', detail: `killed by ${r.signal} after ${summaryTimeoutMs()}ms` }
+  if (r.signal) return { reason: 'timeout', detail: `killed by ${r.signal} after ${timeoutMs}ms` }
 
   // 🔴 EVERYTHING BELOW APPLIES ONLY TO A FAILED CALL. Exit 0 means the model answered; its answer
   // is CONTENT, not a status report, and must never be scanned for failure keywords.
@@ -582,8 +599,8 @@ export function classifyEdgeFailure(r) {
       reason: 'auth-expired',
       detail: 'the subscription login for headless `claude --print` is dead. Run `claude setup-token`, '
         + 'then set CLAUDE_CODE_OAUTH_TOKEN in ~/.claude/settings.json (env). '
-        + 'Until then EVERY session ships its transcript tail to the server instead of a local digest, '
-        + 'and no page proposals are made.',
+        + 'Until then EVERY session on this machine goes uncaptured: each one waits in the local queue '
+        + '(~/.cortex/capture-queue) and is reported at session start. Nothing is sent to be summarized elsewhere.',
     }
   }
   return { reason: 'exit', detail: `claude exited ${r.status}: ${firstLine(out)}` }

package/lib/hydrate.mjs

@@ -15,11 +15,49 @@ import { writePresence } from './statusline.mjs'
 // hook can't cheaply judge a semantic topic change.
 //
 // It MUST be synchronous: the value is being in-context before the reply, so it cannot be detached like
-// capture. That cost is bounded — once per session, an 8s timeout, and FAIL-OPEN: any miss injects
+// capture. That cost is bounded — once per session, an 8s timeout inside a 10s total budget (no retry
+// of a timeout — see HYDRATE_RETRY_POLICY), and FAIL-OPEN: any miss injects
 // nothing and never holds up the user's first message. Always exits 0; hydration must never break a turn.
 
 const HYDRATE_TIMEOUT_MS = 8_000
 const MAX_ATTEMPTS = 2 // give up after N failed tries so a dead endpoint isn't re-hit every turn
+
+// How long the user's first message can be held, in total, retries included. The first attempt gets
+// its full 8 s; the remaining 2 s only ever admits a FAST retry (see the policy below).
+export const HYDRATE_BUDGET_MS = 10_000
+
+// D9. This call used to be `{ retries: 1 }` with the old any-429/5xx-or-timeout loop, so a session-context
+// request that timed out BECAUSE THE SERVER WAS SLOW was immediately sent again — doubling the load on the
+// thing that was already too slow to answer, while the person's first prompt waited up to ~16 s for it.
+// Now it retries only where a retry cannot add load to a struggling server:
+//   · a connection that was never made (refused / DNS) — nothing reached the server;
+//   · a 429/503 that says WHEN (Retry-After), and only if that fits the budget.
+// Never a timeout, never a 5xx, never a 429 without a Retry-After. Missing context is fail-open anyway:
+// the turn proceeds without it and `attempts` lets one LATER turn try again.
+export const HYDRATE_RETRY_POLICY = Object.freeze({
+  retries: 1,
+  idempotent: false,        // no retry on 5xx or a broken connection mid-flight
+  retryOnTimeout: false,    // never re-ask a server that was too slow to answer
+  requireRetryAfter: true,  // a 429/503 is retried only when the server says when
+  budgetMs: HYDRATE_BUDGET_MS,
+})
+
+/** The hydration request itself. Exported so the retry policy is testable against a real fetch path. */
+export function fetchSessionContext({ base, token, prompt, timeoutMs = HYDRATE_TIMEOUT_MS, policy = HYDRATE_RETRY_POLICY }) {
+  return fetchCortex(
+    `${base}/api/session-context`,
+    {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      // Redact credential-shaped strings before the prompt leaves the machine (a pasted key must never
+      // be transmitted, same discipline as capture).
+      body: JSON.stringify({ question: redactSecrets(prompt) }),
+      timeoutMs,
+    },
+    policy,
+  )
+}
+
 const MIN_SUBSTANTIVE_CHARS = 15
 // Bare greetings/affirmations are not a real opening query — skip WITHOUT marking done, so the first
 // substantive prompt still hydrates. Anchored to the whole string so "go" skips but "go build X" does not.
@@ -126,18 +164,7 @@ export async function runHydrate() {
 
   let res
   try {
-    res = await fetchCortex(
-      `${base}/api/session-context`,
-      {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
-        // Redact credential-shaped strings before the prompt leaves the machine (a pasted key must never
-        // be transmitted, same discipline as capture).
-        body: JSON.stringify({ question: redactSecrets(prompt) }),
-        timeoutMs: HYDRATE_TIMEOUT_MS,
-      },
-      { retries: 1 },
-    )
+    res = await fetchSessionContext({ base, token, prompt })
   } catch (e) {
     process.stderr.write(`cortex: hydrate skipped — ${e?.message ?? String(e)}\n`)
     bumpAttempt()

package/lib/propose_obligation.mjs

@@ -0,0 +1,99 @@
+// ADR-0059 §5.6 — THE VERB A READING AGENT WAS MISSING.
+//
+// 🔴 WHY (Theron, 2026-09-11: *"Why isn't the agent just surfacing those as obligations?"*). Two emails he
+// had been sent asked him for something — a 15-minute call "this week", and a mentee meeting to log that
+// week. A session read both, filed them onto pages as knowledge, and proposed NOTHING. The asks evaporated.
+//
+// Nothing was broken. The proposal path — evidence + `state='proposed'` + the reviewer — existed and
+// worked; it was reachable only by the detached capture worker, over HTTP with a bearer token. The one
+// obligation verb an agent had was `track_obligation`, which records something YOU OWE: no evidence, no
+// proposed state. So a reading agent's only options were to assert a commitment the person never made
+// (ADR-0059 §3's defect: machine-proposed and user-created become indistinguishable) or to write a script.
+// **A capability an agent can only reach by writing a script is a capability it does not have.**
+//
+// So this is the same write the extractor does, as one tool call: the record, what is owed, and the
+// sentence that says so. It lands as a PROPOSAL the person confirms or dismisses — never as a commitment.
+//
+// ⚠ AND IT IS DELIBERATELY NOT A SUBSTITUTE FOR EXTRACTION. This repo has measured what asking agents to
+// volunteer yields: `route_record` 10.9% (ADR-0051), `capture_route` one attachment in ten sessions
+// (ADR-0055). Voluntary noticing supplements deterministic extraction; it cannot replace it.
+
+/** The evidence floor, matching the edge's verbatim gate (`verbatimIn`): a three-word fragment is not a
+ *  quote, and it is exactly what a hurried agent would pass. */
+export const MIN_EVIDENCE_CHARS = 16
+const PARTIES = new Set(['self', 'other', 'none'])
+const norm = (s) => String(s ?? '').replace(/\s+/g, ' ').trim()
+
+/**
+ * PURE. Validate one proposal locally and return `{ candidate }` or `{ error }`.
+ *
+ * The server drops a malformed candidate silently (it answers `malformed: 1` and writes nothing), which
+ * for an interactive caller is the wrong shape of failure: the agent believes it surfaced the ask. So the
+ * same rules are enforced here, loudly, with the reason.
+ *
+ * A `due_phrase` that is NOT inside the evidence is dropped rather than refused, and the caller is told:
+ * that is the edge's own rule (a phrase from some other sentence must not decide the date), and the
+ * candidate is still worth proposing without it.
+ */
+export function buildProposal({ subject, evidence, due_phrase, due_at, obligated_party = 'self' } = {}) {
+  const s = norm(subject)
+  const e = norm(evidence)
+  if (!s) return { error: 'subject is required — what must be done, in one short phrase' }
+  if (!e) return { error: 'evidence is required — the VERBATIM sentence from the record that asks for it' }
+  if (e.length < MIN_EVIDENCE_CHARS) {
+    return { error: `evidence is too short to be a quote (${e.length} chars, need ${MIN_EVIDENCE_CHARS}) — pass the whole sentence` }
+  }
+  const party = norm(obligated_party) || 'self'
+  if (!PARTIES.has(party)) return { error: `obligated_party must be self, other or none (got "${party}")` }
+  const phrase = norm(due_phrase)
+  const phraseInside = phrase ? norm(e).toLowerCase().includes(phrase.toLowerCase()) : false
+  return {
+    candidate: {
+      subject: s.slice(0, 200),
+      due_at: norm(due_at) || null,
+      ...(phraseInside ? { due_phrase: phrase.slice(0, 120) } : {}),
+      evidence: e.slice(0, 500),
+      obligated_party: party,
+    },
+    ...(phrase && !phraseInside
+      ? { note: `the words "${phrase}" are not in the evidence sentence, so they were dropped — the date comes from due_at or from the quote itself` }
+      : {}),
+  }
+}
+
+/** PURE. What the caller reads back. Says it is a PROPOSAL, and says so when it landed with no date. */
+export function renderProposal(body, candidate, note) {
+  const b = body ?? {}
+  const lines = []
+  const what = candidate?.subject ?? '(unknown)'
+  if (b.refreshed) lines.push(`Updated the existing proposal for that sentence: "${what}"`)
+  else if (b.proposed) lines.push(`Proposed (NOT yet something you owe): "${what}"`)
+  else lines.push(`Nothing was written for "${what}" — the record already carries a row for that sentence that you have acted on.`)
+  if (b.undated) lines.push('⚠ It has NO date. Nothing will nudge you about it until it has one.')
+  if (b.fromQuote) lines.push('Its date was read out of the quote itself.')
+  if (note) lines.push(`⚠ ${note}`)
+  if (b.proposed || b.refreshed) {
+    lines.push('See it with my_obligations. Confirm or dismiss it with resolve_obligation — a proposal you never answer stays a proposal.')
+  }
+  return lines.join('\n')
+}
+
+/**
+ * PURE. The one line a reading tool appends TO ITS OUTPUT, so an agent that just read an ask knows what to
+ * do with it.
+ *
+ * ⚠ IT LIVES IN THE OUTPUT, NOT IN THE TOOL DESCRIPTION, and that is not a style choice. `source-invariants`
+ * caps a tool description at 1,950 characters because a client silently truncates the tail — and `my_day`
+ * was already AT the ceiling, so appending there would have pushed the instruction into the invisible part
+ * (measured 2026-09-11: my_day 2,195 chars, 245 over). The output is also the better place on its own
+ * merits: it arrives with the content in view, at the moment there is something to notice, rather than in a
+ * tool catalogue read once at startup.
+ */
+export const NOTICE_ASKS =
+  'If something here ASKS THIS PERSON FOR SOMETHING — a reply, a call, a form, a deadline — propose it with ' +
+  '`propose_obligation` and the sentence that says so. Reading it and filing it is not surfacing it.'
+
+/** PURE. Append the notice to what a reading tool returns. */
+export function withAskNotice(text) {
+  return `${String(text ?? '')}\n\n${NOTICE_ASKS}`
+}