@claude-flow/cli 3.48.0 → 3.50.0

package/dist/src/commands/mods.js

@@ -0,0 +1,126 @@
+/**
+ * `ruflo mods` — opt into running ruflo as a Claude Code mod (ADR-404,
+ * Claude Code function hooks, early access).
+ *
+ * install/uninstall edit one settings file and record what they added;
+ * status/doctor report what can be known from outside a session; sync-policy
+ * rewrites the policy projection the mod's tool check reads. Classic hooks
+ * are never removed: they stay the default and the fallback.
+ */
+import { output } from '../output.js';
+import { installMod, uninstallMod } from '../mods/install.js';
+import { probeMods } from '../mods/probe.js';
+function projectRoot(ctx) {
+    return ctx.flags.projectRoot ?? ctx.flags['project-root'] ?? ctx.cwd ?? process.cwd();
+}
+function printFindings(findings) {
+    for (const f of findings) {
+        const mark = f.status === 'pass' ? output.success('✓') : f.status === 'warn' ? output.warning('!') : output.error('✗');
+        output.writeln(`${mark} ${f.name}: ${f.message}`);
+        if (f.fix && f.status !== 'pass')
+            output.writeln(output.dim(`    fix: ${f.fix}`));
+    }
+}
+const rootOption = { name: 'project-root', description: 'Project root (default: current directory)', type: 'string' };
+const installSub = {
+    name: 'install',
+    description: 'Enable the ruflo-mods plugin for this project (opt-in; classic hooks stay as fallback)',
+    options: [
+        rootOption,
+        { name: 'scope', description: 'local (.claude/settings.local.json, default) | project (.claude/settings.json)', type: 'string', default: 'local' },
+        { name: 'dry-run', description: 'Show the settings that would be written', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const scope = ctx.flags.scope ?? 'local';
+        if (scope !== 'local' && scope !== 'project') {
+            output.printError(`--scope must be local or project, got ${scope}`);
+            return { success: false, exitCode: 1 };
+        }
+        const root = projectRoot(ctx);
+        const result = installMod(root, scope, (ctx.flags.dryRun === true || ctx.flags['dry-run'] === true));
+        if (result.dryRun) {
+            output.writeln(`Would write ${result.settingsFile}:`);
+            output.printJson(result.next);
+            return { success: true, data: result };
+        }
+        await syncPolicy(root, true);
+        output.printSuccess(`ruflo-mods enabled in ${result.settingsFile}${result.backup ? ` (backup: ${result.backup})` : ''}`);
+        output.writeln('Restart Claude Code, then run /ruflo-mods in a session to see what the mod owns.');
+        output.writeln(output.dim('Early access: Claude Code loads it only where function hooks are on. Run `ruflo mods doctor`.'));
+        return { success: true, data: result };
+    },
+};
+const uninstallSub = {
+    name: 'uninstall',
+    description: 'Remove what `ruflo mods install` added (classic hooks take every event back)',
+    options: [rootOption, { name: 'dry-run', description: 'Show what would be removed', type: 'boolean', default: false }],
+    action: async (ctx) => {
+        const result = uninstallMod(projectRoot(ctx), (ctx.flags.dryRun === true || ctx.flags['dry-run'] === true));
+        if (!result.removed) {
+            output.printWarning('No install record (.claude-flow/mods/install.json): nothing ruflo added to remove.');
+            return { success: true, data: result };
+        }
+        output.printSuccess(`${result.dryRun ? 'Would remove' : 'Removed'} ruflo-mods from ${result.settingsFile}`);
+        return { success: true, data: result };
+    },
+};
+function findingsCommand(name, description) {
+    return {
+        name,
+        description,
+        options: [rootOption, { name: 'json', description: 'Output as JSON', 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; doctor gates (warnings are expected while early access is off).
+            return { success: !failed, exitCode: name === 'doctor' && failed ? 1 : 0, data: findings };
+        },
+    };
+}
+async function syncPolicy(root, quiet) {
+    try {
+        const { loadPolicyState } = await import('../services/policy-runtime.js');
+        const { syncPolicyProjection } = await import('../mods/policy-projection.js');
+        const result = syncPolicyProjection(root, loadPolicyState(root));
+        if (!quiet || result.action !== 'unchanged')
+            output.writeln(`policy projection: ${result.action} (${result.path})`);
+        return true;
+    }
+    catch (error) {
+        output.printWarning(`policy projection not synced: ${error.message}`);
+        return false;
+    }
+}
+const syncPolicySub = {
+    name: 'sync-policy',
+    description: 'Rewrite the Claude Code policy projection from .claude-flow/policy/state.json',
+    options: [rootOption],
+    action: async (ctx) => {
+        const ok = await syncPolicy(projectRoot(ctx), false);
+        return { success: ok, exitCode: ok ? 0 : 1 };
+    },
+};
+const statusSub = findingsCommand('status', 'Show whether the mod is enabled, can load, and what it owns');
+export const modsCommand = {
+    name: 'mods',
+    description: 'Run ruflo as a Claude Code mod (function hooks, early access, ADR-404)',
+    subcommands: [
+        installSub,
+        uninstallSub,
+        statusSub,
+        findingsCommand('doctor', 'Check the mod path; exits 1 only on a failure'),
+        syncPolicySub,
+    ],
+    examples: [
+        { command: 'ruflo mods install', description: 'Enable for this project (settings.local.json)' },
+        { command: 'ruflo mods doctor', description: 'Function hooks on? Refused by policy? Handshake supported?' },
+        { command: 'ruflo mods uninstall', description: 'Remove only what install added' },
+    ],
+    action: statusSub.action,
+};
+export default modsCommand;
+//# sourceMappingURL=mods.js.map

package/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/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/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/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/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/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/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