brainclaw 0.23.0 → 0.24.0

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import path from 'node:path';
 import { Command } from 'commander';
 import { runInit } from './commands/init.js';
 import { runSetup } from './commands/setup.js';
@@ -94,15 +95,26 @@ program
     .hook('preAction', (_thisCommand, actionCommand) => {
     const root = actionCommand.optsWithGlobals();
     initLogLevel({ verbose: root.verbose, debug: root.debug });
-    // Resolve effective cwd (--cwd > BRAINCLAW_PROJECT > active-project > process.cwd)
-    const effectiveCwd = resolveEffectiveCwd({ explicitCwd: root.cwd });
-    if (effectiveCwd !== process.cwd()) {
-        // Store resolved cwd so commands can read it via optsWithGlobals().cwd
-        actionCommand.setOptionValue('cwd', effectiveCwd);
+    // Skip effective cwd resolution for commands that create the store
+    const cmdName = actionCommand.name();
+    const skipResolution = cmdName === 'init' || cmdName === 'setup';
+    if (!skipResolution) {
+        // Resolve effective cwd (--cwd > BRAINCLAW_PROJECT > active-project > process.cwd)
+        const effectiveCwd = resolveEffectiveCwd({ explicitCwd: root.cwd });
+        if (effectiveCwd !== process.cwd()) {
+            // Change process.cwd() so all commands resolve the correct store
+            // without needing individual --cwd plumbing
+            process.chdir(effectiveCwd);
+            logger.info(`Resolved effective cwd: ${effectiveCwd}`);
+        }
+        const removed = cleanOrphanFiles(memoryDir());
+        if (removed > 0) {
+            logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir()}`);
+        }
     }
-    const removed = cleanOrphanFiles(memoryDir(effectiveCwd));
-    if (removed > 0) {
-        logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir(effectiveCwd)}`);
+    else if (root.cwd) {
+        // For init/setup, still respect explicit --cwd but nothing else
+        process.chdir(path.resolve(root.cwd));
     }
 });
 // --- init ---

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/commands/switch.js

@@ -106,8 +106,8 @@ function listProjects(wsRoot, json) {
             });
         }
     }
-    // Discover child projects
-    const children = scanNestedBrainclawProjects(wsRoot, 4);
+    // Discover child projects (depth 7 covers deep workspace layouts like /srv/dev/repos/global/applications/*/...)
+    const children = scanNestedBrainclawProjects(wsRoot, 7);
     for (const child of children) {
         const childPath = path.resolve(child.path);
         if (childPath === wsRoot)

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/architecture/project-refs.md

@@ -257,10 +257,29 @@ Likely persisted fields:
 
 This should stay clearly separate from canonical memory items such as decisions and constraints.
 
+## Current Implementation (v0.23.0)
+
+`brainclaw switch` provides the first layer of project navigation:
+
+- `brainclaw switch <name-or-path>` — set active project by name or relative path
+- `brainclaw switch --list` — discover available projects in workspace
+- `resolveProjectRef()` — shared resolver for CLI and MCP (name, path, registry lookup)
+- `resolveEffectiveCwd()` — single source of truth: `--cwd` > `BRAINCLAW_PROJECT` env > active-project > cwd
+- MCP tools automatically resolve the active project
+
+This covers the most common agent friction (cwd-dependent resolution) without requiring the full `project_ref` model yet.
+
 ## Migration Strategy
 
 The migration should be low-risk and incremental.
 
+Phase 0 (done):
+
+- `brainclaw switch` with name/path resolution
+- global `--cwd` option
+- `BRAINCLAW_PROJECT` environment variable
+- `resolveEffectiveCwd()` used by CLI and MCP
+
 Phase 1:
 
 - introduce `project_ref` in workspace discovery/registry

package/docs/cli.md

@@ -11,6 +11,53 @@ For capable coding agents, prefer MCP for dynamic runtime state:
 
 Use the CLI when a human operator is driving the workflow, when you are scripting setup or release operations, or when MCP is not the integration path.
 
+## Global Options
+
+All commands support these global options:
+
+| Option | Description |
+|---|---|
+| `--cwd <path>` | Override working directory for this invocation. Bypasses active project and env var resolution. |
+| `--verbose` | Show info-level log messages on stderr |
+| `--debug` | Show debug-level log messages on stderr |
+
+**Effective cwd resolution priority** (highest wins):
+
+1. `--cwd` flag
+2. `BRAINCLAW_PROJECT` environment variable (project name or path)
+3. Active project set via `brainclaw switch`
+4. `process.cwd()` (shell working directory)
+
+---
+
+## Multi-Project Navigation
+
+### `brainclaw switch [project]`
+
+Set the active project for subsequent CLI and MCP commands. This eliminates the need to `cd` into a subproject directory in multi-project workspaces. The active project is persisted per-workspace in `.brainclaw/active-project.json`.
+
+| Option | Description |
+|---|---|
+| `--list` | List all available projects in the workspace |
+| `--clear` | Clear the active project (revert to cwd default) |
+| `--json` | Output as JSON |
+
+The `<project>` argument accepts:
+- **Project name** — matched against the global registry and workspace config
+- **Relative path** — resolved from the workspace root (e.g. `apps/lodestar`)
+- **Absolute path** — used directly
+
+```bash
+brainclaw switch --list              # discover available projects
+brainclaw switch lodestar            # switch by project name
+brainclaw switch apps/lodestar       # switch by relative path
+brainclaw switch                     # show current active project
+brainclaw switch --clear             # clear, revert to cwd
+brainclaw --cwd /other/path status   # one-off override without switching
+```
+
+**MCP usage:** The active project also affects MCP tools. When `bclaw_get_context()` is called without an explicit path, it resolves context from the active project's store. Agents can also use `BRAINCLAW_PROJECT=<name>` environment variable for the same effect.
+
 ---
 
 ## Initialize and Inspect

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/concepts/workspace-bootstrapping.md

@@ -38,3 +38,44 @@ If shared memory is absent, that should not always be interpreted as "there is n
 It may simply mean the workspace has not been onboarded yet.
 
 This lets a single machine support multiple very different workspaces without forcing one static instruction layer to fit all of them equally well.
+
+## Multi-project workspaces
+
+A workspace may contain multiple brainclaw-initialized child projects (each with its own `.brainclaw/` store). In this topology:
+
+- The workspace root holds shared instructions, constraints, and coordination state
+- Each child project holds project-specific memory (decisions, traps, plans)
+- The store chain walks upward: child → repo → workspace → user
+
+### Working with child projects
+
+Agents and operators can address child projects without `cd`:
+
+```bash
+brainclaw switch apps/lodestar    # set active project
+brainclaw plan list               # now targets lodestar's store
+brainclaw switch --clear          # back to workspace root
+```
+
+Or use environment variables:
+
+```bash
+export BRAINCLAW_PROJECT=lodestar
+brainclaw context                 # resolves lodestar's store
+```
+
+Or one-off overrides:
+
+```bash
+brainclaw --cwd apps/lodestar plan list
+```
+
+### Project discovery
+
+`brainclaw switch --list` discovers child projects via:
+
+1. Global project registry
+2. Workspace config `projects.known`
+3. Filesystem scan for subdirectories containing `.brainclaw/`
+
+The bootstrap analysis (`analyzeRepository`) also detects brainclaw-native workspace complexity (child stores, folder strategy, known projects) alongside classic monorepo markers.

package/docs/integrations/agents.md

@@ -101,6 +101,41 @@ brainclaw adds all generated files to `.gitignore` automatically during init.
 
 Exception: use `--shared` if you intentionally want the main instruction file (e.g., CLAUDE.md) versioned for the whole team.
 
+## Multi-project workspaces
+
+When a workspace contains multiple brainclaw-initialized child projects, agents need to target the correct project store. There are three mechanisms (from most to least ergonomic):
+
+### 1. `brainclaw switch` (persistent)
+
+An operator or agent sets the active project once, and all subsequent commands resolve against it:
+
+```bash
+brainclaw switch apps/lodestar    # set active project
+brainclaw plan list               # targets lodestar
+bclaw_get_context()               # MCP also targets lodestar
+brainclaw switch --clear          # back to workspace root
+```
+
+### 2. `BRAINCLAW_PROJECT` environment variable
+
+Set in the shell or agent configuration. Useful for CI/CD or when the agent can control its environment:
+
+```bash
+export BRAINCLAW_PROJECT=lodestar
+```
+
+### 3. `--cwd` flag (one-off override)
+
+For a single command without changing the active project:
+
+```bash
+brainclaw --cwd apps/lodestar plan list
+```
+
+**Priority**: `--cwd` > `BRAINCLAW_PROJECT` > active project > shell cwd.
+
+**Discovery**: use `brainclaw switch --list` to see all available projects in the workspace.
+
 ## Session lifecycle
 
 ### Starting work

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.0",
+  "version": "0.24.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {