claude-flow 3.56.1 → 3.56.3

package/.claude/.proven-config-version

@@ -0,0 +1 @@
+sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319

package/.claude/proven-config.json

@@ -0,0 +1,42 @@
+{
+  "adoptedAt": 1791580942030,
+  "championId": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+  "manifest": {
+    "schema": "ruflo.proven-config/v1",
+    "policy": {
+      "ref": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+      "value": {
+        "alpha": 0.3,
+        "subjectWeight": 1,
+        "mmrLambda": 0.5,
+        "bodyWeight": 1.5,
+        "typePenaltyFactor": 0.5
+      }
+    },
+    "layer": "framework/node-cli",
+    "compatibility": {
+      "ruflo": ">=3.24.0"
+    },
+    "benchmark": {
+      "corpus": "ADR-081-labelled-v1",
+      "corpusHash": "sha256:2f700b5c363e20a3bd88ce2bc9b87bbbbaa61732c6177894c6ec37890f888982"
+    },
+    "receipt": {
+      "heldOutDelta": 0.07381404928570845,
+      "redblue": "PASS",
+      "drift": 0,
+      "canary": {
+        "rollbackRate": 0,
+        "latencyP95": 244.612458000076,
+        "costPerTask": 0
+      },
+      "receiptCoverage": 1
+    },
+    "platform": [
+      "linux",
+      "macOS",
+      "windows"
+    ]
+  },
+  "previous": ""
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.56.1",
+  "version": "3.56.3",
   "workspaces": [
     "v3/@claude-flow/codex",
     "v3/@claude-flow/mcp",
@@ -101,7 +101,7 @@
     "@ruvector/router": "^0.1.31",
     "@ruvector/router-linux-x64-gnu": "^0.1.31",
     "@ruvector/sona": "^0.1.5",
-    "agentdb": "^3.0.0-alpha.17",
+    "agentdb": "^3.0.0-alpha.20",
     "agentic-flow": "^2.0.14",
     "better-sqlite3": "12.9.0"
   },

package/v3/@claude-flow/cli/README.md

@@ -1,22 +1,85 @@
 <div align="center">
 
-[![Ruflo Banner](ruflo/assets/ruflo-small.jpeg)](https://cognitum.one/agentic-engineering)
+<a href="https://cognitum.one/agentic-engineering"><img src="ruflo/assets/ruflo-neon-flicker.gif" alt="Ruflo animated neon sign" width="100%"></a>
+
+**An agent meta-harness for Claude Code and Codex.**
 
 <!-- Try Ruflo — the 3 badges first-time visitors actually act on -->
 [![npm version (ruflo)](https://img.shields.io/npm/v/ruflo?label=npx%20ruflo&style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/ruflo)
 [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT)
 [![Star on GitHub](https://img.shields.io/github/stars/ruvnet/claude-flow?style=for-the-badge&logo=github&color=gold)](https://github.com/ruvnet/claude-flow)
 
-<!-- Ecosystem strip (collapsed visually with flat-square) -->
-[![🕸️ RuVector Agentic DB](https://img.shields.io/badge/RuVector_Agentic-DB-06b6d4?style=flat-square&logoColor=white&logo=graphql)](https://github.com/ruvnet/ruvector)
-[![Ecosystem downloads](https://img.shields.io/badge/ecosystem%20downloads-8.1M%2B-blue?style=flat-square&logo=npm)](https://github.com/ruvnet/ruflo/blob/main/data/clone-data.proof.json)
-[![Git clones (14d)](https://img.shields.io/badge/git%20clones%2014d-106k-blueviolet?style=flat-square&logo=github)](https://github.com/ruvnet/ruflo/blob/main/data/clone-data.ledger.json)
-[![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-D97757?style=flat-square&logoColor=white&logo=anthropic)](https://github.com/ruvnet/claude-flow)
-[![Codex Plugin](https://img.shields.io/badge/Codex-Plugin-412991?style=flat-square&logoColor=white&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0yMi4yODIgOS44MjFhNS45ODUgNS45ODUgMCAwIDAtLjUxNi00LjkxIDYuMDQ2IDYuMDQ2IDAgMCAwLTYuNTEtMi45QTYuMDY1IDYuMDY1IDAgMCAwIDQuOTgxIDQuMThhNS45ODUgNS45ODUgMCAwIDAtMy45OTggMi45IDYuMDQ2IDYuMDQ2IDAgMCAwIC43NDMgNy4wOTcgNS45OCA1Ljk4IDAgMCAwIC41MSA0LjkxMSA2LjA1MSA2LjA1MSAwIDAgMCA2LjUxNSAyLjlBNS45ODUgNS45ODUgMCAwIDAgMTMuMjYgMjRhNi4wNTYgNi4wNTYgMCAwIDAgNS43NzItNC4yMDYgNS45OSA1Ljk5IDAgMCAwIDMuOTk4LTIuOSA2LjA1NiA2LjA1NiAwIDAgMC0uNzQ3LTcuMDczek0xMy4yNiAyMi40M2E0LjQ3NiA0LjQ3NiAwIDAgMS0yLjg3Ni0xLjA0bC4xNDItLjA4IDQuNzc4LTIuNzU4YS43OTUuNzk1IDAgMCAwIC4zOTMtLjY4MXYtNi43MzdsMi4wMiAxLjE2OGEuMDcxLjA3MSAwIDAgMSAuMDM4LjA1MnY1LjU4M2E0LjUwNCA0LjUwNCAwIDAgMS00LjQ5NSA0LjQ5NHpNMy42IDE4LjMwNGE0LjQ3IDQuNDcgMCAwIDEtLjUzNS0zLjAxNGwuMTQyLjA4NSA0Ljc4MyAyLjc1OWEuNzcxLjc3MSAwIDAgMCAuNzgxIDBsNS44NDMtMy4zNjl2Mi4zMzJhLjA4LjA4IDAgMCAxLS4wMzMuMDYyTDkuNzQgMTkuOTVhNC41IDQuNSAwIDAgMS02LjE0LTEuNjQ2ek0yLjM0IDcuODk2YTQuNDg1IDQuNDg1IDAgMCAxIDIuMzY2LTEuOTczVjExLjZhLjc2Ni43NjYgMCAwIDAgLjM4OC42NzdsNS44MTUgMy4zNTQtMi4wMiAxLjE2OGEuMDc2LjA3NiAwIDAgMS0uMDcyIDBsLTQuODMtMi43ODZBNC41MDQgNC41MDQgMCAwIDEgMi4zNCA3Ljg3MnptMTYuNTk3IDMuODU1LTUuODMzLTMuMzg3IDIuMDE2LTEuMTY1YS4wNzYuMDc2IDAgMCAxIC4wNzEgMGw0LjgzIDIuNzkxYTQuNDk0IDQuNDk0IDAgMCAxLS42NzYgOC4xMDR2LTUuNjc3YS43OS43OSAwIDAgMC0uNDA3LS42Njd6bTIuMDEtMy4wMjMtLjE0MS0uMDg1LTQuNzc0LTIuNzgyYS43NzYuNzc2IDAgMCAwLS43ODUgMEw5LjQwOSA5LjIzVjYuODk3YS4wNjYuMDY2IDAgMCAxIC4wMjgtLjA2Mmw0LjgzLTIuNzg3YTQuNDk5IDQuNDk5IDAgMCAxIDYuNjggNC42NnpNOC4zMDcgMTIuODYzbC0yLjAyLTEuMTY0YS4wOC4wOCAwIDAgMS0uMDM4LS4wNTdWNi4wNzRhNC40OTkgNC40OTkgMCAwIDEgNy4zNzYtMy40NTRsLS4xNDIuMDgtNC43NzggMi43NThhLjc5NS43OTUgMCAwIDAtLjM5My42ODJ6bTEuMDk3LTIuMzY2IDIuNjAyLTEuNSAyLjYwNyAxLjV2Mi45OTlsLTIuNTk3IDEuNS0yLjYwNy0xLjVaIi8%2BPC9zdmc%2B)](https://www.npmjs.com/package/@claude-flow/codex)
+<p align="center">
+<a href="data/npm-downloads.latest.json"><img src="docs/assets/readme/badges/downloads.svg?v=mobile-readable-3" width="300" alt="Ecosystem npm downloads: 12.52M over 12 months through October 4, 2026"></a>
+<br>
+<a href="https://github.com/ruvnet/claude-flow"><img src="docs/assets/readme/badges/claude.svg?v=mobile-readable-3" width="300" alt="Claude Code"></a>
+<a href="https://www.npmjs.com/package/@claude-flow/codex"><img src="docs/assets/readme/badges/codex.svg?v=mobile-readable-3" width="300" alt="Codex Plugin"></a>
+</p>
+
+</div>
+
+<a id="start-here"></a>
+
+## <img src="docs/assets/readme/icons/terminal.svg" width="32" height="32" alt=""> Get started with Ruflo
+
+<img src="docs/assets/readme/icons/plugins.svg" width="28" height="28" alt=""> **Start in Claude Code** with core tools, the visual console and runtime mods. Requires Claude Code **2.1.287 or later**. Run inside Claude Code:
+
+```text
+/plugin marketplace add ruvnet/ruflo
+/plugin install ruflo-core@ruflo
+/plugin install ruflo-console@ruflo
+/plugin install ruflo-mods@ruflo
+/reload-plugins
+/ruflo
+```
+
+**Core** provides foundation tools. **Console** opens the agent cockpit. **Mods** add routing and policy enforcement inside Claude Code. Mods run with your account's permissions; review their code before installing.
+
+<img src="docs/assets/readme/icons/terminal.svg" width="28" height="28" alt=""> **Using Codex or another MCP enabled tool?** Use NPX for Ruflo project setup and connect your client to the Ruflo MCP server. Run the setup wizard in your project terminal:
+
+```bash
+npx ruflo@latest init wizard
+```
+
+For clients that support local stdio MCP servers, configure **command** `npx` and **arguments** `["-y", "ruflo@latest", "mcp", "start"]`. The equivalent server command is:
+
+```bash
+npx -y ruflo@latest mcp start
+```
+
+MCP exposes Ruflo tools to your client. The console and mods above are Claude Code integrations; hook support depends on the client.
+
+[Compare install paths](#quick-start) · [Open the console](#console-walkthrough) · [User guide](docs/USERGUIDE.md)
+
+<div align="center">
+
+
+### Optional: ruOS Desktop
+
+<a href="https://ruos.cognitum.one"><img src="ruflo/assets/ruos-animated.svg" alt="ruOS — A desktop that runs itself" width="100%"></a>
+
+**Connect ruOS to ChatGPT or Claude via MCP:**
+
+```text
+https://ruos.cognitum.one/mcp
+```
+
+
+
+<!-- RuVector promo -->
+<a href="https://github.com/ruvnet/ruvector"><img src="docs/assets/readme/ruvector-promo-depth.svg" width="100%" alt="RuVector: Give your agents memory. Local vector search, persistent context, graph relationships and feedback learning. Explore RuVector."></a>
+
+```bash
+npx ruvector
+```
+
+
+
 
 # Ruflo
 
-**An agent meta-harness for Claude Code and Codex.**
+[English](README.md) · [简体中文](README.zh-CN.md)
+
 
 [![RuFlo Explained — build an AI team that plans, remembers, tests, and improves](docs/assets/ruflo-explained/ch14.jpg)](docs/ruflo-explained.md)
 
@@ -29,13 +92,16 @@ A 14-chapter guide: from the basic idea to a first useful task, then memory, age
 
 One `npx ruflo init` gives Claude Code a nervous system: agents self-organize into swarms, learn from every task, remember across sessions, and — with federation — securely talk to agents on other machines without leaking data. You keep writing code. Ruflo handles the coordination.
 
-```
-Self-Learning / Self-Optimizing Agent Architecture
+<p align="center"><img src="docs/assets/readme/learning-cinematic-compact.svg" width="100%" alt="Ruflo trajectory learning: branching memory paths, outcome feedback, contrastive AI and local learning. No LLM required for local vector retrieval and contrastive updates; agent execution may still use an LLM."></p>
 
-User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Providers
-                          ^                           |
-                          +---- Learning Loop <-------+
-```
+<sub>Conceptual learning loop. Local vector retrieval and contrastive updates can run without an LLM; embeddings and configured learning modules are still required. See the <a href="v3/@claude-flow/cli/src/services/ruvector-training.ts">RuVector training integration</a> and <a href="v3/@claude-flow/neural/src/modes/balanced.ts">trajectory contrastive learning</a>.</sub>
+
+<details>
+<summary>Architecture in text</summary>
+
+User → Ruflo (CLI/MCP) → Router → Swarm → Agents → Memory → LLM providers. Memory feeds useful experience back into routing. This is a conceptual flow, not a live execution trace.
+
+</details>
 
 > **New to Ruflo?** You don't need to learn 314 MCP tools or 26 CLI commands. After `init`, just use Claude Code normally — the hooks system automatically routes tasks, learns from successful patterns, and coordinates agents in the background.
 
@@ -48,10 +114,50 @@ User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Prov
 
 ---
 
-![Ruflo Plugins](./ruflo-plugins.gif)
+<p align="center"><img src="docs/assets/readme/console.svg" alt="Mission control: inspect agent work" width="100%"></p>
+
+<p align="center"><img src="docs/assets/ruflo-console-workflows.svg" width="952" height="964" alt="An animated recording of the ruflo console inside Claude Code: the boot (the neon sign and every area checked), then the Workflows page on a sample run: phases and agents with model, tokens and time; drilling from a run into one agent's activity, log and result; search; failure triage; cost; replay and compare; the control tab with a confirm card; and the mission autopilot panel"></p>
+
+<img src="docs/assets/readme/console-icon-workflows.svg" width="28" height="28" alt=""> **Your agent cockpit.** Track workflows, agents, models, tokens and cost beside Claude Code. The animation shows startup checks and a **sample workflow**, not a live session.
+
+<img src="docs/assets/readme/console-icon-inspect.svg" width="28" height="28" alt=""> **Inspect any run.** Open agent logs and results, search, triage failures, replay and compare. Start with `npx ruflo init`, restart Claude Code, then `/ruflo`. [Full console tour](docs/assets/ruflo-console-walkthrough-wide.gif).
+
+<img src="docs/assets/readme/console-icon-control.svg" width="28" height="28" alt=""> **Let Claude drive. You set the limits.** Enable **Settings → Claude control** to navigate and run console actions. Choose `read`, `write`, `manage` or `full`, with `ask` or `auto` approval. The current default is **read + ask**; raising the level is your choice. Actions above your permission level are refused, and network, spending and destructive actions require confirmation even in `auto`. Review the live action log or press **Take back control** to stop Claude control. [Details](v3/docs/adr/ADR-444-claude-controls-the-console.md).
+
+<a id="console-walkthrough"></a>
+
+### One task: create a mission with Claude
+
+<img src="docs/assets/readme/console-icon-workflows.svg" width="28" height="28" alt=""> **Watch the recorded console session below.** Claude creates a mission, opens the Learning and Security pages, and reports its actions in Overview.
+
+1. **Set the boundary.** Install the console using the commands below, open `/ruflo`, then choose **Settings → Claude control → write + ask**.
+2. **Give a concrete request.** Try: “Create a mission to add a dark mode toggle. Show me the mission and its status.”
+3. **Approve creation.** Claude opens Missions and sets the goal. Confirm the pending create action in the console.
+4. **Verify the result.** Check that Missions contains the goal and Overview records the action. Creating a mission does not mean the feature has been implemented.
+5. **Keep control.** **Take back control** pauses Claude's console tools. A later call should be refused until you restore control.
+
+**What the recording demonstrates:** a real Claude Haiku session with `write + auto`, mission creation, page navigation, a refused swarm stop, and control being taken back. The steps above use `ask` so you approve creation yourself. The separate workflow animation uses sample data; neither is evidence of completed swarm work or memory recall.
+
+[Implementation and recorded test findings](v3/docs/adr/ADR-444-claude-controls-the-console.md) · [Reproduction script](plugins/ruflo-console/scripts/e2e-control.sh)
+
+<p align="center"><img src="docs/assets/ruflo-console-claude-control.gif" alt="Claude Code with the ruflo console beside it: Claude sets a mission goal, creates the mission and opens the Learning, Security and Overview pages through the console tools; the Claude control dashboard logs each action; swarm-stop is refused because it needs the full level; the person clicks Take back control and the next request is refused"></p>
+
+
+**Install the mods from the ruflo marketplace** (Claude Code 2.1.287 or later; mods run with your account's permissions and are not sandboxed, so read the code first):
+
+```text
+/plugin marketplace add ruvnet/ruflo
+/plugin install ruflo-console@ruflo
+/plugin install ruflo-mods@ruflo
+/reload-plugins
+```
+
+`ruflo-console` is the cockpit above, `ruflo-mods` routes prompts and enforces policy in-process, `ruflo-swarm` shows the swarm in a pane, and `ruflo-ruos` adds the ruOS status segment. Open `/plugin` to confirm they appear in the active mods line. Inside the console, `/ruflo market` is the Plugin Catalog: every ruflo plugin, mod and skill with what it ships, and buttons to install, enable, disable and update (each asks first).
 
 ## Quick Start
 
+<p align="center"><img src="docs/assets/readme/quick-start.svg" alt="Start building with Ruflo" width="100%"></p>
+
 There are **two different install paths** with very different surface areas. Pick based on what you need (#1744):
 
 | | **Claude Code Plugin** | **CLI install (`npx ruflo init`)** |
@@ -162,7 +268,7 @@ This adds slash commands and agent definitions. `ruflo-core` (installed above) d
 
 </details>
 
-### CLI Install
+### <img src="docs/assets/readme/icons/terminal.svg" width="28" height="28" alt=""> CLI Install
 
 **macOS / Linux / WSL / Git-Bash:**
 
@@ -186,68 +292,50 @@ npm install -g ruflo@latest
 
 > 💡 **Windows users:** the `curl ... | bash` form needs a POSIX shell (Git-Bash, WSL, MSYS). The `npx ruflo@latest init wizard` line works natively in PowerShell and cmd. If you hit an `'bash' is not recognized` error, use the `npx` line instead — both end up running the same init flow.
 
-### MCP Server
+### <img src="docs/assets/readme/icons/network.svg" width="28" height="28" alt=""> MCP Server
 
 ```bash
 # Add Ruflo as an MCP server in Claude Code
 claude mcp add claude-flow -- npx ruflo@latest mcp start
 ```
 
-#### HTTP transport security
+---
 
-`ruflo mcp start -t http` exposes every registered tool over HTTP (`/rpc`, `/mcp`, `/ws`). The default `stdio` transport is not affected.
+## What You Get
 
-| Setting | Effect |
-|---|---|
-| `RUFLO_MCP_HTTP_TOKEN=<token>` | Require `Authorization: Bearer <token>` on every request. Failure is a bare `401`. The token is compared in constant time and is never logged. Prefer this over `--auth-token`, which is visible in `ps`. |
-| `--auth-token-file <path>` | Read the token from a file (one line). Takes precedence over the env var. |
-| `--auth-token <token>` | Same, on the command line (visible in argv; highest precedence). |
-| `RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1` | Allow an unauthenticated bind to a non-loopback `--host`. Only for a trusted network boundary or an authenticating reverse proxy. |
+<p align="center"><img src="docs/assets/readme/capabilities.svg" alt="Your agent toolkit" width="100%"></p>
 
-A token must be 16-512 printable ASCII characters (no spaces). `GET /health` stays public and returns only `{"status":"ok"}` when a token is set. Tokens are supported for `-t http` only; `-t websocket` rejects one.
+<table>
+<tr><td width="50%"><a href="plugins/ruflo-swarm/README.md"><img src="docs/assets/readme/card-swarm.svg" width="100%" alt="Agent teams"></a></td><td width="50%"><a href="plugins/ruflo-rag-memory/README.md"><img src="docs/assets/readme/card-memory.svg" width="100%" alt="Persistent memory"></a></td></tr>
+<tr><td width="50%"><a href="plugins/ruflo-intelligence/README.md"><img src="docs/assets/readme/card-learning.svg" width="100%" alt="Learning loops"></a></td><td width="50%"><a href="plugins/ruflo-security-audit/README.md"><img src="docs/assets/readme/card-security.svg" width="100%" alt="Security controls"></a></td></tr>
+<tr><td width="50%"><a href="https://ruvnet.github.io/ruflo"><img src="docs/assets/readme/card-plugins.svg" width="100%" alt="Plugin marketplace"></a></td><td width="50%"><a href="plugins/ruflo-ruvllm/README.md"><img src="docs/assets/readme/card-routing.svg" width="100%" alt="Models and routing"></a></td></tr>
+</table>
 
-| `--host` | no token | token set |
-|---|---|---|
-| `localhost`, `127.0.0.1`, `::1` | starts, **unauthenticated** | starts, token required |
-| anything else (`0.0.0.0`, `::`, a LAN IP, `127.0.0.2`, `[::1]`, `LOCALHOST`) | **refuses to start** unless `RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1` | starts, token required |
+| Capability | Description |
+|------------|-------------|
+| <img src="docs/assets/readme/icons/agents.svg" width="28" height="28" alt=""> **100+ Agents** | Specialized agents for coding, testing, security, docs, architecture |
+| <img src="docs/assets/readme/icons/network.svg" width="28" height="28" alt=""> **Comms Layer** | Zero-trust federation — agents across machines/orgs discover, authenticate, and exchange work securely |
+| <img src="docs/assets/readme/icons/swarm.svg" width="28" height="28" alt=""> **Swarm Coordination** | Hierarchical, mesh, and adaptive topologies with consensus |
+| <img src="docs/assets/readme/icons/learning.svg" width="28" height="28" alt=""> **Self-Learning** | SONA neural patterns, ReasoningBank, trajectory learning |
+| <img src="docs/assets/readme/icons/memory.svg" width="28" height="28" alt=""> **Vector Memory** | HNSW-indexed AgentDB — measured ~1.9x faster at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99); ANN wins above the crossover, ties/loses at small N. See [audit](docs/reviews/intelligence-system-audit-2026-05-29.md) + [`scripts/benchmark-intelligence.mjs`](scripts/benchmark-intelligence.mjs) |
+| <img src="docs/assets/readme/icons/workers.svg" width="28" height="28" alt=""> **Background Workers** | 12 auto-triggered workers (audit, optimize, testgaps, etc.) |
+| <img src="docs/assets/readme/icons/plugins.svg" width="28" height="28" alt=""> **Plugin Marketplace** | 33 native Claude Code plugins + 21 npm plugins |
+| <img src="docs/assets/readme/icons/routing.svg" width="28" height="28" alt=""> **Multi-Provider** | Claude, GPT, Gemini, Cohere, Ollama with smart routing |
+| <img src="docs/assets/readme/icons/security.svg" width="28" height="28" alt=""> **Security** | AIDefence, input validation, CVE remediation, path traversal prevention |
+| <img src="docs/assets/readme/icons/federation.svg" width="28" height="28" alt=""> **Agent Federation** | Cross-installation agent collaboration with zero-trust security |
+| <img src="docs/assets/readme/icons/audit.svg" width="28" height="28" alt=""> **[MetaHarness](docs/metaharness-user-guide.md)** | Audit your AI agent setup before you ship. Grade readiness (1-100), scan tool configs for security issues, snapshot the whole project to catch regressions over time, and find templates that match your repo. `ruflo eject` turns a ruflo project into a standalone agent toolkit with its own name. [Full guide](docs/metaharness-user-guide.md). |
 
-Without a token, a loopback server is still unauthenticated: any process on the machine, and any web page that can reach it via DNS rebinding, can call tools. Set `RUFLO_MCP_HTTP_TOKEN` whenever the HTTP transport is used.
+### <img src="docs/assets/readme/icons/learning.svg" width="28" height="28" alt=""> Learning from experience
 
-**Upgrading:** binding off loopback (for example `--host 0.0.0.0` in Docker) now needs a token or the opt-out above; otherwise the server exits with an error.
+<p align="center"><img src="docs/assets/readme/learning-flow.svg" width="100%" alt="Recall, execute, evaluate, store, adapt and reuse: an illustrative agent learning cycle."></p>
 
----
-
-## What You Get
-
-| Capability | Description |
-|------------|-------------|
-| 🤖 **100+ Agents** | Specialized agents for coding, testing, security, docs, architecture |
-| 📡 **Comms Layer** | Zero-trust federation — agents across machines/orgs discover, authenticate, and exchange work securely |
-| 🐝 **Swarm Coordination** | Hierarchical, mesh, and adaptive topologies with consensus |
-| 🧠 **Self-Learning** | SONA neural patterns, ReasoningBank, trajectory learning |
-| 💾 **Vector Memory** | HNSW-indexed AgentDB — measured ~1.9x faster at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99); ANN wins above the crossover, ties/loses at small N. See [audit](docs/reviews/intelligence-system-audit-2026-05-29.md) + [`scripts/benchmark-intelligence.mjs`](scripts/benchmark-intelligence.mjs) |
-| ⚡ **Background Workers** | 12 auto-triggered workers (audit, optimize, testgaps, etc.) |
-| 🧩 **Plugin Marketplace** | 33 native Claude Code plugins + 21 npm plugins |
-| 🔌 **Multi-Provider** | Claude, GPT, Gemini, Cohere, Ollama with smart routing |
-| 🛡️ **Security** | AIDefence, input validation, CVE remediation, path traversal prevention |
-| 🌐 **Agent Federation** | Cross-installation agent collaboration with zero-trust security |
-| 🔬 **[MetaHarness](docs/metaharness-user-guide.md)** | Audit your AI agent setup before you ship. Grade readiness (1-100), scan tool configs for security issues, snapshot the whole project to catch regressions over time, and find templates that match your repo. `ruflo eject` turns a ruflo project into a standalone agent toolkit with its own name. [Full guide](docs/metaharness-user-guide.md). |
+Useful trajectories and task feedback can inform future work. Results depend on the configured memory, learning components and quality of feedback. [Learning plugin](plugins/ruflo-intelligence/README.md).
 
 ### Agent Federation — Slack for Agents
 
-```
-Your Agent --> [ Remove secrets ] --> [ Sign message ] --> [ Encrypted channel ]
-                 Emails, SSNs,        Proves it came       No one reads it
-                 keys stripped         from you              in transit
-                                                                |
-                                                                v
-Their Agent <-- [ Block attacks ] <-- [ Check identity ] <------+
-                 Stops prompt          Rejects forgeries
-                 injection
-
-                          Audit trail on both sides.
-                  Trust builds over time. Bad behavior = instant downgrade.
-```
+<p align="center"><img src="docs/assets/readme/federation.svg" alt="Connected intelligence across machines" width="100%"></p>
+
+<p align="center"><img src="docs/assets/readme/federation-flow.svg" width="100%" alt="Outbound agent, data filtering, signing and encryption, identity verification, input checks and receiving agent."></p>
 
 Slack gave teams channels. Federation gives agents the same thing — **shared workspaces across trust boundaries**, where agents on different machines, orgs, or cloud regions can discover each other, prove who they are, and collaborate on tasks.
 
@@ -349,6 +437,8 @@ User --> Claude Code / CLI
 
 ## Documentation
 
+<p align="center"><img src="docs/assets/readme/documentation.svg" alt="Guides, architecture and verification" width="100%"></p>
+
 Four docs for four audiences:
 
 | Doc | When to read it |
@@ -379,6 +469,8 @@ User Guide section index:
 
 ## Support
 
+<p align="center"><img src="docs/assets/readme/support.svg" alt="Build with the Ruflo community" width="100%"></p>
+
 | Resource | Link |
 |----------|------|
 | Documentation | [User Guide](docs/USERGUIDE.md) |
@@ -387,6 +479,10 @@ User Guide section index:
 | Community | [Agentics Foundation Discord](https://discord.com/invite/dfxmpwkG2D) |
 | Powered by | [Cognitum.one](https://cognitum.one) |
 
+<p align="center"><img src="docs/assets/readme/signal-divider.svg" alt="Ruflo" width="100%"></p>
+
 ## License
 
 MIT - [RuvNet](https://github.com/ruvnet)
+
+<a href="https://cognitum.one"><img src="docs/assets/readme/cognitum-banner-v2.svg" width="100%" alt="Cognitum One: Ambient Intelligence at the edge of the Physical World. Explore cognitum.one."></a>

package/v3/@claude-flow/cli/catalog-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generation": 6,
-  "generatedAt": "2026-09-17T21:28:47.530Z",
-  "gitSha": "702d1461",
+  "generation": 7,
+  "generatedAt": "2026-10-09T21:52:00.476Z",
+  "gitSha": "8c60c8c7",
   "catalog": {
-    "agents": 167,
-    "tools": 418,
+    "agents": 176,
+    "tools": 423,
     "skills": 34
   },
   "benchmark": null

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

@@ -2600,8 +2600,12 @@ export const hooksSessionEnd = {
             try {
                 await bridge?.shutdownBridge();
             }
-            catch {
-                // Cleanup is best-effort and must not fail session-end.
+            catch (err) {
+                // Cleanup is best-effort and must not fail session-end, but a failed
+                // AgentDB persist (lock/concurrent writer) is never silent.
+                if (err?.code === 'AGENTDB_LOCK_UNRECOVERABLE') {
+                    process.stderr.write(`[ruflo] warning: ${err.message}\n`);
+                }
             }
         }
         return {

package/v3/@claude-flow/cli/dist/src/mcp-tools/task-tools.d.ts

@@ -4,5 +4,10 @@
  * Tool definitions for task management with file persistence.
  */
 import { type MCPTool } from './types.js';
+export declare const TASK_STATUSES: readonly ["pending", "in_progress", "completed", "failed", "cancelled"];
+type TaskStatus = (typeof TASK_STATUSES)[number];
+/** The canonical status for a written one (trimmed, any case, known aliases), or null when it is none of the five. */
+export declare function statusOf(value: unknown): TaskStatus | null;
 export declare const taskTools: MCPTool[];
+export {};
 //# sourceMappingURL=task-tools.d.ts.map

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

@@ -12,6 +12,21 @@ import { validateIdentifier, validateText } from './validate-input.js';
 const STORAGE_DIR = '.claude-flow';
 const TASK_DIR = 'tasks';
 const TASK_FILE = 'store.json';
+export const TASK_STATUSES = ['pending', 'in_progress', 'completed', 'failed', 'cancelled'];
+// Spellings agents write for the same five states (seen in the wild: "complete").
+const STATUS_ALIASES = {
+    complete: 'completed', done: 'completed', canceled: 'cancelled',
+    running: 'in_progress', 'in-progress': 'in_progress', inprogress: 'in_progress',
+};
+/** The canonical status for a written one (trimmed, any case, known aliases), or null when it is none of the five. */
+export function statusOf(value) {
+    if (typeof value !== 'string')
+        return null;
+    const key = value.trim().toLowerCase();
+    if (TASK_STATUSES.includes(key))
+        return key;
+    return Object.hasOwn(STATUS_ALIASES, key) ? STATUS_ALIASES[key] : null;
+}
 function getTaskDir() {
     return join(getProjectCwd(), STORAGE_DIR, TASK_DIR);
 }
@@ -290,7 +305,9 @@ export const taskTools = [
             type: 'object',
             properties: {
                 taskId: { type: 'string', description: 'Task ID' },
-                status: { type: 'string', description: 'New status' },
+                // No schema enum: the HTTP/WebSocket registry validates enums before the handler, which would refuse the aliases there
+                // while stdio accepted them. The handler is the one place that normalises and refuses, for every transport.
+                status: { type: 'string', description: 'New status: pending, in_progress, completed, failed or cancelled' },
                 progress: { type: 'number', description: 'Progress percentage (0-100)' },
                 assignTo: { type: 'array', items: { type: 'string' }, description: 'Agent IDs to assign' },
                 result: { type: 'object', description: 'Result data (e.g. the failure of a failed task)' },
@@ -302,26 +319,52 @@ export const taskTools = [
             const vId = validateIdentifier(input.taskId, 'taskId');
             if (!vId.valid)
                 return { success: false, error: vId.error };
+            // A status outside the five is stored as written otherwise, and every reader that buckets
+            // by status (task_list filters, the console kanban) then miscounts it: "complete" read as pending.
+            const status = input.status === undefined ? undefined : statusOf(input.status);
+            if (status === null) {
+                return { success: false, error: `status must be one of ${TASK_STATUSES.join(', ')}` };
+            }
             const store = loadTaskStore();
             const taskId = input.taskId;
             const task = store.tasks[taskId];
             if (task) {
-                if (input.status) {
-                    const newStatus = input.status;
+                // Worker effects run AFTER the task store is saved, as task_complete does: a failed save must not leave
+                // workers freed and counted against a task that still reads unfinished.
+                let afterSave;
+                if (status !== undefined) {
+                    const newStatus = status;
+                    const wasCompleted = task.status === 'completed';
                     task.status = newStatus;
                     if (newStatus === 'in_progress' && !task.startedAt) {
                         task.startedAt = new Date().toISOString();
                     }
-                    // A failed task frees its workers, as task_complete and task_cancel do;
-                    // otherwise a worker whose run failed stays `busy` forever.
-                    if (newStatus === 'failed') {
+                    // A finished task frees its workers, as task_complete and task_cancel do; otherwise a worker
+                    // whose task was finished through task_update stays `busy` forever, and a later task_complete
+                    // returns early because the status already reads completed.
+                    if (newStatus === 'failed' || newStatus === 'cancelled') {
+                        task.completedAt = new Date().toISOString();
+                        afterSave = () => releaseAgents(task.assignedTo, taskId);
+                    }
+                    if (newStatus === 'completed' && !wasCompleted) {
                         task.completedAt = new Date().toISOString();
-                        releaseAgents(task.assignedTo, taskId);
+                        // Credited only to a worker still holding this task, so complete -> pending -> complete
+                        // (no reassignment in between) never counts the same work twice.
+                        afterSave = () => updateAgents(task.assignedTo, (agent) => {
+                            if (agent.currentTask === taskId) {
+                                agent.status = 'idle';
+                                agent.currentTask = null;
+                                agent.taskCount = (agent.taskCount || 0) + 1;
+                            }
+                        });
                     }
                 }
                 if (typeof input.progress === 'number') {
                     task.progress = Math.min(100, Math.max(0, input.progress));
                 }
+                // Completing is 100% whatever progress the same call carried.
+                if (task.status === 'completed')
+                    task.progress = 100;
                 if (input.assignTo) {
                     task.assignedTo = input.assignTo;
                 }
@@ -329,6 +372,7 @@ export const taskTools = [
                     task.result = input.result;
                 }
                 saveTaskStore(store);
+                afterSave?.();
                 return {
                     success: true,
                     taskId: task.taskId,

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

@@ -2087,16 +2087,25 @@ export function shutdownBridge() {
         if (activeOperations > 0)
             await new Promise(resolve => { drained = resolve; });
         await Promise.allSettled([...registryPromises.values()]);
+        // A failed PERSIST (AGENTDB_LOCK_UNRECOVERABLE: live lock or concurrent
+        // writer on a sql.js database) means pending changes were not saved. That
+        // is surfaced after cleanup completes; other close errors stay best-effort.
+        let persistFailure;
         for (const registry of new Set(registryInstances.values())) {
             try {
                 await registry.shutdown();
             }
-            catch { /* best-effort cleanup */ }
+            catch (err) {
+                if (err?.code === 'AGENTDB_LOCK_UNRECOVERABLE')
+                    persistFailure ??= err;
+            }
         }
         registryInstances.clear();
         registryPromises.clear();
         testRegistryOverride = null;
         bridgeFailureReasons.clear();
+        if (persistFailure)
+            throw persistFailure;
     })().finally(() => { shutdownPromise = null; });
     return shutdownPromise;
 }