@claude-flow/cli 3.32.33 → 3.32.35

package/dist/src/mcp-tools/swarm-tools.js

@@ -4,13 +4,16 @@
  * Tool definitions for swarm coordination with file-based state persistence.
  * Replaces previous stub implementations with real state tracking.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier } from './validate-input.js';
+import { createApscState, isApscAgentEligible, normalizeApscConfig, recordApscSignal, } from '../services/pheromone-adaptive.js';
 // Swarm state persistence
 const SWARM_DIR = '.claude-flow/swarm';
 const SWARM_STATE_FILE = 'swarm-state.json';
+const SWARM_STATE_LOCK = 'swarm-state.lock';
+const SWARM_LOCK_STALE_MS = 10_000;
 function getSwarmDir() {
     return join(getProjectCwd(), SWARM_DIR);
 }
@@ -103,12 +106,101 @@ export function loadSwarmStore() {
 }
 export function saveSwarmStore(store) {
     ensureSwarmDir();
-    writeFileSync(getSwarmStatePath(), JSON.stringify(store, null, 2), 'utf-8');
+    const target = getSwarmStatePath();
+    const temporary = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        writeFileSync(temporary, JSON.stringify(store, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        renameSync(temporary, target);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch { /* already renamed or never created */ }
+        throw error;
+    }
+}
+function withSwarmStoreLock(operation) {
+    ensureSwarmDir();
+    const lockPath = join(getSwarmDir(), SWARM_STATE_LOCK);
+    let descriptor;
+    const waiter = new Int32Array(new SharedArrayBuffer(4));
+    for (let attempt = 0; attempt < 100; attempt++) {
+        try {
+            descriptor = openSync(lockPath, 'wx', 0o600);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > SWARM_LOCK_STALE_MS) {
+                    unlinkSync(lockPath);
+                    continue;
+                }
+            }
+            catch { /* another writer released it */ }
+            Atomics.wait(waiter, 0, 0, 10);
+        }
+    }
+    if (descriptor === undefined)
+        throw new Error('swarm state is busy; retry the outcome update');
+    try {
+        return operation();
+    }
+    finally {
+        try {
+            closeSync(descriptor);
+        }
+        catch { /* best effort */ }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* best effort */ }
+    }
 }
 // Input validation
 const VALID_TOPOLOGIES = new Set([
-    'hierarchical', 'mesh', 'hierarchical-mesh', 'ring', 'star', 'hybrid', 'adaptive',
+    'hierarchical', 'mesh', 'hierarchical-mesh', 'ring', 'star', 'hybrid', 'adaptive', 'pheromone-adaptive',
 ]);
+function latestRunningSwarm(store) {
+    return Object.values(store.swarms)
+        .filter((swarm) => swarm.status === 'running')
+        .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())[0];
+}
+function apscStateOf(swarm) {
+    if (!swarm || swarm.topology !== 'pheromone-adaptive')
+        return undefined;
+    const state = swarm.config.apscState;
+    return state?.schemaVersion ? state : undefined;
+}
+/** Shared by hooks_post-task so outcome labels immediately drive APSC. */
+export function recordSwarmPheromoneSignal(signal) {
+    return withSwarmStoreLock(() => {
+        const store = loadSwarmStore();
+        const swarm = latestRunningSwarm(store);
+        const current = apscStateOf(swarm);
+        if (!swarm || !current)
+            return { active: false, reason: 'no running pheromone-adaptive swarm' };
+        const result = recordApscSignal(current, signal);
+        swarm.config.apscState = result.state;
+        swarm.updatedAt = new Date().toISOString();
+        saveSwarmStore(store);
+        return { active: true, swarmId: swarm.swarmId, decision: result.decision };
+    });
+}
+/** Scheduling gate used by agent_execute. Dry-run topologies remain eligible. */
+export function pheromoneAgentEligibility(agentId) {
+    const current = apscStateOf(latestRunningSwarm(loadSwarmStore()));
+    if (!current)
+        return { eligible: true, active: false };
+    const eligible = isApscAgentEligible(current, agentId);
+    return {
+        eligible,
+        active: true,
+        reason: eligible ? undefined : 'agent suspended by pheromone-adaptive scheduling gate',
+    };
+}
 export const swarmTools = [
     {
         name: 'swarm_init',
@@ -117,7 +209,7 @@ export const swarmTools = [
         inputSchema: {
             type: 'object',
             properties: {
-                topology: { type: 'string', description: 'Swarm topology type (hierarchical, mesh, hierarchical-mesh, ring, star, hybrid, adaptive)' },
+                topology: { type: 'string', description: 'Swarm topology type (hierarchical, mesh, hierarchical-mesh, ring, star, hybrid, adaptive, pheromone-adaptive)' },
                 maxAgents: { type: 'number', description: 'Maximum number of agents (1-50)' },
                 strategy: { type: 'string', description: 'Agent strategy (specialized, balanced, adaptive)' },
                 config: { type: 'object', description: 'Additional swarm configuration' },
@@ -145,6 +237,19 @@ export const swarmTools = [
                     error: `Invalid topology: ${topology}. Valid: ${[...VALID_TOPOLOGIES].join(', ')}`,
                 };
             }
+            let apscState;
+            if (topology === 'pheromone-adaptive') {
+                try {
+                    const apscConfig = normalizeApscConfig((config.apsc ?? {}));
+                    if (apscConfig.minActiveAgents > maxAgents) {
+                        return { success: false, error: 'APSC minActiveAgents cannot exceed maxAgents' };
+                    }
+                    apscState = createApscState(apscConfig);
+                }
+                catch (error) {
+                    return { success: false, error: `Invalid APSC config: ${error.message}` };
+                }
+            }
             const swarmId = `swarm-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
             const now = new Date().toISOString();
             const swarmState = {
@@ -161,12 +266,14 @@ export const swarmTools = [
                     communicationProtocol: config.communicationProtocol || 'message-bus',
                     autoScaling: config.autoScaling ?? true,
                     consensusMechanism: config.consensusMechanism || 'majority',
+                    ...(apscState ? { apscState } : {}),
                 },
                 createdAt: now,
                 updatedAt: now,
-                // #1799 — record host PID so subsequent loads can detect orphans
-                // when this process exits without a graceful swarm_shutdown.
-                pid: process.pid,
+                // A normal CLI invocation exits immediately after creating this
+                // coordination record; its PID is therefore not the swarm lifetime.
+                // Long-lived hosts may opt into PID ownership explicitly.
+                pid: config.trackHostProcess === true ? process.pid : undefined,
             };
             const store = loadSwarmStore();
             store.swarms[swarmId] = swarmState;
@@ -180,6 +287,62 @@ export const swarmTools = [
                 initializedAt: now,
                 config: swarmState.config,
                 persisted: true,
+                apsc: apscState ? {
+                    dryRun: apscState.config.dryRun,
+                    minActiveAgents: apscState.config.minActiveAgents,
+                    minSamples: apscState.config.minSamples,
+                } : undefined,
+            };
+        },
+    },
+    {
+        name: 'swarm_pheromone_update',
+        description: 'Record a normalized per-agent task outcome for a running pheromone-adaptive swarm. Use when a static agent pool is wrong because repeated task evidence should update role-aware EMA fitness and produce a bounded keep/suspend/reactivate decision; native Task has no persistent swarm eligibility gate.',
+        category: 'swarm',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'Stable tracked agent identifier' },
+                role: { type: 'string', description: 'Agent role used for role-local normalization' },
+                taskSuccess: { type: 'number', description: 'Observed task success in [0,1]' },
+                normalizedLatency: { type: 'number', description: 'Latency divided by the configured budget, clamped to [0,1]' },
+                consensusAlignment: { type: 'number', description: 'Agreement with the accepted consensus in [0,1]' },
+            },
+            required: ['agentId', 'role', 'taskSuccess', 'normalizedLatency', 'consensusAlignment'],
+        },
+        handler: async (input) => {
+            try {
+                return recordSwarmPheromoneSignal({
+                    agentId: String(input.agentId),
+                    role: String(input.role),
+                    taskSuccess: Number(input.taskSuccess),
+                    normalizedLatency: Number(input.normalizedLatency),
+                    consensusAlignment: Number(input.consensusAlignment),
+                });
+            }
+            catch (error) {
+                return { active: false, reason: error.message };
+            }
+        },
+    },
+    {
+        name: 'swarm_pheromone_status',
+        description: 'Inspect the threshold, safety configuration, per-agent EMA scores, and scheduling eligibility of the active pheromone-adaptive swarm. Use when aggregate swarm status is wrong because calibration requires the exact APSC threshold and per-agent evidence before switching from dry-run to live suspension.',
+        category: 'swarm',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            const store = loadSwarmStore();
+            const swarm = latestRunningSwarm(store);
+            const state = apscStateOf(swarm);
+            if (!swarm || !state)
+                return { active: false, reason: 'no running pheromone-adaptive swarm' };
+            return {
+                active: true,
+                swarmId: swarm.swarmId,
+                threshold: state.threshold,
+                round: state.round,
+                config: state.config,
+                agents: Object.values(state.agents).sort((a, b) => a.agentId.localeCompare(b.agentId)),
             };
         },
     },
@@ -212,6 +375,7 @@ export const swarmTools = [
                     agentCount: swarm.agents.length,
                     taskCount: swarm.tasks.length,
                     config: swarm.config,
+                    apsc: apscStateOf(swarm),
                     createdAt: swarm.createdAt,
                     updatedAt: swarm.updatedAt,
                 };
@@ -236,6 +400,7 @@ export const swarmTools = [
                 agentCount: latest.agents.length,
                 taskCount: latest.tasks.length,
                 config: latest.config,
+                apsc: apscStateOf(latest),
                 createdAt: latest.createdAt,
                 updatedAt: latest.updatedAt,
                 totalSwarms: swarmIds.length,

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.d.ts

@@ -36,7 +36,7 @@ export declare function resolveDbPath(cliFlag?: string): string;
  * Vector embeddings enabled for semantic search
  */
 export declare const MEMORY_SCHEMA_V3 = "\n-- RuFlo V3 Memory Database\n-- Version: 3.0.0\n-- Features: Pattern learning, vector embeddings, temporal decay, migration tracking\n\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA foreign_keys = ON;\n\n-- ============================================\n-- CORE MEMORY TABLES\n-- ============================================\n\n-- Memory entries (main storage)\nCREATE TABLE IF NOT EXISTS memory_entries (\n  id TEXT PRIMARY KEY,\n  key TEXT NOT NULL,\n  namespace TEXT DEFAULT 'default',\n  content TEXT NOT NULL,\n  type TEXT DEFAULT 'semantic' CHECK(type IN ('semantic', 'episodic', 'procedural', 'working', 'pattern')),\n\n  -- Vector embedding for semantic search (stored as JSON array)\n  embedding TEXT,\n  embedding_model TEXT DEFAULT 'local',\n  embedding_dimensions INTEGER,\n\n  -- Metadata\n  tags TEXT, -- JSON array\n  metadata TEXT, -- JSON object\n  owner_id TEXT,\n\n  -- ADR-323: who/what produced this entry \u2014 lets shared-namespace retrieval\n  -- filter by trust level instead of conflating a user's stated claim with\n  -- an agent's own output or a raw tool/system observation.\n  provenance_type TEXT DEFAULT 'unknown' CHECK(provenance_type IN (\n    'user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'\n  )),\n\n  -- Timestamps\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  expires_at INTEGER,\n  last_accessed_at INTEGER,\n\n  -- Access tracking for hot/cold detection\n  access_count INTEGER DEFAULT 0,\n\n  -- Status\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'archived', 'deleted')),\n\n  UNIQUE(namespace, key)\n);\n\n-- Indexes for memory entries\nCREATE INDEX IF NOT EXISTS idx_memory_namespace ON memory_entries(namespace);\nCREATE INDEX IF NOT EXISTS idx_memory_key ON memory_entries(key);\nCREATE INDEX IF NOT EXISTS idx_memory_type ON memory_entries(type);\nCREATE INDEX IF NOT EXISTS idx_memory_status ON memory_entries(status);\nCREATE INDEX IF NOT EXISTS idx_memory_created ON memory_entries(created_at);\nCREATE INDEX IF NOT EXISTS idx_memory_accessed ON memory_entries(last_accessed_at);\nCREATE INDEX IF NOT EXISTS idx_memory_owner ON memory_entries(owner_id);\n\n-- ============================================\n-- PATTERN LEARNING TABLES\n-- ============================================\n\n-- Learned patterns with confidence scoring and versioning\nCREATE TABLE IF NOT EXISTS patterns (\n  id TEXT PRIMARY KEY,\n\n  -- Pattern identification\n  name TEXT NOT NULL,\n  pattern_type TEXT NOT NULL CHECK(pattern_type IN (\n    'task-routing', 'error-recovery', 'optimization', 'learning',\n    'coordination', 'prediction', 'code-pattern', 'workflow'\n  )),\n\n  -- Pattern definition\n  condition TEXT NOT NULL, -- Regex or semantic match\n  action TEXT NOT NULL, -- What to do when pattern matches\n  description TEXT,\n\n  -- Confidence scoring (0.0 - 1.0)\n  confidence REAL DEFAULT 0.5,\n  success_count INTEGER DEFAULT 0,\n  failure_count INTEGER DEFAULT 0,\n\n  -- Temporal decay\n  decay_rate REAL DEFAULT 0.01, -- How fast confidence decays\n  half_life_days INTEGER DEFAULT 30, -- Days until confidence halves without use\n\n  -- Vector embedding for semantic pattern matching\n  embedding TEXT,\n  embedding_dimensions INTEGER,\n\n  -- Versioning\n  version INTEGER DEFAULT 1,\n  parent_id TEXT REFERENCES patterns(id),\n\n  -- Metadata\n  tags TEXT, -- JSON array\n  metadata TEXT, -- JSON object\n  source TEXT, -- Where the pattern was learned from\n\n  -- Timestamps\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  last_matched_at INTEGER,\n  last_success_at INTEGER,\n  last_failure_at INTEGER,\n\n  -- Status\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'archived', 'deprecated', 'experimental'))\n);\n\n-- Indexes for patterns\nCREATE INDEX IF NOT EXISTS idx_patterns_type ON patterns(pattern_type);\nCREATE INDEX IF NOT EXISTS idx_patterns_confidence ON patterns(confidence DESC);\nCREATE INDEX IF NOT EXISTS idx_patterns_status ON patterns(status);\nCREATE INDEX IF NOT EXISTS idx_patterns_last_matched ON patterns(last_matched_at);\n\n-- Pattern evolution history (for versioning)\nCREATE TABLE IF NOT EXISTS pattern_history (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  pattern_id TEXT NOT NULL REFERENCES patterns(id),\n  version INTEGER NOT NULL,\n\n  -- Snapshot of pattern state\n  confidence REAL,\n  success_count INTEGER,\n  failure_count INTEGER,\n  condition TEXT,\n  action TEXT,\n\n  -- What changed\n  change_type TEXT CHECK(change_type IN ('created', 'updated', 'success', 'failure', 'decay', 'merged', 'split')),\n  change_reason TEXT,\n\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\nCREATE INDEX IF NOT EXISTS idx_pattern_history_pattern ON pattern_history(pattern_id);\n\n-- ============================================\n-- LEARNING & TRAJECTORY TABLES\n-- ============================================\n\n-- Learning trajectories (SONA integration)\nCREATE TABLE IF NOT EXISTS trajectories (\n  id TEXT PRIMARY KEY,\n  session_id TEXT,\n\n  -- Trajectory state\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'completed', 'failed', 'abandoned')),\n  verdict TEXT CHECK(verdict IN ('success', 'failure', 'partial', NULL)),\n\n  -- Context\n  task TEXT,\n  context TEXT, -- JSON object\n\n  -- Metrics\n  total_steps INTEGER DEFAULT 0,\n  total_reward REAL DEFAULT 0,\n\n  -- Timestamps\n  started_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  ended_at INTEGER,\n\n  -- Reference to extracted pattern (if any)\n  extracted_pattern_id TEXT REFERENCES patterns(id)\n);\n\n-- Trajectory steps\nCREATE TABLE IF NOT EXISTS trajectory_steps (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  trajectory_id TEXT NOT NULL REFERENCES trajectories(id),\n  step_number INTEGER NOT NULL,\n\n  -- Step data\n  action TEXT NOT NULL,\n  observation TEXT,\n  reward REAL DEFAULT 0,\n\n  -- Metadata\n  metadata TEXT, -- JSON object\n\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\nCREATE INDEX IF NOT EXISTS idx_steps_trajectory ON trajectory_steps(trajectory_id);\n\n-- ============================================\n-- MIGRATION STATE TRACKING\n-- ============================================\n\n-- Migration state (for resume capability)\nCREATE TABLE IF NOT EXISTS migration_state (\n  id TEXT PRIMARY KEY,\n  migration_type TEXT NOT NULL, -- 'v2-to-v3', 'pattern', 'memory', etc.\n\n  -- Progress tracking\n  status TEXT DEFAULT 'pending' CHECK(status IN ('pending', 'in_progress', 'completed', 'failed', 'rolled_back')),\n  total_items INTEGER DEFAULT 0,\n  processed_items INTEGER DEFAULT 0,\n  failed_items INTEGER DEFAULT 0,\n  skipped_items INTEGER DEFAULT 0,\n\n  -- Current position (for resume)\n  current_batch INTEGER DEFAULT 0,\n  last_processed_id TEXT,\n\n  -- Source/destination info\n  source_path TEXT,\n  source_type TEXT,\n  destination_path TEXT,\n\n  -- Backup info\n  backup_path TEXT,\n  backup_created_at INTEGER,\n\n  -- Error tracking\n  last_error TEXT,\n  errors TEXT, -- JSON array of errors\n\n  -- Timestamps\n  started_at INTEGER,\n  completed_at INTEGER,\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\n-- ============================================\n-- SESSION MANAGEMENT\n-- ============================================\n\n-- Sessions for context persistence\nCREATE TABLE IF NOT EXISTS sessions (\n  id TEXT PRIMARY KEY,\n\n  -- Session state\n  state TEXT NOT NULL, -- JSON object with full session state\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'paused', 'completed', 'expired')),\n\n  -- Context\n  project_path TEXT,\n  branch TEXT,\n\n  -- Metrics\n  tasks_completed INTEGER DEFAULT 0,\n  patterns_learned INTEGER DEFAULT 0,\n\n  -- Timestamps\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  expires_at INTEGER\n);\n\n-- ============================================\n-- VECTOR INDEX METADATA (for HNSW)\n-- ============================================\n\n-- Track HNSW index state\nCREATE TABLE IF NOT EXISTS vector_indexes (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL UNIQUE,\n\n  -- Index configuration\n  dimensions INTEGER NOT NULL,\n  metric TEXT DEFAULT 'cosine' CHECK(metric IN ('cosine', 'euclidean', 'dot')),\n\n  -- HNSW parameters\n  hnsw_m INTEGER DEFAULT 16,\n  hnsw_ef_construction INTEGER DEFAULT 200,\n  hnsw_ef_search INTEGER DEFAULT 100,\n\n  -- Quantization\n  quantization_type TEXT CHECK(quantization_type IN ('none', 'scalar', 'product')),\n  quantization_bits INTEGER DEFAULT 8,\n\n  -- Statistics\n  total_vectors INTEGER DEFAULT 0,\n  last_rebuild_at INTEGER,\n\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\n-- ============================================\n-- GRAPH EDGES (ADR-130 Phase 1)\n-- Unified knowledge graph backend \u2014 sql.js canonical store\n-- ============================================\n\n-- Unified graph edges table (ADR-130)\n-- Node IDs use domain-prefixed format: {domain}:{uuid}\n-- where domain in (mem, agent, task, entity, span, pattern)\nCREATE TABLE IF NOT EXISTS graph_edges (\n  id              TEXT PRIMARY KEY,          -- edge-{uuid}\n  source_id       TEXT NOT NULL,             -- domain-prefixed node ID\n  target_id       TEXT NOT NULL,             -- domain-prefixed node ID\n  relation        TEXT NOT NULL,             -- e.g. \"caused\", \"depends-on\", \"imports\"\n  weight          REAL DEFAULT 1.0,\n  -- Temporal / reliability semantics (ADR-130 \u00A7\"graph that forgets\" property)\n  confidence      REAL DEFAULT 1.0,          -- [0,1]; updated by JUDGE step\n  decay_rate      REAL DEFAULT 0.0,          -- per-day exponential decay applied at read time\n  last_reinforced TEXT,                      -- ISO-8601; set when CONSOLIDATE re-touches edge\n  witness_id      TEXT,                      -- FK to verification/witness-fixes.json (ADR-103)\n  -- Embedding storage: \"inline:{base64}\" | \"vector_indexes:{id}\" | NULL\n  embedding_ref   TEXT,\n  metadata        TEXT,                      -- JSON blob for plugin-specific fields\n  created_at      TEXT NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_graph_edges_source    ON graph_edges (source_id);\nCREATE INDEX IF NOT EXISTS idx_graph_edges_target    ON graph_edges (target_id);\nCREATE INDEX IF NOT EXISTS idx_graph_edges_relation  ON graph_edges (relation);\nCREATE INDEX IF NOT EXISTS idx_graph_edges_reinforced ON graph_edges (last_reinforced);\n\n-- ============================================\n-- SYSTEM METADATA\n-- ============================================\n\nCREATE TABLE IF NOT EXISTS metadata (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL,\n  updated_at INTEGER DEFAULT (strftime('%s', 'now') * 1000)\n);\n";
-interface HNSWEntry {
+export interface HNSWEntry {
     id: string;
     key: string;
     namespace: string;
@@ -57,6 +57,14 @@ export declare function getHNSWIndex(options?: {
     dimensions?: number;
     forceRebuild?: boolean;
 }): Promise<HNSWIndex | null>;
+export declare function removeHNSWEntriesByLogicalKey(entries: Map<string, HNSWEntry>, key: string, namespace: string): number;
+/**
+ * Remove HNSW metadata whose authoritative SQLite row is no longer active.
+ * Persistent graph nodes may remain physically allocated, but without metadata
+ * they cannot resolve into search results; the next rebuild repopulates only
+ * active rows. Returns the number of searchable vectors invalidated.
+ */
+export declare function reconcileHNSWIndex(dbPath?: string): Promise<number>;
 /**
  * Add entry to HNSW index (with automatic persistence)
  */