@jackwener/opencli 1.7.16 → 1.7.18

package/dist/src/cli.test.js

@@ -343,7 +343,7 @@ describe('createProgram root help descriptions', () => {
             const program = createProgram('', '');
             const browser = program.commands.find(cmd => cmd.name() === 'browser');
             expect(browser).toBeTruthy();
-            process.argv = ['node', 'opencli', 'browser', '--help', '-f', 'yaml'];
+            process.argv = ['node', 'opencli', 'browser', '--session', 'test', '--help', '-f', 'yaml'];
             const data = yaml.load(browser.helpInformation());
             expect(data.namespace).toBe('browser');
             expect(data.command).toBe('opencli browser');
@@ -351,20 +351,17 @@ describe('createProgram root help descriptions', () => {
             expect(data.command_count).toBeGreaterThan(20);
             expect(data.namespace_options).toEqual(expect.arrayContaining([
                 expect.objectContaining({
-                    name: 'workspace',
-                    flags: '--workspace <name>',
+                    name: 'session',
+                    flags: '--session <name>',
                     takes_value: 'required',
+                    required: true,
+                    help: expect.stringContaining('required'),
                 }),
                 expect.objectContaining({
                     name: 'window',
                     flags: '--window <mode>',
                     takes_value: 'required',
                 }),
-                expect.objectContaining({
-                    name: 'keepTab',
-                    flags: '--keep-tab <bool>',
-                    takes_value: 'required',
-                }),
             ]));
             expect(data.global_options).toEqual(expect.arrayContaining([
                 expect.objectContaining({
@@ -411,7 +408,7 @@ describe('createProgram root help descriptions', () => {
             const browser = program.commands.find(cmd => cmd.name() === 'browser');
             const tab = browser.commands.find(cmd => cmd.name() === 'tab');
             expect(tab).toBeTruthy();
-            process.argv = ['node', 'opencli', 'browser', 'tab', '--help', '-f', 'yaml'];
+            process.argv = ['node', 'opencli', 'browser', '--session', 'test', 'tab', '--help', '-f', 'yaml'];
             const data = yaml.load(tab.helpInformation());
             expect(data).toMatchObject({
                 namespace: 'browser',
@@ -431,7 +428,7 @@ describe('createProgram root help descriptions', () => {
                 usage: 'opencli browser tab close [targetId] [options]',
                 positionals: [{ name: 'targetId', help: 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"' }],
             });
-            expect(data.namespace_options.map((option) => option.name)).toEqual(['workspace', 'window', 'keepTab']);
+            expect(data.namespace_options.map((option) => option.name)).toEqual(['session', 'window']);
             expect(data.structured_help).toMatchObject({
                 usage: 'opencli browser tab --help -f yaml',
             });
@@ -447,7 +444,7 @@ describe('createProgram root help descriptions', () => {
             const browser = program.commands.find(cmd => cmd.name() === 'browser');
             const click = browser.commands.find(cmd => cmd.name() === 'click');
             expect(click).toBeTruthy();
-            process.argv = ['node', 'opencli', 'browser', 'click', '--help', '-f', 'yaml'];
+            process.argv = ['node', 'opencli', 'browser', '--session', 'test', 'click', '--help', '-f', 'yaml'];
             const data = yaml.load(click.helpInformation());
             expect(data).toMatchObject({
                 namespace: 'browser',
@@ -460,7 +457,7 @@ describe('createProgram root help descriptions', () => {
                 },
             });
             expect(data.command_options.map((option) => option.name)).toEqual(['role', 'name', 'label', 'text', 'testid', 'nth', 'tab']);
-            expect(data.namespace_options.map((option) => option.name)).toEqual(['workspace', 'window', 'keepTab']);
+            expect(data.namespace_options.map((option) => option.name)).toEqual(['session', 'window']);
             expect(data.global_options.map((option) => option.name)).toContain('profile');
         }
         finally {
@@ -664,7 +661,7 @@ describe('browser verify', () => {
             fs.mkdirSync(adapterDir, { recursive: true });
             fs.writeFileSync(path.join(adapterDir, 'top.js'), 'export default {};\n', 'utf-8');
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'verify', 'hn/top', '--no-fixture', '--trace', 'retain-on-failure']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'verify', 'hn/top', '--no-fixture', '--trace', 'retain-on-failure']);
             expect(mockExecFileSync).toHaveBeenCalledTimes(1);
             const [, execArgs] = mockExecFileSync.mock.calls[0];
             expect(execArgs.slice(-6)).toEqual(['hn', 'top', '--trace', 'retain-on-failure', '--format', 'json']);
@@ -692,7 +689,7 @@ describe('browser verify', () => {
             fs.mkdirSync(adapterDir, { recursive: true });
             fs.writeFileSync(path.join(adapterDir, 'top.js'), 'export default {};\n', 'utf-8');
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'verify', 'hn/top', '--no-fixture', '--seed-args', 'opencli-verify']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'verify', 'hn/top', '--no-fixture', '--seed-args', 'opencli-verify']);
             expect(mockExecFileSync).toHaveBeenCalledTimes(1);
             const [, execArgs] = mockExecFileSync.mock.calls[0];
             expect(execArgs.slice(-5)).toEqual(['hn', 'top', 'opencli-verify', '--format', 'json']);
@@ -721,7 +718,7 @@ describe('browser verify', () => {
             fs.mkdirSync(adapterDir, { recursive: true });
             fs.writeFileSync(path.join(adapterDir, 'top.js'), 'export default {};\n', 'utf-8');
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'verify', 'hn/top', '--write-fixture', '--seed-args', 'opencli-verify']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'verify', 'hn/top', '--write-fixture', '--seed-args', 'opencli-verify']);
             const fixtureFile = path.join(fakeHome, '.opencli', 'sites', 'hn', 'verify', 'top.json');
             const fixture = JSON.parse(fs.readFileSync(fixtureFile, 'utf-8'));
             expect(fixture.args).toEqual(['opencli-verify']);
@@ -753,7 +750,7 @@ describe('browser verify', () => {
             fs.mkdirSync(adapterDir, { recursive: true });
             fs.writeFileSync(path.join(adapterDir, 'top.js'), 'export default {};\n', 'utf-8');
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'verify', 'hn/top', '--no-fixture']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'verify', 'hn/top', '--no-fixture']);
             expect(process.exitCode).toBe(1);
             const output = consoleLogSpy.mock.calls.map((args) => args.join(' ')).join('\n');
             expect(output).toContain('Adapter output violates row shape conventions');
@@ -827,8 +824,8 @@ describe('profile list', () => {
 describe('browser tab targeting commands', () => {
     const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
     const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-    function getBrowserStateFile(cacheDir) {
-        return path.join(cacheDir, 'browser-state', 'browser_default.json');
+    function getBrowserStateFile(cacheDir, session = 'test') {
+        return path.join(cacheDir, 'browser-state', `${session}.json`);
     }
     beforeEach(() => {
         process.exitCode = undefined;
@@ -838,9 +835,8 @@ describe('browser tab targeting commands', () => {
         mockBrowserConnect.mockClear();
         mockBrowserClose.mockReset().mockResolvedValue(undefined);
         delete process.env.OPENCLI_WINDOW;
-        delete process.env.OPENCLI_KEEP_TAB;
         mockBindTab.mockReset().mockResolvedValue({
-            workspace: 'bound:default',
+            session: 'test',
             page: 'tab-2',
             url: 'https://user.example/inbox',
             title: 'Inbox',
@@ -879,6 +875,7 @@ describe('browser tab targeting commands', () => {
                 state: 'complete',
                 elapsedMs: 10,
             }),
+            session: 'test',
         };
     });
     function lastJsonLog() {
@@ -890,55 +887,40 @@ describe('browser tab targeting commands', () => {
             throw new Error(`Expected string arg to console.log, got ${typeof last}`);
         return JSON.parse(last);
     }
-    it('binds the current Chrome tab into a bound workspace', async () => {
+    it('binds the current Chrome tab into a browser session', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'bind', '--domain', 'user.example', '--path-prefix', '/inbox']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default' });
-        expect(mockBindTab).toHaveBeenCalledWith('bound:default', {
-            matchDomain: 'user.example',
-            matchPathPrefix: '/inbox',
-        });
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'bind']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, session: 'test', surface: 'browser' });
+        expect(mockBindTab).toHaveBeenCalledWith('test', {});
         const out = lastJsonLog();
-        expect(out.workspace).toBe('bound:default');
+        expect(out.session).toBe('test');
         expect(out.url).toBe('https://user.example/inbox');
     });
-    it('rejects bind workspaces outside the bound namespace', async () => {
+    it('requires an explicit session for browser commands', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'bind', '--workspace', 'browser:default']);
+        program.exitOverride((err) => { throw err; });
+        program.commands.find(cmd => cmd.name() === 'browser')?.exitOverride((err) => { throw err; });
+        await expect(program.parseAsync(['node', 'opencli', 'browser', 'state'])).rejects.toMatchObject({
+            code: 'commander.missingMandatoryOptionValue',
+        });
         expect(mockBrowserConnect).not.toHaveBeenCalled();
-        expect(mockBindTab).not.toHaveBeenCalled();
-        const out = lastJsonLog();
-        expect(out.error.code).toBe('invalid_bind_workspace');
-        expect(process.exitCode).toBeDefined();
+        expect(stderrSpy.mock.calls.flat().join('')).toContain("required option '--session <name>' not specified");
     });
-    it('runs browser commands against an explicit bound workspace', async () => {
+    it('runs browser commands against an explicit session', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', 'state']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default', windowMode: 'foreground' });
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'state']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, session: 'test', surface: 'browser', windowMode: 'foreground' });
         expect(browserState.page?.snapshot).toHaveBeenCalled();
     });
     it('passes browser --window through Commander options without relying on env pre-processing', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', '--window', 'background', 'state']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'browser:default', windowMode: 'background' });
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', '--window', 'background', 'state']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, session: 'test', surface: 'browser', windowMode: 'background' });
         expect(browserState.page?.snapshot).toHaveBeenCalled();
     });
-    it('releases non-bound browser tab leases when --keep-tab=false', async () => {
-        const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', '--keep-tab', 'false', 'state']);
-        expect(browserState.page?.snapshot).toHaveBeenCalled();
-        expect(browserState.page?.closeWindow).toHaveBeenCalled();
-    });
-    it('does not auto-release explicit bound workspaces when --keep-tab=false', async () => {
-        const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', '--keep-tab', 'false', 'state']);
-        expect(browserState.page?.snapshot).toHaveBeenCalled();
-        expect(browserState.page?.closeWindow).not.toHaveBeenCalled();
-        expect(stderrSpy.mock.calls.flat().join('')).toContain('--window/--keep-tab ignored for bound:* workspaces');
-    });
     it('passes the opt-in AX source to browser state', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'state', '--source', 'ax']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'state', '--source', 'ax']);
         expect(browserState.page?.snapshot).toHaveBeenCalledWith({ viewportExpand: 2000, source: 'ax' });
     });
     it('prints DOM vs AX snapshot metrics without changing default state output', async () => {
@@ -952,7 +934,7 @@ describe('browser tab targeting commands', () => {
             }),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'state', '--compare-sources']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'state', '--compare-sources']);
         expect(browserState.page?.snapshot).toHaveBeenCalledWith({ viewportExpand: 2000, source: 'dom' });
         expect(browserState.page?.snapshot).toHaveBeenCalledWith({ viewportExpand: 2000, source: 'ax' });
         const out = lastJsonLog();
@@ -970,7 +952,7 @@ describe('browser tab targeting commands', () => {
             }),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'state', '--compare-sources']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'state', '--compare-sources']);
         const out = lastJsonLog();
         expect(out.sources.dom).toMatchObject({ ok: true, refs: 1 });
         expect(out.sources.ax).toMatchObject({
@@ -980,7 +962,7 @@ describe('browser tab targeting commands', () => {
     });
     it('rejects unknown browser state sources before touching the page', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'state', '--source', 'magic']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'state', '--source', 'magic']);
         expect(browserState.page?.snapshot).not.toHaveBeenCalled();
         const out = lastJsonLog();
         expect(out.error.code).toBe('invalid_source');
@@ -988,7 +970,7 @@ describe('browser tab targeting commands', () => {
     });
     it('captures annotated screenshots through the visual ref overlay path', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'screenshot', '--annotate']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'screenshot', '--annotate']);
         expect(browserState.page?.annotatedScreenshot).toHaveBeenCalledWith({
             fullPage: false,
             annotate: true,
@@ -999,38 +981,36 @@ describe('browser tab targeting commands', () => {
         expect(browserState.page?.screenshot).not.toHaveBeenCalled();
         expect(consoleLogSpy).toHaveBeenLastCalledWith('annotated-base64-shot');
     });
-    it('blocks history navigation on bound workspaces unless explicitly allowed', async () => {
+    it('allows history navigation in a bound session', async () => {
         browserState.page = {
             ...browserState.page,
-            workspace: 'bound:default',
             evaluate: vi.fn(),
             wait: vi.fn(),
+            session: 'test',
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', 'back']);
-        expect(browserState.page?.evaluate).not.toHaveBeenCalled();
-        const out = lastJsonLog();
-        expect(out.error.code).toBe('bound_navigation_blocked');
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'back']);
+        expect(browserState.page?.evaluate).toHaveBeenCalledWith('history.back()');
     });
-    it('unbinds a bound workspace through the daemon close-window command', async () => {
+    it('unbinds a session through the daemon close-window command', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'unbind', '--workspace', 'bound:default']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default' });
-        expect(mockSendCommand).toHaveBeenCalledWith('close-window', { workspace: 'bound:default' });
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'unbind']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, session: 'test', surface: 'browser' });
+        expect(mockSendCommand).toHaveBeenCalledWith('close-window', { session: 'test', surface: 'browser' });
         const out = lastJsonLog();
-        expect(out).toEqual({ unbound: true, workspace: 'bound:default' });
+        expect(out).toEqual({ unbound: true, session: 'test' });
     });
     it('does not print false success when unbind fails', async () => {
-        mockSendCommand.mockRejectedValueOnce(new BrowserCommandError('Workspace "bound:default" is not attached to a tab.', 'bound_session_missing', 'Run bind again, then retry the browser command.'));
+        mockSendCommand.mockRejectedValueOnce(new BrowserCommandError('Session "test" is not attached to a tab.', 'bound_session_missing', 'Run bind again, then retry the browser command.'));
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'unbind', '--workspace', 'bound:default']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'unbind']);
         const out = lastJsonLog();
         expect(out.error.code).toBe('bound_session_missing');
         expect(process.exitCode).toBeDefined();
     });
     it('accepts JavaScript dialogs through the browser dialog command', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'dialog', 'accept', '--text', 'ok']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'dialog', 'accept', '--text', 'ok']);
         expect(browserState.page?.handleJavaScriptDialog).toHaveBeenCalledWith(true, 'ok');
         const out = lastJsonLog();
         expect(out).toEqual({ handled: true, action: 'accept', text: 'ok' });
@@ -1041,7 +1021,7 @@ describe('browser tab targeting commands', () => {
             evaluate: vi.fn().mockRejectedValue(new Error('JavaScript dialog showing')),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'eval', 'document.title']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'eval', 'document.title']);
         const out = lastJsonLog();
         expect(out.error.code).toBe('javascript_dialog_open');
         expect(out.error.hint).toContain('browser dialog accept');
@@ -1049,7 +1029,7 @@ describe('browser tab targeting commands', () => {
     });
     it('binds browser commands to an explicit target tab via --tab', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'eval', '--tab', 'tab-2', 'document.title']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'eval', '--tab', 'tab-2', 'document.title']);
         expect(browserState.page?.setActivePage).toHaveBeenCalledWith('tab-2');
         expect(browserState.page?.evaluate).toHaveBeenCalledWith('document.title');
     });
@@ -1061,7 +1041,7 @@ describe('browser tab targeting commands', () => {
             evaluate: vi.fn(),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'eval', '--tab', 'tab-stale', 'document.title']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'eval', '--tab', 'tab-stale', 'document.title']);
         expect(process.exitCode).toBeDefined();
         expect(browserState.page?.setActivePage).not.toHaveBeenCalled();
         expect(browserState.page?.evaluate).not.toHaveBeenCalled();
@@ -1069,50 +1049,50 @@ describe('browser tab targeting commands', () => {
     });
     it('lists tabs with target IDs via browser tab list', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'tab', 'list']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'tab', 'list']);
         expect(browserState.page?.tabs).toHaveBeenCalledTimes(1);
         expect(consoleLogSpy.mock.calls.flat().join('\n')).toContain('"page": "tab-1"');
         expect(consoleLogSpy.mock.calls.flat().join('\n')).toContain('"page": "tab-2"');
     });
     it('creates a new tab and prints its target ID', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'tab', 'new', 'https://three.example']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'tab', 'new', 'https://three.example']);
         expect(browserState.page?.newTab).toHaveBeenCalledWith('https://three.example');
         expect(consoleLogSpy.mock.calls.flat().join('\n')).toContain('"page": "tab-3"');
     });
     it('prints the resolved target ID when browser open creates or navigates a tab', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'open', 'https://example.com']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'open', 'https://example.com']);
         expect(browserState.page?.goto).toHaveBeenCalledWith('https://example.com');
         expect(consoleLogSpy.mock.calls.flat().join('\n')).toContain('"url": "https://one.example"');
         expect(consoleLogSpy.mock.calls.flat().join('\n')).toContain('"page": "tab-1"');
     });
     it('lists cross-origin frames via browser frames', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'frames']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'frames']);
         expect(browserState.page?.frames).toHaveBeenCalledTimes(1);
         expect(consoleLogSpy.mock.calls.flat().join('\n')).toContain('"frameId": "frame-1"');
         expect(consoleLogSpy.mock.calls.flat().join('\n')).toContain('"url": "https://x.example/embed"');
     });
     it('routes browser eval --frame through frame-targeted evaluation', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'eval', '--frame', '0', 'document.title']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'eval', '--frame', '0', 'document.title']);
         expect(browserState.page?.evaluateInFrame).toHaveBeenCalledWith('document.title', 0);
         expect(browserState.page?.evaluate).not.toHaveBeenCalled();
         expect(consoleLogSpy.mock.calls.flat().join('\n')).toContain('inside frame');
     });
     it('does not promote a newly created tab to the persisted default target', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'tab', 'new', 'https://three.example']);
-        await program.parseAsync(['node', 'opencli', 'browser', 'eval', 'document.title']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'tab', 'new', 'https://three.example']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'eval', 'document.title']);
         expect(browserState.page?.newTab).toHaveBeenCalledWith('https://three.example');
         expect(browserState.page?.setActivePage).not.toHaveBeenCalled();
         expect(browserState.page?.evaluate).toHaveBeenCalledWith('document.title');
     });
     it('persists an explicitly selected tab as the default target for later untargeted commands', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'tab', 'select', 'tab-2']);
-        await program.parseAsync(['node', 'opencli', 'browser', 'eval', 'document.title']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'tab', 'select', 'tab-2']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'eval', 'document.title']);
         expect(browserState.page?.selectTab).toHaveBeenCalledWith('tab-2');
         expect(browserState.page?.setActivePage).toHaveBeenCalledWith('tab-2');
         expect(browserState.page?.evaluate).toHaveBeenCalledWith('document.title');
@@ -1121,7 +1101,7 @@ describe('browser tab targeting commands', () => {
     it('clears a saved default target when it is no longer present in the current session', async () => {
         const cacheDir = String(process.env.OPENCLI_CACHE_DIR);
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'tab', 'select', 'tab-2']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'tab', 'select', 'tab-2']);
         expect(fs.existsSync(getBrowserStateFile(cacheDir))).toBe(true);
         browserState.page = {
             setActivePage: vi.fn(),
@@ -1130,35 +1110,36 @@ describe('browser tab targeting commands', () => {
             evaluate: vi.fn().mockResolvedValue({ ok: true }),
             readNetworkCapture: vi.fn().mockResolvedValue([]),
         };
-        await program.parseAsync(['node', 'opencli', 'browser', 'eval', 'document.title']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'eval', 'document.title']);
         expect(browserState.page?.setActivePage).not.toHaveBeenCalled();
         expect(browserState.page?.evaluate).toHaveBeenCalledWith('document.title');
         expect(fs.existsSync(getBrowserStateFile(cacheDir))).toBe(false);
     });
     it('clears the persisted default target when that tab is closed', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'tab', 'select', 'tab-2']);
-        await program.parseAsync(['node', 'opencli', 'browser', 'tab', 'close', 'tab-2']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'tab', 'select', 'tab-2']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'tab', 'close', 'tab-2']);
         vi.mocked(browserState.page?.setActivePage).mockClear();
         vi.mocked(browserState.page?.evaluate).mockClear();
-        await program.parseAsync(['node', 'opencli', 'browser', 'eval', 'document.title']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'eval', 'document.title']);
         expect(browserState.page?.closeTab).toHaveBeenCalledWith('tab-2');
         expect(browserState.page?.setActivePage).not.toHaveBeenCalled();
         expect(browserState.page?.evaluate).toHaveBeenCalledWith('document.title');
     });
     it('closes a tab by target ID', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'tab', 'close', 'tab-2']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'tab', 'close', 'tab-2']);
         expect(browserState.page?.closeTab).toHaveBeenCalledWith('tab-2');
         expect(consoleLogSpy.mock.calls.flat().join('\n')).toContain('"closed": "tab-2"');
     });
     it('rejects closing a stale tab target ID that is no longer in the current session', async () => {
         browserState.page = {
+            session: 'test',
             tabs: vi.fn().mockResolvedValue([]),
             closeTab: vi.fn(),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'tab', 'close', 'tab-stale']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'tab', 'close', 'tab-stale']);
         expect(process.exitCode).toBeDefined();
         expect(browserState.page?.closeTab).not.toHaveBeenCalled();
         expect(stderrSpy.mock.calls.flat().join('\n')).toContain('Target tab tab-stale is not part of the current browser session');
@@ -1205,7 +1186,7 @@ describe('browser tab targeting commands', () => {
             ]),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'analyze', 'https://target.example/']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'analyze', 'https://target.example/']);
         const out = lastJsonLog();
         expect(browserState.page?.readNetworkCapture).toHaveBeenCalledTimes(2);
         expect(out.anti_bot.vendor).toBe('cloudflare');
@@ -1266,7 +1247,7 @@ describe('browser tab targeting commands', () => {
             readNetworkCapture: vi.fn().mockResolvedValue([]),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'analyze', 'https://target.example/']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'analyze', 'https://target.example/']);
         const out = lastJsonLog();
         expect(browserState.page?.readNetworkCapture).toHaveBeenCalledTimes(2);
         expect(bufferReads).toBe(2);
@@ -1305,7 +1286,7 @@ describe('browser tab targeting commands', () => {
             ]),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'wait', 'xhr', '/api/target', '--timeout', '900']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'wait', 'xhr', '/api/target', '--timeout', '900']);
         const out = lastJsonLog();
         expect(browserState.page?.startNetworkCapture).toHaveBeenCalledTimes(1);
         expect(browserState.page?.evaluate).toHaveBeenCalledWith(expect.stringContaining('window.__opencli_net'));
@@ -1353,7 +1334,7 @@ describe('browser tab targeting commands', () => {
             readNetworkCapture: vi.fn().mockResolvedValue([]),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'wait', 'xhr', '/api/target', '--timeout', '900']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'wait', 'xhr', '/api/target', '--timeout', '900']);
         const out = lastJsonLog();
         expect(browserState.page?.startNetworkCapture).toHaveBeenCalledTimes(1);
         expect(browserState.page?.readNetworkCapture).toHaveBeenCalledTimes(2);
@@ -1377,7 +1358,7 @@ describe('browser tab targeting commands', () => {
             tabs: vi.fn().mockResolvedValue([{ index: 0, page: 'tab-1', url: 'https://target.example', title: 'Target', active: true }]),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'wait', 'download', 'receipt', '--timeout', '900']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'wait', 'download', 'receipt', '--timeout', '900']);
         expect(browserState.page?.waitForDownload).toHaveBeenCalledWith('receipt', 900);
         expect(lastJsonLog()).toEqual({
             downloaded: true,
@@ -1403,7 +1384,7 @@ describe('browser tab targeting commands', () => {
             tabs: vi.fn().mockResolvedValue([{ index: 0, page: 'tab-1', url: 'https://target.example', title: 'Target', active: true }]),
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'wait', 'download', 'receipt', '--timeout', '900']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'wait', 'download', 'receipt', '--timeout', '900']);
         const out = lastJsonLog();
         expect(out.error.code).toBe('download_not_seen');
         expect(out.download.elapsedMs).toBe(900);
@@ -1413,10 +1394,10 @@ describe('browser tab targeting commands', () => {
 describe('browser network command', () => {
     const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
     function getNetworkCachePath(cacheDir) {
-        return path.join(cacheDir, 'browser-network', 'browser_default.json');
+        return path.join(cacheDir, 'browser-network', 'test.json');
     }
-    function getBoundNetworkCachePath(cacheDir) {
-        return path.join(cacheDir, 'browser-network', 'bound_default.json');
+    function getCustomNetworkCachePath(cacheDir) {
+        return path.join(cacheDir, 'browser-network', 'custom.json');
     }
     function lastJsonLog() {
         const calls = consoleLogSpy.mock.calls;
@@ -1434,6 +1415,7 @@ describe('browser network command', () => {
         mockBrowserConnect.mockClear();
         mockBrowserClose.mockReset().mockResolvedValue(undefined);
         browserState.page = {
+            session: 'test',
             setActivePage: vi.fn(),
             getActivePage: vi.fn().mockReturnValue('tab-1'),
             tabs: vi.fn().mockResolvedValue([{ page: 'tab-1', active: true }]),
@@ -1460,7 +1442,7 @@ describe('browser network command', () => {
     it('emits JSON with shape previews and persists the capture to disk', async () => {
         const cacheDir = String(process.env.OPENCLI_CACHE_DIR);
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
         const out = lastJsonLog();
         expect(out.count).toBe(1);
         expect(out.filtered_out).toBe(1);
@@ -1469,22 +1451,22 @@ describe('browser network command', () => {
         expect(out.entries[0]).not.toHaveProperty('body');
         expect(fs.existsSync(getNetworkCachePath(cacheDir))).toBe(true);
     });
-    it('uses the selected browser workspace for network cache scope', async () => {
+    it('uses the selected browser session for network cache scope', async () => {
         const cacheDir = String(process.env.OPENCLI_CACHE_DIR);
         browserState.page = {
             ...browserState.page,
-            workspace: 'bound:default',
+            session: 'custom',
         };
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', 'network']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'custom', 'network']);
         const out = lastJsonLog();
-        expect(out.workspace).toBe('bound:default');
-        expect(fs.existsSync(getBoundNetworkCachePath(cacheDir))).toBe(true);
+        expect(out.session).toBe('custom');
+        expect(fs.existsSync(getCustomNetworkCachePath(cacheDir))).toBe(true);
         expect(fs.existsSync(getNetworkCachePath(cacheDir))).toBe(false);
     });
     it('--all includes static resources that the default filter drops', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--all']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--all']);
         const out = lastJsonLog();
         expect(out.count).toBe(2);
         expect(out.entries.map((e) => e.key)).toContain('UserTweets');
@@ -1519,7 +1501,7 @@ describe('browser network command', () => {
             },
         ]);
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--since', '120s', '--failed']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--since', '120s', '--failed']);
         const out = lastJsonLog();
         expect(out.count).toBe(1);
         expect(out.entries[0].url).toBe('https://api.example.com/new-fail');
@@ -1543,7 +1525,7 @@ describe('browser network command', () => {
             },
         ]);
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
         const out = lastJsonLog();
         expect(out.count).toBe(1);
         expect(out.filtered_out).toBe(1);
@@ -1553,16 +1535,16 @@ describe('browser network command', () => {
     });
     it('--raw emits full bodies inline for every entry', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--raw']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--raw']);
         const out = lastJsonLog();
         expect(out.entries[0].body).toEqual({ data: { user: { rest_id: '42' } } });
         expect(out.entries[0].timestamp).toMatch(/T/);
     });
     it('--detail <key> returns the full body for the requested entry', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
         consoleLogSpy.mockClear();
-        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--detail', 'UserTweets']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--detail', 'UserTweets']);
         const out = lastJsonLog();
         expect(out.key).toBe('UserTweets');
         expect(out.body).toEqual({ data: { user: { rest_id: '42' } } });
@@ -1571,9 +1553,9 @@ describe('browser network command', () => {
     });
     it('--detail reports key_not_found with the list of available keys', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
         consoleLogSpy.mockClear();
-        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--detail', 'NopeOp']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--detail', 'NopeOp']);
         const out = lastJsonLog();
         expect(out.error.code).toBe('key_not_found');
         expect(out.error.available_keys).toContain('UserTweets');
@@ -1581,7 +1563,7 @@ describe('browser network command', () => {
     });
     it('--detail reports cache_missing when no capture has been persisted yet', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--detail', 'UserTweets']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--detail', 'UserTweets']);
         const out = lastJsonLog();
         expect(out.error.code).toBe('cache_missing');
         expect(process.exitCode).toBeDefined();
@@ -1589,7 +1571,7 @@ describe('browser network command', () => {
     it('emits capture_failed when readNetworkCapture throws', async () => {
         browserState.page.readNetworkCapture = vi.fn().mockRejectedValue(new Error('CDP disconnected'));
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
         const out = lastJsonLog();
         expect(out.error.code).toBe('capture_failed');
         expect(out.error.message).toContain('CDP disconnected');
@@ -1602,7 +1584,7 @@ describe('browser network command', () => {
         const clashDir = path.join(cacheDir, 'browser-network');
         fs.writeFileSync(clashDir, 'not-a-directory');
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
         const out = lastJsonLog();
         expect(out.cache_warning).toMatch(/Could not persist capture cache/);
         expect(out.count).toBe(1);
@@ -1627,7 +1609,7 @@ describe('browser network command', () => {
         });
         it('narrows entries to those whose shape has ALL named fields', async () => {
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'author,text,likes']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--filter', 'author,text,likes']);
             const out = lastJsonLog();
             expect(out.count).toBe(1);
             expect(out.filter).toEqual(['author', 'text', 'likes']);
@@ -1636,14 +1618,14 @@ describe('browser network command', () => {
         });
         it('matches container segments too, not just leaf names (any-segment rule)', async () => {
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'data,items']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--filter', 'data,items']);
             const out = lastJsonLog();
             expect(out.count).toBe(1);
             expect(out.entries[0].key).toBe('UserTweets');
         });
         it('drops entries that are missing any required field (AND semantics)', async () => {
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'author,followers']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--filter', 'author,followers']);
             const out = lastJsonLog();
             expect(out.count).toBe(0);
             expect(out.entries).toEqual([]);
@@ -1652,7 +1634,7 @@ describe('browser network command', () => {
         });
         it('returns empty entries (not an error) when nothing matches', async () => {
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'nonexistent_field']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--filter', 'nonexistent_field']);
             const out = lastJsonLog();
             expect(out.count).toBe(0);
             expect(out.entries).toEqual([]);
@@ -1661,43 +1643,43 @@ describe('browser network command', () => {
         });
         it('is case-sensitive so agents do not conflate `Id` with `id`', async () => {
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'Data']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--filter', 'Data']);
             const out = lastJsonLog();
             expect(out.count).toBe(0);
         });
         it('persists the full (unfiltered) capture so --detail lookups still find filtered-out keys', async () => {
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'author,text,likes']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--filter', 'author,text,likes']);
             consoleLogSpy.mockClear();
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--detail', 'UserProfile']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--detail', 'UserProfile']);
             const out = lastJsonLog();
             expect(out.key).toBe('UserProfile');
             expect(out.body).toEqual({ data: { user: { id: 'u1', followers: 10 } } });
         });
         it('composes with --raw: entries keep full bodies, filter still narrows', async () => {
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'author', '--raw']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--filter', 'author', '--raw']);
             const out = lastJsonLog();
             expect(out.count).toBe(1);
             expect(out.entries[0].body).toEqual({ data: { items: [{ author: 'a', text: 't', likes: 1 }] } });
         });
         it('reports invalid_filter for empty value', async () => {
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', '']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--filter', '']);
             const out = lastJsonLog();
             expect(out.error.code).toBe('invalid_filter');
             expect(process.exitCode).toBeDefined();
         });
         it('reports invalid_filter for commas-only value', async () => {
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', ',,,']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--filter', ',,,']);
             const out = lastJsonLog();
             expect(out.error.code).toBe('invalid_filter');
             expect(process.exitCode).toBeDefined();
         });
         it('rejects --filter combined with --detail as invalid_args', async () => {
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'author', '--detail', 'UserTweets']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--filter', 'author', '--detail', 'UserTweets']);
             const out = lastJsonLog();
             expect(out.error.code).toBe('invalid_args');
             expect(out.error.message).toContain('--filter');
@@ -1719,7 +1701,7 @@ describe('browser network command', () => {
                 },
             ]);
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
             const out = lastJsonLog();
             expect(out.body_truncated_count).toBe(1);
             expect(out.entries[0].body_truncated).toBe(true);
@@ -1738,9 +1720,9 @@ describe('browser network command', () => {
                 },
             ]);
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
             consoleLogSpy.mockClear();
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--detail', 'GET api.example.com/huge']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--detail', 'GET api.example.com/huge']);
             const out = lastJsonLog();
             expect(out.body_truncated).toBe(true);
             expect(out.body_full_size).toBe(50_000_000);
@@ -1758,10 +1740,10 @@ describe('browser network command', () => {
                 },
             ]);
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
             consoleLogSpy.mockClear();
             await program.parseAsync([
-                'node', 'opencli', 'browser', 'network',
+                'node', 'opencli', 'browser', '--session', 'test', 'network',
                 '--detail', 'GET api.example.com/plain',
                 '--max-body', '100',
             ]);
@@ -1783,10 +1765,10 @@ describe('browser network command', () => {
                 },
             ]);
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
             consoleLogSpy.mockClear();
             await program.parseAsync([
-                'node', 'opencli', 'browser', 'network',
+                'node', 'opencli', 'browser', '--session', 'test', 'network',
                 '--detail', 'GET api.example.com/json',
                 '--max-body', '10',
             ]);
@@ -1807,10 +1789,10 @@ describe('browser network command', () => {
                 },
             ]);
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network']);
             consoleLogSpy.mockClear();
             await program.parseAsync([
-                'node', 'opencli', 'browser', 'network',
+                'node', 'opencli', 'browser', '--session', 'test', 'network',
                 '--detail', 'GET api.example.com/x',
                 '--max-body', 'abc',
             ]);
@@ -1830,7 +1812,7 @@ describe('browser network command', () => {
                 },
             ]);
             const program = createProgram('', '');
-            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--raw']);
+            await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'network', '--raw']);
             const out = lastJsonLog();
             expect(out.entries).toHaveLength(1);
             const entry = out.entries[0];
@@ -1851,6 +1833,7 @@ describe('browser console command', () => {
         mockBrowserClose.mockReset().mockResolvedValue(undefined);
         const now = Date.now();
         browserState.page = {
+            session: 'test',
             setActivePage: vi.fn(),
             getActivePage: vi.fn().mockReturnValue('tab-1'),
             tabs: vi.fn().mockResolvedValue([{ page: 'tab-1', active: true }]),
@@ -1872,7 +1855,7 @@ describe('browser console command', () => {
     }
     it('filters console messages by level and time window', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'console', '--level', 'error', '--since', '120s']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'console', '--level', 'error', '--since', '120s']);
         const out = lastJsonLog();
         expect(out.count).toBe(1);
         expect(out.messages[0]).toMatchObject({ type: 'error', text: 'boom' });
@@ -1909,14 +1892,14 @@ describe('browser get html command', () => {
         const big = '<div>' + 'x'.repeat(100_000) + '</div>';
         browserState.page.evaluate.mockResolvedValueOnce({ kind: 'ok', html: big });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html']);
         expect(lastLogArg()).toBe(big);
     });
     it('caps output with --max and prepends a visible truncation marker', async () => {
         const big = '<div>' + 'x'.repeat(500) + '</div>';
         browserState.page.evaluate.mockResolvedValueOnce({ kind: 'ok', html: big });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--max', '100']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html', '--max', '100']);
         const out = String(lastLogArg());
         expect(out.startsWith('<!-- opencli: truncated 100 of')).toBe(true);
         expect(out.length).toBeGreaterThan(100);
@@ -1924,21 +1907,21 @@ describe('browser get html command', () => {
     });
     it('rejects negative --max with invalid_max error', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--max', '-1']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html', '--max', '-1']);
         expect(lastJsonLog().error.code).toBe('invalid_max');
         expect(process.exitCode).toBeDefined();
         expect(browserState.page.evaluate).not.toHaveBeenCalled();
     });
     it('rejects fractional --max with invalid_max error', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--max', '1.5']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html', '--max', '1.5']);
         expect(lastJsonLog().error.code).toBe('invalid_max');
         expect(process.exitCode).toBeDefined();
         expect(browserState.page.evaluate).not.toHaveBeenCalled();
     });
     it('rejects non-numeric --max (e.g. "10abc") with invalid_max error', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--max', '10abc']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html', '--max', '10abc']);
         expect(lastJsonLog().error.code).toBe('invalid_max');
         expect(process.exitCode).toBeDefined();
         expect(browserState.page.evaluate).not.toHaveBeenCalled();
@@ -1950,7 +1933,7 @@ describe('browser get html command', () => {
             tree: { tag: 'div', attrs: { class: 'hero' }, text: 'Hi', children: [] },
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--selector', '.hero', '--as', 'json']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html', '--selector', '.hero', '--as', 'json']);
         const out = lastJsonLog();
         expect(out.matched).toBe(1);
         expect(out.tree.tag).toBe('div');
@@ -1959,14 +1942,14 @@ describe('browser get html command', () => {
     it('--as json emits selector_not_found when matched is 0', async () => {
         browserState.page.evaluate.mockResolvedValueOnce({ selector: '.missing', matched: 0, tree: null });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--selector', '.missing', '--as', 'json']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html', '--selector', '.missing', '--as', 'json']);
         expect(lastJsonLog().error.code).toBe('selector_not_found');
         expect(process.exitCode).toBeDefined();
     });
     it('raw mode emits selector_not_found when the selector matches nothing', async () => {
         browserState.page.evaluate.mockResolvedValueOnce({ kind: 'ok', html: null });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--selector', '.missing']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html', '--selector', '.missing']);
         expect(lastJsonLog().error.code).toBe('selector_not_found');
         expect(process.exitCode).toBeDefined();
     });
@@ -1976,7 +1959,7 @@ describe('browser get html command', () => {
             reason: "'##$@@' is not a valid selector",
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--selector', '##$@@']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html', '--selector', '##$@@']);
         const err = lastJsonLog().error;
         expect(err.code).toBe('invalid_selector');
         expect(err.message).toContain('##$@@');
@@ -1990,7 +1973,7 @@ describe('browser get html command', () => {
             reason: "'##$@@' is not a valid selector",
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--selector', '##$@@', '--as', 'json']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html', '--selector', '##$@@', '--as', 'json']);
         const err = lastJsonLog().error;
         expect(err.code).toBe('invalid_selector');
         expect(err.message).toContain('##$@@');
@@ -1998,7 +1981,7 @@ describe('browser get html command', () => {
     });
     it('rejects unknown --as format with invalid_format error', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--as', 'yaml']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'html', '--as', 'yaml']);
         expect(lastJsonLog().error.code).toBe('invalid_format');
         expect(process.exitCode).toBeDefined();
     });
@@ -2031,6 +2014,7 @@ function installSelectorFirstTestHarness(label, pageOverrides) {
             setActivePage: vi.fn(),
             getActivePage: vi.fn().mockReturnValue('tab-1'),
             tabs: vi.fn().mockResolvedValue([{ page: 'tab-1', active: true }]),
+            session: 'test',
             ...pageOverrides(),
         };
     });
@@ -2052,7 +2036,7 @@ describe('browser find command', () => {
             ],
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--css', '.btn']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'find', '--css', '.btn']);
         const out = lastJsonLog();
         expect(out.matches_n).toBe(2);
         expect(out.entries).toHaveLength(2);
@@ -2068,7 +2052,7 @@ describe('browser find command', () => {
             ],
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--role', 'button', '--name', 'Save']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'find', '--role', 'button', '--name', 'Save']);
         const js = browserState.page.evaluate.mock.calls[0][0];
         expect(js).toContain('CRITERIA');
         expect(js).toContain('function accessibleName');
@@ -2082,7 +2066,7 @@ describe('browser find command', () => {
     it('forwards --limit / --text-max into the generated JS', async () => {
         browserState.page.evaluate.mockResolvedValueOnce({ matches_n: 0, entries: [] });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--css', '.btn', '--limit', '3', '--text-max', '20']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'find', '--css', '.btn', '--limit', '3', '--text-max', '20']);
         const js = browserState.page.evaluate.mock.calls[0][0];
         expect(js).toContain('LIMIT = 3');
         expect(js).toContain('TEXT_MAX = 20');
@@ -2092,7 +2076,7 @@ describe('browser find command', () => {
             error: { code: 'invalid_selector', message: 'Invalid CSS selector: ">>>"', hint: 'Check the selector syntax.' },
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--css', '>>>']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'find', '--css', '>>>']);
         expect(lastJsonLog().error.code).toBe('invalid_selector');
         expect(process.exitCode).toBeDefined();
     });
@@ -2101,20 +2085,20 @@ describe('browser find command', () => {
             error: { code: 'selector_not_found', message: 'CSS selector ".missing" matched 0 elements', hint: 'Use browser state to inspect the page.' },
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--css', '.missing']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'find', '--css', '.missing']);
         expect(lastJsonLog().error.code).toBe('selector_not_found');
         expect(process.exitCode).toBeDefined();
     });
     it('rejects missing --css with usage_error (no evaluate call)', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'find']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'find']);
         expect(lastJsonLog().error.code).toBe('usage_error');
         expect(browserState.page.evaluate).not.toHaveBeenCalled();
         expect(process.exitCode).toBeDefined();
     });
     it('rejects malformed --limit with usage_error (no evaluate call)', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--css', '.btn', '--limit', 'abc']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'find', '--css', '.btn', '--limit', 'abc']);
         expect(lastJsonLog().error.code).toBe('usage_error');
         expect(browserState.page.evaluate).not.toHaveBeenCalled();
         expect(process.exitCode).toBeDefined();
@@ -2131,7 +2115,7 @@ describe('browser get text/value/attributes commands', () => {
         // 2nd call: getTextResolvedJs -> the element's text
         evalMock.mockResolvedValueOnce('Hello world');
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '7']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'text', '7']);
         expect(lastJsonLog()).toEqual({ value: 'Hello world', matches_n: 1, match_level: 'exact' });
     });
     it('resolves a semantic locator to a ref before get text', async () => {
@@ -2145,7 +2129,7 @@ describe('browser get text/value/attributes commands', () => {
         evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
         evalMock.mockResolvedValueOnce('Save');
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '--role', 'button', '--name', 'Save']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'text', '--role', 'button', '--name', 'Save']);
         expect(evalMock.mock.calls[0][0]).toContain('function accessibleName');
         expect(evalMock.mock.calls[1][0]).toContain('const ref = "12"');
         expect(lastJsonLog()).toEqual({ value: 'Save', matches_n: 1, match_level: 'exact' });
@@ -2163,7 +2147,7 @@ describe('browser get text/value/attributes commands', () => {
         evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
         evalMock.mockResolvedValueOnce('Save');
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '--role', 'button', '--name', 'Save']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'text', '--role', 'button', '--name', 'Save']);
         expect(evalMock.mock.calls[0][0]).toContain('const LIMIT = 6');
         expect(evalMock.mock.calls[1][0]).toContain('const ref = "12"');
         expect(lastJsonLog()).toEqual({ value: 'Save', matches_n: 1, match_level: 'exact', total_matches: 3 });
@@ -2173,7 +2157,7 @@ describe('browser get text/value/attributes commands', () => {
         evalMock.mockResolvedValueOnce({ ok: true, matches_n: 3, match_level: 'exact' });
         evalMock.mockResolvedValueOnce('first');
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '.btn']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'text', '.btn']);
         expect(lastJsonLog()).toEqual({ value: 'first', matches_n: 3, match_level: 'exact' });
     });
     it('parses the attributes payload back into a real object', async () => {
@@ -2182,7 +2166,7 @@ describe('browser get text/value/attributes commands', () => {
         // getAttributesResolvedJs returns a JSON-encoded string — the CLI must parse it
         evalMock.mockResolvedValueOnce(JSON.stringify({ id: 'nav', class: 'hero' }));
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'attributes', '#nav']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'attributes', '#nav']);
         const out = lastJsonLog();
         expect(out.matches_n).toBe(1);
         expect(out.match_level).toBe('exact');
@@ -2196,7 +2180,7 @@ describe('browser get text/value/attributes commands', () => {
             hint: 'Try a less specific selector.',
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '.missing']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'text', '.missing']);
         expect(lastJsonLog().error.code).toBe('selector_not_found');
         expect(process.exitCode).toBeDefined();
     });
@@ -2205,7 +2189,7 @@ describe('browser get text/value/attributes commands', () => {
         evalMock.mockResolvedValueOnce({ ok: true, matches_n: 4, match_level: 'exact' });
         evalMock.mockResolvedValueOnce('second');
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'value', '.btn', '--nth', '1']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'value', '.btn', '--nth', '1']);
         const resolveJs = evalMock.mock.calls[0][0];
         // resolveTargetJs embeds nth as a raw number literal; look for the binding
         expect(resolveJs).toContain('const nth = 1');
@@ -2213,7 +2197,7 @@ describe('browser get text/value/attributes commands', () => {
     });
     it('rejects malformed --nth with usage_error before touching the page', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '.btn', '--nth', 'abc']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'get', 'text', '.btn', '--nth', 'abc']);
         expect(lastJsonLog().error.code).toBe('usage_error');
         expect(browserState.page.evaluate).not.toHaveBeenCalled();
         expect(process.exitCode).toBeDefined();
@@ -2261,7 +2245,7 @@ describe('browser click/type commands', () => {
     it('emits {clicked, target, matches_n, match_level} on success', async () => {
         browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'click', '#save']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'click', '#save']);
         expect(browserState.page.click).toHaveBeenCalledWith('#save', {});
         expect(lastJsonLog()).toEqual({ clicked: true, target: '#save', matches_n: 1, match_level: 'exact' });
     });
@@ -2274,7 +2258,7 @@ describe('browser click/type commands', () => {
         });
         browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'click', '--role', 'button', '--name', 'Submit']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'click', '--role', 'button', '--name', 'Submit']);
         expect(browserState.page.click).toHaveBeenCalledWith('23', {});
         expect(lastJsonLog()).toEqual({ clicked: true, target: '23', matches_n: 1, match_level: 'exact' });
     });
@@ -2287,7 +2271,7 @@ describe('browser click/type commands', () => {
             ],
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'click', '--role', 'button', '--name', 'Save']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'click', '--role', 'button', '--name', 'Save']);
         const err = lastJsonLog().error;
         expect(err.code).toBe('semantic_ambiguous');
         expect(err.matches_n).toBe(2);
@@ -2302,7 +2286,7 @@ describe('browser click/type commands', () => {
             ],
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'hover', '--role', 'button', '--name', 'Settings']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'hover', '--role', 'button', '--name', 'Settings']);
         expect(browserState.page.hover).toHaveBeenCalledWith('31', {});
         expect(lastJsonLog()).toEqual({ hovered: true, target: '31', matches_n: 1, match_level: 'exact' });
     });
@@ -2315,7 +2299,7 @@ describe('browser click/type commands', () => {
         });
         browserState.page.setChecked.mockResolvedValueOnce({ checked: true, changed: false, matches_n: 1, match_level: 'exact', kind: 'checkbox' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'check', '--role', 'checkbox', '--name', 'Accept']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'check', '--role', 'checkbox', '--name', 'Accept']);
         expect(browserState.page.setChecked).toHaveBeenCalledWith('32', true, {});
         expect(lastJsonLog()).toEqual({ checked: true, changed: false, target: '32', matches_n: 1, match_level: 'exact', kind: 'checkbox' });
     });
@@ -2339,7 +2323,7 @@ describe('browser click/type commands', () => {
             multiple: false,
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'upload', '--role', 'button', '--name', 'Upload receipt', file]);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'upload', '--role', 'button', '--name', 'Upload receipt', file]);
         expect(browserState.page.uploadFiles).toHaveBeenCalledWith('33', [file], {});
         expect(lastJsonLog()).toMatchObject({ uploaded: true, target: '33', files: 1 });
     });
@@ -2355,7 +2339,7 @@ describe('browser click/type commands', () => {
         browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
         browserState.page.typeText.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'type', '--label', 'Email', 'me@example.com']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'type', '--label', 'Email', 'me@example.com']);
         expect(browserState.page.click).toHaveBeenCalledWith('34', {});
         expect(browserState.page.typeText).toHaveBeenCalledWith('34', 'me@example.com', {});
         expect(lastJsonLog()).toMatchObject({ typed: true, target: '34', text: 'me@example.com' });
@@ -2377,7 +2361,7 @@ describe('browser click/type commands', () => {
             match_level: 'exact',
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '--label', 'Email', 'me@example.com']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'fill', '--label', 'Email', 'me@example.com']);
         expect(browserState.page.fillText).toHaveBeenCalledWith('35', 'me@example.com', {});
         expect(lastJsonLog()).toMatchObject({ filled: true, verified: true, target: '35', text: 'me@example.com' });
     });
@@ -2409,6 +2393,8 @@ describe('browser click/type commands', () => {
             'node',
             'opencli',
             'browser',
+            '--session',
+            'test',
             'drag',
             '--from-role',
             'button',
@@ -2425,13 +2411,13 @@ describe('browser click/type commands', () => {
     it('surfaces match_level=stable when resolver falls back to fingerprint match', async () => {
         browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'stable' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'click', '7']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'click', '7']);
         expect(lastJsonLog()).toEqual({ clicked: true, target: '7', matches_n: 1, match_level: 'stable' });
     });
     it('forwards --nth as ResolveOptions.nth to page.click', async () => {
         browserState.page.click.mockResolvedValueOnce({ matches_n: 3, match_level: 'exact' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'click', '.btn', '--nth', '2']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'click', '.btn', '--nth', '2']);
         expect(browserState.page.click).toHaveBeenCalledWith('.btn', { nth: 2 });
         expect(lastJsonLog()).toEqual({ clicked: true, target: '.btn', matches_n: 3, match_level: 'exact' });
     });
@@ -2443,7 +2429,7 @@ describe('browser click/type commands', () => {
             matches_n: 3,
         }));
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'click', '.btn']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'click', '.btn']);
         const err = lastJsonLog().error;
         expect(err.code).toBe('selector_ambiguous');
         expect(err.matches_n).toBe(3);
@@ -2457,13 +2443,13 @@ describe('browser click/type commands', () => {
             matches_n: 3,
         }));
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'click', '.btn', '--nth', '99']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'click', '.btn', '--nth', '99']);
         expect(lastJsonLog().error.code).toBe('selector_nth_out_of_range');
         expect(process.exitCode).toBeDefined();
     });
     it('rejects malformed --nth on click with usage_error before touching the page', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'click', '.btn', '--nth', 'abc']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'click', '.btn', '--nth', 'abc']);
         expect(lastJsonLog().error.code).toBe('usage_error');
         expect(browserState.page.click).not.toHaveBeenCalled();
         expect(process.exitCode).toBeDefined();
@@ -2471,21 +2457,21 @@ describe('browser click/type commands', () => {
     it('hover: delegates to page.hover and emits a structured envelope', async () => {
         browserState.page.hover.mockResolvedValueOnce({ matches_n: 2, match_level: 'exact' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'hover', '.menu', '--nth', '1']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'hover', '.menu', '--nth', '1']);
         expect(browserState.page.hover).toHaveBeenCalledWith('.menu', { nth: 1 });
         expect(lastJsonLog()).toEqual({ hovered: true, target: '.menu', matches_n: 2, match_level: 'exact' });
     });
     it('focus: delegates to page.focus and reports whether the element took focus', async () => {
         browserState.page.focus.mockResolvedValueOnce({ focused: true, matches_n: 1, match_level: 'stable' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'focus', '7']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'focus', '7']);
         expect(browserState.page.focus).toHaveBeenCalledWith('7', {});
         expect(lastJsonLog()).toEqual({ focused: true, target: '7', matches_n: 1, match_level: 'stable' });
     });
     it('dblclick: delegates to page.dblClick and emits a structured envelope', async () => {
         browserState.page.dblClick.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'dblclick', '#row']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'dblclick', '#row']);
         expect(browserState.page.dblClick).toHaveBeenCalledWith('#row', {});
         expect(lastJsonLog()).toEqual({ dblclicked: true, target: '#row', matches_n: 1, match_level: 'exact' });
     });
@@ -2498,7 +2484,7 @@ describe('browser click/type commands', () => {
             kind: 'checkbox',
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'check', '.todo', '--nth', '1']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'check', '.todo', '--nth', '1']);
         expect(browserState.page.setChecked).toHaveBeenCalledWith('.todo', true, { nth: 1 });
         expect(lastJsonLog()).toEqual({ checked: true, changed: true, target: '.todo', matches_n: 2, match_level: 'exact', kind: 'checkbox' });
     });
@@ -2511,7 +2497,7 @@ describe('browser click/type commands', () => {
             kind: 'checkbox',
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'uncheck', '#subscribe']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'uncheck', '#subscribe']);
         expect(browserState.page.setChecked).toHaveBeenCalledWith('#subscribe', false, {});
         expect(lastJsonLog()).toEqual({ checked: false, changed: false, target: '#subscribe', matches_n: 1, match_level: 'stable', kind: 'checkbox' });
     });
@@ -2529,7 +2515,7 @@ describe('browser click/type commands', () => {
             multiple: false,
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'upload', '#file', file]);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'upload', '#file', file]);
         expect(browserState.page.uploadFiles).toHaveBeenCalledWith('#file', [file], {});
         expect(lastJsonLog()).toEqual({
             uploaded: true,
@@ -2543,7 +2529,7 @@ describe('browser click/type commands', () => {
     });
     it('upload: rejects missing files before touching the page', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'upload', '#file', '/tmp/opencli-missing-file']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'upload', '#file', '/tmp/opencli-missing-file']);
         expect(lastJsonLog().error.code).toBe('file_not_found');
         expect(browserState.page.uploadFiles).not.toHaveBeenCalled();
         expect(process.exitCode).toBeDefined();
@@ -2559,7 +2545,7 @@ describe('browser click/type commands', () => {
             target_match_level: 'stable',
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'drag', '.card', '.lane', '--from-nth', '2', '--to-nth', '1']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'drag', '.card', '.lane', '--from-nth', '2', '--to-nth', '1']);
         expect(browserState.page.drag).toHaveBeenCalledWith('.card', '.lane', { from: { nth: 2 }, to: { nth: 1 } });
         expect(lastJsonLog()).toEqual({
             dragged: true,
@@ -2573,7 +2559,7 @@ describe('browser click/type commands', () => {
     });
     it('drag: rejects malformed --from-nth before touching the page', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'drag', '.card', '.lane', '--from-nth', 'abc']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'drag', '.card', '.lane', '--from-nth', 'abc']);
         expect(lastJsonLog().error.code).toBe('usage_error');
         expect(browserState.page.drag).not.toHaveBeenCalled();
         expect(process.exitCode).toBeDefined();
@@ -2583,7 +2569,7 @@ describe('browser click/type commands', () => {
         browserState.page.typeText.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
         browserState.page.evaluate.mockResolvedValueOnce(false); // isAutocomplete
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'type', '#q', 'hello']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'type', '#q', 'hello']);
         expect(browserState.page.click).toHaveBeenCalledWith('#q', {});
         expect(browserState.page.wait).toHaveBeenCalledWith(0.3);
         expect(browserState.page.typeText).toHaveBeenCalledWith('#q', 'hello', {});
@@ -2596,7 +2582,7 @@ describe('browser click/type commands', () => {
         browserState.page.typeText.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
         browserState.page.evaluate.mockResolvedValueOnce(true);
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'type', '#q', 'hi']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'type', '#q', 'hi']);
         const waitCalls = browserState.page.wait.mock.calls;
         expect(waitCalls).toContainEqual([0.3]);
         expect(waitCalls).toContainEqual([0.4]);
@@ -2608,7 +2594,7 @@ describe('browser click/type commands', () => {
         browserState.page.typeText.mockResolvedValueOnce({ matches_n: 1, match_level: 'reidentified' });
         browserState.page.evaluate.mockResolvedValueOnce(false);
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'type', '9', 'hi']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'type', '9', 'hi']);
         // The typeText call is the authoritative match_level source for the `type` envelope.
         expect(lastJsonLog().match_level).toBe('reidentified');
     });
@@ -2616,7 +2602,7 @@ describe('browser click/type commands', () => {
         browserState.page.click.mockResolvedValueOnce({ matches_n: 5, match_level: 'exact' });
         browserState.page.typeText.mockResolvedValueOnce({ matches_n: 5, match_level: 'exact' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'type', '.field', 'x', '--nth', '3']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'type', '.field', 'x', '--nth', '3']);
         expect(browserState.page.click).toHaveBeenCalledWith('.field', { nth: 3 });
         expect(browserState.page.typeText).toHaveBeenCalledWith('.field', 'x', { nth: 3 });
     });
@@ -2632,7 +2618,7 @@ describe('browser click/type commands', () => {
             mode: 'textarea',
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '#msg', 'line1\\n/ / raw']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'fill', '#msg', 'line1\\n/ / raw']);
         expect(browserState.page.fillText).toHaveBeenCalledWith('#msg', 'line1\\n/ / raw', {});
         expect(lastJsonLog()).toEqual({
             filled: true,
@@ -2658,7 +2644,7 @@ describe('browser click/type commands', () => {
             match_level: 'exact',
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '#msg', 'expected']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'fill', '#msg', 'expected']);
         expect(lastJsonLog()).toEqual({
             filled: true,
             verified: false,
@@ -2673,7 +2659,7 @@ describe('browser click/type commands', () => {
     });
     it('fill: forwards --nth to page.fillText', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '.field', 'x', '--nth', '2']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'fill', '.field', 'x', '--nth', '2']);
         expect(browserState.page.fillText).toHaveBeenCalledWith('.field', 'x', { nth: 2 });
     });
 });
@@ -2686,7 +2672,7 @@ describe('browser select command', () => {
         evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
         evalMock.mockResolvedValueOnce({ selected: 'US' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'select', '#country', 'US']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'select', '#country', 'US']);
         expect(lastJsonLog()).toEqual({ selected: 'US', target: '#country', matches_n: 1, match_level: 'exact' });
     });
     it('maps "Not a <select>" to a not_a_select error envelope', async () => {
@@ -2694,7 +2680,7 @@ describe('browser select command', () => {
         evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
         evalMock.mockResolvedValueOnce({ error: 'Not a <select>' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'select', '#not-select', 'US']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'select', '#not-select', 'US']);
         const err = lastJsonLog().error;
         expect(err.code).toBe('not_a_select');
         expect(err.matches_n).toBe(1);
@@ -2705,7 +2691,7 @@ describe('browser select command', () => {
         evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
         evalMock.mockResolvedValueOnce({ error: 'Option "XX" not found', available: ['US', 'CA'] });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'select', '#country', 'XX']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'select', '#country', 'XX']);
         const err = lastJsonLog().error;
         expect(err.code).toBe('option_not_found');
         expect(err.available).toEqual(['US', 'CA']);
@@ -2723,7 +2709,7 @@ describe('browser select command', () => {
             .mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' })
             .mockResolvedValueOnce({ selected: 'Uruguay' });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'select', '--label', 'Country', 'Uruguay']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'select', '--label', 'Country', 'Uruguay']);
         expect(lastJsonLog()).toEqual({ selected: 'Uruguay', target: '36', matches_n: 1, match_level: 'exact' });
     });
     it('surfaces selector_ambiguous from the resolver before calling selectResolvedJs', async () => {
@@ -2735,7 +2721,7 @@ describe('browser select command', () => {
             matches_n: 2,
         });
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'select', '.dropdown', 'US']);
+        await program.parseAsync(['node', 'opencli', 'browser', '--session', 'test', 'select', '.dropdown', 'US']);
         expect(lastJsonLog().error.code).toBe('selector_ambiguous');
         // The select payload JS must not fire when resolution fails
         expect(browserState.page.evaluate.mock.calls).toHaveLength(1);