brainclaw 0.23.1 → 0.24.0

package/dist/commands/accept.js

@@ -1,4 +1,6 @@
-import { memoryExists, withStoreLock } from '../core/io.js';
+import { memoryExists } from '../core/io.js';
+import { mutate } from '../core/mutation-pipeline.js';
+import { rebuildProjectMd } from '../core/markdown.js';
 import { loadCandidate, archiveCandidate, resolveIdOrAlias } from '../core/candidates.js';
 import { loadState, persistState } from '../core/state.js';
 import { generateIdWithLabel, nowISO } from '../core/ids.js';
@@ -36,7 +38,7 @@ export function acceptCandidate(id, by, cwd, byId) {
     requireMinimumTrustLevel(actorIdentity, 'trusted');
     const actor = actorIdentity.agent_name;
     let promotedItemId = '';
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         const state = loadState(cwd);
         switch (candidate.type) {
             case 'constraint': {
@@ -136,6 +138,7 @@ export function acceptCandidate(id, by, cwd, byId) {
             after: { type: candidate.type, text: candidate.text },
             reason: 'trusted-agent',
         }, cwd);
+        rebuildProjectMd(loadState(cwd), cwd);
     });
     return {
         candidate_id: resolvedId,

package/dist/commands/claim.js

@@ -1,7 +1,8 @@
 import { buildOperationalIdentity } from '../core/identity.js';
-import { memoryExists, memoryPath, withStoreLock, writeFileAtomic } from '../core/io.js';
+import { memoryExists } from '../core/io.js';
+import { mutate } from '../core/mutation-pipeline.js';
 import { saveClaim, generateClaimId, listClaims } from '../core/claims.js';
-import { generateMarkdown } from '../core/markdown.js';
+import { rebuildProjectMd } from '../core/markdown.js';
 import { loadState, saveState } from '../core/state.js';
 import { nowISO } from '../core/ids.js';
 import { requireMinimumTrustLevel, requireRegisteredAgentIdentity } from '../core/agent-registry.js';
@@ -72,7 +73,7 @@ export function runClaim(description, options) {
         status: 'active',
         expires_at: options.ttl ? parseTtl(options.ttl) : undefined,
     };
-    withStoreLock(options.cwd, () => {
+    mutate({ cwd: options.cwd }, () => {
         if (plan) {
             if (!plan.assignee) {
                 plan.assignee = actor.agent;
@@ -84,7 +85,7 @@ export function runClaim(description, options) {
             saveState(state, options.cwd);
         }
         saveClaim(claim, options.cwd);
-        writeFileAtomic(memoryPath('project.md', options.cwd), generateMarkdown(plan ? state : loadState(options.cwd), options.cwd));
+        rebuildProjectMd(plan ? state : loadState(options.cwd), options.cwd);
     });
     const planInfo = claim.plan_id ? ` [plan ${claim.plan_id}]` : '';
     const ttlInfo = claim.expires_at ? ` (expires ${claim.expires_at.slice(0, 16).replace('T', ' ')})` : '';

package/dist/commands/instruction.js

@@ -1,8 +1,9 @@
 import { resolveAgentScope, resolveCurrentAgentName } from '../core/agent-registry.js';
 import { loadConfig } from '../core/config.js';
 import { createInstruction } from '../core/instructions.js';
-import { memoryExists, memoryPath, withStoreLock, writeFileAtomic } from '../core/io.js';
-import { generateMarkdown } from '../core/markdown.js';
+import { memoryExists } from '../core/io.js';
+import { mutate } from '../core/mutation-pipeline.js';
+import { rebuildProjectMd } from '../core/markdown.js';
 import { loadState } from '../core/state.js';
 import { scanText } from '../core/security.js';
 import { validateCliInput } from '../core/input-validation.js';
@@ -26,7 +27,7 @@ export function runInstruction(text, options = {}) {
         }
     }
     let entry;
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         entry = createInstruction(text, {
             layer,
             scope,
@@ -34,7 +35,7 @@ export function runInstruction(text, options = {}) {
             author: options.author ?? resolveCurrentAgentName(cwd),
             supersedes: options.supersedes,
         }, cwd);
-        writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(loadState(cwd)));
+        rebuildProjectMd(loadState(cwd), cwd);
     });
     if (!entry) {
         console.error('Error: failed to persist instruction.');

package/dist/commands/mcp.js

@@ -667,6 +667,11 @@ export class McpTaskRunner {
     onInternalError;
     active;
     queue = [];
+    _totalExecuted = 0;
+    _totalCancelled = 0;
+    _peakQueueDepth = 0;
+    _lastDurationMs = 0;
+    _lastWaitMs = 0;
     constructor(options) {
         this.executeTool = options.executeTool;
         this.onResult = options.onResult;
@@ -678,19 +683,35 @@ export class McpTaskRunner {
     get queuedRequestIds() {
         return this.queue.map((task) => task.requestId);
     }
+    /** Current single-writer queue metrics. */
+    get metrics() {
+        return {
+            totalExecuted: this._totalExecuted,
+            totalCancelled: this._totalCancelled,
+            queueDepth: this.queue.length,
+            peakQueueDepth: this._peakQueueDepth,
+            lastDurationMs: this._lastDurationMs,
+            lastWaitMs: this._lastWaitMs,
+        };
+    }
     enqueue(requestId, payload) {
         this.queue.push({
             requestId,
             payload,
             controller: new AbortController(),
             cancelled: false,
+            enqueuedAt: performance.now(),
         });
+        if (this.queue.length > this._peakQueueDepth) {
+            this._peakQueueDepth = this.queue.length;
+        }
         this.drain();
     }
     cancel(requestId) {
         if (this.active && this.active.requestId === requestId) {
             this.active.cancelled = true;
             this.active.controller.abort();
+            this._totalCancelled++;
             return 'active';
         }
         const index = this.queue.findIndex((task) => task.requestId === requestId);
@@ -698,6 +719,7 @@ export class McpTaskRunner {
             const [task] = this.queue.splice(index, 1);
             task.cancelled = true;
             task.controller.abort();
+            this._totalCancelled++;
             return 'queued';
         }
         return 'missing';
@@ -722,6 +744,7 @@ export class McpTaskRunner {
             return;
         }
         if (next.cancelled) {
+            this._totalCancelled++;
             this.drain();
             return;
         }
@@ -729,6 +752,8 @@ export class McpTaskRunner {
         void this.runTask(next);
     }
     async runTask(task) {
+        const startedAt = performance.now();
+        this._lastWaitMs = startedAt - task.enqueuedAt;
         try {
             const outcome = await this.executeTool(task.payload, task.controller.signal);
             if (!task.cancelled) {
@@ -741,6 +766,8 @@ export class McpTaskRunner {
             }
         }
         finally {
+            this._lastDurationMs = performance.now() - startedAt;
+            this._totalExecuted++;
             if (this.active === task) {
                 this.active = undefined;
             }

package/dist/commands/prune.js

@@ -1,6 +1,7 @@
 import { loadState, saveState } from '../core/state.js';
-import { memoryExists, memoryPath, withStoreLock, writeFileAtomic } from '../core/io.js';
-import { generateMarkdown } from '../core/markdown.js';
+import { memoryExists } from '../core/io.js';
+import { mutate } from '../core/mutation-pipeline.js';
+import { rebuildProjectMd } from '../core/markdown.js';
 import { deleteRuntimeNote, listRuntimeNotes } from '../core/runtime.js';
 import { expireStaleActiveClaims } from '../core/claims.js';
 export function runPrune(options = {}) {
@@ -13,7 +14,7 @@ export function runPrune(options = {}) {
     let prunedCount = 0;
     let expiredClaimsCount = 0;
     let expiredNotesCount = 0;
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         const state = loadState(cwd);
         const originalLength = state.active_constraints.length;
         for (const c of state.active_constraints) {
@@ -38,7 +39,7 @@ export function runPrune(options = {}) {
                 }
             }
         }
-        writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(loadState(cwd), cwd));
+        rebuildProjectMd(loadState(cwd), cwd);
     });
     if (options.expired) {
         console.log(`✔ Pruned ${prunedCount} expired constraints, ${expiredNotesCount} expired runtime notes, ${expiredClaimsCount} expired claims.`);

package/dist/commands/reflect.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import { memoryExists } from '../core/io.js';
+import { rebuildProjectMd } from '../core/markdown.js';
 import { loadConfig } from '../core/config.js';
 import { buildOperationalIdentity } from '../core/identity.js';
 import { loadState, persistState } from '../core/state.js';
@@ -265,6 +266,7 @@ function promoteCandidateToState(candidate, cwd) {
         }
     }
     persistState(state, cwd);
+    rebuildProjectMd(loadState(cwd), cwd);
     return promotedItemId;
 }
 export function mapEventTypeToCandidateType(eventType) {

package/dist/commands/release-claim.js

@@ -1,7 +1,7 @@
 import { memoryExists } from '../core/io.js';
-import { memoryPath, withStoreLock, writeFileAtomic } from '../core/io.js';
+import { mutate } from '../core/mutation-pipeline.js';
 import { loadClaim, listClaims, releaseClaim } from '../core/claims.js';
-import { generateMarkdown } from '../core/markdown.js';
+import { rebuildProjectMd } from '../core/markdown.js';
 import { loadState, saveState } from '../core/state.js';
 export function runReleaseClaim(id, options = {}) {
     if (!memoryExists(options.cwd)) {
@@ -10,7 +10,7 @@ export function runReleaseClaim(id, options = {}) {
     }
     try {
         let claim = loadClaim(id, options.cwd);
-        withStoreLock(options.cwd, () => {
+        mutate({ cwd: options.cwd }, () => {
             const existing = loadClaim(id, options.cwd);
             claim = releaseClaim(id, options.cwd);
             let state = loadState(options.cwd);
@@ -31,7 +31,7 @@ export function runReleaseClaim(id, options = {}) {
                     saveState(state, options.cwd);
                 }
             }
-            writeFileAtomic(memoryPath('project.md', options.cwd), generateMarkdown(state, options.cwd));
+            rebuildProjectMd(state, options.cwd);
         });
         console.log(`✔ Claim [${id}] released (was: ${claim.agent} → ${claim.scope})`);
     }

package/dist/commands/release-claims.js

@@ -1,7 +1,8 @@
 import { execSync } from 'node:child_process';
-import { memoryExists, memoryPath, withStoreLock, writeFileAtomic } from '../core/io.js';
+import { memoryExists } from '../core/io.js';
+import { mutate } from '../core/mutation-pipeline.js';
 import { listClaims, releaseClaim } from '../core/claims.js';
-import { generateMarkdown } from '../core/markdown.js';
+import { rebuildProjectMd } from '../core/markdown.js';
 import { loadState, saveState } from '../core/state.js';
 function normPath(p) {
     return p.replace(/\\/g, '/').replace(/^\.\//, '');
@@ -36,7 +37,7 @@ export function runReleaseClaims(options = {}) {
     if (toRelease.length === 0)
         process.exit(0);
     let released = 0;
-    withStoreLock(options.cwd, () => {
+    mutate({ cwd: options.cwd }, () => {
         let state = loadState(options.cwd);
         for (const claim of toRelease) {
             try {
@@ -59,7 +60,7 @@ export function runReleaseClaims(options = {}) {
             catch { /* skip individual failures */ }
         }
         state = loadState(options.cwd);
-        writeFileAtomic(memoryPath('project.md', options.cwd), generateMarkdown(state, options.cwd));
+        rebuildProjectMd(state, options.cwd);
     });
     if (released > 0) {
         console.log(`brainclaw: ${released} claim(s) auto-released after merge.`);

package/dist/core/ai-surface-tasks.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { JsonStore } from './json-store.js';
-import { resolveEntityDir, withStoreLock } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { AiSurfaceTaskRequestSchema } from './schema.js';
 function surfaceTasksDir(cwd, mode = 'read') {
     return resolveEntityDir('surface-tasks', cwd ?? process.cwd(), mode);
@@ -20,7 +21,7 @@ export function ensureAiSurfaceTasksDir(cwd) {
     }
 }
 export function saveAiSurfaceTask(task, cwd) {
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         ensureAiSurfaceTasksDir(cwd);
         const writeStore = new JsonStore({
             dirPath: surfaceTasksDir(cwd, 'write'),

package/dist/core/audit.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { memoryDir, withStoreLock } from './io.js';
+import { memoryDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { nowISO } from './ids.js';
 import { logger } from './logger.js';
 import { appendEvent } from './event-log.js';
@@ -23,7 +24,7 @@ function auditLogPath(cwd) {
 }
 export function appendAuditEntry(entry, cwd) {
     try {
-        withStoreLock(cwd, () => {
+        mutate({ cwd }, () => {
             const full = {
                 timestamp: nowISO(),
                 actor: entry.actor,

package/dist/core/bootstrap.js

@@ -4,7 +4,8 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { JsonStore } from './json-store.js';
 import { generateId, generateIdWithLabel, nowISO } from './ids.js';
-import { memoryPath, resolveEntityDir, withStoreLock, writeFileAtomic } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { BootstrapApplicationReceiptSchema, BootstrapInterviewAnswerSchema, BootstrapInterviewPlanSchema, BootstrapInterviewQuestionSchema, BootstrapImportPlanDocumentSchema, BootstrapProfileDocumentSchema, BootstrapSuggestionDocumentSchema, MemorySeedDocumentSchema, } from './schema.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { analyzeRepository } from './repo-analysis.js';
@@ -13,7 +14,7 @@ import { buildAgentToolingContext } from './agent-context.js';
 import { createInstruction, loadInstructions, saveInstruction } from './instructions.js';
 import { resolveCurrentAgentName } from './agent-registry.js';
 import { loadState, persistState } from './state.js';
-import { generateMarkdown } from './markdown.js';
+import { rebuildProjectMd } from './markdown.js';
 const README_CANDIDATES = ['README.md', 'README', 'README.txt', 'README.mdx'];
 const DOC_HINTS = ['docs', 'doc'];
 const MAKEFILE_NAME = 'Makefile';
@@ -1241,7 +1242,7 @@ export function applyBootstrapImport(options = {}) {
     const managedArtifacts = [];
     let createdCount = 0;
     let skippedCount = 0;
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         const state = loadState(cwd);
         const activeInstructionKeys = new Set(loadInstructions(cwd)
             .filter((entry) => entry.active)
@@ -1380,7 +1381,7 @@ export function applyBootstrapImport(options = {}) {
             persistState(state, cwd, { writeProjectMarkdown: false });
         }
         if (createdCount > 0) {
-            writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(loadState(cwd), cwd));
+            rebuildProjectMd(loadState(cwd), cwd);
         }
     });
     const receipt = BootstrapApplicationReceiptSchema.parse({
@@ -1414,7 +1415,7 @@ export function uninstallBootstrapImport(cwd) {
     let deactivatedCount = 0;
     let deletedCount = 0;
     let skippedCount = 0;
-    withStoreLock(resolvedCwd, () => {
+    mutate({ cwd: resolvedCwd }, () => {
         const state = loadState(resolvedCwd);
         const instructions = loadInstructions(resolvedCwd);
         let stateChanged = false;
@@ -1459,7 +1460,7 @@ export function uninstallBootstrapImport(cwd) {
             persistState(state, resolvedCwd, { writeProjectMarkdown: false });
         }
         if (deactivatedCount > 0 || deletedCount > 0) {
-            writeFileAtomic(memoryPath('project.md', resolvedCwd), generateMarkdown(loadState(resolvedCwd), resolvedCwd));
+            rebuildProjectMd(loadState(resolvedCwd), resolvedCwd);
         }
     });
     const nextReceipt = BootstrapApplicationReceiptSchema.parse({

package/dist/core/candidates.js

@@ -2,7 +2,8 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { CandidateSchema } from './schema.js';
-import { resolveEntityDir, withStoreLock } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { nowISO, getNextShortLabel } from './ids.js';
 import { JsonStore } from './json-store.js';
 function inboxDir(cwd, mode = 'read') {
@@ -35,7 +36,7 @@ function candidateStore(dest = 'pending', cwd) {
     });
 }
 export function saveCandidate(candidate, cwd) {
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         ensureInboxDirs(cwd);
         candidateStore('pending', cwd).save(CandidateSchema.parse(candidate));
     });
@@ -51,7 +52,7 @@ export function listCandidates(status, cwd) {
     return status ? candidates.filter((candidate) => candidate.status === status) : candidates;
 }
 export function archiveCandidate(candidate, dest, cwd) {
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         ensureInboxDirs(cwd);
         candidateStore(dest, cwd).save(CandidateSchema.parse(candidate));
         candidateStore('pending', cwd).delete(candidate.id);

package/dist/core/claims.js

@@ -1,7 +1,8 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import { ClaimSchema } from './schema.js';
-import { resolveEntityDir, withStoreLock } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { nowISO } from './ids.js';
 import { JsonStore } from './json-store.js';
 function claimsDir(cwd, mode = 'read') {
@@ -22,7 +23,7 @@ function claimStore(cwd) {
     });
 }
 export function saveClaim(claim, cwd) {
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         ensureClaimsDir(cwd);
         const writeStore = new JsonStore({
             dirPath: claimsDir(cwd, 'write'),

package/dist/core/instructions.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
-import { resolveEntityDir, withStoreLock } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { generateId } from './ids.js';
 import { InstructionEntrySchema } from './schema.js';
 import { JsonStore } from './json-store.js';
@@ -19,7 +20,7 @@ export function loadInstructions(cwd) {
     return instructionStore(cwd).list();
 }
 export function saveInstruction(entry, cwd) {
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         instructionStore(cwd, 'write').save(InstructionEntrySchema.parse(entry));
     });
 }

package/dist/core/io.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { withLock, cleanStaleLocks } from './lock.js';
+export { mutate } from './mutation-pipeline.js';
 export const MEMORY_DIR = '.brainclaw';
 const STORE_LOCK_BASENAME = '.store-mutation';
 const RETRYABLE_RENAME_ERROR_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);

package/dist/core/lock.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
-const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_TIMEOUT_MS = 5000;
 const LOCK_RETRY_INTERVAL_MS = 50;
-const LOCK_EXPIRY_MS = 5000;
+const LOCK_EXPIRY_MS = 10000;
 const heldLocks = new Map();
 function lockFilePath(targetPath) {
     return targetPath + '.lock';

package/dist/core/markdown.js

@@ -1,6 +1,8 @@
 import { listClaims } from './claims.js';
 import { loadInstructions } from './instructions.js';
+import { memoryPath, writeFileAtomic } from './io.js';
 import { isTrapActive } from './traps.js';
+import { logger } from './logger.js';
 export function generateMarkdown(state, cwd) {
     const lines = ['# Project Memory', ''];
     const instructions = loadInstructions(cwd).filter((entry) => entry.active);
@@ -117,4 +119,20 @@ export function generateMarkdown(state, cwd) {
     lines.push('');
     return lines.join('\n');
 }
+/**
+ * Rebuild `.brainclaw/project.md` from canonical state.
+ *
+ * This is a **derived view** — it can always be regenerated from the
+ * canonical JSON files. Call this once at the end of a top-level mutation,
+ * not inside every nested helper. Best-effort: failures are logged but
+ * never propagate to the caller.
+ */
+export function rebuildProjectMd(state, cwd) {
+    try {
+        writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(state, cwd));
+    }
+    catch (err) {
+        logger.debug('Failed to rebuild project.md:', err);
+    }
+}
 //# sourceMappingURL=markdown.js.map

package/dist/core/mutation-pipeline.js

@@ -0,0 +1,39 @@
+/**
+ * Mutation pipeline — single entry point for all .brainclaw/ store mutations.
+ *
+ * Every write operation against the store MUST go through `mutate()`.
+ * This ensures:
+ *   1. Store-wide serialization via the advisory file lock
+ *   2. Consistent error handling and timeout behavior
+ *   3. Observable mutation metadata for debugging and auditing
+ *
+ * @module
+ */
+import { ensureMemoryDir, storeLockPath } from './io.js';
+import { withLock } from './lock.js';
+import { logger } from './logger.js';
+/** Default timeout for store-wide lock acquisition (ms). */
+export const STORE_LOCK_TIMEOUT_MS = 5_000;
+export function mutate(optionsOrFn, maybeFn) {
+    const options = typeof optionsOrFn === 'function' ? {} : optionsOrFn;
+    const fn = typeof optionsOrFn === 'function' ? optionsOrFn : maybeFn;
+    const cwd = options.cwd ?? process.cwd();
+    const timeoutMs = options.timeoutMs ?? STORE_LOCK_TIMEOUT_MS;
+    ensureMemoryDir(cwd, options.preferredDirName);
+    const lockTarget = storeLockPath(cwd, options.preferredDirName);
+    const start = performance.now();
+    try {
+        const value = withLock(lockTarget, () => fn(cwd), timeoutMs);
+        const durationMs = performance.now() - start;
+        if (durationMs > 1_000) {
+            logger.debug(`Slow mutation: ${durationMs.toFixed(0)}ms (cwd=${cwd})`);
+        }
+        return value;
+    }
+    catch (err) {
+        const durationMs = performance.now() - start;
+        logger.debug(`Mutation failed after ${durationMs.toFixed(0)}ms: ${err instanceof Error ? err.message : String(err)}`);
+        throw err;
+    }
+}
+//# sourceMappingURL=mutation-pipeline.js.map

package/dist/core/runtime.js

@@ -2,7 +2,8 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveCurrentHostId, sanitizeHostId } from './host.js';
-import { resolveEntityDir, withStoreLock } from './io.js';
+import { resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { RuntimeNoteSchema } from './schema.js';
 import { commitMemoryChange } from './memory-git.js';
@@ -40,7 +41,7 @@ export function saveRuntimeNote(note, cwd) {
     const persistedNote = visibility === 'shared'
         ? { ...note, visibility, host_id: hostId }
         : { ...note, visibility, host_id: hostId };
-    withStoreLock(cwd, () => {
+    mutate({ cwd }, () => {
         ensureRuntimeDir(note.agent, cwd, visibility, hostId);
         const filepath = visibility === 'shared'
             ? path.join(sharedAgentDir(note.agent, cwd, 'write'), `${note.id}.json`)
@@ -58,7 +59,7 @@ export function runtimeNotePath(note, cwd) {
         : path.join(hostAgentDir(visibility, hostId, note.agent, cwd), `${note.id}.json`);
 }
 export function deleteRuntimeNote(note, cwd) {
-    return withStoreLock(cwd, () => {
+    return mutate({ cwd }, () => {
         const filepath = runtimeNotePath(note, cwd);
         if (!fs.existsSync(filepath)) {
             return false;

package/dist/core/state.js

@@ -1,11 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ConstraintSchema, DecisionSchema, TrapSchema, HandoffSchema, PlanItemSchema } from './schema.js';
-import { ensureMemoryDir, memoryPath, resolveEntityDir, withStoreLock, writeFileAtomic } from './io.js';
+import { ensureMemoryDir, resolveEntityDir } from './io.js';
+import { mutate } from './mutation-pipeline.js';
 import { commitMemoryChange } from './memory-git.js';
 import { appendEvent } from './event-log.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
-import { generateMarkdown } from './markdown.js';
+import { rebuildProjectMd } from './markdown.js';
 export function emptyState() {
     return {
         version: 1,
@@ -83,10 +84,10 @@ function writeStateDirectories(state, cwd) {
 }
 export function persistState(state, cwd, options = {}) {
     const effectiveCwd = cwd ?? process.cwd();
-    withStoreLock(effectiveCwd, () => {
+    mutate({ cwd: effectiveCwd }, () => {
         writeStateDirectories(state, effectiveCwd);
         if (options.writeProjectMarkdown ?? true) {
-            writeFileAtomic(memoryPath('project.md', effectiveCwd), generateMarkdown(state, effectiveCwd));
+            rebuildProjectMd(state, effectiveCwd);
         }
         appendEvent({
             action: options.eventAction ?? 'update',

package/docs/concepts/memory.md

@@ -32,7 +32,7 @@ Examples: constraints, decisions, traps, completed plans, handoffs.
 
 Shared traps now have a lifecycle too: `active`, `resolved`, or `expired`. Active views such as generated context, status, and `project.md` prioritize only active traps so old machine-setup issues stop polluting the current working set, while the canonical memory still keeps resolved traps for audit and search.
 
-These live in `.brainclaw/store.json` and are shared via Git (or by reading the same file).
+These live as individual JSON files under `.brainclaw/memory/` (constraints, decisions, traps, instructions) and `.brainclaw/coordination/` (plans, claims, handoffs). They are versioned in `.brainclaw/.git` and shared via Git.
 
 ### Runtime memory
 Operational observations that may be short-lived, host-specific, or private.
@@ -59,8 +59,9 @@ brainclaw makes this context visible and versionable.
 
 brainclaw keeps:
 
-- canonical structured JSON as the source of truth (`.brainclaw/store.json`)
-- a generated readable view in each agent's native format (`CLAUDE.md`, `.cursor/rules/brainclaw.md`, etc.)
+- canonical structured JSON as the source of truth (individual files under `.brainclaw/memory/` and `.brainclaw/coordination/`)
+- a derived readable view (`project.md`) regenerated best-effort from canonical state
+- native agent instruction files (`CLAUDE.md`, `.cursor/rules/brainclaw.md`, etc.) generated via `brainclaw export`
 
 This balances machine reliability with human readability.
 

package/docs/integrations/claude-code.md

@@ -14,7 +14,7 @@ brainclaw export --format claude-md --write
 
 - use MCP as the default runtime path for dynamic retrieval and writes
 - keep `CLAUDE.md` lightweight and behavioral: it should tell Claude Code when to call Brainclaw, not carry all mutable workspace state
-- use `.brainclaw/project.md` as a readable fallback baseline, not as the primary live source of truth
+- use `.brainclaw/project.md` as a readable fallback (it is a derived view, regenerated best-effort — run `brainclaw rebuild` if stale)
 - use hooks or workflow checks when a stronger reminder is needed
 
 ## Key idea

package/docs/integrations/codex.md

@@ -14,7 +14,7 @@ brainclaw export --format agents-md --write
 
 - use MCP as the default runtime path for fresh context, plans, claims, and runtime notes
 - keep `AGENTS.md` lightweight and behavioral: it should remind Codex how to use Brainclaw, not duplicate live state
-- use `.brainclaw/project.md` only as a readable fallback when MCP is unavailable or when a human wants a simple snapshot
+- use `.brainclaw/project.md` only as a readable fallback (derived view, regenerated best-effort — run `brainclaw rebuild` if stale)
 - encourage plans, claims, and handoffs during multi-step work
 
 ## Good role for brainclaw here

package/docs/integrations/copilot.md

@@ -14,7 +14,7 @@ brainclaw export --format copilot-instructions --write
 
 - use MCP whenever the Copilot surface supports it for fresh context and coordination views
 - keep `.github/copilot-instructions.md` lightweight and behavioral
-- use `.brainclaw/project.md` as readable fallback, not as the only live context source
+- use `.brainclaw/project.md` as readable fallback (derived view, regenerated best-effort — may need `brainclaw rebuild` if stale)
 - use plans, claims, and handoffs to reduce ambiguity across sessions
 
 ## Why this matters

package/docs/integrations/cursor.md

@@ -14,7 +14,7 @@ brainclaw export --format cursor-rules --write
 
 - use MCP as the default dynamic path for context, board state, plans, and claims
 - let the generated `.cursor/rules/brainclaw.md` tell Cursor when to consult Brainclaw and how to stay inside the workflow
-- use `.brainclaw/project.md` only as readable fallback shared state
+- use `.brainclaw/project.md` only as readable fallback (derived view, may be stale — run `brainclaw rebuild` to refresh)
 - rely on claims and plans when multiple agents or humans are active in the same repo
 
 ## Key point

package/docs/integrations/mcp.md

@@ -58,7 +58,7 @@ This keeps session continuity inside Brainclaw instead of pushing the agent back
 | Runtime writes with session continuity | MCP |
 | Local behavioral reminders inside the agent UI | native agent files |
 | Human inspection or scripting | CLI |
-| Simple readable fallback | `.brainclaw/project.md` |
+| Simple readable fallback | `.brainclaw/project.md` (derived view, may be stale) |
 
 ## Starting The Server
 
@@ -87,16 +87,26 @@ Interview answers are keyed by question ID and may contain:
 - `response_boolean`
 - optional explicit `suggestions` when the agent wants to confirm exact canonical memory items
 
+## Mutation Safety
+
+The MCP server serializes all mutations through a single-writer queue (`McpTaskRunner`). When an agent calls a write tool (e.g. `bclaw_claim`, `bclaw_write_note`, `bclaw_create_plan`), the request is enqueued and executed one at a time. This guarantees:
+
+- no concurrent writes from the same MCP connection
+- no partial state from interleaved mutations
+- deterministic ordering of operations
+
+A secondary file-based lock (`mutate()`) provides cross-process safety in case CLI commands run alongside MCP. But for agents, MCP is the safe path by design — no extra precautions needed.
+
 ## Important Rule
 
-If the agent has MCP available, do not treat the CLI as the primary runtime interface.
+If the agent has MCP available, do not treat the CLI as the primary runtime interface. All agent mutations MUST go through MCP tools.
 
 The CLI remains valuable for:
 
-- setup
+- setup and initialization
 - bootstrap by a human operator
-- scripting
+- scripting and automation
 - release and packaging
 - debugging and fallback access
 
-But for capable agents, MCP should be the first-class path for dynamic state.
+But for capable agents, MCP is the first-class path for both reads and writes.

package/docs/integrations/overview.md

@@ -87,9 +87,9 @@ The developer can dial back individual surfaces if needed, but the default is fu
 
 ## Sequential collaboration, not parallel editing
 
-For now, brainclaw works best when one agent works at a time in a given checkout. The next agent can pick up where the previous one stopped, using shared plans, claims, handoffs, and memory.
+brainclaw's store mutations are serialized (MCP single-writer queue + file-based lock), so memory writes are safe even under contention. However, running multiple agents in parallel on the same checkout can still cause Git conflicts and confusing file-level state.
 
-Running multiple agents in parallel on the same checkout will create conflicts. Git worktree isolation per agent is planned but not yet available.
+For now, brainclaw works best when one agent works at a time in a given checkout. The next agent can pick up where the previous one stopped, using shared plans, claims, handoffs, and memory. Git worktree isolation per agent is planned but not yet available.
 
 ## Next reads
 

package/docs/quickstart.md

@@ -74,7 +74,9 @@ This keeps non-code work visible to the project without overloading the active c
 
 ## Important: one agent at a time
 
-For now, use brainclaw for sequential collaboration. One agent works, finishes, and the next one picks up from shared context. Running multiple agents in parallel on the same checkout will cause conflicts.
+brainclaw serializes all store mutations (file lock + MCP single-writer queue), so writes are safe. But running multiple agents in parallel on the same checkout can still cause Git conflicts and confusing state transitions.
+
+Use brainclaw for sequential collaboration: one agent works, finishes, and the next one picks up from shared context. Use `bclaw_session_end` to hand off cleanly.
 
 ## Next reads
 

package/docs/storage.md

@@ -6,37 +6,62 @@ brainclaw is local-first and workspace-centric.
 
 ```text
 .brainclaw/
-  project.md        ← Human & agent readable view (auto-generated)
-  config.yaml       ← Project configuration
-  instructions/     ← Layered shared instructions
-  plans/            ← Shared plan items
-  constraints/      ← Canonical constraint entries
-  decisions/        ← Canonical decision entries
-  traps/            ← Canonical trap entries
-  handoffs/         ← Canonical handoff entries
+  config.yaml                    ← Project configuration
+  project.md                     ← Derived readable view (best-effort, regenerable)
+  events.jsonl                   ← Append-only event log (agent notifications)
+  audit.log                      ← Append-only audit trail (before/after snapshots)
+  memory/
+    constraints/                 ← Canonical constraint entries (one JSON per entity)
+    decisions/                   ← Canonical decision entries
+    traps/                       ← Canonical trap entries
+    instructions/                ← Layered shared instructions
+  coordination/
+    plans/                       ← Shared plan items
+    claims/                      ← Active scope claims
+    handoffs/                    ← Handoff records
+    sessions/                    ← Session state
+    runtime/                     ← Runtime notes (shared, machine, private)
+    inbox/                       ← Candidate review queue
+  discovery/
+    bootstrap/                   ← Bootstrap profiles and seeds
+  agents/                        ← Agent registration and identity
 ```
 
 ## Design principles
 
 ### Canonical state is split
-Each entity is stored as its own JSON file.
+Each entity is stored as its own JSON file (e.g. `memory/decisions/dec_abc123.json`).
 
 Benefits:
 
-- readable diffs
+- readable diffs in `.brainclaw/.git`
 - easier merges
-- clear provenance
-- straightforward automation
+- clear provenance per entity
+- O(1) lookup by ID (direct file access)
 - no giant monolithic memory blob
+- isolated corruption (one bad file does not affect others)
 
-### Human-readable view is generated
-`project.md` is regenerated from canonical state on every write.
+### Derived views are best-effort
+`project.md` is a **derived view** regenerated from canonical state via `rebuildProjectMd()`. It is not a write target — it can always be rebuilt from the JSON files using `brainclaw rebuild`.
 
-Benefits:
+Failures to regenerate `project.md` are logged but never block mutations. If it gets stale, `brainclaw doctor` detects the drift.
+
+### All mutations go through a single pipeline
+Every write to `.brainclaw/` is serialized through `mutate()` (`src/core/mutation-pipeline.ts`):
+
+1. **Store-wide lock** — advisory file lock at `.brainclaw/.store-mutation` (5s timeout, 10s expiry)
+2. **Reentrant** — nested mutations within the same process are safe
+3. **Atomic writes** — individual files use temp-file + rename pattern
+4. **Git versioned** — `.brainclaw/.git` tracks all changes for rollback
+
+For agents using MCP (the recommended path), mutations are additionally serialized by the MCP server's `McpTaskRunner` — a FIFO queue that runs one task at a time. This provides two layers of write safety:
+
+| Layer | Scope | Mechanism |
+|---|---|---|
+| **McpTaskRunner** | Single MCP server process | FIFO queue, one active Worker thread |
+| **mutate() file lock** | Cross-process (CLI + MCP) | Advisory `.store-mutation` lock file |
 
-- agents can read a simple file
-- humans get an inspectable summary
-- the source of truth remains structured
+Agents should always use MCP tools for mutations. The CLI is for human operators, scripting, and fallback workflows.
 
 ### Topology can vary
 
@@ -57,21 +82,23 @@ Depending on configuration, storage may be:
 - handoffs
 - plans
 
-## What may stay more operational
+## What stays operational
 
 - machine-local runtime notes
 - private notes
-- short-lived observations
+- short-lived observations (with optional TTL)
 - reflective candidates awaiting review
+- event log and audit trail
 
 ## Why this model matters
 
 The storage model is part of the product value:
 
-- local-first
-- inspectable
-- Git-friendly
-- reversible
+- local-first — no cloud dependency
+- inspectable — plain text + JSON
+- Git-friendly — entity-per-file, readable diffs
+- reversible — `.brainclaw/.git` history + rollback
+- mutation-safe — serialized writes, atomic file operations
 - suitable for both humans and agents
 
 ## Related pages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {