@theronap/cortex-mcp 0.9.141 → 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

package/lib/edge_extract.mjs

@@ -345,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)
@@ -433,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`)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.141",
+  "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": {