@theronap/cortex-mcp 0.9.137 → 0.9.138

package/lib/edge_extract.mjs

@@ -216,22 +216,96 @@ 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) {
+    return r.error.code === 'ENOENT'
+      ? { reason: 'no-claude', detail: '`claude` is not on PATH for this hook; edge extraction cannot run here' }
+      : { reason: 'spawn-failed', detail: r.error.message }
+  }
+  // timeout: spawnSync kills the child, so status is null and signal is 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.138",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {