claude-flow 3.21.1 → 3.23.0

package/v3/@claude-flow/cli/dist/src/init/executor.js

@@ -15,6 +15,7 @@ import { generateSettingsJson, generateSettings } from './settings-generator.js'
 import { generateMCPJson } from './mcp-generator.js';
 import { generateStatuslineScript } from './statusline-generator.js';
 import { generatePreCommitHook, generatePostCommitHook, generateSessionManager, generateAgentRouter, generateMemoryHelper, generateHookHandler, generateIntelligenceStub, generateAutoMemoryHook, generateRufloHookCjs, } from './helpers-generator.js';
+import { getInstalledCliVersion, HELPERS_STAMP_FILE } from './helper-refresh.js';
 import { generateClaudeMd } from './claudemd-generator.js';
 import { recordMemoryPackagePath } from './memory-package-resolver.js';
 /**
@@ -207,6 +208,19 @@ export async function executeInit(options) {
             if (memRecord) {
                 result.created.files.push('.claude-flow/memory-package.json');
             }
+            // #2568-followup: if this project already has a memory DB that predates
+            // the `vector_indexes` table (older CLI / agentdb-written), self-heal it
+            // so the statusline vector count + namespace routing work. Best-effort,
+            // dynamically imported so a WASM-only host without better-sqlite3 just
+            // skips it. Fresh projects have no DB yet — this is a no-op there.
+            try {
+                const memDbPath = path.join(targetDir, '.swarm', 'memory.db');
+                if (fs.existsSync(memDbPath)) {
+                    const { repairVectorIndexes } = await import('../memory/memory-initializer.js');
+                    await repairVectorIndexes(memDbPath, { autoRecover: true });
+                }
+            }
+            catch { /* best-effort — never block init on memory repair */ }
         }
         // Generate statusline
         if (options.components.statusline) {
@@ -483,6 +497,12 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                 catch { }
             }
         }
+        // Stamp the installed version so the startup auto-refresh treats these as
+        // current (no redundant re-copy on the next command).
+        try {
+            fs.writeFileSync(path.join(targetDir, '.claude', 'helpers', HELPERS_STAMP_FILE), getInstalledCliVersion(), 'utf-8');
+        }
+        catch { /* non-fatal */ }
         // #2545: (re)record the resolved @claude-flow/memory path so the auto-memory
         // hook can find it on the npx install path. Best-effort — see executeInit.
         const memRecord = recordMemoryPackagePath(targetDir, 'upgrade');

package/v3/@claude-flow/cli/dist/src/init/helper-refresh.d.ts

@@ -0,0 +1,19 @@
+export declare const HELPERS_STAMP_FILE = ".helpers-version";
+/** ruflo-owned helpers that carry hook logic and must track the package version. */
+export declare const CRITICAL_HELPERS: string[];
+/** Installed @claude-flow/cli version — the value the helpers are stamped with. */
+export declare function getInstalledCliVersion(): string;
+/**
+ * On CLI startup: if an initialized project's critical helpers are stamped older
+ * than the installed CLI version, silently re-copy them. Fast path is a single
+ * stamp read + string compare (sub-ms); the copy runs at most once per version
+ * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
+ * existing hook-handler.cjs — never creates files in an unrelated directory).
+ */
+export declare function autoRefreshHelpersIfStale(cwd: string): Promise<{
+    refreshed: boolean;
+    from?: string;
+    to?: string;
+    blocked?: string;
+}>;
+//# sourceMappingURL=helper-refresh.d.ts.map

package/v3/@claude-flow/cli/dist/src/init/helper-refresh.js

@@ -0,0 +1,175 @@
+/**
+ * Version-stamped critical-helper auto-refresh.
+ *
+ * The Claude Code hooks run the PROJECT-LOCAL `.claude/helpers/*.cjs` copies,
+ * not the installed npm package — so `npx ruflo@latest` does NOT update them,
+ * and users don't know to re-run `init`. This module stamps the helpers with
+ * the installed CLI version and, on the next CLI command, silently re-copies
+ * them when the stamp is stale. Hook fixes (e.g. the ADR-174 failure-capture
+ * change) then propagate to every user on their next `ruflo` command with zero
+ * action required.
+ *
+ * This file is intentionally LIGHTWEIGHT — it is imported on every CLI startup,
+ * so it depends only on `fs`/`path`/`module` at load time and lazily imports the
+ * heavy generators only on the rare fallback path (source dir unresolvable).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import { verifyHelpersManifest, sha256Hex, HELPERS_MANIFEST_FILE, } from './helper-signing.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const HELPERS_STAMP_FILE = '.helpers-version';
+/** ruflo-owned helpers that carry hook logic and must track the package version. */
+export const CRITICAL_HELPERS = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs'];
+/** Installed @claude-flow/cli version — the value the helpers are stamped with. */
+export function getInstalledCliVersion() {
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkg = JSON.parse(fs.readFileSync(esmRequire.resolve('@claude-flow/cli/package.json'), 'utf-8'));
+        return String(pkg.version || '0.0.0');
+    }
+    catch {
+        // dist/src/init → package root
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', '..', 'package.json'), 'utf-8'));
+            return String(pkg.version || '0.0.0');
+        }
+        catch {
+            return '0.0.0';
+        }
+    }
+}
+/** Locate the in-package `.claude/helpers` dir (the copy source). Null if not found. */
+function findPackageHelpersDir() {
+    const candidates = [];
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkgRoot = path.dirname(esmRequire.resolve('@claude-flow/cli/package.json'));
+        candidates.push(path.join(pkgRoot, '.claude', 'helpers'));
+    }
+    catch { /* not resolvable */ }
+    candidates.push(path.resolve(__dirname, '..', '..', '..', '.claude', 'helpers'));
+    for (const c of candidates) {
+        if (fs.existsSync(path.join(c, 'hook-handler.cjs')))
+            return c;
+    }
+    return null;
+}
+/**
+ * Re-copy the critical helpers into `helpersDir` and stamp `version`.
+ *
+ * SECURITY (fail-closed): when copying from the installed package, every source
+ * helper is verified against ruflo's Ed25519-signed manifest FIRST — nothing is
+ * copied unless the manifest signature is valid AND each helper's SHA-256
+ * matches. A tampered helper or manifest (e.g. a sibling package's postinstall
+ * overwriting on-disk hook code) is REFUSED, not propagated. The generator
+ * fallback needs no manifest — that content comes from the CLI's own compiled
+ * code, which is already the trust root.
+ */
+async function writeCriticalHelpers(helpersDir, version) {
+    const source = findPackageHelpersDir();
+    if (source) {
+        // 1. Verify the signed manifest against the baked public key.
+        let trusted = null;
+        try {
+            trusted = verifyHelpersManifest(fs.readFileSync(path.join(source, HELPERS_MANIFEST_FILE), 'utf-8'));
+        }
+        catch {
+            trusted = null;
+        }
+        if (!trusted)
+            return { wrote: false, blocked: 'signed helpers manifest missing or signature invalid' };
+        // 2. Verify EVERY source helper's hash before copying ANYTHING (atomic gate).
+        const toCopy = [];
+        for (const name of CRITICAL_HELPERS) {
+            const sp = path.join(source, name);
+            if (!fs.existsSync(sp))
+                continue;
+            const expected = trusted.files[name];
+            if (!expected || sha256Hex(fs.readFileSync(sp)) !== expected) {
+                return { wrote: false, blocked: `integrity check failed for ${name} — refusing to install` };
+            }
+            toCopy.push(name);
+        }
+        // 3. All verified — copy, plus the signed manifest itself as an audit trail.
+        let wrote = false;
+        for (const name of toCopy) {
+            const tp = path.join(helpersDir, name);
+            fs.copyFileSync(path.join(source, name), tp);
+            try {
+                fs.chmodSync(tp, '755');
+            }
+            catch { /* non-fatal */ }
+            wrote = true;
+        }
+        try {
+            fs.copyFileSync(path.join(source, HELPERS_MANIFEST_FILE), path.join(helpersDir, HELPERS_MANIFEST_FILE));
+        }
+        catch { /* non-fatal */ }
+        if (wrote) {
+            try {
+                fs.writeFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version, 'utf-8');
+            }
+            catch { /* non-fatal */ }
+        }
+        return { wrote };
+    }
+    // Fallback: source unresolvable (broken npx paths) — regenerate from the CLI's
+    // OWN compiled generators (the trust root; no external file to verify).
+    const gen = await import('./helpers-generator.js');
+    const files = {
+        'hook-handler.cjs': gen.generateHookHandler(),
+        'intelligence.cjs': gen.generateIntelligenceStub(),
+        'auto-memory-hook.mjs': gen.generateAutoMemoryHook(),
+    };
+    let wrote = false;
+    for (const [name, content] of Object.entries(files)) {
+        const tp = path.join(helpersDir, name);
+        fs.writeFileSync(tp, content, 'utf-8');
+        try {
+            fs.chmodSync(tp, '755');
+        }
+        catch { /* non-fatal */ }
+        wrote = true;
+    }
+    if (wrote) {
+        try {
+            fs.writeFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version, 'utf-8');
+        }
+        catch { /* non-fatal */ }
+    }
+    return { wrote };
+}
+/**
+ * On CLI startup: if an initialized project's critical helpers are stamped older
+ * than the installed CLI version, silently re-copy them. Fast path is a single
+ * stamp read + string compare (sub-ms); the copy runs at most once per version
+ * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
+ * existing hook-handler.cjs — never creates files in an unrelated directory).
+ */
+export async function autoRefreshHelpersIfStale(cwd) {
+    try {
+        const helpersDir = path.join(cwd, '.claude', 'helpers');
+        if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs')))
+            return { refreshed: false };
+        const version = getInstalledCliVersion();
+        let stamped = '';
+        try {
+            stamped = fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim();
+        }
+        catch { /* pre-feature: unstamped */ }
+        if (stamped === version)
+            return { refreshed: false }; // up to date — fast path
+        const res = await writeCriticalHelpers(helpersDir, version);
+        // A blocked refresh is a SECURITY signal (tampered source/manifest) — surface
+        // it, don't advance the stamp, and leave the project's existing helpers intact.
+        if (res.blocked)
+            return { refreshed: false, blocked: res.blocked };
+        return res.wrote ? { refreshed: true, from: stamped || '(unstamped)', to: version } : { refreshed: false };
+    }
+    catch {
+        return { refreshed: false };
+    }
+}
+//# sourceMappingURL=helper-refresh.js.map

package/v3/@claude-flow/cli/dist/src/init/helper-signing.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ruflo helper-signing PUBLIC key (safe to commit). The matching private key is
+ * held out-of-repo and provided to scripts/sign-helpers.mjs at publish time via
+ * $RUFLO_HELPERS_SIGNING_KEY. Rotating the key = replace this constant + re-sign.
+ */
+export declare const RUFLO_HELPERS_PUBKEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAhnFv74/CRcGWd0hL8zjyZ+52bIJ9SfcSgOutuKgo0Vg=\n-----END PUBLIC KEY-----";
+export declare const HELPERS_MANIFEST_FILE = "helpers.manifest.json";
+export interface HelpersManifest {
+    version: string;
+    files: Record<string, string>;
+}
+export interface SignedHelpersManifest {
+    manifest: HelpersManifest;
+    signature: string;
+    algorithm: 'ed25519';
+}
+export declare function sha256Hex(content: string | Buffer): string;
+/**
+ * Deterministic canonical bytes of a manifest — file keys sorted so the signer
+ * and verifier agree byte-for-byte regardless of object insertion order.
+ */
+export declare function canonicalManifestBytes(m: HelpersManifest): Buffer;
+/**
+ * Verify a signed helpers manifest against ruflo's public key. Returns the
+ * trusted file->sha256 manifest, or null on ANY failure (bad signature,
+ * malformed JSON, wrong algorithm). Fail-closed — the caller MUST refuse to
+ * install unverified helpers.
+ */
+export declare function verifyHelpersManifest(signedJson: string, pubkeyPem?: string): HelpersManifest | null;
+//# sourceMappingURL=helper-signing.d.ts.map

package/v3/@claude-flow/cli/dist/src/init/helper-signing.js

@@ -0,0 +1,60 @@
+/**
+ * Ed25519 provenance for the auto-refreshed critical helpers (ADR-174 security).
+ *
+ * The helper auto-refresh copies auto-EXECUTING hook code (`hook-handler.cjs`
+ * etc.) from the installed package into a project. npm verifies the tarball at
+ * INSTALL time, but not the files on disk afterward — a sibling package's
+ * postinstall (or disk tampering) could overwrite them, and the refresh would
+ * faithfully propagate the tampered code. This gate closes that: every helper
+ * is verified against a ruflo-signed manifest before install, and a mismatch is
+ * REFUSED (fail-closed). The public key is baked in below; the private key is
+ * never in the repo (see scripts/sign-helpers.mjs).
+ *
+ * Native Node crypto (RFC 8032 Ed25519), zero external deps — same primitive as
+ * src/appliance/rvfa-signing.ts.
+ */
+import { createHash, verify as edVerify } from 'crypto';
+/**
+ * Ruflo helper-signing PUBLIC key (safe to commit). The matching private key is
+ * held out-of-repo and provided to scripts/sign-helpers.mjs at publish time via
+ * $RUFLO_HELPERS_SIGNING_KEY. Rotating the key = replace this constant + re-sign.
+ */
+export const RUFLO_HELPERS_PUBKEY = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAhnFv74/CRcGWd0hL8zjyZ+52bIJ9SfcSgOutuKgo0Vg=
+-----END PUBLIC KEY-----`;
+export const HELPERS_MANIFEST_FILE = 'helpers.manifest.json';
+export function sha256Hex(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Deterministic canonical bytes of a manifest — file keys sorted so the signer
+ * and verifier agree byte-for-byte regardless of object insertion order.
+ */
+export function canonicalManifestBytes(m) {
+    const files = {};
+    for (const k of Object.keys(m.files).sort())
+        files[k] = m.files[k];
+    return Buffer.from(JSON.stringify({ version: m.version, files }), 'utf-8');
+}
+/**
+ * Verify a signed helpers manifest against ruflo's public key. Returns the
+ * trusted file->sha256 manifest, or null on ANY failure (bad signature,
+ * malformed JSON, wrong algorithm). Fail-closed — the caller MUST refuse to
+ * install unverified helpers.
+ */
+export function verifyHelpersManifest(signedJson, pubkeyPem = RUFLO_HELPERS_PUBKEY) {
+    try {
+        const signed = JSON.parse(signedJson);
+        if (!signed || signed.algorithm !== 'ed25519' || !signed.signature || !signed.manifest)
+            return null;
+        if (!signed.manifest.files || typeof signed.manifest.files !== 'object')
+            return null;
+        const bytes = canonicalManifestBytes(signed.manifest);
+        const ok = edVerify(null, bytes, pubkeyPem, Buffer.from(signed.signature, 'base64'));
+        return ok ? signed.manifest : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=helper-signing.js.map

package/v3/@claude-flow/cli/dist/src/init/helpers-generator.d.ts

@@ -4,6 +4,22 @@
  */
 import type { InitOptions } from './types.js';
 export declare const ATTRIBUTION_FOOTER = "\uD83E\uDD16 Generated with [RuFlo](https://github.com/ruvnet/ruflo)";
+/**
+ * Detect whether a Claude Code PostToolUse payload represents a FAILED tool run.
+ *
+ * Why this matters: the learning substrate had 898 feedback records, 100%
+ * success, 0 failures — because the post-edit/post-task hooks recorded a
+ * hardcoded `success:true` and never inspected the tool outcome. With no
+ * negative examples, the oracle tier can't teach good-vs-bad (see the DB
+ * analysis + ADR-174). Claude Code passes the tool result in the PostToolUse
+ * hook payload (`tool_response`), which for a failed Write/Edit/Bash carries an
+ * error marker. This predicate is the single source of truth the generated
+ * hook inlines, and is unit-tested here so the detection stays honest.
+ *
+ * Conservative: returns true only on a POSITIVE error signal; ambiguous/missing
+ * payloads default to success (matches prior behavior, avoids false failures).
+ */
+export declare function isToolFailure(hookInput: unknown): boolean;
 /**
  * Generate pre-commit hook script
  */

package/v3/@claude-flow/cli/dist/src/init/helpers-generator.js

@@ -9,6 +9,58 @@ import { generateStatuslineScript, generateStatuslineHook } from './statusline-g
 // PR body templates and release notes.  It is NEVER hard-wired into the
 // static command-file templates — those are user-owned content.
 export const ATTRIBUTION_FOOTER = '🤖 Generated with [RuFlo](https://github.com/ruvnet/ruflo)';
+/**
+ * Detect whether a Claude Code PostToolUse payload represents a FAILED tool run.
+ *
+ * Why this matters: the learning substrate had 898 feedback records, 100%
+ * success, 0 failures — because the post-edit/post-task hooks recorded a
+ * hardcoded `success:true` and never inspected the tool outcome. With no
+ * negative examples, the oracle tier can't teach good-vs-bad (see the DB
+ * analysis + ADR-174). Claude Code passes the tool result in the PostToolUse
+ * hook payload (`tool_response`), which for a failed Write/Edit/Bash carries an
+ * error marker. This predicate is the single source of truth the generated
+ * hook inlines, and is unit-tested here so the detection stays honest.
+ *
+ * Conservative: returns true only on a POSITIVE error signal; ambiguous/missing
+ * payloads default to success (matches prior behavior, avoids false failures).
+ */
+export function isToolFailure(hookInput) {
+    if (!hookInput || typeof hookInput !== 'object')
+        return false;
+    const h = hookInput;
+    const tr = (h.tool_response ?? h.toolResponse ?? h.result);
+    if (tr == null)
+        return false;
+    if (typeof tr === 'string') {
+        return /\b(error|failed|failure|exception|not found|no such|permission denied|traceback)\b/i.test(tr);
+    }
+    if (typeof tr === 'object') {
+        const o = tr;
+        if (o.is_error === true || o.isError === true || o.success === false || o.error != null)
+            return true;
+        // Bash tool: non-zero exit code is a failure.
+        const code = (o.exit_code ?? o.exitCode ?? o.code);
+        if (typeof code === 'number' && code !== 0)
+            return true;
+        // Nested content array (Claude tool result shape): {content:[...], is_error:true}
+        if (Array.isArray(o.content) && o.is_error === true)
+            return true;
+    }
+    return false;
+}
+// The exact predicate the generated hook inlines — kept in sync with
+// isToolFailure() above (mirrored, since the generated .cjs has no imports).
+const TOOL_FAILURE_EXPR = '(function(hi){' +
+    'if(!hi||typeof hi!=="object")return false;' +
+    'var tr=hi.tool_response!=null?hi.tool_response:(hi.toolResponse!=null?hi.toolResponse:hi.result);' +
+    'if(tr==null)return false;' +
+    'if(typeof tr==="string")return /\\b(error|failed|failure|exception|not found|no such|permission denied|traceback)\\b/i.test(tr);' +
+    'if(typeof tr==="object"){' +
+    'if(tr.is_error===true||tr.isError===true||tr.success===false||tr.error!=null)return true;' +
+    'var code=tr.exit_code!=null?tr.exit_code:(tr.exitCode!=null?tr.exitCode:tr.code);' +
+    'if(typeof code==="number"&&code!==0)return true;' +
+    'if(Array.isArray(tr.content)&&tr.is_error===true)return true;' +
+    '}return false;})(hookInput)';
 /**
  * Generate pre-commit hook script
  */
@@ -459,6 +511,9 @@ export function generateHookHandler() {
         '  // hook (#1944). Pull `.command` off whichever stdin shape Claude Code sent.',
         '  var toolInputObj = hookInput.toolInput || hookInput.tool_input || {};',
         "  var prompt = hookInput.prompt || hookInput.command || toolInputObj.command || process.env.PROMPT || process.env.TOOL_INPUT_command || args.join(' ') || '';",
+        '  // Capture FAILURES, not just successes, so the learning substrate has',
+        '  // negative examples (see ADR-174 / DB analysis). Mirrors isToolFailure().',
+        '  var toolFailed = ' + TOOL_FAILURE_EXPR + ';',
         '',
         'const handlers = {',
         "  'route': () => {",
@@ -503,10 +558,10 @@ export function generateHookHandler() {
         '    if (intelligence && intelligence.recordEdit) {',
         '      try {',
         "        var file = process.env.TOOL_INPUT_file_path || args[0] || '';",
-        '        intelligence.recordEdit(file);',
+        '        intelligence.recordEdit(file, !toolFailed);',
         '      } catch (e) { /* non-fatal */ }',
         '    }',
-        "    console.log('[OK] Edit recorded');",
+        "    console.log(toolFailed ? '[LEARN] Edit FAILURE recorded' : '[OK] Edit recorded');",
         '  },',
         '',
         "  'session-restore': () => {",
@@ -562,10 +617,10 @@ export function generateHookHandler() {
         "  'post-task': () => {",
         '    if (intelligence && intelligence.feedback) {',
         '      try {',
-        '        intelligence.feedback(true);',
+        '        intelligence.feedback(!toolFailed);',
         '      } catch (e) { /* non-fatal */ }',
         '    }',
-        "    console.log('[OK] Task completed');",
+        "    console.log(toolFailed ? '[LEARN] Task FAILURE recorded' : '[OK] Task completed');",
         '  },',
         '',
         "  'compact-manual': () => {",
@@ -809,10 +864,12 @@ export function generateIntelligenceStub() {
         '    return lines2.join("\\n");',
         '  },',
         '',
-        '  recordEdit: function(file) {',
+        '  recordEdit: function(file, success) {',
         '    if (!file) return;',
         '    ensureDir(DATA_DIR);',
-        '    var line = JSON.stringify({ type: "edit", file: file, timestamp: Date.now() }) + "\\n";',
+        '    // success defaults to true; an explicit false (failed edit) is recorded',
+        '    // so consolidation/distillation gets a negative example (ADR-174).',
+        '    var line = JSON.stringify({ type: "edit", file: file, success: success !== false, timestamp: Date.now() }) + "\\n";',
         '    fs.appendFileSync(PENDING_PATH, line, "utf-8");',
         '  },',
         '',

package/v3/@claude-flow/cli/dist/src/init/statusline-generator.js

@@ -211,13 +211,24 @@ function getLocalAgentDB() {
     const memDb = path.join(CWD, '.swarm', 'memory.db');
     if (fs.existsSync(memDb)) {
       const Q = String.fromCharCode(34);
-      const sql = Q + 'SELECT (SELECT COUNT(*) FROM memory_entries WHERE embedding IS NOT NULL)||' + "'|'" + '||(SELECT COUNT(*) FROM vector_indexes);' + Q;
-      const out = safeExec("sqlite3 'file:" + memDb + "?mode=ro' " + sql, 1500);
-      if (out && out.indexOf('|') !== -1) {
-        const parts = out.split('|');
-        result.vectorCount = parseInt(parts[0], 10) || 0;
-        result.hasHnsw = (parseInt(parts[1], 10) || 0) > 0;
-      }
+      // Two INDEPENDENT statements -- do NOT combine into one. Coupling the
+      // vector count with the vector_indexes row count in a single statement
+      // meant that on a DB missing the vector_indexes table (older/agentdb-
+      // written DBs), the whole statement failed at PREPARE time (SQLite
+      // compiles the full SQL before running), so the valid memory_entries
+      // count was discarded too and the statusline showed Vectors 0 despite
+      // thousands of real vectors. Split so a missing table can only zero the
+      // HNSW flag, never the count. The init self-heal provisions the table so
+      // the flag recovers on the next ruflo init / MCP start.
+      const countSql = Q + 'SELECT COUNT(*) FROM memory_entries WHERE embedding IS NOT NULL;' + Q;
+      const vc = safeExec("sqlite3 'file:" + memDb + "?mode=ro' " + countSql, 1500);
+      if (vc) result.vectorCount = parseInt(vc, 10) || 0;
+      // HNSW flag: separate statement. If vector_indexes is absent, sqlite3
+      // exits non-zero and safeExec returns empty -- hasHnsw stays false (exact
+      // original semantics: at least one index-config row present).
+      const hnswSql = Q + 'SELECT COUNT(*) FROM vector_indexes;' + Q;
+      const hn = safeExec("sqlite3 'file:" + memDb + "?mode=ro' " + hnswSql, 1500);
+      if (hn) result.hasHnsw = (parseInt(hn, 10) || 0) > 0;
     }
   } catch { /* ignore */ }
   return result;

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

@@ -33,6 +33,10 @@ import { daaTools } from './mcp-tools/daa-tools.js';
 import { coordinationTools } from './mcp-tools/coordination-tools.js';
 import { browserTools } from './mcp-tools/browser-tools.js';
 import { browserSessionTools } from './mcp-tools/browser-session-tools.js';
+// ADR-175 — page-agent natural-language intent layer (browser_act). Always
+// registered; degrades to {degraded:true} at call time when page-agent or an
+// OpenAI-compatible LLM provider isn't available.
+import { browserIntentTools } from './mcp-tools/browser-intent-tools.js';
 import { execFileSync } from 'node:child_process';
 // Phase 6: AgentDB v3 controller tools
 import { agentdbTools } from './mcp-tools/agentdb-tools.js';
@@ -89,6 +93,14 @@ function getBrowserTools() {
 function getBrowserSessionTools() {
     return browserSessionTools;
 }
+/**
+ * ADR-175 `browser_act` — always registered like browserSessionTools; the
+ * handler itself resolves page-agent + LLM-provider availability at call
+ * time and returns `{degraded: true}` rather than throwing.
+ */
+function getBrowserIntentTools() {
+    return browserIntentTools;
+}
 /**
  * MCP Tool Registry
  * Maps tool names to their handler functions
@@ -127,6 +139,7 @@ registerTools([
     ...coordinationTools,
     ...getBrowserTools(),
     ...getBrowserSessionTools(),
+    ...getBrowserIntentTools(),
     // Phase 6: AgentDB v3 controller tools
     ...agentdbTools,
     // RuVector WASM tools

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

@@ -115,11 +115,18 @@ export const agenticowSpeculateTools = [
             }
             // Build the generic {label, fn} candidates. Each fn ingests into its own
             // branch handle, then (for 'nearest') probes it so we can score.
+            // Map validated label → explicit branchPath so the branchPath() resolver
+            // below is O(1) instead of re-scanning + re-validating rawCandidates per
+            // candidate (explore() calls branchPath once per candidate → was O(n²)).
+            const explicitBranchPaths = new Map();
             const candidates = rawCandidates.map((c) => {
                 const label = validateLabel(String(c.label));
                 if (!Array.isArray(c.ingest) || c.ingest.length === 0) {
                     throw new Error(`candidate ${label} must ingest at least one vector`);
                 }
+                if (typeof c.branchPath === 'string' && c.branchPath) {
+                    explicitBranchPaths.set(label, c.branchPath);
+                }
                 const records = c.ingest.map((r) => ({
                     ...(Number.isInteger(r.id) ? { id: r.id } : {}),
                     vector: r.vector,
@@ -151,9 +158,9 @@ export const agenticowSpeculateTools = [
                 return 1 / (1 + Math.max(0, r.bestDistance));
             };
             const branchPath = (label) => {
-                const explicit = rawCandidates.find((c) => validateLabel(String(c.label)) === label)?.branchPath;
+                const explicit = explicitBranchPaths.get(label);
                 if (explicit)
-                    return resolveMemoryPath(String(explicit));
+                    return resolveMemoryPath(explicit);
                 return `${basePath}.spec-${safeSegment(label)}.rvf`;
             };
             // ADR-171 promotion gate. For pure memory A/B the `score` IS the chosen