@claude-flow/cli 3.55.0 → 3.56.0

package/dist/src/memory/append-conditions.d.ts

@@ -0,0 +1,28 @@
+export type AppendCondition = {
+    namespace: string;
+} & ({
+    key: string;
+    sha256: string;
+    latestPrefix?: string;
+} | {
+    absent: true;
+    latestPrefix: string;
+} | {
+    keysSha256: string;
+    count: number;
+});
+export declare class AppendConditionFailed extends Error {
+}
+export declare function validateAppendConditions(input: unknown): AppendCondition[];
+interface NativeReader {
+    prepare(sql: string): {
+        all(...parameters: string[]): Array<{
+            key: string;
+            content: string;
+            status: string | null;
+        }>;
+    };
+}
+export declare function assertAppendConditions(db: NativeReader, conditions: AppendCondition[]): void;
+export {};
+//# sourceMappingURL=append-conditions.d.ts.map

package/dist/src/memory/append-conditions.js

@@ -0,0 +1,56 @@
+/** Native append predicates checked in the SAME write transaction as an immutable insert. */
+import { createHash } from 'node:crypto';
+export class AppendConditionFailed extends Error {
+}
+const text = (value, limit) => typeof value === 'string' && value.length > 0 && value.length <= limit;
+const digest = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+export function validateAppendConditions(input) {
+    if (!Array.isArray(input) || input.length < 1 || input.length > 8)
+        throw new TypeError('append conditions must contain 1-8 predicates');
+    return input.map(condition => {
+        if (!condition || typeof condition !== 'object' || Array.isArray(condition))
+            throw new TypeError('invalid append condition');
+        const row = condition;
+        const fields = Object.keys(row).sort().join(',');
+        const validRecord = ['key,namespace,sha256', 'key,latestPrefix,namespace,sha256'].includes(fields)
+            && text(row.key, 1024) && digest(row.sha256) && (row.latestPrefix === undefined || text(row.latestPrefix, 1024));
+        const validAbsent = fields === 'absent,latestPrefix,namespace' && row.absent === true && text(row.latestPrefix, 1024);
+        const validKeys = fields === 'count,keysSha256,namespace' && digest(row.keysSha256)
+            && Number.isSafeInteger(row.count) && row.count >= 0 && row.count <= 100_000;
+        if (!text(row.namespace, 256) || !(validRecord || validAbsent || validKeys))
+            throw new TypeError('invalid append condition');
+        return row;
+    });
+}
+const sha = (value) => createHash('sha256').update(value).digest('hex');
+export function assertAppendConditions(db, conditions) {
+    for (const condition of conditions) {
+        if ('keysSha256' in condition) {
+            const rows = db.prepare("SELECT key FROM memory_entries WHERE namespace = ? AND (status = 'active' OR status IS NULL)")
+                .all(condition.namespace);
+            const keys = rows.map(row => row.key).sort();
+            if (keys.length !== condition.count || sha(JSON.stringify(keys)) !== condition.keysSha256) {
+                throw new AppendConditionFailed('immutable append rejected: namespace membership changed');
+            }
+            continue;
+        }
+        if ('key' in condition) {
+            const rows = db.prepare('SELECT key, content, status FROM memory_entries WHERE namespace = ? AND key = ?')
+                .all(condition.namespace, condition.key);
+            if (rows.length !== 1 || !['active', null].includes(rows[0].status)
+                || typeof rows[0].content !== 'string' || sha(rows[0].content) !== condition.sha256) {
+                throw new AppendConditionFailed('immutable append rejected: expected parent/authority bytes changed or absent');
+            }
+        }
+        if (condition.latestPrefix !== undefined) {
+            // Include tombstones: deleting a new authority slot must never rewind to an older authority.
+            const pattern = condition.latestPrefix.replace(/[\\%_]/g, character => `\\${character}`) + '%';
+            const latest = db.prepare("SELECT key, content, status FROM memory_entries WHERE namespace = ? AND key LIKE ? ESCAPE '\\' ORDER BY key COLLATE BINARY DESC LIMIT 1")
+                .all(condition.namespace, pattern);
+            if ('absent' in condition ? latest.length !== 0 : latest.length !== 1 || latest[0].key !== condition.key) {
+                throw new AppendConditionFailed('immutable append rejected: newer parent/authority slot exists');
+            }
+        }
+    }
+}
+//# sourceMappingURL=append-conditions.js.map

package/dist/src/memory/graph-edge-writer.d.ts

@@ -29,6 +29,15 @@
  *
  * @module v3/cli/memory/graph-edge-writer
  */
+/**
+ * True iff the memory.db bridge at `customDbPath` (or the default location)
+ * is currently RFE1-encrypted-at-rest. Callers that receive `null` from
+ * getBridgeDb()/insertGraphEdge() can use this to avoid recommending the
+ * destructive `memory init` command for this specific, non-corrupt case.
+ */
+export declare function isBridgeDbEncryptedAtRest(customDbPath?: string): boolean;
+/** Test-only: clear the once-per-path warning dedup set. */
+export declare function _resetRfe1WarningFlag(): void;
 /**
  * Checkpoint and close the cached handle if it is open (optionally only if it
  * is open on `dbPath`). Returns true if a handle was released. Never throws.

package/dist/src/memory/graph-edge-writer.js

@@ -35,6 +35,87 @@ import * as crypto from 'crypto';
 import { getMemoryRoot } from './memory-initializer.js';
 import { encodeEmbedding } from './embedding-quantization.js';
 import { loadBetterSqlite3 } from './shared-sqlite.js';
+import { isEncryptedBlob } from '../encryption/vault.js';
+// ============================================================================
+// #2889 — RFE1 encryption-at-rest guard
+// ============================================================================
+//
+// When CLAUDE_FLOW_ENCRYPT_AT_REST is on, memory.db is an opaque RFE1 blob
+// (see encryption/vault.ts). `new BetterSqlite3(dbPath)` has no RFE1 sniff
+// and throws SQLITE_NOTADB on it, which the generic catch below swallows —
+// indistinguishable from genuine corruption, a missing native module, or a
+// permissions failure. That ambiguity is what let #2889 happen: nothing
+// stopped a caller from concluding the store was broken and running the
+// destructive `memory init`, which creates a fresh EMPTY store instead of
+// using the existing encrypted data.
+//
+// Fix: sniff the header bytes (never buffer the whole file — memory.db can
+// be multi-GB) before attempting the native open. If it's RFE1-encrypted,
+// skip the native open (it would only throw) and warn once per distinct
+// dbPath (not once per process — a process can legitimately touch more
+// than one encrypted store via a custom `dbPath` argument).
+/** Read just the first `len` bytes of a file without loading the whole file
+ * into memory. Mirrors the pattern in commands/doctor.ts's readHeaderBytes
+ * (not imported from there — this is a memory-layer module and must not
+ * depend on the command layer). */
+function readHeaderBytes(filePath, len) {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        const buf = Buffer.alloc(len);
+        const bytesRead = fs.readSync(fd, buf, 0, len, 0);
+        return buf.subarray(0, bytesRead);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+// RFE1 wire format is magic(4) + iv(12) + ciphertext(N) + tag(16); the
+// shortest possible blob is 32 bytes. 64 gives headroom.
+const ENCRYPTION_SNIFF_LEN = 64;
+/** True iff `filePath` is a legitimately RFE1-encrypted-at-rest file. A read
+ * failure (permissions, races) is treated as "not encrypted" — the caller's
+ * own open/query error handling still runs right after. */
+function isRfe1EncryptedAtRest(filePath) {
+    try {
+        return isEncryptedBlob(readHeaderBytes(filePath, ENCRYPTION_SNIFF_LEN));
+    }
+    catch {
+        return false;
+    }
+}
+// Keyed by resolved path (not a single process-wide boolean) — a process
+// that touches more than one RFE1-encrypted dbPath (a custom `dbPath` passed
+// to insertGraphEdge/queryEdgesBySource/countGraphEdges, or any multi-store
+// scenario) must still get the warning for EACH distinct path, not just the
+// first one it happens to see.
+const _warnedRfe1EncryptedPaths = new Set();
+function warnRfe1EncryptedOnce(dbPath) {
+    const resolved = path.resolve(dbPath);
+    if (_warnedRfe1EncryptedPaths.has(resolved))
+        return;
+    _warnedRfe1EncryptedPaths.add(resolved);
+    // eslint-disable-next-line no-console
+    console.error(`[graph-edge-writer] ${dbPath} is encrypted at rest (CLAUDE_FLOW_ENCRYPT_AT_REST). ` +
+        'The native graph-edge bridge cannot open an RFE1-encrypted store directly — ' +
+        'this is a known limitation, not corruption. Your existing data is NOT lost ' +
+        'or damaged. Do NOT run `memory init` in response to this — that would create ' +
+        'a fresh, empty store instead of using your existing encrypted data. ' +
+        'See #2889 (https://github.com/ruvnet/ruflo/issues/2889) for details and recovery options.');
+}
+/**
+ * True iff the memory.db bridge at `customDbPath` (or the default location)
+ * is currently RFE1-encrypted-at-rest. Callers that receive `null` from
+ * getBridgeDb()/insertGraphEdge() can use this to avoid recommending the
+ * destructive `memory init` command for this specific, non-corrupt case.
+ */
+export function isBridgeDbEncryptedAtRest(customDbPath) {
+    const dbPath = customDbPath ?? path.join(getMemoryRoot(), 'memory.db');
+    return fs.existsSync(dbPath) && isRfe1EncryptedAtRest(dbPath);
+}
+/** Test-only: clear the once-per-path warning dedup set. */
+export function _resetRfe1WarningFlag() {
+    _warnedRfe1EncryptedPaths.clear();
+}
 // ============================================================================
 // Lazy-cached better-sqlite3 db handle
 // ============================================================================
@@ -134,6 +215,15 @@ export async function getBridgeDb(customDbPath, opts) {
         const dbExists = fs.existsSync(dbPath);
         if (!dbExists && !createIfMissing)
             return null;
+        // #2889 — detect RFE1 encryption-at-rest before even attempting the
+        // native open: `new BetterSqlite3(dbPath)` on an encrypted file would
+        // only throw SQLITE_NOTADB, caught by the generic catch below with no
+        // way to tell it apart from genuine corruption. Skip straight to a
+        // clear, actionable warning instead.
+        if (dbExists && isRfe1EncryptedAtRest(dbPath)) {
+            warnRfe1EncryptedOnce(dbPath);
+            return null;
+        }
         // Ensure parent dir exists for createIfMissing case.
         if (!dbExists && createIfMissing) {
             const dir = path.dirname(dbPath);

package/dist/src/memory/memory-bridge.d.ts

@@ -16,6 +16,7 @@
  *
  * @module v3/cli/memory-bridge
  */
+import { type AppendCondition } from './append-conditions.js';
 /**
  * #3024: AgentDB's optional native controller stack can abort the whole Node
  * process on Windows during registry initialization (a Rust allocation panic),
@@ -67,6 +68,9 @@ export declare function bridgeStoreEntry(options: {
     ttl?: number;
     dbPath?: string;
     upsert?: boolean;
+    requireNative?: boolean;
+    appendOnly?: boolean;
+    appendConditions?: AppendCondition[];
     /** ADR-323: defaults to 'unknown' when omitted. */
     provenanceType?: string;
 }): Promise<{

package/dist/src/memory/memory-bridge.js

@@ -16,6 +16,7 @@
  *
  * @module v3/cli/memory-bridge
  */
+import { AppendConditionFailed, assertAppendConditions, validateAppendConditions } from './append-conditions.js';
 import { liveMemoryRowSql } from './live-memory-row.js';
 import { resolveAgentdbBetterSqlite3 } from './shared-sqlite.js';
 import { encodeEmbeddingQ8, MAX_LIST_EMBEDDINGS } from './embedding-q8.js';
@@ -1025,13 +1026,24 @@ export async function bridgeStoreEntry(options) {
     const ctx = getDb(registry);
     if (!ctx)
         return null;
+    if (options.appendOnly && !options.requireNative) {
+        return { success: false, id: '', error: 'Immutable append requires a native writer' };
+    }
+    if (options.appendConditions && (!options.requireNative || !options.appendOnly)) {
+        return { success: false, id: "", error: "Conditional append requires native append-only storage" };
+    }
+    if (options.requireNative && (ctx.agentdb?.isWasm === true || typeof ctx.db.inTransaction !== 'boolean'
+        || typeof ctx.db.transaction !== 'function' || ctx.db.memory !== false || typeof ctx.db.name !== 'string'
+        || !ctx.db.name || canonicalDbPath(ctx.db.name) !== canonicalDbPath(options.dbPath))) {
+        return { success: false, id: '', error: 'Native memory writer required; refusing non-native bridge driver' };
+    }
     try {
         const { key, value, namespace = 'default', tags = [], ttl } = options;
         let provenanceType = options.provenanceType ?? 'unknown';
         // An omitted type on an upsert means "update the value", not "erase the
         // existing trust label". New rows still receive the backward-compatible
         // unknown default.
-        if (options.upsert && options.provenanceType === undefined) {
+        if (options.upsert && !options.appendOnly && options.provenanceType === undefined) {
             try {
                 const existing = ctx.db.prepare('SELECT provenance_type FROM memory_entries WHERE namespace = ? AND key = ? LIMIT 1').get(namespace, key);
                 provenanceType = existing?.provenance_type || 'unknown';
@@ -1089,7 +1101,12 @@ export async function bridgeStoreEntry(options) {
         //                                       below → typed "already exists"
         //                                       error, NEVER a null demotion).
         // Upsert path (INSERT OR REPLACE) is unchanged.
-        const insertSql = options.upsert
+        const immutableInsertSql = `INSERT INTO memory_entries (
+          id, key, namespace, content, type,
+          embedding, embedding_dimensions, embedding_model,
+          tags, metadata, provenance_type, created_at, updated_at, expires_at, status
+        ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')`;
+        const insertSql = options.appendOnly ? immutableInsertSql : options.upsert
             ? `INSERT OR REPLACE INTO memory_entries (
           id, key, namespace, content, type,
           embedding, embedding_dimensions, embedding_model,
@@ -1126,7 +1143,28 @@ export async function bridgeStoreEntry(options) {
         }
         catch { /* vector_indexes may not exist on legacy DBs — fall through */ }
         const stmt = ctx.db.prepare(insertSql);
-        const runResult = stmt.run(id, key, namespace, value, embeddingJson, dimensions || null, model, tags.length > 0 ? JSON.stringify(tags) : null, '{}', provenanceType, now, now, ttl ? now + (ttl * 1000) : null);
+        const insert = () => stmt.run(id, key, namespace, value, embeddingJson, dimensions || null, model, tags.length > 0 ? JSON.stringify(tags) : null, '{}', provenanceType, now, now, ttl ? now + (ttl * 1000) : null);
+        let runResult;
+        try {
+            runResult = options.appendOnly
+                ? ctx.db.transaction(() => {
+                    // Legacy native tables may predate UNIQUE(namespace,key). Serialize the exact
+                    // logical-slot check with INSERT, including tombstones, instead of trusting DDL.
+                    if (ctx.db.prepare('SELECT key FROM memory_entries WHERE namespace = ? AND key = ?').all(namespace, key).length) {
+                        throw new AppendConditionFailed('immutable append rejected: logical key already exists');
+                    }
+                    if (options.appendConditions)
+                        assertAppendConditions(ctx.db, validateAppendConditions(options.appendConditions));
+                    return insert();
+                }).immediate()
+                : insert();
+        }
+        catch (error) {
+            if (error instanceof AppendConditionFailed || error instanceof TypeError) {
+                return { success: false, id: '', error: error.message };
+            }
+            throw error;
+        }
         // A completed native write proves the bridge is currently healthy. Do not
         // retain a diagnostic from an earlier transient failure and append it to a
         // later, unrelated sql.js fallback refusal.
@@ -1143,18 +1181,21 @@ export async function bridgeStoreEntry(options) {
                 error: `key "${key}" already exists in namespace "${namespace}" — pass upsert=true (--upsert on the CLI) to update it`,
             };
         }
+        // A non-vector immutable INSERT cannot change the vector count, even with concurrent
+        // writers. Unlike historical strict mode, it never resurrects a vector tombstone.
         // #2558: keep `vector_indexes.total_vectors` accurate so status/tooling
         // stop reporting "HNSW index: 0 vectors" while embedded entries exist.
-        try {
-            ctx.db
-                .prepare(`UPDATE vector_indexes SET
+        if (!(options.appendOnly && embeddingJson === null))
+            try {
+                ctx.db
+                    .prepare(`UPDATE vector_indexes SET
              total_vectors = (SELECT COUNT(*) FROM memory_entries
                               WHERE namespace = ? AND embedding IS NOT NULL),
              updated_at = ?
            WHERE name = ?`)
-                .run(namespace, now, namespace);
-        }
-        catch { /* vector_indexes may not exist on legacy DBs — non-fatal */ }
+                    .run(namespace, now, namespace);
+            }
+            catch { /* vector_indexes may not exist on legacy DBs — non-fatal */ }
         // #2558: better-sqlite3 opens the DB in WAL mode and, for the small write
         // volumes typical of CLI usage, may never reach the auto-checkpoint
         // threshold — leaving committed rows only in the -wal file. WAL-blind

package/dist/src/memory/memory-initializer.d.ts

@@ -8,6 +8,7 @@
  *
  * @module v3/cli/memory-initializer
  */
+import type { AppendCondition } from './append-conditions.js';
 import { type EmbeddingQ8 } from './embedding-q8.js';
 /**
  * ADR-323 — typed memory provenance. Distinguishes WHO/WHAT wrote a memory
@@ -442,6 +443,9 @@ export declare function storeEntry(options: {
     ttl?: number;
     dbPath?: string;
     upsert?: boolean;
+    requireNative?: boolean;
+    appendOnly?: boolean;
+    appendConditions?: AppendCondition[];
     /** ADR-323: defaults to 'unknown' when omitted. */
     provenanceType?: string;
 }): Promise<{

package/dist/src/memory/memory-initializer.js

@@ -1,14 +1,5 @@
-/**
- * V3 Memory Initializer
- * Properly initializes the memory database with sql.js (WASM SQLite)
- * Includes pattern tables, vector embeddings, migration state tracking
- *
- * ADR-053: Routes through ControllerRegistry → AgentDB v3 when available,
- * falls back to raw sql.js for backwards compatibility.
- *
- * @module v3/cli/memory-initializer
- */
 import { loadBetterSqlite3 } from './shared-sqlite.js';
+import { resolveMemoryRoot } from './memory-root.js';
 import { liveMemoryRowSql } from './live-memory-row.js';
 import { encodeEmbeddingQ8, MAX_LIST_EMBEDDINGS } from './embedding-q8.js';
 import * as fs from 'fs';
@@ -59,25 +50,88 @@ function isRuvectorCoreResolvable() {
     return _ruvectorCoreResolvable;
 }
 /**
- * #2735 — before a whole-image sql.js read-modify-persist (export() +
- * rename over the live database path), refuse if there is evidence of a
- * live native (better-sqlite3) WAL connection: `-wal`/`-shm` sidecar files
- * on disk. A native connection in WAL mode keeps its sidecars present for
- * its entire lifetime (removed only on the last connection's clean close),
- * so their presence is strong evidence of a live native holder — and their
- * absence means the image is a clean, checkpointed, standalone file that
- * sql.js can safely read-modify-write.
+ * #2735 / #3161 — before a whole-image sql.js read-modify-persist (export() +
+ * rename over the live database path), refuse if a native (better-sqlite3)
+ * WAL connection is actually LIVE. `-wal`/`-shm` sidecar presence alone is
+ * not proof of that: #3161 found `ruflo doctor`'s readonly diagnostic
+ * connections leave orphaned sidecars behind after a plain `.close()` (WAL
+ * mode does not checkpoint on close unless the closing connection was the
+ * last holder in a state that triggers one), permanently blocking every
+ * later write in that project.
+ *
+ * Liveness is probed in two steps, because a single `wal_checkpoint`
+ * busy-check is not sufficient on its own:
  *
- * This is a scoped-down version of the fuller "scan live process holders"
- * design discussed in #2735: it does not close the narrow assess-then-write
- * race (a native opener could still attach in the gap between this check
- * and the write), but it directly closes the demonstrated corruption
- * mechanism — a whole-image write proceeding while an ALREADY-OPEN native
- * connection's sidecars are on disk — with no platform-specific process
- * scanning. Fails closed (treats a stat error as "unsafe") because this is
- * a safety gate, not a best-effort probe.
+ *  1. Open our own probe connection and run `PRAGMA wal_checkpoint(TRUNCATE)`.
+ *     `busy !== 0` means another connection genuinely holds a lock blocking
+ *     the checkpoint RIGHT NOW (an open transaction) — unsafe, refuse
+ *     immediately. This also truncates a genuinely-orphaned WAL as a side
+ *     effect.
+ *  2. If `busy === 0`, close our probe connection and re-check whether the
+ *     sidecars are still on disk. SQLite only deletes `-wal`/`-shm` when the
+ *     LAST connection to the database closes. If nothing else is attached,
+ *     OUR close is that last close and the sidecars vanish — safe, proceed.
+ *     If they are still present after our own close, some OTHER connection
+ *     is still attached (even idle, holding no lock — e.g. a foreign native
+ *     handle that already finished its last statement), so step 1's
+ *     busy-check alone would have missed it. Refuse.
+ *
+ * Step 2 is what makes this safe against an idle-but-attached native
+ * connection (an open handle holding no lock does not block checkpointing,
+ * so step 1 alone would report "safe" even though a real holder is still
+ * attached) without resorting to platform-specific process scanning.
+ *
+ * The common case (no sidecars at all) stays a couple of cheap `existsSync`
+ * calls — a DB connection is only opened when a sidecar is actually present
+ * to investigate.
+ *
+ * This is still a scoped-down version of the fuller "scan live process
+ * holders" design discussed in #2735: it does not close the narrow
+ * assess-then-write race (a native opener could still attach in the gap
+ * between this check and the write), but it directly closes the
+ * demonstrated corruption mechanism — a whole-image write proceeding while
+ * an ALREADY-OPEN native connection genuinely holds the file — with no
+ * platform-specific process scanning. Fails closed (treats any probe error
+ * as "unsafe") because this is a safety gate, not a best-effort probe.
  */
-function hasNativeWalSidecars(dbPath) {
+async function hasNativeWalSidecars(dbPath) {
+    try {
+        if (!fs.existsSync(`${dbPath}-wal`) && !fs.existsSync(`${dbPath}-shm`)) {
+            return false;
+        }
+    }
+    catch {
+        return true;
+    }
+    let db;
+    try {
+        const Database = await loadBetterSqlite3();
+        const opened = new Database(dbPath);
+        db = opened;
+        // Report busy immediately instead of retrying for the driver's default
+        // (multi-second) busy_timeout — a live holder's checkpoint-blocking
+        // lock is a steady-state fact at probe time, not a transient we should
+        // wait out, and this is a safety gate on a hot write path.
+        opened.pragma('busy_timeout = 0');
+        const [{ busy }] = opened.pragma('wal_checkpoint(TRUNCATE)');
+        if (busy !== 0)
+            return true;
+    }
+    catch {
+        return true;
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            // best-effort
+        }
+    }
+    // Nothing was mid-transaction at probe time, and our own (now-closed)
+    // probe connection just truncated the WAL. If the sidecars are still
+    // here, another connection is still attached and kept them alive through
+    // our close.
     try {
         return fs.existsSync(`${dbPath}-wal`) || fs.existsSync(`${dbPath}-shm`);
     }
@@ -123,34 +177,7 @@ let _memoryRootCache;
 export function getMemoryRoot() {
     if (_memoryRootCache !== undefined)
         return _memoryRootCache;
-    // 1. Env var
-    const envPath = process.env.CLAUDE_FLOW_MEMORY_PATH;
-    if (envPath && envPath.trim().length > 0) {
-        _memoryRootCache = path.resolve(envPath);
-        return _memoryRootCache;
-    }
-    // 2. Config file (claude-flow.config.json)
-    const configCandidates = [
-        path.resolve(process.cwd(), 'claude-flow.config.json'),
-        path.resolve(process.cwd(), '.claude-flow', 'config.json'),
-    ];
-    for (const configPath of configCandidates) {
-        if (!fs.existsSync(configPath))
-            continue;
-        try {
-            const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-            const fromConfig = raw?.memory?.persistPath ?? raw?.memory?.path;
-            if (typeof fromConfig === 'string' && fromConfig.trim().length > 0) {
-                _memoryRootCache = path.resolve(fromConfig);
-                return _memoryRootCache;
-            }
-        }
-        catch {
-            /* malformed config — fall through to default */
-        }
-    }
-    // 3. Default
-    _memoryRootCache = path.resolve(process.cwd(), '.swarm');
+    _memoryRootCache = resolveMemoryRoot(process.cwd());
     return _memoryRootCache;
 }
 /** For tests + the `memory configure` flow that mutates the config at runtime. */
@@ -2532,6 +2559,9 @@ export async function verifyMemoryInit(dbPath, options) {
  * This bypasses MCP and writes directly to the database
  */
 export async function storeEntry(options) {
+    if (options.appendOnly && !options.requireNative) {
+        return { success: false, id: '', error: 'Immutable append requires a native writer' };
+    }
     // ADR-323: validate before touching either backend so an invalid value
     // gets one clear error instead of a raw SQLite CHECK-constraint failure
     // from whichever path (bridge vs sql.js) happens to run.
@@ -2563,8 +2593,12 @@ export async function storeEntry(options) {
             return bridgeResult;
         }
     }
+    if (options.requireNative || options.appendConditions) {
+        return { success: false, id: '', error: 'Native memory writer required; refusing whole-image sql.js fallback' };
+    }
     // Fallback: raw sql.js
-    const { key, value, namespace = 'default', generateEmbeddingFlag = true, tags = [], ttl, dbPath: customPath, upsert = false, provenanceType } = options;
+    const { key, value, namespace = 'default', generateEmbeddingFlag = true, tags = [], ttl, dbPath: customPath, upsert: requestedUpsert = false, provenanceType } = options;
+    const upsert = requestedUpsert && !options.appendOnly;
     const swarmDir = getMemoryRoot();
     const dbPath = customPath ? path.resolve(customPath) : path.join(swarmDir, 'memory.db');
     try {
@@ -2578,7 +2612,7 @@ export async function storeEntry(options) {
         // race). This check gates ensureSchemaColumns()'s own whole-image
         // write below too, not just this function's.
         await releaseOwnNativeHandle(dbPath);
-        if (hasNativeWalSidecars(dbPath)) {
+        if (await hasNativeWalSidecars(dbPath)) {
             return {
                 success: false,
                 id: '',
@@ -2985,7 +3019,7 @@ export async function listEntries(options) {
         // Listing can migrate/backfill the schema, so it is also a whole-image
         // writer. The newly selected native mirror may still have a live WAL.
         await releaseOwnNativeHandle(dbPath);
-        if (hasNativeWalSidecars(dbPath)) {
+        if (await hasNativeWalSidecars(dbPath)) {
             return { success: false, entries: [], total: 0, error: await walRefusalError('read/write') };
         }
         // Ensure schema has all required columns (migration for older DBs)
@@ -3097,7 +3131,7 @@ export async function getEntry(options) {
         // bump is itself a whole-image write, not a lightweight read, even
         // though this function's contract reads as a "get".
         await releaseOwnNativeHandle(dbPath);
-        if (hasNativeWalSidecars(dbPath)) {
+        if (await hasNativeWalSidecars(dbPath)) {
             return {
                 success: false,
                 found: false,
@@ -3217,7 +3251,7 @@ export async function deleteEntry(options) {
         // #2735 — see storeEntry's identical gate for the corruption mechanism
         // this closes.
         await releaseOwnNativeHandle(dbPath);
-        if (hasNativeWalSidecars(dbPath)) {
+        if (await hasNativeWalSidecars(dbPath)) {
             return {
                 success: false,
                 deleted: false,
@@ -3437,7 +3471,7 @@ export async function purgeNamespace(options) {
             }
             // Recheck at mutation time even when the CLI already read a preview.
             await releaseOwnNativeHandle(dbPath);
-            if (hasNativeWalSidecars(dbPath)) {
+            if (await hasNativeWalSidecars(dbPath)) {
                 return { success: false, deletedCount: 0, remainingEntries: 0, error: await walRefusalError('write') };
             }
             await ensureSchemaColumns(dbPath, options);

package/dist/src/memory/memory-root.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveMemoryRoot(cwd: string): string;
+//# sourceMappingURL=memory-root.d.ts.map

package/dist/src/memory/memory-root.js

@@ -0,0 +1,28 @@
+/** Uncached memory-directory authority for an explicit project directory. */
+import * as fs from 'fs';
+import * as path from 'path';
+export function resolveMemoryRoot(cwd) {
+    const envPath = process.env.CLAUDE_FLOW_MEMORY_PATH;
+    if (envPath && envPath.trim().length > 0)
+        return path.resolve(cwd, envPath);
+    const configCandidates = [
+        path.resolve(cwd, 'claude-flow.config.json'),
+        path.resolve(cwd, '.claude-flow', 'config.json'),
+    ];
+    for (const configPath of configCandidates) {
+        if (!fs.existsSync(configPath))
+            continue;
+        try {
+            const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            const fromConfig = raw?.memory?.persistPath ?? raw?.memory?.path;
+            if (typeof fromConfig === 'string' && fromConfig.trim().length > 0) {
+                return path.resolve(cwd, fromConfig);
+            }
+        }
+        catch {
+            /* malformed config — fall through to default */
+        }
+    }
+    return path.resolve(cwd, '.swarm');
+}
+//# sourceMappingURL=memory-root.js.map

package/dist/src/memory/sona-optimizer.d.ts

@@ -93,6 +93,8 @@ export interface SONAStats {
         agents: number;
     } | 'unavailable';
 }
+/** Agent roles supported by the SONA routing optimizer. */
+export declare function isSupportedSonaAgent(agent: string): boolean;
 /**
  * SONA Optimizer for adaptive routing based on trajectory outcomes
  *

package/dist/src/memory/sona-optimizer.js

@@ -61,6 +61,10 @@ const AGENT_TYPES = [
     'security-architect',
     'performance-engineer',
 ];
+/** Agent roles supported by the SONA routing optimizer. */
+export function isSupportedSonaAgent(agent) {
+    return AGENT_TYPES.includes(agent);
+}
 /**
  * Task keywords for pattern extraction
  */

package/dist/src/parser.js

@@ -568,6 +568,13 @@ export class CommandParser {
             if (opt.required && (flags[key] === undefined || flags[key] === '')) {
                 errors.push(`Required option missing: --${opt.name}`);
             }
+            // A value-taking option given with nothing after it (`--task`, `--key` at the end, or
+            // followed by another flag) is parsed as boolean `true`. Commands then treat `true` as
+            // the value: `hooks route --task` crashed with "task.trim is not a function" and
+            // `memory retrieve --key` looked up the key "true". Report it instead.
+            if ((opt.type === 'string' || opt.type === 'number') && flags[key] === true) {
+                errors.push(`Option --${opt.name} needs a value`);
+            }
             // Check choices
             if (opt.choices && flags[key] !== undefined) {
                 const value = String(flags[key]);