klypix-mcp 1.55.0 → 1.57.0

package/A2A.md

@@ -26,10 +26,17 @@ Flags / env: `--vault` (`KLYPIX_VAULT`), `--port` (`KLYPIX_A2A_PORT`, default
 `41241`), `--host` (`KLYPIX_A2A_HOST`, loopback only), and
 `--allow-cross-project` (opt in to machine-wide registered-brain search).
 
-It is **local-only**: it binds loopback and needs no auth because callers are on
-the same machine. Non-loopback `--host` values are refused. Remote exposure is
-unsupported until authentication, TLS, a real identity model, and cross-process
-write coordination exist together.
+It is **local-only and OS-user-authenticated**: it binds loopback (non-loopback
+`--host` values are refused), and because loopback is *machine*-local — not
+user-local — every mutating `POST /` requires a bearer token. The server writes
+a fresh token per start to `~/.claude/project-brain/.a2a-token-<port>` (the same
+user-ACL boundary that protects the coordination lane), so only a process
+running as your OS user can read it. Clients: `GET /health` first and check
+`auth.tokenFingerprint` equals `sha256(token)[:16]` from your token file —
+verifying the server before sending the token, so a port-squatting impostor can
+neither pass verification nor harvest it. `KLYPIX_A2A_TOKEN` sets a shared
+secret instead; `--no-auth` opts out explicitly. Remote exposure remains
+unsupported until TLS and a real identity model exist together.
 
 ## Discover it
 

package/README.md

@@ -550,7 +550,9 @@ keep lazy first-use indexing instead.
 - **The optional semantic model runs on device.** Enabling it (or upgrading its model) can fetch
   model weights from Hugging Face; retrieval inference and brain data stay local.
 - **Coordination state is local files.** The brain is a file in your repo; the presence lane is a
-  file under your home directory. Nothing is uploaded.
+  file under your home directory. Nothing is uploaded — with one explicit, default-OFF exception:
+  the cross-PC presence relay, which (only after per-brain consent in the KLYPIX desktop app)
+  shares metadata-only presence frames over that brain's cloud channel. No consent, no frames.
 - **`install` writes to your home directory:** `~/.claude/project-brain` (engine + runtime),
   `~/.claude/settings.json` (four hooks — written even if Claude Code is not installed),
   `~/.codex/AGENTS.md` (guidance block), and with `--codex-hooks`, `~/.codex/hooks.json`. It also

package/bin/klypix-a2a.mjs

@@ -26,6 +26,7 @@
 
 import http from 'http';
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
 import { fileURLToPath } from 'url';
@@ -63,6 +64,44 @@ if (!isLoopbackHostname(HOST)) {
   process.exit(2);
 }
 
+// ── OS-user auth boundary ────────────────────────────────────────────────────
+// Loopback TCP is MACHINE-local, not OS-user-local: on a shared machine any
+// other local user (or sandboxed process) can reach this port — and POST /
+// includes brain WRITES, which land in every future session's context. A
+// per-start bearer token stored under ~/.claude/project-brain (the SAME
+// user-ACL boundary that already protects the coordination lane) restores the
+// stated boundary: only a process that can read this user's home can mutate.
+// KLYPIX_A2A_TOKEN overrides for shared-secret setups; --no-auth opts out
+// explicitly (never silently).
+const NO_AUTH = process.argv.includes('--no-auth') || process.env.KLYPIX_A2A_NO_AUTH === '1';
+const TOKEN_FILE = path.join(os.homedir(), '.claude', 'project-brain', `.a2a-token-${PORT}`);
+const TOKEN = (() => {
+  if (NO_AUTH) return null;
+  const fromEnv = String(process.env.KLYPIX_A2A_TOKEN || '').trim();
+  if (fromEnv) return fromEnv;
+  const token = crypto.randomBytes(32).toString('hex');
+  try {
+    fs.mkdirSync(path.dirname(TOKEN_FILE), { recursive: true });
+    fs.writeFileSync(TOKEN_FILE, token, { mode: 0o600 });
+  } catch (e) {
+    console.error(`[klypix-a2a] Could not write the auth token file (${e?.message || e}); refusing to start UNAUTHENTICATED. Set KLYPIX_A2A_TOKEN or pass --no-auth explicitly.`);
+    process.exit(2);
+  }
+  return token;
+})();
+// Fingerprint (never the token) served on /health: a client verifies the server
+// actually holds the token from THIS user's token file BEFORE sending it — so a
+// port-squatting impostor can neither pass verification nor harvest the token.
+const TOKEN_FINGERPRINT = TOKEN ? crypto.createHash('sha256').update(TOKEN).digest('hex').slice(0, 16) : null;
+function authorized(req) {
+  if (!TOKEN) return true;
+  const m = /^Bearer\s+(.+)$/i.exec(String(req.headers.authorization || '').trim());
+  if (!m) return false;
+  const presented = Buffer.from(m[1].trim());
+  const expected = Buffer.from(TOKEN);
+  return presented.length === expected.length && crypto.timingSafeEqual(presented, expected);
+}
+
 const KLYPIX_MIME = 'application/vnd.klypix+zip';
 const now = () => new Date().toISOString();
 const uuid = () => crypto.randomUUID();
@@ -615,10 +654,18 @@ const server = http.createServer((req, res) => {
     return sendJson(res, 200, agentCard(publicUrl));
   }
   if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/health')) {
-    return sendJson(res, 200, { name: 'klypix-a2a', version: PKG.version, agentCard: `${publicUrl}.well-known/agent-card.json` });
+    return sendJson(res, 200, {
+      name: 'klypix-a2a', version: PKG.version, agentCard: `${publicUrl}.well-known/agent-card.json`,
+      auth: TOKEN
+        ? { scheme: 'bearer', tokenFile: TOKEN_FILE, tokenFingerprint: TOKEN_FINGERPRINT }
+        : { scheme: 'none' },
+    });
   }
 
   if (req.method === 'POST') {
+    if (!authorized(req)) {
+      return sendJson(res, 401, rpcErr(null, -32001, `Unauthorized. Read the bearer token (same OS user) from ${TOKEN_FILE} and send "Authorization: Bearer <token>"; verify the server first via GET /health tokenFingerprint.`));
+    }
     const contentType = String(req.headers['content-type'] || '').split(';', 1)[0].trim().toLowerCase();
     if (contentType !== 'application/json') {
       return sendJson(res, 415, rpcErr(null, -32600, 'Content-Type must be application/json.'));
@@ -657,6 +704,7 @@ server.maxConnections = 16;
 
 server.listen(PORT, HOST, () => {
   log(`ready · vault=${VAULT}`);
+  log(TOKEN ? `auth: bearer (token file ${TOKEN_FILE} · fingerprint ${TOKEN_FINGERPRINT})` : 'auth: NONE (--no-auth) — any local process, including other OS users, can write');
   log(`agent card: http://${HOST}:${PORT}/.well-known/agent-card.json`);
   log(`A2A endpoint (JSON-RPC): http://${HOST}:${PORT}/`);
   // Bounded mode is lazy; legacy mode is the exact eager-prewarm rollback path.

package/bin/klypix-append.mjs

@@ -19,6 +19,7 @@
 
 import fs from 'fs';
 import { appendToKlypix, atomicWrite } from '../src/klypix-format.mjs';
+import { brainCaptureLockPath, withAdvisoryWriteLock } from '../src/brain-write-lock.mjs';
 
 const args = process.argv.slice(2);
 const file = args.find(a => !a.startsWith('--'));
@@ -32,12 +33,21 @@ try {
     addition = JSON.parse(raw);
 } catch (e) { console.error('Addition is not valid JSON:', e.message); process.exit(2); }
 
-let buf;
-try {
-    buf = await appendToKlypix(fs.readFileSync(file), addition);
-} catch (e) { console.error(e.message); process.exit(1); }
-
-await atomicWrite(file, buf);
+// Read-modify-write under the SAME cross-process lock as the MCP engine, hooks,
+// and desktop app; racing them unlocked is silent last-writer-wins loss.
+const wrote = await withAdvisoryWriteLock(brainCaptureLockPath(file), async (locked) => {
+    if (!locked) return false;
+    let buf;
+    try {
+        buf = await appendToKlypix(fs.readFileSync(file), addition);
+    } catch (e) { console.error(e.message); process.exit(1); }
+    await atomicWrite(file, buf);
+    return true;
+}, { tries: 100, waitMs: 60 });
+if (!wrote) {
+    console.error('append-klypix refused (file unchanged): the write lock is held by another writer — retry in a moment.');
+    process.exit(1);
+}
 const cardCount = Array.isArray(addition.cards) ? addition.cards.length : 0;
 const connCount = Array.isArray(addition.connections) ? addition.connections.length : 0;
 console.log(`Appended ${cardCount} card(s), ${connCount} connection(s) to ${file}.`);

package/bin/klypix-worker.mjs

@@ -173,6 +173,11 @@ if (process.argv[2] === 'init') {
 
 const vaultArgIdx = process.argv.indexOf('--vault');
 const VAULT = resolveVault(vaultArgIdx >= 0 ? process.argv[vaultArgIdx + 1] : undefined);
+// A silent ~/Documents fallback is how idle default-root pairs hide inside the
+// machine's RAM total. Say it loudly; brain_sync {project} re-routes per call.
+if (vaultArgIdx < 0 && !process.env.KLYPIX_VAULT) {
+  log(`DEFAULT ROOT: no --vault/KLYPIX_VAULT — vault fell back to ${VAULT}. Pass the project root via brain_sync {project} (or configure --vault) so this connection serves a real project.`);
+}
 const server = new McpServer(
   { name: 'klypix-canvas', version: PKG_VERSION },
   {
@@ -263,11 +268,27 @@ server.registerTool('project_map_context', {
     deep_history: z.boolean().optional().describe('false (default) uses the sub-second lexical-fast correction-aware path; true opts into whole-brain semantic/history retrieval, which may cold-load the local model.'),
   },
 }, async ({ question, project, graph_path, compare_to, depth, max_nodes, k, deep_history }) => {
+  // One root for BOTH the graph and the brain: mixing repo-X code evidence with
+  // repo-Y decisions under a combined banner is silently misleading. When the
+  // caller explicitly targets another project, that project's OWN brain answers
+  // (pinned via `canvas`, which beats the KLYPIX_BRAIN env override) — and when
+  // it has no brain, the output says so instead of borrowing the session brain.
+  const explicitProject = typeof project === 'string' && project.trim() ? path.resolve(project.trim()) : null;
+  const sessionRoot = path.resolve(mcpPresence.vault);
+  const foreignProject = explicitProject && path.relative(sessionRoot, explicitProject) !== '';
+  const contextRoot = explicitProject || sessionRoot;
+  let brainCanvas;
+  if (foreignProject) {
+    const candidate = ['brain.klypix', 'brain.any']
+      .map(name => path.join(explicitProject, name))
+      .find(file => fs.existsSync(file));
+    brainCanvas = candidate || null;
+  }
   let graphResult;
   let graphMarkdown;
   try {
     graphResult = queryProjectGraph({
-      project: project || mcpPresence.vault,
+      project: contextRoot,
       graphPath: graph_path,
       query: question,
       depth,
@@ -275,7 +296,7 @@ server.registerTool('project_map_context', {
     });
     if (compare_to) {
       const previousGraphResult = queryProjectGraph({
-        project: project || mcpPresence.vault,
+        project: contextRoot,
         graphPath: compare_to,
         query: question,
         depth,
@@ -291,16 +312,23 @@ server.registerTool('project_map_context', {
   const graphFiles = Array.isArray(graphResult?.nodes)
     ? [...new Set(graphResult.nodes.map(node => node.sourceFile).filter(Boolean))].slice(0, 20)
     : [];
-  const brainResult = deep_history
-    ? await opBrainAsk({
-      vault: mcpPresence.vault,
-      question,
-      k: Math.max(1, Math.min(20, Number(k) || 8)),
-      log,
-    })
-    : await opBrainTaskContext({
-      vault: mcpPresence.vault,
-      intent: question,
+  const brainResult = foreignProject && brainCanvas === null
+    ? {
+      blocks: [{ kind: 'text', text: `No brain.klypix was found in ${contextRoot} — code evidence only. The session brain was deliberately NOT substituted, so decisions from another project can never masquerade as this one's.` }],
+      context: { mode: 'lexical-fast', hits: [], sufficient: false },
+    }
+    : deep_history
+      ? await opBrainAsk({
+        vault: contextRoot,
+        canvas: brainCanvas,
+        question,
+        k: Math.max(1, Math.min(20, Number(k) || 8)),
+        log,
+      })
+      : await opBrainTaskContext({
+        vault: contextRoot,
+        canvas: brainCanvas,
+        intent: question,
       files: graphFiles,
       k: Math.max(1, Math.min(8, Number(k) || 8)),
       budgetChars: 4_500,
@@ -711,10 +739,27 @@ const stopRuntimePresence = () => {
   recordRunningServer({ remove: true });
   mcpPresence.stop();
 };
+// Supervisor watchdog: reaping is otherwise 100% stdin-EOF-dependent, so a
+// supervisor that dies without closing pipes pinned this worker (and its RAM)
+// forever. KLYPIX_MCP_SUPERVISOR_PID was set at spawn and read nowhere — the
+// heartbeat now polls it. EPERM = alive without permission; ESRCH = gone.
+const SUPERVISOR_PID = Number(process.env.KLYPIX_MCP_SUPERVISOR_PID || 0) || null;
+const supervisorAlive = () => {
+  if (!SUPERVISOR_PID) return true;
+  try { process.kill(SUPERVISOR_PID, 0); return true; }
+  catch (error) { return error?.code === 'EPERM'; }
+};
 server.server.oninitialized = () => {
   mcpPresence.start(VAULT);
   recordRunningServer();
-  runningHeartbeat = setInterval(() => recordRunningServer(), 30_000);
+  runningHeartbeat = setInterval(() => {
+    if (!supervisorAlive()) {
+      log('supervisor process is gone — cleaning up presence and exiting');
+      stopRuntimePresence();
+      process.exit(0);
+    }
+    recordRunningServer();
+  }, 30_000);
   runningHeartbeat.unref?.();
   // The worker mirrors the supervisor's host-neutral scheduler. This lets an
   // older stable supervisor acquire the updater immediately after hot-swapping

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.55.0",
+  "version": "1.57.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -76,7 +76,7 @@
   },
   "scripts": {
     "test:project-graph": "node test/project-graph.mjs",
-    "test": "node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/context-gateway.mjs && node test/conformance.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/brain-connect-orphans.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/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/context-gateway.mjs && node test/conformance.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/brain-connect-orphans.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/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

package/src/agent-presence.mjs

@@ -107,6 +107,27 @@ function releaseLock(lockFile) {
   catch { /* best effort */ }
 }
 
+// Delivered messages are rendered into a PEER AGENT'S PROMPT, and any same-user
+// process can write the lane file directly — so message text is untrusted. A
+// message carrying a live capture marker ("🧠 BRAIN [X]: fake decision") could
+// be echoed by the receiving model and harvested into the shared brain as if the
+// peer had decided it. Break the glyph-keyword adjacency the marker regexes
+// require (🧠·BRAIN no longer matches /🧠\s*BRAIN/) — visually near-identical,
+// never harvestable. Applied at POST (honest writers) AND at delivery (forged
+// lane rows bypass post).
+export function neutralizeMarkers(text) {
+  return String(text || '').replace(/🧠(\s*)(BRAIN|MSG)/gi, '🧠·$2');
+}
+
+// tmp+rename so lock-free readers (readLane, messageFooter, peers' status
+// lines) can never parse a torn lane as an authoritative "0 peers / no
+// messages", and a crash mid-write can never destroy undelivered messages.
+function writeLaneFileAtomic(laneFile, payload) {
+  const tmp = `${laneFile}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+  fs.writeFileSync(tmp, payload);
+  fs.renameSync(tmp, laneFile);
+}
+
 function freshChannelSeen(channelSeen, now) {
   if (!channelSeen || typeof channelSeen !== 'object' || Array.isArray(channelSeen)) return {};
   return Object.fromEntries(Object.entries(channelSeen)
@@ -266,7 +287,7 @@ export function upsertSession({
     const kept = sessions.filter((session) => session.id !== id);
     kept.push(next);
     fs.mkdirSync(path.dirname(laneFile), { recursive: true });
-    fs.writeFileSync(laneFile, JSON.stringify({
+    writeLaneFileAtomic(laneFile, JSON.stringify({
       ...data,
       sessions: kept.slice(-40),
       messages: capMessages(pruneMessages(data.messages, now), 30),
@@ -323,7 +344,7 @@ export function upsertRemoteSessions({ brainPath, rows, machineId = MACHINE_ID,
       else sessions.push(next);
     }
     fs.mkdirSync(path.dirname(laneFile), { recursive: true });
-    fs.writeFileSync(laneFile, JSON.stringify({
+    writeLaneFileAtomic(laneFile, JSON.stringify({
       ...data,
       sessions: sessions.slice(-40),
       messages: capMessages(pruneMessages(data.messages, now), 30),
@@ -347,7 +368,7 @@ export function purgeRemoteSessions({ brainPath, home, now = Date.now() }) {
     const data = readLane(laneFile);
     const sessions = pruneSessions(data.sessions, now).filter((session) => session.via !== 'cloud');
     fs.mkdirSync(path.dirname(laneFile), { recursive: true });
-    fs.writeFileSync(laneFile, JSON.stringify({
+    writeLaneFileAtomic(laneFile, JSON.stringify({
       ...data,
       sessions,
       messages: capMessages(pruneMessages(data.messages, now), 30),
@@ -385,7 +406,7 @@ export function removeSession({ brainPath, id, channel = null, home, now = Date.
       });
     }
     fs.mkdirSync(path.dirname(laneFile), { recursive: true });
-    fs.writeFileSync(laneFile, JSON.stringify({
+    writeLaneFileAtomic(laneFile, JSON.stringify({
       ...data,
       sessions,
       messages: capMessages(pruneMessages(data.messages, now), 30),
@@ -469,7 +490,7 @@ export function receiveMessages({
         if (!Array.isArray(message.seen)) message.seen = [];
         if (!message.seen.includes(sessionId)) message.seen.push(sessionId);
       }
-      fs.writeFileSync(laneFile, JSON.stringify({ ...data, sessions, messages }));
+      writeLaneFileAtomic(laneFile, JSON.stringify({ ...data, sessions, messages }));
     }
     return delivered;
   } finally {
@@ -522,7 +543,7 @@ export function postPresenceMessage({
   home,
   now = Date.now(),
 }) {
-  const body = String(text || '').replace(/\s+/g, ' ').trim().slice(0, 400);
+  const body = neutralizeMarkers(String(text || '').replace(/\s+/g, ' ').trim().slice(0, 400));
   if (!brainPath || !from || !body) return { posted: false, message: null };
   const laneFile = laneFileFor(brainPath, home);
   const lockFile = laneFile + '.lock';
@@ -558,7 +579,7 @@ export function postPresenceMessage({
     };
     messages.push(message);
     fs.mkdirSync(path.dirname(laneFile), { recursive: true });
-    fs.writeFileSync(laneFile, JSON.stringify({
+    writeLaneFileAtomic(laneFile, JSON.stringify({
       ...data,
       sessions,
       messages: capMessages(messages, 30),
@@ -670,7 +691,7 @@ export function formatReceivedMessages(messages, now = Date.now(), decay = {}) {
   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)}`);
+    lines.push(`- from ${String(message.from || '?').slice(0, 12)} (${ageMin}m ago): ${neutralizeMarkers(String(message.text || '').replace(/\s+/g, ' ').trim().slice(0, 400))}`);
     const info = messageDecayInfo(message, now, decay);
     if (info) lines.push(`  ${info.stampText}`);
   }

package/src/brain-git-hook.mjs

@@ -31,26 +31,11 @@ import { execSync } from 'child_process';
 const CWD = process.argv[2] || process.cwd();
 const BRAIN = path.resolve(CWD, 'brain.klypix');
 const STATE = path.resolve(CWD, '.claude', 'brain-last-commit-git');
-const LOCK = path.resolve(CWD, '.claude', 'brain-capture.lock'); // SAME lock the Claude-Code Stop hook uses
-
-// Advisory lockfile (mirrors global-brain-hook.mjs): O_EXCL create wins; a held
-// lock is waited on (sync sleep, no busy-spin); a STALE lock is stolen so a
-// crashed writer can't wedge the brain. Best-effort — write anyway past budget.
-const LOCK_STALE_MS = 15000;
-const sleepSync = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* */ } };
-function acquireLock(lockPath, { tries = 60, waitMs = 60 } = {}) {
-    try { fs.mkdirSync(path.dirname(lockPath), { recursive: true }); } catch { /* */ }
-    for (let i = 0; i < tries; i++) {
-        try { const fd = fs.openSync(lockPath, 'wx'); fs.writeSync(fd, String(process.pid)); fs.closeSync(fd); return true; }
-        catch (e) {
-            if (e && e.code !== 'EEXIST') return false;
-            try { if (Date.now() - fs.statSync(lockPath).mtimeMs > LOCK_STALE_MS) { fs.unlinkSync(lockPath); continue; } } catch { /* lost a race on the stale file — retry */ }
-            sleepSync(waitMs);
-        }
-    }
-    return false;
-}
-function releaseLock(lockPath) { try { fs.unlinkSync(lockPath); } catch { /* */ } }
+// The SAME cross-process lock the Stop hook, MCP engine, and desktop app use —
+// imported from brain-write-lock.mjs (heartbeat + token-checked release), so
+// there is exactly ONE lock implementation. On timeout this hook REFUSES to
+// write and leaves its commit baseline untouched, so the same commits re-scan
+// on the next commit instead of clobbering a peer's just-merged cards.
 
 const git = (a) => execSync(`git ${a}`, { cwd: CWD, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 4000 }).trim();
 const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
@@ -94,12 +79,24 @@ async function main() {
     if (!candidates.length) { writePrev(head); return; }
 
     const lib = await import('./klypix-format.mjs');               // lazy: only when there's something to write
+    let lockLib = null;
+    try { lockLib = await import('./brain-write-lock.mjs'); } catch { /* stale bundle without the module */ }
+    if (!lockLib || typeof lockLib.withAdvisoryWriteLock !== 'function') {
+        // Fail SAFE: without the shared lock we must not read-modify-write at
+        // all. The baseline stays, so these commits re-scan next commit, and the
+        // Stop hook (which dedups by #commit-hash) records them meanwhile.
+        try { process.stderr.write('[klypix-brain] git capture skipped: shared lock module unavailable (stale bundle) — commits re-scan on the next commit\n'); } catch { /* */ }
+        return;
+    }
     // Read-modify-write UNDER the shared lock so a concurrent Claude-Code Stop
-    // hook can't clobber this batch (or vice-versa). Inside the lock, dedup
-    // against commits ALREADY in the brain so neither a re-run nor the Stop hook
-    // double-records the same commit.
-    const gotLock = acquireLock(LOCK);
-    try {
+    // hook or desktop save can't clobber this batch (or vice-versa). Inside the
+    // lock, dedup against commits ALREADY in the brain so neither a re-run nor
+    // the Stop hook double-records the same commit.
+    await lockLib.withAdvisoryWriteLock(lockLib.brainCaptureLockPath(BRAIN), async (locked) => {
+        if (!locked) {
+            try { process.stderr.write('[klypix-brain] git capture deferred: the brain lock is held — commits re-scan on the next commit\n'); } catch { /* */ }
+            return;
+        }
         const buf = fs.readFileSync(BRAIN);
         const already = new Set();
         try {
@@ -116,8 +113,6 @@ async function main() {
         await lib.atomicWrite(BRAIN, out);
         writePrev(head);
         try { process.stderr.write(`[klypix-brain] git capture: ${res.stats?.added ?? cards.length} commit card(s) → brain.klypix\n`); } catch { /* */ }
-    } finally {
-        if (gotLock) releaseLock(LOCK);
-    }
+    }, { tries: 100, waitMs: 60 });
 }
 main().catch(() => { /* never break a commit */ }).finally(() => process.exit(0));

package/src/brain-note.mjs

@@ -20,6 +20,7 @@
 import fs from 'fs';
 import path from 'path';
 import { captureIntoBrain, tidyBrain, atomicWrite, noteToCaptureInput, formatCaptureReceipts } from './klypix-format.mjs';
+import { brainCaptureLockPath, withAdvisoryWriteLock } from './brain-write-lock.mjs';
 
 const MARKERS = { '': '', '?': '?', '!': '!', '✓': '✓', '~': '~', question: '?', milestone: '!', resolve: '✓', update: '~', decision: '', done: '✓' };
 const normMarker = (m) => MARKERS[String(m || '').toLowerCase()] ?? '';
@@ -58,10 +59,21 @@ if (!fs.existsSync(file)) { console.error(`brain-note: no brain at ${file} (run
 
 const input = noteToCaptureInput({ text: opts.text, area: opts.area, marker: opts.marker, closes: opts.closes, createdVia: 'cli' });
 try {
-    const res = await captureIntoBrain(fs.readFileSync(file), input);
-    let out = res.buffer;
-    try { out = (await tidyBrain(res.buffer)).buffer; } catch { /* keep append result if tidy fails */ }
-    await atomicWrite(file, out);
+    // Same cross-process lock as the MCP engine, hooks, and desktop app: an
+    // unlocked read-modify-write racing any of them is silent last-writer-wins
+    // loss. On timeout we REFUSE (exit 1) — the caller just reruns the command.
+    const res = await withAdvisoryWriteLock(brainCaptureLockPath(file), async (locked) => {
+        if (!locked) return null;
+        const captured = await captureIntoBrain(fs.readFileSync(file), input);
+        let out = captured.buffer;
+        try { out = (await tidyBrain(captured.buffer)).buffer; } catch { /* keep append result if tidy fails */ }
+        await atomicWrite(file, out);
+        return captured;
+    }, { tries: 100, waitMs: 60 });
+    if (!res) {
+        console.error('brain-note refused (brain unchanged): the brain lock is held by another writer — retry in a moment.');
+        process.exit(1);
+    }
     const s = res.stats || {};
     const bits = [`${s.added || 0} added`];
     for (const k of ['resolved', 'updated', 'closed', 'superseded', 'linked']) if (s[k]) bits.push(`${s[k]} ${k}`);

package/src/brain-write-lock.mjs

@@ -28,8 +28,22 @@ async function acquire(lockPath, { tries, waitMs, staleMs }) {
     } catch (error) {
       if (error?.code !== 'EEXIST') return null;
       try {
+        // Stale steal via rename, not stat→unlink: rename atomically claims the
+        // REMOVAL (a second stealer gets ENOENT and just retries), and the token
+        // check below detects the losing race — a FRESH successor lock that
+        // slipped in between our stat and our rename is put back, never deleted.
+        const observed = fs.readFileSync(lockPath, 'utf8');
         if (Date.now() - fs.statSync(lockPath).mtimeMs > staleMs) {
-          fs.unlinkSync(lockPath);
+          const graveyard = `${lockPath}.stale-${process.pid}-${Math.random().toString(36).slice(2)}`;
+          fs.renameSync(lockPath, graveyard);
+          let stolen = null;
+          try { stolen = fs.readFileSync(graveyard, 'utf8'); } catch { /* already gone */ }
+          if (stolen !== null && stolen !== observed) {
+            // We displaced a fresh owner. Restore its token if the slot is still
+            // free ('wx' never overwrites); if not, its own token checks refuse.
+            try { fs.writeFileSync(lockPath, stolen, { flag: 'wx' }); } catch { /* slot re-taken */ }
+          }
+          try { fs.unlinkSync(graveyard); } catch { /* our unique file; best-effort */ }
           continue;
         }
       } catch { /* another process changed the lock; retry normally */ }