@claude-flow/cli 3.36.0 → 3.37.0

package/.claude/helpers/.helpers-version

@@ -1 +1 @@
-3.35.0
+3.33.0

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.36.0",
+    "version": "3.37.0",
     "files": {
       "auto-memory-hook.mjs": "68be7e9a9eba7bf9c4e8a230db7bf61a243b965639f8504842799d6c6ca28762",
       "hook-handler.cjs": "dae295fb9ae2626b89899c19a20cc911541af82b52d2eeb9b214d618b96e9a86",
@@ -8,6 +8,6 @@
       "statusline.cjs": "0457fe53f8cd2c56458ff178392536a5868efd1a573665fa43bc01d2d95ca677"
     }
   },
-  "signature": "quiBH2e5gpMkXXiCB2Y0Qxq7NCra4RozthLNqF8/fsISogpAmNX6N6r2UA9UJljvMyXwgAEtAtChXx4g1zh/AQ==",
+  "signature": "wjNllO+6A/iFejatdXHUflp2Bx831zKmAHCsJANV8L93X/s/8unB79SJCG9MpiiFFnoCAx+ESPken/NV3oG2BQ==",
   "algorithm": "ed25519"
 }

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 4,
-  "generatedAt": "2026-08-10T17:40:16.814Z",
-  "gitSha": "f35c545f",
+  "generatedAt": "2026-08-11T17:05:49.193Z",
+  "gitSha": "6ce18b5a",
   "catalog": {
     "agents": 164,
     "tools": 397,

package/dist/src/commands/proxy-lifecycle.d.ts

@@ -7,13 +7,30 @@
  */
 import type { Command } from '../types.js';
 import { type ProxyStatus } from '../proxy/lifecycle.js';
-/** Pinned and reviewed; later upgrades remain explicit commands. */
-export declare const DEFAULT_PROXY_RELEASE = "0.4.0";
+/**
+ * Pinned and reviewed; later upgrades remain explicit commands.
+ *
+ * Keep this the single source of truth — interpolate it rather than writing
+ * the version into user-facing strings, or the pin silently drifts out of
+ * sync with the text that advertises it.
+ */
+export declare const DEFAULT_PROXY_RELEASE = "0.7.3";
 /**
  * Human-oriented next steps for `ruflo proxy` and `ruflo proxy status`.
  * Keep this independent of the command framework so the state-specific
  * guidance has a small, direct regression-test surface.
  */
+/**
+ * Lines shown when the binary on disk is an older release than the current
+ * pin — empty otherwise, including when the version is unknown (`null`),
+ * where the honest move is to say nothing rather than guess.
+ *
+ * Bumping `DEFAULT_PROXY_RELEASE` only ever changed what a *new* install
+ * gets. Someone who installed the previous pin has no reason to run
+ * `install` again and no signal that anything moved, so a fix that motivated
+ * a bump reaches exactly the people who never needed it. This is the signal.
+ */
+export declare function proxyUpdateGuidance(status: ProxyStatus): string[];
 export declare function proxyConsoleGuidance(status: ProxyStatus): string[];
 export declare function printProxyConsoleGuidance(status: ProxyStatus): void;
 export declare const proxyLifecycleSubcommands: Command[];

package/dist/src/commands/proxy-lifecycle.js

@@ -11,8 +11,14 @@ import { installProxy, uninstallProxy } from '../proxy/install.js';
 import { startForeground, startBackground, stopProxy, getProxyStatus, readProxyLogTail, watchProxyLog, ProxyNotInstalledError, ProxyAlreadyRunningError, } from '../proxy/lifecycle.js';
 import { proxyTokenPath } from '../proxy/paths.js';
 import { removeInjectedToken, startTokenRefreshPump } from '../proxy/token-bridge.js';
-/** Pinned and reviewed; later upgrades remain explicit commands. */
-export const DEFAULT_PROXY_RELEASE = '0.4.0';
+/**
+ * Pinned and reviewed; later upgrades remain explicit commands.
+ *
+ * Keep this the single source of truth — interpolate it rather than writing
+ * the version into user-facing strings, or the pin silently drifts out of
+ * sync with the text that advertises it.
+ */
+export const DEFAULT_PROXY_RELEASE = '0.7.3';
 const PROXY_COMMAND = 'npx ruflo@latest proxy';
 const AUTH_COMMAND = 'npx ruflo@latest auth';
 /**
@@ -20,6 +26,25 @@ const AUTH_COMMAND = 'npx ruflo@latest auth';
  * Keep this independent of the command framework so the state-specific
  * guidance has a small, direct regression-test surface.
  */
+/**
+ * Lines shown when the binary on disk is an older release than the current
+ * pin — empty otherwise, including when the version is unknown (`null`),
+ * where the honest move is to say nothing rather than guess.
+ *
+ * Bumping `DEFAULT_PROXY_RELEASE` only ever changed what a *new* install
+ * gets. Someone who installed the previous pin has no reason to run
+ * `install` again and no signal that anything moved, so a fix that motivated
+ * a bump reaches exactly the people who never needed it. This is the signal.
+ */
+export function proxyUpdateGuidance(status) {
+    if (!status.installed || !status.version || status.version === DEFAULT_PROXY_RELEASE)
+        return [];
+    return [
+        '',
+        `An update is available — installed v${status.version}, current pin v${DEFAULT_PROXY_RELEASE}.`,
+        `  ${PROXY_COMMAND} update              Re-verify and replace with v${DEFAULT_PROXY_RELEASE}`,
+    ];
+}
 export function proxyConsoleGuidance(status) {
     if (!status.installed) {
         return [
@@ -31,6 +56,7 @@ export function proxyConsoleGuidance(status) {
             `  ${PROXY_COMMAND} start --service`,
         ];
     }
+    const update = proxyUpdateGuidance(status);
     if (!status.running) {
         return [
             '',
@@ -39,6 +65,7 @@ export function proxyConsoleGuidance(status) {
             '',
             'Foreground mode (shows live logs; Ctrl+C stops it):',
             `  ${PROXY_COMMAND} start`,
+            ...update,
             '',
             'Optional: enable Cognitum cloud routing (local-only is the default):',
             `  ${AUTH_COMMAND} login`,
@@ -50,6 +77,7 @@ export function proxyConsoleGuidance(status) {
         'Meta Proxy is ready.',
         `  Logs:    ${PROXY_COMMAND} logs`,
         `  Stop:    ${PROXY_COMMAND} stop`,
+        ...update,
         '',
         'Optional: enable Cognitum cloud routing (local-only is the default):',
         `  ${AUTH_COMMAND} login`,
@@ -122,10 +150,21 @@ const installSub = {
 };
 const updateSub = {
     name: 'update',
-    description: 'Re-verify and replace the installed binary with a specific version (never automatic)',
-    options: [{ name: 'release', description: 'Release version to install', type: 'string', required: true }],
+    description: 'Re-verify and replace the installed binary with the pinned release (never automatic)',
+    options: [
+        // Defaults to the pin, matching `install`. `--release` was previously
+        // required, which meant the only in-product way to reach a newer binary
+        // was to already know its version number — so bumping the pin moved
+        // nothing for anyone who had already installed. Still never automatic:
+        // this runs only when a user types it.
+        {
+            name: 'release',
+            description: `Release version to install (default: ${DEFAULT_PROXY_RELEASE})`,
+            type: 'string',
+        },
+    ],
     action: async (ctx) => {
-        const version = typeof ctx.flags.release === 'string' ? ctx.flags.release : undefined;
+        const version = typeof ctx.flags.release === 'string' ? ctx.flags.release : DEFAULT_PROXY_RELEASE;
         if (!version) {
             output.printError('ruflo proxy update requires --release <x.y.z>');
             return { success: false, exitCode: 1 };
@@ -212,6 +251,11 @@ const statusSub = {
         }
         output.writeln('Meta Proxy');
         output.writeln(`  Installation: ${status.installed ? 'ready' : 'not installed'}`);
+        if (status.installed) {
+            // "unknown" rather than an assumed version: the manifest is the only
+            // record of what was installed, and asking the binary would start it.
+            output.writeln(`  Version: ${status.version ?? 'unknown (no install manifest)'}`);
+        }
         output.writeln(`  Process: ${status.running ? `running (pid ${status.pid})` : 'not running'}`);
         if (status.stalePidFile)
             output.writeln('  (a stale PID file was found and will be cleared on next start)');

package/dist/src/commands/proxy.js

@@ -23,7 +23,7 @@ import { clearRateLimitStatus, readRateLimitStatus } from '../funnel/rate-limit-
 import { clearQuotaLowStatus, readQuotaLowStatus } from '../funnel/power-saver-notifier.js';
 import { getInstalledCliVersion } from '../init/helper-refresh.js';
 import * as path from 'path';
-import { proxyLifecycleSubcommands, printProxyConsoleGuidance } from './proxy-lifecycle.js';
+import { proxyLifecycleSubcommands, printProxyConsoleGuidance, DEFAULT_PROXY_RELEASE } from './proxy-lifecycle.js';
 import { getProxyStatus } from '../proxy/lifecycle.js';
 const PROXY_CONFIG_FILE = 'proxy-config.toml';
 /**
@@ -87,61 +87,220 @@ function readDataPlane() {
 function writeDataPlane(plane) {
     writeConfigLine('default_data_plane', `"${plane}"`);
 }
+/**
+ * How to get back to a given plane, for "restore what you had" guidance.
+ * `sponsored` is ADR-313's own consent flow and is deliberately absent — this
+ * command must not offer a one-flag route into someone else's consent gate.
+ */
+const PLANE_RESTORE_COMMAND = {
+    passthrough: 'ruflo proxy config --passthrough',
+    local: 'ruflo proxy config --local-only',
+};
+/**
+ * One line describing a plane in the terms that matter — who serves the
+ * request. Kept together so the no-flag report and the restore hints cannot
+ * describe the same plane two different ways.
+ */
+function describePlane(plane) {
+    switch (plane) {
+        case 'cloud':
+            return 'Cloud routing is ON — cloud-tier requests go to api.cognitum.one.';
+        case 'passthrough':
+            return 'Passthrough — requests go to your own Claude subscription. Prompts do not go to Cognitum.';
+        case 'local':
+            return 'Local-only — requests go to your own backend (Ollama/vLLM/SGLang) and never leave this machine.';
+        case 'sponsored':
+            return "Sponsored — requests go to Cognitum's sponsored capacity (ADR-313).";
+        default:
+            return `Unrecognized plane "${plane}" — meta-proxy will fall back to its own default (passthrough).`;
+    }
+}
+/**
+ * `routing_mode` — how the Cloud plane picks a tier (meta-proxy ADR-321
+ * rev-2). Values match the Rust `RoutingMode` enum (`src/config.rs`, also
+ * `#[serde(rename_all = "snake_case")]`); absent from the file means `auto`,
+ * so an existing config keeps working untouched.
+ */
+const ROUTING_MODES = ['auto', 'low', 'mid', 'high'];
+function readRoutingMode() {
+    const match = readProxyConfigRaw().match(/^routing_mode\s*=\s*"([^"]*)"/m);
+    const value = match?.[1];
+    return ROUTING_MODES.includes(value ?? '') ? value : 'auto';
+}
+function writeRoutingMode(mode) {
+    writeConfigLine('routing_mode', `"${mode}"`);
+}
+/**
+ * ADR-304/321. This is the terminal-side equivalent of the Developer
+ * Console's Cloud selector disclosure — meta-proxy#43 M5a covered the
+ * console, M5b covers "any terminal flow that explicitly activates Cloud",
+ * which is this command.
+ *
+ * It answers the three questions activating Cloud actually decides, because
+ * each has a different answer than the plane the user is leaving:
+ * who processes the prompt, who pays for it, and which model runs. The third
+ * is the one the previous text omitted entirely, and it is not a detail —
+ * on the Cloud plane the client's requested model is deliberately NOT used.
+ */
 const CLOUD_ROUTING_DISCLOSURE = [
     'Enabling cloud routing.',
     '',
-    'With cloud routing ON, prompts for cloud-tier requests are sent to',
-    'api.cognitum.one and forwarded to the selected provider',
-    '(Claude / GPT / Gemini / DeepSeek / OpenRouter).',
+    'Who processes your prompts:',
+    '  Prompts for cloud-tier requests are sent to api.cognitum.one and',
+    '  forwarded to the selected provider (Claude / GPT / Gemini / DeepSeek /',
+    '  OpenRouter). Cognitum handles them server-side.',
+    '',
+    'Who pays:',
+    '  Cloud-tier requests are metered against your Cognitum account, not',
+    '  against your own Claude subscription. Your subscription is used only',
+    '  by the Passthrough plane (the proxy\'s default), which is unaffected',
+    '  by everything below.',
+    '',
+    'Which model runs:',
+    '  The cloud plane picks the tier per prompt instead of using the model',
+    '  your client asked for (ADR-321). That is the point of the plane: a',
+    '  trivial question is not served at frontier rates because the client',
+    '  happened to name a frontier model. The scorer reads prompt shape, not',
+    '  task difficulty, so pin a tier if you disagree with its judgement:',
+    '    ruflo proxy config --routing-mode high',
     '',
     'Requests routed to local backends never leave this machine.',
     '',
-    'Disable anytime: ruflo proxy config --local-only',
+    'Turning it off is a choice of where to go back to, not one command:',
+    '  ruflo proxy config --passthrough    Your own Claude subscription',
+    '  ruflo proxy config --local-only     Your own local backend',
 ].join('\n');
 const configSub = {
     name: 'config',
-    description: 'Toggle cloud routing (ADR-304) — local backends only by default',
+    description: 'Toggle cloud routing and its tier selection (ADR-304/321) — local backends only by default',
     options: [
         { name: 'cloud', description: 'Enable cloud routing (requires cloud-routing consent)', type: 'boolean', default: false },
-        { name: 'local-only', description: 'Disable cloud routing, revert to local-only routing', type: 'boolean', default: false },
+        { name: 'local-only', description: 'Disable cloud routing; route to your own local backend', type: 'boolean', default: false },
+        {
+            name: 'passthrough',
+            description: "Disable cloud routing; route to your own Claude subscription (meta-proxy's own default)",
+            type: 'boolean',
+            default: false,
+        },
+        {
+            name: 'routing-mode',
+            description: `How the cloud plane picks a tier: ${ROUTING_MODES.join(' | ')} (default: auto)`,
+            type: 'string',
+        },
         { name: 'yes', description: 'Skip the confirmation prompt', type: 'boolean', default: false },
     ],
     action: async (ctx) => {
         const wantCloud = Boolean(ctx.flags.cloud);
         const wantLocalOnly = Boolean(ctx.flags.localOnly ?? ctx.flags['local-only']);
-        if (wantCloud && wantLocalOnly) {
-            output.printError('Pass either --cloud or --local-only, not both.');
+        const wantPassthrough = Boolean(ctx.flags.passthrough);
+        const rawRoutingMode = ctx.flags.routingMode ?? ctx.flags['routing-mode'];
+        const wantRoutingMode = typeof rawRoutingMode === 'string' ? rawRoutingMode : undefined;
+        const planeFlags = [
+            wantCloud && '--cloud',
+            wantLocalOnly && '--local-only',
+            wantPassthrough && '--passthrough',
+        ].filter(Boolean);
+        if (planeFlags.length > 1) {
+            output.printError(`Pass one plane at a time — got ${planeFlags.join(' and ')}.`);
+            return { success: false, exitCode: 1 };
+        }
+        if (wantRoutingMode !== undefined && !ROUTING_MODES.includes(wantRoutingMode)) {
+            output.printError(`Unknown routing mode "${wantRoutingMode}". Valid values: ${ROUTING_MODES.join(', ')}.`);
             return { success: false, exitCode: 1 };
         }
-        if (!wantCloud && !wantLocalOnly) {
+        const routingMode = wantRoutingMode;
+        // A tier only means anything on the Cloud plane, and these flags leave
+        // it. Writing both would record a preference the same command just made
+        // unreachable, so say so instead of silently picking one.
+        const leavingCloud = wantLocalOnly || wantPassthrough;
+        if (routingMode && leavingCloud) {
+            output.printError(`--routing-mode only governs the cloud plane, which ${planeFlags[0]} turns off. Pass one or the other.`);
+            return { success: false, exitCode: 1 };
+        }
+        if (!wantCloud && !leavingCloud && !routingMode) {
             const plane = readDataPlane();
             output.writeln(`Current data plane: ${plane}`);
-            output.writeln(plane === 'cloud'
-                ? 'Cloud routing is ON — cloud-tier requests go to api.cognitum.one.'
-                : 'Cloud routing is OFF — requests never leave this machine (or use your own Claude subscription on Passthrough).');
-            return { success: true, data: { plane } };
+            output.writeln(`  ${describePlane(plane)}`);
+            const mode = readRoutingMode();
+            output.writeln(mode === 'auto'
+                ? '  Tier selection: auto — Cognitum scores each prompt and picks low/mid/high.'
+                : `  Tier selection: pinned to ${mode}.`);
+            if (plane !== 'cloud')
+                output.writeln('  (Tier selection applies only while cloud routing is ON.)');
+            // meta-proxy routing.rs gates automatic quota failover on the plane
+            // being Passthrough — it is the only plane that sees Anthropic's own
+            // rate-limit headers. Worth saying, because nothing else reveals that
+            // sitting on `local` silently opts you out of ADR-321 entirely.
+            if (plane === 'local') {
+                output.writeln('  Note: automatic quota failover (ADR-321) applies only on passthrough.');
+                output.writeln('        Use your Claude subscription instead: ruflo proxy config --passthrough');
+            }
+            return { success: true, data: { plane, routingMode: mode } };
         }
-        if (wantLocalOnly) {
-            writeDataPlane('local');
-            revokeConsent('cloud-routing', 'proxy-config-local-only');
-            output.printSuccess('Cloud routing disabled — reverted to local-only routing.');
-            return { success: true, data: { plane: 'local' } };
+        // Setting a tier must never activate Cloud — meta-proxy ADR-321
+        // Revision 3 keeps the plane choice and this Cloud-only secondary
+        // setting as separate controls, so `--routing-mode` alone writes only
+        // `routing_mode` and asks for no consent it does not need.
+        if (routingMode && !wantCloud) {
+            writeRoutingMode(routingMode);
+            output.printSuccess(routingMode === 'auto'
+                ? 'Cloud tier selection set to auto — Cognitum scores each prompt.'
+                : `Cloud tier selection pinned to ${routingMode}.`);
+            if (readDataPlane() !== 'cloud') {
+                output.writeln('  Cloud routing is currently OFF, so this takes effect once you enable it:');
+                output.writeln('    ruflo proxy config --cloud --yes');
+            }
+            return { success: true, data: { routingMode } };
         }
-        // wantCloud
+        if (leavingCloud) {
+            const plane = wantPassthrough ? 'passthrough' : 'local';
+            writeDataPlane(plane);
+            revokeConsent('cloud-routing', wantPassthrough ? 'proxy-config-passthrough' : 'proxy-config-local-only');
+            output.printSuccess(`Cloud routing disabled — now on ${plane}.`);
+            output.writeln(`  ${describePlane(plane)}`);
+            // Naming the other option here is the point: "disable cloud" has two
+            // destinations, and the one you land on decides whether your own
+            // subscription is used at all.
+            if (plane === 'local') {
+                output.writeln('  Your own Claude subscription is NOT used on this plane. To use it instead:');
+                output.writeln('    ruflo proxy config --passthrough');
+            }
+            return { success: true, data: { plane } };
+        }
+        // wantCloud. Read the plane being left BEFORE overwriting it — this is
+        // the only moment ruflo knows where the user was, and "how do I get back"
+        // is otherwise unanswerable from the config file afterwards.
+        const previousPlane = readDataPlane();
         if (!hasConsent('cloud-routing')) {
             output.writeln(CLOUD_ROUTING_DISCLOSURE);
             output.writeln('');
             if (!ctx.flags.yes) {
                 output.writeln('Re-run with --yes to confirm: ruflo proxy config --cloud --yes');
+                // Nothing is written on the unconfirmed path — including any
+                // --routing-mode passed alongside, which would otherwise leave a
+                // trace of an activation the user never confirmed.
                 return { success: true, data: { confirmed: false } };
             }
             recordConsent('cloud-routing', true, 'proxy-config-cloud');
         }
         writeDataPlane('cloud');
+        if (routingMode)
+            writeRoutingMode(routingMode);
+        const effectiveMode = routingMode ?? readRoutingMode();
         output.printSuccess('Cloud routing enabled.');
+        output.writeln(effectiveMode === 'auto'
+            ? '  Tier selection: auto — Cognitum scores each prompt and picks low/mid/high.'
+            : `  Tier selection: pinned to ${effectiveMode}.`);
         output.writeln('  Requests routed to local backends still never leave this machine.');
-        output.writeln('  Disable anytime: ruflo proxy config --local-only');
-        return { success: true, data: { plane: 'cloud' } };
+        const restore = previousPlane === 'cloud' ? undefined : PLANE_RESTORE_COMMAND[previousPlane];
+        if (restore) {
+            output.writeln(`  Previous plane: ${previousPlane}. Restore it with:`);
+            output.writeln(`    ${restore}`);
+        }
+        else {
+            output.writeln('  Turn it off with: ruflo proxy config --passthrough (or --local-only)');
+        }
+        return { success: true, data: { plane: 'cloud', routingMode: effectiveMode, previousPlane } };
     },
 };
 const SPONSOR_DISCLOSURE = [
@@ -378,10 +537,12 @@ export const proxyCommand = {
         trainingShareEnableSub, trainingShareDisableSub, trainingShareStatusSub,
     ],
     examples: [
-        { command: 'ruflo proxy install --yes', description: 'Install the signed Meta-Proxy v0.4.0 binary' },
+        { command: 'ruflo proxy install --yes', description: `Install the signed Meta-Proxy v${DEFAULT_PROXY_RELEASE} binary` },
         { command: 'ruflo proxy start', description: 'Start meta-proxy in the foreground' },
         { command: 'ruflo proxy status', description: 'Show install + process status' },
         { command: 'ruflo proxy config --cloud --yes', description: 'Enable cloud routing (ADR-304)' },
+        { command: 'ruflo proxy config --routing-mode high', description: 'Pin the cloud tier instead of auto (ADR-321)' },
+        { command: 'ruflo proxy config --passthrough', description: 'Turn cloud routing off, back to your Claude subscription' },
         { command: 'ruflo proxy config --local-only', description: 'Revert to local-only routing' },
         { command: 'ruflo proxy sponsor-status', description: 'Show current sponsored-mode state' },
         { command: 'ruflo proxy sponsor-enable --yes', description: 'Opt into sponsored downtime capacity' },

package/dist/src/proxy/install.d.ts

@@ -11,6 +11,32 @@
 export declare class ExtractionError extends Error {
     constructor(message: string);
 }
+/**
+ * Extracts the archive via the OS's own tools — `tar` for `.tar.gz`
+ * (present on macOS/Linux/Windows 10+), PowerShell `Expand-Archive`
+ * specifically for `.zip` on Windows. Zero new archive-parsing dependency,
+ * matching this repo's existing taste for shelling out over adding a parser dep.
+ *
+ * `Expand-Archive` stays the PRIMARY `.zip` path — bsdtar's zip support is
+ * still not something to lean on by default. But `Microsoft.PowerShell.Archive`
+ * is a *script* module resolved through PowerShell's module autoloading, so it
+ * can fail for environment reasons entirely unrelated to the archive. Observed
+ * in the wild on a healthy Windows 11 box, from ruflo's own `-NonInteractive`
+ * child process:
+ *
+ *   Expand-Archive : The 'Expand-Archive' command was found in the module
+ *   'Microsoft.PowerShell.Archive', but the module could not be loaded.
+ *
+ * The same command succeeded on the same machine minutes later, so this is
+ * intermittent rather than a hard platform break. Previously that aborted the
+ * install outright with nothing to fall back on, stranding an already
+ * downloaded-and-verified archive. Retrying through bsdtar costs one extra
+ * process on a path that was going to fail anyway.
+ *
+ * Exported for tests — extraction is the only platform-divergent step in the
+ * install pipeline and had no direct coverage.
+ */
+export declare function extractArchive(archivePath: string, extractDir: string, ext: 'zip' | 'tar.gz'): Promise<void>;
 export interface InstallOptions {
     version: string;
     log?: (line: string) => void;

package/dist/src/proxy/install.js

@@ -23,28 +23,23 @@ export class ExtractionError extends Error {
 function binaryNameInArchive() {
     return process.platform === 'win32' ? 'meta-proxy.exe' : 'meta-proxy';
 }
+/** `tar` handles `.tar.gz` everywhere, and `.zip` via bsdtar on Windows 10+. */
+async function extractWithTar(archivePath, extractDir, flags) {
+    const { SafeExecutor } = await import('@claude-flow/security');
+    const exec = new SafeExecutor({ allowedCommands: ['tar'], timeout: 60_000 });
+    const result = await exec.execute('tar', [flags, archivePath, '-C', extractDir]);
+    if (result.exitCode !== 0) {
+        throw new ExtractionError(`tar extraction failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
+    }
+}
 /**
- * Extracts the archive via the OS's own tools — `tar` for `.tar.gz`
- * (present on macOS/Linux/Windows 10+), PowerShell `Expand-Archive`
- * specifically for `.zip` on Windows (not tar's bsdtar zip support — not
- * reliable enough to lean on). Zero new archive-parsing dependency, matching
- * this repo's existing taste for shelling out over adding a parser dep.
+ * Single-quoted literal paths (doubling any embedded single quote per
+ * PowerShell string-literal escaping) passed as ONE argv element to
+ * `-Command`. shell:false means no OS shell ever tokenizes this string —
+ * only powershell.exe's own parser does.
  */
-async function extractArchive(archivePath, extractDir, ext) {
+async function extractWithPowerShell(archivePath, extractDir) {
     const { SafeExecutor } = await import('@claude-flow/security');
-    fs.mkdirSync(extractDir, { recursive: true });
-    if (ext === 'tar.gz') {
-        const exec = new SafeExecutor({ allowedCommands: ['tar'], timeout: 60_000 });
-        const result = await exec.execute('tar', ['xzf', archivePath, '-C', extractDir]);
-        if (result.exitCode !== 0) {
-            throw new ExtractionError(`tar extraction failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
-        }
-        return;
-    }
-    // .zip — PowerShell Expand-Archive, single-quoted literal paths (doubling
-    // any embedded single quote per PowerShell string-literal escaping) passed
-    // as ONE argv element to -Command. shell:false means no OS shell ever
-    // tokenizes this string — only powershell.exe's own parser does.
     const escape = (p) => p.replace(/'/g, "''");
     const command = `Expand-Archive -LiteralPath '${escape(archivePath)}' -DestinationPath '${escape(extractDir)}' -Force`;
     const exec = new SafeExecutor({ allowedCommands: ['powershell', 'powershell.exe'], timeout: 60_000 });
@@ -53,6 +48,52 @@ async function extractArchive(archivePath, extractDir, ext) {
         throw new ExtractionError(`Expand-Archive failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
     }
 }
+/**
+ * Extracts the archive via the OS's own tools — `tar` for `.tar.gz`
+ * (present on macOS/Linux/Windows 10+), PowerShell `Expand-Archive`
+ * specifically for `.zip` on Windows. Zero new archive-parsing dependency,
+ * matching this repo's existing taste for shelling out over adding a parser dep.
+ *
+ * `Expand-Archive` stays the PRIMARY `.zip` path — bsdtar's zip support is
+ * still not something to lean on by default. But `Microsoft.PowerShell.Archive`
+ * is a *script* module resolved through PowerShell's module autoloading, so it
+ * can fail for environment reasons entirely unrelated to the archive. Observed
+ * in the wild on a healthy Windows 11 box, from ruflo's own `-NonInteractive`
+ * child process:
+ *
+ *   Expand-Archive : The 'Expand-Archive' command was found in the module
+ *   'Microsoft.PowerShell.Archive', but the module could not be loaded.
+ *
+ * The same command succeeded on the same machine minutes later, so this is
+ * intermittent rather than a hard platform break. Previously that aborted the
+ * install outright with nothing to fall back on, stranding an already
+ * downloaded-and-verified archive. Retrying through bsdtar costs one extra
+ * process on a path that was going to fail anyway.
+ *
+ * Exported for tests — extraction is the only platform-divergent step in the
+ * install pipeline and had no direct coverage.
+ */
+export async function extractArchive(archivePath, extractDir, ext) {
+    fs.mkdirSync(extractDir, { recursive: true });
+    if (ext === 'tar.gz') {
+        await extractWithTar(archivePath, extractDir, 'xzf');
+        return;
+    }
+    try {
+        await extractWithPowerShell(archivePath, extractDir);
+    }
+    catch (primary) {
+        const primaryMessage = primary instanceof Error ? primary.message : String(primary);
+        try {
+            // 'xf', not 'xzf' — a zip is not gzip-compressed; bsdtar sniffs the format.
+            await extractWithTar(archivePath, extractDir, 'xf');
+        }
+        catch (fallback) {
+            const fallbackMessage = fallback instanceof Error ? fallback.message : String(fallback);
+            throw new ExtractionError(`zip extraction failed via both available extractors. Expand-Archive: ${primaryMessage} — tar fallback: ${fallbackMessage}`);
+        }
+    }
+}
 /**
  * Full install pipeline. Refuses (throws) on any verification failure —
  * never writes a partially-verified binary into the live install path.

package/dist/src/proxy/lifecycle.d.ts

@@ -3,10 +3,20 @@
  *
  * Adapts daemon.ts's proven pattern (PID file, O_EXCL lockfile for atomic
  * check-then-start, signal-0 liveness, SIGTERM->1000ms->SIGKILL) to a
- * native binary instead of a forked Node process. The binary itself takes
- * no CLI flags — confirmed empirically (2026-07-16): `meta-proxy.exe` has
- * no `--version`/`--help`, and any invocation just starts the server reading
- * its own config file — so `spawn()` here passes zero arguments, always.
+ * native binary instead of a forked Node process. `spawn()` here passes zero
+ * arguments, always — starting the server is the argument-free behavior and
+ * the only one this module wants.
+ *
+ * That is now a choice rather than a constraint. The 2026-07-16 note here
+ * ("the binary takes no CLI flags — no `--version`/`--help`, any invocation
+ * just starts the server") was true of the release pinned at the time, and
+ * stopped being true: meta-proxy v0.7.2 handles `--help` before binding, and
+ * v0.7.3 makes `--help`/`--version` win from any argv position. Do not read
+ * the old note as "the binary cannot be asked what it is" — it can. The
+ * installed version is still read from the install manifest rather than by
+ * executing the binary, because a filesystem read cannot start a listener
+ * and an exec of an old build can (a `--version` probe against 0.4.0 leaves
+ * a daemon bound to 127.0.0.1:11435).
  *
  * Foreground `start` (the ADR-307 default) uses `stdio: 'inherit'` and
  * blocks directly — simplest and safest, no log-file redirection needed.
@@ -31,6 +41,13 @@ export interface ProxyStatus {
     running: boolean;
     pid: number | null;
     stalePidFile: boolean;
+    /**
+     * The release recorded by the install that produced the binary on disk, or
+     * null when unknown — either nothing is installed, or the binary predates
+     * the manifest / the manifest was hand-removed. Callers must treat null as
+     * "cannot tell", never as "up to date".
+     */
+    version: string | null;
 }
 export declare function getProxyStatus(): ProxyStatus;
 /**

package/dist/src/proxy/lifecycle.js

@@ -3,10 +3,20 @@
  *
  * Adapts daemon.ts's proven pattern (PID file, O_EXCL lockfile for atomic
  * check-then-start, signal-0 liveness, SIGTERM->1000ms->SIGKILL) to a
- * native binary instead of a forked Node process. The binary itself takes
- * no CLI flags — confirmed empirically (2026-07-16): `meta-proxy.exe` has
- * no `--version`/`--help`, and any invocation just starts the server reading
- * its own config file — so `spawn()` here passes zero arguments, always.
+ * native binary instead of a forked Node process. `spawn()` here passes zero
+ * arguments, always — starting the server is the argument-free behavior and
+ * the only one this module wants.
+ *
+ * That is now a choice rather than a constraint. The 2026-07-16 note here
+ * ("the binary takes no CLI flags — no `--version`/`--help`, any invocation
+ * just starts the server") was true of the release pinned at the time, and
+ * stopped being true: meta-proxy v0.7.2 handles `--help` before binding, and
+ * v0.7.3 makes `--help`/`--version` win from any argv position. Do not read
+ * the old note as "the binary cannot be asked what it is" — it can. The
+ * installed version is still read from the install manifest rather than by
+ * executing the binary, because a filesystem read cannot start a listener
+ * and an exec of an old build can (a `--version` probe against 0.4.0 leaves
+ * a daemon bound to 127.0.0.1:11435).
  *
  * Foreground `start` (the ADR-307 default) uses `stdio: 'inherit'` and
  * blocks directly — simplest and safest, no log-file redirection needed.
@@ -20,7 +30,7 @@
  */
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
-import { proxyBinaryPath, proxyPidFilePath, proxyLockFilePath, proxyLogFilePath } from './paths.js';
+import { proxyBinaryPath, proxyPidFilePath, proxyLockFilePath, proxyLogFilePath, proxyInstallManifestPath, } from './paths.js';
 export class ProxyNotInstalledError extends Error {
     constructor() {
         super('meta-proxy is not installed. Run: ruflo proxy install');
@@ -51,19 +61,39 @@ function isProcessRunning(pid) {
         return false;
     }
 }
+/**
+ * The installed release, from `install.ts`'s manifest. Deliberately a
+ * filesystem read and not `meta-proxy --version`: exec'ing the binary to ask
+ * its version is exactly the probe that starts a listener on the older
+ * builds this is most needed to detect.
+ *
+ * Never throws — a missing, unreadable, or malformed manifest is a normal
+ * "unknown", not a reason to fail `proxy status`.
+ */
+function readInstalledVersion() {
+    try {
+        const raw = fs.readFileSync(proxyInstallManifestPath(), 'utf-8');
+        const manifest = JSON.parse(raw);
+        return typeof manifest.version === 'string' && manifest.version ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function getProxyStatus() {
     const installed = fs.existsSync(proxyBinaryPath());
+    const version = installed ? readInstalledVersion() : null;
     const pidPath = proxyPidFilePath();
     if (!fs.existsSync(pidPath)) {
-        return { installed, running: false, pid: null, stalePidFile: false };
+        return { installed, running: false, pid: null, stalePidFile: false, version };
     }
     const raw = fs.readFileSync(pidPath, 'utf-8').trim();
     const pid = parseInt(raw, 10);
     if (!Number.isFinite(pid)) {
-        return { installed, running: false, pid: null, stalePidFile: true };
+        return { installed, running: false, pid: null, stalePidFile: true, version };
     }
     const running = isProcessRunning(pid);
-    return { installed, running, pid: running ? pid : null, stalePidFile: !running };
+    return { installed, running, pid: running ? pid : null, stalePidFile: !running, version };
 }
 function writePidFile(pid) {
     fs.writeFileSync(proxyPidFilePath(), String(pid), 'utf-8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.36.0",
+  "version": "3.37.0",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -122,7 +122,7 @@
   "optionalDependencies": {
     "@agntcy/slim-bindings": "2.0.0-alpha.5",
     "@napi-rs/keyring": "1.3.0",
-    "@claude-flow/memory": "^3.0.0-alpha.21",
+    "@claude-flow/memory": "^3.0.0-alpha.22",
     "@metaharness/darwin": "~0.9.0",
     "@metaharness/flywheel": "~0.1.10",
     "@metaharness/radio": "~0.1.0",