fix: truthful natives across the whole ruflo tree#48
Merged
Conversation
ak's natives heal and status only looked at the agentdb copies of better-sqlite3, while `npx ruflo memory` resolves its binding from @claude-flow/memory and @claude-flow/cli — both declare it only as an optionalDependency, which npm >=11.17's allow-scripts gate silently drops. Result: `ak status` said "natives ok" while ruflo's own memory ran on the sql.js WASM fallback, and `ak dual run` died mid-pipeline at the first shared write (native WAL vs WASM whole-image refusal). - healNatives() now also heals the ruflo memory-runtime contexts. - ensureNativeBsq3's install rung derives its spec from the target tree's own overrides/optionalDependencies (hardcoded `@^12` is EOVERRIDE-rejected in trees pinning better-sqlite3 — verified live); reference forms ($agentdb) and protocols are skipped. - The natives status row load-tests the binding as resolved from each runtime context (require + open :memory: + SELECT 1 in a child process) — no more file-existence false positives. - `ak dual run` pre-flights the #45 defect-2 crash condition (WASM-only runtime + live -wal/-shm sidecars) and refuses with "run: ak sync" instead of corrupting the store mid-run. - New: `memory-pin` status warning when CLAUDE_FLOW_DB_PATH pins a missing or out-of-project path (warn-only; sync never touches it). - npm 9-12 supported: the approve-scripts rung tolerates its absence on npm <=11.16 (runner-matrixed tests for npm-9 and npm-12 behaviors). 53 heal/natives tests total; check chain green. Fixes #45
pacphi
added a commit
that referenced
this pull request
Jul 24, 2026
…md target (ADR-0008) (#50) The block registry knew two guidance targets: machine-wide ~/.claude/CLAUDE.md and the PROJECT AGENTS.md. That asymmetry meant (a) only synced repos ever got codex-side guidance, and (b) machine state leaked into git — the dual-mode block exists only when both hosts are enabled in kit.json, a fact about one machine, yet it was committed into shared checked-in AGENTS.md files. - New `agents-user` target → ~/.codex/AGENTS.md (codex's global guidance file). Dir-exists gated — ak never creates ~/.codex; one-time .bak before the first managed rewrite, mirroring CLAUDE.md's. - `ruflo-dual-mode-reference` re-scoped to ['claude','agents-user']; the project `agents` target stays for genuinely repo-scoped rows. - Migration: each target now also strips sentinel-present blocks that no longer list it (`retiredForTarget` forced-strip rows), so project AGENTS.md files carrying the old block heal on their next sync. - One shared `guidanceTargets()` helper replaces the duplicated target lists in sync.mjs/status.mjs. - Docs aligned with this and #47/#48: template sentinel comment, README setup/status/dual rows (truthful natives, memory-pin, pre-flight refusal), MAINTAINER.md registry description, UPGRADING/ TROUBLESHOOTING remedies. ADR-0008 records the scope split. 314 kit tests green (10 new); full check chain green. Live dry-run: CLAUDE.md upsert + project AGENTS.md strip + ~/.codex/AGENTS.md upsert.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #45.
What broke (verified live while diagnosing this repo's own
ruflo memory storefailure)ak's natives heal and status row only covered the agentdb copies of better-sqlite3 — butnpx ruflo memoryresolves its binding from@claude-flow/memory/@claude-flow/cli, where it's an optionalDependency that npm ≥11.17'sallow-scriptsgate silently drops at install. Soak statussaid✓ natives(defect 1's false positive) while ruflo's memory ran on the sql.js/WASM fallback, andak dual runcrashed at the first shared-memory write against a live native WAL (defect 2).What this PR does
healNatives()now heals the ruflo memory-runtime contexts (@claude-flow/memory,@claude-flow/cli) alongside agentdb + aqe. Missing contexts (older trees) skip silently.ensureNativeBsq3's install rung derives its spec from the target tree's ownoverrides/optionalDependencies— the previous hardcodedbetter-sqlite3@^12is rejected withEOVERRIDEin trees that pin it (ruflo root pins12.9.0;@claude-flow/clipins^12.9.0). Non-installable forms ($agentdbreferences, protocols) are skipped during derivation.require+ open:memory:+SELECT 1in a child process — instead of trusting file existence. A WASM-backed runtime reads as ✗ withsync builds the native bindingas the remedy.ak dual rundetects the exact crash condition (WASM-only runtime and-wal/-shmsidecars beside the target DB) and refuses pre-spawn with the fix (run: ak sync), instead of corrupting the store mid-pipeline. Cheap sidecar stat first; the child-process probe only runs when a WAL is actually live.memory-pinwarning:ak statusnow warns whenCLAUDE_FLOW_DB_PATH(in.claude/settings.local.jsonenv) pins a missing or out-of-project path — the exact failure mode that presented as "Database not initialized" on a healthy DB. Warn-only;syncnever touches the pin.npm compatibility
npm 9, 10, 11, and 12 are supported: every npm invocation used is valid on all four, and the
npm approve-scriptsrung tolerates its absence on ≤11.16 (unknown-command exits don't abort the ladder). Runner-matrixed tests simulate npm-9 and npm-12 behaviors explicitly.Not in scope (as discussed in the issue)
The native↔WASM conflict inside
@claude-flow/codex's dual orchestrator itself is upstream ruflo's to fix — this PR makes ak refuse the unsafe run and heal the substrate so the condition doesn't arise.Verification
pnpm run checkgreen (typecheck · eslint · markdownlint · build · full suite).ak statusshows✓ ruflo memory runtime native (memory, cli)andruflo memory store→searchround-trips.🤖 Generated with Claude Code