Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

feat(doctor): flag better-sqlite3 copies built against Node 24.19+ headers on 24.19-24.21 (#4055)

rf38576e12599
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9582dd9906..5c6b13b76c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+
+- `ruflo doctor` reports `better-sqlite3` copies compiled against Node 24.19+ headers when running Node 24.19–24.21, where they can abort the process (`Assertion failed: (env) != nullptr`, nodejs/node#65446), with the documented workarounds. `doctor --component native-addon` runs it alone (#4055, reported by @ronmikailov).
+
### Fixed
Batch of reviewed fixes from @rudycelekli (PRs #4020-#4026, #4028-#4030, #4032, #4033, #4035, #4037; #4027 and #4034 landed earlier):
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index 8a6e638258..a703c35da9 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -2846,6 +2846,7 @@ Run `npx ruflo@latest doctor` to diagnose and fix common issues.
| **MCP servers** | Responsive | βœ… Restarts unresponsive servers |
| **Disk space** | >100MB free | ❌ Manual cleanup required |
| **TypeScript** | Installed | βœ… Installs if missing |
+| **Native addon headers** | No `better-sqlite3` built against Node 24.19+ headers while running Node 24.19–24.21 | ❌ See below |
**Commands:**
@@ -2863,6 +2864,14 @@ npx ruflo@latest doctor --component memory
npx ruflo@latest doctor --verbose
```
+**Node 24.19–24.21 abort (#4055).** A native addon compiled against Node 24.19+ headers can abort the process with `Assertion failed: (env) != nullptr` in `node::RemoveEnvironmentCleanupHook` (nodejs/node#65446; the fix, PR #65943, is in no release through 24.21.0). Prebuilt binaries are not affected, only copies compiled locally, which carry a `build/config.gypi` naming the headers they used. `doctor --component native-addon` reads those files (it never loads an addon) and lists each affected copy. Workarounds, any one of:
+
+- run Node 22, or Node 24.18.1, or a Node release that contains the fix;
+- rebuild the listed copy against older headers: `cd <copy> && npx node-gyp rebuild --release --nodedir=<node 24.18.1 headers>`;
+- install the 12.x prebuilt in the project: `npm install better-sqlite3@12`.
+
+ruflo opens AgentDB through its own prebuilt 12.x copy (since 3.56.4), so a flagged nested copy under `agentdb` or `agentic-flow` matters only to code that loads it directly. npm ignores `overrides` in a dependency's package.json, so the nested 11.x copies cannot be removed from inside the published package.
+
**Output Example:**
```
diff --git a/v3/@claude-flow/cli/__tests__/doctor-native-addon-headers-4055.test.ts b/v3/@claude-flow/cli/__tests__/doctor-native-addon-headers-4055.test.ts
new file mode 100644
index 0000000000..5f3f39e332
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/doctor-native-addon-headers-4055.test.ts
@@ -0,0 +1,123 @@
+/** #4055: native addons built against Node >=24.19 headers abort on Node 24.19-24.21 (nodejs/node#65446). */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+ checkNativeAddonHeaders,
+ headersVersionFromGypi,
+ isAffectedNodeVersion,
+} from '../src/commands/doctor-native-addon.js';
+
+let root: string;
+beforeEach(() => { root = mkdtempSync(join(tmpdir(), 'ruflo-4055-')); });
+afterEach(() => { rmSync(root, { recursive: true, force: true }); });
+
+const gypi = (nodedir: string) => `# Do not edit. File was generated by node-gyp's "configure" step
+{
+ "target_defaults": { "cflags": [], "default_configuration": "Release" },
+ "variables": {
+ "napi_build_version": "0",
+ "nodedir": "${nodedir}",
+ "node_module_version": 137
+ }
+}
+`;
+
+function addon(dir: string, version: string, nodedir: string | null) {
+ mkdirSync(join(dir, 'build'), { recursive: true });
+ writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'better-sqlite3', version }));
+ if (nodedir !== null) writeFileSync(join(dir, 'build', 'config.gypi'), gypi(nodedir));
+}
+
+describe('isAffectedNodeVersion', () => {
+ it.each([
+ ['24.18.1', false], ['24.19.0', true], ['24.20.1', true], ['24.21.0', true],
+ ['24.21.5', true], ['22.23.2', false], ['25.0.0', false], ['20.11.0', false],
+ ])('%s -> %s', (v, expected) => expect(isAffectedNodeVersion(v)).toBe(expected));
+});
+
+describe('headersVersionFromGypi', () => {
+ it('reads the version out of the node-gyp cache nodedir', () => {
+ expect(headersVersionFromGypi(gypi('/home/u/.cache/node-gyp/24.20.0'))).toBe('24.20.0');
+ });
+ it('reads a node-vXX source-tree nodedir', () => {
+ expect(headersVersionFromGypi(gypi('/opt/node-v24.21.0'))).toBe('24.21.0');
+ });
+ it('returns null when no version can be read', () => {
+ expect(headersVersionFromGypi(gypi('/usr/include/node'))).toBeNull();
+ expect(headersVersionFromGypi('not a gypi')).toBeNull();
+ });
+});
+
+describe('checkNativeAddonHeaders', () => {
+ it('warns for a copy built against 24.20 headers on Node 24.21', async () => {
+ const bad = join(root, 'node_modules', 'agentdb', 'node_modules', 'better-sqlite3');
+ addon(bad, '11.10.0', '/home/u/.cache/node-gyp/24.20.0');
+ const r = await checkNativeAddonHeaders({ nodeVersion: '24.21.0', copies: [bad] });
+ expect(r.status).toBe('warn');
+ expect(r.message).toContain('11.10.0');
+ expect(r.message).toContain('24.20.0');
+ expect(r.message).toContain(bad);
+ expect(r.fix).toMatch(/24\.18\.1/);
+ expect(r.fix).toMatch(/node-gyp rebuild/);
+ expect(r.fix).toMatch(/nodedir/);
+ });
+
+ it('passes for a prebuilt copy (no config.gypi) on an affected Node', async () => {
+ const pre = join(root, 'node_modules', 'better-sqlite3');
+ addon(pre, '12.11.1', null);
+ const r = await checkNativeAddonHeaders({ nodeVersion: '24.21.0', copies: [pre] });
+ expect(r.status).toBe('pass');
+ });
+
+ it('passes for a copy rebuilt against 24.18.1 headers', async () => {
+ const ok = join(root, 'node_modules', 'better-sqlite3');
+ addon(ok, '11.10.0', '/home/u/.cache/node-gyp/24.18.1');
+ const r = await checkNativeAddonHeaders({ nodeVersion: '24.21.0', copies: [ok] });
+ expect(r.status).toBe('pass');
+ });
+
+ it('is not applicable off the affected Node range', async () => {
+ const bad = join(root, 'node_modules', 'better-sqlite3');
+ addon(bad, '11.10.0', '/home/u/.cache/node-gyp/24.20.0');
+ for (const nodeVersion of ['22.23.2', '24.18.1', '25.0.0']) {
+ const r = await checkNativeAddonHeaders({ nodeVersion, copies: [bad] });
+ expect(r.status).toBe('pass');
+ expect(r.message).toMatch(/not affected|not in the affected/i);
+ }
+ });
+
+ it('reports every bad copy, not just the first', async () => {
+ const a = join(root, 'node_modules', 'agentdb', 'node_modules', 'better-sqlite3');
+ const b = join(root, 'node_modules', 'agentic-flow', 'node_modules', 'better-sqlite3');
+ addon(a, '11.10.0', '/c/node-gyp/24.20.0');
+ addon(b, '11.10.0', '/c/node-gyp/24.19.0');
+ const r = await checkNativeAddonHeaders({ nodeVersion: '24.20.0', copies: [a, b] });
+ expect(r.status).toBe('warn');
+ expect(r.message).toContain(a);
+ expect(r.message).toContain(b);
+ });
+
+ it('discovers nested copies under node_modules by walking up from a start dir', async () => {
+ const top = join(root, 'node_modules', 'better-sqlite3');
+ const nested = join(root, 'node_modules', 'agentdb', 'node_modules', 'better-sqlite3');
+ addon(top, '12.11.1', null);
+ addon(nested, '11.10.0', '/c/node-gyp/24.20.0');
+ const start = join(root, 'node_modules', '@claude-flow', 'cli', 'dist', 'src', 'commands');
+ mkdirSync(start, { recursive: true });
+ const r = await checkNativeAddonHeaders({ nodeVersion: '24.21.0', startDirs: [start] });
+ expect(r.status).toBe('warn');
+ expect(r.message).toContain(nested);
+ expect(r.message).not.toContain(`${top} `);
+ });
+
+ it('never throws on unreadable or malformed files', async () => {
+ const weird = join(root, 'node_modules', 'better-sqlite3');
+ mkdirSync(join(weird, 'build'), { recursive: true });
+ writeFileSync(join(weird, 'package.json'), '{not json');
+ writeFileSync(join(weird, 'build', 'config.gypi'), '\u0000\u0001');
+ const r = await checkNativeAddonHeaders({ nodeVersion: '24.21.0', copies: [weird, join(root, 'missing')] });
+ expect(['pass', 'warn']).toContain(r.status);
+ });
+});
diff --git a/v3/@claude-flow/cli/src/commands/doctor-native-addon.ts b/v3/@claude-flow/cli/src/commands/doctor-native-addon.ts
new file mode 100644
index 0000000000..6d17526e42
--- /dev/null
+++ b/v3/@claude-flow/cli/src/commands/doctor-native-addon.ts
@@ -0,0 +1,132 @@
+/**
+ * #4055: native addons compiled against Node >= 24.19 headers abort when a
+ * garbage-collected ObjectWrap (a better-sqlite3 Statement) calls
+ * RemoveEnvironmentCleanupHook() with no Environment (nodejs/node#65446).
+ * The fix (abe1b673e9b, PR #65943) was in no release through v24.21.0.
+ *
+ * Only copies that were COMPILED LOCALLY carry a build/config.gypi naming the
+ * headers they were built against; prebuilt binaries (prebuild-install) do not,
+ * so they are never flagged. The check is read-only and never loads an addon.
+ */
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface NativeAddonCheck {
+ name: string;
+ status: 'pass' | 'warn' | 'fail';
+ message: string;
+ fix?: string;
+}
+
+const NAME = 'Native addon headers (Node 24)';
+
+function parse(v: string): [number, number, number] | null {
+ const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(v);
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** Node 24.19.0 up to, but not including, 24.22.0. Re-check this bound when a release ships the fix. */
+export function isAffectedNodeVersion(version: string): boolean {
+ const v = parse(version);
+ if (!v || v[0] !== 24) return false;
+ return v[1] >= 19 && v[1] <= 21;
+}
+
+/** The Node version of the headers a copy was built against, from its config.gypi. */
+export function headersVersionFromGypi(gypi: string): string | null {
+ const field = /["']node_version["']\s*:\s*["']v?(\d+\.\d+\.\d+)["']/.exec(gypi);
+ if (field) return field[1];
+ const dir = /["']nodedir["']\s*:\s*["']([^"']*)["']/.exec(gypi);
+ if (!dir) return null;
+ const all = [...dir[1].matchAll(/(\d+)\.(\d+)\.(\d+)/g)];
+ const last = all[all.length - 1];
+ return last ? `${last[1]}.${last[2]}.${last[3]}` : null;
+}
+
+function readJson(path: string): Record<string, unknown> | null {
+ try { return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>; } catch { return null; }
+}
+
+function listDir(path: string): string[] {
+ try { return readdirSync(path); } catch { return []; }
+}
+
+/** `better-sqlite3` copies in node_modules next to, or one level under, each ancestor of the start dirs. */
+export function findBetterSqlite3Copies(startDirs: string[], maxDepth = 12): string[] {
+ const found = new Set<string>();
+ const add = (dir: string) => {
+ if (!existsSync(join(dir, 'package.json'))) return;
+ try { found.add(realpathSync(dir)); } catch { /* unreadable */ }
+ };
+ const scanNodeModules = (nm: string) => {
+ add(join(nm, 'better-sqlite3'));
+ for (const entry of listDir(nm)) {
+ if (entry.startsWith('.') || entry === 'better-sqlite3') continue;
+ if (entry.startsWith('@')) {
+ for (const sub of listDir(join(nm, entry))) add(join(nm, entry, sub, 'node_modules', 'better-sqlite3'));
+ } else {
+ add(join(nm, entry, 'node_modules', 'better-sqlite3'));
+ }
+ }
+ };
+ for (const start of startDirs) {
+ let dir = resolve(start);
+ for (let i = 0; i < maxDepth; i++) {
+ scanNodeModules(join(dir, 'node_modules'));
+ const parent = dirname(dir);
+ if (parent === dir) break;
+ dir = parent;
+ }
+ }
+ return [...found].sort();
+}
+
+export interface NativeAddonCheckDeps {
+ /** Runtime version, default process.versions.node. */
+ nodeVersion?: string;
+ /** Exact better-sqlite3 package directories to inspect (skips discovery). */
+ copies?: string[];
+ /** Directories to walk up from when discovering copies. */
+ startDirs?: string[];
+}
+
+const FIX = [
+ 'Use a Node release that contains nodejs/node#65946 (not in any release through 24.21.0), or Node 22 / 24.18.1;',
+ 'or rebuild each listed copy against 24.18.1 headers:',
+ 'cd <copy> && npx node-gyp rebuild --release --nodedir=<path to node 24.18.1 headers> ;',
+ 'or install the 12.x prebuilt (npm install better-sqlite3@12 in the project).',
+ 'ruflo itself opens AgentDB through its own prebuilt 12.x copy, so a flagged nested copy matters only to code that loads it directly.',
+].join(' ');
+
+/** Read-only: warn when a locally compiled better-sqlite3 was built against Node >= 24.19 headers on an affected runtime. */
+export async function checkNativeAddonHeaders(deps: NativeAddonCheckDeps = {}): Promise<NativeAddonCheck> {
+ const nodeVersion = deps.nodeVersion ?? process.versions.node;
+ if (!isAffectedNodeVersion(nodeVersion)) {
+ return { name: NAME, status: 'pass', message: `Node ${nodeVersion} is not in the affected range (24.19.0-24.21.x)` };
+ }
+ const here = dirname(fileURLToPath(import.meta.url));
+ const copies = deps.copies ?? findBetterSqlite3Copies(deps.startDirs ?? [here, process.cwd()]);
+ if (copies.length === 0) {
+ return { name: NAME, status: 'pass', message: `Node ${nodeVersion}: no better-sqlite3 copy found to inspect` };
+ }
+ const bad: string[] = [];
+ for (const copy of copies) {
+ let gypi: string;
+ try { gypi = readFileSync(join(copy, 'build', 'config.gypi'), 'utf8'); } catch { continue; }
+ const headers = headersVersionFromGypi(gypi);
+ const parsed = headers ? parse(headers) : null;
+ if (!parsed || parsed[0] !== 24 || parsed[1] < 19) continue;
+ const version = readJson(join(copy, 'package.json'))?.version;
+ bad.push(`${copy} (better-sqlite3 ${typeof version === 'string' ? version : '?'}, built against Node ${headers} headers)`);
+ }
+ if (bad.length === 0) {
+ return { name: NAME, status: 'pass', message: `Node ${nodeVersion}: ${copies.length} better-sqlite3 cop${copies.length === 1 ? 'y' : 'ies'} checked, none built against 24.19+ headers` };
+ }
+ return {
+ name: NAME,
+ status: 'warn',
+ message: `Node ${nodeVersion} can abort ("Assertion failed: (env) != nullptr", nodejs/node#65446) in: ${bad.join('; ')}`,
+ fix: FIX,
+ };
+}
diff --git a/v3/@claude-flow/cli/src/commands/doctor.ts b/v3/@claude-flow/cli/src/commands/doctor.ts
index 97eaa30d6b..4959ebb45f 100644
--- a/v3/@claude-flow/cli/src/commands/doctor.ts
+++ b/v3/@claude-flow/cli/src/commands/doctor.ts
@@ -12,6 +12,7 @@ import { join, dirname } from 'path';
import { fileURLToPath, pathToFileURL } from 'url';
import { createHash } from 'crypto';
import { ownInstallAncestors } from '../plugins/own-install.js';
+import { checkNativeAddonHeaders } from './doctor-native-addon.js';
import { execSync, exec, execFile } from 'child_process';
import { promisify } from 'util';
import { decodeKey, isEncryptionEnabled } from '../encryption/vault.js';
@@ -2669,6 +2670,7 @@ export const doctorCommand: Command = {
checkMemoryCritiqueCoverage, // #2677 check 6: feedback carries lessons
]; },
'memory-package': checkMemoryPackageVersion, // #3392
+ 'native-addon': () => checkNativeAddonHeaders(), // #4055
'learning': checkLearningBridge, // #2545
'learning-bridge': checkLearningBridge, // #2545
'api': checkApiKeys,
@@ -2794,6 +2796,7 @@ export const doctorCommand: Command = {
checkMemoryPersistenceDriver, // #2968/#3321 β€” read-only native capability probe
checkLearningBridge, // #2545 β€” can the auto-memory hook actually load @claude-flow/memory?
checkMemoryPackageVersion, // #3392 β€” loaded @claude-flow/memory must satisfy the CLI's declared range
+ () => checkNativeAddonHeaders(), // #4055 β€” better-sqlite3 built against Node 24.19+ headers on 24.19-24.21
checkApiKeys,
checkMcpServers,
checkMcpSchemaOverhead, // #2726 β€” fixed tools/list prompt cost