@theronap/cortex-mcp 0.9.74 → 0.9.76

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

@@ -719,7 +719,14 @@ export async function runServer(version) {
       }
       const out = await res.json().catch(() => null)
       if (!res.ok) return toolError(`Could not roll back "${name}": ${out?.error ?? res.status}`)
-      return { content: [{ type: 'text', text: `Done — "${name}" ${out.note}. \`read_page "${name}"\` to confirm the current content.` }] }
+      // #477: when the target revision had no summary, the page's CURRENT summary was kept rather than
+      // erased. Say it on its own line instead of at the tail of `note` — this is the 2026-08-04 W3
+      // shape, where empty summaries copied over populated ones destroyed 31 of them under a report
+      // that read as success. A rescue the operator does not see is still a silent write.
+      const keptLine = out.summaryKept === 'current'
+        ? `\n\n⚠ That revision had NO summary, so the page's current summary was KEPT rather than erased — check it still describes the restored body, and use set_summary if not.`
+        : ''
+      return { content: [{ type: 'text', text: `Done — "${name}" ${out.note}. \`read_page "${name}"\` to confirm the current content.${keptLine}` }] }
     },
   )
 

package/lib/skills.mjs

@@ -265,22 +265,65 @@ export async function syncOrgSkills(opts = {}) {
   return summary
 }
 
-// `skills push <file>` / `skills push --disable <name>` / `skills push --enable <name>` —
-// publish or toggle an org skill (owner/manager/admin; the server enforces the role).
-async function runSkillsPush(argv) {
+// Render a failed push. THE SERVER ALREADY ANSWERED THE QUESTION — brain_choice_response.ts builds a
+// body carrying a full `message` plus every brain's NAME, PAGE COUNT and SAMPLE TITLES, explicitly so
+// the caller can choose "by what each one HOLDS, not by which name sounds related". This function
+// existed as `body.error ?? HTTP ${status}`, which printed the bare code `brain_required` and threw
+// all of that away — the user saw a two-word error with no notion of what a brain is, which ones they
+// have, or what to type next. Pure + exported so the shape is unit-testable without a network.
+export function renderPushError(body, status) {
+  const lines = [body?.message ?? body?.error ?? `HTTP ${status}`]
+  const brains = Array.isArray(body?.brains) ? body.brains : []
+  if (brains.length) {
+    lines.push('', '  Your brains:')
+    for (const b of brains) {
+      const pages = typeof b?.pageCount === 'number' ? ` — ${b.pageCount} page${b.pageCount === 1 ? '' : 's'}` : ''
+      const titles = Array.isArray(b?.sampleTitles) && b.sampleTitles.length
+        ? `: ${b.sampleTitles.slice(0, 2).join('; ')}` : ''
+      lines.push(`    ${b?.name ?? b?.orgId ?? '(unnamed)'}${pages}${titles}`)
+    }
+    lines.push('', '  Re-run with --brain "<name>".')
+  }
+  return lines.join('\n')
+}
+
+// `skills push <file> [--brain <name>]` / `skills push --disable <name> [--brain <name>]` /
+// `skills push --enable <name> [--brain <name>]` — publish or toggle an org skill
+// (owner/manager/admin; the server enforces the role).
+//
+// ⚠ --brain IS NOT OPTIONAL FOR A MULTI-BRAIN CALLER, and until 2026-08-08 there was no way to pass
+// it. Publishing MODIFIES one brain, so the server correctly uses ADR-0022's `requireBrain` half and
+// refuses to guess — but this command sent no `brain`, so every push and every --disable from a
+// multi-brain account died on `brain_required` with no way forward. Confirmed against production:
+// `skills push --disable cortex-author-docs` → `✗ brain_required`, full stop.
+//
+// This is the WRITE twin of the GET bug fixed in #467. The read was miscategorised and now fans out;
+// the write was categorised correctly and simply had no input for the answer it demanded.
+export async function runSkillsPush(argv) {
   const { resolveBase, readWiredToken, fetchCortex } = await import('./diagnose.mjs')
   const token = process.env.CORTEX_TOKEN || readWiredToken()
   if (!token) { process.stderr.write('No Agnoclast token wired — run setup first.\n'); return 1 }
   const base = resolveBase(process.env.CORTEX_URL)
 
+  const brainIdx = argv.findIndex((a) => a === '--brain')
+  const brain = brainIdx === -1 ? null : argv[brainIdx + 1]
+  if (brainIdx !== -1 && (!brain || brain.startsWith('-'))) {
+    process.stderr.write('Usage: skills push … --brain <name>  (missing brain name)\n')
+    return 1
+  }
+  // Strip --brain AND its value before any positional parsing below. The value does not start with
+  // '-', so the `argv.find(a => !a.startsWith('-'))` file lookup would otherwise take it as the
+  // SKILL.md path and push the wrong thing.
+  const rest = brainIdx === -1 ? argv : argv.filter((_, i) => i !== brainIdx && i !== brainIdx + 1)
+
   let payload
-  const toggleIdx = argv.findIndex((a) => a === '--disable' || a === '--enable')
+  const toggleIdx = rest.findIndex((a) => a === '--disable' || a === '--enable')
   if (toggleIdx !== -1) {
-    const name = argv[toggleIdx + 1]
-    if (!name) { process.stderr.write(`Usage: skills push ${argv[toggleIdx]} <name>\n`); return 1 }
-    payload = { name, enabled: argv[toggleIdx] === '--enable' }
+    const name = rest[toggleIdx + 1]
+    if (!name) { process.stderr.write(`Usage: skills push ${rest[toggleIdx]} <name>\n`); return 1 }
+    payload = { name, enabled: rest[toggleIdx] === '--enable' }
   } else {
-    const file = argv.find((a) => !a.startsWith('-'))
+    const file = rest.find((a) => !a.startsWith('-'))
     if (!file || !existsSync(file)) { process.stderr.write('Usage: skills push <SKILL.md>  (file not found)\n'); return 1 }
     const body_md = readFileSync(file, 'utf8')
     const name = frontmatterName(body_md, '').toLowerCase()
@@ -292,13 +335,14 @@ async function runSkillsPush(argv) {
   }
 
   try {
-    const res = await fetchCortex(`${base}/api/skills`, {
+    const qs = brain ? `?brain=${encodeURIComponent(brain)}` : ''
+    const res = await fetchCortex(`${base}/api/skills${qs}`, {
       method: 'POST',
       headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
       body: JSON.stringify(payload),
     })
     const body = await res.json().catch(() => ({}))
-    if (!res.ok) { process.stderr.write(`✗ ${body.error ?? `HTTP ${res.status}`}\n`); return 1 }
+    if (!res.ok) { process.stderr.write(`✗ ${renderPushError(body, res.status)}\n`); return 1 }
     process.stdout.write(
       payload.body_md
         ? `✓ published "${payload.name}" to your org — every seat installs it on next session start.\n`

package/package.json

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