claude-flow 3.57.1 → 3.58.0

package/v3/@claude-flow/cli/dist/src/mcp-tools/claims-tools.js

@@ -13,6 +13,7 @@ import { existsSync, writeFileSync, mkdirSync } from 'fs';
 import { join, resolve } from 'path';
 const CLAIMS_DIR = '.claude-flow/claims';
 const CLAIMS_FILE = 'claims.json';
+const DEFAULT_MAX_CLAIMS = 5;
 function getClaimsPath() {
     return resolve(join(CLAIMS_DIR, CLAIMS_FILE));
 }
@@ -47,7 +48,7 @@ function parseClaimant(str) {
 export const claimsTools = [
     {
         name: 'claims_claim',
-        description: 'Claim an issue for work (human or agent) Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Claim an issue for work (human or agent). Use when multiple agents might pick up the same issue — claiming makes ownership visible via claims_list before work starts.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -64,6 +65,10 @@ export const claimsTools = [
                     type: 'string',
                     description: 'Optional context about the work approach',
                 },
+                ttlMs: {
+                    type: 'number',
+                    description: 'Optional time-to-live in milliseconds; when set, the claim records an expiresAt timestamp. Informational only today — no handler currently enforces it (e.g. claims_steal still requires claims_mark-stealable rather than checking expiry).',
+                },
             },
             required: ['issueId', 'claimant'],
         },
@@ -71,6 +76,7 @@ export const claimsTools = [
             const issueId = input.issueId;
             const claimantStr = input.claimant;
             const context = input.context;
+            const ttlMs = input.ttlMs;
             {
                 const v = validateIdentifier(issueId, 'issueId');
                 if (!v.valid)
@@ -86,6 +92,9 @@ export const claimsTools = [
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
+            if (ttlMs !== undefined && (typeof ttlMs !== 'number' || !Number.isFinite(ttlMs) || ttlMs <= 0)) {
+                return { success: false, error: 'ttlMs must be a positive number' };
+            }
             const claimant = parseClaimant(claimantStr);
             if (!claimant) {
                 return { success: false, error: 'Invalid claimant format. Use "human:userId:name" or "agent:agentId:agentType"' };
@@ -109,6 +118,7 @@ export const claimsTools = [
                 statusChangedAt: now,
                 progress: 0,
                 context,
+                expiresAt: ttlMs !== undefined ? new Date(Date.now() + ttlMs).toISOString() : undefined,
             };
             store.claims[issueId] = claim;
             saveClaims(store);
@@ -121,7 +131,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_release',
-        description: 'Release a claim on an issue Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Release a claim on an issue. Use when the claimant stops working on it, freeing it for another claims_claim instead of leaving it claimed indefinitely.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -186,7 +196,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_handoff',
-        description: 'Request handoff of an issue to another claimant Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Request handoff of an issue to another claimant. Use when transferring in-progress work to a different agent, instead of releasing and having them claim it fresh.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -270,7 +280,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_accept-handoff',
-        description: 'Accept a pending handoff Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Accept a pending handoff. Use when the receiving claimant confirms a claims_handoff request, completing the ownership transfer.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -333,7 +343,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_status',
-        description: 'Update claim status Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Update claim status. Use when progress changes (active, blocked, review-requested, etc.) so claims_list and claims_load reflect current state.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -398,7 +408,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_list',
-        description: 'List all claims or filter by criteria Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'List all claims or filter by criteria. Use when checking what is already claimed before starting new work, instead of guessing from issue comments.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -453,7 +463,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_mark-stealable',
-        description: 'Mark an issue as stealable by other agents Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Mark an issue as stealable by other agents. Use when a claimant is overloaded or stalled and wants another agent to pick it up via claims_steal.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -521,7 +531,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_steal',
-        description: 'Steal a stealable issue Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Steal a stealable issue. Use when picking up work already marked stealable via claims_mark-stealable, rather than claiming an issue someone else still owns.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -592,7 +602,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_stealable',
-        description: 'List all stealable issues Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'List all stealable issues. Use when looking for available work that has been freed up via claims_mark-stealable.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -628,7 +638,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_load',
-        description: 'Get agent load information Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Get agent load information. Use when deciding which agent should take new work by comparing claim counts against claims_rebalance targets.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -689,8 +699,8 @@ export const claimsTools = [
                 agentId: l.agentId,
                 agentType: l.agentType,
                 claimCount: l.claims.length,
-                maxClaims: 5, // Default max
-                utilization: l.claims.length / 5,
+                maxClaims: DEFAULT_MAX_CLAIMS,
+                utilization: l.claims.length / DEFAULT_MAX_CLAIMS,
                 blockedCount: l.blockedCount,
                 claims: l.claims.map(c => ({
                     issueId: c.issueId,
@@ -711,7 +721,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_board',
-        description: 'Get a visual board view of all claims Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Get a visual board view of all claims. Use when scanning overall claim status across issues and agents instead of composing the view from claims_list yourself.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -760,7 +770,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_rebalance',
-        description: 'Suggest or apply load rebalancing across agents Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Suggest or apply load rebalancing across agents. Use when some agents are overloaded and others idle, instead of manually reassigning claims one at a time.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -794,7 +804,7 @@ export const claimsTools = [
                 agentLoads.get(key).claims.push(claim);
             }
             const loads = Array.from(agentLoads.values());
-            const maxClaims = 5;
+            const maxClaims = DEFAULT_MAX_CLAIMS;
             const avgLoad = loads.length > 0
                 ? loads.reduce((sum, l) => sum + l.claims.length, 0) / loads.length
                 : 0;

package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js

@@ -4175,12 +4175,12 @@ export const hooksIntelligenceLearn = {
 // Intelligence attention hook
 export const hooksIntelligenceAttention = {
     name: 'hooks_intelligence_attention',
-    description: 'Compute attention-weighted similarity using MoE/Flash/Hyperbolic Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
+    description: 'Compute attention-weighted similarity using MoE/Flash. Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
             query: { type: 'string', description: 'Query for attention computation' },
-            mode: { type: 'string', description: 'Attention mode (flash, moe, hyperbolic)' },
+            mode: { type: 'string', description: 'Attention mode (flash, moe)' },
             topK: { type: 'number', description: 'Top-k results' },
         },
         required: ['query'],
@@ -4195,6 +4195,12 @@ export const hooksIntelligenceAttention = {
             if (!v.valid)
                 return { success: false, error: v.error };
         }
+        // #3548: only flash and moe have an implementation. Any other mode
+        // (including the previously advertised 'hyperbolic') used to return an
+        // empty stub whose note blamed a missing package; say so instead.
+        if (mode !== 'flash' && mode !== 'moe') {
+            return { success: false, error: `Attention mode "${mode}" is not implemented; supported modes: flash, moe` };
+        }
         let implementation = 'placeholder';
         let embeddingSource = 'none';
         const results = [];
@@ -4370,7 +4376,7 @@ export const hooksIntelligenceAttention = {
                 implementation,
                 _embeddingSource: embeddingSource,
                 _stub: implementation === 'none',
-                _note: implementation === 'none' ? 'No attention backend available. Install @ruvector/attention for real computation.' : undefined,
+                _note: implementation === 'none' ? 'No attention backend available: flash/moe attention from @claude-flow/neural could not be loaded or failed.' : undefined,
                 ...(embeddingSource === 'hash-fallback' && implementation !== 'none'
                     ? { _embeddingNote: 'Query embeddings are hash-based (not semantic). Install @claude-flow/embeddings for real ONNX embeddings.' }
                     : {}),

package/v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js

@@ -227,15 +227,31 @@ function loadLegacyStore() {
 /**
  * Mark migration as complete
  */
-function markMigrationComplete() {
+function markMigrationComplete(counts) {
     const legacyDir = resolve(LEGACY_MEMORY_DIR);
     if (!existsSync(legacyDir))
         mkdirSync(legacyDir, { recursive: true });
     writeFileSync(resolve(join(LEGACY_MEMORY_DIR, MIGRATION_MARKER)), JSON.stringify({
         migratedAt: new Date().toISOString(),
         version: '3.0.0',
+        ...(counts ?? {}),
     }), 'utf-8');
 }
+/**
+ * Counts recorded by the migration that wrote the marker, or null when no
+ * marker (or an older marker without counts) is present.
+ */
+function readMigrationCounts() {
+    try {
+        const marker = JSON.parse(readFileSync(resolve(join(LEGACY_MEMORY_DIR, MIGRATION_MARKER)), 'utf-8'));
+        return typeof marker?.migrated === 'number' && typeof marker?.total === 'number'
+            ? { migrated: marker.migrated, total: marker.total }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Lazy-load memory initializer functions to avoid circular deps
  */
@@ -391,7 +407,7 @@ async function ensureInitialized(dbPath) {
                         }
                     }
                     console.error(`[MCP Memory] Migrated ${migrated}/${Object.keys(legacyStore.entries).length} entries`);
-                    markMigrationComplete();
+                    markMigrationComplete({ migrated, total: Object.keys(legacyStore.entries).length });
                 }
             }
         }
@@ -636,7 +652,11 @@ export const memoryTools = [
                             });
                             return {
                                 results: r.results.map(e => ({
-                                    id: e.id,
+                                    // #2271: searchEntries() truncates ids to 12 chars ("entry_" +
+                                    // the leading digits of Date.now()), so entries written within
+                                    // ~2.8h share one id and RRF fused them into a single result.
+                                    // SmartRetrieval dedupes on id: give it the (namespace, key) tuple.
+                                    id: JSON.stringify([e.namespace, e.key]),
                                     key: e.key,
                                     content: e.content,
                                     score: e.score,
@@ -966,11 +986,17 @@ export const memoryTools = [
         },
         handler: async (input) => {
             const force = input.force;
-            // Remove migration marker if forcing
+            // Remove the migration marker if forcing. hasLegacyStore() checks the marker
+            // beside the legacy store, so that is the one force must clear (#4194);
+            // the old .swarm marker path is cleared too for compatibility.
             if (force) {
-                const markerPath = getMigrationMarkerPath();
-                if (existsSync(markerPath)) {
-                    unlinkSync(markerPath);
+                for (const markerPath of [
+                    resolve(join(LEGACY_MEMORY_DIR, MIGRATION_MARKER)),
+                    getMigrationMarkerPath(),
+                ]) {
+                    if (existsSync(markerPath)) {
+                        unlinkSync(markerPath);
+                    }
                 }
             }
             // Check for legacy data
@@ -982,12 +1008,35 @@ export const memoryTools = [
                     migrated: 0,
                 };
             }
+            // A marker beside the store means a migration already ran; ensureInitialized
+            // would move nothing, so say so instead of reporting the store's size.
+            if (!hasLegacyStore()) {
+                return {
+                    success: true,
+                    message: 'Legacy store already migrated (marker present); nothing was moved. Pass force: true to re-run.',
+                    migrated: 0,
+                    total: Object.keys(legacyStore.entries).length,
+                };
+            }
             // Run migration via ensureInitialized
             await ensureInitialized();
+            // ensureInitialized swallows errors and records what it moved in the marker.
+            const counts = readMigrationCounts();
+            if (!counts) {
+                return {
+                    success: false,
+                    message: 'Migration did not complete; no entries were recorded as migrated. See the MCP server log.',
+                    migrated: 0,
+                    total: Object.keys(legacyStore.entries).length,
+                };
+            }
             return {
                 success: true,
-                message: 'Migration completed',
-                migrated: Object.keys(legacyStore.entries).length,
+                message: counts.migrated === counts.total
+                    ? 'Migration completed'
+                    : `Migration completed with failures: ${counts.migrated} of ${counts.total} entries migrated`,
+                migrated: counts.migrated,
+                total: counts.total,
                 backend: await describeBackend(),
             };
         },

package/v3/@claude-flow/cli/dist/src/mcp-tools/workflow-tools.js

@@ -577,7 +577,8 @@ export const workflowTools = [
             const store = loadWorkflowStore();
             let workflows = Object.values(store.workflows);
             // Apply filters
-            if (input.status) {
+            // 'all' is the CLI's explicit "no filter" value (`workflow list` sends it by default).
+            if (input.status && input.status !== 'all') {
                 workflows = workflows.filter(w => w.status === input.status);
             }
             // Sort by creation date (newest first)

package/v3/@claude-flow/cli/dist/src/memory/graph-edge-writer.d.ts

@@ -30,10 +30,12 @@
  * @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.
+ * True iff the memory.db bridge at `customDbPath` — or, when omitted, the
+ * path `resolveDbPath()` resolves from the `CLAUDE_FLOW_DB_PATH` env binding
+ * / memory root default (#4291) — 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. */
@@ -60,6 +62,16 @@ export declare function releaseBridgeDb(dbPath?: string): boolean;
  * #2431 fix: better-sqlite3 + WAL mode replaces sql.js + whole-file
  * writeFileSync. Eliminates the dual-write race that corrupted memory.db
  * when called alongside the memory bridge's better-sqlite3 writer.
+ *
+ * #4291 fix: the file is resolved via `resolveDbPath()` — the project's one
+ * documented path-priority rule (explicit `customDbPath` argument wins, then
+ * the `CLAUDE_FLOW_DB_PATH` env binding, then the plain `memory.db` default
+ * under the memory root) — instead of a local `customDbPath ?? <default>`
+ * expression that silently ignored `CLAUDE_FLOW_DB_PATH`. A caller that
+ * explicitly selected a store via that env var no longer gets answers read
+ * from a different, unselected database file. When the resolved file is
+ * missing (and `createIfMissing` is false) or encrypted at rest, this
+ * refuses (returns null) rather than falling back to any other store.
  */
 export declare function getBridgeDb(customDbPath?: string, opts?: {
     createIfMissing?: boolean;

package/v3/@claude-flow/cli/dist/src/memory/graph-edge-writer.js

@@ -33,7 +33,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import * as crypto from 'crypto';
 import { execFileSync } from 'child_process';
-import { getMemoryRoot } from './memory-initializer.js';
+import { resolveDbPath } from './memory-initializer.js';
 import { encodeEmbedding } from './embedding-quantization.js';
 import { loadBetterSqlite3 } from './shared-sqlite.js';
 import { isEncryptedBlob } from '../encryption/vault.js';
@@ -125,13 +125,15 @@ function warnRfe1EncryptedOnce(dbPath) {
         '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.
+ * True iff the memory.db bridge at `customDbPath` — or, when omitted, the
+ * path `resolveDbPath()` resolves from the `CLAUDE_FLOW_DB_PATH` env binding
+ * / memory root default (#4291) — 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');
+    const dbPath = resolveDbPath(customDbPath);
     return fs.existsSync(dbPath) && isRfe1EncryptedAtRest(dbPath);
 }
 /** Test-only: clear the once-per-path warning dedup set. */
@@ -222,9 +224,19 @@ export function releaseBridgeDb(dbPath) {
  * #2431 fix: better-sqlite3 + WAL mode replaces sql.js + whole-file
  * writeFileSync. Eliminates the dual-write race that corrupted memory.db
  * when called alongside the memory bridge's better-sqlite3 writer.
+ *
+ * #4291 fix: the file is resolved via `resolveDbPath()` — the project's one
+ * documented path-priority rule (explicit `customDbPath` argument wins, then
+ * the `CLAUDE_FLOW_DB_PATH` env binding, then the plain `memory.db` default
+ * under the memory root) — instead of a local `customDbPath ?? <default>`
+ * expression that silently ignored `CLAUDE_FLOW_DB_PATH`. A caller that
+ * explicitly selected a store via that env var no longer gets answers read
+ * from a different, unselected database file. When the resolved file is
+ * missing (and `createIfMissing` is false) or encrypted at rest, this
+ * refuses (returns null) rather than falling back to any other store.
  */
 export async function getBridgeDb(customDbPath, opts) {
-    const dbPath = customDbPath ?? path.join(getMemoryRoot(), 'memory.db');
+    const dbPath = resolveDbPath(customDbPath);
     const createIfMissing = opts?.createIfMissing === true;
     if (_db && _dbPath === dbPath) {
         armIdleRelease();

package/v3/@claude-flow/cli/dist/src/memory/intelligence.js

@@ -1077,6 +1077,10 @@ export async function recordTrajectory(steps, verdict) {
         }
         bumpStat('trajectoriesRecorded');
         globalStats.lastAdaptation = Date.now();
+        // #4283: the bank's own save is debounced, and the one-shot bins exit as
+        // soon as the command resolves, so write the patterns now. Otherwise
+        // stats.json counts patterns that never reach patterns.json.
+        reasoningBank?.flushToDisk();
         savePersistedStats();
         return true;
     }

package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js

@@ -10,6 +10,7 @@ import { createRequire } from 'node:module';
 import { readFileMaybeEncrypted, writeDbImagePreservingFormat, writeFileRestricted } from '../fs-secure.js';
 import { restoreMemoryDbFromBackup } from '../services/memory-backup.js';
 import { validateIdentifier } from '../mcp-tools/validate-input.js';
+import { resolveModelCacheDir } from './model-cache-dir.js';
 /**
  * ADR-323 — typed memory provenance. Distinguishes WHO/WHAT wrote a memory
  * entry (a user's stated claim vs an agent's own output vs a tool result vs
@@ -2009,6 +2010,8 @@ export async function applyTemporalDecay(dbPath) {
         };
     }
 }
+/** ADR-454: minimum interval before a 'retryable' degraded state re-attempts real init. */
+const MODEL_INIT_RETRY_INTERVAL_MS = 60_000;
 /**
  * State of the LOCAL embedding chain only (transformers.js / agentic-flow /
  * ruvector ONNX / hash). #3375: the AgentDB bridge's result is cached
@@ -2058,8 +2061,15 @@ export async function loadEmbeddingModel(options) {
  */
 async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now()) {
     if (embeddingModelState?.loaded) {
-        return { success: true, dimensions: embeddingModelState.dimensions, modelName: 'cached', loadTime: 0 };
+        const isRetryableDue = embeddingModelState.degradedReason === 'retryable' &&
+            Date.now() - (embeddingModelState.lastAttemptAt ?? 0) >= MODEL_INIT_RETRY_INTERVAL_MS;
+        if (!isRetryableDue) {
+            return { success: true, dimensions: embeddingModelState.dimensions, modelName: 'cached', loadTime: 0 };
+        }
+        // Fall through to re-attempt real initialization — the retryable
+        // failure (e.g. EACCES on the model cache dir) may now be fixed.
     }
+    let sawRetryableFailure = false;
     try {
         // ADR-094: prefer @huggingface/transformers (clears protobufjs <7.5.5
         // critical RCE chain), fall back to legacy @xenova/transformers.
@@ -2068,6 +2078,7 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
         // @claude-flow/embeddings/src/transformers-loader.ts.
         let transformersSource = null;
         let pipelineFn = null;
+        let transformersModule = null;
         {
             const tryLoad = async (specifier) => {
                 try {
@@ -2081,12 +2092,14 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
             if (hf && typeof hf.pipeline === 'function') {
                 pipelineFn = hf.pipeline;
                 transformersSource = '@huggingface/transformers';
+                transformersModule = hf;
             }
             else {
                 const xen = await tryLoad('@xenova/transformers');
                 if (xen && typeof xen.pipeline === 'function') {
                     pipelineFn = xen.pipeline;
                     transformersSource = '@xenova/transformers';
+                    transformersModule = xen;
                 }
             }
         }
@@ -2103,6 +2116,14 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
                 if (verbose) {
                     console.log(`Loading ONNX embedding model via ${transformersSource} (all-MiniLM-L6-v2)...`);
                 }
+                // ADR-454: route model downloads to a user-writable cache dir —
+                // the package-relative default is root-owned under a system-prefix
+                // global install, which throws EACCES for the runtime user.
+                const cacheDir = resolveModelCacheDir();
+                fs.mkdirSync(cacheDir, { recursive: true });
+                const env = transformersModule?.env;
+                if (env)
+                    env.cacheDir = cacheDir;
                 const embedder = await pipelineFn('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
                 embeddingModelState = {
                     loaded: true,
@@ -2118,6 +2139,10 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
                 };
             }
             catch (err) {
+                // ADR-454: a real backend was importable and callable — this failure
+                // (EACCES, ENOSPC, transient network error, etc.) is environmental,
+                // not a missing dependency, so it must not be memoized permanently.
+                sawRetryableFailure = true;
                 if (verbose) {
                     console.warn(`${transformersSource} pipeline init failed (${err instanceof Error ? err.message : String(err)}); ` +
                         'falling through to ruvector ONNX / agentic-flow / hash fallback.');
@@ -2131,15 +2156,19 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
             if (verbose) {
                 console.log('Loading agentic-flow ReasoningBank embedding model...');
             }
+            // #3113: register a callable, like the ruvector branch below —
+            // generateLocalEmbedding() only invokes function models. The bundled
+            // model is all-MiniLM-L6-v2 (384-dim, per agentic-flow's
+            // getEmbeddingDimensions()).
             embeddingModelState = {
                 loaded: true,
-                model: { embed: reasoningBank.computeEmbedding },
+                model: (text) => reasoningBank.computeEmbedding(text),
                 tokenizer: null,
-                dimensions: 768
+                dimensions: 384
             };
             return {
                 success: true,
-                dimensions: 768,
+                dimensions: 384,
                 modelName: 'agentic-flow/reasoningbank',
                 loadTime: Date.now() - startTime
             };
@@ -2182,12 +2211,18 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
         }
         // No agentic-flow root-entry fallback: no published root exports
         // `embeddings`, and importing it runs its CLI main() in 3.0.0-alpha.x.
-        // No ONNX model available - use fallback
+        // No ONNX model available - use fallback.
+        // ADR-454: mark whether this is a permanent (no backend importable at
+        // all) or retryable (a backend existed but init failed for an
+        // environmental reason) degraded state, so a later call can re-attempt
+        // real initialization once the condition is fixed.
         embeddingModelState = {
             loaded: true,
             model: null, // Will use simple hash-based fallback
             tokenizer: null,
-            dimensions: 128 // Smaller fallback dimensions
+            dimensions: 128, // Smaller fallback dimensions
+            degradedReason: sawRetryableFailure ? 'retryable' : 'permanent',
+            lastAttemptAt: Date.now()
         };
         return {
             success: true,
@@ -2253,7 +2288,15 @@ export async function generateLocalEmbedding(text) {
     // loadEmbeddingModel(), which is bridge-first — when the bridge answered
     // there, no local model was ever loaded and this function always returned
     // the hash fallback.
-    if (!embeddingModelState?.loaded) {
+    //
+    // ADR-454: also re-attempt when the memoized state is a 'retryable'
+    // degraded fallback whose retry interval has elapsed — otherwise this
+    // guard short-circuits past loadLocalEmbeddingChain()'s own retry check
+    // and the fix (e.g. a now-writable cache dir) never gets exercised.
+    const shouldRetryLoad = !embeddingModelState?.loaded ||
+        (embeddingModelState.degradedReason === 'retryable' &&
+            Date.now() - (embeddingModelState.lastAttemptAt ?? 0) >= MODEL_INIT_RETRY_INTERVAL_MS);
+    if (shouldRetryLoad) {
         await loadLocalEmbeddingChain();
     }
     // #2461: loadEmbeddingModel() can leave embeddingModelState null when an
@@ -2272,10 +2315,13 @@ export async function generateLocalEmbedding(text) {
     if (state.model && typeof state.model === 'function') {
         try {
             const output = await state.model(text, { pooling: 'mean', normalize: true });
-            // Handle both @xenova/transformers (output.data) and ruvector (plain array) formats
+            // Handle @xenova/transformers (output.data), ruvector (plain array) and
+            // typed-array (ReasoningBank Float32Array, #3114) formats. DataView is an
+            // ArrayBuffer view without an iterator (Array.from gives []), so exclude it.
             const embedding = output?.data
                 ? Array.from(output.data)
-                : Array.isArray(output) ? output : null;
+                : Array.isArray(output) ? output
+                    : ArrayBuffer.isView(output) && !(output instanceof DataView) ? Array.from(output) : null;
             if (embedding) {
                 return {
                     embedding,

package/v3/@claude-flow/cli/dist/src/memory/memory-peek.d.ts

@@ -0,0 +1,28 @@
+export type MemoryRootSource = 'path' | 'CLAUDE_FLOW_DB_PATH' | 'CLAUDE_FLOW_MEMORY_PATH' | 'config' | 'default';
+export interface MemoryPeekStore {
+    role: 'cli' | 'mcp';
+    path: string;
+    exists: boolean;
+    rows: number | null;
+    lastWrite: string | null;
+    sizeBytes: number | null;
+    walBytes: number | null;
+    encrypted?: boolean;
+}
+export interface MemoryPeekResult {
+    cwd: string;
+    root: {
+        path: string;
+        source: MemoryRootSource;
+    };
+    stores: MemoryPeekStore[];
+    sharedKeys: number | null;
+}
+/**
+ * Resolve the route and report both stores, read-only. Never creates,
+ * initializes, or migrates anything, on an empty project or any other.
+ */
+export declare function memoryPeek(opts?: {
+    path?: string;
+}): Promise<MemoryPeekResult>;
+//# sourceMappingURL=memory-peek.d.ts.map