@agentrhq/webcmd 0.3.1 → 0.3.3

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

@@ -10,7 +10,7 @@ class CloakActionError extends Error {
         this.errorHint = errorHint;
     }
 }
-function commandProfileId(manager, command) {
+export function resolveCloakCommandProfileId(manager, command) {
     const requested = command.profileId ?? command.contextId;
     if (requested?.trim())
         return requested.trim();
@@ -38,7 +38,7 @@ async function resolveLease(manager, command) {
         throw new CloakActionError('stale_page_identity', `Page not found: ${command.page} — stale page identity`);
     }
     return manager.getPage({
-        profileId: commandProfileId(manager, command),
+        profileId: resolveCloakCommandProfileId(manager, command),
         session: command.session,
         surface: command.surface,
         siteSession: command.siteSession,
@@ -109,12 +109,12 @@ export async function dispatchCloakAction(manager, command) {
             }
             case 'close-window': {
                 if (command.page) {
-                    const closed = await manager.closePage({ profileId: commandProfileId(manager, command), pageId: command.page });
+                    const closed = await manager.closePage({ profileId: resolveCloakCommandProfileId(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(manager, command),
+                        profileId: resolveCloakCommandProfileId(manager, command),
                         session: command.session,
                         surface: command.surface,
                     });
@@ -124,12 +124,12 @@ export async function dispatchCloakAction(manager, command) {
             case 'tabs': {
                 switch (command.op ?? 'list') {
                     case 'list': {
-                        const tabs = await manager.listPages({ profileId: commandProfileId(manager, command) });
+                        const tabs = await manager.listPages({ profileId: resolveCloakCommandProfileId(manager, command) });
                         return { id: command.id, ok: true, data: tabs };
                     }
                     case 'new': {
                         const lease = await manager.newPage({
-                            profileId: commandProfileId(manager, command),
+                            profileId: resolveCloakCommandProfileId(manager, command),
                             session: command.session,
                             surface: command.surface,
                             siteSession: command.siteSession,
@@ -140,13 +140,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(manager, command), pageId: command.page, index: command.index, windowMode: command.windowMode });
+                        const lease = await manager.selectPage({ profileId: resolveCloakCommandProfileId(manager, command), pageId: command.page, index: command.index, windowMode: command.windowMode });
                         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(manager, command), pageId: command.page, index: command.index });
+                        const closed = await manager.closePage({ profileId: resolveCloakCommandProfileId(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 } };
@@ -214,7 +214,7 @@ export async function dispatchCloakAction(manager, command) {
                 }
                 {
                     const lease = await manager.bindPage({
-                        profileId: commandProfileId(manager, command),
+                        profileId: resolveCloakCommandProfileId(manager, command),
                         session: command.session,
                         surface: command.surface,
                         siteSession: command.siteSession,

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

@@ -10,6 +10,7 @@ export declare class LocalCloakRuntimeProvider implements BrowserRuntimeProvider
     private readonly manager;
     constructor(opts?: LocalCloakRuntimeProviderOptions);
     status(_opts?: RuntimeStatusOptions): Promise<BrowserRuntimeStatus>;
+    resolveProfileId(command: BrowserRuntimeCommand): string;
     dispatch(command: BrowserRuntimeCommand): Promise<BrowserRuntimeResult>;
     shutdown(): Promise<void>;
 }

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

@@ -1,5 +1,5 @@
-import { dispatchCloakAction } from './actions.js';
-import { CloakSessionManager } from './session-manager.js';
+import { dispatchCloakAction, resolveCloakCommandProfileId } from './actions.js';
+import { CloakSessionManager, resolveCloakBrowserVersion } from './session-manager.js';
 export class LocalCloakRuntimeProvider {
     opts;
     manager;
@@ -12,12 +12,15 @@ export class LocalCloakRuntimeProvider {
         return {
             runtimeConnected: true,
             runtimeName: 'cloak',
-            runtimeVersion: undefined,
+            runtimeVersion: resolveCloakBrowserVersion(),
             profiles,
             pending: 0,
             commandResultUnknown: 0,
         };
     }
+    resolveProfileId(command) {
+        return resolveCloakCommandProfileId(this.manager, command);
+    }
     async dispatch(command) {
         return dispatchCloakAction(this.manager, command);
     }

package/dist/src/browser/runtime/local-cloak/provider.test.js

@@ -27,6 +27,7 @@ function fakePage(url) {
 function makeProviderWithFakePage() {
     const pages = [fakePage('https://example.com/')];
     const context = {
+        on: vi.fn(),
         pages: vi.fn(() => pages.filter((page) => !page.isClosed())),
         newPage: vi.fn(async () => {
             const page = fakePage('about:blank');

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

@@ -3,6 +3,8 @@ import { launchPersistentContext as cloakLaunchPersistentContext } from 'cloakbr
 import type { BrowserSurface, BrowserWindowMode, SiteSessionMode } from '../../protocol.js';
 import { activateDarwinBackgroundContext } from './darwin-background-launch.js';
 import { CloakNetworkCapture } from './network.js';
+/** Installed `cloakbrowser` npm package version, for doctor/status display. */
+export declare function resolveCloakBrowserVersion(): string | undefined;
 export type LaunchPersistentContext = typeof cloakLaunchPersistentContext;
 export type RecoverLockedProfile = (userDataDir: string) => Promise<boolean>;
 export interface SessionKeyInput {
@@ -85,6 +87,9 @@ export declare class CloakSessionManager {
     shutdown(): Promise<void>;
     private getProfileRuntime;
     private launchProfileRuntime;
+    private invalidateProfileRuntime;
+    private attachRuntimeLifecycle;
+    private createPageWithRecovery;
     private openEntries;
     private findEntryByPageId;
     private refreshIdleTimer;

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

@@ -1,9 +1,23 @@
 import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { execFile } from 'node:child_process';
 import { launchPersistentContext as cloakLaunchPersistentContext } from 'cloakbrowser';
 import { activateDarwinBackgroundContext, launchDarwinBackgroundPersistentContext } from './darwin-background-launch.js';
 import { normalizeProfileId, resolveCloakProfileDir } from './profiles.js';
 import { CloakNetworkCapture } from './network.js';
+import { findPackageRoot } from '../../../package-paths.js';
+/** Installed `cloakbrowser` npm package version, for doctor/status display. */
+export function resolveCloakBrowserVersion() {
+    try {
+        const entryPath = fileURLToPath(import.meta.resolve('cloakbrowser'));
+        const pkg = JSON.parse(fs.readFileSync(path.join(findPackageRoot(entryPath), 'package.json'), 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 let pageCounter = 0;
 export function resolveLeaseKey(input) {
     const surface = input.surface === 'adapter' ? 'adapter' : 'browser';
@@ -15,6 +29,10 @@ export function resolveLeaseKey(input) {
 function pageIsClosed(page) {
     return page.isClosed?.() === true;
 }
+function isClosedContextError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /Target page, context or browser has been closed/i.test(message);
+}
 export class CloakSessionManager {
     opts;
     networkCapture = new CloakNetworkCapture();
@@ -37,7 +55,7 @@ export class CloakSessionManager {
         return [...this.profiles.entries()].map(([contextId, runtime]) => ({
             contextId,
             runtimeConnected: true,
-            runtimeVersion: runtime.runtimeVersion,
+            runtimeVersion: resolveCloakBrowserVersion(),
             pending: 0,
             lastSeenAt: runtime.lastSeenAt,
         }));
@@ -67,16 +85,21 @@ export class CloakSessionManager {
             if (!pageIsClosed(existing.page))
                 await existing.page.close().catch(() => { });
         }
-        const existingPages = runtime.context.pages();
-        // 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);
-        this.refreshIdleTimer(runtime, leaseKey, entry);
-        runtime.selectedPageId = pageId;
-        runtime.lastSeenAt = Date.now();
-        return { profileId, leaseKey, context: runtime.context, page, pageId };
+        return this.createPageWithRecovery(profileId, input.windowMode, (candidate) => {
+            const existingPages = candidate.context.pages();
+            // freshPage must never adopt a leftover tab — its whole point is a clean DOM.
+            return !freshPage && existingPages[0] && candidate.pages.size === 0
+                ? existingPages[0]
+                : candidate.context.newPage();
+        }, (candidate, page) => {
+            const pageId = nextPageId();
+            const entry = { page, pageId, session, surface, siteSession: input.siteSession, idleTimeout: input.idleTimeout };
+            candidate.pages.set(leaseKey, entry);
+            this.refreshIdleTimer(candidate, leaseKey, entry);
+            candidate.selectedPageId = pageId;
+            candidate.lastSeenAt = Date.now();
+            return { profileId, leaseKey, context: candidate.context, page, pageId };
+        });
     }
     findPageById(pageId, opts = {}) {
         for (const [profileId, runtime] of this.profiles.entries()) {
@@ -137,18 +160,36 @@ export class CloakSessionManager {
         const profileId = normalizeProfileId(input.profileId);
         const session = requireSession(input.session);
         const surface = normalizeSurface(input.surface);
-        const runtime = await this.getProfileRuntime(profileId, input.windowMode);
-        const page = await runtime.context.newPage();
+        const acquired = await this.createPageWithRecovery(profileId, input.windowMode, (candidate) => candidate.context.newPage(), (runtime, page) => ({ runtime, page }));
         if (input.url) {
-            await page.goto(input.url, { waitUntil: 'load' });
+            try {
+                await acquired.page.goto(input.url, { waitUntil: 'load' });
+            }
+            catch (error) {
+                if (!pageIsClosed(acquired.page))
+                    await acquired.page.close().catch(() => { });
+                throw error;
+            }
+        }
+        if (this.profiles.get(profileId) !== acquired.runtime) {
+            if (!pageIsClosed(acquired.page))
+                await acquired.page.close().catch(() => { });
+            throw new Error('Target page, context or browser has been closed');
         }
         const pageId = nextPageId();
         const leaseKey = `${resolveLeaseKey(input)}\u0000${pageId}`;
-        const entry = { page, pageId, session, surface, siteSession: input.siteSession, idleTimeout: input.idleTimeout };
-        runtime.pages.set(leaseKey, entry);
-        this.refreshIdleTimer(runtime, leaseKey, entry);
-        runtime.lastSeenAt = Date.now();
-        return { profileId, leaseKey, context: runtime.context, page, pageId };
+        const entry = {
+            page: acquired.page,
+            pageId,
+            session,
+            surface,
+            siteSession: input.siteSession,
+            idleTimeout: input.idleTimeout,
+        };
+        acquired.runtime.pages.set(leaseKey, entry);
+        this.refreshIdleTimer(acquired.runtime, leaseKey, entry);
+        acquired.runtime.lastSeenAt = Date.now();
+        return { profileId, leaseKey, context: acquired.runtime.context, page: acquired.page, pageId };
     }
     async selectPage(input) {
         const profileId = normalizeProfileId(input.profileId);
@@ -285,9 +326,44 @@ export class CloakSessionManager {
             context = await launchPersistentContext(launchOptions);
         }
         const runtime = { context, pages: new Map(), lastSeenAt: Date.now() };
+        this.attachRuntimeLifecycle(profileId, runtime);
         this.profiles.set(profileId, runtime);
         return runtime;
     }
+    invalidateProfileRuntime(profileId, runtime) {
+        if (this.profiles.get(profileId) !== runtime)
+            return;
+        this.profiles.delete(profileId);
+        for (const entry of runtime.pages.values()) {
+            if (entry.idleTimer)
+                clearTimeout(entry.idleTimer);
+            this.networkCapture.stop(entry.page);
+        }
+        runtime.pages.clear();
+        runtime.selectedPageId = undefined;
+    }
+    attachRuntimeLifecycle(profileId, runtime) {
+        runtime.context.on('close', () => this.invalidateProfileRuntime(profileId, runtime));
+    }
+    async createPageWithRecovery(profileId, windowMode, createPage, commitPage, attempt = 0) {
+        const runtime = await this.getProfileRuntime(profileId, windowMode);
+        let page;
+        try {
+            page = await createPage(runtime);
+        }
+        catch (error) {
+            if (attempt !== 0 || !isClosedContextError(error))
+                throw error;
+            this.invalidateProfileRuntime(profileId, runtime);
+            return this.createPageWithRecovery(profileId, windowMode, createPage, commitPage, 1);
+        }
+        if (this.profiles.get(profileId) !== runtime) {
+            if (!pageIsClosed(page))
+                await page.close().catch(() => { });
+            throw new Error('Target page, context or browser has been closed');
+        }
+        return commitPage(runtime, page);
+    }
     openEntries(runtime) {
         return [...runtime.pages.entries()].filter(([, entry]) => !pageIsClosed(entry.page));
     }

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

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { CloakSessionManager } from './session-manager.js';
 import { dispatchCloakAction } from './actions.js';
 function fakeContext() {
+    const listeners = new Map();
     const page = {
         goto: vi.fn().mockResolvedValue(undefined),
         evaluate: vi.fn().mockResolvedValue('ok'),
@@ -14,6 +15,15 @@ function fakeContext() {
     };
     return {
         context: {
+            on(event, listener) {
+                const bucket = listeners.get(event) ?? new Set();
+                bucket.add(listener);
+                listeners.set(event, bucket);
+            },
+            emit(event) {
+                for (const listener of listeners.get(event) ?? [])
+                    listener();
+            },
             pages: vi.fn().mockReturnValue([page]),
             newPage: vi.fn().mockResolvedValue(page),
             cookies: vi.fn().mockResolvedValue([{ name: 'sid', value: '1', domain: 'example.com', path: '/' }]),
@@ -98,6 +108,229 @@ describe('CloakSessionManager', () => {
         expect(second.context).toBe(launched.context);
         expect(first.page).toBe(second.page);
     });
+    it('evicts a closed runtime and clears every tracked page resource', async () => {
+        vi.useFakeTimers();
+        const launched = fakeContext();
+        const secondPage = fakeContext().page;
+        launched.context.newPage.mockResolvedValue(secondPage);
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(launched.context),
+        });
+        const stopCapture = vi.spyOn(manager.networkCapture, 'stop');
+        const first = await manager.getPage({ profileId: 'default', session: 'one', surface: 'browser', idleTimeout: 25 });
+        const second = await manager.newPage({ profileId: 'default', session: 'two', surface: 'browser', idleTimeout: 25 });
+        expect(manager.activeProfileIds()).toEqual(['default']);
+        expect(vi.getTimerCount()).toBe(2);
+        launched.context.emit('close');
+        expect(manager.activeProfileIds()).toEqual([]);
+        expect(manager.profileStatuses()).toEqual([]);
+        expect(vi.getTimerCount()).toBe(0);
+        expect(stopCapture).toHaveBeenCalledTimes(2);
+        expect(stopCapture).toHaveBeenCalledWith(first.page);
+        expect(stopCapture).toHaveBeenCalledWith(second.page);
+        await vi.advanceTimersByTimeAsync(25);
+        expect(first.page.close).not.toHaveBeenCalled();
+        expect(second.page.close).not.toHaveBeenCalled();
+    });
+    it('does not let a late close from an old runtime evict its replacement', async () => {
+        const first = fakeContext();
+        const replacement = fakeContext();
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        await manager.getPage({ profileId: 'default', session: 'first', surface: 'browser' });
+        first.context.emit('close');
+        const replacementLease = await manager.getPage({ profileId: 'default', session: 'replacement', surface: 'browser' });
+        first.context.emit('close');
+        expect(manager.activeProfileIds()).toEqual(['default']);
+        expect(manager.profileStatuses()).toHaveLength(1);
+        expect((await manager.getPage({ profileId: 'default', session: 'replacement', surface: 'browser' })).context)
+            .toBe(replacementLease.context);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('coalesces simultaneous replacement launches after a context closes', async () => {
+        const first = fakeContext();
+        const replacement = fakeContext();
+        let resolveReplacement;
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockImplementationOnce(() => new Promise((resolve) => {
+            resolveReplacement = resolve;
+        }));
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        await manager.getPage({ profileId: 'default', session: 'first', surface: 'browser' });
+        first.context.emit('close');
+        const one = manager.getPage({ profileId: 'default', session: 'one', surface: 'browser' });
+        const two = manager.getPage({ profileId: 'default', session: 'two', surface: 'browser' });
+        await Promise.resolve();
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+        resolveReplacement(replacement.context);
+        const leases = await Promise.all([one, two]);
+        expect(leases[0].context).toBe(replacement.context);
+        expect(leases[1].context).toBe(replacement.context);
+    });
+    it('discards a page created after its runtime closes and defers recovery to the next command', async () => {
+        const first = fakeContext();
+        first.context.pages.mockReturnValue([]);
+        let resolveFirstPage;
+        let markPageCreationStarted;
+        const pageCreationStarted = new Promise((resolve) => {
+            markPageCreationStarted = resolve;
+        });
+        first.context.newPage.mockImplementation(() => {
+            markPageCreationStarted();
+            return new Promise((resolve) => {
+                resolveFirstPage = resolve;
+            });
+        });
+        const replacement = fakeContext();
+        replacement.context.pages.mockReturnValue([]);
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        const pendingLease = manager.getPage({ profileId: 'default', session: 'work', surface: 'browser' });
+        await pageCreationStarted;
+        first.context.emit('close');
+        resolveFirstPage(first.page);
+        await expect(pendingLease).rejects.toThrow('Target page, context or browser has been closed');
+        expect(first.page.close).toHaveBeenCalled();
+        expect(manager.activeProfileIds()).toEqual([]);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(1);
+        const lease = await manager.getPage({ profileId: 'default', session: 'work', surface: 'browser' });
+        expect(lease.context).toBe(replacement.context);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('does not publish an orphaned page after acquisition validation', async () => {
+        vi.useFakeTimers();
+        const first = fakeContext();
+        first.context.pages.mockReturnValue([]);
+        first.context.newPage.mockImplementation(() => ({
+            then(resolve) {
+                resolve(first.page);
+                queueMicrotask(() => first.context.emit('close'));
+            },
+        }));
+        const replacement = fakeContext();
+        replacement.context.pages.mockReturnValue([]);
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        await manager.getPage({ profileId: 'default', session: 'first', surface: 'browser', idleTimeout: 25 });
+        expect(manager.activeProfileIds()).toEqual([]);
+        expect(vi.getTimerCount()).toBe(0);
+        const lease = await manager.getPage({ profileId: 'default', session: 'replacement', surface: 'browser' });
+        expect(lease.context).toBe(replacement.context);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('retries getPage page creation once after a closed-context failure', async () => {
+        const closed = new Error('Target page, context or browser has been closed');
+        const first = fakeContext();
+        first.context.pages.mockReturnValue([]);
+        first.context.newPage.mockRejectedValue(closed);
+        const replacement = fakeContext();
+        replacement.context.pages.mockReturnValue([]);
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        const lease = await manager.getPage({ profileId: 'default', session: 'work', surface: 'browser' });
+        expect(lease.context).toBe(replacement.context);
+        expect(first.context.newPage).toHaveBeenCalledTimes(1);
+        expect(replacement.context.newPage).toHaveBeenCalledTimes(1);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('retries explicit newPage page creation once after a closed-context failure', async () => {
+        const closed = new Error('browserContext.newPage: Target page, context or browser has been closed');
+        const first = fakeContext();
+        first.context.newPage.mockRejectedValue(closed);
+        const replacement = fakeContext();
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        const lease = await manager.newPage({ profileId: 'default', session: 'work', surface: 'browser' });
+        expect(lease.context).toBe(replacement.context);
+        expect(first.context.newPage).toHaveBeenCalledTimes(1);
+        expect(replacement.context.newPage).toHaveBeenCalledTimes(1);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('returns the second closed-context page creation failure without looping', async () => {
+        const firstFailure = new Error('Target page, context or browser has been closed');
+        const secondFailure = new Error('Target page, context or browser has been closed again');
+        const first = fakeContext();
+        first.context.newPage.mockRejectedValue(firstFailure);
+        const replacement = fakeContext();
+        replacement.context.newPage.mockRejectedValue(secondFailure);
+        const launchPersistentContext = vi.fn()
+            .mockResolvedValueOnce(first.context)
+            .mockResolvedValueOnce(replacement.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        await expect(manager.newPage({ profileId: 'default', session: 'work', surface: 'browser' }))
+            .rejects.toBe(secondFailure);
+        expect(first.context.newPage).toHaveBeenCalledTimes(1);
+        expect(replacement.context.newPage).toHaveBeenCalledTimes(1);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
+    it('keeps an explicitly navigated page untracked until navigation succeeds', async () => {
+        vi.useFakeTimers();
+        const launched = fakeContext();
+        let resolveNavigation;
+        let markNavigationStarted;
+        const navigationStarted = new Promise((resolve) => {
+            markNavigationStarted = resolve;
+        });
+        launched.page.goto.mockImplementation(() => {
+            markNavigationStarted();
+            return new Promise((resolve) => {
+                resolveNavigation = resolve;
+            });
+        });
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(launched.context),
+        });
+        const pendingLease = manager.newPage({
+            profileId: 'default',
+            session: 'work',
+            surface: 'browser',
+            idleTimeout: 25,
+            url: 'https://example.com/',
+        });
+        await navigationStarted;
+        const pagesDuringNavigation = await manager.listPages({ profileId: 'default' });
+        const pageIdDuringNavigation = manager.pageIdFor(launched.page);
+        const timersDuringNavigation = vi.getTimerCount();
+        resolveNavigation();
+        const lease = await pendingLease;
+        expect(pagesDuringNavigation).toEqual([]);
+        expect(pageIdDuringNavigation).toBeUndefined();
+        expect(timersDuringNavigation).toBe(0);
+        expect(manager.pageIdFor(launched.page)).toBe(lease.pageId);
+        expect(await manager.listPages({ profileId: 'default' })).toHaveLength(1);
+        expect(vi.getTimerCount()).toBe(1);
+    });
+    it('does not retry or retain a page when navigation fails after creation', async () => {
+        const navigationFailure = new Error('Target page, context or browser has been closed');
+        const launched = fakeContext();
+        launched.page.goto.mockRejectedValue(navigationFailure);
+        const launchPersistentContext = vi.fn().mockResolvedValue(launched.context);
+        const manager = new CloakSessionManager({ baseDir: '/tmp/webcmd-test', launchPersistentContext });
+        await expect(manager.newPage({
+            profileId: 'default',
+            session: 'work',
+            surface: 'browser',
+            url: 'https://example.com/',
+        })).rejects.toBe(navigationFailure);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(1);
+        expect(launched.context.newPage).toHaveBeenCalledTimes(1);
+        expect(launched.page.goto).toHaveBeenCalledTimes(1);
+        expect(launched.page.close).toHaveBeenCalledTimes(1);
+        expect(await manager.listPages({ profileId: 'default' })).toEqual([]);
+    });
     it('clears a stale Cloak profile owner and retries when Chromium reports an existing session', async () => {
         const launched = fakeContext();
         const launchPersistentContext = vi.fn()
@@ -125,6 +358,7 @@ describe('CloakSessionManager', () => {
         });
         const openPages = [];
         const context = {
+            on: vi.fn(),
             pages: vi.fn(() => openPages),
             newPage: vi.fn(async () => {
                 const page = makePage();
@@ -159,6 +393,7 @@ describe('CloakSessionManager', () => {
             close: vi.fn().mockResolvedValue(undefined),
         };
         const context = {
+            on: vi.fn(),
             pages: vi.fn().mockReturnValue([leftover]),
             newPage: vi.fn().mockResolvedValue(created),
             cookies: vi.fn().mockResolvedValue([]),

package/dist/src/browser/runtime/provider.d.ts

@@ -4,6 +4,7 @@ export interface RuntimeStatusOptions {
 }
 export interface BrowserRuntimeProvider {
     status(opts?: RuntimeStatusOptions): Promise<BrowserRuntimeStatus>;
+    resolveProfileId?(command: BrowserRuntimeCommand): string;
     dispatch(command: BrowserRuntimeCommand): Promise<BrowserRuntimeResult>;
     shutdown(): Promise<void>;
 }