claude-flow 3.32.1 → 3.32.8

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

@@ -23,6 +23,8 @@ 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 { getProxyStatus } from '../proxy/lifecycle.js';
 const PROXY_CONFIG_FILE = 'proxy-config.toml';
 /**
  * Minimal hand-rolled TOML writer — this config has exactly one boolean
@@ -40,12 +42,12 @@ function readProxyConfigRaw() {
         return '';
     }
 }
-function writeConsentMirrorLine(field, value) {
+function writeConfigLine(field, rawValue) {
     const dir = funnelStateDir();
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     const target = path.join(dir, PROXY_CONFIG_FILE);
     const raw = readProxyConfigRaw();
-    const line = `${field} = ${value}`;
+    const line = `${field} = ${rawValue}`;
     const pattern = new RegExp(`^${field}\\s*=.*$`, 'm');
     let next;
     if (pattern.test(raw)) {
@@ -58,6 +60,9 @@ function writeConsentMirrorLine(field, value) {
     fs.writeFileSync(tmp, next, { encoding: 'utf-8', mode: 0o600 });
     fs.renameSync(tmp, target);
 }
+function writeConsentMirrorLine(field, value) {
+    writeConfigLine(field, String(value));
+}
 function writeSponsoredConsentMirror(granted) {
     writeConsentMirrorLine('sponsored_consent_granted', granted);
 }
@@ -67,6 +72,78 @@ function writePowerSaverConsentMirror(granted) {
 function writeTrainingShareConsentMirror(granted) {
     writeConsentMirrorLine('training_share_consent_granted', granted);
 }
+/**
+ * `default_data_plane` — the ADR-304 cloud-routing toggle. Values confirmed
+ * against meta-proxy's actual `DataPlane` enum (`src/config.rs`,
+ * `#[serde(rename_all = "snake_case")]`): "local" | "cloud" | "sponsored" |
+ * "passthrough" (the last two are not written by this command — sponsored
+ * is ADR-313's own consent flag, passthrough is the proxy's own default).
+ */
+function readDataPlane() {
+    const raw = readProxyConfigRaw();
+    const match = raw.match(/^default_data_plane\s*=\s*"([^"]*)"/m);
+    return match ? match[1] : 'passthrough'; // matches the Rust struct's own default
+}
+function writeDataPlane(plane) {
+    writeConfigLine('default_data_plane', `"${plane}"`);
+}
+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).',
+    '',
+    'Requests routed to local backends never leave this machine.',
+    '',
+    'Disable anytime: ruflo proxy config --local-only',
+].join('\n');
+const configSub = {
+    name: 'config',
+    description: 'Toggle cloud routing (ADR-304) — 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: '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.');
+            return { success: false, exitCode: 1 };
+        }
+        if (!wantCloud && !wantLocalOnly) {
+            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 } };
+        }
+        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' } };
+        }
+        // wantCloud
+        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');
+                return { success: true, data: { confirmed: false } };
+            }
+            recordConsent('cloud-routing', true, 'proxy-config-cloud');
+        }
+        writeDataPlane('cloud');
+        output.printSuccess('Cloud routing enabled.');
+        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 SPONSOR_DISCLOSURE = [
     'Enabling sponsored downtime mode.',
     '',
@@ -292,19 +369,35 @@ const trainingShareStatusSub = {
 };
 export const proxyCommand = {
     name: 'proxy',
-    description: 'Meta LLM Proxy — sponsored downtime + power saver + training-data sharing (ADR-304/307/313/314/315)',
+    description: 'Meta LLM Proxy — install/lifecycle + sponsored downtime + power saver + training-data sharing (ADR-304/307/313/314/315)',
     subcommands: [
+        ...proxyLifecycleSubcommands,
+        configSub,
         sponsorEnableSub, sponsorDisableSub, sponsorStatusSub, sponsorClearSub,
         powerSaverEnableSub, powerSaverDisableSub, powerSaverStatusSub, powerSaverClearSub,
         trainingShareEnableSub, trainingShareDisableSub, trainingShareStatusSub,
     ],
     examples: [
+        { command: 'ruflo proxy install --yes', description: 'Install the signed Meta-Proxy v0.4.0 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 --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' },
         { command: 'ruflo proxy power-saver-enable --yes', description: 'Opt into power saver mode' },
         { command: 'ruflo proxy training-share-enable --yes', description: 'Opt into training-data sharing (ADR-315)' },
     ],
-    action: sponsorStatusSub.action,
+    action: async () => {
+        const status = getProxyStatus();
+        output.writeln('Meta Proxy');
+        output.writeln(`  Installation: ${status.installed ? 'ready' : 'not installed'}`);
+        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)');
+        printProxyConsoleGuidance(status);
+        return { success: true, data: status };
+    },
 };
 export default proxyCommand;
 //# sourceMappingURL=proxy.js.map

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

@@ -6,6 +6,7 @@
  */
 import { output } from '../output.js';
 import { execSync } from 'node:child_process';
+import { createBuiltinAIDefence } from '../security/builtin-aidefence.js';
 // Scan subcommand
 const scanCommand = {
     name: 'scan',
@@ -861,16 +862,17 @@ const defendCommand = {
         output.writeln(output.bold('🛡️ AIDefence - AI Manipulation Defense System'));
         output.writeln(output.dim('─'.repeat(55)));
         // Dynamic import of aidefence (allows package to be optional)
-        let createAIDefence;
+        let defender;
         try {
             const aidefence = await import('@claude-flow/aidefence');
-            createAIDefence = aidefence.createAIDefence;
+            defender = aidefence.createAIDefence({ enableLearning });
         }
         catch {
-            output.error('AIDefence package not installed. Run: npm install @claude-flow/aidefence');
-            return { success: false, message: 'AIDefence not available' };
+            // Keep cold npx startup lean (#2561): the full learning engine remains
+            // user-installable, while the CLI always ships a deterministic scanner.
+            defender = createBuiltinAIDefence();
+            output.writeln(output.dim('Using built-in defense engine (install @claude-flow/aidefence for adaptive learning)'));
         }
-        const defender = createAIDefence({ enableLearning });
         // Show stats mode
         if (showStats) {
             const stats = await defender.getStats();
@@ -893,8 +895,8 @@ const defendCommand = {
                 output.writeln(output.dim(`Reading file: ${filePath}`));
             }
             catch (err) {
-                output.error(`Failed to read file: ${filePath}`);
-                return { success: false, message: 'File not found' };
+                output.printError(`Failed to read file: ${filePath}`);
+                return { success: false, exitCode: 2, message: 'File not found' };
             }
         }
         if (!textToScan) {
@@ -914,8 +916,9 @@ const defendCommand = {
         spinner.start();
         // Perform scan
         const startTime = performance.now();
-        const result = quickMode
-            ? { ...defender.quickScan(textToScan), threats: [], piiFound: false, detectionTimeMs: 0, inputHash: '', safe: !defender.quickScan(textToScan).threat }
+        const quickResult = quickMode ? defender.quickScan(textToScan) : undefined;
+        const result = quickResult
+            ? { ...quickResult, threats: [], piiFound: false, detectionTimeMs: 0, inputHash: '', safe: !quickResult.threat }
             : await defender.detect(textToScan);
         const scanTime = performance.now() - startTime;
         spinner.stop();
@@ -927,7 +930,8 @@ const defendCommand = {
                 piiFound: result.piiFound,
                 detectionTimeMs: scanTime,
             }, null, 2));
-            return { success: true };
+            const safe = result.safe && !result.piiFound;
+            return { success: safe, exitCode: safe ? 0 : 1 };
         }
         // Text output
         output.writeln();
@@ -969,7 +973,8 @@ const defendCommand = {
             }
         }
         output.writeln(output.dim(`Detection time: ${scanTime.toFixed(3)}ms`));
-        return { success: result.safe };
+        const safe = result.safe && !result.piiFound;
+        return { success: safe, exitCode: safe ? 0 : 1 };
     },
 };
 // Main security command

package/v3/@claude-flow/cli/dist/src/funnel/insights.d.ts

@@ -30,6 +30,7 @@ export interface LocalInsight {
 export interface LocalInsightContext {
     security?: {
         status: string;
+        findings?: number;
         cvesFixed: number;
         totalCves: number;
     };

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

@@ -42,11 +42,11 @@ function securityInsight(ctx) {
     const s = ctx.security;
     if (!s)
         return null;
-    const pending = s.totalCves - s.cvesFixed;
-    if (pending > 0) {
+    const findings = Math.max(0, s.findings ?? 0);
+    if (s.status === 'ISSUES' || findings > 0) {
         return {
-            id: 'insight-cves-pending',
-            text: `⚠ ${pending} CVE${pending === 1 ? '' : 's'} pending — Run ruflo security scan --depth full`,
+            id: 'insight-security-findings',
+            text: `⚠ ${findings} security finding${findings === 1 ? '' : 's'} — Review the latest ruflo security scan`,
             priority: 90,
         };
     }

package/v3/@claude-flow/cli/dist/src/funnel/local-signals.d.ts

@@ -1,6 +1,11 @@
 export interface SecurityStatus {
-    status: 'CLEAN' | 'IN_PROGRESS' | 'PENDING';
+    status: 'CLEAN' | 'ISSUES' | 'PENDING';
+    /** Generic code-pattern findings from `ruflo security scan` (not CVEs). */
+    findings: number;
+    scannedAt?: string;
+    /** @deprecated Retained as a zero-valued compatibility field. */
     cvesFixed: number;
+    /** @deprecated Retained as a zero-valued compatibility field. */
     totalCves: number;
 }
 export declare function getSecurityStatus(cwd?: string): SecurityStatus;

package/v3/@claude-flow/cli/dist/src/funnel/local-signals.js

@@ -11,30 +11,39 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 export function getSecurityStatus(cwd = process.cwd()) {
+    const empty = {
+        status: 'PENDING', findings: 0, cvesFixed: 0, totalCves: 0,
+    };
     const scanResultsPath = path.join(cwd, '.claude', 'security-scans');
-    let cvesFixed = 0;
-    const totalCves = 3;
-    if (fs.existsSync(scanResultsPath)) {
-        try {
-            const scans = fs.readdirSync(scanResultsPath).filter((f) => f.endsWith('.json'));
-            cvesFixed = Math.min(totalCves, scans.length);
-        }
-        catch {
-            // Ignore
+    if (!fs.existsSync(scanResultsPath))
+        return empty;
+    try {
+        const files = fs.readdirSync(scanResultsPath).filter((f) => f.endsWith('.json'));
+        if (files.length === 0)
+            return empty;
+        let newest = files[0];
+        let newestMtime = -1;
+        for (const f of files) {
+            const st = fs.statSync(path.join(scanResultsPath, f));
+            if (st.mtimeMs > newestMtime) {
+                newestMtime = st.mtimeMs;
+                newest = f;
+            }
         }
+        const scan = JSON.parse(fs.readFileSync(path.join(scanResultsPath, newest), 'utf-8'));
+        const rawFindings = scan.summary?.total ?? scan.totalFindings ?? scan.findings?.length ?? 0;
+        const findings = Math.max(0, Number.isFinite(rawFindings) ? rawFindings : 0);
+        return {
+            status: findings > 0 ? 'ISSUES' : 'CLEAN',
+            findings,
+            scannedAt: typeof scan.timestamp === 'string' ? scan.timestamp : undefined,
+            cvesFixed: 0,
+            totalCves: 0,
+        };
     }
-    const auditPath = path.join(cwd, '.swarm', 'security');
-    if (fs.existsSync(auditPath)) {
-        try {
-            const audits = fs.readdirSync(auditPath).filter((f) => f.includes('audit'));
-            cvesFixed = Math.min(totalCves, Math.max(cvesFixed, audits.length));
-        }
-        catch {
-            // Ignore
-        }
+    catch {
+        return empty;
     }
-    const status = cvesFixed >= totalCves ? 'CLEAN' : cvesFixed > 0 ? 'IN_PROGRESS' : 'PENDING';
-    return { status, cvesFixed, totalCves };
 }
 export function getSwarmStatus() {
     let activeAgents = 0;

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

@@ -619,7 +619,7 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                 initialized: new Date().toISOString(),
                 status: 'PENDING',
                 cvesFixed: 0,
-                totalCves: 3,
+                totalCves: 0,
                 lastScan: null,
                 _note: 'Run: npx @claude-flow/cli@latest security scan'
             };
@@ -1541,7 +1541,7 @@ async function writeInitialMetrics(targetDir, options, result) {
             initialized: new Date().toISOString(),
             status: 'PENDING',
             cvesFixed: 0,
-            totalCves: 3,
+            totalCves: 0,
             lastScan: null,
             _note: 'Run: npx @claude-flow/cli@latest security scan'
         };

package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js

@@ -2010,8 +2010,9 @@ export const hooksSessionEnd = {
         }
         // Phase 5: Wire ReflexionMemory session end + NightlyLearner consolidation via bridge
         let sessionPersistence = null;
+        let bridge = null;
         try {
-            const bridge = await import('../memory/memory-bridge.js');
+            bridge = await import('../memory/memory-bridge.js');
             const result = await bridge.bridgeSessionEnd({
                 sessionId,
                 summary: saveState ? 'Session ended with state saved' : 'Session ended',
@@ -2028,6 +2029,17 @@ export const hooksSessionEnd = {
         catch {
             // Bridge not available
         }
+        finally {
+            // Release AgentDB/ONNX resources after one-shot session persistence.
+            // A partially initialized native pool can otherwise keep Node alive
+            // after the command has completed all logical work (#2691).
+            try {
+                await bridge?.shutdownBridge();
+            }
+            catch {
+                // Cleanup is best-effort and must not fail session-end.
+            }
+        }
         return {
             sessionId,
             duration: 3600000, // 1 hour in ms

package/v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js

@@ -389,7 +389,7 @@ export const memoryTools = [
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'Search query (semantic similarity)' },
-                namespace: { type: 'string', description: 'Namespace to search (default: "default")' },
+                namespace: { type: 'string', description: 'Namespace to search (default: all namespaces — omit to search across every namespace)' },
                 limit: { type: 'number', description: 'Maximum results (default: 10)' },
                 threshold: { type: 'number', description: 'Minimum similarity threshold 0-1 (default: 0.3)' },
                 smart: { type: 'boolean', description: 'Enable SmartRetrieval pipeline — query expansion, RRF fusion, recency boost, MMR diversity (default: false)' },
@@ -400,10 +400,18 @@ export const memoryTools = [
             await ensureInitialized();
             const { searchEntries } = await getMemoryFunctions();
             const query = input.query;
-            const namespace = input.namespace || 'default';
+            // #2646 (3rd occurrence of #1123/#1131 shape): do NOT coerce an omitted
+            // namespace to the literal string 'default' here. Both searchEntries()
+            // and bridgeSearchEntries() already resolve an omitted/undefined
+            // namespace to 'all' (fan out across every namespace) — but 'default'
+            // is truthy, so passing it defeats that fallback and silently scopes
+            // the search to a namespace that is usually empty. Leave namespace
+            // undefined when not provided so the underlying `|| 'all'` fallback
+            // in the search layer actually fires.
+            const namespace = input.namespace;
             const limit = input.limit ?? 10;
             const threshold = input.threshold ?? 0.3;
-            validateMemoryInput(undefined, undefined, query);
+            validateMemoryInput(undefined, undefined, query, namespace);
             const startTime = performance.now();
             try {
                 // #1846: feature-detect smartSearch on the resolved memory package.

package/v3/@claude-flow/cli/dist/src/proxy/install.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `ruflo proxy install`/`update` orchestration (ADR-307): download -> verify
+ * -> extract -> place -> record. The per-user bearer token
+ * (`~/.ruflo/proxy-token`) is NOT generated here — confirmed empirically
+ * (2026-07-16) that the meta-proxy binary itself creates it on first launch
+ * (`load_or_create_token()`), so this module's job ends at a verified binary
+ * on disk plus an install manifest doctor can check against.
+ *
+ * @module proxy/install
+ */
+export declare class ExtractionError extends Error {
+    constructor(message: string);
+}
+export interface InstallOptions {
+    version: string;
+    log?: (line: string) => void;
+}
+export interface InstallResult {
+    version: string;
+    binaryPath: string;
+    sha256: string;
+}
+/**
+ * Full install pipeline. Refuses (throws) on any verification failure —
+ * never writes a partially-verified binary into the live install path.
+ */
+export declare function installProxy(opts: InstallOptions): Promise<InstallResult>;
+export declare function uninstallProxy(): Promise<boolean>;
+//# sourceMappingURL=install.d.ts.map

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

@@ -0,0 +1,135 @@
+/**
+ * `ruflo proxy install`/`update` orchestration (ADR-307): download -> verify
+ * -> extract -> place -> record. The per-user bearer token
+ * (`~/.ruflo/proxy-token`) is NOT generated here — confirmed empirically
+ * (2026-07-16) that the meta-proxy binary itself creates it on first launch
+ * (`load_or_create_token()`), so this module's job ends at a verified binary
+ * on disk plus an install manifest doctor can check against.
+ *
+ * @module proxy/install
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fetchReleaseAssets, detectTargetTriple, releaseArchiveExtension, releaseAssetFilename } from './release.js';
+import { verifyRelease, sha256Hex, PROXY_RELEASE_PUBKEY_PEM } from './verify.js';
+import { proxyBinaryPath, proxyInstallManifestPath } from './paths.js';
+export class ExtractionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ExtractionError';
+    }
+}
+function binaryNameInArchive() {
+    return process.platform === 'win32' ? 'meta-proxy.exe' : 'meta-proxy';
+}
+/**
+ * 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.
+ */
+async function extractArchive(archivePath, extractDir, ext) {
+    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 });
+    const result = await exec.execute('powershell', ['-NoProfile', '-NonInteractive', '-Command', command]);
+    if (result.exitCode !== 0) {
+        throw new ExtractionError(`Expand-Archive failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
+    }
+}
+/**
+ * Full install pipeline. Refuses (throws) on any verification failure —
+ * never writes a partially-verified binary into the live install path.
+ */
+export async function installProxy(opts) {
+    const log = opts.log ?? (() => { });
+    const triple = detectTargetTriple();
+    const archiveFilename = releaseAssetFilename(opts.version, triple);
+    const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ruflo-proxy-install-'));
+    try {
+        log(`Fetching meta-proxy ${opts.version} (${triple})...`);
+        const assets = await fetchReleaseAssets(opts.version, triple, workDir, log);
+        log('Verifying release signature and checksum...');
+        const { sha256 } = verifyRelease({
+            sumsBytes: assets.sumsBytes,
+            sigBase64: assets.sigBase64,
+            assetBytes: assets.archiveBytes,
+            assetFilename: assets.archiveFilename,
+        });
+        log(`Verified — sha256 ${sha256.slice(0, 16)}…`);
+        // fetchReleaseAssets's dev (gh) path already wrote the archive to workDir
+        // under archiveFilename; ensure it's there regardless of source so
+        // extraction always has a real file to operate on.
+        const archivePath = path.join(workDir, archiveFilename);
+        if (!fs.existsSync(archivePath)) {
+            fs.writeFileSync(archivePath, assets.archiveBytes);
+        }
+        const extractDir = path.join(workDir, 'extracted');
+        await extractArchive(archivePath, extractDir, releaseArchiveExtension(triple));
+        const extractedBinaryPath = path.join(extractDir, binaryNameInArchive());
+        if (!fs.existsSync(extractedBinaryPath)) {
+            throw new ExtractionError(`archive did not contain the expected binary at its root: ${binaryNameInArchive()}`);
+        }
+        // Defense in depth: confirm the extracted binary genuinely resolves
+        // inside extractDir (catches a symlink swap or similar), even though
+        // we only ever read one specific expected relative path, never an
+        // archive-listed one (so "zip slip" via arbitrary archive paths isn't
+        // reachable here in the first place).
+        const { PathValidator } = await import('@claude-flow/security');
+        const validator = new PathValidator({ allowedPrefixes: [extractDir] });
+        const validation = await validator.validate(extractedBinaryPath);
+        if (!validation.isValid) {
+            throw new ExtractionError(`extracted binary path failed validation: ${validation.errors.join('; ') || 'unknown'}`);
+        }
+        const finalPath = proxyBinaryPath();
+        fs.mkdirSync(path.dirname(finalPath), { recursive: true, mode: 0o700 });
+        const tmp = `${finalPath}.tmp`;
+        fs.copyFileSync(extractedBinaryPath, tmp);
+        fs.chmodSync(tmp, 0o755);
+        fs.renameSync(tmp, finalPath);
+        const liveSha = sha256Hex(fs.readFileSync(finalPath));
+        const manifest = {
+            version: opts.version,
+            sha256: liveSha,
+            verifiedAt: new Date().toISOString(),
+            pubkeyFingerprint: sha256Hex(Buffer.from(PROXY_RELEASE_PUBKEY_PEM)).slice(0, 16),
+        };
+        fs.mkdirSync(path.dirname(proxyInstallManifestPath()), { recursive: true });
+        fs.writeFileSync(proxyInstallManifestPath(), JSON.stringify(manifest, null, 2), { mode: 0o600 });
+        log(`meta-proxy ${opts.version} installed at ${finalPath}`);
+        return { version: opts.version, binaryPath: finalPath, sha256: liveSha };
+    }
+    finally {
+        fs.rmSync(workDir, { recursive: true, force: true });
+    }
+}
+export async function uninstallProxy() {
+    const binPath = proxyBinaryPath();
+    const existed = fs.existsSync(binPath);
+    if (existed)
+        fs.unlinkSync(binPath);
+    try {
+        fs.unlinkSync(proxyInstallManifestPath());
+    }
+    catch {
+        /* absent — fine */
+    }
+    return existed;
+}
+//# sourceMappingURL=install.js.map

package/v3/@claude-flow/cli/dist/src/proxy/lifecycle.d.ts

@@ -0,0 +1,61 @@
+/**
+ * meta-proxy process lifecycle (ADR-307) — start/stop/status/logs.
+ *
+ * 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.
+ *
+ * Foreground `start` (the ADR-307 default) uses `stdio: 'inherit'` and
+ * blocks directly — simplest and safest, no log-file redirection needed.
+ * `start --service` needs REAL file-descriptor redirection
+ * (`stdio: ['ignore', fd, fd]`) + `detached: true` + `unref()` via
+ * `child_process.spawn()` directly — `SafeExecutor.executeStreaming()`
+ * buffers output in-process, which is wrong for a process meant to outlive
+ * the `ruflo` invocation that started it.
+ *
+ * @module proxy/lifecycle
+ */
+import * as fs from 'node:fs';
+export declare class ProxyNotInstalledError extends Error {
+    constructor();
+}
+export declare class ProxyAlreadyRunningError extends Error {
+    readonly pid: number;
+    constructor(pid: number);
+}
+export interface ProxyStatus {
+    installed: boolean;
+    running: boolean;
+    pid: number | null;
+    stalePidFile: boolean;
+}
+export declare function getProxyStatus(): ProxyStatus;
+/**
+ * Foreground start (ADR-307 default) — blocks the caller until the process
+ * exits or is interrupted. `stdio: 'inherit'` passes the proxy's own output
+ * straight through to the terminal; signals (Ctrl+C) propagate naturally to
+ * the child, no manual forwarding needed.
+ */
+export declare function startForeground(supervised?: boolean): Promise<never>;
+/**
+ * Background/`--service` start — detaches so the process outlives this
+ * `ruflo` invocation, redirecting stdout/stderr to a real log file (not
+ * buffered in-process). Returns once the child's PID is confirmed written,
+ * without waiting for the process to exit.
+ */
+export declare function startBackground(): Promise<{
+    pid: number;
+}>;
+export interface StopResult {
+    wasRunning: boolean;
+    pid: number | null;
+}
+/** SIGTERM -> 1000ms -> SIGKILL if still alive, mirroring daemon.ts's killBackgroundDaemon. */
+export declare function stopProxy(): Promise<StopResult>;
+export declare function readProxyLogTail(maxBytes?: number): string;
+/** Streams new log lines as they're appended, starting from the current end of file. */
+export declare function watchProxyLog(onLine: (line: string) => void): fs.FSWatcher;
+//# sourceMappingURL=lifecycle.d.ts.map