@agentrhq/webcmd 0.3.2 → 0.3.4

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/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) {

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

@@ -103,6 +103,68 @@ describe('HostedClient', () => {
         });
         expect(requests).toEqual([{ url: 'https://api.example.com/v1/manifest', authorization: 'Bearer wcmd_live_test' }]);
     });
+    it('accepts boolean freshPage command metadata', async () => {
+        const client = new HostedClient({
+            apiBaseUrl: 'https://api.example.com',
+            apiKey: 'key',
+            fetchImpl: async () => new Response(JSON.stringify({
+                ok: true,
+                manifest: {
+                    userId: 'user_demo',
+                    metadata: {
+                        contractSchemaVersion: 1,
+                        webcmdPackageVersion: '0.3.0',
+                        generatedAt: 'now',
+                    },
+                    commands: [{
+                            site: 'district',
+                            name: 'checkout',
+                            command: 'district/checkout',
+                            description: 'Checkout',
+                            access: 'write',
+                            strategy: 'UI',
+                            browser: true,
+                            args: [],
+                            columns: [],
+                            freshPage: true,
+                        }],
+                },
+            }), { status: 200 }),
+        });
+        await expect(client.getManifest()).resolves.toMatchObject({
+            commands: [expect.objectContaining({ freshPage: true })],
+        });
+    });
+    it('rejects non-boolean freshPage command metadata', async () => {
+        const client = new HostedClient({
+            apiBaseUrl: 'https://api.example.com',
+            apiKey: 'key',
+            fetchImpl: async () => new Response(JSON.stringify({
+                ok: true,
+                manifest: {
+                    userId: 'user_demo',
+                    metadata: {
+                        contractSchemaVersion: 1,
+                        webcmdPackageVersion: '0.3.0',
+                        generatedAt: 'now',
+                    },
+                    commands: [{
+                            site: 'district',
+                            name: 'checkout',
+                            command: 'district/checkout',
+                            description: 'Checkout',
+                            access: 'write',
+                            strategy: 'UI',
+                            browser: true,
+                            args: [],
+                            columns: [],
+                            freshPage: 'yes',
+                        }],
+                },
+            }), { status: 200 }),
+        });
+        await expect(client.getManifest()).rejects.toMatchObject({ code: 'HOSTED_PROTOCOL' });
+    });
     it('parses hosted profile rows without provider identifiers', async () => {
         const client = new HostedClient({
             apiBaseUrl: 'https://api.example.com',

package/dist/src/hosted/main-lifecycle.test.js

@@ -24,6 +24,18 @@ const command = {
     columns: ['value'],
     defaultFormat: 'plain',
 };
+const authCommand = {
+    site: 'auth',
+    name: 'status',
+    command: 'auth/status',
+    description: 'Show hosted login status',
+    access: 'read',
+    strategy: 'PUBLIC',
+    browser: false,
+    args: [],
+    columns: ['value'],
+    defaultFormat: 'plain',
+};
 afterEach(async () => {
     await Promise.all(servers.splice(0).map(server => new Promise((resolve, reject) => {
         server.close(error => error ? reject(error) : resolve());
@@ -77,6 +89,44 @@ describe('hosted CLI process lifecycle', () => {
         expect(result.stdout).toContain('Local-only commands:');
         await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
     }, 20_000);
+    it('runs skills add locally without contacting Cloud when hosted mode is configured', async () => {
+        const fixture = await createHostedFixture('success');
+        const installDir = path.join(fixture.root, 'agent-skills');
+        const result = await runCli(['skills', 'add', '--path', installDir, '--json'], fixture.env);
+        expect(result.status).toBe(0);
+        expect(result.stderr).toBe('');
+        const body = JSON.parse(result.stdout);
+        expect(body.skills.map(skill => skill.name)).toEqual([
+            'smart-search',
+            'webcmd-adapter-author',
+            'webcmd-autofix',
+            'webcmd-browser',
+            'webcmd-browser-sitemap',
+            'webcmd-sitemap-author',
+            'webcmd-usage',
+        ]);
+        expect(body.skills.every(skill => skill.destination?.startsWith(installDir))).toBe(true);
+        await expect(readFile(path.join(installDir, 'webcmd-usage', 'SKILL.md'), 'utf8'))
+            .resolves.toContain('webcmd-usage');
+        await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+        expect(fixture.requests).toEqual([]);
+    }, 20_000);
+    it('keeps hosted auth on Cloud without local discovery', async () => {
+        const fixture = await createHostedFixture('success');
+        const result = await runCli(['auth', 'status', '-f', 'plain'], fixture.env);
+        expect(result.stderr).toBe('');
+        expect(result.status).toBe(0);
+        expect(fixture.requests).toEqual(['GET /v1/manifest', 'POST /v1/execute']);
+        await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+    }, 20_000);
+    it('rejects daemon commands in hosted mode without local discovery', async () => {
+        const fixture = await createHostedFixture('success');
+        const result = await runCli(['daemon', 'status'], fixture.env);
+        expect(result.status).toBe(78);
+        expect(result.stderr).toContain('Hosted mode has no local daemon.');
+        expect(fixture.requests).toEqual([]);
+        await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+    }, 20_000);
 });
 async function createHostedFixture(outcome) {
     const root = await mkdtemp(path.join(tmpdir(), 'webcmd-hosted-lifecycle-'));
@@ -84,6 +134,7 @@ async function createHostedFixture(outcome) {
     const configDir = path.join(root, 'config');
     const userClis = path.join(root, '.webcmd', 'clis', 'lifecycle-sentinel');
     const discoverySentinel = path.join(root, 'local-discovery-ran');
+    const requests = [];
     await mkdir(configDir, { recursive: true });
     await mkdir(userClis, { recursive: true });
     await writeFile(path.join(userClis, 'sentinel.js'), [
@@ -92,7 +143,8 @@ async function createHostedFixture(outcome) {
         "export const sentinel = 'cli(';",
         '',
     ].join('\n'));
-    const server = createServer((request, response) => {
+    const server = createServer(async (request, response) => {
+        requests.push(`${request.method ?? 'GET'} ${request.url ?? '/'}`);
         if (request.url === '/v1/manifest') {
             sendChunkedJson(response, {
                 ok: true,
@@ -103,12 +155,16 @@ async function createHostedFixture(outcome) {
                         webcmdPackageVersion: '0.3.0',
                         generatedAt: '2026-07-14T00:00:00.000Z',
                     },
-                    commands: [command],
+                    commands: [command, authCommand],
                 },
             });
             return;
         }
         if (request.url === '/v1/execute' && request.method === 'POST') {
+            let requestBody = '';
+            for await (const chunk of request)
+                requestBody += chunk;
+            const invocation = JSON.parse(requestBody);
             if (outcome === 'failure') {
                 sendChunkedJson(response, {
                     ok: false,
@@ -118,7 +174,7 @@ async function createHostedFixture(outcome) {
                         help: 'Retry the lifecycle fixture.',
                         exitCode: 69,
                     },
-                    execution: { id: 'exec_lifecycle', command: command.command, status: 'failed' },
+                    execution: { id: 'exec_lifecycle', command: invocation.command, status: 'failed' },
                 }, 422);
                 return;
             }
@@ -126,8 +182,10 @@ async function createHostedFixture(outcome) {
                 ok: true,
                 result: { value: largeOutput },
                 columns: ['value'],
-                execution: { id: 'exec_lifecycle', command: command.command, status: 'succeeded' },
-                trace: { executionId: 'exec_lifecycle', receipt: traceReceipt },
+                execution: { id: 'exec_lifecycle', command: invocation.command, status: 'succeeded' },
+                ...(invocation.trace === 'on'
+                    ? { trace: { executionId: 'exec_lifecycle', receipt: traceReceipt } }
+                    : {}),
             });
             return;
         }
@@ -156,10 +214,13 @@ async function createHostedFixture(outcome) {
         updatedAt: '2026-07-14T00:00:00.000Z',
     })}\n`, { mode: 0o600 });
     return {
+        root,
         discoverySentinel,
+        requests,
         env: {
             ...process.env,
             HOME: root,
+            USERPROFILE: root,
             WEBCMD_CONFIG_DIR: configDir,
             WEBCMD_NO_UPDATE_CHECK: '1',
         },