@theronap/agnoclast-mcp 0.9.96

package/lib/editors/cursor.mjs

@@ -0,0 +1,77 @@
+// Editor adapter: Cursor. P0-b task 4 (+ review fixes).
+// ~/.cursor/mcp.json uses the same mcpServers.cortex shape as Claude (minus the `type` field the real
+// Cursor config omits), so wiring Cursor is a pure JSON merge (mergeCursorMcp).
+import { homedir } from 'node:os'
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { backupFile } from './_fsutil.mjs'
+
+/** Merge the Agnoclast MCP server into a Cursor mcp.json object. Pure + idempotent: sets only the
+ *  `cortex` entry, preserves every other server. `spec` is the package@dist-tag STRING — the same
+ *  convention claude/codex/setup.mjs use, so one install driver can pass a single spec to every adapter. */
+export function mergeCursorMcp(existing, spec, token) {
+  const cfg = existing && typeof existing === 'object' ? { ...existing } : {}
+  cfg.mcpServers = cfg.mcpServers && typeof cfg.mcpServers === 'object' ? { ...cfg.mcpServers } : {}
+  cfg.mcpServers.cortex = { command: 'npx', args: ['-y', spec], env: { CORTEX_TOKEN: token } }
+  return cfg
+}
+
+/** @type {import('./index.mjs').EditorAdapter} */
+export default {
+  id: 'cursor',
+  displayName: 'Cursor',
+
+  detect({ home = homedir(), exists = existsSync } = {}) {
+    return exists(join(home, '.cursor'))
+  },
+
+  // Today Cursor is capture-only: the hook buffers turns and POSTs to /api/ingest, but does not
+  // inject sibling-session context at prompt time. promptTimeInjection stays false until the
+  // Pillar-1 Cursor inject hook is built (a named gap in cross-app-session-visibility-spec.md).
+  capabilities: {
+    promptTimeInjection: false,
+    sessionStart: false,
+    captureHook: true,           // ~/.cursor/hooks/cortex-cursor.mjs
+    skillDir: null,              // Cursor rules/commands dir — revisit in Pillar 2
+    docTrigger: 'hook',
+  },
+
+  // Non-fatal by contract: a Cursor failure (parse OR IO) must never abort the other editors' wiring.
+  async wire({ home = homedir(), token, spec, log = () => {} } = {}) {
+    const wrote = [], skipped = [], warnings = []
+    if (!token) { warnings.push('no token — skipped Cursor'); return { wrote, skipped, warnings } }
+
+    const cursorDir = join(home, '.cursor')
+    const mcpPath = join(cursorDir, 'mcp.json')
+    try {
+      let existing = {}
+      if (existsSync(mcpPath)) {
+        try {
+          existing = JSON.parse(readFileSync(mcpPath, 'utf8'))
+        } catch {
+          // Data-loss guard: a malformed mcp.json may still hold the user's other MCP servers we can't
+          // safely parse. Do NOT overwrite it with a cortex-only config — skip with a warning.
+          warnings.push(`${mcpPath} is not valid JSON — left untouched (fix it, then re-run) to avoid dropping your other MCP servers`)
+          return { wrote, skipped, warnings }
+        }
+      }
+      const bak = backupFile(mcpPath)
+      mkdirSync(cursorDir, { recursive: true })
+      writeFileSync(mcpPath, JSON.stringify(mergeCursorMcp(existing, spec, token), null, 2))
+      wrote.push(mcpPath)
+      log(`  ✓ MCP server → ${mcpPath}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      warnings.push(`Cursor MCP wiring skipped: ${e.message}`) // IO error → non-fatal, siblings unaffected
+    }
+
+    // Capture hook: detect, don't fabricate. The cortex-cursor.mjs hook isn't bundled in this package
+    // yet (it was hand-installed), so warn rather than write a guessed file. Bundling it is follow-up.
+    const hookPath = join(cursorDir, 'hooks', 'cortex-cursor.mjs')
+    if (!existsSync(hookPath)) {
+      warnings.push('Cursor capture hook (~/.cursor/hooks/cortex-cursor.mjs) not found — Cursor sessions will not be captured until it is installed')
+    } else {
+      skipped.push(`${hookPath} (already present)`)
+    }
+    return { wrote, skipped, warnings }
+  },
+}

package/lib/editors/index.mjs

@@ -0,0 +1,42 @@
+// Editor adapter registry (P0-b task 1). One place that knows every editor Agnoclast can wire.
+// Adding an editor = add a module here; the install driver + capability manifest fall out of it.
+//
+// EditorAdapter shape (see the four modules):
+//   id            stable string id (used in the manifest + `--editor <id>`)
+//   displayName   human label
+//   detect(env)   → boolean; env = { home?, exists? } is injectable for tests
+//   capabilities  { promptTimeInjection, sessionStart, captureHook, skillDir, docTrigger }
+//   wire(ctx)     → performs the install for this editor (stubbed in task 1)
+//
+/** @typedef {Object} EditorAdapter */
+
+import claude from './claude.mjs'
+import codex from './codex.mjs'
+import cursor from './cursor.mjs'
+import antigravity from './antigravity.mjs'
+
+export const ADAPTERS = [claude, codex, cursor, antigravity]
+
+/**
+ * Resolve which editors an install targets.
+ *   'auto'          → every adapter whose detect() is true on this machine (the default)
+ *   'all'           → every adapter, regardless of detection
+ *   'id'|'a,b'      → the named adapter(s); throws on an unknown id (fail loud, don't silently skip)
+ *
+ * @param {string} [flag='auto']
+ * @param {{ adapters?: EditorAdapter[], env?: { home?: string, exists?: (p: string) => boolean } }} [opts]
+ * @returns {EditorAdapter[]}
+ */
+export function resolveEditors(flag = 'auto', { adapters = ADAPTERS, env } = {}) {
+  if (flag === 'all') return [...adapters]
+  if (flag === 'auto') return adapters.filter((a) => a.detect(env))
+
+  const ids = String(flag).split(',').map((s) => s.trim()).filter(Boolean)
+  const known = new Set(adapters.map((a) => a.id))
+  const unknown = ids.filter((id) => !known.has(id))
+  if (unknown.length) {
+    throw new Error(`Unknown editor(s): ${unknown.join(', ')}. Known: ${adapters.map((a) => a.id).join(', ')}`)
+  }
+  // Preserve registry order, dedupe.
+  return adapters.filter((a) => ids.includes(a.id))
+}

package/lib/extract_typed.mjs

@@ -0,0 +1,68 @@
+import { spawnSync } from 'child_process'
+import { edgeSafeEnv } from './edge_extract.mjs'
+
+// Typed extraction (synthesis slice 2) — registry-driven. Given a transcript + the node_types registry,
+// the LLM emits TYPED NOTES (one per real thing that happened / was mentioned) conforming to the type
+// definitions, instead of the old loose {summary, people, namedEntities} blob. Runs locally on the
+// subscription (edgeSafeEnv strips ANTHROPIC_*). PARALLEL to edge_extract.mjs — does NOT replace it yet;
+// built to be tested in isolation, then wired into capture once proven (slice 2b).
+//
+// Per the ontology (cortex-node-ontology-spec): programmatic fields are filled by the caller from source
+// metadata BEFORE this runs; here the LLM fills only what the text supports, self-flags llm_filled fields,
+// and uses "unknown" for required fields it can't determine (→ red-link downstream). It may also COIN a
+// new type (open registry) when nothing fits.
+
+function typeCard(t) {
+  const fields = (arr) => (Array.isArray(arr) ? arr : []).map((f) => `${f.field}${f.note ? ` (${f.note})` : ''}`).join(', ')
+  return `• ${t.name} [${t.layer}]${t.applies_to?.length ? ` applies_to:${t.applies_to.join('/')}` : ''}\n` +
+    `    required: ${fields(t.required_fields) || '—'}\n` +
+    `    optional: ${fields(t.optional_fields) || '—'}\n` +
+    `    how: ${t.extraction_instructions}`
+}
+
+export function extractTyped(transcript, registry, opts = {}) {
+  const text = (transcript ?? '').trim()
+  if (!text || !Array.isArray(registry) || !registry.length) return null
+  const catalog = registry.map(typeCard).join('\n')
+  const prompt =
+    'You are building an organization knowledge graph from a work session. Using ONLY the node/note types ' +
+    'in the CATALOG below, emit the typed notes this session supports — one per real thing that happened ' +
+    '(actions, decisions, communications) or entity referenced (people, projects, etc.).\n\n' +
+    'RULES:\n' +
+    '- Fill a field ONLY if the text supports it. If a REQUIRED field is unknowable, set it to "unknown".\n' +
+    '- List the fields YOU inferred (vs. ones obviously given) in "llm_filled".\n' +
+    '- Reference other things by name (e.g. actors:["Jane Doe"]) — do not invent ids.\n' +
+    '- NEVER invent numbers (amounts, values, metrics) — "unknown" if not explicitly stated.\n' +
+    '- Be conservative: only emit a note for something genuinely present. Empty array is fine.\n' +
+    '- If something important fits NO type, you may coin one: add it to "new_types" with ' +
+    '{name, layer, required_fields:[{field}], why}.\n\n' +
+    'Return ONLY minified JSON: {"notes":[{"type","fields":{...},"llm_filled":[...]}],"new_types":[...]}.\n\n' +
+    '--- CATALOG ---\n' + catalog + '\n\n--- SESSION ---\n' + text.slice(0, 12000) + '\n--- END ---'
+  try {
+    const r = spawnSync(
+      'claude',
+      ['--print', '--model', opts.model ?? process.env.CORTEX_SUMMARY_MODEL ?? 'claude-haiku-4-5', prompt],
+      { env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }), encoding: 'utf8', timeout: 120_000, maxBuffer: 8 * 1024 * 1024 },
+    )
+    if (r.status !== 0 || !r.stdout) return null
+    return parseTyped(r.stdout)
+  } catch {
+    return null
+  }
+}
+
+export function parseTyped(out) {
+  if (!out) return null
+  const start = out.indexOf('{')
+  const end = out.lastIndexOf('}')
+  if (start < 0 || end <= start) return null
+  try {
+    const o = JSON.parse(out.slice(start, end + 1))
+    return {
+      notes: Array.isArray(o.notes) ? o.notes : [],
+      new_types: Array.isArray(o.new_types) ? o.new_types : [],
+    }
+  } catch {
+    return null
+  }
+}

package/lib/graphify_sync.mjs

@@ -0,0 +1,134 @@
+import { spawnSync } from 'child_process'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { fetchCortex, classify, resolveBase, resolveEnvToken } from './diagnose.mjs'
+
+// `cortex-mcp graphify-sync [path]` — local producer: incrementally rebuild a repo's structural
+// code graph (graphify — tree-sitter AST, no LLM) and log an evidence-tier timeline event via
+// POST /api/timeline/graphify. LLM-free, idempotent (server dedupes on repo+commit), additive —
+// never touches the wiki graph (cortex-wiki-primary-spec: extracted/structural data is evidence,
+// never auto-promoted into an authored page).
+//
+// Meant to run from a periodic cron/launchd job per repo you want graphed — NOT a git post-commit
+// hook. A hook fires synchronously inside `git commit`/`git push` and can race another session's
+// git operations in a shared checkout (see reference-cortex-shared-checkout-hazards); a timer-based
+// job just reads whatever the tree looks like at that moment, no hook into git operations at all.
+
+function run(cmd, args, cwd) {
+  const r = spawnSync(cmd, args, { cwd, encoding: 'utf8', timeout: 120_000 })
+  return r.status === 0 ? (r.stdout || '').trim() : null
+}
+
+function repoFullNameFromRemote(cwd) {
+  const url = run('git', ['remote', 'get-url', 'origin'], cwd)
+  if (!url) return null
+  const m = /github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/i.exec(url)
+  return m ? `${m[1]}/${m[2]}` : null
+}
+
+// `--brain <name-or-org-id>` — which brain an UNROUTED repo's graph event lands in.
+//
+// Deliberately a flag and nothing cleverer. /api/timeline/graphify routes deterministically by repo
+// (resolveSourceRoute) and only asks when the repo has no route; its comment is blunt about why it
+// must not be guessed: this writes a `records` row unique on (org_id, dedupe_key), so "a repo whose
+// graph updates land in two brains becomes two record sets that never reconcile, and re-pointing
+// later converges on nothing (ADR-0020). It is the one write class where a wrong answer is genuinely
+// unrecoverable." So: no sweep (unlike `resolve`, which is a maintenance pass over everything) and
+// no auto-pick.
+//
+// It does NOT create a source route as a side effect, though that would stop the question recurring:
+// routes are append-only precisely because "re-pointing a live source splits its history
+// irreparably", and a near-irreversible write should not fall out of a CLI flag. This command runs
+// from a per-repo cron/launchd job, so the flag lives in that job's definition — answered once,
+// where it is visible. (Route creation currently has NO client on any surface; that is a separate
+// gap, not this command's to paper over.)
+// Split argv into { cwd, brain }. Pure + exported so the ordering trap below is unit-testable
+// without a git repo, a graphify binary or a network.
+//
+// THE TRAP: argv[0] doubles as the optional repo path, and `--brain`'s VALUE has no leading '-'.
+// Parsed naively, `graphify-sync --brain Personal` reads "Personal" as the path and syncs whatever
+// happens to be there. So the flag and its value are stripped BEFORE the positional check.
+export function parseGraphifyArgs(argv = [], fallbackCwd = process.cwd()) {
+  const bIdx = argv.indexOf('--brain')
+  const brain = bIdx === -1 ? null : argv[bIdx + 1]
+  if (bIdx !== -1 && (!brain || brain.startsWith('-'))) {
+    return { error: 'Usage: graphify-sync [path] [--brain <name-or-org-id>]' }
+  }
+  const rest = bIdx === -1 ? argv : argv.filter((_, i) => i !== bIdx && i !== bIdx + 1)
+  return { cwd: rest[0] && !rest[0].startsWith('-') ? rest[0] : fallbackCwd, brain }
+}
+
+export async function runGraphifySync(argv = []) {
+  const parsed = parseGraphifyArgs(argv)
+  if (parsed.error) { process.stderr.write(parsed.error + '\n'); return 1 }
+  const { cwd, brain } = parsed
+  const TOKEN = resolveEnvToken().token
+  const BASE = resolveBase(process.env.CORTEX_URL)
+  if (!TOKEN) {
+    process.stderr.write('cortex-mcp graphify-sync: CORTEX_TOKEN is required.\n')
+    return 1
+  }
+  const graphFile = join(cwd, 'graphify-out', 'graph.json')
+  if (!existsSync(graphFile)) {
+    process.stderr.write(`cortex-mcp graphify-sync: no graph at ${graphFile} — run the graphify skill (\`/graphify .\`) in this repo first.\n`)
+    return 1
+  }
+  if (!run('graphify', ['--version'], cwd)) {
+    process.stderr.write('cortex-mcp graphify-sync: graphify CLI not on PATH (`uv tool install graphifyy`).\n')
+    return 1
+  }
+
+  const update = spawnSync('graphify', ['update', '.'], { cwd, encoding: 'utf8', timeout: 300_000, maxBuffer: 8 * 1024 * 1024 })
+  if (update.status !== 0) {
+    process.stderr.write(`cortex-mcp graphify-sync: \`graphify update\` failed:\n${(update.stderr || update.stdout || '').trim()}\n`)
+    return 1
+  }
+  if (update.stdout) process.stdout.write(update.stdout.trim() + '\n')
+
+  let graph
+  try {
+    graph = JSON.parse(readFileSync(graphFile, 'utf8'))
+  } catch (e) {
+    process.stderr.write(`cortex-mcp graphify-sync: could not read ${graphFile}: ${e.message}\n`)
+    return 1
+  }
+  const nodes = Array.isArray(graph.nodes) ? graph.nodes : []
+  const nodeCount = nodes.length
+  const edgeCount = Array.isArray(graph.links) ? graph.links.length : 0
+  const communityCount = new Set(nodes.map((n) => n.community).filter((c) => c !== undefined)).size
+  const commitSha = typeof graph.built_at_commit === 'string' ? graph.built_at_commit : null
+
+  const repo = repoFullNameFromRemote(cwd)
+  if (!commitSha || !repo) {
+    process.stdout.write('cortex-mcp graphify-sync: graph updated locally; skipping timeline log (no git commit / no github.com origin found).\n')
+    return 0
+  }
+
+  const res = await fetchCortex(`${BASE}/api/timeline/graphify`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ repo, commitSha, nodeCount, edgeCount, communityCount, ...(brain ? { brain } : {}) }),
+  })
+  if (!res.ok) {
+    const body = await res.text()
+    const d = classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id'))
+    process.stderr.write(d.message + '\n')
+    // classify names the brains but speaks in MCP terms ("re-run this tool with `brain`"). Say the
+    // actual flag, and where to put it — this runs unattended from cron, so the person reading this
+    // is looking at a log after the fact, not a prompt.
+    if (res.status === 409 && !brain) {
+      process.stderr.write(
+        `\n${repo} has no routing decision yet, so it cannot be filed without one.\n` +
+        `Re-run with:  cortex-mcp graphify-sync ${cwd === process.cwd() ? '' : `${cwd} `}--brain "<name-or-org-id>"\n` +
+        `and add that flag to this repo's cron/launchd job so it stops asking.\n`,
+      )
+    }
+    return 1
+  }
+  const payload = await res.json()
+  process.stdout.write(
+    `Logged to Agnoclast timeline: ${repo}@${commitSha.slice(0, 7)} (${nodeCount} nodes, ${edgeCount} edges, ${communityCount} communities)` +
+      `${payload.inserted ? '' : ' (already logged)'}\n`,
+  )
+  return 0
+}

package/lib/grep_cli.mjs

@@ -0,0 +1,82 @@
+import { fetchCortex, classify, resolveBase, resolveEnvToken } from './diagnose.mjs'
+
+// `cortex grep` CLI + shared formatting for the MCP grep tool (Lane B / T6). Thin client of
+// GET /api/grep — the server runs the RLS-INVOKER RPC AS the viewer, so no DB credentials live here.
+// Output is ASCII-only (outbound-message convention).
+
+// Pure: parse argv after `grep` → { query, mode, max }.
+//   cortex grep <terms...> [--substring | --literal] [--max N]
+// Default mode is 'fts' (ranked keyword — multi-word queries work); pass --substring/--literal for
+// an exact literal match (identifiers, [[links]], code). (#220)
+export function parseGrepArgs(argv = []) {
+  const out = { query: '', mode: 'fts', max: undefined }
+  const terms = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--mode') {
+      out.mode = argv[++i] === 'substring' ? 'substring' : 'fts'
+    } else if (a === '--fts') {
+      out.mode = 'fts'
+    } else if (a === '--substring' || a === '--literal') {
+      out.mode = 'substring'
+    } else if (a === '--max') {
+      const n = Number(argv[++i])
+      if (Number.isFinite(n)) out.max = Math.trunc(n)
+    } else {
+      terms.push(a)
+    }
+  }
+  out.query = terms.join(' ').trim()
+  return out
+}
+
+// Pure: render a /api/grep payload to readable ASCII text.
+export function formatGrepHits(payload, query) {
+  const hits = (payload && payload.hits) || []
+  if (!hits.length) {
+    // Reactive red-link hint — ONLY when the query looks like a page NAME (short, no code/operators), so
+    // code and typo searches don't get nagged. read_page carries the full triage (node / new / alias).
+    const nameish = /^[\w .'-]{2,40}$/.test(query) && query.split(/\s+/).length <= 5
+    return nameish
+      ? `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}":`, '']
+  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(' ')}`)
+  }
+  return lines.join('\n')
+}
+
+// Effectful: run the CLI subcommand. Returns an exit code.
+export async function runGrep(rest = []) {
+  const TOKEN = resolveEnvToken().token
+  const BASE = resolveBase(process.env.CORTEX_URL)
+  if (!TOKEN) {
+    process.stderr.write('cortex grep: CORTEX_TOKEN is required (get yours from the Agnoclast console).\n')
+    return 1
+  }
+  const { query, mode, max } = parseGrepArgs(rest)
+  if (!query) {
+    process.stderr.write('usage: cortex grep <query> [--substring|--literal] [--max N]\n')
+    return 1
+  }
+  const qs = new URLSearchParams({ q: query, mode })
+  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()
+    process.stderr.write(
+      classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message + '\n',
+    )
+    return 1
+  }
+  const payload = await res.json()
+  process.stdout.write(formatGrepHits(payload, query) + '\n')
+  return 0
+}

package/lib/hydrate.mjs

@@ -0,0 +1,181 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSync, unlinkSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { fetchCortex, classify, resolveBase, resolveTokenSource } 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 Agnoclast context BEFORE it answers — then never again this session. It closes the
+// gap that read-triggered authoring can't: an agent that never READS the wiki (works from code + memory)
+// never triggers a currency update, and re-derives already-authored truth. cortex-context is a SKILL the
+// model may forget to invoke; this makes the first hydration non-discretionary (the same move that made
+// authoring pre-authorized). Mid-session topic-shift refresh stays the cortex-context skill's job — a
+// hook can't cheaply judge a semantic topic change.
+//
+// It MUST be synchronous: the value is being in-context before the reply, so it cannot be detached like
+// capture. That cost is bounded — once per session, an 8s timeout, and FAIL-OPEN: any miss injects
+// nothing and never holds up the user's first message. Always exits 0; hydration must never break a turn.
+
+const HYDRATE_TIMEOUT_MS = 8_000
+const MAX_ATTEMPTS = 2 // give up after N failed tries so a dead endpoint isn't re-hit every turn
+const MIN_SUBSTANTIVE_CHARS = 15
+// Bare greetings/affirmations are not a real opening query — skip WITHOUT marking done, so the first
+// substantive prompt still hydrates. Anchored to the whole string so "go" skips but "go build X" does not.
+const TRIVIAL_RE = /^(hi|hey|hello|yo|sup|thanks|thank you|ty|ok|okay|k|kk|yes|yep|yup|yeah|no|nope|nah|sure|go|go ahead|do it|continue|next|please)\b[\s!.?]*$/i
+const STATE_RETENTION_DAYS = 7
+
+function hydrationDir() {
+  return join(homedir(), '.cortex', 'hydration')
+}
+function stateFile(sessionId) {
+  return join(hydrationDir(), `${sessionId}.json`)
+}
+
+function readState(sessionId) {
+  try {
+    return JSON.parse(readFileSync(stateFile(sessionId), 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+function writeState(sessionId, state) {
+  try {
+    const dir = hydrationDir()
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+    writeFileSync(stateFile(sessionId), JSON.stringify(state))
+  } catch {
+    /* best-effort — a state write failure must never break the turn */
+  }
+}
+
+// Drop state files older than the retention window so per-session markers can't grow unbounded.
+// Best-effort, silent (mirrors the snapshot/beacon prune discipline).
+function pruneState() {
+  try {
+    const dir = hydrationDir()
+    if (!existsSync(dir)) return
+    const cutoff = Date.now() - STATE_RETENTION_DAYS * 24 * 3600 * 1000
+    for (const f of readdirSync(dir)) {
+      try {
+        if (statSync(join(dir, f)).mtimeMs < cutoff) unlinkSync(join(dir, f))
+      } catch {
+        /* ignore individual failures */
+      }
+    }
+  } catch {
+    /* ignore — never break the turn */
+  }
+}
+
+// A real opening question, not chit-chat. Cheap heuristic (length + a trivial-phrase guard); the point is
+// only to avoid burning the once-per-session hydration on "hi". Anything borderline hydrates.
+export function isSubstantive(prompt) {
+  const p = (prompt || '').trim()
+  if (p.length < MIN_SUBSTANTIVE_CHARS) return false
+  if (TRIVIAL_RE.test(p)) return false
+  return true
+}
+
+// Pure gate decision, extracted so it is unit-testable without stdin/network. Returns one of:
+//   'skip-no-session' | 'skip-done' | 'skip-attempts' | 'skip-trivial' | 'go'
+export function decideHydrate({ hasSessionId, done, attempts = 0, prompt, maxAttempts = MAX_ATTEMPTS }) {
+  if (!hasSessionId) return 'skip-no-session' // can't gate without an id → do nothing, never fire every turn
+  if (done) return 'skip-done' // the gate: hydrate exactly once per session
+  if (attempts >= maxAttempts) return 'skip-attempts' // stop retrying a dead endpoint
+  if (!isSubstantive(prompt)) return 'skip-trivial' // wait for a real query; do NOT mark done
+  return 'go'
+}
+
+// UserPromptSubmit sends a JSON payload on stdin: { session_id, prompt, cwd, ... }.
+function readHook() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+export async function runHydrate() {
+  pruneState()
+
+  const hook = readHook()
+  const sessionId = hook.session_id || process.env.CLAUDE_SESSION_ID || ''
+  const prompt = hook.prompt ?? hook.user_prompt ?? ''
+  const state = readState(sessionId)
+
+  const action = decideHydrate({
+    hasSessionId: Boolean(sessionId),
+    done: Boolean(state.done),
+    attempts: state.attempts ?? 0,
+    prompt,
+  })
+  if (action !== 'go') return 0
+
+  const token = resolveTokenSource().token
+  if (!token) return 0 // not wired → silent no-op (don't mark done; a later session may be wired)
+  const base = resolveBase(process.env.CORTEX_URL)
+
+  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(
+      `${base}/api/session-context`,
+      {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        // Redact credential-shaped strings before the prompt leaves the machine (a pasted key must never
+        // be transmitted, same discipline as capture).
+        body: JSON.stringify({ question: redactSecrets(prompt) }),
+        timeoutMs: HYDRATE_TIMEOUT_MS,
+      },
+      { retries: 1 },
+    )
+  } catch (e) {
+    process.stderr.write(`cortex: hydrate skipped — ${e?.message ?? String(e)}\n`)
+    bumpAttempt()
+    return 0 // fail-open: never hold the user's first message hostage to hydration
+  }
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    process.stderr.write(
+      `cortex: hydrate skipped — ${classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message}\n`,
+    )
+    bumpAttempt()
+    return 0
+  }
+
+  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
+  }
+  return 0
+}