fix: always run session end hooks on all shutdown paths

Ensure |onBeforeSessionEnd|, |onSessionEnd| and |onAfterSessionEnd| are always executed.

- Route |SECURITY_VIOLATION| through endSession()
- Trigger `onSessionEnd` on launch failures
- Preserve shutdown reason across lifecycle

Author: jagadeshjai

api/src/services/cdp/cdp.service.ts

@@ -69,7 +69,7 @@ import {
   SessionContextType,
   categorizeError,
 } from "./errors/launch-errors.js";
-import { BasePlugin } from "./plugins/core/base-plugin.js";
+import { BasePlugin, ShutdownReason } from "./plugins/core/base-plugin.js";
 import { PluginManager } from "./plugins/core/plugin-manager.js";
 import { isSimilarConfig, validateLaunchConfig, validateTimezone } from "./utils/validation.js";
 import { TargetInstrumentationManager } from "./instrumentation/target-manager.js";
@@ -376,7 +376,7 @@ export class CDPService extends EventEmitter {
               `[CDPService] Blocked response from file protocol: ${response.url()}`,
             );
             page.close().catch(() => {});
-            this.shutdown();
+            this.endSession(ShutdownReason.SECURITY_VIOLATION);
           }
         });
       }
@@ -436,7 +436,7 @@ export class CDPService extends EventEmitter {
     if (url.startsWith("file://")) {
       this.logger.error(`[CDPService] Blocked request to file protocol: ${url}`);
       page.close().catch(() => {});
-      this.shutdown();
+      this.endSession(ShutdownReason.SECURITY_VIOLATION);
     } else {
       await request.continue({ headers });
     }
@@ -456,16 +456,16 @@ export class CDPService extends EventEmitter {
   }
 
   @traceable
-  public async shutdown(): Promise<void> {
+  public async shutdown(reason: ShutdownReason): Promise<void> {
     this.shuttingDown = true;
-    this.logger.info(`[CDPService] Shutting down and cleaning up resources`);
+    this.logger.info(`[CDPService] Shutting down and cleaning up resources (reason: ${reason})`);
 
     try {
       if (this.browserInstance) {
         await this.pluginManager.onBrowserClose(this.browserInstance);
       }
 
-      await this.pluginManager.onShutdown();
+      await this.pluginManager.onShutdown(reason);
 
       this.removeAllHandlers();
       await this.browserInstance?.close();
@@ -527,7 +527,7 @@ export class CDPService extends EventEmitter {
         return await this.launchInternal(config);
       } catch (error) {
         try {
-          await this.pluginManager.onShutdown();
+          await this.pluginManager.onShutdown(ShutdownReason.LAUNCH_FAILURE);
           await this.shutdownHook();
         } catch (e) {
           this.logger.warn(
@@ -609,7 +609,7 @@ export class CDPService extends EventEmitter {
           );
           await executeBestEffort(
             this.logger,
-            async () => this.shutdown(),
+            async () => this.shutdown(ShutdownReason.RELAUNCH),
             "Error during shutdown before launch",
           );
         }
@@ -1278,21 +1278,24 @@ export class CDPService extends EventEmitter {
     try {
       return await this.launch(sessionConfig);
     } catch (error) {
+      // If launch fails, ensure we still notify plugins about session end to allow for proper cleanup
+      await this.pluginManager.onBeforeSessionEnd(sessionConfig);
+      await this.pluginManager.onSessionEnd(sessionConfig);
       await this.pluginManager.onAfterSessionEnd(sessionConfig);
       throw error;
     }
   }
 
   @traceable
-  public async endSession(): Promise<void> {
+  public async endSession(reason: ShutdownReason = ShutdownReason.SESSION_END): Promise<void> {
     this.logger.info("Ending current session and resetting to default configuration.");
     const sessionConfig = this.currentSessionConfig!;
 
     this.sessionContext = await this.getBrowserState().catch(() => null);
 
     try {
       await this.pluginManager.onBeforeSessionEnd(sessionConfig);
-      await this.shutdown();
+      await this.shutdown(reason);
       await this.pluginManager.onSessionEnd(sessionConfig);
       this.currentSessionConfig = null;
       this.sessionContext = null;

api/src/services/cdp/plugins/core/base-plugin.ts

@@ -2,6 +2,23 @@ import type { Browser, Page } from "puppeteer-core";
 import type { CDPService } from "../../cdp.service.js";
 import type { BrowserLauncherOptions } from "../../../../types/browser.js";
 
+/**
+ * Reason why the browser is being shut down.
+ * Plugins can use this to decide what cleanup actions to take.
+ */
+export enum ShutdownReason {
+  /** Normal session end — user or system ended the session gracefully */
+  SESSION_END = "session_end",
+  /** Security violation detected (e.g. file:// protocol access) */
+  SECURITY_VIOLATION = "security_violation",
+  /** Browser is being relaunched (closing old instance before new launch) */
+  RELAUNCH = "relaunch",
+  /** Browser launch failed — cleanup before retry */
+  LAUNCH_FAILURE = "launch_failure",
+  /** Switching to a different browser mode (e.g. CDP → Selenium) */
+  MODE_SWITCH = "mode_switch",
+}
+
 export interface PluginOptions {
   name: string;
   [key: string]: any;
@@ -33,7 +50,7 @@ export abstract class BasePlugin {
   public async onPageUnload(page: Page): Promise<void> {}
   public async onBrowserClose(browser: Browser): Promise<void> {}
   public async onBeforePageClose(page: Page): Promise<void> {}
-  public async onShutdown(): Promise<void> {}
+  public async onShutdown(reason: ShutdownReason): Promise<void> {}
   public async onSessionEnd(sessionConfig: BrowserLauncherOptions): Promise<void> {}
 }
 

api/src/services/cdp/plugins/core/plugin-manager.ts

@@ -1,6 +1,6 @@
 import { Browser, Page } from "puppeteer-core";
 import { CDPService } from "../../cdp.service.js";
-import { BasePlugin } from "./base-plugin.js";
+import { BasePlugin, ShutdownReason } from "./base-plugin.js";
 import { FastifyBaseLogger } from "fastify";
 import { BrowserLauncherOptions } from "../../../../types/browser.js";
 
@@ -190,10 +190,10 @@ export class PluginManager {
   /**
    * Notify all plugins about shutdown
    */
-  public async onShutdown(): Promise<void> {
+  public async onShutdown(reason: ShutdownReason): Promise<void> {
     const promises = Array.from(this.plugins.values()).map(async (plugin) => {
       try {
-        await plugin.onShutdown();
+        await plugin.onShutdown(reason);
       } catch (error) {
         this.logger.error(`Error in plugin ${plugin.name}.onShutdown: ${error}`);
       }

api/src/services/session.service.ts

@@ -11,6 +11,7 @@ import { BrowserLauncherOptions, OptimizeBandwidthOptions } from "../types/index
 import { IProxyServer, ProxyServer } from "../utils/proxy.js";
 import { getBaseUrl, getUrl } from "../utils/url.js";
 import { CDPService } from "./cdp/cdp.service.js";
+import { ShutdownReason } from "./cdp/plugins/core/base-plugin.js";
 import { CookieData } from "./context/types.js";
 import { FileService } from "./file.service.js";
 import { SeleniumService } from "./selenium.service.js";
@@ -224,7 +225,7 @@ export class SessionService {
     };
 
     if (isSelenium) {
-      await this.cdpService.shutdown();
+      await this.cdpService.shutdown(ShutdownReason.MODE_SWITCH);
       await this.seleniumService.launch(browserLauncherOptions);
 
       Object.assign(this.activeSession, {