claude-flow 3.47.0 → 3.48.0

package/v3/@claude-flow/cli/dist/src/mcp-tools/policy-enforcer.js

@@ -58,7 +58,6 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 export function isPolicyEnforcementEnabled(env = process.env) {
     const v = env.RUFLO_MCP_ENFORCE_POLICY;
     return v === '1' || (v ?? '').toLowerCase() === 'true';
@@ -118,11 +117,18 @@ let auditLogPathOverride = null;
 export function setAuditLogPathForTesting(p) {
     auditLogPathOverride = p;
 }
-function defaultAuditLogPath() {
-    return path.join(os.tmpdir(), 'ruflo-mcp-audit.jsonl');
-}
-export function getAuditLogPath() {
-    return auditLogPathOverride ?? defaultAuditLogPath();
+export function getAuditLogPath(options = {}) {
+    if (auditLogPathOverride !== null)
+        return auditLogPathOverride;
+    if (options.auditLogPath !== undefined &&
+        (typeof options.auditLogPath !== 'string' || options.auditLogPath.trim().length === 0)) {
+        throw new Error('auditLogPath must be a non-empty string');
+    }
+    // Precedence: explicit caller/policy destination, environment, project default.
+    const configured = options.auditLogPath ?? process.env.RUFLO_MCP_AUDIT_LOG_PATH;
+    return configured
+        ? path.resolve(process.cwd(), configured)
+        : path.join(process.cwd(), '.claude-flow', 'logs', 'mcp-audit.jsonl');
 }
 /**
  * Appends one JSONL audit record. Returns `true` if `policy.auditLog` is not
@@ -135,8 +141,74 @@ export function appendAuditLog(policy, entry) {
     if (!policy.auditLog)
         return true;
     try {
-        fs.appendFileSync(getAuditLogPath(), `${JSON.stringify(entry)}\n`, 'utf-8');
-        return true;
+        const maxBytes = policy.auditLogMaxBytes ?? 10 * 1024 * 1024;
+        const maxFiles = policy.auditLogMaxFiles ?? 5;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 ||
+            !Number.isSafeInteger(maxFiles) || maxFiles < 1 || maxFiles > 100)
+            return false;
+        const line = `${JSON.stringify({ ...entry, projectPath: path.resolve(process.cwd()) })}\n`;
+        const bytes = Buffer.byteLength(line, 'utf8');
+        if (bytes > maxBytes)
+            return false;
+        const logPath = getAuditLogPath(policy);
+        fs.mkdirSync(path.dirname(logPath), { recursive: true, mode: 0o700 });
+        // All writers of a configured path serialize rotation AND append. On
+        // contention (or a stale lock after a crash), deny rather than lose audit
+        // evidence by racing a rename. Only the lock owner removes its lock.
+        const lockPath = `${logPath}.lock`;
+        const lock = fs.openSync(lockPath, 'wx', 0o600);
+        try {
+            let size = 0;
+            try {
+                const stat = fs.lstatSync(logPath);
+                if (!stat.isFile())
+                    throw new Error('Audit log is not a regular file');
+                size = stat.size;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            if (size + bytes > maxBytes) {
+                // Validate the entire chain before moving or expiring any evidence.
+                for (let index = 1; index <= maxFiles; index++) {
+                    try {
+                        if (!fs.lstatSync(`${logPath}.${index}`).isFile())
+                            throw new Error('Audit segment is not a regular file');
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                }
+                for (let index = maxFiles; index >= 1; index--) {
+                    const source = index === 1 ? logPath : `${logPath}.${index - 1}`;
+                    const target = `${logPath}.${index}`;
+                    if (index === maxFiles) {
+                        try {
+                            fs.unlinkSync(target);
+                        }
+                        catch (error) {
+                            if (error.code !== 'ENOENT')
+                                throw error;
+                        }
+                    }
+                    try {
+                        fs.renameSync(source, target);
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                }
+            }
+            fs.appendFileSync(logPath, line, { encoding: 'utf8', mode: 0o600 });
+            return true;
+        }
+        finally {
+            fs.closeSync(lock);
+            fs.unlinkSync(lockPath);
+        }
     }
     catch {
         return false;

package/v3/@claude-flow/cli/dist/src/mcp-tools/session-tools.js

@@ -4,6 +4,7 @@
  * Tool definitions for session management with file persistence.
  */
 import { existsSync, readFileSync, readdirSync, unlinkSync, statSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { getProjectCwd } from './types.js';
 import { mkdirRestricted, readFileMaybeEncrypted, writeFileRestricted, } from '../fs-secure.js';
@@ -126,7 +127,7 @@ export const sessionTools = [
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
-            const sessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const sessionId = `session-${Date.now()}-${randomUUID().slice(0, 8)}`;
             // Load related data based on options
             const data = loadRelatedStores({
                 includeMemory: input.includeMemory,
@@ -170,6 +171,9 @@ export const sessionTools = [
             properties: {
                 sessionId: { type: 'string', description: 'Session ID to restore' },
                 name: { type: 'string', description: 'Session name to restore' },
+                restoreMemory: { type: 'boolean', description: 'Restore memory (default true)' },
+                restoreTasks: { type: 'boolean', description: 'Restore tasks (default true)' },
+                restoreAgents: { type: 'boolean', description: 'Restore agents (default true)' },
             },
         },
         handler: async (input) => {
@@ -205,7 +209,7 @@ export const sessionTools = [
             if (session) {
                 // Restore data to respective stores (legacy JSON for backward compat).
                 // audit_1776853149979: tighten perms on the restored stores too.
-                if (session.data?.memory) {
+                if (input.restoreMemory !== false && session.data?.memory) {
                     const memoryDir = join(getProjectCwd(), STORAGE_DIR, 'memory');
                     if (!existsSync(memoryDir))
                         mkdirRestricted(memoryDir);
@@ -233,13 +237,13 @@ export const sessionTools = [
                         // Legacy JSON restore is the fallback -- sql.js import may not be available
                     }
                 }
-                if (session.data?.tasks) {
+                if (input.restoreTasks !== false && session.data?.tasks) {
                     const taskDir = join(getProjectCwd(), STORAGE_DIR, 'tasks');
                     if (!existsSync(taskDir))
                         mkdirRestricted(taskDir);
                     writeFileRestricted(join(taskDir, 'store.json'), JSON.stringify(session.data.tasks, null, 2));
                 }
-                if (session.data?.agents) {
+                if (input.restoreAgents !== false && session.data?.agents) {
                     const agentDir = join(getProjectCwd(), STORAGE_DIR, 'agents');
                     if (!existsSync(agentDir))
                         mkdirRestricted(agentDir);
@@ -249,6 +253,11 @@ export const sessionTools = [
                     sessionId: session.sessionId,
                     name: session.name,
                     restored: true,
+                    restoredComponents: {
+                        memory: input.restoreMemory !== false && !!session.data?.memory,
+                        tasks: input.restoreTasks !== false && !!session.data?.tasks,
+                        agents: input.restoreAgents !== false && !!session.data?.agents,
+                    },
                     restoredAt: new Date().toISOString(),
                     stats: session.stats,
                 };
@@ -437,7 +446,7 @@ export const sessionTools = [
             properties: {
                 sessionId: { type: 'string', description: 'Session ID to export' },
                 outputPath: { type: 'string', description: 'File path to write the export to (optional)' },
-                includeMemory: { type: 'boolean', description: 'Include the memory snapshot (advisory — already in the saved record)' },
+                includeMemory: { type: 'boolean', description: 'Include the memory snapshot (default true)' },
             },
             required: ['sessionId'],
         },
@@ -449,6 +458,14 @@ export const sessionTools = [
             const session = loadSession(sessionId);
             if (!session)
                 return { sessionId, error: 'Session not found' };
+            // Apply the explicit exclusion before either returning or writing the
+            // snapshot. The saved source remains intact for a later full restore.
+            if (input.includeMemory === false) {
+                if (session.data)
+                    delete session.data.memory;
+                session.stats = { ...session.stats, memoryEntries: 0, totalSize: 0 };
+                session.stats.totalSize = Buffer.byteLength(JSON.stringify(session), 'utf-8');
+            }
             let path = null;
             const outputPath = input.outputPath ? String(input.outputPath) : null;
             if (outputPath) {
@@ -474,7 +491,7 @@ export const sessionTools = [
             properties: {
                 inputPath: { type: 'string', description: 'Path to the session JSON file to import' },
                 name: { type: 'string', description: 'Override the imported session name' },
-                activate: { type: 'boolean', description: 'Make the imported session the current one (advisory)' },
+                activate: { type: 'boolean', description: 'Restore the imported session into the active stores' },
             },
             required: ['inputPath'],
         },
@@ -489,7 +506,7 @@ export const sessionTools = [
             catch (e) {
                 return { error: `Invalid session JSON: ${e.message}` };
             }
-            const newId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const newId = `session-${Date.now()}-${randomUUID().slice(0, 8)}`;
             const stats = parsed.stats || { tasks: 0, agents: 0, memoryEntries: 0, totalSize: 0 };
             const session = {
                 sessionId: newId,
@@ -500,6 +517,15 @@ export const sessionTools = [
                 data: parsed.data,
             };
             saveSession(session);
+            let activated = false;
+            if (input.activate === true) {
+                const restore = sessionTools.find(tool => tool.name === 'session_restore');
+                const result = await restore.handler({ sessionId: newId });
+                if (result.restored !== true) {
+                    return { sessionId: newId, activated: false, error: result.error || 'Imported session could not be restored' };
+                }
+                activated = true;
+            }
             return {
                 sessionId: newId,
                 name: session.name,
@@ -509,7 +535,7 @@ export const sessionTools = [
                     tasksImported: stats.tasks,
                     memoryEntriesImported: stats.memoryEntries,
                 },
-                activated: input.activate === true,
+                activated,
             };
         },
     },

package/v3/@claude-flow/cli/dist/src/mcp-tools/task-tools.js

@@ -40,6 +40,53 @@ function saveTaskStore(store) {
     ensureTaskDir();
     writeFileSync(getTaskPath(), JSON.stringify(store, null, 2), 'utf-8');
 }
+/**
+ * Apply an agent-state change to every store that holds the agent.
+ *
+ * `hive-mind_spawn` keeps its workers in `.claude-flow/agents.json`, not the
+ * canonical `.claude-flow/agents/store.json` (#1916). Syncing only the
+ * canonical store meant assigning a task to a hive worker never marked it
+ * busy, and completing one never counted it: `hive-mind status` showed the
+ * worker idle with 0 completed while its task sat in the queue.
+ */
+function updateAgents(agentIds, mutate) {
+    if (agentIds.length === 0)
+        return;
+    const paths = [
+        join(getProjectCwd(), STORAGE_DIR, 'agents', 'store.json'),
+        join(getProjectCwd(), STORAGE_DIR, 'agents.json'),
+    ];
+    for (const path of paths) {
+        try {
+            if (!existsSync(path))
+                continue;
+            const store = JSON.parse(readFileSync(path, 'utf-8'));
+            if (!store.agents)
+                continue;
+            let touched = false;
+            for (const id of agentIds) {
+                if (store.agents[id]) {
+                    mutate(store.agents[id]);
+                    touched = true;
+                }
+            }
+            if (touched)
+                writeFileSync(path, JSON.stringify(store, null, 2), 'utf-8');
+        }
+        catch {
+            // Best-effort agent sync: a corrupt agent store must not fail the task op.
+        }
+    }
+}
+/** Return agents still holding `taskId` to idle. */
+function releaseAgents(agentIds, taskId) {
+    updateAgents(agentIds, (agent) => {
+        if (agent.currentTask === taskId) {
+            agent.status = 'idle';
+            agent.currentTask = null;
+        }
+    });
+}
 export const taskTools = [
     {
         name: 'task_create',
@@ -214,33 +261,22 @@ export const taskTools = [
             const taskId = input.taskId;
             const task = store.tasks[taskId];
             if (task) {
+                if (task.status === 'completed') {
+                    return { taskId: task.taskId, status: task.status, completedAt: task.completedAt, result: task.result };
+                }
                 task.status = 'completed';
                 task.progress = 100;
                 task.completedAt = new Date().toISOString();
                 task.result = input.result || {};
                 saveTaskStore(store);
                 // Sync assigned agents back to idle and increment taskCount
-                if (task.assignedTo.length > 0) {
-                    const agentStorePath = join(getProjectCwd(), STORAGE_DIR, 'agents', 'store.json');
-                    try {
-                        let agentStore = { agents: {} };
-                        if (existsSync(agentStorePath)) {
-                            agentStore = JSON.parse(readFileSync(agentStorePath, 'utf-8'));
-                        }
-                        for (const agentId of task.assignedTo) {
-                            if (agentStore.agents[agentId]) {
-                                agentStore.agents[agentId].status = 'idle';
-                                agentStore.agents[agentId].currentTask = null;
-                                agentStore.agents[agentId].taskCount =
-                                    (agentStore.agents[agentId].taskCount || 0) + 1;
-                            }
-                        }
-                        writeFileSync(agentStorePath, JSON.stringify(agentStore, null, 2), 'utf-8');
-                    }
-                    catch {
-                        // Best-effort agent sync
+                updateAgents(task.assignedTo, (agent) => {
+                    if (agent.currentTask === taskId) {
+                        agent.status = 'idle';
+                        agent.currentTask = null;
                     }
-                }
+                    agent.taskCount = (agent.taskCount || 0) + 1;
+                });
                 return {
                     taskId: task.taskId,
                     status: task.status,
@@ -266,6 +302,7 @@ export const taskTools = [
                 status: { type: 'string', description: 'New status' },
                 progress: { type: 'number', description: 'Progress percentage (0-100)' },
                 assignTo: { type: 'array', items: { type: 'string' }, description: 'Agent IDs to assign' },
+                result: { type: 'object', description: 'Result data (e.g. the failure of a failed task)' },
             },
             required: ['taskId'],
         },
@@ -284,6 +321,12 @@ export const taskTools = [
                     if (newStatus === 'in_progress' && !task.startedAt) {
                         task.startedAt = new Date().toISOString();
                     }
+                    // A failed task frees its workers, as task_complete and task_cancel do;
+                    // otherwise a worker whose run failed stays `busy` forever.
+                    if (newStatus === 'failed') {
+                        task.completedAt = new Date().toISOString();
+                        releaseAgents(task.assignedTo, taskId);
+                    }
                 }
                 if (typeof input.progress === 'number') {
                     task.progress = Math.min(100, Math.max(0, input.progress));
@@ -291,6 +334,9 @@ export const taskTools = [
                 if (input.assignTo) {
                     task.assignedTo = input.assignTo;
                 }
+                if (input.result && typeof input.result === 'object') {
+                    task.result = input.result;
+                }
                 saveTaskStore(store);
                 return {
                     success: true,
@@ -332,41 +378,20 @@ export const taskTools = [
                 return { taskId, error: 'Task not found' };
             }
             const previouslyAssigned = [...task.assignedTo];
-            // Load agent store to sync worker state
-            const agentStorePath = join(getProjectCwd(), STORAGE_DIR, 'agents', 'store.json');
-            let agentStore = { agents: {} };
-            try {
-                if (existsSync(agentStorePath)) {
-                    agentStore = JSON.parse(readFileSync(agentStorePath, 'utf-8'));
-                }
-            }
-            catch { /* ignore */ }
             if (input.unassign) {
                 // Revert previously assigned agents to idle
-                for (const agentId of previouslyAssigned) {
-                    if (agentStore.agents[agentId]) {
-                        agentStore.agents[agentId].status = 'idle';
-                        agentStore.agents[agentId].currentTask = null;
-                    }
-                }
+                releaseAgents(previouslyAssigned, taskId);
                 task.assignedTo = [];
             }
             else {
                 const agentIds = input.agentIds || [];
                 // Revert old agents to idle
-                for (const agentId of previouslyAssigned) {
-                    if (!agentIds.includes(agentId) && agentStore.agents[agentId]) {
-                        agentStore.agents[agentId].status = 'idle';
-                        agentStore.agents[agentId].currentTask = null;
-                    }
-                }
+                releaseAgents(previouslyAssigned.filter((id) => !agentIds.includes(id)), taskId);
                 // Set new agents to active
-                for (const agentId of agentIds) {
-                    if (agentStore.agents[agentId]) {
-                        agentStore.agents[agentId].status = 'active';
-                        agentStore.agents[agentId].currentTask = taskId;
-                    }
-                }
+                updateAgents(agentIds, (agent) => {
+                    agent.status = 'busy';
+                    agent.currentTask = taskId;
+                });
                 task.assignedTo = agentIds;
                 // Auto-transition task to in_progress if pending
                 if (task.status === 'pending' && agentIds.length > 0) {
@@ -377,12 +402,6 @@ export const taskTools = [
                 }
             }
             saveTaskStore(store);
-            // Save agent store
-            const agentDir = join(getProjectCwd(), STORAGE_DIR, 'agents');
-            if (!existsSync(agentDir)) {
-                mkdirSync(agentDir, { recursive: true });
-            }
-            writeFileSync(agentStorePath, JSON.stringify(agentStore, null, 2), 'utf-8');
             return {
                 taskId: task.taskId,
                 assignedTo: task.assignedTo,
@@ -421,6 +440,7 @@ export const taskTools = [
                 task.completedAt = new Date().toISOString();
                 task.result = { cancelReason: input.reason || 'Cancelled by user' };
                 saveTaskStore(store);
+                releaseAgents(task.assignedTo, taskId);
                 return {
                     success: true,
                     taskId: task.taskId,

package/v3/@claude-flow/cli/dist/src/memory/feedback-patterns.d.ts

@@ -0,0 +1,13 @@
+/** Shared input contract for learned patterns supplied by feedback callers. */
+export declare const feedbackPatternsSchema: {
+    type: string;
+    items: {
+        type: string;
+        minLength: number;
+        maxLength: number;
+    };
+    maxItems: number;
+    description: string;
+};
+export declare function validateFeedbackPatterns(value: unknown): string[] | undefined;
+//# sourceMappingURL=feedback-patterns.d.ts.map

package/v3/@claude-flow/cli/dist/src/memory/feedback-patterns.js

@@ -0,0 +1,14 @@
+/** Shared input contract for learned patterns supplied by feedback callers. */
+export const feedbackPatternsSchema = {
+    type: 'array', items: { type: 'string', minLength: 1, maxLength: 10_000 }, maxItems: 100,
+    description: 'Learned patterns to retain; successful tasks with quality >= 0.9 may create reusable skills',
+};
+export function validateFeedbackPatterns(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length > 100 || value.some(item => typeof item !== 'string' || !item.trim() || item.length > 10_000)) {
+        throw new Error('patterns must be an array of at most 100 non-empty strings (maximum 10000 characters each)');
+    }
+    return value;
+}
+//# sourceMappingURL=feedback-patterns.js.map

package/v3/@claude-flow/cli/dist/src/memory/live-memory-row.d.ts

@@ -0,0 +1,3 @@
+/** TTL is a read-time visibility rule, independent of background cleanup. */
+export declare function liveMemoryRowSql(): string;
+//# sourceMappingURL=live-memory-row.d.ts.map

package/v3/@claude-flow/cli/dist/src/memory/live-memory-row.js

@@ -0,0 +1,5 @@
+/** TTL is a read-time visibility rule, independent of background cleanup. */
+export function liveMemoryRowSql() {
+    return `(status = 'active' OR status IS NULL) AND (expires_at IS NULL OR expires_at > ${Date.now()})`;
+}
+//# sourceMappingURL=live-memory-row.js.map

package/v3/@claude-flow/cli/dist/src/memory/memory-bridge.d.ts

@@ -36,6 +36,8 @@ export declare function shouldDisableNativeBridge(platform?: NodeJS.Platform, en
 export declare function shouldSuppressInitLog(msg: string): boolean;
 /** Test seam: forget cached registries so a test can exercise a fresh open. */
 export declare function _resetRegistryCacheForTest(): void;
+/** Inject registry construction without requiring the optional native package in tests. */
+export declare function __setMemoryBridgeRegistryFactoryForTests(factory: (() => any) | null): void;
 /** #3196: the sibling store AgentDB owns next to a given sql.js database. */
 export declare function siblingAgentDbPath(dbPath: string): string | null;
 /**
@@ -271,6 +273,7 @@ export declare function bridgeAddEmbedding(id: string, embedding: number[], entr
 }, dbPath?: string): Promise<boolean | null>;
 /**
  * Get a named controller from AgentDB v3 via ControllerRegistry.
+ * This borrowed handle must not be retained across shutdownBridge().
  * Returns null if unavailable.
  */
 export declare function bridgeGetController(name: string, dbPath?: string): Promise<any | null>;
@@ -292,13 +295,15 @@ export declare function bridgeListControllers(dbPath?: string): Promise<Array<{
 export declare function isBridgeAvailable(dbPath?: string): Promise<boolean>;
 /**
  * Get the ControllerRegistry instance (for advanced consumers).
+ * This is a borrowed handle, valid only until shutdownBridge(). Callers must
+ * finish using it before requesting shutdown; bridge operations own their own
+ * leases. Prefer bridgeListControllers() for status inspection.
  */
 export declare function getControllerRegistry(dbPath?: string): Promise<any | null>;
 /**
  * Why the bridge last declined a write, or null when it has not.
  *
- * Deliberately NOT gated on `bridgeAvailable === false`. A bridge that
- * initialised fine can still fail every write — a schema mismatch throws
+ * A bridge that initialised fine can still fail every write — a schema mismatch throws
  * per-operation while the registry stays healthy — and that case is exactly
  * the one worth reporting, since the caller then demotes to a fallback whose
  * error message describes something else entirely.
@@ -306,7 +311,7 @@ export declare function getControllerRegistry(dbPath?: string): Promise<any | nu
  * Callers that surface a degraded-path error should include this so the
  * operator learns the cause instead of only the symptom.
  */
-export declare function getBridgeFailureReason(): string | null;
+export declare function getBridgeFailureReason(dbPath?: string): string | null;
 /**
  * Install a pre-initialized registry for deterministic bridge tests.
  *
@@ -321,10 +326,8 @@ export declare function __setMemoryBridgeRegistryForTests(registry: any | null):
  * Shutdown the bridge and release resources.
  *
  * The cached state is cleared unconditionally. Previously the reset lived
- * inside `if (registryInstance)`, so it could not clear a FAILED init — the
- * one state that actually needs clearing, since `registryInstance` is null
- * precisely when init failed. A process that latched `bridgeAvailable = false`
- * therefore had no recovery path short of a restart.
+ * inside `if (registryInstance)`, so it could not clear a FAILED init. This
+ * also clears per-path failed promises, allowing a later retry.
  */
 export declare function shutdownBridge(): Promise<void>;
 /**
@@ -589,15 +592,7 @@ export declare function bridgeHierarchicalRecall(params: {
     topK?: number;
     includeExpired?: boolean;
 }): Promise<any>;
-/**
- * Run memory consolidation.
- *
- * Real MemoryConsolidation API (agentdb alpha.10+):
- *   consolidate() → Promise<ConsolidationReport>
- *   ConsolidationReport = { episodicProcessed, semanticCreated, memoriesForgotten, ... }
- * Stub API (fallback):
- *   consolidate() → { promoted, pruned, timestamp }
- */
+/** Run consolidation when a real controller is available. */
 export declare function bridgeConsolidate(params: {
     minAge?: number;
     maxEntries?: number;
@@ -612,10 +607,6 @@ export declare function bridgeBatchOperation(params: {
     operation: string;
     entries: any[];
 }): Promise<any>;
-/**
- * Synthesize context from memories.
- * ContextSynthesizer.synthesize is a static method that takes MemoryPattern[] (not a string).
- */
 export declare function bridgeContextSynthesize(params: {
     query: string;
     maxEntries?: number;