fix(runtime): block session creation during companion shutdown

packages/runtime/src/index.test.ts

@@ -329,4 +329,32 @@ describe("BrowserRuntime", () => {
       message: "other failure",
     });
   });
+
+  it("rejects createSession after shutdown without relaunching the browser", async () => {
+    const { browser } = createMockBrowserTree();
+    mockChromiumLaunch.mockResolvedValueOnce(browser);
+
+    const rt = new BrowserRuntime({ headless: true });
+    await rt.createSession();
+    await rt.shutdown();
+
+    mockChromiumLaunch.mockClear();
+    await expect(rt.createSession()).rejects.toMatchObject({
+      code: "COMMAND_FAILED",
+      message: "Runtime is shutting down; cannot create session",
+    });
+    expect(mockChromiumLaunch).not.toHaveBeenCalled();
+  });
+
+  it("shutdown is idempotent", async () => {
+    const { browser, browserClose } = createMockBrowserTree();
+    mockChromiumLaunch.mockResolvedValueOnce(browser);
+
+    const rt = new BrowserRuntime({ headless: true });
+    await rt.createSession();
+    await rt.shutdown();
+    await rt.shutdown();
+
+    expect(browserClose).toHaveBeenCalledTimes(1);
+  });
 });

packages/runtime/src/index.ts

@@ -33,9 +33,19 @@ type SessionRecord = {
 export class BrowserRuntime {
   private browserPromise: Promise<Browser> | null = null;
   private sessions = new Map<string, SessionRecord>();
+  private shuttingDown = false;
 
   constructor(private readonly options: BrowserRuntimeOptions = {}) {}
 
+  private assertActive(operation: string) {
+    if (this.shuttingDown) {
+      throw new WebchainRuntimeError(
+        "COMMAND_FAILED",
+        `Runtime is shutting down; cannot ${operation}`,
+      );
+    }
+  }
+
   private async getBrowser(): Promise<Browser> {
     if (!this.browserPromise) {
       this.browserPromise = this.launchBrowser();
@@ -70,6 +80,7 @@ export class BrowserRuntime {
   }
 
   async createSession(): Promise<RuntimeSession> {
+    this.assertActive("create session");
     const browser = await this.getBrowser();
     const context = await browser.newContext();
 
@@ -96,6 +107,7 @@ export class BrowserRuntime {
   }
 
   async navigate(command: NavigateCommand): Promise<ActionResult> {
+    this.assertActive("navigate");
     const session = this.getSession(command.sessionId);
     try {
       await session.page.goto(command.url, { waitUntil: "domcontentloaded" });
@@ -111,6 +123,7 @@ export class BrowserRuntime {
   }
 
   async snapshot(command: SnapshotCommand): Promise<SnapshotResult> {
+    this.assertActive("snapshot");
     const session = this.getSession(command.sessionId);
     try {
       const page = session.page;
@@ -164,6 +177,7 @@ export class BrowserRuntime {
   }
 
   async click(command: ClickCommand): Promise<ActionResult> {
+    this.assertActive("click");
     const session = this.getSession(command.sessionId);
     try {
       await session.page.locator(command.selector).first().click();
@@ -179,6 +193,7 @@ export class BrowserRuntime {
   }
 
   async type(command: TypeCommand): Promise<ActionResult> {
+    this.assertActive("type");
     const session = this.getSession(command.sessionId);
     try {
       await session.page.locator(command.selector).first().fill(command.text);
@@ -196,6 +211,7 @@ export class BrowserRuntime {
   async closeSession(
     command: CloseSessionCommand,
   ): Promise<CloseSessionResult> {
+    this.assertActive("close session");
     const session = this.getSession(command.sessionId);
     try {
       await session.context.close();
@@ -211,6 +227,11 @@ export class BrowserRuntime {
   }
 
   async shutdown() {
+    if (this.shuttingDown) {
+      return;
+    }
+    this.shuttingDown = true;
+
     await Promise.all(
       [...this.sessions.values()].map(async (session) => {
         await session.context.close();

services/companion/src/index.ts

@@ -9,9 +9,16 @@ const runtime = new BrowserRuntime({
 
 const { app } = await createCompanionApp({ runtime });
 
+let closing = false;
+
 const closeGracefully = async () => {
-  await runtime.shutdown();
+  if (closing) {
+    return;
+  }
+  closing = true;
+
   await app.close();
+  await runtime.shutdown();
   process.exit(0);
 };
 

services/mcp/src/test-support/bootstrap-mcp-stack.ts

@@ -80,8 +80,8 @@ export async function bootstrapMcpStack(
     shutdown: async () => {
       await client.close();
       await stdioTransport.close();
-      await runtime.shutdown();
       await app.close();
+      await runtime.shutdown();
     },
   };
 }