@theronap/agnoclast-mcp 0.9.96

package/lib/migrate_key.mjs

@@ -0,0 +1,139 @@
+import { homedir } from 'node:os'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { readJson, backupFile, ensureDir, writeJson } from './editors/_fsutil.mjs'
+import { allowedToolsFor } from './editors/claude.mjs'
+
+// The C2 key flip, made self-sufficient (ADR-0033 §5, T8).
+//
+// The plan was: C1 adds `mcp__agnoclast__*` to the permission allowlist, then C2 one release later
+// flips `mcpServers.cortex` → `mcpServers.agnoclast`. An earlier draft claimed the release gap made
+// the dangerous ordering "structurally impossible". IT DOES NOT. There is no forced upgrade
+// sequence and — by this ADR's own decision — no version telemetry, so a seat that sits idle
+// through C1 and then upgrades straight to a C2 build receives the flip having never received the
+// allowlist. The gap helps the common case and guarantees nothing.
+//
+// So the ordering guarantee lives HERE, on the machine, not in the release cadence:
+//
+//   1. ensure the new namespace's allow rules are present   (additive — nothing is removed)
+//   2. RE-READ from disk and verify they actually landed
+//   3. only then flip the config key
+//   4. re-read and verify the flip landed
+//   5. record it, so a re-run is a no-op
+//
+// If step 2 fails, the key is NOT flipped and the machine stays fully working on the old name. The
+// failure this prevents is silent: renamed tools that fall outside the allowlist do not error, they
+// prompt — which on an unattended seat (cron, scheduled agents, --print) is a hang or a skip.
+//
+// Note this is the REVERSE of the order editors/claude.mjs wire() uses, which writes .claude.json
+// before settings.json. That is fine for a fresh install, where neither exists yet; it is exactly
+// wrong for a migration, where the config key must move last.
+
+export const OLD_KEY = 'cortex'
+export const NEW_KEY = 'agnoclast'
+
+/** Where the completed migration is recorded. Under ~/.cortex, which ADR-0033 D3 keeps. */
+export const migrationStatePath = (home) => join(home, '.cortex', 'migration.json')
+
+/** PURE. The mcpServers object with our entry moved to the new key, preserving the entry verbatim.
+ *  Returns the same object reference semantics as the input (a copy), plus what it did. */
+export function migratedMcpServers(servers) {
+  const out = { ...(servers ?? {}) }
+  if (out[NEW_KEY] && !out[OLD_KEY]) return { servers: out, moved: false, reason: 'already-new-key' }
+  if (!out[OLD_KEY]) return { servers: out, moved: false, reason: 'no-entry' }
+  // Carry the entry across untouched: command, args (the package spec) and env all survive, so a
+  // dogfooder pinned to @latest stays pinned and the token is not re-derived.
+  out[NEW_KEY] = out[OLD_KEY]
+  delete out[OLD_KEY]
+  return { servers: out, moved: true, reason: null }
+}
+
+/** PURE. Allow rules the new namespace needs that this settings object does not yet carry. */
+export function missingAllows(settings, required = allowedToolsFor(NEW_KEY)) {
+  const have = new Set(Array.isArray(settings?.permissions?.allow) ? settings.permissions.allow : [])
+  return required.filter((r) => !have.has(r))
+}
+
+/** PURE. Settings with the new namespace's rules added. ADDITIVE — the old namespace's rules and
+ *  every user-added rule survive (editors/claude.mjs:48 invariant), and `deny` is never touched. */
+export function withNewAllows(settings, required = allowedToolsFor(NEW_KEY)) {
+  const s = settings && typeof settings === 'object' ? { ...settings } : {}
+  s.permissions = s.permissions && typeof s.permissions === 'object' ? { ...s.permissions } : {}
+  s.permissions.allow = Array.isArray(s.permissions.allow) ? [...s.permissions.allow] : []
+  for (const rule of required) if (!s.permissions.allow.includes(rule)) s.permissions.allow.push(rule)
+  return s
+}
+
+/**
+ * Perform the guarded migration on one machine. Idempotent.
+ * Returns { status, ...detail } where status is one of:
+ *   'already'            — the state file says this machine is done
+ *   'nothing-to-migrate' — no entry of ours under either key
+ *   'aborted'            — the allowlist could not be verified; the key was NOT flipped
+ *   'migrated'           — allows verified, key flipped, state recorded
+ */
+export function runKeyMigration({ home = homedir(), dryRun = false, io = {} } = {}) {
+  const { read = readJson, write = writeJson, backup = backupFile, mkdir = ensureDir, exists = existsSync } = io
+  const claudeJson = join(home, '.claude.json')
+  const settingsJson = join(home, '.claude', 'settings.json')
+  const statePath = migrationStatePath(home)
+  const required = allowedToolsFor(NEW_KEY)
+
+  if (exists(statePath)) {
+    try { if (read(statePath)?.to === NEW_KEY) return { status: 'already', statePath } } catch { /* re-run */ }
+  }
+
+  let cfg
+  try { cfg = read(claudeJson) } catch (e) { return { status: 'aborted', step: 'read-config', reason: e.message } }
+  const plan = migratedMcpServers(cfg?.mcpServers)
+  if (!plan.moved) return { status: 'nothing-to-migrate', reason: plan.reason }
+
+  // ── 1+2. Allowlist FIRST, then verify from disk. ───────────────────────────
+  let settings
+  try { settings = read(settingsJson) } catch (e) { return { status: 'aborted', step: 'read-settings', reason: e.message } }
+  const missing = missingAllows(settings, required)
+  if (dryRun) return { status: 'dry-run', wouldAdd: missing, wouldFlip: `${OLD_KEY} -> ${NEW_KEY}` }
+
+  if (missing.length) {
+    try {
+      backup(settingsJson)
+      mkdir(settingsJson)
+      write(settingsJson, withNewAllows(settings, required))
+    } catch (e) {
+      return { status: 'aborted', step: 'write-settings', reason: e.message, added: 0 }
+    }
+  }
+
+  // Re-read from disk. Writing is not the same as landing: a full disk, a concurrent writer, or a
+  // permission problem can all produce a successful-looking write and an unchanged file.
+  let verify
+  try { verify = read(settingsJson) } catch (e) {
+    return { status: 'aborted', step: 'verify-settings', reason: e.message }
+  }
+  const stillMissing = missingAllows(verify, required)
+  if (stillMissing.length) {
+    return { status: 'aborted', step: 'verify-settings', reason: 'allow rules did not persist', stillMissing }
+  }
+
+  // ── 3+4. Only now flip the key, then verify that too. ──────────────────────
+  try {
+    backup(claudeJson)
+    mkdir(claudeJson)
+    write(claudeJson, { ...cfg, mcpServers: plan.servers })
+  } catch (e) {
+    return { status: 'aborted', step: 'write-config', reason: e.message, allowsAdded: missing.length }
+  }
+  let cfgAfter
+  try { cfgAfter = read(claudeJson) } catch (e) {
+    return { status: 'aborted', step: 'verify-config', reason: e.message }
+  }
+  if (!cfgAfter?.mcpServers?.[NEW_KEY]) {
+    return { status: 'aborted', step: 'verify-config', reason: 'config key did not persist' }
+  }
+
+  // ── 5. Record it. Best-effort: a missing state file only costs an idempotent re-run. ──
+  const record = { from: OLD_KEY, to: NEW_KEY, allowsAdded: missing.length }
+  try { mkdir(statePath); write(statePath, record) } catch { /* non-fatal */ }
+
+  return { status: 'migrated', ...record, statePath }
+}

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

@@ -0,0 +1,51 @@
+// The names this package is published under, and how to derive each variant's package.json.
+//
+// ADR-0033 §3. Phase B publishes the SAME build under two names: `@theronap/agnoclast-mcp` going
+// forward, and `@theronap/cortex-mcp` in perpetuity, because the old name is hardcoded in hook
+// command strings and in generated launchd/cron scripts on machines we cannot reach. Generated
+// scripts are frozen at write time (D9), so a script written last year still invokes the old name
+// and no upgrade can repair it. Unpublishing would break those silently.
+//
+// "Byte-identical tarballs" is impossible — the name lives inside the tarball's own package.json —
+// so the guarantee is weaker and more precise: both variants are packed from ONE source tree in ONE
+// release step, and differ ONLY in the fields listed in VARIANT_FIELDS.
+//
+// The `bin` key differs too, and must. npm installs bins by key, so two packages both declaring
+// `cortex-mcp` collide on any machine that resolves both. Each variant declares a bin named after
+// itself. `npx -y <either name>` still works: with exactly one bin declared, npx runs it regardless
+// of what the key is called.
+
+/** The fields that may legitimately differ between variants. Anything else differing is a bug. */
+export const VARIANT_FIELDS = ['name', 'bin']
+
+/** Publish targets, primary first. Additive only: a name that has ever been published stays here. */
+export const PUBLISH_TARGETS = [
+  { name: '@theronap/agnoclast-mcp', bin: 'agnoclast-mcp', role: 'primary' },
+  { name: '@theronap/cortex-mcp', bin: 'cortex-mcp', role: 'alias' },
+]
+
+/** The entry point every variant's bin points at. One file, many names. */
+export const BIN_ENTRY = 'bin/cortex-mcp.mjs'
+
+/** PURE. The package.json to publish for one target, derived from the source manifest. */
+export function variantPackageJson(sourcePkg, target) {
+  if (!sourcePkg || typeof sourcePkg !== 'object') throw new TypeError('variantPackageJson: sourcePkg must be an object')
+  if (!target?.name || !target?.bin) throw new TypeError('variantPackageJson: target needs { name, bin }')
+  return { ...sourcePkg, name: target.name, bin: { [target.bin]: BIN_ENTRY } }
+}
+
+/** PURE. Fields that differ between two manifests, so a release can assert only VARIANT_FIELDS do.
+ *  Returns a sorted list of top-level keys whose JSON serialization differs. */
+export function differingFields(a, b) {
+  const keys = new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})])
+  const out = []
+  for (const k of keys) {
+    if (JSON.stringify(a?.[k]) !== JSON.stringify(b?.[k])) out.push(k)
+  }
+  return out.sort()
+}
+
+/** PURE. True when two variants differ ONLY in the fields allowed to differ. */
+export function variantsAreEquivalent(a, b) {
+  return differingFields(a, b).every((f) => VARIANT_FIELDS.includes(f))
+}

package/lib/red_link_triage.mjs

@@ -0,0 +1,37 @@
+// Red-link triage rendering (Mechanism 2) — the text an agent sees on a read_page miss.
+//
+// Standalone + dependency-free (like grep_cli.mjs) so it unit-tests without pulling the MCP SDK in.
+// server.mjs owns the fetch; this owns the wording.
+//
+// The demoted arm is the one that matters. A superseded/historical page stays greppable
+// (grep_brain_sections applies no validity filter) but read_page won't serve it (authored_page_tiers
+// filters validity='current'), so an agent that greps a hit and then read_page's it lands here — and
+// used to be told "no page yet, author it now". Authoring is pre-authorized, so the compliant next step
+// was to overwrite a page a human deliberately retired, with nothing to catch it. Absence invites
+// authoring; a demotion forbids it.
+//
+// Keyed off the ADDITIVE `t.demoted` flag, checked BEFORE category — never off a new category value. A
+// server predating the flag omits it and every arm behaves exactly as before, so client and server can
+// ship in either order.
+
+// PURE: triage payload → miss text.
+export function renderTriage(t, name) {
+  const refs = t.tracked
+    ? ` It's referenced by ${t.refCount} page${t.refCount === 1 ? '' : 's'}${t.isSteward ? ' and is routed to YOU as its most-likely steward' : ''}.`
+    : ''
+  const aliasHint = `if it's really an existing page under another title, \`grep "${name}"\` to find it, then \`alias_page name="${name}" target_name="<that page>"\``
+  if (t.demoted) {
+    // KWA-28 — `red_link_targets` is a graph-side object and must carry an as-of. The server ALREADY
+    // sends `updatedAt` on this arm (the retirement's own timestamp) and this renderer was dropping it,
+    // so "deliberately retired" read as timeless. WHEN it was retired is the load-bearing fact here:
+    // the whole point of the arm is to stop an agent authoring over a human decision, and a decision
+    // from yesterday and one from eight months ago warrant different confidence about whether it still
+    // holds. Explicitly undated rather than silent when the server predates the field.
+    const when = t.updatedAt ? ` on ${String(t.updatedAt).slice(0, 10)}` : ' (retirement date not recorded)'
+    return `\n\n[[${name}]] EXISTS but is marked ${t.validity ?? 'superseded'} — it was authored and then deliberately retired${when}, so read_page (which serves only current pages) will not show it. It is NOT missing.${refs} Do NOT author over it: that would silently overwrite a decision someone made on purpose. Read it with \`page_history "${name}"\` then \`read_page "${name}"\` with a version. If it genuinely should be live again, revive it deliberately with \`set_page_validity\`.`
+  }
+  if (t.category === 'node') {
+    return `\n\n[[${name}]] is a wanted page — a ${t.isPerson ? 'person' : 'node'} exists but has no page yet.${refs} Either author it now with \`author\`, or ${aliasHint}.`
+  }
+  return `\n\n"${name}" isn't authored anywhere yet.${refs} Either author a new page with \`author\`, or ${aliasHint}.`
+}

package/lib/redact.mjs

@@ -0,0 +1,40 @@
+// redact.mjs — strip high-confidence credential patterns from text BEFORE it leaves
+// the machine (capture POSTs a transcript tail to the org). A leaked secret in a
+// transcript — a user pastes an API key, a tool reads a config file holding one, or
+// (the 2026-06-22 finding) a login token sits inlined in a hook command — must never
+// be transmitted or stored. Conservative by design: targets known secret SHAPES so it
+// won't mangle ordinary prose or record/UUID ids. Mirrored server-side in
+// web/lib/engine/redact.ts — keep the two pattern lists in sync.
+
+// [pattern, replacement]. Order matters: most specific Anthropic forms first so a
+// login token reads as [REDACTED:anthropic-oauth], not the generic key bucket.
+const PATTERNS = [
+  [/sk-ant-oat\d{2}-[A-Za-z0-9_-]{20,}/g, '[REDACTED:anthropic-oauth]'],
+  [/sk-ant-api\d{2}-[A-Za-z0-9_-]{20,}/g, '[REDACTED:anthropic-key]'],
+  [/sk-ant-[A-Za-z0-9_-]{20,}/g, '[REDACTED:anthropic]'],
+  [/sk-proj-[A-Za-z0-9_-]{20,}/g, '[REDACTED:openai]'],
+  [/sk-[A-Za-z0-9]{32,}/g, '[REDACTED:openai]'],
+  [/gh[pousr]_[A-Za-z0-9]{36,}/g, '[REDACTED:github]'],
+  [/github_pat_[A-Za-z0-9_]{22,}/g, '[REDACTED:github-pat]'],
+  [/AKIA[0-9A-Z]{16}/g, '[REDACTED:aws-akid]'],
+  [/AIza[0-9A-Za-z_-]{35}/g, '[REDACTED:google]'],
+  [/xox[baprs]-[A-Za-z0-9-]{10,}/g, '[REDACTED:slack]'],
+  [/eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, '[REDACTED:jwt]'],
+  [/(Bearer\s+)[A-Za-z0-9._-]{20,}/g, '$1[REDACTED]'],
+  // Agnoclast's own login token wherever it appears in KEY=value / KEY: value form (hooks.json,
+  // config.toml, shell commands — the 2026-07-02 finding: a grep of hooks.json put the live token
+  // in a transcript and nothing below caught it). Specific pattern first for the accurate label.
+  [/((?:AGNOCLAST|CORTEX)_TOKEN["']?\s*[=:]\s*["']?)[0-9a-fA-F][0-9a-fA-F-]{30,}/g, '$1[REDACTED:agnoclast-token]'],
+  // Generic secret-shaped assignment: an UPPER_SNAKE name ending in TOKEN/SECRET/PASSWORD/
+  // API_KEY/APIKEY assigned a ≥16-char value. Conservative: the name-suffix + length floor keep
+  // ordinary prose, short placeholders, and bare UUIDs (record ids) intact.
+  [/([A-Z][A-Z0-9_]{2,}(?:TOKEN|SECRET|PASSWORD|API_KEY|APIKEY)["']?\s*[=:]\s*["']?)[A-Za-z0-9._/+-]{16,}/g, '$1[REDACTED:env]'],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '[REDACTED:private-key]'],
+]
+
+export function redactSecrets(text) {
+  if (!text || typeof text !== 'string') return text
+  let out = text
+  for (const [re, repl] of PATTERNS) out = out.replace(re, repl)
+  return out
+}

package/lib/rename_notice.mjs

@@ -0,0 +1,31 @@
+import { NEW_KEY, OLD_KEY } from './migrate_key.mjs'
+
+// The C1 warning (ADR-0033 §4, T7).
+//
+// THIS WHOLE MODULE IS TEMPORARY. It ships in C1, one release ahead of the C2 key flip, and is
+// DELETED a release after C2. If you are reading this and C2 shipped more than one release ago,
+// delete the file, its test, and the two lines that call it in doctor.mjs.
+//
+// The decision it implements: warn once that the flip is coming, then it is the user's file and
+// their call. No detection loop, no dismiss state, no expiry to guess. Earlier drafts proposed
+// grepping every user's CLAUDE.md on a cadence and nagging until it changed; that was rejected —
+// the package has never written CLAUDE.md and should not start, and a nag that cannot tell a fixed
+// file from an unfixed one is wrong for some readers the entire time it runs.
+//
+// It is self-limiting without any state: the notice renders only while this machine is still on the
+// OLD config key. Once `migrate-key` flips it, the condition is false and the message stops. That is
+// "warn, then leave them alone" expressed as a condition rather than as a timer.
+
+/** C1 sets this true. Until then the notice is inert, so building it now changes nothing for the
+ *  people currently on @latest. Flipping this constant IS the C1 release. */
+export const RENAME_NOTICE_ACTIVE = false
+
+/** PURE. The one-line warning, or null when it should stay quiet.
+ *  `key` is which config key answered on this machine ('cortex' | 'agnoclast' | null). */
+export function renderRenameNotice(key, { active = RENAME_NOTICE_ACTIVE } = {}) {
+  if (!active) return null
+  if (key !== OLD_KEY) return null // already flipped, or nothing wired — nothing to warn about
+  return `Agnoclast: heads up — the MCP tools are being renamed from mcp__${OLD_KEY}__* to `
+    + `mcp__${NEW_KEY}__*. If your CLAUDE.md names the old tools, update it when convenient. `
+    + `Run \`npx -y @theronap/cortex-mcp migrate-key\` to switch now, or wait and it will happen for you.`
+}