@theronap/cortex-mcp 0.9.140 → 0.9.142

package/bin/cortex-mcp.mjs

@@ -152,6 +152,13 @@ if (cmd === 'login') {
   await runCapture()
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'extract-obligations') {
+  // ADR-0059 step 2: the detached worker capture_record launches (job on stdin), or by hand with
+  // --record/--intake <id> --file <path> [--dry-run] to read a record captured before this existed.
+  const { runObligationWorker } = await import('../lib/obligations_worker.mjs')
+  await runObligationWorker(process.argv.slice(3))
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
 } else if (cmd === 'resolve') {
   // Entity identity dedup: judge the server-flagged fuzzy duplicate pairs locally via `claude -p`.
   const { runResolve } = await import('../lib/resolve.mjs')

package/lib/capture.mjs

@@ -314,6 +314,20 @@ async function captureWork(stdinRaw) {
   if (!token) { process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — no CORTEX_TOKEN in env or wired config\n`); return }
   const base = resolveBase(process.env.CORTEX_URL)
 
+  // ADR-0059 step 2 — retry obligations capture_record's worker parked while their sealed unit waited
+  // to be materialised (p90 ~1 day for a handoff). Here because this is the one thing that runs on
+  // every turn of every session on this machine; it costs one readdir when nothing is parked, and
+  // each entry carries its own backoff so a unit that waits a week is not posted every turn.
+  try {
+    const { flushParkedObligations, parkDir, postCandidates } = await import('./obligations_worker.mjs')
+    await flushParkedObligations({
+      dir: parkDir(),
+      post: (target, obligations) => postCandidates({ base, token, target, obligations, fetchImpl: fetchCortex }),
+      log: (line) => process.stderr.write(`cortex: ${stamp} obligations[flush] ${line}\n`),
+      now: () => Date.now(),
+    })
+  } catch { /* a parked retry must never cost a session its capture */ }
+
   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
@@ -396,6 +410,10 @@ async function captureWork(stdinRaw) {
         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`.
+        ...(extracted.obligations?.length ? { obligations: extracted.obligations } : {}),
       }
     : { ...common, transcript }
 

package/lib/edge_extract.mjs

@@ -12,9 +12,31 @@ import { homedir } from 'os'
 // timeout + grace, or whose PID is dead) is reclaimed.
 const LOCK_PATH = join(homedir(), '.cortex', 'summarize.lock')
 
+// 🔴 THE TIMEOUT MUST COVER THE TAIL OF A WIDE DISTRIBUTION, NOT ITS MIDDLE. Every full extraction
+// 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
+// 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
+// one-key summary of the full 50k-char CSG transcript returns in ~12s. The five-key extraction of the
+// same text takes 93s+. And ENT 425, three times LONGER than CSG, ran FASTER (77s) — because CSG names
+// ~35 people in its team roster and each person is a six-field object. The cost is generating the JSON.
+// So a record dense with names is slow regardless of its length, and no length-scaled timeout would
+// have predicted it.
+//
+// ⚠ 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.
+//
+// ⚠ Its effect on capture_route (1 attachment in its first two days) is a candidate, NOT proven.
 function summaryTimeoutMs() {
   const n = Number(process.env.CORTEX_SUMMARY_TIMEOUT_MS)
-  return Number.isFinite(n) && n > 0 ? n : 45_000
+  return Number.isFinite(n) && n > 0 ? n : 300_000
 }
 
 // Try to acquire the lock. Returns true if acquired (caller must call releaseSummaryLock in a finally),
@@ -134,6 +156,32 @@ const PAGES_FRAGMENT =
   'page. Most sessions belong on one to three pages. Empty array is correct for a session with no ' +
   'durable subject, and is much better than a loose guess.)'
 
+// ── ADR-0059 — obligations ───────────────────────────────────────────────────────────────────────
+//
+// A DIFFERENT QUESTION FROM `pages`, AND DELIBERATELY NOT AS CONSERVATIVE. The pages prompt says an
+// empty array is "much better than a loose guess", which is right for attachment — a missed page
+// costs retrieval quality — and measured: capture_route produced 1 attachment across 10 sessions on
+// a capable client (2026-09-09). A missed DEADLINE is a different cost, in the other direction, so
+// this fragment asks for the same care about applicability without importing the same reluctance.
+//
+// ⚠ `evidence` IS VERIFIED HERE, NOT SERVER-SIDE (ADR-0059 §4.1). The cloud receives only the derived
+// digest and never the transcript, so there is nothing server-side to compare a quote against. The
+// check is `verbatimIn()` below, run against the SAME slice the model was shown.
+const OBLIGATIONS_FRAGMENT =
+  '"obligations" (array of things someone must DO by a date, stated in this session. Each an object ' +
+  'with "subject" (what must be done, one short phrase), ' +
+  '"due_at" (ISO 8601 date or datetime if one is stated, otherwise null — do NOT invent or infer a ' +
+  'date that was not said), ' +
+  '"evidence" (the sentence from the session that says so, copied EXACTLY and VERBATIM — it is ' +
+  'checked against the transcript and the whole item is discarded if it does not match), ' +
+  '"obligated_party" (exactly one of: "self" if the person whose session this is must do it; ' +
+  '"other" if someone else must; "none" if nobody must). ' +
+  'The hard part is "none", so read it carefully: a real date about a real person is still "none" ' +
+  'when nobody owes anything — "so-and-so\'s birthday is today" has every surface feature of a ' +
+  'deadline and is not one. Historical and course-content dates are "none" too. ' +
+  'Include an item when the session genuinely states an obligation, and do not stretch to find one; ' +
+  'an empty array is correct for a session that contains no deadlines.)'
+
 const ENTITY_FRAGMENT =
   '"namedEntities" (array of important NON-PERSON things this content is about — concrete, named ' +
   'projects, processes, systems, products, documents, teams, tools, events, places, or topics. ' +
@@ -145,6 +193,108 @@ const ENTITY_FRAGMENT =
 
 // PURE. The scheduled task this transcript is an unattended run of, or null for a human session.
 // Claude Code wraps a scheduled run's instructions in <scheduled-task name="..." file="...">.
+// ── THE SUMMARIZER'S WINDOW — the whole record, unless it is enormous ────────────────────────────
+//
+// 🔴 NO FIXED WINDOW WORKS, AND TWO REAL TRANSCRIPTS PROVED IT FROM OPPOSITE DIRECTIONS (2026-09-10).
+//
+//   ENT 425 lecture (146,890 chars): the one assignment sits at char 147,121 — the LAST line. A head
+//   window cannot see it. A tail window can.
+//
+//   CSG kickoff (50,241 chars): all three dated deadlines sit at chars 8,027–11,390 — the EARLY
+//   MIDDLE, in the "upcoming schedule" segment. A head window sees all three. A head+tail window,
+//   which is what this function did for about twenty minutes, sees NONE of them.
+//
+// Each placement fixed one transcript by breaking the other. The head-only slice this replaced was
+// wrong; the head+tail "fix" was a second guess about where content lives, validated against n=1 and
+// refuted by n=2. Where obligations appear depends on how a particular meeting was run, so any rule
+// about which part to keep is a bet on the next transcript's structure.
+//
+// ✅ THE ACTUAL CONSTRAINT WAS NEVER THE MODEL. Measured: full text of the 146,890-char transcript ran
+// in 77.0s, faster than the 12k-window runs of the same file (56–86s). Latency barely tracks length
+// at this scale. And on CSG, full text found 2 of the 3 dated deadlines on BOTH runs, with correct ISO
+// dates and zero false positives, where the head+tail window found 0 of 3.
+//
+// So the default is effectively "send everything". The head+tail fallback survives only for records
+// so long they approach the model's context, where SOME window is unavoidable. At that size the
+// placement bet returns, and it should be treated as a known-lossy last resort, not a design.
+//
+// ⚠ THIS REQUIRES THE PROMPT TO TRAVEL ON STDIN (see extractSession). Full text exceeds Linux's
+// per-argument limit and Windows' command-line limit; as argv it would fail everywhere but macOS.
+//
+// ⚠ Env override CORTEX_SUMMARY_WINDOW is for MEASUREMENT. The default is what ships.
+const SUMMARY_WINDOW = Number(process.env.CORTEX_SUMMARY_WINDOW) > 0 ? Number(process.env.CORTEX_SUMMARY_WINDOW) : 400_000
+const ELISION = '\n\n[… middle of the session elided for length …]\n\n'
+
+/**
+ * PURE, exported for tests. The text the summarizer actually sees — the whole record, unless it
+ * exceeds the budget, in which case both ends are kept around a MARKED elision.
+ *
+ * ⚠ WHATEVER THIS RETURNS IS ALSO THE CORPUS THE VERBATIM GATE CHECKS AGAINST (see `extractSession`).
+ * That coupling is required, not incidental: checking a quote against text the model was never shown
+ * would reject valid quotes, and checking against MORE than it was shown would accept a fabrication
+ * that happens to appear in the discarded middle. A quote spanning the elision fails closed, which is
+ * the correct outcome — those two passages were never adjacent.
+ */
+export function summaryWindow(text, budget = SUMMARY_WINDOW) {
+  const s = String(text ?? '')
+  if (s.length <= budget) return s
+  const headBudget = Math.max(0, Math.floor((budget - ELISION.length) * 0.4))
+  const tailBudget = Math.max(0, budget - ELISION.length - headBudget)
+  return s.slice(0, headBudget) + ELISION + s.slice(s.length - tailBudget)
+}
+
+// ── ADR-0059 §4.1 — the verbatim gate ────────────────────────────────────────────────────────────
+
+const OBLIGATION_PARTIES = new Set(['self', 'other', 'none'])
+
+/** A guard against a runaway answer, not a target — the same framing as MAX_CAPTURE_PAGES. */
+const MAX_OBLIGATIONS = 5
+
+/**
+ * Is `needle` actually present in `haystack`, allowing only whitespace to differ?
+ *
+ * ⚠ WHITESPACE IS NORMALISED AND NOTHING ELSE IS. A transcript wraps lines; a model reproducing a
+ * sentence will not reproduce the wrapping. Collapsing runs of whitespace is the difference between
+ * a check that passes on real quotes and one that rejects nearly all of them. Case, punctuation and
+ * wording are NOT normalised — loosening those turns "is this sentence in the source" into "is this
+ * roughly like something in the source", which is the question this gate exists to refuse.
+ *
+ * 🔴 AND THE MINIMUM LENGTH IS LOAD-BEARING, NOT TIDINESS. Without it the gate is defeated by a
+ * one-word quote: `evidence: "Friday"` appears verbatim in almost any transcript that mentions a
+ * day, so a fabricated obligation would pass the check that exists to catch fabrication. A quote
+ * short enough to be accidentally present proves nothing about the claim attached to it.
+ */
+export function verbatimIn(needle, haystack) {
+  const norm = (s) => String(s ?? '').replace(/\s+/g, ' ').trim()
+  const n = norm(needle)
+  if (n.length < 16) return false
+  return norm(haystack).includes(n)
+}
+
+/**
+ * Drop every obligation candidate that cannot be verified against the text the model was shown.
+ *
+ * Shape first, then the quote. A candidate missing a subject, missing evidence, or carrying an
+ * `obligated_party` outside the preset is malformed and goes — the server's CHECK constraint would
+ * reject it anyway, and failing here means the record still lands with its other keys intact.
+ */
+export function keepVerifiableObligations(items, shown) {
+  if (!Array.isArray(items)) return []
+  const out = []
+  for (const it of items) {
+    if (!it || typeof it !== 'object') continue
+    const subject = typeof it.subject === 'string' ? it.subject.trim() : ''
+    const evidence = typeof it.evidence === 'string' ? it.evidence.trim() : ''
+    const party = typeof it.obligated_party === 'string' ? it.obligated_party.trim() : ''
+    if (!subject || !evidence || !OBLIGATION_PARTIES.has(party)) continue
+    if (!verbatimIn(evidence, shown)) continue
+    const due = typeof it.due_at === 'string' && it.due_at.trim() ? it.due_at.trim() : null
+    out.push({ subject: subject.slice(0, 200), due_at: due, evidence: evidence.slice(0, 500), obligated_party: party })
+    if (out.length >= MAX_OBLIGATIONS) break
+  }
+  return out
+}
+
 export function scheduledTaskName(transcript) {
   const m = String(transcript ?? '').match(/<scheduled-task\s+[^>]*name="([^"]+)"/)
   return m ? m[1] : null
@@ -195,6 +345,7 @@ const scheduledTaskFragment = (name) =>
   'One genuine finding outweighs an otherwise unremarkable run; summarize the FINDING, not the run.'
 
 export function extractSession(transcript) {
+  LAST_SKIP = null
   const raw = (transcript ?? '').trim()
   if (!raw || process.env.CORTEX_SUMMARIZE_DISABLED) return null
   const task = scheduledTaskName(raw)
@@ -203,31 +354,57 @@ export function extractSession(transcript) {
   const text = task ? stripScheduledTaskBlocks(raw) : raw
   // A run whose entire transcript WAS the instruction block leaves nothing to judge. That is a
   // heartbeat by definition — skip without spending a `claude -p` call on it.
-  if (task && !text) return { summary: 'NOOP', people: [], namedEntities: [], pages: [] }
+  if (task && !text) return { summary: 'NOOP', people: [], namedEntities: [], pages: [], obligations: [] }
+  // ONE window, named, used by both the prompt and the verbatim check — see `summaryWindow`.
+  const shown = summaryWindow(text)
+  // ⚠ THE OPENING FRAMING WAS "a Claude Code work session", AND IT CLASSIFIED A LECTURE AS NOOP.
+  // Measured 2026-09-10: the tail of the ENT 425 transcript came back `summary: "NOOP"` because the
+  // old no-op test — "no real work — greetings, no tasks" — reads "no tasks" as "no code was
+  // written". A NOOP here does not merely lose the summary: capture.mjs returns before ingest, so the
+  // record is never created at all.
+  //
+  // The new bar is "no DURABLE content", which still catches the case the rule exists for — a
+  // greeting, an interrupted session, a run that did nothing — and stops equating "nothing was built"
+  // with "nothing happened". Unattended scheduled runs are unaffected: `scheduledTaskFragment` is
+  // appended below and carries its own, stricter changed-vs-unchanged bar, which is where the
+  // heartbeat suppression that matters actually lives. ⚠ That fragment's own header records a NOOP
+  // wording change that killed a real finding on its first attempt — so this one is asserted by a
+  // negative control (a bare greeting must still NOOP), not just by the case it was written for.
   const prompt =
-    'You are processing a Claude Code work session for a knowledge base. Return ONLY minified JSON ' +
-    '(no prose, no markdown fences) with EXACTLY these four keys:\n' +
-    '"summary" (ONE concrete sentence under 20 words: what was worked on or decided. If the session ' +
-    'had no real work — greetings, no tasks — set summary to exactly "NOOP"),\n' +
+    'You are processing a captured record — a work session, a meeting, or a lecture transcript — for a ' +
+    'knowledge base. Return ONLY minified JSON (no prose, no markdown fences) with EXACTLY these five keys:\n' +
+    '"summary" (ONE concrete sentence under 20 words: what was worked on, decided, discussed or taught. ' +
+    'If the record holds NO durable content at all — only greetings, small talk, or a run that did ' +
+    'nothing — set summary to exactly "NOOP". A lecture, meeting or discussion with real content is ' +
+    'NOT a no-op merely because nothing was built),\n' +
     PEOPLE_FRAGMENT + ',\n' +
     ENTITY_FRAGMENT + ',\n' +
-    PAGES_FRAGMENT +
+    PAGES_FRAGMENT + ',\n' +
+    OBLIGATIONS_FRAGMENT +
     (task ? scheduledTaskFragment(task) : '') +
-    '\n\n--- SESSION ---\n' + text.slice(0, 12000) + '\n--- END ---'
+    '\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')
   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)
+    // and Windows caps the WHOLE command line at 32,767 characters. The full-text window can exceed
+    // both — ENT 425 alone is 146,890 characters. As argv it would work on macOS (ARG_MAX 1MB, the
+    // only machine that tests this) and fail with E2BIG everywhere else, green on the dev box and
+    // broken for the user. `claude --print` reads its prompt from stdin; verified live 2026-09-10.
     const r = spawnSync(
       'claude',
-      ['--print', '--model', process.env.CORTEX_SUMMARY_MODEL ?? 'claude-haiku-4-5', prompt],
-      { env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }), encoding: 'utf8', timeout: summaryTimeoutMs(), maxBuffer: 4 * 1024 * 1024 },
+      ['--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 },
     )
     const why = classifyEdgeFailure(r)
     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')
-    return parsed
+    // ADR-0059 §4.1 — the verbatim gate. This is the ONLY place it can run: the server never receives
+    // the transcript, so a quote it cannot see is a quote it cannot check.
+    return { ...parsed, obligations: keepVerifiableObligations(parsed.obligations, shown) }
   } catch (e) {
     return edgeSkip('threw', e instanceof Error ? e.message : String(e))
   } finally {
@@ -257,7 +434,16 @@ export function extractSession(transcript) {
 // next session, the second needs a human to run `claude setup-token` and will otherwise never
 // recover. Collapsing them into one silent `return null` is the same defect family as
 // claimRecordForTriage's "probably in the future" — a message that names one cause for many.
+// Why the most recent extractSession() in this process returned null, or null if it did not.
+// extractSession's contract stays "value or null" — the Stop hook treats every null alike, correctly,
+// because the next turn re-captures anyway. A ONE-SHOT caller cannot: a lecture handed to
+// capture_record is extracted once, and "another session holds the lock" (retry in a minute) and
+// "the credential expired" (stop) must not look the same to it. Read by obligations_worker.mjs.
+let LAST_SKIP = null
+export function lastEdgeSkip() { return LAST_SKIP }
+
 function edgeSkip(reason, detail) {
+  LAST_SKIP = { reason, detail }
   // stderr, not stdout: stdout of a Stop hook is not read, and anything written there would land in
   // the transcript of the NEXT capture. Prefixed so `cortex doctor` and a log grep can find it.
   process.stderr.write(`cortex: edge extraction SKIPPED [${reason}] ${detail}\n`)
@@ -343,6 +529,9 @@ export function parseEdgeJson(out) {
       // model returned and no matter what the prompt asked for. Adding a prompt fragment without
       // adding it here yields a feature that ships, runs, and does nothing.
       pages: Array.isArray(o.pages) ? o.pages : [],
+      // ADR-0059. Unverified at this point — parseEdgeJson has no transcript to check a quote
+      // against. `extractSession` filters these through `verbatimIn()` before returning.
+      obligations: Array.isArray(o.obligations) ? o.obligations : [],
     }
   } catch {
     return null

package/lib/obligations_worker.mjs

@@ -0,0 +1,284 @@
+// ADR-0059 step 2 — obligations from things HANDED OVER, not only from sessions.
+//
+// capture_record files a transcript and returns at once. This worker then reads it for obligations
+// the way the Stop hook reads a session (the same extractSession, the same verbatim gate), and posts
+// what it finds to /api/obligations/candidates against the handle the capture returned.
+//
+// WHY DETACHED. Extraction runs 56–151s on a lecture (measured 2026-09-10). Blocking the tool call
+// that long stalls the session, and Codex's default MCP tool timeout is 60s: a timed-out capture
+// invites a retry, and every capture_record call mints a fresh unit, so a retry is a duplicate.
+//
+// 🔴 WHY IT PARKS. On a private-intake account the capture is SEALED and there is no record until
+// someone materialises the unit — median 0 minutes for a handoff, but p90 ~1 day and max ~6 days on
+// the seat this was built for. The server stores nothing for a sealed unit (a proposal's subject and
+// quote ARE content, and sealed content stays sealed until the person materialises it), so it answers
+// 409 and the candidates wait HERE, on the person's own machine — the machine the transcript came
+// from — in ~/.cortex/obligations-pending/, mode 0600. Every Stop-hook capture calls
+// flushParkedObligations, which retries what is due with backoff. A worker that slept in memory
+// instead would lose them to the first reboot, which a six-day wait all but guarantees.
+//
+// Every outcome is one line in ~/.cortex/capture.log. A detached worker has nowhere else to speak,
+// and this subsystem's history is silent success over broken parts (see capture.mjs captureLogFd).
+
+import { spawn } from 'node:child_process'
+import { mkdirSync, openSync, readdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const MAX_PARK_DAYS = 30
+export const FIRST_RETRY_MS = 5 * 60_000
+export const MAX_RETRY_MS = 6 * 60 * 60_000
+export const BUSY_WAIT_MS = 30_000
+export const BUSY_MAX_WAIT_MS = 20 * 60_000
+
+export function parkDir(home = homedir()) {
+  return join(home, '.cortex', 'obligations-pending')
+}
+
+export function targetId(target) {
+  return target?.recordId ?? target?.intakeItemId ?? null
+}
+
+/** PURE. What the worker should do with a response from /api/obligations/candidates. */
+export function classifyPost(status) {
+  if (status >= 200 && status < 300) return 'recorded'
+  // Not materialised yet. The one answer that means "same request, later".
+  if (status === 409) return 'pending'
+  // Not yours / discarded / malformed. A retry cannot change the answer.
+  if (status === 400 || status === 403 || status === 404 || status === 410) return 'drop'
+  // 401 is deliberately a retry: an expired credential is fixed by logging in again, and the
+  // candidates should still be there when that happens. So are 429, 5xx and a network failure.
+  return 'retry'
+}
+
+/** PURE. The next retry delay: 5 min, doubling, capped at 6 h. */
+export function backoffMs(attempts) {
+  return Math.min(FIRST_RETRY_MS * 2 ** Math.max(0, attempts - 1), MAX_RETRY_MS)
+}
+
+/** POST the candidates. Never throws: a network failure is `retry`, like a 5xx. */
+export async function postCandidates({ base, token, target, obligations, fetchImpl }) {
+  if (!token) return { action: 'retry', status: 0, body: { error: 'no CORTEX_TOKEN in env or wired config' } }
+  try {
+    const res = await fetchImpl(`${base}/api/obligations/candidates`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ...target, obligations }),
+    })
+    const body = await res.json().catch(() => ({}))
+    return { action: classifyPost(res.status), status: res.status, body }
+  } catch (e) {
+    return { action: 'retry', status: 0, body: { error: e instanceof Error ? e.message : String(e) } }
+  }
+}
+
+function writeParked(dir, entry) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const file = join(dir, `${targetId(entry.target)}.json`)
+  const tmp = `${file}.${process.pid}.tmp`
+  writeFileSync(tmp, JSON.stringify(entry), { mode: 0o600 })
+  renameSync(tmp, file) // atomic: a concurrent flush never reads half a file
+}
+
+/**
+ * Extract, then post — or park. Dependencies are injected so every branch is testable without
+ * spawning `claude` or touching the network.
+ *
+ * deps: { extract(text) → result|null, lastSkip() → {reason}|null, post(target, obligations) → {action,status,body},
+ *         park(entry), log(line), sleep(ms), now() → ms }
+ */
+export async function processJob(job, deps) {
+  const { extract, lastSkip, post, park, log, sleep, now } = deps
+  const giveUpAt = now() + BUSY_MAX_WAIT_MS
+  let result = extract(job.text)
+  // Another session holding the summarizer lock is the one failure worth waiting out: this record is
+  // read ONCE, so skipping it (right for the Stop hook, which re-captures next turn) would lose it.
+  while (!result && lastSkip()?.reason === 'busy' && now() < giveUpAt) {
+    await sleep(BUSY_WAIT_MS)
+    result = extract(job.text)
+  }
+  if (!result) {
+    const why = lastSkip()
+    log(`extraction FAILED [${why?.reason ?? 'unknown'}] — this record was NOT checked for obligations`)
+    return { outcome: 'extract-failed', reason: why?.reason ?? null }
+  }
+  const obligations = Array.isArray(result.obligations) ? result.obligations : []
+  if (obligations.length === 0) {
+    log('no obligations found')
+    return { outcome: 'none' }
+  }
+  const res = await post(job.target, obligations)
+  if (res.action === 'recorded') {
+    log(`recorded ${res.body?.proposed ?? '?'} of ${obligations.length} as proposals on record ${res.body?.recordId ?? '?'}`)
+    return { outcome: 'recorded', proposed: res.body?.proposed ?? null }
+  }
+  if (res.action === 'drop') {
+    log(`DROPPED ${obligations.length} — the server answered ${res.status} ${res.body?.error ?? ''}`.trim())
+    return { outcome: 'dropped', status: res.status }
+  }
+  const t = now()
+  park({ target: job.target, title: job.title ?? null, obligations, parkedAt: t, attempts: 1, nextAttemptAt: t + backoffMs(1) })
+  log(`parked ${obligations.length} — ${res.action === 'pending' ? 'the unit is not materialised yet' : `${res.status} ${res.body?.error ?? ''}`.trim()}; retried by later captures`)
+  return { outcome: 'parked', status: res.status }
+}
+
+/**
+ * Retry everything parked that is due. Called by every Stop-hook capture, so it must be cheap when
+ * there is nothing to do (one readdir) and must never throw.
+ *
+ * deps: { dir, post(target, obligations), log(line), now() → ms }
+ */
+export async function flushParkedObligations(deps) {
+  const { dir, post, log, now } = deps
+  let names
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith('.json'))
+  } catch {
+    return { flushed: 0 } // no directory: nothing has ever been parked
+  }
+  let flushed = 0
+  for (const name of names) {
+    const file = join(dir, name)
+    let entry
+    try {
+      entry = JSON.parse(readFileSync(file, 'utf8'))
+    } catch {
+      try { unlinkSync(file) } catch { /* raced with another flush */ }
+      log(`discarded unreadable parked file ${name}`)
+      continue
+    }
+    const id = targetId(entry.target)
+    const t = now()
+    if (t - (entry.parkedAt ?? t) > MAX_PARK_DAYS * 24 * 60 * 60_000) {
+      try { unlinkSync(file) } catch { /* raced */ }
+      log(`GAVE UP on ${entry.obligations?.length ?? '?'} parked obligations for ${id} after ${MAX_PARK_DAYS} days — the unit never materialised`)
+      continue
+    }
+    if ((entry.nextAttemptAt ?? 0) > t) continue
+    const res = await post(entry.target, entry.obligations)
+    if (res.action === 'recorded' || res.action === 'drop') {
+      try { unlinkSync(file) } catch { /* raced with another flush; the write is idempotent */ }
+      flushed += 1
+      log(res.action === 'recorded'
+        ? `recorded ${res.body?.proposed ?? '?'} parked obligations for ${id} on attempt ${(entry.attempts ?? 0) + 1}`
+        : `DROPPED parked obligations for ${id} — the server answered ${res.status} ${res.body?.error ?? ''}`.trim())
+      continue
+    }
+    const attempts = (entry.attempts ?? 1) + 1
+    writeParked(dir, { ...entry, attempts, nextAttemptAt: t + backoffMs(attempts) })
+  }
+  return { flushed }
+}
+
+// ── process plumbing (not unit-tested; kept thin) ────────────────────────────────────────────────
+
+function logFd() {
+  try {
+    const dir = join(homedir(), '.cortex')
+    mkdirSync(dir, { recursive: true })
+    return openSync(join(dir, 'capture.log'), 'a')
+  } catch {
+    return 'ignore'
+  }
+}
+
+function logger(target) {
+  const id = (targetId(target) ?? 'unknown').slice(0, 8)
+  return (line) => process.stderr.write(`cortex: ${new Date().toISOString()} obligations[${id}] ${line}\n`)
+}
+
+/**
+ * Launch the worker fully detached, the job on its stdin. Never throws: a capture that succeeded must
+ * not be reported as failed because a background read could not start.
+ *
+ * Returns 'started' | 'disabled' | 'failed' — three, not a boolean, because the caller REPORTS it:
+ * "disabled" is the person's own setting and needs no remark, "failed" means this record was not
+ * checked and the capture reply must say so.
+ */
+export function spawnObligationWorker(job) {
+  if (process.env.CORTEX_SUMMARIZE_DISABLED) return 'disabled'
+  try {
+    const bin = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'cortex-mcp.mjs')
+    const fd = logFd()
+    const child = spawn(process.execPath, [bin, 'extract-obligations'], {
+      env: { ...process.env },
+      detached: true,
+      stdio: ['pipe', fd, fd],
+    })
+    child.on('error', () => {})
+    child.stdin.on('error', () => {})
+    child.stdin.end(JSON.stringify(job))
+    child.unref()
+    return 'started'
+  } catch {
+    return 'failed'
+  }
+}
+
+async function realDeps(target) {
+  const { extractSession, lastEdgeSkip } = await import('./edge_extract.mjs')
+  const { fetchCortex, resolveBase, resolveTokenSource } = await import('./diagnose.mjs')
+  const base = resolveBase(process.env.CORTEX_URL)
+  const token = resolveTokenSource().token
+  return {
+    extract: extractSession,
+    lastSkip: lastEdgeSkip,
+    post: (t, obligations) => postCandidates({ base, token, target: t, obligations, fetchImpl: fetchCortex }),
+    park: (entry) => writeParked(parkDir(), entry),
+    log: logger(target),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    now: () => Date.now(),
+  }
+}
+
+function readStdin() {
+  try { return readFileSync(0, 'utf8') } catch { return '' }
+}
+
+function flag(argv, name) {
+  const i = argv.indexOf(name)
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null
+}
+
+/**
+ * `cortex-mcp extract-obligations`
+ *   (no flags)                       detached-worker mode: the job arrives as JSON on stdin
+ *   --record <id> | --intake <id>    foreground: read --file, extract, post, print the outcome
+ *   --file <path> [--dry-run]        --dry-run prints what WOULD be posted and posts nothing
+ *
+ * The foreground form is how records captured before this existed get read — ADR-0059 §7
+ * criterion 1 ("re-run the captured transcripts") needs exactly this and nothing else.
+ */
+export async function runObligationWorker(argv = []) {
+  const file = flag(argv, '--file')
+  if (!file) {
+    let job
+    try { job = JSON.parse(readStdin()) } catch { job = null }
+    if (!job?.text || !targetId(job?.target)) {
+      process.stderr.write(`cortex: ${new Date().toISOString()} obligations[unknown] no job on stdin — nothing to do\n`)
+      return
+    }
+    await processJob(job, await realDeps(job.target))
+    return
+  }
+  const recordId = flag(argv, '--record')
+  const intakeItemId = flag(argv, '--intake')
+  if (Boolean(recordId) === Boolean(intakeItemId)) {
+    console.error('Pass exactly one of --record <id> or --intake <id>, with --file <path>.')
+    process.exitCode = 2
+    return
+  }
+  const target = recordId ? { recordId } : { intakeItemId }
+  const text = readFileSync(file, 'utf8')
+  const deps = await realDeps(target)
+  deps.log = (line) => console.log(line)
+  if (argv.includes('--dry-run')) {
+    const result = deps.extract(text)
+    if (!result) { console.log(`extraction FAILED [${deps.lastSkip()?.reason ?? 'unknown'}]`); process.exitCode = 1; return }
+    console.log(JSON.stringify(result.obligations ?? [], null, 2))
+    return
+  }
+  const out = await processJob({ target, text, title: null }, deps)
+  if (out.outcome === 'extract-failed' || out.outcome === 'dropped') process.exitCode = 1
+}

package/lib/server.mjs

@@ -14,6 +14,7 @@ import { renderCaptureStatus } from './capture_status.mjs'
 import { renderTriage } from './red_link_triage.mjs'
 import { runCodeGraphQuery } from './code_graph_cli.mjs'
 import { repoFullNameFrom } from './capture.mjs'
+import { spawnObligationWorker } from './obligations_worker.mjs'
 
 // Reactive red-link triage (Mechanism 2). On a read_page miss, ask the server whether the name is a
 // tracked wanted page, whether a bare node exists for it, and whether it's a deliberately demoted page,
@@ -2348,6 +2349,17 @@ function renderNudge(payload) {
     },
   )
 
+  // ADR-0059 step 2 — what capture_record says about the background obligations read. ⚠ It must not
+  // claim more than happened: the read has only STARTED, it can fail, and what it finds is a proposal,
+  // not a calendar entry. 'disabled' is the person's own CORTEX_SUMMARIZE_DISABLED and needs no remark.
+  const obligationCheckLine = (started, sealed) => {
+    if (started === 'disabled') return null
+    if (started === 'failed') return '⚠ Could not start the background check for deadlines — this record was NOT read for obligations.'
+    return sealed
+      ? 'Reading it for deadlines in the background (a long transcript takes 1–3 min). Anything found waits on this machine and is attached as a proposal once you materialise it. Outcome in ~/.cortex/capture.log.'
+      : 'Reading it for deadlines in the background (a long transcript takes 1–3 min). Anything found is stored as a proposal on this record. Outcome in ~/.cortex/capture.log.'
+  }
+
   server.registerTool(
     'capture_record',
     {
@@ -2421,6 +2433,8 @@ function renderNudge(payload) {
         if (body.containerDeferred) {
           l.push(`Container ${body.containerRecordId} is carried with it and applied when you materialise — you do not need to place it again.`)
         }
+        const check = obligationCheckLine(spawnObligationWorker({ target: { intakeItemId: body.intakeItemId }, text, title }), true)
+        if (check) l.push(check)
         return { content: [{ type: 'text', text: l.join('\n') }] }
       }
       const lines = [`Captured "${title}" as record ${body.id}.`]
@@ -2429,6 +2443,8 @@ function renderNudge(payload) {
       if (body.routed_by?.length) lines.push(`Routes via: ${body.routed_by.join(', ')} — it reaches whatever page claims those.`)
       else lines.push('⚠ NO IDENTIFIERS — this record reaches no page. Nobody will find it unless you give it one (identifiers) or attach it by hand.')
       if (body.contained) lines.push('Placed inside the container you named.')
+      const check = obligationCheckLine(spawnObligationWorker({ target: { recordId: body.id }, text, title }), false)
+      if (check) lines.push(check)
       return { content: [{ type: 'text', text: lines.join('\n') }] }
     },
   )

package/lib/setup.mjs

@@ -168,6 +168,33 @@ export async function runSetup(argv, version) {
     log(`  ⚠ skills install skipped: ${e.message} (will retry on next session)`)
   }
 
+  // ── 3b. Stamp what installed this machine — ADR-0057 ──────────────────────────────────────────
+  // Nothing recorded which CLI last ran setup, and the desktop app needs exactly that to decide
+  // whether a seat's on-disk artifacts are stale.
+  //
+  // ⚠ WHY A STAMP AND NOT THE WIRED SPEC. The config holds a moving dist-tag (see pickSpec above:
+  // "never a version"), so it says nothing about WHEN this machine was installed or by what. The
+  // desktop's autoHealMcp() used to read a version out of it and, once this file started writing
+  // `@stable`, silently returned on every launch for three weeks — the skills/hooks refresh simply
+  // stopped. This file is the signal that replaces it.
+  //
+  // Written AFTER the artifacts it describes (config, hooks, skills) and BEFORE the token check on
+  // purpose: a bad token means the connection is wrong, not that the files failed to install.
+  // Claiming otherwise would leave a correctly-installed machine looking permanently stale.
+  //
+  // Fail-soft: a stamp we cannot write must never break an otherwise successful setup. A missing
+  // stamp reads as stale downstream, so the cost of failing here is one redundant heal, not a break.
+  try {
+    const cortexDir = join(homedir(), '.cortex')
+    if (!existsSync(cortexDir)) mkdirSync(cortexDir, { recursive: true })
+    writeFileSync(
+      join(cortexDir, 'setup.json'),
+      JSON.stringify({ version, spec, at: new Date().toISOString() }, null, 2),
+    )
+  } catch (e) {
+    log(`  ⚠ could not record the setup stamp: ${e.message} (harmless; the app may re-run setup once)`)
+  }
+
   // ── 4. Self-verify — writing config proves "files written", NOT "connection works".
   // Actually call the API so a bad/expired token is caught HERE, not 40 minutes into debugging.
   log('')

package/package.json

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