klypix-mcp 1.88.0 → 1.90.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)
 ```
 
@@ -460,8 +460,8 @@ receiving model calls `brain_message_receipt` with the exact message id and per-
 token; only that token-bound action records `consumed`. Pending, offered, and acknowledged notes
 survive reconnects. Expiry or bounded-capacity eviction records a failed per-recipient receipt
 instead of silently looking delivered. The send-time audience is fixed, unresolved targeted sends
-fail closed, the core lane is machine-local, notes expire after 24 hours, and they are never written
-into the brain.
+fail closed, the core lane is machine-local, a note to every session expires after 24 hours and a
+directed note after 7 days, and notes are never written into the brain.
 
 Durable handoffs go in the brain itself — decisions, findings, open questions and skills captured
 as cards, each stamped with the agent that wrote it.
@@ -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 |
@@ -730,19 +750,59 @@ replaceable worker runs the brain core. A staged update is hash-verified, initia
 checked for backward-compatible tool schemas, and handed the current `brain_sync` task scope before
 the supervisor switches between requests. Added tools use the standard
 `notifications/tools/list_changed` signal. A failed or breaking candidate is rejected while the old
-worker keeps serving. A blocked result claim is kept in a durable per-project/session marker, so a
-worker replacement cannot turn a failed evidence check into a result-less completion.
+worker keeps serving. A connection idle for 10 minutes releases its worker and keeps its presence;
+it stays asleep until its host sends a request, and the new worker it then starts passes the same
+checks. If they reject it, the connection resumes the version it last ran, or answers with a
+retryable `/mcp reconnect` error rather than restarting in a loop. A blocked result claim is kept
+in a durable per-project/session marker, so a worker replacement cannot turn a failed evidence
+check into a result-less completion.
 
 Compatible engine updates therefore activate behind the same live connection — no reconnect, no
 host restart. Three cases still require a deliberate reconnect or manual install: the one-time
-legacy→supervisor migration, a supervisor-code change, and a major or tool-removing release.
-`brain_doctor` reports the live supervisor and the automatic-update receipt explicitly.
-
-The supervisor performs **one machine-wide npm version check per 24 hours**, however many sessions
-are open. It installs an exact stable same-major release in `--runtime-only` mode, preserving host
-settings and project files. The check is detached and fail-open, developer-owned installs are
-protected, concurrent sessions collapse behind one lock, and `KLYPIX_AUTO_UPDATE=0` opts out
-entirely.
+legacy→supervisor migration, a supervisor-code change, and a major or tool-removing release. Fixes
+to the supervisor itself reach a connection only after one `/mcp` reconnect or a host restart;
+worker and doctor changes hot-swap. `brain_doctor` reports the live supervisors (including how many
+still run older supervisor code) and the automatic-update schedule: the last result, which install
+it describes, and when the next check runs. The MCP tool also returns these as structured data.
+
+The updater checks npm **once per machine every 6 hours**, however many sessions are open. It
+checks once more, never sooner than 5 minutes after the last attempt, when another install upgrades
+this runtime or moves it from a developer deploy to a released install. Examples are a manual
+`npx klypix-mcp install` of a newer release, or a release replacing a developer deploy. A failed
+check retries after 15 minutes, then 1 hour, then 4 hours, then returns to the 6-hour cadence. Each
+attempt is recorded as failed before it touches the network, so a check that dies part-way backs
+off instead of retrying in a loop. Checks run from the open KLYPIX sessions: the supervisor and
+worker look every 10 minutes, and a new session looks 2 seconds after it starts.
+
+The updater installs an exact stable release of the **same major version** in `--runtime-only`
+mode, preserving host settings and project files; a new major always needs a manual install. It
+never downgrades. A deliberate downgrade (`npx klypix-mcp@<older> install --force`) onto a release
+newer than 1.89.0 is **held**: the updater does not re-install the version it was rolled back from,
+only a newer release. To take the held version back, run `npx -y klypix-mcp@latest install` (or set
+`KLYPIX_AUTO_UPDATE_FORCE=1` where `KLYPIX_AUTO_UPDATE` is set, below, for one check, then remove
+it). A rollback onto 1.89.0 or earlier also rolls the updater back, and those releases have no
+hold: they re-install the newest same-major release within 24 hours of their last check. To stay
+on such a release, set `KLYPIX_AUTO_UPDATE=0` in every place listed below for as long as you stay;
+`brain_doctor` warns when a downgrade is not held. The updater never fetches anything for a
+developer-owned install and never installs over it. The check is detached and fail-open, and
+concurrent sessions collapse behind one lock.
+
+`KLYPIX_AUTO_UPDATE=0` opts out. Every process reads its own environment, so set it in each host's
+launch environment: the `env` of each KLYPIX MCP server entry, and the environment Claude Code runs
+its hooks in. It takes effect at that host's next supervisor start or `/mcp` reconnect.
+
+There is one second, smaller probe. In a brain project (a directory with `./brain.klypix`), the
+Claude Code Stop hook refreshes a local npm-version cache, which the next SessionStart reads to say
+whether an update is available. That notice also says what the updater will do with the update,
+and when. The probe:
+
+- runs at most once a day, developer-owned installs included;
+- makes the same kind of anonymous request the updater makes, a GET of
+  `https://registry.npmjs.org/klypix-mcp/latest` that carries no user or machine identifier;
+- is skipped while the updater fetched npm's latest version less than a day ago;
+- is off with the same `KLYPIX_AUTO_UPDATE=0`, read from the environment Claude Code runs its hooks
+  in;
+- never installs anything.
 
 When the optional semantic runtime is already enabled, an update also schedules one detached,
 single-writer cache migration across registered brains. That removes the multi-minute first-query
@@ -754,9 +814,13 @@ keep lazy first-use indexing instead.
 
 - **Apache-2.0, source public** at [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
 - **The brain engine makes no network calls and sends no telemetry.** All engine intelligence is
-  deterministic and local; the only LLM anywhere is *your* agent. The one exception in this package
-  is the supervisor's once-per-24h npm version check described above — turn it off with
-  `KLYPIX_AUTO_UPDATE=0`.
+  deterministic and local; the only LLM anywhere is *your* agent. The exceptions in this package
+  are the two update probes described above. One is the updater's npm version check, every 6
+  hours, plus one re-check after another install upgrades the runtime, and retries after a failed
+  check (15 minutes, 1 hour, 4 hours); when it finds a newer same-major release, it also runs that
+  release's npm install. The other is the Claude Code Stop hook's version probe, at most once a day
+  in brain projects. Both are the same kind of anonymous GET of the package's `latest` version, and
+  `KLYPIX_AUTO_UPDATE=0` turns both off.
 - **The optional semantic model runs on device.** Enabling it (or upgrading its model) can fetch
   model weights from Hugging Face; retrieval inference and brain data stay local.
 - **Coordination state is local files.** The brain is a file in your repo; the presence lane is a
@@ -849,8 +913,8 @@ independently validated.
   fewer than four content words: junk injection 93% → 35%, mean cards injected on junk 3.6 → 1.5,
   at a one-question cost on the 35 real prompts (inside noise). The prompts stay private; the
   sweep tables are in the source next to the bars they chose.
-- **What we do not publish.** No download count: this package's own 24-hour auto-updater generates
-  most of it, so it is not a user count. No adoption, team or customer figures. No brief-token
+- **What we do not publish.** No download count: this package's own auto-updater generates most
+  of it, so it is not a user count. No adoption, team or customer figures. No brief-token
   figure — the last one was measured at ~600 cards and is stale at 2,479.
 - **The eval harness is not in this repo.** It lives in the private KLYPIX desktop repository. The
   numbers above are ours to defend, not yours to reproduce from here — treat them accordingly.

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-doctor.mjs

@@ -2,8 +2,8 @@
 // klypix-doctor — `npx klypix-mcp doctor`. The brain's self-check: is THIS machine's
 // brain current, are the Claude capture and Codex presence adapters wired, what verbs
 // does it expose, which lifecycle sessions are live, and is the harness projection in
-// sync? ONE fact, ONE reconcile block. Read-only (never writes). Exits 0 = ALIGNED,
-// 1 = DRIFTED — so it
+// sync? ONE fact, ONE reconcile block. Read-only (never writes). Exits 0 = ALIGNED
+// or PARTIAL (readiness warnings, no drift), 1 = DRIFTED — so it
 // doubles as a pre-commit / CI readiness gate.
 //
 //   npx klypix-mcp doctor              # this project + this machine's brain
@@ -63,9 +63,14 @@ try {
   }
 
   const drifted = report.verdict === 'DRIFTED' || extraDrift > 0;
+  // PARTIAL used to end with "✓ aligned." under a head that said PARTIAL
+  // (2026-10-03) — the closing line is what people read. Exit code unchanged.
+  const warnings = Array.isArray(report.readinessWarnings) ? report.readinessWarnings.length : 0;
   console.log(drifted ? (color ? '\x1b[33m' : '') + `\n✗ drift found — see reconcile above.` + (color ? '\x1b[0m' : '')
     : report.verdict === 'NOT-INSTALLED' ? '\n• brain not installed on this machine.'
-      : (color ? '\x1b[32m' : '') + '\n✓ aligned.' + (color ? '\x1b[0m' : ''));
+      : report.verdict === 'PARTIAL'
+        ? (color ? '\x1b[33m' : '') + `\n• partial — ${warnings} readiness warning${warnings === 1 ? '' : 's'} above (no drift)` + (color ? '\x1b[0m' : '')
+        : (color ? '\x1b[32m' : '') + '\n✓ aligned.' + (color ? '\x1b[0m' : ''));
   process.exit(drifted ? 1 : 0);
 } catch (e) {
   console.error(`✗ doctor failed: ${e?.message || e}`);

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 [