@theronap/cortex-mcp 0.9.141 → 0.9.143

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/doctor.mjs

@@ -3,6 +3,7 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { checkToken, checkSkills, resolveBase, resolveTokenSource } from './diagnose.mjs'
 import { renderRenameNotice } from './rename_notice.mjs'
+import { detectSurface, renderSurface } from './surface.mjs'
 
 // `npx @theronap/cortex-mcp doctor` — a live, one-command health check.
 //
@@ -21,13 +22,27 @@ export const resolveToken = resolveTokenSource
 // signal inside Claude Code itself (three-machine dry-run finding 2026-06-09: with no
 // indicator, a user can't tell whether their sessions are flowing to the org).
 // Always returns 0 — a status line must never break a session start.
+//
+// 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() {
-  const base = resolveBase(process.env.CORTEX_URL)
   const out = (m) => process.stdout.write(m + '\n')
+  try {
+    await statusLine(out)
+  } finally {
+    const surface = renderSurface(detectSurface(process.env), 'status')
+    if (surface) out(surface)
+  }
+  return 0
+}
+
+async function statusLine(out) {
+  const base = resolveBase(process.env.CORTEX_URL)
   const { token } = resolveToken()
   if (!token) {
     out('Agnoclast: NOT connected — no token found. Run: npx -y @theronap/cortex-mcp setup <token>')
-    return 0
+    return
   }
   try {
     const r = await checkToken(token, base)
@@ -40,7 +55,7 @@ export async function runStatus() {
       // warning that contradicts it.
       if (r.captureNotice?.message) {
         out(`Agnoclast: ⚠ ${r.captureNotice.message}`)
-        return 0
+        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}.`)
@@ -58,12 +73,24 @@ export async function runStatus() {
   } catch (e) {
     out(`Agnoclast: status check failed (${e?.message ?? String(e)}) — run doctor.`)
   }
-  return 0
 }
 
+// The surface block goes LAST, from a `finally`, for the same reason as in runStatus: all three
+// verdicts (PASS, PARTIAL, FAIL) can be printed to a person in Claude's Home tab, and PASS is the
+// one that misled. It says "reopen Claude Code", and reopening the Claude app can put them straight
+// back in Home. The exit code is unchanged: not being able to see the surface is not a failure.
 export async function runDoctor() {
-  const base = resolveBase(process.env.CORTEX_URL)
   const out = (m) => process.stdout.write(m + '\n')
+  try {
+    return await doctorChecks(out)
+  } finally {
+    out(renderSurface(detectSurface(process.env), 'doctor'))
+    out('')
+  }
+}
+
+async function doctorChecks(out) {
+  const base = resolveBase(process.env.CORTEX_URL)
 
   out('')
   out('Agnoclast doctor — checking your connection…')

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_render.mjs

@@ -0,0 +1,39 @@
+// PURE: what my_obligations prints. Out of server.mjs so the labelling below can be tested — the tool
+// handler itself is reachable by no test.
+//
+// 🔴 A PROPOSAL MUST NOT READ AS SOMETHING THE PERSON ENTERED. ADR-0059 extraction writes rows in state
+// `proposed`, and listObligations returns the owner's own proposals alongside confirmed ones — by
+// design, since a proposal nobody sees is a silent drop. Until 2026-09-10 this renderer printed them
+// all under "N open:" with no mark, so two lines extracted from a lecture (one of them wrongly dated)
+// looked exactly like obligations the person had written down. It is labelled here, and the header
+// says what to do with a wrong one.
+//
+// `dueAt` arrives in the OWNER's zone with its offset (web/lib/engine/due_dates.ts), so slice(0, 10)
+// below is the owner's calendar date and new Date() is still the exact instant.
+export function renderObligations(obs, now = Date.now()) {
+  if (!obs?.length) return 'Nothing open.'
+  const proposed = obs.filter((o) => o.state === 'proposed').length
+  const lines = [
+    proposed
+      ? `${obs.length} open — ${proposed} of them PROPOSED: extracted from a record, not entered by you. A wrong one: resolve_obligation with state "cancelled".`
+      : `${obs.length} open:`,
+    '',
+  ]
+  for (const o of obs) {
+    const overdue = o.dueAt && new Date(o.dueAt).getTime() <= now
+    const when = o.dueAt ? `${overdue ? 'OVERDUE ' : 'due '}${o.dueAt.slice(0, 10)}` : 'no deadline'
+    lines.push(`${o.id}`)
+    lines.push(`  ${o.subject}  — ${when}${o.state === 'snoozed' ? ' (snooze expired)' : ''}${o.state === 'proposed' ? '  [PROPOSED]' : ''}`)
+    // ⚠ EVIDENCE IS RENDERED AS A QUESTION, NEVER AS A VERDICT. The phrasing is the feature:
+    // "is this done?" costs the reader a second, "you still owe this" about finished work costs
+    // the channel its credibility.
+    if (o.evidence?.length) {
+      lines.push(`  ❓ ${o.evidence.length} record(s) suggest this may already be done — check, then resolve_obligation:`)
+      for (const e of o.evidence.slice(0, 3)) {
+        lines.push(`      ${e.occurredAt.slice(0, 10)}  ${e.title ?? '(untitled)'}${e.viaIdentifier ? `  [${e.viaIdentifier}]` : ''}`)
+      }
+    }
+    lines.push('')
+  }
+  return lines.join('\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,8 @@ 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'
+import { renderObligations } from './obligations_render.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,
@@ -2122,27 +2124,7 @@ function renderNudge(payload) {
       const out = await res.json().catch(() => null)
       if (!res.ok) return toolError(`Could not list: ${out?.error ?? res.status}`)
       const obs = out?.obligations ?? []
-      if (!obs.length) return { content: [{ type: 'text', text: 'Nothing open.' }] }
-
-      const now = Date.now()
-      const lines = [`${obs.length} open:`, '']
-      for (const o of obs) {
-        const overdue = o.dueAt && new Date(o.dueAt).getTime() <= now
-        const when = o.dueAt ? `${overdue ? 'OVERDUE ' : 'due '}${o.dueAt.slice(0, 10)}` : 'no deadline'
-        lines.push(`${o.id}`)
-        lines.push(`  ${o.subject}  \u2014 ${when}${o.state === 'snoozed' ? ' (snooze expired)' : ''}`)
-        // \u26a0 EVIDENCE IS RENDERED AS A QUESTION, NEVER AS A VERDICT. The phrasing is the feature:
-        // "is this done?" costs the reader a second, "you still owe this" about finished work costs
-        // the channel its credibility.
-        if (o.evidence?.length) {
-          lines.push(`  \u2753 ${o.evidence.length} record(s) suggest this may already be done \u2014 check, then resolve_obligation:`)
-          for (const e of o.evidence.slice(0, 3)) {
-            lines.push(`      ${e.occurredAt.slice(0, 10)}  ${e.title ?? '(untitled)'}${e.viaIdentifier ? `  [${e.viaIdentifier}]` : ''}`)
-          }
-        }
-        lines.push('')
-      }
-      return { content: [{ type: 'text', text: lines.join('\n') }] }
+      return { content: [{ type: 'text', text: renderObligations(obs) }] }
     },
   )
 
@@ -2348,6 +2330,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 +2414,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 +2424,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/surface.mjs

@@ -0,0 +1,94 @@
+// Which app is running `doctor` / `status` — and, when that cannot be told, the requirement, plainly.
+//
+// WHY THIS EXISTS (T23, v1 scope lock, added 2026-09-09). A new seat lost about an hour to being in
+// the Claude desktop app's Home tab instead of its Code tab. Everything Agnoclast installs lives in
+// Claude Code's own config: the server in ~/.claude.json, the hooks in ~/.claude/settings.json. Home
+// reads neither, so nothing connected and nothing said why. `doctor` and `status` both ran in that
+// state and neither mentioned the one fact that mattered. `doctor` printed PASS, because the token
+// was fine, then told the person to "reopen Claude Code", which put them back in Home.
+//
+// WHAT CAN BE DETECTED. Verified against the Claude Code 2.1.260 binary on 2026-09-10, not assumed:
+//   CLAUDECODE="1"          Claude Code puts this in the environment of every hook command, MCP
+//                           server and shell command it starts. Present means Claude Code started us.
+//   CLAUDE_CODE_ENTRYPOINT  Claude Code sets it at startup when its launcher has not: 'cli', or
+//                           'sdk-cli' for `claude -p`. Launchers set their own: 'claude-desktop' (the
+//                           desktop app's Code tab), 'claude-vscode', 'local-agent', 'remote', 'sdk-ts'.
+//
+// WHAT CANNOT: Home. Home never starts this process, so no process running `doctor` or `status` is
+// ever "in Home". A person in Home who runs `doctor` does it from a terminal, and that terminal looks
+// like every other terminal. So a missing signal means UNKNOWN, never "fine", and UNKNOWN prints the
+// requirement. That is the T23 acceptance criterion: the message appears when the surface is absent,
+// rather than merely being able to appear.
+//
+// ⚠ Only the entrypoints below count as a place Agnoclast is known to work. Claude Code also runs
+// underneath other products ('local-agent', 'remote*', 'sdk-ts', ...), and whether those load the
+// user's ~/.claude.json has not been verified. They get the requirement, not a ✓. A wrong ✓ hides the
+// message from the one person who needed it. A wrong ⚠ costs a line that begins "If that's where
+// you are".
+//
+// Deliberately NOT used, each for a reason:
+//   ~/.claude.json wiring      `doctor` already reports it as "token source", and it was just as
+//                              present in the Home incident. Wired is not a fact about where you are.
+//   /api/session-ping          keyed by person + cwd, not by machine; says "some host started the
+//                              server recently", not "the app you are looking at can"; and it adds a
+//                              network round trip to a SessionStart hook already measured at 4.6s.
+//   ~/.cortex/presence.json    written only after a SUCCESSFUL hydrate, so a missing file cannot tell
+//                              "never used Code here" from "hydrate failed". It is history, not location.
+//   Claude.app installed       says nothing about which tab is open.
+//
+// Pure: no I/O. The caller passes the environment in.
+
+/** Entrypoints known to be Claude Code proper, i.e. Claude Code reading this user's own config. */
+const CODE_ENTRYPOINTS = {
+  'cli': 'Claude Code in a terminal',
+  'sdk-cli': 'Claude Code in a terminal',
+  'claude-desktop': 'the Code tab of the Claude desktop app',
+  'claude-desktop-3p': 'the Code tab of the Claude desktop app',
+  'claude-vscode': 'the Claude Code editor extension',
+}
+
+// ONE text, two renderings. `status` joins these into one line; `doctor` prints them wrapped. Keeping
+// a single source matters: capture_status.mjs records two copies of one answer that had already
+// drifted apart. Written for someone who has never heard of a terminal flag or a config file.
+//
+// "If you use Claude" is load-bearing. `install` also wires Codex, Cursor and Antigravity, so an
+// unqualified "Agnoclast only works in Claude Code" would be false for those seats. "Home or Chat"
+// names both labels: the desktop app's own policy code calls the surface "Chat", and the seat that
+// prompted this called it "Home".
+export const REQUIREMENT_LINES = [
+  'If you use Claude, Agnoclast only works in Claude Code: the Code tab of the Claude',
+  'desktop app, Claude Code in a terminal, or the Claude Code extension for VS Code or',
+  "JetBrains. The Claude app's Home or Chat tab can't start Agnoclast, so nothing",
+  "connects there and nothing tells you why. If that's where you are, switch to the",
+  'Code tab.',
+]
+
+/**
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {{ surface: 'code', where: string, entrypoint: string|null } | { surface: 'unknown', entrypoint: string|null }}
+ */
+export function detectSurface(env = process.env) {
+  const entrypoint = env?.CLAUDE_CODE_ENTRYPOINT || null
+  // Exactly "1", which is the only value Claude Code writes. Stricter than Claude Code's own truthiness
+  // check on purpose, because a false positive here suppresses the requirement.
+  if (env?.CLAUDECODE !== '1') return { surface: 'unknown', entrypoint }
+  // A Claude Code old enough not to set an entrypoint was still Claude Code reading this user's config.
+  if (!entrypoint) return { surface: 'code', where: 'Claude Code', entrypoint: null }
+  const where = CODE_ENTRYPOINTS[entrypoint]
+  return where ? { surface: 'code', where, entrypoint } : { surface: 'unknown', entrypoint }
+}
+
+/**
+ * What to print about the surface. Returns '' when there is nothing to say.
+ *   status: silent inside Claude Code. It runs as a SessionStart hook, its stdout lands in the model's
+ *           context every session, and there the requirement is already met.
+ *   doctor: always says something. A ✓ when the surface is known, the requirement when it is not.
+ * @param {ReturnType<typeof detectSurface>} detection
+ * @param {'doctor'|'status'} mode
+ */
+export function renderSurface(detection, mode) {
+  const known = detection?.surface === 'code'
+  if (mode === 'status') return known ? '' : `Agnoclast: ⚠ ${REQUIREMENT_LINES.join(' ')}`
+  if (known) return `  ✓ app       — running inside ${detection.where}, where Agnoclast works.`
+  return REQUIREMENT_LINES.map((l, i) => (i === 0 ? `  ⚠ ${l}` : `    ${l}`)).join('\n')
+}

package/package.json

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