@theronap/cortex-mcp 0.9.59 → 0.9.61

package/bin/cortex-mcp.mjs

@@ -36,11 +36,13 @@ if (cmd === '--version' || cmd === '-v') {
 if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
   process.stdout.write(
     `cortex-mcp ${VERSION} — connect your AI assistant to Cortex\n\n` +
-    `Onboard (one command):\n` +
-    `  npx -y @theronap/cortex-mcp setup <YOUR_TOKEN>\n\n` +
-    `This wires your Claude config so your AI sees your Cortex context and your\n` +
-    `sessions flow into the org automatically. Restart Claude Code after.\n\n` +
+    `Onboard (one command, no token to copy):\n` +
+    `  npx -y @theronap/cortex-mcp login\n\n` +
+    `This opens your browser, you click Approve, and it wires everything up. Restart\n` +
+    `Claude Code after, and your AI sees your Cortex context while your sessions flow\n` +
+    `into the org automatically.\n\n` +
     `Subcommands:\n` +
+    `  login [--label <name>]  browser-approved sign-in — gets a token for you, then runs setup\n` +
     `  setup <token>   wire MCP server + capture hook into ~/.claude config (single editor)\n` +
     `  install [<token>] [--editor auto|all|<id,...>]  wire Cortex into EVERY detected editor + write the capability manifest\n` +
     `  repair          re-run setup at the latest version using your existing token (no token needed)\n` +
@@ -68,7 +70,14 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
 // A graceful drain lets libuv finish those handles first, so the assertion never fires. The MCP
 // server (default branch) runs forever and never reaches an exit path. if/else so the CLI
 // commands don't fall through into the server.
-if (cmd === 'setup') {
+if (cmd === 'login') {
+  // Browser-approved sign-in: no token to copy. Ends by calling runSetup with the token it
+  // collected, so there is still exactly ONE code path that writes a credential to disk.
+  const { runLogin } = await import('../lib/login.mjs')
+  await runLogin(rest, VERSION)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'setup') {
   const { runSetup } = await import('../lib/setup.mjs')
   await runSetup(rest, VERSION)
   const { closeFetch } = await import('../lib/diagnose.mjs')

package/lib/login.mjs

@@ -0,0 +1,148 @@
+import os from 'node:os'
+import { spawn } from 'node:child_process'
+import { resolveBase, CANONICAL_BASE } from './diagnose.mjs'
+
+// `cortex-mcp login` — get a token without the human copy-pasting one out of the web console.
+//
+// WHY THIS EXISTS: the old path was log into the console, find /connect, copy a uuid, paste it into
+// a terminal. That copy-paste is the step that failed on the first non-technical onboarding
+// (2026-08-03), and it is the reason there could never be a real one-line install. Here the person
+// clicks Approve in a browser and types nothing.
+//
+// THE FLOW (server side: /api/device/{start,approve,exchange}):
+//   1. start    — we generate nothing; the server issues a device_code (our secret) + a short
+//                 user_code, and we open the pre-filled approval URL.
+//   2. approve  — happens in their browser, against their login. We never see their password and
+//                 never handle a JWT.
+//   3. exchange — we poll with the device_code; once a human has approved, the token is minted and
+//                 returned exactly once. Then we hand straight off to the normal `setup` wiring.
+//
+// Deliberately a DEVICE flow rather than a loopback redirect. Loopback needs a local port and an
+// open browser on the same machine, so it dies over SSH and on locked-down laptops. With the URL
+// pre-filled, the device flow costs the user the same single click and works everywhere.
+
+/** Open a URL in the user's default browser. Best-effort: never throws, never blocks the flow. */
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '""', url] : [url]
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true })
+    // If the browser cannot be launched we still printed the URL, so this is genuinely non-fatal.
+    child.on('error', () => {})
+    child.unref()
+    return true
+  } catch {
+    return false
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+/** A label the person will recognise on the approval screen. Machine name, not a user name. */
+function deviceLabel() {
+  const host = os.hostname().replace(/\.local$/i, '')
+  return host || `${os.platform()} device`
+}
+
+export async function runLogin(argv = [], version = 'dev') {
+  const base = resolveBase(process.env.CORTEX_URL) || CANONICAL_BASE
+
+  // --label lets a person running several machines tell them apart later; account_tokens.label
+  // carries it, so it survives long after the grant row is swept.
+  const labelFlag = argv.indexOf('--label')
+  const label = labelFlag !== -1 && argv[labelFlag + 1] ? argv[labelFlag + 1] : deviceLabel()
+
+  let start
+  try {
+    const res = await fetch(`${base}/api/device/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ label }),
+    })
+    if (!res.ok) throw new Error(`server said ${res.status}`)
+    start = await res.json()
+  } catch (err) {
+    process.stderr.write(
+      `cortex: could not reach ${base} to start login (${err.message}).\n` +
+        `Check your connection, then try again.\n`,
+    )
+    process.exitCode = 1
+    return
+  }
+
+  const opened = openBrowser(start.verificationUriComplete)
+
+  process.stdout.write(
+    `\n  Confirm this code in your browser:  ${start.userCode}\n\n` +
+      (opened
+        ? `  A browser should have opened. If not, go to:\n    ${start.verificationUriComplete}\n\n`
+        : `  Open this in your browser:\n    ${start.verificationUriComplete}\n\n`) +
+      `  Waiting for you to approve it...\n`,
+  )
+
+  // Poll until approved or the grant expires. The server sets the pace (and says slow_down if we
+  // are early), so the cadence stays server-controlled rather than hardcoded here.
+  let interval = (start.interval ?? 2) * 1000
+  const deadline = Date.now() + (start.expiresIn ?? 600) * 1000
+  let token = null
+  let activeOrgId = null
+
+  while (Date.now() < deadline) {
+    await sleep(interval)
+    let res
+    try {
+      res = await fetch(`${base}/api/device/exchange`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deviceCode: start.deviceCode }),
+      })
+    } catch {
+      continue // transient network blip: keep waiting rather than failing a login mid-approval
+    }
+
+    if (res.status === 429) {
+      interval = Math.min(interval * 2, 10_000) // back off, do not give up
+      continue
+    }
+    if (res.status === 410) {
+      process.stderr.write(`\ncortex: that took too long and the code expired. Run login again.\n`)
+      process.exitCode = 1
+      return
+    }
+    if (res.status === 409 || res.status === 404) {
+      const body = await res.json().catch(() => ({}))
+      process.stderr.write(`\ncortex: ${body.error ?? 'this login is no longer valid'}. Run login again.\n`)
+      process.exitCode = 1
+      return
+    }
+    if (!res.ok) continue
+
+    const body = await res.json().catch(() => ({}))
+    if (body.status === 'approved' && body.personalToken) {
+      token = body.personalToken
+      activeOrgId = body.activeOrgId ?? null
+      break
+    }
+    // 'pending' — the human has not clicked yet. Keep waiting quietly; a spinner that reprints
+    // every two seconds is noise on the one screen where the person is reading instructions.
+  }
+
+  if (!token) {
+    process.stderr.write(`\ncortex: nobody approved that login before it expired. Run login again.\n`)
+    process.exitCode = 1
+    return
+  }
+
+  process.stdout.write(`\n  Approved. Setting up...\n\n`)
+
+  // Hand the raw token straight to the existing installer. We never write it anywhere ourselves —
+  // runSetup owns every file that touches a credential, so there is exactly one code path that
+  // stores a token and one place to audit.
+  const { runSetup } = await import('./setup.mjs')
+  await runSetup([token], version)
+
+  if (activeOrgId) {
+    process.stdout.write(`  New pages will be saved in the space you picked.\n`)
+  }
+}

package/lib/server.mjs

@@ -28,6 +28,18 @@ async function redLinkTriage(BASE, TOKEN, name) {
   }
 }
 
+// MCP tool results carry an `isError` flag, and a failure that omits it is indistinguishable from a
+// success at the protocol level — the caller just sees a normal result whose text happens to begin
+// "Could not". This file had 41 tools, 64 failure returns and ZERO uses of isError, so nothing
+// downstream could tell a rejected write from a completed one. Measured 2026-07-31: a walker over
+// 397 transcripts scored 18 REJECTED `author` calls as successful writes for exactly this reason,
+// and an agent skimming its own tool result is exposed the same way. Route every failure through
+// here so the flag cannot be forgotten at a new call site.
+//
+// NAME: deliberately not `fail` — runServer already has a local `fail(verb, res)` for the
+// file-request tools, and a module-level `fail` would be silently shadowed by it from that point on.
+const toolError = (text) => ({ content: [{ type: 'text', text }], isError: true })
+
 // The Cortex MCP server (stdio). Serves the signed-in employee's scoped org
 // context to their AI assistant. CORTEX_TOKEN identifies the user + org.
 
@@ -406,12 +418,12 @@ export async function runServer(version) {
           if (vr.status === 404) return { content: [{ type: 'text', text: `No version "${version}" for "${name}" (or you can't see it). Use page_history "${name}" to list its versions.` }] }
           if (!vr.ok) {
             const d = classify(vr.status, vr.headers.get('content-type'), await vr.text(), vr.headers.get('x-vercel-id'))
-            return { content: [{ type: 'text', text: `Could not read version "${version}" of "${name}": ${d.message}` }] }
+            return toolError(`Could not read version "${version}" of "${name}": ${d.message}`)
           }
           const v = await vr.json()
           return { content: [{ type: 'text', text: `# ${name} — historical version (rev ${v.revNo} · ${v.op} · ${String(v.createdAt).slice(0, 10)} · ${v.tier})\nversion: ${v.version}\n\n${v.body}\n\n— This is a HISTORICAL snapshot, not the current page. \`read_page "${name}"\` (no version) shows what's live; \`rollback_page\` restores this one as a new version.` }] }
         } catch (e) {
-          return { content: [{ type: 'text', text: `Could not read version "${version}" of "${name}": ${e.message}` }] }
+          return toolError(`Could not read version "${version}" of "${name}": ${e.message}`)
         }
       }
       // PER-NODE TIMELINE (slice 4): history = the projection over the node's identifier stamps.
@@ -422,7 +434,7 @@ export async function runServer(version) {
           if (r.status === 404) return { content: [{ type: 'text', text: `No ${k} named "${name}" — cannot project a timeline.` }] }
           if (!r.ok) {
             const d = classify(r.status, r.headers.get('content-type'), await r.text(), r.headers.get('x-vercel-id'))
-            return { content: [{ type: 'text', text: `Could not read the timeline for "${name}": ${d.message}` }] }
+            return toolError(`Could not read the timeline for "${name}": ${d.message}`)
           }
           const t = await r.json()
           if (!t.identifiers?.length) {
@@ -435,7 +447,7 @@ export async function runServer(version) {
           if (t.siblings?.length) lines.push(`Sibling homes (share a stamp — bridges, not history): ${t.siblings.map((s) => `"${s.title}"`).join(', ')}`)
           return { content: [{ type: 'text', text: lines.join('\n') }] }
         } catch (e) {
-          return { content: [{ type: 'text', text: `Could not read the timeline for "${name}": ${e.message}` }] }
+          return toolError(`Could not read the timeline for "${name}": ${e.message}`)
         }
       }
       // IDENTIFIER RESOLUTION (slice 3): an identifier-shaped name is a JOIN KEY, not a page — resolve
@@ -474,14 +486,14 @@ export async function runServer(version) {
         res = await fetchCortex(`${BASE}/api/brain/page?kind=${k}&key=${encodeURIComponent(name)}`,
           { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not read "${name}": ${e.message}` }] }
+        return toolError(`Could not read "${name}": ${e.message}`)
       }
       if (res.status === 404) {
         return { content: [{ type: 'text', text: `No ${k} page named "${name}". If it's a person or team, pass kind (person/org).${await redLinkTriage(BASE, TOKEN, name)}` }] }
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not read "${name}": ${d.message}` }] }
+        return toolError(`Could not read "${name}": ${d.message}`)
       }
       const page = await res.json()
       // Multi-brain (decision 3A): /api/brain/page returns matches[] — one entry per brain that has a
@@ -559,12 +571,12 @@ export async function runServer(version) {
         const qs = new URLSearchParams({ kind: k, key: name, ...(limit ? { limit: String(limit) } : {}) })
         res = await fetchCortex(`${BASE}/api/brain/page-history?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not read history for "${name}": ${e.message}` }] }
+        return toolError(`Could not read history for "${name}": ${e.message}`)
       }
       if (res.status === 404) return { content: [{ type: 'text', text: `No ${k} named "${name}". Pass kind (person/org) if it isn't a project.` }] }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not read history for "${name}": ${d.message}` }] }
+        return toolError(`Could not read history for "${name}": ${d.message}`)
       }
       const out = await res.json()
       const revs = out.revisions ?? []
@@ -612,12 +624,12 @@ export async function runServer(version) {
         })
         res = await fetchCortex(`${BASE}/api/brain/page-diff?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not diff "${name}": ${e.message}` }] }
+        return toolError(`Could not diff "${name}": ${e.message}`)
       }
       if (res.status === 404) return { content: [{ type: 'text', text: `No ${k} named "${name}", or it has no version "${to}". Run \`page_history "${name}"\` to list its versions.` }] }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not diff "${name}": ${d.message}` }] }
+        return toolError(`Could not diff "${name}": ${d.message}`)
       }
       const out = await res.json()
       const d = out.diff
@@ -669,10 +681,10 @@ export async function runServer(version) {
           body: JSON.stringify({ kind: k, name, to_version, ...(tier ? { tier } : {}), ...(reason ? { reason } : {}) }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not roll back "${name}": ${e.message}` }] }
+        return toolError(`Could not roll back "${name}": ${e.message}`)
       }
       const out = await res.json().catch(() => null)
-      if (!res.ok) return { content: [{ type: 'text', text: `Could not roll back "${name}": ${out?.error ?? res.status}` }] }
+      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.` }] }
     },
   )
@@ -705,7 +717,7 @@ export async function runServer(version) {
           }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not rename the section: ${e.message}` }] }
+        return toolError(`Could not rename the section: ${e.message}`)
       }
       const out = await res.json().catch(() => null)
       if (!res.ok) {
@@ -718,7 +730,7 @@ export async function runServer(version) {
           out?.currentVersion ? `current version: ${out.currentVersion}` : '',
         ].filter(Boolean).join(' · ')
         const hint = out?.hint ? `\n${out.hint}` : ''
-        return { content: [{ type: 'text', text: `Could not rename "${from}" on "${name}": ${out?.error ?? res.status}${extra ? `\n${extra}` : ''}${hint}` }] }
+        return toolError(`Could not rename "${from}" on "${name}": ${out?.error ?? res.status}${extra ? `\n${extra}` : ''}${hint}`)
       }
       return { content: [{ type: 'text', text: `Renamed on "${name}" (${out.brain} · ${out.tier} tier): "${out.from}" -> "${out.to}". The section kept its body, position and as-of date. New version: ${out.version}` }] }
     },
@@ -753,7 +765,7 @@ export async function runServer(version) {
           }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not edit "${name}": ${e.message}` }] }
+        return toolError(`Could not edit "${name}": ${e.message}`)
       }
       const out = await res.json().catch(() => null)
       if (!res.ok) {
@@ -784,7 +796,7 @@ export async function runServer(version) {
           Array.isArray(out?.concurrentRemoved) && out.concurrentRemoved.length ? `sections REMOVED elsewhere: ${out.concurrentRemoved.join(', ')}` : '',
           Array.isArray(out?.concurrentTruncated) && out.concurrentTruncated.length ? `(truncated, see page_diff for all of: ${out.concurrentTruncated.join(', ')})` : '',
         ].filter(Boolean).join('\n')
-        return { content: [{ type: 'text', text: `Could not edit "${name}": ${out?.error ?? res.status}${out?.hint ? `\n${out.hint}` : ''}${bits ? `\n${bits}` : ''}${ccMeta ? `\n${ccMeta}` : ''}${cc}${cur}` }] }
+        return toolError(`Could not edit "${name}": ${out?.error ?? res.status}${out?.hint ? `\n${out.hint}` : ''}${bits ? `\n${bits}` : ''}${ccMeta ? `\n${ccMeta}` : ''}${cc}${cur}`)
       }
       const red = Array.isArray(out.redLinks) && out.redLinks.length
         ? `\nRed-links now on this page: ${out.redLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
@@ -804,11 +816,11 @@ export async function runServer(version) {
       try {
         res = await fetchCortex(`${BASE}/api/style`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not load writing style: ${e.message}` }] }
+        return toolError(`Could not load writing style: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not load writing style: ${d.message}` }] }
+        return toolError(`Could not load writing style: ${d.message}`)
       }
       const { style } = await res.json()
       return { content: [{ type: 'text', text: style }] }
@@ -831,11 +843,11 @@ export async function runServer(version) {
           body: JSON.stringify({ style_md }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not save writing style: ${e.message}` }] }
+        return toolError(`Could not save writing style: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not save writing style: ${d.message}` }] }
+        return toolError(`Could not save writing style: ${d.message}`)
       }
       const r = await res.json()
       return { content: [{ type: 'text', text: r.saved ? `Saved your writing-style profile (${r.chars} chars).` : 'Cleared your writing-style profile.' }] }
@@ -854,11 +866,11 @@ export async function runServer(version) {
       try {
         res = await fetchCortex(`${BASE}/api/brains`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not list brains: ${e.message}` }] }
+        return toolError(`Could not list brains: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not list brains: ${d.message}` }] }
+        return toolError(`Could not list brains: ${d.message}`)
       }
       const { brains, activeIsExplicit, activeSource, sessionOrgId, accountOrgId } = await res.json()
       if (!brains?.length) return { content: [{ type: 'text', text: 'You have no brains.' }] }
@@ -898,11 +910,11 @@ export async function runServer(version) {
       try {
         res = await fetchCortex(`${BASE}/api/brains/pages?orgId=${encodeURIComponent(org_id)}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not list pages: ${e.message}` }] }
+        return toolError(`Could not list pages: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not list pages: ${d.message}` }] }
+        return toolError(`Could not list pages: ${d.message}`)
       }
       const { nodeCount, rowCount, pages } = await res.json()
       if (!pages?.length) return { content: [{ type: 'text', text: `Brain ${org_id} has no authored pages.` }] }
@@ -939,11 +951,11 @@ export async function runServer(version) {
           body: JSON.stringify({ orgId: org_id ?? null, scope: scope ?? 'session' }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not set active brain: ${e.message}` }] }
+        return toolError(`Could not set active brain: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not set active brain: ${d.message}` }] }
+        return toolError(`Could not set active brain: ${d.message}`)
       }
       const r = await res.json()
       // Always say WHICH scope changed. The default is session-only, so a caller expecting the old
@@ -974,11 +986,11 @@ export async function runServer(version) {
           body: JSON.stringify({ name }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not create brain: ${e.message}` }] }
+        return toolError(`Could not create brain: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not create brain: ${d.message}` }] }
+        return toolError(`Could not create brain: ${d.message}`)
       }
       const r = await res.json()
       return { content: [{ type: 'text', text: `Created brain "${name}" [${r.orgId}]. Reads already span it. Edits to pages in it route themselves; set_active_brain only if you want NEW pages to default here.` }] }
@@ -1007,11 +1019,11 @@ export async function runServer(version) {
       try {
         res = await fetchCortex(`${BASE}/api/records?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not list records: ${e.message}` }] }
+        return toolError(`Could not list records: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not list records: ${d.message}` }] }
+        return toolError(`Could not list records: ${d.message}`)
       }
       const { text } = await res.json()
       return { content: [{ type: 'text', text }] }
@@ -1039,11 +1051,11 @@ export async function runServer(version) {
       try {
         res = await fetchCortex(`${BASE}/api/records/daily?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not build daily log: ${e.message}` }] }
+        return toolError(`Could not build daily log: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not build daily log: ${d.message}` }] }
+        return toolError(`Could not build daily log: ${d.message}`)
       }
       const { text } = await res.json()
       return { content: [{ type: 'text', text }] }
@@ -1064,11 +1076,11 @@ export async function runServer(version) {
           headers: { Authorization: `Bearer ${TOKEN}` },
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not list your sessions: ${e.message}` }] }
+        return toolError(`Could not list your sessions: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not list your sessions: ${d.message}` }] }
+        return toolError(`Could not list your sessions: ${d.message}`)
       }
       const { text } = await res.json()
       return { content: [{ type: 'text', text }] }
@@ -1094,11 +1106,11 @@ export async function runServer(version) {
           body: JSON.stringify({ privacy }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not set privacy: ${e.message}` }] }
+        return toolError(`Could not set privacy: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not set privacy: ${d.message}` }] }
+        return toolError(`Could not set privacy: ${d.message}`)
       }
       const out = await res.json()
       return { content: [{ type: 'text', text: `Done — record ${out.id} is now "${out.privacy}".` }] }
@@ -1127,11 +1139,11 @@ export async function runServer(version) {
           body: JSON.stringify({ kind, name, validity, modality, superseded_by }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not set validity: ${e.message}` }] }
+        return toolError(`Could not set validity: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not set validity: ${d.message}` }] }
+        return toolError(`Could not set validity: ${d.message}`)
       }
       const out = await res.json()
       return { content: [{ type: 'text', text: `Done — "${out.name}" is now ${out.validity}${out.modality ? ` / ${out.modality}` : ''} (${out.docs_updated} tier-doc(s) updated).` }] }
@@ -1158,10 +1170,10 @@ export async function runServer(version) {
           body: JSON.stringify({ name, target_name, ...(target_kind ? { target_kind } : {}) }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not alias: ${e.message}` }] }
+        return toolError(`Could not alias: ${e.message}`)
       }
       const out = await res.json().catch(() => null)
-      if (!res.ok) return { content: [{ type: 'text', text: `Could not alias "${name}": ${out?.error ?? res.status}` }] }
+      if (!res.ok) return toolError(`Could not alias "${name}": ${out?.error ?? res.status}`)
       if (!out) return { content: [{ type: 'text', text: `Aliased "${name}", but the server returned no body — re-read the page to confirm.` }] }
       return { content: [{ type: 'text', text: `Done — [[${out.alias}]] now resolves to "${out.target}" (${out.target_kind}). It's out of the wanted-page backlog.` }] }
     },
@@ -1186,10 +1198,10 @@ export async function runServer(version) {
           body: JSON.stringify({ name, ...(days ? { days } : {}) }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not snooze: ${e.message}` }] }
+        return toolError(`Could not snooze: ${e.message}`)
       }
       const out = await res.json().catch(() => null)
-      if (!res.ok) return { content: [{ type: 'text', text: `Could not snooze "${name}": ${out?.error ?? res.status}` }] }
+      if (!res.ok) return toolError(`Could not snooze "${name}": ${out?.error ?? res.status}`)
       if (!out) return { content: [{ type: 'text', text: `Snoozed "${name}", but the server returned no body.` }] }
       return { content: [{ type: 'text', text: `Snoozed "${out.name}" for ${out.days} day${out.days === 1 ? '' : 's'} — it won't surface until then.` }] }
     },
@@ -1218,7 +1230,7 @@ export async function runServer(version) {
           body: JSON.stringify({ kind, name, tier, ...(source_tier ? { source_tier } : {}), ...(absorb ? { absorb: true } : {}), ...(target_version ? { target_version } : {}) }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not set page privacy: ${e.message}` }] }
+        return toolError(`Could not set page privacy: ${e.message}`)
       }
       const out = await res.json().catch(() => null)
       if (!res.ok) {
@@ -1228,10 +1240,10 @@ export async function runServer(version) {
           const extra = out.collision === 'readable' && out.blocking
             ? `\nYour ${out.source?.tier} page: ${out.source?.summary ?? out.source?.title}\nExisting ${out.blocking.tier} page (current version: ${out.blocking.version ?? 'none — this page predates content-hash tracking and cannot be re-authored via base_version; ask an admin about a backfill'}): ${out.blocking.summary ?? out.blocking.title}`
             : ''
-          return { content: [{ type: 'text', text: `Could not set page privacy: ${out.error}${extra}` }] }
+          return toolError(`Could not set page privacy: ${out.error}${extra}`)
         }
         const d = classify(res.status, res.headers.get('content-type'), '', res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not set page privacy: ${d.message}` }] }
+        return toolError(`Could not set page privacy: ${d.message}`)
       }
       const g = out.live_grants?.length
         ? ` Grants still active for: ${out.live_grants.map((x) => x.grantee_name ?? x.grantee_user_id).join(', ')}.`
@@ -1262,10 +1274,10 @@ export async function runServer(version) {
           body: JSON.stringify({ kind, name, grantee, action, ...(tier ? { tier } : {}) }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not ${action}: ${e.message}` }] }
+        return toolError(`Could not ${action}: ${e.message}`)
       }
       const out = await res.json().catch(() => null)
-      if (!res.ok) return { content: [{ type: 'text', text: `Could not ${action}: ${out?.error ?? res.status}` }] }
+      if (!res.ok) return toolError(`Could not ${action}: ${out?.error ?? res.status}`)
       const verb = { granted: 'now has access to', already_granted: 'already had access to', revoked: 'no longer has access to', not_granted: 'had no grant on' }[out.action]
       return { content: [{ type: 'text', text: `Done — ${out.grantee} ${verb} the ${out.tier} page.` }] }
     },
@@ -1288,10 +1300,10 @@ export async function runServer(version) {
           headers: { Authorization: `Bearer ${TOKEN}` },
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not list grants: ${e.message}` }] }
+        return toolError(`Could not list grants: ${e.message}`)
       }
       const out = await res.json().catch(() => null)
-      if (!res.ok) return { content: [{ type: 'text', text: `Could not list grants: ${out?.error ?? res.status}` }] }
+      if (!res.ok) return toolError(`Could not list grants: ${out?.error ?? res.status}`)
       if (!out.grants?.length) return { content: [{ type: 'text', text: 'No grants on this page.' }] }
       const lines = out.grants.map((g) => `- ${g.grantee_name ?? g.grantee_user_id} → ${g.tier} variant (since ${String(g.created_at).slice(0, 10)})`)
       return { content: [{ type: 'text', text: `Grants (${out.grants.length}):\n${lines.join('\n')}` }] }
@@ -1310,11 +1322,11 @@ export async function runServer(version) {
       try {
         res = await fetchCortex(`${BASE}/api/brain/retier-notices`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not list notices: ${e.message}` }] }
+        return toolError(`Could not list notices: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not list notices: ${d.message}` }] }
+        return toolError(`Could not list notices: ${d.message}`)
       }
       const { notices } = await res.json()
       if (!notices?.length) return { content: [{ type: 'text', text: 'No re-tier notices.' }] }
@@ -1336,11 +1348,11 @@ export async function runServer(version) {
       try {
         res = await fetchCortex(`${BASE}/api/brain/page-merge-requests`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not list merge requests: ${e.message}` }] }
+        return toolError(`Could not list merge requests: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not list merge requests: ${d.message}` }] }
+        return toolError(`Could not list merge requests: ${d.message}`)
       }
       const { requests } = await res.json()
       if (!requests?.length) return { content: [{ type: 'text', text: 'No pending page merge requests.' }] }
@@ -1369,17 +1381,17 @@ export async function runServer(version) {
           body: JSON.stringify({ id, decision }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not decide: ${e.message}` }] }
+        return toolError(`Could not decide: ${e.message}`)
       }
       const out = await res.json().catch(() => null)
-      if (!res.ok) return { content: [{ type: 'text', text: `Could not decide: ${out?.error ?? res.status}` }] }
+      if (!res.ok) return toolError(`Could not decide: ${out?.error ?? res.status}`)
       return { content: [{ type: 'text', text: out.decision === 'denied' ? 'Denied — nothing moved.' : `Approved — removed variant(s): ${out.removed_variants.join(', ') || 'none remained'}. ${out.note}` }] }
     },
   )
 
   // ── File requests: ask the owner for a record's FULL original (lives on their machine) ──
   const fail = (verb, res) => async () =>
-    ({ content: [{ type: 'text', text: `Could not ${verb}: ${classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id')).message}` }] })
+    toolError(`Could not ${verb}: ${classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id')).message}`)
 
   server.registerTool(
     'request_file',
@@ -1395,7 +1407,7 @@ export async function runServer(version) {
           method: 'POST', headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
           body: JSON.stringify({ recordId: record_id }),
         })
-      } catch (e) { return { content: [{ type: 'text', text: `Could not request: ${e.message}` }] } }
+      } catch (e) { return toolError(`Could not request: ${e.message}`) }
       if (res.status === 409) {
         const j = await res.json().catch(() => ({}))
         if (j.error === 'you_own_it') return { content: [{ type: 'text', text: `You own this record — open the original directly:\n${j.uri}` }] }
@@ -1417,7 +1429,7 @@ export async function runServer(version) {
     async () => {
       let res
       try { res = await fetchCortex(`${BASE}/api/file-requests`, { headers: { Authorization: `Bearer ${TOKEN}` } }) }
-      catch (e) { return { content: [{ type: 'text', text: `Could not load file requests: ${e.message}` }] } }
+      catch (e) { return toolError(`Could not load file requests: ${e.message}`) }
       if (!res.ok) return (await fail('load file requests', res))()
       const { mine, inbox } = await res.json()
       const parts = []
@@ -1441,7 +1453,7 @@ export async function runServer(version) {
           method: 'POST', headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
           body: JSON.stringify({ action: decision }),
         })
-      } catch (e) { return { content: [{ type: 'text', text: `Could not decide: ${e.message}` }] } }
+      } catch (e) { return toolError(`Could not decide: ${e.message}`) }
       if (!res.ok) return (await fail('decide', res))()
       return { content: [{ type: 'text', text: `Request ${decision === 'approve' ? 'approved' : 'denied'}.` }] }
     },
@@ -1457,7 +1469,7 @@ export async function runServer(version) {
     async ({ request_id }) => {
       let res
       try { res = await fetchCortex(`${BASE}/api/file-requests/${request_id}/download`, { headers: { Authorization: `Bearer ${TOKEN}` } }) }
-      catch (e) { return { content: [{ type: 'text', text: `Could not download: ${e.message}` }] } }
+      catch (e) { return toolError(`Could not download: ${e.message}`) }
       if (res.status === 409) return { content: [{ type: 'text', text: 'Not ready — the owner hasn\'t fulfilled this yet. Try again after they approve.' }] }
       if (res.status === 410) return { content: [{ type: 'text', text: 'This file has expired (downloads are available for 7 days). Request it again.' }] }
       if (!res.ok) return (await fail('download', res))()
@@ -1516,11 +1528,11 @@ export async function runServer(version) {
       try {
         res = await fetchCortex(`${BASE}/api/brain/authoring-context?kind=${k}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not fetch authoring context: ${e.message}` }] }
+        return toolError(`Could not fetch authoring context: ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not fetch authoring context: ${d.message}` }] }
+        return toolError(`Could not fetch authoring context: ${d.message}`)
       }
       const { connectionRules, namespace, retiredLinks } = await res.json()
       const ns = Array.isArray(namespace) ? namespace : []
@@ -1571,11 +1583,11 @@ export async function runServer(version) {
           body: JSON.stringify({ kind, name, pages, reason, change_kind }),
         })
       } catch (e) {
-        return { content: [{ type: 'text', text: `Could not author "${name}": ${e.message}` }] }
+        return toolError(`Could not author "${name}": ${e.message}`)
       }
       if (!res.ok) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
-        return { content: [{ type: 'text', text: `Could not author "${name}": ${d.message}` }] }
+        return toolError(`Could not author "${name}": ${d.message}`)
       }
       const out = await res.json()
       const blue = out?.links?.blue ?? 0

package/package.json

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

package/skills/log/SKILL.md

@@ -52,9 +52,8 @@ No arguments. Read the conversation context.
    docs are pending, follow the `cortex-author-docs` skill (author each into its page, then
    `docs-scan --mark`). Specs/plans written to disk this session must not die on disk — a spec IS
    a page. If no roots are registered or nothing is pending, skip silently.
-7. **Reconcile & verify (prove the sweep — don't trust it).** Step 5 relies on your in-the-moment
-   judgment of "what advanced"; this step closes the loop so nothing is silently missed and no stale
-   write slips through. Before printing the Output:
+7. **Reconcile the sweep (don't trust it).** Step 5 relies on your in-the-moment judgment of "what
+   advanced"; this step closes the loop so nothing is silently missed. Before printing the Output:
    a. **Enumerate what you touched** — from the transcript, list the concrete entities this session
       advanced: the project(s), notable files/artifacts, and the people you coordinated with. Derive
       this checklist from what actually *happened*, not from what you remember authoring — the whole
@@ -62,18 +61,21 @@ No arguments. Read the conversation context.
    b. **Assert one outcome per entity** — every item gets exactly `authored [[Page]]` **or**
       `skipped — <reason>` (e.g. "no material change", "not a node", "already current"). Nothing may be
       left unaccounted for. If an entity that genuinely advanced has neither, `author` it now (Step 5).
-   c. **Verify the writes landed and are right** — for each page you claim you authored, `read_page` it
-      (or check `page_history`) and confirm both: (i) **the change applied** — an `author` that returned
-      "no change" when you *intended* an update means it did NOT land (stale `base_version`, wrong
-      brain/namespace, or nothing actually differed) — re-check rather than assume; and (ii) **the page
-      reflects THIS session's first-hand findings**, not a prior you copied forward. This is the
-      read-after-write half of the read-before-write rule — the guard against laundering stale priors
-      into the wiki. Fix a page you can edit; `set_page_validity` on one you can't. (Cross-brain note:
-      `read_page` can resolve a page in another brain that `author` won't write — if a "verify" read
-      looks right but your write reported no-op, run `my_brains` / check `authoring_context` before
-      trusting the read.)
-   Carry the tally into the Output. If any intended write did not land, say so — never report a clean
-   sweep you didn't confirm.
+   Carry the tally into the Output.
+
+   > **A read-back verification sub-step lived here and was REMOVED 2026-07-31. Do not re-add it
+   > without new evidence.** It asked you to `read_page` every page you had just authored, to confirm
+   > the write landed. Measured over 397 local transcripts — 18 sessions that wrote a page,
+   > 2026-07-29→31 — **18 `author` calls were rejected and all 18 were retried to success: zero
+   > silently lost.** An end-of-session pass would have caught nothing, because the rejection reason
+   > arrives *in the tool result at the moment of the call*. Session end is the weakest place to
+   > verify a write; the result you already have in hand is the strongest.
+   >
+   > **What replaces it — at the moment of each write, not at the end:** a rejected `author` comes back
+   > as an ORDINARY tool result with **no error flag** — `Could not author "<page>": Cortex API 409:
+   > <reason>` — and `No change to "<page>"` is a **200 OK that wrote nothing**. Neither is an error at
+   > the protocol level, so nothing will interrupt you. **Read the result text of every write; never
+   > skim it.** That inline read is where this step's value actually was.
 
 ## Output
 
@@ -88,7 +90,7 @@ After calling `log_session`, show a short structured summary:
 **Coordinated with:** people involved
 **Logged:** ✅ persisted as the session's record (authoritative)  (or ⚠ log_session errored — run doctor)
 **Wiki authored:** [[Node A]], [[Node B]] — pages updated (or "— nothing advanced this session")
-**Reconciled:** N touched → M authored, K skipped (reason each); writes verified ✅ (or ⚠ <what didn't land>)
+**Reconciled:** N touched → M authored, K skipped (reason each)
 ```
 
 ## Safety rules