browser-debugger-cli 0.6.6 → 0.6.7

package/dist/session/QueryCacheManager.js

@@ -0,0 +1,233 @@
+/**
+ * Query cache manager for DOM element index-based access.
+ *
+ * Provides centralized management of DOM query result caching with:
+ * - Singleton pattern for consistent cache access
+ * - Navigation-aware staleness detection
+ * - TTL-based navigation ID caching to reduce IPC calls
+ *
+ * The cache enables index-based element access patterns like
+ * "bdg dom get 0" after running "bdg dom query .selector".
+ *
+ * @example
+ * ```typescript
+ * const manager = QueryCacheManager.getInstance();
+ *
+ * // Store query results
+ * await manager.set(queryResult);
+ *
+ * // Validate and retrieve (throws if stale)
+ * const validation = await manager.validate();
+ * if (validation.valid) {
+ *   const cache = validation.cache;
+ * }
+ * ```
+ */
+import { existsSync } from 'fs';
+import { readFile, rm, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { getErrorMessage } from '../connection/errors.js';
+import { getSessionDir } from '../session/paths.js';
+import { createLogger } from '../ui/logging/index.js';
+const log = createLogger('session');
+/** TTL for cached navigation ID (500ms). */
+const NAVIGATION_ID_CACHE_TTL_MS = 500;
+/**
+ * Singleton manager for DOM query result caching.
+ *
+ * Centralizes all cache operations with navigation-aware staleness detection.
+ * Uses file-based persistence for cross-process access.
+ */
+export class QueryCacheManager {
+    static instance = null;
+    /** Cached navigation ID with timestamp for TTL-based invalidation. */
+    cachedNavigationId = null;
+    /**
+     * Get the singleton instance.
+     *
+     * @returns QueryCacheManager instance
+     */
+    static getInstance() {
+        QueryCacheManager.instance ??= new QueryCacheManager();
+        return QueryCacheManager.instance;
+    }
+    /**
+     * Reset the singleton instance (for testing).
+     */
+    static resetInstance() {
+        QueryCacheManager.instance = null;
+    }
+    /**
+     * Get path to query cache file.
+     *
+     * @returns Absolute path to query-cache.json
+     */
+    getCachePath() {
+        return join(getSessionDir(), 'query-cache.json');
+    }
+    /**
+     * Store query results for index-based access.
+     *
+     * Writes results to ~/.bdg/query-cache.json for cross-process access.
+     *
+     * @param result - DOM query result to cache
+     */
+    async set(result) {
+        try {
+            const cachePath = this.getCachePath();
+            await writeFile(cachePath, JSON.stringify(result), 'utf-8');
+            log.debug(`Cached ${result.nodes.length} query results to ${cachePath}`);
+        }
+        catch (error) {
+            log.debug(`Failed to write query cache: ${getErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Get validated cache results.
+     *
+     * Returns null if cache is stale or doesn't exist.
+     * Use getRaw() for unchecked access.
+     *
+     * @returns Cached query result or null if invalid/missing
+     */
+    async get() {
+        const validation = await this.validate();
+        return validation.valid ? validation.cache : null;
+    }
+    /**
+     * Get raw cache without validation.
+     *
+     * Reads from ~/.bdg/query-cache.json if it exists.
+     * Does not check navigation staleness.
+     *
+     * @returns Cached query result or null if no cache exists
+     */
+    async getRaw() {
+        try {
+            const cachePath = this.getCachePath();
+            if (!existsSync(cachePath)) {
+                return null;
+            }
+            const content = await readFile(cachePath, 'utf-8');
+            const result = JSON.parse(content);
+            log.debug(`Retrieved ${result.nodes.length} cached query results`);
+            return result;
+        }
+        catch (error) {
+            log.debug(`Failed to read query cache: ${getErrorMessage(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Validate cache against current navigation state.
+     *
+     * Checks if the cached query results are still valid by comparing
+     * the stored navigationId with the current one from the daemon.
+     *
+     * @returns Validation result with cache and error info
+     *
+     * @example
+     * ```typescript
+     * const validation = await manager.validate();
+     * if (!validation.valid) {
+     *   throw new CommandError(validation.error, { suggestion: validation.suggestion });
+     * }
+     * const cache = validation.cache;
+     * ```
+     */
+    async validate() {
+        const cache = await this.getRaw();
+        if (!cache) {
+            return {
+                valid: false,
+                cache: null,
+                error: 'No cached query results found',
+                suggestion: 'Run "bdg dom query <selector>" first to generate indexed results',
+            };
+        }
+        if (cache.navigationId === undefined) {
+            log.debug('Query cache missing navigationId (legacy format), allowing access');
+            return { valid: true, cache };
+        }
+        const currentNavId = await this.getCurrentNavigationId();
+        if (currentNavId === null) {
+            log.debug('Could not get current navigationId, allowing cache access');
+            return { valid: true, cache };
+        }
+        if (cache.navigationId !== currentNavId) {
+            return {
+                valid: false,
+                cache,
+                error: `Query cache is stale (page has navigated since query was run)`,
+                suggestion: `Re-run "bdg dom query ${cache.selector}" to refresh cached results`,
+            };
+        }
+        return { valid: true, cache };
+    }
+    /**
+     * Clear the query cache.
+     *
+     * Removes ~/.bdg/query-cache.json.
+     * Called when starting a new query or when the session ends.
+     */
+    async clear() {
+        try {
+            const cachePath = this.getCachePath();
+            if (existsSync(cachePath)) {
+                await rm(cachePath, { force: true });
+                log.debug('Cleared query cache');
+            }
+        }
+        catch (error) {
+            log.debug(`Failed to clear query cache: ${getErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Check if cache file exists.
+     *
+     * @returns True if cache file exists
+     */
+    exists() {
+        return existsSync(this.getCachePath());
+    }
+    /**
+     * Get current navigation ID from the daemon.
+     *
+     * Caches the result for 500ms to avoid redundant IPC calls within a single
+     * command execution while ensuring freshness for subsequent commands.
+     *
+     * @returns Current navigation ID or null if unavailable
+     */
+    async getCurrentNavigationId() {
+        if (this.cachedNavigationId &&
+            Date.now() - this.cachedNavigationId.timestamp < NAVIGATION_ID_CACHE_TTL_MS) {
+            return this.cachedNavigationId.value;
+        }
+        try {
+            const { getStatus } = await import('../ipc/client.js');
+            const response = await getStatus();
+            if (response.status === 'ok' && response.data?.navigationId !== undefined) {
+                this.cachedNavigationId = {
+                    value: response.data.navigationId,
+                    timestamp: Date.now(),
+                };
+                return response.data.navigationId;
+            }
+            return null;
+        }
+        catch (error) {
+            log.debug(`Failed to get current navigation ID: ${getErrorMessage(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Invalidate cached navigation ID.
+     *
+     * Forces fresh fetch on next getCurrentNavigationId() call.
+     * Useful after navigation events.
+     */
+    invalidateNavigationCache() {
+        this.cachedNavigationId = null;
+    }
+}
+//# sourceMappingURL=QueryCacheManager.js.map

package/dist/session/QueryCacheManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryCacheManager.js","sourceRoot":"","sources":["../../src/session/QueryCacheManager.ts"],"names":[],"mappings":"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"}

package/dist/session/cleanup.d.ts

@@ -75,5 +75,67 @@ export declare function cleanupStaleDaemonPid(): boolean;
  * }
  * ```
  */
-export declare function cleanupOrphanedDaemons(): number;
+export declare function cleanupOrphanedDaemons(): Promise<number>;
+/**
+ * Options for unified session cleanup.
+ */
+export interface SessionCleanupOptions {
+    /** Kill the associated Chrome process. */
+    killChrome?: boolean | undefined;
+    /** Force cleanup even if session appears active. */
+    force?: boolean | undefined;
+    /** Aggressively kill all orphaned processes. */
+    aggressive?: boolean | undefined;
+    /** Also remove the session.json output file. */
+    removeOutput?: boolean | undefined;
+    /** Chrome PID from daemon response (for stop command). */
+    chromePid?: number | undefined;
+}
+/**
+ * Result of session cleanup operation.
+ */
+export interface SessionCleanupResult {
+    /** What was cleaned up. */
+    cleaned: {
+        /** Session files (PID, metadata, socket, lock). */
+        session: boolean;
+        /** Chrome browser process. */
+        chrome: boolean;
+        /** Orphaned daemon processes. */
+        daemons: boolean;
+        /** Session output file (session.json). */
+        output: boolean;
+    };
+    /** Number of orphaned daemons killed. */
+    orphanedDaemonsCount: number;
+    /** Warnings encountered during cleanup. */
+    warnings: string[];
+}
+/**
+ * Unified session cleanup for stop and cleanup commands.
+ *
+ * Consolidates cleanup logic from stop.ts and cleanup.ts into a single
+ * reusable function. Handles Chrome processes, daemon PIDs, session files,
+ * and orphaned processes.
+ *
+ * @param options - Cleanup options
+ * @returns Cleanup result with what was cleaned and any warnings
+ *
+ * @example
+ * ```typescript
+ * // From stop command
+ * const result = await performSessionCleanup({
+ *   killChrome: opts.killChrome,
+ *   chromePid: response.chromePid,
+ * });
+ *
+ * // From cleanup command
+ * const result = await performSessionCleanup({
+ *   force: true,
+ *   aggressive: true,
+ *   removeOutput: true,
+ * });
+ * ```
+ */
+export declare function performSessionCleanup(options: SessionCleanupOptions): Promise<SessionCleanupResult>;
 //# sourceMappingURL=cleanup.d.ts.map

package/dist/session/cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/session/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2GH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CA0F7C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,IAAI,IAAI,CA6BrC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAoD/C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAuB/C"}
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/session/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgHH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAmE7C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAcrC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAoD/C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC,CAuB9D;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,gDAAgD;IAChD,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,gDAAgD;IAChD,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,OAAO,EAAE;QACP,mDAAmD;QACnD,OAAO,EAAE,OAAO,CAAC;QACjB,8BAA8B;QAC9B,MAAM,EAAE,OAAO,CAAC;QAChB,iCAAiC;QACjC,OAAO,EAAE,OAAO,CAAC;QACjB,0CAA0C;QAC1C,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,yCAAyC;IACzC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAyHD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAkD/B"}

package/dist/session/cleanup.js

@@ -4,16 +4,20 @@
  * Handles cleanup of session files (PID, metadata, lock, socket).
  * WHY: Centralized cleanup logic ensures consistent cleanup across error paths and normal shutdown.
  */
-import { execSync } from 'child_process';
+import { exec } from 'child_process';
 import * as fs from 'fs';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
 import { getErrorMessage } from '../connection/errors.js';
-import { createLogger } from '../ui/logging/index.js';
+import { createLogger, logDebugError } from '../ui/logging/index.js';
+import { safeRemoveFile } from '../utils/file.js';
 import { isProcessAlive, killChromeProcess } from '../utils/process.js';
+import { QueryCacheManager } from './QueryCacheManager.js';
 import { readChromePid, clearChromePid } from './chrome.js';
 import { acquireSessionLock, releaseSessionLock } from './lock.js';
 import { getSessionFilePath, ensureSessionDir } from './paths.js';
 import { readPid, cleanupPidFile, readPidFromFile } from './pid.js';
-import { clearSessionQueryCache } from './queryCache.js';
+// Note: QueryCacheManager must be after chrome.js per alphabetical order
 const log = createLogger('cleanup');
 function killOrphanedWorker(pid) {
     try {
@@ -52,7 +56,7 @@ function killCachedChromeProcess(reason) {
  *
  * @returns Array of orphaned daemon PIDs
  */
-function findOrphanedDaemons() {
+async function findOrphanedDaemons() {
     const orphanedPids = [];
     try {
         const daemonPidPath = getSessionFilePath('DAEMON_PID');
@@ -60,7 +64,7 @@ function findOrphanedDaemons() {
         const psCommand = process.platform === 'win32'
             ? 'wmic process where "commandline like \'%dist/daemon.js%\'" get processid'
             : 'ps aux | grep -E "node.*dist/daemon\\.js" | grep -v grep';
-        const output = execSync(psCommand, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] });
+        const { stdout: output } = await execAsync(psCommand);
         const lines = output.trim().split('\n');
         for (const line of lines) {
             let pid;
@@ -90,7 +94,7 @@ function findOrphanedDaemons() {
         }
     }
     catch (error) {
-        log.debug(`Failed to find orphaned daemons: ${getErrorMessage(error)}`);
+        logDebugError(log, 'find orphaned daemons', error);
     }
     return orphanedPids;
 }
@@ -127,14 +131,9 @@ export function cleanupStaleSession() {
             }
         }
         catch (error) {
-            log.debug(`Failed to read stale session lock: ${getErrorMessage(error)}`);
-        }
-        try {
-            fs.rmSync(lockPath, { force: true });
-        }
-        catch (error) {
-            log.debug(`Failed to remove stale session lock: ${getErrorMessage(error)}`);
+            logDebugError(log, 'read stale session lock', error);
         }
+        safeRemoveFile(lockPath, 'stale session lock', log);
         if (!acquireSessionLock()) {
             return false;
         }
@@ -160,30 +159,10 @@ export function cleanupStaleSession() {
         log.info('Removing stale session files...');
         killCachedChromeProcess('stale session cleanup');
         cleanupPidFile();
-        try {
-            fs.rmSync(getSessionFilePath('METADATA'), { force: true });
-        }
-        catch (error) {
-            log.debug(`Failed to remove metadata file: ${getErrorMessage(error)}`);
-        }
-        try {
-            fs.rmSync(daemonPidPath, { force: true });
-        }
-        catch (error) {
-            log.debug(`Failed to remove daemon PID file: ${getErrorMessage(error)}`);
-        }
-        try {
-            fs.rmSync(getSessionFilePath('DAEMON_SOCKET'), { force: true });
-        }
-        catch (error) {
-            log.debug(`Failed to remove daemon socket: ${getErrorMessage(error)}`);
-        }
-        try {
-            fs.rmSync(getSessionFilePath('DAEMON_LOCK'), { force: true });
-        }
-        catch (error) {
-            log.debug(`Failed to remove daemon lock: ${getErrorMessage(error)}`);
-        }
+        safeRemoveFile(getSessionFilePath('METADATA'), 'metadata file', log);
+        safeRemoveFile(daemonPidPath, 'daemon PID file', log);
+        safeRemoveFile(getSessionFilePath('DAEMON_SOCKET'), 'daemon socket', log);
+        safeRemoveFile(getSessionFilePath('DAEMON_LOCK'), 'daemon lock', log);
         log.info('Stale session cleanup complete');
         return true;
     }
@@ -215,31 +194,15 @@ export function cleanupStaleSession() {
 export function cleanupSession() {
     cleanupPidFile();
     releaseSessionLock();
-    try {
-        fs.rmSync(getSessionFilePath('METADATA'), { force: true });
-    }
-    catch (error) {
-        log.debug(`Failed to remove metadata file: ${getErrorMessage(error)}`);
-    }
-    try {
-        fs.rmSync(getSessionFilePath('DAEMON_PID'), { force: true });
-    }
-    catch (error) {
-        log.debug(`Failed to remove daemon PID file: ${getErrorMessage(error)}`);
-    }
-    try {
-        fs.rmSync(getSessionFilePath('DAEMON_SOCKET'), { force: true });
-    }
-    catch (error) {
-        log.debug(`Failed to remove daemon socket: ${getErrorMessage(error)}`);
-    }
-    try {
-        fs.rmSync(getSessionFilePath('DAEMON_LOCK'), { force: true });
-    }
-    catch (error) {
-        log.debug(`Failed to remove daemon lock: ${getErrorMessage(error)}`);
-    }
-    clearSessionQueryCache();
+    safeRemoveFile(getSessionFilePath('METADATA'), 'metadata file', log);
+    safeRemoveFile(getSessionFilePath('DAEMON_PID'), 'daemon PID file', log);
+    safeRemoveFile(getSessionFilePath('DAEMON_SOCKET'), 'daemon socket', log);
+    safeRemoveFile(getSessionFilePath('DAEMON_LOCK'), 'daemon lock', log);
+    void QueryCacheManager.getInstance()
+        .clear()
+        .catch((error) => {
+        logDebugError(log, 'clear query cache', error);
+    });
 }
 /**
  * Cleanup stale daemon PID file if daemon process is dead.
@@ -319,8 +282,8 @@ export function cleanupStaleDaemonPid() {
  * }
  * ```
  */
-export function cleanupOrphanedDaemons() {
-    const orphanedPids = findOrphanedDaemons();
+export async function cleanupOrphanedDaemons() {
+    const orphanedPids = await findOrphanedDaemons();
     if (orphanedPids.length === 0) {
         log.debug('No orphaned daemon processes found');
         return 0;
@@ -334,9 +297,172 @@ export function cleanupOrphanedDaemons() {
             killedCount++;
         }
         catch (error) {
-            log.debug(`Failed to kill orphaned daemon ${pid}: ${getErrorMessage(error)}`);
+            logDebugError(log, `kill orphaned daemon ${pid}`, error);
         }
     }
     return killedCount;
 }
+function createCleanupState() {
+    return {
+        warnings: [],
+        sessionCleaned: false,
+        chromeCleaned: false,
+        daemonsCleaned: false,
+        outputCleaned: false,
+        orphanedDaemonsCount: 0,
+    };
+}
+/**
+ * Kill a specific Chrome process by PID.
+ */
+function cleanupChromeProcess(chromePid, clearChromePid, state) {
+    try {
+        killChromeProcess(chromePid, 'SIGTERM');
+        state.chromeCleaned = true;
+        clearChromePid();
+    }
+    catch (error) {
+        state.warnings.push(`Could not kill Chrome: ${getErrorMessage(error)}`);
+    }
+}
+/**
+ * Clean up stale daemon PID file and update state.
+ */
+function cleanupDaemonPidIfStale(state) {
+    const daemonPidPath = getSessionFilePath('DAEMON_PID');
+    if (!fs.existsSync(daemonPidPath)) {
+        return;
+    }
+    try {
+        const daemonPidStr = fs.readFileSync(daemonPidPath, 'utf-8').trim();
+        const daemonPid = parseInt(daemonPidStr, 10);
+        if (Number.isNaN(daemonPid) || !isProcessAlive(daemonPid)) {
+            log.info(`Removing stale daemon PID file (PID ${daemonPid})`);
+            fs.unlinkSync(daemonPidPath);
+            state.sessionCleaned = true;
+        }
+    }
+    catch {
+        try {
+            fs.unlinkSync(daemonPidPath);
+            state.sessionCleaned = true;
+        }
+        catch (removeError) {
+            state.warnings.push(`Could not remove daemon.pid: ${getErrorMessage(removeError)}`);
+        }
+    }
+}
+/**
+ * Clean up active session, optionally forcing cleanup if still running.
+ */
+async function cleanupActiveSession(force, cleanupStaleChrome, state) {
+    const sessionPid = readPid();
+    if (!sessionPid) {
+        return;
+    }
+    const isAlive = isProcessAlive(sessionPid);
+    if (isAlive && !force) {
+        return;
+    }
+    if (isAlive && force) {
+        state.warnings.push(`Process ${sessionPid} is still running but forcing cleanup anyway`);
+        log.info(`Force cleanup: killing Chrome for active session ${sessionPid}`);
+        try {
+            await cleanupStaleChrome();
+            state.chromeCleaned = true;
+        }
+        catch (error) {
+            state.warnings.push(`Could not kill Chrome processes: ${getErrorMessage(error)}`);
+        }
+    }
+    cleanupSession();
+    state.sessionCleaned = true;
+}
+/**
+ * Clean up session output file.
+ */
+function cleanupOutputFile(state) {
+    const outputPath = getSessionFilePath('OUTPUT');
+    if (!fs.existsSync(outputPath)) {
+        return;
+    }
+    try {
+        fs.unlinkSync(outputPath);
+        state.outputCleaned = true;
+    }
+    catch (error) {
+        state.warnings.push(`Could not remove session.json: ${getErrorMessage(error)}`);
+    }
+}
+/**
+ * Unified session cleanup for stop and cleanup commands.
+ *
+ * Consolidates cleanup logic from stop.ts and cleanup.ts into a single
+ * reusable function. Handles Chrome processes, daemon PIDs, session files,
+ * and orphaned processes.
+ *
+ * @param options - Cleanup options
+ * @returns Cleanup result with what was cleaned and any warnings
+ *
+ * @example
+ * ```typescript
+ * // From stop command
+ * const result = await performSessionCleanup({
+ *   killChrome: opts.killChrome,
+ *   chromePid: response.chromePid,
+ * });
+ *
+ * // From cleanup command
+ * const result = await performSessionCleanup({
+ *   force: true,
+ *   aggressive: true,
+ *   removeOutput: true,
+ * });
+ * ```
+ */
+export async function performSessionCleanup(options) {
+    const { cleanupStaleChrome, clearChromePid } = await import('./chrome.js');
+    const state = createCleanupState();
+    if (options.aggressive) {
+        const daemonsKilled = await cleanupOrphanedDaemons();
+        if (daemonsKilled > 0) {
+            state.daemonsCleaned = true;
+            state.orphanedDaemonsCount = daemonsKilled;
+            console.error(`✓ Killed ${daemonsKilled} orphaned daemon process(es)`);
+        }
+        const errorCount = await cleanupStaleChrome();
+        state.chromeCleaned = true;
+        if (errorCount > 0) {
+            state.warnings.push('Some Chrome processes could not be killed');
+        }
+    }
+    if (options.killChrome && options.chromePid) {
+        cleanupChromeProcess(options.chromePid, clearChromePid, state);
+    }
+    else if (options.killChrome && !options.chromePid) {
+        state.warnings.push('Chrome PID not found (Chrome was not launched by bdg)');
+    }
+    cleanupDaemonPidIfStale(state);
+    await cleanupActiveSession(options.force ?? false, cleanupStaleChrome, state);
+    if (!options.aggressive) {
+        const daemonsKilled = await cleanupOrphanedDaemons();
+        if (daemonsKilled > 0) {
+            state.daemonsCleaned = true;
+            state.orphanedDaemonsCount = daemonsKilled;
+        }
+    }
+    if (options.removeOutput) {
+        cleanupOutputFile(state);
+    }
+    return {
+        cleaned: {
+            session: state.sessionCleaned,
+            chrome: state.chromeCleaned,
+            daemons: state.daemonsCleaned,
+            output: state.outputCleaned,
+        },
+        orphanedDaemonsCount: state.orphanedDaemonsCount,
+        warnings: state.warnings,
+    };
+}
 //# sourceMappingURL=cleanup.js.map