@claude-flow/cli 3.32.2 → 3.32.4

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

@@ -0,0 +1,12 @@
+/**
+ * `ruflo proxy install|start|stop|status|logs|update|uninstall` (ADR-307) —
+ * the full lifecycle command set, kept in its own file so
+ * src/commands/proxy.ts (the ADR-313/314/315 consent subcommands) stays
+ * under the repo's 500-line-per-file convention. Merged into one
+ * `proxyCommand` in proxy.ts.
+ */
+import type { Command } from '../types.js';
+/** Pinned and reviewed; later upgrades remain explicit commands. */
+export declare const DEFAULT_PROXY_RELEASE = "0.4.0";
+export declare const proxyLifecycleSubcommands: Command[];
+//# sourceMappingURL=proxy-lifecycle.d.ts.map

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

@@ -0,0 +1,232 @@
+/**
+ * `ruflo proxy install|start|stop|status|logs|update|uninstall` (ADR-307) —
+ * the full lifecycle command set, kept in its own file so
+ * src/commands/proxy.ts (the ADR-313/314/315 consent subcommands) stays
+ * under the repo's 500-line-per-file convention. Merged into one
+ * `proxyCommand` in proxy.ts.
+ */
+import { output } from '../output.js';
+import { hasConsent, recordConsent, revokeConsent } from '../funnel/index.js';
+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';
+const INSTALL_DISCLOSURE = [
+    'Installing the Meta LLM Proxy (ADR-304/307).',
+    '',
+    'This downloads a separately-released Rust binary (Ed25519-signature and',
+    'checksum verified before anything is written to disk) and runs it as a',
+    'local process bound to 127.0.0.1 only. The proxy routes to LOCAL',
+    'backends by default — no prompt leaves this machine. Cloud routing is a',
+    'separate, explicit opt-in (`ruflo proxy config --cloud`), never enabled',
+    'by install alone.',
+    '',
+    'Uninstall anytime: ruflo proxy uninstall',
+].join('\n');
+const installSub = {
+    name: 'install',
+    description: 'Download, verify, and install the meta-proxy binary (ADR-307)',
+    options: [
+        // NOT named 'version' — index.ts:107 globally intercepts any --version/-v
+        // anywhere in argv (`if (flags.version || flags.V) { showVersion(); return; }`)
+        // BEFORE subcommand dispatch, regardless of which command defines it. A
+        // subcommand-local --version is silently swallowed by the CLI's own
+        // `ruflo --version` handling — confirmed the hard way in E2E testing.
+        { name: 'release', description: `Release version to install (default: ${DEFAULT_PROXY_RELEASE})`, type: 'string' },
+        { name: 'yes', description: 'Skip the confirmation prompt', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        // Resolve the reviewed default before the consent gate. An explicit empty
+        // override still fails below without recording a consent receipt.
+        const version = typeof ctx.flags.release === 'string' ? ctx.flags.release : DEFAULT_PROXY_RELEASE;
+        if (!version) {
+            output.printError('ruflo proxy install requires --release <x.y.z> — there is no version-discovery ' +
+                'endpoint yet (see the plan doc for the tracked follow-up). Find the latest at ' +
+                'the release channel and pass it explicitly.');
+            return { success: false, exitCode: 1 };
+        }
+        if (!hasConsent('proxy-install')) {
+            output.writeln(INSTALL_DISCLOSURE);
+            output.writeln('');
+            const confirmed = Boolean(ctx.flags.yes);
+            if (!confirmed) {
+                output.writeln(`Re-run with --yes to confirm: ruflo proxy install --yes (installs ${version})`);
+                return { success: true, data: { confirmed: false } };
+            }
+            recordConsent('proxy-install', true, 'proxy-install');
+        }
+        try {
+            const spinner = output.createSpinner({ text: `Installing meta-proxy ${version}...`, spinner: 'dots' });
+            spinner.start();
+            const result = await installProxy({ version, log: (line) => spinner.setText(line) });
+            spinner.succeed(`meta-proxy ${version} installed`);
+            output.writeln(`  binary: ${result.binaryPath}`);
+            output.writeln(`  sha256: ${result.sha256}`);
+            return { success: true, data: result };
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            output.printError('Install failed', message);
+            return { success: false, message, exitCode: 1 };
+        }
+    },
+};
+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 }],
+    action: async (ctx) => {
+        const version = typeof ctx.flags.release === 'string' ? ctx.flags.release : undefined;
+        if (!version) {
+            output.printError('ruflo proxy update requires --release <x.y.z>');
+            return { success: false, exitCode: 1 };
+        }
+        try {
+            const spinner = output.createSpinner({ text: `Updating meta-proxy to ${version}...`, spinner: 'dots' });
+            spinner.start();
+            const result = await installProxy({ version, log: (line) => spinner.setText(line) });
+            spinner.succeed(`meta-proxy updated to ${version}`);
+            output.writeln(`  binary: ${result.binaryPath}`);
+            return { success: true, data: result };
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            output.printError('Update failed', message);
+            return { success: false, message, exitCode: 1 };
+        }
+    },
+};
+const startSub = {
+    name: 'start',
+    description: 'Start meta-proxy (foreground by default; --service to detach)',
+    options: [
+        { name: 'service', description: 'Run detached (background), survives terminal close but not a reboot — full OS-service registration is not yet implemented', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const service = Boolean(ctx.flags.service);
+        try {
+            if (service) {
+                const { pid } = await startBackground();
+                output.printSuccess(`meta-proxy started in the background (pid ${pid})`);
+                output.writeln('  Note: survives this terminal closing, but not a reboot — OS-service registration is not yet implemented.');
+                output.writeln('  Logs: ruflo proxy logs');
+                return { success: true, data: { pid } };
+            }
+            output.writeln('Starting meta-proxy in the foreground — press Ctrl+C to stop.');
+            await startTokenRefreshPump();
+            await startForeground(); // never returns normally
+            return { success: true };
+        }
+        catch (e) {
+            if (e instanceof ProxyNotInstalledError || e instanceof ProxyAlreadyRunningError) {
+                output.printError(e.message);
+                return { success: false, message: e.message, exitCode: 1 };
+            }
+            const message = e instanceof Error ? e.message : String(e);
+            output.printError('Failed to start meta-proxy', message);
+            return { success: false, message, exitCode: 1 };
+        }
+    },
+};
+const superviseSub = {
+    name: 'supervise',
+    description: 'Internal detached supervisor for token refresh and meta-proxy lifecycle',
+    action: async () => {
+        await startTokenRefreshPump();
+        await startForeground(true);
+        return { success: true };
+    },
+};
+const stopSub = {
+    name: 'stop',
+    description: 'Stop a running meta-proxy process',
+    action: async () => {
+        const result = await stopProxy();
+        removeInjectedToken();
+        if (!result.wasRunning) {
+            output.writeln('meta-proxy was not running.');
+            return { success: true, data: result };
+        }
+        output.printSuccess(`meta-proxy stopped (was pid ${result.pid})`);
+        return { success: true, data: result };
+    },
+};
+const statusSub = {
+    name: 'status',
+    description: 'Show meta-proxy install + process status',
+    options: [{ name: 'json', description: 'Machine-readable output', type: 'boolean', default: false }],
+    action: async (ctx) => {
+        const status = getProxyStatus();
+        if (ctx.flags.json) {
+            output.printJson(status);
+            return { success: true, data: status };
+        }
+        output.writeln(`Installed: ${status.installed ? 'yes' : 'no'}`);
+        output.writeln(`Running: ${status.running ? `yes (pid ${status.pid})` : 'no'}`);
+        if (status.stalePidFile)
+            output.writeln('  (a stale PID file was found and will be cleared on next start)');
+        if (!status.installed)
+            output.writeln(`Run: ruflo proxy install --yes (installs ${DEFAULT_PROXY_RELEASE})`);
+        else if (!status.running)
+            output.writeln('Run: ruflo proxy start');
+        return { success: true, data: status };
+    },
+};
+const logsSub = {
+    name: 'logs',
+    description: 'Show meta-proxy --service logs',
+    options: [
+        { name: 'follow', short: 'f', description: 'Stream new log lines as they arrive', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        if (ctx.flags.follow) {
+            output.writeln('Following meta-proxy logs — press Ctrl+C to stop.');
+            try {
+                const watcher = watchProxyLog((line) => output.writeln(line));
+                await new Promise((resolve) => {
+                    process.on('SIGINT', () => {
+                        watcher.close();
+                        resolve();
+                    });
+                });
+                return { success: true };
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                output.printError(message);
+                return { success: false, message, exitCode: 1 };
+            }
+        }
+        const tail = readProxyLogTail();
+        if (!tail) {
+            output.writeln('No log content yet — meta-proxy has never been started in --service mode.');
+            return { success: true, data: { empty: true } };
+        }
+        output.writeln(tail);
+        return { success: true };
+    },
+};
+const uninstallSub = {
+    name: 'uninstall',
+    description: 'Stop the proxy (if running), remove the binary, token, and consent receipt',
+    action: async () => {
+        const status = getProxyStatus();
+        if (status.running) {
+            await stopProxy();
+            output.writeln('Stopped the running meta-proxy process.');
+        }
+        const removed = await uninstallProxy();
+        const { existsSync, unlinkSync } = await import('node:fs');
+        const tokenPath = proxyTokenPath();
+        if (existsSync(tokenPath))
+            unlinkSync(tokenPath);
+        removeInjectedToken();
+        revokeConsent('proxy-install', 'proxy-uninstall');
+        output.printSuccess(removed ? 'meta-proxy uninstalled.' : 'Nothing was installed — cleaned up any leftover state.');
+        return { success: true, data: { removed } };
+    },
+};
+export const proxyLifecycleSubcommands = [installSub, updateSub, startSub, superviseSub, stopSub, statusSub, logsSub, uninstallSub];
+//# sourceMappingURL=proxy-lifecycle.js.map

package/dist/src/commands/proxy.js

@@ -23,6 +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 } from './proxy-lifecycle.js';
 const PROXY_CONFIG_FILE = 'proxy-config.toml';
 /**
  * Minimal hand-rolled TOML writer — this config has exactly one boolean
@@ -40,12 +41,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 +59,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 +71,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 +368,31 @@ 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 (ctx) => {
+        const { getProxyStatus } = await import('../proxy/lifecycle.js');
+        const status = getProxyStatus();
+        output.writeln(`Installed: ${status.installed ? 'yes' : 'no'}; Running: ${status.running ? `yes (pid ${status.pid})` : 'no'}`);
+        return sponsorStatusSub.action(ctx);
+    },
 };
 export default proxyCommand;
 //# sourceMappingURL=proxy.js.map

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