crbro-memory 2.10.0 → 2.11.0

package/dist/daemon/surface.js

@@ -0,0 +1,116 @@
+"use strict";
+// ─── What the server says before it does anything ────────────────
+//
+// `initialize`, `ping` and `tools/list` have the same answer for every
+// conversation of one build: who the server is, what it can do, how it is
+// meant to be used and which tools it has. A proxy that waited for a backend
+// to say so kept the client in silence while it found, started or gave up on
+// the daemon — past 12 s in the worst case, beyond Codex's 10 s start-up
+// limit. So the proxy answers them itself, at once.
+//
+// The answers are never written by hand. They are taken from the real server
+// (createServer, with engines that are built but never started): at build
+// time into dist/mcp-surface.json, or in this process when that file is
+// missing or belongs to another build. tests/daemon.startup.test.ts holds the
+// proxy's answers against the real server's.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SURFACE_FILE = void 0;
+exports.loadSurface = loadSurface;
+exports.computeSurface = computeSurface;
+exports.getSurface = getSurface;
+exports.answerFromSurface = answerFromSurface;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+exports.SURFACE_FILE = 'mcp-surface.json';
+function isSurface(v) {
+    return !!v && typeof v.build === 'string' && typeof v.latest === 'string' && Array.isArray(v.supported)
+        && v.supported.every((x) => typeof x === 'string')
+        && !!v.initialize && typeof v.initialize.capabilities === 'object' && typeof v.initialize.serverInfo === 'object'
+        && !!v.tools && Array.isArray(v.tools.tools);
+}
+/** The snapshot next to the compiled code, if it is this build's. */
+function loadSurface(build, dir = node_path_1.default.join(__dirname, '..')) {
+    try {
+        const s = JSON.parse((0, node_fs_1.readFileSync)(node_path_1.default.join(dir, exports.SURFACE_FILE), 'utf8'));
+        return isSurface(s) && s.build === build ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ask a real server, in this process. Its engines are constructed (that reads
+ * nothing) and never started: no brain is opened, no index loaded.
+ */
+async function computeSurface(build) {
+    const { createServer, createEngines } = await import('../server.js');
+    const { LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS } = await import('@modelcontextprotocol/sdk/types.js');
+    const { LoopbackTransport } = await import('./lines.js');
+    const answers = new Map();
+    const transport = new LoopbackTransport(line => { const m = JSON.parse(line); if (m.id !== undefined)
+        answers.set(String(m.id), m); });
+    const server = createServer(createEngines());
+    await server.connect(transport);
+    transport.receive(JSON.stringify({
+        jsonrpc: '2.0', id: 'surface-init', method: 'initialize',
+        params: { protocolVersion: LATEST_PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: 'crbro-surface', version: '0' } },
+    }));
+    transport.receive(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }));
+    transport.receive(JSON.stringify({ jsonrpc: '2.0', id: 'surface-tools', method: 'tools/list', params: {} }));
+    const until = Date.now() + 10_000;
+    while ((!answers.has('surface-init') || !answers.has('surface-tools')) && Date.now() < until) {
+        await new Promise(r => setImmediate(r));
+    }
+    await server.close().catch(() => undefined);
+    const init = answers.get('surface-init')?.result;
+    const tools = answers.get('surface-tools')?.result;
+    if (!init || !tools)
+        throw new Error('the server did not describe itself');
+    const { protocolVersion: _negotiated, ...initialize } = init;
+    return { build, latest: LATEST_PROTOCOL_VERSION, supported: [...SUPPORTED_PROTOCOL_VERSIONS], initialize, tools };
+}
+const computed = new Map();
+/** The snapshot if there is one for this build, else the real server asked here (once per process). Null if neither can be had. */
+async function getSurface(build) {
+    const s = loadSurface(build);
+    if (s)
+        return s;
+    let p = computed.get(build);
+    if (!p) {
+        p = computeSurface(build).catch(() => null);
+        computed.set(build, p);
+    }
+    return p;
+}
+/** Only an initialize the server itself would accept is answered here; anything else goes to it and gets its own answer. */
+function wellFormedInitialize(m) {
+    const p = m?.params;
+    return !!p && typeof p === 'object' && typeof p.protocolVersion === 'string'
+        && !!p.capabilities && typeof p.capabilities === 'object'
+        && !!p.clientInfo && typeof p.clientInfo === 'object' && typeof p.clientInfo.name === 'string' && typeof p.clientInfo.version === 'string';
+}
+/**
+ * The answer the server would give to this request, or null when it is not
+ * one of the requests whose answer is fixed per build. The protocol version
+ * is negotiated exactly as the SDK does: the client's if supported, else the
+ * latest.
+ */
+function answerFromSurface(s, m) {
+    if (!m || m.jsonrpc !== '2.0' || m.id === undefined || m.id === null || typeof m.method !== 'string')
+        return null;
+    if (m.method === 'initialize') {
+        if (!wellFormedInitialize(m))
+            return null;
+        const protocolVersion = s.supported.includes(m.params.protocolVersion) ? m.params.protocolVersion : s.latest;
+        return { jsonrpc: '2.0', id: m.id, result: { protocolVersion, ...s.initialize } };
+    }
+    if (m.method === 'ping')
+        return { jsonrpc: '2.0', id: m.id, result: {} };
+    if (m.method === 'tools/list')
+        return { jsonrpc: '2.0', id: m.id, result: s.tools };
+    return null;
+}
+//# sourceMappingURL=surface.js.map

package/dist/daemon/trace.js

@@ -0,0 +1,73 @@
+"use strict";
+// ─── CRBRO_STARTUP_TRACE=1: where the start-up time goes ──────────
+//
+// Until 2.11 "the client says CRBRO is slow to start" could not be broken
+// down: not in the client, not in the server. With the variable set, each
+// process writes one line per phase — milliseconds since the process started,
+// the phase, a detail — to stderr and to <brain>/.daemon/startup-trace.log
+// (a detached daemon has no stderr anybody reads). Phases: process start,
+// initialize answered, backend connected or in-process fallback, engine
+// ready, first tool result.
+//
+// Off, it costs one boolean test per call site: nothing is formatted, nothing
+// is written.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRACE_ON = void 0;
+exports.traceStart = traceStart;
+exports.trace = trace;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_perf_hooks_1 = require("node:perf_hooks");
+exports.TRACE_ON = (process.env.CRBRO_STARTUP_TRACE || '').trim() === '1';
+const LOG_MAX_BYTES = 512 * 1024;
+let file = null;
+let role = 'process';
+const seen = new Set();
+/** Where the log goes and who is writing (proxy, daemon, classic). Writes the "process start" line. */
+function traceStart(brainRoot, who) {
+    if (!exports.TRACE_ON)
+        return;
+    role = who;
+    if (brainRoot) {
+        try {
+            const dir = node_path_1.default.join(brainRoot, '.daemon');
+            (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+            file = node_path_1.default.join(dir, 'startup-trace.log');
+            // Left on for weeks, it keeps one previous file and starts again.
+            try {
+                if ((0, node_fs_1.statSync)(file).size > LOG_MAX_BYTES)
+                    (0, node_fs_1.renameSync)(file, `${file}.1`);
+            }
+            catch { /* no log yet */ }
+        }
+        catch {
+            file = null;
+        }
+    }
+    trace('process start', `pid ${process.pid} · started ${new Date(node_perf_hooks_1.performance.timeOrigin).toISOString()}`);
+}
+/** One phase. `once`: only the first time this phase is reached in this process. */
+function trace(phase, detail = '', once = false) {
+    if (!exports.TRACE_ON)
+        return;
+    if (once) {
+        if (seen.has(phase))
+            return;
+        seen.add(phase);
+    }
+    const line = `[crbro trace] ${role} +${node_perf_hooks_1.performance.now().toFixed(1)}ms ${phase}${detail ? ` · ${detail}` : ''}`;
+    try {
+        process.stderr.write(`${line}\n`);
+    }
+    catch { /* no stderr (detached) */ }
+    if (file) {
+        try {
+            (0, node_fs_1.appendFileSync)(file, `${new Date().toISOString()} [${process.pid}] ${line}\n`);
+        }
+        catch { /* the trace never breaks start-up */ }
+    }
+}
+//# sourceMappingURL=trace.js.map

package/dist/engine/atrest.js

@@ -0,0 +1,132 @@
+"use strict";
+// ─── Encryption at rest, opt-in: backups and quarantine ─────────
+//
+// The brain is plain JSON on purpose — people read it, diff it and fix it by
+// hand. Its two copies are a different matter: a backup is made to be carried
+// to a synced folder, and the quarantine holds exactly what somebody asked to
+// forget, credentials included. Whoever syncs those to a cloud drive may want
+// them sealed. Off by default; nothing changes for anyone who does not ask.
+//
+//   CRBRO_ENCRYPT_AT_REST=1   seal new backups and quarantine copies
+//
+// The key: 32 random bytes, base64, kept in the OS keychain under
+// CRBRO_AT_REST_KEY (crbro_secret / `crbro-memory secret set`), never in the
+// brain and never next to the files it protects. With the switch on and no key
+// CRBRO fails loudly: it never falls back to writing in clear and never deletes
+// anything for lack of a key. Create the key once, explicitly:
+//
+//   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" \
+//     | npx crbro-memory secret set CRBRO_AT_REST_KEY --description "crbro - at-rest key"
+//
+// Lose the key and the sealed copies are gone with it: that is what sealing
+// means. Clear files stay readable whatever the switch says.
+//
+// Format: MAGIC (8 bytes) | IV (12) | GCM tag (16) | ciphertext. AES-256-GCM
+// from node:crypto, the magic bound as additional data. Readers recognise a
+// sealed file by its first bytes, never by its name.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtRestKeyError = exports.AT_REST_KEY_NAME = void 0;
+exports.atRestEnabled = atRestEnabled;
+exports.generateAtRestKey = generateAtRestKey;
+exports._resetAtRestKeyCache = _resetAtRestKeyCache;
+exports.loadAtRestKey = loadAtRestKey;
+exports.isSealed = isSealed;
+exports.seal = seal;
+exports.unseal = unseal;
+exports.maybeSeal = maybeSeal;
+const node_crypto_1 = require("node:crypto");
+const keychain_js_1 = require("./keychain.js");
+exports.AT_REST_KEY_NAME = 'CRBRO_AT_REST_KEY';
+const MAGIC = Buffer.from('CRBRENC1', 'ascii');
+const IV_LEN = 12;
+const TAG_LEN = 16;
+class AtRestKeyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AtRestKeyError';
+    }
+}
+exports.AtRestKeyError = AtRestKeyError;
+/** The switch. Only an explicit "1"/"true"/"on" turns it on. */
+function atRestEnabled(env = process.env) {
+    return /^(1|true|on|yes)$/i.test((env['CRBRO_ENCRYPT_AT_REST'] || '').trim());
+}
+/** A fresh key, base64. For the person setting it up; CRBRO never stores one by itself. */
+function generateAtRestKey() {
+    return (0, node_crypto_1.randomBytes)(32).toString('base64');
+}
+let cache = null;
+const CACHE_MS = 60_000;
+/** Tests switch keys and keychain folders between cases. */
+function _resetAtRestKeyCache() {
+    cache = null;
+}
+/** The key from the keychain, or a loud error saying how to create it. */
+function loadAtRestKey() {
+    if (cache && Date.now() - cache.at < CACHE_MS)
+        return cache.key;
+    let raw;
+    try {
+        raw = (0, keychain_js_1.getSecret)(exports.AT_REST_KEY_NAME);
+    }
+    catch (err) {
+        throw new AtRestKeyError(`Encryption at rest is on (CRBRO_ENCRYPT_AT_REST) but the keychain could not be read: ${err.message}. ` +
+            'Nothing was written in clear and nothing was deleted.');
+    }
+    if (!raw || !raw.trim()) {
+        throw new AtRestKeyError(`Encryption at rest is on (CRBRO_ENCRYPT_AT_REST) but there is no ${exports.AT_REST_KEY_NAME} in the keychain. ` +
+            'Nothing was written in clear and nothing was deleted. Create the key once with: ' +
+            `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" | npx crbro-memory secret set ${exports.AT_REST_KEY_NAME}`);
+    }
+    const key = Buffer.from(raw.trim(), 'base64');
+    if (key.length !== 32) {
+        throw new AtRestKeyError(`${exports.AT_REST_KEY_NAME} must be 32 bytes in base64 (got ${key.length} bytes). Nothing was written.`);
+    }
+    cache = { key, at: Date.now() };
+    return key;
+}
+function isSealed(data) {
+    return data.length >= MAGIC.length + IV_LEN + TAG_LEN && data.subarray(0, MAGIC.length).equals(MAGIC);
+}
+function seal(plain, key = loadAtRestKey()) {
+    const iv = (0, node_crypto_1.randomBytes)(IV_LEN);
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', key, iv);
+    cipher.setAAD(MAGIC);
+    const body = Buffer.concat([cipher.update(plain), cipher.final()]);
+    return Buffer.concat([MAGIC, iv, cipher.getAuthTag(), body]);
+}
+/**
+ * Clear data comes back as it is; sealed data is opened with the keychain key
+ * whatever the switch says (turning encryption off must not orphan old copies).
+ */
+function unseal(data, key) {
+    if (!isSealed(data))
+        return data;
+    const k = key ?? (() => {
+        try {
+            return loadAtRestKey();
+        }
+        catch (err) {
+            throw new AtRestKeyError(`This file is encrypted at rest and the key is not available: ${err.message}`);
+        }
+    })();
+    const iv = data.subarray(MAGIC.length, MAGIC.length + IV_LEN);
+    const tag = data.subarray(MAGIC.length + IV_LEN, MAGIC.length + IV_LEN + TAG_LEN);
+    const body = data.subarray(MAGIC.length + IV_LEN + TAG_LEN);
+    const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', k, iv);
+    decipher.setAAD(MAGIC);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(body), decipher.final()]);
+    }
+    catch {
+        throw new AtRestKeyError('Encrypted file could not be opened: wrong key or damaged file.');
+    }
+}
+/** Seal when the switch is on, else return the bytes untouched. Throws (never writes clear) if on and keyless. */
+function maybeSeal(plain, env = process.env) {
+    if (!atRestEnabled(env))
+        return { data: plain, sealed: false };
+    return { data: seal(plain), sealed: true };
+}
+//# sourceMappingURL=atrest.js.map

package/dist/engine/backup.js

@@ -2,6 +2,13 @@
 // ─── Brain backup ────────────────────────────────────────────────
 // One gzipped JSON file per backup, with rotation.
 //
+// 2.11: --keep is validated (a whole number ≥ 1), each new copy is read back
+// before anything is rotated, the copy just written is never rotated, a
+// future-dated copy no longer counts as the newest, retention is tiered
+// (newest N + one per day for N days + per ISO week for 4 weeks + per month
+// for 6 months), and with CRBRO_ENCRYPT_AT_REST=1 copies are sealed
+// (`.json.gz.enc`, see atrest.ts).
+//
 // Why a single file and not a copied directory: it is written with
 // tmp + rename, so a backup either exists whole or does not exist; a copied
 // tree interrupted half-way looks like a backup and is not one. It is also
@@ -25,9 +32,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AUTO_BACKUP_INTERVAL_MS = exports.DEFAULT_KEEP = exports.BACKUP_FORMAT = void 0;
+exports.DEFAULT_RETENTION = exports.AUTO_BACKUP_INTERVAL_MS = exports.DEFAULT_KEEP = exports.BACKUP_FORMAT = void 0;
+exports.validateKeep = validateKeep;
 exports.resolveBackupDir = resolveBackupDir;
 exports.listBackups = listBackups;
+exports.retainedBackups = retainedBackups;
 exports.createBackup = createBackup;
 exports.readBackup = readBackup;
 exports.restoreBackup = restoreBackup;
@@ -37,7 +46,10 @@ const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const zlib_1 = __importDefault(require("zlib"));
 const util_1 = require("util");
+const fs_js_1 = require("../utils/fs.js");
 const gzip = (0, util_1.promisify)(zlib_1.default.gzip);
+/** Loaded on first use: doctor and listing never need the keychain. */
+const atRest = () => import('./atrest.js');
 const gunzip = (0, util_1.promisify)(zlib_1.default.gunzip);
 exports.BACKUP_FORMAT = 1;
 exports.DEFAULT_KEEP = 7;
@@ -51,6 +63,17 @@ const SKIP_TOP = new Set(['.quarantine', '.search', '.semantic', '.device-token'
 const SKIP_ANYWHERE = new Set(['.git', 'node_modules']);
 const PREFIX = 'brain-';
 const SUFFIX = '.json.gz';
+/** A copy sealed with the at-rest key (CRBRO_ENCRYPT_AT_REST=1). */
+const SUFFIX_ENC = '.json.gz.enc';
+/** A copy whose name is further ahead of the clock than this is future-dated. */
+const FUTURE_TOLERANCE_MS = 24 * 60 * 60 * 1000;
+exports.DEFAULT_RETENTION = { keep: exports.DEFAULT_KEEP, daily: 7, weekly: 4, monthly: 6 };
+/** An integer ≥ 1, or an error that says so. `backup --keep siete` used to mean "delete every copy". */
+function validateKeep(keep) {
+    if (typeof keep === 'number' && Number.isInteger(keep) && keep >= 1)
+        return keep;
+    throw new Error(`--keep must be a whole number of at least 1 (got ${JSON.stringify(keep)}). Nothing was written or rotated.`);
+}
 /**
  * Where backups go: a sibling of the brain they belong to — `~/.crbro` →
  * `~/.crbro-backups/brain`.
@@ -104,7 +127,10 @@ async function walk(root, rel, out) {
         }
     }
 }
-async function listBackups(dir) {
+function isBackupName(n) {
+    return n.startsWith(PREFIX) && (n.endsWith(SUFFIX) || n.endsWith(SUFFIX_ENC));
+}
+async function listBackups(dir, now = new Date()) {
     let names;
     try {
         names = await fs_1.promises.readdir(dir);
@@ -113,23 +139,69 @@ async function listBackups(dir) {
         return [];
     }
     const found = [];
+    const limite = now.getTime() + FUTURE_TOLERANCE_MS;
     for (const n of names) {
-        if (!n.startsWith(PREFIX) || !n.endsWith(SUFFIX))
+        if (!isBackupName(n))
             continue;
         try {
             const st = await fs_1.promises.stat(path_1.default.join(dir, n));
-            const m = n.slice(PREFIX.length, -SUFFIX.length).match(/^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})/);
-            const created = m ? `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}.000Z` : st.mtime.toISOString();
-            found.push({ file: n, path: path_1.default.join(dir, n), created, size_bytes: st.size });
+            const m = n.slice(PREFIX.length).match(/^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})/);
+            let created = m ? `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}.000Z` : st.mtime.toISOString();
+            // A clock set ahead once must not make that copy "the newest" for
+            // months: it blocked every automatic copy and got the good ones rotated
+            // out first. Its name is not evidence; the file's own date is.
+            let future = false;
+            if (!Number.isFinite(Date.parse(created)) || Date.parse(created) > limite) {
+                future = true;
+                // A file date ahead too: it sorts as the oldest copy, never the newest.
+                created = new Date(st.mtimeMs <= limite ? st.mtimeMs : 0).toISOString();
+            }
+            found.push({
+                file: n, path: path_1.default.join(dir, n), created, size_bytes: st.size,
+                ...(n.endsWith(SUFFIX_ENC) ? { encrypted: true } : {}),
+                ...(future ? { future_dated: true } : {}),
+            });
         }
         catch { /* gone */ }
     }
-    return found.sort((a, b) => (a.file < b.file ? 1 : -1)); // newest first
+    return found.sort((a, b) => (a.created < b.created ? 1 : a.created > b.created ? -1 : a.file < b.file ? 1 : -1)); // newest first
+}
+const isoWeek = (d) => {
+    const t = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+    const dia = t.getUTCDay() || 7;
+    t.setUTCDate(t.getUTCDate() + 4 - dia);
+    const inicio = new Date(Date.UTC(t.getUTCFullYear(), 0, 1));
+    const semana = Math.ceil(((t.getTime() - inicio.getTime()) / 86_400_000 + 1) / 7);
+    return `${t.getUTCFullYear()}-W${String(semana).padStart(2, '0')}`;
+};
+/** Which copies a retention policy keeps, by file name. Pure. `all` is newest first. */
+function retainedBackups(all, policy = exports.DEFAULT_RETENTION) {
+    const keep = new Set();
+    for (const b of all.slice(0, policy.keep))
+        keep.add(b.file);
+    const tier = (key, n) => {
+        const vistos = new Set();
+        for (const b of all) {
+            const k = key(new Date(b.created));
+            if (vistos.has(k))
+                continue;
+            if (vistos.size >= n)
+                break;
+            vistos.add(k);
+            keep.add(b.file); // newest of that bucket: `all` is newest first
+        }
+    };
+    tier(d => d.toISOString().slice(0, 10), policy.daily);
+    tier(isoWeek, policy.weekly);
+    tier(d => d.toISOString().slice(0, 7), policy.monthly);
+    return keep;
 }
 async function createBackup(paths, opts = {}) {
     const dir = opts.dir || resolveBackupDir(paths.root);
-    const keep = Math.max(1, opts.keep ?? exports.DEFAULT_KEEP);
+    const keep = opts.keep === undefined ? exports.DEFAULT_KEEP : validateKeep(opts.keep);
+    const retention = { ...exports.DEFAULT_RETENTION, daily: keep, ...opts.retention, keep };
     const when = opts.now || new Date();
+    const env = opts.env || process.env;
     const files = {};
     await walk(paths.root, '', files);
     const keys = Object.keys(files);
@@ -151,28 +223,74 @@ async function createBackup(paths, opts = {}) {
         // An empty bundle would rotate a real backup out. Refuse instead.
         throw new Error(`Nothing to back up at ${paths.root}: no neurons and no sessions found.`);
     }
+    // A neuron that does not parse is copied as it is — its bytes may be all
+    // that is left of it — and named, so nobody restores it believing it fine.
+    const unreadable = [];
+    for (const k of keys) {
+        if (!k.startsWith('cortex/') || !k.endsWith('.json'))
+            continue;
+        try {
+            JSON.parse((0, fs_js_1.stripBOM)(files[k]));
+        }
+        catch {
+            unreadable.push(k);
+        }
+    }
+    const gz = await gzip(Buffer.from(JSON.stringify(bundle), 'utf8'), { level: 6 });
+    // Sealed when encryption at rest is on; throws before writing anything when
+    // it is on and the key is missing — never a clear copy instead.
+    const { maybeSeal } = await atRest();
+    const { data: packed, sealed } = maybeSeal(gz, env);
     await fs_1.promises.mkdir(dir, { recursive: true });
-    const name = `${PREFIX}${stamp(when)}${SUFFIX}`;
+    const name = `${PREFIX}${stamp(when)}${sealed ? SUFFIX_ENC : SUFFIX}`;
     const target = path_1.default.join(dir, name);
     const tmp = `${target}.tmp-${process.pid}`;
-    const packed = await gzip(Buffer.from(JSON.stringify(bundle), 'utf8'), { level: 6 });
-    await fs_1.promises.writeFile(tmp, packed);
+    const fh = await fs_1.promises.open(tmp, 'w');
+    try {
+        await fh.writeFile(packed);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
     await fs_1.promises.rename(tmp, target);
-    // Rotation only ever removes files this module named, and only after the new
-    // one is safely on disk.
-    const all = await listBackups(dir);
+    // Read it back before trusting it. A copy cut short by a crash or a full
+    // disk used to be followed straight away by the rotation of the oldest GOOD
+    // one. A copy that does not read back is removed (it would otherwise count
+    // as the newest) and nothing is rotated.
+    try {
+        const back = await readBackup(target);
+        if (Object.keys(back.files).length !== bundle.counts.files) {
+            throw new Error(`holds ${Object.keys(back.files).length} files, expected ${bundle.counts.files}`);
+        }
+    }
+    catch (err) {
+        await fs_1.promises.unlink(target).catch(() => { });
+        throw new Error(`The new backup did not read back (${err.message}); it was removed and nothing was rotated.`);
+    }
+    // Rotation only ever removes files this module named, never the one just
+    // written, and only after that one has been read back.
+    const all = await listBackups(dir, when);
+    const guardar = retainedBackups(all, retention);
+    guardar.add(name);
     const rotated = [];
-    for (const old of all.slice(keep)) {
+    for (const old of all) {
+        if (guardar.has(old.file))
+            continue;
         try {
             await fs_1.promises.unlink(old.path);
             rotated.push(old.file);
         }
         catch { /* keep going */ }
     }
-    return { file: name, path: target, created: bundle.created, size_bytes: packed.length, counts: bundle.counts, rotated_out: rotated, dir };
+    return {
+        file: name, path: target, created: bundle.created, size_bytes: packed.length, counts: bundle.counts, rotated_out: rotated, dir,
+        verified: true, unreadable, retention, ...(sealed ? { encrypted: true } : {}),
+    };
 }
 async function readBackup(file) {
-    const raw = await fs_1.promises.readFile(file);
+    const bytes = await fs_1.promises.readFile(file);
+    const raw = (await atRest()).unseal(bytes);
     const bundle = JSON.parse((await gunzip(raw)).toString('utf8'));
     if (!bundle || typeof bundle !== 'object' || !bundle.files || typeof bundle.files !== 'object') {
         throw new Error('Not a CRBRO backup: no files section.');
@@ -218,11 +336,13 @@ async function autoBackupIfDue(paths, opts = {}) {
     try {
         const dir = opts.dir || resolveBackupDir(paths.root, env);
         const now = opts.now || new Date();
-        const newest = (await listBackups(dir))[0];
+        // A future-dated copy is listed by its file date, so it cannot hold
+        // automatic copies off until the clock catches up with its name.
+        const newest = (await listBackups(dir, now))[0];
         if (newest && now.getTime() - Date.parse(newest.created) < exports.AUTO_BACKUP_INTERVAL_MS) {
             return { made: false, reason: 'recent backup exists', file: newest.file };
         }
-        const r = await createBackup(paths, { dir, now });
+        const r = await createBackup(paths, { dir, now, env });
         return { made: true, reason: newest ? 'older than 24h' : 'first backup', file: r.file };
     }
     catch (err) {

package/dist/engine/brain.js

@@ -66,6 +66,11 @@ const MANIFEST_FILE = 'manifest.json';
 // crbro_inspect view=status.
 const CRBRO_VERSION = '1.0.0';
 // ─── Paths ───────────────────────────────────────────────────────
+function fileId(id) {
+    if (typeof id !== 'string' || !id || /[\\/:\0]/.test(id))
+        throw new Error(`Invalid id: ${JSON.stringify(String(id).slice(0, 80))}`);
+    return id;
+}
 class BrainPaths {
     root;
     cortex;
@@ -94,11 +99,13 @@ class BrainPaths {
     manifest() {
         return node_path_1.default.join(this.root, MANIFEST_FILE);
     }
+    // An id is a file name, never a path: "../../x" from a tool argument (and,
+    // with serve --http, from the network) must not read or write outside the brain.
     neuron(id) {
-        return node_path_1.default.join(this.cortex, `${id}.json`);
+        return node_path_1.default.join(this.cortex, `${fileId(id)}.json`);
     }
     synapse(id) {
-        return node_path_1.default.join(this.synapses, `${id}.json`);
+        return node_path_1.default.join(this.synapses, `${fileId(id)}.json`);
     }
     session(id) {
         return node_path_1.default.join(this.hippocampus, `${id}.json`);
@@ -324,19 +331,28 @@ class Brain {
             for (const file of files) {
                 if (!file.startsWith('protocol_') || !file.endsWith('.json'))
                     continue;
-                const neuron = await (0, fs_js_1.readJSON)(node_path_1.default.join(cortexDir, file));
+                // One unreadable protocol file costs that protocol only (2.11): it
+                // used to end the loop, and every protocol after it left the boot.
+                let neuron = null;
+                try {
+                    neuron = await (0, fs_js_1.readJSON)(node_path_1.default.join(cortexDir, file));
+                }
+                catch {
+                    continue;
+                }
                 if (!neuron)
                     continue;
+                const tags = Array.isArray(neuron.tags) ? neuron.tags : [];
                 // Extract priority from tags (e.g., "priority:10")
-                const priorityTag = neuron.tags.find(t => t.startsWith('priority:'));
+                const priorityTag = tags.find(t => t.startsWith('priority:'));
                 const priority = priorityTag ? parseInt(priorityTag.split(':')[1]) : 5;
                 // Extract source from tags (e.g., "source:zero-deck")
-                const sourceTag = neuron.tags.find(t => t.startsWith('source:'));
+                const sourceTag = tags.find(t => t.startsWith('source:'));
                 const source = sourceTag ? sourceTag.split(':')[1] : 'manual';
                 // Combine the ACTIVE facts into a single instruction block. Without
                 // the filter, correcting a protocol via supersedes injected both the
                 // old and the new wording into every session, side by side.
-                const instructions = neuron.facts
+                const instructions = (neuron.facts || [])
                     .filter(f => !f.status || f.status === 'active')
                     .map(f => f.text)
                     .join('\n\n');