Remove process exit signal handler (#1275)

miguelg719 · web-flow · commit a372b3c6f059 · 2025-11-21T16:26:16.000-08:00
# why
`process.exit()` calls and signal handlers in BaseCache.ts were causing
immediate process termination, interfering with applications' graceful
shutdown logic that waits for active jobs to complete.

  # what changed

  - Removed SIGINT/SIGTERM handlers from BaseCache.ts
  - Removed `process.exit()` calls from BaseCache.ts and lib/index.ts
  - Kept passive 'exit' event handler for lock cleanup

  # test plan
diff --git a/.changeset/cuddly-ears-report.md b/.changeset/cuddly-ears-report.md
@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Remove process exit on signal handler
diff --git a/evals/deterministic/tests/browserbase/sessions.test.ts b/evals/deterministic/tests/browserbase/sessions.test.ts
@@ -23,7 +23,7 @@ test.describe("Browserbase Sessions", () => {
     });
     await bigStagehand.init();
     await bigStagehand.page.goto(
-      "https://docs.stagehand.dev/first-steps/introduction",
+      "https://docs.stagehand.dev/v3/first-steps/introduction",
     );
     sessionId = bigStagehand.browserbaseSessionID;
     if (!sessionId) {
@@ -45,7 +45,7 @@ test.describe("Browserbase Sessions", () => {
     const page = stagehand.page;
 
     expect(page.url()).toBe(
-      "https://docs.stagehand.dev/first-steps/introduction",
+      "https://docs.stagehand.dev/v3/first-steps/introduction",
     );
   });
   test("resumes a session via CDP URL", async () => {
@@ -63,7 +63,7 @@ test.describe("Browserbase Sessions", () => {
     const page = stagehand.page;
 
     expect(page.url()).toBe(
-      "https://docs.stagehand.dev/first-steps/introduction",
+      "https://docs.stagehand.dev/v3/first-steps/introduction",
     );
   });
 });
diff --git a/lib/cache/BaseCache.ts b/lib/cache/BaseCache.ts
@@ -43,34 +43,17 @@ export class BaseCache<T extends CacheEntry> {
   }
 
   private setupProcessHandlers(): void {
-    const releaseLockAndExit = () => {
+    const releaseLockOnExit = () => {
       this.releaseLock();
-      process.exit();
     };
 
-    process.on("exit", releaseLockAndExit);
-    process.on("SIGINT", releaseLockAndExit);
-    process.on("SIGTERM", releaseLockAndExit);
-    process.on("uncaughtException", (err) => {
-      this.logger({
-        category: "base_cache",
-        message: "uncaught exception",
-        level: 2,
-        auxiliary: {
-          error: {
-            value: err.message,
-            type: "string",
-          },
-          trace: {
-            value: err.stack,
-            type: "string",
-          },
-        },
-      });
-      if (this.lockAcquired) {
-        releaseLockAndExit();
-      }
-    });
+    // Passive cleanup on exit - doesn't interfere with signal handling
+    process.on("exit", releaseLockOnExit);
+
+    // Note: We intentionally do NOT handle SIGINT/SIGTERM here.
+    // Applications using Stagehand as a library should manage their own
+    // signal handlers for graceful shutdown, and call cleanup methods
+    // (like releaseLock or a future dispose() method) explicitly.
   }
 
   protected ensureCacheDirectory(): void {
diff --git a/lib/index.ts b/lib/index.ts
@@ -698,7 +698,6 @@ export class Stagehand {
         });
       } finally {
         // Exit explicitly once cleanup is done
-        process.exit(0);
       }
     };
 

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@browserbasehq/stagehand": patch
 +---
++
 +Remove process exit on signal handler
Original file line number	Diff line number	Diff line change
`@@ -698,7 +698,6 @@ export class Stagehand {`
`698`	`698`	`});`
`699`	`699`	`} finally {`
`700`	`700`	`// Exit explicitly once cleanup is done`
`701`		`- process.exit(0);`
`702`	`701`	`}`
`703`	`702`	`};`
`704`	`703`