klypix-mcp 1.33.0 → 1.34.0

package/README.md

@@ -16,11 +16,12 @@ You've seen the setup: point an AI at a folder of notes, watch the graph fill up
 npx klypix-mcp install
 ```
 
-Claude Code gets live hooks for auto-brief + auto-capture. Codex gets a native
-`~/.codex/config.toml` MCP registration and conditional global guidance that activates
-only when a project contains `./brain.klypix`. Existing MCP servers, Codex settings, and
-personal instructions are preserved and backed up before KLYPIX-owned blocks change.
-Restart Codex after installation so it loads the new server.
+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.
 
 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*),
@@ -73,7 +74,7 @@ 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."*
 
-## The 16 verbs
+## The 17 verbs
 
 | Tool | What it does |
 |---|---|
@@ -83,7 +84,7 @@ Then ask your agent things like *"what did we decide about auth?"*, *"challenge
 | `brain_reconcile` | Find stale-vs-correction pairs + unrecorded migrations |
 | `brain_insights` | Hubs, orphaned decisions, stale questions, area sizes |
 | `brain_garden` | Maintenance pass over the brain |
-| `brain_doctor` | Self-diagnosis: version alignment, hooks wired, projection drift |
+| `brain_doctor` | Self-diagnosis: version, host adapters, active lifecycle sessions, projection drift |
 | `brain_message` | Session-to-session coordination notes |
 | `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 |
@@ -96,7 +97,19 @@ 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 live hooks and Codex's native MCP + conditional global guidance; `link` projects the repository-level MCP and instruction files used by Codex and the other coding agents. Full transcript-driven auto-capture remains a Claude Code hook capability; Codex and other hookless clients capture durable decisions through the MCP instructions and `brain_note`.
+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.
+
+### 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.
+
+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.
 
 ### Updates — the propagation contract
 

package/bin/klypix-doctor.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 // klypix-doctor — `npx klypix-mcp doctor`. The brain's self-check: is THIS machine's
-// brain current, are the 4 Claude Code hooks wired, what verbs does it expose, who else
-// is live on this project's brain, and is the harness projection in sync? ONE fact, ONE
-// reconcile block. Read-only (never writes). Exits 0 = ALIGNED, 1 = DRIFTED — so it
+// brain current, are the Claude capture and Codex presence adapters wired, what verbs
+// does it expose, which lifecycle sessions are live, and is the harness projection in
+// sync? ONE fact, ONE reconcile block. Read-only (never writes). Exits 0 = ALIGNED,
+// 1 = DRIFTED — so it
 // doubles as a pre-commit / CI readiness gate.
 //
 //   npx klypix-mcp doctor              # this project + this machine's brain

package/bin/klypix-install.mjs

@@ -21,6 +21,7 @@ import {
     mcpServerEntry,
     mergeCodexGlobalInstructions,
 } from '../src/agent-rules.mjs';
+import { mergeCodexPresenceHooks } from '../src/codex-hooks.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -45,25 +46,36 @@ function copyDir(src, dest) {
     }
 }
 
-// Codex has two independent integration layers: MCP gives it the brain tools,
-// while a conditional managed block in ~/.codex/AGENTS.md tells every session
-// to use those tools when ./brain.klypix exists.
+// 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.
 function wireCodex() {
     const mcp = connectCodexMcpServer({
         configPath: CODEX_CONFIG,
         entry: mcpServerEntry({ vault: '.', home: HOME }),
     });
     const instructions = mergeCodexGlobalInstructions(HOME);
-    return { mcp, instructions, ok: mcp.ok && instructions.ok };
+    const hookScript = path.join(BRAIN_DIR, 'codex-brain-hook.mjs');
+    const presence = 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 };
 }
 
 function reportCodex(result) {
     if (result.ok) {
-        console.log(`✓ wired Codex: MCP tools (${result.mcp.action}) + conditional project-brain guidance (${result.instructions.action})`);
+        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}`);
         return;
     }
     if (!result.mcp.ok) console.error(`⚠ Codex MCP was not changed: ${result.mcp.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}`);
     console.error('  Claude Code installation is intact. Fix the Codex warning, then re-run this command.');
 }
 
@@ -199,7 +211,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', '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', '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']]) {
@@ -253,7 +265,7 @@ try {
     //    (heals an existing stale config so the next MCP server spawn runs current).
     const migrated = migrateProjectMcpConfig();
 
-    // Codex needs both native MCP tools and conditional global guidance.
+    // Codex needs native MCP tools, conditional guidance, and lifecycle presence.
     const codex = wireCodex();
 
     // 8) READINESS check — re-read what we just wrote and confirm all 4 hooks actually
@@ -270,7 +282,7 @@ 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 auto-briefs + captures through hooks; Codex reads + writes through native MCP and managed guidance.');
+    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('  ⚠ 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-mcp.mjs

@@ -265,7 +265,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 live 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 HOOK-WIRED sessions (Claude Code with the brain hooks) — each sees the note once at its next prompt. A hookless peer (plain Cursor/Cline session) will NOT receive it, so don\'t rely on this to warn one. 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 (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.',
   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.'),
@@ -278,7 +278,7 @@ server.registerTool('brain_message', {
 
 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 (the deployed brain-core version + optional npm-latest currency), HOOKS (are all 4 Claude Code hooks wired — liveness vs readiness), TOOLS (the discoverable MCP verb manifest), PEERS (other live sessions on this project\'s brain right now), and HARNESS (per-file projection drift: ok/stale/hand-edited/missing). Use to answer "is my brain current + correctly installed + in sync, and who else is 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 (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`.',
   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`).'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.33.0",
+  "version": "1.34.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",
@@ -38,7 +38,8 @@
   "exports": {
     ".": "./index.mjs",
     "./format": "./src/klypix-format.mjs",
-    "./core": "./src/klypix-core.mjs"
+    "./core": "./src/klypix-core.mjs",
+    "./presence": "./src/agent-presence.mjs"
   },
   "files": [
     "src",
@@ -53,7 +54,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "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/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",

package/src/agent-presence.mjs

@@ -0,0 +1,297 @@
+// Agent-neutral live-session registry.
+//
+// Every host adapter writes the same per-brain lane used by Claude Code's
+// existing global-brain-hook. The schema is deliberately additive: old Claude
+// entries remain valid, while newer adapters can identify their client, model,
+// surface, current intent, and touched files.
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+export const SESSION_FRESH_MS = 10 * 60 * 1000;
+export const MESSAGE_FRESH_MS = 24 * 60 * 60 * 1000;
+
+const sha16 = (value) => crypto.createHash('sha1').update(String(value)).digest('hex').slice(0, 16);
+const normBrainPath = (value) => String(value).replace(/\\/g, '/').replace(/^[a-zA-Z]:/, (m) => m.toLowerCase());
+const canonicalPath = (value) => {
+  try { return fs.realpathSync.native(value); }
+  catch { return path.resolve(value); }
+};
+const sleepSync = (ms) => {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+  catch { /* best effort */ }
+};
+
+export function findProjectBrain(cwd = process.cwd()) {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    for (const name of ['brain.klypix', 'brain.any']) {
+      const candidate = path.join(dir, name);
+      try { if (fs.statSync(candidate).isFile()) return candidate; }
+      catch { /* keep walking */ }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function laneFileFor(brainPath, home = os.homedir()) {
+  const key = sha16(normBrainPath(canonicalPath(brainPath)));
+  return path.join(home, '.claude', 'project-brain', 'sessions', `${key}.json`);
+}
+
+function readLane(file) {
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return data && typeof data === 'object' ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+function acquireLock(lockFile, { tries = 30, waitMs = 20, staleMs = 30_000 } = {}) {
+  try { fs.mkdirSync(path.dirname(lockFile), { recursive: true }); }
+  catch { /* write below will report failure */ }
+  for (let i = 0; i < tries; i++) {
+    try {
+      const fd = fs.openSync(lockFile, 'wx');
+      fs.writeSync(fd, String(process.pid));
+      fs.closeSync(fd);
+      return true;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') return false;
+      try {
+        if (Date.now() - fs.statSync(lockFile).mtimeMs > staleMs) {
+          fs.unlinkSync(lockFile);
+          continue;
+        }
+      } catch { /* raced with the lock owner */ }
+      sleepSync(waitMs);
+    }
+  }
+  return false;
+}
+
+function releaseLock(lockFile) {
+  try { fs.unlinkSync(lockFile); }
+  catch { /* best effort */ }
+}
+
+function pruneSessions(sessions, now) {
+  return (Array.isArray(sessions) ? sessions : [])
+    .filter((session) => session?.id && now - Number(session.lastSeen || 0) < SESSION_FRESH_MS);
+}
+
+function pruneMessages(messages, now) {
+  return (Array.isArray(messages) ? messages : [])
+    .filter((message) => message?.id && now - Number(message.ts || 0) < MESSAGE_FRESH_MS);
+}
+
+function normalizeFiles(files) {
+  const seen = new Set();
+  const out = [];
+  for (const file of Array.isArray(files) ? files : []) {
+    const value = String(file || '').replace(/\\/g, '/').trim();
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+    out.push(value);
+  }
+  return out.slice(-20);
+}
+
+export function listActiveSessions({ brainPath, home, now = Date.now() }) {
+  if (!brainPath) return [];
+  const lane = readLane(laneFileFor(brainPath, home));
+  return pruneSessions(lane.sessions, now).sort((a, b) => Number(b.lastSeen || 0) - Number(a.lastSeen || 0));
+}
+
+export function upsertSession({
+  brainPath,
+  id,
+  client = 'unknown',
+  surface = null,
+  model = null,
+  permissionMode = null,
+  branch = null,
+  intent,
+  files,
+  event = null,
+  cwd = null,
+  home,
+  now = Date.now(),
+}) {
+  if (!brainPath || !id) return [];
+  const laneFile = laneFileFor(brainPath, home);
+  const lockFile = laneFile + '.lock';
+  const gotLock = acquireLock(lockFile);
+  if (!gotLock) return listActiveSessions({ brainPath, home, now });
+  try {
+    const data = readLane(laneFile);
+    const sessions = pruneSessions(data.sessions, now);
+    const previous = sessions.find((session) => session.id === id) || {};
+    const mergedFiles = files === undefined
+      ? normalizeFiles(previous.files)
+      : normalizeFiles([...(previous.files || []), ...(files || [])]);
+    const next = {
+      ...previous,
+      id: String(id),
+      pid: process.pid,
+      project: path.basename(path.dirname(brainPath)),
+      client: String(client || previous.client || 'unknown'),
+      surface: surface ?? previous.surface ?? null,
+      model: model ?? previous.model ?? null,
+      permissionMode: permissionMode ?? previous.permissionMode ?? null,
+      branch: branch ?? previous.branch ?? null,
+      intent: intent !== undefined ? String(intent || '').replace(/\s+/g, ' ').trim().slice(0, 160) : (previous.intent || ''),
+      files: mergedFiles,
+      event: event ?? previous.event ?? null,
+      cwd: cwd ? path.resolve(cwd) : (previous.cwd || path.dirname(brainPath)),
+      startedAt: previous.startedAt || now,
+      lastSeen: now,
+    };
+    const kept = sessions.filter((session) => session.id !== id);
+    kept.push(next);
+    fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+    fs.writeFileSync(laneFile, JSON.stringify({
+      ...data,
+      sessions: kept.slice(-40),
+      messages: pruneMessages(data.messages, now).slice(-30),
+    }));
+    return kept.sort((a, b) => Number(b.lastSeen || 0) - Number(a.lastSeen || 0));
+  } finally {
+    if (gotLock) releaseLock(lockFile);
+  }
+}
+
+export function removeSession({ brainPath, id, home, now = Date.now() }) {
+  if (!brainPath || !id) return [];
+  const laneFile = laneFileFor(brainPath, home);
+  const lockFile = laneFile + '.lock';
+  const gotLock = acquireLock(lockFile);
+  if (!gotLock) return listActiveSessions({ brainPath, home, now });
+  try {
+    const data = readLane(laneFile);
+    const sessions = pruneSessions(data.sessions, now).filter((session) => session.id !== id);
+    fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+    fs.writeFileSync(laneFile, JSON.stringify({
+      ...data,
+      sessions,
+      messages: pruneMessages(data.messages, now).slice(-30),
+    }));
+    return sessions;
+  } finally {
+    if (gotLock) releaseLock(lockFile);
+  }
+}
+
+function messageTargetsSession(message, session, sessionId) {
+  const target = String(message?.to || '').trim().toLowerCase();
+  if (!target || target === 'all' || target === '*') return true;
+  const searchable = [
+    String(sessionId || '').slice(0, 8),
+    session?.branch,
+    session?.intent,
+    session?.client,
+    session?.surface,
+  ].filter(Boolean).join(' ').toLowerCase();
+  return searchable.includes(target);
+}
+
+export function receiveMessages({
+  brainPath,
+  sessionId,
+  ignoreTexts = [],
+  home,
+  now = Date.now(),
+}) {
+  if (!brainPath || !sessionId) return [];
+  const laneFile = laneFileFor(brainPath, home);
+  const lockFile = laneFile + '.lock';
+  const gotLock = acquireLock(lockFile);
+  if (!gotLock) return [];
+  try {
+    const data = readLane(laneFile);
+    const sessions = pruneSessions(data.sessions, now);
+    const messages = pruneMessages(data.messages, now);
+    const me = sessions.find((session) => session.id === sessionId);
+    const unseen = messages.filter((message) =>
+      message.from !== sessionId
+      && !(Array.isArray(message.seen) && message.seen.includes(sessionId))
+      && messageTargetsSession(message, me, sessionId));
+    if (!unseen.length) return [];
+
+    const unseenIds = new Set(unseen.map((message) => message.id));
+    for (const message of messages) {
+      if (!unseenIds.has(message.id)) continue;
+      if (!Array.isArray(message.seen)) message.seen = [];
+      if (!message.seen.includes(sessionId)) message.seen.push(sessionId);
+    }
+    fs.writeFileSync(laneFile, JSON.stringify({ ...data, sessions, messages }));
+
+    const ignored = new Set(ignoreTexts.map((text) => String(text || '').replace(/\s+/g, ' ').trim().toLowerCase()));
+    const shown = [];
+    const seenText = new Set();
+    for (const message of unseen) {
+      const key = String(message.text || '').replace(/\s+/g, ' ').trim().toLowerCase();
+      if (!key || ignored.has(key) || seenText.has(key)) continue;
+      seenText.add(key);
+      shown.push(message);
+    }
+    return shown.slice(0, 6);
+  } finally {
+    if (gotLock) releaseLock(lockFile);
+  }
+}
+
+const clientLabel = (session) => {
+  const client = String(session?.client || '').toLowerCase();
+  if (!client) return 'Claude Code';
+  if (client === 'codex') return 'Codex';
+  if (client === 'claude-code' || client === 'claude') return 'Claude Code';
+  return client.replace(/(^|[-_ ])([a-z])/g, (_m, prefix, letter) => `${prefix}${letter.toUpperCase()}`);
+};
+
+export function formatPresenceMessage(sessions, selfId, { includeSolo = false, now = Date.now() } = {}) {
+  const active = Array.isArray(sessions) ? sessions : [];
+  const others = active.filter((session) => session.id !== selfId);
+  if (!includeSolo && !others.length) return '';
+
+  const counts = new Map();
+  for (const session of active) {
+    const label = clientLabel(session);
+    counts.set(label, (counts.get(label) || 0) + 1);
+  }
+  const mix = [...counts.entries()].map(([label, count]) => `${label} ${count}`).join(', ');
+  const lines = [
+    `KLYPIX session awareness: ${active.length} active session${active.length === 1 ? '' : 's'} on this project (${mix || 'none'}); ${others.length} other${others.length === 1 ? '' : 's'} besides this chat.`,
+  ];
+  if (!others.length) {
+    lines.push('Saved/recent chat rows are history, not active sessions; a session counts only while its lifecycle hook has heartbeated in the last 10 minutes.');
+    return lines.join('\n');
+  }
+  lines.push('Other active sessions:');
+  for (const session of others.slice(0, 8)) {
+    const ageMin = Math.max(0, Math.round((now - Number(session.lastSeen || now)) / 60_000));
+    const details = [
+      clientLabel(session),
+      session.branch ? `branch ${session.branch}` : null,
+      session.intent ? `"${String(session.intent).slice(0, 90)}"` : null,
+      `${ageMin}m ago`,
+    ].filter(Boolean);
+    lines.push(`- ${String(session.id).slice(0, 8)}: ${details.join(' | ')}`);
+  }
+  lines.push('Coordinate before touching shared files; use brain_message for a targeted note.');
+  return lines.join('\n');
+}
+
+export function formatReceivedMessages(messages, now = Date.now()) {
+  if (!Array.isArray(messages) || !messages.length) return '';
+  const lines = ['KLYPIX message(s) from another active session:'];
+  for (const message of messages) {
+    const ageMin = Math.max(0, Math.round((now - Number(message.ts || now)) / 60_000));
+    lines.push(`- from ${String(message.from || '?').slice(0, 12)} (${ageMin}m ago): ${String(message.text || '').replace(/\s+/g, ' ').trim().slice(0, 400)}`);
+  }
+  return lines.join('\n');
+}

package/src/agent-rules.mjs

@@ -64,6 +64,7 @@ const CODEX_GLOBAL_BODY = [
   'When the current project contains `./brain.klypix`, treat it as the authoritative shared project memory.',
   'At task start, read `.claude/brain-brief.md` when present; otherwise use the `klypix-canvas`',
   'MCP tools (`brain_ask`, `read_canvas` with canvas `"brain"`, or `brain_insights`).',
+  'Use `brain_doctor` when live-session awareness matters; recent chat rows are history, not presence.',
   'Capture durable decisions and milestones with `brain_note`. Never hand-edit `brain.klypix`.',
   'If the project has no `brain.klypix`, ignore this section.',
   CODEX_GLOBAL_END,
@@ -400,10 +401,11 @@ project decision live *only* in your host's memory or a scratch file — put it
 session/agent has it.
 
 **Working alongside other live sessions?** Send a one-time coordination note with the
-\`brain_message\` MCP tool ("merged the hook refactor — rebase before you commit"); hook-wired peer
-sessions (Claude Code) see it at their next prompt. Any client can SEND; only hook-wired sessions
-receive, so don't rely on it to reach a hookless peer. Notes are ephemeral (24h), NOT brain cards —
-durable decisions still go through \`brain_note\`.
+\`brain_message\` MCP tool ("merged the hook refactor — rebase before you commit"). Sessions with
+a KLYPIX presence adapter (Claude Code and Codex; more hosts can implement the same protocol) see it
+once through their lifecycle hooks. Hookless clients can send but cannot receive. Use
+\`brain_doctor\` for the all-host active-session count; saved/recent chats are history, not presence.
+Notes are ephemeral (24h), NOT brain cards — durable decisions still go through \`brain_note\`.
 
 **Don't** hand-edit \`brain.klypix\` (it's a packaged canvas — use the tools) or dump file contents into it; capture the *decision*, not the file.`;
 

package/src/brain-doctor.mjs

@@ -10,12 +10,11 @@
 //                 klypix-mcp-server.mjs) is the source of truth, because the install
 //                 stamp's version key is channel-dependent (npm writes `brainVersion`,
 //                 the desktop app writes `appVersion`). + the deploy `dirty` flag.
-//   • HOOKS     — are all 4 Claude Code hooks actually wired (HOOK_MARK present)?
-//                 SessionStart firing proves liveness; the other 3 prove readiness.
+//   • CLAUDE    — are all 4 existing Claude Code hooks wired (HOOK_MARK present)?
+//   • CODEX     — are all 5 Codex presence lifecycle hooks wired?
 //   • TOOLS     — the discoverable MCP verb manifest (what the installed server
 //                 REALLY registers) so a caller can't assume a phantom tool.
-//   • PEERS     — live sessions on this project's brain (the alignment seam), so
-//                 "who else is editing right now?" is answerable, not just footer-passive.
+//   • SESSIONS  — all live lifecycle sessions on this project's brain, by host.
 //   • HARNESS   — per-file projection drift (ok/stale/hand-edited/missing) via the
 //                 versioned fence in agent-rules.
 //
@@ -27,6 +26,7 @@ import path from 'path';
 import crypto from 'crypto';
 import { fileURLToPath } from 'url';
 import { auditProject, resolveVersion } from './agent-rules.mjs';
+import { codexPresenceHookStatus } from './codex-hooks.mjs';
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -156,7 +156,16 @@ function inspectPeers(brainDir, brainPath, now) {
   const data = readJson(file, null);
   const sessions = Array.isArray(data?.sessions) ? data.sessions : [];
   const live = sessions.filter(s => s && now - (s.lastSeen || 0) < SESSION_FRESH_MS)
-    .map(s => ({ id: String(s.id || '').slice(0, 8), branch: s.branch || null, intent: s.intent || '', files: Array.isArray(s.files) ? s.files : [], lastSeenMin: Math.round((now - (s.lastSeen || 0)) / 60000) }));
+    .map(s => ({
+      id: String(s.id || '').slice(0, 8),
+      client: s.client || 'claude-code',
+      surface: s.surface || null,
+      model: s.model || null,
+      branch: s.branch || null,
+      intent: s.intent || '',
+      files: Array.isArray(s.files) ? s.files : [],
+      lastSeenMin: Math.round((now - (s.lastSeen || 0)) / 60000),
+    }));
   return { file, live, count: live.length };
 }
 
@@ -169,12 +178,15 @@ export function inspect(opts = {}) {
   const projectDir = opts.projectDir || process.cwd();
   const now = opts.now || Date.now();
   const brainDir = path.join(home, '.claude', 'project-brain');
-  const brainPath = path.join(projectDir, 'brain.klypix');
-  const hasBrain = fs.existsSync(brainPath) || fs.existsSync(path.join(projectDir, 'brain.any'));
+  const klypixBrain = path.join(projectDir, 'brain.klypix');
+  const anyBrain = path.join(projectDir, 'brain.any');
+  const brainPath = fs.existsSync(klypixBrain) ? klypixBrain : anyBrain;
+  const hasBrain = fs.existsSync(brainPath);
 
   const version = inspectVersion(brainDir);
   const running = inspectRunning(brainDir, version.baked, now, opts.self);
   const hooks = inspectHooks(home);
+  const codexHooks = codexPresenceHookStatus(home);
   const tools = inspectTools(brainDir, PKG_ROOT);
   const peers = inspectPeers(brainDir, brainPath, now);
 
@@ -196,6 +208,7 @@ export function inspect(opts = {}) {
     // is NOT drift; it's a reconnect prompt.
     running: !running.known ? 'unknown' : (running.matchesInstalled === false ? 'drift' : 'ok'),
     hooks: !hooks.settingsPresent ? 'absent' : (hooks.missing.length ? 'drift' : 'ok'),
+    codexHooks: codexHooks.installed ? 'ok' : 'drift',
     harness: hasBrain ? (harness.ok ? 'ok' : 'drift') : 'n/a',
   };
   const drifted = Object.values(layers).filter(s => s === 'drift').length;
@@ -209,10 +222,11 @@ export function inspect(opts = {}) {
     if (npm && npm.matches === false) actions.push(`npx klypix-mcp install   # installed brain v${version.baked} < npm latest v${npm.latest}`);
     if (running.matchesInstalled === false) actions.push(`/mcp reconnect (or restart the session)   # LIVE server v${running.version} ≠ installed v${version.baked} — the running MCP server is stale`);
     if (hooks.missing.length) actions.push(`npx klypix-mcp install   # half-wired: hooks not active — ${hooks.missing.join(', ')}`);
+    if (!codexHooks.installed) actions.push(`npx klypix-mcp install   # Codex live presence hooks missing: ${codexHooks.missing.join(', ')}`);
     if (hasBrain && !harness.ok) actions.push('npx klypix-mcp link      # harness configs drifted — re-project managed blocks');
   }
 
-  return { verdict, layers, drifted, version, running, hooks, tools, peers, harness, npm, project: { dir: projectDir, brainPath, hasBrain }, brainDir, actions };
+  return { verdict, layers, drifted, version, running, hooks, codexHooks, tools, peers, sessions: peers, harness, npm, project: { dir: projectDir, brainPath, hasBrain }, brainDir, actions };
 }
 
 // One-line drift summary (empty when clean) — for a footer / status line.
@@ -224,6 +238,7 @@ export function driftLine(r) {
   if (r.npm && r.npm.matches === false) bits.push(`v${r.version.baked}<${r.npm.latest}`);
   if (r.running && r.running.matchesInstalled === false) bits.push(`live server v${r.running.version}≠installed v${r.version.baked} (/mcp reconnect)`);
   if (r.hooks.missing.length) bits.push(`${r.hooks.missing.length} hook(s) unwired`);
+  if (!r.codexHooks.installed) bits.push(`${r.codexHooks.missing.length} Codex presence hook(s) unwired`);
   if (r.project.hasBrain && !r.harness.ok) bits.push(`${r.harness.drift.length} harness file(s) drifted`);
   return bits.length ? `⚠️ brain DRIFTED: ${bits.join(' · ')}` : '';
 }
@@ -259,20 +274,24 @@ export function render(r, opts = {}) {
     for (const s of extra) L.push(`        ${c.dim}· ${run.self ? 'other' : 'server'} pid ${s.pid ?? '?'} · v${s.version}${s.vault ? ' · ' + s.vault : ''}${s.ageMin != null ? ` (booted ${s.ageMin}m ago)` : ''}${c.rst}`);
   }
 
-  // HOOKS
+  // Host adapters
   const hmark = r.layers.hooks === 'ok' ? ok : warn;
-  if (!r.hooks.settingsPresent) L.push(`${hmark} ${c.bold}HOOKS${c.rst}    no ~/.claude/settings.json found`);
-  else if (r.hooks.missing.length) L.push(`${hmark} ${c.bold}HOOKS${c.rst}    half-wired — missing: ${c.yel}${r.hooks.missing.join(', ')}${c.rst}  ${c.dim}(liveness up, readiness no)${c.rst}`);
-  else L.push(`${hmark} ${c.bold}HOOKS${c.rst}    all 4 wired: ${r.hooks.wired.join(', ')}`);
+  if (!r.hooks.settingsPresent) L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   no ~/.claude/settings.json found`);
+  else if (r.hooks.missing.length) L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   half-wired — missing: ${c.yel}${r.hooks.missing.join(', ')}${c.rst}  ${c.dim}(liveness up, readiness no)${c.rst}`);
+  else L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   existing 4-hook capture path intact: ${r.hooks.wired.join(', ')}`);
+  const chmark = r.layers.codexHooks === 'ok' ? ok : warn;
+  if (r.codexHooks.error) L.push(`${chmark} ${c.bold}CODEX${c.rst}    ${c.yel}${r.codexHooks.error}${c.rst}`);
+  else if (!r.codexHooks.installed) L.push(`${chmark} ${c.bold}CODEX${c.rst}    live presence missing: ${c.yel}${r.codexHooks.missing.join(', ')}${c.rst}`);
+  else L.push(`${chmark} ${c.bold}CODEX${c.rst}    all 5 live-presence hooks wired: ${r.codexHooks.wired.join(', ')}`);
 
   // TOOLS
   L.push(`${ok} ${c.bold}TOOLS${c.rst}    ${r.tools.count} MCP verb(s)${r.tools.hash ? ` ${c.dim}[#${r.tools.hash}, ${r.tools.source}]${c.rst}` : ''}${r.tools.count ? `: ${c.dim}${r.tools.names.join(', ')}${c.rst}` : ''}`);
 
-  // PEERS
-  if (!r.peers.count) L.push(`${ok} ${c.bold}PEERS${c.rst}    solo — no other live session ${c.dim}(the brain is shared, NOT live-merged)${c.rst}`);
+  // SESSIONS: this is an all-session count. A recent-chat row is not a heartbeat.
+  if (!r.sessions.count) L.push(`${ok} ${c.bold}SESSIONS${c.rst}  0 active lifecycle sessions ${c.dim}(saved/recent chats are history, not active)${c.rst}`);
   else {
-    L.push(`${warn}${c.bold}PEERS${c.rst}    ${r.peers.count} live ${c.dim}(shared, NOT live-merged — coordinate before committing)${c.rst}`);
-    for (const p of r.peers.live) L.push(`        · ${p.id}${p.branch ? ' @' + p.branch : ''}${p.intent ? ` “${p.intent.slice(0, 50)}”` : ''} ${c.dim}(${p.lastSeenMin}m ago)${c.rst}`);
+    L.push(`${r.sessions.count > 1 ? warn : ok} ${c.bold}SESSIONS${c.rst}  ${r.sessions.count} active lifecycle session${r.sessions.count === 1 ? '' : 's'} ${c.dim}(all hosts; 10-minute crash TTL)${c.rst}`);
+    for (const p of r.sessions.live) L.push(`        · ${p.client}:${p.id}${p.branch ? ' @' + p.branch : ''}${p.intent ? ` “${p.intent.slice(0, 50)}”` : ''} ${c.dim}(${p.lastSeenMin}m ago)${c.rst}`);
   }
 
   // HARNESS

package/src/codex-brain-hook.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// Codex lifecycle adapter for the agent-neutral KLYPIX presence lane.
+// It never reads Codex's unstable transcript format and never modifies the brain.
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import {
+  findProjectBrain,
+  formatPresenceMessage,
+  formatReceivedMessages,
+  receiveMessages,
+  removeSession,
+  upsertSession,
+} from './agent-presence.mjs';
+
+function readInput() {
+  try {
+    if (process.stdin.isTTY) return {};
+    const raw = fs.readFileSync(0, 'utf8');
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function gitBranch(cwd) {
+  try {
+    const branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1200,
+    }).trim();
+    return branch && branch !== 'HEAD' ? branch : null;
+  } catch {
+    return null;
+  }
+}
+
+function toolName(input) {
+  return String(input.tool_name || input.toolName || input.tool?.name || '');
+}
+
+function toolInput(input) {
+  const candidate = input.tool_input || input.toolInput || input.tool?.input;
+  return candidate && typeof candidate === 'object' ? candidate : {};
+}
+
+function projectRelative(file, projectDir) {
+  if (!file) return null;
+  const absolute = path.isAbsolute(file) ? path.normalize(file) : path.resolve(projectDir, file);
+  const relative = path.relative(projectDir, absolute).replace(/\\/g, '/');
+  if (!relative || relative === '.' || relative === '..' || relative.startsWith('../')) return null;
+  return relative;
+}
+
+function touchedFiles(input, projectDir) {
+  const name = toolName(input);
+  const args = toolInput(input);
+  const candidates = [];
+  for (const key of ['path', 'file_path', 'filePath', 'target_file', 'targetFile']) {
+    if (typeof args[key] === 'string') candidates.push(args[key]);
+  }
+  const patch = [args.patch, args.input, args.content]
+    .find((value) => typeof value === 'string' && value.includes('*** '));
+  if (patch && /apply_patch|Edit|Write/i.test(name)) {
+    for (const match of patch.matchAll(/^\*\*\* (?:Add|Update|Delete) File:\s*(.+)$/gm)) {
+      candidates.push(match[1].trim());
+    }
+  }
+  return [...new Set(candidates.map((file) => projectRelative(file, projectDir)).filter(Boolean))];
+}
+
+function ownBrainMessageText(input) {
+  if (!/brain_message$/i.test(toolName(input))) return [];
+  const text = toolInput(input).text;
+  return typeof text === 'string' && text.trim() ? [text] : [];
+}
+
+function emitSystemMessage(parts) {
+  const systemMessage = parts.filter(Boolean).join('\n\n').trim();
+  if (!systemMessage) return;
+  process.stdout.write(JSON.stringify({ continue: true, systemMessage }));
+}
+
+async function main() {
+  const input = readInput();
+  const event = String(input.hook_event_name || input.hookEventName || '');
+  const sessionId = String(input.session_id || input.sessionId || '');
+  const cwd = path.resolve(input.cwd || process.cwd());
+  const brainPath = findProjectBrain(cwd);
+  if (!event || !sessionId || !brainPath) return;
+
+  if (event === 'SessionEnd') {
+    removeSession({ brainPath, id: sessionId });
+    return;
+  }
+
+  const projectDir = path.dirname(brainPath);
+  const prompt = input.prompt || input.user_prompt || input.userPrompt;
+  const files = event === 'PostToolUse' ? touchedFiles(input, projectDir) : undefined;
+  const sessions = upsertSession({
+    brainPath,
+    id: sessionId,
+    client: 'codex',
+    surface: input.surface || 'local',
+    model: input.model || null,
+    permissionMode: input.permission_mode || input.permissionMode || null,
+    branch: gitBranch(cwd),
+    intent: prompt === undefined ? undefined : prompt,
+    files,
+    event,
+    cwd,
+  });
+
+  const ignored = event === 'PostToolUse' ? ownBrainMessageText(input) : [];
+  const messages = receiveMessages({ brainPath, sessionId, ignoreTexts: ignored });
+  if (event === 'SessionStart') {
+    emitSystemMessage([
+      formatPresenceMessage(sessions, sessionId, { includeSolo: true }),
+      formatReceivedMessages(messages),
+    ]);
+    return;
+  }
+  if (event === 'UserPromptSubmit') {
+    emitSystemMessage([
+      formatPresenceMessage(sessions, sessionId),
+      formatReceivedMessages(messages),
+    ]);
+    return;
+  }
+  if (messages.length) emitSystemMessage([formatReceivedMessages(messages)]);
+}
+
+main().catch(() => {}).finally(() => process.exit(0));

package/src/codex-hooks.mjs

@@ -0,0 +1,142 @@
+// Safe ownership-scoped merger for ~/.codex/hooks.json.
+//
+// KLYPIX owns only command handlers that launch codex-brain-hook.mjs. Existing
+// hooks, top-level settings, ordering, and unrelated event groups are preserved.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+export const CODEX_PRESENCE_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'Stop',
+  'PostToolUse',
+  'SessionEnd',
+];
+
+const HOOK_MARK = 'codex-brain-hook.mjs';
+
+export function resolveCodexHooksPath(home = os.homedir()) {
+  return path.join(home, '.codex', 'hooks.json');
+}
+
+export function codexPresenceGroups(command) {
+  const handler = (timeout = 5) => ({ type: 'command', command, timeout });
+  return {
+    SessionStart: [{ hooks: [handler()] }],
+    UserPromptSubmit: [{ hooks: [handler()] }],
+    Stop: [{ hooks: [handler()] }],
+    PostToolUse: [{ hooks: [handler()] }],
+    SessionEnd: [{ hooks: [handler(3)] }],
+  };
+}
+
+function readHooks(file) {
+  if (!fs.existsSync(file)) return { ok: true, raw: '', data: {} };
+  let raw = '';
+  try { raw = fs.readFileSync(file, 'utf8'); }
+  catch (error) { return { ok: false, raw: '', data: null, error: `Can't read ${file}: ${error?.message || error}` }; }
+  if (!raw.trim()) return { ok: true, raw, data: {} };
+  try {
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('root must be an object');
+    return { ok: true, raw, data };
+  } catch (error) {
+    return { ok: false, raw, data: null, error: `${path.basename(file)} is invalid JSON (${error?.message || error}). KLYPIX left it untouched.` };
+  }
+}
+
+function stripOwned(groups) {
+  return (Array.isArray(groups) ? groups : [])
+    .map((group) => {
+      if (!group || !Array.isArray(group.hooks)) return group;
+      return {
+        ...group,
+        hooks: group.hooks.filter((hook) => !(typeof hook?.command === 'string' && hook.command.includes(HOOK_MARK))),
+      };
+    })
+    .filter((group) => !group || !Array.isArray(group.hooks) || group.hooks.length > 0);
+}
+
+function writeHooks(file, raw, data) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    let backup;
+    if (raw) {
+      backup = file + '.klypix-bak';
+      try { fs.writeFileSync(backup, raw, 'utf8'); }
+      catch { backup = undefined; }
+    }
+    const temp = file + '.klypix-tmp';
+    fs.writeFileSync(temp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    JSON.parse(fs.readFileSync(temp, 'utf8'));
+    fs.renameSync(temp, file);
+    return { ok: true, backup };
+  } catch (error) {
+    return { ok: false, error: `Couldn't write ${file}: ${error?.message || error}` };
+  }
+}
+
+export function codexPresenceHookStatus(home = os.homedir()) {
+  const file = resolveCodexHooksPath(home);
+  const parsed = readHooks(file);
+  if (!parsed.ok) return { installed: false, file, error: parsed.error, wired: [], missing: CODEX_PRESENCE_EVENTS.slice() };
+  const hooks = parsed.data?.hooks && typeof parsed.data.hooks === 'object' && !Array.isArray(parsed.data.hooks)
+    ? parsed.data.hooks
+    : {};
+  const wired = CODEX_PRESENCE_EVENTS.filter((event) =>
+    Array.isArray(hooks[event])
+    && hooks[event].some((group) => Array.isArray(group?.hooks)
+      && group.hooks.some((hook) => typeof hook?.command === 'string' && hook.command.includes(HOOK_MARK))));
+  return {
+    installed: wired.length === CODEX_PRESENCE_EVENTS.length,
+    file,
+    error: null,
+    wired,
+    missing: CODEX_PRESENCE_EVENTS.filter((event) => !wired.includes(event)),
+  };
+}
+
+export function mergeCodexPresenceHooks({ home = os.homedir(), command } = {}) {
+  if (!command || !String(command).includes(HOOK_MARK)) {
+    return { ok: false, error: `Codex presence hook command must launch ${HOOK_MARK}.` };
+  }
+  const file = resolveCodexHooksPath(home);
+  const parsed = readHooks(file);
+  if (!parsed.ok) return { ok: false, error: parsed.error, path: file };
+  const data = structuredClone(parsed.data || {});
+  if (!data.hooks || typeof data.hooks !== 'object' || Array.isArray(data.hooks)) data.hooks = {};
+  const groups = codexPresenceGroups(String(command));
+  for (const event of CODEX_PRESENCE_EVENTS) {
+    data.hooks[event] = [...stripOwned(data.hooks[event]), ...groups[event]];
+  }
+  const next = JSON.stringify(data, null, 2) + '\n';
+  if (next === parsed.raw) return { ok: true, action: 'unchanged', path: file };
+  const written = writeHooks(file, parsed.raw, data);
+  if (!written.ok) return { ...written, path: file };
+  return { ok: true, action: parsed.raw ? 'updated' : 'connected', path: file, backup: written.backup };
+}
+
+export function removeCodexPresenceHooks(home = os.homedir()) {
+  const file = resolveCodexHooksPath(home);
+  const parsed = readHooks(file);
+  if (!parsed.ok) return { ok: false, error: parsed.error, path: file };
+  if (!parsed.raw) return { ok: true, action: 'unchanged', path: file };
+  const data = structuredClone(parsed.data || {});
+  if (!data.hooks || typeof data.hooks !== 'object' || Array.isArray(data.hooks)) {
+    return { ok: true, action: 'unchanged', path: file };
+  }
+  let changed = false;
+  for (const event of CODEX_PRESENCE_EVENTS) {
+    const before = Array.isArray(data.hooks[event]) ? data.hooks[event] : [];
+    const after = stripOwned(before);
+    if (JSON.stringify(after) !== JSON.stringify(before)) changed = true;
+    if (after.length) data.hooks[event] = after;
+    else delete data.hooks[event];
+  }
+  if (!Object.keys(data.hooks).length) delete data.hooks;
+  if (!changed) return { ok: true, action: 'unchanged', path: file };
+  const written = writeHooks(file, parsed.raw, data);
+  if (!written.ok) return { ...written, path: file };
+  return { ok: true, action: 'disconnected', path: file, backup: written.backup };
+}

package/src/klypix-core.mjs

@@ -902,10 +902,10 @@ export async function opBrainNote({ vault, canvas, text: noteText, area, marker
 // ── brain_message — the MCP twin of the hook's 🧠 MSG marker ─────────────────
 // A DELIBERATE one-time note to the OTHER live agent sessions on this project
 // ("merged the hook refactor — rebase before you commit"), delivered once to each
-// peer at its next prompt via the per-project coordination lane. Hook agents send
-// these by emitting `🧠 MSG [to]: text`; this op gives HOOKLESS clients (Cursor /
-// Cline / Windsurf / Desktop) the same send path. Ephemeral (24h), NOT a brain
-// card — durable decisions go through brain_note.
+// peer through its host lifecycle adapter and the per-project coordination lane.
+// Claude hook agents can also send by emitting `🧠 MSG [to]: text`; this op gives
+// every MCP client the same send path. Ephemeral (24h), NOT a brain card — durable
+// decisions go through brain_note.
 //
 // The lane primitives below MUST byte-match src/global-brain-hook.mjs (sha-16 of
 // normBrainPath(brain), sessions/<key>.json layout, MSG_FRESH_MS, the wx-lockfile) —
@@ -964,7 +964,7 @@ export async function opBrainMessage({ vault, canvas, text: msgText, to, via })
   } catch (e) {
     return err(`brain_message failed: ${e.message}`);
   } finally { if (got) { try { fs.unlinkSync(lock); } catch { /* */ } } }
-  return { blocks: [text(`📨 posted to this project's coordination lane (to: ${msg.to}) — ${live} live hook-wired session(s) right now; each sees it once at its next prompt. Hookless clients can send but not receive. Ephemeral (24h), not a brain card — use brain_note for durable decisions.`)] };
+  return { blocks: [text(`📨 posted to this project's coordination lane (to: ${msg.to}) — ${live} active presence-wired session(s) right now; each receives it once through its host lifecycle hook. Hookless clients can send but not receive. Ephemeral (24h), not a brain card — use brain_note for durable decisions.`)] };
 }
 
 // Re-export the format helpers the bins need for non-op work (init onboarding).