ruflo

Patch release. Three fixes from the issue backlog, each confirmed in source before any change and each with a regression test proven to fail without the fix.

A curate can no longer destroy a user's memory index (#3224)

AutoMemoryBridge.curateIndex() rebuilt MEMORY.md from its own topic files and overwrote whatever was there. The #1556 guard only skipped the write when nothing matched — but the bridge writes the first topic file itself, so the guard protected exactly one sync and then stopped applying. The reporter measured a hand-curated index of 75 lines and 49 links reduced to a 6-line stub.

A curate may now grow or reorder the index and never shrink it. When the generated view is smaller, the existing file is left untouched, the generated view is written beside it as MEMORY.generated.md, and the bridge emits index:preserved. The old failure was silent; a silent refusal would only be a quieter version of the same problem.

autoStart: false is honoured (#3278)

Two mismatches were stacked:

	what init writes	what the check read
file	.claude/settings.json	claude-flow.config.json
key	claudeFlow.daemon.autoStart	daemon.autostart

A different file and a different capital S, so the setting a fresh project ships was never consulted — under a comment reading "Opt-in only — prevents unintended token consumption (#1427, #1330)". Both files and both spellings are now read.

Reads disclose the store they did not search (#3228, in part)

3.41.1 shipped the sibling-store disclosure in memory list alone. retrieve, search and an empty list kept returning a clean negative while the rows sat in the file they do not read — on the reported Windows install, 31,673 rows answering found:false.

Still not fixed: the Windows 0xC0000409 abort on a ~4.4 GB allocation with the native bridge enabled. That is #2948 and this release does not touch it. On Windows the split is now visible, not healed.

Install

npx ruflo@3.41.2

Merge commit df87b0db338a.

Patch release. Two fixes, both reported by people hitting them rather than found in-house.

Memory path identity (#3196)

An explicit database path now selects that database. The bridge cached one registry globally, so the first caller to touch it decided the file for the whole process and every later caller's --path or CLAUDE_FLOW_DB_PATH was accepted and then silently ignored. A CLI write and an MCP write landed in two files, both reporting success, and neither interface could see the other's rows.

memory list also stopped printing a confident total for one store while rows sat unread in its sibling — it now names the store it did not read.

Reported downstream by pacphi/agentic-kit#213.

Not done deliberately: merging the two database files. #2786 gave AgentDB its own plaintext file so native better-sqlite3 never opens an encrypted memory.db. Unifying them would re-break encryption at rest.

Seraphina truncation (#3267)

Seraphina no longer passes a truncated reasoning dump off as coordination guidance. The routed model spent its whole token budget reasoning and never emitted its JSON, and the resulting empty proposal list read as the swarm needs nothing — the one conclusion a coordinator must never reach by accident.

Install

npx ruflo@3.41.1

Merge commit cda8b04f6ae1.

RuFlo 3.41.0 — Join the open swarm in four commands

Any machine running RuFlo can now join a shared, signed, invite-gated swarm at x.ruv.io with a key only it holds. No Tailscale, no VPN, no account.

Step-by-step guide with troubleshooting: https://gist.github.com/ruvnet/6d3202cc7030e32169e8d5ac73b4e870 Illustrated explainer: The Swarm Wall (Cognitum Media plates)

Try it

npx ruflo@latest federation join --code v2.…     # 1 · get in with your own key (code comes to you privately)
npx ruflo@latest federation roster               # 2 · you are listed
npx ruflo@latest federation claims               # 3 · who owns what
npx ruflo@latest federation sync                 # 4 · read what the swarm posted

Then in Claude Code: claude mcp add --transport http --scope user x-ruv-io https://x.ruv.io/mcp

What's new

• ruflo federation command (#3256): join, sync, roster, claims, registry, plus admin-gated invite, admit, publish. Self-service join generates ~/.ruflo/nostr.key (0600), redeems the invite with a NIP-98 signature, and proves membership with NIP-42.
• Public and private swarm channels (#3261, ADR-386): ruflo federation channel --action create|grant|accept|publish|read|list. Private channels are NIP-44 encrypted with keys the gateway never sees.
• x.ruv.io gateway plugin (#3255): MCP at https://x.ruv.io/mcp, WebSocket proxy, ruv://federation/registry, ruv://swarm/roster, ruv://claims/board, ruv://swarm/channels. Admin writes are token-gated and fail closed.
• Seraphina (#3256): swarm coordinator via the cognitum meta-llm. seraphina_guidance { goal } returns guidance, proposals and risks. Advisory only.
• Canonical relay wss://relay.ruv.io. Sign the NIP-42 relay tag with this exact address; the old *.run.app host still works as legacyRelay.
• 15 federation MCP tools ship in the RuFlo MCP server.
• CI: @metaharness/darwin pinned to 0.10.2 so the pin-drift and clean-install gates are green again (#3262); skills and gateway docs cover channels (#3263).

Validated before this release

• 67 CLI tests and 12 gateway tests green; all 23 workflows green on main.
• Fresh npm install ruflo@latest on a clean cache: federation join with a new key, registry, roster, sync, and a public-channel publish/read round trip against the live relay.
• Relay E2E on three paths: direct wss://relay.ruv.io, the legacy host, and proxied through wss://x.ruv.io.
• Private-channel E2E from a second, independent key: plaintext for members, ciphertext only for non-members.

Known

• ruflo verify reports the same one stale witness marker (#1697 rvf-wasm overrides) as 3.40.0; manifest refresh is tracked separately.

Packages

@claude-flow/cli, claude-flow, ruflo → 3.41.0 (latest, alpha, v3alpha).

🕸️ Cross-Host Federation + Claims

Coordinate agents across machines with signed, verifiable messages and work claims. Two coordinators — use either alone or together:

• Local mesh (agentbbs): HTTP pull, Ed25519-signed, pinned keys. Works over Tailscale, LAN, VPN, or loopback — no Tailscale required.
• Slack: coordinate in a channel thread with structured messages. Zero infrastructure.

Install

npx ruflo@latest --version   # 3.40.0

Quick start — join the mesh (run on each host)

1. federation_bbs_identity {}                              → your nodeId + publicKey
2. federation_bbs_peer_add { nodeId, publicKey, url }      → pin every other node
3. federation_bbs_serve { bindHost:"<your routable IP>", port:7777 }
4. federation_bbs_register { roomLabel:"#coordination" }
5. federation_bbs_sync { roomId:"<from step 4>" }          → on a 15–30s timer

Unsigned, misattributed, oversize, or over-hop messages are dropped and counted — a hostile or looping peer can't corrupt the log.

Claims — coordinate who owns what

Runtime tools: claims_claim, claims_release, claims_handoff, claims_status. Cross-host, publish claim events:

{ "type":"ClaimIssued", "from":"nodeA", "resourceId":"deploy-api", "ttlSeconds":3600 }

One owner per resource. Claim → wait for the coordinator's ClaimAck → then do the work.

Security

Every mesh message is Ed25519-verified against a pinned key. Registry-anchored pinning refuses any endpoint presenting a different key for a known node (identity-hijack / MITM protection). Private keys never leave the host. Don't put secrets in message payloads.

What's also in 3.40.0

• Restored memory search recall (a real regression: the default threshold made keyword recall impossible) — #3252
• Full CLI test suite green (69 → 0 failures)

📖 Full step-by-step guide, protocol reference, GCP-secret bootstrap, and troubleshooting: https://gist.github.com/ruvnet/2fbad4d0e3bc02cc7d47b4f6fdd2c205

🤖 Generated with RuFlo

Patch release shipping #3250.

Fixed

• federation_bbs_* tools were unconditionally degraded. All four tools (register / publish / watch / human_join) gated on await import('agentbbs'). The published agentbbs package is a CLI-only launcher — its tarball contains only bin/agentbbs.js, package.json and README.md, with no main, no exports, and no root index.js for Node to fall back to. That import could never resolve, so the tools reported degraded: true no matter whether agentbbs was installed and working. Replaced with a subprocess presence probe.
• Probe shell gated to win32. The follow-up hardening: shell: true was unconditional while the probed binary comes from AGENTBBS_BIN, and under a shell that argument is command-interpreted — a crafted value ran a trailing command (verified locally). POSIX now spawns without a shell; Windows keeps cmd.exe so the agentbbs.cmd shim still resolves via PATHEXT. Matches the existing convention in browser-tools.ts, commands/init.ts and init/helpers-generator.ts.
• @noble/ed25519 no longer externalized in tests. It is a hard dependency of @claude-flow/cli, not an optional one, and externalizing it broke dynamic-import resolution under Vite's SSR transform.

Scope

This makes the Phase 1 local room/envelope surface functional when agentbbs is genuinely installed. It does not implement cross-host federation — that remains Phase 2+.

Install

npx ruflo@latest

All three packages (@claude-flow/cli, claude-flow, ruflo) are at 3.39.3 on latest, alpha, and v3alpha.

🤖 Generated with RuFlo

https://claude.ai/code/session_013u4pmL9ZUAXb6usVQgNo67

⚠️ Upgrade from 3.39.1 — its CVE fix was incomplete

3.39.1 shipped a fast-uri bump that never reached users. The root package.json was updated, but @claude-flow/cli carried its own hard pin "fast-uri": "3.1.5" — and that is the package that actually ships. A fresh npm install ruflo@3.39.1 still resolved fast-uri@3.1.5, squarely inside the advisory range.

This was caught by post-publish validation (fresh-installing the published tarball, not reading the lockfile) and is fixed here. If you are on 3.39.1, upgrade.

ruflo@3.39.1
└─┬ @claude-flow/cli@3.39.1
  ├─┬ ajv@8.20.0
  │ └── fast-uri@3.1.5 deduped
  └── fast-uri@3.1.5      ← the hard pin the root bump did not override

Verified on 3.39.2 by fresh install: resolved fast-uri@3.1.7 ✅

---

Security — GHSA-5jgf-p345-68v8 (high, CVSS 7.5) — #3222

fast-uri host confusion via skipped IDN canonicalization on scheme-relative references. Advisory range >=3.1.3 <3.1.6; we were pinned at exactly 3.1.5.

• @claude-flow/cli: fast-uri 3.1.5 → ^3.1.6 (the shipping dependency)
• ruflo: added "fast-uri": ">=3.1.6" override so the wrapper cannot regress independently
• Also clears the ajv high that inherited it

Credit to @aeonframework (#3222) for the original report and patch.

Memory — a gated native bridge was reported as the active backend — #3228

On Windows the #3024 kill-switch makes getRegistry() return null, so memory reads/writes silently fall back to the sql.js store (memory.db) instead of the AgentDB corpus (agentdb-memory.db).

The failure mode is why this matters: a canary store/retrieve round-trip succeeds — both halves use the same unintended file — while an existing live-store key returns found: false against 31,673 real rows. A normal smoke test cannot detect it.

The status surface hid the substitution. getHNSWStatus() gated its bridge branch on whether the bridge module was loaded — which it is, even when the registry is gated off — so describeBackend() printed sqlite (bridge, brute-force cosine) for a store the bridge never touched.

Now gates on whether the bridge is permitted to be the active path, and the backend label names the gate and its reason.

Deliberately out of scope: the opt-in allocation abort (#2948, 0xC0000409 on a ~4.4 GB allocation) and rerouting the fallback to the AgentDB corpus. Both need Windows validation. This release makes the silent case loud, which is what the report asked for first.

Thanks to @seo-yas for an unusually thorough report — line-numbered root cause across three files, a three-arm controlled reproduction, and file-level before/after hashes.

Swarm — AgentPool could never detect a dead agent — #3242 / #3243

AgentPool.performHealthChecks() stamped lastHeartbeat = now on every "still healthy" tick, and updateAgentHeartbeat() — the only other way to advance that field — has zero call sites anywhere in v3/.

So the health check's own tick was the sole thing keeping every pooled agent's heartbeat fresh: timeSinceLastActivity could never exceed one interval, the interval × 3 threshold could never be crossed, and replaceUnhealthyAgent() could never fire — for any agent, in any pool, ever. The check refreshed the very field it was checking.

Fixed by removing the self-stamping side effect (one line), matching the correct sibling pattern in UnifiedSwarmCoordinator.checkHeartbeats(). Adds agent-pool.test.ts (3 tests; baseline fails 2 of 3, candidate passes 3 of 3 under stash isolation).

Scope: @claude-flow/swarm is not currently reachable from the shipped CLI, so this is a package-internal correctness fix rather than a user-facing hot-path change. Disclosed by the evaluating run's own adversarial critic.

Known issues

• clean-install / pin-drift CI checks fail — @metaharness/darwin is pinned ~0.9.0 while npm latest is 0.10.2 (#3219). Pre-existing and unrelated; deliberately not bundled here, since 0.9 → 0.10 on a 0.x package is semver-breaking and does not belong in a security patch.
• 8 remaining high-severity advisories come from the transformers/onnxruntime/adm-zip chain inside upstream agentdb/agentic-flow and are not pinnable from this repo.

Install

npx ruflo@latest --version   # 3.39.2

All three packages published at 3.39.2 with latest, alpha, and v3alpha aligned: @claude-flow/cli, claude-flow, ruflo.

Full changelog: https://github.com/ruvnet/ruflo/compare/v3.39.0...v3.39.2

Patch release covering everything landed since 3.38.21.

Fixes

• #3221 — EnhancedModelRouter could escalate a task to a stronger tier while forwarding a stale modelId chosen for the cheaper tier, and first-call dispatch treated that identity as authoritative — so a security-sensitive task classified for a strong model could still execute against a weaker one. Forwarded identity metadata is now gated on the base model matching the escalated model.
• #3177 — bounded two ReDoS-prone patterns, made PII regexes stateless, and made the confidence pass O(P).
• #3169 — wired embedding-cosine into SmartRetrieval's MMR step.
• #3184 — wired real cold-start measurement and removed a fabricated V2-vs-V3 benchmark.
• #3204 — fixed two stale main-tree Test Suite failures (embedding width; hook-handler exports).
• #3203 — added v3/@claude-flow/mcp to the root npm workspaces so npm ci resolves the unpublished alpha.10 pin.

Note on the version number

3.38.22 is skipped. @claude-flow/cli's publish for that version stuck in npm's "staged" state — the umbrella packages went live while the CLI itself 404'd, and the registry then refused to republish over the staged entry even after unpublishing it. All three packages moved to 3.38.23 together rather than leave the release train out of lockstep.

Install

npx ruflo@latest

All three packages (@claude-flow/cli, claude-flow, ruflo) are at 3.38.23 on latest, alpha, and v3alpha.

🤖 Generated with RuFlo

https://claude.ai/code/session_01Ff2xRKvYrqXJhefvcapfE1

Fixed

• #3155 — ruflo mcp start -t http: entries stored via the bridge were unreadable after a bridge restart (found:false, memory_list empty), even though .swarm/memory.db held them and the CLI read them fine. Root cause: initializeMemoryDatabase() seeded the process-wide ControllerRegistry singleton with the sql.js-facing memory.db path instead of the dedicated agentdb-memory.db path. Fixed in #3156.
• #3059 (CI) — agentic-flow-agent.test.ts asserted result.duration strictly > 0; under coarse CI clock resolution a ~1ms task's duration could legitimately read 0, flaking the test-ratchet gate on main. Relaxed to >= 0.

Known, separately-tracked gap (not in this release)

@claude-flow/mcp is pinned to 3.0.0-alpha.10 in root/CLI package.json (bumped in the 3.38.20 release commit) but that exact version was never published standalone to npm — only alpha.9 exists on the registry. This breaks a fresh npm ci inside the ruvnet/ruflo monorepo itself (confirmed failing on CI). It does not affect end users installing ruflo/@claude-flow/cli from npm, since @claude-flow/mcp ships bundled inside those tarballs. Filed for follow-up.

Fix

• statusline: stop pinning intelligence to a hardcoded 0% (#3092, closes #3091)

  intelligencePct had exactly one assignment in the whole statusline helper, inside the local-CLI fallback path. Every other read used it as-is, and the local-overlay repair pass — which already covers ADRs, AgentDB, tests, hooks, integration, and security — never touched system. So any CLI failure (a source-only plugin-marketplace checkout with no install step, or an npx fetch dying in a workspace root with no version field — both reachable under ordinary conditions) silently pinned the brain segment to a literal 0% beside sibling segments that were still rendering live data, with nothing to tell them apart.

  getLocalIntelligence() now joins the local-overlay set: it derives the percentage from .claude-flow/neural/patterns.json (project, then home) whenever the CLI didn't already report a positive value, with the pattern-count parse cached on the store's mtime+size so a large store (14.5 MB / 1,277 patterns measured) doesn't get re-parsed on every prompt render. Unknown now renders as — instead of 0%, so a genuinely-absent measurement is no longer indistinguishable from a real zero.

  Applied identically to both committed copies of the helper (.claude/helpers/statusline.cjs and v3/@claude-flow/cli/.claude/helpers/statusline.cjs).

🤖 Generated with claude-flow

Supersedes v3.38.17 and v3.38.18, both of which shipped with a corrupted dependency graph due to a publish race between two concurrent sessions working this checkout simultaneously (see the postmortem note below). v3.38.17/3.38.18 are now deprecated on npm for all three packages.

What's actually fixed (same content as v3.38.18 intended, now correctly published)

• #2992 — Windows CI Build V3 matrix job pinned to windows-2022 (was windows-latest, which moved to VS2026 — node-gyp can't detect it, breaking native builds for hnswlib-node/better-sqlite3).
• #2977 — @claude-flow/memory's controller-registry.ts no longer attempts dead import('agentdb') calls for 8 exports no installable agentdb range provides. hierarchicalMemory/memoryConsolidation now go straight to their working fallback implementations; the other 6 controllers with no fallback return null directly. agentdb_consolidate's stub response now says explicitly that it didn't run. Published as @claude-flow/memory@3.0.0-alpha.23.
• #2968 — new read-only doctor check (checkMemoryPersistenceDriver) reports whether the active SQLite driver is native better-sqlite3 (durable) or the sql.js fallback (silently drops writes), using the ~47-vs-~10 table-count signal from the issue.
• #2990 — MCP HTTP transport protocolVersion/tools-list/dual-stack-bind fixes were already on main; this release actually ships them (previous releases pinned an unpublished @claude-flow/mcp@3.0.0-alpha.10, now corrected to ^3.0.0-alpha.9).
• #3002 (ruvocal hidden-tab stream freeze) — confirmed already fixed on main, no change needed this release.

Postmortem: why 3.38.17 and 3.38.18 were broken

A subagent spawned mid-session to relay a status message went out of scope and independently ran its own fix/verify/publish cycle in parallel, racing the primary session's edits on the same checkout. Combined with stale-cached claude-flow daemon background processes self-healing package.json mid-write (tracked in #3005), @claude-flow/cli got published twice (3.38.17, 3.38.18) with a broken @claude-flow/mcp pin, and 3.38.18 additionally shipped with @claude-flow/memory missing from dependencies entirely. claude-flow and ruflo inherited the defect at 3.38.18. All three are now deprecated at those versions; 3.38.19 is the verified-correct cut.

---

⚠️ BROKEN — superseded by v3.38.19

This version (and 3.38.17) shipped with a corrupted dependency graph due to a publish race — see v3.38.19 for the postmortem. @claude-flow/cli, claude-flow, and ruflo are all deprecated on npm at this version. Install 3.38.19 or later instead.

Fixes

• #2992 — Windows CI (Build V3 job) was fully broken: windows-latest moved to VS2026, which node-gyp's VS detector can't identify, breaking native builds for hnswlib-node and better-sqlite3. Pinned the matrix to windows-2022.
• #2977 — @claude-flow/memory's controller registry attempted to import 8 agentdb exports that no installable agentdb range actually provides, silently degrading every fresh install. Removed the dead import attempts and promoted the existing, verified-working fallback implementations (tieredMemoryFallback, the consolidation stub) to first-class for hierarchicalMemory/memoryConsolidation; the 6 controllers with no fallback now return null directly. agentdb_consolidate's stub response now says explicitly that it's a no-op rather than reading as "nothing to consolidate."
• #2968 — Added a read-only doctor check (checkMemoryPersistenceDriver) that reports whether the active SQLite driver is native better-sqlite3 (durable, WAL-capable) or the silently-lossy sql.js fallback, using the table-count signal from the issue (~47 native vs ~10 fallback tables). Warns, never fails; does not change install behavior.
• #2990 — MCP HTTP transport spec violations (non-string protocolVersion, HTTP tools/list only exposing 4 system tools, IPv6-only bind) were already fixed in source but had never shipped in a release; this release ships them.
• Fixed a stale @claude-flow/mcp dependency pin (3.0.0-alpha.10, never published) that broke a plain npm install of the monorepo; repinned to the real published range.
• @claude-flow/memory bumped to 3.0.0-alpha.23 (carries the #2977 fix) and republished, since it's resolved via the npm registry rather than bundled with @claude-flow/cli.

Verified: @claude-flow/memory full test suite (459/459), @claude-flow/cli doctor/commands/mcp-tools suites (541/541), clean tsc --noEmit on both packages, clean production builds. #3002 (ruvocal hidden-tab stream freeze) was checked and found already fixed on main — no change needed.

Release train off three dream-cycle landings.

Dream Cycles

• #3062 → #3061 — dream(swarm): MessageBus retry-attempts silently reset to 0 on every re-queue, unbounded redelivery, `message.failed` unreachable. Bounded retry counter now persists across re-queues; `message.failed` fires at the cap. 220/220 tests. ACCEPT. Details in docs/dream-cycle/dream-gist-2026-08-19.md.
• #3057 → #3056 — dream(memory): `hybridSearch` controller was built but unreachable — explicit opt-in flag silently null-returned. Fixed via controller-registry wiring + graceful-retrieval test. Overall recall@10 +0.267 (category B pure-paraphrase regresses -0.133, disclosed). ACCEPT-scoped. Details in docs/dream-cycle/dream-gist-2026-08-18.md.
• #3049 → #3048 — dream(intelligence): discounted Thompson-sampling prior decay for the model-router bandit (opt-in). Recovers ~17.6% faster after workload shift in the low-cost bucket (t=7.00, held); med-bucket null (no generalization, disclosed). ACCEPT-scoped. Details in docs/dream-cycle/dream-gist-2026-08-17.md.

Install

• `npx ruflo@latest` (or `@alpha` / `@v3alpha` — all three tags aligned)

Merged PRs

• #3062, #3057, #3049, #3081 (release bump)

Closes #3061, #3056, #3048.

🤖 Generated with RuFlo

https://claude.ai/code/session_0118jMsYhwHD5dx2vStENsEB

Bug-fix + security-hardening train: four PRs merged from external contributors and one dream cycle.

Fixes

• #3060 → #3055 — `mcp tools` now honors `CLAUDE_FLOW_MCP_TOOLS` when listing (previously the env var was accepted but ignored on the list path). Thanks @dajiaohuang.
• #3076 → #3071 — Claude Code launches now resolve correctly on Windows npm installs. Replaces the brittle `which claude` execSync with a platform-aware `resolveClaudeLaunchCommand` that follows the npm shim to the native `claude.exe` (or falls back to `node <cli.js>` for older JS installs). Thanks @dajiaohuang.
• #3077 → #3063 — `hooks session-end` now persists the real session state (session id, duration, task/edit/command/error metrics from the actual run) instead of a hardcoded summary + fabricated session id. Thanks @dajiaohuang.

Security (Dream Cycle 2026-08-16)

• #3044 → #3043 — Advisory scanner for untrusted `.claude/settings.json` `hooks` and `permissions.allow` entries that `ruflo init` / `ruflo init --upgrade` previously carried forward unexamined. Same trust shape as CVE-2025-59536 (settings.json hook payload achieving command execution with no review step), reached via ruflo's own merge logic. Advisory-only — the merge/write behavior itself is unchanged, findings surface as CLI warnings. Hardened after an independent adversarial-critic pass found 6 concrete bypasses (intermediate-pipe-stage downloads, two-step download+exec, eval-wrapped base64, interpreter-mediated dangerous commands, absolute-path-prefixed commands, whitespace-evasive allow rules) — all fixed and pinned as a held-out regression set. Also self-identified an ANSI/control-character injection risk in the warning output and stripped it.

Install

• `npx ruflo@latest` (or `@alpha` / `@v3alpha` — all three tags aligned)

Merged PRs

• #3060, #3076, #3077, #3044, #3080 (release bump)

Closes #3055, #3063, #3071, #3043.

🤖 Generated with RuFlo

https://claude.ai/code/session_0118jMsYhwHD5dx2vStENsEB

Follow-up patch to v3.38.13 — fixes the last of the recently-reported issues.

Fix

#3051 — memory_store accepted a tags array and returned success: true, but the very next memory_retrieve (or memory_list) came back with tags: [].

Root cause was in bridgeStoreEntry: after the DB insert (which serialized tags correctly to the tags column), the write-through cache set stored only a partial entry — { id, key, namespace, content, embedding } — with no tags. The next bridgeGetEntry hit that cache and returned tags: cached.tags || [] = [].

Fix: replace the partial write-through with cache invalidation. Next read re-fetches the authoritative row (which correctly parses the tags JSON column) and repopulates the cache with the full shape. Side benefit: same defect had also caused access_count, createdAt, and updatedAt to be stale from the cache — invalidation fixes those too.

Proven regression test in __tests__/memory-store-tags-cache-3051.test.ts: pre-fix returns tags: [], post-fix returns the real tags.

Install

• npx ruflo@latest (or @alpha / @v3alpha — all three tags aligned)

Merged PR

Closes #3051 — #3079

🤖 Generated with RuFlo

https://claude.ai/code/session_0118jMsYhwHD5dx2vStENsEB

Bug-fix train + one new plugin. All three npm packages published as 3.38.13 (latest + alpha + v3alpha).

Bug fixes

• #3045 — .claude/helpers/statusline.cjs getGitInfo() ran the 5-command git chain uncached on every render, queuing subprocesses faster than they finished on large repos with concurrent Claude Code sessions. Now wrapped in a per-cwd tmp-file cache with 5s TTL — dirty status still feels live, pileup is bounded.
• #3064 — hooks post-task silently dropped every colon-namespaced plugin agent (ruflo-core:reviewer, feature-dev:code-explorer, …). Removed the narrow ad-hoc regex; the canonical validateIdentifier() upstream already allows : and .. Regression test locks in 4 shape variants and is proven to catch the bug (2/4 fail on revert; 4/4 with the fix).
• #3065 — plugins/ruflo-metaharness/skills/harness-gepa/SKILL.md had an unquoted colon in description that broke npx skills add. Quoted the field and rephrased the bare (default: to avoid the leading colon.

New plugin

• plugins/ruflo-deepseek-harness/ — sibling to ruflo-metaharness (ADR-150 shape). Two skills — deepseek-chat (non-reasoning) and deepseek-reason (surfaces reasoning_content separately from the final answer). Reads DEEPSEEK_API_KEY; degrades gracefully ({status: 'degraded', reason, hint} with exit 0) when the key is missing or the API is unreachable. --alert-on-error opts into hard exit 1 for CI gates.

Not fixed

• #3051 (memory_store tags dropped) — current source's handler passes tags straight through to storeEntry; a maintainer already verified round-trip works on fa13ee4ad. Waiting on the reporter's ruflo/@claude-flow/cli version to identify the affected release path before patching.

Install

• npx ruflo@latest (or @alpha / @v3alpha for the legacy tags, all aligned)
• npx @claude-flow/cli@latest / npx claude-flow@latest

Merged PR

Closes #3045, #3064, #3065 — #3078

🤖 Generated with RuFlo

https://claude.ai/code/session_0118jMsYhwHD5dx2vStENsEB

Fixes

#3010 — PathValidator rejected everything under a symlinked prefix, breaking ruflo proxy install on macOS. validate() canonicalized the candidate path through fs.realpath but the constructor only ever path.resolve()d the allowed prefixes — so on macOS, where os.tmpdir() is reached through a symlink (/var → /private/var), the realpath'd candidate could never match the non-realpath'd prefix, and every path under it — including the prefix's own contents — was rejected as "outside allowed directories." Download and Ed25519 signature verification both succeeded during proxy install; it then failed on this defense-in-depth path check. Fixed by realpath-ing prefixes at construction time too, with the same ENOENT-tolerant fallback validate() already uses for candidates.

Links

• PR: #3013 (#3010)
• Previous release: v3.38.8 (#2962 — provider/model config propagation)

Highlights

• fix(agent): explicit provider/model config now propagates into agent execution (#2962, PR #3007)

providers configure and agent spawn --provider/--model previously persisted user intent but the execution path (callAnthropicMessages, executeAgentTask, determineAgentModel) only ever consulted env vars and a fixed 5-alias model list — silently discarding both. A user who configured local Ollama or OpenRouter would see two successful CLI commands, then execution would either fail closed or silently use a different provider/model than requested.

• determineAgentModel() now treats any non-alias config.model string (e.g. an Ollama tag) as an explicit selection via the existing modelId fast-path, instead of falling through to task-based routing / agent-type defaults.
• agent_spawn forwards config.provider into the stored (and returned) agent record when it's an unambiguous explicit choice (ollama/openrouter; anthropic is excluded since the CLI silently defaults to it when --provider isn't passed).
• callAnthropicMessages() now consults the persisted agents.providers config for baseUrl/apiKey/model when env vars are absent. A self-hosted, unauthenticated Ollama endpoint no longer requires the undocumented OLLAMA_API_KEY=local sentinel.
• executeAgentTask() forwards the agent's explicit provider into the first dispatch call.

Precedence (resolving the open design question from the issue thread, credit @pacphi): explicit per-agent flag → env vars → persisted agents.providers config → key-presence inference (unchanged, last resort).

Regression coverage: v3/@claude-flow/cli/__tests__/agent-provider-model-propagation.test.ts (3 tests, each verified to fail against the pre-fix code and pass against the fix).

Verification

• TypeScript clean (tsc --noEmit)
• 202/209 existing tests green for touched files (7 pre-existing unrelated failures confirmed present on unpatched main too — stale fs mock in mcp-tools-deep.test.ts)
• CI: 107 checks passed, 3 skipped (conditional), 0 failed
• Tarball-verified: fix present in the published @claude-flow/cli@3.38.8 package

Fixes

#2920 (follow-up) — consolidate()'s graph write was missing the contentFingerprint stamp that init()'s cache-hit gate checks. The v3.38.6 fix made consolidate() (the session-end path) rebuild graph-state.json unconditionally, but that write never included contentFingerprint — only init()'s own write did. So every init() immediately following a consolidate() saw nodeCount match but contentFingerprint undefined !== <real hash>, missed the cache, and did a full rebuild even with zero content changes. Fail direction was safe (extra rebuilds, never stale data), so it didn't block v3.38.6 — but it meant the 60s graph cache never actually fired across a consolidate/restart boundary.

#2922 — the memory bridge's brute-force cosine search was misreported as HNSW-accelerated. getHNSWStatus() returned available: true whenever the AgentDB v3 bridge was loaded, regardless of whether an HNSW index was actually in the request path — the bridge's default search is a full-table SELECT + brute-force cosine similarity loop that never touches @ruvector/core. Same issue in bridgeGetHNSWStatus (unconditional available: true) and in three misleadingly-named functions that do no HNSW work: bridgeSearchHNSW, bridgeAddToHNSW, bridgeGetHNSWStatus — renamed to bridgeSearchBruteForceCosine, bridgeAddEmbedding, bridgeGetVectorSearchStatus. Both status functions now expose an algorithm: 'hnsw' | 'brute-force-cosine' field. The memory_stats MCP tool response (and 6 others) previously hardcoded backend: 'sql.js + HNSW' regardless of which path ran — now reports the real algorithm.

Note: this changes the values returned in the backend field of 7 MCP memory tool responses (memory_store, memory_retrieve, memory_search, etc.) from the previous hardcoded 'sql.js + HNSW' to an accurate value — an observable but non-breaking change (the field's type and presence are unchanged).

Actually wiring AgentDBBackend's real HNSW implementation into the bridge's default search path is a larger architectural question, tracked as the remaining open scope on #2922.

Links

• PR: #3003 (#2920 follow-up)
• PR: #3006 (#2922, re-opened after #3004 was auto-closed by a base-branch deletion)
• Filed: #3005 — a suspected root-cause bug in helper-refresh.ts's self-heal path, discovered while working this release
• Previous release: v3.38.6

Fixes

#2947 — DualModeOrchestrator left every Codex worker's stdin open, causing codex exec to hang waiting for EOF. Both Claude and Codex workers receive their prompt positionally/via a flag — never over stdin — but the pipe was never written to or closed. claude -p ignores the unused pipe, but codex exec blocks in resolve_root_prompt waiting for stdin EOF that never arrives, hanging every real Codex worker until the orchestrator's own multi-minute timeout kills it. Now closes stdin immediately after spawn for both platforms.

#2920 — Editing a MEMORY.md section's body (same ID, same entry count) served stale cached content instead of refreshing it. Two related bugs in the intelligence helper's graph/store caching, both keyed on entry count instead of content: init()'s graph-cache-hit gate compared only node count, so a same-ID content edit was invisible to it and ranked-context.json never refreshed; consolidate()'s persist gate only fired on insight creation or a dedup-driven shrink, so an in-memory content change (e.g. assigning an id to a previously id-less entry) was silently never written back to disk. Added a storeFingerprint() helper folding every entry's content into one aggregate value, used to gate the cache hit and to make consolidate() always persist.

#2935 — .claude-flow/config.json resourceThresholds overrides were silently lost to a stale daemon-state.json. The daemon's stale-state restoration guard only checked the constructor arg (originalConfig), not a value set via config.json — so an explicit override (e.g. minFreeMemoryPercent: 0, a workaround for Darwin's os.freemem() undercounting reclaimable memory) kept losing to whatever a daemon-state.json from before the override existed had persisted, on every restart. Same bug class as #2661 (aiWorkersEnabled), fixed the same way, per-field. Also fixed a secondary diagnostic bug: readDaemonConfigFromFile() logged "Daemon config loaded from ..." from inside the constructor before this.config existed, so the log call threw inside its own try/catch and never reached daemon.log — made "is the config file even being read?" impossible to answer from the log. Does not address this issue's primary Darwin os.freemem() memory-gate report — that needs vm_stat/memory_pressure-based measurement, left for a follow-up.

CI infrastructure

Fixed a recurring sharp/libvips "socket hang up" / 503 flake in npm ci across CI workflows (confirmed on 8+ unrelated PRs this session) by adding a retry-with-backoff composite action and wiring it into every npm ci call site, including the two OS-conditional fallback blocks initially missed.

Links

• PR: #2997 (#2947)
• PR: #2998 (CI retry infra)
• PR: #2999 (#2920)
• PR: #3000 (#2935)
• PR: #3001 (CI retry follow-up)
• Previous release: v3.38.5

Fixes

#2911 — ruflo-adr's ADR importer indexed thousands of foreign ADRs from ruvnet-brain's cloned repos, burying the project's own. SKIP_DIRS omitted .brain, which holds shallow clones of ~50 external repos, many with their own docs/adr/. Since .brain sorts before docs, the project's own ADRs landed dead last in the walk order — an interrupted run could index hundreds of foreign ADRs and zero of the project's own. Added .brain to SKIP_DIRS. Also fixed the plugin's own smoke test, which hard-coded its regression-test-file count and broke on the new test file this fix added.

#2963 — github_issue_track's create/update/close/list actions validated the caller-supplied owner/repo but never passed them to gh. gh silently resolved the target repository from the current working directory's git remote instead — a caller supplying owner/repo expecting an operation to land in that specific repository had no guarantee it did. Now passes --repo <owner>/<repo> to gh whenever both are supplied.

#2931 — security scan's hardcoded-secret detection missed common real-world Stripe/OpenAI key shapes. The regex required 20+ characters after the sk-/sk_live_/sk_test_ prefix (missing shorter-but-real keys) and a quote literally adjacent to the prefix (missing the very common Authorization: "Bearer sk_live_..." shape, where the quote sits next to "Bearer", not the key). Replaced with lookaround word-boundaries and a lower length floor.

Links

• PR: #2994
• PR: #2995
• PR: #2996
• Previous release: v3.38.4

Fixes

#2952 — ruflo init --all-agents, --skip-claude, --only-claude, and --cloud-mcp were silent no-ops. Every long-flag write path in the parser normalizes kebab-case to camelCase before storing (--all-agents → flags.allAgents), but initClaudeAction read the literal kebab-case keys — which the parser never produces — so all four reads were always undefined. Same bug class already fixed for --no-global five lines above in the same function, never applied to these siblings. Fixed by reading the real normalized keys. Regression test verifies --all-agents now installs the full 89-agent catalog instead of the curated 17-agent default.

#2961 — ruflo hooks post-task (CLI) reliably dropped the ADR-130 "reinforced-by" graph edge that the identical hooks_post-task MCP tool writes. The edge write was a fire-and-forget async IIFE the handler never awaited — invisible from the long-running MCP server, but the CLI form is a one-shot process that calls process.exit(0) immediately after the command resolves, killing the still-pending write before its first tick, every time. Fixed by awaiting it.

Links

• PR: #2989
• PR: #2991
• Previous release: v3.38.3

Fixes

#2940 — ruflo hooks intelligence --train exited 0 and printed a full success dashboard without ever training anything. The --train flag was declared on the hooks_intelligence MCP tool's input schema but never read — the handler always returned the same read-only status snapshot, and the CLI's --train branch was a cosmetic 500ms sleep followed by an unconditional "Training cycle completed". lastAdaptation (what --status reports as "Last Training") never moved, so it could only ever age no matter how many times --train ran — a naive --status diff looked like progress in exactly the wrong direction.

Now hooks_intelligence calls the existing distillLearning() when --train is passed and reports what actually happened: patterns distilled (with the count), ran but found nothing new to distill (the common case — SONA already adapts incrementally per-trajectory, so a manual pass legitimately finding nothing new isn't an error), or the intelligence system being unavailable. --status immediately reflects a real training pass (0s ago) instead of showing a stale, aged value.

Also investigated this cycle

• #2908 (hooks post-task --store-results writes an entry memory search never finds) — root-caused precisely: memory-bridge.ts's getRegistry() is a process-wide singleton that locks onto whichever DB path its first caller in a process supplies, and hooks post-task makes several bridge calls before the write in question — so a dbPath fix scoped to just that call site is silently discarded. Same class of issue as #2259, just resurfaced under different filenames on the current codebase. Did not ship a narrow fix since it doesn't actually work end-to-end (verified by trying). Full mechanism: #2908 comment.
• #2905 (npx @claude-flow/cli@alpha --version "hangs" on a cold cache) — reframed: it's not an infinite hang, a truly cold install completes in ~3 minutes (verified), just slow enough to look like one under a 60–90s timeout. Root-caused one concrete, narrow contributor: @agntcy/slim-bindings's nine platform sub-packages are all missing os/cpu fields, so npm installs all nine on every platform instead of the one that matches. Filed upstream: agntcy/slim#1981.

Links

• PR: #2988
• Previous release: v3.38.2

Fixes

#2985 — ruflo migrate status's ADR-128 removed-agent remediation printed a command that couldn't succeed. ruflo plugins install <plugin> required -n/--name (not a positional) and targeted the npm-package plugin system entirely, while the gap detector's own registry check (installed_plugins.json) is for the Claude Code marketplace system. Fixed to print /plugin install <plugin>@ruflo, and — going further than a pointer fix — adds a real ruflo migrate fix --agents command that restores the missing agent files from their canonical plugin content (marketplace clone → repo checkout → GitHub tag → main fallback), rewriting the marketplace-only mcp__plugin_ruflo-core_ruflo__* tool namespace to the canonical claude-flow server key for npm-track users. Never overwrites an existing file. Contributed by @pacphi via #2986.

#2984 — ruflo mcp start -t http printed a full "Status: Running" success table, then exited within seconds without ever binding the port. Root cause: bin/cli.js's dispatcher unconditionally exits the process once a command's action resolves (an assumption that only holds for genuinely one-shot commands) — mcp start's HTTP/WebSocket path returned immediately after printing its success table, tearing down the freshly-bound http.Server before any client could connect. Fixed by blocking in the foreground with SIGINT/SIGTERM-driven graceful shutdown, matching daemon start --foreground's established pattern.

Also corrected doc drift found while investigating #2985: README.md/docs/USERGUIDE.md's claude mcp add examples now use the canonical claude-flow server key (per #2206); README's claim that the Claude Code plugin path never registers an MCP server corrected (ruflo-core ships its own).

Also investigated this cycle, not reproduced

#2969 (--version hang), #2970 (witness verify soft-pass), #2967 bug 1 (uptime unit mismatch) — checked via direct repro against main, none reproduced. See the linked issues for the evidence.

Links

• PR: #2986 (external contribution, reviewed and merged)
• PR: #2987
• Previous release: v3.38.1

Fixes

#2982 / #2976 — memory search silently dropped entries on large corpora. bridgeSearchEntries() and bridgeSearchHNSW() pre-ranked the memory corpus with an unordered LIMIT 1000 / LIMIT 10000 before BM25/embedding scoring ever ran. Without an ORDER BY, SQLite returns rows in arbitrary storage order (insertion order on a fresh table) — so on any corpus over the limit, the newest entries never reached scoring at all, regardless of how well they matched the query. Both paths now order by updated_at DESC before truncating, matching the pattern bridgeListEntries() already used.

Verified with a stash-based A/B on a 1005-row fixture: the exact same search returns zero results without the fix, recalls correctly with it.

#2968 — memory store claimed success even when the write might not persist. On the sql.js fallback driver (engaged when better-sqlite3's native binding never got built — e.g. a skipped optionalDependency postinstall), the post-write wal_checkpoint(PASSIVE) checkpoint throws Invalid PRAGMA command every time and was silently swallowed as "non-fatal." bridgeStoreEntry() now distinguishes that specific failure signature from an ordinary busy/non-WAL pragma failure and surfaces it as persistWarning, which memory store prints instead of an unconditional green "Data stored successfully."

Both fixes are scoped to ruflo's own CLI bridge layer — no changes to the external agentdb/better-sqlite3 packages.

Also investigated, not changed

From the same triage pass: #2969 (--version hang), #2970 (witness verify soft-pass), and #2967 bug 1 (uptime unit mismatch) were all checked with a direct repro against current main and none reproduced — --version exits cleanly and fast, verify.mjs already exits 2 on a forced source-only checkout, and the uptime math is already correct post-#2235(B). No speculative fixes shipped for those.

Links

• PR: #2983
• Issues closed: #2982, #2976; part of #2968

An investigation into ruflo's two install tracks (npm install vs. the Claude Code marketplace plugin) surfaced four independently-verified defects in the init scaffold and its own remediation tooling, documented in ADR-382 and tracked in #2971. All four are fixed in this release.

Fixed

• Unfulfilled ADR-128 migrate mitigation (#2973): ADR-128 Phase 2 removed 9 forked agent files (coder.md, researcher.md, reviewer.md, tester.md, memory-specialist.md, security-auditor.md, sparc-orchestrator.md, goal-planner.md, adr-architect.md) from the init template, making each plugin canonical — but the promised ruflo migrate detection for that removal was never implemented. ruflo migrate status now detects the gap and prints the exact ruflo plugins install <plugin> command to restore each missing agent.
• Unpinned marketplace-plugin MCP launch (#2975): plugins/ruflo-core/.mcp.json always launched npx -y @claude-flow/cli@latest, silently overriding any local npm install a user had, causing version divergence between the two install tracks. It now resolves a local install first (mirroring hook-handler.cjs's existing resolveCliBinForHook() pattern), falling back to npx @latest only when nothing local resolves.
• 3 plugins missing from the marketplace registry (#2975): ruflo-agntcy, ruflo-bbs-federation, and ruflo-business-pods existed in plugins/ but were absent from .claude-plugin/marketplace.json, making them uninstallable via the marketplace despite being fully built. Registered.
• Dead CLI/tool references in bundled scaffold content (#2974): 701 occurrences of the stale npx claude-flow invocation form were remapped to npx @claude-flow/cli@latest across 142 files. A new CI guard (scripts/smoke-init-scaffold-references.mjs, warn-only) now derives live MCP-tool and CLI-subcommand sets and flags any future drift; 410 dead MCP-tool-name references (e.g. sparc_mode, task_orchestrate, memory_usage) were deliberately left FLAGged rather than guessed at, and are tracked as follow-up work rather than silently dropped.

Notes

• No breaking changes; this is a backward-compatible bug-fix and tooling release.
• The plugins/ruflo-core MCP-launch fix applies to the git-based marketplace-plugin install track directly (already effective on main); the migrate.ts detection and scaffold-content remap ship in this npm release.

What's in this release

Four independently-reviewed fixes to the Meta LLM Proxy control surface (ruflo proxy ...):

• #2925 — bumps the pinned meta-proxy release from 0.4.0 to 0.7.3. The old pin predates the commit that separated authentication from cloud-routing consent (meta-proxy #60, first in v0.7.0) — on 0.4.0, even a --version probe starts the daemon and binds a port. proxy status/console guidance now also surfaces when an already-installed binary has drifted behind the current pin, with a one-line proxy update prompt.
• #2926 — proxy install on Windows no longer discards a fully signature-verified archive when PowerShell's Expand-Archive fails to autoload its module (intermittent, unrelated to the archive itself). It now falls back to tar -xf (bsdtar, ships on Windows 10+), with independent SafeExecutor allowlists per extractor and a combined error message if both fail.
• #2927 — ruflo proxy config --cloud now discloses all three things enabling cloud routing actually decides: who processes the prompt, who pays, and — previously undisclosed entirely — that the cloud plane picks a tier per prompt instead of honoring the client's requested model. New flag: ruflo proxy config --routing-mode <auto|low|mid|high> to pin a tier, matching meta-proxy's RoutingMode enum (ADR-321 rev-2/rev-3).
• #2928 — --local-only was the only documented way to leave the cloud plane, but it points at your own local backend — not passthrough (meta-proxy's own default, which uses your Claude subscription and is the only plane eligible for ADR-321's automatic quota failover). New flag: ruflo proxy config --passthrough restores the subscription plane; --cloud now remembers and reports the plane you're leaving so there's always a real "undo" command.

Versioning note

Minor bump (not patch) — #2927 and #2928 add backward-compatible CLI flags (--routing-mode, --passthrough), not just bug fixes. No breaking changes; a user who never touches proxy config sees no behavior change.

Verification

• All three packages (@claude-flow/cli, claude-flow, ruflo) published at 3.37.0 with latest/alpha/v3alpha dist-tags aligned — verified via npm view <pkg> dist-tags --json.
• 64/64 proxy-suite tests passing, tsc --noEmit clean, pnpm install --frozen-lockfile verified in the v3/ workspace.
• Each PR independently reviewed against its own claims (not just its description) before merge; one factual inaccuracy caught and fixed in #2927's disclosure text pre-merge (a "which plane you're currently on" claim that didn't hold for --local-only users).

🤖 Generated with RuFlo

What's in this release

• metaharness#176 (upstream) shipped @metaharness/turn-credit (ADR-248 — recursive turn-level credit assignment for agent trajectories, based on AgentOPSD/arXiv:2608.05987), plus a bump to @metaharness/darwin 0.9.0 (ADR-249 additive scorer signal seams) and @metaharness/router 0.4.0 (new calibration-audit module).
• This release brings ruflo's dependency contract in sync with that upstream work:
  • Adds @metaharness/turn-credit@~0.1.0 as a new installable optionalDependency, following the same pattern as darwin/flywheel/radio (ADR-150) — dependency-free, ~65KB unpacked, no lifecycle scripts.
  • Fixes two stale pins the review turned up: @metaharness/darwin (~0.8.3 → ~0.9.0) and @metaharness/router's peer range (^0.3.2 → ^0.4.0) — both had drifted out of range of what's actually published.
  • Bumps the no-cli-optdep-bloat-2561 CI guard's budget from 10 → 13, fixing a "zero slack" trap left by the previous release (v3.35.0) that would have broken on the very next unrelated optional dependency.
  • Fixes a live ReferenceError in a test file (MH_DARWIN_PIN referenced but never imported) that had somehow slipped through v3.35.0's CI.

👉 Full plain-language write-up (what turn-credit does, why the pin bugs mattered, and a lesson learned about pnpm lockfile drift): https://gist.github.com/ruvnet/0202e6a060b04b3a4f5d9bd18345169d

Upgrade

npx ruflo@latest --version   # 3.36.0
npm install @metaharness/turn-credit   # optional — new capability, not auto-installed by ruflo's own peer/opt-in design

No breaking changes — backward-compatible minor release.

Verification

All three packages (@claude-flow/cli, claude-flow, ruflo) published at 3.36.0 with latest/alpha/v3alpha dist-tags aligned, verified via npm view <pkg> dist-tags --json and a live npx ruflo@latest --version smoke test.

🤖 Generated with RuFlo

Addendum (2026-08-11)

This release's published npm artifact also included three data-integrity/correctness fixes whose commit landed in git after this tag was originally cut, because the build that was published included that work before it was committed. The v3.36.0 git tag has been moved to point at the commit that actually matches what's published (efd0406e7); the original tag target (f35c545fb) only had the turn-credit/pin-fix work above.

Fixed in this release (see #2966):

• #2887 — agentdb_hierarchical-store reported success:true for writes that were never persisted (agentdb dropped its HierarchicalMemory export at 3.0.0-alpha.17; the fallback store is now durable and refuses to claim success for a lost write). Also required publishing @claude-flow/memory@3.0.0-alpha.22 — that package carries the fix and is an independent optional dependency, not bundled into this tarball.
• #2878 — concurrent memory.db writers silently lost updates while reporting success (10/12 lost in a 12-way repro). All mutating paths now serialize under withMemoryDbLock.
• #2877 — daemon lock/PID keyed to raw cwd, letting a subdirectory invocation spawn a duplicate daemon for the same project.

Action needed for the #2887 fix to take effect: run npm install @claude-flow/memory@latest (or reinstall @claude-flow/cli) to pick up 3.0.0-alpha.22.

What's in this release

• #2956 — Fixes a dependency-contract bug where a clean ruflo install shipped with zero MetaHarness packages on disk (they were declared as optional peer dependencies, which npm never auto-installs). MetaHarness packages are now explicit optionalDependencies, tilde-pinned, with a mandatory clean-install CI gate.
• #2956 — Adds strict, statistically-governed evidence requirements (ADR-381) to the self-optimizing flywheel's promotion gate, bounding the family-wise false-promotion probability at ≤5% across an adaptively-chosen candidate stream.
• Follow-up fix on #2956 — Code review of the PR before merge found and fixed 3 confirmed concurrency/epoch-boundary bugs in the new sequential-evidence machinery that could silently violate that ≤5% guarantee under concurrent or decoupled evaluation/registration timing. See the companion write-up for the full story in plain language: 👉 https://gist.github.com/ruvnet/0202e6a060b04b3a4f5d9bd18345169d
• #2957 — Version bump housekeeping + a stale test assertion fix (distill-oracle.test.ts — a version-pinned command no longer matched the test's un-pinned substring check).

Upgrade

npx ruflo@latest --version   # 3.35.0
npx @claude-flow/cli@latest doctor --component metaharness

No breaking changes — this is a backward-compatible minor release (new optional dependencies, new doctor checks, new CLI/MCP surface for flywheel evidence-reset).

Verification

All three packages (@claude-flow/cli, claude-flow, ruflo) published at 3.35.0 with latest/alpha/v3alpha dist-tags aligned, verified via npm view <pkg> dist-tags --json and a live npx ruflo@latest --version smoke test.

🤖 Generated with RuFlo

AGNTCY/Outshift runtime integration (ADR-378/379/380)

Optional, removable augmentation per ADR-150's pattern — the kernel stays fully operational with these packages absent.

• New CLI verbs: ruflo transport use slim, ruflo agent publish, ruflo swarm join <namespace>. All exit 0 with a clear message when RUFLO_AGNTCY_SLIM_ENDPOINT is unset — no fake success paths.
• CASA (Continuous Agentic Semantic Authorization) — deterministic free-text-objective → bounded allow/deny/budget/expiry envelope compiler, deny-by-default enforcement gate, Ed25519-signed decision receipts (.swarm/casa-receipts.jsonl).
• AGNTCY OTel span attributes — coordination.episode, authorization.decision.
• Companion Rust crate v3/crates/ruflo-agntcy mirrors the TS enforcement logic (real in-process LocalTransport, SlimTransport stub behind a non-default slim Cargo feature).
• Companion package @metaharness/agntcy (build-time half — identity, OASF export, Directory publish, semantic observability) published for the first time from the sibling metaharness repo.
• See it in action: AGNTCY showcase — a real trace and the presentation deck.

npm Trusted Publishing release workflow (ADR-378)

.github/workflows/stable-npm-release.yml publishes the three-package stable train (@claude-flow/cli, claude-flow, ruflo) from an immutable, tag-pinned checkout with a full test/build/pack/install smoke-test gate before any registry write, verifies published-package integrity against the locally-built archive, and rolls out latest/alpha/v3alpha dist-tags together. This release is the first real run of that workflow.

Fixed

• @agntcy/slim-bindings pinned to the confirmed-working alpha (2.0.0-alpha.5) — the SLIM maintainers moved off uniffi-bindgen-react-native (incompatible with plain Node) onto @ubjs/core/@ubjs/node; verified live end-to-end.
• security scan failed open on unvalidated --depth/--type/--target — all three now fail closed before anything is scanned or written.

Changed / Removed

• security scan --depth full deprecated (normalises to deep with a warning).
• security scan --type container now rejected instead of silently reporting clean (breaking for pipelines passing --type container).

Full changelog: CHANGELOG.md

---

Install: npx ruflo@latest doctor · npx ruflo@latest agent publish --help

Merge marker for PR #2879 — not an npm version release (@claude-flow/cli/claude-flow/ruflo remain at 3.33.0 on npm).

Full consolidated release notes: https://gist.github.com/ruvnet/d6fc9bea2758049fd87424a2718dec1e

See it illustrated: ruflo × AGNTCY — an animated walkthrough

Three ADRs merged: npm Trusted Publishing proposal (ADR-378), optional statusline usage segments (ADR-379), and AGNTCY/Outshift runtime integration with real, tested CASA envelope enforcement + CLI scaffolding (ADR-380). Companion: ruvnet/metaharness PR #155 (ADR-240).

An adversarial security review found and PR #2879 fixed two real bugs in the CASA enforcement gate before merge — see the gist for details.

Update: PR #2888 pins @agntcy/slim-bindings to the confirmed-working pre-release build (2.0.0-alpha.5) — verified live, a real SLIM server/client bring-up now succeeds under plain Node with zero errors. Not yet in an npx ruflo@latest release; build from main to try it today.

AgentDB Retrieval Security Layer (ADR-377)

Closes #2516 / tracked in #2873: AgentDB's retrieval and write paths had zero certified defenses against memory poisoning (undefended attack success 93–100% per SMSR, arXiv:2606.12703). Full 3-phase implementation shipped in #2874, all off by default until independently benchmarked.

• AgentDbRetrievalGuard (@claude-flow/memory) — filters HNSW retrieval results through ToolOutputGuardrail's OWASP LLM01/LLM08 pattern scan before context assembly. CLAUDE_FLOW_RETRIEVAL_GUARD / _STRICT.
• MemoryPoisonForensics (@claude-flow/hooks) — rolling-window z-score anomaly detection on AgentDB write sequences (write-interval, content-length). CLAUDE_FLOW_POISON_FORENSICS=0 to disable.
• McpCallerIdentity (@claude-flow/security) — Ed25519 per-invocation capability tokens. CLAUDE_FLOW_MCP_CALLER_AUTH, off by default pending a follow-on key-distribution ADR.

Also in this release:

• #2871 — consolidated 49 stale dream-cycle research proposals (open since 2026-05-29, never merged) into ADR-334 through ADR-376, resolving the ADR-147/ADR-179/ADR-320 numbering collisions along the way.
• #2872 — recovered ADR-377 itself from an abandoned dream-cycle branch that never got a PR opened for it.

31 new tests across the three touched packages, zero regressions (memory 451, hooks 145, security 570 full suites re-run clean).

Packages

• @claude-flow/cli@3.33.0
• claude-flow@3.33.0
• ruflo@3.33.0

🤖 Generated with Claude Code

Fixed

#2864 — hooks route gated learned routing patterns at score ≥0.65 vs static patterns at >0.4, so a top-scoring learned pattern could lose to a lower-scoring static one that simply cleared the easier bar. Measured 49% agreement with the router's own recorded training labels on a real store (only 1/61 replayed routes decided by a learned pattern). Both sources now share the same score gate; support/reliability remain the learned-specific quality guard.

#2865 — the hooks intelligence MoE panel showed a hardcoded Routing Accuracy: 82.0% (plus Active Experts/Load Balance constants) whenever any local neural data existed, regardless of actual routing quality — the same "self-confidence presented as accuracy" problem already fixed on the hooks metrics path in an earlier release. These fields are now omitted rather than fabricated when no real value is reported.

#2859 — hooks transfer from-project reported success and quality stats (avgConfidence, avgAge) without ever reading or writing the destination project's memory store — every number was invented from fixed percentages of the source pattern count. Now performs a real merge: reads the destination, skips low-confidence/duplicate/conflicting entries, and actually persists whatever remains. Reported counts and stats are computed from what was actually processed.

All three verified against the exact reproductions in their issues using the real built CLI (not unit mocks).

PR: https://github.com/ruvnet/ruflo/pull/2869

Packages

`@claude-flow/cli`, `claude-flow`, and `ruflo` are all at 3.32.41; `latest`, `alpha`, and `v3alpha` dist-tags all point to it.

Fixed

Security (reported privately via SECURITY.md, external reproduction + patch): ruflo security scan validated none of its --depth, --type, or --target flags. An unrecognised value did not error — it silently reduced or eliminated the scan while still printing "No security issues found!" and exiting 0. On a fixture whose only HIGH finding sat below the shallow-traversal budget, --depth full → --depth full (the CLI's own emitted value) silently flipped the critical/high exit-code gate from 1 to 0, and a typo'd --target produced a persisted CLEAN report that downstream status checks trusted as genuine.

All three flags now fail closed before anything is scanned or written:

• --depth/--type validated against exhaustive Record<ScanDepth, number> maps with real type predicates (no unsafe casts that could silently re-disable the recursion limiter)
• --depth full (never a real value, but emitted by the CLI's own statusline/announcements/generated CLAUDE.md/shipped agents) is deprecated-but-accepted → deep, with a warning, rather than breaking every caller told to use it
• --type container (advertised but never implemented) now hard-rejects instead of silently reporting clean — breaking for any pipeline passing it, previously exited 0
• --target validated for existence and directory-ness

246 lines of new tests cover depth-budget boundaries by nesting level, case sensitivity, a path-traversal-via---type attempt, stdout/stderr separation, and no-persisted-report-on-rejection.

PR: https://github.com/ruvnet/ruflo/pull/2866

Packages

`@claude-flow/cli`, `claude-flow`, and `ruflo` are all at 3.32.40; `latest`, `alpha`, and `v3alpha` dist-tags all point to it.

Fixes

#2855 — Codex's plugin hook-manifest loader accepts only description and hooks at the top level. plugins/ruflo-core/hooks/hooks.json and plugins/ruflo-cost-tracker/hooks/hooks.json carried _note/_platform_note documentation fields, so a fresh Codex install of ruflo-core@ruflo failed to load the plugin at all with unknown field \_note`, expected `description` or `hooks`. Fixed by folding the doc content into description. Added a permanent CI guard (scripts/audit-plugin-hooks-cross-platform.mjs`) so this can't regress silently again.

#2856 — Once the manifest could load, modify-bash/modify-file PreToolUse hooks always echoed Cursor's {"permission":"allow"} verdict, which Codex's own stricter output schema rejects outright (hook returned invalid pre-tool-use JSON output) — verified directly against the real parser (codex-rs/hooks/src/engine/output_parser.rs). Hardened Codex-host detection with a turn_id-based fallback alongside the existing PLUGIN_ROOT/PLUGIN_DATA env-var check.

ruflo-core bumped 0.2.5 → 0.2.6 and ruflo-cost-tracker 0.26.2 → 0.26.3 so Codex's per-version plugin cache invalidates and picks up the fix rather than serving a stale cached copy indefinitely.

PR: https://github.com/ruvnet/ruflo/pull/2857

Packages

`@claude-flow/cli`, `claude-flow`, and `ruflo` are all at 3.32.39; `latest`, `alpha`, and `v3alpha` dist-tags all point to it.

Ruflo v3.32.38: Daemons Start Only for Ruflo Projects

Ruflo v3.32.38 fixes a background-process leak discovered during the post-release audit: a read-only command in a directory containing only a Claude Code .claude/ folder could start a detached Ruflo daemon.

The trigger was subtle. Signed-champion startup migration created a .claude-flow/ state directory, and daemon auto-start then mistook that startup-created directory for prior user initialization. Repeated commands in unrelated Claude projects could therefore accumulate one daemon per directory.

Install or upgrade

npm install --global ruflo@3.32.38
ruflo --version

What changed

Daemon auto-start now requires a durable Ruflo project marker:

• a Ruflo runtime config under .claude-flow/;
• a legacy claude-flow.config.json;
• an initialized .swarm/memory.db;
• a Ruflo-specific Claude settings section; or
• a Ruflo/Claude Flow MCP server entry.

A generic .claude/ directory, an empty .claude-flow/ directory, or policy state created during the current startup no longer authorizes a detached process. Explicit ruflo daemon start remains available everywhere, and initialized Ruflo projects retain automatic background workers.

Validation

• The exact issue reproduction was run against 3.32.37 and produced a daemon.
• The same reproduction against the patched build produced no process and no daemon PID file, even though signed-champion and policy state were applied.
• Daemon auto-start regression suite: 13/13.
• CLI TypeScript build passes.
• The stable release pipeline builds immutable archives, smoke-installs all three public packages, publishes those same bytes, and verifies a fresh registry installation.

This release resolves #2852.

Ruflo v3.32.37: Complete Reports, Consistent Initialization

Ruflo v3.32.37 closes the follow-up defects found while verifying v3.32.36 against older open bug reports. MetaHarness readiness verdicts remain machine-readable even when a repository is blocked, memory initialization uses the same configured database path as every later operation, and dual Claude Code/Codex initialization now installs both native surfaces.

The release also removes unbacked Codex skill placeholders, makes ADR indexing idempotent, repairs legacy live-memory row visibility, and bounds the quadratic work in session-end intelligence consolidation.

Install or upgrade

npm install --global ruflo@3.32.37
ruflo doctor

Existing projects remain compatible. The stable train still contains exactly the three supported packages: @claude-flow/cli, claude-flow, and ruflo.

MetaHarness readiness is data

ruflo metaharness genome --path . --format json

Upstream MetaHarness intentionally uses exit 1 for needs-work and exit 2 for blocked. Ruflo now preserves those valid reports instead of replacing them with a generic subprocess error:

{
  "risk_score": 0.72,
  "verdict": "blocked",
  "verdictExitCode": 2
}

The Ruflo wrapper exits successfully for a valid report so CLI and MCP callers can consume it. --alert-on-risk-above still exits 1 when its policy threshold is crossed, and malformed or missing reports still fail with exit 2.

Initialization and portability

• memory init honors CLAUDE_FLOW_DB_PATH, completing the shared-path contract used by dual-mode bootstrap and background workers.
• init --dual runs both native initializers, preserving the full Claude Code scaffold while adding Codex assets.
• Root .gitignore protection covers .env secrets in initialized projects.
• Codex full init installs canonical skill implementations only; it no longer generates more than one hundred placeholder skills that appear usable but have no implementation.
• Every tracked shell and Windows hook shim now resolves the same stable Ruflo dist-tag.

ADR and memory correctness

• ADR metadata parsing accepts the bullet-prefixed Date, Tags, and relationship format emitted by adr-create.
• ADR records use explicit upsert semantics and stable keys.
• ADR relationships use deterministic semantic keys and are deduplicated within an import, while verification remains compatible with legacy keys.
• ADR creation guidance uses the real AgentDB key/value contract.
• Native memory CRUD treats legacy NULL status rows consistently as live.
• Intelligence consolidation deduplicates by content before graph creation and caps similarity comparisons while preserving temporal edges.

Validation

• Blocked-genome CLI and MCP fixtures preserve the complete verdict.
• ADR smoke: 22/22; hook-shim smoke: 12/12.
• Release gates: 12 CLI contract, 238 Codex, 559 security, and 640 federation tests pass.
• All 23 buildable V3 workspace packages compile successfully.
• Focused MetaHarness, memory-path, dual-init, canonical-skill, ADR parser, ADR idempotency, memory visibility, and consolidation regressions pass.
• The stable release workflow builds immutable archives, tests the bundled policy/Codex/federation runtimes, installs all three archives, publishes the same bytes, and installs them again from the npm registry.

This patch resolves #2626, #2629, #2600, #2634, #2636, #2637, #2660, #2659, #2651, #2628, and the remaining active-row visibility defect in #2652.

Ruflo v3.32.36: Trustworthy Signals, Portable Codex Workflows

Ruflo v3.32.36 makes the information an agent sees line up with what the runtime is actually doing. Embedding commands now disclose when they are using the deterministic mock fallback, routing metrics distinguish confidence from measured outcomes, swarm status reads canonical agent state, and learned patterns preserve the task description that caused them.

The release also makes mixed Claude Code and Codex installations easier to operate. Codex receives a native read-only Ruflo status skill, dual-mode memory workers share one database path, large MCP catalogs can be filtered for small-context models, and project/plugin hook overlap is claimed exactly once. Hermetic witness verification and Node 24 MCP images strengthen the release path without adding a runtime dependency.

Install or upgrade

npm install --global ruflo@3.32.36
ruflo doctor

Existing projects remain compatible. The default MCP tool set is unchanged, legacy memory state remains readable, explicit database-path overrides are preserved, and mock embeddings remain available. The difference is that degraded or unmeasured states are now reported honestly instead of being presented as grounded semantic results or routing accuracy.

Use a smaller MCP catalog

Keep the default full catalog:

ruflo mcp start

Or select only the capabilities a constrained model needs:

ruflo mcp start --tools memory,swarm,hooks

The equivalent environment form is useful in MCP host configuration:

CLAUDE_FLOW_MCP_TOOLS=memory,swarm,hooks ruflo mcp start

Selectors accept categories, tool-name prefixes, and exact tool names. Ruflo doctor now reports catalog/schema overhead so the selection can be measured.

Inspect grounded learning state

ruflo embeddings status
ruflo hooks metrics
ruflo swarm status
ruflo doctor --component memory

embeddings status identifies the active backend and whether semantic claims are grounded. Hook metrics expose average confidence and observed outcome success separately. The memory doctor checks structural integrity, content and embedding coverage, Reflexion episode coverage, and feedback critiques.

To populate or repair the derived reasoning tables from existing memory:

ruflo memory distill run
ruflo memory distill status

Raw memory_entries and the SONA feed remain the operational write path. reasoning_patterns, episodes, embeddings, critiques, and causal edges are derived intelligence populated by distillation or the consolidate worker.

Codex and dual-mode projects

After initialization, Codex can invoke the native ruflo-status skill without receiving Cursor-specific permission JSON. Dual-mode workers now use a shared CLAUDE_FLOW_DB_PATH, including worker subprocesses and relative configuration files, so bootstrap, writes, reads, policy checks, and background work observe the same database.

The packaged Codex skill set now includes:

• swarm orchestration;
• memory management;
• SPARC methodology;
• security audit;
• GitHub automation;
• performance analysis.

Security and verification

• Witness signature verification uses Node's built-in Ed25519 support in a source-only checkout and preserves the legacy exit-2 precondition for an unbuilt full-tree verification.
• Helper signing has one public-key source, supports a piped stdin key, uses gcloud.cmd on Windows, validates Ed25519 keys, and redacts failures.
• MCP bridge images use the supported Node 24 LTS line.
• MetaHarness wrappers preserve structured HIGH findings when the upstream scanner exits non-zero.
• Root and packaged hook helpers are byte-identical and covered by a signed four-helper manifest.

What changed

• Reports the actual embedding backend and suppresses unsupported semantic interpretations while the mock fallback is active.
• Replaces misleading “Routing Accuracy” output with average confidence and measured outcome-success signals.
• Fixes learned-pattern success/failure counts and retains task descriptions in the learning write.
• Reads canonical per-agent IDs and statuses for agent list and swarm status.
• Fixes statusline install discovery, numeric version comparison, project-root resolution, and legacy nested-intelligence migration.
• Keeps non-TTY spinner output clean and erases TTY spinner lines correctly.
• Deduplicates overlapping project/plugin post-edit and session-end side effects using an atomic event claim.
• Adds MCP tool filtering and schema-overhead diagnostics.
• Repairs dual-mode Codex memory-path consistency and packaged skill assets.
• Adds memory distillation episode embeddings, historical backfill, critique preservation, and strict doctor coverage checks.

Validation

• All 23 V3 workspace packages built successfully.
• 171 changed-surface CLI tests passed.
• Codex passed 235 tests, security passed 559, and federation passed 640.
• Ruflo core hook integration passed 22/22, including duplicate-event exactly-once behavior.
• MetaHarness passed its complete plugin regression matrix, including structured finding preservation.
• Helper signing security, hermetic witness, MCP security lock, scan-format, and 37 release invariants passed.
• The stable release workflow additionally installs and tests immutable tarball archives for @claude-flow/cli, claude-flow, and ruflo before publishing those exact bytes.

This release resolves the current runtime and verification defects tracked in #2847, #2821, #2818, #2816, #2814, #2812, #2811, #2810, #2809, #2808, #2807, #2805, #2766, #2765, #2750, #2729, #2726, #2677, #2675, and #2674.

Ruflo v3.32.35: Adaptive Swarms and Safer Learning Loops

Ruflo v3.32.35 gives long-running agent teams a controlled way to learn which workers should receive future tasks. The new pheromone-adaptive topology combines outcome, latency, and consensus signals while preserving protected roles, a minimum active quorum, and existing permissions. It begins in dry-run mode so teams can inspect its decisions before enabling scheduling changes.

This release also makes the surrounding learning loop more trustworthy: project flywheels must evaluate against a project-local, hash-pinned benchmark; learned routing updates inside a live MCP process; AgentDB deletes and upserts remove stale vectors; and daemon auto-start is limited to actual Ruflo projects.

Install or upgrade

npm install --global ruflo@3.32.35
ruflo doctor

Existing installations remain compatible. The default topology is still hierarchical, old swarm state remains readable, historical flywheel receipts remain verifiable, and the new adaptive scheduler is opt-in.

Try adaptive swarm scheduling

Start in the default calibration mode:

ruflo swarm init \
  --topology pheromone-adaptive \
  --max-agents 8

ruflo swarm pheromone
ruflo agent metrics --format json

When the observations look right, explicitly enable scheduling enforcement:

ruflo swarm init \
  --topology pheromone-adaptive \
  --max-agents 8 \
  --apsc-live

Live mode changes Ruflo dispatch eligibility only. It does not terminate agents, revoke access, discard context, or widen permissions.

Use a project-local flywheel anchor

Create .claude/eval/flywheel-anchor.manifest.json:

{
  "schemaVersion": "ruflo.flywheel-anchor-manifest/v1",
  "path": "my-project-anchor.json",
  "sha256": "sha256:<canonical-task-hash>"
}

The referenced anchor contains at least four labelled tasks. Ruflo binds its canonical hash into new evaluation receipts. A non-Ruflo repository without a project anchor now fails closed instead of silently optimizing against Ruflo's built-in development benchmark.

What changed

• Adds the opt-in pheromone-adaptive swarm topology with role-aware EMA scoring, dry-run calibration, protected roles, quorum floors, bounded exploration, atomic cross-process updates, CLI inspection, and MCP tools.
• Connects hooks post-task outcomes to adaptive scheduling and exposes each agent's score, sample count, role, and eligibility through agent metrics.
• Adds hash-pinned, project-local flywheel evaluation anchors and receipt binding while retaining historical receipt verification.
• Makes learned routing use supported, discriminative evidence and immediately invalidates a warm router after labelled outcomes.
• Makes AgentDB logical-key upserts, deletes, and cleanup reconcile every stale vector and report accurate lifecycle metrics.
• Limits daemon auto-start to projects containing .claude-flow/, reports the first start, and applies a 30-minute abandoned-daemon idle timeout.

Measured benchmark

On the declared synthetic benchmark (12 agents, 20,000 updates), adaptive scheduling produced:

• 33.3% active-agent reduction;
• +0.2617 admitted mean score;
• 0.0066 ms update p95 in the release validation run;
• preserved quorum and protected-role invariants.

These are Ruflo benchmark results for that workload, not a universal production performance claim.

Validation

• TypeScript builds passed for @claude-flow/shared, @claude-flow/swarm, and @claude-flow/cli.
• The changed-surface suite passed 93 tests across nine files.
• Twenty concurrent outcome writers persisted all twenty rounds with no residual lock.
• Built CLI smoke tests covered initialization, automatic post-task learning, status, manual updates, and JSON metrics.
• CI/CD, V3 CI/CD, CodeQL, cross-agent integration, CVE audit, and verification workflows passed on the merged commit.

This release ships #2848 and resolves #2815, #2819, #2832, #2834, #2839, and #2840.

Ruflo v3.32.34: Reliable Memory Writes on Existing Installations

v3.32.34 repairs a migration gap that could prevent memory store and MCP memory_store writes on databases created before ADR-323.

The native AgentDB bridge now adds the required provenance_type column to existing memory_entries tables before writing. If that migration cannot run because the database is read-only, locked, or damaged, Ruflo fails closed and reports the native bridge error instead of presenting an unrelated WAL fallback message.

The bridge failure latch is also recoverable: shutdown resets it, successful native writes clear stale diagnostics, and degradation notices remain visible.

Install or upgrade

npm install --global ruflo@3.32.34
ruflo doctor

Existing databases are migrated automatically on the first native bridge access. No manual SQL is required.

Verify memory round-trip

ruflo memory store \
  --key release-3.32.34-check \
  --value "memory bridge migration works" \
  --namespace verification

ruflo memory retrieve \
  --key release-3.32.34-check \
  --namespace verification

For MCP clients, the equivalent memory_store and memory_retrieve tools use the same repaired path.

What changed

• Migrates provenance_type on pre-ADR-323 AgentDB files.
• Retries schema setup when the database was not writable.
• Preserves the actual native bridge error for diagnostics.
• Clears obsolete bridge errors after a successful native write.
• Resets a failed initialization latch during bridge shutdown.
• Keeps native-driver fallback notices visible.
• Adds regression coverage for legacy databases, idempotent migration, fail-closed migration, and failure-latch recovery.

Compatibility

The migration is additive and idempotent. New databases already contain the column; existing databases receive it once; installations without the optional native bridge continue to use the existing sql.js path.

This release resolves #2843 via #2844.

Ruflo v3.32.33: Autopilot Scope Enforcement at the Real CLI Boundary

v3.32.33 completes the Flywheel and Autopilot reliability release by enforcing explicit task-source validation through the same normalized flags users pass to the CLI.

The V3 parser converts kebab-case options such as --task-sources and --max-iterations to taskSources and maxIterations. The initial validation implementation correctly rejected unsupported values at the service and MCP layers but read the legacy kebab-case keys in the CLI action. As a result, the real command ignored the supplied value and persisted the default source set.

This release reads the parser's canonical camelCase keys while retaining the legacy keys for direct action callers. A parser-to-command integration test and an immutable-tarball release smoke now prove that unsupported task sources fail without creating state.

Install or upgrade

npm install --global ruflo@3.32.33
ruflo doctor

Configure an exact Autopilot scope

ruflo autopilot config \
  --task-sources swarm-tasks,file-checklist \
  --max-iterations 77

Unsupported sources fail and leave the stored configuration unchanged:

ruflo autopilot config --task-sources issues

Flywheel fix included

The release also includes the v2 retrieval safety envelope from #2836. The built-in proposer can evaluate bounded full-policy candidates without gaining promotion authority.

ruflo metaharness flywheel status
ruflo metaharness flywheel run --proposer local

Release lineage

• v3.32.31 stopped before npm publication because its helper manifest was signed for the prior version.
• v3.32.32 corrected the signed manifest and was published, but independent post-registry validation found the CLI flag-normalization mismatch.
• v3.32.33 is the validated release and receives the stable npm tags.

Ruflo v3.32.30: Capability Brain, Now Complete in the Public Install

Ruflo can coordinate hundreds of agent, memory, policy, federation, and MetaHarness capabilities—but users should not have to memorize that surface or install unpublished internal packages to make it work. v3.32.30 makes the public install self-contained and teaches newly initialized agents how to use the system safely.

This is a corrective release for v3.32.29. That package exposed the new policy runtime through a static @claude-flow/security import while declaring the unpublished package optional. Fresh installs could run --version, but policy and daemon command loading failed with ERR_MODULE_NOT_FOUND. v3.32.30 embeds the reviewed Security, Codex, and federation runtimes in each applicable public artifact and promotes their public transitive dependencies to the containing package.

What this enables

• Ask guidance_brain which registered Ruflo capabilities fit a task instead of guessing tool names.
• Run the full policy ledger, daemon, MCP, and standard CLI command surface from a fresh three-package installation.
• Generate CLAUDE.md and AGENTS.md instructions that use the Capability Brain, the validated implementation loop, isolated concurrent writers, source-bound evidence, and non-expanding authority envelopes.
• Initialize Codex projects from the bundled adapter, including its built-in skills, without requiring a standalone @claude-flow/codex publication.
• Discover the bundled federation foundation without requiring a standalone federation package. Production federation still requires deployment-specific durable storage, identity, policy, and acceptance testing.

Install or upgrade

npm install --global ruflo@3.32.30
ruflo doctor

Or run without a global install:

npx ruflo@3.32.30 --help

Use the Capability Brain

From an MCP client:

{
  "name": "guidance_brain",
  "arguments": {
    "mode": "recommend",
    "task": "Implement, test, benchmark, and review this change with concurrent agents"
  }
}

The returned workflow follows:

recall → inspect → route → plan → execute → test → validate
       → benchmark → optimize → receipt → handoff → authorized publish

Learning, Darwin, Flywheel, and MetaHarness can propose or evaluate candidates. They cannot promote themselves or expand tools, network access, secrets, spending, concurrency, or release authority.

Concurrent development defaults

Generated guidance now requires:

• one isolated worktree and explicit file scope per writing agent;
• shared checkouts only for read-only research;
• one integration owner for shared manifests, lockfiles, and overlap reconciliation;
• continued independent work after spawning agents rather than stopping;
• tests, benchmarks, policy decisions, and handoffs bound to an exact clean commit or immutable dirty-worktree snapshot.

Public package train

The normal release publishes exactly:

• @claude-flow/cli@3.32.30
• claude-flow@3.32.30
• ruflo@3.32.30

The Security, Codex, and federation runtimes are built from the reviewed monorepo source and carried as npm bundled dependencies inside the CLI and umbrella artifacts. Their source package coordinates are not published as part of this release.

Compatibility

• Existing projects are never overwritten by init unless --force is used.
• Existing guidance MCP tools remain available when guidance_brain is absent.
• Policy migration remains legacy by default; operators can move through observe before enforce.
• Optional native keychain, AgentDB, neural, and MetaHarness dependencies retain their existing graceful-degradation behavior.
• ruflo, claude-flow, and @claude-flow/cli remain version-locked and install through their established command names.

Validation contract

Release acceptance requires:

• the three-package version lockstep audit;
• focused generated-guidance and Codex adapter tests;
• Security, Codex, and federation builds and tests;
• tarball inspection proving all three internal runtimes are bundled;
• fresh tarball installation with optional dependencies omitted;
• --version, policy status, daemon start/status/stop, and init --codex smoke tests;
• npm ls without invalid dependency edges;
• registry verification and aligned latest, alpha, and v3alpha tags.

v3.32.29 is the corrective stable publication of the Capability Brain work first preserved in the immutable v3.32.28 source release. The v3.32.28 npm train was not published: its release credential was rejected, and the intended federation 1.0.0-alpha.17 coordinate was already occupied by an older artifact. Ruflo did not move the existing tag or reuse the immutable package coordinate.

This release advances ruflo, claude-flow, and @claude-flow/cli to 3.32.29, advances the federation plugin to 1.0.0-alpha.18, and retains the reviewed @claude-flow/security@3.0.0-alpha.14 and @claude-flow/codex@3.0.3 components. The original release and its end-user gist remain intact. The corrected end-user guide is available as a separate v3.32.29 gist.

Ruflo has grown into a large agentic runtime, but its old MCP guidance catalog only knew about 61 of the 353 tools available in a fully equipped process. That made powerful features hard to discover and made agents more likely to guess at stale tool names.

v3.32.29 publishes the Ruflo Capability Brain: a live, machine-readable map of the MCP registry, CLI commands, agents, skills, packages, plugins, authority boundaries, risk, and the end-to-end implementation loop. Agents can now ask Ruflo which capabilities fit a task and automatically choose from tools that are actually registered in the current process.

What you can use it for

• Discover every MCP tool registered in your running Ruflo server.
• Route a task to suitable tools, agents, skills, and a swarm topology.
• Find capabilities across .claude, .agents, installed packages, and Ruflo plugins.
• Keep optional or remote integrations honest: registered, configured, reachable, healthy, and authorized are reported as different facts.
• Guide autonomous development through recall, inspection, planning, implementation, testing, validation, benchmarking, optimization, evidence, handoff, and authorized publication.
• Distinguish policy authorization, exclusive work claims, content-safety evidence, memory learning, consensus, and release authority.
• Route Cognitum identity through the implemented PKCE/OOB profile lifecycle, while reporting RFC 8628 polling and server-side logout revocation as unavailable instead of guessing.

Try the Capability Brain

In Codex, Claude Code, or another MCP client, ask the agent:

Use Ruflo guidance_brain to recommend the best workflow for implementing this task, then follow the returned implementation loop.

Or call the MCP tool directly:

{
  "name": "guidance_brain",
  "arguments": {
    "mode": "recommend",
    "task": "Implement a secure API change with concurrent agents, tests, benchmarks, and a release"
  }
}

Useful modes:

{"name":"guidance_brain","arguments":{"mode":"overview"}}
{"name":"guidance_brain","arguments":{"mode":"capabilities","domain":"memory-knowledge"}}
{"name":"guidance_brain","arguments":{"mode":"coverage"}}
{"name":"guidance_brain","arguments":{"mode":"ecosystem"}}
{"name":"guidance_brain","arguments":{"mode":"implementation-loop"}}

The existing guidance_capabilities, guidance_recommend, guidance_discover, guidance_workflow, and guidance_quickref tools remain compatible. Their old string catalog is now labeled compatibility-only, and stale references are never presented as live recommendations.

The implementation loop

Generated Codex AGENTS.md guidance and capability recommendations now use one complete loop:

1. Recall relevant memory and ADR constraints.
2. Inspect source, runtime, dependencies, policy, and health.
3. Route to the smallest capable topology and tool set.
4. Plan acceptance criteria, safety, ownership, and validation.
5. Execute in isolated scopes; Ruflo coordinates while the coding agent works.
6. Test focused, regression, and failure paths.
7. Validate types, security, policy, compatibility, and artifacts.
8. Benchmark a source-bound candidate against a source-bound baseline.
9. Optimize measured bottlenecks without weakening safety.
10. Bind claims and evidence to exact source/build inputs.
11. Reconcile concurrent handoffs and disclose limitations.
12. Publish only through a separately authorized release gate.

Learning and optimization remain proposal/evidence capabilities. They cannot promote themselves or expand network, secrets, spending, concurrency, or policy authority.

Federation and Cognitum foundations

This release also adds opt-in foundations for policy-governed federation and Cognitum product actions:

• Upgraded federation peers advertise recursive JCS/Ed25519 signatures by default. JCS is negotiated only when the join includes a signature-verified peer manifest; endpoint-only joins stay untrusted.
• Legacy federation signatures are restricted to heartbeat and status-broadcast; consequential legacy messages are rejected on ingress and fail closed on egress to legacy-only peers.
• Inbound federation authorization runs after signature verification and before acceptance, replay marking, or event delivery.
• The Security SDK adds a closed 31-action product vocabulary for the Cognitum dashboard, Meta-LLM, Comms, Cog Studio, RuView, and validated learning.
• Product envelopes enforce audience, tenant, freshness, capability, policy, Ed25519 signature, action-specific obligations, and atomic replay-store hooks.
• RuView exports are constrained to registered, privacy-minimized semantic observations rather than raw sensor payloads.

Concurrent development foundations

The Codex package now exposes:

• content-addressed Git-visible source-state capture;
• separately declared and recomputable build-input/toolchain evidence;
• portable path/case ambiguity refusal;
• in-memory reference implementations for fenced leases, acknowledged inbox semantics, and content-addressed run receipts.

These references are deliberately observe-only, unsigned, non-persistent, and single-process. They help adapter authors test semantics; they are not distributed release authorities.

Install or upgrade

npm install --global ruflo@3.32.29
ruflo doctor

Or run it without a global install:

npx ruflo@3.32.29 --help

Package train:

• ruflo@3.32.29
• claude-flow@3.32.29
• @claude-flow/cli@3.32.29
• @claude-flow/codex@3.0.3
• @claude-flow/security@3.0.0-alpha.14
• @claude-flow/plugin-agent-federation@1.0.0-alpha.18

Compatibility

• Existing guidance MCP tools remain available.
• Existing projects stay in their current policy compatibility mode.
• JCS federation signing is negotiated; no downgrade occurs after a failed JCS verification.
• Older installations continue local workflows when optional packages are absent.
• The new Codex harness and Cognitum product-plane APIs are additive exports.

Local validation and benchmarks

Validated on Node.js 22/Linux:

• Capability Brain: all 353 observed live tools assigned exactly once; zero duplicate or fallback classifications.
• CLI focused brain/guardrail tests: 12 passing.
• Codex: 229 tests passing.
• Security: 559 tests passing.
• Federation: 638 tests passing.
• Capability Brain build for a 353-tool registry: p99 about 0.44 ms in the latest local run; recommendation p99 about 0.04 ms.
• 1.5 KiB federation JCS canonicalization: p50 8.39 µs, p99 8.68 µs, approximately 119,204 operations/second.
• 1.0 KiB signed Cognitum action verification: p50 71.97 µs, p99 81.93 µs, approximately 13,894 verifications/second.
• Source-state capture over a clean 200-file Git fixture averaged 15.77 ms; the dirty-patch plus 25-file manifest fixture averaged 27.09 ms.

These are local microbenchmarks, not cross-platform service SLOs.

Important limitations

These APIs are an opt-in foundation, not a declaration that distributed claim federation is production-ready. Persistent control-plane leases, durable inbox/outbox storage, signed receipt ledgers, release-decision composition, cross-service identity links, and Cognitum production adapters still require deployment-specific implementation and acceptance testing.

A lease, signature, claim, score, memory, consensus result, or passing test is evidence. None grants product or release authority by itself.

Architecture

• ADR-325: zero-trust claim federation and work ownership
• ADR-326: Cognitum product-plane federation profile
• ADR-327: federated concurrent development harness
• ADR-328: Cognitum-assisted agent learning
• ADR-329: Ruflo Capability Brain for MCP guidance

Ruflo v3.32.28: Agents That Know the Whole System

Ruflo has grown into a large agentic runtime, but its old MCP guidance catalog only knew about 61 of the 353 tools available in a fully equipped process. That made powerful features hard to discover and made agents more likely to guess at stale tool names.

v3.32.28 introduces the Ruflo Capability Brain: a live, machine-readable map of the MCP registry, CLI commands, agents, skills, packages, plugins, authority boundaries, risk, and the end-to-end implementation loop. Agents can now ask Ruflo which capabilities fit a task and automatically choose from tools that are actually registered in the current process.

What you can use it for

• Discover every MCP tool registered in your running Ruflo server.
• Route a task to suitable tools, agents, skills, and a swarm topology.
• Find capabilities across .claude, .agents, installed packages, and Ruflo plugins.
• Keep optional or remote integrations honest: registered, configured, reachable, healthy, and authorized are reported as different facts.
• Guide autonomous development through recall, inspection, planning, implementation, testing, validation, benchmarking, optimization, evidence, handoff, and authorized publication.
• Distinguish policy authorization, exclusive work claims, content-safety evidence, memory learning, consensus, and release authority.
• Route Cognitum identity through the implemented PKCE/OOB profile lifecycle, while reporting RFC 8628 polling and server-side logout revocation as unavailable instead of guessing.

Try the Capability Brain

In Codex, Claude Code, or another MCP client, ask the agent:

Use Ruflo guidance_brain to recommend the best workflow for implementing this task, then follow the returned implementation loop.

Or call the MCP tool directly:

{
  "name": "guidance_brain",
  "arguments": {
    "mode": "recommend",
    "task": "Implement a secure API change with concurrent agents, tests, benchmarks, and a release"
  }
}

Useful modes:

{"name":"guidance_brain","arguments":{"mode":"overview"}}
{"name":"guidance_brain","arguments":{"mode":"capabilities","domain":"memory-knowledge"}}
{"name":"guidance_brain","arguments":{"mode":"coverage"}}
{"name":"guidance_brain","arguments":{"mode":"ecosystem"}}
{"name":"guidance_brain","arguments":{"mode":"implementation-loop"}}

The existing guidance_capabilities, guidance_recommend, guidance_discover, guidance_workflow, and guidance_quickref tools remain compatible. Their old string catalog is now labeled compatibility-only, and stale references are never presented as live recommendations.

The implementation loop

Generated Codex AGENTS.md guidance and capability recommendations now use one complete loop:

1. Recall relevant memory and ADR constraints.
2. Inspect source, runtime, dependencies, policy, and health.
3. Route to the smallest capable topology and tool set.
4. Plan acceptance criteria, safety, ownership, and validation.
5. Execute in isolated scopes; Ruflo coordinates while the coding agent works.
6. Test focused, regression, and failure paths.
7. Validate types, security, policy, compatibility, and artifacts.
8. Benchmark a source-bound candidate against a source-bound baseline.
9. Optimize measured bottlenecks without weakening safety.
10. Bind claims and evidence to exact source/build inputs.
11. Reconcile concurrent handoffs and disclose limitations.
12. Publish only through a separately authorized release gate.

Learning and optimization remain proposal/evidence capabilities. They cannot promote themselves or expand network, secrets, spending, concurrency, or policy authority.

Federation and Cognitum foundations

This release also adds opt-in foundations for policy-governed federation and Cognitum product actions:

• Upgraded federation peers advertise recursive JCS/Ed25519 signatures by default. JCS is negotiated only when the join includes a signature-verified peer manifest; endpoint-only joins stay untrusted.
• Legacy federation signatures are restricted to heartbeat and status-broadcast; consequential legacy messages are rejected on ingress and fail closed on egress to legacy-only peers.
• Inbound federation authorization runs after signature verification and before acceptance, replay marking, or event delivery.
• The Security SDK adds a closed 31-action product vocabulary for the Cognitum dashboard, Meta-LLM, Comms, Cog Studio, RuView, and validated learning.
• Product envelopes enforce audience, tenant, freshness, capability, policy, Ed25519 signature, action-specific obligations, and atomic replay-store hooks.
• RuView exports are constrained to registered, privacy-minimized semantic observations rather than raw sensor payloads.

Concurrent development foundations

The Codex package now exposes:

• content-addressed Git-visible source-state capture;
• separately declared and recomputable build-input/toolchain evidence;
• portable path/case ambiguity refusal;
• in-memory reference implementations for fenced leases, acknowledged inbox semantics, and content-addressed run receipts.

These references are deliberately observe-only, unsigned, non-persistent, and single-process. They help adapter authors test semantics; they are not distributed release authorities.

Install or upgrade

npm install --global ruflo@3.32.28
ruflo doctor

Or run it without a global install:

npx ruflo@3.32.28 --help

Package train:

• ruflo@3.32.28
• claude-flow@3.32.28
• @claude-flow/cli@3.32.28
• @claude-flow/codex@3.0.3
• @claude-flow/security@3.0.0-alpha.14
• @claude-flow/plugin-agent-federation@1.0.0-alpha.17

Compatibility

• Existing guidance MCP tools remain available.
• Existing projects stay in their current policy compatibility mode.
• JCS federation signing is negotiated; no downgrade occurs after a failed JCS verification.
• Older installations continue local workflows when optional packages are absent.
• The new Codex harness and Cognitum product-plane APIs are additive exports.

Local validation and benchmarks

Validated on Node.js 22/Linux:

• Capability Brain: all 353 observed live tools assigned exactly once; zero duplicate or fallback classifications.
• CLI focused brain/guardrail tests: 12 passing.
• Codex: 229 tests passing.
• Security: 559 tests passing.
• Federation: 638 tests passing.
• Capability Brain build for a 353-tool registry: p99 about 0.44 ms in the latest local run; recommendation p99 about 0.04 ms.
• 1.5 KiB federation JCS canonicalization: p50 8.47 µs, p99 8.83 µs, approximately 118,087 operations/second.
• 1.0 KiB signed Cognitum action verification: p50 71.97 µs, p99 81.93 µs, approximately 13,894 verifications/second.
• Source-state capture over a clean 200-file Git fixture averaged 15.77 ms; the dirty-patch plus 25-file manifest fixture averaged 27.09 ms.

These are local microbenchmarks, not cross-platform service SLOs.

Important limitations

These APIs are an opt-in foundation, not a declaration that distributed claim federation is production-ready. Persistent control-plane leases, durable inbox/outbox storage, signed receipt ledgers, release-decision composition, cross-service identity links, and Cognitum production adapters still require deployment-specific implementation and acceptance testing.

A lease, signature, claim, score, memory, consensus result, or passing test is evidence. None grants product or release authority by itself.

Architecture

• ADR-325: zero-trust claim federation and work ownership
• ADR-326: Cognitum product-plane federation profile
• ADR-327: federated concurrent development harness
• ADR-328: Cognitum-assisted agent learning
• ADR-329: Ruflo Capability Brain for MCP guidance

Agents can now move quickly without receiving unlimited authority.

Ruflo v3.32.27 adds an enforceable policy layer between an agent's intent and a consequential action. Teams can define what an agent may do, cap spend and concurrency, require authenticated approval for sensitive actions, constrain delegated workers, and audit every decision through a tamper-evident receipt ledger.

Existing installations remain compatible. Start in legacy, rehearse the policy in observe, and enable blocking with enforce after reviewing the recorded decisions.

What you can use it for

• Put daily cost and token ceilings around model or tool calls.
• Require approval for production deploys, destructive actions, or flywheel promotion.
• Limit tools, MCP servers, namespaces, environments, network access, and delegated authority.
• Run bounded concurrent Codex development with a separate worktree and reduced capability envelope for every writing worker.
• Allow MetaHarness to benchmark candidates concurrently without allowing the optimizer to promote itself.
• Audit policy decisions and detect modified or reordered receipts.
• Filter AgentDB retrieval by typed provenance without breaking legacy records.

Install or upgrade

The verified GitHub release artifacts are available now. Their embedded helper manifest is signed. Install the policy runtime, CLI, and Ruflo wrapper together:

npm install --global \
  https://github.com/ruvnet/ruflo/releases/download/v3.32.27/claude-flow-security-3.0.0-alpha.13.tgz \
  https://github.com/ruvnet/ruflo/releases/download/v3.32.27/claude-flow-cli-3.32.27.tgz \
  https://github.com/ruvnet/ruflo/releases/download/v3.32.27/ruflo-3.32.27.tgz
ruflo --version
ruflo policy status

The normal npm install --global ruflo@3.32.27 path will become available after npm trusted-publisher authorization is completed. No source rebuild is required.

Safe rollout

Inspect or migrate the local policy state:

ruflo policy init
ruflo policy status
ruflo policy verify

Observe policy decisions without blocking normal actions:

ruflo policy init --mode observe

Add a daily model budget:

ruflo policy budget set '{
  "id": "daily-model-budget",
  "action": "model.call",
  "maxCostUsd": 10,
  "maxTokens": 500000,
  "periodMs": 86400000
}'

Evaluate an action:

ruflo policy evaluate '{
  "identity": {
    "id": "codex-worker-1",
    "type": "agent",
    "roles": ["developer"]
  },
  "action": {
    "type": "model.call",
    "resource": "openrouter",
    "environment": "development",
    "costUsd": 0.12,
    "tokens": 8000,
    "concurrency": 2,
    "network": true
  }
}'

After reviewing receipts and defining explicit rules:

ruflo policy init --mode enforce

The end-user quick start walks through rules, budgets, delegated capability envelopes, concurrent Codex workflows, MetaHarness promotion, and troubleshooting.

Policy-governed MetaHarness

Candidate evaluation is now bounded by both the flywheel SafetyEnvelope and the agentic policy engine:

ruflo metaharness flywheel run \
  --project-root . \
  --proposer local \
  --sample 40 \
  --max-concurrency 2 \
  --timeout-ms 120000 \
  --private-key /path/to/flywheel-private.pem \
  --public-key /path/to/flywheel-public.pem

Promotion remains a separate, explicit, policy-authorized transaction:

ruflo metaharness flywheel promote <receipt-id> \
  --project-root . \
  --public-key /path/to/flywheel-public.pem \
  --approval-id <authenticated-approval-id> \
  --confirm

Darwin proposes; Ruflo disposes. The optimizer cannot authorize its own promotion.

Safe defaults

• Existing projects migrate in backward-compatible legacy mode.
• observe records denials but does not block ordinary actions.
• Capability-envelope violations are always blocked; delegated authority cannot expand.
• observe and enforce are default-deny when no rule matches.
• Budgeted requests must report cost or token usage; missing metering does not bypass a ceiling.
• Local policy administration requires an interactive terminal.
• Approval issuance requires an authenticated human identity adapter. A local TTY is not treated as identity proof.
• MetaHarness, Darwin, and Flywheel remain optional dependencies.
• Missing optional packages do not break the local policy engine or existing AgentDB workflows.

AgentDB provenance

This release also includes ADR-323 typed provenance across AgentDB retrieval: user_claim, agent_output, system_observation, tool_result, and unknown. Legacy records remain readable and are conservatively classified as unknown; unsigned caller claims are never silently promoted to trusted evidence.

Compatibility

This is a backward-compatible patch release. Existing Ruflo and AgentDB installations continue to work without opting into enforcement. The release preserves the v3.32.26 flywheel transaction and receipt formats while adding policy authorization around privileged operations.

Release artifacts:

claude-flow-security-3.0.0-alpha.13.tgz
claude-flow-cli-3.32.27.tgz
claude-flow-3.32.27.tgz
ruflo-3.32.27.tgz
SHA256SUMS

Validation

The implementation passed:

• the complete ADR-324 policy-engine and security test suites;
• atomic budget, approval, delegation, evidence, and receipt-ledger tests;
• concurrent Codex worktree coordination tests;
• governed in-process MetaHarness evaluation and promotion tests;
• the 122-case MetaHarness contract suite;
• operation without AgentBBS or MetaHarness installed;
• MCP discoverability, install-safety, type-check, package, CodeQL, and cross-platform CI gates;
• policy-engine performance benchmarks.

Learn more

• End-user quick start
• ADR-324 architecture
• ADR-323 typed provenance
• ADR-322 governed flywheel
• Policy-engine PR #2822
• Typed-provenance PR #2820
• Full changelog

Ruflo can now test improvements to its retrieval behavior without changing the configuration you are currently using.

This release introduces a controlled flywheel:

evaluate → review → promote

Ruflo evaluates candidate settings, records the results in a verifiable receipt, and waits for you to approve an accepted candidate. Nothing is promoted automatically.

Why this matters

Self-improvement should not mean handing control to an optimizer.

With v3.32.26, you can:

• test retrieval-policy improvements against held-out tasks;
• compare quality, latency, token use, failures, and cost limits;
• inspect the evidence before making a change;
• activate an accepted candidate with an explicit command;
• audit what changed through receipts and promotion history.

Darwin can explore and propose candidates, but Ruflo remains responsible for deciding whether a candidate is safe to promote.

Install or upgrade

npm install --global ruflo@3.32.26
ruflo --version

You can also try this release without a global installation:

npx ruflo@3.32.26 metaharness flywheel status --project-root .

Try the flywheel

Check the current state:

ruflo metaharness flywheel status --project-root .

Run a local evaluation:

ruflo metaharness flywheel run \
  --project-root . \
  --proposer local \
  --sample 40 \
  --private-key /path/to/flywheel-private.pem \
  --public-key /path/to/flywheel-public.pem

Review the results:

ruflo metaharness flywheel receipts --project-root .
ruflo metaharness flywheel history --project-root .

Promote an accepted result:

ruflo metaharness flywheel promote <receipt-id> \
  --project-root . \
  --public-key /path/to/flywheel-public.pem \
  --confirm

The end-user quick start includes signing-key setup and a complete walkthrough.

Also new

• First-class metaharness flywheel commands in the CLI and MCP.
• Darwin candidate evolution through metaharness evolve.
• Stable benchmark creation and verification through metaharness bench.
• Signed receipts that detect altered evaluation evidence.
• Atomic, one-time promotion with consistent crash recovery.
• Safe local operation when the optional Darwin or Flywheel packages are not installed.

Safe by default

• Evaluation never changes the active policy.
• Promotion requires an accepted receipt and explicit --confirm.
• Stale, changed, untrusted, or already-used receipts are rejected.
• Candidate resource limits are enforced before candidates are considered.
• Darwin failures do not silently become Darwin-authorized promotions.
• Automatic unattended promotion is not enabled in this release.

v3.32.26 currently applies the new loop to bounded retrieval-policy tuning. Tool-policy evolution, model-policy evolution, and unattended autopilot remain disabled until their separate security and spending controls are ready.

Compatibility

This is a backward-compatible patch release. Existing Ruflo workflows continue to work, and the new flywheel remains opt-in.

Published packages:

ruflo@3.32.26
claude-flow@3.32.26
@claude-flow/cli@3.32.26

Validation

The release passed the focused flywheel suite, signed-receipt and tamper checks, stale-state and crash-recovery tests, resource-limit tests, and a 100-way concurrent promotion test that produced exactly one successful promotion.

Learn more

• End-user quick start
• ADR-322 architecture and safety model
• Implementation PR #2817
• Full changelog

Fixed

Floating @metaharness/darwin pin. distill-oracle.ts invoked npx --yes @metaharness/darwin with no version at three call sites (Tier-1 mechanical oracle), floating to npm latest — a breaking darwin release could change eval behavior mid-run. Now pinned via a single MH_DARWIN_PIN = '0.8.0' constant, declared @metaharness/darwin: ^0.8.0 in optionalDependencies as the single source of truth, and a stale ~0.3.1 doc comment corrected. Ruflo's analog of upstream agent-harness-generator#142.

Added

metaharness pin-drift guard (the #149 analog ruflo lacked):

• scripts/check-metaharness-pins.mjs — diffs each declared range (metaharness, @metaharness/router, @metaharness/darwin) against npm latest + a lock-step check that MH_DARWIN_PIN satisfies the darwin range. Network flakes warn, never false-positive.
• .github/workflows/metaharness-pin-drift.yml — runs weekly + on PRs touching the pins; opens/updates a tracking issue on drift, hard-fails PRs that introduce it.

Upstream companion PRs

Filed against the metaharness repo: #150 (darwin pin ^0.2.2→^0.8.0, #142) and #151 (META_PROXY_VERSION→0.7.0 + ported pin-drift watcher, #149).

Upgrade

npx ruflo@latest --version   # → 3.32.25

Refs: ADR-150, ADR-321.

Fixed

#2801 — ruflo init --codex/--dual now installs the ruflo-core@ruflo plugin. Before, Codex init set up AGENTS.md, skills, config, and the Ruflo MCP server — but no Ruflo lifecycle hooks. New installRufloCorePlugin() idempotently runs codex plugin marketplace add ruvnet/ruflo --ref main + codex plugin add ruflo-core@ruflo at user scope (canonical upstream plugin, avoiding the #2640 double-firing class), degrades gracefully with a manual-install hint if the Codex CLI is absent, and always emits a prominent ACTION REQUIRED message to trust the hooks in a new Codex session (Codex does not auto-trust command hooks). Ships in @claude-flow/codex@3.0.2.

Changed

metaharness promoted to a hard dependency (ADR-321). metaharness@^0.4.1 and @metaharness/router@^0.3.2 moved from optional to dependencies on @claude-flow/cli, so they're always present. ADR-321 supersedes ADR-150's optional-only constraint for these two and records the tradeoff honestly: the MCP metaharness tools invoke via subprocess (zero static imports), so this is functionally a cache-warm for them; the one load-bearing consumer of a declared dep is neural-router.ts's @metaharness/router import behind CLAUDE_FLOW_ROUTER_NEURAL=1. Graceful-degradation fallbacks were kept (trivial reversibility).

Packages

Package	Version
@claude-flow/cli / claude-flow / ruflo	3.32.24
@claude-flow/codex	3.0.2

Upgrade

npx ruflo@latest --version   # → 3.32.24

Closes: #2801. Refs: ADR-321, ADR-150.

Three "clean exit, no real work reflected" bugs reported by @vidaunited on v3.32.22 — all reader/writer store-shape mismatches. Each fixed and validated E2E on the published package.

Fixed

#2797 — hooks metrics Pattern Learning always 0. The pattern reader filtered on key.includes('pattern') || metadata.type==='pattern' || key.startsWith('learned-'), but no writer produces that shape. The post-task dual-write (#2786 fix-2) persists learned patterns as routing-decision:* entries in the patterns namespace. Fix: broaden the pattern filter to count namespace==='patterns' and metadata.type==='routing-decision'. Shipped validation: patterns.total 0 → 1 after one hooks post-task --store-results.

#2798 — Nightly memory backup silent no-op under CLAUDE_FLOW_ENCRYPT_AT_REST. Same class as #2786: backupMemoryDb() opened the RFE1-encrypted .swarm/memory.db with better-sqlite3's online-backup API → "file is not a database" → recorded as skipped while the worker reported 100% success. Users with encryption had zero backups behind a green status. Fix: fall back to a plain byte copy (valid — sql.js rewrites the encrypted file wholesale per flush). Shipped validation: RFE1 source → 176 KB snapshot written.

#2799 — swarm status always Total 0 agents. swarm status read .swarm/agents/*.json (never written); agent spawn records the count in .claude-flow/metrics/swarm-activity.json. Fix: reconcile against the activity file agent spawn actually writes when the agents dir is empty. Shipped validation: spawn 4 → swarm status Total 0 → 4 (matches agent list).

Verification

• Regression tests: 3/3 pass (hooks-metrics-swarm-backup-2797-2798-2799.test.ts, real execFileSync repros)
• Post-publish: all three fixes re-validated on npx ruflo@3.32.23

Upgrade

npx ruflo@latest --version   # → 3.32.23

Closes: #2797 #2798 #2799.

Hotfix for the verification agent's #2794 finding — CI on main was red since 03:04 UTC because v3.32.17's #2752 MemPoison env var didn't match the ADR-125 §"CLI flag wins" pattern the audit script requires.

Fixed

Restructured the RUFLO_MEMORY_SCAN_ON_WRITE read so ctx.flags.scanContent takes precedence via nullish coalescing, with the exact ADR-125 comment format. Removed default: false from the --scan-content option so the parser leaves it undefined when unset (required for ?? env to see the env value). Explicit --no-scan-content still wins over the env var.

Verification

• Audit script: ok: all CLAUDE_FLOW_ / RUFLO_ env var reads have documented CLI-flag precedence**
• Regression tests still green: planflip-mempoison-2752 (6/6) + memory-search-2790 (4/4)

Closes: #2794.

Two-defect fix filed by markt-heximal in #2790.

Fixed

--type keyword|hybrid silently ignored. memory search accepted, echoed, and then discarded the type flag — every search ran semantic. Now:

• --type keyword — listEntries + substring match on key+content, key hit scores 1.0, content hit 0.7
• --type hybrid — semantic ∪ keyword, dedup by (namespace, key), rerank

--threshold 0 silently replaced by fallback. Classic 0 || fallback idiom. Fixed with nullish coalescing at 3 reporter-flagged sites (memory.ts, embeddings.ts twice) plus 4 same-class hooks.ts sites (per reporter's "worth grepping more broadly" note). Also reconciled the memory.ts declared-default (0.7) vs code-fallback (0.3) disagreement.

Reporter's diagnostic invariant now holds: lower threshold returns ≥ results, not fewer.

Regression tests

4/4 E2E via real execFileSync against bin/cli.js:

• --type keyword hits substring
• --type keyword returns 0 for absent substring
• --type hybrid ≥ semantic set
• --threshold 0 ≥ --threshold 0.01 (monotonic)

Upgrade

npx ruflo@latest --version   # → 3.32.21

Closes: #2790.