@vibesdotdev/pm 0.0.0-stage → 1.0.0-rc.2

package/dist/daemon/orphan-scanner.js

@@ -0,0 +1,684 @@
+/**
+ * Orphan Scanner
+ * Detects and cleans up orphaned processes and sockets from previous daemon sessions
+ */
+import { attempt } from "../utils/attempt.js";
+import { processExitOf } from "../schemas/process.js";
+import { checkProcessLiveness } from "../utils/liveness.js";
+import { killProcessTree, verifyProcessOwnership, getProcessCommand, isProcessRunning } from "../utils/process-tree.js";
+import { findProcessOnPort, extractMonitoredPorts, matchesCommandSignature } from "../utils/ports.js";
+import { canonicalizePathOn, formatForeignHolderRefusal, provePortOwnership } from "../utils/port-ownership.js";
+import { valueFreeFailure } from '@vibesdotdev/kernel';
+import { getPMDaemonLogger } from "../utils/logging.js";
+import { pmFileSystem } from "../helpers/runtime-files.js";
+/**
+ * Scans for and cleans up orphaned processes and sockets
+ * Coordinates with the startup-time orphan killer in services/orphans.ts
+ */
+export class OrphanScanner {
+    deps;
+    config;
+    daemonStartTime;
+    observedProcesses = new Map();
+    // CRITICAL FIX (Issue 3.4): Port scan result cache with TTL
+    // Avoids redundant lsof calls for the same port within short time windows
+    portScanCache = new Map();
+    PORT_SCAN_CACHE_TTL_MS = 5000; // 5 second TTL
+    /** The daemon runtime's Logging, read per entry so it follows hot-reload generations (C083a). */
+    get logger() {
+        return getPMDaemonLogger(this.deps.getRuntime(), 'global').child('orphans');
+    }
+    constructor(deps, config) {
+        this.deps = deps;
+        this.config = {
+            gracePeriodMs: config?.gracePeriodMs ?? 30000,
+            warmupPeriodMs: config?.warmupPeriodMs ?? 60000,
+            enableAdoption: config?.enableAdoption ?? true
+        };
+        this.daemonStartTime = new Date();
+    }
+    /**
+     * Update the daemon start time (call when daemon restarts)
+     */
+    setDaemonStartTime(time) {
+        this.daemonStartTime = time;
+        this.observedProcesses.clear();
+    }
+    /**
+     * Update available configs (for command signature matching)
+     */
+    setConfigs(configs) {
+        this.deps.configs = configs;
+    }
+    sameObservation(current, observed) {
+        return current.status === observed.status && current.pid === observed.pid &&
+            current.startedAt?.getTime() === observed.startedAt?.getTime();
+    }
+    async ownsObservation(state) {
+        const current = await this.deps.store.get(state.id);
+        if (!current || !this.sameObservation(current, state))
+            return false;
+        const generation = state.startedAt?.getTime();
+        return !(generation !== undefined && processExitOf(state) && (await this.deps.store.taskObligations(state.id)).some(entry => entry.startedAt === generation));
+    }
+    /** Recheck owed evidence under the existing admission, after external probes settle. */
+    updateObservation(state, updates) {
+        return this.deps.store.withProcessAdmission(state.id, async () => {
+            if (!(await this.ownsObservation(state)))
+                return false;
+            return this.deps.store.updateWhen(state.id, updates, current => this.sameObservation(current, state));
+        });
+    }
+    /**
+     * Scan for and cleanup orphaned sockets from previous daemon sessions
+     * Uses unified liveness checking for consistent state detection
+     * This runs once at daemon startup to recover from crashes
+     */
+    async scanForOrphanedSockets() {
+        this.logger.info('scanning for orphaned sockets');
+        const states = await this.deps.store.getAll();
+        let orphanCount = 0;
+        for (const state of states) {
+            // Only check processes that claim to be running
+            if (state.status !== 'running')
+                continue;
+            const reconciled = await attempt(() => this.reconcileRunningState(state));
+            if (!reconciled.ok) {
+                this.logger.error('failed to check liveness for orphan scan', {
+                    processId: state.id,
+                    failure: valueFreeFailure(reconciled.failure)
+                });
+                continue;
+            }
+            orphanCount += reconciled.value;
+        }
+        if (orphanCount > 0) {
+            this.logger.info('cleaned orphaned sockets', { count: orphanCount });
+        }
+        else {
+            this.logger.debug('no orphaned sockets found');
+        }
+    }
+    /**
+     * Reconcile one state the store calls running with its liveness. Returns 1
+     * when it cleaned that process's orphaned socket, else 0.
+     */
+    async reconcileRunningState(state) {
+        let cleaned = 0;
+        // Use unified liveness checker to determine actual state
+        const livenessResult = await checkProcessLiveness(this.deps.getRuntime(), state);
+        if (!(await this.ownsObservation(state)))
+            return 0;
+        if (!livenessResult.alive) {
+            this.logger.warn('process marked running but liveness failed', {
+                processId: state.id,
+                reason: livenessResult.details.reason
+            });
+            // A connect() failure alone can be a false negative: the
+            // BOTH_REQUIRED strategy fails as soon as the socket half is
+            // unreachable, even when the pid (e.g. an orphaned runtime
+            // daemon from a previous PM generation) is still running.
+            // `checkProcessLiveness` already probed the pid directly
+            // (`isPIDAlive`, the same primitive `daemon.ts` reconcile
+            // uses) — reuse that verdict as the single ownership decision
+            // instead of lsof-ing the socket for a current holder. This
+            // keeps both call sites in agreement and drops a dependency
+            // on an external binary that is not guaranteed to be present
+            // (e.g. a minimal CI sandbox).
+            const pidAlive = livenessResult.details.pidAlive === true;
+            const isStaleSocket = livenessResult.details.socketExists === true &&
+                livenessResult.details.socketConnectable !== true;
+            if (pidAlive) {
+                // Live-but-socketless: repair, never delete. Leave the
+                // state (still 'running') and any socket file alone so a
+                // repair path (e.g. runtime daemon autostart) can recover
+                // it instead of us destroying the record for a process
+                // that is demonstrably still alive.
+                this.logger.warn('liveness failed but pid is still alive (socket unreachable or missing) — leaving state and socket alone for repair', { processId: state.id, pid: state.pid, socketPath: state.socketPath });
+                return 0;
+            }
+            if (isStaleSocket) {
+                // pid is confirmed dead — socket is genuinely orphaned.
+                this.logger.warn('found orphaned socket', {
+                    processId: state.id,
+                    socketPath: state.socketPath
+                });
+                // Cleanup the socket
+                await this.deps.pm.cleanupSocket(state.id);
+                cleaned++;
+            }
+            // Mark process as crashed with detailed error message
+            await this.updateObservation(state, {
+                status: 'crashed',
+                stoppedAt: new Date(),
+                staleSocket: isStaleSocket,
+                lastError: `Process crashed in previous session: ${livenessResult.details.reason}`
+            });
+        }
+        return cleaned;
+    }
+    /**
+     * Scan for and kill orphaned processes
+     * Runs periodically to find:
+     * 1. Processes marked as stopped/crashed but still running (orphans in state)
+     * 2. Unknown processes on monitored ports (orphans not in state)
+     *
+     * PART 2: Smart orphan detection with observation tracking and adoption
+     */
+    async scanAndKillOrphans() {
+        const states = await this.deps.store.getAll();
+        let orphanCount = 0;
+        let adoptedCount = 0;
+        let zombieCount = 0;
+        let refusedCount = 0;
+        // Per-scan-cycle tracking: pids already adopted in this tick
+        const adoptedThisCycle = new Set();
+        // PART 0: Check for zombie processes in 'running' state
+        // CRITICAL FIX (Issue 1.7): Detect and clean up zombie processes
+        const { isZombieProcess } = await import("../utils/process-tree.js");
+        for (const state of states) {
+            if (state.status === 'running' && state.pid) {
+                if (await isZombieProcess(this.deps.getRuntime(), state.pid)) {
+                    if (!(await this.ownsObservation(state)))
+                        continue;
+                    this.logger.warn('found zombie process (defunct), cleaning up state', {
+                        processId: state.id,
+                        pid: state.pid
+                    });
+                    const changed = await this.updateObservation(state, {
+                        status: 'crashed',
+                        pid: undefined,
+                        stoppedAt: new Date(),
+                        lastError: `${state.lastError || 'Process crashed'} (zombie process detected by orphan scanner)`
+                    });
+                    if (changed)
+                        zombieCount++;
+                }
+            }
+        }
+        // PART 1: Check processes in state that shouldn't be running
+        for (const state of states) {
+            // Look for processes marked as stopped/crashed but with a PID
+            if ((state.status === 'crashed' || state.status === 'stopped') && state.pid) {
+                if (!(await this.ownsObservation(state)))
+                    continue;
+                // CRITICAL FIX: Use unified liveness checker instead of just PID check
+                // This handles kubectl processes, workers, and all other process types correctly
+                const livenessResult = await checkProcessLiveness(this.deps.getRuntime(), state);
+                if (!(await this.ownsObservation(state)))
+                    continue;
+                if (livenessResult.alive) {
+                    // CRITICAL FIX: Verify PID ownership before killing
+                    // The PID might have been reused by an unrelated process
+                    const config = await this.deps.pm.getConfig(state.id);
+                    const verifyTokens = config
+                        ? [config.command, ...(config.args || [])].filter(Boolean)
+                        : [state.id];
+                    const ownership = await verifyProcessOwnership(this.deps.getRuntime(), state.pid, state.id, verifyTokens);
+                    if (!(await this.ownsObservation(state)))
+                        continue;
+                    if (ownership.owned) {
+                        // PID belongs to our process - it's actually an orphan, kill it
+                        this.logger.warn('found orphaned process', {
+                            processId: state.id,
+                            pid: state.pid,
+                            status: state.status,
+                            reason: livenessResult.details.reason
+                        });
+                        // Use shared killProcessTree which verifies kill success
+                        const orphanPid = state.pid;
+                        const killed = await attempt(() => killProcessTree(this.deps.getRuntime(), orphanPid, state.id));
+                        if (!killed.ok) {
+                            this.logger.error('failed to kill orphaned process', {
+                                processId: state.id,
+                                pid: state.pid,
+                                failure: valueFreeFailure(killed.failure)
+                            });
+                            // Keep the PID in state so we can try again next scan
+                            continue;
+                        }
+                        this.logger.info('killed orphaned process', {
+                            processId: state.id,
+                            pid: state.pid
+                        });
+                        orphanCount++;
+                    }
+                    else {
+                        // PID was reused by different process - just clear our stale state
+                        this.logger.warn('pid reused by different process; clearing state', {
+                            processId: state.id,
+                            pid: state.pid
+                        });
+                    }
+                    // Clear the PID now that we've handled it
+                    await this.updateObservation(state, {
+                        pid: undefined,
+                        lastActivity: new Date(),
+                        lastError: ownership.owned
+                            ? `${state.lastError || 'Process orphaned'} (cleaned up by orphan scanner)`
+                            : `${state.lastError || 'Process stopped'} (PID reused by different process)`
+                    });
+                }
+                else if (state.pid) {
+                    // Process is dead according to liveness check, clear the PID
+                    await this.updateObservation(state, {
+                        pid: undefined,
+                        lastError: `${state.lastError || 'Process stopped'} (verified dead: ${livenessResult.details.reason})`
+                    });
+                }
+            }
+        }
+        // PART 2: Unknown processes on ports not in state
+        // Smart logic that tracks observations and distinguishes legitimate processes from orphans
+        const observed = await this.scanMonitoredPorts(states);
+        for (const proc of observed) {
+            // Skip if already adopted in this cycle (idempotency)
+            if (adoptedThisCycle.has(proc.pid)) {
+                this.logger.debug('pid already adopted this cycle, skipping', { pid: proc.pid, port: proc.port });
+                continue;
+            }
+            const decision = await this.evaluateProcess(proc, states);
+            switch (decision.action) {
+                case 'adopt':
+                    if (decision.matchingConfigId) {
+                        // Mark as adopted in this cycle before adoption
+                        adoptedThisCycle.add(proc.pid);
+                        await this.adoptProcess(proc, decision.matchingConfigId, states);
+                        adoptedCount++;
+                    }
+                    break;
+                case 'refuse':
+                    // Rule 13: loud, by pid, with a remedy — and untouched.
+                    refusedCount++;
+                    this.logger.warn('refusing to touch a port holder this daemon did not start', {
+                        pid: proc.pid,
+                        port: proc.port,
+                        command: proc.command?.slice(0, 200) ?? null,
+                        reason: decision.reason
+                    });
+                    break;
+                case 'ignore':
+                    // Process doesn't match any expected signature, leave it alone
+                    this.logger.debug('ignoring unknown process on port', {
+                        pid: proc.pid,
+                        port: proc.port,
+                        reason: decision.reason
+                    });
+                    break;
+            }
+        }
+        if (orphanCount > 0) {
+            this.logger.info('killed orphaned processes', { count: orphanCount });
+        }
+        if (adoptedCount > 0) {
+            this.logger.info('adopted pre-daemon processes', { count: adoptedCount });
+        }
+        if (zombieCount > 0) {
+            this.logger.info('cleaned up zombie processes', { count: zombieCount });
+        }
+        if (refusedCount > 0) {
+            this.logger.warn('left foreign port holders untouched', { count: refusedCount });
+        }
+    }
+    /**
+     * Get process ID on port with caching
+     * CRITICAL FIX (Issue 3.4): Cache port scan results to avoid redundant lsof calls
+     */
+    async getProcessOnPortCached(port) {
+        const now = Date.now();
+        const cached = this.portScanCache.get(port);
+        if (cached && now - cached.timestamp < this.PORT_SCAN_CACHE_TTL_MS) {
+            this.logger.debug('Using cached port scan result', { port, pid: cached.pid });
+            return cached.pid;
+        }
+        // Not in cache or expired, perform the scan
+        const pid = await findProcessOnPort(this.deps.getRuntime(), port);
+        // Update cache
+        this.portScanCache.set(port, { pid, timestamp: now });
+        // Clean up expired cache entries periodically (every 100 scans)
+        if (this.portScanCache.size > 100) {
+            const expiry = now - this.PORT_SCAN_CACHE_TTL_MS;
+            for (const [key, value] of this.portScanCache.entries()) {
+                if (value.timestamp < expiry) {
+                    this.portScanCache.delete(key);
+                }
+            }
+        }
+        return pid;
+    }
+    /**
+     * Scan all monitored ports for running processes
+     */
+    async scanMonitoredPorts(states) {
+        const observed = [];
+        const knownPids = new Set();
+        // Build set of known PIDs from state
+        for (const state of states) {
+            if (state.pid) {
+                knownPids.add(state.pid);
+            }
+        }
+        // CRITICAL FIX (Issue 5): Clean up observedProcesses map for dead PIDs
+        // The map was growing unboundedly - evict entries for processes that no longer exist
+        const pidsToEvict = [];
+        for (const [pid] of this.observedProcesses.entries()) {
+            if (!(await isProcessRunning(this.deps.getRuntime(), pid))) {
+                pidsToEvict.push(pid);
+            }
+        }
+        for (const pid of pidsToEvict) {
+            this.observedProcesses.delete(pid);
+            this.logger.debug('evicted dead process from observedProcesses map', { pid });
+        }
+        // Get all ports we monitor from configs
+        const configs = this.deps.configs || new Map();
+        const monitoredPorts = new Set();
+        for (const config of configs.values()) {
+            const ports = await extractMonitoredPorts(this.deps.getRuntime(), config);
+            ports.forEach((p) => monitoredPorts.add(p));
+        }
+        // Also add ports from running states that have ports
+        for (const state of states) {
+            if (state.status === 'running') {
+                const config = configs.get(state.id);
+                if (config) {
+                    const ports = await extractMonitoredPorts(this.deps.getRuntime(), config);
+                    ports.forEach((p) => monitoredPorts.add(p));
+                }
+            }
+        }
+        // Scan each port with caching
+        // A probe that cannot read the port or process table fails the scan (the
+        // daemon's scan tick logs it); it is never an absent process.
+        for (const port of monitoredPorts) {
+            // CRITICAL FIX (Issue 3.4): Use cached port scan
+            const pid = await this.getProcessOnPortCached(port);
+            if (!pid)
+                continue;
+            // Check if we already have this in our state
+            const isKnown = knownPids.has(pid);
+            // If this is a known PID in running state, skip it
+            if (isKnown) {
+                const state = states.find((s) => s.pid === pid);
+                if (state?.status === 'running') {
+                    continue;
+                }
+            }
+            // Get command line for signature matching. Null: the process exited
+            // after the port probe, so there is nothing to observe.
+            const command = await getProcessCommand(this.deps.getRuntime(), pid);
+            if (command === null)
+                continue;
+            // CRITICAL FIX (Issue 3): Verify command consistency to detect PID reuse race
+            // The PID could be reused between lsof and ps calls, giving us wrong command
+            // If we have a previous observation, verify command hasn't changed significantly
+            let observedProc = this.observedProcesses.get(pid);
+            if (observedProc) {
+                // Check if command changed (indicates possible PID reuse)
+                // CRITICAL FIX (Issue 3): Use full command comparison instead of weak substring(0, 20) check
+                const oldCmd = observedProc.command?.toLowerCase() ?? '';
+                const newCmd = command?.toLowerCase() ?? '';
+                // Commands should be identical for the same PID - if they differ significantly, it's likely PID reuse
+                if (oldCmd && newCmd && oldCmd !== newCmd) {
+                    this.logger.warn('PID command changed significantly, possible PID reuse race', {
+                        pid,
+                        port,
+                        oldCommand: observedProc.command?.substring(0, 100),
+                        newCommand: command?.substring(0, 100)
+                    });
+                    // Reset observation with new command
+                    observedProc = undefined;
+                }
+            }
+            if (!observedProc) {
+                observedProc = {
+                    pid,
+                    port,
+                    command,
+                    firstObservedAt: new Date(),
+                    isKnown
+                };
+                this.observedProcesses.set(pid, observedProc);
+            }
+            observed.push(observedProc);
+        }
+        return observed;
+    }
+    /**
+     * Evaluate whether to kill, adopt, wait, or ignore a process
+     */
+    async evaluateProcess(proc, states) {
+        const now = Date.now();
+        const observedDuration = now - proc.firstObservedAt.getTime();
+        const daemonUptime = now - this.daemonStartTime.getTime();
+        // Check if process is actually still running
+        // CRITICAL FIX (Issue 2): isProcessRunning is sync, don't await it
+        if (!(await isProcessRunning(this.deps.getRuntime(), proc.pid))) {
+            return { action: 'ignore', reason: 'Process no longer running' };
+        }
+        // CRITICAL FIX (Issue 3 part 2): Re-verify command to detect PID reuse between scan and evaluation
+        // The PID could have been recycled between scanMonitoredPorts and now
+        const currentCommand = await getProcessCommand(this.deps.getRuntime(), proc.pid);
+        if (currentCommand === null)
+            return { action: 'ignore', reason: 'Process no longer running' };
+        const observedCmd = proc.command?.toLowerCase() ?? '';
+        const currentCmd = currentCommand?.toLowerCase() ?? '';
+        if (observedCmd && currentCmd && observedCmd !== currentCmd) {
+            this.logger.warn('PID command changed between scan and evaluation, PID was likely reused', {
+                pid: proc.pid,
+                port: proc.port,
+                observedCommand: proc.command?.substring(0, 100),
+                currentCommand: currentCommand?.substring(0, 100)
+            });
+            // Treat as if process is no longer running - don't take action on wrong process
+            return { action: 'ignore', reason: 'PID was reused by different process' };
+        }
+        // Find matching config by command signature
+        const matchingConfig = await this.findMatchingConfig(proc);
+        if (matchingConfig) {
+            // Check if we already have a state for this config
+            const existingState = states.find((s) => s.id === matchingConfig.id);
+            if (existingState) {
+                if (existingState.status === 'running' && existingState.pid === proc.pid) {
+                    // Already properly tracked
+                    return { action: 'ignore', reason: 'Process already tracked' };
+                }
+            }
+            // A signature match is NOT ownership. A peer lane on this machine runs
+            // byte-identical argv, and adopting its process means we go on to
+            // restart and eventually kill it. Demand scope before adopting.
+            const ownership = await provePortOwnership({
+                runtime: this.deps.getRuntime(),
+                pid: proc.pid,
+                isOurs: existingState?.pid === proc.pid,
+                signatureMatches: true,
+                configCwd: matchingConfig.cwd,
+                daemonScope: this.deps.daemonScope
+            });
+            if (!ownership.owned) {
+                return {
+                    action: 'refuse',
+                    reason: formatForeignHolderRefusal({
+                        port: proc.port,
+                        pid: proc.pid,
+                        command: proc.command,
+                        holderCwd: ownership.holderCwd,
+                        ourCwd: matchingConfig.cwd,
+                        mismatch: ownership.mismatch,
+                        reason: ownership.reason,
+                        alternatePortHint: `give '${matchingConfig.id}' a port this workspace owns`
+                    })
+                };
+            }
+            if (existingState &&
+                (existingState.status === 'stopped' || existingState.status === 'crashed')) {
+                // State says stopped but process is running - adopt it
+                return {
+                    action: 'adopt',
+                    reason: `Process running but state shows ${existingState.status}`,
+                    matchingConfigId: matchingConfig.id
+                };
+            }
+            // No existing state or in starting/waiting state - adopt
+            return {
+                action: 'adopt',
+                reason: `Command signature matches expected config and scope (${ownership.basis})`,
+                matchingConfigId: matchingConfig.id
+            };
+        }
+        // No matching config — a process this daemon demonstrably did not start.
+        //
+        // This branch used to return `kill` once warmup and a grace period had
+        // elapsed. That is how a scratch daemon in a throwaway VIBES_HOME killed a
+        // peer lane's MCP host on machine-global port 3000: nothing about "we
+        // monitor this port number" makes another user's listener ours. Waiting
+        // longer never turns a stranger into an orphan, so the grace/warmup timers
+        // are gone from this path and the verdict is a loud refusal.
+        void daemonUptime;
+        void observedDuration;
+        return {
+            action: 'refuse',
+            reason: formatForeignHolderRefusal({
+                port: proc.port,
+                pid: proc.pid,
+                command: proc.command,
+                holderCwd: await canonicalizePathOn(await pmFileSystem(this.deps.getRuntime()), await this.resolveHolderCwd(proc.pid)),
+                alternatePortHint: `move the conflicting managed process to a port this workspace owns`
+            })
+        };
+    }
+    /** Seam-friendly cwd read for refusal messages. */
+    async resolveHolderCwd(pid) {
+        const { resolveProcessCwd } = await import("../utils/process-tree.js");
+        return resolveProcessCwd(this.deps.getRuntime(), pid);
+    }
+    /**
+     * Find a config that matches the observed process's command signature AND port.
+     * Returns the matching config if exactly one match; undefined if none; throws (refuse) if ambiguous.
+     */
+    async findMatchingConfig(proc) {
+        if (!proc.command)
+            return undefined;
+        const configs = this.deps.configs;
+        if (!configs)
+            return undefined;
+        const exactMatches = [];
+        const commandMatches = [];
+        for (const config of configs.values()) {
+            // Check if command matches: the selected launch-preparation
+            // provider's identity hook when one applies, else the generic
+            // command-line match.
+            const commandMatchesFlag = await matchesCommandSignature(this.deps.getRuntime(), proc.command, config, proc.port);
+            if (!commandMatchesFlag)
+                continue;
+            commandMatches.push(config);
+            // Require port match for exactness: the config's declared port must equal the observed port
+            const configPorts = await extractMonitoredPorts(this.deps.getRuntime(), config);
+            if (configPorts.length > 0 && configPorts.includes(proc.port)) {
+                exactMatches.push(config);
+            }
+        }
+        // If exactly one config matches by command AND port, adopt it
+        if (exactMatches.length === 1) {
+            return exactMatches[0];
+        }
+        // If no exact matches but command matches exist, refuse (ambiguous or wrong port)
+        if (exactMatches.length === 0 && commandMatches.length > 0) {
+            // Multiple configs match by command but on wrong ports, or port mismatch
+            this.logger.warn('process command matches multiple configs but port does not match declared ports', {
+                pid: proc.pid,
+                port: proc.port,
+                command: proc.command?.slice(0, 100),
+                matchingConfigIds: commandMatches.map(c => c.id)
+            });
+            return undefined;
+        }
+        // If multiple exact matches (impossible for real listeners, but possible if state is stale)
+        if (exactMatches.length > 1) {
+            this.logger.warn('process matches multiple configs exactly (command + port)', {
+                pid: proc.pid,
+                port: proc.port,
+                matchingConfigIds: exactMatches.map(c => c.id)
+            });
+            return undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Adopt a process into our state
+     * Only adopts if the PID is not already tracked (idempotency).
+     */
+    async adoptProcess(observed, configId, states) {
+        // Check if pid is already tracked in ANY state (idempotency - per brief: if ANY tracked process state already has this pid (alive), skip)
+        const alreadyTracked = states.find((s) => s.pid === observed.pid && s.status === 'running');
+        if (alreadyTracked) {
+            this.logger.debug('pid already tracked in state, not re-adopting', {
+                processId: alreadyTracked.id,
+                pid: observed.pid
+            });
+            return;
+        }
+        this.logger.info('adopting pre-daemon process', {
+            processId: configId,
+            pid: observed.pid,
+            port: observed.port,
+            command: observed.command?.substring(0, 100)
+        });
+        // CRITICAL FIX (Issue 5): Use simple PID check for adoption, not full health checks
+        // The full checkProcessLiveness checks sockets/HTTP endpoints which may not be set up
+        // correctly for pre-daemon processes. A simple PID check is sufficient for adoption.
+        if (!(await isProcessRunning(this.deps.getRuntime(), observed.pid))) {
+            this.logger.warn('process no longer running, not adopting', {
+                processId: configId,
+                pid: observed.pid
+            });
+            return;
+        }
+        // Get existing state or create adoption state
+        let state = await this.deps.store.get(configId);
+        const now = new Date();
+        const isStateChange = !state || state.status !== 'running' || state.pid !== observed.pid;
+        if (state) {
+            // Update existing state
+            await this.deps.store.update(configId, {
+                pid: observed.pid,
+                status: 'running',
+                firstObservedAt: observed.firstObservedAt,
+                commandSignature: observed.command?.substring(0, 200) ?? undefined,
+                adopted: true,
+                lastActivity: now,
+                lastError: state.lastError
+                    ? `${state.lastError} (adopted by orphan scanner at ${now.toISOString()})`
+                    : `Adopted by orphan scanner at ${now.toISOString()}`
+            });
+        }
+        else {
+            // Create new state for adopted process
+            await this.deps.store.set({
+                id: configId,
+                pid: observed.pid,
+                status: 'running',
+                startedAt: now,
+                firstObservedAt: observed.firstObservedAt,
+                commandSignature: observed.command?.substring(0, 200) ?? undefined,
+                adopted: true,
+                lastActivity: now,
+                restartCount: 0,
+                consecutiveCrashRestarts: 0,
+                retryCount: 0
+            });
+        }
+        // Log state change at info level only
+        if (isStateChange) {
+            this.logger.info('adopted process into state', {
+                processId: configId,
+                pid: observed.pid,
+                wasRestart: !!state
+            });
+        }
+        // CRITICAL FIX (Issue 5): Clean up observedProcesses map after adopting
+        // The process is now tracked in state, remove from observation map to prevent memory leak
+        this.observedProcesses.delete(observed.pid);
+    }
+}
+//# sourceMappingURL=orphan-scanner.js.map