@theronap/cortex-mcp 0.9.137 → 0.9.139

package/bin/cortex-mcp.mjs

@@ -28,6 +28,36 @@ const VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.u
 const cmd = process.argv[2]
 const rest = process.argv.slice(3)
 
+// ── The summarizer subprocess runs NO context hooks ──────────────────────────────────────────────
+//
+// Edge extraction shells out to `claude --print` with CORTEX_SUMMARIZING=1. That headless session
+// fires the SAME hook chain as a real one, and on a wired seat that is five SessionStart commands
+// plus hydrate on UserPromptSubmit — four of which make network calls to Agnoclast.
+//
+// `capture` (Stop) has guarded on this env var since the recursion fix. Nothing else did, so every
+// summarizer call still paid for snapshot-context + status + skills + hydrate before the model saw
+// a single token of the prompt. Two consequences, both measured live 2026-09-08:
+//
+//   1. LATENCY. Extraction ran 45-68s against a 45s timeout and failed as often as it succeeded.
+//      A one-off `claude --print 'say ok'` on the same credential answers in about a second.
+//   2. POLLUTED OUTPUT. `status` prints the pending-records block to stdout, so the summarizer
+//      answered THAT before the prompt: its stdout began "You have 17 intake units in the cleanup
+//      queue ... Want me to help with either?" ahead of the JSON. The extractor asks for "ONLY
+//      minified JSON"; a hook prepending prose to the model's input is how that instruction gets
+//      overridden by the system itself.
+//
+// The guard is here, at the dispatcher, rather than in each subcommand: it is one rule about what a
+// summarizer subprocess IS, and putting it in five places is how the sixth gets forgotten. Exit 0
+// and silent — a hook that errors is noise, and there is genuinely nothing to do.
+//
+// ⚠ NOT guarded: `capture` (has its own, with a diagnostic), and anything a human might run by hand
+// while this var happens to be set. Only the ambient context commands are listed.
+const CONTEXT_HOOK_COMMANDS = new Set(['snapshot-context', 'status', 'hydrate', 'skills'])
+if (process.env.CORTEX_SUMMARIZING && CONTEXT_HOOK_COMMANDS.has(cmd)) {
+  process.stderr.write(`cortex: ${cmd} skipped — summarizer subprocess (CORTEX_SUMMARIZING)\n`)
+  process.exit(0)
+}
+
 if (cmd === '--version' || cmd === '-v') {
   process.stdout.write(`cortex-mcp ${VERSION}\n`)
   process.exit(0)

package/lib/edge_extract.mjs

@@ -216,22 +216,104 @@ export function extractSession(transcript) {
     '\n\n--- SESSION ---\n' + text.slice(0, 12000) + '\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 null
+  if (!acquireSummaryLock()) return edgeSkip('busy', 'another session is summarizing; the tail ships instead')
   try {
     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 },
     )
-    if (r.status !== 0 || !r.stdout) return null
-    return parseEdgeJson(r.stdout.trim())
-  } catch {
-    return null
+    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
+  } catch (e) {
+    return edgeSkip('threw', e instanceof Error ? e.message : String(e))
   } finally {
     releaseSummaryLock()
   }
 }
 
+// ── WHY THE EXTRACTION DID NOT RUN ───────────────────────────────────────────────────────────────
+//
+// Every failure path here returns null, and the caller correctly treats null as "ship the transcript
+// tail and let the server summarize". That fallback is right. What was wrong is that FIVE different
+// failures were indistinguishable, and one of them never fixes itself.
+//
+// 🔴 THE EVIDENCE. Found 2026-09-08: `claude --print` had been exiting 1 with
+// "Failed to authenticate: OAuth session expired and could not be refreshed" — so edge extraction
+// returned null for EVERY session, on every seat with an expired token. Nothing said so anywhere.
+// It was invisible because the fallback works: 51 of 51 `claude-code` records over the preceding ten
+// days carried a summary, because the SERVER wrote them. A green outcome over a dead mechanism.
+//
+// Two things were silently untrue for however long that lasted:
+//   1. this module's own header — "the cloud then receives only the derived digest, never the raw
+//      transcript" — since the fallback ships the (redacted) tail instead;
+//   2. anything downstream of the extraction, including ADR-0055's page proposals, which cannot
+//      exist if the call that would make them never returns.
+//
+// A busy lock and an expired credential are not the same event: the first resolves itself on the
+// 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.
+function edgeSkip(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`)
+  return null
+}
+
+/**
+ * PURE (unit-tested): classify a finished `claude --print` result, or null when it succeeded.
+ *
+ * Exported so the failure taxonomy is testable without spawning anything — the auth case in
+ * particular could not otherwise be covered, and it is the one that matters most.
+ */
+export function classifyEdgeFailure(r) {
+  if (!r) return { reason: 'no-result', detail: 'spawn returned nothing' }
+  // spawn itself failed — almost always ENOENT, i.e. `claude` is not on the hook's PATH. A Stop hook
+  // runs with a login shell's PATH, which is not always the interactive one.
+  if (r.error) {
+    if (r.error.code === 'ENOENT') {
+      return { reason: 'no-claude', detail: '`claude` is not on PATH for this hook; edge extraction cannot run here' }
+    }
+    // ⚠ A spawnSync TIMEOUT surfaces here, as error.code ETIMEDOUT — not only as a signal. Observed
+    // live 2026-09-08: `[spawn-failed] spawnSync claude ETIMEDOUT` at 47.3s against a 45s limit,
+    // which reads as "the spawn broke" when the truth is "it ran and was too slow". Checking the
+    // signal alone missed it, so both are checked; this classifier's own first outing found this.
+    if (r.error.code === 'ETIMEDOUT') {
+      return { reason: 'timeout', detail: `exceeded ${summaryTimeoutMs()}ms` }
+    }
+    return { reason: 'spawn-failed', detail: r.error.message }
+  }
+  // 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` }
+
+  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:
+  //   status 1, stderr "", stdout "Failed to authenticate: OAuth session expired and could not be
+  //   refreshed". Matching only stderr would classify this as a plain non-zero exit and lose the one
+  //   fact that tells a human what to do.
+  if (/oauth|authenticat|not logged in|401|unauthorized/i.test(out)) {
+    return {
+      reason: 'auth-expired',
+      detail: 'the subscription login for headless `claude --print` is dead. Run `claude setup-token`, '
+        + 'then set CLAUDE_CODE_OAUTH_TOKEN in ~/.claude/settings.json (env). '
+        + 'Until then EVERY session ships its transcript tail to the server instead of a local digest, '
+        + '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
+}
+
+function firstLine(s) {
+  return String(s ?? '').split('\n').map((l) => l.trim()).filter(Boolean)[0] ?? '(no output)'
+}
+
 // Tolerant JSON extraction: the model may wrap output in prose / ```json fences, so grab the first
 // balanced-looking {...} span. Arrays pass through untouched — the SERVER validates them.
 export function parseEdgeJson(out) {

package/package.json

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