Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix(verify+memory+browser): #1880, #2019, #2015 β€” three precondition/contract fixes + CI guards

ruve4bd9bbcbe72
diff --git a/.github/workflows/v3-ci.yml b/.github/workflows/v3-ci.yml
index 9682398313..74b0eb15fe 100644
--- a/.github/workflows/v3-ci.yml
+++ b/.github/workflows/v3-ci.yml
@@ -18,6 +18,10 @@ on:
- '**/scripts/ruflo-hook.sh'
# pre-bash hook safety (#2017) β€” both handler copies trigger the smoke
- '**/.claude/helpers/hook-handler.cjs'
+ # ruflo-browser rvf create flag (#2015) β€” TS source, plugin shell
+ # scripts, agent-facing recipes all guarded by the same smoke.
+ - 'v3/@claude-flow/cli/src/mcp-tools/browser-session-tools.ts'
+ - 'plugins/ruflo-browser/**'
pull_request:
branches: [main]
paths:
@@ -28,6 +32,9 @@ on:
- '**/hooks/hooks.json'
- '**/scripts/ruflo-hook.sh'
- '**/.claude/helpers/hook-handler.cjs'
+ # ruflo-browser rvf create flag (#2015)
+ - 'v3/@claude-flow/cli/src/mcp-tools/browser-session-tools.ts'
+ - 'plugins/ruflo-browser/**'
# witness manifests / fix list β€” so witness-verify runs on PRs that
# touch them (otherwise a stale per-OS manifest only fails post-merge).
- 'verification/**'
@@ -305,6 +312,79 @@ jobs:
node plugins/ruflo-core/scripts/test-hooks.mjs \
"node $GITHUB_WORKSPACE/v3/@claude-flow/cli/bin/cli.js"
+ browser-rvf-create-flags-smoke:
+ # Regression guard for ruvnet/ruflo#2015 β€” the ruflo-browser
+ # `browser_session_record` MCP tool wraps `ruvector rvf create`.
+ # [email protected] makes `-d, --dimension <n>` required, so before
+ # this fix every session-record call failed with
+ # `error: required option '-d, --dimension <n>' not specified`
+ # and the wrapper returned `{ success: false, error: "rvf create
+ # failed" }`.
+ #
+ # This smoke scans every place we shell out to `rvf create
+ # --kind browser-session` across the repo (TS source, compiled
+ # dist, shell scripts, agent-facing markdown recipes) and fails
+ # if any call is missing the dimension flag.
+ name: browser rvf create flag smoke (#2015)
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: '22'
+
+ - name: Build CLI (so the compiled dist is scanned alongside src)
+ run: |
+ cd v3/@claude-flow/cli
+ npm install --no-audit --no-fund --legacy-peer-deps
+ npm run build
+
+ - name: Static scan of every rvf create call site
+ run: node scripts/smoke-browser-rvf-create-flags.mjs
+
+ witness-verify-precondition-smoke:
+ # Regression guard for ruvnet/ruflo#1880 β€” the 12h scheduled witness
+ # verification runs in a source-only checkout (no `npm ci`, no
+ # `npm run build`). Before this fix, that environment exited 1
+ # (real verification failure) because `@noble/ed25519` wasn't
+ # installed and 87+ dist files referenced by the manifest didn't
+ # exist on disk β€” so the scheduled runner filed a "verification
+ # broken" issue every 12 hours even though nothing was actually
+ # wrong with the signed manifest.
+ #
+ # verify.mjs now reserves exit 2 for precondition failures
+ # (missing dep, source-only checkout) and exit 1 strictly for real
+ # failures (signature invalid, dist file regressed). This smoke
+ # drives both shapes through and asserts the contract holds:
+ # - missing @noble/ed25519 β†’ exit 2 + named in the error
+ # - all-manifest-files missing β†’ exit 2 + precondition tag
+ # - built tree β†’ exit is NEVER 2
+ #
+ # Independent job so a precondition contract break is named clearly
+ # in the CI summary. Wired into witness-verify's `needs:` below.
+ name: witness verify precondition smoke (#1880)
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: '22'
+
+ - name: Install root dependencies (provides @noble/ed25519 for Case 3)
+ run: npm ci --legacy-peer-deps
+
+ - name: Drive precondition + built-tree shapes through verify.mjs
+ shell: bash
+ run: node scripts/smoke-witness-verify-precondition.mjs
+
pre-bash-hook-smoke:
# Regression guard for ruvnet/ruflo#2017 β€” the `pre-bash` PreToolUse hook
# in `.claude/helpers/hook-handler.cjs` is a security gate that refuses to
@@ -711,7 +791,7 @@ jobs:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
- needs: [smoke-install-no-bsqlite, plugin-hooks-smoke, pre-bash-hook-smoke, mcp-protocol-smoke, memory-import-smoke, tool-descriptions-audit, mcp-roundtrip-smoke, plugin-package-audit, cli-npx-install-smoke, hook-command-audit, vector-dim-audit]
+ needs: [smoke-install-no-bsqlite, plugin-hooks-smoke, pre-bash-hook-smoke, witness-verify-precondition-smoke, browser-rvf-create-flags-smoke, mcp-protocol-smoke, memory-import-smoke, tool-descriptions-audit, mcp-roundtrip-smoke, plugin-package-audit, cli-npx-install-smoke, hook-command-audit, vector-dim-audit]
steps:
- name: Checkout code
diff --git a/plugins/ruflo-browser/agents/browser-agent.md b/plugins/ruflo-browser/agents/browser-agent.md
index d27452c9e7..f2572d0c6f 100644
--- a/plugins/ruflo-browser/agents/browser-agent.md
+++ b/plugins/ruflo-browser/agents/browser-agent.md
@@ -12,7 +12,7 @@ Every browser session you open MUST be allocated as an RVF cognitive container a
```bash
SID=$(date +%Y%m%d-%H%M%S)-<task-slug>
-npx -y [email protected] rvf create "$SID.rvf" --kind browser-session
+npx -y [email protected] rvf create "$SID.rvf" --kind browser-session --dimension 384
npx -y [email protected] hooks trajectory-begin --session-id "$SID" --task "<human-task>"
```
diff --git a/plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md b/plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md
index 6319f2811c..49c4e4c7b1 100644
--- a/plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md
+++ b/plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md
@@ -47,7 +47,7 @@ We propose to refactor `ruflo-browser` around a **session-as-skill** architectur
### 1. Session model β€” RVF as the session container
-Every browser session opened by ruflo-browser is allocated an RVF container at session start (`rvf create --kind browser-session --id <session-name>`) and committed at session end (`rvf compact && rvf export`). The container holds:
+Every browser session opened by ruflo-browser is allocated an RVF container at session start (`rvf create --kind browser-session --dimension 384 --id <session-name>`) and committed at session end (`rvf compact && rvf export`). The container holds:
| Slot | Producer | Notes |
|------|----------|-------|
diff --git a/plugins/ruflo-browser/scripts/replay-spike.sh b/plugins/ruflo-browser/scripts/replay-spike.sh
index 4b04a9e2da..4cac02164e 100755
--- a/plugins/ruflo-browser/scripts/replay-spike.sh
+++ b/plugins/ruflo-browser/scripts/replay-spike.sh
@@ -43,7 +43,8 @@ site_record_replay() {
local rvf="$RESULTS_DIR/$sid.rvf"
# 1. Record a minimal baseline interaction
- if ! npx -y [email protected] rvf create "$rvf" --kind browser-session >/dev/null 2>&1; then
+ # #2015: [email protected] requires --dimension on `rvf create`.
+ if ! npx -y [email protected] rvf create "$rvf" --kind browser-session --dimension 384 >/dev/null 2>&1; then
echo "SKIP:$label rvf-create-failed" ; return 2
fi
if ! npx -y [email protected] hooks trajectory-begin --session-id "$sid" --task "spike-$label" >/dev/null 2>&1; then
diff --git a/plugins/ruflo-browser/skills/browser-record/SKILL.md b/plugins/ruflo-browser/skills/browser-record/SKILL.md
index a3f49092cb..938f1d6717 100644
--- a/plugins/ruflo-browser/skills/browser-record/SKILL.md
+++ b/plugins/ruflo-browser/skills/browser-record/SKILL.md
@@ -20,7 +20,7 @@ Primitive on which every other browser skill composes. Opens a named browser ses
1. **Allocate session id and RVF container**:
```bash
SID="$(date +%Y%m%d-%H%M%S)-${TASK_SLUG:-record}"
- npx -y [email protected] rvf create "$SID.rvf" --kind browser-session
+ npx -y [email protected] rvf create "$SID.rvf" --kind browser-session --dimension 384
npx -y [email protected] hooks trajectory-begin --session-id "$SID" --task "$1"
```
2. **Open the browser** via `mcp__claude-flow__browser_open` with the URL.
diff --git a/plugins/ruflo-core/scripts/witness/verify.mjs b/plugins/ruflo-core/scripts/witness/verify.mjs
index 830f2d705b..b02b18f1eb 100644
--- a/plugins/ruflo-core/scripts/witness/verify.mjs
+++ b/plugins/ruflo-core/scripts/witness/verify.mjs
@@ -9,8 +9,13 @@
*
* Exit codes:
* 0 β€” signature valid + all fixes pass or drift (marker present)
- * 1 β€” signature invalid OR any fix regressed/missing
- * 2 β€” bad arguments / file not found
+ * 1 β€” signature invalid OR any fix regressed/missing (real failure)
+ * 2 β€” bad arguments / file not found OR precondition not met
+ * (e.g. @noble/ed25519 not installed, or dist files not built β€”
+ * source-only checkout without `npm ci && npm run build`).
+ * Issue #1880: scheduled runners use this to distinguish a
+ * "needs install+build" environment from a real verification
+ * failure, so we stop filing recurring issues on every cron run.
*/
import { readFileSync, existsSync } from 'node:fs';
@@ -33,6 +38,20 @@ const witness = JSON.parse(readFileSync(manifestPath, 'utf8'));
// ─── signature ────────────────────────────────────────────────────
const sig = await verifySignature(witness, repoRoot);
+// Issue #1880 β€” if @noble/ed25519 isn't installed, this is a
+// precondition failure, not a verification failure. Exit 2 so the
+// scheduled runner can distinguish "install needed" from a real
+// regression and stop filing duplicate issues every 12 hours.
+if (sig.reason === 'noble-ed25519-not-installed') {
+ if (asJson) {
+ console.log(JSON.stringify(
+ { ok: false, precondition: 'noble-ed25519-not-installed', signature: sig },
+ null, 2
+ ));
+ }
+ process.exit(2);
+}
+
// ─── per-fix marker check ─────────────────────────────────────────
const fileResults = witness.manifest.fixes.map((fix) => {
const installed = join(repoRoot, fix.file);
@@ -53,6 +72,35 @@ const summary = {
regressed: fileResults.filter(r => r.status === 'regressed').length,
missing: fileResults.filter(r => r.status === 'missing').length,
};
+
+// Issue #1880 β€” heuristic: if *every* manifest entry is missing AND at
+// least one references a `/dist/` path, the checkout was source-only
+// (no `npm run build`). That's a precondition failure, not a regression.
+// Anything more nuanced (partial dist build, real regressions, etc.)
+// still lands in the normal exit-1 path.
+const allMissing = fileResults.length > 0
+ && summary.missing === fileResults.length;
+const referencesDist = fileResults.some(r => r.file && r.file.includes(`${sep}dist${sep}`)
+ || (r.file && r.file.includes('/dist/')));
+if (allMissing && referencesDist) {
+ if (asJson) {
+ console.log(JSON.stringify(
+ { ok: false, precondition: 'dist-not-built', signature: sig, summary },
+ null, 2
+ ));
+ } else {
+ console.error(
+ `verify.mjs: every manifest entry is missing and the manifest references\n` +
+ `dist/ artifacts. The checkout appears to be source-only (no build run).\n` +
+ `\n` +
+ `Fix: from the repo root, run \`npm ci && npm run build\` (or the\n` +
+ `equivalent for the workspaces witness markers reference) before\n` +
+ `invoking this script. See #1880 for the full diagnosis.`
+ );
+ }
+ process.exit(2);
+}
+
const ok = sig.signatureValid && sig.manifestHashOk && sig.publicKeyReproducible
&& summary.regressed === 0 && summary.missing === 0;
diff --git a/scripts/smoke-browser-rvf-create-flags.mjs b/scripts/smoke-browser-rvf-create-flags.mjs
new file mode 100644
index 0000000000..456755dd94
--- /dev/null
+++ b/scripts/smoke-browser-rvf-create-flags.mjs
@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Regression guard for ruvnet/ruflo#2015.
+ *
+ * [email protected]'s `rvf create` requires a `-d, --dimension <n>`
+ * flag. ruflo-browser 0.2.0's `browser_session_record` MCP tool
+ * invoked the command WITHOUT it, so every call failed with:
+ *
+ * error: required option '-d, --dimension <n>' not specified
+ *
+ * The fix passes `--dimension 384` (matches the MiniLM-L6 default
+ * used by AgentDB indexes and the ONNX embedder). This script
+ * statically scans every place we shell out to `ruvector rvf create`
+ * across the repo and fails if any of them is missing the flag.
+ *
+ * Covers:
+ * - TS source + compiled dist of the MCP tool
+ * - Shell scripts in plugins/ruflo-browser/scripts/
+ * - Doc snippets in plugins/ruflo-browser/{agents,skills}/*.md
+ * (these are agent-facing recipes that get pasted into bashes β€”
+ * if the doc is wrong, agents reproduce the broken call)
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const REPO_ROOT = resolve(process.cwd());
+
+// Find every file that mentions `rvf create` with the browser-session
+// kind. ripgrep is faster than glob+read; fall back to find+grep if rg
+// isn't on the runner.
+let hits;
+try {
+ hits = execSync(
+ `rg -l --no-messages "rvf.{0,8}create" -g '!node_modules' -g '!**/dist/**/*.map' -g '!.git'`,
+ { cwd: REPO_ROOT, encoding: 'utf8' },
+ )
+ .split('\n')
+ .filter(Boolean);
+} catch {
+ hits = execSync(
+ `grep -rl --exclude-dir=node_modules --exclude-dir=.git "rvf create" .`,
+ { cwd: REPO_ROOT, encoding: 'utf8' },
+ )
+ .split('\n')
+ .filter(Boolean);
+}
+
+// We only police call sites that pair `rvf create` with `--kind browser-session`.
+// Other `rvf create` uses (e.g. inside ruvector's own dist or unrelated kinds)
+// aren't in scope of #2015.
+const failures = [];
+const checked = [];
+
+for (const rel of hits) {
+ const path = resolve(REPO_ROOT, rel);
+ if (!existsSync(path)) continue;
+ // Skip worktree clones β€” they're not on the publish path and they
+ // duplicate every finding.
+ if (rel.includes('.claude/worktrees/')) continue;
+ // Skip node_modules just in case the rg ignore didn't match.
+ if (rel.includes('node_modules/')) continue;
+ // Skip stale untracked dist/ at the repo root (the real published
+ // dist lives under v3/@claude-flow/cli/dist/, which IS scanned).
+ if (rel.startsWith('dist/') || rel.startsWith('./dist/')) continue;
+ // Skip this script itself β€” its grep patterns aren't real calls.
+ if (rel.endsWith('smoke-browser-rvf-create-flags.mjs')) continue;
+
+ const content = readFileSync(path, 'utf8');
+
+ // Find every line that has both `rvf create` and `browser-session`.
+ // Multi-line shell quoting is fine β€” the args we care about land
+ // on the same line in every call site we control.
+ const lines = content.split('\n');
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i];
+ if (!/rvf['"\s,]*create/.test(line)) continue;
+ if (!/browser-session/.test(line)) continue;
+
+ checked.push(`${rel}:${i + 1}`);
+
+ // Accept either flag form: `--dimension <n>` or `-d <n>`.
+ const hasFlag = /--dimension\b|(^|[^a-zA-Z0-9_])-d\b/.test(line);
+ if (!hasFlag) {
+ failures.push(`${rel}:${i + 1} missing --dimension on rvf create`);
+ }
+ }
+}
+
+if (checked.length === 0) {
+ console.error('smoke-browser-rvf-create-flags: no call sites matched β€” pattern broken?');
+ process.exit(1);
+}
+
+console.log(`Checked ${checked.length} call site(s):`);
+for (const c of checked) console.log(` - ${c}`);
+
+if (failures.length > 0) {
+ console.error(`\n${failures.length} call site(s) missing --dimension:`);
+ for (const f of failures) console.error(` ${f}`);
+ console.error(`\nFix: append "--dimension 384" (or your project's vector dim)`);
+ console.error(`to the rvf create invocation. See ruvnet/ruflo#2015.`);
+ process.exit(1);
+}
+
+console.log('\nsmoke-browser-rvf-create-flags: all call sites carry --dimension');
diff --git a/scripts/smoke-witness-verify-precondition.mjs b/scripts/smoke-witness-verify-precondition.mjs
new file mode 100644
index 0000000000..16b49182ab
--- /dev/null
+++ b/scripts/smoke-witness-verify-precondition.mjs
@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Regression guard for ruvnet/ruflo#1880.
+ *
+ * The 12-hour scheduled witness verification runs `verify.mjs` in a
+ * source-only checkout (no `npm ci`, no `npm run build`) and conflates
+ * two completely different failure modes:
+ *
+ * 1. `@noble/ed25519` not installed β†’ precondition (install needed)
+ * 2. dist files referenced by manifest β†’ precondition (build needed)
+ * not present on disk
+ * 3. signature actually doesn't verify β†’ real failure
+ * 4. specific dist file regressed β†’ real failure
+ *
+ * Before this guard, all four exited with code 1, so the scheduled
+ * runner filed a duplicate "verification failed" issue every 12 hours
+ * even though nothing was actually wrong with the manifest.
+ *
+ * verify.mjs now reserves exit 2 for preconditions (cases 1 and 2) and
+ * keeps exit 1 strictly for real failures (cases 3 and 4). This smoke
+ * drives both shapes through the script and asserts the contract holds.
+ *
+ * Fails CI if any of:
+ * - missing @noble/ed25519 exit code is anything other than 2
+ * - all-files-missing manifest exit code is anything other than 2
+ * - precondition output missing the operator-facing fix hint
+ * - precondition output missing the machine-parseable `reason` / `precondition` field
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const REPO_ROOT = process.cwd();
+const VERIFY = resolve(REPO_ROOT, 'plugins/ruflo-core/scripts/witness/verify.mjs');
+const REAL_MANIFEST = resolve(REPO_ROOT, 'verification/macos/manifest.md.json');
+
+if (!existsSync(VERIFY)) {
+ console.error(`smoke: not found: ${VERIFY}`);
+ process.exit(1);
+}
+if (!existsSync(REAL_MANIFEST)) {
+ console.error(`smoke: not found: ${REAL_MANIFEST}`);
+ process.exit(1);
+}
+
+const failures = [];
+
+function record(name, condition, detail) {
+ if (condition) {
+ console.log(` PASS ${name}`);
+ } else {
+ console.log(` FAIL ${name}`);
+ if (detail) console.log(` ${detail}`);
+ failures.push(name);
+ }
+}
+
+// ── Case 1: @noble/ed25519 missing β†’ exit 2 (precondition) ──────────
+// Drop verify.mjs into an empty root with no node_modules anywhere up
+// the tree, so the ed25519 probe fails on every candidate.
+console.log('\nCase 1: @noble/ed25519 not installed (source-only)');
+{
+ const tmp = mkdtempSync(join(tmpdir(), 'witness-smoke-nodep-'));
+ // verify.mjs's probes use createRequire(join(root, 'noop.js')) which
+ // walks up from `root`. Putting `root` deep under tmp ensures Node
+ // walks /tmp/.../node_modules (absent) then /tmp/node_modules (absent)
+ // then /node_modules (absent on CI) β€” no resolution.
+ const isolatedRoot = join(tmp, 'isolated', 'repo');
+ mkdirSync(isolatedRoot, { recursive: true });
+ // Stub node_modules to mask any system-level @noble/ed25519 install.
+ mkdirSync(join(isolatedRoot, 'node_modules'), { recursive: true });
+
+ const out = spawnSync('node', [VERIFY, '--manifest', REAL_MANIFEST, '--root', isolatedRoot, '--json'], {
+ encoding: 'utf8',
+ env: { ...process.env, NODE_PATH: '' },
+ });
+
+ record(
+ 'exit code is 2 (precondition), not 1',
+ out.status === 2,
+ `got exit=${out.status}, stdout=${out.stdout?.slice(0, 200)}, stderr=${out.stderr?.slice(0, 200)}`,
+ );
+ record(
+ 'stderr names @noble/ed25519 and the fix command',
+ /@noble\/ed25519/.test(out.stderr) && /npm (ci|install)/.test(out.stderr),
+ `stderr=${out.stderr?.slice(0, 400)}`,
+ );
+ record(
+ 'JSON output carries machine-parseable precondition tag',
+ /noble-ed25519-not-installed/.test(out.stdout),
+ `stdout=${out.stdout?.slice(0, 200)}`,
+ );
+
+ rmSync(tmp, { recursive: true, force: true });
+}
+
+// ── Case 2: all manifest files missing β†’ exit 2 (precondition) ──────
+// Point verify.mjs at an isolated root that DOES have @noble/ed25519
+// reachable (symlinked from the real install) but has none of the
+// manifest's dist/ files β€” mimicking a clean clone with no build run.
+console.log('\nCase 2: all manifest files missing (source-only, deps installed)');
+{
+ const tmp = mkdtempSync(join(tmpdir(), 'witness-smoke-nobuild-'));
+ // Make @noble/ed25519 reachable by symlinking node_modules.
+ const realNodeModules = resolve(REPO_ROOT, 'node_modules');
+ if (existsSync(join(realNodeModules, '@noble', 'ed25519'))) {
+ mkdirSync(join(tmp, 'node_modules', '@noble'), { recursive: true });
+ // Use a relative symlink that survives the spawn.
+ const src = join(realNodeModules, '@noble', 'ed25519');
+ const dst = join(tmp, 'node_modules', '@noble', 'ed25519');
+ try {
+ // fs.symlinkSync via spawnSync to avoid extra import for the rare-path branch.
+ spawnSync('ln', ['-s', src, dst]);
+ } catch { /* best-effort */ }
+ }
+
+ const out = spawnSync('node', [VERIFY, '--manifest', REAL_MANIFEST, '--root', tmp, '--json'], {
+ encoding: 'utf8',
+ });
+
+ // We accept either:
+ // - exit 2 with precondition=dist-not-built (the new behavior)
+ // - exit 2 with precondition=noble-ed25519-not-installed (if the
+ // symlink trick didn't satisfy the probe on this runner β€” also a
+ // precondition, still not a real failure)
+ // We do NOT accept exit 1 β€” that's the bug this guard exists to catch.
+ record(
+ 'exit code is 2 (precondition), not 1',
+ out.status === 2,
+ `got exit=${out.status}, stdout head=${out.stdout?.slice(0, 200)}, stderr head=${out.stderr?.slice(0, 200)}`,
+ );
+ record(
+ 'output carries a precondition tag',
+ /noble-ed25519-not-installed|dist-not-built/.test(out.stdout + out.stderr),
+ `combined output=${(out.stdout + out.stderr).slice(0, 400)}`,
+ );
+
+ rmSync(tmp, { recursive: true, force: true });
+}
+
+// ── Case 3: built tree β†’ never exit 2 (precondition is one-way) ─────
+// On a built tree the verifier may produce 0 (clean) or 1 (some real
+// regression caught) β€” both mean verification actually ran. What it
+// must NEVER produce here is exit 2, because that would mean a built
+// tree was mis-classified as "needs install/build" and the scheduled
+// runner would silently skip filing real regressions.
+console.log('\nCase 3: built tree never reports precondition');
+{
+ const out = spawnSync('node', [VERIFY, '--manifest', REAL_MANIFEST], {
+ encoding: 'utf8',
+ cwd: REPO_ROOT,
+ });
+ record(
+ 'exit code is NOT 2 (built tree should never be flagged as a precondition miss)',
+ out.status !== 2,
+ `got exit=${out.status}, tail=${(out.stdout + out.stderr).slice(-300)}`,
+ );
+}
+
+console.log('');
+if (failures.length > 0) {
+ console.error(`smoke-witness-verify-precondition: ${failures.length} check(s) failed:`);
+ for (const f of failures) console.error(` - ${f}`);
+ process.exit(1);
+}
+console.log('smoke-witness-verify-precondition: all checks passed');
diff --git a/v3/@claude-flow/cli/src/mcp-tools/browser-session-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/browser-session-tools.ts
index d9fbd42e8a..6352cbf209 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/browser-session-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/browser-session-tools.ts
@@ -112,8 +112,17 @@ export const browserSessionTools: MCPTool[] = [
const dir = (input.rvf_dir as string | undefined) ?? (await ensureSessionsDir());
const rvfPath = path.join(dir, `${sessionId}.rvf`);
- // 1. RVF allocate
- const rvf = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'create', rvfPath, '--kind', 'browser-session'], { timeout: 60000 });
+ // 1. RVF allocate.
+ // Issue #2015: [email protected] requires `-d, --dimension <n>` for
+ // `rvf create`. Without it the command exits non-zero and the
+ // tool returned `{ success: false, error: "rvf create failed" }`
+ // for every invocation. 384 matches the MiniLM-L6 default used by
+ // the rest of the toolchain (ONNX embedder + AgentDB indexes).
+ const rvf = await shell(
+ 'npx',
+ ['-y', RUVECTOR_PIN, 'rvf', 'create', rvfPath, '--kind', 'browser-session', '--dimension', '384'],
+ { timeout: 60000 },
+ );
if (!rvf.success) return fail('rvf create failed', { detail: rvf.error, stderr: rvf.stderr, sessionId, rvfPath });
// 2. trajectory-begin
diff --git a/v3/@claude-flow/memory/src/controller-registry.test.ts b/v3/@claude-flow/memory/src/controller-registry.test.ts
index 47fe2788ad..225fe93d75 100644
--- a/v3/@claude-flow/memory/src/controller-registry.test.ts
+++ b/v3/@claude-flow/memory/src/controller-registry.test.ts
@@ -404,6 +404,65 @@ describe('ControllerRegistry', () => {
});
expect(registry.isEnabled('learningBridge')).toBe(false);
});
+
+ // Regression guard for ruvnet/ruflo#2019.
+ //
+ // [email protected]'s `getController()` switch only handles
+ // memory/reflexion/skills/causal/causalGraph and THROWS
+ // `Unknown controller: vectorBackend` for everything else. The
+ // registry's old try/catch silently swallowed that throw and
+ // returned null β€” so `vectorBackend` (and `graphAdapter`) reported
+ // `enabled: false` even though the field is right there on the
+ // agentdb instance. The fix probes `agentdb[name]` directly before
+ // falling back to getController.
+ it('vectorBackend/graphAdapter: prefers direct property over getController (issue #2019)', async () => {
+ const fakeVectorBackend = { kind: 'vectorBackend' };
+ const fakeGraphAdapter = { kind: 'graphAdapter' };
+ // Simulate [email protected]: fields exist, but getController
+ // throws Unknown controller for anything not in the small switch.
+ const fakeAgentDb: any = {
+ vectorBackend: fakeVectorBackend,
+ graphAdapter: fakeGraphAdapter,
+ getController(name: string) {
+ if (name === 'memory' || name === 'reflexion') return null;
+ throw new Error(`Unknown controller: ${name}`);
+ },
+ };
+
+ await registry.initialize({
+ backend: mockBackend,
+ agentdb: fakeAgentDb,
+ });
+
+ // Both controllers must be reachable via the direct property
+ // probe, NOT silently null because getController threw.
+ expect(registry.get('vectorBackend')).toBe(fakeVectorBackend);
+ expect(registry.get('graphAdapter')).toBe(fakeGraphAdapter);
+ expect(registry.isEnabled('vectorBackend')).toBe(true);
+ expect(registry.isEnabled('graphAdapter')).toBe(true);
+ });
+
+ // Companion guard: if a future agentdb exposes these via
+ // getController instead of as direct fields, we must still find
+ // them β€” proves the fallback path stays intact.
+ it('vectorBackend: falls back to getController when no direct property exists (issue #2019)', async () => {
+ const fakeVectorBackend = { kind: 'vectorBackend-via-controller' };
+ const fakeAgentDb: any = {
+ // No `.vectorBackend` field at all.
+ getController(name: string) {
+ if (name === 'vectorBackend') return fakeVectorBackend;
+ return null;
+ },
+ };
+
+ await registry.initialize({
+ backend: mockBackend,
+ agentdb: fakeAgentDb,
+ });
+
+ expect(registry.get('vectorBackend')).toBe(fakeVectorBackend);
+ expect(registry.isEnabled('vectorBackend')).toBe(true);
+ });
});
// ----- Health Check -----
diff --git a/v3/@claude-flow/memory/src/controller-registry.ts b/v3/@claude-flow/memory/src/controller-registry.ts
index 6b39a46263..f58c0b3c90 100644
--- a/v3/@claude-flow/memory/src/controller-registry.ts
+++ b/v3/@claude-flow/memory/src/controller-registry.ts
@@ -136,6 +136,16 @@ export interface RuntimeConfig {
/** Backend instance to use (if pre-created) */
backend?: IMemoryBackend;
+
+ /**
+ * Pre-initialized AgentDB instance to use. When provided, the
+ * registry skips its own dynamic-import / initialize cycle and uses
+ * this instance as-is β€” useful for testing, multi-registry sharing,
+ * and consumers that already hold an AgentDB they want governed by
+ * the registry. Issue #2019 added the regression tests that depend
+ * on this injection point.
+ */
+ agentdb?: unknown;
}
/**
@@ -327,13 +337,20 @@ export class ControllerRegistry extends EventEmitter {
return entry.instance as T;
}
- // Fall back to AgentDB internal controllers
- if (this.agentdb && typeof this.agentdb.getController === 'function') {
- try {
- const controller = this.agentdb.getController(name);
- if (controller) return controller as T;
- } catch {
- // Controller not available in AgentDB
+ // Fall back to AgentDB internal controllers. Issue #2019:
+ // probe `agentdb[name]` first so we don't depend on the upstream
+ // getController switch knowing about every field it carries.
+ if (this.agentdb) {
+ const agentdb: any = this.agentdb;
+ const direct = agentdb[name];
+ if (direct) return direct as T;
+ if (typeof agentdb.getController === 'function') {
+ try {
+ const controller = agentdb.getController(name);
+ if (controller) return controller as T;
+ } catch {
+ // Upstream switch threw for an unknown name β€” fine, fall through.
+ }
}
}
@@ -347,12 +364,16 @@ export class ControllerRegistry extends EventEmitter {
const entry = this.controllers.get(name);
if (entry?.enabled) return true;
- // Check AgentDB internal controllers
- if (this.agentdb && typeof this.agentdb.getController === 'function') {
- try {
- return this.agentdb.getController(name) !== null;
- } catch {
- return false;
+ // Issue #2019: same direct-then-fallback shape as get() above.
+ if (this.agentdb) {
+ const agentdb: any = this.agentdb;
+ if (agentdb[name]) return true;
+ if (typeof agentdb.getController === 'function') {
+ try {
+ return agentdb.getController(name) !== null;
+ } catch {
+ return false;
+ }
}
}
@@ -458,6 +479,14 @@ export class ControllerRegistry extends EventEmitter {
* Initialize AgentDB instance with dynamic import and fallback chain.
*/
private async initAgentDB(config: RuntimeConfig): Promise<void> {
+ // Caller-supplied agentdb wins β€” used by tests (#2019 regression
+ // guards) and by consumers that own the AgentDB lifecycle.
+ if (config.agentdb) {
+ this.agentdb = config.agentdb;
+ this.emit('agentdb:initialized');
+ return;
+ }
+
try {
// Validate dbPath to prevent path traversal
const dbPath = config.dbPath || ':memory:';
@@ -907,13 +936,30 @@ export class ControllerRegistry extends EventEmitter {
case 'vectorBackend':
case 'graphAdapter': {
- // These are accessed via AgentDB internal state, not direct construction
+ // These are accessed via AgentDB internal state, not direct
+ // construction. Issue #2019: [email protected]'s
+ // `getController()` switch only handles
+ // memory/reflexion/skills/causal/causalGraph and throws
+ // `Unknown controller: vectorBackend` for everything else β€”
+ // which a try/catch silently swallowed, leaving the controller
+ // permanently `enabled: false` even though the field is right
+ // there on the agentdb instance (`agentdb.vectorBackend` is
+ // assigned in AgentDB.initialize()).
+ //
+ // Prefer the direct-property access. Fall back to
+ // `getController` only if the field is absent β€” preserves
+ // forward-compat with a future agentdb that wires
+ // vectorBackend / graphAdapter into the switch but stops
+ // exposing them as public fields.
if (!this.agentdb) return null;
+ const agentdb: any = this.agentdb;
+ const direct = agentdb[name];
+ if (direct) return direct;
try {
- if (typeof this.agentdb.getController === 'function') {
- return this.agentdb.getController(name) ?? null;
+ if (typeof agentdb.getController === 'function') {
+ return agentdb.getController(name) ?? null;
}
- } catch { /* fallthrough */ }
+ } catch { /* upstream switch threw for an unknown name */ }
return null;
}