🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix: serialize learning stats read-merge-write transactions (#4240)
Rudy Mizrahi Celeklif429ccac5318
diff --git a/v3/@claude-flow/cli/__tests__/intelligence-stats-4217.test.ts b/v3/@claude-flow/cli/__tests__/intelligence-stats-4217.test.tsnew file mode 100644index 0000000000..880cd0c3f2--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/intelligence-stats-4217.test.ts@@ -0,0 +1,243 @@+import { afterAll, describe, expect, it } from 'vitest';+import ts from 'typescript';+import { spawn, spawnSync } from 'node:child_process';+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';++const scratch = mkdtempSync(join(tmpdir(), 'intelligence-4217-'));+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const sourceRoot = resolve(packageRoot, '..');+const compiled = join(scratch, 'compiled');+const node = process.env.LEARNING_STATS_TEST_NODE || process.execPath;+mkdirSync(compiled);+writeFileSync(join(compiled, 'package.json'), '{"type":"module"}');+const sources = [+ 'cli/src/memory/intelligence.ts', 'cli/src/ruvector/lora-adapter.ts',+ 'cli/src/mcp-tools/types.ts', 'cli-core/src/mcp-tools/types.ts',+];+if (existsSync(join(packageRoot, 'src/memory/stats-file-lock.ts'))) sources.push('cli/src/memory/stats-file-lock.ts');+for (const source of sources) {+ const input = join(sourceRoot, source);+ const output = join(compiled, source.replace(/\.ts$/, '.js'));+ mkdirSync(dirname(output), { recursive: true });+ writeFileSync(output, ts.transpileModule(readFileSync(input, 'utf8'), {+ compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },+ }).outputText);+}+// Route the real cli-core module to its transpiled source, without a built workspace.+const corePackage = join(compiled, 'node_modules/@claude-flow/cli-core');+mkdirSync(corePackage, { recursive: true });+writeFileSync(join(corePackage, 'package.json'), JSON.stringify({+ type: 'module', exports: { './mcp-tools/types': './types.js' },+}));+writeFileSync(join(corePackage, 'types.js'), readFileSync(join(compiled, 'cli-core/src/mcp-tools/types.js')));+const worker = join(compiled, 'worker.mjs');+writeFileSync(worker, `+import * as intel from './cli/src/memory/intelligence.js';+import * as fs from 'node:fs';+import { join } from 'node:path';+const [mode, root, id = '0'] = process.argv.slice(2);+const stats = join(root, '.claude-flow/neural/stats.json');+const pause = () => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2);+if (mode === 'owner') {+ const { withStatsFileLock } = await import('./cli/src/memory/stats-file-lock.js');+ withStatsFileLock(stats, () => {+ fs.writeFileSync(join(root, 'owned'), '');+ while (!fs.existsSync(join(root, 'release'))) pause();+ });+} else if (mode === 'hot') {+ fs.writeFileSync(join(root, id + '.ready'), '');+ while (!fs.existsSync(join(root, 'start'))) pause();+ for (let i = 0; i < 200; i++) { intel.recordSignalProcessed(); intel.flushIntelligenceStats(); }+ fs.writeFileSync(join(root, id + '.done'), '');+ while (!fs.existsSync(join(root, id + '.drain'))) pause();+ intel.flushIntelligenceStats();+} else if (mode === 'retry') {+ intel.recordSignalProcessed(); intel.flushIntelligenceStats();+ fs.writeFileSync(join(root, 'failed'), fs.readFileSync(stats));+ fs.rmdirSync(stats + '.lock');+ intel.flushIntelligenceStats(); intel.flushIntelligenceStats();+} else if (mode === 'malformed') {+ intel.recordSignalProcessed(); intel.getIntelligenceStats(); intel.flushIntelligenceStats();+ fs.writeFileSync(join(root, 'failed'), fs.readFileSync(stats));+ fs.writeFileSync(stats, '{"signalsProcessed":10,"lastAdaptation":123}');+ intel.flushIntelligenceStats(); intel.flushIntelligenceStats();+} else if (mode === 'write-fail') {+ intel.recordSignalProcessed();+ fs.mkdirSync(stats + '.' + process.pid + '.tmp');+ intel.flushIntelligenceStats();+ fs.writeFileSync(join(root, 'failed'), fs.readFileSync(stats));+ fs.rmdirSync(stats + '.' + process.pid + '.tmp');+ intel.flushIntelligenceStats(); intel.flushIntelligenceStats();+} else if (mode === 'overflow') {+ intel.recordSignalProcessed(); intel.flushIntelligenceStats();+} else {+ intel.recordSignalProcessed(); intel.getIntelligenceStats();+ intel.flushIntelligenceStats(); intel.flushIntelligenceStats();+}+`);+function project(name: string, initial?: string) {+ const root = join(scratch, name);+ mkdirSync(join(root, '.claude-flow/neural'), { recursive: true });+ if (initial !== undefined) writeFileSync(statsPath(root), initial);+ return root;+}+function statsPath(root: string) { return join(root, '.claude-flow/neural/stats.json'); }+function run(mode: string, root: string) {+ return spawnSync(node, [worker, mode, root], {+ env: { ...process.env, CLAUDE_FLOW_CWD: root }, encoding: 'utf8', timeout: 10000,+ });+}+function read(root: string) { return JSON.parse(readFileSync(statsPath(root), 'utf8')); }+async function until(check: () => boolean) {+ const deadline = Date.now() + 15000;+ while (!check()) {+ if (Date.now() > deadline) throw new Error('worker barrier timed out');+ await new Promise(resolve => setTimeout(resolve, 5));+ }+}+function childExit(child: ReturnType<typeof spawn>) {+ let stderr = '';+ child.stderr?.on('data', data => { stderr += data; });+ let forced: ReturnType<typeof setTimeout> | undefined;+ let timedOut = false;+ const timer = setTimeout(() => {+ timedOut = true;+ child.kill('SIGTERM');+ forced = setTimeout(() => child.kill('SIGKILL'), 50);+ }, 12000);+ const ended = new Promise<void>((resolve, reject) => {+ const clear = () => { clearTimeout(timer); if (forced) clearTimeout(forced); };+ child.once('error', error => { clear(); reject(error); });+ child.once('exit', code => {+ clear();+ if (timedOut) reject(new Error('worker exit deadline exceeded'));+ else if (code === 0) resolve();+ else reject(new Error(stderr || `worker exited: ${code}`));+ });+ });+ // A child can fail while another child's barrier is being awaited.+ void ended.catch(() => {});+ return ended;+}+afterAll(() => rmSync(scratch, { recursive: true, force: true }));+describe('cooperating process learning stats transactions (#4217)', () => {+ it('retains every hot-phase increment after a coordinated final drain', async () => {+ const root = project('concurrent');+ const children = Array.from({ length: 8 }, (_, i) => {+ const child = spawn(node, [worker, 'hot', root, String(i)], {+ env: { ...process.env, CLAUDE_FLOW_CWD: root }, stdio: ['ignore', 'ignore', 'pipe'],+ });+ const ended = childExit(child);+ return { child, ended };+ });+ try {+ await until(() => children.every((_, i) => existsSync(join(root, i + '.ready'))));+ writeFileSync(join(root, 'start'), '');+ await until(() => children.every((_, i) => existsSync(join(root, i + '.done'))));+ for (let i = 0; i < children.length; i++) {+ writeFileSync(join(root, i + '.drain'), '');+ await children[i].ended;+ }+ expect(read(root).signalsProcessed).toBe(1600);+ } finally {+ for (const { child } of children) if (child.exitCode === null) child.kill();+ await Promise.allSettled(children.map(child => child.ended));+ }+ }, 30000);+ it('refuses an old held lock and retries pending increments exactly once', () => {+ const initial = '{"signalsProcessed":10}';+ const root = project('held', initial);+ mkdirSync(statsPath(root) + '.lock');+ utimesSync(statsPath(root) + '.lock', new Date(0), new Date(0));+ const result = run('retry', root);+ expect(result.status).toBe(0);+ expect(readFileSync(join(root, 'failed'), 'utf8')).toBe(initial);+ expect(result.stderr).toContain('Could not persist learning stats');+ expect(read(root).signalsProcessed).toBe(11);+ });+ it('preserves malformed JSON, arrays and invalid counter bytes', () => {+ const invalidFiles = [+ '{', '[]', '{"signalsProcessed":"secret"}', '{"signalsProcessed":-1}',+ '{"signalsProcessed":null}', '{"signalsProcessed":0.5}',+ '{"signalsProcessed":9007199254740992}', '{"lastAdaptation":"secret"}',+ ];+ for (const [i, bytes] of invalidFiles.entries()) {+ const root = project('invalid-' + i, bytes);+ const result = run('malformed', root);+ expect(result.status).toBe(0);+ expect(readFileSync(join(root, 'failed'), 'utf8')).toBe(bytes);+ expect(result.stderr).toContain('Could not persist learning stats');+ expect(result.stderr).not.toContain('secret');+ expect(read(root).signalsProcessed).toBe(11);+ expect(read(root).lastAdaptation).toBe(123);+ }+ });+ it('uses the same lock through a symlinked project directory', () => {+ const root = project('real-project', '{"signalsProcessed":10}');+ const alias = join(scratch, 'project-alias');+ symlinkSync(root, alias, process.platform === 'win32' ? 'junction' : 'dir');+ mkdirSync(statsPath(root) + '.lock');+ const busy = run('healthy', alias);+ expect(busy.status).toBe(0);+ expect(read(root).signalsProcessed).toBe(10);+ expect(busy.stderr).toContain('Could not persist learning stats');+ rmSync(statsPath(root) + '.lock', { recursive: true });+ expect(run('healthy', alias).status).toBe(0);+ expect(read(root).signalsProcessed).toBe(11);+ });+ it('retains a failed write delta for retry without double counting', () => {+ const root = project('write-failure', '{"signalsProcessed":10}');+ const result = run('write-fail', root);+ expect(result.status).toBe(0);+ expect(readFileSync(join(root, 'failed'), 'utf8')).toBe('{"signalsProcessed":10}');+ expect(result.stderr).toContain('Could not persist learning stats');+ expect(read(root).signalsProcessed).toBe(11);+ });+ it('preserves a safe counter when adding the pending delta would overflow', () => {+ const bytes = '{"signalsProcessed":9007199254740991}';+ const root = project('overflow', bytes);+ const result = run('overflow', root);+ expect(result.status).toBe(0);+ expect(readFileSync(statsPath(root), 'utf8')).toBe(bytes);+ expect(result.stderr).toContain('EINVALIDSTATS');+ });+ it('supports first use, partial legacy files, late load and repeated flush', () => {+ const fresh = project('fresh');+ expect(run('healthy', fresh).status).toBe(0);+ expect(read(fresh).signalsProcessed).toBe(1);+ const legacy = project('legacy', '{"signalsProcessed":10,"lastAdaptation":null}');+ expect(run('healthy', legacy).status).toBe(0);+ expect(read(legacy).signalsProcessed).toBe(11);+ });+});++// Helper lifecycle controls are additional to the identical baseline API cases above.+describe('stats lock owner lifecycle', () => {+ it('does not steal a paused live owner even when its directory looks old', async () => {+ const root = project('paused-owner', '{"signalsProcessed":10}');+ const child = spawn(node, [worker, 'owner', root], {+ env: { ...process.env, CLAUDE_FLOW_CWD: root }, stdio: 'ignore',+ });+ const ended = childExit(child);+ try {+ await until(() => existsSync(join(root, 'owned')));+ utimesSync(statsPath(root) + '.lock', new Date(0), new Date(0));+ const contender = run('healthy', root);+ expect(contender.status).toBe(0);+ expect(contender.stderr).toContain('ELOCKED');+ expect(read(root).signalsProcessed).toBe(10);+ expect(child.exitCode).toBe(null);+ writeFileSync(join(root, 'release'), '');+ await ended;+ expect(existsSync(statsPath(root) + '.lock')).toBe(false);+ expect(run('healthy', root).status).toBe(0);+ expect(read(root).signalsProcessed).toBe(11);+ } finally {+ if (child.exitCode === null) child.kill();+ await Promise.allSettled([ended]);+ }+ }, 20000);+});diff --git a/v3/@claude-flow/cli/src/memory/intelligence.ts b/v3/@claude-flow/cli/src/memory/intelligence.tsindex ff38963bc5..7e94d8733f 100644--- a/v3/@claude-flow/cli/src/memory/intelligence.ts+++ b/v3/@claude-flow/cli/src/memory/intelligence.ts@@ -17,6 +17,7 @@ import { createRequire } from 'node:module';import { dirname, join } from 'node:path';import { resolveTrainingBackend } from '../ruvector/lora-adapter.js';import { getProjectCwd } from '../mcp-tools/types.js';+import { withStatsFileLock } from './stats-file-lock.js';// ============================================================================// Persistence Configuration@@ -822,10 +823,9 @@ function bumpStat(key: CounterKey, n = 1): void {function readStatsFile(): Partial<typeof globalStats> | null {try {- const path = getStatsPath();- if (!existsSync(path)) return null;- const data = JSON.parse(readFileSync(path, 'utf-8'));- return data && typeof data === 'object' ? data : null;+ // Read-only callers keep their unavailable-on-error contract, while invalid+ // disk values cannot poison local state and a later repaired-file flush.+ return readStatsForWrite(getStatsPath());} catch {return null;}@@ -858,32 +858,75 @@ function maxTimestamp(a: number | null, b: number | null): number | null {return Math.max(a, b);}-/**- * Save stats to disk: merge this process's unsaved deltas into whatever is- * currently on disk (read-merge-write, atomic rename), then adopt the merged- * totals locally so this process also sees other writers' progress.- */+/** Missing files are first use; unreadable or invalid files must not be replaced. */+function readStatsForWrite(path: string): Partial<typeof globalStats> | null {+ let text: string;+ try {+ text = readFileSync(path, 'utf-8');+ } catch (error) {+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;+ throw error;+ }+ let data: Record<string, unknown>;+ try {+ data = JSON.parse(text);+ } catch {+ throw Object.assign(new Error('Invalid learning stats JSON'), { code: 'EINVALIDSTATS' });+ }+ if (!data || typeof data !== 'object' || Array.isArray(data)) {+ throw Object.assign(new Error('Invalid learning stats object'), { code: 'EINVALIDSTATS' });+ }+ for (const key of ['trajectoriesRecorded', 'patternsLearned', 'signalsProcessed']) {+ const value = data[key];+ // Older files may omit a counter, but present counters must be exact counts.+ if (value === undefined) continue;+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {+ throw Object.assign(new Error(`Invalid learning stats field: ${key}`), { code: 'EINVALIDSTATS' });+ }+ }+ const timestamp = data.lastAdaptation;+ if (timestamp != null && (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp < 0)) {+ throw Object.assign(new Error('Invalid learning stats timestamp'), { code: 'EINVALIDSTATS' });+ }+ return data as Partial<typeof globalStats>;+}++/** Merge pending deltas under the cooperating-writer lock, then adopt committed totals. */function savePersistedStats(): void {+ let statsPath: string | undefined;try {- ensureDataDir();- const path = getStatsPath();- const disk = readStatsFile();- const merged = disk- ? {- trajectoriesRecorded: (disk.trajectoriesRecorded ?? 0) + pendingDelta.trajectoriesRecorded,- patternsLearned: (disk.patternsLearned ?? 0) + pendingDelta.patternsLearned,- signalsProcessed: (disk.signalsProcessed ?? 0) + pendingDelta.signalsProcessed,- lastAdaptation: maxTimestamp(disk.lastAdaptation ?? null, globalStats.lastAdaptation),+ statsPath = join(ensureDataDir(), 'stats.json');+ withStatsFileLock(statsPath, (path) => {+ const disk = readStatsForWrite(path);+ const merged = disk+ ? {+ trajectoriesRecorded: (disk.trajectoriesRecorded ?? 0) + pendingDelta.trajectoriesRecorded,+ patternsLearned: (disk.patternsLearned ?? 0) + pendingDelta.patternsLearned,+ signalsProcessed: (disk.signalsProcessed ?? 0) + pendingDelta.signalsProcessed,+ lastAdaptation: maxTimestamp(disk.lastAdaptation ?? null, globalStats.lastAdaptation),+ }+ : { ...globalStats };+ for (const key of ['trajectoriesRecorded', 'patternsLearned', 'signalsProcessed'] as const) {+ if (!Number.isSafeInteger(merged[key]) || merged[key] < 0) {+ throw Object.assign(new Error('Learning stats counter overflow'), { code: 'EINVALIDSTATS' });}- : { ...globalStats };- const tmp = `${path}.${process.pid}.tmp`;- writeFileSync(tmp, JSON.stringify(merged, null, 2), 'utf-8');- renameSync(tmp, path);- globalStats = merged;- pendingDelta = { trajectoriesRecorded: 0, patternsLearned: 0, signalsProcessed: 0 };- persistedStatsLoaded = true;- } catch {- // Ignore save errors (deltas are retained for the next save)+ }+ if (merged.lastAdaptation != null &&+ (!Number.isFinite(merged.lastAdaptation) || merged.lastAdaptation < 0)) {+ throw Object.assign(new Error('Invalid merged learning stats timestamp'), { code: 'EINVALIDSTATS' });+ }+ const tmp = `${path}.${process.pid}.tmp`;+ writeFileSync(tmp, JSON.stringify(merged, null, 2), 'utf-8');+ renameSync(tmp, path);+ // Commit local state before release: a failed release must not replay it.+ globalStats = merged;+ pendingDelta = { trajectoriesRecorded: 0, patternsLearned: 0, signalsProcessed: 0 };+ persistedStatsLoaded = true;+ });+ } catch (error) {+ const { code = 'UNKNOWN', path = statsPath || 'neural stats directory' } = error as NodeJS.ErrnoException;+ // Do not print file contents, which may be malformed or user-controlled.+ console.warn(`[intelligence] Could not persist learning stats at ${path} (${code}); pending increments retained`);}}diff --git a/v3/@claude-flow/cli/src/memory/stats-file-lock.ts b/v3/@claude-flow/cli/src/memory/stats-file-lock.tsnew file mode 100644index 0000000000..4f9c2c0f52--- /dev/null+++ b/v3/@claude-flow/cli/src/memory/stats-file-lock.ts@@ -0,0 +1,46 @@+import { mkdirSync, realpathSync, rmdirSync } from 'node:fs';+import { basename, dirname, join } from 'node:path';++/**+ * Serialize cooperating local writers without stealing a paused writer's lock.+ * Abnormal termination can leave an orphan: recovery requires confirming that+ * no writer still owns the directory before removing it. Never age-reap it.+ */+export function withStatsFileLock<T>(file: string, write: (canonicalFile: string) => T): T {+ const canonicalFile = join(realpathSync(dirname(file)), basename(file));+ const lock = `${canonicalFile}.lock`;+ const deadline = performance.now() + 1000;+ const sleeper = new Int32Array(new SharedArrayBuffer(4));+ for (;;) {+ try {+ mkdirSync(lock, { mode: 0o700 });+ break;+ } catch (error) {+ if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;+ const remaining = deadline - performance.now();+ if (remaining <= 0) {+ throw Object.assign(new Error('Learning stats lock is busy'), { code: 'ELOCKED', path: lock });+ }+ Atomics.wait(sleeper, 0, 0, Math.min(10, remaining));+ }+ }+ const cleanup = () => {+ // Only remove our empty directory. Never recursively remove foreign data.+ rmdirSync(lock);+ };+ const onExit = () => {+ try { cleanup(); } catch { /* abnormal exits may require deliberate recovery */ }+ };+ process.once('exit', onExit);+ try {+ return write(canonicalFile);+ } finally {+ process.removeListener('exit', onExit);+ try {+ cleanup();+ } catch (error) {+ const code = (error as NodeJS.ErrnoException).code || 'UNKNOWN';+ console.warn(`[intelligence] Could not release learning stats lock at ${lock} (${code}); verify ownership before recovery`);+ }+ }+}