@theronap/cortex-mcp 0.9.136 → 0.9.138

package/lib/capture.mjs

@@ -386,8 +386,17 @@ async function captureWork(stdinRaw) {
   }
   const extracted = transcript ? extractSession(transcript) : null
   if (extracted && /^NOOP\b/i.test(extracted.summary)) { process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — summarizer classified it a no-op session\n`); return }
+  // `pages` is the edge's PROPOSAL of where this record belongs (ADR-0055). Free-text names, resolved
+  // against real pages server-side and dropped when they match nothing — the same untrusted-edge
+  // contract people/entities use. Omitted entirely when empty so an older server sees no new field.
   const ingestBody = extracted
-    ? { ...common, summary: extracted.summary, people: extracted.people, entities: extracted.namedEntities }
+    ? {
+        ...common,
+        summary: extracted.summary,
+        people: extracted.people,
+        entities: extracted.namedEntities,
+        ...(extracted.pages?.length ? { pages: extracted.pages } : {}),
+      }
     : { ...common, transcript }
 
   // Parallel typed extraction (OPT-IN via CORTEX_TYPED): registry-driven typed notes, sent ALONGSIDE the

package/lib/capture_status.mjs

@@ -0,0 +1,68 @@
+// How "where do my captures land?" is answered — ONE renderer, two callers.
+//
+// WHY IT IS EXTRACTED. `set_capture_brain` (MCP) and `use-brain` (CLI) each had their own copy of
+// this answer, and the copies had already drifted: the CLI said captures land somewhere "only if you
+// belong to exactly one" brain, the tool said they "are being HELD" if you belong to more than one.
+// Both were the same guess wearing different words. diagnose.mjs' token resolver carries the same
+// warning for the same reason — "a third copy is how a machine ends up 'connected' to one command
+// and 'no token found' to another".
+//
+// WHY IT TAKES DATA INSTEAD OF ASKING. Every branch below is decided by a fact the server already
+// knows: what is staging, and how many brains you are in. Until 2026-09-08 neither surface fetched
+// either, so both could only offer the reader a CONDITION — and on that day a person with one brain
+// and nothing held was told his setup was broken, while a person with 52 held `email` records was
+// told a number that named no source and a remedy that could not reach it.
+//
+// Pure: no I/O, no token, no formatting of anything it was not given.
+
+/** The remedy, phrased for where it will be read. Same decision tree, same facts — only the thing
+ *  the reader would type differs, and getting that wrong is not cosmetic: a CLI user pasting
+ *  `source="email"` gets an error, and an agent told to run a shell command does the wrong thing.
+ *  @type {Record<string, (source: string) => string>} */
+const FIX = {
+  tool: (source) => `call this tool again with brain=<brain> source="${source}"`,
+  cli: (source) => `npx -y @theronap/cortex-mcp use-brain "<brain>" --source ${source}`,
+}
+
+/** @param {{defaults?: Array, held?: Array, brainCount?: number}} state
+ *  @param {'tool'|'cli'} mode */
+export function renderCaptureStatus(state, mode = 'tool') {
+  const defaults = state?.defaults ?? []
+  const held = state?.held ?? []
+  const brainCount = typeof state?.brainCount === 'number' ? state.brainCount : null
+  const fix = FIX[mode] ?? FIX.tool
+  const lines = []
+
+  for (const d of defaults) {
+    lines.push(`${d.sourceType} captures land in "${d.orgName}" (${d.orgId})${d.updatedAt ? `, set ${String(d.updatedAt).slice(0, 10)}` : ''}`)
+  }
+
+  // The actionable case, and it is stated whether or not other defaults exist: a set `claude-code`
+  // default says nothing about `email`, and reading the first as coverage for the second is exactly
+  // how 52 records stayed held for ten days behind a green-looking setting.
+  if (held.length) {
+    if (lines.length) lines.push('')
+    lines.push(`⚠ NOT being saved — held outside every brain, one line per source:`)
+    for (const h of held) {
+      lines.push(`  · ${h.held} ${h.source}${h.oldest ? ` (oldest ${h.oldest})` : ''} — ${fix(h.source)}`)
+    }
+    lines.push('Each source routes on its own; setting one does nothing for the others.')
+    return lines.join('\n')
+  }
+
+  if (lines.length) {
+    lines.push('')
+    lines.push('Nothing is currently held.')
+    return lines.join('\n')
+  }
+
+  // No defaults AND nothing held. Whether that is fine or a latent problem is decided by the brain
+  // count, so say which — never both, and never as a question for the reader.
+  if (brainCount === 1) {
+    return 'No capture brain is set, and none is needed: you belong to exactly one brain, so captures route there automatically. Nothing is held. Nothing to do.'
+  }
+  if (brainCount !== null && brainCount > 1) {
+    return `No capture brain is set. Nothing is held right now, but you belong to ${brainCount} brains — a capture from a source with no default cannot be routed, so it will be held rather than saved. Set one per source you use, e.g. ${fix('claude-code')}`
+  }
+  return 'No capture brain is set, and nothing is currently held.'
+}

package/lib/edge_extract.mjs

@@ -96,6 +96,44 @@ const PEOPLE_FRAGMENT =
   '"importance" ("high" for people central to the work, "low" for incidental). ' +
   'Only real named humans; omit anonymous or incidental mentions. Empty array is fine.)'
 
+// WHERE THIS RECORD BELONGS — the one question the extraction never asked.
+//
+// Measured 2026-09-05..08: of 221 page attachments since the ADR-0051 gate shipped, 215 were
+// mechanical (`deterministic_attach` 197, `session_attach` 18) and 6 were judgment (`route_record`).
+// 2.7%. A session's record lands on the author's profile and any page the session EDITED, and
+// nowhere else — so four hours of work on ADR-0051 is invisible from the ADR-0051 page. ADR-0053
+// measures the consequence: 20% of sessions are findable by subject for a developer, ~0% for a
+// non-developer.
+//
+// Asking a later agent to fix this was tried and rejected: by the time the record exists the session
+// that did the work is gone, and the agent inherits a title. Naive agents given exactly that job
+// parked records because "only the title survived". THIS call already holds the whole transcript,
+// already runs detached with nobody waiting, and already makes judgement calls (people, entities).
+// It is the only place in the system where the context and the question are in the same room.
+//
+// ⚠ "MENTIONED" IS NOT "BELONGS ON", and that distinction is the entire fragment. A session that
+// deploys to Vercel mentions Vercel; it does not belong on the Vercel page. Filing on every mention
+// is worse than filing on none — it makes every page's record list noise, and noise is unreadable in
+// exactly the way an empty list is not. `namedEntities` above is the MENTION list and already exists;
+// this is deliberately a different, smaller question, which is why it is a separate key rather than
+// a flag on that one.
+//
+// Names are proposed as free text and RESOLVED SERVER-SIDE against real pages, the same trust model
+// people/entities already use — the edge is not trusted and does not hold the page list. A name that
+// matches nothing is dropped, so a hallucinated page cannot create one.
+const PAGES_FRAGMENT =
+  '"pages" (array of wiki page names this work should be FILED UNDER — the pages whose reader would ' +
+  'want to know this session happened. Each an object with ' +
+  '"name" (the page name exactly as written in the session — prefer a name that appears verbatim, ' +
+  'especially inside [[double brackets]], an ADR number and title, a project name, or a person\'s ' +
+  'full name), ' +
+  '"why" (one short phrase: what this session did TO or ABOUT that subject). ' +
+  'Include a page ONLY if the work was genuinely about that subject — something was decided, built, ' +
+  'measured, fixed or discovered concerning it. EXCLUDE anything merely used, referenced in passing, ' +
+  'or named as background: a session that deploys to a platform does not belong on that platform\'s ' +
+  'page. Most sessions belong on one to three pages. Empty array is correct for a session with no ' +
+  'durable subject, and is much better than a loose guess.)'
+
 const ENTITY_FRAGMENT =
   '"namedEntities" (array of important NON-PERSON things this content is about — concrete, named ' +
   'projects, processes, systems, products, documents, teams, tools, events, places, or topics. ' +
@@ -165,34 +203,109 @@ export function extractSession(transcript) {
   const text = task ? stripScheduledTaskBlocks(raw) : raw
   // A run whose entire transcript WAS the instruction block leaves nothing to judge. That is a
   // heartbeat by definition — skip without spending a `claude -p` call on it.
-  if (task && !text) return { summary: 'NOOP', people: [], namedEntities: [] }
+  if (task && !text) return { summary: 'NOOP', people: [], namedEntities: [], pages: [] }
   const prompt =
     'You are processing a Claude Code work session for a knowledge base. Return ONLY minified JSON ' +
-    '(no prose, no markdown fences) with EXACTLY these three keys:\n' +
+    '(no prose, no markdown fences) with EXACTLY these four keys:\n' +
     '"summary" (ONE concrete sentence under 20 words: what was worked on or decided. If the session ' +
     'had no real work — greetings, no tasks — set summary to exactly "NOOP"),\n' +
     PEOPLE_FRAGMENT + ',\n' +
-    ENTITY_FRAGMENT +
+    ENTITY_FRAGMENT + ',\n' +
+    PAGES_FRAGMENT +
     (task ? scheduledTaskFragment(task) : '') +
     '\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) {
@@ -208,6 +321,10 @@ export function parseEdgeJson(out) {
       summary: summary.slice(0, 200),
       people: Array.isArray(o.people) ? o.people : [],
       namedEntities: Array.isArray(o.namedEntities) ? o.namedEntities : [],
+      // ⚠ This function WHITELISTS keys — a key absent here is silently dropped no matter what the
+      // model returned and no matter what the prompt asked for. Adding a prompt fragment without
+      // adding it here yields a feature that ships, runs, and does nothing.
+      pages: Array.isArray(o.pages) ? o.pages : [],
     }
   } catch {
     return null

package/lib/grep_cli.mjs

@@ -30,6 +30,9 @@ export function parseGrepArgs(argv = []) {
   return out
 }
 
+// How many [[links]] to print per hit before summarising the rest as "(+N more)".
+export const LINKS_PER_HIT = 8
+
 // Pure: render a /api/grep payload to readable ASCII text.
 export function formatGrepHits(payload, query) {
   const hits = (payload && payload.hits) || []
@@ -41,12 +44,27 @@ export function formatGrepHits(payload, query) {
       ? `No matches for "${query}". If you expected a page here, it may be an unauthored red-link — \`read_page "${query}"\` to triage it (author it, or alias it to an existing page).`
       : `No matches for "${query}".`
   }
-  const lines = [`${hits.length} match${hits.length === 1 ? '' : 'es'} for "${query}":`, '']
+  // `total` (server, 2026-09-05) is the pre-cap match count. Say so when the list was truncated:
+  // a capped list presented as a complete one is how "nothing else mentions this" gets concluded
+  // from a partial answer -- the same failure the per-brain status list exists to prevent.
+  const total = typeof payload.total === 'number' ? payload.total : hits.length
+  const truncated = total > hits.length
+  const header = truncated
+    ? `${hits.length} of ${total} matches for "${query}" (best-ranked first; narrow the query or raise max to see the rest):`
+    : `${hits.length} match${hits.length === 1 ? '' : 'es'} for "${query}":`
+  const lines = [header, '']
   for (const h of hits) {
     const head = h.heading ? ` > ${h.heading}` : ''
     lines.push(`- ${h.title}${head} [${h.tier}]`)
     if (h.snippet) lines.push(`    ${String(h.snippet).replace(/\s+/g, ' ').trim()}`)
-    if (h.links && h.links.length) lines.push(`    -> ${h.links.map((l) => `[[${l}]]`).join(' ')}`)
+    // Cap the link list per hit. Median is 2 but the tail reaches 32, and at ~126 chars/hit the
+    // link lists were the second-largest cost in the payload after snippets. The count is kept so
+    // a trimmed list never reads as the page's complete outbound set.
+    if (h.links && h.links.length) {
+      const shown = h.links.slice(0, LINKS_PER_HIT)
+      const more = h.links.length - shown.length
+      lines.push(`    -> ${shown.map((l) => `[[${l}]]`).join(' ')}${more > 0 ? ` (+${more} more)` : ''}`)
+    }
   }
   return lines.join('\n')
 }

package/lib/server.mjs

@@ -10,6 +10,7 @@ import { folderClaimLine } from './folder_claims.mjs'
 import { resolveSessionKey, resolveLogSessionId } from './session_key.mjs'
 import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.mjs'
+import { renderCaptureStatus } from './capture_status.mjs'
 import { renderTriage } from './red_link_triage.mjs'
 import { runCodeGraphQuery } from './code_graph_cli.mjs'
 import { repoFullNameFrom } from './capture.mjs'
@@ -230,12 +231,13 @@ function renderNudge(payload) {
     {
       title: 'Choose where your session captures are saved',
       description:
-        'Set which brain THIS PERSON\'s unattended session captures (the automatic end-of-session record) land in, or read the current setting by omitting `brain`. WHEN TO USE: whenever the user says their sessions are not being saved, asks where their work is going, or a session-start notice says captures are being HELD. WHY IT IS NEEDED: with more than one brain, a capture that names no brain cannot be routed and is held outside every brain — correct, but invisible, so it accumulates silently. This is per-PERSON and applies to their own captures only; it cannot be set for someone else. ⚠ PASS THE ORG ID when the user has two brains with the SAME NAME (e.g. two called "Personal") — a name matching more than one is REFUSED rather than guessed, and the error lists the ids to choose from. Setting this does NOT file already-held captures; those keep their original dates and may belong in different brains, so sort them deliberately rather than dumping them into the new default.',
+        'Set which brain THIS PERSON\'s unattended session captures (the automatic end-of-session record) land in, or read the current setting by omitting `brain`. WHEN TO USE: whenever the user says their sessions are not being saved, asks where their work is going, or a session-start notice says captures are being HELD. WHY IT IS NEEDED: with more than one brain, a capture that names no brain cannot be routed and is held outside every brain — correct, but invisible, so it accumulates silently. This is per-PERSON and applies to their own captures only; it cannot be set for someone else. ⚠ PASS THE ORG ID when the user has two brains with the SAME NAME (e.g. two called "Personal") — a name matching more than one is REFUSED rather than guessed, and the error lists the ids to choose from. Setting this does NOT file already-held captures; those keep their original dates and may belong in different brains, so sort them deliberately rather than dumping them into the new default. ⚠ A default is PER SOURCE: setting `claude-code` does NOTHING for `email` or `imessage`, which keep staging until each gets its own. If a notice reports held captures, set the source it names.',
       inputSchema: {
         brain: z.string().optional().describe('the brain name or org id (from my_brains) where this person\'s session captures should land. Omit to read the current setting instead of changing it.'),
+        source: z.string().optional().describe("which connector's captures this routes, e.g. 'claude-code', 'email', 'imessage', 'cursor'. Defaults to 'claude-code'. Each source routes independently — set the one the held-captures notice names."),
       },
     },
-    async ({ brain }) => {
+    async ({ brain, source }) => {
       const url = `${BASE}/api/brain/capture-default`
       if (!brain?.trim()) {
         const res = await fetchCortex(url, { headers: { Authorization: `Bearer ${TOKEN}` } })
@@ -243,17 +245,16 @@ function renderNudge(payload) {
           const body = await res.text()
           throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
         }
-        const { defaults } = await res.json()
-        if (!defaults?.length) {
-          return { content: [{ type: 'text', text: 'No capture brain is set. If you belong to more than one brain, your session captures are being HELD outside every brain until you set one. Call this tool again with `brain` to fix it.' }] }
-        }
-        const lines = defaults.map((d) => `${d.sourceType} captures land in "${d.orgName}" (${d.orgId}), set ${String(d.updatedAt).slice(0, 10)}`)
-        return { content: [{ type: 'text', text: lines.join('\n') }] }
+        return { content: [{ type: 'text', text: renderCaptureStatus(await res.json()) }] }
       }
       const res = await fetchCortex(url, {
         method: 'POST',
         headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ sourceType: 'claude-code', brain: brain.trim() }),
+        // The source was pinned to 'claude-code' here and in use-brain from the day both shipped,
+        // while the server has always keyed capture_defaults on (auth_id, source_type). The result:
+        // the remedy the held-captures notice names could not reach any source but one. Defaulted,
+        // not required — the bare call keeps its old meaning exactly.
+        body: JSON.stringify({ sourceType: source?.trim() || 'claude-code', brain: brain.trim() }),
       })
       const body = await res.text()
       if (!res.ok) {
@@ -264,7 +265,7 @@ function renderNudge(payload) {
         throw new Error(msg ?? classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
       }
       const j = JSON.parse(body)
-      return { content: [{ type: 'text', text: `✓ Your Claude Code sessions now land in "${j.brain}" (${j.orgId}). Sessions captured before now are still held and keep their original dates — file those deliberately, they may not all belong in this brain.` }] }
+      return { content: [{ type: 'text', text: `✓ Your ${j.sourceType} captures now land in "${j.brain}" (${j.orgId}). This covers ${j.sourceType} ONLY — every other source keeps its own default and keeps staging until set. Captures from before now are still held and keep their original dates — file those deliberately, they may not all belong in this brain.` }] }
     },
   )
 
@@ -937,15 +938,22 @@ function renderNudge(payload) {
       const lines = []
       const sa = body?.sessionAttachments
       if (sa === null) {
-        lines.push('⚠ Session-page attachment FAILED for this record — it was written, but not filed under the pages this session wrote. Re-run the reconciler.')
+        lines.push('⚠ Session-page attachment FAILED for this record — it was written, but not filed under the pages this session worked on. Re-run the reconciler.')
       } else if (sa && Array.isArray(sa.attached)) {
         if (sa.attached.length > 0) {
-          lines.push(`Filed under ${sa.attached.length} page(s) this session wrote.`)
+          // ⚠ "worked on", not "wrote" — [[ADR-0053]] made this line wrong on 2026-09-08.
+          // Attachments now come from two places: pages the session AUTHORED (ADR-0032, via
+          // page_revisions.session_key) and pages it merely OPENED (ADR-0053, via read_page). The
+          // server returns one flat `attached` list and does not say which is which, so this cannot
+          // report the split without a server change — but it must not assert the narrower of the two.
+          // Observed live the day ADR-0053 shipped: a session that authored nothing and only read
+          // [[Travis Peterson]] was told "Filed under 1 page(s) this session wrote."
+          lines.push(`Filed under ${sa.attached.length} page(s) this session worked on.`)
         } else {
-          lines.push('No pages filed: this session authored none in this brain (the normal case).')
+          lines.push('No pages filed: this session neither wrote nor opened a page in this brain (the normal case).')
         }
         if (sa.droppedCrossBrain > 0) {
-          lines.push(`${sa.droppedCrossBrain} page(s) this session wrote live in another brain and were skipped — a record belongs to one brain.`)
+          lines.push(`${sa.droppedCrossBrain} page(s) this session worked on live in another brain and were skipped — a record belongs to one brain.`)
         }
       }
       // Containment carried from capture. Three states, and they are not interchangeable:
@@ -1217,14 +1225,16 @@ function renderNudge(payload) {
     {
       title: 'Grep the brain wiki',
       description:
-        'Ranked keyword search across your visible brain wiki pages. Multi-word natural-language queries work (results are ranked by relevance). Pass mode:"substring" for an exact literal match of symbols, identifiers, or [[links]]. Returns matching sections with a context snippet and their outbound [[links]].',
+        'Ranked keyword search across your visible brain wiki pages. Multi-word natural-language queries work (results are ranked by relevance). Pass mode:"substring" for an exact literal match of symbols, identifiers, or [[links]] — and for an English STOPWORD ("own", "not"), which ranked search drops. Returns matching sections with a context snippet and their outbound [[links]]. A broad query fans out across every brain you can see, so pass `max` when you only need to locate a page; the header always says how many matched in total, so a capped list is never mistaken for the whole answer.',
       inputSchema: {
         query: z.string().describe('search terms (natural language is fine)'),
         mode: z.enum(['substring', 'fts']).optional().describe("'fts' (default, ranked keyword) or 'substring' (exact literal — for identifiers / [[links]] / code)"),
+        max: z.number().int().optional().describe('how many matches to return, best-ranked first (default 50, max 200). Lower it when you only need to LOCATE a page; a broad query across many brains can otherwise return well over a hundred matches in one call.'),
       },
     },
-    async ({ query, mode }) => {
+    async ({ query, mode, max }) => {
       const qs = new URLSearchParams({ q: query, mode: mode === 'substring' ? 'substring' : 'fts' })
+      if (max) qs.set('max', String(max))
       const res = await fetchCortex(`${BASE}/api/grep?${qs.toString()}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       if (!res.ok) {
         const body = await res.text()
@@ -1313,7 +1323,7 @@ function renderNudge(payload) {
         'READ the full authored wiki page for one node (project/person/org/you) by its canonical name — every section, every tier you can see. This is how you READ a node; `grep` only LOCATES pages (snippets + their [[links]]), it does not read them. Navigate like a researcher: read the page you need, then FOLLOW its inline [[links]] by calling read_page on each linked name — keep following while the linked pages stay relevant, stop when they do not. You decide how deep to go. Returns only what you are permitted to see.',
       inputSchema: {
         name: z.string().describe('the canonical node name exactly as written (e.g. "Agnoclast", "Ben", or a [[link]] target) — identifier links ([[repo:owner/name]]) resolve to their authored HOME + a visible-event count'),
-        kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('node kind (default project; pass person/org for people/teams)'),
+        kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('node kind — a PREFERENCE, not a filter. The lookup matches every kind by title and only prefers this one when several share a name, so omitting it never hides a person/org/user page. Pass it to disambiguate a name that exists as more than one kind.'),
         expand: z.boolean().optional().describe('identifier names only: also list recent visible timeline events for this identifier (default: home + count)'),
         history: z.boolean().optional().describe('node names only: return the node\'s TIMELINE (events joined via its [[repo:…]] stamps, reverse-chron, viewer-visible) instead of the page body. The page is the present; this is the history.'),
         version: z.string().optional().describe('read a HISTORICAL version of this page instead of the current one: a rev_no (e.g. "3") or a content_hash from page_history. Use page_history first to see the versions, then rollback_page to restore one.'),
@@ -1445,7 +1455,16 @@ function renderNudge(payload) {
         matches = [{ brain: null, authored: true, ref: page.ref, title: page.title, tiers: page.tiers }]
       }
       if (!matches.length) {
-        return { content: [{ type: 'text', text: `No authored ${k} page named "${name}" in any of your brains. If it's a person or team, pass kind (person/org).${await redLinkTriage(BASE, TOKEN, name)}` }] }
+        // ⚠ This used to say: `No authored ${k} page named "X" ... If it's a person or team, pass
+        // kind (person/org).` Both halves misled. resolveNodeByTitle matches EVERY kind and uses the
+        // requested one only as an ORDER BY preference (resolve_node.ts: `order by (bd.engram_kind =
+        // ${kind}) desc, ...`), so (a) naming the kind implies a kind-scoped search that never
+        // happened, and (b) retrying with kind:'person' re-runs the identical query and returns the
+        // identical nothing. That is worse than unhelpful: it hands the caller an experiment that
+        // cannot disconfirm "the page does not exist", so the empty retry reads as CORROBORATION.
+        // Two sessions ran that loop and reported read_page false negatives that did not exist.
+        // Say what was actually searched, and point at a check that can actually come back different.
+        return { content: [{ type: 'text', text: `No authored page named "${name}" — of ANY kind (project/person/org/user), in any brain you are an active member of. Passing \`kind\` will not change this: kind only orders the candidates, it does not narrow the search. If you expected a page here, the name may differ (\`grep "${name}"\` finds pages that MENTION it, and \`mode:"substring"\` matches an exact literal), or it may be an alias.${await redLinkTriage(BASE, TOKEN, name)}` }] }
       }
       const day = (d) => (d ? String(d).slice(0, 10) : '')
       const renderMatch = (m, tagBrain) => {
@@ -3398,14 +3417,35 @@ function renderNudge(payload) {
       if (view === 'sweep') {
         const cands = out?.candidates ?? []
         if (cands.length === 0) {
-          return { content: [{ type: 'text', text: `No page-name candidates for "${out?.title ?? recordId}". Park it — a stale record with no match is not worth reading pages over.` }] }
+          // ⚠ A NULL RESULT MEANS "NO TITLE OVERLAP", NOT "NO HOME". Measured 2026-09-05 across four
+          // naive agents working the backlog: this line recommended parking 4/5, 5/6, 6/6 and 4/5
+          // records, and was WRONG almost every time — the records had correct homes that simply did
+          // not share words with their subject lines. One agent said it plainly: "I'd treat sweep as
+          // a hint, never as the recommendation it phrases itself as." So it no longer phrases itself
+          // as one. This matcher compares TITLES; it cannot see a page whose subject is the record's
+          // subject under a different name.
+          return { content: [{ type: 'text', text:
+            `No page-title overlap for "${out?.title ?? recordId}".\n\n`
+            + `⚠ That means this matcher found nothing — NOT that no home exists. It compares titles only, so it is blind\n`
+            + `whenever the right page is named differently from the record. Measured 2026-09-05: it recommended parking\n`
+            + `records that were already correctly filed, in four sessions out of four.\n\n`
+            + `If you have context on this record, use it — search_org or read_page will beat this matcher.\n`
+            + `Park only once YOU have looked and found nothing.` }] }
         }
         const lines = cands.map((c) => `  ${c.strength === 'strong' ? '●' : '○'} ${c.title} (${c.strength}) — ${c.documentId}`)
         const rec = out?.recommendation
         return {
           content: [{
             type: 'text',
-            text: `Candidates for "${out?.title}":\n${lines.join('\n')}\n\nRecommended: ${rec?.action} — ${rec?.why}\n● strong = titles contain each other, safe to route. ○ weak = one generic word matched; read those pages ONLY if this record is worth the tokens, otherwise park.`,
+            // "Recommended" overstated what a title match knows. Renamed to what it actually is —
+            // the matcher's own reading — and the weak rung no longer ends in "otherwise park",
+            // which is the phrasing that pushed agents to park correctly-homed records.
+            text: `Candidates for "${out?.title}":\n${lines.join('\n')}\n\n`
+              + `Title matcher says: ${rec?.action} — ${rec?.why}\n`
+              + `● strong = titles contain each other, safe to route. ○ weak = one generic word matched.\n`
+              + `⚠ This ranks TITLE OVERLAP ONLY. A page whose subject is this record's subject under a different name\n`
+              + `scores nothing here. Absence of candidates is not evidence of absence of a home — if you have context,\n`
+              + `trust it over this list.`,
           }],
         }
       }

package/lib/use_brain.mjs

@@ -1,5 +1,6 @@
 import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 import { resolveToken } from './doctor.mjs'
+import { renderCaptureStatus } from './capture_status.mjs'
 
 // `use-brain` — set (or show) which brain this machine's unattended session captures land in.
 //
@@ -14,6 +15,32 @@ import { resolveToken } from './doctor.mjs'
 
 function out(m) { process.stdout.write(m + '\n') }
 
+/** Split `--source <type>` / `--source=<type>` out of the argv, leaving the brain words.
+ *
+ *  WHY THIS EXISTS. The POST body pinned `sourceType: 'claude-code'` from the day this command
+ *  shipped, while the server has always keyed capture_defaults on (auth_id, source_type). So a
+ *  person told by the SessionStart notice that N captures were being held could run exactly the
+ *  command the notice named, watch it succeed, and fix only their claude-code captures — every
+ *  `email` row kept staging and the warning kept firing. Measured 2026-09-08: one account had 52
+ *  email records held for 10 days behind a correctly-followed remedy that could not reach them.
+ *
+ *  `--source` DEFAULTS rather than being required: the bare form is what the notice, the docs and
+ *  two months of muscle memory all say, and breaking it to fix this would trade one silent failure
+ *  for a loud one. The old invocation keeps its old meaning exactly. */
+export function parseUseBrainArgs(argv) {
+  const words = []
+  let source = 'claude-code'
+  let sawFlag = false
+  for (let i = 0; i < (argv ?? []).length; i++) {
+    const a = argv[i]
+    if (a === '--source') { source = (argv[++i] ?? '').trim(); sawFlag = true; continue }
+    if (a.startsWith('--source=')) { source = a.slice('--source='.length).trim(); sawFlag = true; continue }
+    if (a.startsWith('--')) continue
+    words.push(a)
+  }
+  return { source, brain: words.join(' ').trim(), sawFlag }
+}
+
 export async function runUseBrain(args) {
   const base = resolveBase(process.env.CORTEX_URL)
   const { token } = resolveToken()
@@ -22,10 +49,14 @@ export async function runUseBrain(args) {
     return 1
   }
 
-  // Everything after the subcommand is the brain, joined — so an unquoted multi-word name still
+  // Everything that is not a flag is the brain, joined — so an unquoted multi-word name still
   // works. `use-brain Real estate` is what a person actually types; refusing it over a missing pair
   // of quotes would be the same species of unhelpfulness this command exists to remove.
-  const wanted = (args ?? []).filter((a) => !a.startsWith('--')).join(' ').trim()
+  const { source, brain: wanted, sawFlag } = parseUseBrainArgs(args)
+  if (sawFlag && !source) {
+    out('Agnoclast: --source needs a value, e.g. --source email')
+    return 1
+  }
   const url = `${base}/api/brain/capture-default`
 
   if (!wanted) {
@@ -38,14 +69,11 @@ export async function runUseBrain(args) {
         out(`Agnoclast: could not read your capture settings — ${classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message}`)
         return 1
       }
-      const { defaults } = await res.json()
-      if (!defaults?.length) {
-        out('Agnoclast: no capture brain set. Your unattended session captures land in a brain only if')
-        out('  you belong to exactly one; otherwise they are HELD outside every brain until you set this.')
-        out('  Set one:  npx -y @theronap/cortex-mcp use-brain "<brain name or org id>"')
-        return 0
-      }
-      for (const d of defaults) out(`Agnoclast: ${d.sourceType} captures land in "${d.orgName}" (${d.orgId})`)
+      // One renderer, shared with the `set_capture_brain` MCP tool — see capture_status.mjs for why
+      // these two answers must not be written twice.
+      const rendered = renderCaptureStatus(await res.json(), 'cli').split('\n')
+      out(`Agnoclast: ${rendered[0]}`)
+      for (const line of rendered.slice(1)) out(line)
       return 0
     } catch (e) {
       out(`Agnoclast: could not reach the server (${e?.message ?? String(e)})`)
@@ -57,7 +85,7 @@ export async function runUseBrain(args) {
     const res = await fetchCortex(url, {
       method: 'POST',
       headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
-      body: JSON.stringify({ sourceType: 'claude-code', brain: wanted }),
+      body: JSON.stringify({ sourceType: source, brain: wanted }),
     })
     const body = await res.text()
     if (!res.ok) {
@@ -69,10 +97,14 @@ export async function runUseBrain(args) {
       return 1
     }
     const j = JSON.parse(body)
-    out(`Agnoclast: ✓ your Claude Code sessions now land in "${j.brain}".`)
+    // Name the SOURCE this actually set. "your Claude Code sessions now land in X" was printed
+    // verbatim after setting an `email` default too, because the source was pinned — so the one
+    // line that could have revealed the pin instead concealed it.
+    out(`Agnoclast: ✓ your ${j.sourceType} captures now land in "${j.brain}".`)
     // Say plainly what this does NOT do. The setter's own server-side note makes the same point,
     // because "I fixed it" reading as "and the backlog is handled" is how held records stay held.
-    out('  Sessions captured BEFORE now are still held — they keep their original dates until sorted.')
+    out(`  Only ${j.sourceType} — every other connector keeps its own default (use --source).`)
+    out('  Captures from BEFORE now are still held — they keep their original dates until sorted.')
     out('  Ask your assistant to file them (they may not all belong in the same brain).')
     return 0
   } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.136",
+  "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": {