@theronap/cortex-mcp 0.9.69 → 0.9.71

package/bin/cortex-mcp.mjs

@@ -55,6 +55,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  graphify-sync [path]  rebuild the local code graph (graphify) + log an evidence-tier timeline event\n` +
     `  snapshot-context save the exact startup context Cortex served to a local snapshot\n` +
     `  hydrate         UserPromptSubmit hook — inject query-centered context on the first substantive turn\n` +
+    `  statusline      ambient presence line for the Claude Code statusline (local read only)\n` +
     `  capture         Stop-hook capturer (invoked by Claude Code)\n` +
     `  ingest-folder <path>   ingest a local markdown folder as your authored records\n` +
     `  (no args)       run the MCP server (used by your Claude config)\n\n` +
@@ -159,6 +160,11 @@ if (cmd === 'login') {
   process.exitCode = await runHydrate()
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'statusline') {
+  // Ambient presence: read one local breadcrumb and print a line. No network, no auth — it redraws
+  // constantly, so anything more expensive than a file read does not belong here.
+  const { runStatusline } = await import('../lib/statusline.mjs')
+  process.exitCode = runStatusline()
 } else if (cmd === 'skills') {
   // Install / repair the managed Cortex skills — bundled + org-published (`skills push` publishes).
   // Org sync is network-fail-soft so the SessionStart hook stays safe offline.

package/lib/editors/claude.mjs

@@ -22,7 +22,9 @@ export function mergeClaudeMcp(existing, spec, token) {
  *  CAS-protected + snapshotted (page_revisions → page_history/rollback_page).
  *  Deliberately EXCLUDED — these keep prompting: send_imessage (external side effect),
  *  set_page_privacy / set_record_privacy / grant_page_access (visibility widening — the
- *  unowned-project accessible-default sharp edge, 2026-07-02), rollback_page, decide_page_merge /
+ *  unowned-project accessible-default sharp edge, 2026-07-02), replace_variant (destroys a page body
+ *  and deletes a variant row — the one write here that is not merely CAS-protected but genuinely
+ *  lossy at the row level, so the prompt IS the guard D1 argued for), rollback_page, decide_page_merge /
  *  decide_file_request / request_file / get_file, create_brain / set_active_brain, alias_page,
  *  set_writing_style. */
 export const CORTEX_ALLOWED_TOOLS = [
@@ -38,8 +40,9 @@ export const CORTEX_ALLOWED_TOOLS = [
 
 /** Merge Cortex's Claude Code hooks into a ~/.claude/settings.json object. Pure + idempotent: drops
  *  any prior cortex entry (old token/path/version) from each hook array before appending the current
- *  one — capture (Stop), status + skills-repair + snapshot-context (SessionStart), precompact
- *  (PreCompact). Commands carry NO inline token (each subcommand self-resolves it). Mirrors setup.mjs
+ *  one — capture (Stop), status + skills-repair + snapshot-context (SessionStart), hydrate
+ *  (UserPromptSubmit), precompact (PreCompact). Commands carry NO inline token (each subcommand
+ *  self-resolves it). Mirrors setup.mjs
  *  step 2 exactly; foreign hooks are never touched. Also merges the CORTEX_ALLOWED_TOOLS permission
  *  allowlist — additive-only: a user's own allow entries (even extra mcp__cortex__* ones) are never
  *  removed, and `deny` is never touched (a user deny always beats our allow). */
@@ -81,6 +84,27 @@ export function mergeClaudeSettings(existing, spec) {
   }
   sgrp.hooks.push({ type: 'command', command: snapshotCmd })
 
+  // UserPromptSubmit — hydrate (① discovery). Makes the FIRST context load of a session
+  // non-discretionary: without it, hydration is a skill the agent may simply forget, and an agent
+  // that never reads the wiki never triggers a currency update — it re-derives design that is
+  // already authored and already shipped. This is also the surface that prints the presence receipt,
+  // so wiring it is what makes a read visible to the person in the chair.
+  //
+  // The filter is deliberately loose (`cortex-mcp.*hydrate`) so it also reclaims a hand-wired LOCAL
+  // pointer of the form `[ -f <worktree>/bin/cortex-mcp.mjs ] && node … hydrate || true`. Those were
+  // the recommended way to trial the hook before release, and one on this project's own machine went
+  // dead for five days when its worktree was deleted — the `-f` guard fails open, so the hook silently
+  // became a no-op with the config still looking wired. Re-running setup should heal that, not skip it.
+  s.hooks.UserPromptSubmit = Array.isArray(s.hooks.UserPromptSubmit) ? s.hooks.UserPromptSubmit : []
+  const hydrateCmd = `npx -y ${spec} hydrate`
+  for (const hg of s.hooks.UserPromptSubmit) {
+    if (Array.isArray(hg.hooks)) hg.hooks = hg.hooks.filter((h) => !/cortex-mcp.*hydrate/.test(h.command ?? ''))
+  }
+  let hgrp = s.hooks.UserPromptSubmit.find((g) => (g.matcher ?? '') === '')
+  if (!hgrp) { hgrp = { matcher: '', hooks: [] }; s.hooks.UserPromptSubmit.push(hgrp) }
+  hgrp.hooks = hgrp.hooks ?? []
+  hgrp.hooks.push({ type: 'command', command: hydrateCmd })
+
   // PreCompact — "author now" reminder.
   s.hooks.PreCompact = Array.isArray(s.hooks.PreCompact) ? s.hooks.PreCompact : []
   const precompactCmd = `npx -y ${spec} precompact`
@@ -148,7 +172,7 @@ export default {
       ensureDir(settingsJson)
       writeJson(settingsJson, mergeClaudeSettings(s, spec))
       wrote.push(settingsJson)
-      log(`  ✓ Capture hook + status line → ${settingsJson}${bak ? ' (backup saved)' : ''}`)
+      log(`  ✓ Capture + hydrate hooks + status line → ${settingsJson}${bak ? ' (backup saved)' : ''}`)
     } catch (e) {
       warnings.push(`${settingsJson} wiring skipped: ${e.message}`)
     }

package/lib/hydrate.mjs

@@ -3,6 +3,8 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { fetchCortex, classify, resolveBase, readWiredToken } from './diagnose.mjs'
 import { redactSecrets } from './redact.mjs'
+import { formatReceipt, renderUncounted, subjectOf } from './presence.mjs'
+import { writePresence } from './statusline.mjs'
 
 // UserPromptSubmit hook (① discovery): on the FIRST substantive turn of a session, hydrate the model
 // with query-centered Cortex context BEFORE it answers — then never again this session. It closes the
@@ -118,6 +120,10 @@ export async function runHydrate() {
 
   const bumpAttempt = () => writeState(sessionId, { ...state, attempts: (state.attempts ?? 0) + 1 })
 
+  // Measured across the request only. Latency is the cheapest possible proof that a real round-trip
+  // happened rather than a cache or a stub — worth showing for that reason alone.
+  const startedAt = Date.now()
+
   let res
   try {
     res = await fetchCortex(
@@ -147,11 +153,27 @@ export async function runHydrate() {
     return 0
   }
 
-  const { context } = await res.json().catch(() => ({}))
+  const { context, meta } = await res.json().catch(() => ({}))
   if (context && typeof context === 'string' && context.trim()) {
     // stdout from a UserPromptSubmit hook is injected into THIS turn's context, before the model answers.
+    // The receipt goes FIRST and deliberately reaches both readers: the human sees that something was
+    // served, and the model sees — in the miss case — an explicit instruction not to quietly answer
+    // from somewhere else. That is the failure this cue was built for.
+    // A server that predates `meta` still served real context — fall back to a countless presence line
+    // rather than to formatReceipt, whose empty-pages branch would report a gap that was never measured.
+    const receipt =
+      meta && typeof meta === 'object' && !Array.isArray(meta)
+        ? formatReceipt({ subject: subjectOf(prompt), ...meta, ms: Date.now() - startedAt })
+        : renderUncounted()
+    if (receipt) process.stdout.write(receipt + '\n\n')
     process.stdout.write(context.trimEnd() + '\n')
     writeState(sessionId, { done: true, at: new Date().toISOString() })
+    // Leave the breadcrumb the statusline reads. Only ever what this machine just observed, so the
+    // ambient line can never assert something the org did not actually serve.
+    writePresence({
+      pages: Array.isArray(meta?.pages) ? meta.pages : [],
+      kind: meta && typeof meta === 'object' && !Array.isArray(meta) ? 'hit' : 'uncounted',
+    })
   } else {
     bumpAttempt() // empty body — treat as a miss, allow one bounded retry next turn
   }

package/lib/presence.mjs

@@ -0,0 +1,226 @@
+// The presence cue: the one place Agnoclast tells a human it is there.
+//
+// Every cue this product shipped before now reported the WRITE path — "connected", "logged
+// context", "you owe the org a page". Nothing ever announced a READ, which is the only moment
+// the thing is actually earning its keep. So the value was invisible by construction, and the
+// first outside reviewer's blocker was, verbatim, "I don't fully understand how it's going to
+// help yet."
+//
+// TWO RULES GOVERN THIS FILE.
+//
+// (1) THE MISS IS LOUDER THAN THE HIT. A cue that only lights up on success manufactures
+//     confidence, which is this codebase's documented recurring failure. The gate-6 miss on
+//     2026-07-29 was exactly that shape: the agent hit the edge of the wiki, silently read the
+//     repo instead, and the answer still came back sounding authoritative. `renderMiss` exists
+//     to make that impossible to do quietly — and because hook stdout is injected into the
+//     model's context, it addresses the AGENT as well as the human. It is a guardrail wearing a
+//     receipt's clothes.
+//
+// (2) NEVER INVENT A NUMBER. Every field here is either supplied by the server or omitted.
+//     There is no inference, no "probably", no derived-looking count that came from parsing
+//     prose. A receipt that guesses is worse than no receipt, because it is a confident-looking
+//     claim about the one system whose whole job is not making those.
+//
+// Pure and side-effect free on purpose: no network, no fs, no clock. Callers pass everything in,
+// which is what makes the three states unit-testable without a live org.
+
+// Deliberately plain text, no ANSI. Hook stdout is both rendered to the user AND injected into
+// model context; escape codes are noise in the second channel and can render literally in the
+// first depending on the surface. Glyph weight carries the state instead of color.
+const MARK_HIT = '◆'
+const MARK_MISS = '◇'
+const MARK_STALE = '◈'
+
+// The blob. Claude's is a pulsing eight-spoke asterisk, so these are the same glyph at rising and
+// falling stroke weight — read in sequence it breathes rather than spins. A spinner says "busy";
+// a breath says "here", which is the thing we are actually trying to convey.
+export const BLOB_FRAMES = ['✳', '✷', '✸', '✹', '✺', '✹', '✸', '✷']
+
+export function blobFrame(tick) {
+  return BLOB_FRAMES[((tick % BLOB_FRAMES.length) + BLOB_FRAMES.length) % BLOB_FRAMES.length]
+}
+
+const WIDTH = 92
+
+// Join names to fit one line, and say how many were dropped rather than trailing off. "+3 more" is
+// a fact; a bare ellipsis is a shrug.
+export function joinFit(names, budget) {
+  const list = (names ?? []).filter((n) => typeof n === 'string' && n.trim()).map((n) => n.trim())
+  if (list.length === 0) return ''
+  const out = []
+  let used = 0
+  for (const name of list) {
+    const cost = used === 0 ? name.length : name.length + 3
+    const remaining = list.length - out.length - 1
+    // Reserve room for the "+N more" tail so the fit never depends on it being empty.
+    const tail = remaining > 0 ? ` +${remaining} more`.length : 0
+    if (used + cost + tail > budget && out.length > 0) break
+    out.push(name)
+    used += cost
+  }
+  const dropped = list.length - out.length
+  return dropped > 0 ? `${out.join(' · ')} +${dropped} more` : out.join(' · ')
+}
+
+function line(text) {
+  return `  ${text}`
+}
+
+// Shorten a question to a nameable subject for the miss line. Kept local to the client — the server
+// is never asked to echo the query back, so this adds no new data flow and nothing is stored. That
+// matters: the raw query is customer content, and the standing position is that insight has to be
+// derivable without reading it.
+export function subjectOf(prompt, max = 48) {
+  const p = (prompt ?? '').trim().replace(/\s+/g, ' ')
+  if (!p) return ''
+  if (p.length <= max) return p
+  const cut = p.slice(0, max)
+  const lastSpace = cut.lastIndexOf(' ')
+  return (lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd() + '…'
+}
+
+// A read that landed. `unasked` is the Jarvis beat — something the query did not name that the
+// graph surfaced anyway. It is the single most persuasive line this product can print, so it is
+// also the one most worth refusing to fake: absent means absent.
+export function renderHit({ pages = [], ms, unasked } = {}) {
+  const count = pages.length
+  const head = [`${MARK_HIT} agnoclast · read ${count} page${count === 1 ? '' : 's'}`]
+  if (Number.isFinite(ms)) head.push(`${Math.round(ms)}ms`)
+  const out = [head.join(' · ')]
+  const names = joinFit(pages, WIDTH - 2)
+  if (names) out.push(line(names))
+  if (unasked) out.push(line(`↳ unasked: ${unasked}`))
+  return out.join('\n')
+}
+
+// A read that found nothing. This is the load-bearing state.
+//
+// `subject` is what was looked for, `unabsorbed` is how many records have landed on the node since
+// its page was last edited — high-and-recent means someone is actively working on a thing the wiki
+// has not caught up to, which is a far more useful thing to tell a human than "no results".
+//
+// The closing directive is aimed at the model. It is the counter to the documented failure where
+// the agent reached for the repo and reported nothing.
+//
+// ⚠ IT SAYS "SERVED", NOT "AUTHORED", AND THE DISTINCTION IS THE WHOLE POINT. An earlier revision
+// read "nothing authored on X" — an assertion about the CORPUS that this client cannot possibly
+// verify, and which is provably false today for two independent reasons:
+//   (1) #407 — `brainPages` is fetched inside the block pinned to the anchor brain
+//       (`runAsCloud(authId, fn, viewer.org_id)`), so a caller active in N brains only ever sees
+//       pages from one. Measured 2026-08-05: that is 5 brains for the operator, 2 each for two
+//       other people. Retrieval itself DOES span brains (`runAcrossBrains`), so the epicenter can
+//       be correct while the page lookup silently finds nothing.
+//   (2) `CORTEX_BRAIN_DIGEST` — when that flag is not 'on', `brainPages` is `[]` unconditionally.
+// Either way `pages: []` means "none reached me", never "none exist". A receipt built on the rule
+// NEVER INVENT A NUMBER had, in its single most load-bearing line, been inventing a fact.
+export function renderMiss({ subject, unabsorbed } = {}) {
+  const out = [`${MARK_MISS} agnoclast · read 0 pages`]
+  const what = subject ? `nothing served for "${subject}"` : 'nothing served for this'
+  const tail =
+    Number.isFinite(unabsorbed) && unabsorbed > 0
+      ? ` — ${unabsorbed} unabsorbed record${unabsorbed === 1 ? '' : 's'} on this node`
+      : ''
+  out.push(line(what + tail))
+  out.push(line('a gap in what was SERVED, not proof none exists — say so rather than substituting another source'))
+  return out.join('\n')
+}
+
+// A page changed. Surfacing `why` and `rev` is what makes the write feel accountable instead of
+// mysterious: the reader can see the reason and knows it is reversible without being told.
+export function renderWrite({ section, page, why, rev } = {}) {
+  const target = section ? `wrote §${section} → ${page ?? 'page'}` : `wrote ${page ?? 'page'}`
+  const out = [`${MARK_HIT} agnoclast · ${target}`]
+  const detail = []
+  if (why) detail.push(`why: ${why}`)
+  if (rev != null) detail.push(`rev ${rev}`)
+  detail.push('reversible')
+  out.push(line(detail.join(' · ')))
+  return out.join('\n')
+}
+
+// A read that landed on a page nothing has refreshed in a while. Distinct from a miss: the answer
+// is real, but the reader should weigh it knowing new facts have arrived since. Time alone does not
+// make a page wrong — unabsorbed facts do, which is why the count is the trigger, not the age.
+export function renderStale({ pages = [], unabsorbed, ms } = {}) {
+  const count = pages.length
+  const head = [`${MARK_STALE} agnoclast · read ${count} page${count === 1 ? '' : 's'} · stale`]
+  if (Number.isFinite(ms)) head.push(`${Math.round(ms)}ms`)
+  const out = [head.join(' · ')]
+  const names = joinFit(pages, WIDTH - 2)
+  if (names) out.push(line(names))
+  if (Number.isFinite(unabsorbed) && unabsorbed > 0) {
+    out.push(line(`${unabsorbed} record${unabsorbed === 1 ? '' : 's'} landed since the last edit — treat as possibly behind`))
+  }
+  return out.join('\n')
+}
+
+// A server too old to report counts. Context WAS served, so claiming a miss here would be a false
+// negative — every bit as dishonest as a false positive, and far easier to ship by accident because
+// `{...undefined}` silently produces an empty object that looks like a measured zero. "The server
+// said zero pages" and "the server did not say" are different facts and must never collapse into one
+// line. So: presence without arithmetic.
+export function renderUncounted() {
+  return `${MARK_HIT} agnoclast · context loaded`
+}
+
+// ── Ambient state ────────────────────────────────────────────────────────────────────────────────
+// The receipt is the moment; the blob is the presence. The statusline cannot call the org on every
+// render (it redraws constantly, and this product is bought or rejected on per-operation cost), so
+// hydration leaves a small breadcrumb behind and the statusline only ever reads the file.
+//
+// Deliberately NOT a cache of org data: it holds what THIS machine did and when, which is the one
+// thing it can state without a round-trip and without going stale behind the reader's back.
+
+const PRESENCE_FILE = 'presence.json'
+
+export function presencePath(home) {
+  return joinPath(home, '.cortex', PRESENCE_FILE)
+}
+
+function joinPath(...parts) {
+  return parts.join('/').replace(/\/+/g, '/')
+}
+
+// Pure: decide what the statusline should say, given the breadcrumb and how old it is. Extracted from
+// all I/O so the decay boundaries are testable without touching a clock or a disk.
+export function describePresence(state, nowMs, idleAfterMs = 45 * 60 * 1000) {
+  if (!state || typeof state !== 'object' || Array.isArray(state)) return { status: 'unwired', text: 'agnoclast · not wired' }
+  const at = Date.parse(state.at ?? '')
+  if (!Number.isFinite(at)) return { status: 'unwired', text: 'agnoclast · not wired' }
+
+  const ageMs = nowMs - at
+  if (ageMs > idleAfterMs) return { status: 'idle', text: 'agnoclast · idle' }
+
+  // A server too old to report counts served real context with an empty `pages`. Reading that as a
+  // miss would republish, in the ambient line, exactly the false negative renderUncounted exists to
+  // prevent — caught here by a live run against prod, which is the only place the two differ.
+  if (state.kind === 'uncounted') return { status: 'live', text: 'agnoclast · context loaded' }
+
+  const pages = Array.isArray(state.pages) ? state.pages.length : 0
+  if (state.kind === 'miss' || pages === 0) return { status: 'miss', text: 'agnoclast · no pages served' }
+  return { status: 'live', text: `agnoclast · ${pages} page${pages === 1 ? '' : 's'}` }
+}
+
+// The rendered statusline. `tick` advances the blob so it breathes as the conversation moves — the
+// motion is tied to real activity rather than to a timer, which is both cheaper and more honest: it
+// stops moving precisely when nothing is happening.
+export function renderStatusline(state, nowMs, tick = 0) {
+  const { status, text } = describePresence(state, nowMs)
+  const glyph = status === 'live' ? blobFrame(tick) : status === 'miss' ? MARK_MISS : status === 'idle' ? '·' : '○'
+  return `${glyph} ${text}`
+}
+
+// Single entry point. Chooses the state from server-supplied meta ONLY — an absent field routes to
+// the honest branch rather than an optimistic one. Returns '' when there is nothing truthful to
+// say, because a receipt with nothing behind it is the exact failure this file exists to prevent.
+export function formatReceipt(meta) {
+  // Arrays are objects and truthy, so a malformed payload would otherwise fall through and render a
+  // MISS — reporting a gap that was never measured. Junk in must produce silence, not a finding.
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return ''
+  if (meta.kind === 'write') return renderWrite(meta)
+
+  const pages = Array.isArray(meta.pages) ? meta.pages.filter(Boolean) : []
+  if (pages.length === 0) return renderMiss(meta)
+  if (Number.isFinite(meta.unabsorbed) && meta.unabsorbed > 0) return renderStale({ ...meta, pages })
+  return renderHit({ ...meta, pages })
+}

package/lib/server.mjs

@@ -934,8 +934,8 @@ export async function runServer(version) {
   server.registerTool(
     'my_brains',
     {
-      title: 'List your brains + which one writes land in',
-      description: 'List the brains (orgs/workspaces) you belong to. Reads span ALL of them, and writes to an EXISTING page now resolve to the brain that holds it — you do NOT need to check or switch anything before authoring, and you should not. The active brain is only a default for creating a page that exists nowhere yet. Use this when you genuinely need to see what brains exist or how they are populated.',
+      title: 'List your brains and what each one holds',
+      description: 'List the brains (orgs/workspaces) you belong to, with what each one CONTAINS — page count and sample titles. Reads span ALL of them, and an edit to an EXISTING page routes to the brain holding that page, so you do NOT need to check anything before editing. There is no active brain to set (ADR-0022 deleted the write pointer). Use this when creating a page that exists in NO brain yet: pick by relevance from the contents shown here and pass it as `brain`, because a caller with more than one brain must name one.',
       inputSchema: {},
     },
     async () => {
@@ -949,27 +949,36 @@ export async function runServer(version) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
         return toolError(`Could not list brains: ${d.message}`)
       }
-      const { brains, activeIsExplicit, activeSource, sessionOrgId, accountOrgId } = await res.json()
+      const { brains } = await res.json()
       if (!brains?.length) return { content: [{ type: 'text', text: 'You have no brains.' }] }
       // Show CONTENTS, not just the name (ADR-0020 §7 corollary): a brain named TTO that holds 4
       // pages while the real TTO inventory sits in Personal reads as correct and is exactly
       // backwards. The page count and a couple of titles make that visible at the moment of choosing.
+      //
+      // ⚠ ADR-0022 CLEANUP. This handler used to destructure activeIsExplicit / activeSource /
+      // sessionOrgId / accountOrgId and render a ▶ marker from b.isActive. /api/brains stopped
+      // returning ALL of those when the write pointer was deleted, and the client kept reading them.
+      // The failure was SILENT and confidently wrong rather than an error: `activeIsExplicit` arrived
+      // `undefined`, `!undefined` is `true`, so the branch meaning "you have one brain" printed
+      // unconditionally — telling a six-brain account it had one. The ▶ legend likewise advertised a
+      // marker that could no longer appear, because b.isActive was undefined for every row.
+      //
+      // The lesson worth keeping: a client reading a field the server no longer sends does not fail,
+      // it narrates. Every branch here asserted a FACT ("you have one brain") that was only ever an
+      // inference from a DIFFERENT condition (no explicit pointer set). Deleting the pointer decoupled
+      // the two and left the assertion running. Prefer deleting a stale branch to correcting it — a
+      // corrected branch still reads state that no longer exists.
       const lines = brains.map((b) => {
         const inv = b.pageCount === 0
           ? 'EMPTY'
           : `${b.pageCount} page${b.pageCount === 1 ? '' : 's'}${b.sampleTitles?.length ? `: ${b.sampleTitles.slice(0, 2).join(', ')}` : ''}`
-        return `${b.isActive ? '▶' : ' '} ${b.name}  (${b.role}${b.status !== 'active' ? `, ${b.status}` : ''})  — ${inv}  [${b.orgId}]`
+        return `  ${b.name}  (${b.role}${b.status !== 'active' ? `, ${b.status}` : ''})  — ${inv}  [${b.orgId}]`
       })
-      // Which layer is deciding, and what clearing it would fall back to — otherwise the pointer
-      // confusion simply reappears one level down.
-      const note = !activeIsExplicit
-        ? '\n(you have one brain; nothing to choose.)'
-        : activeSource === 'session'
-          ? `\n(this SESSION's override — your other sessions are unaffected${accountOrgId && accountOrgId !== sessionOrgId ? `; clearing it falls back to ${accountOrgId}` : ''}.)`
-          : activeSource === 'account'
-            ? '\n(account-wide pointer — shared by every session that has not set its own.)'
-            : ''
-      return { content: [{ type: 'text', text: `Your brains (▶ = default for NEW pages only — edits to existing pages route themselves):\n${lines.join('\n')}${note}` }] }
+      // Say how writes actually route now, since that is the question this list gets opened to answer.
+      const header = brains.length === 1
+        ? 'Your brain:'
+        : 'Your brains (reads span all of them; an edit routes to the brain holding the page; creating a NEW page takes an explicit `brain`):'
+      return { content: [{ type: 'text', text: `${header}\n${lines.join('\n')}` }] }
     },
   )
 
@@ -1046,14 +1055,19 @@ export async function runServer(version) {
         }
         target = byId ?? byName[0]
       } else {
-        target = brains.find((b) => b.isActive)
+        // ADR-0022: there is no active brain to fall back to — /api/brains stopped sending isActive
+        // when the write pointer was deleted, so the old `brains.find((b) => b.isActive)` here could
+        // only ever return undefined. Behaviour was already correct (undefined falls through to the
+        // error below, which is the right contract), but it was correct by accident, reading a field
+        // that no longer exists. Made explicit: sole membership resolves itself, anything else asks.
+        target = brains.length === 1 ? brains[0] : undefined
       }
       if (!target) {
         const names = brains.map((b) => `${b.name} [${b.orgId}]`).join(', ')
         return toolError(
           wanted
             ? `No brain called "${brain}". You belong to: ${names}.`
-            : `Could not tell which brain you mean — you belong to ${brains.length} and none is marked active. Pass one of: ${names}.`,
+            : `Could not tell which brain you mean — you belong to ${brains.length} and there is no default. Pass one of: ${names}.`,
         )
       }
 
@@ -1455,6 +1469,53 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'replace_variant',
+    {
+      title: 'Move one tier variant\'s body into another, collapsing the node to one page',
+      description: 'DESTRUCTIVE, and the only sanctioned way to fix a FORKED page. When one node exists at two tiers with different bodies, this moves the SOURCE variant\'s body into the TARGET variant\'s slot and DELETES the source, leaving the node with a single page. The source\'s body WINS — this is not `absorb`, where the target survives; in a fork repair the target is usually the damaged page, so mirroring absorb would keep the damage and delete the good copy. Sections are copied as ROWS, never re-derived from text: re-deriving a body from context is exactly what destroyed 258 sections on 2026-07-18 while sincerely reporting "copied verbatim". BEFORE CALLING: read_page the TARGET and pass its version as target_version — it proves you know which body is about to be overwritten, and a stale or guessed value is rejected rather than silently accepted. If the target tier has NO page, do not use this: the slot is free, so set_page_privacy moves the page there cheaply. Both prior bodies are retained in page history and the operation is reversible via page_history/rollback_page. Owner or editor on BOTH variants; an OWNERLESS target may be overwritten only by an org admin.',
+      inputSchema: {
+        kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
+        name: z.string().optional().describe('the exact page name (or pass `ref` instead — one of the two is required)'),
+        ref: z.string().optional().describe('the page\'s stable id, printed as `ref:` by read_page. PREFER THIS over name when you have it: a ref is unique across brains, so it addresses exactly one page and never needs a brain to disambiguate it.'),
+        source_tier: z.enum(['accessible', 'scoped', 'confidential']).describe('the variant whose BODY WINS and survives. This variant\'s row is then deleted.'),
+        target_tier: z.enum(['accessible', 'scoped', 'confidential']).describe('the OCCUPIED slot the body lands in. This variant\'s current body is DESTROYED (snapshotted to page history first). The surviving page sits at this tier.'),
+        target_version: z.string().describe('REQUIRED — the TARGET page\'s version, from read_page. Proves you know what is being overwritten. Do not retry a rejection blindly; re-read the target and confirm you are replacing what you think you are.'),
+        brain: z.string().optional().describe('only when the same page name exists in more than one of your brains'),
+      },
+    },
+    async ({ kind, name, ref, source_tier, target_tier, target_version, brain }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/replace-variant`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            kind, ...(name ? { name } : {}), ...(ref ? { ref } : {}),
+            source_tier, target_tier, target_version, ...(brain ? { brain } : {}),
+          }),
+        })
+      } catch (e) {
+        return toolError(`Could not replace variant: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        // The engine's rejections carry the remedy in their text (free slot → use set_page_privacy;
+        // hash mismatch → re-read, do not retry blindly). Surface it verbatim rather than paraphrasing.
+        if (out?.error) return toolError(`Could not replace variant: ${out.error}`)
+        const d = classify(res.status, res.headers.get('content-type'), '', res.headers.get('x-vercel-id'))
+        return toolError(`Could not replace variant: ${d.message}`)
+      }
+      if (!out) return { content: [{ type: 'text', text: 'Replace reported success, but the server returned no body — re-read the page before assuming it landed.' }] }
+      return {
+        content: [{
+          type: 'text',
+          text: `Done — "${out.moved.title}": the ${out.moved.from} body now occupies the ${out.moved.to} page (${out.sections} section${out.sections === 1 ? '' : 's'}), and the ${out.moved.from} variant was removed. The node now has ONE variant. ${out.note}`,
+        }],
+      }
+    },
+  )
+
   server.registerTool(
     'grant_page_access',
     {

package/lib/setup.mjs

@@ -134,7 +134,7 @@ export async function runSetup(argv, version) {
 
     ensureDir(settingsJson)
     writeFileSync(settingsJson, JSON.stringify(s, null, 2))
-    log(`  ✓ Capture hook + status line → ${settingsJson}${bak ? ' (backup saved)' : ''}`)
+    log(`  ✓ Capture + hydrate hooks + status line → ${settingsJson}${bak ? ' (backup saved)' : ''}`)
   } catch (e) {
     process.stderr.write(`  ✗ failed to update ${settingsJson}: ${e.message}\n`)
     process.exit(1)

package/lib/statusline.mjs

@@ -0,0 +1,67 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { renderStatusline } from './presence.mjs'
+
+// `cortex-mcp statusline` — the ambient half of the presence cue.
+//
+// Claude Code runs a statusline command on each redraw and prints its stdout under the prompt, so
+// this is the only place Agnoclast can sit permanently in view. It must therefore be the cheapest
+// thing in the product: no network, no auth, no org call. It reads one small local file that
+// hydration wrote and renders a line.
+//
+// It also has to be honest when nothing is happening. An indicator that looks alive while the system
+// is disconnected is worse than no indicator — that is precisely how the hook on this machine sat
+// dead for five days without anyone noticing. Hence the decay to `idle`, and `not wired` when there
+// is no breadcrumb at all.
+
+const STATE_DIR = () => join(homedir(), '.cortex')
+const STATE_FILE = () => join(STATE_DIR(), 'presence.json')
+const TICK_FILE = () => join(STATE_DIR(), 'presence-tick')
+
+function readState() {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE(), 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+// The blob advances one frame per redraw. Persisting the counter is what makes it BREATHE across
+// renders rather than freeze on a single glyph — without it every render would draw frame 0.
+function nextTick() {
+  try {
+    const prev = Number.parseInt(readFileSync(TICK_FILE(), 'utf8'), 10)
+    const tick = (Number.isFinite(prev) ? prev + 1 : 0) % 1_000_000
+    writeFileSync(TICK_FILE(), String(tick))
+    return tick
+  } catch {
+    try {
+      if (!existsSync(STATE_DIR())) mkdirSync(STATE_DIR(), { recursive: true })
+      writeFileSync(TICK_FILE(), '0')
+    } catch {
+      /* ignore — the statusline must never fail loudly */
+    }
+    return 0
+  }
+}
+
+// Record what hydration served, for the statusline to read. Best-effort by design: a failure here
+// must never affect the turn it was observing.
+export function writePresence({ pages = [], kind = 'hit', at = new Date().toISOString() } = {}) {
+  try {
+    if (!existsSync(STATE_DIR())) mkdirSync(STATE_DIR(), { recursive: true })
+    writeFileSync(STATE_FILE(), JSON.stringify({ pages, kind, at }))
+  } catch {
+    /* best-effort */
+  }
+}
+
+export function runStatusline() {
+  try {
+    process.stdout.write(renderStatusline(readState(), Date.now(), nextTick()) + '\n')
+  } catch {
+    // Print nothing rather than an error: a broken statusline should vanish, not shout.
+  }
+  return 0
+}

package/package.json

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