fix: limit parallel browser instances and reject concurrent persistent sessions

- Persistent/existing mode: throw error when instance is already in-use,
  instructing the model to run browser tasks sequentially. This prevents
  Chrome profile lock conflicts from concurrent --userDataDir usage.
- Isolated mode: allow parallel instances up to MAX_PARALLEL_INSTANCES (5).
  Throw when the limit is exceeded to prevent resource exhaustion.
- Update integration test to use isolated mode for concurrent browser agents.
- Add 3 new unit tests for persistent/existing rejection and max limit.

Author: gsquared94

integration-tests/browser-agent.test.ts

@@ -308,7 +308,7 @@ describe.skipIf(!chromeAvailable)('browser-agent', () => {
     await run.expectText('successfully written', 15000);
   });
 
-  it('should handle concurrent browser agents with persistent session mode', async () => {
+  it('should handle concurrent browser agents with isolated session mode', async () => {
     rig.setup('browser-concurrent', {
       fakeResponsesPath: join(__dirname, 'browser-agent.concurrent.responses'),
       settings: {
@@ -320,9 +320,10 @@ describe.skipIf(!chromeAvailable)('browser-agent', () => {
           },
           browser: {
             headless: true,
-            // Persistent mode is the default — the regression scenario.
-            // Two concurrent calls should each get a separate browser.
-            sessionMode: 'persistent',
+            // Isolated mode supports concurrent browser agents.
+            // Persistent/existing modes reject concurrent calls to prevent
+            // Chrome profile lock conflicts.
+            sessionMode: 'isolated',
           },
         },
       },

packages/core/src/agents/browser/browserManager.test.ts

@@ -874,11 +874,44 @@ describe('BrowserManager', () => {
       expect(instance1).not.toBe(instance2);
     });
 
-    it('should return a different instance when the primary is acquired', () => {
+    it('should throw when acquired instance is requested in persistent mode', () => {
+      // mockConfig defaults to persistent mode
       const instance1 = BrowserManager.getInstance(mockConfig);
       instance1.acquire();
 
-      const instance2 = BrowserManager.getInstance(mockConfig);
+      expect(() => BrowserManager.getInstance(mockConfig)).toThrow(
+        /Cannot launch a concurrent browser agent in "persistent" session mode/,
+      );
+    });
+
+    it('should throw when acquired instance is requested in existing mode', () => {
+      const existingConfig = makeFakeConfig({
+        agents: {
+          overrides: { browser_agent: { enabled: true } },
+          browser: { sessionMode: 'existing' },
+        },
+      });
+
+      const instance1 = BrowserManager.getInstance(existingConfig);
+      instance1.acquire();
+
+      expect(() => BrowserManager.getInstance(existingConfig)).toThrow(
+        /Cannot launch a concurrent browser agent in "existing" session mode/,
+      );
+    });
+
+    it('should return a different instance when the primary is acquired in isolated mode', () => {
+      const isolatedConfig = makeFakeConfig({
+        agents: {
+          overrides: { browser_agent: { enabled: true } },
+          browser: { sessionMode: 'isolated' },
+        },
+      });
+
+      const instance1 = BrowserManager.getInstance(isolatedConfig);
+      instance1.acquire();
+
+      const instance2 = BrowserManager.getInstance(isolatedConfig);
 
       expect(instance2).not.toBe(instance1);
       expect(instance1.isAcquired()).toBe(true);
@@ -896,32 +929,66 @@ describe('BrowserManager', () => {
       expect(instance1.isAcquired()).toBe(false);
     });
 
-    it('should reuse a released parallel instance', () => {
-      const instance1 = BrowserManager.getInstance(mockConfig);
+    it('should reuse a released parallel instance in isolated mode', () => {
+      const isolatedConfig = makeFakeConfig({
+        agents: {
+          overrides: { browser_agent: { enabled: true } },
+          browser: { sessionMode: 'isolated' },
+        },
+      });
+
+      const instance1 = BrowserManager.getInstance(isolatedConfig);
       instance1.acquire();
 
-      const instance2 = BrowserManager.getInstance(mockConfig);
+      const instance2 = BrowserManager.getInstance(isolatedConfig);
       instance2.acquire();
       instance2.release();
 
       // Primary is still acquired, parallel is released — should reuse parallel
-      const instance3 = BrowserManager.getInstance(mockConfig);
+      const instance3 = BrowserManager.getInstance(isolatedConfig);
       expect(instance3).toBe(instance2);
     });
 
-    it('should create multiple parallel instances for multiple concurrent calls', () => {
-      const instance1 = BrowserManager.getInstance(mockConfig);
+    it('should create multiple parallel instances in isolated mode', () => {
+      const isolatedConfig = makeFakeConfig({
+        agents: {
+          overrides: { browser_agent: { enabled: true } },
+          browser: { sessionMode: 'isolated' },
+        },
+      });
+
+      const instance1 = BrowserManager.getInstance(isolatedConfig);
       instance1.acquire();
 
-      const instance2 = BrowserManager.getInstance(mockConfig);
+      const instance2 = BrowserManager.getInstance(isolatedConfig);
       instance2.acquire();
 
-      const instance3 = BrowserManager.getInstance(mockConfig);
+      const instance3 = BrowserManager.getInstance(isolatedConfig);
 
       expect(instance1).not.toBe(instance2);
       expect(instance2).not.toBe(instance3);
       expect(instance1).not.toBe(instance3);
     });
+
+    it('should throw when MAX_PARALLEL_INSTANCES is reached in isolated mode', () => {
+      const isolatedConfig = makeFakeConfig({
+        agents: {
+          overrides: { browser_agent: { enabled: true } },
+          browser: { sessionMode: 'isolated' },
+        },
+      });
+
+      // Acquire MAX_PARALLEL_INSTANCES instances
+      for (let i = 0; i < BrowserManager.MAX_PARALLEL_INSTANCES; i++) {
+        const instance = BrowserManager.getInstance(isolatedConfig);
+        instance.acquire();
+      }
+
+      // Next call should throw
+      expect(() => BrowserManager.getInstance(isolatedConfig)).toThrow(
+        /Maximum number of parallel browser instances/,
+      );
+    });
   });
 
   describe('resetAll', () => {

packages/core/src/agents/browser/browserManager.ts

@@ -114,6 +114,12 @@ export class BrowserManager {
   // --- Static singleton management ---
   private static instances = new Map<string, BrowserManager>();
 
+  /**
+   * Maximum number of parallel browser instances allowed in isolated mode.
+   * Prevents unbounded resource consumption from concurrent browser_agent calls.
+   */
+  static readonly MAX_PARALLEL_INSTANCES = 5;
+
   /**
    * Returns the cache key for a given config.
    * Uses `sessionMode:profilePath` so different profiles get separate instances.
@@ -129,24 +135,47 @@ export class BrowserManager {
    * Returns an existing BrowserManager for the current config's session mode
    * and profile, or creates a new one.
    *
-   * When an instance is currently acquired (in-use by an active invocation),
-   * a new instance is created with a suffixed key so concurrent browser_agent
-   * calls each get their own browser.
+   * Concurrency rules:
+   * - **persistent / existing mode**: Only one instance is allowed at a time.
+   *   If the instance is already in-use, an error is thrown instructing the
+   *   caller to run browser tasks sequentially.
+   * - **isolated mode**: Parallel instances are allowed up to
+   *   MAX_PARALLEL_INSTANCES. Each isolated instance gets its own temp profile.
    */
   static getInstance(config: Config): BrowserManager {
     const key = BrowserManager.getInstanceKey(config);
+    const sessionMode =
+      config.getBrowserAgentConfig().customConfig.sessionMode ?? 'persistent';
     let instance = BrowserManager.instances.get(key);
     if (!instance) {
       instance = new BrowserManager(config);
       BrowserManager.instances.set(key, instance);
       debugLogger.log(`Created new BrowserManager singleton (key: ${key})`);
     } else if (instance.inUse) {
-      // The primary instance is in-use by another concurrent invocation.
-      // Find or create a parallel instance with a suffixed key.
+      // Persistent and existing modes share a browser profile directory.
+      // Chrome prevents multiple instances from using the same profile, so
+      // concurrent usage would cause "profile locked" errors.
+      if (sessionMode === 'persistent' || sessionMode === 'existing') {
+        throw new Error(
+          `Cannot launch a concurrent browser agent in "${sessionMode}" session mode. ` +
+            `The browser instance is already in use by another task. ` +
+            `Please run browser tasks sequentially, or switch to "isolated" session mode for concurrent browser usage.`,
+        );
+      }
+
+      // Isolated mode: allow parallel instances up to the limit.
+      let inUseCount = 1; // primary is already in-use
       let suffix = 1;
       let parallelKey = `${key}:${suffix}`;
       let parallel = BrowserManager.instances.get(parallelKey);
       while (parallel?.inUse) {
+        inUseCount++;
+        if (inUseCount >= BrowserManager.MAX_PARALLEL_INSTANCES) {
+          throw new Error(
+            `Maximum number of parallel browser instances (${BrowserManager.MAX_PARALLEL_INSTANCES}) reached. ` +
+              `Please wait for an existing browser task to complete before starting a new one.`,
+          );
+        }
         suffix++;
         parallelKey = `${key}:${suffix}`;
         parallel = BrowserManager.instances.get(parallelKey);