klypix-mcp 1.15.0 → 1.16.0

package/bin/klypix-append.mjs

@@ -41,4 +41,4 @@ await atomicWrite(file, buf);
 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}.`);
-console.log(`Reopen it in KLYPIX, or verify: node scripts/read-klypix.mjs "${file}"`);
+console.log(`Reopen it in the KLYPIX app, or verify: node scripts/read-klypix.mjs "${file}"`);

package/bin/klypix-mcp.mjs

@@ -24,7 +24,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   resolveVault, getEmbedder, buildKlypixMap, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
-  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote,
+  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage,
 } from '../src/klypix-core.mjs';
 
 // Real package version for the MCP handshake (was hardcoded '1.0.0', which
@@ -160,7 +160,7 @@ server.registerTool('brain_garden', {
 
 server.registerTool('create_canvas', {
   title: 'Create a KLYPIX canvas',
-  description: 'Create a new .klypix canvas from cards + connections and save it to the vault. The user opens it in KLYPIX (Canvas → Open). Prefer short, titled cards (one idea each) connected by meaningful arrows.',
+  description: 'Create a new .klypix canvas from cards + connections and save it to the vault. The user opens it in the KLYPIX app (Canvas → Open). Prefer short, titled cards (one idea each) connected by meaningful arrows.',
   inputSchema: {
     title: z.string().describe('Canvas title (also the filename).'),
     cards: z.array(cardSchema).min(1).describe('The cards. 5-12 atomic cards is ideal.'),
@@ -199,6 +199,19 @@ server.registerTool('brain_note', {
   return toContent(await opBrainNote({ vault: VAULT, canvas, text, area, marker: marker || '', closes, via }));
 });
 
+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.',
+  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.'),
+    canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
+  },
+}, async ({ text, to, canvas }) => {
+  let via; try { via = server.server.getClientVersion()?.name; } catch { /* optional */ }
+  return toContent(await opBrainMessage({ vault: VAULT, canvas, text, to, via }));
+});
+
 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`.',

package/bin/klypix-write.mjs

@@ -42,4 +42,4 @@ await atomicWrite(outPath, buf);
 const cardCount = spec.cards.length;
 const connCount = Array.isArray(spec.connections) ? spec.connections.length : 0;
 console.log(`Wrote ${outPath} — ${cardCount} cards, ${connCount} connections.`);
-console.log(`Open it in KLYPIX (Canvas → Open), or verify: node scripts/read-klypix.mjs "${outPath}"`);
+console.log(`Open it in the KLYPIX app (Canvas → Open), or verify: node scripts/read-klypix.mjs "${outPath}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "An open, local-first, agent-neutral canvas file your AI reads and writes over MCP — works with Claude, Cursor, Cline, any model.",
   "type": "module",
   "license": "MIT",
@@ -53,7 +53,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs"
+    "test": "node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/src/agent-rules.mjs

@@ -73,6 +73,12 @@ memory the whole team and every agent reads, not a private scratchpad only you c
 project decision live *only* in your host's memory or a scratch file — put it here so the next
 session/agent has it.
 
+**Working alongside other live sessions?** Send a one-time coordination note with the
+\`brain_message\` MCP tool ("merged the hook refactor — rebase before you commit"); hook-wired peer
+sessions (Claude Code) see it at their next prompt. Any client can SEND; only hook-wired sessions
+receive, so don't rely on it to reach a hookless peer. Notes are ephemeral (24h), NOT brain cards —
+durable decisions still go through \`brain_note\`.
+
 **Don't** hand-edit \`brain.klypix\` (it's a packaged canvas — use the tools) or dump file contents into it; capture the *decision*, not the file.`;
 
 // Content fingerprint of the canonical instructions — stamped into the fence so a
@@ -101,17 +107,43 @@ function parseFence(text) {
   return { version: m[1] || null, hash: m[2] || null, body: m[3] || '' };
 }
 
-// Classify a projected fenced file WITHOUT writing (the drift audit).
+// Classify a projected fenced file WITHOUT writing (the drift audit). THE single
+// source of truth for both check AND write: fenceMerge/writeDedicated skip a file
+// IFF this says 'ok', so classify-ok ⇔ link-unchanged can never disagree (the 1.16
+// adversarial review found three ways they used to: an unrepairable hand-edited
+// stamp, an invisible frontmatter strip, and a check-ok-but-link-downgrades skew).
 //   missing      — file absent, or present but carries no managed block
-//   hand-edited  — block body no longer matches the hash it was stamped with
-//   stale        — block intact but stamped from an older brain (version < current),
-//                   or a legacy unstamped block (no version) → a re-link refreshes it
-//   ok           — block present, current version, body matches its hash
-function classifyFenced(file, version) {
+//   hand-edited  — block body no longer matches the hash it was stamped with; or
+//                   (owned dedicated files) anything OUTSIDE the fence drifted —
+//                   e.g. a stripped `alwaysApply:`/`trigger:` frontmatter, which
+//                   silently disables the rule in Cursor/Windsurf
+//   ok           — block body is EXACTLY what we'd project today AND the stamp is
+//                   consistent with it — regardless of the stamped version. CONTENT
+//                   is the contract, the stamp is provenance: a version-only bump
+//                   must NOT re-drift every adopter into a re-link treadmill. A
+//                   self-consistent block stamped NEWER than the running brain is
+//                   also 'ok' (and link leaves it alone — never downgrade).
+//   stale        — block body differs from today's instructions AND was stamped from
+//                   an older brain (or is a legacy unstamped block) → re-link refreshes
+const STAMP_RE = /<!--\s*klypix-brain:start[\s\S]*?-->/;
+function classifyFenced(file, version, frontmatter = null) {
   if (!exists(file)) return { status: 'missing' };
-  const fence = parseFence(fs.readFileSync(file, 'utf8'));
+  const raw = fs.readFileSync(file, 'utf8');
+  const fence = parseFence(raw);
   if (!fence) return { status: 'missing' };
   if (fence.hash && sha8(fence.body.trim()) !== fence.hash) return { status: 'hand-edited', stampedVersion: fence.version };
+  const bodyCurrent = sha8(fence.body.trim()) === INSTRUCTIONS_HASH;
+  const stampConsistent = !fence.hash || fence.hash === INSTRUCTIONS_HASH;
+  if (bodyCurrent && stampConsistent) {
+    // Owned dedicated files are OURS wholesale — frontmatter included. Compare the
+    // whole file modulo the stamp line so a frontmatter strip/flip reads as drift.
+    if (frontmatter !== null) {
+      const norm = (s) => String(s).replace(STAMP_RE, '<STAMP>').replace(/\r\n/g, '\n').trim();
+      const expected = (frontmatter ? frontmatter + '\n' : '') + fencedBlock(version) + '\n';
+      if (norm(raw) !== norm(expected)) return { status: 'hand-edited', stampedVersion: fence.version || null, why: 'frontmatter/layout drifted' };
+    }
+    return { status: 'ok', stampedVersion: fence.version || null };
+  }
   if (!fence.version) return { status: 'stale', stampedVersion: null };
   if (cmpSemver(fence.version, version) < 0) return { status: 'stale', stampedVersion: fence.version };
   return { status: 'ok', stampedVersion: fence.version };
@@ -120,6 +152,10 @@ function classifyFenced(file, version) {
 // Shared markdown (AGENTS.md, copilot-instructions.md, GEMINI.md): merge our fenced
 // block in place, preserving the user's own prose outside the fence.
 function fenceMerge(file, version) {
+  // Zero-touch IFF the audit says 'ok' (same classifier, so check and write can
+  // never disagree): current+consistent block → byte-identical file, no stamp-only
+  // churn; a hand-edited stamp or stale body falls through and gets rebuilt.
+  if (classifyFenced(file, version).status === 'ok') return { action: 'unchanged' };
   let cur = '';
   let had = false;
   if (exists(file)) { cur = fs.readFileSync(file, 'utf8'); had = true; }
@@ -136,9 +172,11 @@ function fenceMerge(file, version) {
 
 // Owned dedicated rules file: rewrite wholesale (optional frontmatter for always-apply).
 function writeDedicated(file, frontmatter, version) {
-  const body = (frontmatter ? frontmatter + '\n' : '') + fencedBlock(version) + '\n';
+  // Zero-touch IFF the audit says 'ok' — which for owned dedicated files includes
+  // the frontmatter (a stripped alwaysApply/trigger MUST be repaired, not skipped).
+  if (classifyFenced(file, version, frontmatter || '').status === 'ok') return { action: 'unchanged' };
   const had = exists(file);
-  if (had && fs.readFileSync(file, 'utf8') === body) return { action: 'unchanged' };
+  const body = (frontmatter ? frontmatter + '\n' : '') + fencedBlock(version) + '\n';
   ensureDir(file); fs.writeFileSync(file, body, 'utf8');
   return { action: had ? 'updated' : 'created' };
 }
@@ -219,7 +257,7 @@ export function linkProject(projectDir, opts = {}) {
 
   const rules = t.rules.map((r) => {
     const file = relFile(projectDir, r.file);
-    if (check) return { tool: r.tool, file, ...classifyFenced(r.file, version) };
+    if (check) return { tool: r.tool, file, ...classifyFenced(r.file, version, r.kind === 'dedicated' ? (r.frontmatter || '') : null) };
     const res = r.kind === 'merge' ? fenceMerge(r.file, version) : writeDedicated(r.file, r.frontmatter, version);
     return { tool: r.tool, file, ...res };
   });

package/src/global-brain-hook.mjs

@@ -268,7 +268,11 @@ function releaseLock(lockPath) { try { fs.unlinkSync(lockPath); } catch { /* */
 // self-pruning (a lane unseen for FRESH_MS is gone). Sibling of the registry/health
 // sidecars; same ~/.claude/project-brain home, same acquireLock/never-throw rules.
 const SESSIONS_DIR = path.join(os.homedir(), '.claude', 'project-brain', 'sessions');
-const SESSIONS_FILE = path.join(SESSIONS_DIR, `${sha(normBrainPath(BRAIN))}.json`); // one lane-file per PROJECT (shared by its concurrent sessions)
+// Lane key: canonicalize (on-disk casing + symlinks) BEFORE hashing, so an MCP
+// server that resolved the SAME brain via a differently-cased cwd / KLYPIX_BRAIN
+// lands in the SAME lane file — klypix-core.mjs laneFileFor mirrors this exactly.
+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';
 const SESSION_FRESH_MS = 10 * 60 * 1000;   // a lane unseen for 10min is treated as ended
 const safeGit = (args, timeout = 1500) => { try { return execSync(`git ${args}`, { cwd: CWD, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout }); } catch { return ''; } };
@@ -377,8 +381,34 @@ function msgTargetsMe(m, me, sid) {
     if (!to || to === 'all' || to === '*') return true;
     return [String(sid || '').slice(0, 8), me?.branch || '', me?.intent || ''].join(' ').toLowerCase().includes(to);
 }
+// Self-echo guard for the MCP twin (brain_message): an MCP-posted note carries the
+// CLIENT name as `from` (the server has no session identity), so messageFooter's
+// `from !== sid` can't exclude the sender. The sender's own transcript DOES contain
+// the tool_use, though — scan its tail for brain_message inputs and return their
+// texts so the footer can drop (and ack) the session's own sends. Best-effort.
+function ownMcpSendTexts(tp) {
+    try {
+        if (!tp || !fs.existsSync(tp)) return new Set();
+        const buf = fs.readFileSync(tp);
+        const s = buf.length > 2_000_000 ? buf.toString('utf8', buf.length - 2_000_000) : buf.toString('utf8');
+        if (!s.includes('brain_message')) return new Set();
+        const out = new Set();
+        for (const ln of s.split('\n')) {
+            if (!ln.includes('brain_message')) continue;
+            let e; try { e = JSON.parse(ln); } catch { continue; }
+            const c = e?.message?.content;
+            if (!Array.isArray(c)) continue;
+            for (const b of c) {
+                if (b?.type === 'tool_use' && /brain_message$/.test(String(b.name || '')) && b.input?.text) {
+                    out.add(String(b.input.text).trim().slice(0, 400));
+                }
+            }
+        }
+        return out;
+    } catch { return new Set(); }
+}
 // Surface unseen messages addressed to me, mark them seen (delivered once) under lock.
-function messageFooter(sid) {
+function messageFooter(sid, tp) {
     if (!sid) return '';
     let data = {}; try { data = JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8')); } catch { return ''; }
     const all = Array.isArray(data.messages) ? data.messages : [];
@@ -388,10 +418,12 @@ function messageFooter(sid) {
     const unseen = all.filter(m => m && (now - (m.ts || 0) < MSG_FRESH_MS) && m.from !== sid
         && !(Array.isArray(m.seen) && m.seen.includes(sid)) && msgTargetsMe(m, me, sid));
     if (!unseen.length) return '';
+    const own = ownMcpSendTexts(tp);
+    const show = own.size ? unseen.filter(m => !own.has(String(m.text || '').trim().slice(0, 400))) : unseen;
     const got = acquireLock(SESSIONS_LOCK, { tries: 15, waitMs: 25 });   // ack under lock so a peer read can't lose it
     try {
         let d2 = {}; try { d2 = JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8')); } catch { /* */ }
-        const ids = new Set(unseen.map(u => u.id));
+        const ids = new Set(unseen.map(u => u.id));   // ack self-sent notes too — they must never resurface here
         for (const m of (Array.isArray(d2.messages) ? d2.messages : [])) {
             if (!ids.has(m.id)) continue;
             if (!Array.isArray(m.seen)) m.seen = [];
@@ -399,9 +431,10 @@ function messageFooter(sid) {
         }
         fs.writeFileSync(SESSIONS_FILE, JSON.stringify(d2));
     } catch { /* */ } finally { if (got) releaseLock(SESSIONS_LOCK); }
+    if (!show.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)'];
-    for (const m of unseen.slice(0, 6)) out.push(`- from ${String(m.from || '?').slice(0, 8)} · ${ago(m.ts)}: ${String(m.text).replace(/\s+/g, ' ').trim().slice(0, 200)}`);
+    for (const m of show.slice(0, 6)) out.push(`- from ${String(m.from || '?').slice(0, 8)} · ${ago(m.ts)}: ${String(m.text).replace(/\s+/g, ' ').trim().slice(0, 400)}`);
     out.push('Reply with `🧠 MSG [<their-id or all>]: <text>` — it reaches them on their next prompt.');
     return '\n' + out.join('\n');
 }
@@ -1032,7 +1065,10 @@ async function refreshAgentsBrief(lib, buffer) {
     const agentsPath = path.resolve(CWD, 'AGENTS.md');
     if (!fs.existsSync(agentsPath) || typeof lib.structToBrief !== 'function') return;
     const { struct } = await lib.parseKlypix(buffer);
-    const brief = lib.structToBrief(struct, { recentDays: 7, maxRecent: 10, maxMilestones: 3, maxConnections: 5 }).trim();
+    // detailRecent: 0 — this block is committed into adopters' AGENTS.md and read
+    // by every hookless agent each session; it stays headlines-only by contract
+    // (the SessionStart brief is where the detailed-newest tier lives).
+    const brief = lib.structToBrief(struct, { recentDays: 7, maxRecent: 10, maxMilestones: 3, maxConnections: 5, detailRecent: 0 }).trim();
     const START = '<!-- klypix-brain-brief:start -->', END = '<!-- klypix-brain-brief:end -->';
     const block = `${START}\n<!-- auto-refreshed by the brain hook on capture · headlines only · full cards via the klypix-canvas MCP -->\n${brief}\n${END}`;
     const txt = fs.readFileSync(agentsPath, 'utf8');
@@ -1107,7 +1143,7 @@ async function promptRetrieve(lib) {
     // Other live sessions in THIS repo — surfaced even when the prompt retrieves
     // nothing (a peer's presence/ship is itself the signal). Empty string when solo.
     const peers = peerFooter(sid);
-    const messages = messageFooter(sid);   // 📨 deliberate notes another session left for me (delivered once)
+    const messages = messageFooter(sid, input.transcript_path);   // 📨 deliberate notes another session left for me (delivered once)
     let hits = [], repeats = [], struct = null;
     if (tokens.length) {
         struct = await cachedStruct(lib);
@@ -1419,7 +1455,7 @@ async function read(lib) {
         : lib.structToMarkdown(struct);
     // ⚡ In-flight footer goes RIGHT AFTER the brief (highest signal: what a peer
     // shipped seconds ago, before it's in the brain) — closes the 1.3.17-blindness gap.
-    process.stdout.write(outStr + inflightFooter(input.session_id, struct) + selfHealFooter(drifted) + reconcileFooter(lib, struct) + staleOpenFooter(lib, struct) + selfCheckFooter() + doctorFooter() + versionCurrencyFooter() + messageFooter(input.session_id || '') + legendFooter() + memoryFooter());
+    process.stdout.write(outStr + inflightFooter(input.session_id, struct) + selfHealFooter(drifted) + reconcileFooter(lib, struct) + staleOpenFooter(lib, struct) + selfCheckFooter() + doctorFooter() + versionCurrencyFooter() + messageFooter(input.session_id || '', input.transcript_path) + legendFooter() + memoryFooter());
     // Heartbeat: prove the brief actually injected (and how big) so a dead or
     // stale live-copy of the hook stops being a silent no-op.
     appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'read', ok: true, briefBytes: Buffer.byteLength(outStr), cards: struct?.counts?.cards ?? null }, 500);

package/src/klypix-core.mjs

@@ -456,7 +456,7 @@ export async function opBrainGarden({ vault, canvas, apply = false, syntheses })
     if (!stats.synthCards) return { blocks: [text(`No areas consolidated — each synthesis \`title\` must match a dry-run area title exactly.${skippedNote}`)] };
     let out = buffer; try { out = (await tidyBrain(buffer)).buffer; } catch { /* keep apply result if tidy fails */ }
     await atomicWrite(file, out);
-    return { blocks: [text(`🌿 Gardened ${stats.areas} area(s): ${stats.archived} old card(s) → ${stats.synthCards} synthesis card(s); originals archived with "consolidated into" arrows (any prose-dropped figures appended verbatim). Reopen the brain in KLYPIX to see it.${skippedNote}`)] };
+    return { blocks: [text(`🌿 Gardened ${stats.areas} area(s): ${stats.archived} old card(s) → ${stats.synthCards} synthesis card(s); originals archived with "consolidated into" arrows (any prose-dropped figures appended verbatim). Reopen the brain in the KLYPIX app to see it.${skippedNote}`)] };
   } catch (e) {
     return err(`Garden apply failed (brain unchanged): ${e.message}`);
   }
@@ -530,7 +530,7 @@ export async function opCreateCanvas({ vault, title, cards, connections, filenam
     let detail = '', struct;
     try { ({ struct } = await parseKlypix(buf)); detail = cardDetailBlock(struct); } catch { /* detail is optional */ }
     return {
-      blocks: [text(`Created ${out} — ${cards.length} cards, ${(connections || []).length} connections. Open it in KLYPIX (Canvas → Open).${detail}`)],
+      blocks: [text(`Created ${out} — ${cards.length} cards, ${(connections || []).length} connections. Open it in the KLYPIX app (Canvas → Open).${detail}`)],
       file: { name, buffer: buf }, struct,
     };
   } catch (e) {
@@ -555,7 +555,7 @@ export async function opAddToCanvas({ vault, canvas, cards, connections, via })
       detail = cardDetailBlock(struct, new Set(struct.cards.map(c => c.id).filter(id => !beforeIds.has(id))));
     } catch { /* detail is optional */ }
     return {
-      blocks: [text(`Added ${cards.length} card(s) to ${path.relative(vault, file)}. Reopen the canvas in KLYPIX to see them.${detail}`)],
+      blocks: [text(`Added ${cards.length} card(s) to ${path.relative(vault, file)}. Reopen the canvas in the KLYPIX app to see them.${detail}`)],
       file: { name: path.basename(file), buffer: buf }, struct,
     };
   } catch (e) {
@@ -587,11 +587,79 @@ export async function opBrainNote({ vault, canvas, text: noteText, area, marker
     for (const k of ['resolved', 'updated', 'closed', 'superseded', 'linked']) if (s[k]) bits.push(`${s[k]} ${k}`);
     // Name the resolved brain explicitly (basename + how) so a write never lands
     // in a surprise file silently — the write-side twin of the read-op stamp.
-    return { blocks: [text(`✓ brain_note → ${path.basename(file)} (via ${t.how}) · ${bits.join(' · ')}. Reopen the brain in KLYPIX to see it.`)] };
+    return { blocks: [text(`✓ brain_note → ${path.basename(file)} (via ${t.how}) · ${bits.join(' · ')}. Reopen the brain in the KLYPIX app to see it.`)] };
   } catch (e) {
     return err(`brain_note failed (brain unchanged): ${e.message}`);
   }
 }
 
+// ── brain_message — the MCP twin of the hook's 🧠 MSG marker ─────────────────
+// A DELIBERATE one-time note to the OTHER live agent sessions on this project
+// ("merged the hook refactor — rebase before you commit"), delivered once to each
+// peer at its next prompt via the per-project coordination lane. Hook agents send
+// these by emitting `🧠 MSG [to]: text`; this op gives HOOKLESS clients (Cursor /
+// Cline / Windsurf / Desktop) the same send path. Ephemeral (24h), NOT a brain
+// card — durable decisions go through brain_note.
+//
+// The lane primitives below MUST byte-match src/global-brain-hook.mjs (sha-16 of
+// normBrainPath(brain), sessions/<key>.json layout, MSG_FRESH_MS, the wx-lockfile) —
+// the hook is the READER of what we post. test/lane-message.mjs drives the REAL
+// hook over a message posted by this op; if the two implementations drift, it fails.
+const laneSha16 = (s) => crypto.createHash('sha1').update(String(s)).digest('hex').slice(0, 16);
+const laneNormBrainPath = (p) => String(p).replace(/\\/g, '/').replace(/^[a-zA-Z]:/, (m) => m.toLowerCase());
+const LANE_MSG_FRESH_MS = 24 * 60 * 60 * 1000;   // messages expire after a day
+const LANE_SESSION_FRESH_MS = 10 * 60 * 1000;    // a lane unseen for 10min is treated as ended
+// Canonicalize (on-disk casing + symlinks) before hashing — the hook does the same,
+// so a brain resolved via a differently-cased cwd/KLYPIX_BRAIN still lands in the
+// hook's lane file instead of a silently-unread sibling.
+const laneCanon = (p) => { try { return fs.realpathSync.native(p); } catch { return path.resolve(p); } };
+const laneFileFor = (brainAbs) => path.join(os.homedir(), '.claude', 'project-brain', 'sessions', `${laneSha16(laneNormBrainPath(laneCanon(brainAbs)))}.json`);
+const laneSleep = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* */ } };
+function laneLock(lockPath, tries = 20, waitMs = 25) {
+  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 > 15000) { fs.unlinkSync(lockPath); continue; } } catch { /* lost a race — retry */ }
+      laneSleep(waitMs);
+    }
+  }
+  return false;   // contended → write best-effort (same contract as the hook)
+}
+
+export async function opBrainMessage({ vault, canvas, text: msgText, to, via }) {
+  const t = brainTarget(vault, canvas);
+  if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
+  if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
+  const txt = String(msgText || '').trim();
+  if (!txt) return err('brain_message needs a non-empty text.');
+  const laneFile = laneFileFor(t.file);
+  const lock = laneFile + '.lock';
+  const now = Date.now();
+  const msg = {
+    id: laneSha16('mcp|' + txt + '|' + now + '|' + Math.random()),
+    from: via ? String(via).replace(/\s+/g, '-').slice(0, 24) : 'mcp',
+    // 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: [],
+  };
+  const got = laneLock(lock);
+  let live = 0;
+  try {
+    let data = {}; try { data = JSON.parse(fs.readFileSync(laneFile, 'utf8')); } catch { /* fresh lane */ }
+    const sessions = Array.isArray(data.sessions) ? data.sessions : [];
+    live = sessions.filter(s => s && s.id && now - (s.lastSeen || 0) < LANE_SESSION_FRESH_MS).length;
+    const kept = (Array.isArray(data.messages) ? data.messages : []).filter(m => m && now - (m.ts || 0) < LANE_MSG_FRESH_MS);
+    kept.push(msg);
+    fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+    fs.writeFileSync(laneFile, JSON.stringify({ sessions, messages: kept.slice(-30) }));
+  } catch (e) {
+    return err(`brain_message failed: ${e.message}`);
+  } finally { if (got) { try { fs.unlinkSync(lock); } catch { /* */ } } }
+  return { blocks: [text(`📨 posted to this project's coordination lane (to: ${msg.to}) — ${live} live hook-wired session(s) right now; each sees it once at its next prompt. Hookless clients can send but not receive. Ephemeral (24h), not a brain card — use brain_note for durable decisions.`)] };
+}
+
 // Re-export the format helpers the bins need for non-op work (init onboarding).
 export { buildKlypixMap, parseKlypix };

package/src/klypix-format.mjs

@@ -561,7 +561,7 @@ export async function tidyBrain(buffer) {
 // decisions + milestones. Everything older stays in the file, reachable via the
 // klypix-canvas MCP search or `--full`. Keeps the session-start cost flat as
 // the brain grows (the full markdown scales with history; this doesn't).
-export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMilestones = 8, maxConnections = 30, maxSkills = 24, freshness = null } = {}) {
+export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMilestones = 8, maxConnections = 30, maxSkills = 24, detailRecent = 8, freshness = null } = {}) {
     const cutoff = Date.now() - recentDays * 86_400_000;
     const texts = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim());
     const containers = struct.cards.filter(c => c.type === 'container');
@@ -593,18 +593,33 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     const fr = (c) => (freshness && freshness[c.id]) ? freshness[c.id] + ' ' : '';
     // HEADLINE = first sentence-ish, hard-capped — the brief is a scannable
     // changelog; the agent pulls any card's full text via the MCP when needed.
+    // Hard cuts must not split a UTF-16 surrogate pair (an emoji straddling the cap
+    // would serialize as U+FFFD in the brief / AGENTS.md).
+    const safeCut = (t, n) => { let s = t.slice(0, n); if (/[\uD800-\uDBFF]$/.test(s)) s = s.slice(0, -1); return s.trimEnd() + '…'; };
     const headline = (c, max = 160) => {
         const t = flat(c.text);
         const stop = t.search(/(?<=[.!?])\s/);
         const h = stop > 40 && stop < max ? t.slice(0, stop) : t;
-        return h.length > max ? h.slice(0, max - 1).trimEnd() + '…' : h;
+        return h.length > max ? safeCut(h, max - 1) : h;
+    };
+    // EXCERPT = the first few sentences, cut at the last sentence boundary under the
+    // cap. The newest `detailRecent` decisions get this instead of a headline: the
+    // recall eval showed detail questions about the freshest cards are exactly what a
+    // 160-char headline loses (status, resolution, the "what exactly shipped").
+    const excerpt = (c, max = 420) => {
+        const t = flat(c.text);
+        if (t.length <= max) return t;
+        let cut = -1;
+        const re = /(?<=[.!?])\s/g; let m;
+        while ((m = re.exec(t)) && m.index < max) cut = m.index;
+        return cut > 120 ? t.slice(0, cut) : safeCut(t, max - 1);
     };
     const day = (ts) => ts ? new Date(ts).toISOString().slice(0, 10) : '';
 
     // TOKEN BUDGET (≈ chars/4): sections are added in priority order — Focus,
     // Open, Areas, Milestones, Recent, Connections — and Recent stops when the
     // budget is hit. The brief stays ~flat forever no matter how active a week.
-    const BUDGET_CHARS = 11_000; // ≈ 2.7k tokens
+    const BUDGET_CHARS = 13_500; // ≈ 3.3k tokens (raised for the detailed-newest tier; still hard-capped/flat)
     let used = 0;
     const out = [];
     const push = (...lines) => { for (const l of lines) { out.push(l); used += l.length + 1; } };
@@ -635,10 +650,20 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     }
     let shownRecent = 0;
     if (recent.length) {
-        push('', `## Recent decisions (last ${recentDays}d — headlines)`);
+        push('', `## Recent decisions (last ${recentDays}d — newest first in detail, rest headlines)`);
+        // Detail tier FIRST (recent is newest-first), so the budget can never be
+        // eaten by older headlines before the cards the header promises in detail.
+        const detail = recent.slice(0, detailRecent);
+        for (const c of detail) {
+            if (used > BUDGET_CHARS) break;
+            push(`- ${fr(c)}[${flat(c.area) || 'Notes'}] ${day(c.createdAt)} ${excerpt(c)}`);
+            shownRecent++;
+        }
+        const rest = recent.slice(detailRecent);
         const byArea = new Map();
-        for (const c of recent) { const a = flat(c.area) || 'Notes'; if (!byArea.has(a)) byArea.set(a, []); byArea.get(a).push(c); }
+        for (const c of rest) { const a = flat(c.area) || 'Notes'; if (!byArea.has(a)) byArea.set(a, []); byArea.get(a).push(c); }
         outer: for (const [a, cs] of byArea) {
+            if (used > BUDGET_CHARS) break;
             push(`### ${a}`);
             for (const c of cs) {
                 if (used > BUDGET_CHARS) break outer;