claude-flow 3.48.0 → 3.50.0

package/v3/@claude-flow/cli/dist/src/commands/plugins.js

@@ -8,6 +8,7 @@
 import { output } from '../output.js';
 import { createPluginDiscoveryService, searchPlugins, getPluginSearchSuggestions, getFeaturedPlugins, getOfficialPlugins, } from '../plugins/store/index.js';
 import { getPluginManager } from '../plugins/manager.js';
+import { DEFAULT_PLUGIN_PERMISSIONS } from '../plugins/trust-policy.js';
 import { getBulkRatings } from '../services/registry-api.js';
 // List subcommand - Now uses IPFS-based registry
 const listCommand = {
@@ -185,18 +186,29 @@ const installCommand = {
         { name: 'version', short: 'v', type: 'string', description: 'Specific version to install' },
         { name: 'global', short: 'g', type: 'boolean', description: 'Install globally' },
         { name: 'dev', short: 'd', type: 'boolean', description: 'Install as dev dependency' },
-        { name: 'verify', type: 'boolean', description: 'Verify checksum (default: true)', default: true },
+        {
+            name: 'verify',
+            type: 'boolean',
+            description: 'Verify before registering (default: true). Registry installs must match the registry sha256 checksum. ' +
+                'Hooks and commands are withheld from a plugin that declares trustLevel "untrusted"/"unverified" or ' +
+                `permissions beyond the default set (${DEFAULT_PLUGIN_PERMISSIONS.join(', ')}) unless --trust is given. ` +
+                '--no-verify skips all of this.',
+            default: true,
+        },
+        { name: 'trust', type: 'boolean', description: 'Register hooks and commands even if the plugin is untrusted or declares elevated permissions', default: false },
         { name: 'registry', short: 'r', type: 'string', description: 'Registry to use' },
     ],
     examples: [
         { command: 'claude-flow plugins install -n community-analytics', description: 'Install plugin from IPFS' },
         { command: 'claude-flow plugins install -n ./my-plugin --dev', description: 'Install local plugin' },
+        { command: 'claude-flow plugins install -n ./my-plugin --trust', description: 'Install a local plugin that declares elevated permissions, registering its hooks' },
     ],
     action: async (ctx) => {
         const name = ctx.flags.name;
         const version = ctx.flags.version || 'latest';
         const registryName = ctx.flags.registry;
         const verify = ctx.flags.verify !== false;
+        const trust = ctx.flags.trust === true;
         if (!name) {
             output.printError('Plugin name is required');
             return { success: false, exitCode: 1 };
@@ -227,7 +239,7 @@ const installCommand = {
             if (isLocalPath) {
                 // Install from local path
                 spinner.setText(`Installing from ${name}...`);
-                result = await manager.installFromLocal(name);
+                result = await manager.installFromLocal(name, { verify, trust });
             }
             else {
                 // First, try to find in registry for metadata
@@ -242,7 +254,13 @@ const installCommand = {
                 }
                 // Install from npm (since IPFS is demo mode)
                 spinner.setText(`Installing ${name} from npm...`);
-                result = await manager.installFromNpm(name, version !== 'latest' ? version : undefined);
+                result = await manager.installFromNpm(name, version !== 'latest' ? version : undefined, {
+                    verify,
+                    trust,
+                    expectedChecksum: plugin?.checksum,
+                    registryTrustLevel: plugin?.trustLevel,
+                    registryPermissions: plugin?.permissions,
+                });
             }
             if (!result.success) {
                 spinner.fail(`Installation failed: ${result.error}`);
@@ -251,20 +269,39 @@ const installCommand = {
             const installed = result.plugin;
             spinner.succeed(`Installed ${installed.name}@${installed.version}`);
             output.writeln();
+            if (result.decision?.verificationSkipped) {
+                output.printWarning('Verification skipped (--no-verify): hooks and commands were registered without a trust or checksum check.');
+            }
+            for (const warning of result.warnings ?? []) {
+                output.printWarning(warning);
+            }
             const boxContent = [
                 `Plugin: ${installed.name}`,
                 `Version: ${installed.version}`,
                 `Source: ${installed.source}`,
                 `Path: ${installed.path || 'N/A'}`,
                 ``,
+                `Trust: ${installed.trustLevel ?? 'not declared'}`,
+                `Permissions: ${installed.permissions?.join(', ') || 'none declared'}`,
+                `Verification: ${installed.verification ?? 'n/a'}`,
+                `Install scripts: ${installed.source === 'local' ? 'n/a (local link)' : installed.scriptsRun ? 'ran' : 'skipped (use --trust to run)'}`,
+                ``,
                 `Hooks registered: ${installed.hooks?.length || 0}`,
                 `Commands added: ${installed.commands?.length || 0}`,
             ];
-            if (plugin) {
-                boxContent.push(`Trust: ${plugin.trustLevel}`);
-                boxContent.push(`Permissions: ${plugin.permissions.join(', ') || 'none'}`);
-            }
             output.printBox(boxContent.join('\n'), 'Installation Complete');
+            if (installed.withheld) {
+                output.writeln();
+                output.printWarning(`Withheld ${installed.withheld.hooks.length} hook(s) and ${installed.withheld.commands.length} command(s) ` +
+                    `from ${installed.name} because it ${installed.withheld.reasons.join('; ')}.`);
+                if (installed.withheld.hooks.length > 0) {
+                    output.writeln(output.dim(`  Hooks not registered: ${installed.withheld.hooks.join(', ')}`));
+                }
+                if (installed.withheld.commands.length > 0) {
+                    output.writeln(output.dim(`  Commands not added: ${installed.withheld.commands.join(', ')}`));
+                }
+                output.writeln(output.dim(`  To register them, uninstall and reinstall with --trust.`));
+            }
             return { success: true, data: installed };
         }
         catch (error) {

package/v3/@claude-flow/cli/dist/src/commands/policy.js

@@ -86,8 +86,11 @@ export const policyCommand = {
                 const state = loadPolicyState(root);
                 return print({ receipts: state.receipts });
             }
-            if (operation === 'verify')
-                return print(await verifyPolicyLedger(root));
+            if (operation === 'verify') {
+                const ledger = await verifyPolicyLedger(root);
+                const result = print(ledger);
+                return ledger.valid ? result : { ...result, success: false, exitCode: 1 };
+            }
             throw new Error(`unknown policy operation: ${operation}`);
         }
         catch (error) {

package/v3/@claude-flow/cli/dist/src/commands/session.js

@@ -28,6 +28,33 @@ function formatDate(dateStr) {
     // Otherwise show date
     return date.toLocaleDateString() + ' ' + date.toLocaleTimeString();
 }
+/**
+ * #3575: the session MCP tools report failure as `{ error }` (or
+ * `success: false`) rather than throwing, so every call site must check before
+ * printing a success line or reading result fields.
+ */
+function toolError(result) {
+    if (!result || typeof result !== 'object')
+        return 'the tool returned no result';
+    const r = result;
+    if (typeof r.error === 'string' && r.error.length > 0)
+        return r.error;
+    if (r.success === false)
+        return 'the operation failed';
+    return null;
+}
+/** #3573: say what happened to memory instead of printing an invented 0. */
+function memoryCaptureLabel(capture, fallback) {
+    if (!capture)
+        return fallback ?? 'unknown';
+    if (!capture.requested)
+        return 'not included';
+    if (capture.status === 'error')
+        return `not captured (${capture.error || 'error'})`;
+    if (capture.status === 'no-store')
+        return '0 (no memory store found)';
+    return capture.entries;
+}
 // Format session status
 function formatStatus(status) {
     switch (status) {
@@ -186,6 +213,12 @@ const saveCommand = {
                 includeAgents: ctx.flags['include-agents'] !== false,
                 includeTasks: ctx.flags['include-tasks'] !== false
             });
+            const failure = toolError(result);
+            if (failure) {
+                spinner.fail('Failed to save session');
+                output.printError(failure);
+                return { success: false, exitCode: 1 };
+            }
             spinner.succeed('Session saved');
             output.writeln();
             const stats = result.stats || {};
@@ -201,10 +234,13 @@ const saveCommand = {
                     { property: 'Saved At', value: new Date(result.savedAt).toLocaleString() },
                     { property: 'Agents', value: stats.agentCount ?? stats.agents ?? 0 },
                     { property: 'Tasks', value: stats.taskCount ?? stats.tasks ?? 0 },
-                    { property: 'Memory Entries', value: stats.memoryEntries ?? 0 },
+                    { property: 'Memory Entries', value: memoryCaptureLabel(result.memoryCapture, stats.memoryEntries) },
                     { property: 'Total Size', value: formatSize(stats.totalSize ?? 0) }
                 ]
             });
+            if (result.memoryCapture?.status === 'error') {
+                output.printWarning(`Memory was requested but could not be captured: ${result.memoryCapture.error}`);
+            }
             output.writeln();
             output.printSuccess(`Session saved: ${result.sessionId}`);
             output.printInfo(`Restore with: claude-flow session restore ${result.sessionId}`);
@@ -313,8 +349,25 @@ const restoreCommand = {
                 restoreAgents,
                 restoreTasks
             });
-            spinner.succeed('Session restored');
+            const failure = toolError(result) ?? (result.restored === false ? 'Session not found' : null);
+            if (failure) {
+                spinner.fail('Failed to restore session');
+                output.printError(failure);
+                return { success: false, exitCode: 1 };
+            }
+            const memoryRestore = result.memoryRestore;
+            const memoryPartial = !!memoryRestore && memoryRestore.failed > 0;
+            if (memoryPartial) {
+                spinner.fail('Session restored with memory errors');
+            }
+            else {
+                spinner.succeed('Session restored');
+            }
             output.writeln();
+            // #3573: distinguish "not requested" from "the session holds no memory".
+            const memoryStatus = result.restoredComponents.memory
+                ? (memoryPartial ? output.error('Partial') : output.success('Restored'))
+                : restoreMemory ? output.dim('Not in session') : output.dim('Skipped');
             output.printTable({
                 columns: [
                     { key: 'component', header: 'Component', width: 20 },
@@ -324,8 +377,10 @@ const restoreCommand = {
                 data: [
                     {
                         component: 'Memory',
-                        status: result.restoredComponents.memory ? output.success('Restored') : output.dim('Skipped'),
-                        count: result.restoredComponents.memory ? result.stats.memoryEntries : 0
+                        status: memoryStatus,
+                        count: result.restoredComponents.memory
+                            ? (result.stats.memoryEntriesRestored ?? result.stats.memoryEntries)
+                            : 0
                     },
                     {
                         component: 'Agents',
@@ -340,11 +395,19 @@ const restoreCommand = {
                 ]
             });
             output.writeln();
-            output.printSuccess(`Session ${sessionId} restored successfully`);
+            if (memoryPartial) {
+                output.printWarning(`${memoryRestore.failed} memory entries could not be restored` +
+                    (memoryRestore.errors.length ? `: ${memoryRestore.errors.join('; ')}` : ''));
+            }
+            else {
+                output.printSuccess(`Session ${sessionId} restored successfully`);
+            }
             if (ctx.flags.format === 'json') {
                 output.printJson(result);
             }
-            return { success: true, data: result };
+            return memoryPartial
+                ? { success: false, exitCode: 1, data: result }
+                : { success: true, data: result };
         }
         catch (error) {
             spinner.fail('Failed to restore session');
@@ -391,6 +454,11 @@ const deleteCommand = {
         }
         try {
             const result = await callMCPTool('session_delete', { sessionId });
+            const failure = toolError(result) ?? (result.deleted === false ? 'Session not found' : null);
+            if (failure) {
+                output.printError(`Failed to delete session: ${failure}`);
+                return { success: false, exitCode: 1 };
+            }
             output.writeln();
             output.printSuccess(`Session ${sessionId} deleted`);
             if (ctx.flags.format === 'json') {
@@ -412,7 +480,7 @@ const deleteCommand = {
 // Export subcommand
 const exportCommand = {
     name: 'export',
-    description: 'Export session to file',
+    description: 'Export a saved session to a file. Usage: session export <session-id> [-o file] (or --latest)',
     options: [
         {
             name: 'output',
@@ -420,6 +488,12 @@ const exportCommand = {
             description: 'Output file path',
             type: 'string'
         },
+        {
+            name: 'latest',
+            description: 'Export the most recently saved session when no session id is given',
+            type: 'boolean',
+            default: false
+        },
         {
             name: 'format',
             short: 'f',
@@ -446,14 +520,23 @@ const exportCommand = {
         let outputPath = ctx.flags.output;
         const exportFormat = ctx.flags.format;
         const compress = ctx.flags.compress;
-        // Get current session if no ID provided
+        // #3575: like `session delete`, refuse to guess which session to act on.
+        // Exporting the most recent one is available, but only when asked for.
         if (!sessionId) {
+            if (!ctx.flags.latest) {
+                output.printError('Session ID is required. Pass a session id, or --latest to export the most recently saved session.');
+                return { success: false, exitCode: 1 };
+            }
             try {
                 const current = await callMCPTool('session_current', {});
+                if (toolError(current) || !current.sessionId) {
+                    output.printError('No saved sessions to export.');
+                    return { success: false, exitCode: 1 };
+                }
                 sessionId = current.sessionId;
             }
             catch {
-                output.printError('No active session. Provide a session ID to export.');
+                output.printError('No saved sessions to export.');
                 return { success: false, exitCode: 1 };
             }
         }
@@ -469,6 +552,12 @@ const exportCommand = {
                 sessionId,
                 includeMemory: ctx.flags['include-memory'] !== false
             });
+            const failure = toolError(result);
+            if (failure || result.data === undefined) {
+                spinner.fail('Failed to export session');
+                output.printError(failure || 'The export returned no session data');
+                return { success: false, exitCode: 1 };
+            }
             // Format output
             let content;
             if (exportFormat === 'yaml') {
@@ -484,7 +573,8 @@ const exportCommand = {
             fs.writeFileSync(absolutePath, content, 'utf-8');
             spinner.succeed('Session exported');
             output.writeln();
-            const exportStats = result.stats || {};
+            // session_export returns the whole record under `data`; its stats live there.
+            const exportStats = result.stats || result.data?.stats || {};
             output.printTable({
                 columns: [
                     { key: 'property', header: 'Property', width: 18 },
@@ -522,7 +612,7 @@ const exportCommand = {
 // Import subcommand
 const importCommand = {
     name: 'import',
-    description: 'Import session from file',
+    description: 'Import a session from a file written by session export. Usage: session import <file> [--name n] [--activate]',
     options: [
         {
             name: 'name',
@@ -555,21 +645,32 @@ const importCommand = {
         const spinner = output.createSpinner({ text: 'Importing session...' });
         spinner.start();
         try {
-            const content = fs.readFileSync(absolutePath, 'utf-8');
-            let data;
-            // Parse based on extension
+            // The YAML written by `session export --format yaml` is display-only;
+            // there is no YAML parser here, so say so instead of failing obscurely.
             if (absolutePath.endsWith('.yaml') || absolutePath.endsWith('.yml')) {
-                // Simple YAML parsing (basic implementation)
-                data = JSON.parse(content); // Would need proper YAML parser
-            }
-            else {
-                data = JSON.parse(content);
+                try {
+                    JSON.parse(fs.readFileSync(absolutePath, 'utf-8'));
+                }
+                catch {
+                    spinner.fail('Failed to import session');
+                    output.printError('YAML session import is not supported. Export with --format json and import that file.');
+                    return { success: false, exitCode: 1 };
+                }
             }
+            // #3575: session_import reads the file itself from `inputPath`. Passing a
+            // parsed `data` object used to hit its required-argument check, and the
+            // CLI then printed "Session imported" before crashing on the error result.
             const result = await callMCPTool('session_import', {
-                data,
+                inputPath: absolutePath,
                 name: sessionName,
                 activate
             });
+            const failure = toolError(result);
+            if (failure) {
+                spinner.fail('Failed to import session');
+                output.printError(failure);
+                return { success: false, exitCode: 1 };
+            }
             spinner.succeed('Session imported');
             output.writeln();
             output.printTable({
@@ -619,6 +720,11 @@ const currentCommand = {
     action: async (ctx) => {
         try {
             const result = await callMCPTool('session_current', { includeStats: true });
+            if (toolError(result)) {
+                output.printWarning('No active session');
+                output.printInfo('Save one with "claude-flow session save"');
+                return { success: true, data: { active: false } };
+            }
             if (ctx.flags.format === 'json') {
                 output.printJson(result);
                 return { success: true, data: result };
@@ -727,7 +833,8 @@ export const sessionCommand = {
         { command: 'claude-flow session save -n "checkpoint-1"', description: 'Save current session' },
         { command: 'claude-flow session restore session-123', description: 'Restore a session' },
         { command: 'claude-flow session delete session-123', description: 'Delete a session' },
-        { command: 'claude-flow session export -o backup.json', description: 'Export session to file' },
+        { command: 'claude-flow session export session-123 -o backup.json', description: 'Export a session to file' },
+        { command: 'claude-flow session export --latest -o backup.json', description: 'Export the most recently saved session' },
         { command: 'claude-flow session import backup.json', description: 'Import session from file' },
         { command: 'claude-flow session current', description: 'Show current session' }
     ],

package/v3/@claude-flow/cli/dist/src/commands/swarm.js

@@ -196,17 +196,14 @@ function getSwarmStatus(swarmId) {
             // Ignore
         }
     }
-    // Calculate dynamic progress based on actual state
-    // If no swarm state, show 0%. Otherwise calculate from completed tasks
+    // Progress is completed / total tasks. With no tasks there is nothing to be
+    // a fraction of, so it is `null` with a reason — never an invented number
+    // (#3572: a hard-coded 5% was shown for a swarm with no tasks, forever).
     const totalTasks = completedTasks + inProgressTasks + pendingTasks;
-    let progress = 0;
-    if (totalTasks > 0) {
-        progress = Math.round((completedTasks / totalTasks) * 100);
-    }
-    else if (swarmState) {
-        // Swarm initialized but no tasks yet
-        progress = 5;
-    }
+    const progress = totalTasks > 0
+        ? Math.round((completedTasks / totalTasks) * 100)
+        : null;
+    const progressReason = totalTasks > 0 ? null : 'no tasks';
     // Determine status
     let status = 'idle';
     if (inProgressTasks > 0 || activeAgents > 0) {
@@ -243,6 +240,7 @@ function getSwarmStatus(swarmId) {
             completed: 0
         },
         progress,
+        progressReason,
         tasks: {
             total: totalTasks,
             completed: completedTasks,
@@ -738,7 +736,9 @@ const statusCommand = {
         output.writeln(output.bold(`Swarm Status: ${status.id ?? output.dim('unknown id')}`));
         output.writeln();
         // Progress bar
-        output.writeln(`Overall Progress: ${output.progressBar(status.progress, 100, 40)}`);
+        output.writeln(status.progress === null
+            ? `Overall Progress: ${output.dim(`n/a (${status.progressReason})`)}`
+            : `Overall Progress: ${output.progressBar(status.progress, 100, 40)}`);
         output.writeln();
         // Agent status
         output.writeln(output.bold('Agents'));

package/v3/@claude-flow/cli/dist/src/index.js

@@ -155,10 +155,19 @@ export class CLI {
                         // loudly (not silent) — the existing project helpers were left intact.
                         this.output.printWarning(`Skipped helper auto-refresh — ${r.blocked}. Reinstall @claude-flow/cli from a trusted source.`);
                     }
+                    else if (r.healed) {
+                        // #3565: a critical helper's stamp matched but its on-disk content
+                        // didn't hash-match the signed manifest — restored, but always
+                        // surfaced (not verbose-gated like a routine version-bump refresh).
+                        this.output.printWarning(`Detected tampered critical helper(s) in .claude/helpers (${(r.tampered || []).join(', ')}) — restored verified content from the installed package. If this wasn't expected, find out what modified them.`);
+                    }
                     else if (r.refreshed && this.output.isVerbose()) {
                         this.output.printDebug(`Refreshed .claude/helpers (${r.from} → ${r.to})`);
                     }
-                    if (r.global?.refreshed && this.output.isVerbose()) {
+                    if (r.global?.healed) {
+                        this.output.printWarning(`Detected tampered critical helper(s) in ~/.claude/helpers (${(r.global.tampered || []).join(', ')}) — restored verified content.`);
+                    }
+                    else if (r.global?.refreshed && this.output.isVerbose()) {
                         this.output.printDebug(`Refreshed ~/.claude/helpers (${r.global.from} → ${r.global.to})`);
                     }
                     else if (r.global?.blocked && r.global.blocked !== r.blocked) {

package/v3/@claude-flow/cli/dist/src/init/executor.js

@@ -18,6 +18,7 @@ import { generatePreCommitHook, generatePostCommitHook, generateSessionManager,
 import { getInstalledCliVersion, HELPERS_STAMP_FILE } from './helper-refresh.js';
 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';
 /**
  * Skills to copy based on configuration
@@ -499,7 +500,7 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
         const sourceHelpersForUpgrade = findSourceHelpersDir();
         if (sourceHelpersForUpgrade) {
             // Keep in sync with helper-refresh.ts:CRITICAL_HELPERS.
-            const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs', 'router.js'];
+            const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs', 'router.cjs'];
             for (const helperName of criticalHelpers) {
                 const targetPath = path.join(targetDir, '.claude', 'helpers', helperName);
                 const sourcePath = path.join(sourceHelpersForUpgrade, helperName);
@@ -524,7 +525,7 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                 'hook-handler.cjs': generateHookHandler(),
                 'intelligence.cjs': generateIntelligenceStub(),
                 'auto-memory-hook.mjs': generateAutoMemoryHook(),
-                'router.js': generateAgentRouter(), // ADR-389
+                'router.cjs': generateAgentRouter(), // ADR-389 / #3555
             };
             for (const [helperName, content] of Object.entries(generatedCritical)) {
                 const targetPath = path.join(targetDir, '.claude', 'helpers', helperName);
@@ -541,6 +542,11 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                 catch { }
             }
         }
+        // #3555: the refreshed hook-handler requires the .cjs companions; older
+        // installs only have session.js / memory.js, which can't load in ESM.
+        for (const name of await ensureCommonJsCompanions(path.join(targetDir, '.claude', 'helpers'))) {
+            result.created.push(`.claude/helpers/${name}`);
+        }
         // Stamp the installed version so the startup auto-refresh treats these as
         // current (no redundant re-copy on the next command).
         try {
@@ -1295,9 +1301,9 @@ async function writeHelpers(targetDir, options, result) {
     const helpers = {
         'pre-commit': generatePreCommitHook(),
         'post-commit': generatePostCommitHook(),
-        'session.js': generateSessionManager(),
-        'router.js': generateAgentRouter(),
-        'memory.js': generateMemoryHelper(),
+        'session.cjs': generateSessionManager(),
+        'router.cjs': generateAgentRouter(),
+        'memory.cjs': generateMemoryHelper(),
         'hook-handler.cjs': generateHookHandler(),
         'intelligence.cjs': generateIntelligenceStub(),
         'auto-memory-hook.mjs': generateAutoMemoryHook(),

package/v3/@claude-flow/cli/dist/src/init/helper-companions.d.ts

@@ -0,0 +1,3 @@
+export declare const COMMONJS_COMPANION_HELPERS: readonly ["session.cjs", "memory.cjs"];
+export declare function ensureCommonJsCompanions(helpersDir: string): Promise<string[]>;
+//# sourceMappingURL=helper-companions.d.ts.map

package/v3/@claude-flow/cli/dist/src/init/helper-companions.js

@@ -0,0 +1,34 @@
+/**
+ * CommonJS companion helpers that `hook-handler.cjs` requires but that are not
+ * in the signed critical set (#3555).
+ *
+ * They are CommonJS, so they ship as `.cjs`: a `.js` copy cannot load in a
+ * `"type":"module"` project. Installs made before the rename have only the
+ * `.js` copies, which the refreshed hook-handler no longer requires, so the
+ * refresh writes any missing `.cjs` companion from the CLI's own compiled
+ * generators (the trust root; no external file to verify). Stale `.js` copies
+ * are left in place and ignored. Existing `.cjs` files are never overwritten.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export const COMMONJS_COMPANION_HELPERS = ['session.cjs', 'memory.cjs'];
+export async function ensureCommonJsCompanions(helpersDir) {
+    const missing = COMMONJS_COMPANION_HELPERS.filter((name) => !fs.existsSync(path.join(helpersDir, name)));
+    if (missing.length === 0)
+        return [];
+    const gen = await import('./helpers-generator.js');
+    const content = {
+        'session.cjs': gen.generateSessionManager,
+        'memory.cjs': gen.generateMemoryHelper,
+    };
+    const written = [];
+    for (const name of missing) {
+        try {
+            fs.writeFileSync(path.join(helpersDir, name), content[name](), { encoding: 'utf-8', mode: 0o755 });
+            written.push(name);
+        }
+        catch { /* best-effort: hook-handler degrades gracefully without it */ }
+    }
+    return written;
+}
+//# sourceMappingURL=helper-companions.js.map

package/v3/@claude-flow/cli/dist/src/init/helper-integrity.d.ts

@@ -0,0 +1,21 @@
+export interface IntegrityResult {
+    /** Critical helper names whose on-disk hash doesn't match the signed manifest
+     *  (or that are missing from disk despite being part of the signed set). */
+    tampered: string[];
+    /** Set only when the package's OWN signed manifest can't be verified at all —
+     *  there's no ground truth to check the installed files against, distinct
+     *  from a clean `tampered: []` result. */
+    blocked?: string;
+}
+/**
+ * Re-verify each of `criticalHelpers` present on disk in `helpersDir` against
+ * `sourceDir`'s signed manifest. Read-only — safe to call without holding any
+ * refresh lock; callers only need to acquire one if `tampered` comes back
+ * non-empty and they intend to repair it.
+ *
+ * `sourceDir: null` (package source unresolvable) returns `{ tampered: [] }`
+ * — fails open rather than flagging every install as tampered when there is
+ * no ground truth at all to compare against.
+ */
+export declare function verifyInstalledCriticalHelpers(helpersDir: string, sourceDir: string | null, criticalHelpers: readonly string[], pubkeyPemOverride?: string): IntegrityResult;
+//# sourceMappingURL=helper-integrity.d.ts.map

package/v3/@claude-flow/cli/dist/src/init/helper-integrity.js

@@ -0,0 +1,62 @@
+/**
+ * Post-install integrity re-verification for signed critical helpers (#3565).
+ *
+ * `helper-refresh.ts` verifies a helper's signature/hash once, at copy time,
+ * then stamps the target directory with the installed CLI version. Every
+ * later command short-circuited on "stamp already matches" with NO further
+ * verification — so a critical helper modified on disk after that point (a
+ * sibling package's postinstall, a stray older CLI process racing a write,
+ * direct tampering) stayed silently modified through any number of
+ * subsequent commands, forever. This module re-hashes the already-INSTALLED
+ * helpers against the signed manifest independent of the stamp, so callers
+ * can re-run it on every invocation rather than trusting a single past check.
+ *
+ * Deliberately has no opinion on WHAT to do about tampering (re-copy, warn,
+ * refuse) — that policy lives in helper-refresh.ts, which already owns the
+ * fail-closed verify-then-copy path this result feeds into to heal.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { verifyHelpersManifest, sha256Hex, HELPERS_MANIFEST_FILE, } from './helper-signing.js';
+/**
+ * Re-verify each of `criticalHelpers` present on disk in `helpersDir` against
+ * `sourceDir`'s signed manifest. Read-only — safe to call without holding any
+ * refresh lock; callers only need to acquire one if `tampered` comes back
+ * non-empty and they intend to repair it.
+ *
+ * `sourceDir: null` (package source unresolvable) returns `{ tampered: [] }`
+ * — fails open rather than flagging every install as tampered when there is
+ * no ground truth at all to compare against.
+ */
+export function verifyInstalledCriticalHelpers(helpersDir, sourceDir, criticalHelpers, pubkeyPemOverride) {
+    if (!sourceDir)
+        return { tampered: [] };
+    let trusted = null;
+    try {
+        trusted = verifyHelpersManifest(fs.readFileSync(path.join(sourceDir, HELPERS_MANIFEST_FILE), 'utf-8'), pubkeyPemOverride);
+    }
+    catch {
+        trusted = null;
+    }
+    if (!trusted)
+        return { tampered: [], blocked: 'signed helpers manifest missing or signature invalid' };
+    const tampered = [];
+    for (const name of criticalHelpers) {
+        const expected = trusted.files[name];
+        // Not part of THIS version's signed set (or source doesn't ship it) —
+        // nothing to compare the installed copy against.
+        if (!expected || !fs.existsSync(path.join(sourceDir, name)))
+            continue;
+        let actual = null;
+        try {
+            actual = sha256Hex(fs.readFileSync(path.join(helpersDir, name)));
+        }
+        catch {
+            actual = null;
+        }
+        if (actual !== expected)
+            tampered.push(name);
+    }
+    return { tampered };
+}
+//# sourceMappingURL=helper-integrity.js.map