@agentrhq/webcmd 0.3.1 → 0.3.3

package/dist/src/execution.js

@@ -15,11 +15,11 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import { executePipeline } from './pipeline/index.js';
-import { adapterLoadError, ArgumentError, CommandExecutionError, attachTraceReceipt, getErrorMessage } from './errors.js';
+import { adapterLoadError, ArgumentError, CommandExecutionError, TimeoutError, attachTraceReceipt, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 import { profileRouteParams, resolveProfileSelection } from './browser/profile.js';
-import { setDaemonCommandTimeoutSeconds } from './browser/daemon-client.js';
+import { releaseSiteSessionLease, setDaemonCommandTimeoutSeconds } from './browser/daemon-client.js';
 import { emitHook } from './hooks.js';
 import { log } from './logger.js';
 import { isElectronApp } from './electron-apps.js';
@@ -27,10 +27,16 @@ import { probeCDP, resolveElectronEndpoint } from './launcher.js';
 import { ObservationSession, exportObservationSession } from './observation/index.js';
 import { resolveAdapterSourcePath } from './adapter-source.js';
 import { coerceCommandArguments, TRACE_MODES } from './command-surface.js';
+import { clearDaemonRunContext, generateRunId, isUnknownOutcomeError, runWithDaemonRunContext } from './session-lease.js';
 const _loadedModules = new Map();
 /** Track mtime of loaded user adapter files for hot-reload in daemon mode. */
 const _moduleMtimes = new Map();
 const _userClisDir = `${os.homedir()}/.webcmd/clis/`;
+async function finalizeRun(runId, release) {
+    clearDaemonRunContext(runId);
+    if (release)
+        await releaseSiteSessionLease(runId).catch(() => undefined);
+}
 function normalizeTraceMode(raw) {
     if (raw === undefined || raw === null || raw === '' || raw === 'off')
         return 'off';
@@ -178,7 +184,15 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
             const session = resolveAdapterBrowserSession(cmd, siteSession);
             const keepTab = resolveKeepTab(siteSession, opts.keepTab);
             const windowMode = resolveBrowserWindowMode(cmd.defaultWindowMode ?? 'background', opts.windowMode);
-            result = await browserSession(BrowserFactory, async (page) => {
+            const surface = 'adapter';
+            const canonicalCommand = fullName(cmd);
+            const leaseEligible = surface === 'adapter'
+                && siteSession === 'persistent'
+                && cmd.access === 'write';
+            const runId = leaseEligible ? generateRunId() : undefined;
+            let releaseRun = true;
+            let deferRunFinalization = false;
+            const executeAdapter = async (page) => {
                 const observation = traceMode === 'off'
                     ? null
                     : new ObservationSession({
@@ -223,6 +237,8 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         });
                     }
                     catch (err) {
+                        if (runId && isUnknownOutcomeError(err))
+                            releaseRun = false;
                         observation?.record({
                             stream: 'action',
                             name: 'pre_navigate',
@@ -244,13 +260,16 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         throw wrapped;
                     }
                 }
+                const adapterPromise = Promise.resolve(runCommand(cmd, page, kwargs, debug));
+                let adapterSettled = false;
+                void adapterPromise.then(() => { adapterSettled = true; }, () => { adapterSettled = true; });
                 try {
                     const browserTimeout = userTimeoutSec !== null
                         ? userTimeoutSec + RUNTIME_TIMEOUT_PADDING_SECONDS
                         : DEFAULT_BROWSER_COMMAND_TIMEOUT;
-                    const result = await runWithTimeout(runCommand(cmd, page, kwargs, debug), {
+                    const result = await runWithTimeout(adapterPromise, {
                         timeout: browserTimeout,
-                        label: fullName(cmd),
+                        label: canonicalCommand,
                     });
                     observation?.record({
                         stream: 'action',
@@ -269,6 +288,15 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     return result;
                 }
                 catch (err) {
+                    if (runId && isUnknownOutcomeError(err))
+                        releaseRun = false;
+                    if (runId && err instanceof TimeoutError && !adapterSettled) {
+                        releaseRun = false;
+                        deferRunFinalization = true;
+                        void adapterPromise
+                            .then(() => finalizeRun(runId, true), (lateError) => finalizeRun(runId, !isUnknownOutcomeError(lateError)))
+                            .catch(() => undefined);
+                    }
                     if (observation) {
                         observation.record({
                             stream: 'action',
@@ -293,7 +321,30 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { session, cdpEndpoint, ...profileRouting, windowMode, surface: 'adapter', siteSession, freshPage: cmd.freshPage === true && siteSession === 'persistent' });
+            };
+            const executeBrowser = () => browserSession(BrowserFactory, executeAdapter, {
+                session,
+                cdpEndpoint,
+                ...profileRouting,
+                windowMode,
+                surface,
+                siteSession,
+                freshPage: cmd.freshPage === true && siteSession === 'persistent',
+            });
+            try {
+                result = runId
+                    ? await runWithDaemonRunContext({ runId, command: canonicalCommand, access: 'write' }, executeBrowser)
+                    : await executeBrowser();
+            }
+            catch (err) {
+                if (runId && isUnknownOutcomeError(err))
+                    releaseRun = false;
+                throw err;
+            }
+            finally {
+                if (runId && !deferRunFinalization)
+                    await finalizeRun(runId, releaseRun);
+            }
         }
         else {
             // Non-browser commands: enforce a timeout only when the command exposes

package/dist/src/execution.test.js

@@ -1,14 +1,16 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-const { mockSetDaemonCommandTimeoutSeconds } = vi.hoisted(() => ({
+const { mockReleaseSiteSessionLease, mockSetDaemonCommandTimeoutSeconds } = vi.hoisted(() => ({
+    mockReleaseSiteSessionLease: vi.fn().mockResolvedValue(undefined),
     mockSetDaemonCommandTimeoutSeconds: vi.fn(),
 }));
 vi.mock('./browser/daemon-client.js', async () => {
     const actual = await vi.importActual('./browser/daemon-client.js');
     return {
         ...actual,
+        releaseSiteSessionLease: mockReleaseSiteSessionLease,
         setDaemonCommandTimeoutSeconds: mockSetDaemonCommandTimeoutSeconds,
     };
 });
@@ -17,6 +19,17 @@ import { ArgumentError, TimeoutError, toEnvelope } from './errors.js';
 import { cli, Strategy } from './registry.js';
 import * as runtime from './runtime.js';
 import * as capRouting from './capabilityRouting.js';
+import { clearDaemonRunContext, getDaemonRunContext } from './session-lease.js';
+import { sendCommand } from './browser/daemon-client.js';
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
 describe('executeCommand — non-browser timeout', () => {
     it('applies the user --timeout arg as the ceiling for non-browser commands', async () => {
         const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
@@ -148,6 +161,417 @@ describe('executeCommand — non-browser timeout', () => {
         });
         vi.restoreAllMocks();
     });
+    describe('persistent write run ownership', () => {
+        afterEach(() => {
+            const activeRun = getDaemonRunContext();
+            if (activeRun)
+                clearDaemonRunContext(activeRun.runId);
+            mockReleaseSiteSessionLease.mockReset().mockResolvedValue(undefined);
+            vi.restoreAllMocks();
+            vi.unstubAllGlobals();
+        });
+        it('binds a run only for browser-backed persistent writes', async () => {
+            const seen = new Map();
+            const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockImplementation(cmd => cmd.browser !== false);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+            const makeCommand = (name, access, browser, siteSession) => cli({
+                site: 'test-execution',
+                name,
+                access,
+                description: 'test logical run eligibility',
+                browser,
+                strategy: Strategy.PUBLIC,
+                siteSession,
+                func: async () => {
+                    seen.set(name, getDaemonRunContext());
+                    return [{ ok: true }];
+                },
+            });
+            await executeCommand(makeCommand('run-eligible', 'write', true, 'persistent'), {});
+            await executeCommand(makeCommand('run-read', 'read', true, 'persistent'), {});
+            await executeCommand(makeCommand('run-ephemeral', 'write', true, 'ephemeral'), {});
+            await executeCommand(makeCommand('run-non-browser', 'write', false, 'persistent'), {});
+            const eligibleRun = seen.get('run-eligible');
+            expect(eligibleRun).toMatchObject({
+                runId: expect.stringMatching(/^run_/),
+                command: 'test-execution/run-eligible',
+                access: 'write',
+            });
+            expect(seen.get('run-read')).toBeUndefined();
+            expect(seen.get('run-ephemeral')).toBeUndefined();
+            expect(seen.get('run-non-browser')).toBeUndefined();
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledOnce();
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledWith(eligibleRun?.runId);
+        });
+        it('binds one canonical run before session setup, pre-navigation, and adapter execution', async () => {
+            const seen = [];
+            const capture = (stage) => seen.push({ stage, run: getDaemonRunContext() });
+            const mockPage = {
+                closeWindow: vi.fn().mockResolvedValue(undefined),
+                getCurrentUrl: vi.fn().mockImplementation(async () => {
+                    capture('current-url');
+                    return 'about:blank';
+                }),
+                goto: vi.fn().mockImplementation(async () => capture('pre-navigation')),
+            };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => {
+                capture('session');
+                return fn(mockPage);
+            });
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'run-bound-before-operations',
+                access: 'write',
+                description: 'test one run spans the complete adapter execution',
+                browser: true,
+                strategy: Strategy.COOKIE,
+                domain: 'example.com',
+                siteSession: 'persistent',
+                func: async () => {
+                    capture('adapter');
+                    return [{ ok: true }];
+                },
+            });
+            await expect(executeCommand(cmd, {})).resolves.toEqual([{ ok: true }]);
+            expect(seen.map(entry => entry.stage)).toEqual([
+                'session',
+                'current-url',
+                'pre-navigation',
+                'adapter',
+            ]);
+            const runId = seen[0]?.run?.runId;
+            expect(runId).toMatch(/^run_/);
+            for (const entry of seen) {
+                expect(entry.run).toEqual({
+                    runId,
+                    command: 'test-execution/run-bound-before-operations',
+                    access: 'write',
+                });
+            }
+            expect(getDaemonRunContext()).toBeUndefined();
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledOnce();
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledWith(runId);
+        });
+        it('clears and releases the run once after an ordinary adapter error', async () => {
+            let runId;
+            const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'run-ordinary-error',
+                access: 'write',
+                description: 'test ordinary errors release run ownership',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'persistent',
+                func: async () => {
+                    runId = getDaemonRunContext()?.runId;
+                    throw new Error('ordinary adapter failure');
+                },
+            });
+            await expect(executeCommand(cmd, {})).rejects.toThrow('ordinary adapter failure');
+            expect(runId).toMatch(/^run_/);
+            expect(getDaemonRunContext()).toBeUndefined();
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledOnce();
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledWith(runId);
+        });
+        it('clears but does not release a run when an error cause has unknown outcome', async () => {
+            let runId;
+            const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+            const unknownOutcome = new Error('wrapped adapter failure');
+            unknownOutcome.cause = { code: 'COMMAND_RESULT_UNKNOWN' };
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'run-unknown-outcome',
+                access: 'write',
+                description: 'test unknown outcomes retain the daemon lease',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'persistent',
+                func: async () => {
+                    runId = getDaemonRunContext()?.runId;
+                    throw unknownOutcome;
+                },
+            });
+            await expect(executeCommand(cmd, {})).rejects.toBe(unknownOutcome);
+            expect(runId).toMatch(/^run_/);
+            expect(getDaemonRunContext()).toBeUndefined();
+            expect(mockReleaseSiteSessionLease).not.toHaveBeenCalled();
+        });
+        it('does not release a run when pre-navigation has unknown outcome', async () => {
+            let runId;
+            const unknownOutcome = new Error('navigation result unknown');
+            unknownOutcome.cause = { errorCode: 'COMMAND_LOST' };
+            const mockPage = {
+                closeWindow: vi.fn().mockResolvedValue(undefined),
+                getCurrentUrl: vi.fn().mockResolvedValue('about:blank'),
+                goto: vi.fn().mockImplementation(async () => {
+                    runId = getDaemonRunContext()?.runId;
+                    throw unknownOutcome;
+                }),
+            };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'run-unknown-prenavigation',
+                access: 'write',
+                description: 'test unknown pre-navigation retains the daemon lease',
+                browser: true,
+                strategy: Strategy.COOKIE,
+                domain: 'example.com',
+                siteSession: 'persistent',
+                func: async () => [{ ok: true }],
+            });
+            await expect(executeCommand(cmd, {})).rejects.toThrow('Pre-navigation');
+            expect(runId).toMatch(/^run_/);
+            expect(getDaemonRunContext()).toBeUndefined();
+            expect(mockReleaseSiteSessionLease).not.toHaveBeenCalled();
+        });
+        it('releases after a wrapper timeout when the adapter later succeeds', async () => {
+            const adapter = deferred();
+            let runId;
+            let settledRunId;
+            let adapterSettled = false;
+            const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+            vi.spyOn(runtime, 'runWithTimeout').mockRejectedValueOnce(new TimeoutError('logical run', 1));
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'run-timeout',
+                access: 'write',
+                description: 'test timeout defers local run cleanup',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'persistent',
+                func: async () => {
+                    runId = getDaemonRunContext()?.runId;
+                    await adapter.promise;
+                    settledRunId = getDaemonRunContext()?.runId;
+                    adapterSettled = true;
+                },
+            });
+            await expect(executeCommand(cmd, {})).rejects.toBeInstanceOf(TimeoutError);
+            expect(runId).toMatch(/^run_/);
+            expect(adapterSettled).toBe(false);
+            expect(getDaemonRunContext()).toBeUndefined();
+            expect(mockReleaseSiteSessionLease).not.toHaveBeenCalled();
+            adapter.resolve();
+            await vi.waitFor(() => expect(adapterSettled).toBe(true));
+            expect(settledRunId).toBe(runId);
+            expect(getDaemonRunContext()).toBeUndefined();
+            await vi.waitFor(() => expect(mockReleaseSiteSessionLease).toHaveBeenCalledOnce());
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledWith(runId);
+        });
+        it('releases after a wrapper timeout when the adapter later fails ordinarily', async () => {
+            const adapter = deferred();
+            let runId;
+            const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+            vi.spyOn(runtime, 'runWithTimeout').mockRejectedValueOnce(new TimeoutError('logical run', 1));
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'run-timeout-late-ordinary-failure',
+                access: 'write',
+                description: 'test late ordinary failure releases run ownership',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'persistent',
+                func: async () => {
+                    runId = getDaemonRunContext()?.runId;
+                    await adapter.promise;
+                },
+            });
+            await expect(executeCommand(cmd, {})).rejects.toBeInstanceOf(TimeoutError);
+            expect(runId).toMatch(/^run_/);
+            expect(mockReleaseSiteSessionLease).not.toHaveBeenCalled();
+            adapter.reject(new Error('late ordinary failure'));
+            await vi.waitFor(() => expect(mockReleaseSiteSessionLease).toHaveBeenCalledOnce());
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledWith(runId);
+            expect(getDaemonRunContext()).toBeUndefined();
+        });
+        it('retains ownership for TTL after a wrapper timeout when the adapter later has an unknown outcome', async () => {
+            const adapter = deferred();
+            let runId;
+            let adapterSettled = false;
+            const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+            vi.spyOn(runtime, 'runWithTimeout').mockRejectedValueOnce(new TimeoutError('logical run', 1));
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'run-timeout-late-unknown-failure',
+                access: 'write',
+                description: 'test late unknown failure retains ownership for TTL',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'persistent',
+                func: async () => {
+                    runId = getDaemonRunContext()?.runId;
+                    try {
+                        await adapter.promise;
+                    }
+                    finally {
+                        adapterSettled = true;
+                    }
+                },
+            });
+            await expect(executeCommand(cmd, {})).rejects.toBeInstanceOf(TimeoutError);
+            expect(runId).toMatch(/^run_/);
+            expect(mockReleaseSiteSessionLease).not.toHaveBeenCalled();
+            const unknownOutcome = new Error('late result unknown');
+            unknownOutcome.cause = { code: 'COMMAND_RESULT_UNKNOWN' };
+            adapter.reject(unknownOutcome);
+            await vi.waitFor(() => expect(adapterSettled).toBe(true));
+            expect(getDaemonRunContext()).toBeUndefined();
+            expect(mockReleaseSiteSessionLease).not.toHaveBeenCalled();
+        });
+        it('releases normally when the adapter itself rejects with TimeoutError', async () => {
+            let runId;
+            const adapterTimeout = new TimeoutError('adapter operation', 1);
+            const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'run-adapter-timeout',
+                access: 'write',
+                description: 'test a settled adapter timeout releases normally',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'persistent',
+                func: async () => {
+                    runId = getDaemonRunContext()?.runId;
+                    throw adapterTimeout;
+                },
+            });
+            await expect(executeCommand(cmd, {})).rejects.toBe(adapterTimeout);
+            expect(runId).toMatch(/^run_/);
+            expect(getDaemonRunContext()).toBeUndefined();
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledOnce();
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledWith(runId);
+        });
+        it('does not let deferred timeout cleanup clear a later run', async () => {
+            const firstAdapter = deferred();
+            const secondAdapter = deferred();
+            let firstRunId;
+            let secondRunId;
+            const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+            vi.spyOn(runtime, 'runWithTimeout')
+                .mockRejectedValueOnce(new TimeoutError('first logical run', 1))
+                .mockImplementationOnce(async (promise) => promise);
+            const firstCommand = cli({
+                site: 'test-execution',
+                name: 'run-timeout-first',
+                access: 'write',
+                description: 'test deferred cleanup for an older run',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'persistent',
+                func: () => {
+                    firstRunId = getDaemonRunContext()?.runId;
+                    return firstAdapter.promise;
+                },
+            });
+            const secondCommand = cli({
+                site: 'test-execution',
+                name: 'run-timeout-second',
+                access: 'write',
+                description: 'test a newer run survives old deferred cleanup',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'persistent',
+                func: () => {
+                    secondRunId = getDaemonRunContext()?.runId;
+                    return secondAdapter.promise;
+                },
+            });
+            await expect(executeCommand(firstCommand, {})).rejects.toBeInstanceOf(TimeoutError);
+            const secondExecution = executeCommand(secondCommand, {});
+            await vi.waitFor(() => expect(secondRunId).toMatch(/^run_/));
+            expect(secondRunId).not.toBe(firstRunId);
+            firstAdapter.resolve();
+            await firstAdapter.promise;
+            await vi.waitFor(() => expect(getDaemonRunContext()).toBeUndefined());
+            secondAdapter.resolve();
+            await expect(secondExecution).resolves.toBeUndefined();
+            expect(getDaemonRunContext()).toBeUndefined();
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledTimes(2);
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledWith(firstRunId);
+            expect(mockReleaseSiteSessionLease).toHaveBeenCalledWith(secondRunId);
+        });
+        it('keeps daemon metadata scoped to overlapping timed-out and active runs', async () => {
+            const resumeFirst = deferred();
+            const firstFinished = deferred();
+            const finishSecond = deferred();
+            const secondStarted = deferred();
+            let firstRunId;
+            let secondRunId;
+            const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+            vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+            vi.spyOn(runtime, 'runWithTimeout')
+                .mockRejectedValueOnce(new TimeoutError('first logical run', 1))
+                .mockImplementationOnce(async (promise) => promise);
+            vi.stubGlobal('fetch', vi.fn().mockImplementation(async (_input, init) => {
+                const request = JSON.parse(String(init?.body));
+                return {
+                    status: 200,
+                    json: async () => ({ id: request.id, ok: true, data: 'ok' }),
+                };
+            }));
+            const firstCommand = cli({
+                site: 'test-execution',
+                name: 'run-overlap-first',
+                access: 'write',
+                description: 'test timed-out run keeps its daemon metadata',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'persistent',
+                func: async () => {
+                    firstRunId = getDaemonRunContext()?.runId;
+                    await resumeFirst.promise;
+                    await sendCommand('exec', { code: 'first-after-second' });
+                    firstFinished.resolve();
+                },
+            });
+            const secondCommand = cli({
+                site: 'test-execution',
+                name: 'run-overlap-second',
+                access: 'write',
+                description: 'test active run keeps its daemon metadata',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'persistent',
+                func: async () => {
+                    secondRunId = getDaemonRunContext()?.runId;
+                    await sendCommand('exec', { code: 'second-active' });
+                    secondStarted.resolve();
+                    await finishSecond.promise;
+                },
+            });
+            await expect(executeCommand(firstCommand, {})).rejects.toBeInstanceOf(TimeoutError);
+            const secondExecution = executeCommand(secondCommand, {});
+            await secondStarted.promise;
+            resumeFirst.resolve();
+            await firstFinished.promise;
+            const bodies = vi.mocked(fetch).mock.calls.map(([, init]) => JSON.parse(String(init?.body)));
+            expect(bodies.find(body => body.code === 'first-after-second')?.runId).toBe(firstRunId);
+            expect(bodies.find(body => body.code === 'second-active')?.runId).toBe(secondRunId);
+            expect(firstRunId).not.toBe(secondRunId);
+            finishSecond.resolve();
+            await expect(secondExecution).resolves.toBeUndefined();
+        });
+    });
     it('reuses a persistent site browser session and keeps the tab lease open', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };

package/dist/src/hosted/availability.test.js

@@ -10,6 +10,17 @@ const EXPECTED_LOCAL_TOOLS = [
     'antigravity/state-keys',
     'antigravity/workspaces-list',
     'mercury/reimbursement-plan',
+    'spotify/auth',
+    'spotify/next',
+    'spotify/pause',
+    'spotify/play',
+    'spotify/prev',
+    'spotify/queue',
+    'spotify/repeat',
+    'spotify/search',
+    'spotify/shuffle',
+    'spotify/status',
+    'spotify/volume',
     'trae-solo/extensions-list',
     'trae-solo/recent-workspaces',
     'trae-solo/settings-read',
@@ -174,7 +185,7 @@ describe('hosted availability', () => {
         const desktopApps = (byReason.get('desktop-app') ?? []).sort();
         expect(exceptionDiff(localTools, EXPECTED_LOCAL_TOOLS)).toEqual({ added: [], missing: [] });
         expect(exceptionDiff(desktopApps, EXPECTED_DESKTOP_APPS)).toEqual({ added: [], missing: [] });
-        expect(localTools).toHaveLength(19);
+        expect(localTools).toHaveLength(30);
         expect(desktopApps).toHaveLength(111);
     });
 });

package/dist/src/hosted/client.js

@@ -293,7 +293,7 @@ function isHostedManifestCommand(value) {
     if (!hasOnlyKeys(value, [
         'site', 'name', 'aliases', 'command', 'description', 'access', 'example', 'domain', 'strategy', 'browser',
         'args', 'columns', 'pipeline', 'defaultFormat', 'type', 'modulePath', 'sourceFile', 'navigateBefore',
-        'siteSession', 'defaultWindowMode', 'adapterPackageId', 'adapterPackageName', 'adapterPackageVersion',
+        'siteSession', 'freshPage', 'defaultWindowMode', 'adapterPackageId', 'adapterPackageName', 'adapterPackageVersion',
     ]))
         return false;
     if (typeof value.site !== 'string' || typeof value.name !== 'string' || typeof value.command !== 'string')
@@ -318,6 +318,8 @@ function isHostedManifestCommand(value) {
         if (value[key] !== undefined && typeof value[key] !== 'string')
             return false;
     }
+    if (value.freshPage !== undefined && typeof value.freshPage !== 'boolean')
+        return false;
     return value.navigateBefore === undefined || typeof value.navigateBefore === 'boolean' || typeof value.navigateBefore === 'string';
 }
 function isHostedManifestArg(value) {