klypix-mcp 1.62.0 → 1.64.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-brain-history.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// `klypix-mcp brain-history [list|restore <id>|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.
+import fs from 'fs';
+import path from 'path';
+import { listBrainHistory, pruneBrainHistory, restoreBrainSnapshot, historyDirFor } from '../src/brain-history.mjs';
+
+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 positional = argv.filter((a) => !a.startsWith('-'));
+
+const ago = (ts) => {
+  const m = Math.max(0, Math.round((Date.now() - ts) / 60000));
+  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`;
+};
+const kb = (b) => `${(b / 1024).toFixed(0)} KB`;
+
+// Card counts make a restore point meaningful ("this one still has the 14 cards
+// you deleted"). Parsing ≤20 small zips is fine for a human-invoked command;
+// a parse failure degrades to size only rather than failing the listing.
+async function cardCount(file) {
+  try {
+    const { parseKlypix } = await import('../src/klypix-format.mjs');
+    const { struct } = await parseKlypix(fs.readFileSync(file));
+    return struct?.cards?.length ?? null;
+  } catch { return null; }
+}
+
+if (action === 'list') {
+  const entries = listBrainHistory(brainPath);
+  if (!entries.length) {
+    console.log(`No restore points for ${brainPath}.`);
+    console.log(`They are written automatically before each brain write, to ${historyDirFor(brainPath)}.`);
+    process.exit(0);
+  }
+  const liveExists = fs.existsSync(brainPath);
+  const liveCards = liveExists ? await cardCount(brainPath) : null;
+  console.log(`Restore points for ${brainPath}${liveExists ? '' : '  (the brain itself is MISSING — restore will recreate it)'}`);
+  if (liveCards != null) console.log(`current: ${liveCards} cards, ${kb(fs.statSync(brainPath).size)}\n`);
+  for (const e of entries) {
+    const cards = await cardCount(e.file);
+    const delta = cards != null && liveCards != null ? cards - liveCards : null;
+    const deltaText = delta == null ? '' : delta > 0 ? `  (+${delta} cards vs now)` : delta < 0 ? `  (${delta} cards vs now)` : '  (same card count)';
+    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.');
+  process.exit(0);
+}
+
+if (action === 'prune') {
+  const removed = pruneBrainHistory(brainPath);
+  console.log(`Pruned ${removed} restore point(s) beyond the retention window (newest 20 + one per day for 14 days).`);
+  process.exit(0);
+}
+
+// restore
+const id = positional[0];
+if (!id) {
+  console.error('Usage: npx klypix-mcp brain-history restore <id> [--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 });
+if (!res.ok) { console.error(`Restore failed: ${res.error}`); process.exit(1); }
+console.log(`Restored ${brainPath} from ${res.restoredFrom} (${kb(res.bytes)}).`);
+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-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', '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', '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.`,
@@ -36,6 +36,8 @@ const USAGE = [
   '  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-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

@@ -121,6 +121,14 @@ await runVerb('git-driver', './klypix-git-driver.mjs');
 // commits with rationale bodies card into the brain from ANY agent, branch, or
 // worktree at commit time (the Stop hook alone is blind to other worktrees).
 await runVerb('git-hook', './klypix-git-hook.mjs');
+// `npx klypix-mcp brain-history` — list/restore the automatic restore points
+// 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.62.0",
+  "version": "1.64.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/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/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-doctor.mjs

@@ -41,6 +41,8 @@ let fmtLib = null;
 try { fmtLib = await import('./klypix-format.mjs'); } catch { fmtLib = null; }
 let gitCaptureLib = null;
 try { gitCaptureLib = await import('./git-capture-install.mjs'); } catch { gitCaptureLib = null; }
+let historyLib = null;
+try { historyLib = await import('./brain-history.mjs'); } catch { historyLib = null; }
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -383,6 +385,15 @@ export function inspect(opts = {}) {
   if (hasBrain && gitCaptureLib && typeof gitCaptureLib.gitCaptureHookStatus === 'function') {
     try { gitCapture = gitCaptureLib.gitCaptureHookStatus(projectDir, { home }); } catch { gitCapture = { state: 'error', hooks: {} }; }
   }
+  // Restore points (2026-08-07). Informational: their absence on a brand-new
+  // brain is normal, and a missing history must never read as machine drift.
+  let history = { available: false, count: 0, newestAt: null };
+  if (hasBrain && historyLib && typeof historyLib.listBrainHistory === 'function') {
+    try {
+      const points = historyLib.listBrainHistory(brainPath, { home });
+      history = { available: true, count: points.length, newestAt: points[0]?.ts || null };
+    } catch { history = { available: true, count: 0, newestAt: null }; }
+  }
   const tools = inspectTools(brainDir, PKG_ROOT);
   const env = opts.env || process.env;
   // MCP passes the adopted live id explicitly. The CLI can inherit a host id,
@@ -477,7 +488,7 @@ export function inspect(opts = {}) {
     }
   }
 
-  return { verdict, layers, drifted, readinessWarnings, version, running, supervisors, autoUpdate, hooks, codexSmart, codexHooks, gitCapture, tools, peers, sessions: peers, receipts: peers.receipts, receiptSessionId, harness, npm, decayGuard, project: { dir: projectDir, brainPath, hasBrain }, brainDir, actions };
+  return { verdict, layers, drifted, readinessWarnings, version, running, supervisors, autoUpdate, hooks, codexSmart, codexHooks, gitCapture, history, tools, peers, sessions: peers, receipts: peers.receipts, receiptSessionId, harness, npm, decayGuard, project: { dir: projectDir, brainPath, hasBrain }, brainDir, actions };
 }
 
 // One-line drift summary (empty when clean) — for a footer / status line.
@@ -611,6 +622,12 @@ export function render(r, opts = {}) {
             : `${c.dim}${gc.state} — installs automatically at the next session start${c.rst}`;
     L.push(`${gmark} ${c.bold}GIT-CAP${c.rst}  ${detail}`);
   }
+  // Restore points — say the count and the age, because "you can undo an
+  // accidental delete" is only believable if the machine can show the receipts.
+  if (r.history?.available) {
+    const age = r.history.newestAt ? `${Math.max(0, Math.round((Date.now() - r.history.newestAt) / 60000))}m ago` : 'none yet';
+    L.push(`${ok} ${c.bold}HISTORY${c.rst}  ${r.history.count} restore point(s) · newest ${age} ${c.dim}(npx klypix-mcp brain-history list)${c.rst}`);
+  }
 
   // TOOLS
   L.push(`${ok} ${c.bold}TOOLS${c.rst}    ${r.tools.count} MCP verb(s)${r.tools.hash ? ` ${c.dim}[#${r.tools.hash}, ${r.tools.source}]${c.rst}` : ''}${r.tools.count ? `: ${c.dim}${r.tools.names.join(', ')}${c.rst}` : ''}`);

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/brain-history.mjs

@@ -0,0 +1,229 @@
+// brain-history — restore points for a project brain.
+//
+// WHY THE BRAIN AND NOT EVERY CANVAS. A normal canvas is authored and observed
+// by one human: they made every mark, so losing one is a mistake they can see
+// and redo. A brain is CO-OWNED and mostly written while nobody is watching —
+// hooks, the MCP server, commit capture and peers on other machines all append
+// to it unattended. So a human can destroy work they never saw arrive, and an
+// agent can destroy work the human never saved. Undo does not span that: it
+// lives in one renderer session, and the writers here are separate processes.
+//
+// WHAT WAS AND WAS NOT ALREADY SAFE (audited 2026-08-07):
+//   safe      merge / git-driver union .............. lossless by contract + tests
+//   safe      tidy / arrange ......................... lossless by contract
+//   safe      brain_garden ........................... archives, approval-gated
+//   safe      concurrent writers ..................... advisory lock + queue
+//   safe      torn or corrupt write .................. atomicWrite parse-validates
+//   UNSAFE    human deletes a card, then saves ....... persisted, irreversible
+//   UNSAFE    multi-select delete .................... same, larger
+//   UNSAFE    destructive edit of a card's text ...... same
+//   UNSAFE    the .klypix file deleted outright ...... nothing to fall back to
+//   UNSAFE    an external tool overwrites the file ... no prior copy
+//   UNSAFE    a stale machine's sync lands backwards . no prior copy
+// Every UNSAFE row is one sentence: the file's previous bytes are gone. So the
+// primitive is not a confirmation dialog (people click through those, and the
+// brain NEEDS deletion to stay correctable) — it is keeping the previous bytes.
+//
+// DESIGN RULES, each one earned from a way this could make things worse:
+//   • MACHINE-LOCAL, never beside the brain. A `.klypix-history/` in the repo
+//     would land in git, in the merge driver's path, in cloud sync, and in
+//     everyone's diffs. Restore points are undo, not project content.
+//   • NEVER BLOCK A WRITE. Every entry point is best-effort and swallows its
+//     own errors: a full disk must not stop the brain from saving.
+//   • DEDUPED BY CONTENT. Identical bytes are never stored twice.
+//   • SHRINK IS ALWAYS INTERESTING. Routine writes throttle; a write that makes
+//     the brain measurably SMALLER is the exact accident this exists for and is
+//     never throttled.
+//   • BOUNDED. Newest N plus one per day, so it cannot grow without limit.
+//   • RESTORE IS ITSELF REVERSIBLE. Restoring first snapshots what is there now.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+
+const KEEP_NEWEST = 20;
+const KEEP_DAILY_DAYS = 14;
+const THROTTLE_MS = 60 * 1000;
+// A write that shrinks the file by more than this is treated as a deletion
+// signal and bypasses the throttle. ZIP size tracks card count closely enough
+// for a heuristic, and being wrong here only costs one extra snapshot.
+const SHRINK_RATIO = 0.02;
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+function canonPath(p) {
+  try { return (fs.realpathSync.native || fs.realpathSync)(p); }
+  catch { return path.resolve(p); }
+}
+
+// Key on the canonical path with the drive letter lowercased, matching the
+// presence lane's convention so both agree about what "the same brain" means.
+export function historyKeyFor(brainPath) {
+  const norm = canonPath(brainPath).replace(/\\/g, '/').replace(/^([a-z]):/i, (m, d) => `${d.toLowerCase()}:`);
+  return crypto.createHash('sha1').update(norm).digest('hex').slice(0, 16);
+}
+
+export function historyDirFor(brainPath, home = os.homedir()) {
+  return path.join(home, '.claude', 'project-brain', 'history', historyKeyFor(brainPath));
+}
+
+const SNAP_RE = /^(\d+)-([0-9a-f]{8})\.klypix$/;
+
+function readEntries(dir) {
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const name of names) {
+    const m = SNAP_RE.exec(name);
+    if (!m) continue;
+    const full = path.join(dir, name);
+    let bytes = 0;
+    try { bytes = fs.statSync(full).size; } catch { continue; }
+    out.push({ id: name.replace(/\.klypix$/, ''), ts: Number(m[1]), sha8: m[2], bytes, file: full });
+  }
+  return out.sort((a, b) => b.ts - a.ts);
+}
+
+/** Restore points for a brain, newest first. Works even if the brain is gone. */
+export function listBrainHistory(brainPath, { home = os.homedir() } = {}) {
+  const dir = historyDirFor(brainPath, home);
+  const entries = readEntries(dir);
+  let meta = null;
+  try { meta = JSON.parse(fs.readFileSync(path.join(dir, 'source.json'), 'utf8')); } catch { /* optional */ }
+  return entries.map((e) => ({ ...e, reason: meta?.reasons?.[e.id] || null }));
+}
+
+// Newest N, plus the OLDEST surviving snapshot of each of the last KEEP_DAILY_DAYS
+// days. Keeping the oldest-of-day (not the newest) is deliberate: after a slow
+// accident you want the state BEFORE that day's edits, not after them.
+function selectDoomed(entries, now) {
+  const keep = new Set(entries.slice(0, KEEP_NEWEST).map((e) => e.id));
+  const dayFloor = now - KEEP_DAILY_DAYS * 24 * 60 * 60 * 1000;
+  const oldestPerDay = new Map();
+  for (const e of entries) {
+    if (e.ts < dayFloor) continue;
+    const day = new Date(e.ts).toISOString().slice(0, 10);
+    const prev = oldestPerDay.get(day);
+    if (!prev || e.ts < prev.ts) oldestPerDay.set(day, e);
+  }
+  for (const e of oldestPerDay.values()) keep.add(e.id);
+  return entries.filter((e) => !keep.has(e.id));
+}
+
+export function pruneBrainHistory(brainPath, { home = os.homedir(), now = Date.now() } = {}) {
+  const dir = historyDirFor(brainPath, home);
+  const doomed = selectDoomed(readEntries(dir), now);
+  let removed = 0;
+  for (const e of doomed) {
+    try { fs.unlinkSync(e.file); removed++; } catch { /* raced */ }
+  }
+  if (removed) {
+    try {
+      const metaPath = path.join(dir, 'source.json');
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      for (const e of doomed) delete meta.reasons?.[e.id];
+      fs.writeFileSync(metaPath, JSON.stringify(meta));
+    } catch { /* metadata is a convenience */ }
+  }
+  return removed;
+}
+
+/**
+ * True when a snapshot right now would be suppressed by the throttle. Callers
+ * use this to decide whether it is worth computing an accurate "does this write
+ * remove cards?" answer: outside the window a snapshot happens regardless, so
+ * nobody should pay to find out.
+ */
+export function wouldThrottle(brainPath, { home = os.homedir(), now = Date.now() } = {}) {
+  const entries = readEntries(historyDirFor(brainPath, home));
+  return Boolean(entries.length) && now - entries[0].ts < THROTTLE_MS;
+}
+
+/**
+ * Snapshot the brain's CURRENT on-disk bytes before something replaces them.
+ * Call immediately BEFORE a write. Never throws.
+ *
+ * `nextBytes` (the size about to be written) enables the shrink rule — pass it
+ * whenever the caller knows it; without it every eligible write is snapshotted,
+ * which is safe, just chattier.
+ */
+export function snapshotBrain(brainPath, { home = os.homedir(), reason = 'write', nextBytes = null, now = Date.now(), force = false } = {}) {
+  try {
+    let buf;
+    try { buf = fs.readFileSync(brainPath); } catch { return { saved: false, skipped: 'no-current-file' }; }
+    if (!buf.length) return { saved: false, skipped: 'empty' };
+
+    const dir = historyDirFor(brainPath, home);
+    const entries = readEntries(dir);
+    const sha = sha256(buf);
+    const sha8 = sha.slice(0, 8);
+
+    // Content dedup: the newest snapshot already holds these exact bytes.
+    if (entries.length && entries[0].sha8 === sha8 && entries[0].bytes === buf.length) {
+      return { saved: false, skipped: 'unchanged' };
+    }
+
+    // Shrink beats throttle — a write that removes content is the whole point.
+    const shrinking = nextBytes != null && buf.length > 0
+      && (buf.length - nextBytes) / buf.length > SHRINK_RATIO;
+    if (!force && !shrinking && entries.length && now - entries[0].ts < THROTTLE_MS) {
+      return { saved: false, skipped: 'throttled' };
+    }
+
+    fs.mkdirSync(dir, { recursive: true });
+    const id = `${now}-${sha8}`;
+    const dest = path.join(dir, `${id}.klypix`);
+    const tmp = `${dest}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, buf);
+    try { fs.renameSync(tmp, dest); }
+    catch (err) {
+      try { fs.renameSync(tmp, dest); }
+      catch { try { fs.unlinkSync(tmp); } catch { /* */ } throw err; }
+    }
+
+    // Remember where this came from (so `list` can name it even after the
+    // project moves) and why each point exists.
+    try {
+      const metaPath = path.join(dir, 'source.json');
+      let meta = { path: canonPath(brainPath), reasons: {} };
+      try { meta = { ...meta, ...JSON.parse(fs.readFileSync(metaPath, 'utf8')) }; } catch { /* first write */ }
+      meta.path = canonPath(brainPath);
+      meta.reasons = { ...(meta.reasons || {}), [id]: shrinking ? `${reason}+shrink` : reason };
+      fs.writeFileSync(metaPath, JSON.stringify(meta));
+    } catch { /* metadata is a convenience, never a blocker */ }
+
+    pruneBrainHistory(brainPath, { home, now });
+    return { saved: true, id, path: dest, bytes: buf.length, shrinking };
+  } catch (err) {
+    return { saved: false, skipped: 'error', error: String(err?.message || err) };
+  }
+}
+
+/**
+ * Put a restore point back. Snapshots the CURRENT file first (reason
+ * 'pre-restore') so a restore is never the destructive act. Verifies the
+ * snapshot still parses as a canvas before overwriting anything, if a parser
+ * is supplied — a corrupt restore point must not replace a working brain.
+ */
+export async function restoreBrainSnapshot(brainPath, id, { home = os.homedir(), now = Date.now(), parse = null } = {}) {
+  const dir = historyDirFor(brainPath, home);
+  const entry = readEntries(dir).find((e) => e.id === id || e.id.startsWith(id));
+  if (!entry) return { ok: false, error: `no restore point matching "${id}"` };
+  let buf;
+  try { buf = fs.readFileSync(entry.file); } catch (err) { return { ok: false, error: `unreadable restore point: ${err?.message || err}` }; }
+  if (typeof parse === 'function') {
+    try { await parse(buf); }
+    catch (err) { return { ok: false, error: `restore point does not parse as a canvas: ${err?.message || err}` }; }
+  }
+  const safety = snapshotBrain(brainPath, { home, reason: 'pre-restore', now, force: true });
+  try {
+    fs.mkdirSync(path.dirname(brainPath), { recursive: true });
+    const tmp = `${brainPath}.restore-tmp-${process.pid}`;
+    fs.writeFileSync(tmp, buf);
+    try { fs.renameSync(tmp, brainPath); }
+    catch (err) { try { fs.unlinkSync(tmp); } catch { /* */ } throw err; }
+  } catch (err) {
+    return { ok: false, error: `write failed: ${err?.message || err}`, safetyId: safety.id || null };
+  }
+  return { ok: true, restoredFrom: entry.id, bytes: buf.length, safetyId: safety.id || null };
+}

package/src/klypix-format.mjs

@@ -148,9 +148,74 @@ export const shard = (id) => id.replace(/^[a-z]+[_:]/i, '').toLowerCase().slice(
  * write leaves the previous good file intact. Use this for ALL brain writes
  * instead of fs.writeFileSync.
  */
-export async function atomicWrite(filePath, buf) {
+// Restore points (2026-08-07). Every agent-side brain write funnels through
+// atomicWrite, so this is the one place that can keep the PREVIOUS bytes before
+// they are replaced — the only thing that makes an accidental card deletion,
+// a destructive edit, or a stale overwrite recoverable at all. Dynamic +
+// guarded: a bundle that predates brain-history.mjs must keep writing normally,
+// and a snapshot failure (full disk, locked dir) must NEVER block a save.
+let _historyLib;
+async function loadHistoryLib() {
+    if (_historyLib !== undefined) return _historyLib;
+    try { _historyLib = await import(new URL('./brain-history.mjs', import.meta.url).href); }
+    catch { _historyLib = null; }
+    return _historyLib;
+}
+// Only brains get restore points: they are co-owned and written unattended (see
+// brain-history.mjs). A normal canvas is one human's observed work.
+const looksLikeBrain = (p) => /^brain\.(klypix|any)$/i.test(path.basename(p || ''));
+
+// How many cards an archive actually HOLDS, read from canvas.json's `order`
+// alone — one small inflate, no per-item reads: ~40ms on a 1.7 MB / 2000-card
+// brain against ~380ms for a full parse.
+//
+// Two wrong answers were tried first, and both let a real 400-card deletion
+// through during verification:
+//   • byte size — re-zipping at a different compression level can make a
+//     SMALLER brain into a BIGGER file;
+//   • item-file count — `order` is what decides which cards exist, so a write
+//     that drops ids from `order` loses them even while their item files linger
+//     in the archive as orphans.
+// `order` is the definition of the card set, so it is the only honest signal.
+async function countCardsCheap(buf) {
+    const zip = await JSZip.loadAsync(buf);
+    const raw = await (zip.file('canvas.json')?.async('string') ?? Promise.resolve(null));
+    if (!raw) throw new Error('no canvas.json');
+    const canvas = JSON.parse(raw);
+    if (Array.isArray(canvas.order)) return canvas.order.length;          // v4
+    if (Array.isArray(canvas.items)) return canvas.items.length;          // legacy v1–v3
+    throw new Error('unrecognised canvas shape');
+}
+
+export async function atomicWrite(filePath, buf, opts = {}) {
     try { await parseKlypix(buf); }
     catch (e) { throw new Error('refusing to write an unparseable .klypix (' + path.basename(filePath) + '): ' + (e?.message || e)); }
+    if (opts.snapshot !== false && (opts.isBrain ?? looksLikeBrain(filePath))) {
+        try {
+            const hist = await loadHistoryLib();
+            if (hist?.snapshotBrain) {
+                // Does this write REMOVE cards? Computed only when a recent
+                // restore point would otherwise throttle this one — so the
+                // common path pays nothing, and the one write that must never
+                // be skipped is never skipped.
+                let removesCards = false;
+                if (hist.wouldThrottle?.(filePath)) {
+                    try {
+                        const [prev, next] = await Promise.all([
+                            countCardsCheap(fs.readFileSync(filePath)),
+                            countCardsCheap(buf),
+                        ]);
+                        removesCards = next < prev;
+                    } catch { removesCards = true; }   // can't tell → snapshot; being wrong costs one file
+                }
+                hist.snapshotBrain(filePath, {
+                    reason: opts.reason || 'write',
+                    nextBytes: buf.length,
+                    force: removesCards,
+                });
+            }
+        } catch { /* best-effort by contract — a restore point is never worth a lost save */ }
+    }
     const tmp = filePath + '.tmp-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
     fs.writeFileSync(tmp, buf);
     try { fs.renameSync(tmp, filePath); }    // Node uses MoveFileEx(REPLACE_EXISTING) on Windows → overwrites atomically
@@ -231,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);
@@ -276,6 +363,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 };
 }

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;