@jackwener/opencli 1.7.15 → 1.7.17

package/dist/src/cli.test.js

@@ -343,19 +343,24 @@ 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');
             expect(data.description).toBe('Browser control — navigate, click, type, extract, wait (no LLM needed)');
             expect(data.command_count).toBeGreaterThan(20);
-            expect(data.namespace_options).toMatchObject([
-                {
-                    name: 'workspace',
-                    flags: '--workspace <name>',
+            expect(data.namespace_options).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    name: 'session',
+                    flags: '--session <name>',
                     takes_value: 'required',
-                },
-            ]);
+                }),
+                expect.objectContaining({
+                    name: 'window',
+                    flags: '--window <mode>',
+                    takes_value: 'required',
+                }),
+            ]));
             expect(data.global_options).toEqual(expect.arrayContaining([
                 expect.objectContaining({
                     name: 'version',
@@ -401,7 +406,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',
@@ -421,7 +426,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']);
+            expect(data.namespace_options.map((option) => option.name)).toEqual(['session', 'window']);
             expect(data.structured_help).toMatchObject({
                 usage: 'opencli browser tab --help -f yaml',
             });
@@ -437,7 +442,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',
@@ -450,13 +455,113 @@ 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']);
+            expect(data.namespace_options.map((option) => option.name)).toEqual(['session', 'window']);
             expect(data.global_options.map((option) => option.name)).toContain('profile');
         }
         finally {
             process.argv = argv;
         }
     });
+    it('renders daemon namespace structured help with leaves and global options', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const daemon = program.commands.find(cmd => cmd.name() === 'daemon');
+            expect(daemon).toBeTruthy();
+            process.argv = ['node', 'opencli', 'daemon', '--help', '-f', 'yaml'];
+            const data = yaml.load(daemon.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'daemon',
+                command: 'opencli daemon',
+                usage: 'opencli daemon <command> [args] [options]',
+                description: 'Manage the opencli daemon',
+                command_count: 3,
+                namespace_options: [],
+                structured_help: { usage: 'opencli daemon --help -f yaml' },
+            });
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['restart', 'status', 'stop']);
+            expect(data.global_options.map((option) => option.name)).toEqual(expect.arrayContaining(['version', 'profile']));
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders plugin namespace structured help with positional + option leaves', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const plugin = program.commands.find(cmd => cmd.name() === 'plugin');
+            expect(plugin).toBeTruthy();
+            process.argv = ['node', 'opencli', 'plugin', '--help', '-f', 'yaml'];
+            const data = yaml.load(plugin.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'plugin',
+                command: 'opencli plugin',
+                description: 'Manage opencli plugins',
+                namespace_options: [],
+            });
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['create', 'install', 'list', 'uninstall', 'update']);
+            const update = data.commands.find((cmd) => cmd.name === 'update');
+            expect(update).toMatchObject({
+                usage: 'opencli plugin update [name] [options]',
+                positionals: [{ name: 'name' }],
+            });
+            expect(update.command_options.map((option) => option.name)).toEqual(['all']);
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders adapter namespace structured help preserving original description after applyRootSubcommandSummaries', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const adapter = program.commands.find(cmd => cmd.name() === 'adapter');
+            expect(adapter).toBeTruthy();
+            process.argv = ['node', 'opencli', 'adapter', '--help', '-f', 'yaml'];
+            const data = yaml.load(adapter.helpInformation());
+            // applyRootSubcommandSummaries() rewrites .description() to a child-name listing;
+            // structured help must surface the original product description via the snapshot.
+            expect(data.description).toBe('Manage CLI adapters');
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['eject', 'reset', 'status']);
+            const reset = data.commands.find((cmd) => cmd.name === 'reset');
+            expect(reset).toMatchObject({
+                usage: 'opencli adapter reset [site] [options]',
+                positionals: [{ name: 'site' }],
+            });
+            expect(reset.command_options.map((option) => option.name)).toEqual(['all']);
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders profile namespace structured help including required positionals', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const profile = program.commands.find(cmd => cmd.name() === 'profile');
+            expect(profile).toBeTruthy();
+            process.argv = ['node', 'opencli', 'profile', '--help', '-f', 'yaml'];
+            const data = yaml.load(profile.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'profile',
+                description: 'Manage Browser Bridge Chrome profiles',
+                command_count: 3,
+            });
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['list', 'rename', 'use']);
+            const rename = data.commands.find((cmd) => cmd.name === 'rename');
+            expect(rename).toMatchObject({
+                usage: 'opencli profile rename <contextId> <alias> [options]',
+                positionals: [
+                    { name: 'contextId', required: true },
+                    { name: 'alias', required: true },
+                ],
+            });
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
 });
 describe('resolveBrowserVerifyInvocation', () => {
     it('prefers the built entry declared in package metadata', () => {
@@ -554,7 +659,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']);
@@ -582,7 +687,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']);
@@ -611,7 +716,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']);
@@ -643,7 +748,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');
@@ -717,8 +822,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;
@@ -727,8 +832,9 @@ describe('browser tab targeting commands', () => {
         stderrSpy.mockClear();
         mockBrowserConnect.mockClear();
         mockBrowserClose.mockReset().mockResolvedValue(undefined);
+        delete process.env.OPENCLI_WINDOW;
         mockBindTab.mockReset().mockResolvedValue({
-            workspace: 'bound:default',
+            session: 'test',
             page: 'tab-2',
             url: 'https://user.example/inbox',
             title: 'Inbox',
@@ -759,6 +865,7 @@ describe('browser tab targeting commands', () => {
             screenshot: vi.fn().mockResolvedValue('base64-shot'),
             annotatedScreenshot: vi.fn().mockResolvedValue('annotated-base64-shot'),
             readNetworkCapture: vi.fn().mockResolvedValue([]),
+            closeWindow: vi.fn().mockResolvedValue(undefined),
             waitForDownload: vi.fn().mockResolvedValue({
                 downloaded: true,
                 filename: '/tmp/receipt.pdf',
@@ -766,6 +873,7 @@ describe('browser tab targeting commands', () => {
                 state: 'complete',
                 elapsedMs: 10,
             }),
+            session: 'test',
         };
     });
     function lastJsonLog() {
@@ -777,36 +885,37 @@ 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']);
+        await program.parseAsync(['node', 'opencli', 'browser', 'state']);
         expect(mockBrowserConnect).not.toHaveBeenCalled();
-        expect(mockBindTab).not.toHaveBeenCalled();
-        const out = lastJsonLog();
-        expect(out.error.code).toBe('invalid_bind_workspace');
+        expect(stderrSpy.mock.calls.flat().join('')).toContain('--session <name> is required');
         expect(process.exitCode).toBeDefined();
     });
-    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' });
+        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', '--session', 'test', '--window', 'background', 'state']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, session: 'test', surface: 'browser', windowMode: 'background' });
         expect(browserState.page?.snapshot).toHaveBeenCalled();
     });
     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 () => {
@@ -820,7 +929,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();
@@ -838,7 +947,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({
@@ -848,7 +957,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');
@@ -856,7 +965,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,
@@ -867,38 +976,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' });
@@ -909,7 +1016,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');
@@ -917,7 +1024,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');
     });
@@ -929,7 +1036,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();
@@ -937,50 +1044,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');
@@ -989,7 +1096,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(),
@@ -998,35 +1105,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');
@@ -1073,7 +1181,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');
@@ -1134,7 +1242,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);
@@ -1173,7 +1281,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'));
@@ -1221,7 +1329,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);
@@ -1245,7 +1353,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,
@@ -1271,7 +1379,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);
@@ -1281,10 +1389,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;
@@ -1302,6 +1410,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 }]),
@@ -1328,7 +1437,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);
@@ -1337,22 +1446,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');
@@ -1387,7 +1496,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');
@@ -1411,7 +1520,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);
@@ -1421,16 +1530,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' } } });
@@ -1439,9 +1548,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');
@@ -1449,7 +1558,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();
@@ -1457,7 +1566,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');
@@ -1470,7 +1579,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);
@@ -1495,7 +1604,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']);
@@ -1504,14 +1613,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([]);
@@ -1520,7 +1629,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([]);
@@ -1529,43 +1638,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');
@@ -1587,7 +1696,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);
@@ -1606,9 +1715,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);
@@ -1626,10 +1735,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',
             ]);
@@ -1651,10 +1760,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',
             ]);
@@ -1675,10 +1784,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',
             ]);
@@ -1698,7 +1807,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];
@@ -1719,6 +1828,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 }]),
@@ -1740,7 +1850,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' });
@@ -1777,14 +1887,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);
@@ -1792,21 +1902,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();
@@ -1818,7 +1928,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');
@@ -1827,14 +1937,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();
     });
@@ -1844,7 +1954,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('##$@@');
@@ -1858,7 +1968,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('##$@@');
@@ -1866,7 +1976,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();
     });
@@ -1899,6 +2009,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(),
         };
     });
@@ -1920,7 +2031,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);
@@ -1936,7 +2047,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');
@@ -1950,7 +2061,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');
@@ -1960,7 +2071,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();
     });
@@ -1969,20 +2080,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();
@@ -1999,7 +2110,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 () => {
@@ -2013,7 +2124,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' });
@@ -2031,7 +2142,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 });
@@ -2041,7 +2152,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 () => {
@@ -2050,7 +2161,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');
@@ -2064,7 +2175,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();
     });
@@ -2073,7 +2184,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');
@@ -2081,7 +2192,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();
@@ -2129,7 +2240,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' });
     });
@@ -2142,7 +2253,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' });
     });
@@ -2155,7 +2266,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);
@@ -2170,7 +2281,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' });
     });
@@ -2183,7 +2294,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' });
     });
@@ -2207,7 +2318,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 });
     });
@@ -2223,7 +2334,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' });
@@ -2245,7 +2356,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' });
     });
@@ -2277,6 +2388,8 @@ describe('browser click/type commands', () => {
             'node',
             'opencli',
             'browser',
+            '--session',
+            'test',
             'drag',
             '--from-role',
             'button',
@@ -2293,13 +2406,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' });
     });
@@ -2311,7 +2424,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);
@@ -2325,13 +2438,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();
@@ -2339,21 +2452,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' });
     });
@@ -2366,7 +2479,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' });
     });
@@ -2379,7 +2492,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' });
     });
@@ -2397,7 +2510,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,
@@ -2411,7 +2524,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();
@@ -2427,7 +2540,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,
@@ -2441,7 +2554,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();
@@ -2451,7 +2564,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', {});
@@ -2464,7 +2577,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]);
@@ -2476,7 +2589,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');
     });
@@ -2484,7 +2597,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 });
     });
@@ -2500,7 +2613,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,
@@ -2526,7 +2639,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,
@@ -2541,7 +2654,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 });
     });
 });
@@ -2554,7 +2667,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 () => {
@@ -2562,7 +2675,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);
@@ -2573,7 +2686,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']);
@@ -2591,7 +2704,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 () => {
@@ -2603,7 +2716,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);