fix(security): dedup better-sqlite3 to patched 12.9.0 across dependency tree (#2736) (#2746)

* fix(security): dedup better-sqlite3 to patched 12.9.0 across dependency tree

Fixes #2736 (defense-in-depth mitigation).

SQLite's documented WAL-Reset Bug (sqlite.org/wal.html §11) is a race
between overlapping checkpoint operations and a WAL-resetting commit
that can make a later checkpoint skip a committed transaction, silently
losing acknowledged writes and/or corrupting index/table structure.
Affects SQLite 3.7.0-3.51.2; fixed in 3.51.3, backported to 3.44.6 and
3.50.7.

agentdb's own published dependency floor (`better-sqlite3@^11.8.1`,
confirmed in this tree resolving to 11.10.0, which bundles vulnerable
SQLite 3.49.2) created a mixed-engine tree alongside this repo's own
direct dependency on better-sqlite3 12.9.0 (patched SQLite 3.53.0, via
v3/@claude-flow/memory). Multiple concurrent connections (daemon, MCP
servers, CLI invocations) issuing wal_checkpoint(PASSIVE) after every
memory-bridge store is exactly the race precondition this bug requires.

This forces a single deduplicated better-sqlite3 build tree-wide via
pnpm overrides, pinned to the exact version this repo's own
@claude-flow/memory package already depends on directly (12.9.0,
bundling patched SQLite 3.53.0) — no new version to vet, just true
deduplication of agentdb's nested resolution into the already-patched
copy.

Changes (following this repo's existing #2112-lesson override
convention — multiple package.json files, each consumed a different
way):
- v3/package.json: pnpm.overrides (the v3 pnpm workspace root — this
  is where agentdb's better-sqlite3@11.10.0 actually lived pre-fix)
- v3/@claude-flow/cli/package.json: npm-style overrides (effective
  when @claude-flow/cli is npm-installed standalone via npx)
- package.json (root "claude-flow" umbrella): bumped the existing
  ">=12.8.0" override to an exact "12.9.0" pin, AND added a
  pnpm.overrides block — the bare "overrides" key alone is silently
  ignored by pnpm (only read by npm), so the pre-existing override was
  a no-op for local `pnpm install` at repo root despite being present
  in package.json for a while
- ruflo/package.json: bumped ">=12.8.0" to exact "12.9.0" (npm-style,
  effective for `npx ruflo@latest`)
- v3/pnpm-lock.yaml, pnpm-lock.yaml: regenerated via `pnpm install`

Verification:
- `pnpm why -r better-sqlite3` (v3/) and `pnpm why better-sqlite3`
  (root): exactly one resolved version, 12.9.0, everywhere
- Confirmed via realpath resolution (not hoisted symlink) from each of
  the 4 installed agentdb versions' own on-disk directories
  (1.6.1, 2.0.0-alpha.3.4, 2.0.0-alpha.3.7, 3.0.0-alpha.17) that each
  now binds the same deduplicated better-sqlite3@12.9.0 copy
- `db.prepare('select sqlite_version()').get()` from that binding
  returns 3.53.0 (>= 3.51.3 patched floor)
- v3/@claude-flow/memory test suite: 438/442 passing; the 4 failures
  are pre-existing Windows path-separator and perf-threshold issues
  unrelated to SQLite (none of the failing test files touch
  better-sqlite3/sqlite at all)

Not fixed here (upstream, out of reach from this repo):
- agentdb's own published package.json floor (`^11.8.1`) is
  unchanged — this override is a same-repo mitigation, not a fix to
  agentdb itself. agentdb needs the same bump upstream.

Not touched here (explicitly out of scope, separate/riskier change):
- The wal_checkpoint(PASSIVE)-after-every-store pattern in
  memory-bridge.ts (#2558) is left as-is; the issue calls that
  "defense-in-depth" / optional, and dedup alone removes the
  mixed-engine race precondition regardless.

Co-Authored-By: RuFlo <ruv@ruv.net>

* fix(deps): regenerate package-lock.json for better-sqlite3 dedup override

package.json pins the better-sqlite3 override to 12.9.0 (patched,
fixes the WAL-reset bug) but package-lock.json still resolved a stray
top-level better-sqlite3@12.10.0 and was missing the nested
better-sqlite3@12.9.0 entries under @claude-flow/memory, agentdb, and
agentic-flow — causing npm ci to fail in CI with "Missing:
better-sqlite3@12.9.0 from lock file".

Co-Authored-By: RuFlo <ruv@ruv.net>

* fix(deps): restore better-sqlite3 as direct root optionalDependency

The #2736 dedup fix pinned better-sqlite3 to 12.9.0 via a pure
"overrides" entry (no direct dependency), which removed the top-level
hoisted node_modules/better-sqlite3 that used to exist under the
looser ">=12.8.0" override. That silently broke the "graph schema
smoke (ADR-130 P1)" CI job: its "npm rebuild better-sqlite3" step
(and graph-edge-writer.ts's bare `await import('better-sqlite3')`,
which Node resolves by walking up node_modules from the importing
file) had nothing at the root to rebuild/resolve, so _openDb() failed
closed and insertGraphEdge() silently returned false — 8/22 assertions
failing.

Restoring the direct optionalDependency (matching what this file
already had historically, before the override-only refactor) gives
npm a concrete anchor to hoist a single deduplicated copy back to
root node_modules, preserving the override's version pin while
keeping the graph-edge-writer's resolution path intact. Regenerated
package-lock.json accordingly.

Verified locally: `npm rebuild better-sqlite3` now finds and rebuilds
the root copy, and a direct insertGraphEdge() call against a real
better-sqlite3 handle returns true.

Co-Authored-By: RuFlo <ruv@ruv.net>

* fix(deps): resync v3/pnpm-lock.yaml specifier after merging main

Merging main (which carries #2748's direct better-sqlite3 dependency
on @claude-flow/cli) forward into this branch left the recorded
lockfile specifier at the pre-override "^12.9.0" while this branch's
own overrides.better-sqlite3 pin ("12.9.0", exact) is now the
effective spec pnpm resolves against — a one-line drift causing
`pnpm install --frozen-lockfile` to fail across the whole v3-ci.yml
matrix. Regenerated to match.

Co-Authored-By: RuFlo <ruv@ruv.net>

* fix(memory): force WAL checkpoint before close in graph-edge-writer

The "graph schema smoke (ADR-130 P1)" CI job started failing
deterministically on Linux runners after the better-sqlite3 dedup
(this branch) pinned a single 12.9.0 build tree-wide: TEST 2/3
insert-then-reread assertions found embedding_ref/source_id undefined
immediately after _resetBridgeDb() closed the write connection.

_resetBridgeDb()'s close() relied on SQLite's implicit "last
connection close" PASSIVE auto-checkpoint to flush the WAL into the
main file before a same-process sql.js reader re-reads the raw file.
That's best-effort, not guaranteed synchronous, and evidently more
prone to leaving data in the WAL under Linux CI's I/O/lock timing than
on Windows (did not reproduce locally). Not a correctness regression
in 12.9.0 itself — a latent timing assumption the dedup made newly
observable by changing which exact build backs every connection.

Force a blocking `wal_checkpoint(TRUNCATE)` before close so the main
file always reflects committed writes before any other reader (same
process or otherwise) touches it, regardless of platform timing.

Co-Authored-By: RuFlo <ruv@ruv.net>

package-lock.json

@@ -38,7 +38,7 @@
         "url": "https://github.com/sponsors/ruvnet"
       },
       "optionalDependencies": {
-        "@claude-flow/codex": "^3.0.0",
+        "@claude-flow/codex": "^3.0.1",
         "@claude-flow/plugin-gastown-bridge": "^0.1.3",
         "@ruvector/attention": "^0.1.3",
         "@ruvector/core": "^0.1.30",
@@ -46,7 +46,8 @@
         "@ruvector/router-linux-x64-gnu": "^0.1.30",
         "@ruvector/sona": "^0.1.5",
         "agentdb": "^3.0.0-alpha.17",
-        "agentic-flow": "^2.0.14"
+        "agentic-flow": "^2.0.14",
+        "better-sqlite3": "12.9.0"
       }
     },
     "node_modules/@anthropic-ai/claude-agent-sdk": {
@@ -4447,9 +4448,9 @@
       "optional": true
     },
     "node_modules/better-sqlite3": {
-      "version": "12.10.0",
+      "version": "12.9.0",
-      "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-12.10.0.tgz",
+      "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-12.9.0.tgz",
-      "integrity": "sha512-CyzaZRQKyHkB2ZInfTTl2nvT33EbDpjkLEbE8/Zck3Ll6O0qqvuGdrJ45HgtH+HykRg88ITY3AdreBGN70aBSQ==",
+      "integrity": "sha512-wqUv4Gm3toFpHDQmaKD4QhZm3g1DjUBI0yzS4UBl6lElUmXFYdTQmmEDpAFa5o8FiFiymURypEnfVHzILKaxqQ==",
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
@@ -4458,7 +4459,7 @@
         "prebuild-install": "^7.1.1"
       },
       "engines": {
-        "node": "20.x || 22.x || 23.x || 24.x || 25.x || 26.x"
+        "node": "20.x || 22.x || 23.x || 24.x || 25.x"
       }
     },
     "node_modules/bignumber.js": {

package.json

@@ -78,11 +78,12 @@
     "@ruvector/router-linux-x64-gnu": "^0.1.30",
     "@ruvector/sona": "^0.1.5",
     "agentdb": "^3.0.0-alpha.17",
-    "agentic-flow": "^2.0.14"
+    "agentic-flow": "^2.0.14",
+    "better-sqlite3": "12.9.0"
   },
   "overrides": {
     "ruvector": "^0.2.27",
-    "better-sqlite3": ">=12.8.0",
+    "better-sqlite3": "12.9.0",
     "js-yaml": ">=4.3.0",
     "hono": ">=4.12.25",
     "@ruvector/rvf-wasm": "0.1.5",
@@ -131,6 +132,11 @@
     "typescript": "^5.0.0",
     "vitest": "^3.2.6"
   },
+  "pnpm": {
+    "overrides": {
+      "better-sqlite3": "12.9.0"
+    }
+  },
   "engines": {
     "node": ">=20.0.0"
   },

pnpm-lock.yaml

@@ -4,6 +4,9 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+overrides:
+  better-sqlite3: 12.9.0
+
 importers:
 
   .:
@@ -1725,12 +1728,9 @@ packages:
   base64-js@1.5.1:
     resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
 
-  better-sqlite3@11.10.0:
+  better-sqlite3@12.9.0:
-    resolution: {integrity: sha512-EwhOpyXiOEL/lKzHz9AW1msWFNzGc/z+LzeB3/jnFJpxu+th2yqvzsSWas1v9jgs9+xiXJcD5A8CJxAG2TaghQ==}
+    resolution: {integrity: sha512-wqUv4Gm3toFpHDQmaKD4QhZm3g1DjUBI0yzS4UBl6lElUmXFYdTQmmEDpAFa5o8FiFiymURypEnfVHzILKaxqQ==}
-
+    engines: {node: 20.x || 22.x || 23.x || 24.x || 25.x}
-  better-sqlite3@12.11.1:
-    resolution: {integrity: sha512-dq9AtApgg5PGFtBzPFSBl3HZQjHok5gaQCM6zh2Yk0aSmDCs1CbnVI8/HgASQkNKsWFpseIO9beg5xxpYhbIfA==}
-    engines: {node: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x}
 
   bignumber.js@9.3.1:
     resolution: {integrity: sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==}
@@ -3660,7 +3660,7 @@ snapshots:
       agentdb: 3.0.0-alpha.17(@types/node@20.19.39)(zod@3.25.76)
       sql.js: 1.14.1
     optionalDependencies:
-      better-sqlite3: 12.11.1
+      better-sqlite3: 12.9.0
     transitivePeerDependencies:
       - '@cfworker/json-schema'
       - '@types/node'
@@ -5016,7 +5016,7 @@ snapshots:
       '@ruvector/sona': 0.1.6
       '@xenova/transformers': 2.17.2
       argon2: 0.44.0
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
       chalk: 5.6.2
       commander: 12.1.0
       hnswlib-node: 3.0.0
@@ -5066,7 +5066,7 @@ snapshots:
       '@ruvector/attention': 0.1.32
       '@ruvector/sona': 0.1.6
       agentdb: 3.0.0-alpha.17(@types/node@20.19.39)(zod@3.25.76)
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
       onnxruntime-node: 1.25.1
       sharp: 0.32.6
       sql.js: 1.14.1
@@ -5205,13 +5205,7 @@ snapshots:
   base64-js@1.5.1:
     optional: true
 
-  better-sqlite3@11.10.0:
+  better-sqlite3@12.9.0:
-    dependencies:
-      bindings: 1.5.0
-      prebuild-install: 7.1.3
-    optional: true
-
-  better-sqlite3@12.11.1:
     dependencies:
       bindings: 1.5.0
       prebuild-install: 7.1.3

ruflo/package.json

@@ -45,7 +45,7 @@
   "optionalDependencies": {},
   "overrides": {
     "ruvector": "^0.2.27",
-    "better-sqlite3": ">=12.8.0",
+    "better-sqlite3": "12.9.0",
     "@ruvector/rvf-wasm": "0.1.5",
     "@hono/node-server": ">=1.19.10",
     "flatted": ">=3.4.0",

v3/@claude-flow/cli/package.json

@@ -131,6 +131,7 @@
     "@opentelemetry/resources": ">=2.8.0",
     "@opentelemetry/sdk-trace-base": ">=2.8.0",
     "@opentelemetry/sdk-node": ">=0.220.0",
-    "agentdb": "$agentdb"
+    "agentdb": "$agentdb",
+    "better-sqlite3": "12.9.0"
   }
 }

v3/@claude-flow/cli/src/memory/graph-edge-writer.ts

@@ -256,9 +256,19 @@ export async function countGraphEdges(dbPath?: string): Promise<number> {
  * #2431 fix: also explicitly closes the prior handle so file locks
  * release immediately — better-sqlite3 holds an OS-level file handle
  * which the prior sql.js implementation did not.
+ *
+ * #2736-followup fix: `close()` alone only checkpoints the WAL back into
+ * the main file as a best-effort PASSIVE checkpoint when SQLite considers
+ * this the last connection — which is not guaranteed to fully flush under
+ * contention, and was observed leaving writes invisible to a same-process
+ * sql.js reader that re-reads the raw file immediately after close() on
+ * Linux CI runners (not reproduced on Windows). Force a blocking TRUNCATE
+ * checkpoint before close so cross-engine readers always see committed
+ * writes deterministically, regardless of platform/timing.
  */
 export function _resetBridgeDb(): void {
   if (_db) {
+    try { _db.pragma('wal_checkpoint(TRUNCATE)'); } catch { /* best-effort */ }
     try { _db.close(); } catch { /* best-effort */ }
   }
   _db = null;

v3/package.json

@@ -77,7 +77,8 @@
       "@opentelemetry/core": ">=2.8.0",
       "@opentelemetry/resources": ">=2.8.0",
       "@opentelemetry/sdk-trace-base": ">=2.8.0",
-      "@opentelemetry/sdk-node": ">=0.220.0"
+      "@opentelemetry/sdk-node": ">=0.220.0",
+      "better-sqlite3": "12.9.0"
     }
   }
 }

v3/pnpm-lock.yaml

@@ -23,6 +23,7 @@ overrides:
   '@opentelemetry/resources': '>=2.8.0'
   '@opentelemetry/sdk-trace-base': '>=2.8.0'
   '@opentelemetry/sdk-node': '>=0.220.0'
+  better-sqlite3: 12.9.0
 
 importers:
 
@@ -154,7 +155,7 @@ importers:
         specifier: ^3.0.0-alpha.1
         version: 3.0.0-alpha.2
       better-sqlite3:
-        specifier: ^12.9.0
+        specifier: 12.9.0
         version: 12.9.0
       ruvector:
         specifier: ^0.2.27
@@ -291,8 +292,8 @@ importers:
         version: 3.25.76
     optionalDependencies:
       better-sqlite3:
-        specifier: ^11.0.0
+        specifier: 12.9.0
-        version: 11.10.0
+        version: 12.9.0
     devDependencies:
       '@types/better-sqlite3':
         specifier: ^7.6.11
@@ -362,7 +363,7 @@ importers:
         version: 1.13.0
     optionalDependencies:
       better-sqlite3:
-        specifier: ^12.9.0
+        specifier: 12.9.0
         version: 12.9.0
     devDependencies:
       '@types/better-sqlite3':
@@ -6730,7 +6731,7 @@ packages:
       sql.js: 1.14.1
       zod: 3.25.76
     optionalDependencies:
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
     transitivePeerDependencies:
       - '@cfworker/json-schema'
       - bare-abort-controller
@@ -6780,7 +6781,7 @@ packages:
       '@xenova/transformers': 2.17.2
       argon2: 0.44.0
       bcrypt: 6.0.0
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
       express-rate-limit: 8.3.2(express@5.2.1)
       helmet: 8.1.0
       hnswlib-node: 3.0.0
@@ -6841,7 +6842,7 @@ packages:
       '@xenova/transformers': 2.17.2
       argon2: 0.44.0
       bcrypt: 6.0.0
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
       express-rate-limit: 8.3.2(express@5.2.1)
       helmet: 8.1.0
       hnswlib-node: 3.0.0
@@ -6886,7 +6887,7 @@ packages:
       '@ruvector/sona': 0.1.8
       '@xenova/transformers': 2.17.2
       argon2: 0.44.0
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
       chalk: 5.6.2
       commander: 12.1.0
       hnswlib-node: 3.0.0
@@ -6916,7 +6917,7 @@ packages:
       '@xenova/transformers': 2.17.2
       agentdb: 1.6.1
       axios: 1.13.2
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
       dotenv: 16.6.1
       express: 5.2.1
       fastmcp: 3.26.7
@@ -6973,7 +6974,7 @@ packages:
       agentic-payments: 0.1.13(typescript@5.9.3)
       autoprefixer: 10.4.23(postcss@8.5.6)
       axios: 1.13.2
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
       dotenv: 16.6.1
       express: 5.2.1
       fastmcp: 3.26.7
@@ -7057,7 +7058,7 @@ packages:
       '@ruvector/attention': 0.1.32
       '@ruvector/sona': 0.1.8
       agentdb: 3.0.0-alpha.17(@types/node@20.19.27)(zod@3.25.76)
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
       onnxruntime-node: 1.24.3
       sharp: 0.32.6
       sql.js: 1.14.1
@@ -7113,7 +7114,7 @@ packages:
       '@ruvector/sona': 0.1.8
       '@xenova/transformers': 2.17.2
       agentdb: 3.0.0-alpha.17(@types/node@20.19.27)(zod@3.25.76)
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
       onnxruntime-node: 1.24.3
       sharp: 0.32.6
       sql.js: 1.14.1
@@ -7169,7 +7170,7 @@ packages:
       '@ruvector/attention': 0.1.32
       '@ruvector/sona': 0.1.8
       agentdb: 2.0.0-alpha.3.7(@types/node@20.19.27)(express@5.2.1)(marked@11.2.0)
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
       onnxruntime-node: 1.24.3
       sharp: 0.32.6
       sql.js: 1.14.1
@@ -7266,7 +7267,7 @@ packages:
       zod: 4.3.5
     optionalDependencies:
       agentic-flow: 1.10.2(@modelcontextprotocol/sdk@1.27.1)
-      better-sqlite3: 11.10.0
+      better-sqlite3: 12.9.0
     transitivePeerDependencies:
       - '@cfworker/json-schema'
       - '@valibot/to-json-schema'
@@ -7592,13 +7593,6 @@ packages:
   /before-after-hook@4.0.0:
     resolution: {integrity: sha512-q6tR3RPqIB1pMiTRMFcZwuG5T8vwp+vUvEG0vuI6B+Rikh5BfPp2fQ82c925FOs+b0lcFQ8CFrL+KbilfZFhOQ==}
 
-  /better-sqlite3@11.10.0:
-    resolution: {integrity: sha512-EwhOpyXiOEL/lKzHz9AW1msWFNzGc/z+LzeB3/jnFJpxu+th2yqvzsSWas1v9jgs9+xiXJcD5A8CJxAG2TaghQ==}
-    requiresBuild: true
-    dependencies:
-      bindings: 1.5.0
-      prebuild-install: 7.1.3
-
   /better-sqlite3@12.9.0:
     resolution: {integrity: sha512-wqUv4Gm3toFpHDQmaKD4QhZm3g1DjUBI0yzS4UBl6lElUmXFYdTQmmEDpAFa5o8FiFiymURypEnfVHzILKaxqQ==}
     engines: {node: 20.x || 22.x || 23.x || 24.x || 25.x}
@@ -7606,8 +7600,6 @@ packages:
     dependencies:
       bindings: 1.5.0
       prebuild-install: 7.1.3
-    dev: false
-    optional: true
 
   /bignumber.js@9.3.1:
     resolution: {integrity: sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==}
@@ -11091,6 +11083,7 @@ packages:
   /prebuild-install@7.1.3:
     resolution: {integrity: sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug==}
     engines: {node: '>=10'}
+    deprecated: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
     hasBin: true
     dependencies:
       detect-libc: 2.1.2