@stanco323/oh-my-claude-code 4.10.3

package/dist/tools/python-repl/bridge-manager.js

@@ -0,0 +1,746 @@
+/**
+ * Bridge Manager - Python process lifecycle management
+ *
+ * Manages the gyoshu_bridge.py process:
+ * - Spawning with proper environment detection
+ * - Ensuring single bridge per session with security validations
+ * - Graceful shutdown with signal escalation
+ * - PID reuse detection via process identity verification
+ */
+import { spawn, execSync } from 'child_process';
+import * as fs from 'fs';
+import * as fsPromises from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { getRuntimeDir, getSessionDir, getBridgeSocketPath, getBridgeMetaPath, getBridgePortPath, getSessionLockPath } from './paths.js';
+import { isPythonSandboxEnabled } from '../../lib/security-config.js';
+import { atomicWriteJson, safeReadJson, ensureDirSync } from '../../lib/atomic-write.js';
+import { getProcessStartTime, isProcessAlive } from '../../platform/index.js';
+const execFileAsync = promisify(execFile);
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const BRIDGE_SPAWN_TIMEOUT_MS = 30000; // 30 seconds to wait for socket
+const DEFAULT_GRACE_PERIOD_MS = 5000; // 5 seconds for SIGINT
+const SIGTERM_GRACE_MS = 2500; // 2.5 seconds for SIGTERM
+const ownedBridgeSessionIds = new Set();
+export function trackOwnedBridgeSession(sessionId) {
+    if (sessionId) {
+        ownedBridgeSessionIds.add(sessionId);
+    }
+}
+// =============================================================================
+// BRIDGE PATH RESOLUTION
+// =============================================================================
+/**
+ * Resolve the path to gyoshu_bridge.py relative to this module.
+ * The bridge script is at: <package-root>/bridge/gyoshu_bridge.py
+ *
+ * Handles both ESM and CJS contexts (for bundled MCP server).
+ */
+function getBridgeScriptPath() {
+    // Check for OMC_BRIDGE_SCRIPT environment variable first (set by MCP server context)
+    if (process.env.OMC_BRIDGE_SCRIPT) {
+        const override = path.resolve(process.env.OMC_BRIDGE_SCRIPT);
+        const overrideBasename = path.basename(override);
+        if (overrideBasename !== 'gyoshu_bridge.py') {
+            throw new Error(`OMC_BRIDGE_SCRIPT must point to gyoshu_bridge.py, got: ${overrideBasename}`);
+        }
+        if (!fs.existsSync(override)) {
+            throw new Error(`OMC_BRIDGE_SCRIPT file not found: ${override}`);
+        }
+        return override;
+    }
+    let moduleDir;
+    // Try ESM import.meta.url first
+    try {
+        if (import.meta.url) {
+            const __filename = fileURLToPath(import.meta.url);
+            moduleDir = path.dirname(__filename);
+        }
+        else {
+            throw new Error('import.meta.url is empty');
+        }
+    }
+    catch {
+        // Fallback for CJS context (bundled MCP server)
+        // In CJS bundle, __dirname points to the bundle's directory
+        moduleDir = typeof __dirname !== 'undefined' ? __dirname : process.cwd();
+    }
+    // From src/tools/python-repl/ -> ../../.. -> package root -> bridge/
+    // Or from bridge/ (CJS bundle) -> bridge/
+    const packageRoot = path.resolve(moduleDir, '..', '..', '..');
+    const bridgePath = path.join(packageRoot, 'bridge', 'gyoshu_bridge.py');
+    // If that doesn't exist, try relative to moduleDir (for bundled CJS)
+    if (!fs.existsSync(bridgePath)) {
+        // In bundled CJS, moduleDir is the bridge/ directory itself
+        const bundledBridgePath = path.join(moduleDir, 'gyoshu_bridge.py');
+        if (fs.existsSync(bundledBridgePath)) {
+            return bundledBridgePath;
+        }
+    }
+    return bridgePath;
+}
+// =============================================================================
+// PYTHON ENVIRONMENT DETECTION
+// =============================================================================
+/**
+ * Detect an existing Python virtual environment in the project directory.
+ * Returns null if no .venv is found.
+ */
+function detectExistingPythonEnv(projectRoot) {
+    const isWindows = process.platform === 'win32';
+    const binDir = isWindows ? 'Scripts' : 'bin';
+    const pythonExe = isWindows ? 'python.exe' : 'python';
+    const venvPython = path.join(projectRoot, '.venv', binDir, pythonExe);
+    if (fs.existsSync(venvPython)) {
+        return { pythonPath: venvPython, type: 'venv' };
+    }
+    return null;
+}
+/**
+ * Ensure a Python environment is available for the project.
+ * Currently requires an existing .venv - does not auto-create.
+ */
+async function ensurePythonEnvironment(projectRoot) {
+    const existing = detectExistingPythonEnv(projectRoot);
+    if (existing) {
+        return existing;
+    }
+    // Fallback: try system python3
+    try {
+        await execFileAsync('python3', ['--version']);
+        // type is 'venv' because PythonEnvInfo only supports 'venv'; this is a system fallback
+        return { pythonPath: 'python3', type: 'venv' };
+    }
+    catch {
+        // python3 not available
+    }
+    throw new Error('No Python environment found. Create a virtual environment first:\n' +
+        '  python -m venv .venv\n' +
+        '  .venv/bin/pip install pandas numpy matplotlib');
+}
+// =============================================================================
+// PROCESS IDENTITY VERIFICATION
+// =============================================================================
+/**
+ * Verify that a bridge process is still running and is the same process
+ * that was originally spawned (guards against PID reuse).
+ *
+ * Returns false if:
+ * - Process is not alive
+ * - Start time was recorded but doesn't match (PID reused)
+ * - Start time was recorded but cannot be retrieved (fail-closed)
+ */
+export async function verifyProcessIdentity(meta) {
+    // Basic alive check first
+    if (!isProcessAlive(meta.pid)) {
+        return false;
+    }
+    // If we have a recorded start time, verify it matches
+    if (meta.processStartTime !== undefined) {
+        const currentStartTime = await getProcessStartTime(meta.pid);
+        // Fail-closed: if we can't get current start time but we have a recorded one,
+        // assume PID reuse has occurred (safer than assuming same process)
+        if (currentStartTime === undefined) {
+            return false;
+        }
+        if (currentStartTime !== meta.processStartTime) {
+            return false; // PID reuse detected
+        }
+    }
+    return true;
+}
+// =============================================================================
+// SOCKET UTILITIES
+// =============================================================================
+/** Whether the current platform lacks AF_UNIX (e.g. Windows CPython). */
+const USE_TCP_FALLBACK = process.platform === 'win32';
+/**
+ * Check if a path points to a Unix socket.
+ */
+function isSocket(socketPath) {
+    try {
+        const stat = fs.lstatSync(socketPath);
+        return stat.isSocket();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check whether the bridge is ready to accept connections.
+ * On Unix, checks for the socket file. On Windows, checks for the TCP port file.
+ */
+function isBridgeReady(socketPath, sessionId) {
+    if (USE_TCP_FALLBACK) {
+        return fs.existsSync(getBridgePortPath(sessionId));
+    }
+    return isSocket(socketPath);
+}
+/**
+ * Read the TCP port number from the port file written by the Python bridge.
+ * Returns undefined if the file doesn't exist or is invalid.
+ */
+function readTcpPort(sessionId) {
+    const portPath = getBridgePortPath(sessionId);
+    try {
+        const content = fs.readFileSync(portPath, 'utf-8').trim();
+        const port = parseInt(content, 10);
+        if (Number.isFinite(port) && port > 0 && port <= 65535) {
+            return port;
+        }
+    }
+    catch {
+        // File doesn't exist or can't be read
+    }
+    return undefined;
+}
+/**
+ * Safely unlink a socket file if it exists within the expected directory.
+ */
+function safeUnlinkSocket(socketPath) {
+    try {
+        if (fs.existsSync(socketPath)) {
+            fs.unlinkSync(socketPath);
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+}
+/**
+ * Safely unlink the TCP port file for a session.
+ */
+function safeUnlinkPortFile(sessionId) {
+    try {
+        const portPath = getBridgePortPath(sessionId);
+        if (fs.existsSync(portPath)) {
+            fs.unlinkSync(portPath);
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+}
+// =============================================================================
+// BRIDGE METADATA VALIDATION
+// =============================================================================
+/**
+ * Validate that parsed JSON matches BridgeMeta schema.
+ */
+function isValidBridgeMeta(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const obj = data;
+    return (typeof obj.pid === 'number' &&
+        Number.isInteger(obj.pid) &&
+        obj.pid > 0 &&
+        typeof obj.socketPath === 'string' &&
+        typeof obj.startedAt === 'string' &&
+        typeof obj.sessionId === 'string' &&
+        typeof obj.pythonEnv === 'object' &&
+        obj.pythonEnv !== null &&
+        typeof obj.pythonEnv.pythonPath === 'string' &&
+        (obj.processStartTime === undefined || typeof obj.processStartTime === 'number'));
+}
+// =============================================================================
+// PROCESS GROUP MANAGEMENT
+// =============================================================================
+/**
+ * Kill a process group (process + children).
+ * Cross-platform: Uses taskkill /T on Windows, negative PID on Unix.
+ */
+function killProcessGroup(pid, signal) {
+    if (process.platform === 'win32') {
+        // On Windows, use taskkill with /T for tree kill
+        try {
+            const force = signal === 'SIGKILL';
+            const args = force ? '/F /T' : '/T';
+            execSync(`taskkill ${args} /PID ${pid}`, { stdio: 'ignore', timeout: 5000, windowsHide: true });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    else {
+        // Unix: use negative PID for process group
+        try {
+            process.kill(-pid, signal);
+            return true;
+        }
+        catch {
+            try {
+                process.kill(pid, signal);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+}
+// =============================================================================
+// SPAWN BRIDGE SERVER
+// =============================================================================
+/**
+ * Spawn a new bridge server process for the given session.
+ *
+ * @param sessionId - Unique session identifier
+ * @param projectDir - Optional project directory (defaults to cwd)
+ * @returns BridgeMeta containing process information
+ */
+export async function spawnBridgeServer(sessionId, projectDir) {
+    const sessionDir = getSessionDir(sessionId);
+    ensureDirSync(sessionDir);
+    const socketPath = getBridgeSocketPath(sessionId);
+    const bridgePath = getBridgeScriptPath();
+    // Verify bridge script exists
+    if (!fs.existsSync(bridgePath)) {
+        throw new Error(`Bridge script not found: ${bridgePath}`);
+    }
+    // Clean up any stale socket / port file
+    safeUnlinkSocket(socketPath);
+    if (USE_TCP_FALLBACK) {
+        safeUnlinkPortFile(sessionId);
+    }
+    const effectiveProjectDir = projectDir || process.cwd();
+    const pythonEnv = await ensurePythonEnvironment(effectiveProjectDir);
+    // Pass socket path as positional argument (matches gyoshu_bridge.py argparse)
+    const bridgeArgs = [bridgePath, socketPath];
+    const proc = spawn(pythonEnv.pythonPath, bridgeArgs, {
+        stdio: ['ignore', 'ignore', 'pipe'],
+        cwd: effectiveProjectDir,
+        env: {
+            ...process.env,
+            PYTHONUNBUFFERED: '1',
+            OMC_PARENT_PID: String(process.pid),
+            ...(isPythonSandboxEnabled() ? { OMC_PYTHON_SANDBOX: '1' } : {}),
+        },
+        detached: true,
+    });
+    proc.unref();
+    // Capture stderr for error reporting (capped at 64KB)
+    const MAX_STDERR_CHARS = 64 * 1024;
+    let stderrBuffer = '';
+    let stderrTruncated = false;
+    proc.stderr?.on('data', (chunk) => {
+        if (stderrTruncated)
+            return;
+        const text = chunk.toString();
+        if (stderrBuffer.length + text.length > MAX_STDERR_CHARS) {
+            stderrBuffer = stderrBuffer.slice(0, MAX_STDERR_CHARS - 20) + '\n...[truncated]';
+            stderrTruncated = true;
+        }
+        else {
+            stderrBuffer += text;
+        }
+    });
+    // Track early process exit so we can short-circuit the socket poll
+    let procExitCode = null;
+    proc.on('exit', (code) => {
+        procExitCode = code ?? 1;
+    });
+    // Wait for socket (Unix) or port file (Windows) to appear
+    const startTime = Date.now();
+    while (!isBridgeReady(socketPath, sessionId)) {
+        // Short-circuit: process exited before creating the socket/port file
+        if (procExitCode !== null) {
+            // Clean up any non-socket file that might exist (poisoning attempt)
+            if (!USE_TCP_FALLBACK && fs.existsSync(socketPath) && !isSocket(socketPath)) {
+                safeUnlinkSocket(socketPath);
+            }
+            if (USE_TCP_FALLBACK) {
+                safeUnlinkPortFile(sessionId);
+            }
+            throw new Error(`Bridge process exited with code ${procExitCode} before creating socket. ` +
+                `Stderr: ${stderrBuffer || '(empty)'}`);
+        }
+        if (Date.now() - startTime > BRIDGE_SPAWN_TIMEOUT_MS) {
+            // Kill the process on timeout
+            if (proc.pid) {
+                killProcessGroup(proc.pid, 'SIGKILL');
+            }
+            // Clean up any non-socket file that might exist (poisoning attempt)
+            if (!USE_TCP_FALLBACK && fs.existsSync(socketPath) && !isSocket(socketPath)) {
+                safeUnlinkSocket(socketPath);
+            }
+            if (USE_TCP_FALLBACK) {
+                safeUnlinkPortFile(sessionId);
+            }
+            throw new Error(`Bridge failed to create socket in ${BRIDGE_SPAWN_TIMEOUT_MS}ms. ` +
+                `Stderr: ${stderrBuffer || '(empty)'}`);
+        }
+        await sleep(100);
+    }
+    // Get process start time for PID reuse detection
+    const processStartTime = proc.pid ? await getProcessStartTime(proc.pid) : undefined;
+    // On Windows (TCP fallback), read the port and encode as tcp:PORT
+    let effectiveSocketPath = socketPath;
+    if (USE_TCP_FALLBACK) {
+        const port = readTcpPort(sessionId);
+        if (port === undefined) {
+            throw new Error('Bridge created port file but content is invalid');
+        }
+        effectiveSocketPath = `tcp:${port}`;
+    }
+    if (proc.pid === undefined) {
+        throw new Error('Bridge process failed to spawn: pid is undefined');
+    }
+    const meta = {
+        pid: proc.pid,
+        socketPath: effectiveSocketPath,
+        startedAt: new Date().toISOString(),
+        sessionId,
+        pythonEnv,
+        processStartTime,
+    };
+    // Persist metadata
+    const metaPath = getBridgeMetaPath(sessionId);
+    await atomicWriteJson(metaPath, meta);
+    trackOwnedBridgeSession(sessionId);
+    return meta;
+}
+// =============================================================================
+// ENSURE BRIDGE
+// =============================================================================
+/**
+ * Get or spawn a bridge server for the session.
+ *
+ * Implements security validations:
+ * - Anti-poisoning: Verifies sessionId in metadata matches expected
+ * - Anti-hijack: Verifies socketPath is the expected canonical path
+ * - Socket type: Verifies the socket path is actually a socket
+ * - Process identity: Verifies PID + start time match
+ *
+ * @param sessionId - Unique session identifier
+ * @param projectDir - Optional project directory (defaults to cwd)
+ * @returns BridgeMeta for the active bridge
+ */
+export async function ensureBridge(sessionId, projectDir) {
+    const metaPath = getBridgeMetaPath(sessionId);
+    const expectedSocketPath = getBridgeSocketPath(sessionId);
+    const meta = await safeReadJson(metaPath);
+    if (meta && isValidBridgeMeta(meta)) {
+        // Security validation 1: Anti-poisoning - verify sessionId matches
+        if (meta.sessionId !== sessionId) {
+            await deleteBridgeMeta(sessionId);
+            return spawnBridgeServer(sessionId, projectDir);
+        }
+        // Security validation 2: Anti-hijack - verify socket path is expected
+        // TCP meta uses "tcp:<port>" encoding which won't match the raw socket path; skip for TCP.
+        const isTcpMeta = meta.socketPath.startsWith('tcp:');
+        if (!isTcpMeta && meta.socketPath !== expectedSocketPath) {
+            await deleteBridgeMeta(sessionId);
+            return spawnBridgeServer(sessionId, projectDir);
+        }
+        // Security validation 3: Process identity - verify PID is still our process
+        const stillOurs = await verifyProcessIdentity(meta);
+        if (stillOurs) {
+            // Security validation 4: Socket/port check
+            if (meta.socketPath.startsWith('tcp:')) {
+                // TCP mode - port file existence confirms bridge is ready
+                if (fs.existsSync(getBridgePortPath(sessionId))) {
+                    return meta;
+                }
+            }
+            else if (isSocket(meta.socketPath)) {
+                return meta;
+            }
+            // Socket/port missing or wrong type - kill the orphan process
+            try {
+                process.kill(meta.pid, 'SIGKILL');
+            }
+            catch {
+                // Process might already be dead
+            }
+        }
+        await deleteBridgeMeta(sessionId);
+    }
+    return spawnBridgeServer(sessionId, projectDir);
+}
+// =============================================================================
+// KILL BRIDGE WITH ESCALATION
+// =============================================================================
+/**
+ * Terminate a bridge process with signal escalation.
+ *
+ * Escalation order:
+ * 1. SIGINT - wait gracePeriodMs (default 5000ms)
+ * 2. SIGTERM - wait 2500ms
+ * 3. SIGKILL - immediate termination
+ *
+ * Uses process group kill (-pid) to also terminate child processes.
+ *
+ * @param sessionId - Session whose bridge to kill
+ * @param options - Optional configuration
+ * @returns EscalationResult with termination details
+ */
+export async function killBridgeWithEscalation(sessionId, options) {
+    const gracePeriod = options?.gracePeriodMs ?? DEFAULT_GRACE_PERIOD_MS;
+    const startTime = Date.now();
+    const metaPath = getBridgeMetaPath(sessionId);
+    const meta = await safeReadJson(metaPath);
+    if (!meta || !isValidBridgeMeta(meta)) {
+        ownedBridgeSessionIds.delete(sessionId);
+        return { terminated: true }; // Already dead or no metadata
+    }
+    // Anti-poisoning check
+    if (meta.sessionId !== sessionId) {
+        await deleteBridgeMeta(sessionId);
+        ownedBridgeSessionIds.delete(sessionId);
+        return { terminated: true };
+    }
+    // Verify we're killing the right process
+    if (!(await verifyProcessIdentity(meta))) {
+        await deleteBridgeMeta(sessionId);
+        ownedBridgeSessionIds.delete(sessionId);
+        return { terminated: true }; // Process already dead or PID reused
+    }
+    // Helper to wait for process exit with identity verification
+    const waitForExit = async (timeoutMs) => {
+        const checkStart = Date.now();
+        while (Date.now() - checkStart < timeoutMs) {
+            const stillOurs = await verifyProcessIdentity(meta);
+            if (!stillOurs) {
+                return true; // Process is gone or PID reused
+            }
+            await sleep(100);
+        }
+        return false;
+    };
+    let terminatedBy = 'SIGINT';
+    // Stage 1: SIGINT
+    killProcessGroup(meta.pid, 'SIGINT');
+    if (!(await waitForExit(gracePeriod))) {
+        // Stage 2: SIGTERM
+        terminatedBy = 'SIGTERM';
+        killProcessGroup(meta.pid, 'SIGTERM');
+        if (!(await waitForExit(SIGTERM_GRACE_MS))) {
+            // Stage 3: SIGKILL
+            terminatedBy = 'SIGKILL';
+            killProcessGroup(meta.pid, 'SIGKILL');
+            await waitForExit(1000); // Brief wait for SIGKILL
+        }
+    }
+    // Cleanup
+    await deleteBridgeMeta(sessionId);
+    ownedBridgeSessionIds.delete(sessionId);
+    const sessionDir = getSessionDir(sessionId);
+    const socketPath = meta.socketPath;
+    if (socketPath.startsWith('tcp:')) {
+        safeUnlinkPortFile(sessionId);
+    }
+    else if (socketPath.startsWith(sessionDir)) {
+        safeUnlinkSocket(socketPath);
+    }
+    return {
+        terminated: true,
+        terminatedBy,
+        terminationTimeMs: Date.now() - startTime,
+    };
+}
+/**
+ * Clean up bridge processes for explicit session IDs.
+ * Used by session-end to terminate bridges created during the ending session.
+ */
+export async function cleanupBridgeSessions(sessionIds) {
+    const uniqueSessionIds = [...new Set(Array.from(sessionIds).filter(Boolean))];
+    const result = {
+        requestedSessions: uniqueSessionIds.length,
+        foundSessions: 0,
+        terminatedSessions: 0,
+        errors: [],
+    };
+    for (const sessionId of uniqueSessionIds) {
+        try {
+            ownedBridgeSessionIds.delete(sessionId);
+            const metaPath = getBridgeMetaPath(sessionId);
+            const socketPath = getBridgeSocketPath(sessionId);
+            const portPath = getBridgePortPath(sessionId);
+            const lockPath = getSessionLockPath(sessionId);
+            const hasArtifacts = fs.existsSync(metaPath) || fs.existsSync(socketPath) || fs.existsSync(portPath) || fs.existsSync(lockPath);
+            if (!hasArtifacts) {
+                continue;
+            }
+            result.foundSessions++;
+            const meta = await safeReadJson(metaPath);
+            if (meta && isValidBridgeMeta(meta)) {
+                const escalation = await killBridgeWithEscalation(sessionId);
+                if (escalation.terminatedBy) {
+                    result.terminatedSessions++;
+                }
+            }
+            else {
+                await removeFileIfExists(metaPath);
+                await removeFileIfExists(socketPath);
+                await removeFileIfExists(portPath);
+            }
+            // Lock files can linger after abnormal exits; always best-effort cleanup.
+            await removeFileIfExists(lockPath);
+        }
+        catch (error) {
+            result.errors.push(`session=${sessionId}: ${error.message}`);
+        }
+    }
+    return result;
+}
+export async function cleanupOwnedBridgeSessions() {
+    const ownedSessions = [...ownedBridgeSessionIds];
+    ownedBridgeSessionIds.clear();
+    return cleanupBridgeSessions(ownedSessions);
+}
+/**
+ * Clean up stale bridge artifacts across all runtime sessions.
+ * "Stale" means metadata is invalid OR process is no longer alive.
+ */
+export async function cleanupStaleBridges() {
+    const result = {
+        scannedSessions: 0,
+        staleSessions: 0,
+        activeSessions: 0,
+        filesRemoved: 0,
+        metaRemoved: 0,
+        socketRemoved: 0,
+        lockRemoved: 0,
+        errors: [],
+    };
+    const runtimeDir = getRuntimeDir();
+    if (!fs.existsSync(runtimeDir)) {
+        return result;
+    }
+    let entries;
+    try {
+        entries = await fsPromises.readdir(runtimeDir, { withFileTypes: true });
+    }
+    catch (error) {
+        result.errors.push(`runtimeDir=${runtimeDir}: ${error.message}`);
+        return result;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const sessionDir = path.join(runtimeDir, entry.name);
+        // Paths are constructed directly here instead of using getBridgeMetaPath/etc
+        // because entry.name is the short hash from the directory listing, not the
+        // original sessionId that the path helpers expect.
+        const metaPath = path.join(sessionDir, 'bridge_meta.json');
+        const socketPath = path.join(sessionDir, 'bridge.sock');
+        const portPath = path.join(sessionDir, 'bridge.port');
+        const lockPath = path.join(sessionDir, 'session.lock');
+        const hasArtifacts = fs.existsSync(metaPath) || fs.existsSync(socketPath) || fs.existsSync(portPath) || fs.existsSync(lockPath);
+        if (!hasArtifacts) {
+            continue;
+        }
+        result.scannedSessions++;
+        try {
+            // No metadata means we cannot verify ownership/process identity; treat as stale artifacts.
+            if (!fs.existsSync(metaPath)) {
+                result.staleSessions++;
+                const socketRemoved = await removeFileIfExists(socketPath);
+                const portRemoved = await removeFileIfExists(portPath);
+                const lockRemoved = await removeFileIfExists(lockPath);
+                if (socketRemoved) {
+                    result.socketRemoved++;
+                    result.filesRemoved++;
+                }
+                if (portRemoved) {
+                    result.filesRemoved++;
+                }
+                if (lockRemoved) {
+                    result.lockRemoved++;
+                    result.filesRemoved++;
+                }
+                continue;
+            }
+            const meta = await safeReadJson(metaPath);
+            if (!meta || !isValidBridgeMeta(meta)) {
+                result.staleSessions++;
+                const metaRemoved = await removeFileIfExists(metaPath);
+                const socketRemoved = await removeFileIfExists(socketPath);
+                await removeFileIfExists(portPath);
+                const lockRemoved = await removeFileIfExists(lockPath);
+                if (metaRemoved) {
+                    result.metaRemoved++;
+                    result.filesRemoved++;
+                }
+                if (socketRemoved) {
+                    result.socketRemoved++;
+                    result.filesRemoved++;
+                }
+                if (lockRemoved) {
+                    result.lockRemoved++;
+                    result.filesRemoved++;
+                }
+                continue;
+            }
+            const alive = await verifyProcessIdentity(meta);
+            if (alive) {
+                result.activeSessions++;
+                continue;
+            }
+            result.staleSessions++;
+            const metaRemoved = await removeFileIfExists(metaPath);
+            const socketRemoved = await removeFileIfExists(socketPath);
+            await removeFileIfExists(portPath);
+            const lockRemoved = await removeFileIfExists(lockPath);
+            if (metaRemoved) {
+                result.metaRemoved++;
+                result.filesRemoved++;
+            }
+            if (socketRemoved) {
+                result.socketRemoved++;
+                result.filesRemoved++;
+            }
+            if (lockRemoved) {
+                result.lockRemoved++;
+                result.filesRemoved++;
+            }
+        }
+        catch (error) {
+            result.errors.push(`sessionDir=${sessionDir}: ${error.message}`);
+        }
+    }
+    return result;
+}
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+/**
+ * Delete bridge metadata file.
+ */
+async function deleteBridgeMeta(sessionId) {
+    const metaPath = getBridgeMetaPath(sessionId);
+    try {
+        await fsPromises.unlink(metaPath);
+    }
+    catch {
+        // Ignore errors (file might not exist)
+    }
+}
+/**
+ * Remove a file if it exists. Returns true when a file was removed.
+ */
+async function removeFileIfExists(filePath) {
+    try {
+        await fsPromises.unlink(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Sleep for specified milliseconds.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=bridge-manager.js.map