π 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
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.mdindex 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).+### FixedBatch 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.mdindex 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 memorynpx 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 probecheckLearningBridge, // #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.21checkApiKeys,checkMcpServers,checkMcpSchemaOverhead, // #2726 β fixed tools/list prompt cost