🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
dream(performance): #3329 wire MoE gate's load-balance loss into the actual weight update (evaluated, ACCEPT-scoped) (#3330)
rUv47c5dd408a61
diff --git a/docs/dream-cycle/LEDGER.md b/docs/dream-cycle/LEDGER.mdindex a10e3e94d6..d61936475b 100644--- a/docs/dream-cycle/LEDGER.md+++ b/docs/dream-cycle/LEDGER.md@@ -192,6 +192,7 @@ as a first-class, high-priority candidate, not a background note.| 2026-09-10 | performance | `mmrRerank()` eagerly re-tokenized every remaining candidate's content on every MMR outer-loop pass (O(N×limit) `tokenize()` calls) — a pattern that predates and survived PR #3169's embedding-cosine wiring unchanged, even though the cosine branch made that tokenization mostly discarded work in the now-common all-embedded case; made lazy and cached per-candidate | #3265 | #3266 | yes | ACCEPT | `tokenize()` calls 400→0 (N=30/limit=20 corpus, stash-isolated: fails against real baseline, passes against candidate); wall-clock 5.88x faster (0.6745ms→0.1148ms mean), independently reproduced at 5.96x by an adversarial critic; selection output byte-identical to baseline across all-embedded/none/mixed/lambda-extreme scenarios; 473/474 full-suite both ways (1 pre-existing unrelated failure), `tsc` clean | 78c074ef... | rebased onto main (post #3086/#3094/#3103/#3110/#3119/#3123/#3130/#3139/#3152/#3160/#3232 merges), awaiting fresh CI as of 2026-09-14 || 2026-09-11 | security | `hive-mind_consensus` accepted votes from any caller-supplied `voterId` with no check against `state.workers` (a single caller could cross any strategy's quorum by voting under fabricated identities — a Sybil attack on consensus); fail-closed roster-membership check added. **Update (ruvnet review):** REJECTed the initial scoped fix on the caveat the adversarial critic had already disclosed (`hive-mind_join`/`leave` fully unauthenticated — the roster itself could be Sybil'd) plus a required-CI cold-install failure (`@claude-flow/security` missing a `prepare` script, so root `npm ci` never built its dist/). Both addressed same-session: `join`/`leave`/`vote` now capability-bound to a `hiveToken` minted by `hive-mind_init` (32-byte random, constant-time comparison, fail-closed — zero state change for denied calls, verified via a fresh state.json reload simulating restart; a same-machine-only token reader lets the CLI's own subcommands keep working without exposing the token over any MCP response); `@claude-flow/security`'s `package.json` gained a `prepare: npm run build` so root `npm ci` builds it automatically for every consumer, not just this CI job | #3290 | #3291 | yes | ACCEPT-scoped (post-review) | stash-isolated 2/3 fail baseline (forged votes silently accepted) → 3/3 pass candidate; full `@claude-flow/cli` suite failures 46→28 after the CI fix (remainder pre-existing/unrelated); adversarial critic CONFIRMED-WITH-CAVEATS pre-review, both caveats closed post-review | 55d67b4a... | rebased onto main (post #3086/#3094/#3103/#3110/#3119/#3123/#3130/#3139/#3152/#3160/#3232/#3266 merges), awaiting fresh CI as of 2026-09-14 || 2026-09-12 | intelligence | `LocalReasoningBank.findSimilar()` overwrote every returned pattern's `confidence` (learned reliability) with the per-query cosine similarity score instead of the already-declared `PatternMatch.similarity` field, inverting `distillLearning()`'s "only distill from high-confidence matches" gate (it tested query-similarity, not reliability) and forcing `findSimilarPatterns()`'s public API into an unsafe cast that made `confidence`/`similarity` always identical; `findSimilar()` now preserves real `confidence` and returns `similarity` separately, with the one affected consumer (`memory-bridge.ts`'s search-ranking score) migrated accordingly | #3301 | #3302 | yes | ACCEPT | 4 new discriminating tests, baseline-fails/candidate-passes via stash isolation; full suite 90-vs-91-failed-files identical except the new test file; `tsc --noEmit` byte-identical (463 errors both ways); independent adversarial critique CONFIRMED, no blocking caveats | cb60b43b... | rebased onto main (post #3086/#3094/#3103/#3110/#3119/#3123/#3130/#3139/#3152/#3160/#3232/#3266/#3291 merges), awaiting fresh CI as of 2026-09-14 |+| 2026-09-15 | performance | `MoERouter.route()` computed a Switch-Transformer-style load-balance auxiliary loss every call and returned it in `RoutingResult`, but `updateExpertWeights()` (the sole mutator of gate weights) never read that loss or its coefficient in its REINFORCE gradient math — the regularizer the module's own header claims had zero actual training effect; wired the analytic (softmax-Jacobian) gradient into the existing update path, using a per-`route()` fraction snapshot for consistency | #3329 | #3330 | yes | ACCEPT-scoped | 4 new discriminating tests, baseline-fails/candidate-passes via stash isolation (reproduced independently by critic); full `@claude-flow/neural` suite 132/132→136/136, 0 regressions; `tsc --noEmit` clean; independent adversarial critique CONFIRMED (scoping caveat: `updateExpertWeights()` has zero production callers today, though `route()` itself is live) | 5e719b96... | trailing 7 nights (#3086,#3139,#3152,#3160,#3232,#3243,#3266,#3291,#3302) all MERGED 2026-09-14 — full prior backlog cleared, reversing the earlier "0 of 14" signal |**Note (2026-09-21):** #3302 confirmed **MERGED** 2026-09-15 via `pull_request_read` (authoritative) — `search_pull_requests`'s `merged` field is stale/unreliable (it reported `merged:false` with a populated `merged_at` for this same PR; do not trust it for merge-state checks, use `pull_request_read`/`get`). **New no-run gap, confirmed via `git ls-remote --heads origin "dream/*"`**: 2026-09-13 and 2026-09-14 have no branch, issue, or PR — same verification standard as the documented 08-20..08-23 gap, root cause still undiagnosed. 2026-09-15 through 2026-09-20 all ran (real branches confirmed): #3329/#3330 (perf, MoE load-balance), #3338/#3339 (security, hive-mind capability-token round 2), #3349/#3350 (intelligence, ModelRouter prior-decay env override), #3351/#3352 (memory, AgentDBAdapter upsert-orphan fix), #3356/#3357 (swarm, topology mirror-edge fix), #3377/#3378 (performance, UnifiedSwarmCoordinator busy-poll→event-driven, ~487x measured) — not transcribed row-by-row here per the established "ledger rows only reach `main` via PR merge" convention; all currently open/draft, none stale (<14d old as of tonight).diff --git a/docs/dream-cycle/dream-gist-2026-09-15.md b/docs/dream-cycle/dream-gist-2026-09-15.mdnew file mode 100644index 0000000000..675f84d24a--- /dev/null+++ b/docs/dream-cycle/dream-gist-2026-09-15.md@@ -0,0 +1,114 @@+# Performance SOTA Report — 2026-09-15++TL;DR: Tonight's `performance` deep-dive found that `MoERouter.route()` (`v3/@claude-flow/neural/src/moe-router.ts`) computes a Switch-Transformer-style load-balance auxiliary loss on every routing decision and returns it in `RoutingResult`, but `updateExpertWeights()` — the only method that ever mutates the gating network's weights — never read that loss or its coefficient anywhere in its REINFORCE gradient math. The load-balancing regularizer the module's own header claims ("Load balancing with auxiliary loss") had zero actual effect: the 8-expert gate was free to collapse onto a subset of experts under reward-only updates. Fixed by threading the auxiliary loss's analytic gradient (softmax-Jacobian derived, independently re-verified by an adversarial critic) into the existing gradient-update path. Five research roles ran in parallel tonight (deep researcher, security scan, hive-mind scan, competitor analyst, architecture reviewer); this was the architecture reviewer's top finding, selected over the deep researcher's own five scored candidates on evaluation-robustness grounds (see Hypothesis section).++## What's New in 2026++| Finding | Source | Confidence |+|---|---|---|+| Agent-aware KV-cache/prompt-cache management is an active 2026 research cluster (CacheScout/"Learning Agent Execution for KV-Cache Management") | arXiv:2608.14624 (Aug 2026) | C — single-source preprint |+| Session/agent-aware scheduling reduces multi-agent serving latency vs. per-request scheduling | Agentix, arXiv:2603.18897 (Mar 2026) | C |+| Congestion-based concurrency control improves agentic batch-inference throughput vs. naive continuous batching | CONCUR, arXiv:2601.22705 (Jan 2026) | C |+| Anthropic prompt caching is strictly prefix-based (tools→system→static→variable ordering); a named production case moved 7%→84% cache-hit rate, ~59% cost cut, by reordering | Cross-checked across 3+ independent write-ups of Anthropic's documented API contract, plus a named case (ProjectDiscovery) | B |+| Rule-based LLM routers add <1ms, embedding-based ~5ms, ML-classifier 50-100ms overhead — negligible next to 500-2000ms LLM latency | Vendor/blog routing-engineering guides (2026) | C |+| Qdrant shipped 4-bit TurboQuant quantization (Google Research); Weaviate shipped tenant-aware Rotational Quantization — both new 2026 compression points Ruflo's HNSW/quantization stack doesn't target | Qdrant official docs/benchmarks (A); Weaviate release notes via secondary aggregation (B) | A/B |+| No mainstream agent framework (LangGraph, Microsoft Agent Framework, CrewAI, OpenAI Agents SDK) has true Temporal-style durable execution with external-signal recovery — a shared, industry-wide gap, not a Ruflo-specific one | Diagrid critiques of LangGraph/MS Agent Framework/CrewAI/Google ADK/Strands, cross-checked against each vendor's own docs | B |++Full source list and per-claim grading detail: see tonight's research transcript (deep researcher + competitor analyst roles); condensed here per the 1500-word gist budget.++## Ruflo Current Capability++The MoE routing surface (`v3/@claude-flow/neural/src/moe-router.ts`) implements an 8-expert two-layer gating network (`Linear(384,128)+ReLU → Linear(128,8)+Softmax`) with online REINFORCE weight updates via `updateExpertWeights(expert, reward)`. It is called from production only for read-only routing (`v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts:4066`, the `memory search --mode moe` MCP tool path) — `updateExpertWeights()` itself has **zero production callers anywhere in `v3/`** (grep-confirmed, independently re-confirmed by tonight's adversarial critic). This matches recent nights' "correct-but-currently-dormant" pattern (cf. PR #3243's `AgentPool` fix). CLAUDE.md documents "MoE Gate ... converges — confidence 0.13→0.88" as a measured result; that convergence claim is about the *mechanism working when driven*, and is unaffected by tonight's fix (which restores a regularizer that only matters once real reward-driven updates are wired to a production caller — itself a candidate for a future `intelligence`/`swarm` night, see Recommended Next Steps).++Closed ground from recent performance nights (not rediscovered tonight): HNSW `efSearch`/recall tuning (2026-08-15, REJECTED), HNSW product-quantization dispatch (2026-08-25, ACCEPTED), dead `diskann-backend.ts` removal (2026-08-30), `cli-cold-start.bench.ts`'s fake `setTimeout`-based measurement (2026-09-05), MMR eager-tokenization in `smart-retrieval.ts` (2026-09-10, 5.88x measured speedup).++## Competitor Comparison++| Framework/System | Performance-relevant capability | Primary source | Grade |+|---|---|---|---|+| LangGraph | v1.0 (Oct 2025) ships durable-execution modes (`exit`/`async`/`sync`) trading checkpoint safety for latency; v1.2 (May 2026) added per-node timeouts | Official LangGraph docs/changelog | A |+| Microsoft Agent Framework (GA Apr 2026, AutoGen successor) | Checkpointing at end of each "superstep," pluggable storage w/ partition-key design for scale — but same "not true durable execution" critique as LangGraph applies | GitHub microsoft/agent-framework docs (A); Diagrid critique (B) | A/B |+| CrewAI | Role-based abstraction has real, disclosed token overhead; ChromaDB→LanceDB memory migration still has documented concurrent-writer crash reports | CrewAI GitHub issues #854/#1388 (real reported behavior) | A/B |+| OpenAI Agents SDK | Agent Builder/Evals sunsetting 2026-11-30 (announced 2026-06-03, read-only from Oct 31) — confirms and sharpens prior nights' finding; tracing on-by-default, guardrails default to parallel execution for latency | OpenAI's own deprecations page | A |+| Qdrant | 4-bit TurboQuant quantization (v1.18), 2x denser than scalar quantization at comparable recall — a genuine open gap for Ruflo (team has RaBitQ/Int8 expertise, hasn't targeted this compression point) | Qdrant official docs | A |+| Vespa | Continuous automated perf-regression suite on every release, ~4.9x speedup in a recent tensor-retrieval improvement — unusually transparent methodology for this space | Vespa benchmarks page / newsletter | A |++Synthesis: Ruflo's caveated HNSW numbers (1.9x–4.7x, honestly bounded by a documented crossover) remain more rigorous than most competitor claims in this space right now — a large fraction of "framework X benchmark 2026" search results are ungrounded SEO content (graded C, explicitly flagged rather than laundered as fact by tonight's competitor analyst). The durable-execution gap is real but shared industry-wide, not urgent to chase solo; the 4-bit/tenant-aware quantization gap (Qdrant/Weaviate) is a genuine, Ruflo-specific opportunity worth a future night.++## Hypothesis++> Given `MoERouter.route()` (`v3/@claude-flow/neural/src/moe-router.ts`) computing a Switch-Transformer-style load-balance loss `L = NUM_EXPERTS · loadBalanceCoef · Σᵢ(fᵢ·Pᵢ)` (fᵢ = historical per-expert load fraction, Pᵢ = softmax routing probability) on every call and returning it in `RoutingResult.loadBalanceLoss`, when `updateExpertWeights()` is changed to also compute this loss's analytic gradient w.r.t. the pre-softmax logits (`∂L/∂logit_k = NUM_EXPERTS·coef·P_k·(f_k − Σᵢ fᵢPᵢ)`, using a per-route() fraction snapshot cached specifically to avoid drift from intervening calls) and subtract it from the existing REINFORCE ascent gradient, then a reward=0 update on a routing history skewed toward one expert should measurably reduce that expert's future routing probability — relative to baseline, where a reward=0 call is a complete no-op (the REINFORCE gradient is identically zero, and no other gradient source exists) — subject to:+> 1. `loadBalanceCoef = 0` (explicit opt-out) keeps the update byte-for-byte the same no-op as today;+> 2. a genuine nonzero reward signal still dominates the update (additive, not replacing, REINFORCE);+> 3. all existing neural-package tests remain green;+> 4. fully deterministic, $0 evaluation cost, no LLM calls.++Frozen before evaluation; not modified after seeing results. **Selection note (STEP 3.2 override):** the deep researcher's own top-scored candidate ("instrument the already-wired Anthropic prompt cache," score 4.55) tied this candidate's score (4.55) under the same rubric, but requires live `ANTHROPIC_API_KEY` calls to demonstrate `cache_read_input_tokens > 0` — external network/cost/availability dependency, less robust to evaluate deterministically tonight. This candidate (from the architecture-reviewer role) matches the closed-ground "computed-but-discarded value" pattern (cf. PQ-dispatch #3094, HybridBackend weights #3119, MMR embedding-cosine #3169) with a proven track record of clean, fully-local, $0 evaluability — selected on that basis, not a higher raw score.++## Benchmarks / Evaluation++**evaluated: accepted (ACCEPT-scoped — see caveat below).** Real evaluator: Vitest 4.1.8, deterministic, $0, zero LLM calls. New file: `v3/@claude-flow/neural/__tests__/moe-router-load-balance.test.ts` (4 tests).++**Baseline vs. candidate, isolated via `git stash` of just the source file (test file kept):** the primary discriminating test fails against real baseline — `expected [0.1266,...] to not deeply equal [0.1266,...]` (byte-identical pre/post probability vectors, confirming reward=0 was a true no-op) — and passes against candidate. The other 3 tests pass both ways (they test orthogonal behavior: explicit opt-out via `loadBalanceCoef:0`, genuine-reward-still-works, and a basic shape sanity check) — not fix-dependent, confirming they aren't spuriously coupled. Re-run 25+ times (including by the independent critic) with **zero flakiness** despite `xavierInit()`'s unseeded `Math.random()` — the test's fixed near-zero-magnitude embedding keeps initial logits near-uniform regardless of the random draw, empirically confirmed stable.++Full `@claude-flow/neural` package suite: **136/136 passing** (132 pre-existing + 4 new), 0 regressions. `tsc --noEmit`: 0 errors.++**Independent adversarial critique (STEP 10, separate subagent, no authoring context):** verdict **CONFIRMED**. Independently re-derived the softmax-Jacobian gradient by hand and confirmed it matches the implementation exactly, including the ascent-vs-minimize sign convention; verified `lastLoadBalanceFractions` can never be read before a `route()` call (guarded by the pre-existing null-check on `lastProbs`); independently reproduced the stash-isolated baseline-fail/candidate-pass result; ran the full suite and typecheck itself; grepped the whole repo and confirmed `updateExpertWeights()` has zero production callers (while `route()` itself is live in production) — the scoping caveat reflected in this ACCEPT. One non-blocking cosmetic nit (a per-call `Float32Array` allocation inconsistent with the class's pre-allocated-buffer convention) — fixed same session (hoisted to a reused instance field), re-verified 136/136 green and clean typecheck after the fix.++## Darwin Results++Skipped — confirmed via `npx [email protected] harness darwin --help`: the real interface evolves routing/topology/prompt/memory/tool/tier/context/coordination genome *parameters* against a fitness-scored corpus. Tonight's fix restores an already-decided, already-parameterized mechanism (the Switch-Transformer aux loss, with its own pre-existing `loadBalanceCoef` default) to actually functioning — it isn't a search over a new parameter space. Same skip class as most recent nights (#3110, #3160, #3184, #3221, #3243, #3266, #3302).++## Flywheel Evidence++No `.claude-flow/flywheel/` state or signed `@metaharness/flywheel` bundle exists in this repo (confirmed via `npx ruvector harness flywheel --help`: real `verify`/`gate` interface exists but targets a replay bundle this deterministic code-correctness fix doesn't produce). Evidence retained as: the 4 new discriminating tests, this gist, the linked issue, the stash-isolated baseline-fails/candidate-passes comparison (reproduced independently by the critic), and the full adversarial critique transcript — consistent with every accepted dream-cycle night since 2026-08-18. Classified: OBSERVATION (`updateExpertWeights()` never referenced `loadBalanceLoss`/`loadBalanceCoef`, confirmed via direct code read + grep) / MEASUREMENT (baseline fails the discriminating assertion for the predicted mechanical reason, candidate passes, 132/132→136/136 pre-existing tests unchanged) / DECISION (ship as a scoped, additive gradient-wiring fix) / REJECTION (none this round).++## Reward Hack Check++No standalone reward-hack CLI reachable this session (`npx ruvector harness --help` lists `status`/`route`/`flywheel`/`darwin`, no generic diff/benchmark scanner — consistent with every recent night's own note). Manual checklist, independently re-verified by the adversarial critic: no existing test weakened (new file only, existing 132 untouched and re-verified green); no gold/expected data touched (none exists on this code path); no cherry-picking (full suite reported both ways); no seed manipulation (test is specifically designed to be robust to `xavierInit()`'s unseeded randomness, confirmed via 25+ repeated runs); zero cost. The unrelated `v3/pnpm-lock.yaml` diff in the working tree (from this session's fresh `pnpm install`) is lockfile metadata noise, not part of this candidate.++## Security Review++Not security-sensitive: pure in-process numeric array arithmetic on an already-validated 384-dim embedding vector; no I/O, network, credential, or filesystem surface touched. Independently confirmed by the adversarial critic. Checked for NaN/Infinity paths (fractions bounded [0,1], probs are valid softmax output with a `+1e-8` stability guard — no division in the new code at all) and for the balance term dominating a genuine reward signal at default config (bounded ≤ `coef·NUM_EXPERTS = 0.08` at default `coef=0.01`, vs. REINFORCE's ≤1 magnitude — won't realistically dominate).++## SOTA Proof & Witness++| Field | Value |+|---|---|+| Session commit | `2602b642d92234c710ffbe96bfb33007d481ceab` |+| Gist SHA-256 (pre-witness content) | `34faf6710b82b1477af9b6088329dedcff622ad90f22f37728c9083f928a0e21` |+| Witness stamp | `5e719b96e5bb13905960609266cebaf61d5979dc0b7c5f105f953eee30f4599b` |++Verifier procedure: fetch `docs/dream-cycle/dream-gist-2026-09-15.md` from this branch, strip the witness table's filled values back to `PENDING`, SHA-256 it, concatenate with the session commit above, SHA-256 again — result must equal the witness stamp.++## Scan Findings: security++`v3/@claude-flow/cli/src/mcp-tools/http-fetch-tools.ts`'s `validateUrl()` (line 46) blocks private/loopback/link-local addresses by string-matching the URL's literal hostname (IPv4 regex, `localhost`, IPv6 ULA/link-local prefixes) but never resolves DNS, and `fetch()` is called with the default `redirect: 'follow'` (deliberately kept, per an inline comment), with validation running exactly once pre-connection. This is a TOCTOU SSRF bypass of the tool's own documented "DEFAULT-REFUSES private addresses + loopback" contract: (1) an attacker-registered public hostname that resolves to `127.0.0.1`/`169.254.169.254` at fetch time passes the string check but connects internally (DNS rebinding); (2) a remote server can 302-redirect a validated request to an internal address, which `fetch()` follows without re-validation. `http_fetch` is wired into agent-invokable ops-bench tooling (ADR-164 §5.1.8), so this is reachable via normal tool use. Evidence grade: A-confidence in the underlying SSRF/DNS-rebinding/redirect-revalidation technique (well-established industry pattern per OWASP's SSRF Prevention Cheat Sheet approach), B for the specific "this exact agentic pattern" framing (no OWASP.org page found naming it precisely). Not selected as tonight's candidate (SCAN surface, lighter-weight); strong candidate for a future `security` DEEP night — fix is well-established (resolve-then-connect with IP re-validation per redirect hop).++## Scan Findings: hive-mind++Two previously-flagged gaps confirmed still live tonight (re-verified against current code, not assumed from prior nights' notes): (1) the "consensus-strategy-discard" bug flagged 2026-09-10 — `hive-mind_init` writes a 5-way strategy to `state.consensusStrategy` (`hive-mind-tools.ts:23-28,367`), but `hive-mind_consensus` reads a separate, narrower per-call `strategy` param instead (`hive-mind-tools.ts:619`, feeding `calculateRequiredVotes()`/`tryResolveProposal()`) — `consensusStrategy` never reaches vote resolution (grep-confirmed: only 4 refs, all in init/status display code), so `gossip`/`crdt` init-time strategy labels have zero corresponding resolution branch. (2) `byzantine.ts`'s `handleCommit()` dead-PBFT-path (flagged 2026-08-24) — still only reachable via direct unit-test invocation, no production transport wiring (grep-confirmed). Both are the same class of gap: a config surface structurally disconnected from the code path that actually decides outcomes. Recommendation: a future `hive-mind` DEEP night fixing both together (they both touch `calculateRequiredVotes`/`tryResolveProposal`) rather than separately.++## Competitors Reviewed++LangGraph, Microsoft Agent Framework/AutoGen, CrewAI, OpenAI Agents SDK (mandated floor); Qdrant, Weaviate, Milvus, LanceDB, Vespa (memory/vector-layer comparison, performance-scan relevant); OWASP SSRF Prevention Cheat Sheet pattern (security-scan comparison).++## Additional candidates surfaced but not selected tonight (STEP 3.2)++Scored under `0.25·Ruflo_fit + 0.20·testability + 0.20·measurability + 0.15·production_value + 0.10·novelty + 0.10·reviewability` (1-5 each):++1. **[4.55] Instrument the already-wired Anthropic prompt cache in `agent_execute` Tier-3** (`agent-execute-core.ts:263-300`) — `cache_control:ephemeral` is set but `cache_read_input_tokens`/`cache_creation_input_tokens` from the API response are discarded, so there's zero visibility into whether the caching is working. Requires live API calls to evaluate; see Hypothesis section for why this wasn't selected tonight despite the tied score.+2. **[4.40] Redundant `estimateSize()` recomputation in `CacheManager.delete()`/`evictLRU()`** (`v3/@claude-flow/memory/src/cache-manager.ts`) — re-serializes payloads already sized at `set()` time, on every eviction.+3. **[4.30] Orphaned persistent embedding cache in 3 of 4 `EmbeddingService` providers** (`v3/@claude-flow/embeddings/src/embedding-service.ts`) — `checkPersistentCache()`/`storePersistentCache()` defined, zero callers in `OpenAIEmbeddingService`/`TransformersEmbeddingService`/`AgenticFlowEmbeddingService` (the default `'auto'`-selected `RvfEmbeddingService` has its own working cache, unaffected).+4. **[4.25] `MessageBus.processQueues()` fixed 10ms-interval polling vs. event-driven delivery** (`v3/@claude-flow/swarm/src/message-bus.ts`) — every message hop waits for the next tick; a permanent 100Hz timer runs even on an idle bus. Larger/riskier patch (must preserve batching/priority/backpressure semantics), scoped as demonstrate-tonight/design-later.+5. **[4.10] Cross-process persistence for `task-embedder.ts`'s routing cache** — cold on effectively every CLI/`hook-handler.cjs` invocation given Ruflo's own prescribed short-lived-process workflow. Largest potential win, also the largest correctness-risk surface (concurrent-process writes, staleness) — design-only tonight.++Also from the architecture-reviewer role, not selected: `UnifiedSwarmCoordinator.waitForTaskCompletion()`/`waitForQueuedTask()` busy-poll `state.tasks` every 100ms via `setInterval` despite the class already emitting `task.completed`/`task.failed` events nothing subscribes to (`unified-coordinator.ts:1278-1365`) — a real latency/CPU-overhead finding (score ≈4.45 by the same rubric), close second to tonight's selection; and a minor `CacheManager.clear()` telemetry bug (`previousSize` always reports 0 — one-line fix, flagged as trivial/not worth a full candidate slot).++## Recommended Next Steps++1. **Merge tonight's linked draft PR** (human review required) — restores the MoE gate's load-balance regularizer with a discriminating, non-flaky test suite.+2. **Wire a real production caller to `updateExpertWeights()`** — tonight's fix is correct but currently dormant (no production code path calls it); pairs naturally with a future `intelligence`/`swarm` night that also revisits `priorDecay` (flagged 2026-09-12, still dead) in the same "implemented but never wired" family.+3. **`UnifiedSwarmCoordinator` event-driven task-completion wait** — close second candidate tonight (busy-poll → subscribe to already-emitted `task.completed`/`task.failed` events); good target for next `performance` or `swarm` night.+4. **`http_fetch` SSRF hardening** (security scan finding) — resolve-then-connect with per-redirect-hop IP re-validation; concrete, well-scoped future `security` night candidate.+5. **`hive-mind` consensus-strategy dispatch + byzantine dead-PBFT-path** (hive-mind scan finding) — fix together in a future `hive-mind` DEEP night, both touch the same tally-resolution functions.diff --git a/v3/@claude-flow/neural/__tests__/moe-router-load-balance.test.ts b/v3/@claude-flow/neural/__tests__/moe-router-load-balance.test.tsnew file mode 100644index 0000000000..fa003a45b1--- /dev/null+++ b/v3/@claude-flow/neural/__tests__/moe-router-load-balance.test.ts@@ -0,0 +1,230 @@+/**+ * MoE Router — load-balance auxiliary-loss gradient tests+ *+ * MoERouter.route() computes a Switch-Transformer-style load-balance loss+ * (computeLoadBalanceLoss()) on every call and returns it in RoutingResult,+ * but updateExpertWeights() — the only method that mutates the gating+ * network's weights — never read loadBalanceLoss/loadBalanceCoef anywhere+ * in its REINFORCE gradient computation. The regularizer the module's own+ * header claims ("Load balancing with auxiliary loss") had zero actual+ * effect on training.+ *+ * These tests are discriminating: against the pre-fix source, a call to+ * updateExpertWeights(expert, 0) is a pure no-op (reward=0 zeroes the+ * REINFORCE gradient entirely, and no other gradient source existed), so+ * output logits/probabilities for a fixed input are byte-identical before+ * and after. Against the fix, the load-balance term supplies a nonzero+ * gradient even at reward=0, moving weights away from an over-represented+ * expert.+ *+ * Review round 2 additions (caught real gaps in round 1): a temperature+ * derivative the analytic gradient omitted (exact only at temperature=1),+ * and a pre-existing loadWeights() bug — totalRoutings was never persisted+ * and got reconstructed as sum(routingCounts), which only equals the real+ * call count when topK===1 — that silently corrupts this fix's fractions+ * after any save/load cycle at the default topK=2.+ */++import { describe, it, expect, afterEach } from 'vitest';+import { existsSync, mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { MoERouter, INPUT_DIM, NUM_EXPERTS } from '../src/moe-router.js';++// Fixed, deterministic embedding — small uniform magnitude keeps initial+// logits near zero (softmax near-uniform), which keeps the discriminating+// expert's probability safely away from the 0/1 boundary regardless of the+// specific (random) Xavier initialization drawn for a given test run.+function fixedEmbedding(): Float32Array {+ const arr = new Float32Array(INPUT_DIM);+ arr.fill(0.01);+ return arr;+}++describe('MoERouter load-balance gradient wiring', () => {+ it('reward=0 update on a skewed routing history changes gate output (was a no-op)', () => {+ const router = new MoERouter({+ enableNoise: false, // deterministic forward pass across repeated route() calls+ topK: 1,+ loadBalanceCoef: 1.0, // amplified for a clearly measurable effect+ learningRate: 0.1,+ autoSaveInterval: 0, // no disk writes from this test+ });++ const input = fixedEmbedding();++ // Warm up: repeatedly route the SAME fixed input with noise disabled.+ // Since weights are unchanged across these calls (no update yet), the+ // same top-1 expert is selected deterministically every time, building+ // a maximally skewed routingCounts history toward that one expert.+ let last = router.route(input);+ for (let i = 0; i < 9; i++) {+ last = router.route(input);+ }+ const dominantExpert = last.experts[0].index;+ const probsBefore = Array.from(last.allScores);++ // Sanity: the load-balance loss the (pre-existing) computation produces+ // is genuinely nonzero once history is skewed — confirms the discarded+ // value itself was real, not a red herring.+ expect(last.loadBalanceLoss).toBeGreaterThan(0);++ // Reward=0: the REINFORCE term contributes nothing (clampedReward=0+ // zeroes every entry of the reward-based gradient before the balance+ // term is added). Any change below is attributable to the load-balance+ // gradient alone.+ router.updateExpertWeights(dominantExpert, 0);++ // Re-route the identical input (noise still disabled) — any difference+ // in output proves the reward=0 update had a real effect.+ const after = router.route(input);+ const probsAfter = Array.from(after.allScores);++ expect(probsAfter).not.toEqual(probsBefore);+ // Directional check matching the Switch-Transformer intuition: weight+ // is pushed away from the historically over-represented expert.+ expect(probsAfter[dominantExpert]).toBeLessThan(probsBefore[dominantExpert]);+ });++ it('loadBalanceCoef=0 (explicit opt-out) keeps reward=0 update a true no-op', () => {+ const router = new MoERouter({+ enableNoise: false,+ topK: 1,+ loadBalanceCoef: 0,+ learningRate: 0.1,+ autoSaveInterval: 0,+ });++ const input = fixedEmbedding();+ let last = router.route(input);+ for (let i = 0; i < 9; i++) {+ last = router.route(input);+ }+ const dominantExpert = last.experts[0].index;+ const probsBefore = Array.from(last.allScores);++ expect(last.loadBalanceLoss).toBe(0); // coef=0 => computeLoadBalanceLoss() scales to 0++ router.updateExpertWeights(dominantExpert, 0);++ const after = router.route(input);+ expect(Array.from(after.allScores)).toEqual(probsBefore);+ });++ it('a genuine reward signal still dominates the update (additive, not replaced)', () => {+ const router = new MoERouter({+ enableNoise: false,+ topK: 1,+ loadBalanceCoef: 0.01, // default magnitude+ learningRate: 0.1,+ autoSaveInterval: 0,+ });++ const input = fixedEmbedding();+ const first = router.route(input);+ const chosen = first.experts[0].index;++ // Strong positive reward for the chosen expert should still increase+ // its own probability on a repeat route(), not be swamped by the+ // (default-magnitude) balance term pulling the opposite direction.+ router.updateExpertWeights(chosen, 1);+ const after = router.route(input);++ expect(after.allScores[chosen]).toBeGreaterThan(first.allScores[chosen]);+ });++ it('routing result shape is correct at default topK=2', () => {+ const router = new MoERouter({ enableNoise: false, topK: 2, autoSaveInterval: 0 });+ const input = fixedEmbedding();+ for (let i = 0; i < 5; i++) router.route(input);+ const result = router.route(input);+ expect(result.allScores).toHaveLength(NUM_EXPERTS);+ expect(result.experts).toHaveLength(2);+ expect(result.loadBalanceLoss).toBeGreaterThanOrEqual(0);+ });++ describe('save/load persistence', () => {+ let tmpDir: string;++ afterEach(() => {+ if (tmpDir && existsSync(tmpDir)) rmSync(tmpDir, { recursive: true, force: true });+ });++ it('round-trips the real totalRoutings, not sum(routingCounts) (topK=2 default)', async () => {+ tmpDir = mkdtempSync(join(tmpdir(), 'moe-router-persist-'));+ const weightsPath = join(tmpDir, 'weights.json');++ const router = new MoERouter({ enableNoise: false, topK: 2, weightsPath, autoSaveInterval: 0 });+ const input = fixedEmbedding();+ for (let i = 0; i < 5; i++) router.route(input);++ // topK=2: 5 calls increment routingCounts by 2 each (sum=10) but+ // totalRoutings by exactly 1 each (=5) -- a discriminating pair.+ const beforeSave = router.getLoadBalance();+ expect(beforeSave.totalRoutings).toBe(5);+ const countSum = Object.values(beforeSave.routingCounts).reduce((a, b) => a + b, 0);+ expect(countSum).toBe(10);++ expect(await router.saveWeights()).toBe(true);++ const reloaded = new MoERouter({ enableNoise: false, topK: 2, weightsPath, autoSaveInterval: 0 });+ expect(await reloaded.loadWeights()).toBe(true);++ // Before the fix, loadWeights() reconstructed totalRoutings as+ // sum(routingCounts)=10 instead of the real 5.+ expect(reloaded.getLoadBalance().totalRoutings).toBe(5);+ });++ it('reload preserves the load-balance loss magnitude (was silently halved by the totalRoutings bug)', async () => {+ tmpDir = mkdtempSync(join(tmpdir(), 'moe-router-persist-'));+ const weightsPath = join(tmpDir, 'weights.json');++ const router = new MoERouter({ enableNoise: false, topK: 2, weightsPath, autoSaveInterval: 0 });+ const input = fixedEmbedding();+ for (let i = 0; i < 5; i++) router.route(input);+ const beforeLoss = router.route(input).loadBalanceLoss;++ expect(await router.saveWeights()).toBe(true);++ const reloaded = new MoERouter({ enableNoise: false, topK: 2, weightsPath, autoSaveInterval: 0 });+ await reloaded.loadWeights();+ const afterLoss = reloaded.route(input).loadBalanceLoss;++ // Before the fix: reconstructed totalRoutings=10 (should be 5) halved+ // every fraction, and thus halved this loss, on the very next route().+ expect(afterLoss).toBeCloseTo(beforeLoss, 5);+ });+ });++ it('balance gradient still pushes the correct direction at a non-default temperature', () => {+ // The analytic gradient's 1/temperature factor only matters when+ // temperature !== 1 (the default). This is the same reward=0 /+ // skewed-history construction as the primary test above, just at+ // temperature=2 -- discriminating against the version of the fix that+ // omitted the 1/T term only insofar as it proves the corrected term+ // still produces the intended, correctly-signed effect (the omitted+ // constant-factor bug wouldn't flip the sign, only the magnitude, so+ // this is a real but coarser check than the primary no-op/effect test).+ const router = new MoERouter({+ enableNoise: false,+ topK: 1,+ temperature: 2,+ loadBalanceCoef: 1.0,+ learningRate: 0.1,+ autoSaveInterval: 0,+ });++ const input = fixedEmbedding();+ let last = router.route(input);+ for (let i = 0; i < 9; i++) {+ last = router.route(input);+ }+ const dominantExpert = last.experts[0].index;+ const probBefore = last.allScores[dominantExpert];++ router.updateExpertWeights(dominantExpert, 0);+ const after = router.route(input);++ expect(after.allScores[dominantExpert]).toBeLessThan(probBefore);+ });+});diff --git a/v3/@claude-flow/neural/src/moe-router.ts b/v3/@claude-flow/neural/src/moe-router.tsindex 0756a25208..2a819b2221 100644--- a/v3/@claude-flow/neural/src/moe-router.ts+++ b/v3/@claude-flow/neural/src/moe-router.ts@@ -138,6 +138,11 @@ interface PersistedModel {updateCount: number;routingCounts: number[];avgReward: number;+ // Real call count of route(), distinct from sum(routingCounts) whenever+ // topK > 1 (each route() call increments topK routingCounts entries but+ // totalRoutings by exactly 1). Optional for backward compatibility with+ // model files saved before this field existed.+ totalRoutings?: number;};metadata: {savedAt: string;@@ -326,6 +331,15 @@ export class MoERouter {private lastHiddenActivated: Float32Array | null = null;private lastProbs: Float32Array | null = null;private lastSelectedExperts: number[] = [];+ // Per-expert historical load fractions (routingCounts / totalRoutings) at+ // the moment of the most recent route() call, i.e. the exact snapshot+ // computeLoadBalanceLoss() used to produce the loadBalanceLoss it returned.+ // Cached so updateExpertWeights() can apply the matching gradient even if+ // routingCounts has advanced further by the time it's called. Only ever+ // read after a route() call has populated lastProbs (guarded below), so+ // pre-allocating here (matching the other pre-allocated buffers above) is+ // safe even though it holds zeros until the first route().+ private lastLoadBalanceFractions: Float32Array = new Float32Array(NUM_EXPERTS);constructor(config: Partial<MoERouterConfig> = {}) {this.config = { ...DEFAULT_CONFIG, ...config };@@ -406,8 +420,17 @@ export class MoERouter {// Select top-k expertsconst expertIndices = this.selectTopK(this.probs, this.config.topK);- // Compute load balance loss+ // Compute load balance loss (and cache the fraction snapshot it used, so+ // updateExpertWeights() can apply a gradient consistent with this value+ // rather than a possibly-drifted later routingCounts state)const loadBalanceLoss = this.computeLoadBalanceLoss();+ if (this.totalRoutings > 0) {+ for (let i = 0; i < NUM_EXPERTS; i++) {+ this.lastLoadBalanceFractions[i] = this.routingCounts[i] / this.totalRoutings;+ }+ } else {+ this.lastLoadBalanceFractions.fill(0);+ }// Compute entropyconst routingEntropy = entropy(this.probs);@@ -487,6 +510,34 @@ export class MoERouter {}}+ // Load-balance auxiliary gradient (Switch Transformer style), added on+ // top of the REINFORCE reward gradient above. computeLoadBalanceLoss()+ // computes L = NUM_EXPERTS * coef * sum_i(f_i * P_i), where f_i is the+ // (fixed, non-differentiable) historical load fraction cached by the+ // most recent route() call and P_i = softmax(logit/T)_i (T = temperature,+ // see softmax()). Differentiating through the temperature-scaled softmax+ // gives dL/dlogit_k = (1/T) * NUM_EXPERTS*coef*P_k*(f_k - S), S =+ // sum_i(f_i*P_i) -- an earlier version of this fix omitted the 1/T+ // factor, exact only at the default temperature=1 (caught in review).+ // This was computed every route() call and returned in RoutingResult,+ // but never fed back into a weight update, so the regularizer had zero+ // actual effect. Subtracted (not added) because this method performs+ // gradient ASCENT on reward (W += lr*grad) while the balance term is a+ // loss to MINIMIZE (W -= lr*dL/dW).+ if (this.config.loadBalanceCoef !== 0) {+ const fractions = this.lastLoadBalanceFractions;+ const invTemperature = 1 / this.config.temperature;+ let weightedProbSum = 0;+ for (let i = 0; i < NUM_EXPERTS; i++) {+ weightedProbSum += fractions[i] * this.lastProbs[i];+ }+ for (let k = 0; k < NUM_EXPERTS; k++) {+ const balanceGrad =+ invTemperature * NUM_EXPERTS * this.lastProbs[k] * (fractions[k] - weightedProbSum);+ this.gradb2[k] -= this.config.loadBalanceCoef * balanceGrad;+ }+ }+// Gradient w.r.t. W2: outer product of gradb2 and hiddenActivatedfor (let i = 0; i < NUM_EXPERTS; i++) {const rowOffset = i * HIDDEN_DIM;@@ -643,7 +694,15 @@ export class MoERouter {this.routingCounts = new Float32Array(model.stats.routingCounts || new Array(NUM_EXPERTS).fill(0));- this.totalRoutings = this.routingCounts.reduce((a, b) => a + b, 0);+ // Prefer the persisted real call count. sum(routingCounts) only equals+ // it when topK === 1 (each route() call increments topK entries but+ // totalRoutings by exactly 1) -- falling back to that sum is only for+ // reading model files saved before totalRoutings was persisted, and is+ // an approximation for any topK > 1 history in that older file.+ this.totalRoutings =+ typeof model.stats.totalRoutings === 'number'+ ? model.stats.totalRoutings+ : this.routingCounts.reduce((a, b) => a + b, 0);return true;} catch (err) {@@ -693,6 +752,7 @@ export class MoERouter {updateCount: this.updateCount,routingCounts: Array.from(this.routingCounts),avgReward: this.avgReward,+ totalRoutings: this.totalRoutings,},metadata: {savedAt: new Date().toISOString(),