browser-pilot-cli 0.3.0-rc.6 → 0.4.0

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import { writeFileSync as writeFileSync2, readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
 import { resolve as resolvePath } from "path";
 
 // src/version.ts
-var BROWSER_PILOT_VERSION = "0.3.0-rc.6";
+var BROWSER_PILOT_VERSION = "0.4.0";
 
 // src/protocol/errors.ts
 var ERROR_CODES = [
@@ -911,7 +911,7 @@ async function discoverBrowserCandidates(options = {}) {
       id: stableBrowserId(definition, os),
       product: definition.product,
       channel: definition.channel,
-      profile: definition.dataDir,
+      userDataRoot: definition.dataDir,
       processState,
       remoteDebuggingState,
       authorizationState,
@@ -923,324 +923,6 @@ async function discoverBrowserCandidates(options = {}) {
   return results;
 }
 
-// src/page-scripts.ts
-var CLICK_TARGET_STATE_FUNCTION = `function() {
-  const target = this;
-  if (!target || target.nodeType !== 1 || !target.isConnected) {
-    return {connected:false, kind:'other', focused:false};
-  }
-  const composedParent = node => {
-    if (node && node.parentElement) return node.parentElement;
-    const root = node && typeof node.getRootNode === 'function' ? node.getRootNode() : null;
-    return root && root.host ? root.host : null;
-  };
-  const composedContains = (container, node) => {
-    for (let current = node; current; current = composedParent(current)) {
-      if (current === container) return true;
-    }
-    return false;
-  };
-  const isShadowHostOf = (node, possibleHost) => {
-    let root = node && typeof node.getRootNode === 'function' ? node.getRootNode() : null;
-    while (root && root.host) {
-      if (root.host === possibleHost) return true;
-      root = typeof root.host.getRootNode === 'function' ? root.host.getRootNode() : null;
-    }
-    return false;
-  };
-  const token = (value, mixed) => {
-    const normalized = String(value || '').trim().toLowerCase();
-    if (normalized === 'true') return true;
-    if (normalized === 'false') return false;
-    return mixed && normalized === 'mixed' ? 'mixed' : undefined;
-  };
-  const tag = String(target.tagName || '').toLowerCase();
-  const role = String(target.getAttribute && target.getAttribute('role') || '').trim().toLowerCase();
-  const inputType = tag === 'input' ? String(target.type || '').toLowerCase() : '';
-  let kind = 'other';
-  if (inputType === 'checkbox' || role === 'checkbox' || role === 'menuitemcheckbox') kind = 'checkbox';
-  else if (inputType === 'radio' || role === 'radio' || role === 'menuitemradio') kind = 'radio';
-  else if (role === 'switch') kind = 'switch';
-  else if (tag === 'option' || role === 'option') kind = 'option';
-  else if (tag === 'select' || role === 'listbox' || role === 'combobox') kind = 'select';
-  else if (
-    tag === 'button' || tag === 'a' || tag === 'input' || tag === 'textarea' ||
-    role === 'button' || role === 'link' || role === 'tab' || role === 'menuitem'
-  ) kind = 'control';
-
-  const state = {connected:true, kind, focused:false};
-  if ((kind === 'checkbox' || kind === 'radio') && tag === 'input') {
-    state.checked = !!target.checked;
-  } else if (kind === 'checkbox' || kind === 'radio' || kind === 'switch') {
-    const checked = token(target.getAttribute('aria-checked'), true);
-    if (checked !== undefined) state.checked = checked;
-  }
-  if (kind === 'option' && tag === 'option') state.selected = !!target.selected;
-  else {
-    const selected = token(target.getAttribute('aria-selected'), false);
-    if (selected !== undefined) state.selected = selected === true;
-  }
-  const pressed = token(target.getAttribute('aria-pressed'), true);
-  if (pressed !== undefined) state.pressed = pressed;
-  const expanded = token(target.getAttribute('aria-expanded'), false);
-  if (expanded !== undefined) state.expanded = expanded === true;
-
-  let active = document.activeElement;
-  for (let depth = 0; depth < 32 && active && active.shadowRoot && active.shadowRoot.activeElement; depth += 1) {
-    active = active.shadowRoot.activeElement;
-  }
-  state.focused = active === target || composedContains(target, active) || isShadowHostOf(target, active);
-  return state;
-}`;
-var GET_POINTER_TARGET_STATE = `function() {
-  const blocked = (reason, obstruction) => ({
-    status: 'blocked',
-    reason,
-    ...(obstruction ? {obstruction} : {}),
-  });
-  const composedParent = node => {
-    if (node && node.parentElement) return node.parentElement;
-    const root = node && typeof node.getRootNode === 'function' ? node.getRootNode() : null;
-    return root && root.host ? root.host : null;
-  };
-  const composedContains = (container, node) => {
-    for (let current = node; current; current = composedParent(current)) {
-      if (current === container) return true;
-    }
-    return false;
-  };
-  const isShadowHostOf = (node, possibleHost) => {
-    let root = node && typeof node.getRootNode === 'function' ? node.getRootNode() : null;
-    while (root && root.host) {
-      if (root.host === possibleHost) return true;
-      root = typeof root.host.getRootNode === 'function' ? root.host.getRootNode() : null;
-    }
-    return false;
-  };
-  const describes = node => {
-    if (!node || typeof node.tagName !== 'string') return undefined;
-    const tagName = node.tagName.toLowerCase().slice(0, 40);
-    const rawRole = typeof node.getAttribute === 'function' ? node.getAttribute('role') : null;
-    const role = typeof rawRole === 'string' ? rawRole.trim().slice(0, 40) : '';
-    return role ? {tagName, role} : {tagName};
-  };
-
-  const target = this;
-  if (!target || target.nodeType !== 1 || !target.isConnected) return blocked('detached');
-  target.scrollIntoView({block:'center', inline:'center', behavior:'instant'});
-  if (!target.isConnected) return blocked('detached');
-
-  const style = getComputedStyle(target);
-  if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse') {
-    return blocked('no_layout');
-  }
-
-  for (let current = target; current; current = composedParent(current)) {
-    const ariaDisabled = typeof current.getAttribute === 'function'
-      ? current.getAttribute('aria-disabled') : null;
-    const nativeDisabled = typeof current.matches === 'function' && current.matches(':disabled');
-    if (nativeDisabled || current.inert === true || String(ariaDisabled).trim().toLowerCase() === 'true') {
-      return blocked('disabled');
-    }
-  }
-
-  const viewportWidth = Math.max(0, window.innerWidth || document.documentElement.clientWidth || 0);
-  const viewportHeight = Math.max(0, window.innerHeight || document.documentElement.clientHeight || 0);
-  const rectList = target.getClientRects();
-  const rects = [];
-  for (let index = 0; index < Math.min(rectList.length, 64); index += 1) {
-    const rect = rectList[index];
-    if (
-      Number.isFinite(rect.left) && Number.isFinite(rect.top) &&
-      Number.isFinite(rect.right) && Number.isFinite(rect.bottom) &&
-      rect.width > 0 && rect.height > 0
-    ) rects.push(rect);
-  }
-  if (rects.length === 0) return blocked('no_layout');
-
-  const visibleRects = rects.map(rect => ({
-    left: Math.max(0, rect.left),
-    top: Math.max(0, rect.top),
-    right: Math.min(viewportWidth, rect.right),
-    bottom: Math.min(viewportHeight, rect.bottom),
-  })).filter(rect => rect.right > rect.left && rect.bottom > rect.top)
-    .sort((a, b) => ((b.right - b.left) * (b.bottom - b.top)) - ((a.right - a.left) * (a.bottom - a.top)))
-    .slice(0, 4);
-  if (visibleRects.length === 0) return blocked('outside_viewport');
-
-  const labels = [];
-  if (target.labels && typeof target.labels.length === 'number') {
-    for (let index = 0; index < Math.min(target.labels.length, 32); index += 1) {
-      labels.push(target.labels[index]);
-    }
-  }
-  for (let current = target; current; current = composedParent(current)) {
-    if (String(current.tagName).toLowerCase() === 'label') labels.push(current);
-  }
-  const accepts = hit => {
-    if (!hit) return false;
-    if (hit === target || composedContains(target, hit) || isShadowHostOf(target, hit)) return true;
-    return labels.some(label => (
-      hit === label || composedContains(label, hit) || isShadowHostOf(label, hit)
-    ));
-  };
-
-  let firstObstruction;
-  for (const rect of visibleRects) {
-    const width = rect.right - rect.left;
-    const height = rect.bottom - rect.top;
-    const points = [
-      [rect.left + width * 0.5, rect.top + height * 0.5],
-      [rect.left + width * 0.25, rect.top + height * 0.25],
-      [rect.left + width * 0.75, rect.top + height * 0.25],
-      [rect.left + width * 0.25, rect.top + height * 0.75],
-      [rect.left + width * 0.75, rect.top + height * 0.75],
-    ];
-    for (const [x, y] of points) {
-      const hit = document.elementsFromPoint(x, y)[0];
-      if (accepts(hit)) {
-        const readClickTargetState = ${CLICK_TARGET_STATE_FUNCTION};
-        return {status:'ready', x, y, targetState:readClickTargetState.call(target)};
-      }
-      if (!firstObstruction && hit) firstObstruction = describes(hit);
-    }
-  }
-  return blocked('obscured', firstObstruction);
-}`;
-var EDITABLE_STATE_FUNCTION = `function(target) {
-  const unsupported = (reason, inputType) => ({
-    kind:'unsupported', value:'', sensitive:false, editable:false,
-    ...(inputType ? {inputType} : {}), reason,
-  });
-  if (!target || target.nodeType !== 1 || !target.isConnected) return unsupported('detached');
-
-  const composedParent = node => {
-    if (node && node.parentElement) return node.parentElement;
-    const root = node && typeof node.getRootNode === 'function' ? node.getRootNode() : null;
-    return root && root.host ? root.host : null;
-  };
-  const hasComposedState = (node, property, attribute) => {
-    for (let current = node; current; current = composedParent(current)) {
-      if (current[property] === true || current.hasAttribute?.(attribute)) return true;
-    }
-    return false;
-  };
-  const ariaTrue = (node, name) => String(node.getAttribute?.(name) || '').trim().toLowerCase() === 'true';
-  const blockedReason = node => {
-    if (hasComposedState(node, 'inert', 'inert')) return 'inert';
-    for (let current = node; current; current = composedParent(current)) {
-      if (current.matches?.(':disabled') || current.disabled === true || ariaTrue(current, 'aria-disabled')) {
-        return 'disabled';
-      }
-    }
-    for (let current = node; current; current = composedParent(current)) {
-      if (current.readOnly === true || ariaTrue(current, 'aria-readonly')) return 'readonly';
-    }
-    return null;
-  };
-  const contenteditableRoot = node => {
-    let root = node;
-    while (root.parentElement && root.parentElement.isContentEditable) root = root.parentElement;
-    return root;
-  };
-
-  if (target instanceof HTMLInputElement) {
-    const inputType = String(target.type || 'text').toLowerCase();
-    const rangeTextTypes = new Set(['text', 'search', 'tel', 'url', 'password']);
-    const selectTextTypes = new Set(['email', 'number']);
-    const valueTypes = new Set(['date', 'time', 'datetime-local', 'month', 'week', 'color', 'range']);
-    const editMode = rangeTextTypes.has(inputType) || selectTextTypes.has(inputType)
-      ? 'text' : valueTypes.has(inputType) ? 'value' : null;
-    if (!editMode) return unsupported('unsupported_input_type', inputType);
-    const reason = blockedReason(target);
-    return {
-      kind:'input', value:String(target.value ?? ''), sensitive:inputType === 'password',
-      editable:!reason, inputType, editMode,
-      ...(editMode === 'text' ? {selectionMode:selectTextTypes.has(inputType) ? 'select' : 'range'} : {}),
-      ...(reason ? {reason} : {}),
-    };
-  }
-  if (target instanceof HTMLTextAreaElement) {
-    const reason = blockedReason(target);
-    return {
-      kind:'input', value:String(target.value ?? ''), sensitive:false,
-      editable:!reason, inputType:'textarea', editMode:'text', selectionMode:'range',
-      ...(reason ? {reason} : {}),
-    };
-  }
-  if (target.isContentEditable) {
-    const root = contenteditableRoot(target);
-    const reason = blockedReason(root);
-    return {
-      kind:'contenteditable', value:String(root.innerText ?? root.textContent ?? ''), sensitive:false,
-      editable:!reason, inputType:'contenteditable', editMode:'text', selectionMode:'range',
-      ...(reason ? {reason} : {}),
-    };
-  }
-  return unsupported('unsupported_element');
-}`;
-var PREPARE_EDITABLE_TARGET = `function(clear) {
-  const readState = ${EDITABLE_STATE_FUNCTION};
-  const state = readState(this);
-  if (!state.editable) return state;
-
-  if (state.kind === 'input') {
-    this.focus();
-    const focusedState = readState(this);
-    if (!focusedState.editable) return focusedState;
-    if (focusedState.editMode === 'text') {
-      if (focusedState.selectionMode === 'range') {
-        const end = String(this.value ?? '').length;
-        this.setSelectionRange(clear ? 0 : end, end, 'none');
-      } else if (clear) {
-        this.select();
-      }
-    }
-    return focusedState;
-  }
-
-  let root = this;
-  while (root.parentElement && root.parentElement.isContentEditable) root = root.parentElement;
-  root.focus();
-  const focusedState = readState(root);
-  if (!focusedState.editable) return focusedState;
-  const range = document.createRange();
-  range.selectNodeContents(root);
-  if (!clear) range.collapse(false);
-  const selection = window.getSelection();
-  if (!selection) return {...focusedState, editable:false, reason:'selection_unavailable'};
-  selection.removeAllRanges();
-  selection.addRange(range);
-  return focusedState;
-}`;
-var SET_VALUE_CONTROL = `function(value) {
-  const readState = ${EDITABLE_STATE_FUNCTION};
-  const state = readState(this);
-  if (!state.editable || state.kind !== 'input' || state.editMode !== 'value') return;
-  this.focus();
-  const beforeInput = new InputEvent('beforeinput', {
-    bubbles:true, composed:true, cancelable:true, inputType:'insertReplacementText', data:value,
-  });
-  if (!this.dispatchEvent(beforeInput)) return;
-  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
-  if (setter) setter.call(this, value); else this.value = value;
-  this.dispatchEvent(new InputEvent('input', {
-    bubbles:true, composed:true, inputType:'insertReplacementText', data:value,
-  }));
-}`;
-var READ_EDITABLE_STATE = `function() {
-  const readState = ${EDITABLE_STATE_FUNCTION};
-  return readState(this);
-}`;
-var READ_ACTIVE_EDITABLE_STATE = `(() => {
-  const readState = ${EDITABLE_STATE_FUNCTION};
-  let active = document.activeElement;
-  while (active && active.shadowRoot && active.shadowRoot.activeElement) {
-    active = active.shadowRoot.activeElement;
-  }
-  return readState(active);
-})()`;
-
 // src/runtime-layout.ts
 import { fileURLToPath } from "url";
 function isSelfContainedRuntime() {
@@ -1459,6 +1141,12 @@ var CAPABILITIES = [
   "cookies.read",
   "developer.eval"
 ];
+var PROFILE_IDENTITY_ERROR_CODES = [
+  "profile_path_unavailable",
+  "profile_path_unverified",
+  "local_state_unavailable",
+  "profile_metadata_missing"
+];
 var OBSERVATION_TRUNCATION_REASONS = [
   "element_limit",
   "text_limit",
@@ -2020,6 +1708,12 @@ var profileRepresentativeTabSchema = objectSchema({
 var profileContextSchema = objectSchema({
   profileContextId: opaqueIdSchema,
   label: stringSchema({ minLength: 1, maxLength: 128 }),
+  identityStatus: stringSchema({ enum: ["unidentified", "verified", "unavailable"] }),
+  profileName: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
+  accountName: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
+  accountEmail: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
+  profileDirectory: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
+  identityErrorCode: stringSchema({ enum: [...PROFILE_IDENTITY_ERROR_CODES] }),
   displayName: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
   tabCount: integerSchema({ minimum: 0 }),
   eligibleTabCount: integerSchema({ minimum: 0 }),
@@ -2048,6 +1742,7 @@ var TOOL_DEFINITIONS = [
         id: opaqueIdSchema,
         product: stringSchema({ minLength: 1, maxLength: 128 }),
         channel: stringSchema({ maxLength: 128 }),
+        userDataRoot: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
         profile: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
         processState: stringSchema({ enum: ["running", "not_running", "unknown"] }),
         remoteDebuggingState: stringSchema({ enum: ["enabled", "disabled", "stale"] }),
@@ -2108,6 +1803,25 @@ var TOOL_DEFINITIONS = [
     sensitivity: { input: [], output: ["browser_data"] },
     artifactKinds: []
   }),
+  tool({
+    name: "browser.profiles.identify",
+    title: "Identify browser Profiles",
+    description: "Explicitly identify live Chrome Profiles using temporary visible chrome://version targets.",
+    context: "workspace",
+    inputSchema: objectSchema({
+      profileContextId: opaqueIdSchema,
+      refresh: booleanSchema()
+    }),
+    outputSchema: resultSchema("workspace", {
+      profiles: arraySchema(profileContextSchema, { maxItems: 128 })
+    }, ["profiles"]),
+    requiredCapabilities: ["browser.control"],
+    mutating: true,
+    idempotency: "non_idempotent",
+    cancellation: "best_effort",
+    sensitivity: { input: [], output: ["browser_data"] },
+    artifactKinds: []
+  }),
   tool({
     name: "browser.profiles.select",
     title: "Select browser Profile",
@@ -2117,6 +1831,12 @@ var TOOL_DEFINITIONS = [
     outputSchema: resultSchema("workspace", {
       profileContextId: opaqueIdSchema,
       label: stringSchema({ minLength: 1, maxLength: 128 }),
+      identityStatus: stringSchema({ enum: ["unidentified", "verified", "unavailable"] }),
+      profileName: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
+      accountName: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
+      accountEmail: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
+      profileDirectory: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
+      identityErrorCode: stringSchema({ enum: [...PROFILE_IDENTITY_ERROR_CODES] }),
       displayName: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data")
     }, ["profileContextId", "label"]),
     requiredCapabilities: ["browser.control"],
@@ -2545,10 +2265,11 @@ var TOOL_DEFINITIONS = [
         title: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
         url: boundedUrl,
         active: booleanSchema(),
+        selected: booleanSchema(),
         origin: stringSchema({ enum: ["managed", "managed_popup", "user_tab"] }),
         managedTabSetId: opaqueIdSchema,
         controlState: stringSchema({ enum: ["available", "controlled", "busy"] })
-      }, ["targetId", "title", "url", "active", "origin", "controlState"]))
+      }, ["targetId", "title", "url", "origin", "controlState"]))
     }, ["targets"]),
     requiredCapabilities: ["browser.control"],
     mutating: false,
@@ -2560,7 +2281,7 @@ var TOOL_DEFINITIONS = [
   tool({
     name: "browser.tabs.switch",
     title: "Switch tab",
-    description: "Set a managed or user tab as the active controlled target for the current Lease.",
+    description: "Select a managed or user tab as the controlled target for the current Lease.",
     context: "workspace",
     inputSchema: objectSchema({ targetId: opaqueIdSchema }, ["targetId"]),
     outputSchema: resultSchema("target"),
@@ -3207,10 +2928,23 @@ async function runStdioBridge(options) {
 }
 
 // src/compatibility-broker-client.ts
-import { randomUUID as randomUUID6 } from "crypto";
+import { createHash as createHash4, randomUUID as randomUUID6 } from "crypto";
 var BRIDGE_SESSION_ID = "bridge:browser-pilot-cli";
 var CLIENT_KEY = "browser-pilot-cli";
 var LEASE_TTL_MS = 5 * 6e4;
+function compatibilityIdentity(clientKey) {
+  if (clientKey === CLIENT_KEY) {
+    return { bridgeSessionId: BRIDGE_SESSION_ID, instanceId: "local:one-shot" };
+  }
+  const digest = createHash4("sha256").update(clientKey).digest("base64url").slice(0, 24);
+  return {
+    bridgeSessionId: `bridge:browser-pilot-cli:${digest}`,
+    instanceId: `local:one-shot:${digest}`
+  };
+}
+function isSelected(target) {
+  return target.selected ?? target.active === true;
+}
 function asRecord(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new BrowserPilotError("internal_error", `${label} returned an invalid result`);
@@ -3226,22 +2960,24 @@ function commandResult(value, method) {
   return asRecord(outcome.result, `${method} result`);
 }
 var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
-  constructor(transport, initialized, workspace, lease) {
+  constructor(transport, bridgeSessionId, initialized, workspace, lease) {
     this.transport = transport;
+    this.bridgeSessionId = bridgeSessionId;
     this.initialized = initialized;
     this.workspace = workspace;
     this.lease = lease;
   }
   commandSequence = 0;
-  static async create(transport, executableVersion) {
-    const initialized = asRecord(await transport.brokerCall(BRIDGE_SESSION_ID, "initialize", {
+  static async create(transport, executableVersion, clientKey = CLIENT_KEY) {
+    const identity = compatibilityIdentity(clientKey);
+    const initialized = asRecord(await transport.brokerCall(identity.bridgeSessionId, "initialize", {
       client: {
         id: "org.browser-pilot.cli",
         name: "Browser Pilot CLI",
         version: executableVersion,
-        instanceId: "local:one-shot"
+        instanceId: identity.instanceId
       },
-      protocol: { min: { major: 1, minor: 1 }, max: { major: 1, minor: 2 } },
+      protocol: { min: { major: 1, minor: 1 }, max: { major: 1, minor: 3 } },
       requestedCapabilities: [...CAPABILITIES],
       launchMode: "one-shot"
     }), "initialize");
@@ -3254,19 +2990,25 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
         }
       });
     }
-    const created = asRecord(await transport.brokerCall(BRIDGE_SESSION_ID, "workspaces/create", {
-      clientKey: CLIENT_KEY
+    const created = asRecord(await transport.brokerCall(identity.bridgeSessionId, "workspaces/create", {
+      clientKey
     }), "workspaces/create");
-    const leased = asRecord(await transport.brokerCall(BRIDGE_SESSION_ID, "leases/create", {
+    const leased = asRecord(await transport.brokerCall(identity.bridgeSessionId, "leases/create", {
       workspaceId: created.workspace.id,
-      clientKey: CLIENT_KEY,
+      clientKey,
       ttlMs: LEASE_TTL_MS
     }), "leases/create");
-    return new _CompatibilityBrokerClient(transport, initialized, created.workspace, leased.lease);
+    return new _CompatibilityBrokerClient(
+      transport,
+      identity.bridgeSessionId,
+      initialized,
+      created.workspace,
+      leased.lease
+    );
   }
   async callTool(name, args = {}, targetId) {
     this.commandSequence += 1;
-    return commandResult(await this.transport.brokerCall(BRIDGE_SESSION_ID, "tools/call", {
+    return commandResult(await this.transport.brokerCall(this.bridgeSessionId, "tools/call", {
       name,
       arguments: args,
       workspaceId: this.workspace.id,
@@ -3304,6 +3046,16 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
     }
     return result.profiles;
   }
+  async identifyProfiles(profileContextId, refresh = false) {
+    const result = await this.callTool("browser.profiles.identify", {
+      ...profileContextId ? { profileContextId } : {},
+      ...refresh ? { refresh: true } : {}
+    });
+    if (!Array.isArray(result.profiles)) {
+      throw new BrowserPilotError("internal_error", "browser.profiles.identify returned invalid Profiles");
+    }
+    return result.profiles;
+  }
   async selectProfile(profileContextId) {
     const result = await this.callTool("browser.profiles.select", { profileContextId });
     const profiles = await this.listProfiles();
@@ -3317,11 +3069,11 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
   }
   async ensureTarget() {
     const targets = await this.listTabs("all");
-    const selected = targets.find((target) => target.active) ?? targets.find((target) => target.origin !== "user_tab");
+    const selected = targets.find(isSelected) ?? targets.find((target) => target.origin !== "user_tab");
     if (selected) {
-      if (!selected.active) {
+      if (!isSelected(selected)) {
         await this.callTool("browser.tabs.switch", { targetId: selected.targetId });
-        selected.active = true;
+        selected.selected = true;
       }
       return selected;
     }
@@ -3329,11 +3081,11 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
   }
   async ensureManagedTarget() {
     const targets = await this.listTabs("managed_only");
-    const selected = targets.find((target) => target.active) ?? targets[0];
+    const selected = targets.find(isSelected) ?? targets[0];
     if (selected) {
-      if (!selected.active) {
+      if (!isSelected(selected)) {
         await this.callTool("browser.tabs.switch", { targetId: selected.targetId });
-        selected.active = true;
+        selected.selected = true;
       }
       return selected;
     }
@@ -3350,7 +3102,7 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
       profileContextId: opened.profileContextId,
       title: String(opened.title ?? ""),
       url: String(opened.url),
-      active: true,
+      selected: true,
       origin: "managed",
       controlState: "controlled"
     };
@@ -3363,7 +3115,7 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
     return result.observationId;
   }
   async importArtifact(path, mimeType) {
-    const result = asRecord(await this.transport.brokerCall(BRIDGE_SESSION_ID, "artifacts/import", {
+    const result = asRecord(await this.transport.brokerCall(this.bridgeSessionId, "artifacts/import", {
       workspaceId: this.workspace.id,
       leaseId: this.lease.id,
       path,
@@ -3372,7 +3124,7 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
     return asRecord(result.artifact, "imported Artifact");
   }
   async exportArtifact(artifactId, path) {
-    await this.transport.brokerCall(BRIDGE_SESSION_ID, "artifacts/export", {
+    await this.transport.brokerCall(this.bridgeSessionId, "artifacts/export", {
       workspaceId: this.workspace.id,
       leaseId: this.lease.id,
       artifactId,
@@ -3381,14 +3133,14 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
     });
   }
   async releaseArtifact(artifactId) {
-    await this.transport.brokerCall(BRIDGE_SESSION_ID, "artifacts/release", {
+    await this.transport.brokerCall(this.bridgeSessionId, "artifacts/release", {
       workspaceId: this.workspace.id,
       leaseId: this.lease.id,
       artifactId
     });
   }
   async releaseWorkspace() {
-    await this.transport.brokerCall(BRIDGE_SESSION_ID, "workspaces/release", {
+    await this.transport.brokerCall(this.bridgeSessionId, "workspaces/release", {
       workspaceId: this.workspace.id
     });
   }
@@ -3427,29 +3179,29 @@ async function validateCompatibilityDaemon(client, executableVersion) {
     });
   }
 }
-async function connectCompatibility(executableVersion, browserFilter) {
+async function connectCompatibility(executableVersion, browserFilter, clientKey = CLIENT_KEY) {
   const daemon = await connectDaemon(browserFilter);
   await validateCompatibilityDaemon(daemon, executableVersion);
-  return CompatibilityBrokerClient.create(daemon, executableVersion);
+  return CompatibilityBrokerClient.create(daemon, executableVersion, clientKey);
 }
-async function resumeCompatibility(executableVersion) {
+async function resumeCompatibility(executableVersion, clientKey = CLIENT_KEY) {
   if (!isDaemonRunning()) return null;
   const daemon = new DaemonClient();
   try {
     await validateCompatibilityDaemon(daemon, executableVersion);
-    return await CompatibilityBrokerClient.create(daemon, executableVersion);
+    return await CompatibilityBrokerClient.create(daemon, executableVersion, clientKey);
   } catch (error) {
     if (error instanceof BrowserPilotError && error.code === "protocol_incompatible") throw error;
     return null;
   }
 }
-async function withCompatibilityTarget(executableVersion, operation) {
-  const client = await resumeCompatibility(executableVersion);
+async function withCompatibilityTarget(executableVersion, operation, clientKey = CLIENT_KEY) {
+  const client = await resumeCompatibility(executableVersion, clientKey);
   if (!client) throw new Error("Not connected");
   const target = await client.ensureTarget();
   return operation(client, target);
 }
-async function shutdownCompatibility(executableVersion) {
+async function shutdownCompatibility(executableVersion, clientKey = CLIENT_KEY) {
   if (!isDaemonRunning()) return;
   const daemon = new DaemonClient();
   await validateDaemon(daemon);
@@ -3481,11 +3233,15 @@ async function shutdownCompatibility(executableVersion) {
     });
   }
   try {
-    const client = await CompatibilityBrokerClient.create(daemon, executableVersion);
+    const client = await CompatibilityBrokerClient.create(daemon, executableVersion, clientKey);
     await client.releaseWorkspace();
   } catch (error) {
     if (!(error instanceof BrowserPilotError) || error.code !== "browser_not_found") throw error;
   }
+  const afterRelease = await daemon.healthInfo();
+  if ((afterRelease.clients?.embeddedConnections ?? 0) > 0 || (afterRelease.clients?.activeLeases ?? 0) > 0) {
+    return;
+  }
   await daemon.shutdown({
     brokerProcessIdentity: health.brokerProcessIdentity,
     executableVersion: requester.version,
@@ -3495,7 +3251,8 @@ async function shutdownCompatibility(executableVersion) {
 
 // src/cli.ts
 var program = new Command();
-program.name("bp").description("Control your browser from the command line").version(BROWSER_PILOT_VERSION).option("--human", "force human-readable output (default when TTY)").addHelpText("after", `
+program.exitOverride();
+program.name("bp").description("Control your browser from the command line").version(BROWSER_PILOT_VERSION).option("--human", "force human-readable output (default when TTY)").option("--client-key <key>", "stable namespace for one-shot Agent state").addHelpText("after", `
 Workflow:
   bp connect                          # one-time setup (click Allow in Chrome)
   bp profiles                         # list live Chrome Profile contexts
@@ -3525,7 +3282,7 @@ Output:
   JSON by default when piped (for LLM/script use).
   Human-readable when run in a terminal (TTY). Force with --human.
   Actions return: {"ok":true, "title":"...", "url":"...", "elements":[...]}
-  Errors return:  {"ok":false, "error":"...", "hint":"..."}
+  Errors return:  {"ok":false, "error":"...", "code":"...", "retryable":false}
 
 Canvas editors (Google Docs, Sheets, Figma):
   bp keyboard "text" --click ".editor"               # click to focus, then type
@@ -3551,19 +3308,28 @@ Eval (escape hatch for operations without a dedicated command):
   echo 'complex js here' | bp eval                   # stdin for complex JS
 `);
 function useJson() {
-  if (program.opts().human) return false;
+  if (process.argv.slice(2).includes("--human") || program.opts().human) return false;
   return !process.stdout.isTTY;
 }
+program.configureOutput({
+  writeErr: (value) => {
+    if (!useJson()) process.stderr.write(value);
+  }
+});
 function emit(data, human) {
   if (useJson()) console.log(JSON.stringify(data));
   else if (human) console.log(human);
 }
 function fail(error, hint, details) {
+  const stable = details ?? new BrowserPilotError("internal_error", error);
   if (useJson()) console.log(JSON.stringify({
     ok: false,
     error,
+    code: stable.code,
+    retryable: stable.retryable,
     ...hint ? { hint } : {},
-    ...details ? details.toData() : {}
+    ...stable.context ? { context: stable.context } : {},
+    ...stable.remediation ? { remediation: stable.remediation } : {}
   }));
   else console.error(`\u2717 ${error}${hint ? `
   hint: ${hint}` : ""}`);
@@ -3617,13 +3383,17 @@ function emitObservation(result) {
 function action(fn) {
   return (...args) => fn(...args).catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);
-    if (err instanceof BrowserPilotError && err.code === "stale_ref") {
-      fail(msg, "Run 'bp snapshot' to refresh element refs.", err);
+    const stable = err instanceof BrowserPilotError ? err : new BrowserPilotError("internal_error", msg, { cause: err });
+    if (stable.code === "stale_ref") {
+      fail(msg, "Run 'bp snapshot' to refresh element refs.", stable);
     }
-    if (msg.includes("not found") && msg.includes("Ref")) fail(msg, "Run 'bp snapshot' to refresh element refs.", err instanceof BrowserPilotError ? err : void 0);
-    if (msg.includes("Not connected")) fail(msg, "Run 'bp connect' first.", err instanceof BrowserPilotError ? err : void 0);
-    if (msg.includes("Page load timeout")) fail(msg, "Page may still be loading. Retry the command after a moment.", err instanceof BrowserPilotError ? err : void 0);
-    fail(msg, void 0, err instanceof BrowserPilotError ? err : void 0);
+    if (stable.code === "browser_disconnected") {
+      fail(msg, "Run 'bp connect' first.", stable);
+    }
+    if (stable.code === "unknown_outcome") {
+      fail(msg, "Inspect the current tab state before deciding whether to retry.", stable);
+    }
+    fail(msg, void 0, stable);
   });
 }
 function normalizeUrl(url) {
@@ -3631,17 +3401,42 @@ function normalizeUrl(url) {
   return `https://${url}`;
 }
 function parseLimit(raw) {
-  const n = parseInt(raw, 10);
-  if (isNaN(n) || n < 1) throw new Error("--limit must be a positive number");
+  const n = Number(raw);
+  if (!/^\d+$/.test(raw) || !Number.isSafeInteger(n) || n < 1) {
+    throw invalidArgument("--limit must be a positive integer", "limit");
+  }
   return n;
 }
 function parseRef(raw) {
   const ref = Number(raw);
-  if (!Number.isSafeInteger(ref) || ref < 1) {
-    throw new Error("Ref must be a positive integer");
+  if (!/^\d+$/.test(raw) || !Number.isSafeInteger(ref) || ref < 1) {
+    throw invalidArgument("Ref must be a positive integer", "ref");
   }
   return ref;
 }
+function parseCoordinates(raw) {
+  const parts = raw.split(",");
+  if (parts.length !== 2 || parts.some((part) => part.trim() === "")) {
+    throw invalidArgument("--xy must be x,y (e.g. --xy 400,300)", "xy");
+  }
+  const [x, y] = parts.map((part) => Number(part.trim()));
+  if (!Number.isFinite(x) || !Number.isFinite(y)) {
+    throw invalidArgument("--xy must be x,y (e.g. --xy 400,300)", "xy");
+  }
+  return { x, y };
+}
+function cliClientKey() {
+  const value = program.opts().clientKey ?? process.env.BROWSER_PILOT_CLIENT_KEY;
+  if (value === void 0) return "browser-pilot-cli";
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{2,127}$/.test(value)) {
+    throw new BrowserPilotError(
+      "invalid_argument",
+      "Client key must be 3-128 characters using letters, digits, dot, underscore, colon, or hyphen",
+      { context: { field: "clientKey" } }
+    );
+  }
+  return value;
+}
 function requireString2(value, label) {
   if (typeof value !== "string") throw new BrowserPilotError("internal_error", `${label} is missing`);
   return value;
@@ -3659,12 +3454,21 @@ async function cliElementAddress(client, target, raw) {
       ref: parseRef(raw)
     };
   }
-  if (!raw.trim()) throw new Error("Element target must not be empty");
+  if (!raw.trim()) throw invalidArgument("Element target must not be empty", "target");
   return { selector: raw };
 }
 async function requireCompatibility() {
-  const client = await resumeCompatibility(BROWSER_PILOT_VERSION);
-  if (!client) throw new Error("Not connected");
+  const client = await resumeCompatibility(BROWSER_PILOT_VERSION, cliClientKey());
+  if (!client) {
+    throw new BrowserPilotError("browser_disconnected", "Browser Pilot is not connected", {
+      retryable: true,
+      remediation: {
+        code: "connect_browser",
+        message: "Run 'bp connect', complete Chrome authorization if prompted, then retry.",
+        actionRequired: true
+      }
+    });
+  }
   return client;
 }
 async function resolveCliProfile(client, selector) {
@@ -3673,11 +3477,11 @@ async function resolveCliProfile(client, selector) {
   if (exactId) return exactId;
   if (/^\d+$/.test(selector)) {
     const index = Number(selector);
-    if (Number.isSafeInteger(index) && profiles[index]) return profiles[index];
-    throw invalidCliProfile(`Profile index out of range (0-${Math.max(0, profiles.length - 1)})`, selector);
+    if (Number.isSafeInteger(index) && index >= 1 && profiles[index - 1]) return profiles[index - 1];
+    throw invalidCliProfile(`Profile index out of range (1-${profiles.length})`, selector);
   }
   const normalized = selector.trim().toLocaleLowerCase();
-  const matches = profiles.filter((profile) => profile.label.toLocaleLowerCase() === normalized || profile.displayName?.toLocaleLowerCase() === normalized);
+  const matches = profiles.filter((profile) => profile.label.toLocaleLowerCase() === normalized || profile.displayName?.toLocaleLowerCase() === normalized || profile.profileName?.toLocaleLowerCase() === normalized || profile.accountName?.toLocaleLowerCase() === normalized || profile.accountEmail?.toLocaleLowerCase() === normalized);
   if (matches.length === 1) return matches[0];
   if (matches.length > 1) {
     throw invalidCliProfile("Profile selector is ambiguous; use its index or Profile context ID", selector);
@@ -3691,10 +3495,16 @@ function invalidCliProfile(message, selector) {
 }
 function cliProfile(profile, index) {
   return {
-    index,
+    index: index + 1,
     profileContextId: profile.profileContextId,
     label: profile.label,
     ...profile.displayName ? { displayName: profile.displayName } : {},
+    ...profile.identityStatus ? { identityStatus: profile.identityStatus } : {},
+    ...profile.profileName ? { profileName: profile.profileName } : {},
+    ...profile.accountName ? { accountName: profile.accountName } : {},
+    ...profile.accountEmail ? { accountEmail: profile.accountEmail } : {},
+    ...profile.profileDirectory ? { profileDirectory: profile.profileDirectory } : {},
+    ...profile.identityErrorCode ? { identityErrorCode: profile.identityErrorCode } : {},
     tabCount: profile.tabCount,
     eligibleTabCount: profile.eligibleTabCount,
     selected: profile.selected,
@@ -3702,7 +3512,7 @@ function cliProfile(profile, index) {
   };
 }
 function withCliTarget(operation) {
-  return withCompatibilityTarget(BROWSER_PILOT_VERSION, operation);
+  return withCompatibilityTarget(BROWSER_PILOT_VERSION, operation, cliClientKey());
 }
 function readStdin() {
   if (process.stdin.isTTY) return Promise.resolve("");
@@ -3716,7 +3526,7 @@ function readStdin() {
 }
 program.command("browsers").description("List supported local browsers and their setup state").option("-b, --browser <name>", "filter by browser ID, product, or channel").action(action(async (opts) => {
   const filter = typeof opts.browser === "string" ? opts.browser.toLowerCase() : void 0;
-  const client = await resumeCompatibility(BROWSER_PILOT_VERSION);
+  const client = await resumeCompatibility(BROWSER_PILOT_VERSION, cliClientKey());
   const browsers = client ? await client.listBrowsers(filter) : (await discoverBrowserCandidates()).map((discovered) => discovered.candidate).filter((candidate) => !filter || [candidate.id, candidate.product, candidate.channel].some((value) => value?.toLowerCase().includes(filter)));
   if (useJson()) {
     console.log(JSON.stringify({ ok: true, browsers }));
@@ -3743,7 +3553,7 @@ program.command("connect").description("Connect to Chrome and prepare unambiguou
     console.log(`If prompted, click "Allow" in Chrome's authorization dialog.
 `);
   }
-  const client = await connectCompatibility(BROWSER_PILOT_VERSION, opts.browser);
+  const client = await connectCompatibility(BROWSER_PILOT_VERSION, opts.browser, cliClientKey());
   await client.connectBrowser();
   const profiles = await client.listProfiles();
   if (profiles.length <= 1) await client.ensureManagedTarget();
@@ -3753,7 +3563,7 @@ program.command("connect").description("Connect to Chrome and prepare unambiguou
     emit(
       { ok: true, browser, profileSelectionRequired: true, profiles: listed },
       `\u2713 Connected to ${browser}
-Multiple Chrome Profiles are open. Run 'bp profiles', then 'bp profile <index>'.`
+Multiple Chrome Profiles are open. Run 'bp profiles --identify', then 'bp profile <index>'.`
     );
     return;
   }
@@ -3785,11 +3595,13 @@ program.command("bridge").description("Run the Agent-neutral JSON-RPC bridge").o
   });
 });
 program.command("disconnect").description("Release CLI browser state and stop an otherwise unused daemon").action(action(async () => {
-  await shutdownCompatibility(BROWSER_PILOT_VERSION);
+  await shutdownCompatibility(BROWSER_PILOT_VERSION, cliClientKey());
   emit({ ok: true }, "\u2713 Disconnected");
 }));
-program.command("profiles").description("List live Chrome Profile contexts").action(action(async () => {
-  const profiles = (await (await requireCompatibility()).listProfiles()).map(cliProfile);
+program.command("profiles").description("List live Chrome Profile contexts").option("--identify", "explicitly identify Profiles using temporary visible Chrome pages").option("--refresh", "repeat Profile identification instead of using cached results").action(action(async (opts) => {
+  const client = await requireCompatibility();
+  const identified = opts.identify || opts.refresh ? await client.identifyProfiles(void 0, opts.refresh === true) : await client.listProfiles();
+  const profiles = identified.map(cliProfile);
   if (useJson()) {
     console.log(JSON.stringify({ ok: true, profiles }));
     return;
@@ -3799,8 +3611,10 @@ program.command("profiles").description("List live Chrome Profile contexts").act
     return;
   }
   for (const profile of profiles) {
-    const name = profile.displayName ? ` (${profile.displayName})` : "";
-    console.log(`${profile.selected ? "*" : " "} ${profile.index}  ${profile.label}${name}  ${profile.tabCount} tab(s)`);
+    const name = profile.profileName ?? profile.displayName;
+    const account = profile.accountEmail ?? profile.accountName;
+    const identity = name ? `  ${name}${account ? ` (${account})` : ""}  [${profile.label}]` : `  ${profile.label}${profile.identityStatus === "unavailable" ? " (identity unavailable)" : ""}`;
+    console.log(`${profile.selected ? "*" : " "} ${profile.index}${identity}  ${profile.tabCount} tab(s)`);
   }
 }));
 program.command("profile <selector>").description("Select a Chrome Profile context for new managed tabs").action(action(async (selector) => {
@@ -3812,15 +3626,21 @@ program.command("profile <selector>").description("Select a Chrome Profile conte
       ok: true,
       profileContextId: selected.profileContextId,
       label: selected.label,
-      ...selected.displayName ? { displayName: selected.displayName } : {}
+      ...selected.displayName ? { displayName: selected.displayName } : {},
+      ...selected.identityStatus ? { identityStatus: selected.identityStatus } : {},
+      ...selected.profileName ? { profileName: selected.profileName } : {},
+      ...selected.accountName ? { accountName: selected.accountName } : {},
+      ...selected.accountEmail ? { accountEmail: selected.accountEmail } : {},
+      ...selected.profileDirectory ? { profileDirectory: selected.profileDirectory } : {},
+      ...selected.identityErrorCode ? { identityErrorCode: selected.identityErrorCode } : {}
     },
-    `\u2713 Selected ${selected.displayName ?? selected.label}`
+    `\u2713 Selected ${selected.profileName ?? selected.displayName ?? selected.label}`
   );
 }));
-program.command("open <url>").description("Navigate to URL and return page snapshot").option("-n, --new", "open in new tab").option("--profile <selector>", "Profile index, ID, label, or verified display name (requires --new)").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", "\nExamples:\n  bp open https://github.com\n  bp open github.com --new\n  bp open https://example.com --new --profile 1\n  bp open https://example.com --limit 20").action(action(async (url, opts) => {
+program.command("open <url>").description("Navigate to URL and return page snapshot").option("-n, --new", "open in new tab").option("--profile <selector>", "Profile index, ID, label, verified name, or email (requires --new)").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", "\nExamples:\n  bp open https://github.com\n  bp open github.com --new\n  bp open https://example.com --new --profile 1\n  bp open https://example.com --limit 20").action(action(async (url, opts) => {
   url = normalizeUrl(url);
   const limit = parseLimit(opts.limit);
-  if (opts.profile && !opts.new) throw new Error("--profile requires --new");
+  if (opts.profile && !opts.new) throw invalidArgument("--profile requires --new", "profile");
   if (opts.new) {
     const client = await requireCompatibility();
     const profile = opts.profile ? await resolveCliProfile(client, String(opts.profile)) : void 0;
@@ -3854,20 +3674,22 @@ Examples:
   bp click --xy 400,300 --double   # double-click at coordinates
   bp click --xy 400,300 --right    # right-click (context menu)
   bp click 3 --right          # right-click element [3]`).action(action(async (ref, opts) => {
-  if (opts.double && opts.right) throw new Error("--double and --right are mutually exclusive");
-  if (!ref && !opts.xy) throw new Error("Provide a ref number or --xy coordinates");
+  if (opts.double && opts.right) {
+    throw invalidArgument("--double and --right are mutually exclusive", "button");
+  }
+  if (!ref && !opts.xy) throw invalidArgument("Provide a ref number or --xy coordinates", "target");
+  if (ref && opts.xy) throw invalidArgument("Provide either a ref number or --xy, not both", "target");
   const limit = parseLimit(opts.limit);
+  const coordinates = opts.xy ? parseCoordinates(opts.xy) : void 0;
+  const parsedRef = ref ? parseRef(ref) : void 0;
   await withCliTarget(async (client, controlledTarget) => {
     let target;
-    if (opts.xy) {
-      const [xStr, yStr] = opts.xy.split(",");
-      const x = parseFloat(xStr), y = parseFloat(yStr);
-      if (isNaN(x) || isNaN(y)) throw new Error("--xy must be x,y (e.g. --xy 400,300)");
-      target = { x, y };
+    if (coordinates) {
+      target = coordinates;
     } else {
       target = {
         observationId: await client.latestObservation(controlledTarget.targetId),
-        ref: parseRef(ref)
+        ref: parsedRef
       };
     }
     const result = await client.callTool("browser.click", {
@@ -3906,10 +3728,11 @@ Examples:
 }));
 program.command("type <ref> <text>").description("Type text into element and return page snapshot").option("-c, --clear", "clear field before typing").option("-s, --submit", "press Enter after typing").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", '\nExamples:\n  bp type 2 "hello world"\n  bp type 5 "query" --submit\n  bp type 3 "new value" --clear').action(action(async (ref, text, opts) => {
   const limit = parseLimit(opts.limit);
+  const parsedRef = parseRef(ref);
   await withCliTarget(async (client, target) => {
     const result = await client.callTool("browser.type", {
       observationId: await client.latestObservation(target.targetId),
-      ref: parseRef(ref),
+      ref: parsedRef,
       text,
       ...opts.clear ? { clear: true } : {},
       ...opts.submit ? { submit: true } : {},
@@ -3934,8 +3757,10 @@ Examples:
   const limit = parseLimit(opts.limit);
   let delay2 = 0;
   if (opts.delay) {
-    delay2 = parseInt(opts.delay, 10);
-    if (isNaN(delay2) || delay2 < 0) throw new Error("--delay must be a non-negative number");
+    delay2 = Number(opts.delay);
+    if (!/^\d+$/.test(opts.delay) || !Number.isSafeInteger(delay2) || delay2 < 0) {
+      throw invalidArgument("--delay must be a non-negative integer", "delay");
+    }
   }
   await withCliTarget(async (client, target) => {
     const result = await client.callTool("browser.keyboard", {
@@ -3982,7 +3807,9 @@ Examples:
   echo 'complex js' | bp eval`).action(action(async (expression) => {
   if (!expression) {
     expression = await readStdin();
-    if (!expression) throw new Error("No expression. Pass as argument or pipe via stdin.");
+    if (!expression) {
+      throw invalidArgument("No expression. Pass as argument or pipe via stdin.", "expression");
+    }
   }
   await withCliTarget(async (client, target) => {
     const result = await client.callTool("browser.eval", {
@@ -4014,8 +3841,10 @@ When to use which command:
   bp snapshot   \u2192 list interactive elements (buttons, links, inputs)
   bp read       \u2192 page text content (search results, articles)
   bp eval       \u2192 custom extraction (structured data, attributes)`).action(action(async (selector, opts) => {
-  const limit = parseInt(opts.limit, 10);
-  if (isNaN(limit) || limit < 1) throw new Error("--limit must be a positive integer");
+  const limit = Number(opts.limit);
+  if (!/^\d+$/.test(opts.limit) || !Number.isSafeInteger(limit) || limit < 1) {
+    throw invalidArgument("--limit must be a positive integer", "limit");
+  }
   await withCliTarget(async (client, target) => {
     let data;
     try {
@@ -4096,15 +3925,25 @@ Examples:
   bp scroll down --selector ".results"
   bp scroll --ref 8 --to end
   bp scroll --to-text "Payment details"`).action(action(async (direction, opts) => {
-  if (opts.selector && opts.ref) throw new Error("--selector and --ref are mutually exclusive");
+  if (opts.selector && opts.ref) {
+    throw invalidArgument("--selector and --ref are mutually exclusive", "target");
+  }
   const modes = [direction !== void 0, opts.to !== void 0, opts.toText !== void 0].filter(Boolean).length;
-  if (modes > 1) throw new Error("Use only one of direction, --to, or --to-text");
+  if (modes > 1) throw invalidArgument("Use only one of direction, --to, or --to-text", "mode");
   const validDirections = /* @__PURE__ */ new Set(["up", "down", "left", "right"]);
-  if (direction !== void 0 && !validDirections.has(direction)) throw new Error("direction must be up, down, left, or right");
-  if (opts.to !== void 0 && !["start", "end"].includes(opts.to)) throw new Error("--to must be start or end");
-  if (!["pixels", "viewport"].includes(opts.unit)) throw new Error("--unit must be pixels or viewport");
+  if (direction !== void 0 && !validDirections.has(direction)) {
+    throw invalidArgument("direction must be up, down, left, or right", "direction");
+  }
+  if (opts.to !== void 0 && !["start", "end"].includes(opts.to)) {
+    throw invalidArgument("--to must be start or end", "to");
+  }
+  if (!["pixels", "viewport"].includes(opts.unit)) {
+    throw invalidArgument("--unit must be pixels or viewport", "unit");
+  }
   const amount = opts.amount === void 0 ? void 0 : Number(opts.amount);
-  if (amount !== void 0 && (!Number.isFinite(amount) || amount <= 0)) throw new Error("--amount must be a positive number");
+  if (amount !== void 0 && (!Number.isFinite(amount) || amount <= 0)) {
+    throw invalidArgument("--amount must be a positive number", "amount");
+  }
   const limit = parseLimit(opts.limit);
   await withCliTarget(async (client, target) => {
     const rawTarget = opts.selector ?? opts.ref;
@@ -4141,7 +3980,9 @@ program.command("dropdown <target>").description("List native or ARIA dropdown o
   });
 }));
 program.command("select <target> <option>").description("Select and verify a dropdown option").option("--by <mode>", "match by label, value, or index", "label").option("--contains", "use case-insensitive substring matching").option("-l, --limit <n>", "max elements in returned snapshot", "50").addHelpText("after", '\nExamples:\n  bp select 4 "United States"\n  bp select 4 us --by value\n  bp select 4 3 --by index').action(action(async (rawTarget, rawOption, opts) => {
-  if (!["label", "value", "index"].includes(opts.by)) throw new Error("--by must be label, value, or index");
+  if (!["label", "value", "index"].includes(opts.by)) {
+    throw invalidArgument("--by must be label, value, or index", "by");
+  }
   const choice = opts.by === "index" ? { by: "index", index: parseRef(rawOption) } : { by: opts.by, [opts.by]: rawOption, exact: opts.contains !== true };
   const limit = parseLimit(opts.limit);
   await withCliTarget(async (client, target) => {
@@ -4155,9 +3996,11 @@ program.command("select <target> <option>").description("Select and verify a dro
 }));
 program.command("upload <filepath>").description('Upload file (auto-finds <input type="file"> on the page)').option("--nth <n>", "which file input to use if multiple exist", "1").addHelpText("after", "\nAuto-detects file inputs on the page. No ref needed.\n\nExamples:\n  bp upload ./photo.jpg\n  bp upload /tmp/resume.pdf\n  bp upload ./doc.pdf --nth 2    # if multiple file inputs").action(action(async (filepath, opts) => {
   const absPath = resolvePath(filepath);
-  if (!existsSync4(absPath)) throw new Error(`File not found: ${absPath}`);
-  const inputIndex = parseInt(opts.nth, 10);
-  if (isNaN(inputIndex) || inputIndex < 1) throw new Error("--nth must be a positive integer");
+  if (!existsSync4(absPath)) throw invalidArgument(`File not found: ${absPath}`, "filepath");
+  const inputIndex = Number(opts.nth);
+  if (!/^\d+$/.test(opts.nth) || !Number.isSafeInteger(inputIndex) || inputIndex < 1) {
+    throw invalidArgument("--nth must be a positive integer", "nth");
+  }
   await withCliTarget(async (client, target) => {
     const artifact = await client.importArtifact(absPath);
     try {
@@ -4175,7 +4018,7 @@ program.command("upload <filepath>").description('Upload file (auto-finds <input
 }));
 program.command("screenshot [filename]").description("Capture screenshot").option("-f, --full", "capture full page").option("--selector <sel>", "capture specific element").option("--annotate [refs]", "draw Observation ref boxes; optionally comma-separated refs").addHelpText("after", '\nExamples:\n  bp screenshot\n  bp screenshot page.png\n  bp screenshot --full\n  bp screenshot --selector ".chart"\n  bp screenshot page.png --annotate\n  bp screenshot page.png --annotate 1,3,8').action(action(async (filename, opts) => {
   if (opts.annotate !== void 0 && (opts.full || opts.selector)) {
-    throw new Error("--annotate cannot be combined with --full or --selector");
+    throw invalidArgument("--annotate cannot be combined with --full or --selector", "annotate");
   }
   await withCliTarget(async (client, target) => {
     let annotations;
@@ -4263,9 +4106,12 @@ program.command("frame [target]").description("List frames, or switch to a frame
         }
       }
     } else {
-      const idx = parseInt(target, 10);
+      const idx = Number(target);
       if (!Number.isSafeInteger(idx) || idx < 0 || idx >= frames.length) {
-        throw new Error(`Frame index out of range (0-${Math.max(0, frames.length - 1)})`);
+        throw invalidArgument(
+          `Frame index out of range (0-${Math.max(0, frames.length - 1)})`,
+          "target"
+        );
       }
       const frame = frames[idx];
       await client.callTool("browser.frames.switch", idx === 0 ? { top: true } : { frameId: requireString2(frame.frameId, "frameId") }, controlledTarget.targetId);
@@ -4283,7 +4129,7 @@ program.command("auth [username] [password]").description("Set or clear HTTP Bas
     emit({ ok: true }, "\u2713 Auth credentials cleared");
     return;
   }
-  if (!password) throw new Error("Usage: bp auth <username> <password>");
+  if (!password) throw invalidArgument("Usage: bp auth <username> <password>", "password");
   await client.callTool("browser.auth.set", { username, password });
   emit({ ok: true }, "\u2713 Auth credentials set (scoped to HTTP 401 challenges)");
 }));
@@ -4302,7 +4148,7 @@ program.command("dialogs").description("List pending JavaScript dialogs").action
 }));
 program.command("dialog <dialogId>").description("Accept or dismiss a pending JavaScript dialog").option("--accept", "accept the dialog").option("--dismiss", "dismiss the dialog").option("--prompt <text>", "text to submit to a prompt dialog").action(action(async (dialogId, opts) => {
   if (Boolean(opts.accept) === Boolean(opts.dismiss)) {
-    throw new Error("Choose exactly one of --accept or --dismiss");
+    throw invalidArgument("Choose exactly one of --accept or --dismiss", "action");
   }
   const client = await requireCompatibility();
   const listed = await client.callTool("browser.dialogs.list");
@@ -4324,9 +4170,10 @@ program.command("dialog <dialogId>").description("Accept or dismiss a pending Ja
 }));
 program.command("tabs").description("List all controllable browser tabs").action(action(async () => {
   const targets = await (await requireCompatibility()).listTabs("all");
-  const tabs = targets.map(({ targetId: _targetId, managedTabSetId: _managedTabSetId, controlState, ...tab }, index) => ({
-    index,
+  const tabs = targets.map(({ targetId: _targetId, managedTabSetId: _managedTabSetId, controlState, active, selected, ...tab }, index) => ({
+    index: index + 1,
     ...tab,
+    selected: selected ?? active === true,
     controlState
   }));
   if (useJson()) {
@@ -4334,20 +4181,20 @@ program.command("tabs").description("List all controllable browser tabs").action
   } else if (tabs.length === 0) {
     console.log("No controllable tabs open.");
   } else {
-    for (const t of tabs) console.log(`${t.active ? "*" : " "} ${t.index}  ${t.url}  ${t.title}`);
+    for (const t of tabs) console.log(`${t.selected ? "*" : " "} ${t.index}  ${t.url}  ${t.title}`);
   }
 }));
-program.command("tab <index>").description("Switch to tab by index").action(action(async (indexStr) => {
+program.command("tab <index>").description("Select a tab by one-based index").action(action(async (indexStr) => {
   const client = await requireCompatibility();
-  const index = parseInt(indexStr, 10);
+  const index = Number(indexStr);
   const targets = await client.listTabs("all");
-  if (!Number.isSafeInteger(index) || index < 0 || index >= targets.length) {
-    throw new Error(`Tab index out of range (0-${Math.max(0, targets.length - 1)})`);
+  if (!Number.isSafeInteger(index) || index < 1 || index > targets.length) {
+    throw invalidArgument(`Tab index out of range (1-${targets.length})`, "index");
   }
-  await client.callTool("browser.tabs.switch", { targetId: targets[index].targetId });
-  emit({ ok: true, index }, `\u2713 Switched to tab ${index}`);
+  await client.callTool("browser.tabs.switch", { targetId: targets[index - 1].targetId });
+  emit({ ok: true, index }, `\u2713 Selected tab ${index}`);
 }));
-program.command("close").description("Close current browser tab").option("-a, --all", "close all tabs in the current Pilot window").action(action(async (opts) => {
+program.command("close").description("Close current browser tab").option("-a, --all", "close all managed tabs in this Agent Workspace").action(action(async (opts) => {
   const client = await requireCompatibility();
   if (opts.all) {
     const managed = await client.listTabs("managed_only");
@@ -4377,7 +4224,7 @@ program.command("close").description("Close current browser tab").option("-a, --
     await client.callTool("browser.tabs.close", {}, target.targetId);
     const remainingTabs = await client.listTabs("all");
     if (remainingTabs.length > 0) {
-      if (!remainingTabs.some((tab) => tab.active)) {
+      if (!remainingTabs.some((tab) => tab.selected ?? tab.active === true)) {
         const fallback = remainingTabs.find((tab) => tab.origin !== "user_tab");
         if (fallback) await client.callTool("browser.tabs.switch", { targetId: fallback.targetId });
       }
@@ -4404,7 +4251,7 @@ function cliNetworkRequest(request) {
 }
 async function findNetworkRequest(client, sequence) {
   if (!Number.isSafeInteger(sequence) || sequence < 1) {
-    throw new Error("Request ID must be a positive integer");
+    throw invalidArgument("Request ID must be a positive integer", "id");
   }
   const listed = await client.callTool("browser.network.requests", {
     after: sequence - 1,
@@ -4428,14 +4275,18 @@ Examples:
   bp net rules                        # list active rules
   bp net remove --all                 # clear rules`).action(action(async (opts) => {
   const client = await requireCompatibility();
-  const limit = opts.limit ? parseInt(opts.limit, 10) : 20;
+  const limit = parseLimit(opts.limit ?? "20");
+  const after = opts.after === void 0 ? void 0 : Number(opts.after);
+  if (after !== void 0 && (!/^\d+$/.test(opts.after) || !Number.isSafeInteger(after))) {
+    throw invalidArgument("--after must be a non-negative integer", "after");
+  }
   const result = await client.callTool("browser.network.requests", {
     limit,
     ...opts.url ? { url: opts.url } : {},
     ...opts.method ? { method: opts.method } : {},
     ...opts.status ? { status: opts.status } : {},
     ...opts.type ? { type: String(opts.type).split(",").map((value) => value.trim()).filter(Boolean) } : {},
-    ...opts.after ? { after: parseInt(opts.after, 10) } : {}
+    ...after !== void 0 ? { after } : {}
   });
   const requests = networkRequests(result).map(cliNetworkRequest);
   if (useJson()) {
@@ -4459,7 +4310,7 @@ Examples:
 }));
 netCmd.command("show <id>").description("Show full request/response details").option("--save <file>", "save response body to file").action(action(async (idStr, opts) => {
   const client = await requireCompatibility();
-  const id = parseInt(idStr, 10);
+  const id = Number(idStr);
   const summary = await findNetworkRequest(client, id);
   const result = await client.callTool("browser.network.request", {
     requestId: requireString2(summary.requestId, "requestId"),
@@ -4468,7 +4319,13 @@ netCmd.command("show <id>").description("Show full request/response details").op
   const request = result.request && typeof result.request === "object" && !Array.isArray(result.request) ? result.request : {};
   const responseBody = typeof result.body === "string" ? result.body : void 0;
   if (opts.save) {
-    if (responseBody === void 0) throw new Error(`Response body for request #${id} is unavailable`);
+    if (responseBody === void 0) {
+      throw new BrowserPilotError(
+        "action_not_verified",
+        `Response body for request #${id} is unavailable`,
+        { context: { sequence: id } }
+      );
+    }
     const outputPath = resolvePath(opts.save);
     const bytes = result.bodyEncoding === "base64" ? Buffer.from(responseBody, "base64") : Buffer.from(responseBody, "utf8");
     writeFileSync2(outputPath, bytes);
@@ -4497,15 +4354,18 @@ netCmd.command("block <pattern>").description("Block requests matching URL patte
   const rule = { id: result.ruleId, type: "block", pattern };
   emit({ ok: true, rule }, `Rule #${rule.id}: blocking "${pattern}"`);
 }));
-netCmd.command("mock <pattern>").description("Mock responses for matching URLs").option("--body <json>", "response body").option("--file <path>", "read body from file").option("--status <code>", "HTTP status", "200").action(action(async (pattern, opts) => {
+netCmd.command("mock <pattern>").description("Mock responses for matching URLs").option("--body <text>", "response body text").option("--file <path>", "read body from file").option("--status <code>", "HTTP status", "200").action(action(async (pattern, opts) => {
   const client = await requireCompatibility();
   let body = opts.body || "";
   if (opts.file) {
     const filePath = resolvePath(opts.file);
-    if (!existsSync4(filePath)) throw new Error(`File not found: ${filePath}`);
+    if (!existsSync4(filePath)) throw invalidArgument(`File not found: ${filePath}`, "file");
     body = readFileSync4(filePath, "utf-8");
   }
-  const status = parseInt(opts.status, 10);
+  const status = Number(opts.status);
+  if (!/^\d+$/.test(opts.status) || !Number.isSafeInteger(status) || status < 100 || status > 599) {
+    throw invalidArgument("--status must be an HTTP status from 100 through 599", "status");
+  }
   const result = await client.callTool("browser.network.rules.add", {
     type: "mock",
     pattern,
@@ -4552,10 +4412,32 @@ netCmd.command("remove [ruleId]").description("Remove interception rule(s)").opt
   } else if (ruleId) {
     await client.callTool("browser.network.rules.remove", { ruleId });
     emit({ ok: true }, `Rule #${ruleId} removed`);
-  } else throw new Error("Specify a rule ID or use --all");
+  } else throw invalidArgument("Specify a rule ID or use --all", "ruleId");
 }));
 netCmd.command("clear").description("Clear captured request log").action(action(async () => {
   await (await requireCompatibility()).callTool("browser.network.clear");
   emit({ ok: true }, "Request log cleared");
 }));
-program.parse();
+async function main() {
+  try {
+    await program.parseAsync();
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      if (error.exitCode === 0) {
+        process.exitCode = 0;
+      } else if (useJson()) {
+        const message = error.message.replace(/^error:\s*/i, "");
+        const stable = new BrowserPilotError("invalid_argument", message, {
+          context: { parserCode: error.code }
+        });
+        fail(message, void 0, stable);
+      } else {
+        process.exitCode = error.exitCode;
+      }
+    } else {
+      const message = error instanceof Error ? error.message : String(error);
+      fail(message, void 0, error instanceof BrowserPilotError ? error : void 0);
+    }
+  }
+}
+void main();