@theronap/agnoclast-mcp 0.9.148 → 0.9.150

package/lib/capture.mjs

@@ -4,10 +4,14 @@ import { homedir } from 'os'
 import { resolve, dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { createHash } from 'crypto'
-import { fetchCortex, classify, resolveBase, resolveTokenSource } from './diagnose.mjs'
-import { extractSession } from './edge_extract.mjs'
+import { fetchCortex, resolveBase, resolveTokenSource } from './diagnose.mjs'
+import { extractSession, lastEdgeSkip } from './edge_extract.mjs'
 import { extractTyped } from './extract_typed.mjs'
 import { redactSecrets } from './redact.mjs'
+import {
+  queueDir, entryKey, enqueueCapture, removeIfNotNewer, recordDropped, isFlagged, postIngest, drainCaptureQueue,
+  makeGen, cmpGen, genPayload, withLease, readPostedGen, raisePostedGen, LEASE_WAIT_MS,
+} from './capture_queue.mjs'
 
 // Fetch the node-type registry (global + this org's custom types) — the catalog the typed extractor
 // produces against. Best-effort: null on any failure (typed extraction is then skipped, never blocks capture).
@@ -35,8 +39,8 @@ export function projectFrom(cwd) {
   return base ?? 'general'
 }
 
-// Claude Code Stop hook → POSTs a session digest to Agnoclast cloud, which
-// summarizes server-side and upserts ONE record per session. Node-native
+// Claude Code Stop hook → summarizes the session LOCALLY and POSTs only the digest to Agnoclast cloud,
+// which upserts ONE record per session; what cannot land waits in ~/.cortex/capture-queue. Node-native
 // SHR-01/T6 — parse a git remote URL into GitHub 'owner/name', or null.
 //
 // Handles the four remote forms git emits: scp-like ssh (git@github.com:o/n.git), ssh://, https://,
@@ -190,10 +194,10 @@ export function transcriptReadable(path) {
   try { accessSync(path, constants.R_OK); return true } catch { return false }
 }
 
-function transcriptTail(path) {
-  let raw = ''
-  try { raw = readFileSync(path, 'utf8') } catch { return '' }
-  const jsonLines = raw.split('\n').filter(Boolean)
+// Takes the transcript's RAW text (read once by the caller, whose character count is also this
+// capture's generation — see captureTurn), not a path.
+function transcriptTail(raw) {
+  const jsonLines = String(raw ?? '').split('\n').filter(Boolean)
   const textOf = (line) => {
     try {
       const obj = JSON.parse(line)
@@ -328,12 +332,115 @@ async function captureWork(stdinRaw) {
     })
   } catch { /* a parked retry must never cost a session its capture */ }
 
+  const dir = queueDir()
+  const signals = await captureTurn(hook, {
+    base, token, dir,
+    log: (line) => process.stderr.write(`cortex: ${stamp} ${sid} ${line}\n`),
+  })
+
+  // Retry earlier captures that did not land (capture_queue.mjs). ONLY as the detached worker, or when
+  // a person forced sync mode to watch it: the in-band fallback (spawn failed) holds the user's input
+  // box, and a queued `claude -p` retry can take minutes. The next detached run will drain instead.
+  if (process.env.CORTEX_CAPTURE_DETACHED || process.env.CORTEX_CAPTURE_SYNC) {
+    const qlog = (line) => process.stderr.write(`cortex: ${stamp} queue ${line}\n`)
+    await drainCaptureQueue({
+      dir,
+      log: qlog,
+      post: (body, _entry, opts) => postIngest({ base, token, body, repo: body?.project ?? 'general', budgetMs: opts?.budgetMs }),
+      summarize: (text, opts) => summarizeTurn(text, { timeoutMs: opts?.timeoutMs }),
+      buildBody: (common, extracted, text) => buildIngestBody(common, extracted, text, { log: qlog }),
+      skipKey: signals.key,
+      serverHealthy: signals.serverHealthy,
+      summarizerHealthy: signals.summarizerHealthy,
+      allowSummarize: true,
+    })
+  }
+}
+
+// Why the summarizer returned nothing when edge_extract recorded no reason — only one way that happens.
+const noReason = () => (process.env.CORTEX_SUMMARIZE_DISABLED
+  ? { reason: 'disabled', detail: 'CORTEX_SUMMARIZE_DISABLED is set, so sessions are not summarized on this machine' }
+  : { reason: 'unknown', detail: 'the summarizer returned nothing and recorded no reason' })
+
+/**
+ * Summarize one transcript tail locally. → { extracted } | { noop: true } | { unavailable: {reason, detail} }.
+ * Shared by the live capture and the queue drain so both read the same outcome the same way.
+ */
+export function summarizeTurn(transcript, { extract = extractSession, lastSkip = lastEdgeSkip, timeoutMs } = {}) {
+  // `timeoutMs` is the CALLER's remaining time (the queue drain's budget). Without it the summarizer
+  // uses its own 300 s ceiling, which is what let a drain block for five times its stated cap.
+  const extracted = extract(transcript, timeoutMs === undefined ? undefined : { timeoutMs })
+  if (!extracted) return { unavailable: lastSkip() ?? noReason() }
+  if (/^NOOP\b/i.test(extracted.summary)) return { noop: true }
+  return { extracted }
+}
+
+/**
+ * The ingest body for a summarized turn — the DERIVED digest only. There is no `transcript` field and
+ * there is no longer any code path that builds one (D8); postIngest strips it as a backstop regardless.
+ */
+export async function buildIngestBody(common, extracted, transcript, { log = () => {} } = {}) {
+  // ADR-0059 §5.3 — review obligation candidates before they leave the machine: drop what nobody owes,
+  // merge a deadline stated twice, reclassify whose it is. Never adds; fails open (obligation_review.mjs).
+  // Only when there are candidates, which most sessions never produce.
+  let obligations = extracted?.obligations ?? []
+  // The quotes the review retired (merged into a later statement, or not owed). The ONLY thing that lets
+  // the server delete an earlier read's proposal; a read that is merely silent about one deletes nothing.
+  let retiredObligations = []
+  if (obligations.length) {
+    const { reviewObligations, describeReview, retiredEvidence } = await import('./obligation_review.mjs')
+    const rev = reviewObligations(obligations, transcript)
+    log(`obligations ${describeReview(obligations.length, rev)}`)
+    retiredObligations = retiredEvidence(obligations, rev)
+    obligations = rev.obligations
+  }
+  // `pages` is the edge's PROPOSAL of where this record belongs (ADR-0055). Free-text names, resolved
+  // against real pages server-side and dropped when they match nothing — the same untrusted-edge
+  // contract people/entities use. Omitted entirely when empty so an older server sees no new field.
+  return {
+    ...common,
+    summary: extracted.summary,
+    people: extracted.people,
+    entities: extracted.namedEntities,
+    ...(extracted.pages?.length ? { pages: extracted.pages } : {}),
+    // ADR-0059. Obligation candidates the extraction found AND verified verbatim against the
+    // transcript it was shown — the server cannot re-check the quote (it never receives the
+    // transcript), so these arrive already filtered. Omitted when empty, same as `pages`.
+    ...(obligations.length ? { obligations } : {}),
+    // ADR-0059 §5.4: quotes the reviewer retired. Omitted when empty, so an older server sees nothing new.
+    ...(retiredObligations.length ? { retiredObligations } : {}),
+  }
+}
+
+/**
+ * Capture ONE turn: summarize locally, post the digest, and queue whatever did not land. Returns the
+ * health signals the queue drain uses. Dependencies are injectable so every branch is testable without
+ * spawning `claude`, touching the network, or writing under the real home directory.
+ *
+ * deps: { base, token, dir, log, fetchImpl?, extract?, lastSkip?, now?, random?, leaseWaitMs? }
+ */
+export async function captureTurn(hook, deps) {
+  const {
+    base, token, dir, log = () => {}, fetchImpl = fetchCortex,
+    now = Date.now, random = Math.random, leaseWaitMs = LEASE_WAIT_MS,
+  } = deps
+  const key = hook.session_id ? entryKey(hook.session_id) : null
+  const signals = { key, summarizerHealthy: null, serverHealthy: null }
+  const capturedAt = now()
+
   const repo = projectFrom(hook.cwd)
-  // Redact credential-shaped strings BEFORE anything leaves the machine — this `transcript`
-  // feeds local edge/typed extraction AND the fallback POST to the org. A secret in a
-  // transcript (pasted key, a tool that read a config file, a token inlined in a hook cmd)
-  // must never be transmitted or stored. See redact.mjs.
-  const transcript = hook.transcript_path ? redactSecrets(transcriptTail(hook.transcript_path)) : ''
+  // Read the transcript ONCE: its character count is this capture's GENERATION (capture_queue.mjs), and
+  // reading it twice could straddle an append and order this turn against a file it never saw.
+  let raw = ''
+  if (hook.transcript_path) {
+    try { raw = readFileSync(hook.transcript_path, 'utf8') } catch { raw = '' }
+  }
+  const gen = makeGen(raw.length, capturedAt)
+  // Redact credential-shaped strings BEFORE anything else touches it. This `transcript` feeds local
+  // edge/typed extraction and, when that is unavailable, the LOCAL queue (mode 0600) — it is never
+  // posted (D8). A secret in a transcript (pasted key, a tool that read a config file, a token inlined
+  // in a hook cmd) must not be stored in plain text either. See redact.mjs.
+  const transcript = raw ? redactSecrets(transcriptTail(raw)) : ''
 
   // A transcript_path that was SUPPLIED but is unreadable means the session ran with transcript writes
   // disabled — `claude --print --no-session-persistence`, or the SDK's `persistSession:false`. Verified
@@ -351,11 +458,11 @@ async function captureWork(stdinRaw) {
   // unreadable for a moment is picked up by the next turn, so a transient miss self-heals; only a
   // genuinely persistence-disabled session is dropped, and that session has no content to capture.
   if (hook.transcript_path && !transcriptReadable(hook.transcript_path)) {
-    process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — transcript_path unreadable (session persistence disabled?)\n`)
-    return
+    log('NOT RECORDED — transcript_path unreadable (session persistence disabled?)')
+    return signals
   }
 
-  if (!transcript && !hook.session_id) { process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — empty session\n`); return }
+  if (!transcript && !hook.session_id) { log('NOT RECORDED — empty session'); return signals }
 
   // T11: digest node refs surfaced to this session (stashed by the MCP server's my_context, keyed by
   // cwd). Forwarded as hydratedFrom so the materializer excludes this session from the digests it
@@ -367,11 +474,6 @@ async function captureWork(stdinRaw) {
     if (Array.isArray(parsed.refs) && Date.now() - (parsed.ts ?? 0) < 12 * 3600 * 1000) hydratedFrom = parsed.refs
   } catch { /* none — guard stays a no-op */ }
 
-  // Extract LOCALLY on the subscription (claude -p): summary + people + non-person entities. The
-  // cloud then receives only the derived digest, never the raw transcript or the metered API
-  // summarizer (which has been the silent point of failure). Fall back to shipping the transcript
-  // tail only if local extraction is unavailable (e.g. `claude` not on PATH) so we never drop a
-  // session. The server re-validates people/entities — the edge is not trusted.
   // SHR-01/T6: the repo identifier is what lets a PEER read this session (see 0096). Omitted entirely
   // when the cwd is not a GitHub worktree — the record still lands, it just stays private (D2).
   const repoFullName = repoFullNameFrom(hook.cwd)
@@ -382,9 +484,7 @@ async function captureWork(stdinRaw) {
   // this raw read is transmitted — only the derived 'owner/name' strings leave the machine.
   let repoFullNames = repoFullName ? [repoFullName] : []
   try {
-    if (hook.transcript_path) {
-      repoFullNames = repoFullNamesFrom(readFileSync(hook.transcript_path, 'utf8'), hook.cwd)
-    }
+    if (raw) repoFullNames = repoFullNamesFrom(raw, hook.cwd)
   } catch { /* best-effort — a session with no derivable repo is private, not broken */ }
 
   const common = {
@@ -392,131 +492,131 @@ async function captureWork(stdinRaw) {
     project: repo,
     sessionId: hook.session_id,
     title: `Worked in ${repo}`,
-    payload: { session_id: hook.session_id, cwd: hook.cwd },
+    // capture_generation travels with the record so a later SERVER change can refuse a capture older
+    // than the one it already holds for this session (noted as a follow-up; no server change here).
+    payload: { session_id: hook.session_id, cwd: hook.cwd, capture_generation: genPayload(gen) },
     captureSource: 'hook', // T8: fallback writer — never clobbers a cortex-log ('skill') record
     ...(repoFullName ? { repoFullName } : {}),      // back-compat: older servers read only this
     ...(repoFullNames.length ? { repoFullNames } : {}),
     ...(hydratedFrom.length ? { hydratedFrom } : {}),
   }
-  const extracted = transcript ? extractSession(transcript) : null
-  if (extracted && /^NOOP\b/i.test(extracted.summary)) { process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — summarizer classified it a no-op session\n`); return }
-  // ADR-0059 §5.3 — review obligation candidates before they leave the machine: drop what nobody owes,
-  // merge a deadline stated twice, reclassify whose it is. Never adds; fails open (obligation_review.mjs).
-  // Only when there are candidates, which most sessions never produce.
-  let obligations = extracted?.obligations ?? []
-  // The quotes the review retired (merged into a later statement, or not owed). The ONLY thing that lets
-  // the server delete an earlier read's proposal; a read that is merely silent about one deletes nothing.
-  let retiredObligations = []
-  if (obligations.length) {
-    const { reviewObligations, describeReview, retiredEvidence } = await import('./obligation_review.mjs')
-    const rev = reviewObligations(obligations, transcript)
-    process.stderr.write(`cortex: ${stamp} ${sid} obligations ${describeReview(obligations.length, rev)}\n`)
-    retiredObligations = retiredEvidence(obligations, rev)
-    obligations = rev.obligations
-  }
-  // `pages` is the edge's PROPOSAL of where this record belongs (ADR-0055). Free-text names, resolved
-  // against real pages server-side and dropped when they match nothing — the same untrusted-edge
-  // contract people/entities use. Omitted entirely when empty so an older server sees no new field.
-  const ingestBody = extracted
-    ? {
-        ...common,
-        summary: extracted.summary,
-        people: extracted.people,
-        entities: extracted.namedEntities,
-        ...(extracted.pages?.length ? { pages: extracted.pages } : {}),
-        // ADR-0059. Obligation candidates the extraction found AND verified verbatim against the
-        // transcript it was shown — the server cannot re-check the quote (it never receives the
-        // transcript), so these arrive already filtered. Omitted when empty, same as `pages`.
-        ...(obligations.length ? { obligations } : {}),
-        // ADR-0059 §5.4: quotes the reviewer retired. Omitted when empty, so an older server sees nothing new.
-        ...(retiredObligations.length ? { retiredObligations } : {}),
-      }
-    : { ...common, transcript }
 
-  // Parallel typed extraction (OPT-IN via CORTEX_TYPED): registry-driven typed notes, sent ALONGSIDE the
-  // people/entities above. The server's typedNotes receiver persists them additively. Off by default so it
-  // never adds a 2nd `claude` call / latency until verified; flip to default once typed ≥ the blob path.
-  if (process.env.CORTEX_TYPED && transcript) {
-    try {
-      const registry = await fetchRegistry(base, token)
-      if (registry?.length) {
-        const typed = extractTyped(transcript, registry)
-        if (typed?.notes?.length) ingestBody.typedNotes = typed.notes
+  // Extract LOCALLY on the person's own subscription (claude -p): summary + people + entities + page
+  // proposals + obligations. The cloud receives only that derived digest, and re-validates
+  // people/entities — the edge is not trusted.
+  //
+  // 🔴 D8 (eng review 2026-09-11): THERE IS NO SERVER FALLBACK ANY MORE. When local extraction was
+  // unavailable this used to post `{ ...common, transcript }` and the server summarized the raw tail
+  // with Agnoclast's own Anthropic key — so "the transcript never leaves your machine" was false exactly
+  // when the person's AI was broken, which is when nobody was looking. Now the turn is QUEUED ON THIS
+  // MACHINE (capture_queue.mjs), summarization is retried by later runs, and after FLAG_AFTER_ATTEMPTS
+  // failures the next session start says so. Nothing is dropped and nothing is sent.
+  // Summarizing and body-building both run OUTSIDE the session lease taken below: each can spawn
+  // `claude` and take minutes, and a lease held that long would serialize whole sessions.
+  let ingestBody
+  let unavailable = null
+  if (transcript) {
+    const s = summarizeTurn(transcript, { extract: deps.extract, lastSkip: deps.lastSkip })
+    if (s.unavailable) {
+      unavailable = s.unavailable
+      // A BUSY lock (another session summarizing) resolves itself and says nothing about this machine's
+      // summarizer, so it neither counts toward the flag nor marks the summarizer unhealthy.
+      signals.summarizerHealthy = s.unavailable.reason === 'busy' ? null : false
+    } else {
+      signals.summarizerHealthy = true
+      if (s.noop) { log('NOT RECORDED — summarizer classified it a no-op session'); return signals }
+      ingestBody = await buildIngestBody(common, s.extracted, transcript, { log })
+
+      // Parallel typed extraction (OPT-IN via CORTEX_TYPED): registry-driven typed notes, sent ALONGSIDE the
+      // people/entities above. The server's typedNotes receiver persists them additively. Off by default so it
+      // never adds a 2nd `claude` call / latency until verified; flip to default once typed ≥ the blob path.
+      if (process.env.CORTEX_TYPED) {
+        try {
+          const registry = await fetchRegistry(base, token)
+          if (registry?.length) {
+            const typed = extractTyped(transcript, registry)
+            if (typed?.notes?.length) ingestBody.typedNotes = typed.notes
+          }
+        } catch { /* best-effort — never block capture */ }
       }
-    } catch { /* best-effort — never block capture */ }
+    }
+  } else {
+    // A readable transcript whose tail holds no prose (e.g. the last 60 lines are all tool calls).
+    // Nothing to summarize here — or on the server, where the old `transcript: ''` was falsy too — so
+    // this posts exactly what the server received before D8, minus the empty field.
+    ingestBody = { ...common }
   }
 
-  let res
-  try {
-    // Best-effort background ingest: bound it tight and retry once so a hanging/504-ing server
-    // makes a DETACHED worker self-terminate in ~20s instead of lingering on 3 unbounded attempts.
-    res = await fetchCortex(`${base}/api/ingest`, {
-      method: 'POST',
-      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
-      body: JSON.stringify(ingestBody),
-      timeoutMs: 10_000,
-    }, { retries: 1 })
-  } catch (e) {
-    // Never break a session — just report and move on. This is where a 10s timeout against a slow
-    // /api/ingest lands, and with the old discarded stdio it was completely invisible: the session
-    // simply never appeared and nothing anywhere said why. The endpoint is measurably flaky — a
-    // SessionStart context fetch timed out at 09:54 and again at 11:59 on 2026-08-19 while direct
-    // curls answered in ~150ms, so intermittent timeouts here are a live hypothesis for the
-    // 2026-08-13 collapse, not a theoretical one.
-    process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — ${e.message}\n`)
-    return
-  }
+  // ── this session's critical section ─────────────────────────────────────────────────────────────
+  // Everything left either uploads this session or writes its queue entry, and a sibling worker for the
+  // SAME session may be doing the same thing right now (the Stop hook fires per turn, and extraction
+  // above takes tens of seconds, so overlap is normal). Under the lease, a turn can ask "has a newer
+  // generation already been recorded?" and act on the answer without another poster slipping in between.
+  await withLease(dir, key ?? 'nosession', { waitMs: leaseWaitMs }, async (held) => {
+    if (key && !held) log(`the session lease stayed busy for ${Math.round(leaseWaitMs / 1000)}s — proceeding, so ordering is best-effort for this turn`)
+
+    // A newer turn of this session already recorded means this older one has nothing to add: its
+    // transcript is a prefix of what that turn summarized.
+    const posted = key ? readPostedGen(dir, key) : null
+    if (posted && cmpGen(posted, gen) > 0) {
+      log(`NOT POSTED — a newer capture of this session is already recorded (${posted.chars} chars vs this turn's ${gen.chars})`)
+      return
+    }
 
-  // A 2xx FROM /api/ingest DOES NOT MEAN A RECORD EXISTS. The route answers `ok: true` on at least
-  // six outcomes and only one of them writes a session record:
-  //
-  //   { ok: true, id, inserted, title }            -> RECORDED (the only success)
-  //   { ok: true, staged: true, id, reason }       -> held in staged_records, NOT recorded
-  //   { ok: true, skipped: '<why>' }               -> no-op session / past the ingest horizon
-  //   { ok: false, skipped: '<why>' }              -> connector excluded from this brain
-  //   { ok: true, discarded: true }                -> tombstoned by private intake
-  //   { ok: true, queued: true }                   -> accepted for later work
-  //   { ok: true, via: 'private_intake', intakeItemId } -> an intake unit, not a session record
-  //
-  // The old line read `j.inserted ? 'captured' : 'updated'`, so EVERY one of the six non-writing
-  // outcomes printed "updated" — the word for a successful upsert. Worse, `.json().catch(() => ({}))`
-  // means an unparseable body also yields `{}` and therefore also printed "updated". Verified against
-  // prod 2026-08-19: a capture printed `cortex: updated "general" → general` for a session that has no
-  // row in `records` and none in `staged_records` either.
-  //
-  // NOTE `staged` CARRIES AN `id`, so testing for an id alone is not enough — that id is the
-  // staged_records row, not a record. This is the same false-success defect already fixed once in
-  // log_session ("`inserted` is merely falsy when nothing is recorded — an agent reported a session as
-  // saved when it was not"); the fix was applied there and not here. The server route already knew:
-  // its own comment at the no_route_for_source branch says "`{ok: true}` reads as success to
-  // everything that is not looking closely" and notes 84 rows accumulating behind that wording.
-  if (res.ok || res.status === 200) {
-    const raw = await res.text()
-    let j
-    try { j = JSON.parse(raw) } catch { j = null }
-    if (j && j.id && !j.staged) {
-      process.stderr.write(`cortex: ${stamp} ${sid} ${j.inserted ? 'captured' : 'updated'} "${j.title ?? repo}" → ${repo}\n`)
-    } else if (j && j.staged) {
-      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — staged (${j.reason ?? 'no reason given'}); staged session logs are not drainable by /api/staged/promote\n`)
-    } else if (j && j.skipped) {
-      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — server skipped: ${j.skipped}\n`)
-    } else if (j && j.discarded) {
-      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — discarded by private intake\n`)
-    } else if (j && j.queued) {
-      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — queued for later processing\n`)
-    } else if (j && j.intakeItemId) {
-      process.stderr.write(`cortex: ${stamp} ${sid} not a session record — filed as private intake unit ${j.intakeItemId}\n`)
+    if (unavailable) {
+      const busy = unavailable.reason === 'busy'
+      const entry = enqueueCapture(dir, {
+        sessionId: hook.session_id, kind: 'summarize', gen,
+        reason: unavailable.reason, detail: unavailable.detail,
+        common, transcript, countsAsFailure: !busy,
+      }, { now: now(), random, log })
+      log(entry?.superseded
+        ? `NOT RECORDED YET — local summarization unavailable [${unavailable.reason}]; a newer turn of this session is already queued. The transcript was not sent.`
+        : entry
+          ? `NOT RECORDED YET — local summarization unavailable [${unavailable.reason}]; queued on this machine ` +
+            `(attempt ${entry.attempts}${isFlagged(entry) ? ', FLAGGED' : ''}). The transcript was not sent.`
+          : `NOT RECORDED — local summarization unavailable [${unavailable.reason}] and the turn could not be queued. The transcript was not sent.`)
+      return
+    }
+
+    // A 2xx FROM /api/ingest DOES NOT MEAN A RECORD EXISTS — the full table of what each answer means,
+    // and the prod incident behind it, lives with the classifier in capture_queue.mjs.
+    const out = await postIngest({ base, token, body: ingestBody, repo, fetchImpl })
+    if (out.outcome === 'recorded' || out.outcome === 'final') {
+      signals.serverHealthy = true
+      if (key) {
+        raisePostedGen(dir, key, gen)
+        // Compare-and-delete, NOT a blind remove: a queued entry for this session may be a NEWER turn
+        // that failed while this older one was in flight, and deleting it was how that turn was lost.
+        removeIfNotNewer(dir, key, gen)
+      }
+      log(out.line)
+    } else if (out.outcome === 'retry') {
+      // Never break a session — and never lose it either. A 10s timeout against a slow /api/ingest used to
+      // land here and simply vanish (the endpoint is measurably flaky: a SessionStart context fetch timed
+      // out at 09:54 and 11:59 on 2026-08-19 while direct curls answered in ~150ms). Now it waits locally.
+      // occurredAt pins the record to when the work happened, not to whenever the replay succeeds.
+      signals.serverHealthy = false
+      const entry = enqueueCapture(dir, {
+        sessionId: hook.session_id, kind: 'ingest', gen, reason: out.reason,
+        body: { ...ingestBody, occurredAt: new Date(capturedAt).toISOString() },
+        retryAfterMs: out.retryAfterMs,
+      }, { now: now(), random, log })
+      log(`${out.line}; ${entry?.superseded
+        ? 'a newer turn of this session is already queued'
+        : entry
+          ? `queued on this machine (attempt ${entry.attempts}${isFlagged(entry) ? ', FLAGGED' : ''})`
+          : 'and it could not be queued'}`)
     } else {
-      // Unparseable or unrecognised 2xx. Deliberately NOT reported as success: an unknown shape is
-      // exactly the case the old code laundered into "updated".
-      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — unrecognised 2xx response: ${raw.slice(0, 200)}\n`)
+      // A verdict a replay cannot change. Reported through the drop ledger, so the next session start
+      // says so instead of only this log. An older queued turn of the session is KEPT: it may be valid.
+      recordDropped(dir, { sessionId: hook.session_id ?? null, reason: out.reason }, now())
+      log(`${out.line} — not retryable; reported at the next session start`)
     }
-  } else {
-    const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-    process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — ingest failed: ${d.message}\n`)
-  }
+  })
 
   // The post-capture edge-materialize batch (CORTEX_MATERIALIZE → runMaterialize) was EXCISED
   // 2026-07-02 with the legacy materializer: its server pipeline deleted live-authored pages whose
   // record-hashes drifted. Pages come from live authoring (the `author` tool + /log sweep) now.
+  return signals
 }