π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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);