@claude-flow/cli 3.32.33 → 3.32.34

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.32.33",
+    "version": "3.32.34",
     "files": {
       "auto-memory-hook.mjs": "68be7e9a9eba7bf9c4e8a230db7bf61a243b965639f8504842799d6c6ca28762",
       "hook-handler.cjs": "50ea92a72651bdc95634f7588d56a5870963168eef5226f66ed14af3b47c8d9a",
@@ -8,6 +8,6 @@
       "statusline.cjs": "d2a0eac56d1267d8dbed2d70b09feb592299469196ec4b215909f2b052144882"
     }
   },
-  "signature": "cdCqQZfkjY3y+45Yuk0kKw2yV3CApVm21lmQcxZhYrxgAhhh2o6nAWbFnmNUJIMD/LBPmDjiy4zT9kjoRMMOCA==",
+  "signature": "i0qilACTabRlI6VORA0QyP0r4EuvJsrvtkucxia3TStgq/la250iesyKjlcHbLV/6fshZiGtPMLq1nmXLf+ZAw==",
   "algorithm": "ed25519"
 }

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 3,
-  "generatedAt": "2026-07-29T12:53:25.000Z",
-  "gitSha": "c1957608",
+  "generatedAt": "2026-07-29T13:29:39.000Z",
+  "gitSha": "c3cf2d0e",
   "catalog": {
     "agents": 164,
     "tools": 395,

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

@@ -16,6 +16,29 @@
  *
  * @module v3/cli/memory-bridge
  */
+/**
+ * Should this init-time log line be swallowed?
+ *
+ * A DEGRADATION notice never is. AgentDB logs "[AgentDB] better-sqlite3 not
+ * available, using sql.js WASM" when it falls back to WASM, and both the
+ * '[AgentDB]' and 'better-sqlite3' entries above match it — so the one line
+ * explaining why the native driver was not in use was being discarded as
+ * noise. Suppress the banners, keep the bad news.
+ */
+export declare function shouldSuppressInitLog(msg: string): boolean;
+/**
+ * Create/migrate the bridge's `memory_entries` table on `db`.
+ *
+ * Returns true when the schema is known-good, false when the database was not
+ * writable (caller then leaves it un-ensured so a later writable call retries).
+ *
+ * Exported so the ADR-323 column migration can be tested directly: the bug it
+ * fixes was invisible end-to-end, because the resulting error was swallowed and
+ * reported as an unrelated WAL-sidecar refusal.
+ */
+export declare function ensureBridgeSchema(db: {
+    exec: (sql: string) => unknown;
+}): boolean;
 /**
  * Store an entry via AgentDB v3.
  * Phase 2-5: Routes through MutationGuard → TieredCache → DB → AttestationLog.
@@ -239,8 +262,27 @@ export declare function isBridgeAvailable(dbPath?: string): Promise<boolean>;
  * Get the ControllerRegistry instance (for advanced consumers).
  */
 export declare function getControllerRegistry(dbPath?: string): Promise<any | null>;
+/**
+ * Why the bridge last declined a write, or null when it has not.
+ *
+ * Deliberately NOT gated on `bridgeAvailable === false`. A bridge that
+ * initialised fine can still fail every write — a schema mismatch throws
+ * per-operation while the registry stays healthy — and that case is exactly
+ * the one worth reporting, since the caller then demotes to a fallback whose
+ * error message describes something else entirely.
+ *
+ * Callers that surface a degraded-path error should include this so the
+ * operator learns the cause instead of only the symptom.
+ */
+export declare function getBridgeFailureReason(): string | null;
 /**
  * Shutdown the bridge and release resources.
+ *
+ * The cached state is cleared unconditionally. Previously the reset lived
+ * inside `if (registryInstance)`, so it could not clear a FAILED init — the
+ * one state that actually needs clearing, since `registryInstance` is null
+ * precisely when init failed. A process that latched `bridgeAvailable = false`
+ * therefore had no recovery path short of a restart.
  */
 export declare function shutdownBridge(): Promise<void>;
 /**

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

@@ -23,6 +23,17 @@ import { createRequire } from 'node:module';
 let registryPromise = null;
 let registryInstance = null;
 let bridgeAvailable = null;
+/**
+ * Why the bridge is unavailable, when it is.
+ *
+ * `bridgeAvailable = false` latches for the life of the process, so a single
+ * transient init failure (a slow Xenova/ONNX fetch, a locked db) routes every
+ * later write to the sql.js whole-image fallback — which then refuses whenever
+ * -wal/-shm sidecars are present. Without this, that refusal is the only
+ * symptom the caller ever sees, and it names a cause ("restore the native
+ * better-sqlite3 bridge") the caller has no way to check.
+ */
+let bridgeFailureReason = null;
 /**
  * ADR-323: reuse memory-initializer's provenance-type allowlist rather than
  * duplicating it (drift risk). Lazy CJS require for the same circular-ESM-
@@ -109,6 +120,31 @@ function getAgentDbPath() {
 function generateId(prefix) {
     return `${prefix}_${Date.now()}_${crypto.randomBytes(8).toString('hex')}`;
 }
+/** Noisy init banners that carry no operational signal. */
+const INIT_LOG_NOISE = [
+    'Transformers.js',
+    'better-sqlite3',
+    '[AgentDB]',
+    '[HNSWLibBackend]',
+    'RuVector graph',
+];
+/**
+ * Should this init-time log line be swallowed?
+ *
+ * A DEGRADATION notice never is. AgentDB logs "[AgentDB] better-sqlite3 not
+ * available, using sql.js WASM" when it falls back to WASM, and both the
+ * '[AgentDB]' and 'better-sqlite3' entries above match it — so the one line
+ * explaining why the native driver was not in use was being discarded as
+ * noise. Suppress the banners, keep the bad news.
+ */
+export function shouldSuppressInitLog(msg) {
+    const degradation = msg.includes('not available')
+        || msg.includes('falling back')
+        || msg.includes('fallback');
+    if (degradation)
+        return false;
+    return INIT_LOG_NOISE.some((needle) => msg.includes(needle));
+}
 /**
  * Lazily initialize the ControllerRegistry singleton.
  * Returns null if @claude-flow/memory is not available.
@@ -123,15 +159,12 @@ async function getRegistry(dbPath) {
             try {
                 const { ControllerRegistry } = await import('@claude-flow/memory');
                 const registry = new ControllerRegistry();
-                // Suppress noisy console.log during init
+                // Suppress noisy console.log during init — but never suppress a
+                // DEGRADATION notice (see shouldSuppressInitLog).
                 const origLog = console.log;
                 console.log = (...args) => {
                     const msg = String(args[0] ?? '');
-                    if (msg.includes('Transformers.js') ||
-                        msg.includes('better-sqlite3') ||
-                        msg.includes('[AgentDB]') ||
-                        msg.includes('[HNSWLibBackend]') ||
-                        msg.includes('RuVector graph'))
+                    if (shouldSuppressInitLog(msg))
                         return;
                     origLog.apply(console, args);
                 };
@@ -387,9 +420,14 @@ async function getRegistry(dbPath) {
                 }
                 registryInstance = registry;
                 bridgeAvailable = true;
+                bridgeFailureReason = null;
                 return registry;
             }
-            catch {
+            catch (err) {
+                // Record WHY. This latches for the process lifetime (see the
+                // bridgeFailureReason doc comment), so discarding the error here
+                // makes the resulting sql.js-fallback refusal undiagnosable.
+                bridgeFailureReason = err instanceof Error ? err.message : String(err);
                 bridgeAvailable = false;
                 registryPromise = null;
                 return null;
@@ -529,6 +567,70 @@ async function logAttestation(registry, operation, entryId, metadata) {
 // runs the CREATE…IF NOT EXISTS block at most once per handle instead of on
 // every bridge call. WeakSet so handles GC without leaking.
 const _schemaEnsuredDbs = new WeakSet();
+/**
+ * Create/migrate the bridge's `memory_entries` table on `db`.
+ *
+ * Returns true when the schema is known-good, false when the database was not
+ * writable (caller then leaves it un-ensured so a later writable call retries).
+ *
+ * Exported so the ADR-323 column migration can be tested directly: the bug it
+ * fixes was invisible end-to-end, because the resulting error was swallowed and
+ * reported as an unrelated WAL-sidecar refusal.
+ */
+export function ensureBridgeSchema(db) {
+    try {
+        db.exec(`CREATE TABLE IF NOT EXISTS memory_entries (
+      id TEXT PRIMARY KEY,
+      key TEXT NOT NULL,
+      namespace TEXT DEFAULT 'default',
+      content TEXT NOT NULL,
+      type TEXT DEFAULT 'semantic',
+      embedding TEXT,
+      embedding_model TEXT DEFAULT 'local',
+      embedding_dimensions INTEGER,
+      tags TEXT,
+      metadata TEXT,
+      owner_id TEXT,
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+      updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+      expires_at INTEGER,
+      last_accessed_at INTEGER,
+      access_count INTEGER DEFAULT 0,
+      status TEXT DEFAULT 'active',
+      provenance_type TEXT DEFAULT 'unknown',
+      UNIQUE(namespace, key)
+    )`);
+        // ADR-323 added provenance_type to bridgeStoreEntry's INSERT, and
+        // ensureSchemaColumns() backfills it on the sql.js path — the bridge path
+        // had no equivalent. `CREATE TABLE IF NOT EXISTS` is a no-op on a table
+        // created before ADR-323, so on any pre-existing database every bridge
+        // write threw "table memory_entries has no column named provenance_type",
+        // was swallowed by the catch at the end of bridgeStoreEntry(), and demoted
+        // the caller to the sql.js whole-image path — which then refused with a
+        // WAL-sidecar error naming an unrelated cause. Silent, total write loss.
+        try {
+            db.exec(`ALTER TABLE memory_entries ADD COLUMN provenance_type TEXT DEFAULT 'unknown'`);
+        }
+        catch (err) {
+            // Already present is the common case. SQLite has no ADD COLUMN IF NOT
+            // EXISTS, so attempt-and-ignore only that exact condition. Treating a
+            // read-only, locked, or corrupt database as migrated would cache a
+            // schema that bridgeStoreEntry() still cannot use.
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!/duplicate column name:\s*provenance_type/i.test(msg)) {
+                throw err;
+            }
+        }
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_ns ON memory_entries(namespace)`);
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_key ON memory_entries(key)`);
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_status ON memory_entries(status)`);
+        return true;
+    }
+    catch {
+        // Read-only database — leave it un-ensured so a writable call can retry.
+        return false;
+    }
+}
 /**
  * Get the AgentDB database handle and ensure memory_entries table exists.
  * Returns null if not available.
@@ -543,37 +645,8 @@ function getDb(registry) {
     // call (store/search/get) was pure per-op overhead. Keyed by handle via a
     // WeakSet so a new db instance re-ensures without a stale global flag.
     if (!_schemaEnsuredDbs.has(db)) {
-        try {
-            db.exec(`CREATE TABLE IF NOT EXISTS memory_entries (
-        id TEXT PRIMARY KEY,
-        key TEXT NOT NULL,
-        namespace TEXT DEFAULT 'default',
-        content TEXT NOT NULL,
-        type TEXT DEFAULT 'semantic',
-        embedding TEXT,
-        embedding_model TEXT DEFAULT 'local',
-        embedding_dimensions INTEGER,
-        tags TEXT,
-        metadata TEXT,
-        owner_id TEXT,
-        created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
-        updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
-        expires_at INTEGER,
-        last_accessed_at INTEGER,
-        access_count INTEGER DEFAULT 0,
-        status TEXT DEFAULT 'active',
-        UNIQUE(namespace, key)
-      )`);
-            // Ensure indexes
-            db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_ns ON memory_entries(namespace)`);
-            db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_key ON memory_entries(key)`);
-            db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_status ON memory_entries(status)`);
+        if (ensureBridgeSchema(db))
             _schemaEnsuredDbs.add(db);
-        }
-        catch {
-            // Table already exists or db is read-only — that's fine. Don't mark
-            // ensured on failure so a later writable call can retry.
-        }
     }
     // ─── #2256-followup: rescue agentdb.embedder when its transformers.js
     // path fell through to mock embeddings.
@@ -785,6 +858,10 @@ 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);
+        // 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.
+        bridgeFailureReason = null;
         // #2775: strict insert against an ACTIVE existing row → changes === 0
         // (the ON CONFLICT WHERE clause above suppressed the update). Surface
         // this as a typed data-level error rather than a bridge failure —
@@ -858,6 +935,11 @@ export async function bridgeStoreEntry(options) {
                 error: `key "${options.key}" already exists in namespace "${options.namespace ?? 'default'}" — pass upsert=true (--upsert on the CLI) to update it`,
             };
         }
+        // Returning null below demotes the caller to the sql.js whole-image path,
+        // whose WAL-sidecar guard then reports a cause that has nothing to do with
+        // what actually went wrong here. Record the real error so it can be
+        // surfaced alongside that guard's message.
+        bridgeFailureReason = msg;
         return null;
     }
 }
@@ -1562,8 +1644,29 @@ export async function isBridgeAvailable(dbPath) {
 export async function getControllerRegistry(dbPath) {
     return getRegistry(dbPath);
 }
+/**
+ * Why the bridge last declined a write, or null when it has not.
+ *
+ * Deliberately NOT gated on `bridgeAvailable === false`. A bridge that
+ * initialised fine can still fail every write — a schema mismatch throws
+ * per-operation while the registry stays healthy — and that case is exactly
+ * the one worth reporting, since the caller then demotes to a fallback whose
+ * error message describes something else entirely.
+ *
+ * Callers that surface a degraded-path error should include this so the
+ * operator learns the cause instead of only the symptom.
+ */
+export function getBridgeFailureReason() {
+    return bridgeFailureReason;
+}
 /**
  * Shutdown the bridge and release resources.
+ *
+ * The cached state is cleared unconditionally. Previously the reset lived
+ * inside `if (registryInstance)`, so it could not clear a FAILED init — the
+ * one state that actually needs clearing, since `registryInstance` is null
+ * precisely when init failed. A process that latched `bridgeAvailable = false`
+ * therefore had no recovery path short of a restart.
  */
 export async function shutdownBridge() {
     if (registryInstance) {
@@ -1573,10 +1676,11 @@ export async function shutdownBridge() {
         catch {
             // Best-effort
         }
-        registryInstance = null;
-        registryPromise = null;
-        bridgeAvailable = null;
     }
+    registryInstance = null;
+    registryPromise = null;
+    bridgeAvailable = null;
+    bridgeFailureReason = null;
 }
 // ===== Phase 3: ReasoningBank pattern operations =====
 /**

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

@@ -176,6 +176,32 @@ async function getBridge() {
         return null;
     }
 }
+/**
+ * Build the WAL-sidecar refusal message, naming the bridge failure when one
+ * was recorded.
+ *
+ * The refusal tells the operator to "restore the native better-sqlite3
+ * bridge" but, on its own, gives them no way to discover why it is down —
+ * and the usual cause is a latched init failure inside the bridge, not a
+ * missing better-sqlite3. Appending the recorded reason turns an unactionable
+ * message into a diagnosis.
+ */
+async function walRefusalError(operation) {
+    const base = 'memory database has an active native WAL connection '
+        + '(found -wal/-shm sidecar files) — refusing an unsafe sql.js '
+        + `whole-image ${operation}. Retry once the native writer completes, or `
+        + 'restore the native better-sqlite3 bridge.';
+    try {
+        const bridge = await getBridge();
+        const reason = bridge?.getBridgeFailureReason?.();
+        if (reason)
+            return `${base} Bridge unavailable: ${reason}`;
+    }
+    catch {
+        // Diagnostics must never mask the refusal they annotate.
+    }
+    return base;
+}
 /**
  * Enhanced schema with pattern confidence, temporal decay, versioning
  * Vector embeddings enabled for semantic search
@@ -2382,10 +2408,7 @@ export async function storeEntry(options) {
             return {
                 success: false,
                 id: '',
-                error: 'memory database has an active native WAL connection ' +
-                    '(found -wal/-shm sidecar files) — refusing an unsafe sql.js ' +
-                    'whole-image write. Retry once the native writer completes, or ' +
-                    'restore the native better-sqlite3 bridge.',
+                error: await walRefusalError('write'),
             };
         }
         // Ensure schema has all required columns (migration for older DBs)
@@ -2868,10 +2891,7 @@ export async function getEntry(options) {
             return {
                 success: false,
                 found: false,
-                error: 'memory database has an active native WAL connection ' +
-                    '(found -wal/-shm sidecar files) — refusing an unsafe sql.js ' +
-                    'whole-image read/write. Retry once the native writer completes, ' +
-                    'or restore the native better-sqlite3 bridge.',
+                error: await walRefusalError('read/write'),
             };
         }
         // Ensure schema has all required columns (migration for older DBs)
@@ -2994,10 +3014,7 @@ export async function deleteEntry(options) {
                 key,
                 namespace,
                 remainingEntries: 0,
-                error: 'memory database has an active native WAL connection ' +
-                    '(found -wal/-shm sidecar files) — refusing an unsafe sql.js ' +
-                    'whole-image write. Retry once the native writer completes, or ' +
-                    'restore the native better-sqlite3 bridge.',
+                error: await walRefusalError('write'),
             };
         }
         // Ensure schema has all required columns (migration for older DBs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.32.33",
+  "version": "3.32.34",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",