@theronap/agnoclast-mcp 0.9.96

package/lib/capture.mjs

@@ -0,0 +1,470 @@
+import { readFileSync, accessSync, constants, openSync, mkdirSync } from 'fs'
+import { spawn, execFileSync } from 'child_process'
+import { homedir } from 'os'
+import { resolve, dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+import { createHash } from 'crypto'
+import { fetchCortex, classify, resolveBase, resolveTokenSource } from './diagnose.mjs'
+import { extractSession } from './edge_extract.mjs'
+import { extractTyped } from './extract_typed.mjs'
+import { redactSecrets } from './redact.mjs'
+
+// Fetch the node-type registry (global + this org's custom types) — the catalog the typed extractor
+// produces against. Best-effort: null on any failure (typed extraction is then skipped, never blocks capture).
+async function fetchRegistry(base, token) {
+  try {
+    const res = await fetchCortex(`${base}/api/node-types`, { headers: { Authorization: `Bearer ${token}` } })
+    if (!res.ok) return null
+    const j = await res.json().catch(() => ({}))
+    return Array.isArray(j.types) ? j.types : null
+  } catch {
+    return null
+  }
+}
+
+// Project name from the hook cwd — cross-platform. Windows hooks send backslash paths,
+// and splitting on '/' alone turned the WHOLE path into one garbage project slug
+// ("c-users-webst-onedrive-…", three-machine dry-run finding 2026-06-09). A session run
+// from the home directory itself is 'general', not a project named after the user.
+export function projectFrom(cwd) {
+  if (!cwd) return 'general'
+  try {
+    if (resolve(String(cwd)) === homedir()) return 'general'
+  } catch { /* unresolvable path — fall through to basename */ }
+  const base = String(cwd).split(/[\\/]+/).filter((s) => s && !/^[A-Za-z]:$/.test(s)).pop()
+  return base ?? 'general'
+}
+
+// Claude Code Stop hook → POSTs a session digest to Agnoclast cloud, which
+// summarizes server-side and upserts ONE record per session. Node-native
+// SHR-01/T6 — parse a git remote URL into GitHub 'owner/name', or null.
+//
+// Handles the four remote forms git emits: scp-like ssh (git@github.com:o/n.git), ssh://, https://,
+// git://. The HOST CHECK IS LOAD-BEARING, not cosmetic: this string becomes a clearance key, and
+// 'owner/name' on gitlab.com or a self-hosted forge would collide in the identifier namespace with an
+// unrelated GitHub repo of the same name — granting its members read access to each other's sessions.
+export function githubFullName(url) {
+  if (!url) return null
+  const m = String(url).trim()
+    .match(/^(?:git\+)?(?:https?:\/\/|ssh:\/\/|git:\/\/)?(?:[^@/]+@)?github\.com[:/]+([^/]+)\/(.+?)(?:\.git)?\/?$/i)
+  if (!m) return null
+  const owner = m[1].toLowerCase()
+  const name = m[2].toLowerCase()
+  if (!owner || !name || name.includes('/')) return null
+  return `${owner}/${name}`
+}
+
+// SHR-01/T6 — the repo this session is working in, as 'owner/name', or null.
+//
+// D2, FAIL CLOSED: anything that is not unambiguously a GitHub worktree — no repo, no origin remote,
+// a non-GitHub host, git not installed — returns null, and the session is then stamped with NO
+// identifier and stays private. There is deliberately no fallback: a brain-level or hostname-level
+// identifier would be held by every member of the org, so overlap would ALWAYS succeed. That is an
+// accidental org-wide grant, i.e. the default-tier flip that was explicitly declined.
+//
+// `git config --get` is local and does no network I/O. Bounded and swallowed regardless: capture must
+// never break a session, and a missing identifier is a private session, not a broken one.
+export function repoFullNameFrom(cwd) {
+  if (!cwd) return null
+  try {
+    const url = execFileSync('git', ['-C', String(cwd), 'config', '--get', 'remote.origin.url'], {
+      encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return githubFullName(url)
+  } catch {
+    return null
+  }
+}
+
+// ── SHR-01/T9 — stamp the repos the session WORKED IN, not the one it was launched from ─────────
+//
+// WHY THIS EXISTS. `repoFullNameFrom(cwd)` above reads the session's LAUNCH directory. Measured
+// 2026-08-03, four days after the stamp shipped: 3,598 → 3,663 claude-code records, and **still zero
+// carried an identifier**. Not because the code was broken — because Claude Code sessions launch from
+// wherever the terminal happened to be. Theron's launch from `~/Documents/brain` (a git repo with no
+// remote), while every bit of the work happened in `~/dev/cortex-worktrees/*` on theronap/cortex.
+// One session that day touched 319+ paths under those worktrees and was stamped with nothing.
+//
+// So the launch directory is the wrong question. What the clearance rule (ADR-0019) actually asks is
+// whether two people *participated in the same work context* — and the transcript already records
+// that directly, as the files the session read and wrote.
+//
+// ⚠ THE THRESHOLD IS A SECURITY KNOB, NOT A TUNING PARAMETER. Every repo stamped here becomes a key
+// that lets that repo's other workers read this session's SCOPED records. Too low and glancing at one
+// file in repo X hands X's members a session that was really about Y; too high and genuine work goes
+// unstamped, which is the bug above. 3 sits in a wide empty gap — real work in a repo touches dozens
+// to hundreds of files, a drive-by check touches one or two — so the rule rarely makes a close call.
+//
+// Chosen deliberately conservative because the direction matters: LOWERING this later takes effect
+// immediately and safely, while RAISING it does NOT revoke stamps already written to
+// records.event_identifiers. Start tight, loosen once there is real collaborator data.
+export const MIN_FILES_FOR_STAMP = 3
+
+// Bounds the clearance surface a single session can claim, and the work done to compute it.
+export const MAX_STAMPED_REPOS = 5
+const MAX_DIRS_PROBED = 25
+
+// Absolute paths this session touched: file_path/path/notebook_path on any tool call, plus absolute
+// paths appearing in Bash commands. Best-effort and total — a malformed transcript yields [], never
+// throws, because capture must never break a session.
+export function touchedPaths(transcript) {
+  const out = []
+  if (!transcript) return out
+  for (const line of String(transcript).split('\n')) {
+    if (!line) continue
+    let d
+    try { d = JSON.parse(line) } catch { continue }
+    const content = d?.message?.content
+    if (!Array.isArray(content)) continue
+    for (const b of content) {
+      if (b?.type !== 'tool_use') continue
+      const inp = b.input ?? {}
+      for (const k of ['file_path', 'path', 'notebook_path']) {
+        if (typeof inp[k] === 'string' && inp[k].startsWith('/')) out.push(inp[k])
+      }
+      if (typeof inp.command === 'string') {
+        // Non-repo matches (/tmp, /usr, …) simply resolve to no repo and cost one cached probe.
+        for (const m of inp.command.match(/\/(?:Users|home|opt|srv|var)\/[^\s"'`;|&)<>]+/g) ?? []) out.push(m)
+      }
+    }
+  }
+  return out
+}
+
+// The repos this session actually worked in. Always a SUPERSET of the launch-cwd behaviour: the
+// launch repo is included unconditionally when it resolves, so nothing that stamps correctly today
+// stops stamping. Everything else must clear MIN_FILES_FOR_STAMP.
+export function repoFullNamesFrom(transcript, cwd) {
+  const launch = repoFullNameFrom(cwd)
+  const filesByRepo = new Map()   // repo -> Set(distinct file paths)
+  const touchesByDir = new Map()  // dir  -> touch count
+
+  for (const p of touchedPaths(transcript)) {
+    const dir = dirname(p)
+    touchesByDir.set(dir, (touchesByDir.get(dir) ?? 0) + 1)
+  }
+
+  // Probe the most-touched directories first, so a bounded budget still covers the real work.
+  const dirs = [...touchesByDir.entries()].sort((a, b) => b[1] - a[1]).slice(0, MAX_DIRS_PROBED)
+  const repoOfDir = new Map()
+  for (const [dir] of dirs) {
+    if (!repoOfDir.has(dir)) repoOfDir.set(dir, repoFullNameFrom(dir))
+  }
+
+  for (const p of touchedPaths(transcript)) {
+    const repo = repoOfDir.get(dirname(p))
+    if (!repo) continue
+    if (!filesByRepo.has(repo)) filesByRepo.set(repo, new Set())
+    filesByRepo.get(repo).add(p)
+  }
+
+  const earned = [...filesByRepo.entries()]
+    .filter(([repo, files]) => files.size >= MIN_FILES_FOR_STAMP || repo === launch)
+    .sort((a, b) => b[1].size - a[1].size)
+    .map(([repo]) => repo)
+
+  const all = launch ? [launch, ...earned.filter((r) => r !== launch)] : earned
+  return all.slice(0, MAX_STAMPED_REPOS)
+}
+
+// (no bun, no repo clone). Always exits 0 — capture must never break a session.
+
+function readStdin() {
+  try { return readFileSync(0, 'utf8') } catch { return '' }
+}
+
+// Claude transcripts are JSONL; pull human-readable text from the tail so the
+// server has real content to summarize (not raw tool JSON). ALSO scan the FULL
+// file for lifecycle-verb lines (§4b status recall — a "we're pausing X" said at
+// minute 5 of a 2-hour session must reach the server's status prefilter even
+// though only the tail ships) and append the flagged spans.
+const LIFECYCLE_RE = /\b(paus\w*|resum\w*|shipp?\w*|kill\w*|cancel\w*|on hold|sunset\w*)\b/i
+
+// Whether the Stop hook's transcript_path actually resolves to a READABLE file.
+//
+// This distinguishes "no transcript was ever written" from "transcript exists but yielded no prose" —
+// transcriptTail() flattens both into the same empty string, which is exactly why the empty-session
+// guard below could never see the first case.
+export function transcriptReadable(path) {
+  if (!path) return false
+  try { accessSync(path, constants.R_OK); return true } catch { return false }
+}
+
+function transcriptTail(path) {
+  let raw = ''
+  try { raw = readFileSync(path, 'utf8') } catch { return '' }
+  const jsonLines = raw.split('\n').filter(Boolean)
+  const textOf = (line) => {
+    try {
+      const obj = JSON.parse(line)
+      const content = obj?.message?.content ?? obj?.content
+      if (typeof content === 'string') return [content]
+      if (Array.isArray(content)) return content.filter((c) => c?.type === 'text' && c.text).map((c) => c.text)
+    } catch { /* skip non-JSON */ }
+    return []
+  }
+
+  const texts = jsonLines.slice(-60).flatMap(textOf)
+  const tail = texts.join('\n').slice(-6000)
+
+  // Full-session status-candidate spans (last 12 matching lines, capped).
+  const flagged = []
+  for (const line of jsonLines) {
+    for (const t of textOf(line)) {
+      for (const tl of t.split('\n')) {
+        if (LIFECYCLE_RE.test(tl)) flagged.push(tl.trim().slice(0, 200))
+      }
+    }
+  }
+  const spans = flagged.slice(-12).join('\n').slice(0, 1200)
+  return spans && !tail.includes(spans)
+    ? `${tail}\n\n[status-candidate lines from the full session]\n${spans}`
+    : tail
+}
+
+// Stop-hook entry point. The Stop hook fires after EVERY assistant turn, and Claude Code BLOCKS the
+// input box until this returns — so the heavy work (a synchronous `claude -p` edge summary, up to
+// tens of seconds, and worse when it hangs under concurrent sessions) must NEVER run in-band here.
+// Instead we read the (small) stdin payload, hand it to a DETACHED background worker, and return in
+// ~milliseconds. The worker does the extraction + ingest out of band; the user's next prompt is never
+// held. Set CORTEX_CAPTURE_SYNC=1 to force the old in-band behavior (tests / debugging).
+export async function runCapture() {
+  // Recursion guard: edge extraction shells out to `claude --print` with CORTEX_SUMMARIZING=1. That
+  // headless session fires its own Stop hook → this same capture command. Without this guard it would
+  // recurse (and re-ingest the summarizer's prompt as a phantom session). Bail immediately.
+  if (process.env.CORTEX_SUMMARIZING) { process.stderr.write('cortex: summarizer subprocess, skipping\n'); return }
+
+  const stdinRaw = readStdin()
+
+  // Detach the slow work unless we ARE the detached worker (or a caller forced sync). A spawn failure
+  // falls through to the in-band path so a session is never dropped just because fork() failed.
+  if (!process.env.CORTEX_CAPTURE_DETACHED && !process.env.CORTEX_CAPTURE_SYNC) {
+    if (spawnDetachedWorker(stdinRaw)) return
+  }
+  await captureWork(stdinRaw)
+}
+
+// Where a DETACHED worker's stdout/stderr go. Returns a writable fd, or 'ignore' if the log cannot be
+// opened — a capture must never fail because a log file could not be created.
+//
+// WHY THIS EXISTS. The worker previously ran with `stdio: ['pipe', 'ignore', 'ignore']`, so every
+// diagnostic capture prints — `no CORTEX_TOKEN`, `transcript_path unreadable`, `no-op session,
+// skipping`, `ingest failed — <reason>` — was written to a discarded stream. In production that is
+// EVERY capture: the sync path only runs under CORTEX_CAPTURE_SYNC, which nothing sets. So the
+// messages carefully added at each failure branch have never once been readable by anyone.
+//
+// Measured 2026-08-19: session-record writes fell from 107/day (08-10) to 1/day (08-13) and stayed
+// at 0-3/day for six days with no error surfacing anywhere. The failure was found only by forcing
+// CORTEX_CAPTURE_SYNC=1 by hand and watching stderr — which is not a thing anyone will think to do
+// about a subsystem that reports success. Append-only, one line per capture; the file is the only
+// place a silent worker can leave a trace.
+function captureLogFd() {
+  try {
+    const dir = join(homedir(), '.cortex')
+    mkdirSync(dir, { recursive: true })
+    return openSync(join(dir, 'capture.log'), 'a')
+  } catch {
+    return 'ignore'
+  }
+}
+
+// Re-invoke this same CLI as `capture` in a fully detached child (own session, output to capture.log) and
+// feed it the hook payload on its stdin. Returns true if the child was launched (parent may return
+// immediately), false if spawning failed (caller then does the work in-band). The child sees
+// CORTEX_CAPTURE_DETACHED=1 so it runs captureWork() directly instead of forking again.
+function spawnDetachedWorker(stdinRaw) {
+  try {
+    const bin = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'cortex-mcp.mjs')
+    const child = spawn(process.execPath, [bin, 'capture'], {
+      env: { ...process.env, CORTEX_CAPTURE_DETACHED: '1' },
+      detached: true,
+      stdio: ['pipe', captureLogFd(), captureLogFd()],
+    })
+    child.on('error', () => {}) // never let an async spawn error crash the hook
+    child.stdin.on('error', () => {})
+    child.stdin.end(stdinRaw)
+    child.unref()
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function captureWork(stdinRaw) {
+  // Env first (explicit override / legacy inlined hooks), else the token wired into this machine's
+  // MCP config — so hook commands carry no secret (token-hygiene, 2026-07-02).
+  const token = resolveTokenSource().token
+  if (!token) { process.stderr.write('cortex: no CORTEX_TOKEN in env or wired config, skipping\n'); return }
+  const base = resolveBase(process.env.CORTEX_URL)
+
+  let hook = {}
+  try { hook = JSON.parse(stdinRaw) } catch { /* no/invalid stdin */ }
+  const repo = projectFrom(hook.cwd)
+  // Redact credential-shaped strings BEFORE anything leaves the machine — this `transcript`
+  // feeds local edge/typed extraction AND the fallback POST to the org. A secret in a
+  // transcript (pasted key, a tool that read a config file, a token inlined in a hook cmd)
+  // must never be transmitted or stored. See redact.mjs.
+  const transcript = hook.transcript_path ? redactSecrets(transcriptTail(hook.transcript_path)) : ''
+
+  // A transcript_path that was SUPPLIED but is unreadable means the session ran with transcript writes
+  // disabled — `claude --print --no-session-persistence`, or the SDK's `persistSession:false`. Verified
+  // A/B 2026-08-18: with the flag, Claude Code writes no JSONL at all; without it, one appears.
+  //
+  // The guard below cannot catch that case, and never could: `session_id` is ALWAYS present in a Stop
+  // payload, so `!transcript && !hook.session_id` can only ever fire on the session_id half. Capture
+  // therefore sailed straight on and shipped `{...common, transcript: ''}` — a contentless record that
+  // ALSO lost its repo stamp (repoFullNamesFrom throws on the missing file and is swallowed), leaving it
+  // permanently private. That is worse than capturing nothing: it reports `cortex: captured`, and it
+  // inflates the very record count that capture health is judged by (there is no freshness monitor).
+  //
+  // Safe to skip rather than degrade, because capture is not one-shot: the Stop hook fires after EVERY
+  // assistant turn and the server upserts ONE record per session_id. A transcript that is merely
+  // unreadable for a moment is picked up by the next turn, so a transient miss self-heals; only a
+  // genuinely persistence-disabled session is dropped, and that session has no content to capture.
+  if (hook.transcript_path && !transcriptReadable(hook.transcript_path)) {
+    process.stderr.write('cortex: transcript_path unreadable (session persistence disabled?), skipping\n')
+    return
+  }
+
+  if (!transcript && !hook.session_id) { process.stderr.write('cortex: empty session, skipping\n'); return }
+
+  // T11: digest node refs surfaced to this session (stashed by the MCP server's my_context, keyed by
+  // cwd). Forwarded as hydratedFrom so the materializer excludes this session from the digests it
+  // consumed (feedback-loop guard). Best-effort + inert when absent (digest flag off / no my_context).
+  let hydratedFrom = []
+  try {
+    const key = createHash('sha1').update(hook.cwd || process.cwd()).digest('hex').slice(0, 16)
+    const parsed = JSON.parse(readFileSync(resolve(homedir(), '.cortex', 'brain-refs', `${key}.json`), 'utf8'))
+    if (Array.isArray(parsed.refs) && Date.now() - (parsed.ts ?? 0) < 12 * 3600 * 1000) hydratedFrom = parsed.refs
+  } catch { /* none — guard stays a no-op */ }
+
+  // Extract LOCALLY on the subscription (claude -p): summary + people + non-person entities. The
+  // cloud then receives only the derived digest, never the raw transcript or the metered API
+  // summarizer (which has been the silent point of failure). Fall back to shipping the transcript
+  // tail only if local extraction is unavailable (e.g. `claude` not on PATH) so we never drop a
+  // session. The server re-validates people/entities — the edge is not trusted.
+  // SHR-01/T6: the repo identifier is what lets a PEER read this session (see 0096). Omitted entirely
+  // when the cwd is not a GitHub worktree — the record still lands, it just stays private (D2).
+  const repoFullName = repoFullNameFrom(hook.cwd)
+
+  // SHR-01/T9: ...and the repos the session actually WORKED IN, which is usually not the same thing —
+  // the launch cwd stamped 0 of 3,663 sessions. Reads the RAW transcript, not the redacted tail above:
+  // the tail is truncated to ~6k chars and would miss most of the session's file paths. Nothing from
+  // this raw read is transmitted — only the derived 'owner/name' strings leave the machine.
+  let repoFullNames = repoFullName ? [repoFullName] : []
+  try {
+    if (hook.transcript_path) {
+      repoFullNames = repoFullNamesFrom(readFileSync(hook.transcript_path, 'utf8'), hook.cwd)
+    }
+  } catch { /* best-effort — a session with no derivable repo is private, not broken */ }
+
+  const common = {
+    source: 'claude-code',
+    project: repo,
+    sessionId: hook.session_id,
+    title: `Worked in ${repo}`,
+    payload: { session_id: hook.session_id, cwd: hook.cwd },
+    captureSource: 'hook', // T8: fallback writer — never clobbers a cortex-log ('skill') record
+    ...(repoFullName ? { repoFullName } : {}),      // back-compat: older servers read only this
+    ...(repoFullNames.length ? { repoFullNames } : {}),
+    ...(hydratedFrom.length ? { hydratedFrom } : {}),
+  }
+  const extracted = transcript ? extractSession(transcript) : null
+  if (extracted && /^NOOP\b/i.test(extracted.summary)) { process.stderr.write('cortex: no-op session, skipping\n'); return }
+  const ingestBody = extracted
+    ? { ...common, summary: extracted.summary, people: extracted.people, entities: extracted.namedEntities }
+    : { ...common, transcript }
+
+  // Parallel typed extraction (OPT-IN via CORTEX_TYPED): registry-driven typed notes, sent ALONGSIDE the
+  // people/entities above. The server's typedNotes receiver persists them additively. Off by default so it
+  // never adds a 2nd `claude` call / latency until verified; flip to default once typed ≥ the blob path.
+  if (process.env.CORTEX_TYPED && transcript) {
+    try {
+      const registry = await fetchRegistry(base, token)
+      if (registry?.length) {
+        const typed = extractTyped(transcript, registry)
+        if (typed?.notes?.length) ingestBody.typedNotes = typed.notes
+      }
+    } catch { /* best-effort — never block capture */ }
+  }
+
+  // Defined before the fetch so the throw path below can stamp its line the same way. Every line in
+  // capture.log carries an ISO timestamp and the session id, so a silent day can be reconstructed
+  // afterwards and matched against `records` / `page_revisions.session_key`.
+  const stamp = new Date().toISOString()
+  const sid = hook.session_id ?? '(no session_id)'
+
+  let res
+  try {
+    // Best-effort background ingest: bound it tight and retry once so a hanging/504-ing server
+    // makes a DETACHED worker self-terminate in ~20s instead of lingering on 3 unbounded attempts.
+    res = await fetchCortex(`${base}/api/ingest`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(ingestBody),
+      timeoutMs: 10_000,
+    }, { retries: 1 })
+  } catch (e) {
+    // Never break a session — just report and move on. This is where a 10s timeout against a slow
+    // /api/ingest lands, and with the old discarded stdio it was completely invisible: the session
+    // simply never appeared and nothing anywhere said why. The endpoint is measurably flaky — a
+    // SessionStart context fetch timed out at 09:54 and again at 11:59 on 2026-08-19 while direct
+    // curls answered in ~150ms, so intermittent timeouts here are a live hypothesis for the
+    // 2026-08-13 collapse, not a theoretical one.
+    process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — ${e.message}\n`)
+    return
+  }
+
+  // A 2xx FROM /api/ingest DOES NOT MEAN A RECORD EXISTS. The route answers `ok: true` on at least
+  // six outcomes and only one of them writes a session record:
+  //
+  //   { ok: true, id, inserted, title }            -> RECORDED (the only success)
+  //   { ok: true, staged: true, id, reason }       -> held in staged_records, NOT recorded
+  //   { ok: true, skipped: '<why>' }               -> no-op session / past the ingest horizon
+  //   { ok: false, skipped: '<why>' }              -> connector excluded from this brain
+  //   { ok: true, discarded: true }                -> tombstoned by private intake
+  //   { ok: true, queued: true }                   -> accepted for later work
+  //   { ok: true, via: 'private_intake', intakeItemId } -> an intake unit, not a session record
+  //
+  // The old line read `j.inserted ? 'captured' : 'updated'`, so EVERY one of the six non-writing
+  // outcomes printed "updated" — the word for a successful upsert. Worse, `.json().catch(() => ({}))`
+  // means an unparseable body also yields `{}` and therefore also printed "updated". Verified against
+  // prod 2026-08-19: a capture printed `cortex: updated "general" → general` for a session that has no
+  // row in `records` and none in `staged_records` either.
+  //
+  // NOTE `staged` CARRIES AN `id`, so testing for an id alone is not enough — that id is the
+  // staged_records row, not a record. This is the same false-success defect already fixed once in
+  // log_session ("`inserted` is merely falsy when nothing is recorded — an agent reported a session as
+  // saved when it was not"); the fix was applied there and not here. The server route already knew:
+  // its own comment at the no_route_for_source branch says "`{ok: true}` reads as success to
+  // everything that is not looking closely" and notes 84 rows accumulating behind that wording.
+  if (res.ok || res.status === 200) {
+    const raw = await res.text()
+    let j
+    try { j = JSON.parse(raw) } catch { j = null }
+    if (j && j.id && !j.staged) {
+      process.stderr.write(`cortex: ${stamp} ${sid} ${j.inserted ? 'captured' : 'updated'} "${j.title ?? repo}" → ${repo}\n`)
+    } else if (j && j.staged) {
+      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — staged (${j.reason ?? 'no reason given'}); staged session logs are not drainable by /api/staged/promote\n`)
+    } else if (j && j.skipped) {
+      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — server skipped: ${j.skipped}\n`)
+    } else if (j && j.discarded) {
+      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — discarded by private intake\n`)
+    } else if (j && j.queued) {
+      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — queued for later processing\n`)
+    } else if (j && j.intakeItemId) {
+      process.stderr.write(`cortex: ${stamp} ${sid} not a session record — filed as private intake unit ${j.intakeItemId}\n`)
+    } else {
+      // Unparseable or unrecognised 2xx. Deliberately NOT reported as success: an unknown shape is
+      // exactly the case the old code laundered into "updated".
+      process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — unrecognised 2xx response: ${raw.slice(0, 200)}\n`)
+    }
+  } else {
+    const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+    process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — ingest failed: ${d.message}\n`)
+  }
+
+  // The post-capture edge-materialize batch (CORTEX_MATERIALIZE → runMaterialize) was EXCISED
+  // 2026-07-02 with the legacy materializer: its server pipeline deleted live-authored pages whose
+  // record-hashes drifted. Pages come from live authoring (the `author` tool + /log sweep) now.
+}

package/lib/code_graph_cli.mjs

@@ -0,0 +1,59 @@
+import { spawnSync } from 'child_process'
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+// Thin local wrapper around the `graphify` CLI's read-only query subcommands. Deliberately NOT a
+// fetchCortex client like grep/read_page: this is LOCAL-MACHINE data (a tree-sitter AST graph of
+// whatever repo the session's cwd happens to be in), not org-shared Agnoclast content, and it never
+// becomes the wiki graph — see cortex-wiki-primary-spec (structural/extracted data is evidence,
+// never auto-promoted into authored pages). No LLM, no network call; graphify already built the
+// graph on disk, this just queries it.
+
+function graphPath(cwd) {
+  return join(cwd, 'graphify-out', 'graph.json')
+}
+
+function hasGraphifyBinary() {
+  const r = spawnSync('graphify', ['--version'], { encoding: 'utf8', timeout: 10_000 })
+  return !r.error && r.status === 0
+}
+
+// Pure-ish: build the argv for a given action, or return an error string if params are missing.
+export function buildArgs({ action, question, from, to, node }) {
+  if (action === 'path') {
+    if (!from || !to) return { error: 'action:"path" requires both "from" and "to".' }
+    return { args: ['path', from, to] }
+  }
+  if (action === 'explain') {
+    if (!node) return { error: 'action:"explain" requires "node".' }
+    return { args: ['explain', node] }
+  }
+  if (!question) return { error: 'action:"query" requires "question".' }
+  return { args: ['query', question] }
+}
+
+// Effectful: run one of graphify's query/path/explain subcommands against the graph already built
+// for `cwd`. Returns { ok, text } — never throws, always something readable to hand back to the model.
+export function runCodeGraphQuery({ action, question, from, to, node }, cwd = process.cwd()) {
+  if (!existsSync(graphPath(cwd))) {
+    return {
+      ok: false,
+      text: `No code graph found at ${graphPath(cwd)}. Run the graphify skill (\`/graphify .\`) in this repo first to build one.`,
+    }
+  }
+  if (!hasGraphifyBinary()) {
+    return {
+      ok: false,
+      text: 'graphify CLI not found on PATH. Install it with `uv tool install graphifyy` (or `pipx install graphifyy`), then run the graphify skill to build a graph.',
+    }
+  }
+  const built = buildArgs({ action, question, from, to, node })
+  if (built.error) return { ok: false, text: built.error }
+
+  const r = spawnSync('graphify', built.args, { cwd, encoding: 'utf8', timeout: 60_000, maxBuffer: 4 * 1024 * 1024 })
+  if (r.error) return { ok: false, text: `graphify failed to run: ${r.error.message}` }
+  const out = (r.stdout || '').trim()
+  const err = (r.stderr || '').trim()
+  if (r.status !== 0) return { ok: false, text: err || out || `graphify exited with status ${r.status}` }
+  return { ok: true, text: out || '(no results)' }
+}

package/lib/context_log.mjs

@@ -0,0 +1,92 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { fetchCortex, classify, resolveBase, resolveTokenSource } from './diagnose.mjs'
+
+// The private third copy of this lived here until 2026-08-19. doctor.mjs:14 warned that a third
+// copy is how a machine ends up connected to one command and 'no token found' to another; it also
+// missed Codex entirely, so a Codex-only seat WAS in exactly that state. Shared resolver now.
+const resolveToken = () => resolveTokenSource().token
+
+function ensureDir(path) {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true })
+}
+
+function stamp(now = new Date()) {
+  const pad = (n) => String(n).padStart(2, '0')
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`
+}
+
+function snapshotDir() {
+  return join(homedir(), '.cortex', 'context-snapshots')
+}
+
+// Keep only the most recent N timestamped snapshots; latest.md + index.jsonl are
+// always preserved. Without this the per-session-start archives grow unbounded
+// (2k+ files / ~40MB observed in the field). Best-effort: a prune failure must
+// never break session start.
+const SNAPSHOT_RETENTION = 50
+
+function pruneSnapshots(dir, keep = SNAPSHOT_RETENTION) {
+  try {
+    const stamped = readdirSync(dir)
+      .filter((f) => /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}\.md$/.test(f))
+      .sort() // stamp() is zero-padded, so lexicographic order === chronological
+    for (const f of stamped.slice(0, Math.max(0, stamped.length - keep))) {
+      try { unlinkSync(join(dir, f)) } catch { /* ignore individual failures */ }
+    }
+  } catch { /* ignore — never break session start */ }
+}
+
+export async function runSnapshotContext() {
+  const out = (m) => process.stdout.write(m + '\n')
+  const token = resolveToken()
+  if (!token) {
+    out('Agnoclast: context snapshot skipped — no token found.')
+    return 0
+  }
+
+  const base = resolveBase(process.env.CORTEX_URL)
+  let res
+  try {
+    res = await fetchCortex(`${base}/api/mcp-context`, { headers: { Authorization: `Bearer ${token}` } })
+  } catch (e) {
+    out(`Agnoclast: context snapshot failed — ${e?.message ?? String(e)}`)
+    return 0
+  }
+
+  if (!res.ok) {
+    const body = await res.text()
+    out(`Agnoclast: context snapshot failed — ${classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message}`)
+    return 0
+  }
+
+  const payload = await res.json().catch(() => ({}))
+  const context = typeof payload?.context === 'string' ? payload.context : ''
+  const dir = snapshotDir()
+  ensureDir(dir)
+
+  const capturedAt = new Date().toISOString()
+  const file = join(dir, `${stamp()}.md`)
+  const header = [
+    '# Agnoclast startup context snapshot',
+    `- Captured: ${capturedAt}`,
+    `- Source: ${base}/api/mcp-context`,
+    '',
+  ].join('\n')
+  const text = `${header}${context}\n`
+
+  writeFileSync(file, text)
+  writeFileSync(join(dir, 'latest.md'), text)
+  writeFileSync(join(dir, 'index.jsonl'), JSON.stringify({
+    captured_at: capturedAt,
+    file,
+    base,
+    chars: context.length,
+  }) + '\n', { flag: 'a' })
+
+  pruneSnapshots(dir)
+
+  out(`Agnoclast: logged startup context → ${file}`)
+  return 0
+}