klypix-mcp 1.32.0 → 1.34.0

package/README.md

@@ -10,13 +10,22 @@ You've seen the setup: point an AI at a folder of notes, watch the graph fill up
 
 ## Quick start
 
-**Claude Code (native — live hooks, zero effort):**
+**Claude Code + Codex (native, machine-wide):**
 
 ```bash
 npx klypix-mcp install
 ```
 
-Every repo on your machine with a `brain.klypix` now auto-briefs each session with the project's state and auto-captures decisions as you work. 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*), or `create_canvas` makes one from any agent.
+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*),
+or `create_canvas` makes one from any agent.
 
 **Every other agent tool (one command per project):**
 
@@ -24,7 +33,9 @@ Every repo on your machine with a `brain.klypix` now auto-briefs each session wi
 npx klypix-mcp link
 ```
 
-Extends the brain to Cursor & VS Code/Copilot (MCP config + rules) and to Cline, Windsurf, Gemini CLI, Aider, and any AGENTS.md-reading agent — always-on rules that teach the tool to read and capture the brain.
+Adds project-native config for Codex, Cursor, and VS Code/Copilot, plus rules for
+Cline, Windsurf, Gemini CLI, Aider, and any AGENTS.md-reading agent. Verify all
+managed files without changing them with `npx klypix-mcp link --check`.
 
 ## What a project brain does
 
@@ -63,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 |
 |---|---|
@@ -73,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 |
@@ -86,11 +97,23 @@ 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. The **automatic** brain — auto-capturing decisions from your work, injecting the brief into each session, coordinating concurrent sessions (*push*) — runs in a host **hook**, which `npx klypix-mcp install` wires for Claude Code (and the [KLYPIX desktop app](https://klypix.com) ships built-in). Other tools get the always-on rules via `link`.
+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
 
-`install` lays the whole brain (hooks + engine + local MCP server) into `~/.claude/project-brain`, and the emitted config runs the server **from that installed bundle** (no npx cache to go stale). Updates are then automatic: at session start the hook 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.
+`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.
 
 ## Also speaks A2A (Agent-to-Agent)
 

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

@@ -16,7 +16,12 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { mcpServerEntry } from '../src/agent-rules.mjs';
+import {
+    connectCodexMcpServer,
+    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, '..');
@@ -29,6 +34,7 @@ const HOME = os.homedir();
 const CLAUDE_DIR = path.join(HOME, '.claude');
 const BRAIN_DIR = path.join(CLAUDE_DIR, 'project-brain');
 const SETTINGS = path.join(CLAUDE_DIR, 'settings.json');
+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, '/');
@@ -40,6 +46,39 @@ function copyDir(src, dest) {
     }
 }
 
+// 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);
+    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) {
+        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.');
+}
+
 // ── Never-downgrade gate ─────────────────────────────────────────────────────
 // The brain version is a UNIFIED namespace = the klypix-mcp version, stamped by BOTH
 // the npm install (here) and the desktop bundle, so the two channels compare cleanly.
@@ -48,8 +87,16 @@ function copyDir(src, dest) {
 const cmpSemver = (a, b) => { const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0), pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0); for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); } return 0; };
 const cur = (() => { try { return JSON.parse(fs.readFileSync(path.join(BRAIN_DIR, '.brain-version.json'), 'utf8')); } catch { return null; } })();
 if (!FORCE && cur) {
-    if (cur.dev === true) { console.log(`• A dev deploy owns ${BRAIN_DIR} (dev:true) — leaving it untouched. Re-run with --force to override.`); process.exit(0); }
-    if (cur.brainVersion && cmpSemver(cur.brainVersion, VERSION) > 0) { console.log(`• Installed brain v${cur.brainVersion} is newer than this package v${VERSION} — not downgrading. Re-run with --force to override.`); process.exit(0); }
+    if (cur.dev === true) {
+        console.log(`• A dev deploy owns ${BRAIN_DIR} (dev:true) — leaving it untouched. Re-run with --force to override.`);
+        reportCodex(wireCodex());
+        process.exit(0);
+    }
+    if (cur.brainVersion && cmpSemver(cur.brainVersion, VERSION) > 0) {
+        console.log(`• Installed brain v${cur.brainVersion} is newer than this package v${VERSION} — not downgrading. Re-run with --force to override.`);
+        reportCodex(wireCodex());
+        process.exit(0);
+    }
 }
 
 // ── Install lock (auto-propagation, part D — concurrency) ─────────────────────
@@ -164,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']]) {
@@ -218,6 +265,9 @@ try {
     //    (heals an existing stale config so the next MCP server spawn runs current).
     const migrated = migrateProjectMcpConfig();
 
+    // 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
     //    took (a malformed pre-existing group, a partial merge, or a later hand-edit can
     //    leave the brain LIVE but not LEARNING — liveness ≠ readiness). Warn, don't fail.
@@ -226,12 +276,13 @@ try {
     const notWired = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse'].filter(e => !wiredFor(e));
 
     if (gotLock) releaseLock();
+    reportCodex(codex);
     console.log(`✓ installed klypix brain v${VERSION} → ${BRAIN_DIR}  (${n} scripts, ${deps} dep packages)`);
     if (!notWired.length) console.log('✓ wired 4 hooks: SessionStart · UserPromptSubmit (--prompt) · Stop (--capture) · PostToolUse (--live) → settings.json');
     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('  Every project with a ./brain.klypix now auto-reads its brief + captures decisions.');
+    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-link.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 // klypix-link — make THIS project's brain automatic for EVERY agent tool.
-// `npx klypix-mcp install` gives Claude Code the brain via hooks; `link` extends the
-// same automatic read+capture to Cursor, Cline, Windsurf, Copilot/VS Code, Gemini CLI,
-// Aider, and any AGENTS.md-reading agent, by dropping each tool's native MCP config +
+// `npx klypix-mcp install` gives Claude Code hooks and wires Codex globally; `link`
+// extends the same automatic read+capture per project to Codex, Cursor, Cline,
+// Windsurf, Copilot/VS Code, Gemini CLI, Aider, and any AGENTS.md-reading agent,
+// by dropping each tool's native MCP config +
 // rules file in the current project. Idempotent — re-run anytime to refresh. The managed
 // block carries the brain version + a content hash, so:
 //
@@ -48,7 +49,7 @@ try {
 
   const changed = [...rules, ...mcp].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('  Cline & Windsurf MCP servers live in their global config; the rules file points them at the brain regardless.');
+  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`).');
   if (!hasBrain) {
     console.log('\n⚠ No ./brain.klypix here yet — the rules reference it for when you create one.');

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,7 +1,7 @@
 {
   "name": "klypix-mcp",
-  "version": "1.32.0",
-  "description": "Every project gets a brain — one open .klypix file your AI agents read, write, and argue from, over MCP. Works with Claude, Cursor, Cline, any model.",
+  "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",
   "keywords": [
@@ -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');
+}