v3.56.0

# v3.56.0 - hardening and correctness batch

Minor release. Several fixes change behaviour on purpose; they are listed first. Integrated by merging each PR head, so authorship is preserved. Packages: `@claude-flow/cli`, `claude-flow`, `ruflo` 3.56.0 (tags `latest`, `alpha`, `v3alpha`), plus `@claude-flow/memory` 3.0.2 and `@claude-flow/security` 3.0.3 published standalone first.

## Behaviour changes (read these)

- **Unknown ids and value-less options are errors (#3911, @martinvlad).** `agent status` / `task status` with an unknown id print "not found" and exit 1. A declared string/number option given no value (for example `hooks route --task`) now reports `Option --task needs a value` instead of silently becoming `true`. Applies to every command.
- **Sessions (#3489, #3490, @rudycelekli).** `session_save` captures the persisted task, agent and legacy memory stores by default (explicit `false` still excludes). `session_import` rejects malformed stores before saving and derives counts from the snapshot.
- **Backups (#3903).** The default project backup snapshots both `memory.db` and `agentdb-memory.db` and honors the configured memory directory. `--db` and a non-blank `CLAUDE_FLOW_DB_PATH` still select a single file.
- **Zero values are honored (#3488, #3496).** Scaling an agent pool to 0 no longer creates five workers; invalid targets fail before writing; a zero fallback retry budget is respected.
- **Path validators (#3504, `@claude-flow/security` 3.0.3).** Sensitive directory names are blocked anywhere under the project root, not only at the leaf, and the blocked-extension check also applies to synchronous validation.
- **OAuth callback server (#3507, `@claude-flow/security` 3.0.3).** Retains an early callback and ignores unrelated requests.
- **Providers (#3493, #3494, #3495).** An explicit execution provider is honored; Anthropic gateway credentials and endpoint (`ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`) are used (fixes #3100); timeouts cover reading the response body.
- **Routing (#3904, #3498).** `hooks_route` now consults persisted SONA outcome patterns before local routing: only a supported agent at confidence >= 0.6 is used, and `useSemanticRouter: false` keeps keyword routing. With the opt-in neural router, model selection uses calibrated quality predictions, so calibration can move a pick across the quality bar.
- **WAL gate (#3894, @nicholas-ruest; fixes #3161).** Leftover `-wal`/`-shm` files from a closed connection no longer block `memory store`/`list`; a genuinely open holder is still refused.
- **`ruflo init` no longer pins a Claude model (#3528, @HF-teamdev; fixes #3527).**
- **`ruflo` wrapper (#3438).** Pins the matching `@claude-flow/cli` and prints a warning if the resolved CLI version differs. It warns and continues; it does not refuse to run. Fixes #3306.
- **Claims (#3502).** CLI and MCP share one lossless claims.json format; unreadable or malformed stores are refused rather than replaced.
- **Native immutable conditional append (#3750, @stuinfla).** New `memory store` flags `--append-only`, `--append-conditions`, `--require-native`, `--no-embedding`. Additive, CLI only.

## Fixes

- Shipped `.claude/settings.json` had unescaped quotes in hook commands and did not parse (#3895, fixes #3888, @nicholas-ruest). A new test checks that every shipped settings/plugin JSON file parses.
- Remaining better-sqlite3 opens use the shared loader (#3896, @nicholas-ruest; supersedes #3884 by @drakeo338); RFE1-encrypted stores are reported as encrypted, not broken (#3906, fixes #2889, @nicholas-ruest); the demo plugin-registry fallback is labelled as unverified (#3897, @martinvlad).
- `analyze` preserves machine-readable JSON (#3910); `doctor` rejects unsupported component selections (#3907) and loads MetaHarness via file URLs on Windows (#3523, fixes #3186); `daemon start` honors explicit workers (#3586).
- Unreadable task/agent records are preserved (#3484); async registry updates do not revive retired agents (#3492); fallback learning is attributed per attempted model (#3497).
- Workflow step boundaries are validated (#3491); persisted workflows resume without duplicate executors (#3500) and keep control signals and sibling state across awaits (#3505).
- Memory JSON import reports rejected writes accurately (#3499); export reads all pages only after successful reads (#3501); concurrent rotating-token refreshes coalesce (#3506).
- Test fixtures isolate pnpm's NODE_PATH (#3543, fixes #3529, @HF-teamdev's report).
- `@claude-flow/memory` 3.0.2: cache admission accounts for replacement sizes (#3679, fixes #3678); invalidation matches each key independently (#3687, fixes #3686).
- Handlebars lock entries moved to 4.7.10 after new critical advisories against 4.7.9 (dev tooling only).
- An empty `.claude/agents/tmp.json` no longer ships in the CLI tarball.

Contributors: @rudycelekli, @nicholas-ruest, @martinvlad, @HF-teamdev, @drakeo338, @stuinfla. Thank you.

## Not included, and why

- #3503 (fail-closed policy envelope): on the real MCP dispatch path nothing supplies cost/token/concurrency, so any envelope with a ceiling would deny every tool call; its own updated test shows `concurrency-outside-envelope`. Needs the dispatcher to supply metering.
- #3892 (policy ledger retention): default `policy verify` would stop covering the archive; needs the archive tip anchored or cross-checked, and the home mirror handled.
- #3831 (embedding cache dir): needs a rebase and half of it targets `@claude-flow/embeddings`, which cannot be published from main.
- #3694 (configurable MCP rate limits): needs a ceiling for non-loopback binds.
- #3879/#3622/#3476 (EWC), #3835, #3751, #3909, #3905, #3690, #3776: drafts or decisions pending.

## Verification

Full CLI suite 5408 passed (4 failures that reproduce identically on unmodified main in the release environment), security 611/611, memory suite passes, ruflo wrapper test, umbrella lockstep and leaf audits, witness manifests 117/117 on linux/macos/windows, pnpm frozen install passes the new lockfile and fails the old one.

Release PR #3916: 120 CI checks passed on the final head (3 skipped). Registry check after publish: `latest`, `alpha` and `v3alpha` all point at 3.56.0 for `@claude-flow/cli`, `claude-flow` and `ruflo`; a clean `npx ruflo@latest --version` reports v3.56.0 with memory 3.0.2 and security 3.0.3, and `mcp start -t http --host 0.0.0.0` refuses without a token.