klypix-mcp 1.10.1 → 1.12.0

package/bin/klypix-link.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// klypix-link — make THIS project's brain automatic for EVERY agent tool.
+// `npx klypix-mcp install` gives Claude Code the brain via hooks; `link` extends the
+// same automatic read+capture to Cursor, Cline, Windsurf, Copilot/VS Code, and any
+// AGENTS.md-reading agent, by dropping each tool's native MCP config + rules file in
+// the current project. Idempotent — re-run anytime to refresh. Project-scoped (cwd);
+// touches only files inside the project. Reports what it did; exits non-zero on hard fail.
+//
+//   cd your-project && npx klypix-mcp link
+//
+// Synchronous top-level by design: the dispatcher does `await import(this); process.exit(0)`,
+// so all work (and its logs) must complete during module evaluation, before exit.
+import path from 'path';
+import { linkProject } from '../src/agent-rules.mjs';
+
+try {
+  const dirArg = process.argv.slice(3).find(a => !a.startsWith('-'));
+  const projectDir = path.resolve(dirArg || process.cwd());
+  const { rules, mcp, hasBrain } = linkProject(projectDir);
+
+  const mark = (a) => a === 'unchanged' ? '·' : a === 'skipped' ? '⚠' : '✓';
+  console.log(`klypix — linking the brain to every agent tool in ${projectDir}\n`);
+  console.log('  MCP server (so each tool can reach the brain):');
+  for (const r of mcp) console.log(`    ${mark(r.action)} ${r.tool.padEnd(26)} ${r.file}${r.why ? '  (' + r.why + ')' : ''}`);
+  console.log('\n  Rules (so each tool auto-reads + captures the brain):');
+  for (const r of rules) console.log(`    ${mark(r.action)} ${r.tool.padEnd(26)} ${r.file}${r.why ? '  (' + r.why + ')' : ''}`);
+
+  const changed = [...rules, ...mcp].filter(r => r.action && !['unchanged', 'skipped'].includes(r.action)).length;
+  console.log(`\n✓ ${changed} file(s) written/updated — every agent opened in this project now reads + captures ./brain.klypix.`);
+  console.log('  Cline & Windsurf MCP servers live in their global config; the rules file points them at the brain regardless.');
+  if (!hasBrain) {
+    console.log('\n⚠ No ./brain.klypix here yet — the rules reference it for when you create one.');
+    console.log('  Make one in the KLYPIX app (Canvas → Save as brain) or with the create_canvas MCP tool.');
+  }
+} catch (e) {
+  console.error(`✗ link failed: ${e?.message || e}`);
+  process.exit(1);
+}

package/bin/klypix-mcp.mjs

@@ -41,6 +41,12 @@ const log = (...a) => console.error('[klypix-mcp]', ...a);
 // server setup; delegates to the dedicated bin so `npx klypix-install` also works.
 if (process.argv[2] === 'install') { await import('./klypix-install.mjs'); process.exit(0); }
 
+// `npx klypix-mcp link` — make THIS project's brain automatic for EVERY agent tool,
+// not just Claude Code: drop each tool's native MCP config + rules file (Cursor, Cline,
+// Windsurf, Copilot/VS Code, AGENTS.md) so any agent opened here reads + captures the
+// brain on its own. Project-scoped (cwd); idempotent. Runs before any server setup.
+if (process.argv[2] === 'link') { await import('./klypix-link.mjs'); process.exit(0); }
+
 // `npx klypix-mcp init` — 60-second onboarding: seed a starter project brain in
 // the current folder so a new user's FIRST contact isn't an empty vault, then
 // print a paste-ready MCP config. Runs before any server setup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.10.1",
+  "version": "1.12.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",
@@ -26,6 +26,7 @@
   },
   "bin": {
     "klypix-mcp": "bin/klypix-mcp.mjs",
+    "klypix-link": "bin/klypix-link.mjs",
     "klypix-a2a": "bin/klypix-a2a.mjs",
     "klypix-read": "bin/klypix-read.mjs",
     "klypix-write": "bin/klypix-write.mjs",

package/src/agent-rules.mjs

@@ -0,0 +1,126 @@
+// agent-rules — make a project's brain.klypix AUTOMATIC for EVERY agent tool, not
+// just Claude Code. Claude Code gets the brain via hooks (settings.json, see
+// klypix-install). Other agents (Cursor, Cline, Windsurf, Copilot/VS Code, and the
+// AGENTS.md cross-tool standard) have no hook system — so we drop their NATIVE files:
+//
+//   • an MCP server config  → the agent CAN reach the brain's tools
+//   • a rules / instructions → the agent is TOLD to read the brain at task start and
+//                              capture decisions, on every session, automatically
+//
+// Agent-neutral by construction: the brain DATA is one shared brain.klypix; this just
+// teaches each tool to use it. Idempotent — owned files are rewritten wholesale; shared
+// files (AGENTS.md, copilot-instructions.md) get a fenced block merged in place, never
+// clobbering the user's own content. Pure fs/path; never throws for one bad target.
+import fs from 'fs';
+import path from 'path';
+
+const FENCE_START = '<!-- klypix-brain:start (managed by klypix-mcp — re-run `npx klypix-mcp link`) -->';
+const FENCE_END = '<!-- klypix-brain:end -->';
+const FENCE_RE = /<!--\s*klypix-brain:start[\s\S]*?klypix-brain:end\s*-->/;
+
+// The one canonical instruction every agent gets. Tool-and-CLI dual so it works whether
+// or not the agent has the klypix-canvas MCP wired.
+const BRAIN_INSTRUCTIONS = `## KLYPIX project brain
+
+This project has a **spatial brain** at \`./brain.klypix\` — the living memory of its
+decisions, open questions, and findings (the shared human↔agent memory for this repo).
+Treat it as authoritative project context.
+
+**At the start of a task — read it** so you know the project's state and past decisions:
+- with the \`klypix-canvas\` MCP server: call \`search_canvases\` / \`read_canvas\` (canvas: \`"brain"\`), or \`brain_insights\` for the load-bearing cards.
+- or via CLI: \`npx klypix-read brain.klypix\`
+
+**When you make a real decision, finding, or milestone — capture it** so it persists for the next session/agent:
+- with MCP: call \`brain_note\` with a one-line decision, or
+- emit a marker line in your output: \`🧠 BRAIN [Area]: <one-line decision>\`, or
+- via CLI: \`echo "🧠 BRAIN [Area]: <decision>" | npx klypix-append brain.klypix\`
+
+Capture **sparingly** — real decisions/milestones, not routine steps. Link related cards with \`[[other-card]]\`.
+
+**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.`;
+
+const fencedBlock = () => `${FENCE_START}\n${BRAIN_INSTRUCTIONS}\n${FENCE_END}`;
+
+const exists = (p) => { try { fs.statSync(p); return true; } catch { return false; } };
+const ensureDir = (p) => fs.mkdirSync(path.dirname(p), { recursive: true });
+
+// Shared markdown (AGENTS.md, copilot-instructions.md): merge our fenced block in place.
+function fenceMerge(file) {
+  let cur = '';
+  let had = false;
+  if (exists(file)) { cur = fs.readFileSync(file, 'utf8'); had = true; }
+  const block = fencedBlock();
+  let next;
+  let action;
+  if (FENCE_RE.test(cur)) { next = cur.replace(FENCE_RE, block); action = 'updated'; }
+  else if (cur.trim()) { next = cur.replace(/\s*$/, '') + '\n\n' + block + '\n'; action = 'merged'; }
+  else { next = block + '\n'; action = had ? 'merged' : 'created'; }
+  if (next === cur) return { action: 'unchanged' };
+  ensureDir(file); fs.writeFileSync(file, next, 'utf8');
+  return { action };
+}
+
+// Owned dedicated rules file: rewrite wholesale (optional frontmatter for always-apply).
+function writeDedicated(file, frontmatter) {
+  const body = (frontmatter ? frontmatter + '\n' : '') + fencedBlock() + '\n';
+  if (exists(file) && fs.readFileSync(file, 'utf8') === body) return { action: 'unchanged' };
+  ensureDir(file); fs.writeFileSync(file, body, 'utf8');
+  return { action: exists(file) ? 'updated' : 'created' };
+}
+
+// Project-level MCP config: add the klypix-canvas server, preserving any sibling servers.
+// wrapKey differs by tool: Cursor/Claude use "mcpServers"; VS Code uses "servers".
+function mergeMcpJson(file, wrapKey, withType) {
+  const entry = withType
+    ? { type: 'stdio', command: 'npx', args: ['-y', 'klypix-mcp', '--vault', '.'] }
+    : { command: 'npx', args: ['-y', 'klypix-mcp', '--vault', '.'] };
+  let cfg = {};
+  if (exists(file)) {
+    const raw = fs.readFileSync(file, 'utf8');
+    if (raw.trim()) { try { cfg = JSON.parse(raw); } catch { return { action: 'skipped', why: 'invalid JSON — left untouched' }; } }
+  }
+  if (!cfg[wrapKey] || typeof cfg[wrapKey] !== 'object' || Array.isArray(cfg[wrapKey])) cfg[wrapKey] = {};
+  const before = JSON.stringify(cfg[wrapKey]['klypix-canvas']);
+  cfg[wrapKey]['klypix-canvas'] = entry;
+  if (JSON.stringify(cfg[wrapKey]['klypix-canvas']) === before) return { action: 'unchanged' };
+  ensureDir(file); fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+  return { action: before === undefined ? 'created' : 'updated' };
+}
+
+/**
+ * Wire a project so EVERY agent tool reads + captures its brain automatically.
+ * @param {string} projectDir absolute project root (holds ./brain.klypix)
+ * @returns {{ rules: Array, mcp: Array, hasBrain: boolean }}
+ */
+export function linkProject(projectDir) {
+  const j = (...p) => path.join(projectDir, ...p);
+  const hasBrain = exists(j('brain.klypix')) || exists(j('brain.any'));
+
+  // ── Rules / instructions (the "automatically use the brain" half) ──────────────
+  const rules = [
+    // AGENTS.md — the emerging cross-tool standard (Codex, Jules, Zed, Cursor-also-reads…)
+    { tool: 'AGENTS.md (cross-tool standard)', file: 'AGENTS.md', ...fenceMerge(j('AGENTS.md')) },
+    // Cursor — dedicated always-applied rule
+    { tool: 'Cursor', file: '.cursor/rules/klypix-brain.mdc', ...writeDedicated(j('.cursor', 'rules', 'klypix-brain.mdc'),
+      '---\ndescription: KLYPIX project brain — read at task start, capture decisions\nalwaysApply: true\n---') },
+    // Windsurf — dedicated always-on rule
+    { tool: 'Windsurf', file: '.windsurf/rules/klypix-brain.md', ...writeDedicated(j('.windsurf', 'rules', 'klypix-brain.md'),
+      '---\ntrigger: always_on\n---') },
+    // Cline — drops a file in .clinerules/ (Cline reads every file there)
+    { tool: 'Cline', file: '.clinerules/klypix-brain.md', ...writeDedicated(j('.clinerules', 'klypix-brain.md'), '') },
+    // GitHub Copilot — repo-wide custom instructions
+    { tool: 'GitHub Copilot', file: '.github/copilot-instructions.md', ...fenceMerge(j('.github', 'copilot-instructions.md')) },
+  ];
+
+  // ── MCP server config (the "can reach the brain's tools" half) ─────────────────
+  // Project-level files only; Claude Code is covered by `install` (hooks + bundled MCP),
+  // so we skip .mcp.json to avoid double-registering its server.
+  const mcp = [
+    { tool: 'Cursor', file: '.cursor/mcp.json', ...mergeMcpJson(j('.cursor', 'mcp.json'), 'mcpServers', false) },
+    { tool: 'VS Code (Copilot/Continue)', file: '.vscode/mcp.json', ...mergeMcpJson(j('.vscode', 'mcp.json'), 'servers', true) },
+  ];
+
+  return { rules, mcp, hasBrain };
+}
+
+export { BRAIN_INSTRUCTIONS };

package/src/global-brain-hook.mjs

@@ -278,7 +278,8 @@ function touchSession(sid, patch = {}) {
         const now = Date.now();
         const got = acquireLock(SESSIONS_LOCK, { tries: 20, waitMs: 25 });   // ~0.5s budget then best-effort
         try {
-            const all = pruneSessions(readSessions(), now);
+            let data0 = {}; try { data0 = JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8')); } catch { /* fresh */ }
+            const all = pruneSessions(Array.isArray(data0.sessions) ? data0.sessions : [], now);
             const prev = all.find(s => s.id === sid) || {};
             const list = all.filter(s => s.id !== sid);
             list.push({
@@ -292,7 +293,10 @@ function touchSession(sid, patch = {}) {
                 startedAt: prev.startedAt || now, lastSeen: now,
             });
             fs.mkdirSync(SESSIONS_DIR, { recursive: true });
-            fs.writeFileSync(SESSIONS_FILE, JSON.stringify({ sessions: list.slice(-20) }));
+            // Preserve the messages lane — touchSession runs AFTER postMessages in a
+            // capture, and dropping the field here would clobber a just-posted note.
+            const keptMsgs = (Array.isArray(data0.messages) ? data0.messages : []).filter(m => m && (now - (m.ts || 0) < MSG_FRESH_MS));
+            fs.writeFileSync(SESSIONS_FILE, JSON.stringify({ sessions: list.slice(-20), messages: keptMsgs }));
         } finally { if (got) releaseLock(SESSIONS_LOCK); }
     } catch { /* coordination is best-effort */ }
 }
@@ -335,6 +339,64 @@ function peerFooter(sid) {
     return lines.join('\n');
 }
 
+// ── Brain messaging — async agent↔agent notes via the shared per-project lane ─
+// The COMPLEMENT to the live-ledger: the ledger surfaces a peer's AUTOMATIC high-
+// signal events (ships, version bumps); this lets a session leave a DELIBERATE,
+// TARGETED note for another ("merged the hook refactor — rebase your PR first").
+// SEND by emitting `🧠 MSG [<to>]: <text>` in a reply (to = a peer's id-prefix or
+// branch, omitted = all); the Stop hook posts it to the lane, and the recipient's
+// next prompt/session-start surfaces it ONCE (ack'd under the lane lock). Still
+// async (delivered at the peer's next hook event), by design — not real-time.
+const MSG_RE = /🧠\s*MSG\s*(?:\[([^\]]*)\])?\s*:\s*(.+)$/i;
+const MSG_FRESH_MS = 24 * 60 * 60 * 1000;
+function postMessages(msgs) {
+    if (!msgs || !msgs.length) return;
+    const got = acquireLock(SESSIONS_LOCK, { tries: 20, waitMs: 25 });
+    try {
+        let data = {}; try { data = JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8')); } catch { /* fresh */ }
+        const sessions = Array.isArray(data.sessions) ? data.sessions : [];
+        const now = Date.now();
+        const kept = (Array.isArray(data.messages) ? data.messages : []).filter(m => m && (now - (m.ts || 0) < MSG_FRESH_MS));
+        for (const m of msgs) kept.push(m);
+        fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+        fs.writeFileSync(SESSIONS_FILE, JSON.stringify({ sessions, messages: kept.slice(-30) }));
+    } catch { /* best-effort */ } finally { if (got) releaseLock(SESSIONS_LOCK); }
+}
+// to==='all'/'' → everyone; else the hint must appear in my id-prefix / branch / intent.
+function msgTargetsMe(m, me, sid) {
+    const to = String(m.to || '').trim().toLowerCase();
+    if (!to || to === 'all' || to === '*') return true;
+    return [String(sid || '').slice(0, 8), me?.branch || '', me?.intent || ''].join(' ').toLowerCase().includes(to);
+}
+// Surface unseen messages addressed to me, mark them seen (delivered once) under lock.
+function messageFooter(sid) {
+    if (!sid) return '';
+    let data = {}; try { data = JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8')); } catch { return ''; }
+    const all = Array.isArray(data.messages) ? data.messages : [];
+    if (!all.length) return '';
+    const now = Date.now();
+    const me = (Array.isArray(data.sessions) ? data.sessions : []).find(s => s.id === 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 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));
+        for (const m of (Array.isArray(d2.messages) ? d2.messages : [])) {
+            if (!ids.has(m.id)) continue;
+            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 { if (got) releaseLock(SESSIONS_LOCK); }
+    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)}`);
+    out.push('Reply with `🧠 MSG [<their-id or all>]: <text>` — it reaches them on their next prompt.');
+    return '\n' + out.join('\n');
+}
+
 // Pull assistant text out of one transcript line (Claude Code JSONL: content is
 // a string or an array of {type:'text',text}).
 function textOf(entry) {
@@ -755,6 +817,8 @@ async function capture(lib) {
     const resolutions = [];
     const updates = [];
     const ledger = [];   // one entry per marker decision (observability)
+    const messages = [];                 // 🧠 MSG markers → posted to the per-project lane
+    const sid = input.session_id || '';
     // Rolling set of the most-recently-touched file/dir tags (deduped, newest
     // last). A marker emitted after some edits gets tagged with the files that
     // work touched — captured by scanning EVERY entry's tool_use, not just the
@@ -776,7 +840,15 @@ async function capture(lib) {
         const text = textOf(e);
         if (!text.includes('🧠')) continue;
         for (const raw of text.split('\n')) {
-            const m = MARKER.exec(raw.trim()); if (!m) continue;
+            const trimmed = raw.trim();
+            // 🧠 MSG [to]: text — an async note to another session (not a brain card).
+            const mg = MSG_RE.exec(trimmed);
+            if (mg) {
+                const txt = (mg[2] || '').trim();
+                if (txt) messages.push({ id: sha(sid + '|' + txt + '|' + Date.now() + '|' + Math.random()), from: sid, to: (mg[1] || '').trim() || 'all', text: txt.slice(0, 400), ts: Date.now(), seen: [] });
+                continue;
+            }
+            const m = MARKER.exec(trimmed); if (!m) continue;
             const area = (m[1] || '').trim(), type = m[2] || '';
             let body = m[3].trim(); if (!body) continue;
             // Strip optional `closes:` / `ev:` suffixes off the body so they don't
@@ -833,6 +905,7 @@ async function capture(lib) {
             ledger.push({ action: type === '?' ? 'add-question' : type === '!' ? 'add-milestone' : isSkill ? 'add-skill' : 'add-decision', area, preview, files: fileTags, ...(closes ? { closes } : {}), ...(evidence ? { ev: evidence.map(e => e.ref) } : {}) });
         }
     }
+    postMessages(messages);   // deliver any 🧠 MSG notes to peers' lanes (even if no cards this turn)
     // Ship-event auto-capture: deterministic high-signal events (PR merges, releases,
     // npm publishes, tags) from SUCCESSFUL shell calls in the transcript — no marker
     // required (the gap a concurrent session hit: 3 releases + 6 PRs → zero cards).
@@ -1015,6 +1088,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)
     let hits = [], repeats = [], struct = null;
     if (tokens.length) {
         struct = await cachedStruct(lib);
@@ -1061,7 +1135,7 @@ async function promptRetrieve(lib) {
     // Other live sessions' in-flight events (struct may be null on a token-less
     // prompt — then representedInBrain just keeps entries; they're rarely in-brain yet).
     const inflight = inflightFooter(sid, struct);
-    if (!repeats.length && !freshHits.length && !peers && !inflight) return; // nothing → zero output, zero added context
+    if (!repeats.length && !freshHits.length && !peers && !inflight && !messages) return; // nothing → zero output, zero added context
     const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
     const day = (ts) => ts ? new Date(ts).toISOString().slice(0, 10) : '';
     const head = (c, n = 120) => { const t = flat(c.text); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
@@ -1086,6 +1160,7 @@ async function promptRetrieve(lib) {
     if (lines.length) parts.push(lines.join('\n'));
     if (inflight) parts.push(inflight.replace(/^\n+/, '')); // ⚡ in-flight peers' events (its own block)
     if (peers) parts.push(peers.replace(/^\n+/, '')); // live-session presence footer (its own block)
+    if (messages) parts.push(messages.replace(/^\n+/, '')); // 📨 inbound deliberate peer notes
     process.stdout.write(parts.join('\n\n') + '\n'); // UserPromptSubmit injects stdout as context
 }
 
@@ -1196,7 +1271,8 @@ function legendFooter() {
     return '\n\n---\n'
         + '🧠 **Capture markers** — write these in your reply; the Stop hook harvests them into the brain (no separate log step). Use sparingly, for real decisions / milestones / discoveries:\n'
         + '`🧠 BRAIN [Area]: decision` · `[Area] ?: open question` · `[Area] !: milestone` · `[Area] +: 🛠️ skill (reusable how-to / gotcha — resurfaces every session, never ages out)` · `[Area] ✓: resolves+archives the matching card` · `[Area] ~: updates it in place` · 🎯 in text = a goal (reads as open).\n'
-        + 'Optional suffixes: `closes: <card title / [[wikilink]]>` (resolve the strategy/question this fulfils) · `ev: <file[:line]>, PR#<n>` (anchor to code → auto drift-badge).\n';
+        + 'Optional suffixes: `closes: <card title / [[wikilink]]>` (resolve the strategy/question this fulfils) · `ev: <file[:line]>, PR#<n>` (anchor to code → auto drift-badge).\n'
+        + 'Coordinate with a concurrent session: `🧠 MSG [<their-id or all>]: <text>` — a one-time note (NOT a brain card) delivered to that session on its next prompt.\n';
 }
 
 async function read(lib) {
@@ -1213,7 +1289,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() + legendFooter() + memoryFooter());
+    process.stdout.write(outStr + inflightFooter(input.session_id, struct) + selfHealFooter(drifted) + reconcileFooter(lib, struct) + staleOpenFooter(lib, struct) + selfCheckFooter() + messageFooter(input.session_id || '') + 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);