claude-flow 3.32.2 → 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/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

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

@@ -0,0 +1,249 @@
+/**
+ * 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 { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import { proxyBinaryPath, proxyPidFilePath, proxyLockFilePath, proxyLogFilePath } from './paths.js';
+export class ProxyNotInstalledError extends Error {
+    constructor() {
+        super('meta-proxy is not installed. Run: ruflo proxy install');
+        this.name = 'ProxyNotInstalledError';
+    }
+}
+export class ProxyAlreadyRunningError extends Error {
+    pid;
+    constructor(pid) {
+        super(`meta-proxy is already running (pid ${pid}). Stop it first with: ruflo proxy stop`);
+        this.pid = pid;
+        this.name = 'ProxyAlreadyRunningError';
+    }
+}
+function requireBinary() {
+    const bin = proxyBinaryPath();
+    if (!fs.existsSync(bin))
+        throw new ProxyNotInstalledError();
+    return bin;
+}
+/** Signal-0 liveness probe — cross-platform in Node, throws if the process is dead. */
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function getProxyStatus() {
+    const installed = fs.existsSync(proxyBinaryPath());
+    const pidPath = proxyPidFilePath();
+    if (!fs.existsSync(pidPath)) {
+        return { installed, running: false, pid: null, stalePidFile: false };
+    }
+    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 };
+    }
+    const running = isProcessRunning(pid);
+    return { installed, running, pid: running ? pid : null, stalePidFile: !running };
+}
+function writePidFile(pid) {
+    fs.writeFileSync(proxyPidFilePath(), String(pid), 'utf-8');
+}
+function clearStalePidFile() {
+    try {
+        fs.unlinkSync(proxyPidFilePath());
+    }
+    catch {
+        // already absent
+    }
+}
+/**
+ * Atomic check-then-start via an O_EXCL lockfile — the same fix daemon.ts
+ * applies for the identical race (#2407/#2484: without this, N concurrent
+ * `start` calls all see "not running" and all spawn their own process).
+ * Returns the lock fd to release once the PID file has been written (or on
+ * any early-return/throw), never before.
+ */
+function acquireStartLock() {
+    const lockFile = proxyLockFilePath();
+    try {
+        return fs.openSync(lockFile, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
+    }
+    catch (e) {
+        if (e.code === 'EEXIST')
+            return null; // another start is mid-spawn
+        throw e;
+    }
+}
+function releaseStartLock(fd) {
+    if (fd === null)
+        return;
+    try {
+        fs.closeSync(fd);
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        fs.unlinkSync(proxyLockFilePath());
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * 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 async function startForeground(supervised = false) {
+    const bin = requireBinary();
+    const status = getProxyStatus();
+    // In service mode startBackground has already written this supervisor's
+    // PID. Treating it as a competing proxy makes the supervisor immediately
+    // exit before it can spawn meta-proxy.
+    if (!supervised && status.running && status.pid)
+        throw new ProxyAlreadyRunningError(status.pid);
+    if (status.stalePidFile)
+        clearStalePidFile();
+    const child = spawn(bin, [], { stdio: 'inherit', windowsHide: false });
+    if (!supervised && child.pid)
+        writePidFile(child.pid);
+    const cleanup = () => clearStalePidFile();
+    process.on('exit', cleanup);
+    if (supervised) {
+        const forwardSignal = (signal) => {
+            if (!child.killed)
+                child.kill(signal);
+        };
+        process.once('SIGTERM', () => forwardSignal('SIGTERM'));
+        process.once('SIGINT', () => forwardSignal('SIGINT'));
+    }
+    await new Promise((resolve) => {
+        child.on('exit', () => {
+            cleanup();
+            resolve();
+        });
+    });
+    process.exit(0);
+}
+/**
+ * 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 async function startBackground() {
+    requireBinary();
+    const status = getProxyStatus();
+    if (status.running && status.pid)
+        throw new ProxyAlreadyRunningError(status.pid);
+    const lockFd = acquireStartLock();
+    try {
+        // Re-check under the lock — the dedup above raced a concurrent starter.
+        const rechecked = getProxyStatus();
+        if (rechecked.running && rechecked.pid)
+            throw new ProxyAlreadyRunningError(rechecked.pid);
+        if (rechecked.stalePidFile)
+            clearStalePidFile();
+        const logFd = fs.openSync(proxyLogFilePath(), 'a');
+        const cliEntry = process.argv[1];
+        if (!cliEntry)
+            throw new Error('cannot locate the ruflo CLI entrypoint for supervised service mode');
+        const child = spawn(process.execPath, [cliEntry, 'proxy', 'supervise'], {
+            stdio: ['ignore', logFd, logFd],
+            detached: true,
+            windowsHide: true,
+        });
+        fs.closeSync(logFd); // the child holds its own duplicated fd; safe to close ours
+        if (!child.pid)
+            throw new Error('ruflo proxy supervisor failed to spawn — no PID returned');
+        writePidFile(child.pid);
+        child.unref();
+        return { pid: child.pid };
+    }
+    finally {
+        releaseStartLock(lockFd);
+    }
+}
+/** SIGTERM -> 1000ms -> SIGKILL if still alive, mirroring daemon.ts's killBackgroundDaemon. */
+export async function stopProxy() {
+    const status = getProxyStatus();
+    if (!status.running || !status.pid) {
+        if (status.stalePidFile)
+            clearStalePidFile();
+        return { wasRunning: false, pid: null };
+    }
+    const pid = status.pid;
+    process.kill(pid, 'SIGTERM');
+    await new Promise((r) => setTimeout(r, 1000));
+    if (isProcessRunning(pid)) {
+        process.kill(pid, 'SIGKILL');
+    }
+    clearStalePidFile();
+    return { wasRunning: true, pid };
+}
+const TAIL_BYTES = 64 * 1024; // bounded read — a long-running proxy's log grows over weeks
+export function readProxyLogTail(maxBytes = TAIL_BYTES) {
+    const logPath = proxyLogFilePath();
+    if (!fs.existsSync(logPath))
+        return '';
+    const { size } = fs.statSync(logPath);
+    const start = Math.max(0, size - maxBytes);
+    const fd = fs.openSync(logPath, 'r');
+    try {
+        const buf = Buffer.alloc(size - start);
+        fs.readSync(fd, buf, 0, buf.length, start);
+        return buf.toString('utf-8');
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Streams new log lines as they're appended, starting from the current end of file. */
+export function watchProxyLog(onLine) {
+    const logPath = proxyLogFilePath();
+    if (!fs.existsSync(logPath)) {
+        throw new Error('no log file yet — meta-proxy has never been started in --service mode');
+    }
+    let offset = fs.statSync(logPath).size;
+    return fs.watch(logPath, () => {
+        const { size } = fs.statSync(logPath);
+        if (size <= offset)
+            return;
+        const fd = fs.openSync(logPath, 'r');
+        try {
+            const buf = Buffer.alloc(size - offset);
+            fs.readSync(fd, buf, 0, buf.length, offset);
+            offset = size;
+            for (const line of buf.toString('utf-8').split('\n')) {
+                if (line.length > 0)
+                    onLine(line);
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    });
+}
+//# sourceMappingURL=lifecycle.js.map