claude-flow 3.57.1 → 3.58.0

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

@@ -0,0 +1,222 @@
+/**
+ * #3508: read-only memory route/peek.
+ *
+ * A health check needs to know which memory store files a cwd resolves to,
+ * and what is in them, without changing anything to find out. `memory stats`
+ * (even after #3463/#3448) still calls `ensureInitialized()` when no explicit
+ * path is given, and answers for one file per call. This module reports
+ * BOTH files — the sql.js `memory.db` the CLI writes and its native
+ * `agentdb-memory.db` sibling the MCP/bridge path writes — in one read-only
+ * pass, and says which resolution rule picked the root.
+ *
+ * Contract (do not relax without re-reading #3508):
+ *   - never creates, initializes, or migrates anything;
+ *   - never opens a file that does not exist (`existsSync` gated before any
+ *     open attempt, for both engines);
+ *   - every open is `readonly`/`fileMustExist` (native) or a one-shot byte
+ *     buffer handed to sql.js, which is never written back to disk;
+ *   - `rows: null` means "could not read" and is never a count of 0, so an
+ *     empty store and an unreadable one never look the same;
+ *   - an encrypted-at-rest `memory.db` reports `encrypted: true` and
+ *     `rows: null`, but its size is still reported.
+ */
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { getMemoryRoot, resolveDbPath } from './memory-initializer.js';
+import { siblingAgentDbPath } from './memory-bridge.js';
+import { isEncryptedBlob } from '../encryption/vault.js';
+// Mirrors the `ACTIVE_MEMORY_ROW_SQL` convention in memory-initializer.ts:
+// legacy rows with a NULL status predate soft-delete semantics and count.
+const ACTIVE_ROW_SQL = `(status = 'active' OR status IS NULL)`;
+const ENCRYPTION_SNIFF_LEN = 64; // RFE1 magic(4)+iv(12)+tag(16); 64 gives headroom.
+function safeStatSize(filePath) {
+    try {
+        return statSync(filePath).size;
+    }
+    catch {
+        return null;
+    }
+}
+function readHeaderBytes(filePath, len) {
+    const fd = openSync(filePath, 'r');
+    try {
+        const buf = Buffer.alloc(len);
+        const bytesRead = readSync(fd, buf, 0, len, 0);
+        return buf.subarray(0, bytesRead);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function latestMillis(values) {
+    let latest = -Infinity;
+    for (const raw of values) {
+        const millis = typeof raw === 'number' ? raw : Number(raw);
+        if (Number.isFinite(millis))
+            latest = Math.max(latest, millis);
+    }
+    return latest;
+}
+/** sql.js is read as a one-shot in-memory byte buffer — nothing is ever
+ * written back, so reading this file has no on-disk side effect. */
+async function probeSqlJsStore(dbPath) {
+    try {
+        if (isEncryptedBlob(readHeaderBytes(dbPath, ENCRYPTION_SNIFF_LEN))) {
+            return { rows: null, lastWrite: null, keys: null, encrypted: true };
+        }
+    }
+    catch {
+        /* header read failed (permissions/race) — fall through to the open attempt */
+    }
+    try {
+        const initSqlJs = (await import('sql.js')).default ?? (await import('sql.js'));
+        const SQL = await (typeof initSqlJs === 'function' ? initSqlJs() : initSqlJs.default());
+        const buf = readFileSync(dbPath);
+        const db = new SQL.Database(new Uint8Array(buf));
+        try {
+            const tables = db.exec("SELECT name FROM sqlite_master WHERE type='table' AND name='memory_entries'");
+            if (!tables.length)
+                return { rows: null, lastWrite: null, keys: null };
+            const result = db.exec(`SELECT namespace, key, created_at, updated_at FROM memory_entries WHERE ${ACTIVE_ROW_SQL}`);
+            const values = result[0]?.values ?? [];
+            const keys = new Set();
+            let last = -Infinity;
+            for (const [namespace, key, createdAt, updatedAt] of values) {
+                keys.add(`${String(namespace)}\u0000${String(key)}`);
+                last = Math.max(last, latestMillis([createdAt, updatedAt]));
+            }
+            return {
+                rows: values.length,
+                lastWrite: Number.isFinite(last) ? new Date(last).toISOString() : null,
+                keys,
+            };
+        }
+        finally {
+            try {
+                db.close();
+            }
+            catch { /* best effort */ }
+        }
+    }
+    catch {
+        return { rows: null, lastWrite: null, keys: null };
+    }
+}
+/** better-sqlite3 is an optional native dependency — absence must degrade
+ * to "could not read", never throw. Opened `readonly`/`fileMustExist`, same
+ * as `countSiblingStoreRows` in sibling-store.ts. */
+async function probeNativeStore(dbPath) {
+    try {
+        const require = (await import('node:module')).createRequire(import.meta.url);
+        const Database = require('better-sqlite3');
+        const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        try {
+            const table = db
+                .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memory_entries'")
+                .get();
+            if (!table)
+                return { rows: null, lastWrite: null, keys: null };
+            const rows = db
+                .prepare(`SELECT namespace, key, created_at, updated_at FROM memory_entries WHERE ${ACTIVE_ROW_SQL}`)
+                .all();
+            const keys = new Set();
+            let last = -Infinity;
+            for (const row of rows) {
+                keys.add(`${String(row.namespace)}\u0000${String(row.key)}`);
+                last = Math.max(last, latestMillis([row.created_at, row.updated_at]));
+            }
+            return {
+                rows: rows.length,
+                lastWrite: Number.isFinite(last) ? new Date(last).toISOString() : null,
+                keys,
+            };
+        }
+        finally {
+            try {
+                db.close();
+            }
+            catch { /* best effort */ }
+        }
+    }
+    catch {
+        return { rows: null, lastWrite: null, keys: null };
+    }
+}
+/** Same precedence `getMemoryRoot()`/`resolveDbPath()` already own — this
+ * only *labels* which rule decided, it never re-derives the path itself. */
+function decideSource(cliFlag) {
+    if (cliFlag && cliFlag.trim().length > 0)
+        return 'path';
+    if (process.env.CLAUDE_FLOW_DB_PATH && process.env.CLAUDE_FLOW_DB_PATH.trim().length > 0) {
+        return 'CLAUDE_FLOW_DB_PATH';
+    }
+    if (process.env.CLAUDE_FLOW_MEMORY_PATH && process.env.CLAUDE_FLOW_MEMORY_PATH.trim().length > 0) {
+        return 'CLAUDE_FLOW_MEMORY_PATH';
+    }
+    const configCandidates = [
+        path.resolve(process.cwd(), 'claude-flow.config.json'),
+        path.resolve(process.cwd(), '.claude-flow', 'config.json'),
+    ];
+    for (const configPath of configCandidates) {
+        if (!existsSync(configPath))
+            continue;
+        try {
+            const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+            const fromConfig = raw?.memory?.persistPath ?? raw?.memory?.path;
+            if (typeof fromConfig === 'string' && fromConfig.trim().length > 0)
+                return 'config';
+        }
+        catch {
+            /* malformed config — getMemoryRoot() falls through to default too */
+        }
+    }
+    return 'default';
+}
+async function describeStore(role, storePath, probe) {
+    if (!existsSync(storePath)) {
+        return {
+            store: { role, path: storePath, exists: false, rows: null, lastWrite: null, sizeBytes: null, walBytes: null },
+            keys: null,
+        };
+    }
+    const result = await probe(storePath);
+    const sizeBytes = safeStatSize(storePath);
+    const walBytes = safeStatSize(`${storePath}-wal`) ?? 0;
+    return {
+        store: {
+            role,
+            path: storePath,
+            exists: true,
+            rows: result.rows,
+            lastWrite: result.lastWrite,
+            sizeBytes,
+            walBytes,
+            ...(result.encrypted ? { encrypted: true } : {}),
+        },
+        keys: result.keys,
+    };
+}
+/**
+ * Resolve the route and report both stores, read-only. Never creates,
+ * initializes, or migrates anything, on an empty project or any other.
+ */
+export async function memoryPeek(opts) {
+    const cliFlag = opts?.path;
+    const cliPath = resolveDbPath(cliFlag);
+    const mcpPath = siblingAgentDbPath(cliPath);
+    const root = { path: cliFlag ? path.dirname(cliPath) : getMemoryRoot(), source: decideSource(cliFlag) };
+    const cliDescribed = await describeStore('cli', cliPath, probeSqlJsStore);
+    const stores = [cliDescribed.store];
+    let mcpKeys = null;
+    if (mcpPath) {
+        const mcpDescribed = await describeStore('mcp', mcpPath, probeNativeStore);
+        stores.push(mcpDescribed.store);
+        mcpKeys = mcpDescribed.keys;
+    }
+    const cliKeys = cliDescribed.keys;
+    const sharedKeys = cliKeys && mcpKeys
+        ? [...cliKeys].filter((key) => mcpKeys.has(key)).length
+        : null;
+    return { cwd: process.cwd(), root, stores, sharedKeys };
+}
+//# sourceMappingURL=memory-peek.js.map

package/v3/@claude-flow/cli/dist/src/memory/model-cache-dir.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve a writable cache directory for ONNX model downloads.
+ *
+ * ADR-454: duplicated intentionally from
+ * `@claude-flow/embeddings/src/transformers-loader.ts`'s
+ * `resolveModelCacheDir()` rather than imported, since `@claude-flow/cli`
+ * has no dependency on `@claude-flow/embeddings` (see the circular
+ * optional-dep note in `memory-initializer.ts`).
+ */
+export declare function resolveModelCacheDir(): string;
+//# sourceMappingURL=model-cache-dir.d.ts.map

package/v3/@claude-flow/cli/dist/src/memory/model-cache-dir.js

@@ -0,0 +1,17 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+/**
+ * Resolve a writable cache directory for ONNX model downloads.
+ *
+ * ADR-454: duplicated intentionally from
+ * `@claude-flow/embeddings/src/transformers-loader.ts`'s
+ * `resolveModelCacheDir()` rather than imported, since `@claude-flow/cli`
+ * has no dependency on `@claude-flow/embeddings` (see the circular
+ * optional-dep note in `memory-initializer.ts`).
+ */
+export function resolveModelCacheDir() {
+    return (process.env.TRANSFORMERS_CACHE ||
+        process.env.HF_HOME ||
+        path.join(os.homedir(), '.cache', 'ruflo', 'models'));
+}
+//# sourceMappingURL=model-cache-dir.js.map

package/v3/@claude-flow/cli/dist/src/ruvector/task-embedder.js

@@ -19,6 +19,8 @@
  *
  * @module task-embedder
  */
+import * as fs from 'node:fs';
+import { resolveModelCacheDir } from '../memory/model-cache-dir.js';
 // ============================================================================
 // FNV-1a-32 hash (matches scripts/gen-seed-corpus.mjs + router-trajectory.ts)
 // ============================================================================
@@ -38,18 +40,48 @@ function cacheKey(task) {
 // same function (xenova's pipeline returns a callable that accepts either),
 // so we don't pay the ONNX model-load cost twice.
 let _extractorPromise = null;
+/**
+ * ADR-454: distinguishes a null-extractor result caused by a genuinely
+ * missing dependency (permanent — nothing changes without a reinstall) from
+ * one caused by an environmental/fixable failure during `pipeline(...)`
+ * init, such as EACCES on the model cache dir (retryable).
+ */
+let _extractorDegradedReason = null;
+let _extractorLastAttemptAt = 0;
+const EXTRACTOR_RETRY_INTERVAL_MS = 60_000;
 function loadExtractor() {
-    if (_extractorPromise !== null)
-        return _extractorPromise;
+    if (_extractorPromise !== null) {
+        const isRetryableDue = _extractorDegradedReason === 'retryable' &&
+            Date.now() - _extractorLastAttemptAt >= EXTRACTOR_RETRY_INTERVAL_MS;
+        if (!isRetryableDue)
+            return _extractorPromise;
+        // Fall through to re-attempt — the retryable failure may now be fixed.
+    }
+    _extractorLastAttemptAt = Date.now();
     _extractorPromise = (async () => {
+        let packageImportable = false;
         try {
             const specifier = '@xenova/transformers';
             const mod = await import(/* @vite-ignore */ specifier).catch(() => null);
-            if (!mod || typeof mod.pipeline !== 'function')
+            if (!mod || typeof mod.pipeline !== 'function') {
+                _extractorDegradedReason = 'permanent';
                 return null;
-            return await mod.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { quantized: true });
+            }
+            packageImportable = true;
+            // ADR-454: route model downloads to a user-writable cache dir — the
+            // package-relative default is root-owned under a system-prefix
+            // global install, which throws EACCES for the runtime user.
+            const cacheDir = resolveModelCacheDir();
+            fs.mkdirSync(cacheDir, { recursive: true });
+            const env = mod.env;
+            if (env)
+                env.cacheDir = cacheDir;
+            const extractor = await mod.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { quantized: true });
+            _extractorDegradedReason = null;
+            return extractor;
         }
         catch {
+            _extractorDegradedReason = packageImportable ? 'retryable' : 'permanent';
             return null;
         }
     })();
@@ -233,5 +265,7 @@ export function __resetTaskEmbedderForTests() {
     _hits = 0;
     _misses = 0;
     _extractorPromise = null;
+    _extractorDegradedReason = null;
+    _extractorLastAttemptAt = 0;
 }
 //# sourceMappingURL=task-embedder.js.map

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