klypix-mcp 1.63.0 → 1.65.0

package/README.md

@@ -416,6 +416,32 @@ rename, so a crash mid-write leaves the previous good file intact. The lock is a
 sustained contention can still lose an update. That is a deliberate trade — dropping the markers
 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
+*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
+and peers on other machines all write to it while nobody is watching, so you can destroy work you
+never saw arrive.
+
+So every brain write takes a restore point of the previous bytes first:
+
+```bash
+npx klypix-mcp brain-history list          # age, card count, delta against the brain now
+npx klypix-mcp brain-history restore <id>  # and this is itself undoable
+```
+
+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
+never throttled, because that is the case they exist for. Retention is the newest 20 plus one per
+day for 14 days, so a slow-burn mistake is still recoverable without unbounded growth. A snapshot
+that cannot be written is logged and skipped — it never blocks your save.
+
+Normal canvases deliberately get none of this. One human made every mark and saw every change; the
+brain is the file where that is not true.
+
 ---
 
 ## The command line
@@ -432,6 +458,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `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-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 |
 | `npx klypix-mcp pr-brief [ref]` | Brain cards referencing the files changed since a ref, as markdown |
 | `npx klypix-mcp garden-code` | Print the human approval code `brain_garden` requires |

package/bin/klypix-brain-deleted.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// `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>
+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';
+
+const argv = process.argv.slice(2).filter((a) => a !== 'brain-deleted');
+const action = ['list', 'restore', 'purge'].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 flag = (name) => { const i = argv.indexOf(name); return i >= 0 ? (argv.splice(i, 2)[1] ?? '') : null; };
+const olderThan = flag('--older-than');
+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));
+  if (!ts) return 'unknown';
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  return h < 48 ? `${h}h ago` : `${Math.round(h / 24)}d ago`;
+};
+
+if (action === 'list') {
+  const entries = await listGraveyard(buf);
+  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.');
+    process.exit(0);
+  }
+  console.log(`${entries.length} deleted card(s) in ${path.basename(brainPath)} — newest first\n`);
+  for (const e of entries) {
+    const full = ids.includes(e.id) ? await readGraveyardCard(buf, e.id) : null;
+    console.log(`  ${e.id}   ${ago(e.deletedAt).padEnd(9)} ${e.area ? `[${e.area}] ` : ''}${e.preview || '(no text)'}`);
+    if (full?.content) console.log(`\n${String(full.content).split('\n').map((l) => `      ${l}`).join('\n')}\n`);
+  }
+  console.log(`\nFull text:  npx klypix-mcp brain-deleted list <id> --brain "${brainPath}"`);
+  console.log(`Restore:    npx klypix-mcp brain-deleted restore <id>`);
+  console.log(`Purge:      npx klypix-mcp brain-deleted purge --older-than ${DEFAULT_RETENTION_DAYS}d   (or: purge <id>, purge --all)`);
+  process.exit(0);
+}
+
+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);
+  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)' : ''}`);
+  }
+  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.');
+  process.exit(0);
+}
+
+// purge
+if (!ids.length && !all && !olderThan) {
+  console.error(`Usage: brain-deleted purge --older-than ${DEFAULT_RETENTION_DAYS}d | purge <id…> | purge --all`);
+  console.error('Purge is permanent. A restore point is written first (npx klypix-mcp brain-history list).');
+  process.exit(2);
+}
+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,
+});
+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('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}"`);

package/bin/klypix-install.mjs

@@ -293,7 +293,7 @@ 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', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'finding-routing.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']) {
+    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.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', 'agent-presence.mjs', 'mcp-presence.mjs', 'finding-routing.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

@@ -19,7 +19,7 @@ const PKG_VERSION = (() => {
   }
 })();
 
-const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'git-hook', 'brain-history', 'diff', 'pr-brief', 'uninstall', 'bench']);
+const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'git-hook', 'brain-history', 'brain-deleted', 'diff', 'pr-brief', 'uninstall', 'bench']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -37,6 +37,7 @@ const USAGE = [
   '  git-driver [install|status] [repo]  register the lossless .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',
   '  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',
   '',

package/bin/klypix-worker.mjs

@@ -125,6 +125,10 @@ await runVerb('git-hook', './klypix-git-hook.mjs');
 // written before every brain write. The recovery path for an accidental card
 // deletion, a destructive edit, a stale overwrite, or a deleted brain file.
 await runVerb('brain-history', './klypix-brain-history.mjs');
+// `npx klypix-mcp brain-deleted` — the brain's recycle bin. A human delete moves
+// the card's bytes to graveyard/ instead of destroying them; this lists, restores
+// and (permanently) purges them.
+await runVerb('brain-deleted', './klypix-brain-deleted.mjs');
 await runVerb('diff', './klypix-diff.mjs');
 await runVerb('pr-brief', './klypix-pr-brief.mjs');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.63.0",
+  "version": "1.65.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -79,7 +79,7 @@
     "test:project-graph": "node test/project-graph.mjs",
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
-    "test": "node test/publish-verdict.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/agent-presence.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.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/brain-connect-orphans.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/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/publish-verdict.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/agent-presence.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/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/brain-connect-orphans.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/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

package/src/brain-graveyard.mjs

@@ -0,0 +1,131 @@
+// brain-graveyard — the recoverable bin for cards a human deleted from a brain.
+//
+// WHY THIS AND NOT THE ARCHIVE CONTAINER. "Archived" in a KLYPIX brain is a
+// containment fact: the card's parent is a container titled "Archive". Those
+// cards are STILL in canvas.json's `order`, so they still render — this repo's
+// own brain has 275 of them on the canvas right now. Routing deletes there
+// would make a deleted card visibly reappear (and, because the merge's position
+// comparator ignores parentId, reappear exactly where it was). It would also
+// leak: `read_canvas` and `search_canvases` have no archive awareness at all,
+// `brain_ask` includes archived cards by design, and the embedder embeds them.
+//
+// So a deleted card leaves `order` entirely and its bytes move to `graveyard/`,
+// which `parseKlypix` reads into `struct.graveyard` and deliberately never
+// merges into `struct.cards`. That one choice makes every leak impossible by
+// construction rather than by remembering to filter in 30-odd call sites.
+//
+// PURGE STAYS AVAILABLE, AND HONEST. brain.klypix is git-tracked and syncs to
+// collaborators, so "delete" is also the escape hatch for a pasted key or a
+// personal detail. Purge removes the bytes from the working file — it cannot
+// remove them from git history, and the caller is told so.
+import fs from 'fs';
+import JSZip from 'jszip';
+import { parseKlypix, shard } from './klypix-format.mjs';
+
+export const DEFAULT_RETENTION_DAYS = 30;
+
+/** Deleted cards, newest first. */
+export async function listGraveyard(buf) {
+  const { struct } = await parseKlypix(buf);
+  return struct.graveyard || [];
+}
+
+async function readIndex(zip) {
+  const f = zip.file('graveyard.json');
+  if (!f) return { version: 1, entries: {} };
+  try {
+    const parsed = JSON.parse(await f.async('string'));
+    return { version: 1, entries: (parsed && parsed.entries) || {} };
+  } catch { return { version: 1, entries: {} }; }
+}
+
+function writeIndex(zip, index) {
+  if (Object.keys(index.entries).length) zip.file('graveyard.json', JSON.stringify(index));
+  else zip.remove('graveyard.json');
+}
+
+/**
+ * Put a deleted card back into the brain. It returns to `order` (so it renders
+ * again) at its recorded position, and leaves the bin — a card must never be in
+ * both, or the next restore would duplicate it.
+ *
+ * Its former parent may itself be gone; in that case the card is restored to
+ * the canvas root rather than into a dangling container.
+ */
+export async function restoreFromGraveyard(buf, ids) {
+  const zip = await JSZip.loadAsync(buf);
+  const index = await readIndex(zip);
+  const canvasFile = zip.file('canvas.json');
+  if (!canvasFile) throw new Error('Not a .klypix canvas — missing canvas.json');
+  const canvas = JSON.parse(await canvasFile.async('string'));
+  canvas.order = Array.isArray(canvas.order) ? canvas.order : [];
+  canvas.positions = canvas.positions || {};
+  const liveIds = new Set(canvas.order);
+
+  const restored = [], skipped = [];
+  for (const rawId of ids) {
+    const id = String(rawId);
+    const entry = index.entries[id];
+    const file = zip.file(`graveyard/${shard(id)}/${id}.json`);
+    if (!entry || !file) { skipped.push({ id, reason: 'not in the bin' }); continue; }
+    if (liveIds.has(id)) { skipped.push({ id, reason: 'already in the brain' }); continue; }
+
+    zip.file(`items/${shard(id)}/${id}.json`, await file.async('string'));
+    const pos = entry.pos || { x: 0, y: 0 };
+    // Re-parent only if the container still exists — a card must never point at
+    // a container that was itself deleted, which would make it unreachable.
+    const parentAlive = entry.parentId && liveIds.has(entry.parentId);
+    canvas.positions[id] = {
+      x: Number(pos.x) || 0, y: Number(pos.y) || 0,
+      ...(pos.w != null ? { w: pos.w } : {}), ...(pos.h != null ? { h: pos.h } : {}),
+      zIndex: canvas.order.length,
+      parentId: parentAlive ? entry.parentId : null,
+    };
+    canvas.order.push(id);
+    liveIds.add(id);
+    zip.remove(`graveyard/${shard(id)}/${id}.json`);
+    delete index.entries[id];
+    restored.push({ id, reparented: Boolean(entry.parentId) && !parentAlive });
+  }
+
+  zip.file('canvas.json', JSON.stringify(canvas));
+  writeIndex(zip, index);
+  const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  await parseKlypix(buffer);          // never hand back an unreadable brain
+  return { buffer, restored, skipped };
+}
+
+/**
+ * Permanently remove entries from the bin. `olderThanDays` purges by age;
+ * explicit `ids` purge regardless of age (the secret-was-pasted case).
+ */
+export async function purgeGraveyard(buf, { ids = null, olderThanDays = null, now = Date.now() } = {}) {
+  const zip = await JSZip.loadAsync(buf);
+  const index = await readIndex(zip);
+  const cutoff = olderThanDays != null ? now - olderThanDays * 24 * 60 * 60 * 1000 : null;
+
+  const target = [];
+  for (const [id, meta] of Object.entries(index.entries)) {
+    if (ids) { if (ids.includes(id)) target.push(id); continue; }
+    if (cutoff != null && Number(meta?.deletedAt || 0) < cutoff) target.push(id);
+  }
+  for (const id of target) {
+    zip.remove(`graveyard/${shard(id)}/${id}.json`);
+    delete index.entries[id];
+  }
+  writeIndex(zip, index);
+  const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  await parseKlypix(buffer);
+  return { buffer, purged: target };
+}
+
+/** Read a buried card's full text — so `list` can show more than a preview. */
+export async function readGraveyardCard(buf, id) {
+  const zip = await JSZip.loadAsync(buf);
+  const f = zip.file(`graveyard/${shard(String(id))}/${String(id)}.json`);
+  if (!f) return null;
+  try { return JSON.parse(await f.async('string')); } catch { return null; }
+}
+
+/** Convenience for CLI/desktop callers that work in files rather than buffers. */
+export const readBrain = (p) => fs.readFileSync(p);

package/src/klypix-core.mjs

@@ -264,11 +264,17 @@ export async function opSearchCanvases({ vault, query }) {
       hit(c.text) ||
       (c.tags || []).some(t => hit('#' + t)));
     if (nameMatch || matched.length) {
-      const head = `## ${rel} — "${struct.title}" · ${struct.counts.cards} cards, ${struct.counts.connections} connections${nameMatch && !matched.length ? '  (name/title match)' : ''}`;
+      // Matching stays recall-first (an archived card CAN be the right answer to
+      // "what did we try?"), but an archived hit is now labelled. Unlabelled, a
+      // superseded or retired decision read exactly like a current one.
+      const isArchived = (c) => /^archive$/i.test(c.area || '');
+      const n = struct.counts;
+      const head = `## ${rel} — "${struct.title}" · ${n.live ?? n.cards} live cards${n.archived ? `, ${n.archived} archived` : ''}, ${n.connections} connections${nameMatch && !matched.length ? '  (name/title match)' : ''}`;
       const body = matched.slice(0, 8).map(c => {
         const pos = (c.pos && c.pos.x != null) ? ` @(${Math.round(c.pos.x)},${Math.round(c.pos.y)})` : '';
         const tags = (c.tags && c.tags.length) ? ' ' + c.tags.map(t => '#' + t).join(' ') : '';
-        return `- [${c.type}] "${c.title || '(card)'}" (${c.id})${pos}${tags}\n    ${String(c.text || '').replace(/\s+/g, ' ').slice(0, 240)}`;
+        const arch = isArchived(c) ? ' ⛔ archived' : '';
+        return `- [${c.type}] "${c.title || '(card)'}" (${c.id})${pos}${tags}${arch}\n    ${String(c.text || '').replace(/\s+/g, ' ').slice(0, 240)}`;
       }).join('\n');
       hits.push(matched.length ? `${head}\n${body}` : head);
     }

package/src/klypix-format.mjs

@@ -296,6 +296,28 @@ export async function parseKlypix(buffer) {
         for (const it of canvas.items) items[it.id] = it;
     }
 
+    // ── Graveyard: cards a human deleted, kept recoverable ───────────────────
+    // Read from `graveyard.json`, and DELIBERATELY not merged into `items`,
+    // `cards`, `order` or `positions`. That single choice is the whole safety
+    // argument: a deleted card cannot render (the renderer only ever walks
+    // `order`), cannot leak through read_canvas / search_canvases (which walk
+    // `struct.cards`), cannot be embedded or ranked into an answer, and cannot
+    // skew a count — with zero edits to any of those call sites. Contrast the
+    // Archive container, which is containment-only: its 275 cards in this
+    // repo's own brain DO render, and would have reappeared in place.
+    let graveyard = [];
+    try {
+        const gRaw = await readText('graveyard.json');
+        if (gRaw) {
+            const parsed = JSON.parse(gRaw);
+            const entries = parsed && typeof parsed === 'object' ? (parsed.entries || {}) : {};
+            graveyard = Object.entries(entries)
+                .map(([id, e]) => ({ id, ...(e && typeof e === 'object' ? e : {}) }))
+                .filter(e => e.id)
+                .sort((a, b) => Number(b.deletedAt || 0) - Number(a.deletedAt || 0));
+        }
+    } catch { /* a corrupt index must never fail the whole parse */ }
+
     const connections = Array.isArray(canvas.connections) ? canvas.connections : [];
     const titleOf = (id) => cardTitle(items[id]) || (items[id]?.type ? `${items[id].type} ${String(id).slice(0, 8)}` : String(id).slice(0, 8));
     const assetPaths = Object.keys(zip.files).filter(p => p.startsWith('assets/') && !zip.files[p].dir);
@@ -304,7 +326,20 @@ export async function parseKlypix(buffer) {
     const struct = {
         title: manifest?.title || canvas.title || 'Untitled',
         format: isV4 ? 'klypix-v4' : `legacy-v${canvas.version ?? '?'}`,
-        counts: { cards: cards.length, connections: connections.length, assets: assetPaths.length },
+        // `cards` counts EVERY item in `order` — containers and archived cards
+        // included — and several headers print it raw, so a brain whose brief
+        // describes 1,574 live cards announced "1981 cards". Keeping it (readers
+        // depend on it) and adding the honest breakdown beside it, so a surface
+        // that means "how much is live here" can say so.
+        counts: {
+            cards: cards.length,
+            connections: connections.length,
+            assets: assetPaths.length,
+            containers: cards.filter(c => c?.type === 'container').length,
+            archived: cards.filter(c => c?.type !== 'container' && /^archive$/i.test(
+                (c?.parentId ? cardTitle(items[c.parentId]) : '') || '')).length,
+            get live() { return this.cards - this.containers - this.archived; },
+        },
         cards: cards.map(it => ({
             id: it.id, type: it.type,
             title: cardTitle(it),
@@ -341,6 +376,9 @@ export async function parseKlypix(buffer) {
             relationship: c.relationship || null, label: c.label || null,
         })),
         assets: assetPaths.map(p => path.basename(p)),
+        // Recoverable deletions, newest first. Never counted in counts.cards —
+        // a deleted card is not part of the brain, it is part of its bin.
+        graveyard,
     };
     return { struct, zip, assetPaths, isV4, canvas, manifest };
 }
@@ -5105,12 +5143,22 @@ export function lensToMarkdown(d, view = 'all') {
 
 /** Render a parsed struct to the markdown brief (shared by read-klypix + MCP). */
 export function structToMarkdown(struct, { assetsDir } = {}) {
+    // Archived cards were rendered here IDENTICALLY to live ones — no marker, and
+    // `area` was never printed at all — so read_canvas served superseded,
+    // consolidated and deleted-then-archived decisions as current fact. This is
+    // the surface an agent reads to learn a project, which makes it the worst
+    // place for that. They stay in the output (this is a whole-canvas dump, and
+    // history is legitimately part of it) but they are now labelled.
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
     const L = [];
+    const n = struct.counts;
     L.push(`# ${struct.title}`);
-    L.push(`*${struct.format} · ${struct.counts.cards} cards · ${struct.counts.connections} connections · ${struct.counts.assets} assets*\n`);
+    L.push(`*${struct.format} · ${n.live ?? n.cards} live cards${n.archived ? ` · ${n.archived} archived` : ''}${n.containers ? ` · ${n.containers} containers` : ''} · ${n.connections} connections · ${n.assets} assets*\n`);
+    if (n.archived) L.push(`> ⛔ ${n.archived} card(s) below are marked archived — superseded, consolidated or retired. Read them as history, not as the current state.\n`);
     L.push(`## Cards`);
     for (const c of struct.cards) {
-        L.push(`### ${c.title || `(${c.type})`}  \`${c.type}\``);
+        const archived = isArchived(c);
+        L.push(`### ${c.title || `(${c.type})`}  \`${c.type}\`${archived ? '  ⛔ archived' : ''}${c.area && !archived ? `  _[${c.area}]_` : ''}`);
         if (c.text) L.push(c.type === 'text' ? String(c.text).trim() : `→ ${c.text}`);
         const meta = [];
         if (c.links?.length) meta.push(`links: ${c.links.map(t => `[[${t}]]`).join(', ')}`);

package/src/merge-brains.mjs

@@ -106,8 +106,17 @@ async function loadSide(buf) {
     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 || '']));
+  // Graveyard: deleted-but-recoverable cards. Carried verbatim so a merge never
+  // empties another machine's bin, and so the bytes a tombstone removes from
+  // `order` are preserved rather than destroyed.
+  const graveyard = {};             // id -> { meta, json }
+  for (const e of (struct.graveyard || [])) {
+    const f = zip.file(`graveyard/${shard(e.id)}/${e.id}.json`);
+    const { id, ...meta } = e;
+    graveyard[e.id] = { meta, json: f ? await f.async('string') : null };
+  }
   return {
-    order, positions, items, assets, manifest,
+    order, positions, items, assets, manifest, graveyard,
     connections: Array.isArray(canvas.connections) ? canvas.connections : [],
     lines: Array.isArray(canvas.lines) ? canvas.lines : [],
     strokes: Array.isArray(canvas.strokes) ? canvas.strokes : [],
@@ -152,6 +161,39 @@ export async function mergeBrains({ base = null, ours, theirs, deletedIds = [] }
   const conflicts = [];
   const delta = { added: [], updated: [], archived: [], removed: [] };
 
+  // ── Graveyard (2026-08-07) ───────────────────────────────────────────────
+  // An honored tombstone still REMOVES the card from the brain — `order`,
+  // `positions` and `struct.cards` are unchanged, so every read surface, the
+  // renderer and the no-loss invariant keep their exact current semantics. What
+  // changes is that the BYTES are moved to `graveyard/` instead of destroyed,
+  // making the delete recoverable. Deliberately NOT the Archive container:
+  // archived cards are only re-parented, so they still sit in `order` and still
+  // render — a deleted card put there would visibly reappear in place.
+  const graveyard = {};
+  for (const src of [T, O]) if (src?.graveyard) for (const [gid, g] of Object.entries(src.graveyard)) {
+    // Union, never prune: one machine emptying its bin must not empty another's.
+    if (!graveyard[gid] || Number(g.meta?.deletedAt || 0) > Number(graveyard[gid].meta?.deletedAt || 0)) graveyard[gid] = g;
+  }
+  const buryCard = (id) => {
+    if (graveyard[id]) return;                       // already buried — keep the original stamp
+    const json = O.items[id] ?? T.items[id] ?? null;
+    if (json == null) return;                        // nothing to preserve
+    const pos = O.positions[id] || T.positions[id] || null;
+    let preview = '';
+    try { preview = String(JSON.parse(json)?.content || '').replace(/\s+/g, ' ').trim().slice(0, 140); } catch { /* media card */ }
+    graveyard[id] = {
+      meta: {
+        deletedAt: Date.now(),       // `now` below is declared later in this scope
+        deletedBy: 'human',
+        area: (O.titleById.get(pos?.parentId) || T.titleById.get(pos?.parentId) || null),
+        parentId: pos?.parentId ?? null,
+        pos: pos ? { x: pos.x, y: pos.y, w: pos.w ?? null, h: pos.h ?? null } : null,
+        preview,
+      },
+      json,
+    };
+  };
+
   for (const id of allIds) {
     const inO = O.items[id] != null, inT = T.items[id] != null;
     const inB = baseItem(id) != null;
@@ -169,10 +211,35 @@ export async function mergeBrains({ base = null, ours, theirs, deletedIds = [] }
         conflicts.push({ id, kind: 'delete-vs-edit', kept: 'theirs' });
         // fall through to keep from theirs below
       } else {
+        buryCard(id);                // keep the bytes; the card still leaves the brain
         delta.removed.push(id);
         continue;                    // honored delete
       }
     }
+    // ── The bin is a DURABLE tombstone (2026-08-07) ────────────────────────
+    // Before it existed, `deletedIds` was a per-call argument that was consumed
+    // and thrown away, so a delete could not cross machines: sync with a peer
+    // who still had the card and it came straight back, because "absent from
+    // ours" alone is deliberately never a delete. A graveyard entry is not mere
+    // absence — it is a recorded human deletion — so it is honored here.
+    //
+    // The delete-vs-edit rule is unchanged and still wins: if the other side
+    // EDITED the card after our deletion, their information is newer than our
+    // intent, so the card comes back live and leaves the bin. Without a base we
+    // cannot prove an edit, so the deletion stands (conservative: a resurrected
+    // card is visible and re-deletable; a lost one is not).
+    if (graveyard[id] && !inO) {
+      const theirsChangedSinceBase = inT && inB && !sameMeaning(T.items[id], baseItem(id));
+      if (inT && theirsChangedSinceBase) {
+        conflicts.push({ id, kind: 'delete-vs-edit', kept: 'theirs' });
+        delete graveyard[id];        // resurrected — never in the brain AND the bin
+      } else {
+        delta.removed.push(id);      // the deletion propagates
+        continue;
+      }
+    }
+    // Live on our side ⇒ not deleted. Covers a restore and a re-add.
+    if (graveyard[id] && inO) delete graveyard[id];
 
     if (!inO && !inT) continue;
 
@@ -294,6 +361,20 @@ export async function mergeBrains({ base = null, ours, theirs, deletedIds = [] }
   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);
 
+  // Graveyard: card bytes under graveyard/, metadata in one index. Written only
+  // when non-empty so a brain that has never had a delete keeps a byte-identical
+  // shape. Nothing here is reachable from `order`, so nothing here can render,
+  // be searched, be embedded, or be counted.
+  const graveyardEntries = {};
+  for (const [gid, g] of Object.entries(graveyard)) {
+    if (g?.json == null) continue;
+    zip.file(`graveyard/${shard(gid)}/${gid}.json`, g.json);
+    graveyardEntries[gid] = g.meta || {};
+  }
+  if (Object.keys(graveyardEntries).length) {
+    zip.file('graveyard.json', JSON.stringify({ version: 1, entries: graveyardEntries }));
+  }
+
   const positions = {};
   for (const id of order) positions[id] = merged.get(id).pos;