klypix-mcp 1.34.0 → 1.37.0

package/README.md

@@ -10,18 +10,33 @@ 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. 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. `brain_doctor` reports it separately as
+off, execution-unverified, or active; the approval-free smart layer remains active either way.
 
 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 +56,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 +74,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 +88,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,
+and 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 +104,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 +120,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`, 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-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,7 +273,7 @@ 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']]) {
@@ -282,7 +344,8 @@ 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 + automatic conflict alerts) with no hook trust prompt.');
+    console.log('  Optional mechanical Codex lifecycle capture: re-run with `--codex-hooks`, then approve/review KLYPIX 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).');
 } catch (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`).');

package/bin/klypix-mcp.mjs

@@ -27,8 +27,10 @@ import {
   resolveVault, getEmbedder, buildKlypixMap, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
+  opBrainTaskContext,
 } from '../src/klypix-core.mjs';
 import { mcpServerEntry } from '../src/agent-rules.mjs';
+import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS } from '../src/mcp-presence.mjs';
 
 // Real package version for the MCP handshake (was hardcoded '1.0.0', which
 // misled every client/version diagnosis — it could never reflect the true release).
@@ -102,17 +104,21 @@ if (process.argv[2] === 'init') {
 
 const vaultArgIdx = process.argv.indexOf('--vault');
 const VAULT = resolveVault(vaultArgIdx >= 0 ? process.argv[vaultArgIdx + 1] : undefined);
+const server = new McpServer(
+  { name: 'klypix-canvas', version: PKG_VERSION },
+  { instructions: KLYPIX_MCP_INSTRUCTIONS },
+);
+const mcpPresence = createMcpPresence({ server, initialVault: VAULT });
 
 // Map a protocol-neutral core result → an MCP tool result.
 const toContent = (r) => {
   const content = r.blocks.map(b => b.kind === 'image'
     ? { type: 'image', data: b.data, mimeType: b.mime }
     : { type: 'text', text: b.text });
-  return r.isError ? { content, isError: true } : { content };
+  const result = r.isError ? { content, isError: true } : { content };
+  return mcpPresence.decorateToolResult(result);
 };
 
-const server = new McpServer({ name: 'klypix-canvas', version: PKG_VERSION });
-
 server.registerTool('list_canvases', {
   title: 'List KLYPIX canvases',
   description: 'List all .klypix / .any canvas files in the vault, with card and connection counts.',
@@ -265,7 +271,7 @@ server.registerTool('brain_note', {
 
 server.registerTool('brain_message', {
   title: 'Message the other live agent sessions on this project (one-time note, not a brain card)',
-  description: 'Leave a DELIBERATE, targeted note for the OTHER active agent sessions working on this project right now ("merged the hook refactor — rebase before you commit", "don\'t touch canvasStore, mid-refactor"). Any MCP client can SEND (the twin of the `🧠 MSG [to]: text` marker); delivery is to presence-wired sessions (Claude Code and Codex, with more host adapters supported by the shared protocol). Each receives it once through its lifecycle hook. A hookless peer can send but will NOT receive. Ephemeral (expires in 24h) and NOT persisted to the brain — for a durable decision use brain_note instead.',
+  description: 'Leave a DELIBERATE, targeted note for the OTHER active agent sessions working on this project right now ("merged the hook refactor — rebase before you commit", "don\'t touch canvasStore, mid-refactor"). Any MCP client can send and receive through the shared presence lane. Hookless MCP peers receive each note once on their next KLYPIX tool call (and may also see a host logging notification); lifecycle hooks provide more proactive delivery. Ephemeral (expires in 24h) and NOT persisted to the brain — for a durable decision use brain_note instead.',
   inputSchema: {
     text: z.string().describe('The note to deliver (kept to 400 chars).'),
     to: z.string().optional().describe('Target hint — a peer session id-prefix or branch name; omit or "all" for every live session.'),
@@ -273,12 +279,75 @@ server.registerTool('brain_message', {
   },
 }, async ({ text, to, canvas }) => {
   let via; try { via = server.server.getClientVersion()?.name; } catch { /* optional */ }
+  mcpPresence.noteSent(text);
   return toContent(await opBrainMessage({ vault: VAULT, canvas, text, to, via }));
 });
 
+server.registerTool('brain_sync', {
+  title: 'KLYPIX Context Gateway — synchronize task, peers, conflicts, and relevant memory',
+  description: 'APPROVAL-FREE task gateway over the authorized MCP connection. Call FIRST with a concise intent and expected files, again when scope changes, and with phase:"complete" before the final response. One bounded response returns compact task-relevant brain context, active TASK peers (idle connections hidden), one-time messages, structured exact-file conflicts, and automatic late-arrival overlap alerts. Portable across Codex/Antigravity and every MCP host; native hooks are optional.',
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  inputSchema: {
+    intent: z.string().max(160).optional().describe('One sentence describing the current task. Supply for start/checkpoint; completion clears it.'),
+    files: z.array(z.string()).max(20).optional().describe('Project-relative files you expect to touch or have touched. Exact overlaps with peers are flagged.'),
+    phase: z.enum(['start', 'checkpoint', 'complete']).optional().describe('start replaces prior task scope; checkpoint merges changed scope; complete clears task intent/files. Default: checkpoint.'),
+    include_context: z.boolean().optional().describe('Include fast task-relevant brain cards in the same response. Defaults true; ignored for phase complete.'),
+  },
+}, async ({ intent, files, phase, include_context }) => {
+  const totalStartedAt = Date.now();
+  const report = mcpPresence.sync({ intent, files, phase });
+  let taskContext = null;
+  if (phase !== 'complete' && include_context !== false && (intent || files?.length)) {
+    taskContext = await opBrainTaskContext({
+      vault: VAULT,
+      intent,
+      files,
+      k: 5,
+      budgetChars: 2800,
+    });
+  }
+  const contextText = taskContext?.blocks
+    ?.filter((block) => block.kind === 'text')
+    .map((block) => block.text)
+    .filter(Boolean)
+    .join('\n\n') || '';
+  const totalMs = Math.max(0, Date.now() - totalStartedAt);
+  const structuredContent = {
+    ...(report.structured || {
+      schemaVersion: 1,
+      status: 'idle',
+      phase: phase || 'checkpoint',
+    }),
+    context: taskContext?.context || {
+      mode: 'not-requested',
+      hits: [],
+      sufficient: false,
+      durationMs: 0,
+    },
+    timingMs: {
+      ...(report.structured?.timingMs || {}),
+      context: taskContext?.context?.durationMs || 0,
+      total: totalMs,
+    },
+  };
+  const timingText = `Context Gateway total: ${totalMs}ms`
+    + (taskContext?.context ? ` (memory ${taskContext.context.durationMs}ms)` : '') + '.';
+  return {
+    content: [{
+      type: 'text',
+      text: [report.text, contextText, timingText].filter(Boolean).join('\n\n'),
+    }],
+    structuredContent,
+  };
+});
+
 server.registerTool('brain_doctor', {
   title: 'Brain doctor — is this brain current, wired, and in sync?',
-  description: 'Read-only self-check of the installed klypix brain, as ONE verdict: VERSION (deployed brain-core + optional npm currency), CLAUDE (existing 4-hook capture readiness), CODEX (5-hook live-presence readiness), TOOLS (discoverable MCP verbs), SESSIONS (all active lifecycle sessions across hosts, never recent-chat history), and HARNESS (projection drift). Use to answer "is my brain current, correctly installed, in sync, and who is actually live?" without file-spelunking. Never writes. The MCP-callable twin of `npx klypix-mcp doctor`.',
+  description: 'Read-only self-check of the installed klypix brain, as ONE verdict: VERSION (deployed brain-core + optional npm currency), CLAUDE (existing 4-hook capture readiness), CODEX (automatic MCP presence plus optional enhanced-hook status), TOOLS (discoverable MCP verbs), SESSIONS (all active presence-adapter sessions across hosts, never recent-chat history), and HARNESS (projection drift). Use to answer "is my brain current, correctly installed, in sync, and who is actually live?" without file-spelunking. Never writes. The MCP-callable twin of `npx klypix-mcp doctor`.',
   inputSchema: {
     project: z.string().optional().describe('Project dir to audit harness + peers for. Defaults to the server\'s working directory.'),
     check_npm: z.boolean().optional().describe('Also fetch npm latest to flag a stale brain (default false — this one does a network `npm view`).'),
@@ -297,7 +366,7 @@ server.registerTool('brain_doctor', {
     // makes the RUNNING check report the caller's actual server version, never a
     // phantom another session's heartbeat wrote to the shared registry.
     const report = inspect({ projectDir: project ? path.resolve(project) : process.cwd(), npmLatest, self: { pid: process.pid, version: PKG_VERSION } });
-    return { content: [{ type: 'text', text: render(report, { color: false }) }] };
+    return mcpPresence.decorateToolResult({ content: [{ type: 'text', text: render(report, { color: false }) }] });
   } catch (e) {
     return { content: [{ type: 'text', text: `brain_doctor unavailable: ${e?.message || e}` }], isError: true };
   }
@@ -394,9 +463,14 @@ if (!canvasViewAsApp) {
 }
 
 const transport = new StdioServerTransport();
+server.server.oninitialized = () => {
+  mcpPresence.start(VAULT);
+  recordRunningServer();
+  log(`ready · vault=${VAULT} · presence=mcp`);
+};
+server.server.onclose = () => mcpPresence.stop();
+process.once('exit', () => mcpPresence.stop());
 await server.connect(transport);
-recordRunningServer();
-log(`ready · vault=${VAULT}`);
 // Pre-warm the on-device embedder in the BACKGROUND so the first cross-project
 // search of a session is already semantic, not a lexical fallback.
 getEmbedder(log).then(p => log(p ? 'semantic ready (pre-warmed)' : 'semantic unavailable — lexical only')).catch(() => {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.34.0",
+  "version": "1.37.0",
   "description": "Every project gets a brain — one open .klypix file your AI agents read, write, and argue from, over MCP. Works with Claude, Codex, Cursor, Cline, any model.",
   "type": "module",
   "license": "Apache-2.0",
@@ -39,7 +39,8 @@
     ".": "./index.mjs",
     "./format": "./src/klypix-format.mjs",
     "./core": "./src/klypix-core.mjs",
-    "./presence": "./src/agent-presence.mjs"
+    "./presence": "./src/agent-presence.mjs",
+    "./mcp-presence": "./src/mcp-presence.mjs"
   },
   "files": [
     "src",
@@ -54,7 +55,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs"
+    "test": "node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/context-gateway.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",