@theronap/agnoclast-mcp 0.9.96

package/lib/edge_extract.mjs

@@ -0,0 +1,156 @@
+import { spawnSync } from 'child_process'
+import { openSync, closeSync, writeSync, unlinkSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// Single-flight lock so at most ONE edge summarizer (`claude -p`) runs on this machine at a time.
+// Without it, N concurrent Claude sessions all fire their Stop hook at once → N simultaneous headless
+// `claude --print` calls that contend on the same subscription-OAuth refresh and can deadlock (the
+// "prompts hang forever" incident, 2026-07-08). If the lock is already held by a live, recent holder,
+// the caller skips extraction and ships the transcript tail instead (the server summarizes async) —
+// no session is dropped, just summarized server-side that turn. A stale lock (older than the summary
+// timeout + grace, or whose PID is dead) is reclaimed.
+const LOCK_PATH = join(homedir(), '.cortex', 'summarize.lock')
+
+function summaryTimeoutMs() {
+  const n = Number(process.env.CORTEX_SUMMARY_TIMEOUT_MS)
+  return Number.isFinite(n) && n > 0 ? n : 45_000
+}
+
+// Try to acquire the lock. Returns true if acquired (caller must call releaseSummaryLock in a finally),
+// false if another live holder has it. O_CREAT|O_EXCL is the atomic "create only if absent" primitive.
+function acquireSummaryLock(_retried = false) {
+  try {
+    const fd = openSync(LOCK_PATH, 'wx') // wx = O_CREAT|O_EXCL|O_WRONLY — fails if it exists
+    try { writeSync(fd, String(process.pid)) } catch { /* PID write is best-effort */ }
+    closeSync(fd)
+    return true
+  } catch (e) {
+    if (e && e.code === 'EEXIST') {
+      // Someone holds it — reclaim only if it's stale (older than timeout + 15s grace, or PID dead).
+      if (_retried) return false // one reclaim attempt only; a live race means "ship the tail"
+      try {
+        const age = Date.now() - statSync(LOCK_PATH).mtimeMs
+        const holderDead = !pidAlive(readFileSync(LOCK_PATH, 'utf8').trim())
+        if (age > summaryTimeoutMs() + 15_000 || holderDead) {
+          try { unlinkSync(LOCK_PATH) } catch { /* raced with another reclaimer */ }
+          return acquireSummaryLock(true)
+        }
+      } catch { /* unreadable lock — treat as held; ship the tail this turn */ }
+      return false
+    }
+    // Any other error (e.g. ~/.cortex missing): don't block extraction, just run without the lock.
+    return true
+  }
+}
+
+function pidAlive(pid) {
+  const n = Number(pid)
+  if (!Number.isInteger(n) || n <= 0) return false
+  try { process.kill(n, 0); return true } catch (e) { return e && e.code === 'EPERM' }
+}
+
+function releaseSummaryLock() {
+  try { unlinkSync(LOCK_PATH) } catch { /* already gone */ }
+}
+
+// Edge session extractor (slice 2c) — ONE `claude --print` call on the user's SUBSCRIPTION that
+// produces summary + people + non-person entities LOCALLY, so the cloud receives only the derived
+// digest. The server-side summarizer (Anthropic API) silently failed in prod ~2026-06-16 and took
+// both session people AND the entity catalogue down; extracting here keeps the engine on `claude -p`
+// (the standing preference) and removes that dependency. Node-native (no bun) to match capture.mjs.
+//
+// edgeSafeEnv() strips EVERY ANTHROPIC_* var (but KEEPS CLAUDE_CODE_OAUTH_TOKEN — the headless
+// runs on the file-based subscription login and a stray ANTHROPIC_BASE_URL (e.g. a keytunnel proxy)
+// can't reroute "free, local" inference through a billed proxy or ship raw text off-machine. The
+// spawn also sets CORTEX_SUMMARIZING=1 so the headless session's own Stop hook no-ops (runCapture
+// guards on it) instead of recursing.
+//
+// CONTRACT: people[] / namedEntities[] shapes MUST stay compatible with the server validators
+// web/lib/engine/extract_people.ts (parsePeople) + extract_entities.ts (parseEntities). The prompt
+// fragments are copied from there; the SERVER validator is the enforced source of truth — the edge
+// is never trusted. Returns null on any failure → caller falls back to shipping the transcript tail.
+
+export function edgeSafeEnv(base = process.env, extra = {}) {
+  const env = {}
+  for (const [k, v] of Object.entries(base)) {
+    if (v === undefined) continue
+    // Strip billed/proxy routing only (ANTHROPIC_API_KEY metered, ANTHROPIC_BASE_URL keytunnel,
+    // ANTHROPIC_AUTH_TOKEN/CUSTOM_HEADERS proxy) so edge inference runs on the SUBSCRIPTION, never a
+    // metered/proxy path. KEEP CLAUDE_CODE_OAUTH_TOKEN — it IS the headless subscription credential
+    // (from `claude setup-token`); stripping it leaves `claude --print` with no usable auth → 401.
+    // (The earlier "subscription is file-based" assumption was wrong on macOS — headless needs this token.)
+    if (k.startsWith('ANTHROPIC_')) continue
+    env[k] = v
+  }
+  return { ...env, ...extra }
+}
+
+const PEOPLE_FRAGMENT =
+  '"people" (array of important, NAMED individuals mentioned — each an object with ' +
+  '"name" (the person\'s real full name as written — NEVER an email address, handle, or group alias), ' +
+  '"email" (only if explicitly stated, else null), ' +
+  '"company" (their org/employer if stated, else null), ' +
+  '"title" (their role if stated, else null), ' +
+  '"relationship" (one short phrase: how they relate to this work), ' +
+  '"importance" ("high" for people central to the work, "low" for incidental). ' +
+  'Only real named humans; omit anonymous or incidental mentions. Empty array is fine.)'
+
+const ENTITY_FRAGMENT =
+  '"namedEntities" (array of important NON-PERSON things this content is about — concrete, named ' +
+  'projects, processes, systems, products, documents, teams, tools, events, places, or topics. ' +
+  'Each an object with "name" (the specific name as written, NOT a generic word), ' +
+  '"kind" (one of: project|process|system|product|document|team|topic|tool|event|place), ' +
+  '"description" (one short phrase: what it is / how it relates to this work, else null), ' +
+  '"importance" ("high" if central to the work, "low" if incidental). ' +
+  'Do NOT include people or companies (those go in "people"). Omit vague/generic mentions. Empty array is fine.)'
+
+export function extractSession(transcript) {
+  const text = (transcript ?? '').trim()
+  if (!text || process.env.CORTEX_SUMMARIZE_DISABLED) return null
+  const prompt =
+    'You are processing a Claude Code work session for a knowledge base. Return ONLY minified JSON ' +
+    '(no prose, no markdown fences) with EXACTLY these three keys:\n' +
+    '"summary" (ONE concrete sentence under 20 words: what was worked on or decided. If the session ' +
+    'had no real work — greetings, no tasks — set summary to exactly "NOOP"),\n' +
+    PEOPLE_FRAGMENT + ',\n' +
+    ENTITY_FRAGMENT +
+    '\n\n--- SESSION ---\n' + text.slice(0, 12000) + '\n--- END ---'
+  // Single-flight: if another session already has a summarizer running, skip (caller ships the tail;
+  // server summarizes). Prevents the concurrent-`claude -p` stampede that deadlocks the OAuth refresh.
+  if (!acquireSummaryLock()) return null
+  try {
+    const r = spawnSync(
+      'claude',
+      ['--print', '--model', process.env.CORTEX_SUMMARY_MODEL ?? 'claude-haiku-4-5', prompt],
+      { env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }), encoding: 'utf8', timeout: summaryTimeoutMs(), maxBuffer: 4 * 1024 * 1024 },
+    )
+    if (r.status !== 0 || !r.stdout) return null
+    return parseEdgeJson(r.stdout.trim())
+  } catch {
+    return null
+  } finally {
+    releaseSummaryLock()
+  }
+}
+
+// Tolerant JSON extraction: the model may wrap output in prose / ```json fences, so grab the first
+// balanced-looking {...} span. Arrays pass through untouched — the SERVER validates them.
+export function parseEdgeJson(out) {
+  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))
+    const summary = typeof o.summary === 'string' ? o.summary.trim() : ''
+    if (!summary) return null
+    return {
+      summary: summary.slice(0, 200),
+      people: Array.isArray(o.people) ? o.people : [],
+      namedEntities: Array.isArray(o.namedEntities) ? o.namedEntities : [],
+    }
+  } catch {
+    return null
+  }
+}

package/lib/editors/_fsutil.mjs

@@ -0,0 +1,31 @@
+// Shared file helpers for editor adapters. These MIRROR setup.mjs's private helpers exactly so an
+// extracted wire() writes byte-identical output (same backup name, same JSON formatting).
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/** Parse a JSON config, tolerating absent/empty files; THROWS on malformed (caller decides). */
+export function readJson(path) {
+  if (!existsSync(path)) return {}
+  const raw = readFileSync(path, 'utf8').trim()
+  if (!raw) return {}
+  return JSON.parse(raw)
+}
+
+/** Copy path → path.cortex-bak before mutating. Returns the backup path, or null if nothing to back up. */
+export function backupFile(path) {
+  if (!existsSync(path)) return null
+  const bak = `${path}.cortex-bak`
+  copyFileSync(path, bak)
+  return bak
+}
+
+/** Ensure the parent directory of `path` exists. */
+export function ensureDir(path) {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
+/** Write an object as pretty JSON — the exact formatting setup.mjs uses (2-space indent). */
+export function writeJson(path, obj) {
+  writeFileSync(path, JSON.stringify(obj, null, 2))
+}

package/lib/editors/antigravity.mjs

@@ -0,0 +1,130 @@
+// Editor adapter: Antigravity. P0-b task 4 — deterministic artifact generators + wire().
+//
+// Antigravity has no in-editor hook; sync is a launchd agent (com.cortex.antigravity-sync) that
+// WatchPaths the trajectory store and runs a one-shot sync. wire() generates the two artifacts
+// (the sync.sh + the launchd plist) deterministically. It does NOT run `launchctl load` here
+// (an unverifiable system mutation) and it flags the PORTABILITY BLOCKER below.
+//
+// ⚠ BLOCKER (surfaced P0-b task 4): antigravity-sync.sh runs the sync from a LOCAL DEV CHECKOUT
+// ($HOME/dev/cortex/packages/cortex-agent via `bun run src/index.ts antigravity-sync`). A coworker
+// has no ~/dev/cortex, so Antigravity capture is bespoke to the author's machine and is NOT yet
+// installable for a real seat. Making it portable requires a published `antigravity-sync` entrypoint
+// (npx @theronap/cortex-mcp antigravity-sync, or a published cortex-agent) — a prerequisite this
+// adapter cannot satisfy alone. Until then wire() writes the artifacts + returns a blocking warning.
+import { homedir } from 'node:os'
+import { writeFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs'
+import { join } from 'node:path'
+
+const AG_STATE = ['Library', 'Application Support', 'Antigravity']
+const AG_WATCH = [...AG_STATE, 'User', 'globalStorage']
+
+/** The launchd plist, home-substituted. Deterministic — golden-testable byte-for-byte. */
+export function renderAntigravityPlist({ home = homedir() } = {}) {
+  const sh = join(home, '.cortex', 'antigravity-sync.sh')
+  const watch = join(home, ...AG_WATCH)
+  const logp = join(home, '.cortex', 'antigravity-sync.launchd.log')
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.cortex.antigravity-sync</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>${sh}</string>
+  </array>
+  <key>WatchPaths</key>
+  <array>
+    <string>${watch}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <false/>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>StandardOutPath</key>
+  <string>${logp}</string>
+  <key>StandardErrorPath</key>
+  <string>${logp}</string>
+</dict>
+</plist>
+`
+}
+
+/** The sync.sh. Self-resolves paths via $HOME at runtime, so it is a static template.
+ *  NOTE the AGENT_DIR line is the portability blocker documented above. */
+export function renderAntigravitySyncSh() {
+  return `#!/bin/bash
+# Agnoclast ⇄ Antigravity one-shot sync, triggered by launchd WatchPaths on the Antigravity
+# trajectory store. There is no resident daemon — launchd wakes this on change and it exits.
+# Token is resolved by 'cortex-mcp with-token' at runtime (never stored in plist/script, and
+# never parsed here -- see ADR-0033 D9 on frozen generated scripts).
+# ⚠ AGENT_DIR points at a local dev checkout — see antigravity.mjs BLOCKER note (not coworker-portable).
+set -o pipefail
+LOG="$HOME/.cortex/antigravity-sync.log"
+NPX="/usr/local/bin/npx"
+BUN="$HOME/.bun/bin/bun"
+AGENT_DIR="$HOME/dev/cortex/packages/cortex-agent"
+
+stamp() { date -u +%FT%TZ; }
+
+if [ ! -d "$AGENT_DIR" ]; then echo "$(stamp) agent dir missing: $AGENT_DIR" >> "$LOG"; exit 0; fi
+
+# The token is resolved by the package, not parsed here. This script is written once and never
+# rewritten by an upgrade, so an inlined config read would silently stop working the moment the
+# config shape changed -- and its own error handling would swallow that. with-token also keeps the
+# secret out of this shell entirely: it goes from the resolver straight into the child environment.
+# Exit 3 means "nothing wired", which is a skip rather than a failure.
+cd "$AGENT_DIR" || exit 0
+CORTEX_WATCH="$HOME/.cortex-agent" "$NPX" -y @theronap/cortex-mcp@stable with-token -- \
+  "$BUN" run src/index.ts antigravity-sync >> "$LOG" 2>&1
+CODE=$?
+if [ "$CODE" = "3" ]; then echo "$(stamp) no token wired, skipping" >> "$LOG"; exit 0; fi
+echo "$(stamp) exit=$CODE" >> "$LOG"
+exit 0
+`
+}
+
+/** @type {import('./index.mjs').EditorAdapter} */
+export default {
+  id: 'antigravity',
+  displayName: 'Antigravity',
+
+  detect({ home = homedir(), exists = existsSync } = {}) {
+    return exists(join(home, ...AG_STATE))
+  },
+
+  capabilities: {
+    promptTimeInjection: false,  // no in-editor injection possible today
+    sessionStart: false,
+    captureHook: true,           // post-sync, via antigravity-sync.sh
+    skillDir: null,
+    docTrigger: 'watch',
+  },
+
+  // Writes the two artifacts deterministically. Does NOT launchctl-load (unverifiable side effect) and
+  // returns a BLOCKING warning about the dev-checkout dependency — honest about not-yet-installable.
+  async wire({ home = homedir(), log = () => {} } = {}) {
+    const wrote = [], skipped = [], warnings = []
+    const cortexDir = join(home, '.cortex')
+    const shPath = join(cortexDir, 'antigravity-sync.sh')
+    const plistPath = join(home, 'Library', 'LaunchAgents', 'com.cortex.antigravity-sync.plist')
+
+    try { // non-fatal: an IO error must not abort sibling editors
+      mkdirSync(cortexDir, { recursive: true })
+      writeFileSync(shPath, renderAntigravitySyncSh())
+      try { chmodSync(shPath, 0o755) } catch { /* non-fatal on non-posix */ }
+      wrote.push(shPath)
+
+      mkdirSync(join(home, 'Library', 'LaunchAgents'), { recursive: true })
+      writeFileSync(plistPath, renderAntigravityPlist({ home }))
+      wrote.push(plistPath)
+      log(`  ✓ Antigravity artifacts → ${shPath}, ${plistPath}`)
+    } catch (e) {
+      warnings.push(`Antigravity artifact write skipped: ${e.message}`)
+    }
+
+    warnings.push('Antigravity NOT fully wired: (1) run `launchctl load ' + plistPath + '` to activate the watcher; (2) BLOCKER — the sync runs from a local dev checkout (~/dev/cortex/packages/cortex-agent), so it will not work on a machine without that checkout until a published antigravity-sync entrypoint exists.')
+    return { wrote, skipped, warnings }
+  },
+}

package/lib/editors/claude.mjs

@@ -0,0 +1,202 @@
+// Editor adapter: Claude Code. P0-b task 2 — wire() + the pure merge functions extracted from
+// setup.mjs. setup.mjs imports THESE SAME functions (and re-exports them), so the config bytes are
+// structurally identical, not merely "supposed to match".
+import { homedir } from 'node:os'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { readJson, backupFile, ensureDir, writeJson } from './_fsutil.mjs'
+import { markCommand, isManagedSubcommand } from '../managed.mjs'
+
+/** Merge the Agnoclast MCP server into a ~/.claude.json object. Pure + idempotent: sets only the
+ *  `cortex` entry (type:'stdio'), preserves every other server. `spec` = the package@dist-tag string. */
+export function mergeClaudeMcp(existing, spec, token) {
+  const cfg = existing && typeof existing === 'object' ? { ...existing } : {}
+  cfg.mcpServers = cfg.mcpServers && typeof cfg.mcpServers === 'object' ? { ...cfg.mcpServers } : {}
+  cfg.mcpServers.cortex = { type: 'stdio', command: 'npx', args: ['-y', spec], env: { CORTEX_TOKEN: token } }
+  return cfg
+}
+
+/** The Agnoclast tools every seat may run WITHOUT a permission prompt: the read surface, the live
+ *  authoring core, and trivially-reversible maintenance. The contract this enforces: authoring is
+ *  EXPECTED agent behavior — a page update must never stall on a yes/no dialog the user won't read
+ *  (the ask-permission failure mode is how pages go stale). Safe because every page edit is
+ *  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), 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 ALLOWED_TOOL_NAMES = [
+  // read surface
+  'grep', 'read_page', 'my_context', 'project_status', 'session_context', 'search_org',
+  'list_records', 'page_history', 'page_diff', 'timeline_pull', 'my_brains', 'my_sessions', 'writing_style',
+  'code_graph_query', 'my_retier_notices', 'list_page_grants', 'file_requests', 'page_merge_requests',
+  // live authoring core
+  'authoring_context', 'author', 'log_session',
+  // routine, reversible maintenance
+  'set_page_validity', 'snooze_red_link', 'attribute_thread',
+]
+
+/** The same allowlist, rendered for a given tool namespace. ONE source of names, so the cortex and
+ *  agnoclast lists cannot drift apart during the migration — C2 adds the new namespace's rules
+ *  before flipping the config key, and it derives them from here rather than a second copy. */
+export const allowedToolsFor = (namespace) => ALLOWED_TOOL_NAMES.map((t) => `mcp__${namespace}__${t}`)
+
+export const CORTEX_ALLOWED_TOOLS = allowedToolsFor('cortex')
+
+/** Merge Agnoclast'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), hydrate
+ *  (UserPromptSubmit). Also UNWIRES the retired PreCompact reminder from seats that still carry it.
+ *  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). */
+export function mergeClaudeSettings(existing, spec) {
+  const s = existing && typeof existing === 'object' ? existing : {}
+  s.hooks = s.hooks ?? {}
+
+  // Stop — capture.
+  s.hooks.Stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : []
+  const captureCmd = markCommand(`npx -y ${spec} capture`)
+  for (const grp of s.hooks.Stop) {
+    if (Array.isArray(grp.hooks)) grp.hooks = grp.hooks.filter((h) => !isManagedSubcommand(h.command, 'capture'))
+  }
+  let grp = s.hooks.Stop.find((g) => (g.matcher ?? '') === '')
+  if (!grp) { grp = { matcher: '', hooks: [] }; s.hooks.Stop.push(grp) }
+  grp.hooks = grp.hooks ?? []
+  grp.hooks.push({ type: 'command', command: captureCmd })
+
+  // SessionStart — status, then skills self-heal, then snapshot-context (order matters: matches setup).
+  s.hooks.SessionStart = Array.isArray(s.hooks.SessionStart) ? s.hooks.SessionStart : []
+  const statusCmd = markCommand(`npx -y ${spec} status`)
+  for (const sg of s.hooks.SessionStart) {
+    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !isManagedSubcommand(h.command, 'status'))
+  }
+  let sgrp = s.hooks.SessionStart.find((g) => (g.matcher ?? '') === '')
+  if (!sgrp) { sgrp = { matcher: '', hooks: [] }; s.hooks.SessionStart.push(sgrp) }
+  sgrp.hooks = sgrp.hooks ?? []
+  sgrp.hooks.push({ type: 'command', command: statusCmd })
+
+  const skillsCmd = markCommand(`npx -y ${spec} skills --repair --quiet`)
+  for (const sg of s.hooks.SessionStart) {
+    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !isManagedSubcommand(h.command, 'skills'))
+  }
+  sgrp.hooks.push({ type: 'command', command: skillsCmd })
+
+  const snapshotCmd = markCommand(`npx -y ${spec} snapshot-context`)
+  for (const sg of s.hooks.SessionStart) {
+    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !isManagedSubcommand(h.command, 'snapshot-context'))
+  }
+  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 = markCommand(`npx -y ${spec} hydrate`)
+  for (const hg of s.hooks.UserPromptSubmit) {
+    if (Array.isArray(hg.hooks)) hg.hooks = hg.hooks.filter((h) => !isManagedSubcommand(h.command, 'hydrate'))
+  }
+  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 — REMOVED, and this block is the migration that unwires existing seats.
+  //
+  // The "author now" reminder wrote to stdout on the assumption the harness surfaced it as context for
+  // the next turn. It does not: PreCompact accepts a blocking `decision` and nothing else — it has no
+  // additionalContext channel — so the reminder never reached a model. Measured 2026-08-10 across 7,232
+  // local transcripts: the reminder text appears 5 times, every one of them a tool_result from someone
+  // READING the file, assistant prose about it, or a compaction summary that absorbed such prose. Zero
+  // injections, against >=13 transcripts that demonstrably compacted. The control is what makes that
+  // conclusive rather than merely absent: SessionStart's hook output, on a channel that IS injected,
+  // appears in 912 transcripts of the same corpus.
+  //
+  // So: filter, never append. Every install/repair strips the stale entry from seats that already have
+  // it, which is why this runs unconditionally instead of shipping as a separate migration.
+  if (Array.isArray(s.hooks.PreCompact)) {
+    for (const pg of s.hooks.PreCompact) {
+      if (Array.isArray(pg.hooks)) pg.hooks = pg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? precompact/.test(h.command ?? ''))
+    }
+    // Drop groups we just emptied, then the key itself if no foreign hook remains — a bare
+    // `PreCompact: []` reads as "cortex wires this event" to the next person to open settings.json.
+    s.hooks.PreCompact = s.hooks.PreCompact.filter((pg) => (pg.hooks ?? []).length > 0)
+    if (s.hooks.PreCompact.length === 0) delete s.hooks.PreCompact
+  }
+
+  // Permissions — pre-authorize the read + authoring core so a page update never stalls on a
+  // permission prompt. Append-missing only (no filter-and-rebuild like the hooks above): removals
+  // ship via uninstall, and rebuilding would delete allows the user added by hand.
+  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 CORTEX_ALLOWED_TOOLS) {
+    if (!s.permissions.allow.includes(rule)) s.permissions.allow.push(rule)
+  }
+
+  return s
+}
+
+/** @type {import('./index.mjs').EditorAdapter} */
+export default {
+  id: 'claude-code',
+  displayName: 'Claude Code',
+
+  detect({ home = homedir(), exists = existsSync } = {}) {
+    return exists(join(home, '.claude')) || exists(join(home, '.claude.json'))
+  },
+
+  capabilities: {
+    promptTimeInjection: true,
+    sessionStart: true,
+    captureHook: true,
+    skillDir: '~/.claude/skills',
+    docTrigger: 'stop-hook',
+  },
+
+  // Two independent, non-fatal blocks (mirrors codex.mjs): a malformed file OR an IO error is
+  // skipped-with-warning, never a throw that aborts the other block or a sibling editor. readJson
+  // throws on malformed → caught here → that file is left untouched (never overwritten). The WRITTEN
+  // bytes come from the shared pure functions above, so they are identical to setup's output.
+  async wire({ home = homedir(), token, spec, log = () => {} } = {}) {
+    const wrote = [], skipped = [], warnings = []
+    if (!token) { warnings.push('no token — skipped Claude Code'); return { wrote, skipped, warnings } }
+
+    const claudeJson = join(home, '.claude.json')
+    try {
+      const cfg = readJson(claudeJson) // {} if absent/empty; THROWS (→ skip) if malformed
+      const bak = backupFile(claudeJson)
+      ensureDir(claudeJson)
+      writeJson(claudeJson, mergeClaudeMcp(cfg, spec, token))
+      wrote.push(claudeJson)
+      log(`  ✓ MCP server → ${claudeJson}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      warnings.push(`${claudeJson} wiring skipped: ${e.message}`)
+    }
+
+    const settingsJson = join(home, '.claude', 'settings.json')
+    try {
+      const s = readJson(settingsJson)
+      const bak = backupFile(settingsJson)
+      ensureDir(settingsJson)
+      writeJson(settingsJson, mergeClaudeSettings(s, spec))
+      wrote.push(settingsJson)
+      log(`  ✓ Capture + hydrate hooks + status line → ${settingsJson}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      warnings.push(`${settingsJson} wiring skipped: ${e.message}`)
+    }
+    return { wrote, skipped, warnings }
+  },
+}

package/lib/editors/codex.mjs

@@ -0,0 +1,111 @@
+// Editor adapter: OpenAI Codex. P0-b task 3 — wire() + the pure merge functions, moved here verbatim
+// from setup.mjs (which now imports + re-exports them). No caller imported them from setup except
+// setup itself, so this move is transparent.
+import { homedir } from 'node:os'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { readJson, backupFile, ensureDir, writeJson } from './_fsutil.mjs'
+
+/** Merge the Agnoclast MCP server into a Codex config.toml. Pure + idempotent: strips any existing
+ *  [mcp_servers.cortex] / [mcp_servers.cortex.env] tables (so re-runs update in place rather than
+ *  duplicating — a duplicate TOML table would break Codex's parser), preserves every other table,
+ *  and appends a fresh block. Only touches the cortex tables; never rewrites the user's config. */
+export function mergeCodexToml(text, spec, token) {
+  const targets = new Set(['[mcp_servers.cortex]', '[mcp_servers.cortex.env]'])
+  const kept = []
+  let skipping = false
+  for (const line of (text || '').split('\n')) {
+    const t = line.trim()
+    if (t.startsWith('[') && t.endsWith(']')) skipping = targets.has(t)
+    if (!skipping) kept.push(line)
+  }
+  while (kept.length && kept[kept.length - 1].trim() === '') kept.pop() // drop trailing blanks
+  const block = [
+    '',
+    '[mcp_servers.cortex]',
+    'command = "npx"',
+    `args = ["-y", "${spec}"]`,
+    'startup_timeout_sec = 60', // first npx fetch can be slow; don't time out the server on cold start
+    '',
+    '[mcp_servers.cortex.env]',
+    `CORTEX_TOKEN = "${token}"`,
+    '',
+  ]
+  return [...kept, ...block].join('\n')
+}
+
+/** Merge the capture Stop hook into a Codex hooks.json object. Pure + idempotent: drops any prior
+ *  cortex capture entry (old token / old path / old pinned version) before appending the current one,
+ *  so re-running never duplicates and never leaves a stale version pinned behind a live one.
+ *  Codex's hook runtime has NO SessionStart — only capture (Stop) is wired here. */
+export function mergeCodexHooks(existing, captureCmd) {
+  const h = existing && typeof existing === 'object' ? existing : {}
+  h.hooks = h.hooks && typeof h.hooks === 'object' ? h.hooks : {}
+  h.hooks.Stop = Array.isArray(h.hooks.Stop) ? h.hooks.Stop : []
+  for (const grp of h.hooks.Stop) {
+    if (Array.isArray(grp.hooks)) {
+      grp.hooks = grp.hooks.filter((c) => !/cortex-mcp.*capture|capture-session-cloud/.test(c.command ?? ''))
+    }
+  }
+  let grp = h.hooks.Stop.find((g) => (g.matcher ?? '') === '')
+  if (!grp) { grp = { matcher: '', hooks: [] }; h.hooks.Stop.push(grp) }
+  grp.hooks = grp.hooks ?? []
+  grp.hooks.push({ type: 'command', command: captureCmd })
+  return h
+}
+
+/** @type {import('./index.mjs').EditorAdapter} */
+export default {
+  id: 'codex',
+  displayName: 'OpenAI Codex',
+
+  detect({ home = homedir(), exists = existsSync } = {}) {
+    return exists(join(home, '.codex'))
+  },
+
+  // Codex's hook runtime recognizes PreToolUse/PostToolUse/PreCompact/UserPromptSubmit/Stop — notably
+  // NO SessionStart. So status/skills-repair/snapshot-context stay Claude-only; the manifest must
+  // encode sessionStart:false so P1/P2 don't assume it.
+  capabilities: {
+    promptTimeInjection: true,
+    sessionStart: false,
+    captureHook: true,
+    skillDir: null,
+    docTrigger: 'stop-hook',
+  },
+
+  // Two independent, non-fatal blocks (config.toml + hooks.json) — mirrors setup.mjs steps 1b/1c.
+  // Written bytes come from the shared pure functions above → identical to setup's output.
+  async wire({ home = homedir(), token, spec, log = () => {} } = {}) {
+    const wrote = [], skipped = [], warnings = []
+    if (!token) { warnings.push('no token — skipped Codex'); return { wrote, skipped, warnings } }
+    const codexDir = join(home, '.codex')
+
+    try {
+      const codexToml = join(codexDir, 'config.toml')
+      const existing = existsSync(codexToml) ? readFileSync(codexToml, 'utf8') : ''
+      const bak = backupFile(codexToml)
+      ensureDir(codexToml)
+      writeFileSync(codexToml, mergeCodexToml(existing, spec, token)) // raw TOML text, not JSON
+      wrote.push(codexToml)
+      log(`  ✓ MCP server → ${codexToml}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      warnings.push(`Codex MCP wiring skipped: ${e.message}`)
+    }
+
+    try {
+      const codexHooks = join(codexDir, 'hooks.json')
+      let existingHooks
+      try { existingHooks = readJson(codexHooks) } catch { existingHooks = {} } // malformed → start fresh, don't block
+      const bak = backupFile(codexHooks)
+      const captureCmd = `npx -y ${spec} capture`
+      ensureDir(codexHooks)
+      writeJson(codexHooks, mergeCodexHooks(existingHooks, captureCmd))
+      wrote.push(codexHooks)
+      log(`  ✓ Capture hook → ${codexHooks}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      warnings.push(`Codex capture hook skipped: ${e.message}`)
+    }
+    return { wrote, skipped, warnings }
+  },
+}