@theronap/cortex-mcp 0.9.139 → 0.9.141

package/lib/capture.mjs

@@ -396,6 +396,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
@@ -203,31 +353,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 {
@@ -290,6 +466,18 @@ export function classifyEdgeFailure(r) {
   // The other shape of the same event: spawnSync killed the child, so status is null and signal set.
   if (r.signal) return { reason: 'timeout', detail: `killed by ${r.signal} after ${summaryTimeoutMs()}ms` }
 
+  // 🔴 EVERYTHING BELOW APPLIES ONLY TO A FAILED CALL. Exit 0 means the model answered; its answer
+  // is CONTENT, not a status report, and must never be scanned for failure keywords.
+  //
+  // This ordering was wrong on the first version and produced a false `auth-expired` on a call that
+  // had returned status 0 — because the session being summarized was itself about fixing an OAuth
+  // bug, so the model's own summary contained the word. A working extraction was thrown away for
+  // discussing the wrong subject. Any session about auth, 401s or logins would have hit it.
+  //
+  // The general form of the mistake: matching a symptom string across a channel that carries both
+  // diagnostics AND payload. The exit status is the only trustworthy separator, so it goes first.
+  if (r.status === 0) return r.stdout ? null : { reason: 'no-output', detail: 'claude exited 0 with empty stdout' }
+
   const out = `${r.stdout ?? ''}\n${r.stderr ?? ''}`
   // ⚠ THE AUTH MESSAGE ARRIVES ON **STDOUT**, WITH EXIT 1 — not on stderr, which is where a reader
   // would look for it. Verified against the live failure 2026-09-08:
@@ -305,9 +493,7 @@ export function classifyEdgeFailure(r) {
         + 'and no page proposals are made.',
     }
   }
-  if (r.status !== 0) return { reason: 'exit', detail: `claude exited ${r.status}: ${firstLine(out)}` }
-  if (!r.stdout) return { reason: 'no-output', detail: 'claude exited 0 with empty stdout' }
-  return null
+  return { reason: 'exit', detail: `claude exited ${r.status}: ${firstLine(out)}` }
 }
 
 function firstLine(s) {
@@ -333,6 +519,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/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.139",
+  "version": "0.9.141",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {