@agentrhq/webcmd 0.3.1 → 0.3.3

package/README.md

@@ -8,6 +8,9 @@
   <a href="https://www.npmjs.com/package/@agentrhq/webcmd">
     <img alt="NPM downloads" src="https://img.shields.io/npm/dt/@agentrhq/webcmd.svg?style=for-the-badge&color=1E88E5&labelColor=000000">
   </a>
+  <a href="https://docs.webcmd.dev">
+    <img alt="Documentation" src="https://img.shields.io/badge/docs-webcmd.dev-1E88E5.svg?style=for-the-badge&labelColor=000000">
+  </a>
   <a href="https://github.com/agentrhq/webcmd/blob/main/LICENSE">
     <img alt="License" src="https://img.shields.io/badge/license-Apache%202.0-1E88E5.svg?style=for-the-badge&labelColor=000000">
   </a>
@@ -25,6 +28,8 @@
 
 WebCMD learns the navigational context of websites as agents use them, then compiles that knowledge into deterministic commands for faster, cheaper, more reliable browser automation. The goal is simple: stop making agents rediscover the same sites on every run and cut browser-agent token spend by up to 90%.
 
+📖 **Full documentation: [docs.webcmd.dev](https://docs.webcmd.dev)**
+
 On top of live browser control, WebCMD adds 3 layers of learnings. Each layer collapses cost and variance for the layer above it.
 
 | Layer | Scenario | What Webcmd Helps With |
@@ -123,15 +128,17 @@ Agents usually want `-f json`; humans usually want table (default) or yaml.
 
 Webcmd is designed to be driven by coding agents such as Codex, Claude Code, Cursor, and similar tools.
 
-## Install skills (also refreshes existing installs)
+## Add skills (also refreshes existing links)
 
-Install Webcmd skills into your agent environment:
+Add Webcmd skills to your agent environment:
 
 ```bash
-webcmd skills install
+webcmd skills add
 ```
 
-The installer asks whether to install globally or locally, then asks for the coding agent (`agents`, `codex`, `claude`) or a custom skills path. For scripts, pass flags such as `--scope project --provider codex` or `--path ./my-skills`.
+The command asks whether to add globally or locally, then asks for the coding agent (`agents`, `codex`, `claude`) or a custom skills path. For scripts, pass flags such as `--scope project --provider codex` or `--path ./my-skills`.
+
+Remove Webcmd skill symlinks from all supported global and current-project locations with `webcmd skills remove`. Pass `--path ./my-skills` to include a custom directory.
 
 ### Which skill to use
 
@@ -312,8 +319,8 @@ Common paths:
 | `~/.webcmd/clis/` | Private adapters. |
 | `~/.webcmd/cache/browser-network/` | Cached browser network captures. |
 | `~/.webcmd/external-clis.yaml` | User external CLI registry entries. |
-| `~/.agents/skills/` | Common global skills install target for agent skill managers. |
-| `.agents/skills/` | Common workspace-local skills install target. |
+| `~/.agents/skills/` | Common global skills directory for agent skill managers. |
+| `.agents/skills/` | Common workspace-local skills directory. |
 
 ## Troubleshooting
 

package/cli-manifest.json

@@ -21317,7 +21317,7 @@
     "name": "auth",
     "description": "Authenticate with Spotify (OAuth — run once)",
     "access": "write",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [],
     "columns": [
@@ -21332,7 +21332,7 @@
     "name": "next",
     "description": "Skip to next track",
     "access": "write",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [],
     "columns": [
@@ -21347,7 +21347,7 @@
     "name": "pause",
     "description": "Pause playback",
     "access": "write",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [],
     "columns": [
@@ -21362,7 +21362,7 @@
     "name": "play",
     "description": "Resume playback or search and play a track/artist",
     "access": "write",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [
       {
@@ -21388,7 +21388,7 @@
     "name": "prev",
     "description": "Skip to previous track",
     "access": "write",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [],
     "columns": [
@@ -21403,7 +21403,7 @@
     "name": "queue",
     "description": "Add a track to the playback queue",
     "access": "write",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [
       {
@@ -21428,7 +21428,7 @@
     "name": "repeat",
     "description": "Set repeat mode (off / track / context)",
     "access": "write",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [
       {
@@ -21457,7 +21457,7 @@
     "name": "search",
     "description": "Search for tracks",
     "access": "read",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [
       {
@@ -21490,7 +21490,7 @@
     "name": "shuffle",
     "description": "Toggle shuffle on/off",
     "access": "write",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [
       {
@@ -21518,7 +21518,7 @@
     "name": "status",
     "description": "Show current playback status",
     "access": "read",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [],
     "columns": [
@@ -21537,7 +21537,7 @@
     "name": "volume",
     "description": "Set playback volume (0-100)",
     "access": "write",
-    "strategy": "public",
+    "strategy": "local",
     "browser": false,
     "args": [
       {

package/clis/producthunt/browse.js

@@ -6,7 +6,7 @@
  */
 import { cli, Strategy } from '@agentrhq/webcmd/registry';
 import { CliError } from '@agentrhq/webcmd/errors';
-import { PRODUCTHUNT_CATEGORY_SLUGS } from './utils.js';
+import { assertProductHuntAccessible, PRODUCTHUNT_CATEGORY_SLUGS } from './utils.js';
 cli({
     site: 'producthunt',
     name: 'browse',
@@ -30,7 +30,14 @@ cli({
         const slug = String(args.category || '').trim().toLowerCase();
         await page.installInterceptor('producthunt.com');
         await page.goto(`https://www.producthunt.com/categories/${slug}`);
-        await page.waitForCapture(5);
+        try {
+            await page.waitForCapture(5);
+        }
+        catch (error) {
+            await assertProductHuntAccessible(page);
+            throw error;
+        }
+        await assertProductHuntAccessible(page);
         const domItems = await page.evaluate(`
       (() => {
         const seen = new Set();

package/clis/producthunt/browser-commands.test.js

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { getRegistry } from '@agentrhq/webcmd/registry';
+import './hot.js';
+import './browse.js';
+
+function pageMock({ evaluations, captureError } = {}) {
+    const queue = [...(evaluations ?? [])];
+    return {
+        goto: async () => undefined,
+        wait: async () => undefined,
+        installInterceptor: async () => undefined,
+        waitForCapture: async () => {
+            if (captureError) throw captureError;
+        },
+        evaluate: async () => queue.shift(),
+    };
+}
+
+const challenge = {
+    title: 'Just a moment...',
+    body: 'Performing security verification before proceeding',
+    cloudflare: true,
+};
+const accessible = {
+    title: 'Product Hunt',
+    body: 'Discover your next favorite thing',
+    cloudflare: false,
+};
+
+describe('Product Hunt browser commands', () => {
+    it.each([
+        ['producthunt/hot', {}],
+        ['producthunt/browse', { category: 'developer-tools' }],
+    ])('%s reports verification pages as SITE_BLOCKED', async (name, args) => {
+        const command = getRegistry().get(name);
+
+        await expect(command.func(pageMock({ evaluations: [challenge] }), args)).rejects.toMatchObject({
+            code: 'SITE_BLOCKED',
+            exitCode: 69,
+        });
+    });
+
+    it('reports a challenge when category capture fails on the verification page', async () => {
+        const command = getRegistry().get('producthunt/browse');
+        const captureError = new Error('No network capture within 5s');
+
+        await expect(command.func(pageMock({ evaluations: [challenge], captureError }), {
+            category: 'developer-tools',
+        })).rejects.toMatchObject({
+            code: 'SITE_BLOCKED',
+            exitCode: 69,
+        });
+    });
+
+    it.each([
+        ['producthunt/hot', {}, 'Could not retrieve Product Hunt top posts'],
+        ['producthunt/browse', { category: 'developer-tools' }, 'No products found for category'],
+    ])('%s preserves NO_DATA for an accessible empty page', async (name, args, message) => {
+        const command = getRegistry().get(name);
+
+        await expect(command.func(pageMock({ evaluations: [accessible, []] }), args)).rejects.toMatchObject({
+            code: 'NO_DATA',
+            message: expect.stringContaining(message),
+        });
+    });
+});

package/clis/producthunt/hot.js

@@ -5,7 +5,7 @@
  */
 import { cli, Strategy } from '@agentrhq/webcmd/registry';
 import { CliError } from '@agentrhq/webcmd/errors';
-import { pickVoteCount } from './utils.js';
+import { assertProductHuntAccessible, pickVoteCount } from './utils.js';
 cli({
     site: 'producthunt',
     name: 'hot',
@@ -19,9 +19,9 @@ cli({
     columns: ['rank', 'name', 'votes', 'url'],
     func: async (page, args) => {
         const count = Math.min(Number(args.limit) || 20, 50);
-        await page.installInterceptor('producthunt.com');
         await page.goto('https://www.producthunt.com');
-        await page.waitForCapture(5);
+        await page.wait(2);
+        await assertProductHuntAccessible(page);
         const domItems = await page.evaluate(`
       (() => {
         const seen = new Set();

package/clis/producthunt/utils.js

@@ -1,6 +1,8 @@
 /**
  * Product Hunt shared helpers.
  */
+import { CliError, EXIT_CODES } from '@agentrhq/webcmd/errors';
+
 export const PRODUCTHUNT_CATEGORY_SLUGS = [
     'ai-agents',
     'ai-coding-agents',
@@ -19,6 +21,31 @@ export const PRODUCTHUNT_CATEGORY_SLUGS = [
     'engineering-development',
 ];
 const UA = 'Mozilla/5.0 (compatible; webcmd/1.0)';
+
+export function isProductHuntVerificationPage(value) {
+    const title = String(value?.title ?? '');
+    const body = String(value?.body ?? '');
+    return value?.cloudflare === true
+        || /just a moment|security verification/i.test(title)
+        || /performing security verification|verify you are human|enable javascript and cookies/i.test(body);
+}
+
+export async function assertProductHuntAccessible(page) {
+    const state = await page.evaluate(`(() => ({
+      title: document.title || '',
+      body: (document.body?.innerText || '').slice(0, 2000),
+      cloudflare: !!document.querySelector('[id^="cf-"], [class*="cf-challenge"]')
+    }))()`);
+    if (!isProductHuntVerificationPage(state))
+        return;
+    throw new CliError(
+        'SITE_BLOCKED',
+        'Product Hunt served a security verification page',
+        'Complete permitted verification in the active browser when available, then retry. Webcmd will not bypass site verification.',
+        EXIT_CODES.SERVICE_UNAVAIL,
+    );
+}
+
 /**
  * Fetch Product Hunt Atom RSS feed.
  * @param category  Optional category slug (e.g. "ai", "developer-tools")

package/clis/producthunt/utils.test.js

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { parseFeed, pickVoteCount, PRODUCTHUNT_CATEGORY_SLUGS } from './utils.js';
+import * as productHuntUtils from './utils.js';
 const SAMPLE_ATOM = `<?xml version="1.0" encoding="UTF-8"?>
 <feed xmlns="http://www.w3.org/2005/Atom">
   <title>Product Hunt</title>
@@ -61,4 +62,11 @@ describe('parseFeed', () => {
         expect(PRODUCTHUNT_CATEGORY_SLUGS).toContain('developer-tools');
         expect(PRODUCTHUNT_CATEGORY_SLUGS).toContain('ai-agents');
     });
+    it('recognizes explicit Product Hunt verification signals', () => {
+        expect(productHuntUtils.isProductHuntVerificationPage).toBeTypeOf('function');
+        expect(productHuntUtils.isProductHuntVerificationPage({ title: 'Just a moment...', body: '', cloudflare: false })).toBe(true);
+        expect(productHuntUtils.isProductHuntVerificationPage({ title: 'Product Hunt', body: 'Performing security verification', cloudflare: false })).toBe(true);
+        expect(productHuntUtils.isProductHuntVerificationPage({ title: 'Product Hunt', body: '', cloudflare: true })).toBe(true);
+        expect(productHuntUtils.isProductHuntVerificationPage({ title: 'Product Hunt', body: 'Discover your next favorite thing', cloudflare: false })).toBe(false);
+    });
 });

package/clis/spotify/spotify.js

@@ -108,7 +108,7 @@ cli({
     name: 'auth',
     access: 'write',
     description: 'Authenticate with Spotify (OAuth — run once)',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [],
     columns: ['status'],
@@ -175,7 +175,7 @@ cli({
     name: 'status',
     access: 'read',
     description: 'Show current playback status',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [],
     columns: ['track', 'artist', 'album', 'status', 'progress'],
@@ -197,7 +197,7 @@ cli({
     name: 'play',
     access: 'write',
     description: 'Resume playback or search and play a track/artist',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [{ name: 'query', type: 'str', default: '', positional: true, help: 'Track or artist to play (optional)' }],
     columns: ['track', 'artist', 'status'],
@@ -216,7 +216,7 @@ cli({
     name: 'pause',
     access: 'write',
     description: 'Pause playback',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [],
     columns: ['status'],
@@ -227,7 +227,7 @@ cli({
     name: 'next',
     access: 'write',
     description: 'Skip to next track',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [],
     columns: ['status'],
@@ -238,7 +238,7 @@ cli({
     name: 'prev',
     access: 'write',
     description: 'Skip to previous track',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [],
     columns: ['status'],
@@ -249,7 +249,7 @@ cli({
     name: 'volume',
     access: 'write',
     description: 'Set playback volume (0-100)',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [{ name: 'level', type: 'int', default: 50, positional: true, required: true, help: 'Volume 0–100' }],
     columns: ['volume'],
@@ -266,7 +266,7 @@ cli({
     name: 'search',
     access: 'read',
     description: 'Search for tracks',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [
         { name: 'query', type: 'str', required: true, positional: true, help: 'Search query' },
@@ -287,7 +287,7 @@ cli({
     name: 'queue',
     access: 'write',
     description: 'Add a track to the playback queue',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [{ name: 'query', type: 'str', required: true, positional: true, help: 'Track to add to queue' }],
     columns: ['track', 'artist', 'status'],
@@ -302,7 +302,7 @@ cli({
     name: 'shuffle',
     access: 'write',
     description: 'Toggle shuffle on/off',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [{ name: 'state', type: 'str', default: 'on', positional: true, choices: ['on', 'off'], help: 'on or off' }],
     columns: ['shuffle'],
@@ -316,7 +316,7 @@ cli({
     name: 'repeat',
     access: 'write',
     description: 'Set repeat mode (off / track / context)',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [{ name: 'mode', type: 'str', default: 'context', positional: true, choices: ['off', 'track', 'context'], help: 'off / track / context' }],
     columns: ['repeat'],

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

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

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

@@ -4,8 +4,9 @@
  * Provides a typed send() function that posts a Command and returns a Result.
  */
 import { sleep } from '../utils.js';
-import { BrowserConnectError } from '../errors.js';
+import { BrowserConnectError, SessionBusyError } from '../errors.js';
 import { COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT } from '../daemon-utils.js';
+import { getDaemonRunContext } from '../session-lease.js';
 import { classifyBrowserError } from './errors.js';
 import { profileRouteParams, resolveProfileSelection } from './profile.js';
 import { DEFAULT_BROWSER_CONNECT_TIMEOUT } from './config.js';
@@ -112,6 +113,7 @@ async function sendCommandRaw(action, params) {
             throw new BrowserCommandError('Browser command deadline exhausted across transport retries.', COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT);
         }
         const remainingMs = Math.max(1000, deadlineAt - Date.now());
+        const run = action === 'lease-release' ? undefined : getDaemonRunContext();
         const command = {
             id,
             action,
@@ -121,6 +123,12 @@ async function sendCommandRaw(action, params) {
             ...(contextId && { contextId }),
             ...(preferredContextId && { preferredContextId }),
             ...(windowMode && { windowMode }),
+            ...(run && {
+                runId: run.runId,
+                command: run.command,
+                access: run.access,
+                pid: process.pid,
+            }),
         };
         try {
             const res = await requestDaemon('/command', {
@@ -132,6 +140,9 @@ async function sendCommandRaw(action, params) {
             const result = (await res.json());
             if (result.ok)
                 return result;
+            if (res.status === 409 && result.code === 'session_busy' && result.holder) {
+                throw new SessionBusyError(result.holder);
+            }
             if (result.errorCode && UNKNOWN_OUTCOME_CODES.has(result.errorCode)) {
                 throw new BrowserCommandError(result.error ?? 'Browser command result is unknown', result.errorCode, result.errorHint);
             }
@@ -187,6 +198,19 @@ export async function sendCommandFull(action, params = {}) {
     const result = await sendCommandRaw(action, params);
     return { data: result.data, page: result.page };
 }
+export async function releaseSiteSessionLease(runId) {
+    const command = {
+        id: generateId(),
+        action: 'lease-release',
+        runId,
+    };
+    await requestDaemon('/command', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(command),
+        timeout: 2_000,
+    }).catch(() => undefined);
+}
 export async function bindTab(session, opts = {}) {
     return sendCommand('bind', { session, surface: 'browser', ...opts });
 }

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

@@ -1,11 +1,15 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, sendCommand, setDaemonCommandTimeoutSeconds, } from './daemon-client.js';
+import { fetchDaemonStatus, getDaemonHealth, releaseSiteSessionLease, requestDaemonShutdown, sendCommand, setDaemonCommandTimeoutSeconds, } from './daemon-client.js';
 import * as daemonLifecycle from './daemon-lifecycle.js';
+import { clearDaemonRunContext, getDaemonRunContext, setDaemonRunContext } from '../session-lease.js';
 describe('daemon-client', () => {
     beforeEach(() => {
         vi.stubGlobal('fetch', vi.fn());
     });
     afterEach(() => {
+        const run = getDaemonRunContext();
+        if (run)
+            clearDaemonRunContext(run.runId);
         if (typeof setDaemonCommandTimeoutSeconds === 'function') {
             setDaemonCommandTimeoutSeconds(null);
         }
@@ -142,6 +146,25 @@ describe('daemon-client', () => {
         expect(ids[1]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
         expect(ids[0]).not.toBe(ids[1]);
     });
+    it('sendCommand binds the active logical run metadata to each daemon operation', async () => {
+        setDaemonRunContext({
+            runId: 'run_4242_1000_1',
+            command: 'example write',
+            access: 'write',
+        });
+        vi.mocked(fetch).mockResolvedValue({
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+        });
+        await sendCommand('exec', { code: '1' });
+        const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
+        expect(body).toMatchObject({
+            runId: 'run_4242_1000_1',
+            command: 'example write',
+            access: 'write',
+            pid: process.pid,
+        });
+    });
     it('sendCommand forwards WEBCMD_PROFILE as a hard contextId requirement', async () => {
         vi.stubEnv('WEBCMD_PROFILE', 'work');
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
@@ -200,6 +223,68 @@ describe('daemon-client', () => {
         });
         expect(fetchMock).toHaveBeenCalledTimes(1);
     });
+    it('maps daemon session_busy conflicts to SessionBusyError without retrying', async () => {
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValueOnce({
+            ok: false,
+            status: 409,
+            json: () => Promise.resolve({
+                ok: false,
+                code: 'session_busy',
+                holder: {
+                    command: 'other write',
+                    pid: 4242,
+                    acquiredAt: 1_000,
+                    heartbeatAt: 2_000,
+                },
+            }),
+        });
+        await expect(sendCommand('exec', { code: '1' })).rejects.toMatchObject({
+            name: 'SessionBusyError',
+            code: 'SESSION_BUSY',
+            message: expect.stringContaining('other write'),
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+    it('releaseSiteSessionLease makes one best-effort POST without starting or retrying the daemon', async () => {
+        setDaemonRunContext({
+            runId: 'run_9999_newer_2',
+            command: 'newer write',
+            access: 'write',
+        });
+        const ensureSpy = vi.spyOn(daemonLifecycle, 'ensureBrowserBridgeReady');
+        vi.mocked(fetch).mockRejectedValueOnce(new TypeError('fetch failed'));
+        await expect(releaseSiteSessionLease('run_4242_1000_1')).resolves.toBeUndefined();
+        expect(fetch).toHaveBeenCalledTimes(1);
+        expect(ensureSpy).not.toHaveBeenCalled();
+        const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
+        expect(body).toMatchObject({
+            action: 'lease-release',
+            runId: 'run_4242_1000_1',
+        });
+    });
+    it('releaseSiteSessionLease aborts its best-effort POST after two seconds', async () => {
+        vi.useFakeTimers();
+        try {
+            let aborted = false;
+            vi.mocked(fetch).mockImplementationOnce((_url, init) => new Promise((_, reject) => {
+                init?.signal?.addEventListener('abort', () => {
+                    aborted = true;
+                    reject(Object.assign(new Error('This operation was aborted'), { name: 'AbortError' }));
+                });
+            }));
+            const pending = releaseSiteSessionLease('run_4242_1000_1');
+            await vi.advanceTimersByTimeAsync(1_999);
+            expect(aborted).toBe(false);
+            await vi.advanceTimersByTimeAsync(1);
+            expect(aborted).toBe(true);
+            await expect(pending).resolves.toBeUndefined();
+            expect(fetch).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
     it('sendCommand does not retry command_result_unknown even when the message looks transient', async () => {
         const fetchMock = vi.mocked(fetch);
         fetchMock.mockResolvedValue({

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

@@ -1,3 +1,4 @@
+import type { SessionLeaseStatus } from '../session-lease.js';
 export interface DaemonStatus {
     ok: boolean;
     pid: number;
@@ -12,6 +13,7 @@ export interface DaemonStatus {
     profiles?: BrowserProfileStatus[];
     pending: number;
     commandResultUnknown?: number;
+    sessionLeases?: SessionLeaseStatus[];
     memoryMB: number;
     port: number;
 }

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

@@ -1,4 +1,5 @@
-export type BrowserRuntimeAction = 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'wait-download' | 'cdp' | 'frames';
+import type { SessionLeaseStatus } from '../session-lease.js';
+export type BrowserRuntimeAction = 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'wait-download' | 'cdp' | 'frames' | 'lease-release';
 export type BrowserSurface = 'browser' | 'adapter';
 export type SiteSessionMode = 'ephemeral' | 'persistent';
 export type BrowserWindowMode = 'foreground' | 'background';
@@ -38,6 +39,14 @@ export interface BrowserRuntimeCommand {
     contextId?: string;
     preferredContextId?: string;
     profileId?: string;
+    /** Stable identity for the complete logical CLI command run. */
+    runId?: string;
+    /** Human-readable canonical command that owns the logical run. */
+    command?: string;
+    /** Access classification used by daemon-local lease arbitration. */
+    access?: 'read' | 'write';
+    /** Originating CLI process, used only for actionable local busy guidance. */
+    pid?: number;
 }
 export interface BrowserRuntimeResult {
     id: string;
@@ -65,4 +74,6 @@ export interface BrowserRuntimeStatus {
     profiles: BrowserRuntimeProfileStatus[];
     pending: number;
     commandResultUnknown?: number;
+    /** Active local leases with internal run ownership tokens removed. */
+    sessionLeases?: SessionLeaseStatus[];
 }

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

@@ -1,3 +1,4 @@
 import type { BrowserRuntimeCommand, BrowserRuntimeResult } from '../../protocol.js';
 import type { CloakSessionManager } from './session-manager.js';
+export declare function resolveCloakCommandProfileId(manager: CloakSessionManager, command: BrowserRuntimeCommand): string;
 export declare function dispatchCloakAction(manager: CloakSessionManager, command: BrowserRuntimeCommand): Promise<BrowserRuntimeResult>;