@claude-flow/cli 3.56.5 → 3.56.7

package/dist/src/commands/doctor-native-addon.js

@@ -0,0 +1,135 @@
+/**
+ * #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';
+const NAME = 'Native addon headers (Node 24)';
+function parse(v) {
+    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) {
+    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) {
+    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) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function listDir(path) {
+    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, maxDepth = 12) {
+    const found = new Set();
+    const add = (dir) => {
+        if (!existsSync(join(dir, 'package.json')))
+            return;
+        try {
+            found.add(realpathSync(dir));
+        }
+        catch { /* unreadable */ }
+    };
+    const scanNodeModules = (nm) => {
+        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();
+}
+const FIX = [
+    'Use a Node release that contains nodejs/node#65943 (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 = {}) {
+    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 = [];
+    for (const copy of copies) {
+        let gypi;
+        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,
+    };
+}
+//# sourceMappingURL=doctor-native-addon.js.map

package/dist/src/commands/doctor.js

@@ -10,6 +10,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';
@@ -2607,6 +2608,7 @@ export const doctorCommand = {
                 ];
             },
             'memory-package': checkMemoryPackageVersion, // #3392
+            'native-addon': () => checkNativeAddonHeaders(), // #4055
             'learning': checkLearningBridge, // #2545
             'learning-bridge': checkLearningBridge, // #2545
             'api': checkApiKeys,
@@ -2722,6 +2724,7 @@ export const doctorCommand = {
             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

package/dist/src/commands/hooks.js

@@ -599,9 +599,16 @@ const postCommandCommand = {
                 ttl: ctx.flags.ttl,
                 timestamp: Date.now(),
             });
+            // #4056: recording switched off on purpose is not a failure.
+            const recordingOff = result.disabled === true;
             if (ctx.flags.format === 'json') {
                 output.printJson(result);
-                return { success: result.recorded, exitCode: result.recorded ? 0 : 1, data: result };
+                const ok = result.recorded || recordingOff;
+                return { success: ok, exitCode: ok ? 0 : 1, data: result };
+            }
+            if (recordingOff) {
+                output.printInfo('Command recording is switched off (CLAUDE_FLOW_HOOKS_RECORD_COMMANDS / CLAUDE_FLOW_HOOKS_ENABLED / hooks.recordCommands); nothing was stored.');
+                return { success: true, data: result };
             }
             if (!result.recorded) {
                 output.printError('Command outcome could not be recorded');

package/dist/src/commands/index.js

@@ -90,6 +90,8 @@ const commandLoaders = {
     spinner: () => import('./spinner.js'),
     // ruflo as a Claude Code mod: function hooks, early access (ADR-404)
     mods: () => import('./mods.js'),
+    // ADR-489: the console in a terminal of its own (read-only Overview and Cost); loads a bundle from this CLI's own install.
+    tui: () => import('./tui.js'),
     // ADR-406 command catalog and mission control (interim homes until mods.ts follow-up)
     catalog: () => import('./catalog.js'),
     mission: () => import('./mission.js'),

package/dist/src/commands/init.d.ts

@@ -3,10 +3,12 @@
  * Comprehensive initialization for Claude Flow with Claude Code integration
  */
 import type { Command } from '../types.js';
+export declare function readCodexTrustFlag(flags: Record<string, unknown>): 'standard' | 'full' | undefined | null;
 export declare function runCodexInitializerCli(cwd: string, options: {
     template: string;
     force: boolean;
     dual: boolean;
+    codexTrust?: 'standard' | 'full';
 }): boolean;
 export declare const initCommand: Command;
 export default initCommand;

package/dist/src/commands/init.js

@@ -76,6 +76,15 @@ async function resolveCodexInitializer(cwd) {
     }
     return undefined;
 }
+// Trust level for a newly generated .codex/config.toml. Safe by default: only
+// an explicit `--codex-trust full` (or RUFLO_CODEX_TRUST=full, read by the
+// adapter) restores danger-full-access. Anything else is rejected here.
+export function readCodexTrustFlag(flags) {
+    const raw = flags.codexTrust ?? flags['codex-trust'];
+    if (raw === undefined || raw === null || raw === false || raw === '')
+        return undefined;
+    return raw === 'standard' || raw === 'full' ? raw : null;
+}
 // Keep Codex out of the CLI dependency graph so cold `npx ruflo --version`
 // remains fast (#2561). An explicit `init --codex` may fetch the small,
 // stable adapter on demand when it is not already installed by an umbrella
@@ -89,6 +98,7 @@ export function runCodexInitializerCli(cwd, options) {
         options.template,
         ...(options.force ? ['--force'] : []),
         ...(options.dual ? ['--dual'] : []),
+        ...(options.codexTrust ? ['--codex-trust', options.codexTrust] : []),
     ];
     const result = process.platform === 'win32'
         ? spawnSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', ['npx', ...npxArgs].join(' ')], { cwd, stdio: 'inherit', windowsHide: true })
@@ -106,6 +116,7 @@ export function runCodexInitializerCli(cwd, options) {
 // init) and scripted `--format json` output.
 async function maybeAutoDetectCodex(ctx, options) {
     try {
+        const codexTrust = readCodexTrustFlag(ctx.flags) ?? undefined;
         // The CLI parser turns `--no-codex-detect` into `codexDetect: false`.
         // Retain the literal key for programmatic CommandContext callers.
         if (ctx.flags.codexDetect === false || ctx.flags['no-codex-detect'] === true)
@@ -127,6 +138,7 @@ async function maybeAutoDetectCodex(ctx, options) {
             template: (options.minimal ? 'minimal' : options.full ? 'full' : 'default'),
             force: options.force,
             dual: false, // Claude Code files were already written by the main init flow above
+            codexTrust,
         });
         if (!result.success)
             return; // best-effort — never fail the primary init over this
@@ -352,6 +364,11 @@ async function maybeInstallSkillsSh(ctx) {
 // Codex initialization action
 async function initCodexAction(ctx, options) {
     const { force, minimal, full, dualMode } = options;
+    const codexTrust = readCodexTrustFlag(ctx.flags);
+    if (codexTrust === null) {
+        output.printError(`Invalid --codex-trust: ${String(ctx.flags.codexTrust ?? ctx.flags['codex-trust'])} (valid: standard, full)`);
+        return { success: false, exitCode: 1 };
+    }
     output.writeln();
     output.writeln(output.bold('Initializing RuFlo V3 for OpenAI Codex'));
     output.writeln();
@@ -364,7 +381,7 @@ async function initCodexAction(ctx, options) {
         if (!CodexInitializer) {
             spinner.stop();
             output.printInfo('Fetching the stable Codex adapter for this initialization...');
-            const success = runCodexInitializerCli(ctx.cwd, { template, force, dual: dualMode });
+            const success = runCodexInitializerCli(ctx.cwd, { template, force, dual: dualMode, codexTrust });
             if (!success) {
                 output.printError('Codex initialization failed while running @claude-flow/codex@latest.');
                 return { success: false, exitCode: 1 };
@@ -377,6 +394,7 @@ async function initCodexAction(ctx, options) {
             template: template,
             force,
             dual: dualMode,
+            codexTrust,
         });
         if (!result.success) {
             spinner.fail('Codex initialization failed');
@@ -404,14 +422,23 @@ async function initCodexAction(ctx, options) {
             dualMode ? `CLAUDE.md: Claude Code compatibility` : '',
         ].filter(Boolean).join('\n'), 'OpenAI Codex Integration');
         output.writeln();
+        // The trust level of .codex/config.toml is always shown (never truncated
+        // behind other warnings): it decides what Codex may do without asking.
+        const isTrustNote = (w) => w.startsWith('.codex/config.toml');
+        const trustNotes = (result.warnings ?? []).filter(isTrustNote);
+        for (const note of trustNotes)
+            output.printInfo(note);
+        if (trustNotes.length > 0)
+            output.writeln();
         // Warnings
-        if (result.warnings && result.warnings.length > 0) {
+        const otherWarnings = (result.warnings ?? []).filter((w) => !isTrustNote(w));
+        if (otherWarnings.length > 0) {
             output.printWarning('Warnings:');
-            for (const warning of result.warnings.slice(0, 5)) {
+            for (const warning of otherWarnings.slice(0, 5)) {
                 output.printInfo(`  • ${warning}`);
             }
-            if (result.warnings.length > 5) {
-                output.printInfo(`  ... and ${result.warnings.length - 5} more`);
+            if (otherWarnings.length > 5) {
+                output.printInfo(`  ... and ${otherWarnings.length - 5} more`);
             }
             output.writeln();
         }
@@ -1577,6 +1604,11 @@ export const initCommand = {
             type: 'boolean',
             default: false,
         },
+        {
+            name: 'codex-trust',
+            description: 'Trust level of the generated .codex/config.toml: standard (default: workspace-write sandbox, on-request approvals, cached web search) or full (danger-full-access, no approvals, live web search). An existing file is never rewritten',
+            type: 'string',
+        },
         {
             name: 'no-codex-detect',
             description: 'Skip auto-detecting the OpenAI Codex CLI and configuring its MCP server + skills',

package/dist/src/commands/mods.d.ts

@@ -8,6 +8,9 @@
  * are never removed: they stay the default and the fallback.
  */
 import type { Command } from '../types.js';
+import { type Finding } from '../mods/probe.js';
+/** The doctor's exit gate: a failure always fails; with --strict a warning does too. */
+export declare function hasFailureOrStrictWarning(findings: readonly Finding[], strict: boolean): boolean;
 export declare const modsCommand: Command;
 export default modsCommand;
 //# sourceMappingURL=mods.d.ts.map

package/dist/src/commands/mods.js

@@ -105,19 +105,32 @@ const uninstallSub = {
         return { success: result.failed.length === 0, exitCode: result.failed.length ? 1 : 0, data: result };
     },
 };
+/** The doctor's exit gate: a failure always fails; with --strict a warning does too. */
+export function hasFailureOrStrictWarning(findings, strict) {
+    return findings.some((f) => f.status === 'fail' || (strict && f.status === 'warn'));
+}
 function findingsCommand(name, description) {
     return {
         name,
         description,
-        options: [rootOption, { name: 'json', description: 'Output as JSON', type: 'boolean', default: false }],
+        options: [
+            rootOption,
+            { name: 'json', description: 'Output as JSON', type: 'boolean', default: false },
+            ...(name === 'doctor' ? [{ name: 'strict', description: 'Exit 1 on a warning too (a mod that is not fully loaded is a failure for a CI gate)', type: 'boolean', default: false }] : []),
+        ],
         action: async (ctx) => {
             const findings = probeMods({ projectRoot: projectRoot(ctx) });
             if (ctx.flags.json)
                 output.printJson(findings);
             else
                 printFindings(findings);
-            const failed = findings.some((f) => f.status === 'fail');
-            // status reports (exit 0); doctor gates on a failure (warnings are expected while early access is off).
+            const strict = name === 'doctor' && ctx.flags.strict === true;
+            const failed = hasFailureOrStrictWarning(findings, strict);
+            if (failed && !ctx.flags.json) {
+                const first = findings.find((f) => f.status === 'fail') ?? findings.find((f) => f.status === 'warn');
+                output.writeln(output.error(`doctor: ${findings.filter((f) => f.status === 'fail').length} failure(s), ${findings.filter((f) => f.status === 'warn').length} warning(s)${first?.fix ? `; start with: ${first.fix}` : ''}`));
+            }
+            // status reports (exit 0); doctor gates on a failure, and with --strict on a warning.
             return name === 'doctor' && failed ? { success: false, exitCode: 1, data: findings } : { success: true, data: findings };
         },
     };
@@ -153,7 +166,7 @@ export const modsCommand = {
         installSub,
         uninstallSub,
         statusSub,
-        findingsCommand('doctor', 'Check the mod path; exits 1 only on a failure'),
+        findingsCommand('doctor', 'Check the mod path; exits 1 on a failure (--strict: on a warning too)'),
         syncPolicySub,
     ],
     examples: [
@@ -161,7 +174,8 @@ export const modsCommand = {
         { command: 'ruflo mods install --scope project', description: 'Same, in the committed settings.json (what ruflo init does)' },
         { command: 'ruflo mods install --no-plugin-install', description: 'Only write settings; run no claude command' },
         { command: 'ruflo mods install --source local', description: 'Dogfood: load the mods live from this ruflo checkout (directory marketplace)' },
-        { command: 'ruflo mods doctor', description: 'Marketplace fresh? Plugins loadable? Function hooks on? Refused by policy?' },
+        { command: 'ruflo mods doctor', description: 'Marketplace fresh? Plugins loadable? Function hooks on? Refused by policy? Each problem prints a one-line fix' },
+        { command: 'ruflo mods doctor --strict', description: 'Same, and exit 1 when anything is not fully working (for CI)' },
         { command: 'ruflo mods uninstall', description: 'Remove only what install added' },
     ],
     action: statusSub.action,

package/dist/src/commands/tui.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from '../types.js';
+/** `<own install>/plugins/ruflo-console/dist/tui.mjs`, the first that exists. */
+export declare function locateTuiBundle(startDir?: string): string | null;
+/** The AI page's settings from the flags (and one environment variable for the endpoint list). Absent flags leave the defaults; a bad number is ignored, never passed on. */
+export declare function aiPage(flags: Record<string, unknown> | undefined): {
+    model?: string;
+    maxSpendUsd?: number;
+    convoTargets?: string;
+};
+export declare const tuiCommand: Command;
+export default tuiCommand;
+//# sourceMappingURL=tui.d.ts.map

package/dist/src/commands/tui.js

@@ -0,0 +1,98 @@
+/**
+ * `ruflo tui` — the ruflo console in a terminal of its own (ADR-489).
+ *
+ * Runs the same views the Claude Code mod (plugins/ruflo-console) draws, over a Node host instead of the mod host. Read-only in
+ * the pages: Overview, Cost, Swarm, Events and Missions are read-only; AI (key 6) asks Codex (read-only, the pinned 0.162.0) or OpenRouter
+ * (https, openrouter.ai or a convoTargets host), and every question shows a card first. The bundle is built from the plugin's source (scripts/build-tui.mjs) and loaded from this
+ * CLI's OWN install only (never from the working directory: opening a repository must not run code that repository supplies).
+ * No bundle is a message and exit 1, never a crash; ruflo stays operational without it. Without a terminal (a pipe, CI) the live view cannot run:
+ * a one-line hint and exit 2, unless --plain asks for one frame as plain text and exit 0 (ADR-489 decision E).
+ *
+ *   npx ruflo tui                 # interactive, in a terminal
+ *   npx ruflo tui --view swarm    # start on the Swarm page (keys 1-5 or o c s e m switch pages)
+ *   npx ruflo tui --plain | head  # one plain frame, exit 0 (scripts, CI)
+ *   npx ruflo tui | cat           # not a terminal and no --plain: a hint on stderr, exit 2
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { output } from '../output.js';
+import { ownPluginDirs } from '../plugins/own-install.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VIEWS = ['overview', 'cost', 'swarm', 'events', 'missions', 'ai'];
+/** `<own install>/plugins/ruflo-console/dist/tui.mjs`, the first that exists. */
+export function locateTuiBundle(startDir = __dirname) {
+    for (const dir of ownPluginDirs(startDir, 'ruflo-console', 'dist')) {
+        const file = join(dir, 'tui.mjs');
+        if (existsSync(file))
+            return file;
+    }
+    return null;
+}
+/** The running CLI's entry file, so the console's read-only probes run this CLI and never download another. */
+function cliEntry() {
+    const entry = join(__dirname, '..', '..', '..', 'bin', 'cli.js');
+    return existsSync(entry) ? entry : undefined;
+}
+/** The AI page's settings from the flags (and one environment variable for the endpoint list). Absent flags leave the defaults; a bad number is ignored, never passed on. */
+export function aiPage(flags) {
+    const model = typeof flags?.model === 'string' && flags.model !== '' ? flags.model : undefined;
+    const cap = flags?.maxSpendUsd ?? flags?.['max-spend-usd'];
+    const maxSpendUsd = typeof cap === 'number' && Number.isFinite(cap) && cap >= 0 ? cap : typeof cap === 'string' && /^\d+(\.\d+)?$/.test(cap) ? Number(cap) : undefined;
+    const targets = flags?.convoTargets ?? flags?.['convo-targets'] ?? process.env.RUFLO_TUI_CONVO_TARGETS;
+    return { ...(model !== undefined && { model }), ...(maxSpendUsd !== undefined && { maxSpendUsd }), ...(typeof targets === 'string' && targets !== '' && { convoTargets: targets.slice(0, 2000) }) };
+}
+export const tuiCommand = {
+    name: 'tui',
+    description: 'The ruflo console in your terminal: Overview, Cost, Swarm, Events, Missions (read-only) and an AI page that asks Codex or OpenRouter, each question after a card.',
+    options: [
+        { name: 'view', description: `Page to open: ${VIEWS.join(' | ')}`, type: 'string', default: 'overview' },
+        { name: 'ai', description: 'The AI page (ask Codex read-only or OpenRouter, each question after a confirm card). --no-ai turns it off', type: 'boolean', default: true },
+        { name: 'model', description: 'OpenRouter model for this session (default openrouter/auto)', type: 'string' },
+        { name: 'max-spend-usd', description: 'Stop sending to OpenRouter once the provider-reported spend reaches this (default 0.5)', type: 'number' },
+        { name: 'convo-targets', description: 'Extra OpenAI-compatible endpoints, the console convoTargets syntax: endpoint:<name>=<https-base-url>|<KEY_ENV>|<model>;... (a key is named by its environment variable). Also RUFLO_TUI_CONVO_TARGETS', type: 'string' },
+        { name: 'plain', description: 'Print one frame as plain text and exit 0 (scripts and CI). Without it, a non-terminal gets a hint and exit 2', type: 'boolean', default: false },
+    ],
+    examples: [
+        { command: 'npx ruflo tui', description: 'Open the console in this terminal' },
+        { command: 'npx ruflo tui --view swarm', description: 'Start on the Swarm page (keys 1-5 switch pages, tab cycles, q quits)' },
+        { command: 'npx ruflo tui --view ai --model openai/gpt-4o-mini --max-spend-usd 0.1', description: 'The AI page on a cheap OpenRouter model, stopping at $0.10 reported (key in $OPENROUTER_API_KEY, never shown)' },
+        { command: 'npx ruflo tui --plain | head -40', description: 'One plain frame, exit 0: for scripts and CI (no terminal needed)' },
+    ],
+    async action(context) {
+        const ctx = context;
+        const wanted = ctx.flags?.view ?? ctx.args?.find(arg => !arg.startsWith('-')) ?? 'overview';
+        if (!VIEWS.includes(wanted)) {
+            output.writeln(output.error(`tui: unknown view "${String(wanted).slice(0, 40)}". Use one of: ${VIEWS.join(', ')}`));
+            return { success: false, exitCode: 2, data: { error: 'unknown-view' } };
+        }
+        const bundle = locateTuiBundle();
+        if (bundle === null) {
+            output.writeln(output.warning('tui: the terminal console is not available in this install (plugins/ruflo-console/dist/tui.mjs not found).'));
+            output.writeln('From a ruflo checkout: node plugins/ruflo-console/scripts/build-tui.mjs');
+            return { success: false, exitCode: 1, data: { error: 'bundle-missing' } };
+        }
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(bundle).href));
+        }
+        catch (error) {
+            output.writeln(output.error(`tui: could not load the console bundle: ${error instanceof Error ? error.message.slice(0, 160) : 'unknown error'}`));
+            return { success: false, exitCode: 1, data: { error: 'bundle-load-failed' } };
+        }
+        const stop = new AbortController();
+        const onSignal = () => stop.abort();
+        process.once('SIGTERM', onSignal);
+        process.once('SIGHUP', onSignal);
+        try {
+            const code = await mod.runTui({ cwd: ctx.cwd ?? process.cwd(), view: wanted, ...(ctx.flags?.plain === true && { plain: true }), ...(ctx.flags?.ai !== false && { aiPage: aiPage(ctx.flags) }), ...(cliEntry() !== undefined && { cliEntry: cliEntry() }), ...(process.env.CLAUDE_CONFIG_DIR !== undefined && { configDir: process.env.CLAUDE_CONFIG_DIR }) }, { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, env: process.env, signal: stop.signal });
+            return { success: code === 0, exitCode: code };
+        }
+        finally {
+            process.off('SIGTERM', onSignal);
+            process.off('SIGHUP', onSignal);
+        }
+    },
+};
+export default tuiCommand;
+//# sourceMappingURL=tui.js.map

package/dist/src/fs-secure.d.ts

@@ -66,6 +66,31 @@ export interface WriteOptions {
  *   writeFileRestricted(path, data, { encrypt: true })   // opt-in encryption
  */
 export declare function writeFileRestricted(path: string, data: string | Buffer, optsOrEncoding?: BufferEncoding | WriteOptions): void;
+/**
+ * The at-rest format of an existing database file: `true` = RFE1-encrypted,
+ * `false` = plaintext, `null` = missing or unreadable (nothing to preserve).
+ * Reads four bytes only.
+ */
+export declare function existingFileIsEncrypted(path: string): boolean | null;
+/**
+ * Write a whole-file database image back in the format it was read in (#4057).
+ *
+ * A read-modify-write of a database image (sql.js loads the file, mutates it,
+ * exports it) must not change what the file IS. With encryption at rest on, a
+ * plain `{ encrypt: true }` write turned a plaintext native SQLite store into
+ * an RFE1 blob that the native bridge and every SQLite reader then rejected,
+ * while the command reported success. And the reverse, a plain
+ * `writeFileAtomic` of a decrypted image, silently downgraded an encrypted
+ * store to plaintext.
+ *
+ *   existing file RFE1      -> RFE1 (encrypted)
+ *   existing file plaintext -> plaintext
+ *   no existing file        -> `encrypt` (default true: the env gate decides)
+ *   `encrypt: false`        -> plaintext, always (explicit caller choice)
+ */
+export declare function writeDbImagePreservingFormat(path: string, data: Uint8Array | Buffer, opts?: {
+    encrypt?: boolean;
+}): void;
 /**
  * Read a file and transparently decrypt if it carries the RFE1 magic.
  *

package/dist/src/fs-secure.js

@@ -16,9 +16,9 @@
  * sniff so legacy plaintext files keep working unchanged during the
  * incremental migration.
  */
-import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
+import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { decryptBuffer, encryptBuffer, getKey, isEncryptedBlob, isEncryptionEnabled, } from './encryption/vault.js';
+import { decryptBuffer, encryptBuffer, getKey, isEncryptedBlob, isEncryptionEnabled, MAGIC, } from './encryption/vault.js';
 /**
  * Crash-safe atomic file write (issue #2584).
  *
@@ -119,6 +119,55 @@ export function writeFileRestricted(path, data, optsOrEncoding = 'utf-8') {
     const buf = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, encoding);
     writeFileAtomic(path, buf, { mode: 0o600 });
 }
+/**
+ * The at-rest format of an existing database file: `true` = RFE1-encrypted,
+ * `false` = plaintext, `null` = missing or unreadable (nothing to preserve).
+ * Reads four bytes only.
+ */
+export function existingFileIsEncrypted(path) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        const head = Buffer.alloc(4);
+        const n = readSync(fd, head, 0, 4, 0);
+        if (n < 4)
+            return null;
+        return head.equals(MAGIC);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+/**
+ * Write a whole-file database image back in the format it was read in (#4057).
+ *
+ * A read-modify-write of a database image (sql.js loads the file, mutates it,
+ * exports it) must not change what the file IS. With encryption at rest on, a
+ * plain `{ encrypt: true }` write turned a plaintext native SQLite store into
+ * an RFE1 blob that the native bridge and every SQLite reader then rejected,
+ * while the command reported success. And the reverse, a plain
+ * `writeFileAtomic` of a decrypted image, silently downgraded an encrypted
+ * store to plaintext.
+ *
+ *   existing file RFE1      -> RFE1 (encrypted)
+ *   existing file plaintext -> plaintext
+ *   no existing file        -> `encrypt` (default true: the env gate decides)
+ *   `encrypt: false`        -> plaintext, always (explicit caller choice)
+ */
+export function writeDbImagePreservingFormat(path, data, opts = {}) {
+    const requested = opts.encrypt ?? true;
+    const existing = existingFileIsEncrypted(path);
+    const encrypt = requested === false ? false : (existing ?? requested);
+    writeFileRestricted(path, Buffer.isBuffer(data) ? data : Buffer.from(data), { encrypt });
+}
 export function readFileMaybeEncrypted(path, encoding = 'utf-8') {
     const raw = readFileSync(path);
     let plain;

package/dist/src/init/executor.js

@@ -20,7 +20,7 @@ import { generateClaudeMd } from './claudemd-generator.js';
 import { recordMemoryPackagePath } from './memory-package-resolver.js';
 import { ensureCommonJsCompanions } from './helper-companions.js';
 import { scanSettingsForRisk, formatRiskFindingsAsWarnings } from './settings-risk-scanner.js';
-import { helperHookCommand, helperScopeFor, helperStatusLineCommand, pinToUserHelpers } from './helper-commands.js';
+import { AUTO_MEMORY_HOOK_TIMEOUT_S, helperHookCommand, helperScopeFor, helperStatusLineCommand, pinToUserHelpers } from './helper-commands.js';
 /**
  * Skills to copy based on configuration
  */
@@ -307,18 +307,15 @@ export function mergeSettingsForUpgrade(existing, targetDir) {
     // 2. Merge hooks (preserve existing, add new Agent Teams + auto-memory hooks)
     const existingHooks = existing.hooks || {};
     merged.hooks = { ...existingHooks };
-    // Cross-platform auto-memory hook commands that resolve paths via git root.
-    // Uses node -e with git rev-parse so hooks work regardless of CWD (#1259, #1284).
-    const gitRootResolver = "var c=require('child_process'),p=require('path'),u=require('url'),r;"
-        + "try{r=c.execSync('git rev-parse --show-toplevel',{encoding:'utf8'}).trim()}"
-        + 'catch(e){r=process.cwd()}';
+    // Auto-memory hook commands. They go through helperHookCommand like every other
+    // helper hook (#4058): the previous `node -e "…import(file)" import` form left the
+    // subcommand in process.argv[1], the helper read argv[2], and both hooks only
+    // printed the status banner. Hooks run in the project directory with
+    // CLAUDE_PROJECT_DIR set, so the shared probe resolves the helper without a
+    // `git rev-parse` of its own.
     const autoMemoryScript = '.claude/helpers/auto-memory-hook.mjs';
-    const autoMemoryImportCmd = scope === 'user'
-        ? helperHookCommand(autoMemoryScript, 'import', 'user')
-        : `node -e "${gitRootResolver}var f=p.join(r,'${autoMemoryScript}');import(u.pathToFileURL(f).href)" import`;
-    const autoMemorySyncCmd = scope === 'user'
-        ? helperHookCommand(autoMemoryScript, 'sync', 'user')
-        : `node -e "${gitRootResolver}var f=p.join(r,'${autoMemoryScript}');import(u.pathToFileURL(f).href)" sync`;
+    const autoMemoryImportCmd = helperHookCommand(autoMemoryScript, 'import', scope);
+    const autoMemorySyncCmd = helperHookCommand(autoMemoryScript, 'sync', scope);
     // Add auto-memory import to SessionStart (if not already present)
     const sessionStartHooks = existingHooks.SessionStart;
     const hasAutoMemoryImport = sessionStartHooks?.some(group => group.hooks?.some(h => h.command?.includes('auto-memory-hook')));
@@ -333,7 +330,7 @@ export function mergeSettingsForUpgrade(existing, targetDir) {
         startGroup.hooks.push({
             type: 'command',
             command: autoMemoryImportCmd,
-            timeout: 6000,
+            timeout: AUTO_MEMORY_HOOK_TIMEOUT_S,
             continueOnError: true,
         });
     }
@@ -352,7 +349,7 @@ export function mergeSettingsForUpgrade(existing, targetDir) {
         endGroup.hooks.unshift({
             type: 'command',
             command: autoMemorySyncCmd,
-            timeout: 8000,
+            timeout: AUTO_MEMORY_HOOK_TIMEOUT_S,
             continueOnError: true,
         });
     }