klypix-mcp 1.62.0 → 1.63.0

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', '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', 'diff', 'pr-brief', 'uninstall', 'bench']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -36,6 +36,7 @@ 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',
   '  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,10 @@ 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');
 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.63.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/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-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