klypix-mcp 1.47.0 → 1.49.0

package/bin/klypix-diff.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin bin for `klypix-mcp diff` — the worker dispatcher splices the verb out
+// of argv before importing, so this bin re-supplies it. Standalone use works
+// identically: node bin/klypix-diff.mjs <args>
+import { run } from './klypix-git-tools.mjs';
+await run('diff', process.argv.slice(2));

package/bin/klypix-git-driver.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin bin for `klypix-mcp git-driver` — the worker dispatcher splices the verb out
+// of argv before importing, so this bin re-supplies it. Standalone use works
+// identically: node bin/klypix-git-driver.mjs <args>
+import { run } from './klypix-git-tools.mjs';
+await run('git-driver', process.argv.slice(2));

package/bin/klypix-git-tools.mjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+// klypix-git-tools — the GitHub lane: three verbs that put the brain where
+// dev teams actually live (the repo and the PR page).
+//
+//   git-driver [install|status] [repo]   register the lossless .klypix merge
+//                                        driver for a repo, zero-command
+//   diff [ref] [--brain <path>]          readable brain diff vs a git ref
+//   pr-brief [baseRef] [--brain <path>]  brain cards touching the files
+//                                        changed since baseRef (PR comment)
+//
+// Design rules inherited from the engine:
+//   • ONE merge engine — the driver rides src/merge-brains.mjs verbatim.
+//   • The registered driver path is the INSTALLED runtime
+//     (~/.claude/project-brain) — stable across npx cache evictions; this
+//     module self-provisions the three engine files + their two deps there
+//     when missing, without running the full hook installer.
+//   • A truncated list must NEVER render as complete: every capped section
+//     emits its "…and N more" through an unguarded push.
+//   • Failure is a calm, specific message + non-zero exit — never a stack.
+
+// SHAPE: this is a LIB — the worker dispatcher splices the verb out of argv
+// before importing a verb bin (see runVerb), so each verb has a THIN bin
+// (klypix-git-driver.mjs / klypix-diff.mjs / klypix-pr-brief.mjs) that calls
+// run(<verb>, argv.slice(2)) here. Standalone `node <bin> …` works identically.
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFile } from 'child_process';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.join(HERE, '..', 'src');
+// Overridable for tests (temp dirs only — never point tests at the real one).
+const BRAIN_DIR = process.env.KLYPIX_BRAIN_DIR || path.join(os.homedir(), '.claude', 'project-brain');
+
+let args = [];
+const flag = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+let positional = [];
+
+const git = (cwd, gitArgs, opts = {}) => new Promise((resolve, reject) => {
+  execFile('git', gitArgs, { cwd, timeout: 15000, windowsHide: true, maxBuffer: 128 * 1024 * 1024, ...opts },
+    (err, stdout) => err ? reject(err) : resolve(stdout));
+});
+const gitText = async (cwd, ...a) => String(await git(cwd, a)).trim();
+
+async function repoToplevel(startDir) {
+  try { return await gitText(startDir, 'rev-parse', '--show-toplevel'); }
+  catch { return null; }
+}
+
+function findBrain(explicit) {
+  if (explicit) {
+    const p = path.resolve(explicit);
+    return fs.existsSync(p) ? p : null;
+  }
+  let dir = process.cwd();
+  for (let i = 0; i < 12; i++) {
+    const p = path.join(dir, 'brain.klypix');
+    if (fs.existsSync(p)) return p;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// Card text is stored CANVAS-WRAPPED (single \n ≈ visual line breaks), so a
+// naive first-line is ~35 chars of a sentence. Join the first paragraph back
+// into prose and cap it.
+const firstLine = (t) => {
+  const para = String(t || '').split(/\n\s*\n/)[0].replace(/\s*\n\s*/g, ' ').trim();
+  return para.length > 110 ? `${para.slice(0, 110)}…` : para;
+};
+
+async function loadEngine() {
+  const format = await import(new URL('../src/klypix-format.mjs', import.meta.url).href);
+  const merge = await import(new URL('../src/merge-brains.mjs', import.meta.url).href);
+  return { format, merge };
+}
+
+// ── git-driver ──────────────────────────────────────────────────────────────
+
+const ENGINE_FILES = ['klypix-merge-driver.mjs', 'merge-brains.mjs', 'klypix-format.mjs'];
+const ENGINE_DEPS = ['jszip', 'fractional-indexing'];
+
+// Make sure the INSTALLED runtime can actually run the driver: the three
+// engine files plus their two (dependency-free) deps. This is deliberately a
+// light provision — it never touches hooks or servers; the full installer
+// remains `npx klypix-mcp install`.
+function ensureDriverRuntime() {
+  const provisioned = [];
+  fs.mkdirSync(BRAIN_DIR, { recursive: true });
+  for (const f of ENGINE_FILES) {
+    const dest = path.join(BRAIN_DIR, f);
+    const srcFile = path.join(SRC, f);
+    if (!fs.existsSync(dest) || fs.readFileSync(dest, 'utf8') !== fs.readFileSync(srcFile, 'utf8')) {
+      fs.copyFileSync(srcFile, dest);
+      provisioned.push(f);
+    }
+  }
+  const requireHere = createRequire(import.meta.url);
+  // Modern packages fence `exports`, so `<dep>/package.json` may not resolve —
+  // resolve the MAIN entry instead and walk up to the package root.
+  const depRootOf = (dep) => {
+    let p = path.dirname(requireHere.resolve(dep));
+    for (let i = 0; i < 6; i++) {
+      const pkg = path.join(p, 'package.json');
+      try {
+        if (fs.existsSync(pkg) && JSON.parse(fs.readFileSync(pkg, 'utf8')).name === dep) return p;
+      } catch { /* keep walking */ }
+      const up = path.dirname(p);
+      if (up === p) break;
+      p = up;
+    }
+    throw new Error(`cannot locate package root for dependency "${dep}"`);
+  };
+  const destMods = path.join(BRAIN_DIR, 'node_modules');
+  // Deps are provisioned as their RECURSIVE closure (jszip alone pulls pako,
+  // lie, readable-stream, …) — everything resolves from the local install, so
+  // this stays offline and deterministic. Nested (unhoisted) deps resolve via
+  // a require scoped to their parent package.
+  const provisionDep = (dep, fromDir, seen) => {
+    if (seen.has(dep)) return;
+    seen.add(dep);
+    let root;
+    try { root = depRootOf(dep); }
+    catch {
+      const scoped = createRequire(path.join(fromDir, 'package.json'));
+      let p = path.dirname(scoped.resolve(dep));
+      while (p !== path.dirname(p) && !fs.existsSync(path.join(p, 'package.json'))) p = path.dirname(p);
+      root = p;
+    }
+    const destDir = path.join(destMods, dep);
+    if (!fs.existsSync(destDir)) {
+      // Exclude only node_modules NESTED INSIDE the package (the closure walk
+      // provisions those flat) — judged relative to the package root, because
+      // the source root itself lives under a node_modules path.
+      fs.cpSync(root, destDir, {
+        recursive: true,
+        filter: (s) => !path.relative(root, s).split(path.sep).includes('node_modules'),
+      });
+      provisioned.push(`node_modules/${dep}`);
+    }
+    let pkg = {};
+    try { pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { /* leaf */ }
+    for (const child of Object.keys(pkg.dependencies || {})) provisionDep(child, root, seen);
+  };
+  const seen = new Set();
+  for (const dep of ENGINE_DEPS) provisionDep(dep, path.join(HERE, '..'), seen);
+  return provisioned;
+}
+
+const DRIVER_ATTR_RULE = '*.klypix merge=klypix -text';
+
+async function gitDriver() {
+  const sub = positional[0] && !fs.existsSync(positional[0]) ? positional[0] : 'install';
+  const repoArg = positional.find(p => fs.existsSync(p)) || process.cwd();
+  const toplevel = await repoToplevel(repoArg);
+  if (!toplevel) { console.error(`Not a git repository: ${repoArg}`); process.exit(1); }
+
+  const driverPath = path.join(BRAIN_DIR, 'klypix-merge-driver.mjs');
+  const driverCmd = `node "${driverPath.replace(/\\/g, '/')}" %O %A %B %P`;
+  const gaPath = path.join(toplevel, '.gitattributes');
+  const gaText = fs.existsSync(gaPath) ? fs.readFileSync(gaPath, 'utf8') : '';
+  const gaHasRule = /merge=klypix/.test(gaText);
+
+  if (sub === 'status') {
+    let configured = '';
+    try { configured = await gitText(toplevel, 'config', '--get', 'merge.klypix.driver'); } catch { /* unset */ }
+    const runtimeOk = ENGINE_FILES.every(f => fs.existsSync(path.join(BRAIN_DIR, f)));
+    console.log(`repo:          ${toplevel}`);
+    console.log(`driver config: ${configured || '(not registered)'}`);
+    console.log(`.gitattributes rule: ${gaHasRule ? 'present' : 'missing'}`);
+    console.log(`installed runtime:   ${runtimeOk ? BRAIN_DIR : 'missing — run: npx klypix-mcp git-driver install'}`);
+    process.exit(configured && gaHasRule && runtimeOk ? 0 : 1);
+  }
+
+  const provisioned = ensureDriverRuntime();
+  let already = false;
+  try { already = (await gitText(toplevel, 'config', '--get', 'merge.klypix.driver')) === driverCmd; } catch { /* unset */ }
+  if (!already) {
+    await git(toplevel, ['config', 'merge.klypix.name', 'KLYPIX lossless brain merge (union by card id)']);
+    await git(toplevel, ['config', 'merge.klypix.driver', driverCmd]);
+  }
+  let gaState = 'present';
+  if (!gaHasRule) {
+    const rule = `${gaText && !gaText.endsWith('\n') ? '\n' : ''}# .klypix brains merge losslessly via the KLYPIX 3-way union driver\n# (per-machine registration: npx klypix-mcp git-driver install).\n${DRIVER_ATTR_RULE}\n`;
+    fs.appendFileSync(gaPath, rule);
+    gaState = 'added';
+  }
+  console.log(`✓ ${already ? 'Already registered' : 'Registered'} the .klypix merge driver for ${toplevel}`);
+  console.log(`    driver: ${driverPath}${provisioned.length ? `  (provisioned: ${provisioned.join(', ')})` : ''}`);
+  console.log(`    .gitattributes rule: ${gaState}${gaState === 'added' ? ' — commit it so every teammate\'s clone routes .klypix merges here' : ''}`);
+  console.log('  Teammates run the same command once per machine; unregistered machines fall back to a normal conflict.');
+}
+
+// ── diff ────────────────────────────────────────────────────────────────────
+
+function renderCardList(title, entries, cap = 20) {
+  if (!entries.length) return [];
+  const lines = [`**${title} (${entries.length})**`];
+  for (const e of entries.slice(0, cap)) lines.push(`- ${e}`);
+  // Truncation notice is NEVER subject to the cap it reports.
+  if (entries.length > cap) lines.push(`- …and ${entries.length - cap} more`);
+  lines.push('');
+  return lines;
+}
+
+async function brainDiff() {
+  const ref = positional[0] || 'HEAD';
+  const brain = findBrain(flag('--brain'));
+  if (!brain) { console.error('No brain.klypix found (searched upward from cwd; use --brain <path>).'); process.exit(1); }
+  const toplevel = await repoToplevel(path.dirname(brain));
+  if (!toplevel) { console.error(`Brain is not inside a git repository: ${brain}`); process.exit(1); }
+  const rel = path.relative(toplevel, brain).replace(/\\/g, '/');
+
+  const { format, merge } = await loadEngine();
+  const current = fs.readFileSync(brain);
+
+  let baseBuf = null;
+  try { baseBuf = Buffer.from(await git(toplevel, ['show', `${ref}:${rel}`], { encoding: 'buffer' })); }
+  catch { baseBuf = null; }
+
+  const out = [`### 🧠 Brain diff — \`${rel}\` vs \`${ref}\``, ''];
+  if (!baseBuf || baseBuf.length === 0) {
+    const { struct } = await format.parseKlypix(current);
+    out.push(`The brain does not exist at \`${ref}\` — everything is new here (${struct.cards.length} cards).`);
+    console.log(out.join('\n'));
+    return;
+  }
+
+  // SEMANTIC diff, never byte diff: .klypix re-serialization is deliberately
+  // non-reproducible (zip metadata, zIndex renumbering), so comparing raw item
+  // bytes reports the whole brain as "updated" (live-reproduced: 1308 false
+  // updates over 8 commits). Parse both sides and compare key-sorted JSON with
+  // display-derived fields stripped — the same discipline as the sync core.
+  const stable = (v) => JSON.stringify(v, (_k, val) =>
+    (val && typeof val === 'object' && !Array.isArray(val))
+      ? Object.fromEntries(Object.keys(val).sort().map(x => [x, val[x]]))
+      : val);
+  const cardMap = async (buf) => {
+    const { zip, canvas } = await format.parseKlypix(buf);
+    const ids = [...new Set([...(Array.isArray(canvas.order) ? canvas.order : []), ...Object.keys(canvas.positions || {})])];
+    const m = new Map();
+    for (const id of ids) {
+      const f = zip.file(`items/${format.shard(id)}/${id}.json`);
+      if (!f) continue;
+      try {
+        const item = JSON.parse(await f.async('string'));
+        m.set(id, {
+          sig: stable({ ...item, zIndex: undefined }),
+          title: firstLine(item.content || item.title || '') || `\`${id}\``,
+        });
+      } catch { /* unreadable item — skip rather than mis-report */ }
+    }
+    return { map: m, connections: Array.isArray(canvas.connections) ? canvas.connections.length : 0 };
+  };
+  void merge; // brainDelta stays the live-apply engine; diff is semantic by design
+
+  const [baseSide, curSide] = await Promise.all([cardMap(baseBuf), cardMap(current)]);
+  const added = [], updated = [], removed = [];
+  for (const [id, cur] of curSide.map) {
+    const prev = baseSide.map.get(id);
+    if (!prev) added.push(cur.title);
+    else if (prev.sig !== cur.sig) updated.push(cur.title);
+  }
+  for (const [id, prev] of baseSide.map) {
+    if (!curSide.map.has(id)) removed.push(prev.title);
+  }
+  const connDelta = curSide.connections - baseSide.connections;
+
+  if (!added.length && !updated.length && !removed.length && !connDelta) {
+    out.push('No card-level changes.');
+  } else {
+    out.push(`**${added.length} added · ${updated.length} updated · ${removed.length} removed**`, '');
+    out.push(...renderCardList('Added', added));
+    out.push(...renderCardList('Updated', updated));
+    out.push(...renderCardList('Removed', removed));
+    if (connDelta) out.push(`_${connDelta > 0 ? '+' : ''}${connDelta} connection(s)._`);
+  }
+  console.log(out.join('\n'));
+}
+
+// ── pr-brief ────────────────────────────────────────────────────────────────
+
+// The brain's own evidence-tag convention: #file-<slug> where slug is the
+// basename minus its last extension, lowercased, non-alphanumerics folded to
+// hyphens. Tag matches only (precision over recall — a PR comment that spams
+// unrelated cards teaches people to ignore it).
+function fileSlug(p) {
+  const base = path.basename(p).replace(/\.[^.]+$/, '');
+  return base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+async function prBrief() {
+  const baseRef = positional[0] || 'HEAD~1';
+  const brain = findBrain(flag('--brain'));
+  if (!brain) { console.error('No brain.klypix found (searched upward from cwd; use --brain <path>).'); process.exit(1); }
+  const toplevel = await repoToplevel(path.dirname(brain));
+  if (!toplevel) { console.error(`Brain is not inside a git repository: ${brain}`); process.exit(1); }
+
+  let changed = [];
+  try {
+    changed = String(await git(toplevel, ['diff', '--name-only', `${baseRef}...HEAD`]))
+      .split('\n').map(s => s.trim()).filter(Boolean);
+  } catch (e) {
+    console.error(`git diff against "${baseRef}" failed: ${String(e.message || e).split('\n')[0]}`);
+    process.exit(1);
+  }
+  if (!changed.length) { console.log('_No changed files — no brain context to attach._'); return; }
+
+  const { format } = await loadEngine();
+  const { struct } = await format.parseKlypix(fs.readFileSync(brain));
+
+  const perFile = new Map();   // file -> [card first lines]
+  let total = 0;
+  for (const file of changed) {
+    const slug = fileSlug(file);
+    if (!slug) continue;
+    const tag = `#file-${slug}`;
+    const hits = [];
+    for (const card of struct.cards) {
+      const text = String(card.text || card.title || '');
+      const idx = text.indexOf(tag);
+      if (idx < 0) continue;
+      // Tag boundary: the next char must not extend the slug (avoids
+      // #file-use matching #file-usechat).
+      const after = text[idx + tag.length];
+      if (after && /[a-z0-9-]/.test(after)) continue;
+      hits.push(firstLine(text));
+      if (hits.length >= 3) break;   // cap per file; total notice below
+    }
+    if (hits.length) { perFile.set(file, hits); total += hits.length; }
+  }
+
+  if (!perFile.size) {
+    console.log(`_No brain cards reference the ${changed.length} changed file(s)._`);
+    return;
+  }
+
+  const out = [`### 🧠 Brain context for this PR`, '',
+    `Decisions and findings already recorded about the files this PR touches (${perFile.size} of ${changed.length} changed files have brain context):`, ''];
+  let printed = 0;
+  const FILE_CAP = 12;
+  let fileIdx = 0;
+  for (const [file, hits] of perFile) {
+    if (fileIdx >= FILE_CAP) break;
+    fileIdx++;
+    out.push(`**\`${file}\`**`);
+    for (const h of hits) { out.push(`- ${h}`); printed++; }
+    out.push('');
+  }
+  if (perFile.size > FILE_CAP) out.push(`…and ${perFile.size - FILE_CAP} more file(s) with brain context.`);
+  out.push(`_From \`${path.relative(toplevel, brain).replace(/\\/g, '/')}\` — the project's shared brain. ${printed} card(s) shown._`);
+  console.log(out.join('\n'));
+}
+
+// ── entry ───────────────────────────────────────────────────────────────────
+
+export async function run(verb, rawArgs) {
+  args = Array.isArray(rawArgs) ? rawArgs : [];
+  positional = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--brain');
+  try {
+    if (verb === 'git-driver') await gitDriver();
+    else if (verb === 'diff') await brainDiff();
+    else if (verb === 'pr-brief') await prBrief();
+    else { console.error(`klypix-git-tools: unknown verb "${verb}"`); process.exit(2); }
+  } catch (e) {
+    console.error(`${verb} failed: ${String(e?.message || e).split('\n')[0]}`);
+    process.exit(1);
+  }
+}

package/bin/klypix-mcp.mjs

@@ -19,7 +19,7 @@ const PKG_VERSION = (() => {
   }
 })();
 
-const DIRECT = new Set(['install', 'link', 'doctor', 'conformance', 'garden-code', 'init']);
+const DIRECT = new Set(['install', 'link', 'doctor', 'conformance', 'garden-code', 'init', 'git-driver', 'diff', 'pr-brief']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -31,6 +31,9 @@ const USAGE = [
   '  conformance [--json]                launch two real MCP clients against this build',
   '  init                                seed a starter ./brain.klypix + print an MCP config',
   '  garden-code [brain]                 print the human approval code for brain_garden',
+  '  git-driver [install|status] [repo]  register the lossless .klypix merge driver for a repo (zero-command teams)',
+  '  diff [ref] [--brain <path>]         readable brain diff vs a git ref (default HEAD) — markdown to stdout',
+  '  pr-brief [baseRef] [--brain <path>] brain decisions touching the files changed since baseRef — PR-comment markdown',
   '',
   'With no verb (or any --flag, e.g. --vault <dir>) it runs as an MCP stdio server.',
   'There is no uninstall command — removal is manual (see README).',

package/bin/klypix-pr-brief.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin bin for `klypix-mcp pr-brief` — the worker dispatcher splices the verb out
+// of argv before importing, so this bin re-supplies it. Standalone use works
+// identically: node bin/klypix-pr-brief.mjs <args>
+import { run } from './klypix-git-tools.mjs';
+await run('pr-brief', process.argv.slice(2));

package/bin/klypix-worker.mjs

@@ -102,6 +102,14 @@ await runVerb('doctor', './klypix-doctor.mjs');
 // overlap detection, proactive logging, and guaranteed next-action delivery.
 await runVerb('conformance', './klypix-conformance.mjs');
 
+// `npx klypix-mcp git-driver | diff | pr-brief` — the GitHub lane: register the
+// lossless .klypix merge driver for any repo, render a readable brain diff vs a
+// git ref, and print the brain cards touching a PR's changed files. One module,
+// three verbs (it reads argv[2] itself).
+await runVerb('git-driver', './klypix-git-driver.mjs');
+await runVerb('diff', './klypix-diff.mjs');
+await runVerb('pr-brief', './klypix-pr-brief.mjs');
+
 // `npx klypix-mcp garden-code` — the HUMAN half of the garden approval gate.
 // brain_garden's apply requires an 8-char code derived from the exact dormant
 // candidate set + day; the agent is deliberately never shown it. The human runs

package/examples/github/brain-pr.yml

@@ -0,0 +1,68 @@
+# Brain-aware pull requests — copy this file to .github/workflows/brain-pr.yml
+# in any repo whose brain.klypix is committed.
+#
+# On every PR it posts (and keeps updated) ONE sticky comment with:
+#   1. the brain decisions/corrections that reference the files the PR touches
+#      (evidence tags: #file-<name> inside cards), and
+#   2. a readable card-level diff of the brain itself, when the PR changes it.
+#
+# Nothing here talks to any KLYPIX service — the brain is read from the
+# checkout, exactly as your agents read it. Requires only the default
+# GITHUB_TOKEN with pull-requests: write.
+
+name: brain-pr
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  brain-context:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0            # pr-brief and diff need the base ref
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Build the comment
+        id: brain
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+        run: |
+          {
+            npx --yes klypix-mcp pr-brief "$BASE" || true
+            echo ""
+            # Only show the brain diff when the PR actually changes the brain.
+            if git diff --name-only "$BASE"...HEAD | grep -q '\.klypix$'; then
+              npx --yes klypix-mcp diff "$BASE" || true
+            fi
+          } > brain-comment.md
+          # Skip the comment entirely when there is nothing to say.
+          if ! grep -qE '🧠' brain-comment.md; then
+            echo "post=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "post=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Post / update the sticky comment
+        if: steps.brain.outputs.post == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          MARKER="<!-- klypix-brain-pr -->"
+          printf '%s\n\n' "$MARKER" | cat - brain-comment.md > body.md
+          EXISTING=$(gh api "repos/${GITHUB_REPOSITORY}/issues/${PR}/comments" \
+            --jq ".[] | select(.body | startswith(\"$MARKER\")) | .id" | head -1)
+          if [ -n "$EXISTING" ]; then
+            gh api -X PATCH "repos/${GITHUB_REPOSITORY}/issues/comments/${EXISTING}" -F body=@body.md > /dev/null
+          else
+            gh pr comment "$PR" --body-file body.md > /dev/null
+          fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.47.0",
+  "version": "1.49.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -66,7 +66,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/codex-hooks.mjs && node test/agent-presence.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/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/decay-status.mjs && node test/decay-hook.mjs && node test/presence-visibility.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/uninstall.mjs"
+    "test": "node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/codex-hooks.mjs && node test/agent-presence.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/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/decay-status.mjs && node test/decay-hook.mjs && node test/presence-visibility.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",

package/src/klypix-merge-driver.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// klypix-merge-driver — git merge driver for .klypix files.
+//
+// Wires the existing lossless 3-way engine (./merge-brains.mjs — the same one
+// the app uses for merge-on-save) into git, so two people committing to one
+// brain.klypix stop hitting manual binary conflicts: git calls this on
+// conflict, the union merge runs, and both sides' cards survive.
+//
+// git invokes it as:   node scripts/klypix-merge-driver.mjs %O %A %B %P
+//   %O = common ancestor file   %A = ours (result is written HERE)
+//   %B = theirs                 %P = real path (logging only)
+// Exit 0 = merged; any failure exits 1, which leaves the normal binary
+// conflict — i.e. exactly the behavior without this driver. Git's merge
+// commit keeps both parents, so even a bad merge is always reconstructable.
+//
+// Registration is per-machine (git config is never committed):
+//   npx klypix-mcp git-driver install     (any repo, zero setup — canonical)
+//   npm run setup:merge-driver            (KLYPIX repo's local convenience)
+// The KLYPIX desktop app also self-registers this silently when it opens a
+// brain inside a git repo. .gitattributes routes *.klypix here; unregistered
+// machines just get the old manual conflict. CANONICAL HOME: klypix-mcp/src —
+// installs flatten it into ~/.claude/project-brain beside merge-brains.mjs.
+//
+// DELETE SEMANTICS (git context ≠ app context): merge-brains treats absence
+// as NOT-a-delete (in the app, absence can be a deferred renderer apply) and
+// drops cards only via explicit tombstones. In git, both sides are FULL
+// COMMITTED snapshots, so "in ancestor, absent from a side" is a deliberate,
+// committed delete. We honor it as a tombstone ONLY when the other side left
+// the card untouched; if the other side EDITED it after the ancestor, no
+// tombstone is passed and the union keeps the edited card (delete-vs-edit
+// resolves to the edit — no-loss wins over delete).
+
+import fs from 'node:fs';
+import { mergeBrains, sameMeaning } from './merge-brains.mjs';
+import { parseKlypix, shard } from './klypix-format.mjs';
+
+// id -> verbatim item JSON string for one side (null for an empty/absent side).
+async function itemsOf(buf) {
+  if (!buf || buf.length === 0) return null;
+  const { zip, canvas } = await parseKlypix(buf);
+  const ids = new Set([...(Array.isArray(canvas.order) ? canvas.order : []), ...Object.keys(canvas.positions || {})]);
+  const m = new Map();
+  for (const id of ids) {
+    const f = zip.file(`items/${shard(id)}/${id}.json`);
+    m.set(id, f ? await f.async('string') : null);
+  }
+  return m;
+}
+
+const [, , oPath, aPath, bPath, realPath] = process.argv;
+if (!oPath || !aPath || !bPath) {
+  console.error('usage: klypix-merge-driver <ancestor> <ours> <theirs> [path]');
+  process.exit(1);
+}
+
+try {
+  const O = fs.readFileSync(oPath);           // may be 0 bytes (added on both sides)
+  const A = fs.readFileSync(aPath);
+  const B = fs.readFileSync(bPath);
+  const base = O.length ? O : null;
+
+  const [bi, ai, ti] = await Promise.all([itemsOf(base), itemsOf(A), itemsOf(B)]);
+
+  // Committed-absence tombstones (see DELETE SEMANTICS above).
+  const deletedIds = [];
+  if (bi && ai && ti) {
+    for (const [id, baseJson] of bi) {
+      const inA = ai.has(id), inB = ti.has(id);
+      if (inA && inB) continue;                                   // alive on both
+      if (!inA && !inB) { deletedIds.push(id); continue; }        // deleted on both
+      // "Untouched" by MEANING, not bytes — a side that merely re-saved the
+      // file restamps volatile fields (updatedAt), and a byte compare would
+      // read that as an edit and silently refuse to propagate a real delete.
+      const survivorJson = inA ? ai.get(id) : ti.get(id);
+      if (sameMeaning(survivorJson, baseJson)) deletedIds.push(id);   // delete vs untouched → honor
+      // delete vs EDIT → no tombstone; union keeps the edited card
+    }
+  }
+
+  const { buffer, conflicts, delta } = await mergeBrains({ base, ours: A, theirs: B, deletedIds });
+  fs.writeFileSync(aPath, buffer);
+  const bits = [];
+  if (delta.added.length) bits.push(`+${delta.added.length} card(s)`);
+  if (deletedIds.length) bits.push(`-${deletedIds.length} delete(s) honored`);
+  if (conflicts.length) bits.push(`${conflicts.length} conflict twin(s) preserved`);
+  console.error(`klypix-merge: ${realPath || 'brain'} united losslessly${bits.length ? ' — ' + bits.join(', ') : ''}`);
+  process.exit(0);
+} catch (e) {
+  // Any failure → normal binary conflict, same as a machine without the driver.
+  console.error(`klypix-merge: ${realPath || 'brain'} — falling back to manual conflict (${e?.message || e})`);
+  process.exit(1);
+}

package/src/merge-brains.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+// merge-brains — the pure, provable core of the desktop-app<->hooks brain
+// concurrency fix. A 3-way UNION-by-stable-id reconcile of two .klypix brains
+// that share a common ancestor, designed so that NO CARD CAN BE LOST.
+//
+// Why this exists: the desktop app used to SAVE the brain with a blind full-file
+// overwrite, clobbering any card the Claude Code hooks captured after the app
+// opened. This replaces overwrite with union: the app re-reads the disk copy
+// INSIDE the capture lock and merges, so a hook capture written after open is
+// always kept — even if the lock is missed (union is non-destructive).
+//
+// HARDENED against the adversarial design review (data-loss blockers):
+//   • Deletes are honored ONLY via explicit tombstones (deletedIds) — a card
+//     merely ABSENT from `ours` is NEVER inferred as a delete (that absence can
+//     be a deferred/gated renderer apply, not a deletion). This is the fix for
+//     the "false-delete clobber" + "delete-by-absence" blockers.
+//   • assets/ entries are UNIONed by path (else theirs-only images ship blank).
+//   • Content conflict (both edited the same card) keeps BOTH texts losslessly:
+//     the human's stays live on the card, the agent's is preserved as a linked
+//     twin card — never silently dropped.
+//   • zKeys are de-collided (duplicate keys silently no-op in the app reducer).
+//   • Post-merge SUPERSET VERIFICATION: the result is asserted to contain every
+//     surviving id from both sides; the function throws rather than return a
+//     buffer that lost a card.
+//
+// Pure + dependency-light: reads via the shared parseKlypix, so it stays correct
+// as the format evolves. CANONICAL HOME: klypix-mcp/src (moved 2026-08-01 so the
+// git merge driver is npm-distributable to ANY repo — supersedes the old
+// "APP-maintained, edit in KLYPIX scripts/" note). The KLYPIX app bundles this
+// file back via sync-bundled-mcp exactly like klypix-format.mjs, and its
+// brainEngine/deploy paths keep loading it unchanged. Edit it HERE — the app
+// copy is GENERATED. It flattens into ~/.claude/project-brain on install, where
+// jszip + fractional-indexing already live.
+
+import JSZip from 'jszip';
+import { parseKlypix, shard } from './klypix-format.mjs';
+import { generateKeyBetween } from 'fractional-indexing';
+
+const isValidZKey = (k) => { try { generateKeyBetween(k, null); return true; } catch { return false; } };
+const rand = () => Math.random().toString(36).slice(2, 10);
+const ARCHIVE = /^archive$/i;
+
+// ── Semantic item comparison (2026-08-01 field fix) ─────────────────────────
+// A raw byte compare of item JSON was the change detector, on the assumption
+// that "unchanged cards keep byte-identical JSON". That assumption DIED the
+// day cards gained touch metadata: `updatedAt` is restamped whenever a card is
+// written, so two sides holding the SAME card with the SAME text differ in
+// bytes — and every first real sync spawned __agconf conflict twins for cards
+// nobody edited (field-proven on the founder's pump-doctor brain: 5 twins,
+// differing field list = ["updatedAt"] exactly).
+//
+// The fix is the same discipline the sync core and the brain diff already use:
+// compare PARSED MEANING with volatile/derived fields stripped, key-sorted so
+// two writers' key orders can't fake a difference. Byte-compare survives as the
+// fallback for anything unparseable — a malformed item must never crash a merge.
+//
+// VOLATILE = written by the act of saving, not by a human/agent decision:
+//   updatedAt — touch timestamp        zIndex — display order derived from zKey
+// Everything else (content, colors, geometry, evidence, author…) stays load-
+// bearing: a real edit to any of them is still a real conflict.
+const VOLATILE_ITEM_FIELDS = ['updatedAt', 'zIndex'];
+
+const sortedStable = (v) => JSON.stringify(v, (_k, val) =>
+  (val && typeof val === 'object' && !Array.isArray(val))
+    ? Object.fromEntries(Object.keys(val).sort().map(k => [k, val[k]]))
+    : val);
+
+function itemSignature(json) {
+  if (json == null) return null;
+  try {
+    const obj = JSON.parse(json);
+    for (const f of VOLATILE_ITEM_FIELDS) delete obj[f];
+    return sortedStable(obj);
+  } catch {
+    return json;                      // unparseable → byte identity, as before
+  }
+}
+
+/** True when two item JSON strings mean the same thing (volatile fields aside).
+ *  EXPORTED as the single definition of "did this card actually change" — the
+ *  git merge driver and the Brain Sync core both decide committed-absence
+ *  tombstones with it, so all three transports agree on what an edit is. */
+export const sameMeaning = (a, b) => {
+  if (a === b) return true;           // fast path: byte-identical
+  if (a == null || b == null) return false;
+  return itemSignature(a) === itemSignature(b);
+};
+
+// Load one .klypix buffer into a flat, comparison-friendly shape. Item JSON is
+// kept VERBATIM (the merge must write back exactly what a side held); whether
+// two versions actually differ is decided by sameMeaning(), never by these
+// bytes — see its note on volatile fields.
+async function loadSide(buf) {
+  if (!buf) return null;
+  const { zip, canvas, manifest, struct } = await parseKlypix(buf);
+  const order = Array.isArray(canvas.order) ? canvas.order : [];
+  const positions = canvas.positions || {};
+  const items = {};                 // id -> raw item JSON string (verbatim bytes)
+  const idSet = new Set(order.length ? order : Object.keys(positions));
+  for (const id of idSet) {
+    const f = zip.file(`items/${shard(id)}/${id}.json`);
+    items[id] = f ? await f.async('string') : null;
+  }
+  const assets = {};                // "assets/<id>" -> nodebuffer
+  for (const p of Object.keys(zip.files)) {
+    if (p.startsWith('assets/') && !zip.files[p].dir) assets[p] = await zip.file(p).async('nodebuffer');
+  }
+  const titleById = new Map(struct.cards.map(c => [c.id, c.title || '']));
+  return {
+    order, positions, items, assets, manifest,
+    connections: Array.isArray(canvas.connections) ? canvas.connections : [],
+    lines: Array.isArray(canvas.lines) ? canvas.lines : [],
+    strokes: Array.isArray(canvas.strokes) ? canvas.strokes : [],
+    settings: canvas.settings || {},
+    nextGroupNumber: Number(canvas.nextGroupNumber) || 1,   // top-level key, NOT settings
+    view: canvas.view || null,
+    titleById,
+    ids: idSet,
+  };
+}
+
+const samePos = (a, b) => !!a && !!b &&
+  a.x === b.x && a.y === b.y && (a.w ?? null) === (b.w ?? null) && (a.h ?? null) === (b.h ?? null);
+const sameParent = (a, b) => (a?.parentId ?? null) === (b?.parentId ?? null);
+
+/**
+ * mergeBrains — 3-way union of two brains sharing ancestor `base`.
+ * @param {{base?:Buffer|null, ours:Buffer, theirs:Buffer, deletedIds?:string[]}} args
+ *   base      = on-disk struct snapshotted when the app opened (null → pure union).
+ *   ours      = the app's in-memory brain (what the human is saving).
+ *   theirs    = the current on-disk brain, re-read INSIDE the lock (has hook captures).
+ *   deletedIds= ids the HUMAN explicitly deleted (tombstones). ONLY these can drop.
+ * @returns {Promise<{buffer:Buffer, delta:{added:string[],updated:string[],archived:string[],removed:string[]}, conflicts:object[], stats:object}>}
+ */
+export async function mergeBrains({ base = null, ours, theirs, deletedIds = [] }) {
+  if (!ours || !theirs) throw new Error('mergeBrains needs both ours and theirs buffers');
+  const B = await loadSide(base);
+  const O = await loadSide(ours);
+  const T = await loadSide(theirs);
+  const del = new Set(deletedIds);
+
+  const baseItem = (id) => (B && B.items[id]) || null;
+  const basePos = (id) => (B && B.positions[id]) || null;
+  const parentTitle = (side, pos) => {
+    const pid = pos?.parentId; if (!pid) return '';
+    return String(side.titleById.get(pid) || '');
+  };
+
+  const allIds = new Set([...O.ids, ...T.ids]);
+  const merged = new Map();          // id -> { json, pos }
+  const extras = [];                 // conflict-twin cards to append
+  const conflicts = [];
+  const delta = { added: [], updated: [], archived: [], removed: [] };
+
+  for (const id of allIds) {
+    const inO = O.items[id] != null, inT = T.items[id] != null;
+    const inB = baseItem(id) != null;
+
+    // ── Explicit human delete (tombstone) — the ONLY path that drops a card ──
+    if (del.has(id)) {
+      const theirsChanged = inT && inB && T.items[id] !== baseItem(id);
+      if (inT && theirsChanged) {
+        // delete-vs-edit: the human deleted it but a hook edited it after open →
+        // KEEP theirs (never lose the hook's new info); record the conflict.
+        conflicts.push({ id, kind: 'delete-vs-edit', kept: 'theirs' });
+        // fall through to keep from theirs below
+      } else {
+        delta.removed.push(id);
+        continue;                    // honored delete
+      }
+    }
+
+    if (!inO && !inT) continue;
+
+    // ── Choose CONTENT ──────────────────────────────────────────────────────
+    let json, side;
+    if (inO && inT) {
+      // Change + divergence are judged by MEANING, not bytes (see sameMeaning):
+      // a restamped `updatedAt` is not an edit, and two copies of one card that
+      // differ only in volatile fields are not in conflict.
+      const oChg = !inB || !sameMeaning(O.items[id], baseItem(id));
+      const tChg = !inB || !sameMeaning(T.items[id], baseItem(id));
+      const diverged = !sameMeaning(O.items[id], T.items[id]);
+      if (inB && oChg && tChg && diverged) {
+        // GENUINE content conflict: a card that EXISTED at open, edited differently
+        // on both sides → human stays live, agent version preserved as a twin.
+        json = O.items[id]; side = 'ours';
+        const twinId = `${id}__agconf_${rand()}`;
+        extras.push({ id: twinId, json: T.items[id], srcPos: T.positions[id] || O.positions[id], of: id });
+        conflicts.push({ id, kind: 'content', keptLive: 'ours', twin: twinId });
+      } else if (tChg && !oChg) { json = T.items[id]; side = 'theirs'; delta.updated.push(id); }
+      else if (!inB && diverged) {
+        // Same NEW card (same id) present on BOTH sides but never in base — e.g. an
+        // agent card the app also holds via live-apply, re-serialized slightly
+        // differently. It's the SAME card, NOT a conflict → take the disk/agent
+        // bytes; NEVER spawn a twin for a card that was never in base (the
+        // live-apply-then-save duplication bug).
+        json = T.items[id]; side = 'theirs';
+      }
+      else { json = O.items[id]; side = 'ours'; }
+    } else if (inT) {
+      json = T.items[id]; side = 'theirs';
+      if (!inB) delta.added.push(id);            // agent added since open — the anti-clobber core
+    } else {
+      json = O.items[id]; side = 'ours';
+    }
+
+    // ── Choose POSITION + parent (human spatial intent wins; hook archive
+    //    applies only if the human didn't move/re-parent the card) ───────────
+    const oP = O.positions[id], tP = T.positions[id], bP = basePos(id);
+    const oMoved = oP && (!bP || !samePos(oP, bP));
+    const finalXY = oMoved ? oP : (tP || oP);
+
+    let parentId;
+    const oParentChg = oP && (!bP || !sameParent(oP, bP));
+    const tParentChg = tP && (!bP || !sameParent(tP, bP));
+    if (oParentChg) parentId = oP.parentId ?? null;
+    else if (tParentChg) parentId = tP.parentId ?? null;
+    else parentId = (finalXY?.parentId ?? oP?.parentId ?? tP?.parentId ?? null);
+
+    const pos = { ...(finalXY || oP || tP || {}), parentId };
+    // Detect a hook archive-move for the delta receipt.
+    if (side === 'theirs' && tParentChg && ARCHIVE.test(parentTitle(T, tP))) delta.archived.push(id);
+
+    merged.set(id, { json, pos });
+  }
+
+  // ── Conflict twins: place beside their source card, own valid zKey ─────────
+  for (const ex of extras) {
+    const src = ex.srcPos || {};
+    merged.set(ex.id, { json: ex.json, pos: { x: (src.x || 0) + 24, y: (src.y || 0) + 24, w: src.w, h: src.h, parentId: src.parentId ?? null } });
+  }
+
+  // ── Order + zKey heal (de-collide: duplicate zKeys silently no-op in-app) ──
+  const order = [];
+  const seen = new Set();
+  for (const id of [...T.order, ...O.order, ...extras.map(e => e.id)]) {
+    if (merged.has(id) && !seen.has(id)) { seen.add(id); order.push(id); }
+  }
+  // Any merged id not in either order[] (defensive) — append.
+  for (const id of merged.keys()) if (!seen.has(id)) { seen.add(id); order.push(id); }
+
+  const usedZ = new Set();
+  let lastZ = null;
+  for (const id of order) {
+    const rec = merged.get(id);
+    let z = rec.pos.zKey;
+    if (!z || !isValidZKey(z) || usedZ.has(z)) z = generateKeyBetween(lastZ, null);
+    usedZ.add(z); lastZ = z;
+    rec.pos = { ...rec.pos, zKey: z, zIndex: order.indexOf(id) };
+  }
+
+  // ── Union connections / lines / strokes by id; drop dangling connections ──
+  const byId = (arr) => { const m = new Map(); for (const x of arr) if (x && x.id) m.set(x.id, x); return m; };
+  const connMap = new Map([...byId(T.connections), ...byId(O.connections)]);
+  const liveIds = new Set(order);
+  // Collapse EXACT duplicate edges (same endpoints + relationship + label,
+  // different ids). Connection deletes have no tombstone, so an arrange/de-dup
+  // that dropped a redundant edge in-app used to see it resurrected from disk
+  // by this union — as a byte-identical twin arrow. Never meaningful to keep.
+  const seenEdge = new Set();
+  const connections = [...connMap.values()].filter(c => {
+    if (!(liveIds.has(c.fromId) && liveIds.has(c.toId))) return false;
+    const k = `${c.fromId}|${c.toId}|${c.relationship || ''}|${c.label || ''}`;
+    if (seenEdge.has(k)) return false;
+    seenEdge.add(k);
+    return true;
+  });
+  const lines = [...new Map([...byId(T.lines), ...byId(O.lines)]).values()];
+  const strokes = [...new Map([...byId(T.strokes), ...byId(O.strokes)]).values()];
+
+  // ── Union assets by path (theirs preferred, then ours, then base) ─────────
+  const assets = {};
+  for (const src of [B, O, T]) if (src) for (const [p, bytes] of Object.entries(src.assets)) assets[p] = bytes;
+
+  // ── Build merged zip ──────────────────────────────────────────────────────
+  const zip = new JSZip();
+  const now = Date.now();
+  for (const id of order) zip.file(`items/${shard(id)}/${id}.json`, merged.get(id).json);
+  for (const [p, bytes] of Object.entries(assets)) zip.file(p, bytes);
+
+  const positions = {};
+  for (const id of order) positions[id] = merged.get(id).pos;
+
+  // Per-field manifest UNION, theirs-precedence: theirs still wins every field
+  // it carries (the original semantics — disk/hook-side stamps survive an app
+  // save), but a field only OURS has is no longer dropped. Concretely: the
+  // cloud-link stamp (manifest.cloud) added on the local side must survive a
+  // merge against an older cloud copy that predates the link.
+  const manifest = { format: 'klypix', version: 4, ...(O.manifest || {}), ...(T.manifest || {}) };
+  manifest.updatedAt = new Date(now).toISOString();
+  manifest.stats = { ...(manifest.stats || {}), itemCount: order.length, assetCount: Object.keys(assets).length };
+  zip.file('manifest.json', JSON.stringify(manifest));
+
+  const canvasJson = {
+    version: 4,
+    view: O.view || T.view || { panX: 0, panY: 0, zoom: 0.7 },   // human's viewport
+    order, connections, lines, strokes,
+    nextGroupNumber: Math.max(1, ...[O, T].map(s => Number(s.nextGroupNumber) || 1)),
+    positions,
+    settings: { ...(T.settings || {}), ...(O.settings || {}) },
+  };
+  zip.file('canvas.json', JSON.stringify(canvasJson));
+  const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+
+  // ── SUPERSET VERIFICATION — prove no card was lost ─────────────────────────
+  // Every id that survived on either side (minus honored deletes) MUST be in the
+  // result; every asset path from either side MUST be present. Throw otherwise.
+  const survivors = new Set();
+  for (const id of O.ids) if (!delta.removed.includes(id)) survivors.add(id);
+  for (const id of T.ids) if (!delta.removed.includes(id)) survivors.add(id);
+  const resultIds = new Set(order);
+  const missing = [...survivors].filter(id => !resultIds.has(id));
+  if (missing.length) throw new Error(`mergeBrains INVARIANT VIOLATED — dropped ${missing.length} card(s): ${missing.slice(0, 5).join(', ')}`);
+  const wantAssets = new Set([...Object.keys(O.assets), ...Object.keys(T.assets)]);
+  const missingAssets = [...wantAssets].filter(p => !(p in assets));
+  if (missingAssets.length) throw new Error(`mergeBrains INVARIANT VIOLATED — dropped ${missingAssets.length} asset(s): ${missingAssets.slice(0, 3).join(', ')}`);
+  // Re-parse to guarantee the buffer round-trips (never ship an unreadable brain).
+  await parseKlypix(buffer);
+
+  const stats = {
+    ours: O.ids.size, theirs: T.ids.size, base: B ? B.ids.size : 0,
+    merged: order.length, conflicts: conflicts.length,
+    added: delta.added.length, updated: delta.updated.length,
+    archived: delta.archived.length, removed: delta.removed.length,
+    assets: Object.keys(assets).length,
+  };
+  return { buffer, delta, conflicts, stats };
+}
+
+/**
+ * Human deletions inferred SAFELY for the merge-on-SAVE path: ids present in the
+ * open-snapshot BASE but absent from OURS (the full current app state at save).
+ * Sound precisely because base is FROZEN at open — a card the agent added after
+ * open is never in base, so this returns ONLY cards the human actually removed,
+ * and can never mistake an un-applied agent card for a deletion. Feed the result
+ * to mergeBrains({...deletedIds}). NOTE: a card the human deletes that the AGENT
+ * added mid-session isn't in base → not returned here (it re-unions until the
+ * next reopen folds it into base); persisting that stricter case needs explicit
+ * renderer tombstones, a later increment. NEVER use this for the live watcher,
+ * where absence≠delete.
+ */
+export async function deletedByAbsence(baseBuf, oursBuf) {
+  if (!baseBuf || !oursBuf) return [];
+  const [b, o] = await Promise.all([parseKlypix(baseBuf), parseKlypix(oursBuf)]);
+  const oIds = new Set(o.struct.cards.map((c) => c.id));
+  return b.struct.cards.map((c) => c.id).filter((id) => !oIds.has(id));
+}
+
+/**
+ * Delta for the LIVE agent→human watcher: the cards ADDED to `newBuf` since the
+ * frozen open-snapshot `baseBuf`, with each added card's raw item JSON + position
+ * so the renderer can build it with its normal v4 deserializer. Added-only by
+ * design — a new id can never clobber a human's in-progress edit, and the renderer
+ * applies it idempotently, so re-sending the full accumulated added-set every time
+ * lets a briefly-gated tab catch up without any ack/queue. (Updates/removes
+ * reconcile on the next save/reopen — safe, since the merge never loses.)
+ */
+export async function brainDelta(baseBuf, newBuf) {
+  const empty = { added: [], updated: [], removed: [], items: {}, positions: {}, connections: [], manifest: null };
+  if (!baseBuf || !newBuf) return empty;
+  const [b, n] = await Promise.all([parseKlypix(baseBuf), parseKlypix(newBuf)]);
+  const baseIds = new Set(b.struct.cards.map((c) => c.id));
+  const newIds = new Set(n.struct.cards.map((c) => c.id));
+  const bPos = (b.canvas && b.canvas.positions) || {};
+  const nPos = (n.canvas && n.canvas.positions) || {};
+  const posKey = (p) => (p ? JSON.stringify([p.x, p.y, p.w, p.h, p.parentId ?? null]) : '');   // ignore zKey/zIndex noise
+  const raw = async (zip, id) => { const f = zip.file(`items/${shard(id)}/${id}.json`); return f ? f.async('string') : null; };
+
+  const added = [...newIds].filter((id) => !baseIds.has(id));
+  const removed = [...baseIds].filter((id) => !newIds.has(id));
+  const updated = [];
+  for (const id of newIds) {
+    if (!baseIds.has(id)) continue;
+    const [bStr, nStr] = await Promise.all([raw(b.zip, id), raw(n.zip, id)]);
+    if (bStr !== nStr || posKey(bPos[id]) !== posKey(nPos[id])) updated.push(id);
+  }
+
+  const items = {}, positions = {};
+  for (const id of [...added, ...updated]) {
+    const s = await raw(n.zip, id);
+    if (s) items[id] = s;
+    if (nPos[id]) positions[id] = nPos[id];
+  }
+  const baseConn = new Set((b.canvas && b.canvas.connections || []).map((c) => c.id));
+  const connections = (n.canvas && n.canvas.connections || []).filter((c) => c && c.id && !baseConn.has(c.id));
+  return { added, updated, removed, items, positions, connections, manifest: n.manifest || null };
+}
+
+export default mergeBrains;