π 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
docs(ADR-060): remaining bugs and wiring fixes post-v3.5.3
rUv36383cfa5162
diff --git a/v3/implementation/adrs/ADR-060-remaining-bugs-2026-03.md b/v3/implementation/adrs/ADR-060-remaining-bugs-2026-03.mdnew file mode 100644index 0000000000..30b0b91855--- /dev/null+++ b/v3/implementation/adrs/ADR-060-remaining-bugs-2026-03.md@@ -0,0 +1,203 @@+# ADR-060: Remaining Bug & Wiring Fixes β March 2026++**Status:** Accepted+**Date:** 2026-03-05+**Author:** claude-flow+**Supersedes:** Remaining items from ADR-059++## Context++ADR-059 triaged 30 open issues and 11 were fixed in v3.5.3 (PR #1297, #1298). This ADR covers the 19 remaining open issues plus 5 additional issues discovered during the fix cycle that were not in the original triage. Total: 24 open items.++## Priority Levels++| Level | Meaning | SLA |+|-------|---------|-----|+| **P0 β Critical** | Security risk, data loss, or blocks all users | Fix within 24h |+| **P1 β High** | Core functionality broken for a platform or major feature | Fix within 1 week |+| **P2 β Medium** | Incorrect behavior, cosmetic UX bugs, missing config | Fix within 2 weeks |+| **P3 β Low** | Enhancements, polish, feature requests | Next release cycle |++---++## P0 β Critical++### 1. Windows: daemon and memory init silently fail (#1282)+- **Impact:** `init --start-all` reports success but creates nothing on Windows. Zero functionality for Windows users.+- **Root cause:** `child_process.spawn` uses POSIX-only flags (`detached`, `stdio: 'ignore'`). Windows needs `shell: true` and `windowsHide: true`.+- **Fix:** Audit all spawn calls for platform-specific flags; add Windows CI matrix.+- **Effort:** Medium β requires platform detection in daemon.ts, memory-initializer.ts, and process manager.++---++## P1 β High++### 2. hook-handler.cjs ignores stdin β all hook data silently lost (#1211)+- **Impact:** Every Claude Code hook sends structured JSON via stdin, but hook-handler.cjs never reads it. The entire learning, routing, and intelligence pipeline receives no input data.+- **Root cause:** The handler reads `process.argv` but never `process.stdin`.+- **Fix:** Add stdin buffering: `let data = ''; process.stdin.on('data', c => data += c); process.stdin.on('end', () => { /* parse JSON, dispatch */ })`.+- **Effort:** Small β single file fix with high leverage.+- **Note:** This is the single highest-leverage fix remaining. Without it, all hooks are effectively no-ops.++### 3. macOS: daemon dies immediately after start (#1283)+- **Impact:** Daemon always shows STOPPED on macOS. Background workers, learning hooks, and neural training are all non-functional.+- **Root cause:** Likely PID file race condition or signal handling (SIGHUP on terminal close).+- **Fix:** Add `nohup` wrapper or launchd plist support. Write PID file after fork, not before.+- **Effort:** Medium.++### 4. auto-memory-hook.mjs fails to resolve @claude-flow/memory (#1287)+- **Impact:** Auto-memory import fails when installed as nested dependency (npx, monorepos). Memory persistence across sessions is broken.+- **Root cause:** ES module import resolution doesn't traverse node_modules correctly from hook context.+- **Fix:** Use `createRequire(import.meta.url)` for CommonJS-style resolution, or bundle the memory module inline.+- **Effort:** Small.++### 5. Settings-generator missing 13 hooks, 9 env vars, memory config (#1291)+- **Impact:** Fresh installs get incomplete configuration. 13 hooks never fire, 9 env vars undocumented.+- **Fix:** Reconcile `settings-generator.ts` against the actual hooks registry in `hooks.ts`. Add missing hook entries and env var documentation.+- **Effort:** Medium β requires careful audit of all hook types vs generated settings.++### 6. recordFeedback() exposed by AgentDB v3 has zero callers (#1209)+- **Impact:** AgentDB's feedback/reinforcement learning API exists but is never invoked. The learning loop (RETRIEVE β JUDGE β DISTILL β CONSOLIDATE) has no JUDGE step at runtime.+- **Fix:** Wire `recordFeedback()` calls into `post-task` and `post-edit` hooks when `--success` flag is provided.+- **Effort:** Small β add calls in hook handlers.++### 7. MemoryGraph class exported but never instantiated (#1214)+- **Impact:** Graph-based relationship tracking (agentβtask, fileβpattern) is dead code. Semantic search misses relationship context.+- **Fix:** Instantiate MemoryGraph in memory-initializer alongside ControllerRegistry.+- **Effort:** Small.++---++## P2 β Medium++### 8. `workflow run` and `task assign` call missing MCP tools (#1281)+- **Impact:** CLI references `workflow_run` and `task_assign` MCP tools that aren't registered.+- **Fix:** Register the missing tools in the MCP server, or remove the dead references.+- **Effort:** Small.++### 9. CacheManager setInterval missing .unref() prevents process exit (#1256)+- **Impact:** CLI process hangs after completion. Users must Ctrl+C to exit.+- **Fix:** Add `.unref()` to all `setInterval` timers in CacheManager.+- **Effort:** Trivial.++### 10. Zero swarms always: `ruflo spawn hive-mind --claude` (#1279)+- **Impact:** Hive-mind spawning returns zero agents. Multi-agent feature is non-functional via CLI.+- **Fix:** Debug agent spawn path β likely missing topology init or agent pool connection.+- **Effort:** Medium.++### 11. MCP server status reports 'Stopped' in stdio mode (#1289)+- **Impact:** `status` command shows STOPPED for a correctly-running stdio-mode MCP server.+- **Fix:** Detect stdio transport mode and report status accordingly.+- **Effort:** Small.++### 12. doctor: disk space check reports wrong capacity percentage (#1288)+- **Impact:** Misleading health check output (bytes vs KB mismatch).+- **Fix:** Fix arithmetic in disk space calculation.+- **Effort:** Trivial.++### 13. SonaTrajectoryService does not use native @ruvector/sona API (#1243)+- **Impact:** SONA neural learning uses a stub. Learning is no-op.+- **Fix:** Wire to actual `@ruvector/sona` package methods.+- **Effort:** Medium.++### 14. Wire AgentMemoryScope 3-scope isolation (#1227)+- **Impact:** Memory operations don't enforce agent/session/global scope isolation.+- **Fix:** Add scope parameter to memory store/retrieve operations.+- **Effort:** Medium.++### 15. Wire SolverBandit Thompson Sampling into hooks_route (#1217)+- **Impact:** Agent selection uses random/round-robin instead of learned multi-armed bandit.+- **Fix:** Integrate SolverBandit into the route hook's agent selection logic.+- **Effort:** Medium.++### 16. npm ECOMPROMISED cache corruption (#1231)+- **Impact:** Some users get ECOMPROMISED errors on `npx ruflo`. Related to the removed preinstall script.+- **Fix:** Document cache clear workaround: `npm cache clean --force`. The preinstall removal in v3.5.3 should prevent new occurrences.+- **Effort:** Trivial β documentation only.++### 17. AgentDB v2 β v3 upgrade (#1207)+- **Impact:** RVF backend migration path not documented for existing users.+- **Fix:** Add migration guide and automatic detection in `init`.+- **Effort:** Medium.++---++## P3 β Low (Next Release Cycle)++### 18. ruvi MCP server: Edge Functions failing (#1276)+- **Impact:** Supabase Edge Functions intermittently fail (cloud-only).+- **Fix:** Add retry logic and auth token refresh.++### 19. Rollback incident templates (#1238, #1262, #1267, #1268)+- **Impact:** Four empty stubs cluttering the issue tracker.+- **Fix:** Close all four. Create a proper incident template if needed.++### 20. Context Optimization Engine β 95-98% compression (#1273)+- **Type:** Feature request.++### 21. Multilingual embedding model support (#1272)+- **Type:** Feature request for Chinese embeddings.++### 22. Ship `dsp` as bin entry (#1236)+- **Type:** Feature request for convenience alias.++### 23. ADR-058: Self-Contained ruflo.rvf Appliance (#1245)+- **Type:** Enhancement. Phase 3-4 implementation exists.++### 24. ADR-057: Replace sql.js with RVF native storage (#1242)+- **Type:** Enhancement. Architectural improvement.++---++## Summary Matrix++| Priority | Count | Key Themes |+|----------|-------|------------|+| **P0** | 1 | Windows platform support |+| **P1** | 6 | Hook stdin, macOS daemon, memory resolution, settings completeness, learning loop wiring |+| **P2** | 10 | CLI UX, MCP tools, neural wiring, memory scoping, cache fix |+| **P3** | 7 | Feature requests, enhancements, housekeeping |+| **Total** | **24** | |++## Recommended Fix Order++### Sprint 1 (This Week) β Unblock Intelligence Pipeline+1. **#1211** hook-handler.cjs stdin β highest leverage, unblocks all learning+2. **#1209** recordFeedback() wiring β completes the JUDGE step+3. **#1214** MemoryGraph instantiation β enables relationship tracking+4. **#1287** auto-memory-hook resolution β fixes memory persistence+5. **#1256** CacheManager .unref() β trivial, fixes UX annoyance++### Sprint 2 (Next Week) β Platform & Configuration+6. **#1282** Windows daemon/memory β unblocks Windows users+7. **#1283** macOS daemon β unblocks macOS users+8. **#1291** Settings-generator completeness β fixes fresh installs+9. **#1281** Missing MCP tools β removes dead references+10. **#1289** MCP stdio status β fixes confusing UX++### Sprint 3 (Following Week) β Neural & Advanced Wiring+11. **#1243** SONA wiring β enables real neural learning+12. **#1227** AgentMemoryScope β enables scope isolation+13. **#1217** SolverBandit β enables learned agent routing+14. **#1279** Hive-mind zero swarms β fixes multi-agent CLI+15. **#1288** Doctor disk space β trivial arithmetic fix++### Backlog+- #1231 (document cache workaround)+- #1207 (migration guide)+- P3 feature requests and housekeeping++## Decision++1. **Immediately** fix #1211 (hook stdin) β this single fix unblocks the entire intelligence pipeline.+2. **Sprint 1** targets the learning loop: stdin β feedback β memory graph β memory resolution.+3. **Sprint 2** targets platform parity (Windows, macOS) and configuration completeness.+4. **Sprint 3** wires the advanced neural and routing features.+5. **P3** items go to backlog for roadmap planning.++## Consequences++- Sprint 1 fixes should ship as **v3.5.4** (patch β learning pipeline).+- Sprint 2 fixes should ship as **v3.6.0** (minor β platform support, new CI matrix).+- Sprint 3 fixes should ship as **v3.7.0** (minor β neural features).+- The 4 rollback incident stubs (#1238, #1262, #1267, #1268) should be closed immediately as housekeeping.