brainclaw 0.19.5 → 0.19.7

package/dist/core/candidates.js

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

package/dist/core/claims.js

@@ -1,7 +1,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import { ClaimSchema } from './schema.js';
-import { resolveEntityDir } from './io.js';
+import { resolveEntityDir, withStoreLock } from './io.js';
 import { nowISO } from './ids.js';
 import { JsonStore } from './json-store.js';
 function claimsDir(cwd, mode = 'read') {
@@ -22,14 +22,16 @@ function claimStore(cwd) {
     });
 }
 export function saveClaim(claim, cwd) {
-    ensureClaimsDir(cwd);
-    const writeStore = new JsonStore({
-        dirPath: claimsDir(cwd, 'write'),
-        documentType: 'claim',
-        getId: (c) => c.id,
-        sort: (a, b) => a.created_at.localeCompare(b.created_at),
+    withStoreLock(cwd, () => {
+        ensureClaimsDir(cwd);
+        const writeStore = new JsonStore({
+            dirPath: claimsDir(cwd, 'write'),
+            documentType: 'claim',
+            getId: (c) => c.id,
+            sort: (a, b) => a.created_at.localeCompare(b.created_at),
+        });
+        writeStore.save(ClaimSchema.parse(claim));
     });
-    writeStore.save(ClaimSchema.parse(claim));
 }
 export function loadClaim(id, cwd) {
     return claimStore(cwd).load(id);

package/dist/core/coordination.js

@@ -5,7 +5,7 @@ import { listClaims } from './claims.js';
 import { inferProjectFromTarget, loadInstructions, resolveInstructions } from './instructions.js';
 import { buildReputationSummary, findAgentReputationSummary } from './reputation.js';
 import { listRuntimeNotes } from './runtime.js';
-import { loadState, saveState } from './state.js';
+import { loadState, persistState } from './state.js';
 export function buildCoordinationSnapshot(options = {}) {
     const config = loadConfig(options.cwd);
     const state = loadState(options.cwd);
@@ -58,7 +58,7 @@ export function buildCoordinationSnapshot(options = {}) {
             }
         }
         if (changed)
-            saveState(state, options.cwd);
+            persistState(state, options.cwd);
     }
     return {
         project_id: config.project_id,

package/dist/core/instructions.js

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

package/dist/core/io.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { withLock, cleanStaleLocks } from './lock.js';
 export const MEMORY_DIR = '.brainclaw';
+const STORE_LOCK_BASENAME = '.store-mutation';
 const RETRYABLE_RENAME_ERROR_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
 const DEFAULT_RENAME_RETRY_ATTEMPTS = 6;
 const DEFAULT_RENAME_RETRY_DELAY_MS = 25;
@@ -72,6 +73,9 @@ export function memoryDir(cwd = process.cwd(), preferredDirName) {
 export function memoryPath(filename, cwd, preferredDirName) {
     return path.join(memoryDir(cwd, preferredDirName), filename);
 }
+export function storeLockPath(cwd, preferredDirName) {
+    return memoryPath(STORE_LOCK_BASENAME, cwd, preferredDirName);
+}
 export function memoryExists(cwd, preferredDirName) {
     return fs.existsSync(memoryDir(cwd, preferredDirName));
 }
@@ -95,6 +99,10 @@ export function ensureMemoryDir(cwd, preferredDirName) {
         }
     }
 }
+export function withStoreLock(cwd = process.cwd(), fn, preferredDirName) {
+    ensureMemoryDir(cwd, preferredDirName);
+    return withLock(storeLockPath(cwd, preferredDirName), fn);
+}
 /** Check if a path is a file, or a directory with at least one entry. */
 function hasContent(p) {
     try {

package/dist/core/lock.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 const DEFAULT_TIMEOUT_MS = 2000;
 const LOCK_RETRY_INTERVAL_MS = 50;
 const LOCK_EXPIRY_MS = 5000;
+const heldLocks = new Map();
 function lockFilePath(targetPath) {
     return targetPath + '.lock';
 }
@@ -59,22 +60,37 @@ function tryBreakLock(lockPath) {
 }
 export function acquireLock(targetPath, timeoutMs = DEFAULT_TIMEOUT_MS) {
     const lockPath = lockFilePath(targetPath);
+    const heldCount = heldLocks.get(lockPath);
+    if (heldCount) {
+        heldLocks.set(lockPath, heldCount + 1);
+        return true;
+    }
     const deadline = Date.now() + timeoutMs;
     const dir = path.dirname(lockPath);
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
     while (Date.now() < deadline) {
-        if (tryCreateLock(lockPath))
+        if (tryCreateLock(lockPath)) {
+            heldLocks.set(lockPath, 1);
             return true;
-        if (tryBreakLock(lockPath))
+        }
+        if (tryBreakLock(lockPath)) {
+            heldLocks.set(lockPath, 1);
             return true;
+        }
         syncSleep(Math.min(LOCK_RETRY_INTERVAL_MS, deadline - Date.now()));
     }
     return false;
 }
 export function releaseLock(targetPath) {
     const lockPath = lockFilePath(targetPath);
+    const heldCount = heldLocks.get(lockPath);
+    if (heldCount && heldCount > 1) {
+        heldLocks.set(lockPath, heldCount - 1);
+        return;
+    }
+    heldLocks.delete(lockPath);
     try {
         if (fs.existsSync(lockPath)) {
             fs.unlinkSync(lockPath);

package/dist/core/runtime.js

@@ -2,7 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveCurrentHostId, sanitizeHostId } from './host.js';
-import { resolveEntityDir } from './io.js';
+import { resolveEntityDir, withStoreLock } from './io.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { RuntimeNoteSchema } from './schema.js';
 import { commitMemoryChange } from './memory-git.js';
@@ -40,13 +40,15 @@ export function saveRuntimeNote(note, cwd) {
     const persistedNote = visibility === 'shared'
         ? { ...note, visibility, host_id: hostId }
         : { ...note, visibility, host_id: hostId };
-    ensureRuntimeDir(note.agent, cwd, visibility, hostId);
-    const filepath = visibility === 'shared'
-        ? path.join(sharedAgentDir(note.agent, cwd, 'write'), `${note.id}.json`)
-        : path.join(hostAgentDir(visibility, hostId, note.agent, cwd, 'write'), `${note.id}.json`);
-    saveVersionedJsonFile('runtime_note', filepath, RuntimeNoteSchema.parse(persistedNote));
-    appendEvent({ action: 'create', item_type: 'runtime_note', item_id: note.id, agent: note.agent, agent_id: note.agent_id }, cwd);
-    commitMemoryChange(`runtime note: ${note.note_type ?? 'note'} (${note.agent})`, cwd);
+    withStoreLock(cwd, () => {
+        ensureRuntimeDir(note.agent, cwd, visibility, hostId);
+        const filepath = visibility === 'shared'
+            ? path.join(sharedAgentDir(note.agent, cwd, 'write'), `${note.id}.json`)
+            : path.join(hostAgentDir(visibility, hostId, note.agent, cwd, 'write'), `${note.id}.json`);
+        saveVersionedJsonFile('runtime_note', filepath, RuntimeNoteSchema.parse(persistedNote));
+        appendEvent({ action: 'create', item_type: 'runtime_note', item_id: note.id, agent: note.agent, agent_id: note.agent_id }, cwd);
+        commitMemoryChange(`runtime note: ${note.note_type ?? 'note'} (${note.agent})`, cwd);
+    });
 }
 export function runtimeNotePath(note, cwd) {
     const visibility = note.visibility ?? 'shared';
@@ -56,12 +58,14 @@ export function runtimeNotePath(note, cwd) {
         : path.join(hostAgentDir(visibility, hostId, note.agent, cwd), `${note.id}.json`);
 }
 export function deleteRuntimeNote(note, cwd) {
-    const filepath = runtimeNotePath(note, cwd);
-    if (!fs.existsSync(filepath)) {
-        return false;
-    }
-    fs.unlinkSync(filepath);
-    return true;
+    return withStoreLock(cwd, () => {
+        const filepath = runtimeNotePath(note, cwd);
+        if (!fs.existsSync(filepath)) {
+            return false;
+        }
+        fs.unlinkSync(filepath);
+        return true;
+    });
 }
 function readAgentNotes(dir, agent) {
     if (!fs.existsSync(dir))

package/dist/core/state.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ConstraintSchema, DecisionSchema, TrapSchema, HandoffSchema, PlanItemSchema } from './schema.js';
-import { ensureMemoryDir, resolveEntityDir } from './io.js';
+import { ensureMemoryDir, memoryPath, resolveEntityDir, withStoreLock, writeFileAtomic } from './io.js';
 import { commitMemoryChange } from './memory-git.js';
 import { appendEvent } from './event-log.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
+import { generateMarkdown } from './markdown.js';
 export function emptyState() {
     return {
         version: 1,
@@ -69,15 +70,31 @@ function syncDirectory(dirPath, items, documentType) {
     }
 }
 export function saveState(state, cwd) {
+    persistState(state, cwd, { writeProjectMarkdown: false });
+}
+function writeStateDirectories(state, cwd) {
     ensureMemoryDir(cwd);
     const effectiveCwd = cwd ?? process.cwd();
-    // Write to entity-aligned directories
     syncDirectory(resolveEntityDir('constraints', effectiveCwd, 'write'), state.active_constraints, 'constraint');
     syncDirectory(resolveEntityDir('decisions', effectiveCwd, 'write'), state.recent_decisions, 'decision');
     syncDirectory(resolveEntityDir('traps', effectiveCwd, 'write'), state.known_traps, 'trap');
     syncDirectory(resolveEntityDir('handoffs', effectiveCwd, 'write'), state.open_handoffs, 'handoff');
     syncDirectory(resolveEntityDir('plans', effectiveCwd, 'write'), state.plan_items, 'plan');
-    appendEvent({ action: 'update', item_type: 'state', agent: 'system' }, cwd);
-    commitMemoryChange('state update', cwd);
+}
+export function persistState(state, cwd, options = {}) {
+    const effectiveCwd = cwd ?? process.cwd();
+    withStoreLock(effectiveCwd, () => {
+        writeStateDirectories(state, effectiveCwd);
+        if (options.writeProjectMarkdown ?? true) {
+            writeFileAtomic(memoryPath('project.md', effectiveCwd), generateMarkdown(state, effectiveCwd));
+        }
+        appendEvent({
+            action: options.eventAction ?? 'update',
+            item_type: 'state',
+            agent: 'system',
+            summary: options.eventSummary,
+        }, effectiveCwd);
+        commitMemoryChange(options.commitMessage ?? 'state update', effectiveCwd);
+    });
 }
 //# sourceMappingURL=state.js.map

package/docs/adapters/openclaw.md

@@ -0,0 +1,43 @@
+# OpenClaw Adapter Guide
+
+This adapter helps convert OpenClaw runtime traces into brainclaw candidates.
+
+## Supported Inputs
+
+- Runtime event file: JSON array of events.
+- Runtime session import: events filtered by `metadata.session` from `.brainclaw/runtime/`.
+
+## Basic Usage
+
+```bash
+brainclaw adapter-openclaw-import ./openclaw-events.json
+brainclaw adapter-openclaw-import --session sess_42
+```
+
+## Dry-Run Workflow
+
+Use `--dry-run` to preview what would be ingested without writing any files:
+
+```bash
+brainclaw adapter-openclaw-import ./openclaw-events.json --dry-run
+```
+
+Dry-run is useful for CI checks and for validating mapping quality before modifying `.brainclaw/inbox/`.
+
+## Event Mapping
+
+Current mapping converts events into reflective candidate types:
+
+- `risk_detected` -> `trap`
+- `handoff_requested` -> `handoff`
+- `observation` -> `decision`
+- `constraint_detected` -> `constraint`
+
+If an event type is unknown, it defaults to `decision`.
+
+## Recommended Team Flow
+
+1. Import events from file or session.
+2. Run `brainclaw review --prioritized`.
+3. Curators process with `brainclaw accept` or `brainclaw reject`.
+4. Use `brainclaw doctor` or `brainclaw doctor --json` to monitor quality.