ak setup ships ruflo without native SQLite bindings under npm 12; ak dual run then fails with a native↔WASM memory conflict

[dgdev25]

Summary

On a fresh project, ak setup → ak dual run feature "<task>" cannot generate code due to two defects in ruflo's native SQLite memory substrate:

1. Under npm 12, ak setup installs ruflo without compiling the bundled better-sqlite3 native bindings (npm 12's allow-scripts blocks the install script). ruflo's native memory is non-functional, and ak status false-positives ✓ natives.
2. Once the bindings are present (npm ≤11, or npm 12 after a manual build), ak dual run feature fails with a native-WAL-vs-WASM conflict at the first shared-memory write.

Happy to split into two issues if preferred — they're tightly coupled (Defect 2 is what users hit after working around Defect 1).

Environment

• agentic-kit (ak) 4.0.0-alpha.21 · ruflo 3.32.9 · agentic-qe 3.13.1
• Verified across two clean local ruflo installs: npm 10.9.4 / node 22 (bindings build) vs npm 12.0.1 / node 24 (bindings don't build).

Defect 1 — native better-sqlite3 bindings not built under npm 12

Clean local repro (no global mutation):

mkdir t && cd t && npm init -y && npm install ruflo # under npm 12
find node_modules -name better_sqlite3.node | wc -l # -> 0
# install log: "N packages had install scripts blocked because they are not covered by allowScripts"

Contrast under npm 10 (same steps): 3/3 better_sqlite3.node built, no warning.

Impact: ruflo doctor → ✗ Memory Structural Integrity: better-sqlite3 failed to open: Could not locate the bindings file; ruflo status → Memory Backend: none, RuFlo V3 [STOPPED]. ak status still reports ✓ natives — a false positive, because it only inspects the agentdb copy of better-sqlite3 (which builds), not the @claude-flow/cli or @claude-flow/memory copies (which don't).

Expected: ak setup / ak sync builds and verifies all three better-sqlite3 instances (force the install scripts, or restore prebuilt binaries), and ak status's "natives" check load-tests the binding ruflo uses at runtime — not just the agentdb copy.

Defect 2 — ak dual run native↔WASM memory conflict (binding-present systems)

Repro (any system with working bindings, CLAUDE_FLOW_DB_PATH exported):

export CLAUDE_FLOW_DB_PATH="$PWD/.swarm/memory.db"
ak dual run feature "create a tiny hello package"

Fails at the first shared-memory write:

Error: … npx ruflo memory store --key task-context …
[ERROR] memory database has an active native WAL connection (found -wal/-shm sidecar files)
— refusing an unsafe sql.js whole-image write. Retry once the native writer completes,
or restore the native better-sqlite3 bridge.
 at @claude-flow/codex/dist/dual-mode/orchestrator.js:267

Cause: the claude-flow-codex dual orchestrator opens a native better-sqlite3 WAL connection on memory.db, then shells out to npx ruflo memory store, which uses sql.js (WASM) — ruflo memory init advertises "sql.js (WASM SQLite)", and npx ruflo resolves to the global ruflo (verified: no fetch). WASM refuses to whole-image-write over an active native WAL. Reproduced with bindings built via prebuild-install (the same mechanism npm ≤11 uses), so this is not specific to a manual node-gyp build.

Expected: the orchestrator and the npx ruflo memory subprocess agree on one SQLite backend (native) — route memory store through the native bridge, or don't hold a native connection across the npx call.

Workaround (clears Defect 1; exposes Defect 2)

# Build each missing binding directly (npm rebuild is also blocked by allow-scripts):
cd "$(npm root -g)/ruflo/node_modules/@claude-flow/cli/node_modules/better-sqlite3" && npm run install
cd "$(npm root -g)/ruflo/node_modules/@claude-flow/memory/node_modules/better-sqlite3" && npm run install
export CLAUDE_FLOW_DB_PATH="$PWD/.swarm/memory.db"

Impact

ak dual run feature cannot generate code out of the box under npm 12 (Defect 1), and on any binding-present system it then hits Defect 2. Under npm 12, ak status reports healthy while ruflo's memory substrate is non-functional, so the failure is hard to diagnose without running ruflo doctor.

[pacphi]

Thanks for the exceptionally precise report, @dgdev25 — both defects reproduced exactly as described, on the maintainer's own machine no less (defect 1 presented as ruflo memory store → "Database not initialized" while ak status said ✓ natives).

PR #48 addresses ak's side of both:

• Defect 1: healNatives() now heals @claude-flow/memory + @claude-flow/cli (where better-sqlite3 is an optionalDependency that allow-scripts silently drops), and the status natives row now load-tests the binding as resolved from those runtime contexts (child-process require + SELECT 1) — no more file-existence false positives. Also fixed en route: the heal ladder's hardcoded better-sqlite3@^12 spec is EOVERRIDE-rejected in trees that pin it (ruflo root pins 12.9.0); the spec is now derived from the tree's own declarations.
• Defect 2: ak dual run now pre-flights the exact crash condition (WASM-only runtime + live -wal/-shm sidecars) and refuses before spawning with run: ak sync as the fix, rather than dying at the first shared write. The conflict inside @claude-flow/codex's orchestrator itself is upstream ruflo's to fix — ak now heals the substrate and refuses the unsafe run.

npm 9–12 are all supported (the approve-scripts rung tolerates its absence on ≤11.16; runner-matrixed tests cover npm-9 and npm-12 behaviors). Will close via the PR once CI is green.