@theronap/cortex-mcp 0.9.73 → 0.9.75

package/lib/diagnose.mjs

@@ -215,6 +215,41 @@ export async function checkToken(token, base) {
   return { ok: true, status: 200, projectCount, requestId }
 }
 
+// Probe the org-skills surface. SEPARATE FROM checkToken ON PURPOSE.
+//
+// WHY THIS EXISTS. `doctor` checked exactly one endpoint — /api/mcp-context — and reported PASS on
+// the strength of it. Meanwhile /api/skills answered 409 to every multi-brain caller for three days
+// (measured 2026-08-08: 14 requests, 14 × 409, zero successes; the local cache sat frozen from Aug 5
+// to Aug 8). Org-published skills silently never installed, the client swallowed the status, and
+// doctor — the tool setup.txt tells people to run FIRST when something is wrong — said everything
+// was fine, every single time. A check that probes one surface is a health check for that surface,
+// not for the system, and must not be reported as the latter.
+//
+// Returns checkToken's shape so the caller renders both the same way. `skillCount` is
+// informational: an org with zero published skills is perfectly healthy, so it is NOT a failure.
+export async function checkSkills(token, base) {
+  if (!token || !isUuid(token)) {
+    return { ok: false, status: 0, diagnosis: { kind: 'config', retriable: false,
+      message: 'no usable token — the context check above already covers this' } }
+  }
+  const url = `${(base ?? CANONICAL_BASE).replace(/\/$/, '')}/api/skills`
+  let res
+  try {
+    res = await fetchCortex(url, { headers: { Authorization: `Bearer ${token}` } })
+  } catch (e) {
+    return { ok: false, status: 0, diagnosis: { kind: 'network', retriable: true, message: e.message } }
+  }
+  const requestId = res.headers.get('x-vercel-id') ?? null
+  const contentType = res.headers.get('content-type')
+  const body = await res.text()
+  if (!res.ok) {
+    return { ok: false, status: res.status, requestId, diagnosis: classify(res.status, contentType, body, requestId) }
+  }
+  let skillCount
+  try { skillCount = (JSON.parse(body)?.skills ?? []).length } catch { /* shape drift — non-fatal */ }
+  return { ok: true, status: 200, skillCount, requestId }
+}
+
 // Release the keep-alive sockets the global fetch (undici) holds, so a short-lived CLI command
 // can tear down cleanly. Without this, calling process.exit() right after a fetch can race a
 // lingering socket handle and trip a libuv assertion on Windows

package/lib/doctor.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
-import { checkToken, resolveBase } from './diagnose.mjs'
+import { checkToken, checkSkills, resolveBase } from './diagnose.mjs'
 
 // `npx @theronap/cortex-mcp doctor` — a live, one-command health check.
 //
@@ -64,9 +64,33 @@ export async function runDoctor() {
   const r = await checkToken(token, base)
 
   if (r.ok) {
-    out('  ✓ PASS — your token authenticates and Agnoclast returned your context.')
+    out('  ✓ context   — your token authenticates and Agnoclast returned your context.')
     if (typeof r.projectCount === 'number') out(`    You can currently see ${r.projectCount} project(s).`)
     if (r.requestId) out(`    (request id: ${r.requestId})`)
+
+    // A SECOND surface, because one endpoint answering is not "the system is healthy". /api/skills
+    // 409'd every multi-brain caller for three days while this command printed PASS on the strength
+    // of /api/mcp-context alone. See checkSkills' header for the full record.
+    const s = await checkSkills(token, base)
+    if (s.ok) {
+      const n = typeof s.skillCount === 'number'
+        ? ` (${s.skillCount} org skill${s.skillCount === 1 ? '' : 's'} published)` : ''
+      out(`  ✓ skills    — the org-skill surface answers${n}.`)
+    } else {
+      // NOT a total failure — context works, so capture and retrieval are fine. But it must never
+      // again render as PASS, because org skills silently stop updating when this breaks.
+      out(`  ✗ skills    — ${s.diagnosis?.kind ?? 'error'}${s.status ? ` (HTTP ${s.status})` : ''}`)
+      out(`    ${s.diagnosis?.message ?? 'unknown error'}`)
+      out('')
+      out('  ⚠ PARTIAL — your connection is fine and capture/retrieval work, but org-published')
+      out('    skills cannot be fetched, so they will silently stop updating (the client falls')
+      out('    back to its last-good cache). Report this rather than ignoring it.')
+      out('')
+      return 1
+    }
+
+    out('')
+    out('  ✓ PASS — every surface checked is answering.')
     out('')
     out('  If your AI still does not see Agnoclast, the server just is not loaded yet —')
     out('  fully quit and reopen Claude Code (the MCP server starts on launch).')

package/lib/skills.mjs

@@ -160,16 +160,37 @@ export function installSkills(opts = {}) {
   return summary
 }
 
-// Decide what to install from a served org-skill list: drop invalid names and bundled collisions
-// (bundled wins — core skills are inalterable). Pure, so it's unit-testable without a network.
+// Decide what to install from a served org-skill list: drop invalid names, bundled collisions
+// (bundled wins — core skills are inalterable) and cross-brain collisions. Pure, so it's
+// unit-testable without a network.
 export function planOrgInstall(served, bundledNames) {
   const bundled = new Set(bundledNames)
   const install = []
   const skipped = []
+
+  // /api/skills now fans out across EVERY brain the caller belongs to (ADR-0022 acrossMyBrains), so
+  // for the first time two brains can serve the SAME skill name. Installing both would write one
+  // file twice and silently leave whichever landed last — an executable body from a brain the user
+  // never chose. There is no principled winner, so a cross-brain collision installs NEITHER and says
+  // so, matching how a bundled collision already resolves: when in doubt, do not install.
+  const byName = new Map()
+  for (const s of served ?? []) {
+    const n = (s?.name ?? '').trim()
+    if (!byName.has(n)) byName.set(n, [])
+    byName.get(n).push(s)
+  }
+
   for (const s of served ?? []) {
     const name = (s?.name ?? '').trim()
     if (!NAME_RE.test(name) || typeof s?.body_md !== 'string' || !s.body_md.trim()) { skipped.push({ name: name || '(unnamed)', why: 'invalid' }); continue }
     if (bundled.has(name)) { skipped.push({ name, why: 'collides with a bundled core skill' }); continue }
+    const dupes = byName.get(name) ?? []
+    if (dupes.length > 1) {
+      // Name the brains so the owner knows which to rename. `brain` is the tag acrossMyBrains adds.
+      const brains = [...new Set(dupes.map((d) => d?.brain).filter(Boolean))]
+      skipped.push({ name, why: `published by ${dupes.length} brains (${brains.join(', ') || 'unknown'}) — rename one; installing neither` })
+      continue
+    }
     install.push({ name, source: s.body_md })
   }
   return { install, skipped }
@@ -201,6 +222,13 @@ export async function syncOrgSkills(opts = {}) {
     if (res.ok) {
       served = (await res.json())?.skills ?? []
       summary.source = 'server'
+    } else {
+      // ⚠ DO NOT MAKE THIS SILENT AGAIN. `if (res.ok)` alone is how a 100% failure hid for weeks:
+      // /api/skills answered 409 to every multi-brain caller, this fell through to the cache below,
+      // and the only log line ('unreachable and no cache') does NOT print when a cache exists. So
+      // org skills silently stopped updating and nothing anywhere said so. Fail-soft is right —
+      // SessionStart must not break — but fail-soft is not fail-quiet.
+      log(`  · org skills: server said ${res.status} — using last-good cache. Run \`doctor\` if this persists.`)
     }
   } catch { /* fall through to cache */ }
   if (!served && Array.isArray(cache?.skills)) { served = cache.skills; summary.source = 'cache' }

package/package.json

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