klypix-mcp 1.55.0 → 1.56.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.56.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 */ }

package/src/global-brain-hook.mjs

@@ -307,6 +307,30 @@ const SESSIONS_DIR = path.join(os.homedir(), '.claude', 'project-brain', 'sessio
 const laneCanon = (p) => { try { return fs.realpathSync.native(p); } catch { return path.resolve(p); } };
 const SESSIONS_FILE = path.join(SESSIONS_DIR, `${sha(normBrainPath(laneCanon(BRAIN)))}.json`); // one lane-file per PROJECT (shared by its concurrent sessions)
 const SESSIONS_LOCK = SESSIONS_FILE + '.lock';
+// tmp+rename: lock-free readers must never parse a torn lane as an empty one.
+function writeLaneAtomic(payload) { const tmp = SESSIONS_FILE + '.tmp-' + process.pid; fs.writeFileSync(tmp, payload); fs.renameSync(tmp, SESSIONS_FILE); }
+// Pending-captures queue: when the BRAIN lock cannot be acquired, the batch is
+// queued here durably instead of written from a stale base (a best-effort write
+// could erase a peer's or the desktop app's just-merged cards — the exact lost
+// update this lock exists to prevent). Drained under the lock by the NEXT
+// capture in this project, from any session. Ids let a re-refused capture
+// replace only what it drained, so a batch a peer queued meanwhile survives.
+const PENDING_CAPTURES_FILE = path.join(os.homedir(), '.claude', 'project-brain', 'pending', `${sha(normBrainPath(laneCanon(BRAIN)))}.captures.json`);
+const PENDING_CAPTURES_LOCK = PENDING_CAPTURES_FILE + '.lock';
+function readPendingCaptures() {
+    try { const d = JSON.parse(fs.readFileSync(PENDING_CAPTURES_FILE, 'utf8')); return Array.isArray(d) ? d : []; } catch { return []; }
+}
+function updatePendingCaptures(mutate) {
+    const got = acquireLock(PENDING_CAPTURES_LOCK, { tries: 20, waitMs: 25 });
+    try {
+        const next = mutate(readPendingCaptures());
+        fs.mkdirSync(path.dirname(PENDING_CAPTURES_FILE), { recursive: true });
+        const tmp = PENDING_CAPTURES_FILE + '.tmp';
+        fs.writeFileSync(tmp, JSON.stringify(next));
+        fs.renameSync(tmp, PENDING_CAPTURES_FILE);
+    } catch { /* never break the session; the transcript markers remain the fallback */ }
+    finally { if (got) releaseLock(PENDING_CAPTURES_LOCK); }
+}
 const SESSION_FRESH_MS = 10 * 60 * 1000;   // a lane unseen for 10min is treated as ended
 const MCP_SESSION_FRESH_MS = 3 * 60 * 1000; // an mcp-channel heartbeat is dead after 3min (matches agent-presence)
 // The host CLI's pid (Claude Code exports CLAUDE_PID to every child, including
@@ -438,7 +462,7 @@ function touchSession(sid, patch = {}) {
             // MCP-written rows on every heartbeat). Message eviction prefers
             // delivered notes (capMsgs) so an unseen note is never silently lost.
             const keptMsgs = capMsgs((Array.isArray(data0.messages) ? data0.messages : []).filter(m => m && (now - (m.ts || 0) < MSG_FRESH_MS)));
-            fs.writeFileSync(SESSIONS_FILE, JSON.stringify({ ...data0, sessions: list.slice(-40), messages: keptMsgs }));
+            writeLaneAtomic(JSON.stringify({ ...data0, sessions: list.slice(-40), messages: keptMsgs }));
             // Hostmap: host-pid → CURRENT session id, re-read by the MCP server on
             // every touch so its lane row follows /clear + resume id rotation. The
             // file is per-PROJECT (all host pids write it), so its read-modify-write
@@ -456,7 +480,7 @@ function touchSession(sid, patch = {}) {
                     fs.renameSync(tmp, HOSTMAP_FILE);
                 } catch { /* best-effort */ }
             }
-        } finally { releaseLock(SESSIONS_LOCK); }
+        } finally { if (got) releaseLock(SESSIONS_LOCK); }
     } catch { /* coordination is best-effort */ }
 }
 // Other live lanes in THIS project (exclude me by session id, pid, AND host pid).
@@ -570,7 +594,7 @@ function postMessages(msgs) {
             kept.push(m);
         }
         fs.mkdirSync(SESSIONS_DIR, { recursive: true });
-        fs.writeFileSync(SESSIONS_FILE, JSON.stringify({ ...data, sessions, messages: capMsgs(kept) }));
+        writeLaneAtomic(JSON.stringify({ ...data, sessions, messages: capMsgs(kept) }));
     } catch { /* best-effort */ } finally { if (got) releaseLock(SESSIONS_LOCK); }
 }
 // to==='all'/'' → everyone; else the hint must appear in my id-prefix / branch / intent.
@@ -690,14 +714,18 @@ function messageFooter(sid, tp, lib) {
                 if (!Array.isArray(m.seen)) m.seen = [];
                 if (!m.seen.includes(sid)) m.seen.push(sid);
             }
-            fs.writeFileSync(SESSIONS_FILE, JSON.stringify(d2));
-        } catch { /* */ } finally { releaseLock(SESSIONS_LOCK); }
+            writeLaneAtomic(JSON.stringify(d2));
+        } catch { /* */ } finally { if (got) releaseLock(SESSIONS_LOCK); }
     }
     if (!delivered.length) return '';
     const ago = (ts) => { const mm = Math.max(0, Math.round((now - (ts || now)) / 60000)); return mm <= 0 ? 'just now' : `${mm}m ago`; };
     const out = ['', '## 📨 Message(s) from another session in this project (delivered once — act on or reply to them)'];
+    // Neutralize glyph-keyword adjacency in delivered text (🧠·BRAIN can't match
+    // the capture regex): a forged lane row must never plant a harvestable marker
+    // in this session's prompt. Mirrors agent-presence.neutralizeMarkers.
+    const neutral = (s) => String(s).replace(/🧠(\s*)(BRAIN|MSG)/gi, '🧠·$2');
     for (const m of delivered) {
-        out.push(`- from ${String(m.from || '?').slice(0, 8)} · ${ago(m.ts)}: ${String(m.text).replace(/\s+/g, ' ').trim().slice(0, 400)}`);
+        out.push(`- from ${String(m.from || '?').slice(0, 8)} · ${ago(m.ts)}: ${neutral(String(m.text)).replace(/\s+/g, ' ').trim().slice(0, 400)}`);
         // Engine-emitted LAST-KNOWN stamp — its own line, after the 400-char slice.
         const stamp = decayStampForMessage(m.text, m.ts, now, lib);
         if (stamp) out.push(`  ${stamp}`);
@@ -1267,7 +1295,7 @@ const readRuleDrafts = () => { try { const d = JSON.parse(fs.readFileSync(RULE_D
 // pending finding and vice versa. Both writers now read the file first and
 // replace only their own key. Adding a third list is safe by the same rule.
 const readSidecar = () => { try { const d = JSON.parse(fs.readFileSync(RULE_DRAFTS, 'utf8')); return d && typeof d === 'object' && !Array.isArray(d) ? d : {}; } catch { return {}; } };
-const writeSidecar = (patch) => { try { fs.mkdirSync(path.dirname(RULE_DRAFTS), { recursive: true }); fs.writeFileSync(RULE_DRAFTS, JSON.stringify({ ...readSidecar(), ...patch }, null, 2)); } catch { /* best-effort */ } };
+const writeSidecar = (patch) => { try { fs.mkdirSync(path.dirname(RULE_DRAFTS), { recursive: true }); const tmp = `${RULE_DRAFTS}.tmp-${process.pid}`; fs.writeFileSync(tmp, JSON.stringify({ ...readSidecar(), ...patch }, null, 2)); fs.renameSync(tmp, RULE_DRAFTS); } catch { /* best-effort */ } };
 const writeRuleDrafts = (drafts) => writeSidecar({ drafts: (drafts || []).slice(-RULE_DRAFTS_MAX) });
 const draftKey = (area, text) => sha(((area || '') + '|' + String(text)).toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim());
 // Token overlap: is a draft seed substantially covered by a (skill) card's text?
@@ -1300,6 +1328,7 @@ function sessionVerified(shellCmds, errorIds, hadFixCommit) {
 // sidecar in an adopter project, and identical rewrites cause no churn.
 function persistDrafts(mutate) {
     const got = acquireLock(RULE_DRAFTS_LOCK, { tries: 20, waitMs: 25 });
+    if (!got) return;   // lock timeout → SKIP: an unlocked RMW clobbers the other key's writer; a dropped bump re-detects next Stop
     try {
         const now = Date.now();
         const raw = readRuleDrafts();
@@ -1447,6 +1476,7 @@ const readFindings = () => { const d = readSidecar(); return Array.isArray(d.fin
 // that keeps an adopter project from growing an empty sidecar.
 function persistFindings(mutate) {
     const got = acquireLock(RULE_DRAFTS_LOCK, { tries: 20, waitMs: 25 });
+    if (!got) return;   // lock timeout → SKIP (mirrors persistDrafts): never RMW the shared sidecar unlocked
     try {
         const now = Date.now();
         const raw = readFindings();
@@ -1764,7 +1794,10 @@ async function capture(lib) {
         // is this turn's real touch-set — the other half of "own scope".
         await draftFindingsFromCards(cards, verified, sid, recentPaths);
     }
-    if (!cards.length && !resolutions.length && !updates.length) {
+    // A queued batch from a prior lock-refused capture counts as work to do —
+    // the authoritative drain happens INSIDE the brain lock (doCapture), so two
+    // concurrent sessions can never both land the same queued batch.
+    if (!cards.length && !resolutions.length && !updates.length && !readPendingCaptures().length) {
         // Record the commit baseline / advance even with nothing to capture, so
         // the next run doesn't re-scan the same commits.
         if (newLastCommit && newLastCommit !== prevCommit) writeLastCommit(newLastCommit);
@@ -1782,30 +1815,68 @@ async function capture(lib) {
     // and UNION the dedup state (don't clobber a peer's seen-set). captureInto-
     // Brain supersedes heavily-overlapping old cards, applies ✓/~, routes new
     // cards into [Area] containers, and wires [[wikilink]] connections.
-    const gotLock = acquireLock(LOCK);
-    let stats;
-    try {
+    const doCapture = async (locked) => {
         const merged = readState(); for (const k of seen) merged.add(k);
+        if (!locked) {
+            // REFUSED: never write from a stale base. The batch is queued durably
+            // (same home as the dedup state) and drained by the next capture in
+            // this project — deferred-but-safe beats immediate-but-clobbering.
+            if (cards.length || resolutions.length || updates.length) {
+                updatePendingCaptures((current) => [
+                    ...current,
+                    { id: `${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2)}`, ts: nowIso(), cards, resolutions, updates },
+                ]);
+            }
+            writeState(merged);
+            writeLastCommit(newLastCommit); // safe: the batch itself is durably queued
+            if (drainedShips && typeof lib.clearPendingShips === 'function') lib.clearPendingShips(CWD);
+            advanceShipBaseline(lib);
+            appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'capture', ok: false, err: 'lock-timeout — batch QUEUED for the next capture; brain untouched' }, 500);
+            process.stderr.write('[brain] capture deferred: the brain lock is held (desktop save or peer capture) — batch queued durably, nothing lost\n');
+            return null;
+        }
+        // Drain the queue UNDER the lock: read, land, clear-by-id — a peer's
+        // batch queued after this read survives, and no batch lands twice.
+        const pendingBatches = readPendingCaptures();
+        const drainedPendingIds = new Set(pendingBatches.map(b => b && b.id).filter(Boolean));
+        for (const b of pendingBatches) {
+            if (!b || typeof b !== 'object') continue;
+            for (const c of (Array.isArray(b.cards) ? b.cards : [])) cards.push(c);
+            for (const r of (Array.isArray(b.resolutions) ? b.resolutions : [])) resolutions.push(r);
+            for (const u of (Array.isArray(b.updates) ? b.updates : [])) updates.push(u);
+        }
+        if (!cards.length && !resolutions.length && !updates.length) return null;
         const res = await lib.captureIntoBrain(fs.readFileSync(BRAIN), {
             cards: cards.map(c => ({ text: c.text, color: '#e8e8ed', borderColor: c.borderColor, area: c.area, createdVia: c.createdVia || 'claude-code', ...(c.closes ? { closes: c.closes } : {}), ...(c.evidence ? { evidence: c.evidence } : {}), ...(c.verify ? { verify: c.verify } : {}) })),
             resolutions,
             updates,
         });
-        stats = res.stats;
         // Re-pack the whole grid so a container that grew never overlaps its neighbor.
         let out = res.buffer; try { out = (await lib.tidyBrain(res.buffer)).buffer; } catch { /* keep append result if tidy fails */ }
         await lib.atomicWrite(BRAIN, out);
         writeState(merged);
         writeLastCommit(newLastCommit); // advance the commit baseline only after a successful write
+        if (drainedPendingIds.size) updatePendingCaptures((current) => current.filter(b => b && !drainedPendingIds.has(b.id)));
         // Same discipline for the two ship channels: the queue is consumed and
         // the observation baseline advances ONLY now that the cards are durable.
         if (drainedShips && typeof lib.clearPendingShips === 'function') lib.clearPendingShips(CWD);
         advanceShipBaseline(lib);
         try { await refreshAgentsBrief(lib, out); } catch { /* AGENTS.md refresh is best-effort */ }
-    } finally {
-        if (gotLock) releaseLock(LOCK);
+        return res.stats;
+    };
+    // Canonical cross-process lock (heartbeat + token-checked release, shared
+    // with the MCP engine and the desktop app). Stale bundles missing the module
+    // fall back to the local lock — but ALWAYS refuse-and-queue on timeout.
+    let lockLib = null;
+    try { lockLib = await import(new URL('./brain-write-lock.mjs', import.meta.url).href); } catch { /* stale deployment */ }
+    let stats;
+    if (lockLib && typeof lockLib.withAdvisoryWriteLock === 'function') {
+        stats = await lockLib.withAdvisoryWriteLock(lockLib.brainCaptureLockPath(BRAIN), doCapture, { tries: 100, waitMs: 60 });
+    } else {
+        const gotLock = acquireLock(LOCK);
+        try { stats = await doCapture(gotLock); } finally { if (gotLock) releaseLock(LOCK); }
     }
-    if (!gotLock) appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'capture', ok: false, err: 'lock-timeout — wrote best-effort' }, 500);
+    if (!stats) return;
     const bits = [`${stats.added} added`];
     if (stats.resolved) bits.push(`${stats.resolved} resolved`);
     if (stats.updated) bits.push(`${stats.updated} updated`);

package/src/klypix-core.mjs

@@ -34,7 +34,7 @@ import {
   isFastDecayCard, DECAY_STALE_MS, formatDecayAge,
   readPendingShips, clearPendingShips, pendingShipCards, formatCaptureReceipts,
 } from './klypix-format.mjs';
-import { capMessages, findProjectBrain } from './agent-presence.mjs';
+import { capMessages, findProjectBrain, neutralizeMarkers } from './agent-presence.mjs';
 import { brainCaptureLockPath, vaultCreateLockPath, withAdvisoryWriteLock } from './brain-write-lock.mjs';
 import {
   dot, embedTexts, getEmbedder, getEmbedderForUse, withRerankerForUse,
@@ -288,7 +288,10 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
   const asOfTs = as_of ? Date.parse(as_of) : null;
   if (as_of && Number.isNaN(asOfTs)) return err(`Bad as_of date: "${as_of}" — use YYYY-MM-DD.`);
 
-  const pipe = await getEmbedderForUse(log, 20_000);
+  // Queue saturation (KLYPIX_SEMANTIC_QUEUE_FULL) must degrade to lexical, not
+  // error — this tool's own description promises "degrades cleanly".
+  let pipe = null;
+  try { pipe = await getEmbedderForUse(log, 20_000); } catch { /* saturated/unavailable → lexical only */ }
   let qv = null;
   if (pipe) { try { [qv] = await embedTexts(pipe, [q], { kind: 'query' }); } catch { /* lexical only */ } }
 
@@ -895,7 +898,9 @@ export async function opBrainConnect({ vault, canvas, apply = false, max = 24, t
     : (normalizedScope === 'orphans' ? 0.55 : 0.45);
   let edges = [];
   let mode = 'structural (shared tags + [[mentions]])';
-  const pipe = await getEmbedderForUse(log, 20_000);
+  // Queue saturation must degrade to the structural mode, never a hard error.
+  let pipe = null;
+  try { pipe = await getEmbedderForUse(log, 20_000); } catch { /* saturated/unavailable → structural */ }
   if (pipe) {
     try {
       const vecs = await vectorsForBrain(pipe, file, struct.cards);
@@ -1132,9 +1137,15 @@ export async function opBrainMessage({ vault, canvas, text: msgText, to, via })
     // cap + collapse the target hint too — an oversized `to` would bloat the lane
     // file every hook of every session re-reads for 24h (and matches no one anyway)
     to: String(to || 'all').replace(/\s+/g, ' ').trim().slice(0, 64) || 'all',
-    text: txt.slice(0, 400), ts: now, seen: [],
+    // Neutralized at post (delivery surfaces neutralize again for forged rows):
+    // a message must never carry a HARVESTABLE capture marker into a peer's prompt.
+    text: neutralizeMarkers(txt.slice(0, 400)), ts: now, seen: [],
   };
   const got = laneLock(lock);
+  // Lock timeout → REFUSE, never write: an unlocked read-modify-write of the
+  // whole lane can permanently erase a peer's just-posted undelivered message
+  // (the exact loss class touchSession already refuses). Retry is cheap.
+  if (!got) return err('brain_message deferred: the coordination lane is busy (another session is writing). Nothing was posted — retry in a moment.');
   let live = 0;
   try {
     let data = {}; try { data = JSON.parse(fs.readFileSync(laneFile, 'utf8')); } catch { /* fresh lane */ }
@@ -1146,10 +1157,13 @@ export async function opBrainMessage({ vault, canvas, text: msgText, to, via })
     // Delivered-first eviction + ...data spread — the other two lane writers were
     // converted in the 2026-07-29 overhaul; a flat slice here still destroyed the
     // oldest UNDELIVERED note at cap (review-caught).
-    fs.writeFileSync(laneFile, JSON.stringify({ ...data, sessions, messages: capMessages(kept, 30) }));
+    // tmp+rename so lock-free readers can never parse a torn lane as "no messages".
+    const tmp = `${laneFile}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify({ ...data, sessions, messages: capMessages(kept, 30) }));
+    fs.renameSync(tmp, laneFile);
   } catch (e) {
     return err(`brain_message failed: ${e.message}`);
-  } finally { if (got) { try { fs.unlinkSync(lock); } catch { /* */ } } }
+  } finally { try { fs.unlinkSync(lock); } catch { /* */ } }
   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 lifecycle adapter or next brain_sync / KLYPIX tool call. Ephemeral (24h), not a brain card — use brain_note for durable decisions.`)] };
 }
 

package/src/mcp-presence.mjs

@@ -474,7 +474,22 @@ export function createMcpPresence({
       files: details.files,
       replaceFiles: details.replaceFiles === true,
     });
-    timer = setIntervalFn(() => touch(), Math.max(5_000, Number(heartbeatMs) || MCP_HEARTBEAT_MS));
+    // Consume the write verdict (1.52.0 plumbed it; nothing read it): a
+    // contended lane skips the write, and ~3 skipped heartbeats in a row used
+    // to make a LIVE session read as dead to every peer, silently. One
+    // immediate same-tick retry clears transient contention; persistent
+    // failure is surfaced through the server's logging channel.
+    let missedLaneWrites = 0;
+    timer = setIntervalFn(() => {
+      let beat = touch();
+      if (beat?.laneWriteOk === false) beat = touch();   // one quick retry
+      if (beat?.laneWriteOk !== false) { missedLaneWrites = 0; return; }
+      missedLaneWrites++;
+      if (missedLaneWrites >= 3) {
+        try { server?.server?.sendLoggingMessage?.({ level: 'warning', data: `KLYPIX presence heartbeat skipped ${missedLaneWrites}× (lane contended) — peers may briefly see this session as idle.` }); } catch { /* logging is best-effort */ }
+        missedLaneWrites = 0;
+      }
+    }, Math.max(5_000, Number(heartbeatMs) || MCP_HEARTBEAT_MS));
     inboxTimer = setIntervalFn(
       () => pollInbox(),
       Math.max(250, effectiveInboxPollMs),

package/src/mcp-supervisor.mjs

@@ -251,6 +251,13 @@ class Supervisor {
     this.stateFile = path.join(this.stateDir, `${process.pid}.json`);
     this.connectionId = String(options.connectionId || crypto.randomUUID());
     this.parentPid = Number(process.ppid) || null;
+    // Default-root detection: IDE hosts often launch from their install dir
+    // with no --vault/KLYPIX_VAULT, so the pair boots against ~/Documents and
+    // idles there. Flagging it in the state file lets doctor/runtime name these
+    // pairs explicitly instead of them hiding inside the aggregate RAM number.
+    const vaultFlagAt = this.workerArgs ? this.workerArgs.indexOf('--vault') : -1;
+    this.vaultArg = vaultFlagAt >= 0 ? String(this.workerArgs[vaultFlagAt + 1] || '') : null;
+    this.defaultRoot = !this.vaultArg && !process.env.KLYPIX_VAULT;
     this.clientInfo = null;
     this.lastHostMessageAt = null;
     this.lastActivityStateWriteAt = 0;
@@ -288,6 +295,8 @@ class Supervisor {
         pid: process.pid,
         connectionId: this.connectionId,
         parentPid: this.parentPid,
+        vault: this.vaultArg ? this.vaultArg.replace(/\\/g, '/') : null,
+        defaultRoot: this.defaultRoot,
         cwd: process.cwd().replace(/\\/g, '/'),
         bootedAt: this.bootedAt,
         updatedAt: new Date().toISOString(),
@@ -502,13 +511,26 @@ class Supervisor {
   }
 
   failInflight(message) {
-    for (const id of this.hostRequests.values()) {
+    for (const { id } of this.hostRequests.values()) {
       this.sendHost({ jsonrpc: '2.0', id, error: { code: -32603, message } });
     }
     this.hostRequests.clear();
     this.workerRequests.clear();
   }
 
+  // A host request the worker never answers must not pin active+candidate
+  // workers (2× RAM) forever: past the deadline we answer the host with an
+  // error (its own client timeout has long fired) and stop counting it against
+  // candidate commit.
+  expireAbandonedRequests(maxAgeMs = 120_000) {
+    const cutoff = Date.now() - maxAgeMs;
+    for (const [key, entry] of this.hostRequests) {
+      if ((entry?.ts || 0) >= cutoff) continue;
+      this.hostRequests.delete(key);
+      this.sendHost({ jsonrpc: '2.0', id: entry.id, error: { code: -32603, message: 'KLYPIX worker did not answer this request within 120s; it was abandoned so a pending worker swap can proceed.' } });
+    }
+  }
+
   captureTaskScope(message) {
     if (message?.method !== 'tools/call' || message.params?.name !== 'brain_sync') return;
     const args = message.params?.arguments || {};
@@ -581,7 +603,7 @@ class Supervisor {
     this.captureTaskScope(message);
 
     if (message?.method && Object.prototype.hasOwnProperty.call(message, 'id')) {
-      this.hostRequests.set(idKey(message.id), message.id);
+      this.hostRequests.set(idKey(message.id), { id: message.id, ts: Date.now() });
     } else if (!message?.method && Object.prototype.hasOwnProperty.call(message, 'id')) {
       this.workerRequests.delete(idKey(message.id));
     }
@@ -731,6 +753,7 @@ class Supervisor {
 
   maybeCommitCandidate() {
     if (!this.candidate?.ready) return;
+    this.expireAbandonedRequests();
     if (this.hostRequests.size || this.workerRequests.size) return;
     const next = this.candidate;
     const previous = this.active;
@@ -885,6 +908,20 @@ class Supervisor {
     );
     this.autoUpdatePoller.unref?.();
 
+    // Host watchdog: shutdown is otherwise 100% stdin-EOF-dependent, and a
+    // host that dies holding pipes open (or a wedged IDE) pinned this pair —
+    // supervisor AND worker — indefinitely. The parent pid is a cheap,
+    // platform-neutral liveness signal; EPERM still means alive.
+    if (this.parentPid && this.parentPid > 1) {
+      this.parentWatchdog = setInterval(() => {
+        try { process.kill(this.parentPid, 0); }
+        catch (error) {
+          if (error?.code !== 'EPERM') { log('host process is gone — closing the connection pair'); this.close(); }
+        }
+      }, 30_000);
+      this.parentWatchdog.unref?.();
+    }
+
     await new Promise(resolve => {
       this.resolveRun = resolve;
       process.stdin.once('end', () => this.close());
@@ -898,12 +935,22 @@ class Supervisor {
     if (this.closed) return;
     this.closed = true;
     clearInterval(this.poller);
+    clearInterval(this.parentWatchdog);
     clearTimeout(this.autoUpdateStarter);
     clearInterval(this.autoUpdatePoller);
     if (this.recoveryTimer) { clearTimeout(this.recoveryTimer); this.recoveryTimer = null; }
-    for (const worker of [this.active, this.candidate, this.standby]) this.retireWorker(worker, 0);
+    // Real shutdown grace: stdin EOF lets the worker run its own presence
+    // cleanup (stopRuntimePresence/removeSession). An instant SIGTERM is
+    // TerminateProcess on Windows — the cleanup never runs and every normally
+    // closed session leaves a ghost "live" lane row for the TTL window (the
+    // "cleans up automatically" claim was false on exactly this path). SIGTERM
+    // stays as the 350ms backstop; the deliberately NOT-unref'd exit delay
+    // holds this process open just long enough to deliver it.
+    const workers = [this.active, this.candidate, this.standby].filter(w => w && !w.exited);
+    for (const worker of workers) this.retireWorker(worker, 350);
     try { fs.unlinkSync(this.stateFile); } catch { /* */ }
-    this.resolveRun?.();
+    if (workers.length) setTimeout(() => this.resolveRun?.(), 400);
+    else this.resolveRun?.();
   }
 }
 

package/src/presence-relay.mjs

@@ -196,6 +196,33 @@ export function selectOutboundMessages(messages, { sinceTs = 0 } = {}) {
       && !String(message.dedupeKey || '').startsWith(XPC_DEDUPE_PREFIX));
 }
 
+// ── Frame authenticity (optional per-brain MAC) ─────────────────────────────
+// Channel ACLs live outside this repo, so any channel member could otherwise
+// forge sid/machine (fabricated presence, overlap-warning spam) or claim a
+// victim receiver's machineId so that receiver drops the frames as "own echo"
+// (a targeted mute). With a shared per-brain key (the desktop already holds
+// one for each cloud-linked brain), frames carry an HMAC over their sorted
+// fields; a receiver configured with the key DROPS unsigned or mis-signed
+// frames. No key configured → unsigned tolerated (compat: old builds, and
+// consent remains the outer gate either way).
+function frameMac(frame, key) {
+  const entries = Object.keys(frame).filter((k) => k !== 'mac').sort()
+    .map((k) => [k, frame[k]]);
+  return crypto.createHmac('sha256', String(key)).update(JSON.stringify(entries)).digest('hex').slice(0, 32);
+}
+export function signFrame(frame, key) {
+  if (!frame || typeof frame !== 'object' || !key) return frame;
+  return { ...frame, mac: frameMac(frame, key) };
+}
+export function verifyFrame(frame, key) {
+  if (!frame || typeof frame !== 'object') return false;
+  if (!key) return true;                                 // no key → tolerate unsigned
+  if (typeof frame.mac !== 'string' || !frame.mac) return false;
+  const expected = Buffer.from(frameMac(frame, key));
+  const presented = Buffer.from(String(frame.mac));
+  return presented.length === expected.length && crypto.timingSafeEqual(presented, expected);
+}
+
 // ── The transport seam ───────────────────────────────────────────────────────
 // The desktop relay calls exactly these two functions around its Realtime
 // channel; the conformance harness calls them around a mock. Consent is
@@ -214,6 +241,7 @@ export function relayOutbound({
   sinceTs = 0,
   now = Date.now(),
   send,
+  key = null,
 } = {}) {
   if (!presenceConsentAllows(consent)) return { sent: 0, reason: 'no-consent', maxMessageTs: sinceTs };
   if (typeof send !== 'function') return { sent: 0, reason: 'no-channel', maxMessageTs: sinceTs };
@@ -222,22 +250,23 @@ export function relayOutbound({
   for (const session of Array.isArray(sessions) ? sessions : []) {
     const frame = buildPresenceFrame(session, { machineId, hostLabel, root, now });
     if (!frame) continue;
-    send(frame);
+    send(signFrame(frame, key));
     sent++;
   }
   for (const message of selectOutboundMessages(messages, { sinceTs })) {
     const frame = buildMessageFrame(message, { machineId, now });
     if (!frame) continue;
-    send(frame);
+    send(signFrame(frame, key));
     sent++;
     maxMessageTs = Math.max(maxMessageTs, Number(message.ts || 0));
   }
   return { sent, reason: null, maxMessageTs };
 }
 
-export function relayInbound(frame, { consent = null, machineId, now = Date.now() } = {}) {
+export function relayInbound(frame, { consent = null, machineId, now = Date.now(), key = null } = {}) {
   if (!presenceConsentAllows(consent)) return null;   // symmetric: no consent ⇒ no receive-display
   if (!frame || typeof frame !== 'object') return null;
+  if (!verifyFrame(frame, key)) return null;          // key configured → unsigned/mis-signed frames drop
   if (frame.kind === 'presence') {
     const row = acceptPresenceFrame(frame, { machineId, now });
     return row ? { type: 'presence', row } : null;

package/src/project-graph.mjs

@@ -75,7 +75,13 @@ function safeSourceFile(root, value) {
 
 function shortString(value, max = 1_000) {
   if (value == null) return '';
-  return String(value).replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, '').slice(0, max);
+  // Tabs and newlines collapse to one space so a hostile graph label can never
+  // break out of its one-line markdown bullet into headings of its own.
+  return String(value).replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, '')
+    .replace(/[\t\n\r]+/g, ' ')
+    .replace(/ {2,}/g, ' ')
+    .trim()
+    .slice(0, max);
 }
 
 function normalizeConfidence(edge) {
@@ -384,6 +390,22 @@ export function suggestProjectGraphBrainLinks(graphResult, brainContext, limit =
   return proposals;
 }
 
+const STALE_ARTIFACT_MS = 7 * 24 * 60 * 60 * 1000;
+
+function artifactAgeLine(artifact) {
+  const iso = artifact?.modifiedAt;
+  if (!iso) return '';
+  const generated = Date.parse(iso);
+  if (!Number.isFinite(generated)) return '';
+  const ageMs = Math.max(0, Date.now() - generated);
+  const days = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+  const age = days >= 1 ? `${days} day(s) ago` : 'today';
+  const warning = ageMs > STALE_ARTIFACT_MS
+    ? ' — the artifact may be stale; regenerate it if the code has moved.'
+    : '.';
+  return `Artifact generated ${iso} (${age})${warning} Graph evidence is only as current as this artifact.`;
+}
+
 export function projectGraphContextMarkdown(result) {
   if (result.status === 'missing') {
     return `# Project Map\n\nNo supported project graph was found at \`${result.artifact.graphJson}\`. KLYPIX did not install or run a provider. Generate the artifact with Graphify, then retry.`;
@@ -400,6 +422,7 @@ export function projectGraphContextMarkdown(result) {
   return [
     '# Project Map: code evidence',
     `Provider artifact: \`${result.artifact.graphJson}\`; ${result.counts.graphNodes.toLocaleString()} nodes; ${result.counts.graphEdges.toLocaleString()} edges; query \`${result.query || '(overview)'}\`.`,
+    artifactAgeLine(result.artifact),
     warnings.length ? `Safety note: ${warnings.join('; ')}.` : '',
     result.change ? `## Change from \`${result.change.comparedArtifact || 'comparison artifact'}\`\nExact total deltas: ${result.change.graphNodesDelta >= 0 ? '+' : ''}${result.change.graphNodesDelta} nodes; ${result.change.graphEdgesDelta >= 0 ? '+' : ''}${result.change.graphEdgesDelta} edges. Named additions and removals are limited to the two bounded query neighborhoods.` : '',
     result.change?.addedNodes?.length ? `Added in bounded result: ${result.change.addedNodes.slice(0, 20).map(node => `\`${node.label || node.id}\``).join(', ')}.` : '',