@agentrhq/webcmd 0.3.2 → 0.3.4

package/README.md

@@ -8,11 +8,14 @@
   <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-7C3AED.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>
   <a href="https://discord.gg/9YP2C9tvMp">
-    <img alt="Join the community on Discord" src="https://img.shields.io/badge/Join%20the%20community-7C3AED.svg?style=for-the-badge&logo=discord&logoColor=white&labelColor=000000&logoWidth=20">
+    <img alt="Join the community on Discord" src="https://img.shields.io/badge/Join%20the%20community-5865F2.svg?style=for-the-badge&logo=discord&logoColor=white&labelColor=000000&logoWidth=20">
   </a>
   <a href="https://x.com/agentrhq">
     <img alt="Follow AgentR on X" src="https://img.shields.io/badge/Built%20by%20%40agentrhq-000000.svg?style=for-the-badge&logo=x&logoColor=white&labelColor=000000&logoWidth=20">
@@ -123,15 +126,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 +317,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/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',
@@ -21,6 +21,7 @@ cli({
         const count = Math.min(Number(args.limit) || 20, 50);
         await page.goto('https://www.producthunt.com');
         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/dist/src/browser/ax-snapshot.js

@@ -71,7 +71,7 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
     const rawNodes = Array.isArray(axTree?.nodes)
         ? axTree.nodes
         : [];
-    const nodes = rawNodes.filter((node) => node && !node.ignored);
+    const nodes = rawNodes.filter((node) => node);
     const byId = new Map();
     const parentIds = new Set();
     for (const node of nodes) {
@@ -88,11 +88,21 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
     });
     const root = roots[0] ?? nodes[0];
     const maxDepth = Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200));
+    const maxTraversalHops = 200;
     const roleNameCounts = countRoleNames(nodes);
     const roleNameSeen = new Map();
-    function render(node, depth) {
-        if (!node || depth > maxDepth)
+    function render(node, depth, hops, path) {
+        if (!node || depth > maxDepth || hops > maxTraversalHops || path.has(node))
             return false;
+        const nextPath = new Set(path).add(node);
+        if (node.ignored) {
+            let hasVisibleChild = false;
+            for (const childId of node.childIds ?? []) {
+                if (render(byId.get(childId), depth, hops + 1, nextPath))
+                    hasVisibleChild = true;
+            }
+            return hasVisibleChild;
+        }
         const role = axString(node.role) || 'generic';
         const name = cleanText(axString(node.name));
         const value = cleanText(axString(node.value) || propertyValue(node, 'value'));
@@ -109,7 +119,7 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
         const childStart = lines.length;
         let hasVisibleChild = false;
         for (const childId of node.childIds ?? []) {
-            if (render(byId.get(childId), depth + 1))
+            if (render(byId.get(childId), depth + 1, hops + 1, nextPath))
                 hasVisibleChild = true;
         }
         if (!shouldShowSelf && !hasVisibleChild) {
@@ -151,7 +161,7 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
         }
         return true;
     }
-    render(root, opts.baseDepth);
+    render(root, opts.baseDepth, 0, new Set());
     return nextRef;
 }
 export function findAxRefReplacement(axTree, ref) {

package/dist/src/browser/ax-snapshot.test.js

@@ -1,6 +1,12 @@
+import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 import { buildAxSnapshot, buildAxSnapshotFromTrees, findAxRefReplacement } from './ax-snapshot.js';
 describe('AX snapshot prototype', () => {
+    it('publishes the AX snapshot builder as a package subpath', () => {
+        const packageJson = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        expect(packageJson.exports?.['./browser/ax-snapshot'])
+            .toBe('./dist/src/browser/ax-snapshot.js');
+    });
     it('builds compact refs from Accessibility.getFullAXTree output', () => {
         const result = buildAxSnapshot({
             nodes: [
@@ -25,6 +31,49 @@ describe('AX snapshot prototype', () => {
             name: 'Category',
         });
     });
+    it('keeps actionable descendants of ignored AX nodes', () => {
+        const result = buildAxSnapshot({
+            nodes: [
+                { nodeId: '1', role: { value: 'RootWebArea' }, childIds: ['2'] },
+                { nodeId: '2', ignored: true, childIds: ['3', '4'] },
+                { nodeId: '3', role: { value: 'button' }, name: { value: 'First' }, backendDOMNodeId: 30 },
+                { nodeId: '4', role: { value: 'button' }, name: { value: 'Second' }, backendDOMNodeId: 40 },
+            ],
+        });
+        expect(result.text).toContain('  [1]button "First"\n  [2]button "Second"');
+        expect(result.text).not.toContain('ignored');
+        expect([...result.refs.values()]).toEqual([
+            { ref: '1', backendNodeId: 30, role: 'button', name: 'First' },
+            { ref: '2', backendNodeId: 40, role: 'button', name: 'Second' },
+        ]);
+    });
+    it('stops ignored-node cycles without changing promoted indentation', () => {
+        const result = buildAxSnapshot({
+            nodes: [
+                { nodeId: '1', role: { value: 'RootWebArea' }, childIds: ['2'] },
+                { nodeId: '2', ignored: true, childIds: ['2', '3'] },
+                { nodeId: '3', role: { value: 'button' }, name: { value: 'Save' }, backendDOMNodeId: 30 },
+            ],
+        });
+        expect(result.text).toContain('\n  [1]button "Save"\n');
+        expect(result.refs).toHaveLength(1);
+    });
+    it('bounds traversal through long ignored-node chains', () => {
+        const ignored = Array.from({ length: 201 }, (_, index) => ({
+            nodeId: String(index + 2),
+            ignored: true,
+            childIds: [String(index + 3)],
+        }));
+        const result = buildAxSnapshot({
+            nodes: [
+                { nodeId: '1', role: { value: 'RootWebArea' }, childIds: ['2'] },
+                ...ignored,
+                { nodeId: '203', role: { value: 'button' }, name: { value: 'Too deep' }, backendDOMNodeId: 203 },
+            ],
+        });
+        expect(result.text).not.toContain('Too deep');
+        expect(result.refs).toHaveLength(0);
+    });
     it('tracks nth only for duplicate role/name pairs', () => {
         const result = buildAxSnapshot({
             nodes: [

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>;

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

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

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

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