@theihtisham/agent-shadow-brain 6.3.0 → 7.0.0

package/dist/brain/global-brain.js

@@ -1,23 +1,18 @@
-// src/brain/global-brain.ts — Singleton Global Brain (v5.2.0)
-//
-// One brain. Every project. Every agent. Every machine.
-//
-// The Global Brain is a singleton store at ~/.shadow-brain/global.json that
-// every Shadow Brain instance reads from and writes to. Insights from project
-// A using Cursor are immediately available to project B using Claude Code.
-//
-// Storage: append-friendly JSON store (no native deps), persisted on every
-// flush. Combined with l0-cache.ts, hot recalls return in <1ms.
-//
-// Concurrency: write queue + atomic file replace prevents conflicts when
-// multiple agents write simultaneously.
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
+import { setTimeout as delay } from 'node:timers/promises';
 import { getBrainBus } from './brain-bus.js';
-const DEFAULT_DIR = path.join(os.homedir(), '.shadow-brain');
-const DEFAULT_DB_PATH = path.join(DEFAULT_DIR, 'global.json');
+const DEFAULT_DB_PATH = path.join(os.homedir(), '.shadow-brain', 'global.json');
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_POLL_MS = 20;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const BYTES_PER_MB = 1024 * 1024;
+const STOP_WORDS = new Set([
+    'a', 'an', 'and', 'are', 'as', 'for', 'from', 'in', 'into', 'is', 'of', 'on',
+    'or', 'the', 'to', 'with', 'ww2br',
+]);
 const DEFAULT_CONFIG = {
     dbPath: DEFAULT_DB_PATH,
     walMode: true,
@@ -26,23 +21,114 @@ const DEFAULT_CONFIG = {
     autoPruneMB: 1000,
     syncIntervalMs: 5000,
 };
-/**
- * Singleton Global Brain — the source of truth for all projects + agents.
- *
- * Storage: JSON file at ~/.shadow-brain/global.json (zero new deps).
- * In-memory Map keyed by entry.id for O(1) ID lookups.
- */
+class StorageError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'GlobalBrainStorageError';
+    }
+}
+function errorCode(error) {
+    return error?.code;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasUniqueKeys(rows, key, required) {
+    const keys = new Set();
+    for (const row of rows) {
+        if (!isRecord(row) || required.some(field => typeof row[field] !== 'string'))
+            return false;
+        const id = row[key];
+        if (typeof id !== 'string' || !id || keys.has(id))
+            return false;
+        keys.add(id);
+    }
+    return true;
+}
+function validateSnapshot(value) {
+    if (!isRecord(value) || !Number.isInteger(value.schemaVersion) || Number(value.schemaVersion) < 1) {
+        throw new StorageError('STORE_INVALID_SCHEMA', 'The global brain store has an invalid schema.');
+    }
+    if (value.schemaVersion !== 1) {
+        throw new StorageError('STORE_UNSUPPORTED_SCHEMA', 'The global brain store uses an unsupported schema version.');
+    }
+    if (!Array.isArray(value.entries) ||
+        !hasUniqueKeys(value.entries, 'id', ['projectId', 'projectName', 'agentTool', 'category', 'content']) ||
+        !Array.isArray(value.projects) ||
+        !hasUniqueKeys(value.projects, 'id', ['name', 'rootDir']) ||
+        !Array.isArray(value.agents) ||
+        !hasUniqueKeys(value.agents, 'tool', [])) {
+        throw new StorageError('STORE_INVALID_SCHEMA', 'The global brain store has an invalid schema.');
+    }
+}
+function boundedSignal(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.min(value, 1)) : 0;
+}
+function nonNegativeInt(value, fallback = 0) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(0, Math.min(Math.trunc(value), Number.MAX_SAFE_INTEGER))
+        : fallback;
+}
+function dateTime(value) {
+    const timestamp = value instanceof Date
+        ? value.getTime()
+        : typeof value === 'string' || typeof value === 'number' ? new Date(value).getTime() : 0;
+    return Number.isFinite(timestamp) && timestamp > 0 ? timestamp : 0;
+}
+function hydrateEntry(entry) {
+    return {
+        ...entry,
+        importance: boundedSignal(entry.importance),
+        accessCount: nonNegativeInt(entry.accessCount),
+        createdAt: new Date(dateTime(entry.createdAt)),
+        lastAccessed: new Date(dateTime(entry.lastAccessed)),
+        metadata: isRecord(entry.metadata) ? entry.metadata : {},
+    };
+}
+function normalizeText(value) {
+    return value.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+function normalizeKeywords(keywords) {
+    if (!Array.isArray(keywords))
+        return [];
+    const unique = new Set();
+    for (const value of keywords) {
+        if (typeof value !== 'string')
+            continue;
+        const keyword = normalizeText(value);
+        if (keyword.length > 2 && !STOP_WORDS.has(keyword))
+            unique.add(keyword);
+    }
+    return [...unique];
+}
+function searchableMetadata(metadata) {
+    try {
+        return normalizeText(JSON.stringify(metadata));
+    }
+    catch {
+        return '';
+    }
+}
+function evidenceKey(entry) {
+    return JSON.stringify([entry.projectId, entry.category, normalizeText(entry.content)]);
+}
+function compareIds(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Local JSON store shared by cooperating Global Brain processes. */
 export class GlobalBrain {
     constructor(config = {}) {
         this.entries = new Map();
-        this.projects = new Map();
-        this.agents = new Map();
-        this.writeQueue = [];
+        this.pendingOperations = [];
         this.syncTimer = null;
-        this.initialized = false;
-        this.dirty = false;
-        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.syncInFlight = null;
         this.startedAt = Date.now();
+        this.initialized = false;
+        this.shuttingDown = false;
+        this.lastSuccessfulSync = null;
+        this.lastError = null;
+        this.config = { ...DEFAULT_CONFIG, ...config, dbPath: path.resolve(config.dbPath ?? DEFAULT_DB_PATH) };
         this.stats = {
             totalProjects: 0,
             totalAgents: 0,
@@ -59,428 +145,580 @@ export class GlobalBrain {
         };
     }
     static getInstance(config) {
-        if (!GlobalBrain.instance) {
-            GlobalBrain.instance = new GlobalBrain(config);
-        }
+        GlobalBrain.instance ?? (GlobalBrain.instance = new GlobalBrain(config));
         return GlobalBrain.instance;
     }
     async init() {
+        this.initialize();
+    }
+    initialize() {
         if (this.initialized)
             return;
-        fs.mkdirSync(path.dirname(this.config.dbPath), { recursive: true });
-        if (fs.existsSync(this.config.dbPath)) {
+        try {
             try {
-                const raw = fs.readFileSync(this.config.dbPath, 'utf-8');
-                const parsed = JSON.parse(raw);
-                for (const e of parsed.entries ?? []) {
-                    // Re-hydrate Date instances
-                    this.entries.set(e.id, {
-                        ...e,
-                        createdAt: new Date(e.createdAt),
-                        lastAccessed: new Date(e.lastAccessed),
-                    });
-                }
-                for (const p of parsed.projects ?? [])
-                    this.projects.set(p.id, p);
-                for (const a of parsed.agents ?? [])
-                    this.agents.set(a.tool, a);
+                fs.mkdirSync(path.dirname(this.dbPath), { recursive: true });
             }
-            catch {
-                // Corrupted file → start fresh, back up the bad one
-                try {
-                    fs.renameSync(this.config.dbPath, this.config.dbPath + '.corrupt-' + Date.now());
-                }
-                catch { /* ignore */ }
+            catch (error) {
+                throw new StorageError('STORE_READ_FAILED', `Could not open the global brain store directory (${errorCode(error) ?? 'I/O error'}).`);
             }
+            const { data, sizeMB } = this.readLatestSnapshot();
+            this.adoptSnapshot(data, sizeMB, this.hydrateEntries(data));
+            this.initialized = true;
+            this.lastError = null;
+            this.syncTimer = setInterval(() => {
+                if (!this.syncInFlight)
+                    void this.sync().catch(() => { });
+            }, this.config.syncIntervalMs);
+        }
+        catch (error) {
+            throw this.recordError(error);
         }
-        this.startSyncLoop();
-        this.refreshStats();
-        this.initialized = true;
     }
-    /** Generate a stable project ID from absolute path */
+    /** Generate a stable project ID from absolute path. */
     static projectIdFor(rootDir) {
         const abs = path.resolve(rootDir);
         return crypto.createHash('sha1').update(abs).digest('hex').slice(0, 16);
     }
     registerProject(rootDir, name) {
-        if (!this.initialized)
-            throw new Error('GlobalBrain not initialized — call init() first');
+        this.requireWritable();
+        if (name !== undefined && typeof name !== 'string')
+            throw new TypeError('Project name must be a string');
         const id = GlobalBrain.projectIdFor(rootDir);
-        const projectName = name || path.basename(rootDir);
         const now = Date.now();
-        const existing = this.projects.get(id);
-        this.projects.set(id, {
-            id,
-            name: projectName,
-            rootDir: path.resolve(rootDir),
-            firstSeen: existing?.firstSeen ?? now,
-            lastSeen: now,
+        this.pendingOperations.push({
+            kind: 'project',
+            project: { id, name: name || path.basename(rootDir), rootDir: path.resolve(rootDir), firstSeen: now, lastSeen: now },
         });
-        this.dirty = true;
         return id;
     }
     registerAgent(agent) {
-        if (!this.initialized)
+        if (!this.initialized || this.shuttingDown)
             return;
-        const now = Date.now();
-        const existing = this.agents.get(agent);
-        this.agents.set(agent, {
-            tool: agent,
-            firstSeen: existing?.firstSeen ?? now,
-            lastSeen: now,
-            sessionCount: (existing?.sessionCount ?? 0) + 1,
-        });
-        this.dirty = true;
+        if (typeof agent !== 'string' || !agent)
+            throw new TypeError('Agent tool must be a nonempty string');
+        this.pendingOperations.push({ kind: 'agent', tool: agent, at: Date.now() });
     }
-    /** Queue a write — resolves true on success */
+    /** Queue a write. A failed attempt resolves false and retains the entry for a later sync. */
     async write(entry) {
-        if (!this.initialized)
-            await this.init();
-        const fullEntry = {
-            ...entry,
-            id: crypto.randomUUID(),
-            createdAt: new Date(),
-            lastAccessed: new Date(),
-            accessCount: 0,
-        };
-        if (this.writeQueue.length >= this.config.writeQueueSize) {
+        if (this.shuttingDown)
             return false;
-        }
-        return new Promise((resolve) => {
-            this.writeQueue.push({ entry: fullEntry, resolve });
+        this.initialize();
+        if (this.pendingWriteCount() >= this.config.writeQueueSize)
+            return false;
+        const stored = this.prepareEntry(entry);
+        return new Promise(settle => {
+            this.pendingOperations.push({ kind: 'add', entry: stored, queued: true, settle });
         });
     }
-    /** Direct synchronous write — bypasses queue */
+    /** Stage an entry for later sync and return its ID immediately. */
     writeSync(entry) {
+        this.requireWritable();
+        const stored = this.prepareEntry(entry);
+        this.pendingOperations.push({ kind: 'add', entry: stored, queued: false });
+        this.entries.set(stored.id, hydrateEntry(structuredClone(stored)));
+        return stored.id;
+    }
+    requireWritable() {
         if (!this.initialized)
-            throw new Error('GlobalBrain not initialized');
-        const id = crypto.randomUUID();
-        const fullEntry = {
-            ...entry,
-            id,
-            createdAt: new Date(),
-            lastAccessed: new Date(),
-            accessCount: 0,
-        };
-        this.entries.set(id, fullEntry);
-        this.dirty = true;
-        this.stats.totalEntries = this.entries.size;
-        this.publishWrite(fullEntry);
-        return id;
+            throw new Error('GlobalBrain not initialized — call init() first');
+        if (this.shuttingDown)
+            throw new Error('GlobalBrain is shutting down');
+    }
+    prepareEntry(entry) {
+        const now = new Date();
+        // Snapshot caller input now so later mutations or serialization errors cannot block a commit.
+        try {
+            const data = JSON.parse(JSON.stringify({
+                ...entry, id: crypto.randomUUID(), createdAt: now, lastAccessed: now, accessCount: 0,
+            }));
+            if (hasUniqueKeys([data], 'id', ['projectId', 'projectName', 'agentTool', 'category', 'content'])) {
+                return data;
+            }
+        }
+        catch { /* Report an invalid input without exposing its contents. */ }
+        throw new StorageError('STORE_INVALID_ENTRY', 'The memory entry cannot be stored as JSON.');
     }
-    /** Broadcast a memory-write to the realtime activity bus (best-effort). */
     publishWrite(entry) {
         try {
             getBrainBus().publish({
                 id: `memory-write:${entry.id}`,
-                ts: entry.createdAt instanceof Date ? entry.createdAt.getTime() : Date.now(),
+                ts: dateTime(entry.createdAt),
                 type: 'memory-write',
                 source: entry.agentTool,
-                detail: `[${entry.category}] ${String(entry.content).slice(0, 220)}`,
+                detail: `[${entry.category}] ${entry.content.slice(0, 220)}`,
                 meta: {
                     category: entry.category,
-                    importance: entry.importance,
+                    importance: boundedSignal(entry.importance),
                     projectName: entry.projectName,
                     projectId: entry.projectId,
                 },
             });
         }
-        catch { /* bus failures must never break a write */ }
+        catch { /* Activity subscribers cannot affect the outcome of a commit. */ }
     }
-    /** Recall entries — cross-project + cross-agent */
+    /** Recall matching entries across projects and agents. */
     recall(opts = {}) {
         if (!this.initialized)
             return [];
-        const limit = opts.limit ?? 20;
-        const minImp = opts.minImportance ?? 0;
-        const weakKeywords = new Set([
-            'a', 'an', 'and', 'are', 'as', 'for', 'from', 'in', 'into', 'is', 'of', 'on',
-            'or', 'the', 'to', 'with', 'ww2br',
-        ]);
-        const kwLower = opts.keywords
-            ?.map(k => k.trim().toLowerCase())
-            .filter(k => k && !/^\d{1,2}$/.test(k))
-            .filter(k => k.length > 2 && !weakKeywords.has(k)) ?? null;
+        const keywords = normalizeKeywords(opts.keywords);
+        const result = this.findMatches(opts, keywords)
+            .sort((a, b) => b.relevance - a.relevance || this.compareEntries(a.entry, b.entry))
+            .slice(0, nonNegativeInt(opts.limit, 20))
+            .map(match => match.entry);
+        this.recordRecall(result.length);
+        return result;
+    }
+    /** Recall entries with heuristic ranking signals and an explanation of the match. */
+    recallScored(opts = {}) {
+        if (!this.initialized)
+            return [];
+        const keywords = normalizeKeywords(opts.keywords);
+        const candidates = this.findMatches(opts, keywords);
+        const evidence = new Map();
+        for (const { entry } of candidates) {
+            if (normalizeText(entry.content))
+                evidence.set(evidenceKey(entry), new Set());
+        }
+        for (const entry of this.entries.values()) {
+            evidence.get(evidenceKey(entry))?.add(entry.agentTool);
+        }
+        const now = Date.now();
+        const minConfidence = boundedSignal(opts.minConfidence);
+        const result = candidates
+            .map(match => {
+            const entry = match.entry;
+            const peers = [...(evidence.get(evidenceKey(entry)) ?? [])]
+                .filter(tool => tool !== entry.agentTool)
+                .sort(compareIds);
+            return { ...entry, confidence: this.computeConfidence(match, keywords.length, peers, now) };
+        })
+            .filter(entry => entry.confidence.score >= minConfidence)
+            .sort((a, b) => b.confidence.score - a.confidence.score || this.compareEntries(a, b))
+            .slice(0, nonNegativeInt(opts.limit, 20));
+        this.recordRecall(result.length);
+        return result;
+    }
+    findMatches(opts, keywords) {
+        const minImportance = boundedSignal(opts.minImportance);
         const matches = [];
-        for (const e of this.entries.values()) {
-            if (opts.projectId && e.projectId !== opts.projectId)
+        for (const entry of this.entries.values()) {
+            if (opts.projectId && entry.projectId !== opts.projectId)
                 continue;
-            if (opts.agentTool && e.agentTool !== opts.agentTool)
+            if (opts.agentTool && entry.agentTool !== opts.agentTool)
                 continue;
-            if (opts.category && e.category !== opts.category)
+            if (opts.category && entry.category !== opts.category)
                 continue;
-            if (e.importance < minImp)
+            if (boundedSignal(entry.importance) < minImportance)
                 continue;
-            let score = 0;
-            if (kwLower?.length) {
-                const projectName = e.projectName.toLowerCase();
-                const agentTool = e.agentTool.toLowerCase();
-                const category = e.category.toLowerCase();
-                const content = e.content.toLowerCase();
-                const metadata = JSON.stringify(e.metadata ?? {}).toLowerCase();
-                for (const k of kwLower) {
-                    if (category.includes(k))
-                        score += 8;
-                    if (content.includes(k))
-                        score += 5;
-                    if (metadata.includes(k))
-                        score += 3;
-                    if (agentTool.includes(k))
-                        score += 1;
-                    if (projectName.includes(k))
-                        score += 1;
-                }
-                if (score <= 0)
+            if (!keywords.length) {
+                matches.push({ entry, relevance: 0.5, matchedKeywords: [] });
+                continue;
+            }
+            const content = normalizeText(entry.content);
+            const category = normalizeText(entry.category);
+            const metadata = searchableMetadata(entry.metadata);
+            const project = normalizeText(entry.projectName);
+            const tool = normalizeText(entry.agentTool);
+            const matchedKeywords = [];
+            let weight = 0;
+            for (const term of keywords) {
+                if (content.includes(term))
+                    weight += 1;
+                else if (category.includes(term))
+                    weight += 0.9;
+                else if (metadata.includes(term))
+                    weight += 0.55;
+                else if (project.includes(term) || tool.includes(term))
+                    weight += 0.25;
+                else
                     continue;
+                matchedKeywords.push(term);
             }
-            matches.push({ entry: e, score });
+            if (matchedKeywords.length)
+                matches.push({ entry, relevance: weight / keywords.length, matchedKeywords });
         }
-        matches.sort((a, b) => {
-            if (b.score !== a.score)
-                return b.score - a.score;
-            if (b.entry.importance !== a.entry.importance)
-                return b.entry.importance - a.entry.importance;
-            return b.entry.lastAccessed.getTime() - a.entry.lastAccessed.getTime();
-        });
-        const result = matches.slice(0, limit).map(m => m.entry);
-        if (result.length)
+        return matches;
+    }
+    compareEntries(a, b) {
+        return boundedSignal(b.importance) - boundedSignal(a.importance) ||
+            dateTime(b.lastAccessed) - dateTime(a.lastAccessed) ||
+            compareIds(a.id, b.id);
+    }
+    recordRecall(count) {
+        if (count > 0)
             this.stats.hits++;
         else
             this.stats.misses++;
-        return result;
     }
-    /**
-     * Recall entries with a per-entry confidence score (v6.3.0).
-     *
-     * Same matching as recall(), but each result carries a RecallConfidence so
-     * the consuming agent can weight memories by recency, author importance,
-     * cross-agent corroboration, prior usage, and keyword relevance rather than
-     * trusting every hit equally. Ordering switches from raw keyword score to
-     * blended confidence so the most trustworthy memories surface first.
-     */
-    recallScored(opts = {}) {
-        if (!this.initialized)
-            return [];
-        const limit = opts.limit ?? 20;
-        const minConfidence = opts.minConfidence ?? 0;
-        // Pull a wider candidate pool (pre-confidence) so confidence re-ranking has
-        // room to promote highly-trusted-but-lower-keyword-score memories.
-        const candidates = this.recall({
-            projectId: opts.projectId,
-            agentTool: opts.agentTool,
-            category: opts.category,
-            keywords: opts.keywords,
-            limit: Math.max(limit * 3, 60),
-            minImportance: opts.minImportance,
-        });
-        // Corroboration baseline: distinct agents that have written in each category.
-        const agentsPerCategory = new Map();
-        for (const e of this.entries.values()) {
-            let set = agentsPerCategory.get(e.category);
-            if (!set) {
-                set = new Set();
-                agentsPerCategory.set(e.category, set);
-            }
-            set.add(e.agentTool);
-        }
-        const hasKeywords = (opts.keywords?.filter(k => k && k.trim().length > 2).length ?? 0) > 0;
-        const now = Date.now();
-        const scored = candidates
-            .map(entry => ({
-            ...entry,
-            confidence: this.computeConfidence(entry, {
-                hasKeywords,
-                now,
-                distinctAgentsInCategory: agentsPerCategory.get(entry.category)?.size ?? 1,
-            }),
-        }))
-            .filter(e => e.confidence.score >= minConfidence);
-        scored.sort((a, b) => b.confidence.score - a.confidence.score);
-        return scored.slice(0, limit);
-    }
-    /** Blend recall signals into a single confidence score in [0,1]. */
-    computeConfidence(entry, ctx) {
-        const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
-        // Relevance: when the caller supplied keywords, a match means relevance is
-        // high; without keywords we cannot judge relevance, so use a neutral 0.5.
-        const relevance = ctx.hasKeywords ? 0.9 : 0.5;
-        // Recency: exponential decay with a 30-day half-life on last access.
-        const HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000;
-        const lastAccess = entry.lastAccessed instanceof Date
-            ? entry.lastAccessed.getTime()
-            : new Date(entry.lastAccessed).getTime();
-        const ageMs = Math.max(0, ctx.now - lastAccess);
-        const recency = clamp01(Math.pow(0.5, ageMs / HALF_LIFE_MS));
-        // Importance: author-assigned, already in [0,1] by convention.
-        const importance = clamp01(entry.importance);
-        // Corroboration: more distinct agents writing in this category => more
-        // cross-agent agreement. Saturates at 3 agents.
-        const corroboration = clamp01((ctx.distinctAgentsInCategory - 1) / 2);
-        // Usage: log-scaled prior recalls; saturates around ~20 accesses.
-        const usage = clamp01(Math.log10(entry.accessCount + 1) / Math.log10(21));
-        // Weighted blend. Relevance + importance dominate; recency/usage refine;
-        // corroboration is a smaller cross-agent trust nudge.
-        const score = clamp01(relevance * 0.30 +
-            importance * 0.25 +
-            recency * 0.20 +
-            usage * 0.15 +
-            corroboration * 0.10);
-        const level = score >= 0.66 ? 'high' : score >= 0.33 ? 'medium' : 'low';
-        const round = (n) => Math.round(n * 1000) / 1000;
+    computeConfidence(match, totalKeywords, peers, now) {
+        const createdAt = dateTime(match.entry.createdAt);
+        const recency = createdAt > 0 && createdAt <= now ? Math.pow(0.5, (now - createdAt) / (30 * DAY_MS)) : 0;
+        const importance = boundedSignal(match.entry.importance);
+        const corroboration = Math.min(1, peers.length / 2);
+        const usage = Math.min(1, Math.log10(nonNegativeInt(match.entry.accessCount) + 1) / Math.log10(21));
+        const round = (value) => Math.round(boundedSignal(value) * 1000) / 1000;
+        const score = round(match.relevance * 0.30 + importance * 0.25 + recency * 0.20 + usage * 0.15 + corroboration * 0.10);
         return {
-            score: round(score),
-            level,
+            score,
+            level: score >= 0.66 ? 'high' : score >= 0.33 ? 'medium' : 'low',
             signals: {
-                relevance: round(relevance),
+                relevance: round(match.relevance),
                 recency: round(recency),
                 importance: round(importance),
                 corroboration: round(corroboration),
                 usage: round(usage),
             },
+            explanation: { matchedKeywords: match.matchedKeywords, totalKeywords, corroboratingAgents: peers },
         };
     }
-    /** Bump access count for an entry */
+    /** Bump an entry's access count without replacing its persisted snapshot. */
     touch(id) {
+        if (!this.initialized || this.shuttingDown)
+            return;
         const entry = this.entries.get(id);
         if (!entry)
             return;
-        entry.accessCount++;
-        entry.lastAccessed = new Date();
-        this.dirty = true;
+        const now = Date.now();
+        entry.accessCount = nonNegativeInt(nonNegativeInt(entry.accessCount) + 1);
+        entry.lastAccessed = new Date(Math.max(dateTime(entry.lastAccessed), now));
+        this.pendingOperations.push({ kind: 'touch', id, at: now });
     }
     recallByIds(ids) {
         const out = [];
         for (const id of ids) {
-            const e = this.entries.get(id);
-            if (e)
-                out.push(e);
+            const entry = this.entries.get(id);
+            if (entry)
+                out.push(entry);
         }
         return out;
     }
-    /** Chronological proof stream for dashboards, handoffs, and launch demos. */
+    /** Chronological memory stream for dashboards and handoffs. */
     timeline(opts = {}) {
         if (!this.initialized)
             return [];
-        const limit = opts.limit ?? 50;
         return Array.from(this.entries.values())
-            .filter(e => !opts.projectId || e.projectId === opts.projectId)
-            .filter(e => !opts.agentTool || e.agentTool === opts.agentTool)
-            .filter(e => !opts.category || e.category === opts.category)
-            .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
-            .slice(0, limit)
-            .map(e => ({
-            id: e.id,
-            projectId: e.projectId,
-            projectName: e.projectName,
-            agentTool: e.agentTool,
-            category: e.category,
-            content: e.content,
-            importance: e.importance,
-            createdAt: e.createdAt,
-            lastAccessed: e.lastAccessed,
-            metadata: e.metadata,
+            .filter(entry => !opts.projectId || entry.projectId === opts.projectId)
+            .filter(entry => !opts.agentTool || entry.agentTool === opts.agentTool)
+            .filter(entry => !opts.category || entry.category === opts.category)
+            .sort((a, b) => dateTime(b.createdAt) - dateTime(a.createdAt) || compareIds(a.id, b.id))
+            .slice(0, nonNegativeInt(opts.limit, 50))
+            .map(({ id, projectId, projectName, agentTool, category, content, importance, createdAt, lastAccessed, metadata }) => ({
+            id, projectId, projectName, agentTool, category, content, importance, createdAt, lastAccessed, metadata,
         }));
     }
     getStats() {
-        this.refreshStats();
-        return { ...this.stats };
+        const checks = this.stats.hits + this.stats.misses;
+        return {
+            ...this.stats,
+            totalEntries: this.entries.size,
+            pendingWrites: this.pendingWriteCount(),
+            hitRate: checks ? this.stats.hits / checks : 0,
+            uptime: Date.now() - this.startedAt,
+        };
     }
-    /** Absolute path to the on-disk brain store — used by the dashboard file watcher. */
+    pendingWriteCount() {
+        return this.pendingOperations.filter(operation => operation.kind === 'add' && operation.queued).length;
+    }
+    /** Absolute path to the on-disk brain store. */
     get dbPath() {
         return this.config.dbPath;
     }
-    /** Force a sync of pending writes to disk */
+    getStorageHealth() {
+        return {
+            status: this.lastError ? 'error' : this.pendingOperations.length ? 'pending' : 'healthy',
+            dbPath: this.dbPath,
+            initialized: this.initialized,
+            pendingOperations: this.pendingOperations.length,
+            lastSuccessfulSync: this.lastSuccessfulSync,
+            lastError: this.lastError ? { ...this.lastError } : null,
+        };
+    }
+    /** Flush pending operations as one atomic commit against the latest snapshot. */
     async sync() {
+        if (this.syncInFlight) {
+            await this.syncInFlight;
+            return this.sync();
+        }
         if (!this.initialized)
             return;
-        if (this.writeQueue.length > 0) {
-            const pending = this.writeQueue.splice(0, this.writeQueue.length);
-            for (const { entry, resolve } of pending) {
-                try {
-                    this.entries.set(entry.id, entry);
-                    this.publishWrite(entry);
-                    resolve(true);
-                }
-                catch {
-                    resolve(false);
+        if (!this.pendingOperations.length) {
+            this.refreshSnapshot();
+            return;
+        }
+        this.syncInFlight = this.commitPending();
+        try {
+            await this.syncInFlight;
+        }
+        finally {
+            this.syncInFlight = null;
+        }
+    }
+    async commitPending() {
+        let releaseLock;
+        let committed;
+        try {
+            releaseLock = await this.acquireLock();
+            // Capture operations after acquiring the lock. No async work follows inside the merge.
+            const operations = this.pendingOperations;
+            const additions = operations.filter((operation) => operation.kind === 'add');
+            const data = this.mergeOperations(this.readLatestSnapshot().data, operations);
+            const { payload, pruned } = this.serializeSnapshot(data, additions);
+            const entries = this.hydrateEntries(data);
+            const sizeMB = Buffer.byteLength(payload) / BYTES_PER_MB;
+            this.replaceSnapshot(payload);
+            this.adoptSnapshot(data, sizeMB, entries);
+            const now = new Date();
+            this.stats.lastSync = now;
+            if (pruned)
+                this.stats.lastPrune = now;
+            this.lastSuccessfulSync = now.toISOString();
+            this.lastError = null;
+            committed = additions;
+            operations.length = 0;
+        }
+        catch (error) {
+            const failure = this.recordError(error);
+            for (const operation of this.pendingOperations) {
+                if (operation.kind === 'add') {
+                    operation.settle?.(false);
+                    operation.settle = undefined;
                 }
             }
-            this.dirty = true;
+            throw failure;
+        }
+        finally {
+            try {
+                releaseLock?.();
+            }
+            catch (error) {
+                // Lock cleanup cannot reverse a successful replacement or make its operations retryable.
+                if (committed)
+                    this.recordError(error);
+            }
         }
-        if (this.dirty) {
-            this.persist();
-            this.stats.lastSync = new Date();
-            this.dirty = false;
+        for (const operation of committed) {
+            operation.settle?.(true);
+            this.publishWrite(operation.entry);
         }
-        this.maybeAutoMaintenance();
     }
-    maybeAutoMaintenance() {
-        const sizeMB = this.estimateSizeMB();
-        this.stats.totalSizeMB = sizeMB;
-        if (sizeMB > this.config.autoPruneMB)
-            this.prune();
-    }
-    /** Auto-prune: drop low-importance, rarely-accessed entries when over threshold */
-    prune() {
-        const cutoff = Date.now() - 90 * 24 * 60 * 60 * 1000; // 90 days
-        const toDelete = [];
-        for (const [id, e] of this.entries) {
-            if (e.importance < 0.3 && e.accessCount < 2 && e.lastAccessed.getTime() < cutoff) {
-                toDelete.push(id);
+    recordError(error) {
+        const failure = error instanceof StorageError
+            ? error
+            : new StorageError('STORE_WRITE_FAILED', 'Could not commit the global brain store.');
+        this.lastError = { code: failure.code, message: failure.message, at: new Date().toISOString() };
+        return failure;
+    }
+    readLatestSnapshot() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.dbPath, 'utf8');
+        }
+        catch (error) {
+            if (errorCode(error) === 'ENOENT') {
+                return { data: { schemaVersion: 1, entries: [], projects: [], agents: [] }, sizeMB: 0 };
             }
+            throw new StorageError('STORE_READ_FAILED', `Could not read the global brain store (${errorCode(error) ?? 'I/O error'}).`);
+        }
+        let data;
+        try {
+            data = JSON.parse(raw);
         }
-        for (const id of toDelete)
-            this.entries.delete(id);
-        if (toDelete.length) {
-            this.dirty = true;
-            this.stats.lastPrune = new Date();
+        catch {
+            throw new StorageError('STORE_INVALID_JSON', 'The global brain store contains invalid JSON.');
         }
+        validateSnapshot(data);
+        return { data, sizeMB: Buffer.byteLength(raw) / BYTES_PER_MB };
     }
-    persist() {
-        const shape = {
-            schemaVersion: 1,
-            entries: Array.from(this.entries.values()),
-            projects: Array.from(this.projects.values()),
-            agents: Array.from(this.agents.values()),
-        };
-        // Atomic write — write to .tmp then rename
-        const tmp = this.config.dbPath + '.tmp';
-        fs.writeFileSync(tmp, JSON.stringify(shape));
-        fs.renameSync(tmp, this.config.dbPath);
+    hydrateEntries(data) {
+        return new Map(data.entries.map(entry => [entry.id, hydrateEntry(entry)]));
     }
-    startSyncLoop() {
-        if (this.syncTimer)
-            clearInterval(this.syncTimer);
-        this.syncTimer = setInterval(() => {
-            this.sync().catch(() => { });
-        }, this.config.syncIntervalMs);
+    adoptSnapshot(data, sizeMB, entries) {
+        this.entries = entries;
+        this.stats.totalProjects = data.projects.length;
+        this.stats.totalAgents = data.agents.length;
+        this.stats.totalSizeMB = sizeMB;
     }
-    refreshStats() {
-        if (!this.initialized)
-            return;
-        this.stats.totalProjects = this.projects.size;
-        this.stats.totalAgents = this.agents.size;
-        this.stats.totalEntries = this.entries.size;
-        this.stats.pendingWrites = this.writeQueue.length;
-        const totalChecks = this.stats.hits + this.stats.misses;
-        this.stats.hitRate = totalChecks > 0 ? this.stats.hits / totalChecks : 0;
-        this.stats.uptime = Date.now() - this.startedAt;
-    }
-    estimateSizeMB() {
+    refreshSnapshot() {
         try {
-            const stat = fs.statSync(this.config.dbPath);
-            return stat.size / (1024 * 1024);
+            const { data, sizeMB } = this.readLatestSnapshot();
+            this.adoptSnapshot(data, sizeMB, this.hydrateEntries(data));
+            if (this.lastError?.code !== 'STORE_LOCK_FAILED')
+                this.lastError = null;
         }
-        catch {
-            return 0;
+        catch (error) {
+            throw this.recordError(error);
+        }
+    }
+    mergeOperations(data, operations) {
+        const entries = new Map(data.entries.map(entry => [entry.id, entry]));
+        const projects = new Map(data.projects.map(project => [project.id, project]));
+        const agents = new Map(data.agents.map(agent => [agent.tool, agent]));
+        for (const operation of operations) {
+            switch (operation.kind) {
+                case 'add': {
+                    if (!entries.has(operation.entry.id))
+                        entries.set(operation.entry.id, operation.entry);
+                    break;
+                }
+                case 'touch': {
+                    const entry = entries.get(operation.id);
+                    if (entry) {
+                        entries.set(operation.id, {
+                            ...entry,
+                            accessCount: nonNegativeInt(nonNegativeInt(entry.accessCount) + 1),
+                            lastAccessed: new Date(Math.max(dateTime(entry.lastAccessed), operation.at)),
+                        });
+                    }
+                    break;
+                }
+                case 'project': {
+                    const { project } = operation;
+                    const existing = projects.get(project.id);
+                    const lastSeen = nonNegativeInt(existing?.lastSeen);
+                    const latest = existing && lastSeen > project.lastSeen ? existing : project;
+                    projects.set(project.id, {
+                        ...existing,
+                        ...latest,
+                        firstSeen: Math.min(nonNegativeInt(existing?.firstSeen) || project.firstSeen, project.firstSeen),
+                        lastSeen: Math.max(lastSeen, project.lastSeen),
+                    });
+                    break;
+                }
+                case 'agent': {
+                    const existing = agents.get(operation.tool);
+                    agents.set(operation.tool, {
+                        ...existing,
+                        tool: operation.tool,
+                        firstSeen: Math.min(nonNegativeInt(existing?.firstSeen) || operation.at, operation.at),
+                        lastSeen: Math.max(nonNegativeInt(existing?.lastSeen), operation.at),
+                        sessionCount: nonNegativeInt(nonNegativeInt(existing?.sessionCount) + 1),
+                    });
+                    break;
+                }
+            }
+        }
+        return { ...data, entries: [...entries.values()], projects: [...projects.values()], agents: [...agents.values()] };
+    }
+    serializeSnapshot(data, additions) {
+        const payload = JSON.stringify(data);
+        if (Buffer.byteLength(payload) / BYTES_PER_MB <= this.config.autoPruneMB)
+            return { payload, pruned: false };
+        const cutoff = Date.now() - 90 * DAY_MS;
+        const addedIds = new Set(additions.map(({ entry }) => entry.id));
+        const retained = data.entries.filter(entry => {
+            const lastAccess = dateTime(entry.lastAccessed);
+            return addedIds.has(entry.id) || !lastAccess || lastAccess >= cutoff ||
+                boundedSignal(entry.importance) >= 0.3 || nonNegativeInt(entry.accessCount) >= 2;
+        });
+        if (retained.length === data.entries.length)
+            return { payload, pruned: false };
+        data.entries = retained;
+        return { payload: JSON.stringify(data), pruned: true };
+    }
+    async acquireLock() {
+        const lockPath = `${this.dbPath}.lock`;
+        const token = JSON.stringify({ pid: process.pid, id: crypto.randomUUID(), acquiredAt: new Date().toISOString() });
+        const deadline = performance.now() + nonNegativeInt(this.config.lockTimeoutMs, LOCK_TIMEOUT_MS);
+        for (;;) {
+            let fd;
+            try {
+                fd = fs.openSync(lockPath, 'wx', 0o600);
+            }
+            catch (error) {
+                if (errorCode(error) !== 'EEXIST') {
+                    throw new StorageError('STORE_LOCK_FAILED', `Could not acquire the global brain store lock (${errorCode(error) ?? 'I/O error'}).`);
+                }
+                const remaining = deadline - performance.now();
+                if (remaining <= 0)
+                    break;
+                await delay(Math.min(remaining, LOCK_POLL_MS));
+                if (performance.now() >= deadline)
+                    break;
+                continue;
+            }
+            let identity;
+            try {
+                identity = fs.fstatSync(fd, { bigint: true });
+                fs.writeFileSync(fd, token, 'utf8');
+                fs.closeSync(fd);
+            }
+            catch {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* preserve the lock initialization error */ }
+                // A failed token write can leave partial bytes. Check the exclusive file's identity.
+                try {
+                    const current = fs.lstatSync(lockPath, { bigint: true });
+                    if (identity && current.dev === identity.dev && current.ino === identity.ino)
+                        fs.unlinkSync(lockPath);
+                }
+                catch { /* report the lock initialization error */ }
+                throw new StorageError('STORE_LOCK_FAILED', 'Could not initialize the global brain store lock.');
+            }
+            return () => {
+                try {
+                    if (fs.readFileSync(lockPath, 'utf8') === token) {
+                        fs.unlinkSync(lockPath);
+                        return;
+                    }
+                }
+                catch {
+                    throw new StorageError('STORE_LOCK_FAILED', 'Could not release the global brain store lock.');
+                }
+                throw new StorageError('STORE_LOCK_FAILED', 'Global brain store lock ownership changed before release.');
+            };
+        }
+        throw new StorageError('STORE_LOCK_TIMEOUT', 'Timed out waiting for the global brain store lock.');
+    }
+    replaceSnapshot(payload) {
+        const tmp = `${this.dbPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+        let fd;
+        let ownsTemp = false;
+        try {
+            fd = fs.openSync(tmp, 'wx', 0o600);
+            ownsTemp = true;
+            fs.writeFileSync(fd, payload, 'utf8');
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fd = undefined;
+            fs.renameSync(tmp, this.dbPath);
+            ownsTemp = false;
+        }
+        catch (error) {
+            throw new StorageError('STORE_WRITE_FAILED', `Could not replace the global brain store (${errorCode(error) ?? 'I/O error'}).`);
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* preserve the original write error */ }
+            }
+            if (ownsTemp) {
+                try {
+                    fs.unlinkSync(tmp);
+                }
+                catch { /* preserve the original write error */ }
+            }
         }
     }
     async shutdown() {
-        if (this.syncTimer)
+        this.shuttingDown = true;
+        if (this.syncTimer) {
             clearInterval(this.syncTimer);
-        await this.sync();
-        this.initialized = false;
-        GlobalBrain.instance = null;
+            this.syncTimer = null;
+        }
+        try {
+            if (this.pendingOperations.length || this.syncInFlight)
+                await this.sync();
+            this.initialized = false;
+            if (GlobalBrain.instance === this)
+                GlobalBrain.instance = null;
+        }
+        finally {
+            this.shuttingDown = false;
+        }
     }
 }
 GlobalBrain.instance = null;