claude-flow 3.57.0 → 3.57.2

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

@@ -10,7 +10,12 @@ export interface BackupOptions {
     /** Injected epoch millis (tests pass a fixed value; avoids Date.now in logic). */
     timestamp?: number;
     verbose?: boolean;
+    /** Test seam: inject a fake better-sqlite3-shaped constructor instead of importing the real module. */
+    Database?: new (path: string, opts?: Record<string, unknown>) => any;
 }
+/** Which method actually produced the snapshot — downstream migration tooling
+ * should require `native-online-backup` rather than trusting a blanket `backedUp: true`. */
+export type BackupMethod = 'native-online-backup' | 'raw-copy-fallback';
 export interface BackupResult {
     backedUp: boolean;
     path?: string;
@@ -18,6 +23,7 @@ export interface BackupResult {
     rotatedAway?: string[];
     gcsUri?: string;
     skipped?: string;
+    method?: BackupMethod;
 }
 export declare function defaultMemoryDbPath(cwd?: string): string;
 export interface ProjectBackupResult extends BackupResult {

package/v3/@claude-flow/cli/dist/src/services/memory-backup.js

@@ -14,7 +14,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { readFileMaybeEncrypted } from '../fs-secure.js';
+import { existingFileIsEncrypted, readFileMaybeEncrypted } from '../fs-secure.js';
 import { loadBetterSqlite3 } from '../memory/shared-sqlite.js';
 import { resolveMemoryRoot } from '../memory/memory-root.js';
 export function defaultMemoryDbPath(cwd = process.cwd()) {
@@ -37,12 +37,18 @@ export async function backupProjectMemoryDbs(cwd, opts = {}) {
     }
     const successful = backups.filter(result => result.backedUp);
     const failed = backups.find(result => !result.backedUp && result.skipped !== 'no-db');
+    // Only report an aggregate `method` when every successful store agrees — a
+    // mixed native/raw-copy result must not collapse to whichever store
+    // happened to be first, the exact false-confidence #4287 is about.
+    const methods = new Set(successful.map(result => result.method));
+    const aggregateMethod = methods.size === 1 ? successful[0]?.method : undefined;
     return {
         ...successful[0],
         backedUp: successful.length > 0 && !failed,
         sizeBytes: successful.reduce((sum, result) => sum + (result.sizeBytes ?? 0), 0),
         rotatedAway: successful.flatMap(result => result.rotatedAway ?? []),
         skipped: failed?.skipped ?? (successful.length === 0 ? 'no-db' : undefined),
+        method: aggregateMethod,
         backups,
     };
 }
@@ -63,88 +69,25 @@ function isSnapshotFor(file, dbPath) {
     return file.startsWith(prefix)
         && /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z\.db$/.test(file.slice(prefix.length));
 }
-export async function backupMemoryDb(opts = {}) {
-    const dbPath = opts.dbPath ?? defaultMemoryDbPath();
-    if (!dbPath || !fs.existsSync(dbPath))
-        return { backedUp: false, skipped: 'no-db' };
-    let Database;
+/**
+ * A plain file copy of a live WAL-mode SQLite database is not a consistent
+ * snapshot — committed data can live only in the `-wal` sidecar until it's
+ * checkpointed back into the main file. We can't open an RFE1-encrypted
+ * source natively to run a real `wal_checkpoint` probe (it isn't a SQLite
+ * image), so for the raw-copy-fallback path the only signal available is
+ * sidecar presence: a non-empty `-wal` file means there are frames that a
+ * copy of the main file alone would silently drop. Fail closed on that.
+ */
+function hasActiveWal(dbPath) {
     try {
-        const mod = 'better-sqlite3';
-        Database = (await import(mod)).default;
+        return fs.statSync(`${dbPath}-wal`).size > 0;
     }
     catch {
-        return { backedUp: false, skipped: 'better-sqlite3 unavailable' };
+        return false;
     }
-    const destDir = opts.destDir ?? path.join(path.dirname(dbPath), 'backups');
-    try {
-        fs.mkdirSync(destDir, { recursive: true });
-    }
-    catch { /* */ }
-    const destPath = path.join(destDir, `${snapshotPrefix(dbPath)}${fileStamp(opts.timestamp ?? Date.now())}.db`);
-    // WAL-safe online backup: read-only source, consistent snapshot to destPath.
-    let db;
-    try {
-        db = new Database(dbPath, { readonly: true });
-        await db.backup(destPath);
-        db.close();
-    }
-    catch (e) {
-        try {
-            db?.close();
-        }
-        catch { /* */ }
-        // #2798 — under CLAUDE_FLOW_ENCRYPT_AT_REST the source is an RFE1
-        // blob, not native SQLite, so better-sqlite3's online-backup API
-        // throws "file is not a database" and the run was silently recorded
-        // as skipped (users with encryption had ZERO backups behind a green
-        // status). The online-backup API only exists to avoid tearing a live
-        // WAL-mode DB; that concern doesn't apply to the encrypted file (sql.js
-        // rewrites it wholesale per flush), so a plain byte copy is a valid
-        // snapshot. Fall back to it before giving up.
-        try {
-            fs.copyFileSync(dbPath, destPath);
-            const copiedBytes = fs.statSync(destPath).size;
-            if (copiedBytes > 0) {
-                // Fall through to rotation/offsite/return below via a flag path.
-                // (Mirror the success path's tail by re-using the same code.)
-                const keep = typeof opts.keep === 'number' && opts.keep > 0 ? opts.keep : 7;
-                const rotatedAway = [];
-                try {
-                    const snaps = fs.readdirSync(destDir).filter(f => isSnapshotFor(f, dbPath)).sort();
-                    while (snaps.length > keep) {
-                        const old = snaps.shift();
-                        try {
-                            fs.rmSync(path.join(destDir, old), { force: true });
-                            rotatedAway.push(old);
-                        }
-                        catch { /* */ }
-                    }
-                }
-                catch { /* */ }
-                let gcsUri;
-                if (opts.gcs) {
-                    try {
-                        const { execFileSync } = await import('child_process');
-                        const dest = opts.gcs.replace(/\/+$/, '') + '/' + path.basename(destPath);
-                        execFileSync('gcloud', ['storage', 'cp', destPath, dest], { stdio: ['ignore', 'ignore', 'inherit'] });
-                        gcsUri = dest;
-                    }
-                    catch { /* offsite failed — local snapshot stands */ }
-                }
-                if (opts.verbose) {
-                    console.log(`memory DB backed up (byte-copy, encrypted-at-rest) → ${destPath} (${Math.round(copiedBytes / 1024)} KB)`);
-                }
-                return { backedUp: true, path: destPath, sizeBytes: copiedBytes, rotatedAway, gcsUri };
-            }
-        }
-        catch { /* byte-copy also failed — report the original error */ }
-        return { backedUp: false, skipped: `backup failed: ${e?.message ?? e}` };
-    }
-    let sizeBytes = 0;
-    try {
-        sizeBytes = fs.statSync(destPath).size;
-    }
-    catch { /* */ }
+}
+/** Shared tail: rotation + optional GCS offsite + verbose logging + the success receipt. */
+async function finishBackup(destPath, dbPath, destDir, opts, method, sizeBytes) {
     // Rotation — ISO-stamped names sort chronologically, so keep the tail.
     const keep = typeof opts.keep === 'number' && opts.keep > 0 ? opts.keep : 7;
     const rotatedAway = [];
@@ -172,11 +115,96 @@ export async function backupMemoryDb(opts = {}) {
         catch { /* offsite failed — local snapshot stands */ }
     }
     if (opts.verbose) {
-        console.log(`memory DB backed up → ${destPath} (${Math.round(sizeBytes / 1024)} KB)` +
+        const label = method === 'raw-copy-fallback' ? ' (byte-copy, encrypted-at-rest)' : '';
+        console.log(`memory DB backed up${label} → ${destPath} (${Math.round(sizeBytes / 1024)} KB)` +
             (rotatedAway.length ? `, rotated ${rotatedAway.length} old` : '') +
             (gcsUri ? `, offsite ${gcsUri}` : ''));
     }
-    return { backedUp: true, path: destPath, sizeBytes, rotatedAway, gcsUri };
+    return { backedUp: true, path: destPath, sizeBytes, rotatedAway, gcsUri, method };
+}
+export async function backupMemoryDb(opts = {}) {
+    const dbPath = opts.dbPath ?? defaultMemoryDbPath();
+    if (!dbPath || !fs.existsSync(dbPath))
+        return { backedUp: false, skipped: 'no-db' };
+    const destDir = opts.destDir ?? path.join(path.dirname(dbPath), 'backups');
+    try {
+        fs.mkdirSync(destDir, { recursive: true });
+    }
+    catch { /* */ }
+    const destPath = path.join(destDir, `${snapshotPrefix(dbPath)}${fileStamp(opts.timestamp ?? Date.now())}.db`);
+    let Database = opts.Database;
+    let nativeError = null;
+    if (!Database) {
+        try {
+            const mod = 'better-sqlite3';
+            Database = (await import(mod)).default;
+        }
+        catch {
+            nativeError = 'better-sqlite3 unavailable';
+        }
+    }
+    if (!nativeError) {
+        // WAL-safe online backup: read-only source, consistent snapshot to destPath.
+        let db;
+        try {
+            db = new Database(dbPath, { readonly: true });
+            await db.backup(destPath);
+            db.close();
+            let sizeBytes = 0;
+            try {
+                sizeBytes = fs.statSync(destPath).size;
+            }
+            catch { /* */ }
+            return await finishBackup(destPath, dbPath, destDir, opts, 'native-online-backup', sizeBytes);
+        }
+        catch (e) {
+            try {
+                db?.close();
+            }
+            catch { /* */ }
+            try {
+                fs.rmSync(destPath, { force: true });
+            }
+            catch { /* a native backup() that throws mid-write can leave a torn destPath */ }
+            nativeError = e?.message ?? String(e);
+        }
+    }
+    // #2798 — under CLAUDE_FLOW_ENCRYPT_AT_REST the source is an RFE1 blob, not
+    // native SQLite, so better-sqlite3's online-backup API throws "file is not
+    // a database" (or isn't even importable on a WASM-only host). The
+    // online-backup API exists to avoid tearing a live WAL-mode DB; that
+    // concern doesn't apply to the encrypted file (sql.js rewrites it wholesale
+    // per flush), so a plain byte copy IS a valid snapshot there.
+    //
+    // But this fallback must never fire for an ORDINARY (non-encrypted) source
+    // just because the native backup threw — SQLITE_BUSY, a disk error, or any
+    // other native-backup failure on a perfectly normal database must fail
+    // closed, not silently report `backedUp: true` off a raw copy. Positively
+    // verify encryption (4-byte RFE1 magic sniff) before ever taking this path;
+    // "the native backup threw" is never by itself evidence the source is
+    // encrypted.
+    if (existingFileIsEncrypted(dbPath) !== true) {
+        return { backedUp: false, skipped: `native backup failed: ${nativeError}` };
+    }
+    // Even for a confirmed-encrypted source, refuse the raw-copy fallback if
+    // there's an active WAL — a plain copy of the main file alone would miss
+    // uncommitted WAL frames and silently produce an inconsistent snapshot.
+    if (hasActiveWal(dbPath)) {
+        return { backedUp: false, skipped: 'active WAL present — refusing raw-copy fallback (would be inconsistent)' };
+    }
+    try {
+        fs.copyFileSync(dbPath, destPath);
+        const copiedBytes = fs.statSync(destPath).size;
+        if (copiedBytes > 0) {
+            return await finishBackup(destPath, dbPath, destDir, opts, 'raw-copy-fallback', copiedBytes);
+        }
+    }
+    catch { /* byte-copy also failed — report the original native error below */ }
+    try {
+        fs.rmSync(destPath, { force: true });
+    }
+    catch { /* */ }
+    return { backedUp: false, skipped: `native backup failed: ${nativeError}` };
 }
 /** Verify a snapshot without modifying it, including RFE1 images and WASM-only hosts. */
 async function verifiedBackupRows(file, Database) {

package/v3/@claude-flow/cli/dist/src/services/policy-ledger-anchor.d.ts

@@ -32,6 +32,8 @@ export type AnchorAssessment = {
 };
 export type AnchorWriter = (file: string, value: unknown) => Promise<void>;
 export type StreamingAnchorWriter = (file: string, value: AtomicJsonSource) => Promise<void>;
+export declare const ANCHOR_LOG_FILE = "ledger-anchors.json";
+export declare const ANCHOR_MIRROR_FILE = "ledger-anchor-head.json";
 export declare const anchorLogPath: (projectRoot: string) => string;
 /**
  * Directory holding per-project trust material (anchor mirror, HMAC key).

package/v3/@claude-flow/cli/dist/src/services/policy-ledger-anchor.js

@@ -33,9 +33,9 @@ import { closeSync, constants as fsConstants, fstatSync, existsSync, mkdtempSync
 import { isAbsolute, join, resolve } from 'node:path';
 import { homedir, tmpdir, userInfo } from 'node:os';
 import { AgenticPolicyEngine, canonicalizePolicy } from '@claude-flow/security/policy/index';
-const LOG_FILE = 'ledger-anchors.json';
-const MIRROR_FILE = 'ledger-anchor-head.json';
-export const anchorLogPath = (projectRoot) => join(resolve(projectRoot), '.claude-flow', 'policy', LOG_FILE);
+export const ANCHOR_LOG_FILE = 'ledger-anchors.json';
+export const ANCHOR_MIRROR_FILE = 'ledger-anchor-head.json';
+export const anchorLogPath = (projectRoot) => join(resolve(projectRoot), '.claude-flow', 'policy', ANCHOR_LOG_FILE);
 /**
  * The home directory trust material lives under: $HOME when it is an absolute path, else the account's home. An empty or relative
  * $HOME (an unset variable in a wrapper script, `HOME=. cmd`) would make join() yield a path relative to the working directory and
@@ -71,7 +71,7 @@ export function policyTrustRoot() {
 }
 function mirrorPath(projectRoot) {
     const id = createHash('sha256').update(realpathSync(projectRoot)).digest('hex');
-    return join(policyTrustRoot(), id, MIRROR_FILE);
+    return join(policyTrustRoot(), id, ANCHOR_MIRROR_FILE);
 }
 // Duplicated from policy-runtime.ts's RECEIPT_ARCHIVE_FILE rather than
 // imported, to avoid a circular dependency (policy-runtime.ts imports this

package/v3/@claude-flow/cli/dist/src/services/policy-runtime.js

@@ -7,17 +7,18 @@ import { AgenticPolicyEngine, POLICY_STATE_VERSION, createLegacyCompatibleState,
 import { isMcpCallerAuthEnabled, decodeTokenEnvelope, publicKeyFromHex, verifyInvocationToken, } from '@claude-flow/security/mcp-caller-identity';
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, ftruncateSync, writeSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, ftruncateSync, writeSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { hostname, userInfo } from 'node:os';
 import { syncPolicyProjection } from '../mods/policy-projection.js';
 import { ATOMIC_JSON_WRITER } from './policy-anchor-log.js';
 import { captureArchiveSnapshot, verifyFullPolicyLedger } from './policy-ledger-audit.js';
-import { assessAnchors, policyTrustRoot, recordAnchor } from './policy-ledger-anchor.js';
+import { ANCHOR_LOG_FILE, ANCHOR_MIRROR_FILE, assessAnchors, policyTrustRoot, recordAnchor } from './policy-ledger-anchor.js';
 const POLICY_DIR = join('.claude-flow', 'policy');
 const POLICY_FILE = 'state.json';
 const LOCK_FILE = 'state.lock';
 const RECEIPT_ARCHIVE_FILE = 'receipts.ledger.jsonl';
+const STATE_ANCHOR_FILE = 'state.anchor.json';
 const LOCK_WAIT_MS = 5_000;
 // #3164: without a bound, `state.receipts` grows forever and every
 // transaction's verify/clone/serialize cost is O(all receipts ever issued) —
@@ -362,11 +363,59 @@ async function writeJsonAtomic(file, value) {
         }
     }
 }
+// #3164: a writer killed between creating its temp file and renaming it
+// (SIGKILL from a caller's timeout, OOM) never reaches writeJsonAtomic's
+// cleanup, so a full-size copy of the file stays behind forever (~250 MB each
+// on a mature ledger). Every writer of these files holds the project's
+// state.lock, so while the lock is held no temp file for them can belong to a
+// write in progress. That invariant has known gaps: released versions before
+// the dead-owner fix take over any lock older than 30 s, even a live owner's
+// (a writer suspended mid-write, e.g. a sleeping laptop). So a temp is also
+// kept while its writer pid is alive on this host, and until it is
+// ORPHAN_TEMP_MIN_AGE_MS old; a skipped orphan is removed by a later call.
+const ORPHAN_TEMP_MIN_AGE_MS = 10 * 60_000;
+const ATOMIC_TEMP = /^(.+)\.(\d+)\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/;
+const PROJECT_ATOMIC_FILES = new Set([POLICY_FILE, ANCHOR_LOG_FILE]);
+const TRUST_ATOMIC_FILES = new Set([STATE_ANCHOR_FILE, ANCHOR_MIRROR_FILE]);
+function reapOrphanedTemps(dir, files) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    for (const name of names) {
+        const match = ATOMIC_TEMP.exec(name);
+        if (!match || !files.has(match[1]))
+            continue;
+        const pid = Number(match[2]);
+        if (Number.isSafeInteger(pid) && pid > 0 && isPidAlive(pid))
+            continue;
+        const file = join(dir, name);
+        try {
+            const stat = lstatSync(file);
+            if (!stat.isFile() || now - stat.mtimeMs < ORPHAN_TEMP_MIN_AGE_MS)
+                continue;
+            unlinkSync(file);
+        }
+        catch { /* already gone, or not removable: never fail the caller */ }
+    }
+}
+/** Call only while holding the project's state.lock. */
+function reapOrphanedPolicyTemps(projectRoot) {
+    reapOrphanedTemps(paths(projectRoot).dir, PROJECT_ATOMIC_FILES);
+    try {
+        reapOrphanedTemps(dirname(trustPaths(projectRoot).anchor), TRUST_ATOMIC_FILES);
+    }
+    catch { /* no trust dir yet */ }
+}
 function trustPaths(projectRoot) {
     const trustRoot = policyTrustRoot();
     const projectId = createHash('sha256').update(realpathSync(projectRoot)).digest('hex');
     const dir = join(trustRoot, projectId);
-    return { key: join(dir, 'anchor.key'), anchor: join(dir, 'state.anchor.json') };
+    return { key: join(dir, 'anchor.key'), anchor: join(dir, STATE_ANCHOR_FILE) };
 }
 function trustKey(projectRoot, create) {
     const { key } = trustPaths(projectRoot);
@@ -531,6 +580,7 @@ export async function withPolicyTransaction(projectRoot, operation, options = {}
     mkdirDurably(target.dir);
     const release = await acquireLock(target.lock);
     try {
+        reapOrphanedPolicyTemps(projectRoot);
         const loaded = loadPolicyState(projectRoot);
         const engine = AgenticPolicyEngine.fromState(loaded, {
             signingKey: process.env.CLAUDE_FLOW_POLICY_SIGNING_KEY,
@@ -691,6 +741,7 @@ export async function verifyPolicyLedger(projectRoot = process.cwd(), options =
     // strings, receipt arrays or maps. The descriptor pins path replacements.
     const release = await acquireLock(target.lock);
     try {
+        reapOrphanedPolicyTemps(projectRoot);
         const engine = AgenticPolicyEngine.fromState(loadPolicyState(projectRoot), engineOptions);
         const outcome = reconcileLedger(projectRoot, engine, options);
         if (outcome.persist) {

package/v3/@claude-flow/cli/dist/src/services/worker-daemon.js

@@ -1699,6 +1699,10 @@ export class WorkerDaemon extends EventEmitter {
                 rotatedAway: r.rotatedAway?.length ?? 0,
                 gcsUri: r.gcsUri,
                 skipped: r.skipped,
+                // Which method actually completed (per-store detail is in `backups`);
+                // migration tooling should require 'native-online-backup', not a
+                // blanket `backedUp: true` — see #4287.
+                method: r.method,
             };
         }
         catch (error) {

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.57.0",
+  "version": "3.57.2",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -48,6 +48,7 @@
       "import": "./dist/src/index.js"
     },
     "./dist/*": "./dist/*",
+    "./package.json": "./package.json",
     "./ruvector": {
       "types": "./dist/src/ruvector/index.d.ts",
       "import": "./dist/src/ruvector/index.js"
@@ -98,7 +99,7 @@
     "vitest": "^4.1.0"
   },
   "dependencies": {
-    "@claude-flow/cli-core": "3.7.3",
+    "@claude-flow/cli-core": "3.7.5",
     "@claude-flow/codex": "3.0.5",
     "@claude-flow/mcp": "3.1.1",
     "@claude-flow/neural": "3.0.0",
@@ -125,11 +126,11 @@
     "ws": "^8.21.0",
     "yaml": "^2.8.0",
     "zod": "^3.22.0",
-    "@claude-flow/memory": "3.0.5"
+    "@claude-flow/memory": "3.0.6"
   },
   "optionalDependencies": {
     "@agntcy/slim-bindings": "2.0.0-alpha.5",
-    "@claude-flow/memory": "3.0.5",
+    "@claude-flow/memory": "3.0.6",
     "@metaharness/darwin": "~0.12.0",
     "@metaharness/flywheel": "~0.1.10",
     "@metaharness/radio": "~0.1.0",