claude-flow 3.48.0 → 3.49.0

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

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

@@ -10,6 +10,20 @@ interface RefreshOptions {
     lockRetryMsOverride?: number;
     malformedLockStaleMsOverride?: number;
 }
+interface RefreshResult {
+    refreshed: boolean;
+    from?: string;
+    to?: string;
+    blocked?: string;
+    /** Set when `refreshed` was caused by #3565 healing, not a version bump —
+     *  the stamp already matched but one or more critical helpers failed
+     *  on-disk integrity verification and were re-copied from the verified
+     *  source. */
+    healed?: boolean;
+    /** Critical helper names that failed integrity verification, present only
+     *  alongside `healed: true`. */
+    tampered?: string[];
+}
 /**
  * ruflo-owned helpers that carry hook logic (or the render surface for the
  * funnel disclosure row) and must track the package version. Adding to this
@@ -19,6 +33,8 @@ interface RefreshOptions {
 export declare const CRITICAL_HELPERS: string[];
 /** Installed @claude-flow/cli version — the value the helpers are stamped with. */
 export declare function getInstalledCliVersion(): string;
+/** Locate the in-package `.claude/helpers` dir (the copy source). Null if not found. */
+export declare function findPackageHelpersDir(): string | null;
 /**
  * On CLI startup, refresh critical helpers if their stamp is older than the
  * installed CLI version. Two passes:
@@ -70,17 +86,8 @@ export declare function getInstalledCliVersion(): string;
  * compat with pre-3.31.3 callers). If the global pass ran, its own result is
  * carried in the optional `global` field.
  */
-export declare function autoRefreshHelpersIfStale(cwd: string, opts?: RefreshOptions): Promise<{
-    refreshed: boolean;
-    from?: string;
-    to?: string;
-    blocked?: string;
-    global?: {
-        refreshed: boolean;
-        from?: string;
-        to?: string;
-        blocked?: string;
-    };
+export declare function autoRefreshHelpersIfStale(cwd: string, opts?: RefreshOptions): Promise<RefreshResult & {
+    global?: RefreshResult;
 }>;
 export {};
 //# sourceMappingURL=helper-refresh.d.ts.map