klypix-mcp 1.88.0 → 1.89.0

package/FORMAT.md

@@ -17,6 +17,9 @@ your.klypix                      (a ZIP archive)
 ├── canvas.json                  spatial layout: order, positions, connections, lines, strokes, view, settings
 ├── items/
 │   └── <shard>/<id>.json        one file per item (content only; geometry lives in canvas.json)
+├── graveyard.json               Deleted cards index — absent until the first delete (see below)
+├── graveyard/
+│   └── <shard>/<id>.json        a deleted card's item JSON, or a receipt placeholder
 └── assets/                      embedded binaries — any non-directory entry here is an asset
     ├── images/<shard>/<sha256>.<ext>
     ├── files/<shard>/<sha256>.bin
@@ -198,6 +201,50 @@ instead of an asset. New writers use `assetId` and leave `src` empty.
 files — cards and arrows. Embedding binaries is done by the KLYPIX app when you drop
 a file onto a canvas.
 
+## Deleted cards — `graveyard.json` + `graveyard/`
+
+A card deleted from a brain is moved, not destroyed. Its item file goes to
+`graveyard/<shard>/<id>.json` (same sharding as `items/`), and an entry for it goes
+into `graveyard.json`:
+
+```json
+{ "version": 1, "entries": {
+  "txt_hto5hb3r_0_0": {
+    "rid": "r_3f1c…",
+    "deletedAt": 1790676275950,
+    "deletedBy": "user",
+    "deletion": { "initiator": "user", "cause": "history-restore", "source": "klypix-mcp", "confidence": "explicit" },
+    "area": "Work", "parentId": "ctn_…", "pos": { "x": 96, "y": 140, "w": 280, "h": 47 },
+    "preview": "first words of the card…"
+  } } }
+```
+
+Nothing under `graveyard/` is reachable from `canvas.json`'s `order`, so a deleted card
+never renders and is never searched or counted, and a card is never live and in the
+bin at once. Writers add fields to an entry, never rename them; `deletedBy` is the flat
+copy of `deletion.initiator` kept for older readers.
+
+An entry is one of three kinds:
+
+| Kind | How to recognise it | Body file |
+|---|---|---|
+| deleted card | no `purged` | the card's item JSON, verbatim — restorable |
+| permanently deleted | `purged: true`, no `restoredAs` | the placeholder `{"type":"text","content":"","purged":true}` |
+| restored | `purged: true` and `restoredAs: "<id>"` | the same placeholder; the card lives on at `restoredAs` |
+
+The two receipts carry no content, and they are the reason **the bin must travel with
+the file**. A tool that rewrites a `.klypix` has to carry `graveyard.json` and
+`graveyard/` through, or merge them. Dropping them makes the next merge with an older
+copy of the brain read the deletion as "never happened" and bring the card back — a
+permanently deleted one included.
+
+Two id rules follow from the same idea. A card brought back, from the bin or from a
+restore point, should get a new id derived from its deletion (`<id>__r_<12 hex>`, as
+this package's restores do), never the id it was deleted with: other copies still hold
+that deletion and would delete it again. And a card that Arrange collapses as a
+duplicate is buried like any other deletion, with `mergedInto` naming the card that
+absorbed it.
+
 ## Connections, links, tags
 
 - **Arrows:** `canvas.json.connections` (`fromId`/`toId`, optional

package/README.md

@@ -133,7 +133,7 @@ npx klypix-mcp install
 
 One command for supported editors detected on this machine. It finds the project root (walking up,
 so running it from `src/` is fine), gives the project a brain if it doesn't have one, wires the
-agent tools you actually have installed, registers the lossless `.klypix` merge driver if it's a
+agent tools you actually have installed, registers the card-level `.klypix` merge driver if it's a
 git repo, and then **proves the result** before it exits:
 
 ```text
@@ -141,7 +141,7 @@ git repo, and then **proves the result** before it exits:
   brain     created brain.klypix — a starter brain, ready for its first decision
   editors   Claude Code · Cursor · Codex · Gemini CLI · Antigravity · VS Code
   wired     9 file(s) · 9 updated   (skipped 5 for tools you don't have)
-  git       lossless .klypix merge driver registered
+  git       .klypix merge driver registered
   verified  ✓ 22 tools reachable via .mcp.json (892ms)
 ```
 
@@ -541,9 +541,18 @@ That registers a merge driver for `*.klypix` (a per-machine git config line plus
 rule you commit) and provisions the engine it needs. When two people change the brain and one
 pulls, git calls the engine instead of stopping: new cards from both sides are kept, a card only
 one side edited takes that edit, and a card edited differently on both sides keeps **both**
-versions — the second as a linked twin, never a silent overwrite. Before returning, the merge
-asserts it still contains every surviving card from both sides and refuses rather than hand back a
-result that lost one.
+versions — the second as a linked twin, never a silent overwrite. (One exception to "takes that
+edit": a card is never changed to mean exactly what its own conflict twin beside it already means
+(the whole card, not only its words) — both versions stay as they are and the driver's summary line
+says so. Delete the one you do not want.) Deletions travel too: a deleted
+card leaves a receipt in the brain's Deleted cards, and the driver merges those three-way, so a
+card deleted — or permanently deleted — on one branch stays out instead of coming back from the
+other, unless the other branch edited it. That edit comes back as a new card when the deleting
+branch recorded the delete (a receipt in its Deleted cards); when it did not, the edited card
+simply stays. A permanently deleted card stays out even then: the driver's summary line counts the
+edits it dropped, and they remain in that branch's git history. Before returning, the merge asserts
+it still contains every surviving card from both sides and refuses rather than hand back a result
+that lost one.
 
 The honest boundary: a machine that has not run `git-driver install` simply gets the old binary
 conflict — safe degradation, not corruption — and git keeps both parents of every merge, so even a
@@ -570,7 +579,12 @@ was judged worse — but it is a real limit, not a guarantee.
 
 ### Restore points
 
-Merging, tidying and gardening are lossless by contract. What none of them can undo is a
+Merging, tidying and gardening are built to keep every card nobody deleted (one deliberate exception: a
+card deleted permanently also leaves the other copies of the brain when they sync, an edited copy
+included, and the merge reports that edit). Deleting permanently is not a guarantee that the text is
+gone everywhere: a copy of the card that someone restored on another machine at about the same time,
+or resized or edited after restoring it, can stay there and has to be deleted there too; and restore
+points and git history keep what they already held. What none of them can undo is a
 *deliberate-looking* deletion: you select a dozen cards, delete them, and save. That is not a bug
 to prevent — a brain has to stay correctable, and an uncorrectable memory is worse than none — but
 it deserves a way back, because the brain is **co-owned**: hooks, the MCP server, commit capture
@@ -584,6 +598,12 @@ npx klypix-mcp brain-history list          # age, card count, delta against the
 npx klypix-mcp brain-history restore <id>  # and this is itself undoable
 ```
 
+A restore is a merge into the brain as it is now, not a copy over the file, and it prints what it
+changed. The point's cards come back — a card deleted since returns under a new id, so every other
+copy of the brain agrees the old one was deleted — and cards written after the point move to
+Deleted cards (`npx klypix-mcp brain-deleted list`), where each one can be restored. Permanently
+deleted cards stay out unless you pass `--include-purged`.
+
 They live under `~/.claude/project-brain/history/`, never beside the brain — nothing lands in git,
 in the merge driver's path, or in your diffs, and they survive deletion of the `.klypix` file
 itself. Routine writes are deduped and throttled to one a minute; a write that **removes cards** is
@@ -608,7 +628,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `npx klypix-mcp doctor` | One verdict: version, hosts, live sessions, tool count, drift. Exits non-zero — usable as a CI gate |
 | `npx klypix-mcp runtime` | Passive per-connection process/RAM attribution (`--json`, optional `--watch seconds`); never kills or deduplicates |
 | `npx klypix-mcp conformance` | Launch two real MCP clients against this build and verify coordination behaviour |
-| `npx klypix-mcp git-driver` | Register the lossless `.klypix` merge driver for a repo (`status` to check) |
+| `npx klypix-mcp git-driver` | Register the card-level `.klypix` merge driver for a repo (`status` to check) |
 | `npx klypix-mcp git-hook` | Wire the agent-neutral commit-capture hook: rationale-bearing `feat`/`fix`/`perf` commits from any agent, branch, or worktree card into the brain at commit time (`install`/`remove`/`status`; sessions auto-install it where the hook slots are free) |
 | `npx klypix-mcp brain-history` | Restore points for this brain — `list` them, `restore <id>` one. Written automatically before every brain write, kept machine-local, and never throttled away for a write that removes cards |
 | `npx klypix-mcp diff [ref]` | Card-level brain diff against a git ref, as markdown |

package/bin/klypix-brain-deleted.mjs

@@ -2,10 +2,21 @@
 // `klypix-mcp brain-deleted [list|restore <id…>|purge] [--brain <path>]`
 // The recycle bin for a brain: cards a human deleted are kept recoverable
 // instead of destroyed. Standalone: node bin/klypix-brain-deleted.mjs <args>
+//
+// Receipts (1.89): "Delete permanently" keeps a content-free receipt in the bin
+// so every other copy of the brain drops the card too (see brain-graveyard.mjs).
+// Receipts are not deleted cards — `list` hides them, restore refuses them, and
+// `list <id>` names what happened to one.
+//
+// Every write re-reads the brain INSIDE the capture lock and refuses when the
+// lock is held: reading outside it and writing later would silently roll back
+// a capture (or a desktop save) that landed in between.
 import fs from 'fs';
 import path from 'path';
 import { listGraveyard, purgeGraveyard, readGraveyardCard, restoreFromGraveyard, DEFAULT_RETENTION_DAYS } from '../src/brain-graveyard.mjs';
 import { atomicWrite } from '../src/klypix-format.mjs';
+import { brainCaptureLockPath, withAdvisoryWriteLock } from '../src/brain-write-lock.mjs';
+import { snapshotBrain } from '../src/brain-history.mjs';
 
 const argv = process.argv.slice(2).filter((a) => a !== 'brain-deleted');
 const action = ['list', 'restore', 'purge'].includes(argv[0]) ? argv.shift() : 'list';
@@ -17,7 +28,6 @@ const all = argv.includes('--all');
 const ids = argv.filter((a) => !a.startsWith('-'));
 
 if (!fs.existsSync(brainPath)) { console.error(`No brain at ${brainPath}.`); process.exit(1); }
-const buf = fs.readFileSync(brainPath);
 
 const ago = (ts) => {
   const m = Math.max(0, Math.round((Date.now() - Number(ts || 0)) / 60000));
@@ -27,8 +37,40 @@ const ago = (ts) => {
   return h < 48 ? `${h}h ago` : `${Math.round(h / 24)}d ago`;
 };
 
+// Read-modify-write under the capture lock. `mutate(buf)` returns
+// { buffer?, ...report }; no buffer means nothing to write.
+async function lockedWrite(reason, mutate, { forceSnapshot = false } = {}) {
+  return withAdvisoryWriteLock(brainCaptureLockPath(brainPath), async (locked) => {
+    if (!locked) return { busy: true };
+    const report = await mutate(fs.readFileSync(brainPath));
+    if (!report.buffer) return report;
+    if (forceSnapshot) {
+      // The one irreversible action gets a restore point that no throttle may
+      // skip, taken inside the lock so it holds exactly the bytes replaced.
+      try { snapshotBrain(brainPath, { reason, force: true }); } catch { /* best-effort by contract */ }
+      await atomicWrite(brainPath, report.buffer, { reason, snapshot: false });
+    } else {
+      await atomicWrite(brainPath, report.buffer, { reason });
+    }
+    return report;
+  });
+}
+const refuseBusy = () => {
+  console.error('The brain is busy (another writer holds the capture lock) — retry in a moment. Nothing written.');
+  process.exit(1);
+};
+
 if (action === 'list') {
-  const entries = await listGraveyard(buf);
+  const buf = fs.readFileSync(brainPath);
+  const everything = await listGraveyard(buf, { receipts: 'include' });
+  // A receipt asked for by id: say what happened to it rather than "not found".
+  for (const e of everything) {
+    if (!ids.includes(e.id) || e.kind === 'deleted') continue;
+    console.log(e.kind === 'restored'
+      ? `  ${e.id}   restored as ${e.restoredAs} ${ago(e.restoredAt || e.deletedAt)} — it is live under that id`
+      : `  ${e.id}   permanently deleted ${ago(e.purgedAt || e.deletedAt)} — its text is gone from this file (an image or file attached to it is not)`);
+  }
+  const entries = everything.filter((e) => e.kind === 'deleted');
   if (!entries.length) {
     console.log(`Nothing deleted from ${path.basename(brainPath)}.`);
     console.log('Cards you delete from a brain are kept here, recoverable, instead of destroyed.');
@@ -53,15 +95,21 @@ if (action === 'list') {
 
 if (action === 'restore') {
   if (!ids.length) { console.error('Usage: brain-deleted restore <id…>   (ids from `brain-deleted list`)'); process.exit(2); }
-  const res = await restoreFromGraveyard(buf, ids);
+  const res = await lockedWrite('graveyard-restore', async (buf) => {
+    const r = await restoreFromGraveyard(buf, ids);
+    return r.restored.length ? r : { restored: [], skipped: r.skipped };
+  });
+  if (res.busy) refuseBusy();
   if (!res.restored.length) {
     for (const s of res.skipped) console.error(`  ${s.id}: ${s.reason}`);
     console.error('Nothing restored.');
     process.exit(1);
   }
-  await atomicWrite(brainPath, res.buffer, { reason: 'graveyard-restore' });
   for (const r of res.restored) {
-    console.log(`Restored ${r.id}${r.reparented ? ' (its container is gone — placed at the canvas root)' : ''}`);
+    const as = r.restoredAs && r.restoredAs !== r.id ? ` as ${r.restoredAs}` : '';
+    console.log(r.already
+      ? `${r.id} is already back${as}`
+      : `Restored ${r.id}${as}${r.reparented ? ' (its container is gone — placed at the canvas root)' : ''}`);
   }
   for (const s of res.skipped) console.log(`Skipped ${s.id}: ${s.reason}`);
   console.log('If the app has this brain OPEN, close and reopen the tab so it sees the restored card.');
@@ -76,12 +124,19 @@ if (!ids.length && !all && !olderThan) {
 }
 const days = olderThan ? Number(String(olderThan).replace(/d$/i, '')) : null;
 if (olderThan && !Number.isFinite(days)) { console.error(`--older-than expects days, e.g. --older-than ${DEFAULT_RETENTION_DAYS}d`); process.exit(2); }
-const res = await purgeGraveyard(buf, {
-  ids: ids.length ? ids : (all ? (await listGraveyard(buf)).map((e) => e.id) : null),
-  olderThanDays: ids.length || all ? null : days,
-});
+const res = await lockedWrite('graveyard-purge', async (buf) => {
+  const r = await purgeGraveyard(buf, {
+    // --all means every deleted card; receipts hold nothing left to purge.
+    ids: ids.length ? ids : (all ? (await listGraveyard(buf, { receipts: 'hide' })).map((e) => e.id) : null),
+    olderThanDays: ids.length || all ? null : days,
+  });
+  return r.purged.length ? r : { purged: [] };
+}, { forceSnapshot: true });
+if (res.busy) refuseBusy();
 if (!res.purged.length) { console.log('Nothing matched — nothing purged.'); process.exit(0); }
-await atomicWrite(brainPath, res.buffer, { reason: 'graveyard-purge' });
 console.log(`Purged ${res.purged.length} deleted card(s) permanently from ${path.basename(brainPath)}.`);
+console.log('The delete itself is kept as a receipt with no content, so copies that sync with this version or later drop the card too.');
+console.log('An edit of it that a merge kept as a separate card elsewhere is not removed: purge that card as well.');
+console.log('Not its attachments: an image or file a purged card held stays in the brain\'s assets, in this file and every copy.');
 console.log('Note: this removes them from the file, not from git history — a secret committed earlier is still in past commits.');
-console.log(`The pre-purge state is a restore point: npx klypix-mcp brain-history list --brain "${brainPath}"`);
+console.log(`The pre-purge state is a restore point, and the only undo: npx klypix-mcp brain-history list --brain "${brainPath}"`);

package/bin/klypix-brain-history.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-// `klypix-mcp brain-history [list|restore <id>|prune] [--brain <path>]`
+// `klypix-mcp brain-history [list|restore <id> [--include-purged]|prune] [--brain <path>]`
 // The human surface for brain restore points. Protection nobody can see is
 // protection nobody trusts, so `list` is the default and it says plainly what
-// each point would give back.
+// each point would give back, and `restore` says what it changed.
 import fs from 'fs';
 import path from 'path';
 import { listBrainHistory, pruneBrainHistory, restoreBrainSnapshot, historyDirFor } from '../src/brain-history.mjs';
@@ -11,6 +11,7 @@ const argv = process.argv.slice(2).filter((a) => a !== 'brain-history');
 const action = ['list', 'restore', 'prune'].includes(argv[0]) ? argv.shift() : 'list';
 const brainIdx = argv.indexOf('--brain');
 const brainPath = path.resolve(brainIdx >= 0 && argv[brainIdx + 1] ? argv.splice(brainIdx, 2)[1] : 'brain.klypix');
+const includePurged = argv.includes('--include-purged');
 const positional = argv.filter((a) => !a.startsWith('-'));
 
 const ago = (ts) => {
@@ -50,7 +51,8 @@ if (action === 'list') {
     console.log(`  ${e.id}   ${ago(e.ts).padEnd(9)} ${String(cards ?? '?').padStart(5)} cards  ${kb(e.bytes).padStart(8)}${e.reason ? `  [${e.reason}]` : ''}${deltaText}`);
   }
   console.log(`\nRestore: npx klypix-mcp brain-history restore <id> --brain "${brainPath}"`);
-  console.log('Restoring snapshots the current file first, so it is itself undoable.');
+  console.log("A restore brings that point's cards back and moves cards added since to Deleted cards.");
+  console.log('It snapshots the current file first, so it is itself undoable.');
   process.exit(0);
 }
 
@@ -63,13 +65,65 @@ if (action === 'prune') {
 // restore
 const id = positional[0];
 if (!id) {
-  console.error('Usage: npx klypix-mcp brain-history restore <id> [--brain <path>]');
+  console.error('Usage: npx klypix-mcp brain-history restore <id> [--include-purged] [--brain <path>]');
   console.error('Run `npx klypix-mcp brain-history list` to see the ids.');
   process.exit(2);
 }
 const { parseKlypix } = await import('../src/klypix-format.mjs');
-const res = await restoreBrainSnapshot(brainPath, id, { parse: parseKlypix });
+const res = await restoreBrainSnapshot(brainPath, id, { parse: parseKlypix, includePurged });
 if (!res.ok) { console.error(`Restore failed: ${res.error}`); process.exit(1); }
-console.log(`Restored ${brainPath} from ${res.restoredFrom} (${kb(res.bytes)}).`);
+
+const SHOW = 10;
+const listIds = (ids, fmt = (x) => x) => {
+  for (const x of ids.slice(0, SHOW)) console.log(`    ${fmt(x)}`);
+  if (ids.length > SHOW) console.log(`    …and ${ids.length - SHOW} more`);
+};
+if (res.mode === 'merge') {
+  const { reverted = [], restored = [], revived = [], buried = [], keptPurged = [] } = res;
+  // Ids alone mean nothing to a person: show each card's first words, from the
+  // live card or from its Deleted cards entry.
+  const text = new Map();
+  try {
+    const { struct } = await parseKlypix(fs.readFileSync(brainPath));
+    for (const c of struct.cards || []) text.set(c.id, String(c.text || c.title || ''));
+    for (const g of struct.graveyard || []) if (!text.has(g.id)) text.set(g.id, String(g.preview || ''));
+  } catch { /* ids only */ }
+  const said = (id) => {
+    const s = (text.get(id) || '').replace(/\s+/g, ' ').trim();
+    return s ? `${id}  "${s.length > 60 ? `${s.slice(0, 59)}…` : s}"` : id;
+  };
+  console.log(`Restored ${brainPath} from ${res.restoredFrom} (${kb(res.bytes)}), merged into the brain as it is now:`);
+  if (reverted.length) {
+    console.log(`  ${reverted.length} card(s) set back to how they were then:`);
+    listIds(reverted, said);
+  }
+  if (restored.length) {
+    console.log(`  ${restored.length} card(s) that had left with no record came back:`);
+    listIds(restored, said);
+  }
+  if (revived.length) {
+    console.log(`  ${revived.length} card(s) back from Deleted cards, under new ids so every copy agrees the old ones were deleted:`);
+    listIds(revived, (r) => (r.already ? `${said(r.as)} (already back)` : said(r.as)));
+  }
+  if (buried.length) {
+    console.log(`  ${buried.length} card(s) added since that point moved to Deleted cards:`);
+    listIds(buried, said);
+    console.log(`    Bring one back: npx klypix-mcp brain-deleted restore <id> --brain "${brainPath}"`);
+  }
+  if (keptPurged.length) {
+    console.log(`  ${keptPurged.length} permanently deleted card(s) kept out:`);
+    listIds(keptPurged);
+    console.log('    Add --include-purged to bring them back too (under new ids).');
+  }
+  if (!reverted.length && !restored.length && !buried.length && !keptPurged.length && revived.every((r) => r.already)) {
+    console.log('  The brain already matched that point; nothing changed.');
+  }
+} else if (res.mode === 'recreate') {
+  console.log(`The brain file was missing. Recreated ${brainPath} from ${res.restoredFrom} (${kb(res.bytes)}).`);
+} else {
+  console.log(`Restored ${brainPath} from ${res.restoredFrom} (${kb(res.bytes)}).`);
+  console.warn('Warning: the merge engine installed beside this command is older, so this restore replaced the whole file.');
+  console.warn('Brain Sync and git will read the cards it removed as deletes. Update with: npx klypix-mcp install');
+}
 if (res.safetyId) console.log(`The state you just replaced was saved as ${res.safetyId} — undo with: npx klypix-mcp brain-history restore ${res.safetyId}`);
 console.log('If the app has this brain OPEN, close and reopen the tab: its in-memory copy is now older than disk and a save would merge it back.');

package/bin/klypix-git-tools.mjs

@@ -2,7 +2,7 @@
 // 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
+//   git-driver [install|status] [repo]   register the card-level .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
@@ -85,21 +85,51 @@ async function loadEngine() {
 
 // ── git-driver ──────────────────────────────────────────────────────────────
 
-const ENGINE_FILES = ['klypix-merge-driver.mjs', 'merge-brains.mjs', 'klypix-format.mjs', 'brain-graveyard.mjs'];
+// Dependencies first: klypix-format ← brain-graveyard ← merge-brains ← driver.
+// Each file is swapped in atomically, so at every moment the set on disk can
+// link — a new merge-brains beside an old klypix-format is the one mix that
+// cannot (it imports names the old file lacks).
+const ENGINE_FILES = ['klypix-format.mjs', 'brain-graveyard.mjs', 'merge-brains.mjs', 'klypix-merge-driver.mjs'];
 const ENGINE_DEPS = ['jszip', 'fractional-indexing'];
 
+const readJson = (p) => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } };
+
 // Make sure the INSTALLED runtime can actually run the driver: the four
 // engine files plus their two runtime deps. This is deliberately a
 // light provision — it never touches hooks or servers; the full installer
 // remains `npx klypix-mcp install`.
-function ensureDriverRuntime() {
+//
+// Never a downgrade. The same files arrive from the full installer, the
+// desktop bundle and auto-update; an older `npx klypix-mcp git-driver install`
+// (or a pinned devDependency) must not put its engine under a newer one. So
+// the files are copied only when the install gate says this package may
+// install (brainInstallDecision — the same rule the full installer uses), and
+// then always as the whole set.
+async 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);
+  const { brainInstallDecision } = await import(new URL('../src/install-version.mjs', import.meta.url).href);
+  const pkg = readJson(path.join(HERE, '..', 'package.json'));
+  const stamp = readJson(path.join(BRAIN_DIR, '.brain-version.json'));
+  const runtime = readJson(path.join(BRAIN_DIR, '.mcp-runtime.json'));
+  const decision = brainInstallDecision({ candidateVersion: pkg?.version, stamp, runtime });
+  const result = { provisioned };
+  if (decision.action === 'preserve') {
+    const owner = decision.reason === 'dev-owned' ? 'a dev deploy' : `v${decision.installedVersion}${stamp?.via ? ` (via ${stamp.via})` : ''}`;
+    result.kept = `kept the engine installed by ${owner}; this package is v${decision.candidateVersion}`;
+    const missing = ENGINE_FILES.filter((f) => !fs.existsSync(path.join(BRAIN_DIR, f)));
+    if (missing.length) result.missing = missing;
+  } else {
+    // Only files that differ are written, so what is on disk afterwards is
+    // exactly this package's set.
+    for (const f of ENGINE_FILES) {
+      const dest = path.join(BRAIN_DIR, f);
+      const body = fs.readFileSync(path.join(SRC, f), 'utf8');
+      if (fs.existsSync(dest) && fs.readFileSync(dest, 'utf8') === body) continue;
+      const tmp = `${dest}.klypix-new-${process.pid}`;
+      fs.writeFileSync(tmp, body);
+      try { fs.renameSync(tmp, dest); }
+      catch (err) { try { fs.unlinkSync(tmp); } catch { /* */ } throw err; }
       provisioned.push(f);
     }
   }
@@ -152,7 +182,7 @@ function ensureDriverRuntime() {
   };
   const seen = new Set();
   for (const dep of ENGINE_DEPS) provisionDep(dep, path.join(HERE, '..'), seen);
-  return provisioned;
+  return result;
 }
 
 const DRIVER_ATTR_RULE = '*.klypix merge=klypix -text';
@@ -180,21 +210,23 @@ async function gitDriver() {
     process.exit(configured && gaHasRule && runtimeOk ? 0 : 1);
   }
 
-  const provisioned = ensureDriverRuntime();
+  const { provisioned, kept, missing } = await 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.name', 'KLYPIX brain merge (3-way, card by card)']);
     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`;
+    const rule = `${gaText && !gaText.endsWith('\n') ? '\n' : ''}# .klypix brains merge card by card via the KLYPIX 3-way 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(', ')})` : ''}`);
+  if (kept) console.log(`    engine: ${kept}`);
+  if (missing?.length) console.log(`    ! the installed engine is missing ${missing.join(', ')} — repair it with: npx klypix-mcp@latest install`);
   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.');
 }

package/bin/klypix-install.mjs

@@ -395,7 +395,14 @@ try {
     // canvas-view-app.html is the canvas_view MCP App UI — staged raw (an HTML
     // file must never get a JS-comment banner) beside the flat server, which
     // resolves it via its ./canvas-view-app.html candidate path.
-    for (const f of ['global-brain-hook.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'provenance.mjs', 'brain-note.mjs', 'brain-evidence.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'editor-detect.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
+    // Files are renamed one at a time in this order (the hook last), so the
+    // shared libraries go FIRST and the merge engine in dependency order —
+    // klypix-format, brain-graveyard, merge-brains, the git driver. A newer
+    // file beside an older klypix-format can fail to link; an older one beside
+    // a newer klypix-format cannot. merge-brains and the driver ship here so
+    // brain-history's restore merge, the KLYPIX core and the git driver all
+    // find one engine in this directory.
+    for (const f of ['global-brain-hook.mjs', 'klypix-format.mjs', 'brain-graveyard.mjs', 'merge-brains.mjs', 'klypix-merge-driver.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'provenance.mjs', 'brain-note.mjs', 'brain-evidence.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'editor-detect.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
     for (const [src, dst] of [

package/bin/klypix-mcp.mjs

@@ -35,7 +35,7 @@ const USAGE = [
   '  init                                seed a starter ./brain.klypix + print an MCP config',
   '  garden-code [brain]                 print the human approval code for brain_garden',
   '  uninstall [--check|--yes|unlink]    remove this install from the machine (--check inventories first; never deletes a .klypix)',
-  '  git-driver [install|status] [repo]  register the lossless .klypix merge driver for a repo (zero-command teams)',
+  '  git-driver [install|status] [repo]  register the card-level .klypix merge driver for a repo (zero-command teams)',
   '  git-hook [install|remove|status]    wire the agent-neutral commit-capture hook (any agent/branch/worktree → brain cards)',
   '  brain-history [list|restore <id>]   restore points for this brain — undo an accidental delete, edit, or overwrite',
   '  brain-deleted [list|restore|purge]  recycle bin for this brain — cards you deleted, kept recoverable',

package/bin/klypix-worker.mjs

@@ -116,7 +116,7 @@ await runVerb('doctor', './klypix-doctor.mjs');
 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
+// card-level .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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.88.0",
+  "version": "1.89.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
@@ -84,7 +84,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs &&node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.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/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs",
+    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.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/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs",