@agentrhq/webcmd 0.2.0 → 0.2.2

package/dist/src/browser/bridge-readiness.test.js

@@ -9,7 +9,7 @@ function status(runtimeConnected) {
         runtimeName: 'fake',
         pending: 0,
         memoryMB: 0,
-        port: 19825,
+        port: 9777,
     };
 }
 function readyHealth() {

package/dist/src/browser/bridge.d.ts

@@ -17,9 +17,11 @@ export declare class BrowserBridge implements IBrowserFactory {
         session?: string;
         idleTimeout?: number;
         contextId?: string;
+        preferredContextId?: string;
         windowMode?: 'foreground' | 'background';
         surface?: 'browser' | 'adapter';
         siteSession?: 'ephemeral' | 'persistent';
+        freshPage?: boolean;
     }): Promise<IPage>;
     close(): Promise<void>;
     private _ensureDaemon;

package/dist/src/browser/bridge.js

@@ -2,7 +2,7 @@
  * Browser session manager — auto-spawns daemon and provides IPage.
  */
 import { Page } from './page.js';
-import { resolveProfileContextId } from './profile.js';
+import { profileRouteParams, resolveProfileSelection } from './profile.js';
 import { ensureBrowserBridgeReady } from './daemon-lifecycle.js';
 const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
 /**
@@ -26,11 +26,13 @@ export class BrowserBridge {
             throw new Error('Session is closed');
         this._state = 'connecting';
         try {
-            const contextId = opts.contextId ?? resolveProfileContextId();
-            await this._ensureDaemon(opts.timeout, contextId);
+            const routing = opts.contextId || opts.preferredContextId
+                ? { contextId: opts.contextId, preferredContextId: opts.preferredContextId }
+                : profileRouteParams(resolveProfileSelection());
+            await this._ensureDaemon(opts.timeout, routing.contextId);
             if (!opts.session?.trim())
                 throw new Error('Browser session is required');
-            this._page = new Page(opts.session.trim(), opts.idleTimeout, contextId, opts.windowMode, opts.surface, opts.siteSession);
+            this._page = new Page(opts.session.trim(), opts.idleTimeout, routing.contextId, opts.windowMode, opts.surface, opts.siteSession, routing.preferredContextId, opts.freshPage);
             this._state = 'connected';
             return this._page;
         }

package/dist/src/browser/cdp.d.ts

@@ -26,6 +26,7 @@ export declare class CDPBridge implements IBrowserFactory {
         session?: string;
         cdpEndpoint?: string;
         contextId?: string;
+        preferredContextId?: string;
         idleTimeout?: number;
         windowMode?: 'foreground' | 'background';
         surface?: 'browser' | 'adapter';

package/dist/src/browser/daemon-client.d.ts

@@ -28,6 +28,7 @@ export declare function sendCommandFull(action: DaemonCommand['action'], params?
 }>;
 export declare function bindTab(session: string, opts?: {
     contextId?: string;
+    preferredContextId?: string;
     page?: string;
     index?: number;
 }): Promise<unknown>;

package/dist/src/browser/daemon-client.js

@@ -7,7 +7,7 @@ import { sleep } from '../utils.js';
 import { BrowserConnectError } from '../errors.js';
 import { COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT } from '../daemon-utils.js';
 import { classifyBrowserError } from './errors.js';
-import { resolveProfileContextId } from './profile.js';
+import { profileRouteParams, resolveProfileSelection } from './profile.js';
 import { DEFAULT_BROWSER_CONNECT_TIMEOUT } from './config.js';
 import { ensureBrowserBridgeReady } from './daemon-lifecycle.js';
 import { isPreDispatchError } from './bridge-readiness.js';
@@ -90,7 +90,11 @@ async function sendCommandRaw(action, params) {
     const envWindowMode = rawWindowMode === 'foreground' || rawWindowMode === 'background'
         ? rawWindowMode
         : undefined;
-    const contextId = params.contextId ?? resolveProfileContextId();
+    const routing = params.contextId || params.preferredContextId
+        ? { contextId: params.contextId, preferredContextId: params.preferredContextId }
+        : profileRouteParams(resolveProfileSelection());
+    const contextId = routing.contextId;
+    const preferredContextId = routing.preferredContextId;
     const windowMode = params.windowMode ?? envWindowMode;
     let id = generateId();
     let ensureUsed = false;
@@ -115,6 +119,7 @@ async function sendCommandRaw(action, params) {
             timeout: timeoutSeconds,
             deadlineAt,
             ...(contextId && { contextId }),
+            ...(preferredContextId && { preferredContextId }),
             ...(windowMode && { windowMode }),
         };
         try {

package/dist/src/browser/daemon-client.test.js

@@ -22,7 +22,7 @@ describe('daemon-client', () => {
             runtimeVersion: '1.2.3',
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         };
         const fetchMock = vi.mocked(fetch);
         fetchMock.mockResolvedValue({
@@ -60,7 +60,7 @@ describe('daemon-client', () => {
             runtimeName: 'fake',
             pending: 0,
             memoryMB: 16,
-            port: 19825,
+            port: 9777,
         };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
@@ -78,7 +78,7 @@ describe('daemon-client', () => {
             runtimeVersion: '1.2.3',
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
@@ -100,7 +100,7 @@ describe('daemon-client', () => {
             ],
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
@@ -119,32 +119,12 @@ describe('daemon-client', () => {
                 runtimeName: 'fake',
                 pending: 0,
                 memoryMB: 1,
-                port: 19825,
+                port: 9777,
             }),
         });
         await fetchDaemonStatus({ contextId: 'work' });
         expect(vi.mocked(fetch).mock.calls[0][0]).toMatch(/\/status\?contextId=work$/);
     });
-    it('rejects WEBCMD_DAEMON_PORT so CLI and extension cannot split bridge ports', async () => {
-        vi.resetModules();
-        vi.stubEnv('WEBCMD_DAEMON_PORT', '19999');
-        vi.mocked(fetch).mockResolvedValue({
-            ok: true,
-            json: () => Promise.resolve({
-                ok: true,
-                pid: 1,
-                uptime: 0,
-                runtimeConnected: true,
-                runtimeName: 'fake',
-                pending: 0,
-                memoryMB: 1,
-                port: 19825,
-            }),
-        });
-        const freshClient = await import('./daemon-client.js');
-        await expect(freshClient.fetchDaemonStatus()).rejects.toThrow('WEBCMD_DAEMON_PORT is no longer supported');
-        expect(vi.mocked(fetch)).not.toHaveBeenCalled();
-    });
     it('sendCommand includes the current pid in generated command ids', async () => {
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
         vi.mocked(fetch).mockResolvedValue({
@@ -162,7 +142,7 @@ describe('daemon-client', () => {
         expect(ids[1]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
         expect(ids[0]).not.toBe(ids[1]);
     });
-    it('sendCommand forwards WEBCMD_PROFILE as command contextId', async () => {
+    it('sendCommand forwards WEBCMD_PROFILE as a hard contextId requirement', async () => {
         vi.stubEnv('WEBCMD_PROFILE', 'work');
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
         vi.mocked(fetch).mockResolvedValue({
@@ -172,6 +152,29 @@ describe('daemon-client', () => {
         await sendCommand('exec', { code: '1 + 1' });
         const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
         expect(body.contextId).toBe('work');
+        expect(body.preferredContextId).toBeUndefined();
+    });
+    it('sendCommand forwards the config default as preferredContextId', async () => {
+        const fs = await import('node:fs');
+        const os = await import('node:os');
+        const path = await import('node:path');
+        const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-dc-profile-'));
+        fs.writeFileSync(path.join(configDir, 'browser-profiles.json'), JSON.stringify({ version: 1, aliases: {}, defaultContextId: 'profile-default' }));
+        vi.stubEnv('WEBCMD_CONFIG_DIR', configDir);
+        vi.stubEnv('WEBCMD_PROFILE', '');
+        try {
+            vi.mocked(fetch).mockResolvedValue({
+                status: 200,
+                json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+            });
+            await sendCommand('exec', { code: '1 + 1' });
+            const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
+            expect(body.contextId).toBeUndefined();
+            expect(body.preferredContextId).toBe('profile-default');
+        }
+        finally {
+            fs.rmSync(configDir, { recursive: true, force: true });
+        }
     });
     it('sendCommand uses explicit windowMode before WEBCMD_WINDOW env fallback', async () => {
         vi.stubEnv('WEBCMD_WINDOW', 'foreground');
@@ -230,7 +233,7 @@ describe('daemon-client', () => {
                     runtimeName: 'fake',
                     pending: 0,
                     memoryMB: 0,
-                    port: 19825,
+                    port: 9777,
                 },
             },
             spawnedProcess: null,
@@ -269,13 +272,13 @@ describe('daemon-client', () => {
                     runtimeName: 'fake',
                     pending: 0,
                     memoryMB: 0,
-                    port: 19825,
+                    port: 9777,
                 },
             },
             spawnedProcess: null,
         });
         const refused = new TypeError('fetch failed');
-        refused.cause = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:19825'), { code: 'ECONNREFUSED' });
+        refused.cause = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:9777'), { code: 'ECONNREFUSED' });
         const fetchMock = vi.mocked(fetch);
         fetchMock
             .mockRejectedValueOnce(refused)
@@ -300,7 +303,7 @@ describe('daemon-client', () => {
                     runtimeName: 'fake',
                     pending: 0,
                     memoryMB: 0,
-                    port: 19825,
+                    port: 9777,
                 },
             },
             spawnedProcess: null,

package/dist/src/browser/daemon-transport.js

@@ -1,20 +1,8 @@
-import { DAEMON_HEADER_NAME, DEFAULT_DAEMON_PORT, unsupportedDaemonPortEnvMessage } from '../constants.js';
+import { DAEMON_HEADER_NAME, DEFAULT_DAEMON_PORT } from '../constants.js';
 const DAEMON_PORT = DEFAULT_DAEMON_PORT;
 const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
 const WEBCMD_HEADERS = { [DAEMON_HEADER_NAME]: '1' };
-class UnsupportedDaemonPortEnvError extends Error {
-    constructor(value) {
-        super(unsupportedDaemonPortEnvMessage(value));
-        this.name = 'UnsupportedDaemonPortEnvError';
-    }
-}
-function assertSupportedDaemonPortEnv() {
-    const value = process.env.WEBCMD_DAEMON_PORT;
-    if (value !== undefined && value !== '')
-        throw new UnsupportedDaemonPortEnvError(value);
-}
 export async function requestDaemon(pathname, init) {
-    assertSupportedDaemonPortEnv();
     const { timeout = 2000, headers, ...rest } = init ?? {};
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
@@ -37,9 +25,7 @@ export async function fetchDaemonStatus(opts) {
             return null;
         return await res.json();
     }
-    catch (err) {
-        if (err instanceof UnsupportedDaemonPortEnvError)
-            throw err;
+    catch {
         return null;
     }
 }
@@ -60,9 +46,7 @@ export async function requestDaemonShutdown(opts) {
         const res = await requestDaemon('/shutdown', { method: 'POST', timeout: opts?.timeout ?? 5000 });
         return res.ok;
     }
-    catch (err) {
-        if (err instanceof UnsupportedDaemonPortEnvError)
-            throw err;
+    catch {
         return false;
     }
 }

package/dist/src/browser/page.d.ts

@@ -19,8 +19,12 @@ export declare class Page extends BasePage {
     private readonly windowMode?;
     private readonly surface;
     private readonly siteSession?;
+    readonly preferredContextId?: string | undefined;
     private readonly _idleTimeout;
-    constructor(session: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined, surface?: 'browser' | 'adapter', siteSession?: "ephemeral" | "persistent" | undefined);
+    constructor(session: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined, surface?: 'browser' | 'adapter', siteSession?: "ephemeral" | "persistent" | undefined, preferredContextId?: string | undefined, freshPage?: boolean);
+    /** When set, the next daemon command asks for a fresh leased page; consumed on first send. */
+    private _freshPagePending;
+    private _freshPageOpts;
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
     private _networkCaptureUnsupported;

package/dist/src/browser/page.js

@@ -40,15 +40,26 @@ export class Page extends BasePage {
     windowMode;
     surface;
     siteSession;
+    preferredContextId;
     _idleTimeout;
-    constructor(session, idleTimeout, contextId, windowMode, surface = 'browser', siteSession) {
+    constructor(session, idleTimeout, contextId, windowMode, surface = 'browser', siteSession, preferredContextId, freshPage) {
         super();
         this.session = session;
         this.contextId = contextId;
         this.windowMode = windowMode;
         this.surface = surface;
         this.siteSession = siteSession;
+        this.preferredContextId = preferredContextId;
         this._idleTimeout = idleTimeout;
+        this._freshPagePending = freshPage === true;
+    }
+    /** When set, the next daemon command asks for a fresh leased page; consumed on first send. */
+    _freshPagePending;
+    _freshPageOpts() {
+        if (!this._freshPagePending)
+            return {};
+        this._freshPagePending = false;
+        return { freshPage: true };
     }
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     _page;
@@ -60,9 +71,11 @@ export class Page extends BasePage {
             session: this.session,
             surface: this.surface,
             ...(this.contextId && { contextId: this.contextId }),
+            ...(this.preferredContextId && { preferredContextId: this.preferredContextId }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
             ...(this.windowMode && { windowMode: this.windowMode }),
             ...(this.siteSession && { siteSession: this.siteSession }),
+            ...this._freshPageOpts(),
         };
     }
     /** Helper: spread session + page identity into command params */
@@ -71,10 +84,12 @@ export class Page extends BasePage {
             session: this.session,
             surface: this.surface,
             ...(this.contextId && { contextId: this.contextId }),
+            ...(this.preferredContextId && { preferredContextId: this.preferredContextId }),
             ...(this._page !== undefined && { page: this._page }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
             ...(this.windowMode && { windowMode: this.windowMode }),
             ...(this.siteSession && { siteSession: this.siteSession }),
+            ...this._freshPageOpts(),
         };
     }
     async goto(url, options) {

package/dist/src/browser/profile.d.ts

@@ -8,6 +8,15 @@ export declare function normalizeContextId(value: string | undefined | null): st
 export declare function emptyProfileConfig(): ProfileConfig;
 export declare function loadProfileConfig(): ProfileConfig;
 export declare function saveProfileConfig(config: ProfileConfig): void;
+export type ProfileSelection = {
+    contextId: string;
+    source: 'explicit' | 'preferred';
+};
+export declare function resolveProfileSelection(profile?: string): ProfileSelection | undefined;
+export declare function profileRouteParams(selection: ProfileSelection | undefined): {
+    contextId?: string;
+    preferredContextId?: string;
+};
 export declare function resolveProfileContextId(profile?: string): string | undefined;
 export declare function aliasForContextId(config: ProfileConfig, contextId: string): string | undefined;
 export declare function renameProfile(contextId: string, alias: string): ProfileConfig;

package/dist/src/browser/profile.js

@@ -42,14 +42,25 @@ export function saveProfileConfig(config) {
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.writeFileSync(target, JSON.stringify(config, null, 2) + '\n', 'utf-8');
 }
-export function resolveProfileContextId(profile) {
+export function resolveProfileSelection(profile) {
     const config = loadProfileConfig();
-    const requested = normalizeContextId(profile)
-        ?? normalizeContextId(process.env[`${ENV_PREFIX}_PROFILE`])
-        ?? normalizeContextId(config.defaultContextId);
-    if (!requested)
-        return undefined;
-    return config.aliases[requested] ?? requested;
+    const explicit = normalizeContextId(profile) ?? normalizeContextId(process.env[`${ENV_PREFIX}_PROFILE`]);
+    if (explicit)
+        return { contextId: config.aliases[explicit] ?? explicit, source: 'explicit' };
+    const preferred = normalizeContextId(config.defaultContextId);
+    if (preferred)
+        return { contextId: config.aliases[preferred] ?? preferred, source: 'preferred' };
+    return undefined;
+}
+export function profileRouteParams(selection) {
+    if (!selection)
+        return {};
+    return selection.source === 'explicit'
+        ? { contextId: selection.contextId }
+        : { preferredContextId: selection.contextId };
+}
+export function resolveProfileContextId(profile) {
+    return resolveProfileSelection(profile)?.contextId;
 }
 export function aliasForContextId(config, contextId) {
     for (const [alias, id] of Object.entries(config.aliases)) {

package/dist/src/browser/profile.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/profile.test.js

@@ -0,0 +1,44 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { ENV_PREFIX } from '../brand.js';
+import { profileRouteParams, resolveProfileSelection } from './profile.js';
+describe('profile selection', () => {
+    let configDir;
+    beforeEach(() => {
+        configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-profile-test-'));
+        vi.stubEnv(`${ENV_PREFIX}_CONFIG_DIR`, configDir);
+        vi.stubEnv(`${ENV_PREFIX}_PROFILE`, '');
+    });
+    afterEach(() => {
+        vi.unstubAllEnvs();
+        fs.rmSync(configDir, { recursive: true, force: true });
+    });
+    function writeConfig(config) {
+        fs.writeFileSync(path.join(configDir, 'browser-profiles.json'), JSON.stringify(config));
+    }
+    it('tags an explicit profile argument as explicit and resolves aliases', () => {
+        writeConfig({ version: 1, aliases: { work: 'profile-work' } });
+        expect(resolveProfileSelection('work')).toEqual({ contextId: 'profile-work', source: 'explicit' });
+    });
+    it('tags WEBCMD_PROFILE as explicit', () => {
+        vi.stubEnv(`${ENV_PREFIX}_PROFILE`, 'profile-env');
+        expect(resolveProfileSelection()).toEqual({ contextId: 'profile-env', source: 'explicit' });
+    });
+    it('tags the persisted config default as preferred', () => {
+        writeConfig({ version: 1, aliases: {}, defaultContextId: 'profile-default' });
+        expect(resolveProfileSelection()).toEqual({ contextId: 'profile-default', source: 'preferred' });
+    });
+    it('explicit argument beats env, and env beats config default', () => {
+        vi.stubEnv(`${ENV_PREFIX}_PROFILE`, 'from-env');
+        writeConfig({ version: 1, aliases: {}, defaultContextId: 'from-config' });
+        expect(resolveProfileSelection('from-arg')).toEqual({ contextId: 'from-arg', source: 'explicit' });
+        expect(resolveProfileSelection()).toEqual({ contextId: 'from-env', source: 'explicit' });
+    });
+    it('maps explicit routes to contextId and preferred routes to preferredContextId', () => {
+        expect(profileRouteParams({ contextId: 'a', source: 'explicit' })).toEqual({ contextId: 'a' });
+        expect(profileRouteParams({ contextId: 'b', source: 'preferred' })).toEqual({ preferredContextId: 'b' });
+        expect(profileRouteParams(undefined)).toEqual({});
+    });
+});

package/dist/src/browser/protocol.d.ts

@@ -10,6 +10,8 @@ export interface BrowserRuntimeCommand {
     session?: string;
     surface?: BrowserSurface;
     siteSession?: SiteSessionMode;
+    /** Close any existing leased page and start on a new one (sent on the first action of a command run). */
+    freshPage?: boolean;
     url?: string;
     op?: string;
     index?: number;
@@ -34,6 +36,7 @@ export interface BrowserRuntimeCommand {
     idleTimeout?: number;
     frameIndex?: number;
     contextId?: string;
+    preferredContextId?: string;
     profileId?: string;
 }
 export interface BrowserRuntimeResult {

package/dist/src/browser/runtime/local-cloak/actions.js

@@ -10,8 +10,22 @@ class CloakActionError extends Error {
         this.errorHint = errorHint;
     }
 }
-function commandProfileId(command) {
-    return command.profileId ?? command.contextId ?? 'default';
+function commandProfileId(manager, command) {
+    const requested = command.profileId ?? command.contextId;
+    if (requested?.trim())
+        return requested.trim();
+    const preferred = command.preferredContextId?.trim();
+    if (!preferred)
+        return 'default';
+    const active = manager.activeProfileIds();
+    if (active.includes(preferred))
+        return preferred;
+    if (active.length === 1)
+        return active[0];
+    if (active.length > 1) {
+        throw new CloakActionError('profile_required', `Default Cloak profile "${preferred}" is not active and multiple profiles are running; choose one with --profile.`, undefined, 'Run webcmd profile list, then update the default with webcmd profile use <name> or pass --profile <name>.');
+    }
+    return preferred;
 }
 function invalidRequest(command, error) {
     return { id: command.id, ok: false, errorCode: 'invalid_request', error };
@@ -24,11 +38,12 @@ async function resolveLease(manager, command) {
         throw new CloakActionError('stale_page_identity', `Page not found: ${command.page} — stale page identity`);
     }
     return manager.getPage({
-        profileId: commandProfileId(command),
+        profileId: commandProfileId(manager, command),
         session: command.session,
         surface: command.surface,
         siteSession: command.siteSession,
         idleTimeout: command.idleTimeout,
+        freshPage: command.freshPage,
     });
 }
 function execTarget(page, frameIndex, pageId) {
@@ -93,12 +108,12 @@ export async function dispatchCloakAction(manager, command) {
             }
             case 'close-window': {
                 if (command.page) {
-                    const closed = await manager.closePage({ profileId: commandProfileId(command), pageId: command.page });
+                    const closed = await manager.closePage({ profileId: commandProfileId(manager, command), pageId: command.page });
                     return { id: command.id, ok: true, data: { closed: Boolean(closed), page: closed ?? command.page, session: command.session } };
                 }
                 else {
                     await manager.release({
-                        profileId: commandProfileId(command),
+                        profileId: commandProfileId(manager, command),
                         session: command.session,
                         surface: command.surface,
                     });
@@ -108,12 +123,12 @@ export async function dispatchCloakAction(manager, command) {
             case 'tabs': {
                 switch (command.op ?? 'list') {
                     case 'list': {
-                        const tabs = await manager.listPages({ profileId: commandProfileId(command) });
+                        const tabs = await manager.listPages({ profileId: commandProfileId(manager, command) });
                         return { id: command.id, ok: true, data: tabs };
                     }
                     case 'new': {
                         const lease = await manager.newPage({
-                            profileId: commandProfileId(command),
+                            profileId: commandProfileId(manager, command),
                             session: command.session,
                             surface: command.surface,
                             siteSession: command.siteSession,
@@ -123,13 +138,13 @@ export async function dispatchCloakAction(manager, command) {
                         return { id: command.id, ok: true, data: { title: await lease.page.title(), url: lease.page.url() }, page: lease.pageId };
                     }
                     case 'select': {
-                        const lease = await manager.selectPage({ profileId: commandProfileId(command), pageId: command.page, index: command.index });
+                        const lease = await manager.selectPage({ profileId: commandProfileId(manager, command), pageId: command.page, index: command.index });
                         if (!lease)
                             return { id: command.id, ok: false, errorCode: 'runtime_command_failed', error: 'Tab not found' };
                         return { id: command.id, ok: true, data: { selected: true, url: lease.page.url() }, page: lease.pageId };
                     }
                     case 'close': {
-                        const closed = await manager.closePage({ profileId: commandProfileId(command), pageId: command.page, index: command.index });
+                        const closed = await manager.closePage({ profileId: commandProfileId(manager, command), pageId: command.page, index: command.index });
                         if (!closed)
                             return { id: command.id, ok: false, errorCode: 'runtime_command_failed', error: 'Tab not found' };
                         return { id: command.id, ok: true, data: { closed } };
@@ -197,7 +212,7 @@ export async function dispatchCloakAction(manager, command) {
                 }
                 {
                     const lease = await manager.bindPage({
-                        profileId: commandProfileId(command),
+                        profileId: commandProfileId(manager, command),
                         session: command.session,
                         surface: command.surface,
                         siteSession: command.siteSession,

package/dist/src/browser/runtime/local-cloak/session-manager.d.ts

@@ -9,6 +9,8 @@ export interface SessionKeyInput {
     surface?: BrowserSurface;
     siteSession?: SiteSessionMode;
     idleTimeout?: number;
+    /** Discard the existing leased page (if any) and create a new one under the same lease. */
+    freshPage?: boolean;
 }
 export interface CloakPageLease {
     profileId: string;
@@ -46,6 +48,7 @@ export declare class CloakSessionManager {
         pending: number;
         lastSeenAt: number;
     }[];
+    activeProfileIds(): string[];
     getPage(input: SessionKeyInput): Promise<CloakPageLease>;
     findPageById(pageId: string, opts?: Pick<SessionKeyInput, 'idleTimeout'>): CloakPageLease | null;
     pageIdFor(page: PlaywrightPage): string | undefined;

package/dist/src/browser/runtime/local-cloak/session-manager.js

@@ -31,21 +31,34 @@ export class CloakSessionManager {
             lastSeenAt: runtime.lastSeenAt,
         }));
     }
+    activeProfileIds() {
+        return [...this.profiles.keys()];
+    }
     async getPage(input) {
         const profileId = normalizeProfileId(input.profileId);
         const session = requireSession(input.session);
         const surface = normalizeSurface(input.surface);
         const leaseKey = resolveLeaseKey(input);
         const runtime = await this.getProfileRuntime(profileId);
+        const freshPage = input.freshPage === true;
         const existing = runtime.pages.get(leaseKey);
-        if (existing && !pageIsClosed(existing.page)) {
+        if (existing && !pageIsClosed(existing.page) && !freshPage) {
             runtime.lastSeenAt = Date.now();
             existing.idleTimeout = input.idleTimeout;
             this.refreshIdleTimer(runtime, leaseKey, existing);
             return { profileId, leaseKey, context: runtime.context, page: existing.page, pageId: existing.pageId };
         }
+        if (existing && freshPage) {
+            runtime.pages.delete(leaseKey);
+            this.clearIdleTimer(existing);
+            if (runtime.selectedPageId === existing.pageId)
+                runtime.selectedPageId = undefined;
+            if (!pageIsClosed(existing.page))
+                await existing.page.close().catch(() => { });
+        }
         const existingPages = runtime.context.pages();
-        const page = existingPages[0] && runtime.pages.size === 0 ? existingPages[0] : await runtime.context.newPage();
+        // freshPage must never adopt a leftover tab — its whole point is a clean DOM.
+        const page = !freshPage && existingPages[0] && runtime.pages.size === 0 ? existingPages[0] : await runtime.context.newPage();
         const pageId = nextPageId();
         const entry = { page, pageId, session, surface, siteSession: input.siteSession, idleTimeout: input.idleTimeout };
         runtime.pages.set(leaseKey, entry);