klypix-mcp 1.34.0 → 1.38.0

package/README.md

@@ -10,18 +10,46 @@ You've seen the setup: point an AI at a folder of notes, watch the graph fill up
 
 ## Quick start
 
-**Claude Code + Codex (native, machine-wide):**
+**Claude Code + Codex:**
 
 ```bash
 npx klypix-mcp install
 ```
 
-Claude Code keeps its live hooks for auto-brief + auto-capture. Codex gets a native
-`~/.codex/config.toml` MCP registration, conditional global guidance, and lifecycle
-hooks for truthful cross-agent presence and one-time messages. Existing MCP servers,
-hooks, settings, and personal instructions are preserved; KLYPIX owns only its fenced
-blocks and `codex-brain-hook.mjs` handlers, with backups before changes. Restart Codex
-after installation and approve the KLYPIX hooks when Codex presents its trust review.
+Claude Code keeps its live hooks for auto-brief + auto-capture. Codex gets native MCP
+tools, **automatic live-session presence**, and approval-free **smart task synchronization**
+from the authorized MCP connection itself. `brain_sync` is a bounded **Context Gateway**:
+one call returns task-relevant brain memory, meaningful active-task peers, structured
+exact-file conflicts, one-time notes, and automatic late-arrival overlap alerts. The
+earlier session gets a best-effort live MCP logging notification within seconds, while
+the same alert remains guaranteed on its next KLYPIX action if its host hides logs. Idle MCP
+connections stay counted for diagnostics but are hidden from the task-peer list. MCP
+server instructions plus a managed Codex `AGENTS.md` block teach Codex to call it at task
+start, when scope changes, and on completion—no Codex hook approval required. Run inside a
+project containing `brain.klypix`, or run `npx klypix-mcp link` in each brain project.
+The installer removes the obsolete global KLYPIX `--vault "."` table that could resolve
+outside the active project; every unrelated Codex setting and MCP server is preserved.
+
+Optional native lifecycle capture for mechanical prompt/tool/file events:
+
+```bash
+npx klypix-mcp install --codex-hooks
+```
+
+Codex owns this native layer's security decision and asks the user to review/trust the
+hooks on surfaces that expose hook management. Once trusted, the enhanced layer
+automatically injects bounded task-ranked brain memory on every prompt and warns before
+an exact overlapping file edit. `brain_doctor` reports it separately as off,
+execution-unverified, or active; the approval-free smart layer remains active either way.
+
+Prove the exact installed runtime with two isolated real MCP clients:
+
+```bash
+npx klypix-mcp conformance
+```
+
+The test touches only a temporary fixture. It verifies tool discovery, task memory,
+truthful peers, blocking overlap detection, proactive logging, and guaranteed in-band delivery.
 
 Give a project a brain by dropping a `brain.klypix` in it — the
 [KLYPIX app](https://klypix.com) does it in one click (*Save canvas as project brain*),
@@ -41,7 +69,7 @@ managed files without changing them with `npx klypix-mcp link --check`.
 
 The difference from a folder of notes is not the shape — it's that this memory is a **mechanism, not a filing convention**:
 
-- **It briefs every session.** Each agent session starts already knowing the project's decisions, open questions, and standing rules — a compact brief (≈3–5k tokens even at 600+ cards, growing sublinearly). Measured on our own brain: **73% of past decisions recovered with one search round (55% brief-only) vs 0% cold** (n=20).
+- **It briefs each task, not just each session.** `brain_sync` ranks a bounded memory capsule from the actual task intent and expected files. The full generated brief remains available for broad history/status work, while the always-loaded `AGENTS.md` fallback stays compact. Measured on our own brain: **73% of past decisions recovered with one search round (55% brief-only) vs 0% cold** (n=20).
 - **It argues back.** `brain_challenge`: propose a decision and the brain answers with receipts — *"you reversed this on June 12; here's the correction — captured by a different agent, coordinate before overriding."* Deterministic evidence only (correction-cues, opposite-polarity), never mere topical similarity. A memory that can't disagree with you is flattery.
 - **It knows when it's stale.** Decision cards can anchor to the exact code they were decided against (git blob OID). When that code moves on, the card raises its hand in the next brief. Their notes rot silently; ours confess.
 - **It answers from the past.** `brain_ask` with `as_of: 2026-03-01` answers what the project believed *then* — corrections from the future never leak backwards.
@@ -59,7 +87,8 @@ And it's not a cage: everything **exports to Markdown and JSON Canvas** in one c
 
 ## Setup for plain MCP clients
 
-Any MCP client gets the tools without the hooks. For **Claude Desktop**, in `claude_desktop_config.json`:
+Any MCP client gets the tools and connection-lifecycle presence without host hooks. For
+**Claude Desktop**, in `claude_desktop_config.json`:
 
 ```json
 {
@@ -72,9 +101,14 @@ Any MCP client gets the tools without the hooks. For **Claude Desktop**, in `cla
 }
 ```
 
-Then ask your agent things like *"what did we decide about auth?"*, *"challenge this: let's switch to polling"*, or *"turn these notes into a board."*
+If the vault contains `brain.klypix`, that MCP connection also appears as an active
+session. `brain_sync` adds compact task memory, expected-file coordination, task-only peer
+reporting, structured exact-overlap warnings, automatic conflict alerts, timing receipts,
+best-effort proactive notifications, and guaranteed one-time peer-note delivery. Then ask your
+agent things like *"what did we decide about auth?"*, *"challenge this: let's switch
+to polling"*, or *"turn these notes into a board."*
 
-## The 17 verbs
+## The 18 verbs
 
 | Tool | What it does |
 |---|---|
@@ -83,9 +117,11 @@ Then ask your agent things like *"what did we decide about auth?"*, *"challenge
 | `brain_note` | Capture with the full lifecycle — supersede / ✓ resolve / ~ update / 🛠 skill / closes: |
 | `brain_reconcile` | Find stale-vs-correction pairs + unrecorded migrations |
 | `brain_insights` | Hubs, orphaned decisions, stale questions, area sizes |
+| `brain_lens` | Machine-readable freshness, provenance, activity, timeline, orrery, and unresolved views |
 | `brain_garden` | Maintenance pass over the brain |
-| `brain_doctor` | Self-diagnosis: version, host adapters, active lifecycle sessions, projection drift |
+| `brain_doctor` | Self-diagnosis: version, core/enhanced host adapters, active sessions, projection drift |
 | `brain_message` | Session-to-session coordination notes |
+| `brain_sync` | Context Gateway: compact task memory, active-task peers, structured conflicts, automatic alerts, and timing |
 | `brain_connect` | Find + draw related-but-unlinked cards |
 | `canvas_view` | The board as an MCP App — Apps-capable chats get an interactive spatial view; everyone else gets clean text |
 | `read_canvas` | A canvas as markdown (cards, connection graph, `[[links]]`, `#tags`) |
@@ -97,23 +133,25 @@ Then ask your agent things like *"what did we decide about auth?"*, *"challenge
 
 ### Tools vs. the *automatic* brain
 
-This package is the **agent-neutral read/write surface** — any MCP client gets the tools above on demand (*pull*), in any project. `install` wires Claude Code's existing capture path plus Codex's native MCP, conditional guidance, and separate presence adapter; `link` projects the repository-level MCP and instruction files used by other coding agents. Full transcript-driven auto-capture remains a Claude Code capability. Codex reports lifecycle presence and captures durable decisions explicitly through `brain_note`; hookless clients can use the MCP surface but are not reported as active.
+This package is the **agent-neutral read/write surface** — any MCP client gets the tools above on demand (*pull*), automatically registers presence for the lifetime of its authorized connection, and receives the Context Gateway workflow through standard MCP server instructions. `install` wires Claude Code's existing capture path and installs the local runtime; `link` projects repository-level MCP and instruction files for Codex and other coding agents. Codex and other clients retrieve relevant project memory and coordinate task intent/files through one `brain_sync` call, while `brain_note` captures durable decisions explicitly; optional host hooks add mechanically guaranteed lifecycle capture.
 
 ### Agent-neutral live presence
 
-An active session means a host lifecycle hook heartbeated within 10 minutes; a row in a
-recent-chat list is history, not presence. Claude Code and Codex publish into the same
-per-brain lane, while each host keeps its own adapter and capture behavior. `SessionEnd`
-removes clean exits immediately, and the TTL covers crashes.
+An active session means an authorized MCP connection or host lifecycle adapter
+heartbeated within 10 minutes; a row in a recent-chat list is history, not presence.
+Each MCP connection registers at initialization and removes itself on disconnect.
+Optional host adapters merge into that same logical session rather than double-counting
+it, enrich it with intent/files, and remove only their own channel. The TTL covers crashes.
 
-Future hosts can import `klypix-mcp/presence` and map their lifecycle events to
-`upsertSession`, `removeSession`, and `receiveMessages`. The shared contract accepts
-`id`, `client`, `surface`, `model`, `branch`, `intent`, and touched `files`; host-specific
-transcript parsing stays outside the protocol.
+Future hosts get baseline support merely by connecting the MCP server. A deeper adapter
+can import `klypix-mcp/presence` and map lifecycle events to `upsertSession`,
+`removeSession`, `peekMessages`, and `receiveMessages`. The shared contract accepts `id`, `client`,
+`surface`, `model`, `branch`, `intent`, touched `files`, and adapter `channel`;
+host-specific transcript parsing stays outside the protocol.
 
 ### Updates — the propagation contract
 
-`install` lays the whole brain (hooks + engine + local MCP server) into `~/.claude/project-brain`, then points both Claude and Codex at that installed bundle so there is no npx cache to go stale. Updates are automatic through the Claude session-start hook: it checks npm (≤ once/24h, fail-open, disable with `KLYPIX_AUTO_UPDATE=0`) and self-installs newer releases, including healing the Codex registration. One honest caveat: a running stdio server can't hot-swap — a new binary loads on the next full app launch (or `/mcp` reconnect); `brain_doctor`'s RUNNING line tells you when that's needed.
+`install` lays the whole brain (hooks + engine + local MCP server) into `~/.claude/project-brain` and keeps the current brain project's Codex config machine-portable. Updates are automatic through the Claude session-start hook: it checks npm (≤ once/24h, fail-open, disable with `KLYPIX_AUTO_UPDATE=0`) and self-installs newer releases. One honest caveat: a running stdio server can't hot-swap — a new binary loads on the next full app launch (or `/mcp` reconnect); `brain_doctor`'s RUNNING line tells you when that's needed.
 
 ## Also speaks A2A (Agent-to-Agent)
 

package/bin/klypix-conformance.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// Self-contained KLYPIX MCP conformance test.
+//
+// Launches two real stdio clients against this exact installed server build,
+// using a temporary brain + isolated presence registry. It verifies the
+// Context Gateway, task memory, truthful task counts, exact overlap detection,
+// proactive MCP logging, and guaranteed next-action delivery without touching
+// the user's project or durable brain.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { LoggingMessageNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { buildKlypixMap } from '../src/klypix-core.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const jsonMode = process.argv.includes('--json');
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const PKG_VERSION = (() => {
+  try { return createRequire(import.meta.url)('../package.json').version; }
+  catch {
+    try {
+      const stamp = JSON.parse(fs.readFileSync(path.join(here, '.brain-version.json'), 'utf8'));
+      return stamp.brainVersion || stamp.appVersion || 'deployed';
+    } catch { return 'deployed'; }
+  }
+})();
+const serverPath = [
+  path.join(here, 'klypix-mcp.mjs'),
+  path.join(here, 'klypix-mcp-server.mjs'),
+].find((candidate) => fs.existsSync(candidate));
+
+if (!serverPath) {
+  console.error('KLYPIX conformance failed: the MCP server executable is missing beside this command.');
+  process.exit(1);
+}
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'klypix-conformance-'));
+const vault = path.join(tempRoot, 'project');
+const isolatedHome = path.join(tempRoot, 'home');
+fs.mkdirSync(vault, { recursive: true });
+fs.mkdirSync(isolatedHome, { recursive: true });
+fs.writeFileSync(path.join(vault, 'brain.klypix'), await buildKlypixMap({
+  title: 'KLYPIX conformance brain',
+  kind: 'brain',
+  areas: [{
+    title: 'Brain',
+    cards: [{
+      text: 'Codex Context Gateway automatically coordinates active tasks and exact file overlaps across MCP sessions.',
+    }],
+  }],
+}));
+
+const baseEnv = Object.fromEntries(
+  Object.entries(process.env).filter(([, value]) => typeof value === 'string'),
+);
+
+async function connect(name, sessionId) {
+  const logs = [];
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [serverPath, '--vault', vault],
+    env: {
+      ...baseEnv,
+      USERPROFILE: isolatedHome,
+      HOME: isolatedHome,
+      KLYPIX_SESSION_ID: sessionId,
+      KLYPIX_MCP_INBOX_POLL_MS: '250',
+      KLYPIX_RERANK: '0',
+    },
+    stderr: 'pipe',
+  });
+  const client = new Client({ name, version: '1.0.0' });
+  client.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
+    logs.push(String(notification?.params?.data || ''));
+  });
+  await client.connect(transport);
+  await client.setLoggingLevel('info');
+  return { client, transport, logs };
+}
+
+const checks = {};
+const metrics = {};
+let a;
+let b;
+try {
+  a = await connect('codex-klypix-conformance-a', 'klypix-conformance-a');
+  b = await connect('codex-klypix-conformance-b', 'klypix-conformance-b');
+  const tools = await a.client.listTools();
+  checks.brainSyncDiscoverable = tools.tools?.some((tool) => tool.name === 'brain_sync') === true;
+
+  const aStart = await a.client.callTool({
+    name: 'brain_sync',
+    arguments: {
+      phase: 'start',
+      intent: 'Validate automatic Codex Context Gateway coordination',
+      files: ['src/conformance-overlap.ts'],
+    },
+  });
+  const bStart = await b.client.callTool({
+    name: 'brain_sync',
+    arguments: {
+      phase: 'start',
+      intent: 'Validate proactive overlap delivery from a second session',
+      files: ['src/conformance-overlap.ts'],
+    },
+  });
+  const aStructured = aStart.structuredContent || {};
+  const bStructured = bStart.structuredContent || {};
+  checks.taskMemory = Array.isArray(aStructured.context?.hits) && aStructured.context.hits.length > 0;
+  checks.truthfulTaskCount = bStructured.counts?.activeTasks === 2
+    && bStructured.peers?.length === 1;
+  checks.exactBlockingOverlap = bStructured.conflicts?.length === 1
+    && bStructured.conflicts[0]?.kind === 'exact-file'
+    && bStructured.conflicts[0]?.severity === 'blocking';
+  checks.alertQueued = bStructured.alertsQueued?.length === 1;
+  metrics.firstClientMs = aStructured.timingMs?.total ?? null;
+  metrics.secondClientMs = bStructured.timingMs?.total ?? null;
+
+  const pushDeadline = Date.now() + 4_000;
+  while (Date.now() < pushDeadline
+    && !a.logs.some((line) => line.includes('Automatic KLYPIX overlap alert'))) {
+    await wait(100);
+  }
+  checks.proactiveLogging = a.logs.some((line) =>
+    line.includes('Automatic KLYPIX overlap alert'));
+  metrics.firstClientLogCount = a.logs.length;
+  if (!checks.proactiveLogging && a.logs.length) metrics.firstClientLogs = a.logs.slice(-4);
+
+  const aCheckpoint = await a.client.callTool({
+    name: 'brain_sync',
+    arguments: {
+      phase: 'checkpoint',
+      intent: 'Validate automatic Codex Context Gateway coordination',
+      files: ['src/conformance-overlap.ts'],
+    },
+  });
+  const checkpointStructured = aCheckpoint.structuredContent || {};
+  checks.guaranteedInBandDelivery = checkpointStructured.messages?.some((message) =>
+    String(message.text).includes('Automatic KLYPIX overlap alert')) === true;
+
+  await Promise.all([
+    a.client.callTool({ name: 'brain_sync', arguments: { phase: 'complete' } }),
+    b.client.callTool({ name: 'brain_sync', arguments: { phase: 'complete' } }),
+  ]);
+} catch (error) {
+  checks.runtime = false;
+  checks.error = error?.message || String(error);
+} finally {
+  await Promise.allSettled([a?.client?.close(), b?.client?.close()]);
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}
+
+const required = [
+  'brainSyncDiscoverable',
+  'taskMemory',
+  'truthfulTaskCount',
+  'exactBlockingOverlap',
+  'alertQueued',
+  'proactiveLogging',
+  'guaranteedInBandDelivery',
+];
+const ok = required.every((name) => checks[name] === true);
+const result = {
+  ok,
+  packageVersion: PKG_VERSION,
+  checks,
+  metrics,
+  contract: {
+    proactive: 'best-effort MCP logging notification',
+    guaranteed: 'same alert on the next KLYPIX action',
+  },
+};
+
+if (jsonMode) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} else {
+  console.log(`KLYPIX MCP conformance v${PKG_VERSION}: ${ok ? 'PASS' : 'FAIL'}`);
+  for (const name of required) {
+    console.log(`  ${checks[name] ? '✓' : '✗'} ${name}`);
+  }
+  if (checks.error) console.log(`  error: ${checks.error}`);
+  console.log(`  memory/coordination: ${metrics.firstClientMs ?? '?'}ms / ${metrics.secondClientMs ?? '?'}ms`);
+  console.log('  proactive notifications are best-effort; next-action delivery is guaranteed.');
+}
+process.exit(ok ? 0 : 1);

package/bin/klypix-install.mjs

@@ -9,6 +9,7 @@
 //
 //   npx klypix-mcp install            # install / update the brain on this machine
 //   npx klypix-mcp install --force    # overwrite even a newer / dev-deployed brain
+//   npx klypix-mcp install --codex-hooks  # optional prompt/file awareness; Codex asks for trust
 //
 // Never-throws-silently: it's an explicit CLI, so it reports what it did and exits
 // non-zero on a real failure. Never wires a broken settings.json (refuse + restore).
@@ -18,10 +19,14 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import {
     connectCodexMcpServer,
+    disconnectCodexMcpServer,
     mcpServerEntry,
     mergeCodexGlobalInstructions,
 } from '../src/agent-rules.mjs';
-import { mergeCodexPresenceHooks } from '../src/codex-hooks.mjs';
+import {
+    codexPresenceHookStatus,
+    mergeCodexPresenceHooks,
+} from '../src/codex-hooks.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -29,6 +34,7 @@ const SRC = path.join(PKG_ROOT, 'src');
 const BIN = path.join(PKG_ROOT, 'bin');
 const VERSION = (() => { try { return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version || ''; } catch { return ''; } })();
 const FORCE = process.argv.includes('--force');
+const CODEX_HOOKS = process.argv.includes('--codex-hooks');
 
 const HOME = os.homedir();
 const CLAUDE_DIR = path.join(HOME, '.claude');
@@ -38,44 +44,96 @@ const CODEX_CONFIG = path.join(HOME, '.codex', 'config.toml');
 const HOOK_MARK = 'global-brain-hook';
 const exists = (p) => { try { fs.statSync(p); return true; } catch { return false; } };
 const fwd = (p) => p.replace(/\\/g, '/');
+const copyRetrySleepSync = (ms) => {
+    try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+    catch { /* best effort */ }
+};
+function copyFileRobust(src, dest, tries = 8) {
+    for (let attempt = 1; attempt <= tries; attempt++) {
+        try { fs.copyFileSync(src, dest); return; }
+        catch (error) {
+            const retryable = ['EBUSY', 'EPERM', 'EACCES'].includes(error?.code);
+            if (!retryable || attempt === tries) throw error;
+            copyRetrySleepSync(20 * attempt);
+        }
+    }
+}
 function copyDir(src, dest) {
     fs.mkdirSync(dest, { recursive: true });
     for (const e of fs.readdirSync(src, { withFileTypes: true })) {
         const s = path.join(src, e.name), d = path.join(dest, e.name);
-        if (e.isDirectory()) copyDir(s, d); else if (e.isFile()) fs.copyFileSync(s, d);
+        if (e.isDirectory()) copyDir(s, d); else if (e.isFile()) copyFileRobust(s, d);
     }
 }
 
-// Codex has three independent integration layers: MCP gives it the brain tools,
-// a conditional managed block in ~/.codex/AGENTS.md tells every brain project to
-// use them, and lifecycle hooks publish live presence to the shared session lane.
+// Codex has two approval-free layers and one optional native layer:
+// project-scoped MCP gives it tools + live presence + brain_sync, while the
+// conditional ~/.codex/AGENTS.md block makes the Context Gateway workflow
+// automatic on every task. Native lifecycle hooks add mechanical prompt/file
+// capture only when the user explicitly asks for --codex-hooks and approves them
+// in a Codex surface that exposes trust review.
 function wireCodex() {
-    const mcp = connectCodexMcpServer({
-        configPath: CODEX_CONFIG,
-        entry: mcpServerEntry({ vault: '.', home: HOME }),
-    });
+    const projectDir = process.cwd();
+    const hasProjectBrain = exists(path.join(projectDir, 'brain.klypix'))
+        || exists(path.join(projectDir, 'brain.any'));
+    const projectConfig = path.join(projectDir, '.codex', 'config.toml');
+    const mcp = hasProjectBrain
+        ? connectCodexMcpServer({
+            configPath: projectConfig,
+            // Project config is commonly committed. Keep it portable: the
+            // package invocation that is running this installer is exactly the
+            // version the project asked for, while an absolute home path would
+            // dirty the repo and break it on every other machine.
+            entry: { command: 'npx', args: ['-y', 'klypix-mcp', '--vault', '.'] },
+            cwd: '..',
+        })
+        : { ok: true, action: 'skipped-no-project-brain', path: projectConfig };
+    // Pre-1.35 installed a global `--vault "."` entry. A global Codex process
+    // resolves that dot from the app install directory, not the user's project,
+    // so it can silently bind the wrong brain and override the correct project
+    // table. Remove only KLYPIX-owned global tables; preserve every other server.
+    const globalMcp = disconnectCodexMcpServer({ configPath: CODEX_CONFIG });
     const instructions = mergeCodexGlobalInstructions(HOME);
     const hookScript = path.join(BRAIN_DIR, 'codex-brain-hook.mjs');
-    const presence = exists(hookScript)
+    const presence = CODEX_HOOKS && exists(hookScript)
         ? mergeCodexPresenceHooks({
             home: HOME,
             command: `node "${fwd(hookScript)}"`,
         })
-        : { ok: true, action: 'not-available' };
-    return { mcp, instructions, presence, ok: mcp.ok && instructions.ok && presence.ok };
+        : {
+            ok: true,
+            action: codexPresenceHookStatus(HOME).installed ? 'existing' : 'off',
+            ...codexPresenceHookStatus(HOME),
+        };
+    return {
+        mcp,
+        globalMcp,
+        instructions,
+        presence,
+        ok: mcp.ok && globalMcp.ok && instructions.ok && presence.ok,
+    };
 }
 
 function reportCodex(result) {
     if (result.ok) {
-        const live = result.presence.action === 'not-available'
-            ? 'live presence pending a current brain bundle'
-            : `live presence (${result.presence.action})`;
-        console.log(`✓ wired Codex: MCP tools (${result.mcp.action}) + conditional project-brain guidance (${result.instructions.action}) + ${live}`);
+        const mcp = result.mcp.action === 'skipped-no-project-brain'
+            ? 'project MCP skipped (run `npx klypix-mcp link` inside a brain project)'
+            : `project MCP + automatic presence/Context Gateway (${result.mcp.action})`;
+        const enhanced = result.presence.action === 'off'
+            ? 'enhanced hooks off (optional)'
+            : result.presence.action === 'existing'
+                ? `enhanced hooks already configured (${result.presence.executionStatus || 'unverified'})`
+                : `enhanced hooks ${result.presence.action} — approve/review them in Codex /hooks`;
+        console.log(`✓ wired Codex: ${mcp} + approval-free task guidance (${result.instructions.action}) + ${enhanced}`);
+        if (result.globalMcp.action === 'disconnected') {
+            console.log('✓ removed obsolete global Codex KLYPIX MCP entry (it could resolve "." outside the project); other MCP servers were preserved');
+        }
         return;
     }
     if (!result.mcp.ok) console.error(`⚠ Codex MCP was not changed: ${result.mcp.error}`);
+    if (!result.globalMcp.ok) console.error(`⚠ obsolete global Codex MCP entry was not removed: ${result.globalMcp.error}`);
     if (!result.instructions.ok) console.error(`⚠ Codex guidance was not changed: ${result.instructions.error}`);
-    if (!result.presence.ok) console.error(`⚠ Codex live presence was not changed: ${result.presence.error}`);
+    if (!result.presence.ok) console.error(`⚠ Codex enhanced hooks were not changed: ${result.presence.error}`);
     console.error('  Claude Code installation is intact. Fix the Codex warning, then re-run this command.');
 }
 
@@ -134,6 +192,10 @@ function migrateProjectMcpConfig() {
         const entry = servers && servers['klypix-canvas'];
         if (!entry || (entry.command !== 'npx' && entry.command !== 'node')) return null;   // absent / hand-customized → leave it
         const args = Array.isArray(entry.args) ? entry.args : [];
+        // A repo-relative node launch (for example scripts/klypix-mcp-server.mjs)
+        // is deliberately portable and often tracks a project-owned bundle.
+        // Never replace it with a machine-specific ~/.claude path.
+        if (entry.command === 'node' && args[0] && !path.isAbsolute(String(args[0]))) return null;
         const vi = args.indexOf('--vault');
         const vault = vi >= 0 && args[vi + 1] ? args[vi + 1] : '.';
         const next = mcpServerEntry({ vault });   // local now that the bundle is installed
@@ -154,7 +216,7 @@ const flatten = (code) => code
     .replace(/\.\.\/src\/klypix-(core|format)\.mjs/g, './klypix-$1.mjs')
     // brain-doctor + agent-rules (the server's lazy `import('../src/brain-doctor.mjs')`
     // for the brain_doctor tool) → flat sibling refs in the runtime layout.
-    .replace(/\.\.\/src\/(brain-doctor|agent-rules)\.mjs/g, './$1.mjs')
+    .replace(/\.\.\/src\/(brain-doctor|agent-rules|mcp-presence)\.mjs/g, './$1.mjs')
     .replace(/const PKG_VERSION = \(\(\) => \{[\s\S]*?\}\)\(\);/, `const PKG_VERSION = '${VERSION}'; // baked at install (flat layout has no package.json)`);
 
 const gotLock = acquireLock();
@@ -211,10 +273,14 @@ try {
     // canvas-view-app.html is the canvas_view MCP App UI — staged raw (an HTML
     // file must never get a JS-comment banner) beside the flat server, which
     // resolves it via its ./canvas-view-app.html candidate path.
-    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
+    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
-    for (const [src, dst] of [['klypix-mcp.mjs', 'klypix-mcp-server.mjs'], ['klypix-a2a.mjs', 'klypix-a2a-server.mjs']]) {
+    for (const [src, dst] of [
+        ['klypix-mcp.mjs', 'klypix-mcp-server.mjs'],
+        ['klypix-a2a.mjs', 'klypix-a2a-server.mjs'],
+        ['klypix-conformance.mjs', 'klypix-conformance.mjs'],
+    ]) {
         const s = path.join(BIN, src); if (exists(s)) staged.push({ dst, content: flatten(fs.readFileSync(s, 'utf8')) });
     }
     for (const st of staged) fs.writeFileSync(path.join(BRAIN_DIR, st.dst + '.klypix-new'), st.content);
@@ -282,9 +348,10 @@ try {
     else console.error(`⚠ readiness: ${notWired.length} hook(s) did NOT take (${notWired.join(', ')}) — the brain will read but not capture/sync. Re-run \`npx klypix-mcp install --force\` or check ${SETTINGS}.`);
     console.log(`✓ MCP server runs from the local bundle (node ${fwd(path.join(BRAIN_DIR, 'klypix-mcp-server.mjs'))}) — no npx cache, works offline, always the installed version.`);
     if (migrated) console.log(`✓ migrated ${migrated.file} klypix-canvas server: ${migrated.from} → ${migrated.to} (backup: .mcp.json.klypix-bak). Reconnect (/mcp) or restart to pick it up.`);
-    console.log('  Claude Code keeps its existing auto-brief/capture hooks; Codex uses separate lifecycle hooks for live presence and native MCP for durable memory.');
+    console.log('  Claude Code keeps its existing auto-brief/capture hooks; Codex gets the brain_sync Context Gateway (compact task memory + clean peers + proactive/guaranteed conflict alerts) with no hook trust prompt.');
+    console.log('  Enhanced Codex auto-context + pre-edit overlap guard: re-run with `--codex-hooks`, then approve/review KLYPIX once in a Codex surface that supports hook trust.');
     console.log('  ⚠ Open sessions keep their OLD server until relaunched: fully quit & reopen the app (a session resume / new chat does NOT respawn the MCP server). `brain_doctor`\'s RUNNING line confirms when you\'re current.');
-    console.log('  Verify anytime: `npx klypix-mcp doctor` (is the brain current + wired + in sync, who else is live).');
+    console.log('  Verify anytime: `npx klypix-mcp doctor`; prove two-client behavior with `npx klypix-mcp conformance`.');
 } catch (e) {
     if (gotLock) releaseLock();
     console.error(`✗ install failed: ${e?.message || e}`);

package/bin/klypix-link.mjs

@@ -17,7 +17,7 @@
 // Synchronous top-level by design: the dispatcher does `await import(this); process.exit(0)`,
 // so all work (and its logs) must complete during module evaluation, before exit.
 import path from 'path';
-import { linkProject } from '../src/agent-rules.mjs';
+import { compactAgentsBrief, linkProject } from '../src/agent-rules.mjs';
 
 try {
   const args = process.argv.slice(3);
@@ -25,6 +25,7 @@ try {
   const dirArg = args.find(a => !a.startsWith('-'));
   const projectDir = path.resolve(dirArg || process.cwd());
   const { rules, mcp, hasBrain, version } = linkProject(projectDir, { check });
+  const compactBrief = await compactAgentsBrief(projectDir, { check });
 
   if (check) {
     // Audit-only: classify, report, exit 1 on any drift.
@@ -34,7 +35,11 @@ try {
     for (const r of mcp) console.log(`    ${mark(r.status)} ${r.tool.padEnd(26)} ${r.file} — ${r.status.toUpperCase()}${r.why ? ' (' + r.why + ')' : ''}`);
     console.log('\n  Rules / instructions:');
     for (const r of rules) console.log(`    ${mark(r.status)} ${r.tool.padEnd(26)} ${r.file} — ${r.status.toUpperCase()}${r.stampedVersion ? ' (stamped v' + r.stampedVersion + ')' : ''}`);
-    const drift = [...rules, ...mcp].filter(r => r.status !== 'ok');
+    if (compactBrief.status !== 'skipped') {
+      console.log(`    ${mark(compactBrief.status)} ${'AGENTS.md compact fallback'.padEnd(26)} AGENTS.md — ${compactBrief.status.toUpperCase()}${compactBrief.bytes ? ` (${compactBrief.bytes} bytes)` : ''}`);
+    }
+    const briefDrift = ['stale', 'error'].includes(compactBrief.status) ? [compactBrief] : [];
+    const drift = [...rules, ...mcp, ...briefDrift].filter(r => r.status !== 'ok' && r.status !== 'skipped');
     if (!drift.length) { console.log(`\n✓ in sync — all ${rules.length + mcp.length} managed file(s) match brain v${version}.`); process.exit(0); }
     console.log(`\n✗ ${drift.length} file(s) drifted (stale / hand-edited / missing) — run \`npx klypix-mcp link\` to re-project.`);
     process.exit(1);
@@ -46,8 +51,11 @@ try {
   for (const r of mcp) console.log(`    ${mark(r.action)} ${r.tool.padEnd(26)} ${r.file}${r.why ? '  (' + r.why + ')' : ''}`);
   console.log('\n  Rules (so each tool auto-reads + captures the brain):');
   for (const r of rules) console.log(`    ${mark(r.action)} ${r.tool.padEnd(26)} ${r.file}${r.why ? '  (' + r.why + ')' : ''}`);
+  if (compactBrief.status !== 'skipped') {
+    console.log(`    ${mark(compactBrief.action)} ${'AGENTS.md compact fallback'.padEnd(26)} AGENTS.md${compactBrief.bytes ? `  (${compactBrief.bytes} bytes)` : ''}`);
+  }
 
-  const changed = [...rules, ...mcp].filter(r => r.action && !['unchanged', 'skipped'].includes(r.action)).length;
+  const changed = [...rules, ...mcp, compactBrief].filter(r => r.action && !['unchanged', 'skipped'].includes(r.action)).length;
   console.log(`\n✓ ${changed} file(s) written/updated — every agent opened in this project now reads + captures ./brain.klypix.`);
   console.log('  Codex gets .codex/config.toml + AGENTS.md; Cline & Windsurf use their global MCP config plus project rules.');
   console.log('  Verify anytime with `npx klypix-mcp link --check` (or `npx klypix-mcp doctor`).');