Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

fix(memory): fail closed on native backup failure instead of a raw-copy false-success (#4287)

r6959d0135e35
diff --git a/v3/@claude-flow/cli/__tests__/memory-backup-fail-closed.test.ts b/v3/@claude-flow/cli/__tests__/memory-backup-fail-closed.test.ts
new file mode 100644
index 0000000000..a1b2b0bdf9
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/memory-backup-fail-closed.test.ts
@@ -0,0 +1,139 @@
+/**
+ * #4287 β€” a native online-backup failure must fail CLOSED, not silently
+ * fall back to a raw file copy and report success.
+ *
+ * The raw-copy fallback exists ONLY for the encrypted-at-rest (#2798 RFE1)
+ * case, where better-sqlite3's online-backup API fundamentally cannot apply
+ * because the source isn't a native SQLite image at all. It must never fire
+ * for an ordinary (plaintext) source just because the native backup threw
+ * (SQLITE_BUSY, a disk error, or anything else) β€” and even for a genuinely
+ * encrypted source, it must refuse when an active WAL sidecar is present,
+ * since a plain byte copy of the main file alone would silently drop
+ * uncommitted WAL frames.
+ *
+ * These tests use fault injection (a fake native `Database`-like object
+ * passed via the `Database` test seam) plus real temp files/fs β€” no real
+ * SQLite database is opened.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { backupMemoryDb } from '../src/services/memory-backup.js';
+
+// "RFE1" β€” same magic bytes as src/encryption/vault.ts MAGIC.
+const RFE1_MAGIC = Buffer.from([0x52, 0x46, 0x45, 0x31]);
+
+let dir: string;
+beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'memory-backup-fail-closed-')); });
+afterEach(() => { rmSync(dir, { recursive: true, force: true }); });
+
+/** A fake native Database whose online-backup throws like a real SQLITE_BUSY failure. */
+function fakeDatabaseThatThrows(message = 'database is locked'): any {
+ return class FakeDatabase {
+ constructor(_path: string, _opts?: unknown) { /* no-op: never opens a real file */ }
+ async backup(_destPath: string): Promise<void> {
+ throw Object.assign(new Error(message), { code: 'SQLITE_BUSY' });
+ }
+ close(): void { /* no-op */ }
+ };
+}
+
+describe('backupMemoryDb β€” fail closed on native backup failure (#4287)', () => {
+ it('repro: SQLITE_BUSY on an ORDINARY (non-encrypted) source must NOT report backedUp via raw copy', async () => {
+ const dbPath = join(dir, 'memory.db');
+ // Ordinary plaintext SQLite-shaped bytes β€” NOT the RFE1 magic header.
+ writeFileSync(dbPath, Buffer.from('SQLite format 3\0' + 'x'.repeat(100)));
+ const srcBytesBefore = readFileSync(dbPath);
+
+ const r = await backupMemoryDb({
+ dbPath,
+ timestamp: 1_700_000_000_000,
+ Database: fakeDatabaseThatThrows('database is locked'),
+ } as any);
+
+ expect(r.backedUp).toBe(false);
+ expect(r.method).toBeUndefined();
+ expect(r.skipped).toMatch(/native backup failed/);
+ // No raw-copy snapshot was produced (the backups dir may exist β€” it's
+ // created up front β€” but must be empty of any snapshot file), and the
+ // live source is untouched.
+ const snapDir = join(dir, 'backups');
+ if (existsSync(snapDir)) {
+ const { readdirSync } = await import('node:fs');
+ expect(readdirSync(snapDir).filter((f: string) => f.endsWith('.db'))).toHaveLength(0);
+ }
+ expect(readFileSync(dbPath)).toEqual(srcBytesBefore);
+ });
+
+ it('confirmed-encrypted RFE1 source, native backup unavailable/failing, NO active WAL: raw-copy fallback succeeds', async () => {
+ const dbPath = join(dir, 'memory.db');
+ const encryptedBytes = Buffer.concat([RFE1_MAGIC, Buffer.from('ciphertext-not-real-sqlite')]);
+ writeFileSync(dbPath, encryptedBytes);
+ // No -wal sidecar present.
+
+ const r = await backupMemoryDb({
+ dbPath,
+ timestamp: 1_700_000_000_000,
+ Database: fakeDatabaseThatThrows('file is not a database'),
+ } as any);
+
+ expect(r.backedUp).toBe(true);
+ expect(r.method).toBe('raw-copy-fallback');
+ expect(r.path).toBeDefined();
+ expect(existsSync(r.path!)).toBe(true);
+ expect(readFileSync(r.path!)).toEqual(encryptedBytes);
+ // Source untouched.
+ expect(readFileSync(dbPath)).toEqual(encryptedBytes);
+ });
+
+ it('confirmed-encrypted RFE1 source but WITH an active WAL: refuses the raw-copy fallback', async () => {
+ const dbPath = join(dir, 'memory.db');
+ const encryptedBytes = Buffer.concat([RFE1_MAGIC, Buffer.from('ciphertext-not-real-sqlite')]);
+ writeFileSync(dbPath, encryptedBytes);
+ // Active (non-empty) WAL sidecar β€” a plain copy of dbPath alone would be inconsistent.
+ writeFileSync(`${dbPath}-wal`, Buffer.from('uncommitted-wal-frames'));
+
+ const r = await backupMemoryDb({
+ dbPath,
+ timestamp: 1_700_000_000_000,
+ Database: fakeDatabaseThatThrows('file is not a database'),
+ } as any);
+
+ expect(r.backedUp).toBe(false);
+ expect(r.method).toBeUndefined();
+ const snapDir = join(dir, 'backups');
+ if (existsSync(snapDir)) {
+ const { readdirSync } = await import('node:fs');
+ expect(readdirSync(snapDir).filter((f: string) => f.endsWith('.db'))).toHaveLength(0);
+ }
+ // Source and WAL sidecar untouched.
+ expect(readFileSync(dbPath)).toEqual(encryptedBytes);
+ expect(statSync(`${dbPath}-wal`).size).toBeGreaterThan(0);
+ });
+
+ it('a successful native online-backup is marked method: native-online-backup', async () => {
+ const dbPath = join(dir, 'memory.db');
+ let backupCalled = false;
+ const FakeDatabase = class {
+ constructor(_path: string, _opts?: unknown) { /* no-op */ }
+ async backup(destPath: string): Promise<void> {
+ backupCalled = true;
+ writeFileSync(destPath, Buffer.from('fake-consistent-snapshot'));
+ }
+ close(): void { /* no-op */ }
+ };
+ writeFileSync(dbPath, Buffer.from('SQLite format 3\0' + 'x'.repeat(100)));
+
+ const r = await backupMemoryDb({
+ dbPath,
+ timestamp: 1_700_000_000_000,
+ Database: FakeDatabase as any,
+ } as any);
+
+ expect(backupCalled).toBe(true);
+ expect(r.backedUp).toBe(true);
+ expect(r.method).toBe('native-online-backup');
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/memory-backup.test.ts b/v3/@claude-flow/cli/__tests__/memory-backup.test.ts
index f9ca099747..4b63cc0874 100644
--- a/v3/@claude-flow/cli/__tests__/memory-backup.test.ts
+++ b/v3/@claude-flow/cli/__tests__/memory-backup.test.ts
@@ -36,6 +36,7 @@ describe.skipIf(!haveNative)('backupMemoryDb', () => {
const r = await backupMemoryDb({ dbPath, timestamp: 1_700_000_000_000 });
expect(r.backedUp).toBe(true);
+ expect(r.method).toBe('native-online-backup');
expect(existsSync(r.path!)).toBe(true);
expect(r.sizeBytes!).toBeGreaterThan(0);
diff --git a/v3/@claude-flow/cli/src/services/memory-backup.ts b/v3/@claude-flow/cli/src/services/memory-backup.ts
index 92919dfabd..8a4a944a4e 100644
--- a/v3/@claude-flow/cli/src/services/memory-backup.ts
+++ b/v3/@claude-flow/cli/src/services/memory-backup.ts
@@ -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';
@@ -30,8 +30,14 @@ 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;
@@ -39,6 +45,7 @@ export interface BackupResult {
rotatedAway?: string[];
gcsUri?: string;
skipped?: string;
+ method?: BackupMethod;
}
export function defaultMemoryDbPath(cwd: string = process.cwd()): string {
@@ -68,12 +75,18 @@ export async function backupProjectMemoryDbs(
}
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,
};
}
@@ -98,74 +111,32 @@ function isSnapshotFor(file: string, dbPath: string): boolean {
&& /^\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: BackupOptions = {}): Promise<BackupResult> {
- const dbPath = opts.dbPath ?? defaultMemoryDbPath();
- if (!dbPath || !fs.existsSync(dbPath)) return { backedUp: false, skipped: 'no-db' };
-
- let Database: any;
+/**
+ * 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: string): boolean {
try {
- const mod: string = '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: any;
- 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: string[] = [];
- 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: string | undefined;
- 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 as Error)?.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: string,
+ dbPath: string,
+ destDir: string,
+ opts: BackupOptions,
+ method: BackupMethod,
+ sizeBytes: number,
+): Promise<BackupResult> {
// Rotation β€” ISO-stamped names sort chronologically, so keep the tail.
const keep = typeof opts.keep === 'number' && opts.keep > 0 ? opts.keep : 7;
const rotatedAway: string[] = [];
@@ -189,13 +160,86 @@ export async function backupMemoryDb(opts: BackupOptions = {}): Promise<BackupRe
}
if (opts.verbose) {
+ const label = method === 'raw-copy-fallback' ? ' (byte-copy, encrypted-at-rest)' : '';
console.log(
- `memory DB backed up β†’ ${destPath} (${Math.round(sizeBytes / 1024)} KB)` +
+ `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: BackupOptions = {}): Promise<BackupResult> {
+ 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: any = opts.Database;
+ let nativeError: string | null = null;
+ if (!Database) {
+ try {
+ const mod: string = '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: any;
+ 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 as Error)?.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}` };
}
export interface RestoreResult {
diff --git a/v3/@claude-flow/cli/src/services/worker-daemon.ts b/v3/@claude-flow/cli/src/services/worker-daemon.ts
index 55ca9977a7..75551aa2b0 100644
--- a/v3/@claude-flow/cli/src/services/worker-daemon.ts
+++ b/v3/@claude-flow/cli/src/services/worker-daemon.ts
@@ -1913,6 +1913,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) {
const message = error instanceof Error ? error.message : String(error);