@claude-flow/cli 3.56.6 → 3.56.8

package/dist/src/commands/coverage-reader.js

@@ -0,0 +1,247 @@
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** Coverage reports are build output the project controls: refuse anything large enough to stall or exhaust the process. */
+const MAX_REPORT_BYTES = 64 * 1024 * 1024;
+/** The file's text, or undefined when it is missing, not a regular file, unreadable, or over the size cap. */
+function readReport(path) {
+    try {
+        const stat = statSync(path);
+        if (!stat.isFile() || stat.size > MAX_REPORT_BYTES)
+            return undefined;
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read coverage data from disk. Checks these locations in order:
+ * 1. coverage/coverage-summary.json (Jest/Istanbul)
+ * 2. coverage/lcov.info (lcov format)
+ * 3. coverage/coverage-final.json (Istanbul counters)
+ * 4. .nyc_output/out.json (nyc counters or legacy summary)
+ */
+export function readCoverageFromDisk() {
+    const cwd = process.cwd();
+    const noData = {
+        found: false,
+        source: 'none',
+        entries: [],
+        summary: { totalFiles: 0, overallLineCoverage: 0, overallBranchCoverage: 0, overallFunctionCoverage: 0, overallStatementCoverage: 0 },
+    };
+    // 1. Try coverage-summary.json (Jest/Istanbul)
+    for (const relPath of ['coverage/coverage-summary.json', 'coverage-summary.json']) {
+        const text = readReport(join(cwd, relPath));
+        if (text !== undefined) {
+            try {
+                const raw = JSON.parse(text);
+                const report = parseCoverageSummaryJson(raw, relPath);
+                if (report.found)
+                    return report;
+            }
+            catch {
+                // malformed, try next
+            }
+        }
+    }
+    // 2. Try lcov.info
+    for (const relPath of ['coverage/lcov.info', 'lcov.info']) {
+        const raw = readReport(join(cwd, relPath));
+        if (raw !== undefined) {
+            try {
+                const report = parseLcovInfo(raw, relPath);
+                if (report.found)
+                    return report;
+            }
+            catch {
+                // malformed, try next
+            }
+        }
+    }
+    // Istanbul's raw counter map (Jest, Vitest, nyc).
+    for (const relPath of ['coverage/coverage-final.json', 'coverage-final.json', '.nyc_output/out.json']) {
+        const text = readReport(join(cwd, relPath));
+        if (text === undefined)
+            continue;
+        try {
+            const raw = JSON.parse(text);
+            const report = parseIstanbulCoverage(raw, relPath);
+            if (report.found)
+                return report;
+            const legacy = parseCoverageSummaryJson(raw, relPath);
+            if (legacy.found)
+                return legacy;
+        }
+        catch {
+            // Missing or malformed, try the next supported report.
+        }
+    }
+    return noData;
+}
+function parseCoverageSummaryJson(data, source) {
+    const entries = [];
+    const metricsByFile = [];
+    for (const [filePath, metrics] of Object.entries(data)) {
+        if (filePath === 'total')
+            continue;
+        const m = metrics;
+        if (!m || typeof m !== 'object')
+            continue;
+        if (!['lines', 'branches', 'functions', 'statements'].some(key => m[key]))
+            continue;
+        metricsByFile.push(m);
+        const linePct = percentage(m.lines) ?? 0;
+        const branchPct = (percentage(m.branches) ?? 0);
+        const funcPct = (percentage(m.functions) ?? 0);
+        const stmtPct = (percentage(m.statements) ?? 0);
+        entries.push({ filePath, lines: linePct, branches: branchPct, functions: funcPct, statements: stmtPct });
+    }
+    // Only aggregate complete counts. A missing denominator is unknown, not empty.
+    const total = data['total'];
+    const aggregate = (key) => {
+        const supplied = percentage(total?.[key]);
+        if (supplied !== undefined)
+            return supplied;
+        const metrics = metricsByFile.map(file => file[key]);
+        if (metrics.length === 0 || !metrics.every(hasCounts))
+            return 0;
+        return ratio(metrics.reduce((sum, m) => sum + m.covered, 0), metrics.reduce((sum, m) => sum + m.total, 0));
+    };
+    // Sort by lowest line coverage
+    entries.sort((a, b) => a.lines - b.lines);
+    return {
+        found: entries.length > 0,
+        source,
+        entries,
+        summary: {
+            totalFiles: entries.length,
+            overallLineCoverage: aggregate('lines'),
+            overallBranchCoverage: aggregate('branches'),
+            overallFunctionCoverage: aggregate('functions'),
+            overallStatementCoverage: aggregate('statements'),
+        },
+    };
+}
+function parseLcovInfo(raw, source) {
+    const entries = [];
+    let currentFile = '';
+    let linesHit = 0, linesFound = 0;
+    let branchesHit = 0, branchesFound = 0;
+    let functionsHit = 0, functionsFound = 0;
+    let totalLH = 0, totalLF = 0, totalBH = 0, totalBF = 0, totalFH = 0, totalFF = 0;
+    const flushRecord = () => {
+        if (currentFile) {
+            // A corrupt record cannot report more hits than lines, or a negative count.
+            linesHit = Math.min(linesHit, linesFound);
+            branchesHit = Math.min(branchesHit, branchesFound);
+            functionsHit = Math.min(functionsHit, functionsFound);
+            totalLH += linesHit;
+            totalLF += linesFound;
+            totalBH += branchesHit;
+            totalBF += branchesFound;
+            totalFH += functionsHit;
+            totalFF += functionsFound;
+            entries.push({
+                filePath: currentFile,
+                lines: linesFound > 0 ? (linesHit / linesFound) * 100 : 100,
+                branches: branchesFound > 0 ? (branchesHit / branchesFound) * 100 : 100,
+                functions: functionsFound > 0 ? (functionsHit / functionsFound) * 100 : 100,
+                statements: linesFound > 0 ? (linesHit / linesFound) * 100 : 100,
+            });
+        }
+    };
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('SF:')) {
+            flushRecord();
+            currentFile = trimmed.slice(3);
+            linesHit = 0;
+            linesFound = 0;
+            branchesHit = 0;
+            branchesFound = 0;
+            functionsHit = 0;
+            functionsFound = 0;
+        }
+        else if (trimmed.startsWith('LH:')) {
+            linesHit = count(trimmed.slice(3));
+        }
+        else if (trimmed.startsWith('LF:')) {
+            linesFound = count(trimmed.slice(3));
+        }
+        else if (trimmed.startsWith('BRH:')) {
+            branchesHit = count(trimmed.slice(4));
+        }
+        else if (trimmed.startsWith('BRF:')) {
+            branchesFound = count(trimmed.slice(4));
+        }
+        else if (trimmed.startsWith('FNH:')) {
+            functionsHit = count(trimmed.slice(4));
+        }
+        else if (trimmed.startsWith('FNF:')) {
+            functionsFound = count(trimmed.slice(4));
+        }
+        else if (trimmed === 'end_of_record') {
+            flushRecord();
+            currentFile = '';
+        }
+    }
+    flushRecord();
+    entries.sort((a, b) => a.lines - b.lines);
+    return {
+        found: entries.length > 0,
+        source,
+        entries,
+        summary: {
+            totalFiles: entries.length,
+            overallLineCoverage: ratio(totalLH, totalLF),
+            overallBranchCoverage: ratio(totalBH, totalBF),
+            overallFunctionCoverage: ratio(totalFH, totalFF),
+            overallStatementCoverage: ratio(totalLH, totalLF),
+        },
+    };
+}
+/** A non-negative integer count; anything else in a report line is treated as 0. */
+function count(text) {
+    const n = parseInt(text, 10);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
+function ratio(covered, total) {
+    return total > 0 ? covered / total * 100 : 100;
+}
+function hasCounts(metric) {
+    return typeof metric?.total === 'number' && Number.isFinite(metric.total) && metric.total >= 0
+        && typeof metric.covered === 'number' && Number.isFinite(metric.covered)
+        && metric.covered >= 0 && metric.covered <= metric.total;
+}
+function percentage(metric) {
+    if (typeof metric?.pct === 'number' && Number.isFinite(metric.pct)
+        && metric.pct >= 0 && metric.pct <= 100)
+        return metric.pct;
+    return hasCounts(metric) ? ratio(metric.covered, metric.total) : undefined;
+}
+/** Istanbul line coverage uses the maximum statement hit count on each start line. */
+function parseIstanbulCoverage(data, source) {
+    const summary = {};
+    for (const [filePath, value] of Object.entries(data)) {
+        const cov = value;
+        if (!cov || !cov.s || !cov.f || !cov.b || !cov.statementMap)
+            continue;
+        const lines = new Map();
+        for (const [id, hits] of Object.entries(cov.s)) {
+            const line = cov.statementMap[id]?.start?.line;
+            if (!Number.isInteger(line) || line < 1)
+                throw new Error('Invalid Istanbul statement location');
+            lines.set(line, Math.max(lines.get(line) ?? 0, hits));
+        }
+        const metric = (hits) => {
+            if (hits.some(n => !Number.isFinite(n) || n < 0))
+                throw new Error('Invalid Istanbul counter');
+            const covered = hits.filter(n => n > 0).length;
+            return { total: hits.length, covered, pct: ratio(covered, hits.length) };
+        };
+        summary[filePath] = { lines: metric([...lines.values()]), statements: metric(Object.values(cov.s)),
+            functions: metric(Object.values(cov.f)), branches: metric(Object.values(cov.b).flat()) };
+    }
+    return parseCoverageSummaryJson(summary, source);
+}
+//# sourceMappingURL=coverage-reader.js.map

package/dist/src/commands/doctor-native-addon.d.ts

@@ -0,0 +1,23 @@
+export interface NativeAddonCheck {
+    name: string;
+    status: 'pass' | 'warn' | 'fail';
+    message: string;
+    fix?: string;
+}
+/** Node 24.19.0 up to, but not including, 24.22.0. Re-check this bound when a release ships the fix. */
+export declare function isAffectedNodeVersion(version: string): boolean;
+/** The Node version of the headers a copy was built against, from its config.gypi. */
+export declare function headersVersionFromGypi(gypi: string): string | null;
+/** `better-sqlite3` copies in node_modules next to, or one level under, each ancestor of the start dirs. */
+export declare function findBetterSqlite3Copies(startDirs: string[], maxDepth?: number): string[];
+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[];
+}
+/** Read-only: warn when a locally compiled better-sqlite3 was built against Node >= 24.19 headers on an affected runtime. */
+export declare function checkNativeAddonHeaders(deps?: NativeAddonCheckDeps): Promise<NativeAddonCheck>;
+//# sourceMappingURL=doctor-native-addon.d.ts.map

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

@@ -1,10 +1,14 @@
+/**
+ * V3 CLI Hooks Command
+ * Self-learning hooks system for intelligent workflow automation
+ */
 import { validateFeedbackPatterns } from '../memory/feedback-patterns.js';
+import { readCoverageFromDisk } from './coverage-reader.js';
 import { output } from '../output.js';
 import { confirm } from '../prompt.js';
 import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { storeCommand } from './transfer-store.js';
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, statSync } from 'node:fs';
 import { getSecurityStatus as sharedGetSecurityStatus, getSwarmStatus as sharedGetSwarmStatus, getGitUncommittedCount as sharedGetGitUncommittedCount, } from '../funnel/local-signals.js';
 /**
  * #1686 — `?? 0` only defaults null/undefined; NaN slips through and
@@ -16,181 +20,6 @@ function safeNum(value, fallback = 0) {
     const n = typeof value === 'number' ? value : Number(value);
     return Number.isFinite(n) ? n : fallback;
 }
-/**
- * Read coverage data from disk. Checks these locations in order:
- * 1. coverage/coverage-summary.json (Jest/Istanbul)
- * 2. coverage/lcov.info (lcov format)
- * 3. .nyc_output/out.json (nyc)
- */
-function readCoverageFromDisk() {
-    const cwd = process.cwd();
-    const noData = {
-        found: false,
-        source: 'none',
-        entries: [],
-        summary: { totalFiles: 0, overallLineCoverage: 0, overallBranchCoverage: 0, overallFunctionCoverage: 0, overallStatementCoverage: 0 },
-    };
-    // 1. Try coverage-summary.json (Jest/Istanbul)
-    for (const relPath of ['coverage/coverage-summary.json', 'coverage-summary.json']) {
-        const summaryPath = join(cwd, relPath);
-        if (existsSync(summaryPath)) {
-            try {
-                const raw = JSON.parse(readFileSync(summaryPath, 'utf-8'));
-                return parseCoverageSummaryJson(raw, relPath);
-            }
-            catch {
-                // malformed, try next
-            }
-        }
-    }
-    // 2. Try lcov.info
-    for (const relPath of ['coverage/lcov.info', 'lcov.info']) {
-        const lcovPath = join(cwd, relPath);
-        if (existsSync(lcovPath)) {
-            try {
-                const raw = readFileSync(lcovPath, 'utf-8');
-                return parseLcovInfo(raw, relPath);
-            }
-            catch {
-                // malformed, try next
-            }
-        }
-    }
-    // 3. Try .nyc_output/out.json
-    const nycPath = join(cwd, '.nyc_output', 'out.json');
-    if (existsSync(nycPath)) {
-        try {
-            const raw = JSON.parse(readFileSync(nycPath, 'utf-8'));
-            return parseCoverageSummaryJson(raw, '.nyc_output/out.json');
-        }
-        catch {
-            // malformed
-        }
-    }
-    return noData;
-}
-function parseCoverageSummaryJson(data, source) {
-    const entries = [];
-    let totalLines = 0, coveredLines = 0;
-    let totalBranches = 0, coveredBranches = 0;
-    let totalFunctions = 0, coveredFunctions = 0;
-    let totalStatements = 0, coveredStatements = 0;
-    for (const [filePath, metrics] of Object.entries(data)) {
-        if (filePath === 'total')
-            continue;
-        const m = metrics;
-        if (!m || typeof m !== 'object')
-            continue;
-        const linePct = m.lines?.pct ?? m.lines?.covered != null ? ((m.lines?.covered ?? 0) / Math.max(m.lines?.total ?? 1, 1)) * 100 : 0;
-        const branchPct = m.branches?.pct ?? (m.branches?.total ? ((m.branches?.covered ?? 0) / m.branches.total) * 100 : 100);
-        const funcPct = m.functions?.pct ?? (m.functions?.total ? ((m.functions?.covered ?? 0) / m.functions.total) * 100 : 100);
-        const stmtPct = m.statements?.pct ?? (m.statements?.total ? ((m.statements?.covered ?? 0) / m.statements.total) * 100 : 100);
-        entries.push({ filePath, lines: linePct, branches: branchPct, functions: funcPct, statements: stmtPct });
-        totalLines += m.lines?.total ?? 0;
-        coveredLines += m.lines?.covered ?? 0;
-        totalBranches += m.branches?.total ?? 0;
-        coveredBranches += m.branches?.covered ?? 0;
-        totalFunctions += m.functions?.total ?? 0;
-        coveredFunctions += m.functions?.covered ?? 0;
-        totalStatements += m.statements?.total ?? 0;
-        coveredStatements += m.statements?.covered ?? 0;
-    }
-    // Also read the total key if present
-    const total = data['total'];
-    const overallLine = total?.lines?.pct ?? (totalLines > 0 ? (coveredLines / totalLines) * 100 : 0);
-    const overallBranch = total?.branches?.pct ?? (totalBranches > 0 ? (coveredBranches / totalBranches) * 100 : 0);
-    const overallFunction = total?.functions?.pct ?? (totalFunctions > 0 ? (coveredFunctions / totalFunctions) * 100 : 0);
-    const overallStatement = total?.statements?.pct ?? (totalStatements > 0 ? (coveredStatements / totalStatements) * 100 : 0);
-    // Sort by lowest line coverage
-    entries.sort((a, b) => a.lines - b.lines);
-    return {
-        found: true,
-        source,
-        entries,
-        summary: {
-            totalFiles: entries.length,
-            overallLineCoverage: overallLine,
-            overallBranchCoverage: overallBranch,
-            overallFunctionCoverage: overallFunction,
-            overallStatementCoverage: overallStatement,
-        },
-    };
-}
-function parseLcovInfo(raw, source) {
-    const entries = [];
-    let currentFile = '';
-    let linesHit = 0, linesFound = 0;
-    let branchesHit = 0, branchesFound = 0;
-    let functionsHit = 0, functionsFound = 0;
-    const flushRecord = () => {
-        if (currentFile) {
-            entries.push({
-                filePath: currentFile,
-                lines: linesFound > 0 ? (linesHit / linesFound) * 100 : 0,
-                branches: branchesFound > 0 ? (branchesHit / branchesFound) * 100 : 100,
-                functions: functionsFound > 0 ? (functionsHit / functionsFound) * 100 : 100,
-                statements: linesFound > 0 ? (linesHit / linesFound) * 100 : 0,
-            });
-        }
-    };
-    for (const line of raw.split('\n')) {
-        const trimmed = line.trim();
-        if (trimmed.startsWith('SF:')) {
-            currentFile = trimmed.slice(3);
-            linesHit = 0;
-            linesFound = 0;
-            branchesHit = 0;
-            branchesFound = 0;
-            functionsHit = 0;
-            functionsFound = 0;
-        }
-        else if (trimmed.startsWith('LH:')) {
-            linesHit = parseInt(trimmed.slice(3), 10) || 0;
-        }
-        else if (trimmed.startsWith('LF:')) {
-            linesFound = parseInt(trimmed.slice(3), 10) || 0;
-        }
-        else if (trimmed.startsWith('BRH:')) {
-            branchesHit = parseInt(trimmed.slice(4), 10) || 0;
-        }
-        else if (trimmed.startsWith('BRF:')) {
-            branchesFound = parseInt(trimmed.slice(4), 10) || 0;
-        }
-        else if (trimmed.startsWith('FNH:')) {
-            functionsHit = parseInt(trimmed.slice(4), 10) || 0;
-        }
-        else if (trimmed.startsWith('FNF:')) {
-            functionsFound = parseInt(trimmed.slice(4), 10) || 0;
-        }
-        else if (trimmed === 'end_of_record') {
-            flushRecord();
-            currentFile = '';
-        }
-    }
-    flushRecord();
-    entries.sort((a, b) => a.lines - b.lines);
-    let totalLH = 0, totalLF = 0, totalBH = 0, totalBF = 0;
-    for (const e of entries) {
-        // Approximate from percentages (we lost exact counts after flush, but summaries are okay)
-        totalLH += e.lines;
-        totalLF += 100;
-        totalBH += e.branches;
-        totalBF += 100;
-    }
-    const n = entries.length || 1;
-    return {
-        found: true,
-        source,
-        entries,
-        summary: {
-            totalFiles: entries.length,
-            overallLineCoverage: totalLH / n,
-            overallBranchCoverage: totalBH / n,
-            overallFunctionCoverage: 0,
-            overallStatementCoverage: totalLH / n,
-        },
-    };
-}
 /**
  * Classify a coverage gap by priority type based on coverage percentage and threshold
  */
@@ -599,9 +428,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');
@@ -2989,7 +2825,7 @@ const coverageRouteCommand = {
                 'c8:       npx c8 npm test',
             ]);
             output.writeln();
-            output.writeln(output.dim('Expected files: coverage/coverage-summary.json, coverage/lcov.info, or .nyc_output/out.json'));
+            output.writeln(output.dim('Expected files: coverage/coverage-summary.json, coverage/lcov.info, coverage/coverage-final.json, or .nyc_output/out.json'));
             return { success: false, exitCode: 1 };
         }
     }
@@ -3180,7 +3016,7 @@ const coverageSuggestCommand = {
                 'c8:       npx c8 npm test',
             ]);
             output.writeln();
-            output.writeln(output.dim('Expected files: coverage/coverage-summary.json, coverage/lcov.info, or .nyc_output/out.json'));
+            output.writeln(output.dim('Expected files: coverage/coverage-summary.json, coverage/lcov.info, coverage/coverage-final.json, or .nyc_output/out.json'));
             return { success: false, exitCode: 1 };
         }
     }
@@ -3400,7 +3236,7 @@ const coverageGapsCommand = {
                 'c8:       npx c8 npm test',
             ]);
             output.writeln();
-            output.writeln(output.dim('Expected files: coverage/coverage-summary.json, coverage/lcov.info, or .nyc_output/out.json'));
+            output.writeln(output.dim('Expected files: coverage/coverage-summary.json, coverage/lcov.info, coverage/coverage-final.json, or .nyc_output/out.json'));
             return { success: false, exitCode: 1 };
         }
     }

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'),