opensteer 0.9.5 → 0.9.6

package/dist/cli/bin.cjs

@@ -2598,10 +2598,8 @@ var init_cdp_dom_snapshot = __esm({
 });
 
 // ../browser-core/src/cdp-visual-stability.ts
-var DEFAULT_VISUAL_STABILITY_SETTLE_MS;
 var init_cdp_visual_stability = __esm({
   "../browser-core/src/cdp-visual-stability.ts"() {
-    DEFAULT_VISUAL_STABILITY_SETTLE_MS = 750;
   }
 });
 
@@ -10413,7 +10411,8 @@ function normalizeOpensteerEngineName(value, source = "engine") {
   if (normalized === "playwright" || normalized === "abp") {
     return normalized;
   }
-  throw new Error(
+  throw new OpensteerProtocolError(
+    "invalid-argument",
     `${source} must be one of ${OPENSTEER_ENGINE_NAMES.join(", ")}; received "${value}".`
   );
 }
@@ -10422,7 +10421,8 @@ function assertSupportedEngineOptions(input) {
     return;
   }
   if (typeof input.browser === "object" && input.browser !== null && input.browser.mode === "attach") {
-    throw new Error(
+    throw new OpensteerProtocolError(
+      "invalid-argument",
       'ABP engine does not support browser.mode="attach". Use the Playwright engine for attach flows.'
     );
   }
@@ -10430,7 +10430,8 @@ function assertSupportedEngineOptions(input) {
   if (unsupportedContextOptionNames.length === 0) {
     return;
   }
-  throw new Error(
+  throw new OpensteerProtocolError(
+    "invalid-argument",
     `ABP engine does not support ${unsupportedContextOptionNames.join(", ")}. Supported ABP context options: context.viewport.`
   );
 }
@@ -10488,6 +10489,7 @@ function stripWindowSizeArgs(args) {
 var OPENSTEER_ENGINE_NAMES, DEFAULT_OPENSTEER_ENGINE;
 var init_engine_selection = __esm({
   "../runtime-core/src/internal/engine-selection.ts"() {
+    init_src2();
     OPENSTEER_ENGINE_NAMES = ["playwright", "abp"];
     DEFAULT_OPENSTEER_ENGINE = "playwright";
   }
@@ -11472,7 +11474,8 @@ function assertProviderSupportsEngine(provider, engine) {
     return;
   }
   if (provider === "cloud") {
-    throw new Error(
+    throw new OpensteerProtocolError(
+      "invalid-argument",
       "ABP is not supported for provider=cloud. Cloud provider currently requires Playwright."
     );
   }
@@ -11482,7 +11485,8 @@ function normalizeOpensteerProviderMode(value, source = "OPENSTEER_PROVIDER") {
   if (normalized === OPENSTEER_PROVIDER_MODES[0] || normalized === OPENSTEER_PROVIDER_MODES[1]) {
     return normalized;
   }
-  throw new Error(
+  throw new OpensteerProtocolError(
+    "invalid-argument",
     `${source} must be one of ${OPENSTEER_PROVIDER_MODES.join(", ")}; received "${value}".`
   );
 }
@@ -11507,6 +11511,7 @@ function resolveOpensteerProvider(input = {}) {
 var OPENSTEER_PROVIDER_MODES;
 var init_config = __esm({
   "src/provider/config.ts"() {
+    init_src2();
     OPENSTEER_PROVIDER_MODES = ["local", "cloud"];
   }
 });
@@ -11968,12 +11973,60 @@ function wrapCloudFetchError(error, input) {
   wrapped.name = error.name;
   return wrapped;
 }
-var CLOUD_CLOSE_TIMEOUT_MS, CLOUD_CLOSE_POLL_INTERVAL_MS, OpensteerCloudClient;
+async function createCloudRequestError(response, input) {
+  const payload = await readCloudErrorPayload(response);
+  return new OpensteerCloudRequestError({
+    statusCode: response.status,
+    method: input.method,
+    pathname: input.pathname,
+    url: input.url,
+    message: payload?.error ?? `${input.method} ${input.pathname} failed with ${String(response.status)}.`,
+    ...payload?.code === void 0 ? {} : { code: payload.code },
+    ...payload?.details === void 0 ? {} : { details: payload.details }
+  });
+}
+async function readCloudErrorPayload(response) {
+  try {
+    return asCloudErrorPayload(await response.json());
+  } catch {
+    return void 0;
+  }
+}
+function asCloudErrorPayload(value) {
+  if (value === null || typeof value !== "object") {
+    return void 0;
+  }
+  const payload = value;
+  return {
+    ...typeof payload.error === "string" ? { error: payload.error } : {},
+    ...typeof payload.code === "string" ? { code: payload.code } : {},
+    ..."details" in payload ? { details: payload.details } : {}
+  };
+}
+var CLOUD_CLOSE_TIMEOUT_MS, CLOUD_CLOSE_POLL_INTERVAL_MS, OpensteerCloudRequestError, OpensteerCloudClient;
 var init_client = __esm({
   "src/cloud/client.ts"() {
     init_profile_sync();
     CLOUD_CLOSE_TIMEOUT_MS = 6e4;
     CLOUD_CLOSE_POLL_INTERVAL_MS = 250;
+    OpensteerCloudRequestError = class extends Error {
+      statusCode;
+      code;
+      details;
+      method;
+      pathname;
+      url;
+      constructor(args) {
+        super(args.message);
+        this.name = "OpensteerCloudRequestError";
+        this.statusCode = args.statusCode;
+        this.code = args.code;
+        this.details = args.details;
+        this.method = args.method;
+        this.pathname = args.pathname;
+        this.url = args.url;
+      }
+    };
     OpensteerCloudClient = class {
       constructor(config) {
         this.config = config;
@@ -12149,7 +12202,11 @@ var init_client = __esm({
           });
         }
         if (!response.ok) {
-          throw new Error(`${init.method} ${pathname} failed with ${String(response.status)}.`);
+          throw await createCloudRequestError(response, {
+            method: init.method,
+            pathname,
+            url
+          });
         }
         return response;
       }
@@ -12220,7 +12277,7 @@ var init_package = __esm({
   "../runtime-core/package.json"() {
     package_default2 = {
       name: "@opensteer/runtime-core",
-      version: "0.2.4",
+      version: "0.2.5",
       description: "Shared semantic runtime for Opensteer local and cloud execution.",
       license: "MIT",
       type: "module",
@@ -12372,7 +12429,7 @@ var init_errors3 = __esm({
 function defaultPolicy() {
   return DEFAULT_POLICY;
 }
-var DEFAULT_TIMEOUTS, DEFAULT_SETTLE_DELAYS, defaultSnapshotSettleObserver, DOM_ACTION_VISUAL_STABILITY_PROFILES, DEFAULT_DOM_ACTION_VISUAL_STABILITY_PROFILE, NAVIGATION_VISUAL_STABILITY_PROFILE, NAVIGATION_POST_LOAD_CAPTURE_WINDOW_MS, defaultDomActionSettleObserver, defaultNavigationSettleObserver, DEFAULT_SETTLE_OBSERVERS, defaultTimeoutPolicy, defaultSettlePolicy, defaultRetryPolicy, defaultFallbackPolicy, DEFAULT_POLICY;
+var DEFAULT_TIMEOUTS, DEFAULT_SETTLE_DELAYS, DOM_ACTION_VISUAL_STABILITY_PROFILES, DEFAULT_DOM_ACTION_VISUAL_STABILITY_PROFILE, NAVIGATION_VISUAL_STABILITY_PROFILE, NAVIGATION_POST_LOAD_CAPTURE_WINDOW_MS, defaultDomActionSettleObserver, defaultNavigationSettleObserver, DEFAULT_SETTLE_OBSERVERS, defaultTimeoutPolicy, defaultSettlePolicy, defaultRetryPolicy, defaultFallbackPolicy, DEFAULT_POLICY;
 var init_defaults = __esm({
   "../runtime-core/src/policy/defaults.ts"() {
     init_src();
@@ -12401,21 +12458,6 @@ var init_defaults = __esm({
       "dom-action": 100,
       snapshot: 0
     };
-    defaultSnapshotSettleObserver = {
-      async settle(input) {
-        if (input.trigger !== "snapshot") {
-          return false;
-        }
-        await input.engine.waitForVisualStability({
-          pageRef: input.pageRef,
-          ...input.remainingMs === void 0 ? {} : { timeoutMs: input.remainingMs },
-          settleMs: DEFAULT_VISUAL_STABILITY_SETTLE_MS,
-          scope: "visible-frames"
-        });
-        return true;
-      }
-    };
-    Object.freeze(defaultSnapshotSettleObserver);
     DOM_ACTION_VISUAL_STABILITY_PROFILES = {
       "dom.click": { settleMs: 750, scope: "visible-frames", timeoutMs: 7e3 },
       "dom.input": { settleMs: 750, scope: "visible-frames", timeoutMs: 7e3 },
@@ -12494,7 +12536,6 @@ var init_defaults = __esm({
     };
     Object.freeze(defaultNavigationSettleObserver);
     DEFAULT_SETTLE_OBSERVERS = Object.freeze([
-      defaultSnapshotSettleObserver,
       defaultDomActionSettleObserver,
       defaultNavigationSettleObserver
     ]);
@@ -12982,6 +13023,9 @@ function buildClauseSelector(node, clause) {
   if (!clause || typeof clause !== "object") {
     return "";
   }
+  if (clause.kind === "text") {
+    return "";
+  }
   if (clause.kind === "position") {
     if (clause.axis === "nthOfType") {
       return `:nth-of-type(${Math.max(1, Number(node.position?.nthOfType || 1))})`;
@@ -13097,7 +13141,7 @@ function resolveExtractedValueInContext(normalizedValue, options) {
 function stripPositionClauses(nodes) {
   return (nodes || []).map((node) => ({
     ...node,
-    match: (node.match || []).filter((clause) => clause.kind !== "position")
+    match: (node.match || []).filter((clause) => clause.kind !== "position" && clause.kind !== "text")
   }));
 }
 function dedupeSelectors(selectors) {
@@ -13685,9 +13729,17 @@ function resolveDomPathInScope(index, domPath, scope) {
   if (!candidates.length) {
     return null;
   }
+  const lastNode = domPath[domPath.length - 1];
+  const textClauses = lastNode?.match.filter((c) => c.kind === "text") ?? [];
   let fallback = null;
   for (const selector of candidates) {
-    const matches = querySelectorAllInScope(index, selector, scope);
+    let matches = querySelectorAllInScope(index, selector, scope);
+    if (textClauses.length > 0 && matches.length > 1) {
+      const filtered = matches.filter((node) => matchesTextClauses(node, textClauses));
+      if (filtered.length > 0) {
+        matches = filtered;
+      }
+    }
     if (matches.length === 1) {
       return {
         node: matches[0],
@@ -13707,6 +13759,10 @@ function resolveDomPathInScope(index, domPath, scope) {
   }
   return fallback;
 }
+function matchesTextClauses(node, clauses) {
+  const text = (node.textContent ?? "").replace(/\s+/g, " ").trim();
+  return clauses.every((clause) => text.includes(clause.value));
+}
 function queryAllDomPathInScope(index, domPath, scope) {
   const selectors = buildPathCandidates(domPath);
   for (const selector of selectors) {
@@ -13865,7 +13921,13 @@ function clonePathNode(node) {
   };
 }
 function cloneMatchClause(clause) {
-  return clause.kind === "position" ? { kind: "position", axis: clause.axis } : {
+  if (clause.kind === "position") {
+    return { kind: "position", axis: clause.axis };
+  }
+  if (clause.kind === "text") {
+    return { kind: "text", value: clause.value };
+  }
+  return {
     kind: "attr",
     key: clause.key,
     ...clause.op === void 0 ? {} : { op: clause.op },
@@ -13920,6 +13982,13 @@ function normalizeMatch(rawMatch, attrs, position, tag) {
           op,
           ...value === void 0 ? {} : { value }
         });
+        continue;
+      }
+      if (record.kind === "text") {
+        const textValue = typeof record.value === "string" ? record.value.trim() : "";
+        if (textValue) {
+          push({ kind: "text", value: textValue.slice(0, 80) });
+        }
       }
     }
   }
@@ -14334,7 +14403,7 @@ var init_executor = __esm({
     init_action_boundary2();
     init_policy();
     init_bridge();
-    MAX_DOM_ACTION_ATTEMPTS = 3;
+    MAX_DOM_ACTION_ATTEMPTS = 2;
     DEFAULT_SCROLL_OPTIONS = {
       block: "center",
       inline: "center"
@@ -14821,11 +14890,12 @@ var init_executor = __esm({
         throw this.createActionabilityError(
           operation,
           "obscured",
-          `hit test resolved ${hit.nodeRef} outside the target subtree rooted at ${resolved.nodeRef}`,
+          `target is obscured by ${assessment.blockingDescription ?? "another element"} at the click point`,
           {
             ...details,
             hitRelation: assessment.relation,
             ...assessment.ambiguous === void 0 ? {} : { hitAmbiguous: assessment.ambiguous },
+            ...assessment.blockingDescription === void 0 ? {} : { blockingDescription: assessment.blockingDescription },
             ...assessment.canonicalTarget === void 0 ? {} : {
               canonicalNodeRef: assessment.canonicalTarget.nodeRef,
               canonicalDocumentRef: assessment.canonicalTarget.documentRef,
@@ -14839,8 +14909,7 @@ var init_executor = __esm({
             hitMissingFromSnapshot: !resolved.snapshot.nodes.some(
               (node) => node.nodeRef === hit.nodeRef
             )
-          },
-          true
+          }
         );
       }
       async resolveActionablePointerTarget(session, operation, resolved) {
@@ -15031,7 +15100,12 @@ var init_runtime = __esm({
         });
       }
       async buildPath(input) {
-        return sanitizeReplayElementPath(await this.requireBridge().buildReplayPath(input.locator));
+        return sanitizeReplayElementPath(
+          await this.requireBridge().buildReplayPath(
+            input.locator,
+            input.enableTextMatch ? { enableTextMatch: true } : void 0
+          )
+        );
       }
       async resolveTarget(input) {
         return this.withSnapshotSession((session) => this.resolveTargetWithSession(session, input));
@@ -15251,7 +15325,7 @@ var init_runtime = __esm({
         if (resolvedByLocator) {
           const { snapshot, node } = resolvedByLocator;
           const anchor = await this.buildAnchorFromSnapshotNode(session, snapshot, node);
-          const replayPath = await this.tryBuildPathFromNode(snapshot, node);
+          const replayPath = await this.tryBuildPathFromNode(snapshot, node, { enableTextMatch: true });
           return this.createResolvedTarget("live", snapshot, node, anchor, {
             ...target.persist === void 0 ? {} : { persist: target.persist },
             ...replayPath === void 0 ? {} : { replayPath }
@@ -15269,11 +15343,12 @@ var init_runtime = __esm({
         const { snapshot, node } = resolved;
         const anchor = await this.buildAnchorFromSnapshotNode(session, snapshot, node);
         const writeDescriptor = descriptorWriter ?? ((input) => this.descriptors.write(input));
-        const replayPath = await this.tryBuildPathFromNode(snapshot, node);
+        const enableTextMatch = method !== "extract";
+        const replayPath = await this.tryBuildPathFromNode(snapshot, node, { enableTextMatch });
         const descriptor = target.persist === void 0 ? void 0 : await writeDescriptor({
           method,
           persist: target.persist,
-          path: replayPath ?? await this.buildPathForNode(snapshot, node),
+          path: replayPath ?? await this.buildPathForNode(snapshot, node, { enableTextMatch }),
           sourceUrl: snapshot.url
         });
         return this.createResolvedTarget("selector", snapshot, node, anchor, {
@@ -15373,7 +15448,7 @@ var init_runtime = __esm({
             `Unable to resolve structural anchor "${buildPathSelectorHint(anchor)}" in the current session`
           );
         }
-        const replayPath = await this.tryBuildPathFromNode(context.snapshot, target.node);
+        const replayPath = await this.tryBuildPathFromNode(context.snapshot, target.node, { enableTextMatch: true });
         return this.createResolvedTarget(source, context.snapshot, target.node, anchor, {
           ...persist === void 0 ? {} : { persist },
           ...replayPath === void 0 ? {} : { replayPath }
@@ -15544,19 +15619,20 @@ var init_runtime = __esm({
         }
         return this.bridge;
       }
-      async buildPathForNode(snapshot, node) {
+      async buildPathForNode(snapshot, node, options) {
         if (node.nodeRef === void 0) {
           throw new Error(
             `snapshot node ${String(node.snapshotNodeId)} does not expose a live node reference`
           );
         }
         return this.buildPath({
-          locator: createNodeLocator(snapshot.documentRef, snapshot.documentEpoch, node.nodeRef)
+          locator: createNodeLocator(snapshot.documentRef, snapshot.documentEpoch, node.nodeRef),
+          ...options?.enableTextMatch ? { enableTextMatch: true } : {}
         });
       }
-      async tryBuildPathFromNode(snapshot, node) {
+      async tryBuildPathFromNode(snapshot, node, options) {
         try {
-          return await this.buildPathForNode(snapshot, node);
+          return await this.buildPathForNode(snapshot, node, options);
         } catch {
           return void 0;
         }
@@ -17126,6 +17202,9 @@ function relaxPathForSingleSample(path24, mode) {
         }
         return !isLast;
       }
+      if (clause.kind === "text") {
+        return false;
+      }
       const key = String(clause.key || "").trim().toLowerCase();
       if (!key || !shouldKeepAttrForSingleSample(key)) {
         return false;
@@ -17228,9 +17307,11 @@ function buildNodeStructure(node) {
     }
     structuralAttrs[key] = value;
   }
-  const matchClauses = (node.match || []).map(
-    (clause) => clause.kind === "position" ? `position:${clause.axis}` : `attr:${String(clause.key || "").trim().toLowerCase()}`
-  ).sort();
+  const matchClauses = (node.match || []).map((clause) => {
+    if (clause.kind === "position") return `position:${clause.axis}`;
+    if (clause.kind === "text") return `text:${clause.value}`;
+    return `attr:${String(clause.key || "").trim().toLowerCase()}`;
+  }).sort();
   return {
     tag,
     attrs: structuralAttrs,
@@ -17636,6 +17717,9 @@ function mergeMatchByMajority(matchLists, attrs, threshold, positionFlags = {
       });
       continue;
     }
+    if (clause.kind === "text") {
+      continue;
+    }
     if (clause.axis === "nthOfType") {
       if (positionFlags.hasNthOfType) {
         merged.push({ kind: "position", axis: "nthOfType" });
@@ -29528,8 +29612,29 @@ function assertSupportedCloudBrowserMode(browser) {
   }
 }
 function isMissingCloudSessionError(error) {
+  if (error instanceof OpensteerCloudRequestError) {
+    return error.statusCode === 404 && (error.code === void 0 || error.code === "CLOUD_SESSION_NOT_FOUND");
+  }
   return error instanceof Error && /\b404\b/.test(error.message);
 }
+function isRecoverableCloudSessionError(error) {
+  if (!(error instanceof OpensteerCloudRequestError)) {
+    return false;
+  }
+  if (error.statusCode === 404) {
+    return error.code === void 0 || error.code === "CLOUD_SESSION_NOT_FOUND";
+  }
+  return error.statusCode === 409 && error.code === "CLOUD_SESSION_STALE";
+}
+function isBootstrapRecoveryOperation(operation) {
+  return operation === "session.open" || operation === "instrumentation.route" || operation === "instrumentation.intercept-script";
+}
+function isReusableCloudSessionState(session) {
+  if (session.status === "closing" || session.status === "closed" || session.status === "failed") {
+    return false;
+  }
+  return !(typeof session.expiresAt === "number" && session.expiresAt <= Date.now() + CLOUD_SESSION_REUSE_EXPIRY_SKEW_MS);
+}
 function isLoopbackBaseUrl(baseUrl) {
   let url;
   try {
@@ -29539,7 +29644,7 @@ function isLoopbackBaseUrl(baseUrl) {
   }
   return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]";
 }
-var TEMPORARY_CLOUD_WORKSPACE_PREFIX, CloudSessionProxy;
+var TEMPORARY_CLOUD_WORKSPACE_PREFIX, CLOUD_SESSION_REUSE_EXPIRY_SKEW_MS, CloudSessionProxy;
 var init_session_proxy = __esm({
   "src/cloud/session-proxy.ts"() {
     init_src3();
@@ -29549,8 +29654,10 @@ var init_session_proxy = __esm({
     init_policy2();
     init_semantic_rest_client();
     init_automation_client();
+    init_client();
     init_workspace_sync();
     TEMPORARY_CLOUD_WORKSPACE_PREFIX = "opensteer-cloud-workspace-";
+    CLOUD_SESSION_REUSE_EXPIRY_SKEW_MS = 1e4;
     CloudSessionProxy = class {
       rootPath;
       workspace;
@@ -29564,6 +29671,8 @@ var init_session_proxy = __esm({
       automation;
       workspaceStore;
       syncWorkspaceOnClose = false;
+      liveSessionStateEstablished = false;
+      storedInstrumentation = [];
       constructor(cloud, options = {}) {
         this.cloud = cloud;
         this.workspace = options.workspace;
@@ -29593,15 +29702,12 @@ var init_session_proxy = __esm({
         if (this.client === void 0 && this.sessionId === void 0 && persisted !== void 0 && await this.isReusableCloudSession(persisted.sessionId)) {
           this.bindClient(persisted);
         }
-        if (this.automation) {
-          try {
-            const sessionInfo = await this.automation.getSessionInfo();
-            return {
-              ...sessionInfo,
-              ...this.workspace === void 0 ? {} : { workspace: this.workspace }
-            };
-          } catch {
-          }
+        const sessionInfo = this.automation ? await this.automation.getSessionInfo().catch(() => void 0) : void 0;
+        if (sessionInfo !== void 0) {
+          return {
+            ...sessionInfo,
+            ...this.workspace === void 0 ? {} : { workspace: this.workspace }
+          };
         }
         return {
           provider: {
@@ -29713,12 +29819,26 @@ var init_session_proxy = __esm({
         return this.invokeSemanticOperation("session.cookies", input);
       }
       async route(input) {
-        await this.ensureSession();
-        return this.requireAutomation().route(input);
+        const registration = await this.invokeBootstrapInstrumentationOperation(
+          "instrumentation.route",
+          (automation) => automation.route(input)
+        );
+        this.storedInstrumentation.push({
+          kind: "route",
+          input
+        });
+        return registration;
       }
       async interceptScript(input) {
-        await this.ensureSession();
-        return this.requireAutomation().interceptScript(input);
+        const registration = await this.invokeBootstrapInstrumentationOperation(
+          "instrumentation.intercept-script",
+          (automation) => automation.interceptScript(input)
+        );
+        this.storedInstrumentation.push({
+          kind: "intercept-script",
+          input
+        });
+        return registration;
       }
       async getStorageSnapshot(input = {}) {
         return this.invokeSemanticOperation("session.storage", input);
@@ -29766,6 +29886,8 @@ var init_session_proxy = __esm({
           this.client = void 0;
           this.sessionId = void 0;
           this.semanticGrant = void 0;
+          this.liveSessionStateEstablished = false;
+          this.storedInstrumentation.length = 0;
           if (this.cleanupRootOnClose) {
             await promises.rm(this.rootPath, { recursive: true, force: true }).catch(() => void 0);
           }
@@ -29793,6 +29915,8 @@ var init_session_proxy = __esm({
         this.automation = void 0;
         this.sessionId = void 0;
         this.semanticGrant = void 0;
+        this.liveSessionStateEstablished = false;
+        this.storedInstrumentation.length = 0;
         if (syncError !== void 0) {
           throw syncError;
         }
@@ -29840,6 +29964,7 @@ var init_session_proxy = __esm({
         };
         await this.writePersistedSession(record);
         this.bindClient(record, session.initialGrants?.semantic);
+        await this.restoreStoredInstrumentation();
       }
       async syncWorkspaceToCloud() {
         if (this.workspace === void 0) {
@@ -29851,6 +29976,7 @@ var init_session_proxy = __esm({
       bindClient(record, initialSemanticGrant) {
         this.sessionId = record.sessionId;
         this.semanticGrant = initialSemanticGrant?.kind === "semantic" ? initialSemanticGrant : void 0;
+        this.liveSessionStateEstablished = false;
         this.client = new OpensteerSemanticRestClient({
           getBaseUrl: async () => (await this.ensureSemanticGrant()).url,
           getAuthorizationHeader: async () => `Bearer ${(await this.ensureSemanticGrant()).token}`,
@@ -29858,6 +29984,19 @@ var init_session_proxy = __esm({
         });
         this.automation = new OpensteerCloudAutomationClient(this.cloud, record.sessionId);
       }
+      async restoreStoredInstrumentation() {
+        if (this.storedInstrumentation.length === 0) {
+          return;
+        }
+        const automation = this.requireAutomation();
+        for (const registration of this.storedInstrumentation) {
+          if (registration.kind === "route") {
+            await automation.route(registration.input);
+          } else {
+            await automation.interceptScript(registration.input);
+          }
+        }
+      }
       async ensureWorkspaceStore() {
         if (this.workspaceStore !== void 0) {
           return this.workspaceStore;
@@ -29880,13 +30019,22 @@ var init_session_proxy = __esm({
       async clearPersistedSession() {
         await clearPersistedSessionRecord(this.rootPath, "cloud").catch(() => void 0);
       }
+      async invalidateSession() {
+        await this.automation?.close().catch(() => void 0);
+        this.automation = void 0;
+        this.client = void 0;
+        this.sessionId = void 0;
+        this.semanticGrant = void 0;
+        this.liveSessionStateEstablished = false;
+        await this.clearPersistedSession();
+      }
       async isReusableCloudSession(sessionId, timeout) {
         try {
           const session = await this.cloud.getSession(sessionId, {
             signal: timeout?.signal,
             timeoutMs: timeout?.remainingMs()
           });
-          return session.status !== "closed" && session.status !== "failed";
+          return isReusableCloudSessionState(session);
         } catch (error) {
           if (isMissingCloudSessionError(error)) {
             return false;
@@ -29935,26 +30083,79 @@ var init_session_proxy = __esm({
         try {
           await this.ensureSemanticGrant(true);
           return true;
-        } catch {
+        } catch (refreshError) {
+          if (await this.resetStaleSession(refreshError)) {
+            throw refreshError;
+          }
           return false;
         }
       }
       async invokeSemanticOperation(operation, input, sessionInit = {}) {
-        return this.runOperationWithPolicy(operation, async (timeout) => {
+        return this.runOperationWithSessionRecovery(operation, async (timeout) => {
           await this.ensureSession(sessionInit, timeout);
           await this.ensureSemanticGrant(false, timeout);
-          return this.requireClient().invoke(operation, input, {
+          const output = await this.requireClient().invoke(operation, input, {
             signal: timeout.signal,
             timeoutMs: timeout.remainingMs()
           });
+          this.noteSuccessfulLiveOperation(operation);
+          return output;
         });
       }
       async invokeAutomationOperation(operation, invoke, sessionInit = {}) {
-        return this.runOperationWithPolicy(operation, async (timeout) => {
+        return this.runOperationWithSessionRecovery(operation, async (timeout) => {
           await this.ensureSession(sessionInit, timeout);
-          return invoke(this.requireAutomation());
+          const output = await invoke(this.requireAutomation());
+          this.noteSuccessfulLiveOperation(operation);
+          return output;
         });
       }
+      async invokeBootstrapInstrumentationOperation(operation, invoke) {
+        let recovered = false;
+        while (true) {
+          try {
+            await this.ensureSession();
+            return await invoke(this.requireAutomation());
+          } catch (error) {
+            const stale = await this.resetStaleSession(error);
+            if (!stale || recovered || !this.canRecoverWithFreshSession(operation)) {
+              throw error;
+            }
+            recovered = true;
+          }
+        }
+      }
+      async runOperationWithSessionRecovery(operation, invoke) {
+        return this.runOperationWithPolicy(operation, async (timeout) => {
+          let recovered = false;
+          while (true) {
+            try {
+              return await invoke(timeout);
+            } catch (error) {
+              const stale = await this.resetStaleSession(error);
+              if (!stale || recovered || !this.canRecoverWithFreshSession(operation)) {
+                throw error;
+              }
+              recovered = true;
+            }
+          }
+        });
+      }
+      async resetStaleSession(error) {
+        if (!isRecoverableCloudSessionError(error)) {
+          return false;
+        }
+        await this.invalidateSession();
+        return true;
+      }
+      canRecoverWithFreshSession(operation) {
+        return !this.liveSessionStateEstablished && isBootstrapRecoveryOperation(operation);
+      }
+      noteSuccessfulLiveOperation(operation) {
+        if (operation === "session.open" || operation === "page.list" || operation === "page.new" || operation === "page.activate" || operation === "page.close" || operation === "page.goto" || operation === "page.evaluate" || operation === "page.add-init-script" || operation === "page.snapshot" || operation === "dom.click" || operation === "dom.hover" || operation === "dom.input" || operation === "dom.scroll" || operation === "dom.extract" || operation === "network.query" || operation === "network.detail" || operation === "interaction.capture" || operation === "interaction.get" || operation === "interaction.diff" || operation === "interaction.replay" || operation === "scripts.capture" || operation === "artifact.read" || operation === "scripts.beautify" || operation === "scripts.deobfuscate" || operation === "scripts.sandbox" || operation === "captcha.solve" || operation === "session.cookies" || operation === "session.storage" || operation === "session.state" || operation === "session.fetch" || operation === "computer.execute") {
+          this.liveSessionStateEstablished = true;
+        }
+      }
       async runOperationWithPolicy(operation, invoke) {
         return runWithPolicyTimeout(this.policy.timeout, { operation }, invoke);
       }
@@ -30269,14 +30470,85 @@ var init_session_control = __esm({
   }
 });
 
+// src/internal/errors.ts
+function normalizeThrownOpensteerError2(error, fallbackMessage) {
+  if (isOpensteerProtocolError(error)) {
+    return toOpensteerError(error);
+  }
+  if (isBrowserCoreError(error)) {
+    return createOpensteerError(error.code, error.message, {
+      retriable: error.retriable,
+      ...error.details === void 0 ? {} : { details: error.details }
+    });
+  }
+  if (error instanceof OpensteerAttachAmbiguousError) {
+    return createOpensteerError("conflict", error.message, {
+      details: {
+        candidates: error.candidates,
+        code: error.code,
+        name: error.name
+      }
+    });
+  }
+  if (error instanceof Error && "opensteerError" in error && typeof error.opensteerError === "object" && error.opensteerError !== null) {
+    const oe = error.opensteerError;
+    return createOpensteerError(oe.code, oe.message, {
+      retriable: oe.retriable,
+      ...oe.capability === void 0 ? {} : { capability: oe.capability },
+      ...oe.details === void 0 ? {} : { details: oe.details }
+    });
+  }
+  if (error instanceof Error) {
+    return createOpensteerError("operation-failed", error.message, {
+      details: {
+        name: error.name
+      }
+    });
+  }
+  return createOpensteerError("internal", fallbackMessage, {
+    details: {
+      value: error
+    }
+  });
+}
+var init_errors5 = __esm({
+  "src/internal/errors.ts"() {
+    init_src();
+    init_src2();
+    init_cdp_discovery();
+  }
+});
+
 // src/sdk/opensteer.ts
 var opensteer_exports = {};
 __export(opensteer_exports, {
   Opensteer: () => Opensteer
 });
+function createSdkProtocolError(error, fallbackMessage) {
+  const normalized = normalizeThrownOpensteerError2(error, fallbackMessage);
+  return new OpensteerProtocolError(normalized.code, normalized.message, {
+    cause: error,
+    retriable: normalized.retriable,
+    ...normalized.capability === void 0 ? {} : { capability: normalized.capability },
+    ...normalized.details === void 0 ? {} : { details: normalized.details }
+  });
+}
+async function wrapSdkError(operation, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    if (isOpensteerProtocolError(error)) {
+      throw error;
+    }
+    throw createSdkProtocolError(error, `${operation} failed`);
+  }
+}
 function createUnsupportedBrowserController() {
   const fail = async () => {
-    throw new Error("browser.* helpers are only available in local mode.");
+    throw new OpensteerProtocolError(
+      "unsupported-operation",
+      "browser.* helpers are only available in local mode."
+    );
   };
   return {
     status: fail,
@@ -30289,7 +30561,10 @@ function normalizeTargetOptions(input) {
   const hasElement = input.element !== void 0;
   const hasSelector = input.selector !== void 0;
   if (hasElement && hasSelector) {
-    throw new Error("Specify exactly one of element, selector, or persist.");
+    throw new OpensteerProtocolError(
+      "invalid-argument",
+      "Specify exactly one of element, selector, or persist."
+    );
   }
   if (hasElement) {
     return {
@@ -30312,7 +30587,10 @@ function normalizeTargetOptions(input) {
     };
   }
   if (input.persist === void 0) {
-    throw new Error("Specify exactly one of element, selector, or persist.");
+    throw new OpensteerProtocolError(
+      "invalid-argument",
+      "Specify exactly one of element, selector, or persist."
+    );
   }
   return {
     target: {
@@ -30374,8 +30652,10 @@ function delay5(ms) {
 var SessionCookieJar, Opensteer;
 var init_opensteer = __esm({
   "src/sdk/opensteer.ts"() {
+    init_src2();
     init_browser_manager();
     init_env();
+    init_errors5();
     init_runtime_resolution();
     SessionCookieJar = class {
       domain;
@@ -30406,202 +30686,257 @@ var init_opensteer = __esm({
       dom;
       network;
       constructor(options = {}) {
-        const environment = resolveOpensteerEnvironment(options.rootDir);
-        const { provider, engineName, ...runtimeOptions } = options;
-        const runtimeConfig = resolveOpensteerRuntimeConfig({
-          ...provider === void 0 ? {} : { provider },
-          environment
-        });
-        if (runtimeConfig.provider.mode === "cloud") {
-          this.browserManager = void 0;
-          this.runtime = createOpensteerSemanticRuntime({
-            ...provider === void 0 ? {} : { provider },
-            ...engineName === void 0 ? {} : { engine: engineName },
-            environment,
-            runtimeOptions
-          });
-          this.browser = createUnsupportedBrowserController();
-        } else {
-          this.browserManager = new OpensteerBrowserManager({
-            ...runtimeOptions.rootDir === void 0 ? {} : { rootDir: runtimeOptions.rootDir },
-            ...runtimeOptions.rootPath === void 0 ? {} : { rootPath: runtimeOptions.rootPath },
-            ...runtimeOptions.workspace === void 0 ? {} : { workspace: runtimeOptions.workspace },
-            ...engineName === void 0 ? {} : { engineName },
-            environment,
-            ...runtimeOptions.browser === void 0 ? {} : { browser: runtimeOptions.browser },
-            ...runtimeOptions.launch === void 0 ? {} : { launch: runtimeOptions.launch },
-            ...runtimeOptions.context === void 0 ? {} : { context: runtimeOptions.context }
-          });
-          this.runtime = createOpensteerSemanticRuntime({
+        try {
+          const environment = resolveOpensteerEnvironment(options.rootDir);
+          const { provider, engineName, ...runtimeOptions } = options;
+          const runtimeConfig = resolveOpensteerRuntimeConfig({
             ...provider === void 0 ? {} : { provider },
-            ...engineName === void 0 ? {} : { engine: engineName },
-            environment,
-            runtimeOptions: {
-              ...runtimeOptions,
-              rootPath: this.browserManager.rootPath,
-              cleanupRootOnClose: this.browserManager.cleanupRootOnDisconnect
-            }
+            environment
           });
-          this.browser = {
-            status: () => this.browserManager.status(),
-            clone: (input) => this.browserManager.clonePersistentBrowser(input),
-            reset: () => this.browserManager.reset(),
-            delete: () => this.browserManager.delete()
+          if (runtimeConfig.provider.mode === "cloud") {
+            this.browserManager = void 0;
+            this.runtime = createOpensteerSemanticRuntime({
+              ...provider === void 0 ? {} : { provider },
+              ...engineName === void 0 ? {} : { engine: engineName },
+              environment,
+              runtimeOptions
+            });
+            this.browser = createUnsupportedBrowserController();
+          } else {
+            this.browserManager = new OpensteerBrowserManager({
+              ...runtimeOptions.rootDir === void 0 ? {} : { rootDir: runtimeOptions.rootDir },
+              ...runtimeOptions.rootPath === void 0 ? {} : { rootPath: runtimeOptions.rootPath },
+              ...runtimeOptions.workspace === void 0 ? {} : { workspace: runtimeOptions.workspace },
+              ...engineName === void 0 ? {} : { engineName },
+              environment,
+              ...runtimeOptions.browser === void 0 ? {} : { browser: runtimeOptions.browser },
+              ...runtimeOptions.launch === void 0 ? {} : { launch: runtimeOptions.launch },
+              ...runtimeOptions.context === void 0 ? {} : { context: runtimeOptions.context }
+            });
+            this.runtime = createOpensteerSemanticRuntime({
+              ...provider === void 0 ? {} : { provider },
+              ...engineName === void 0 ? {} : { engine: engineName },
+              environment,
+              runtimeOptions: {
+                ...runtimeOptions,
+                rootPath: this.browserManager.rootPath,
+                cleanupRootOnClose: this.browserManager.cleanupRootOnDisconnect
+              }
+            });
+            this.browser = {
+              status: () => wrapSdkError("browser.status", () => this.browserManager.status()),
+              clone: (input) => wrapSdkError("browser.clone", () => this.browserManager.clonePersistentBrowser(input)),
+              reset: () => wrapSdkError("browser.reset", () => this.browserManager.reset()),
+              delete: () => wrapSdkError("browser.delete", () => this.browserManager.delete())
+            };
+          }
+          this.dom = {
+            click: (input) => this.click(input),
+            hover: (input) => this.hover(input),
+            input: (input) => this.input(input),
+            scroll: (input) => this.scroll(input)
+          };
+          this.network = {
+            query: (input = {}) => wrapSdkError("network.query", () => this.runtime.queryNetwork(input)),
+            detail: (recordId, options2) => wrapSdkError(
+              "network.detail",
+              () => this.runtime.getNetworkDetail({ recordId, ...options2 })
+            )
           };
+        } catch (error) {
+          if (isOpensteerProtocolError(error)) {
+            throw error;
+          }
+          throw createSdkProtocolError(error, "Failed to initialize Opensteer");
         }
-        this.dom = {
-          click: (input) => this.click(input),
-          hover: (input) => this.hover(input),
-          input: (input) => this.input(input),
-          scroll: (input) => this.scroll(input)
-        };
-        this.network = {
-          query: (input = {}) => this.runtime.queryNetwork(input),
-          detail: (recordId, options2) => this.runtime.getNetworkDetail({ recordId, ...options2 })
-        };
       }
       async open(input = {}) {
-        return this.runtime.open(typeof input === "string" ? { url: input } : input);
+        return wrapSdkError(
+          "session.open",
+          () => this.runtime.open(typeof input === "string" ? { url: input } : input)
+        );
       }
       async info() {
-        return this.runtime.info();
+        return wrapSdkError("session.info", () => this.runtime.info());
       }
       async listPages(input = {}) {
-        return this.runtime.listPages(input);
+        return wrapSdkError("page.list", () => this.runtime.listPages(input));
       }
       async newPage(input = {}) {
-        return this.runtime.newPage(input);
+        return wrapSdkError("page.new", () => this.runtime.newPage(input));
       }
       async activatePage(input) {
-        return this.runtime.activatePage(input);
+        return wrapSdkError("page.activate", () => this.runtime.activatePage(input));
       }
       async closePage(input = {}) {
-        return this.runtime.closePage(input);
+        return wrapSdkError("page.close", () => this.runtime.closePage(input));
       }
       async goto(url, options = {}) {
-        return this.runtime.goto({
-          url,
-          ...options
-        });
+        return wrapSdkError(
+          "page.goto",
+          () => this.runtime.goto({
+            url,
+            ...options
+          })
+        );
       }
       async evaluate(input) {
-        const normalized = typeof input === "string" ? {
-          script: input
-        } : input;
-        return (await this.runtime.evaluate(normalized)).value;
+        return wrapSdkError("page.evaluate", async () => {
+          const normalized = typeof input === "string" ? {
+            script: input
+          } : input;
+          return (await this.runtime.evaluate(normalized)).value;
+        });
       }
       async addInitScript(input) {
-        return this.runtime.addInitScript(
-          typeof input === "string" ? {
-            script: input
-          } : input
+        return wrapSdkError(
+          "page.addInitScript",
+          () => this.runtime.addInitScript(
+            typeof input === "string" ? {
+              script: input
+            } : input
+          )
         );
       }
       async click(input) {
-        const { button, clickCount, modifiers, ...target } = input;
-        return this.runtime.click({
-          ...normalizeTargetOptions(target),
-          ...button === void 0 ? {} : { button },
-          ...clickCount === void 0 ? {} : { clickCount },
-          ...modifiers === void 0 ? {} : { modifiers }
+        return wrapSdkError("dom.click", () => {
+          const { button, clickCount, modifiers, ...target } = input;
+          return this.runtime.click({
+            ...normalizeTargetOptions(target),
+            ...button === void 0 ? {} : { button },
+            ...clickCount === void 0 ? {} : { clickCount },
+            ...modifiers === void 0 ? {} : { modifiers }
+          });
         });
       }
       async hover(input) {
-        return this.runtime.hover(normalizeTargetOptions(input));
+        return wrapSdkError("dom.hover", () => this.runtime.hover(normalizeTargetOptions(input)));
       }
       async input(input) {
-        return this.runtime.input({
-          ...normalizeTargetOptions(input),
-          text: input.text,
-          ...input.pressEnter === void 0 ? {} : { pressEnter: input.pressEnter }
-        });
+        return wrapSdkError(
+          "dom.input",
+          () => this.runtime.input({
+            ...normalizeTargetOptions(input),
+            text: input.text,
+            ...input.pressEnter === void 0 ? {} : { pressEnter: input.pressEnter }
+          })
+        );
       }
       async scroll(input) {
-        return this.runtime.scroll({
-          ...normalizeTargetOptions(input),
-          direction: input.direction,
-          amount: input.amount
-        });
+        return wrapSdkError(
+          "dom.scroll",
+          () => this.runtime.scroll({
+            ...normalizeTargetOptions(input),
+            direction: input.direction,
+            amount: input.amount
+          })
+        );
       }
       async extract(input) {
-        return (await this.runtime.extract(input)).data;
+        return wrapSdkError("extract", async () => (await this.runtime.extract(input)).data);
       }
       async waitForPage(input = {}) {
-        const baseline = new Set((await this.runtime.listPages()).pages.map((page) => page.pageRef));
-        const timeoutAt = Date.now() + (input.timeoutMs ?? 3e4);
-        const pollIntervalMs = input.pollIntervalMs ?? 100;
-        while (true) {
-          const match = (await this.runtime.listPages()).pages.find((page) => {
-            if (baseline.has(page.pageRef)) {
-              return false;
-            }
-            if (input.openerPageRef !== void 0 && page.openerPageRef !== input.openerPageRef) {
-              return false;
+        return wrapSdkError("page.waitForPage", async () => {
+          const baseline = new Set((await this.runtime.listPages()).pages.map((page) => page.pageRef));
+          const timeoutAt = Date.now() + (input.timeoutMs ?? 3e4);
+          const pollIntervalMs = input.pollIntervalMs ?? 100;
+          while (true) {
+            const match = (await this.runtime.listPages()).pages.find((page) => {
+              if (baseline.has(page.pageRef)) {
+                return false;
+              }
+              if (input.openerPageRef !== void 0 && page.openerPageRef !== input.openerPageRef) {
+                return false;
+              }
+              if (input.urlIncludes !== void 0 && !page.url.includes(input.urlIncludes)) {
+                return false;
+              }
+              return true;
+            });
+            if (match !== void 0) {
+              return match;
             }
-            if (input.urlIncludes !== void 0 && !page.url.includes(input.urlIncludes)) {
-              return false;
+            if (Date.now() >= timeoutAt) {
+              throw new OpensteerProtocolError("timeout", "waitForPage timed out");
             }
-            return true;
-          });
-          if (match !== void 0) {
-            return match;
-          }
-          if (Date.now() >= timeoutAt) {
-            throw new Error("waitForPage timed out");
+            await delay5(pollIntervalMs);
           }
-          await delay5(pollIntervalMs);
-        }
+        });
       }
       async cookies(domain) {
-        return new SessionCookieJar(
-          await this.runtime.getCookies(domain === void 0 ? {} : { domain })
+        return wrapSdkError(
+          "session.cookies",
+          async () => new SessionCookieJar(await this.runtime.getCookies(domain === void 0 ? {} : { domain }))
         );
       }
       async storage(domain, type = "local") {
-        const snapshot = await this.runtime.getStorageSnapshot(domain === void 0 ? {} : { domain });
-        const domainSnapshot = pickStorageDomainSnapshot(snapshot, domain);
-        if (domainSnapshot === void 0) {
-          return {};
-        }
-        const entries = type === "local" ? domainSnapshot.localStorage : domainSnapshot.sessionStorage;
-        return Object.fromEntries(entries.map((entry) => [entry.key, entry.value]));
+        return wrapSdkError("session.storage", async () => {
+          const snapshot = await this.runtime.getStorageSnapshot(
+            domain === void 0 ? {} : { domain }
+          );
+          const domainSnapshot = pickStorageDomainSnapshot(snapshot, domain);
+          if (domainSnapshot === void 0) {
+            return {};
+          }
+          const entries = type === "local" ? domainSnapshot.localStorage : domainSnapshot.sessionStorage;
+          return Object.fromEntries(entries.map((entry) => [entry.key, entry.value]));
+        });
       }
       async state(domain) {
-        return this.runtime.getBrowserState(domain === void 0 ? {} : { domain });
+        return wrapSdkError(
+          "session.state",
+          () => this.runtime.getBrowserState(domain === void 0 ? {} : { domain })
+        );
       }
       async fetch(url, options = {}) {
-        const input = buildFetchInput(url, options);
-        const result = await this.runtime.fetch(input);
-        if (result.response === void 0) {
-          throw new Error(result.note ?? `session.fetch did not produce a response for ${url}`);
-        }
-        return toResponse(result.response);
+        return wrapSdkError("session.fetch", async () => {
+          const input = buildFetchInput(url, options);
+          const result = await this.runtime.fetch(input);
+          if (result.response === void 0) {
+            throw new OpensteerProtocolError(
+              "operation-failed",
+              result.note ?? `session.fetch did not produce a response for ${url}`
+            );
+          }
+          return toResponse(result.response);
+        });
       }
       async computerExecute(input) {
-        return this.runtime.computerExecute(input);
+        return wrapSdkError("session.computerExecute", () => this.runtime.computerExecute(input));
       }
       async route(input) {
-        return this.requireOwnedInstrumentationRuntime("route").route(input);
+        return wrapSdkError(
+          "session.route",
+          () => this.requireOwnedInstrumentationRuntime("route").route(input)
+        );
       }
       async interceptScript(input) {
-        return this.requireOwnedInstrumentationRuntime("interceptScript").interceptScript(input);
+        return wrapSdkError(
+          "session.interceptScript",
+          () => this.requireOwnedInstrumentationRuntime("interceptScript").interceptScript(input)
+        );
       }
       async close() {
-        if (this.browserManager === void 0 || this.browserManager.mode === "temporary") {
-          return this.runtime.close();
-        }
-        const output = await this.runtime.close();
-        await this.browserManager.close();
-        return output;
+        return wrapSdkError("session.close", async () => {
+          if (this.browserManager === void 0 || this.browserManager.mode === "temporary") {
+            return this.runtime.close();
+          }
+          const output = await this.runtime.close();
+          await this.browserManager.close();
+          return output;
+        });
       }
       async disconnect() {
-        await this.runtime.disconnect();
+        return wrapSdkError("session.disconnect", () => this.runtime.disconnect());
       }
       requireOwnedInstrumentationRuntime(method) {
         if (typeof this.runtime.route === "function" && typeof this.runtime.interceptScript === "function") {
           return this.runtime;
         }
-        throw new Error(`${method}() is not available for this session runtime.`);
+        throw new OpensteerProtocolError(
+          "unsupported-operation",
+          `${method}() is not available for this session runtime.`
+        );
       }
     };
   }
@@ -30609,7 +30944,7 @@ var init_opensteer = __esm({
 
 // package.json
 var package_default = {
-  version: "0.9.5"};
+  version: "0.9.6"};
 
 // src/cli/bin.ts
 init_browser_manager();
@@ -30624,6 +30959,110 @@ async function loadCliEnvironment(cwd) {
   loadEnvironment(cwd);
 }
 
+// src/cli/errors.ts
+init_src();
+init_src2();
+var CliError = class extends Error {
+  type;
+  usage;
+  constructor(type, message, usage) {
+    super(message);
+    this.name = "CliError";
+    this.type = type;
+    this.usage = usage;
+  }
+  format() {
+    return this.usage === void 0 ? this.message : `${this.message}
+Usage: ${this.usage}`;
+  }
+};
+function isCliError(value) {
+  return value instanceof CliError;
+}
+function formatCliErrorOutput(error) {
+  if (isCliError(error)) {
+    return {
+      success: false,
+      error: error.format(),
+      type: error.type
+    };
+  }
+  if (isOpensteerProtocolError(error)) {
+    return {
+      success: false,
+      error: error.message,
+      code: error.code,
+      retriable: error.retriable
+    };
+  }
+  if (isBrowserCoreError(error)) {
+    return {
+      success: false,
+      error: error.message,
+      code: error.code,
+      retriable: error.retriable
+    };
+  }
+  if (error instanceof Error && "opensteerError" in error) {
+    const oe = error.opensteerError;
+    return {
+      success: false,
+      error: oe.message,
+      code: oe.code,
+      retriable: oe.retriable
+    };
+  }
+  if (error instanceof SyntaxError) {
+    return {
+      success: false,
+      error: error.message,
+      type: "invalid_value"
+    };
+  }
+  return {
+    success: false,
+    error: error instanceof Error ? error.message : String(error)
+  };
+}
+function emitWarning(warning) {
+  process.stderr.write(`${JSON.stringify({ warning })}
+`);
+}
+var CLI_USAGE_HINTS = {
+  "session.open": "opensteer open <url> [--workspace <id>]",
+  "page.goto": "opensteer goto <url>",
+  "page.evaluate": "opensteer evaluate <script>",
+  "page.add-init-script": "opensteer init-script <script>",
+  "dom.click": "opensteer click <element> --persist <key>",
+  "dom.hover": "opensteer hover <element> --persist <key>",
+  "dom.input": "opensteer input <element> <text> --persist <key>",
+  "dom.scroll": "opensteer scroll <direction> <amount> --persist <key>",
+  "dom.extract": "opensteer extract <template> --persist <key>",
+  "network.detail": "opensteer network detail <recordId>",
+  "session.fetch": "opensteer fetch <url>",
+  "captcha.solve": "opensteer captcha solve --provider <name> --api-key <key>",
+  "scripts.capture": "opensteer scripts capture",
+  "scripts.beautify": "opensteer scripts beautify <artifactId>",
+  "scripts.deobfuscate": "opensteer scripts deobfuscate <artifactId>",
+  "scripts.sandbox": "opensteer scripts sandbox <artifactId>",
+  "interaction.capture": "opensteer interaction capture",
+  "interaction.get": "opensteer interaction get <traceId>",
+  "interaction.replay": "opensteer interaction replay <traceId>",
+  "interaction.diff": "opensteer interaction diff <leftTraceId> <rightTraceId>",
+  "artifact.read": "opensteer artifact read <artifactId>",
+  "computer.click": "opensteer computer click <x> <y>",
+  "computer.type": "opensteer computer type <text>",
+  "computer.key": "opensteer computer key <key>",
+  "computer.scroll": "opensteer computer scroll <x> <y> --dx <n> --dy <n>",
+  "computer.move": "opensteer computer move <x> <y>",
+  "computer.drag": "opensteer computer drag <x1> <y1> <x2> <y2>",
+  "computer.screenshot": "opensteer computer screenshot",
+  exec: "opensteer exec <expression>",
+  record: "opensteer record --url <url> --workspace <id>",
+  "browser.inspect": "opensteer browser inspect <endpoint>",
+  "browser.clone": "opensteer browser clone --source-user-data-dir <path>"
+};
+
 // src/cli/help.ts
 function getHelpText() {
   return `Opensteer CLI
@@ -30885,7 +31324,7 @@ function parseCommandLine(argv) {
     const key = token.slice(2, separator === -1 ? void 0 : separator);
     const spec = CLI_OPTION_SPECS[key];
     if (spec === void 0) {
-      throw new Error(`Unknown option: --${key}.`);
+      throw new CliError("unknown_option", `Unknown option: --${key}.`);
     }
     if (separator !== -1) {
       rawOptions.set(key, [...rawOptions.get(key) ?? [], token.slice(separator + 1)]);
@@ -30914,7 +31353,8 @@ function parseCommandLine(argv) {
       continue;
     }
     if (next === void 0 || next.startsWith("--")) {
-      throw new Error(
+      throw new CliError(
+        "missing_arguments",
         `Option "--${key}" requires a value.${next?.startsWith("--") === true ? ` Use "--${key}=<value>" when the value begins with "--".` : ``}`
       );
     }
@@ -30960,10 +31400,14 @@ function parseCommandLine(argv) {
   const autoLocalView = readOptionalBoolean(rawOptions, "auto");
   const noAutoLocalView = readOptionalBoolean(rawOptions, "no-auto");
   if (autoLocalView === true && noAutoLocalView === true) {
-    throw new Error('Options "--auto" and "--no-auto" cannot be combined.');
+    throw new CliError("invalid_option", 'Options "--auto" and "--no-auto" cannot be combined.');
   }
   if (command[0] !== "view" && (autoLocalView !== void 0 || noAutoLocalView !== void 0)) {
-    throw new Error('Options "--auto" and "--no-auto" are only supported with "view".');
+    throw new CliError(
+      "invalid_option",
+      'Options "--auto" and "--no-auto" are only supported with "view".',
+      "opensteer view --auto"
+    );
   }
   const global = readOptionalBoolean(rawOptions, "global");
   const yes = readOptionalBoolean(rawOptions, "yes");
@@ -31019,7 +31463,7 @@ function parseKeyValueList(values) {
     values.map((entry) => {
       const separator = entry.indexOf("=");
       if (separator <= 0) {
-        throw new Error(`Expected NAME=VALUE, received "${entry}".`);
+        throw new CliError("invalid_value", `Expected NAME=VALUE, received "${entry}".`);
       }
       return [entry.slice(0, separator), entry.slice(separator + 1)];
     })
@@ -31050,7 +31494,7 @@ function readOptionalBoolean(options, name) {
   if (value === "false") {
     return false;
   }
-  throw new Error(`Option "--${name}" must be true or false.`);
+  throw new CliError("invalid_value", `Option "--${name}" must be true or false.`);
 }
 function readOptionalNumber(options, name) {
   const value = readSingle(options, name);
@@ -31059,13 +31503,20 @@ function readOptionalNumber(options, name) {
   }
   const parsed = Number(value);
   if (!Number.isFinite(parsed)) {
-    throw new Error(`Option "--${name}" must be a number.`);
+    throw new CliError("invalid_value", `Option "--${name}" must be a number.`);
   }
   return parsed;
 }
 function readJsonValue(options, name) {
   const value = readSingle(options, name);
-  return value === void 0 ? void 0 : JSON.parse(value);
+  if (value === void 0) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new CliError("invalid_value", `Option "--${name}" contains invalid JSON.`);
+  }
 }
 function readJsonObject(options, name) {
   const parsed = readJsonValue(options, name);
@@ -31073,7 +31524,7 @@ function readJsonObject(options, name) {
     return void 0;
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`Option "--${name}" must be a JSON object.`);
+    throw new CliError("invalid_value", `Option "--${name}" must be a JSON object.`);
   }
   return parsed;
 }
@@ -31083,7 +31534,7 @@ function readJsonArray(options, name) {
     return void 0;
   }
   if (!Array.isArray(parsed)) {
-    throw new Error(`Option "--${name}" must be a JSON array.`);
+    throw new CliError("invalid_value", `Option "--${name}" must be a JSON array.`);
   }
   return parsed;
 }
@@ -31103,7 +31554,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "session.open": {
       const url = parsed.rest[0];
       if (url === void 0) {
-        throw new Error("open requires a URL.");
+        throw new CliError("missing_arguments", "open requires a URL.", CLI_USAGE_HINTS[operation]);
       }
       return {
         url,
@@ -31136,7 +31587,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "page.goto": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("goto requires a URL.");
+        throw new CliError("missing_arguments", "goto requires a URL.", CLI_USAGE_HINTS[operation]);
       }
       const captureNetwork = readSingle(parsed.rawOptions, "capture-network");
       return {
@@ -31148,14 +31599,14 @@ async function buildOperationInput(operation, parsed, runtime) {
       return parsed.rest[0] === void 0 ? {} : { mode: parsed.rest[0] };
     case "page.evaluate":
       if (parsed.rest[0] === void 0) {
-        throw new Error("evaluate requires a script.");
+        throw new CliError("missing_arguments", "evaluate requires a script.", CLI_USAGE_HINTS[operation]);
       }
       return {
         script: joinRest(parsed.rest, 0)
       };
     case "page.add-init-script":
       if (parsed.rest[0] === void 0) {
-        throw new Error("init-script requires a script.");
+        throw new CliError("missing_arguments", "init-script requires a script.", CLI_USAGE_HINTS[operation]);
       }
       return {
         script: joinRest(parsed.rest, 0)
@@ -31171,7 +31622,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       return buildElementTargetInput(parsed, "hover");
     case "dom.input": {
       if (parsed.rest[1] === void 0) {
-        throw new Error("input requires an element number and text.");
+        throw new CliError("missing_arguments", "input requires an element number and text.", CLI_USAGE_HINTS[operation]);
       }
       const pressEnter = readOptionalBoolean(parsed.rawOptions, "press-enter");
       return {
@@ -31202,7 +31653,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "dom.extract": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("extract requires a template.");
+        throw new CliError("missing_arguments", "extract requires a template.", CLI_USAGE_HINTS[operation]);
       }
       const persist = readPersistKey(parsed, "extract");
       return {
@@ -31238,7 +31689,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "network.detail": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("network detail requires a record id.");
+        throw new CliError("missing_arguments", "network detail requires a record id.", CLI_USAGE_HINTS[operation]);
       }
       const probeFlag = readOptionalBoolean(parsed.rawOptions, "probe");
       return {
@@ -31249,7 +31700,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "session.fetch": {
       const url = parsed.rest[0];
       if (url === void 0) {
-        throw new Error("fetch requires a URL.");
+        throw new CliError("missing_arguments", "fetch requires a URL.", CLI_USAGE_HINTS[operation]);
       }
       const bodyJson = readJsonValue(parsed.rawOptions, "body");
       const bodyText = readSingle(parsed.rawOptions, "body-text");
@@ -31257,7 +31708,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       const query = parseKeyValueList(parsed.rawOptions.get("query"));
       const headers = parseKeyValueList(parsed.rawOptions.get("header"));
       if (bodyJson !== void 0 && bodyText !== void 0) {
-        throw new Error('Use either "--body" or "--body-text", not both.');
+        throw new CliError("invalid_option", 'Use either "--body" or "--body-text", not both.');
       }
       const transport = readSingle(parsed.rawOptions, "transport");
       const cookies = readOptionalBoolean(parsed.rawOptions, "cookies");
@@ -31288,7 +31739,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       const siteKey = readSingle(parsed.rawOptions, "site-key");
       const pageUrl = readSingle(parsed.rawOptions, "page-url");
       if (provider === void 0 || apiKey === void 0) {
-        throw new Error('captcha solve requires "--provider" and "--api-key".');
+        throw new CliError("missing_arguments", 'captcha solve requires "--provider" and "--api-key".', CLI_USAGE_HINTS[operation]);
       }
       return {
         provider: readCaptchaProvider(provider),
@@ -31318,7 +31769,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "scripts.beautify":
     case "scripts.deobfuscate": {
       if (parsed.rest[0] === void 0) {
-        throw new Error(`${parsed.command.join(" ")} requires an artifact id.`);
+        throw new CliError("missing_arguments", `${parsed.command.join(" ")} requires an artifact id.`, CLI_USAGE_HINTS[operation]);
       }
       const persist = readOptionalBoolean(parsed.rawOptions, "persist");
       return {
@@ -31328,7 +31779,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "scripts.sandbox":
       if (parsed.rest[0] === void 0) {
-        throw new Error("scripts sandbox requires an artifact id.");
+        throw new CliError("missing_arguments", "scripts sandbox requires an artifact id.", CLI_USAGE_HINTS[operation]);
       }
       {
         const fidelity = readSingle(parsed.rawOptions, "fidelity");
@@ -31377,14 +31828,14 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "interaction.get":
     case "interaction.replay":
       if (parsed.rest[0] === void 0) {
-        throw new Error(`${parsed.command.join(" ")} requires a trace id.`);
+        throw new CliError("missing_arguments", `${parsed.command.join(" ")} requires a trace id.`, CLI_USAGE_HINTS[operation]);
       }
       return {
         traceId: parsed.rest[0]
       };
     case "interaction.diff":
       if (parsed.rest[0] === void 0 || parsed.rest[1] === void 0) {
-        throw new Error("interaction diff requires two trace ids.");
+        throw new CliError("missing_arguments", "interaction diff requires two trace ids.", CLI_USAGE_HINTS[operation]);
       }
       return {
         leftTraceId: parsed.rest[0],
@@ -31392,7 +31843,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       };
     case "artifact.read":
       if (parsed.rest[0] === void 0) {
-        throw new Error("artifact read requires an artifact id.");
+        throw new CliError("missing_arguments", "artifact read requires an artifact id.", CLI_USAGE_HINTS[operation]);
       }
       return {
         artifactId: parsed.rest[0]
@@ -31400,7 +31851,8 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "session.close":
       return {};
     default:
-      throw new Error(
+      throw new CliError(
+        "unsupported_operation",
         `${operation} does not have a direct CLI input shape. Use a supported command or the SDK.`
       );
   }
@@ -31447,7 +31899,7 @@ function buildComputerExecuteInput(parsed) {
     }
     case "type":
       if (parsed.rest[0] === void 0) {
-        throw new Error("computer type requires text.");
+        throw new CliError("missing_arguments", "computer type requires text.");
       }
       return {
         action: {
@@ -31458,7 +31910,7 @@ function buildComputerExecuteInput(parsed) {
       };
     case "key": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("computer key requires a key.");
+        throw new CliError("missing_arguments", "computer key requires a key.");
       }
       const modifiers = readKeyModifiers(readSingle(parsed.rawOptions, "modifiers"));
       return {
@@ -31474,7 +31926,7 @@ function buildComputerExecuteInput(parsed) {
       const dx = readOptionalNumber(parsed.rawOptions, "dx");
       const dy = readOptionalNumber(parsed.rawOptions, "dy");
       if (dx === void 0 || dy === void 0) {
-        throw new Error('computer scroll requires "--dx" and "--dy".');
+        throw new CliError("missing_arguments", 'computer scroll requires "--dx" and "--dy".');
       }
       return {
         action: {
@@ -31529,49 +31981,50 @@ function buildComputerExecuteInput(parsed) {
         }
       };
     default:
-      throw new Error(`Unknown computer command: ${parsed.command.join(" ")}`);
+      throw new CliError("unknown_command", `Unknown computer command: ${parsed.command.join(" ")}`);
   }
 }
 async function resolvePageRefByIndex(runtime, index) {
   const pages = (await runtime.listPages({})).pages;
   const page = pages[index - 1];
   if (page === void 0) {
-    throw new Error(`tab ${String(index)} does not exist.`);
+    throw new CliError("invalid_value", `tab ${String(index)} does not exist.`);
   }
   return page.pageRef;
 }
 function readRequiredPositiveInteger(value, message) {
   const parsed = readRequiredNumber(value, message);
   if (!Number.isInteger(parsed) || parsed < 1) {
-    throw new Error(message);
+    throw new CliError("missing_arguments", message);
   }
   return parsed;
 }
 function readRequiredNumber(value, message) {
   if (value === void 0) {
-    throw new Error(message);
+    throw new CliError("missing_arguments", message);
   }
   const parsed = Number(value);
   if (!Number.isFinite(parsed)) {
-    throw new Error(message);
+    throw new CliError("missing_arguments", message);
   }
   return parsed;
 }
 function readSingleDirection(value) {
   if (value === void 0 || !SCROLL_DIRECTIONS.has(value)) {
-    throw new Error("scroll requires a direction: up, down, left, or right.");
+    throw new CliError("missing_arguments", "scroll requires a direction: up, down, left, or right.");
   }
   return value;
 }
 function readClickButton(value) {
   if (value === void 0 || !CLICK_BUTTONS.has(value)) {
-    throw new Error('Expected "--button" to be one of: left, middle, right.');
+    throw new CliError("invalid_value", 'Expected "--button" to be one of: left, middle, right.');
   }
   return value;
 }
 function readFetchTransport(value) {
   if (value === void 0 || !FETCH_TRANSPORTS.has(value)) {
-    throw new Error(
+    throw new CliError(
+      "invalid_value",
       'Expected "--transport" to be one of: auto, direct, matched-tls, context, page.'
     );
   }
@@ -31579,31 +32032,31 @@ function readFetchTransport(value) {
 }
 function readCaptchaProvider(value) {
   if (value === void 0 || !CAPTCHA_PROVIDERS.has(value)) {
-    throw new Error('Expected "--provider" to be one of: 2captcha, capsolver.');
+    throw new CliError("invalid_value", 'Expected "--provider" to be one of: 2captcha, capsolver.');
   }
   return value;
 }
 function readCaptchaType(value) {
   if (value === void 0 || !CAPTCHA_TYPES.has(value)) {
-    throw new Error('Expected "--type" to be one of: recaptcha-v2, hcaptcha, turnstile.');
+    throw new CliError("invalid_value", 'Expected "--type" to be one of: recaptcha-v2, hcaptcha, turnstile.');
   }
   return value;
 }
 function readSandboxFidelity(value) {
   if (value === void 0 || !SANDBOX_FIDELITIES.has(value)) {
-    throw new Error('Expected "--fidelity" to be one of: minimal, standard, full.');
+    throw new CliError("invalid_value", 'Expected "--fidelity" to be one of: minimal, standard, full.');
   }
   return value;
 }
 function readSandboxClockMode(value) {
   if (value === void 0 || !SANDBOX_CLOCK_MODES.has(value)) {
-    throw new Error('Expected "--clock" to be one of: real, manual.');
+    throw new CliError("invalid_value", 'Expected "--clock" to be one of: real, manual.');
   }
   return value;
 }
 function readScreenshotFormat(value) {
   if (value === void 0 || !SCREENSHOT_FORMATS.has(value)) {
-    throw new Error('Expected "--format" to be one of: png, jpeg, webp.');
+    throw new CliError("invalid_value", 'Expected "--format" to be one of: png, jpeg, webp.');
   }
   return value;
 }
@@ -31614,7 +32067,7 @@ function readKeyModifiers(value) {
   }
   for (const modifier of modifiers) {
     if (!KEY_MODIFIERS.has(modifier)) {
-      throw new Error('Expected "--modifiers" to contain only: Shift, Control, Alt, Meta.');
+      throw new CliError("invalid_value", 'Expected "--modifiers" to contain only: Shift, Control, Alt, Meta.');
     }
   }
   return [...new Set(modifiers)];
@@ -31622,17 +32075,22 @@ function readKeyModifiers(value) {
 function readPersistKey(parsed, verb) {
   const value = readSingle(parsed.rawOptions, "persist");
   if (value === void 0) {
-    throw new Error(`${verb} requires "--persist <key>".`);
+    throw new CliError("missing_arguments", `${verb} requires "--persist <key>".`);
   }
   if (value === "true" || value === "false") {
-    throw new Error(`${verb} requires "--persist <key>".`);
+    throw new CliError("missing_arguments", `${verb} requires "--persist <key>".`);
   }
   return value;
 }
 function parseRequiredJsonObjectArgument(value, label) {
-  const parsed = JSON.parse(value);
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new CliError("invalid_value", `${label} contains invalid JSON.`);
+  }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`${label} must be a JSON object.`);
+    throw new CliError("invalid_value", `${label} must be a JSON object.`);
   }
   return parsed;
 }
@@ -34610,7 +35068,7 @@ async function handleViewCommand(parsed, options = {}) {
     return;
   }
   if (subcommand !== void 0) {
-    throw new Error(`Unknown view command: view ${subcommand}`);
+    throw new CliError("unknown_command", `Unknown view command: view ${subcommand}`);
   }
   if (parsed.options.localViewMode !== void 0) {
     const preference = await setLocalViewMode(parsed.options.localViewMode);
@@ -34658,7 +35116,10 @@ async function resolveWorkspaceSessionId(input) {
 }
 function assertNoViewPreferenceFlag(parsed) {
   if (parsed.options.localViewMode !== void 0) {
-    throw new Error("View preference flags cannot be combined with this subcommand.");
+    throw new CliError(
+      "invalid_option",
+      "View preference flags cannot be combined with this subcommand."
+    );
   }
 }
 function writeViewOutput(parsed, value) {
@@ -34743,10 +35204,10 @@ async function main() {
   }
   const operation = resolveOperation(parsed.command);
   if (!operation) {
-    throw new Error(`Unknown command: ${parsed.command.join(" ")}`);
+    throw new CliError("unknown_command", `Unknown command: ${parsed.command.join(" ")}`);
   }
   if (parsed.options.workspace === void 0) {
-    throw new Error('Stateful commands require "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError("missing_workspace", 'Stateful commands require "--workspace <id>" or OPENSTEER_WORKSPACE.');
   }
   const { engineName, provider, runtimeProvider } = resolveCliRuntimeSelection(parsed);
   if (operation === "session.close") {
@@ -34768,24 +35229,39 @@ async function main() {
   let renderOperation = operation;
   try {
     const input = await buildOperationInput(operation, parsed, runtime);
-    result = await dispatchSemanticOperation(runtime, operation, input);
+    const rawResult = await dispatchSemanticOperation(runtime, operation, input);
     if (parsed.command[0] === "tab" && operation !== "page.list") {
       renderOperation = "page.list";
       result = await runtime.listPages({});
+    } else {
+      result = rawResult;
+    }
+    let warning;
+    if (result !== null && typeof result === "object" && "warning" in result) {
+      const { warning: w, ...rest } = result;
+      if (typeof w === "string") {
+        warning = w;
+        result = rest;
+      }
     }
     process4__default.default.stdout.write(renderOperationOutput(renderOperation, result, input));
+    if (warning !== void 0) {
+      emitWarning(warning);
+    }
   } finally {
     await runtime.disconnect().catch(() => void 0);
   }
 }
 async function handleExecCommand(parsed) {
   if (parsed.options.workspace === void 0) {
-    throw new Error('exec requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError("missing_workspace", 'exec requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
   }
   const expression = parsed.rest.join(" ");
   if (!expression) {
-    throw new Error(
-      `exec requires an expression. Example: exec "await this.evaluate('document.title')"`
+    throw new CliError(
+      "missing_arguments",
+      "exec requires an expression.",
+      "opensteer exec <expression>"
     );
   }
   const { engineName, runtimeProvider } = resolveCliRuntimeSelection(parsed);
@@ -34821,8 +35297,10 @@ async function handleBrowserCommand(parsed) {
   if (subcommand === "inspect") {
     const endpoint = parsed.options.attachEndpoint ?? parsed.rest[0];
     if (!endpoint) {
-      throw new Error(
-        'browser inspect requires "--attach-endpoint <url>" or a positional endpoint.'
+      throw new CliError(
+        "missing_arguments",
+        'browser inspect requires "--attach-endpoint <url>" or a positional endpoint.',
+        "opensteer browser inspect <endpoint>"
       );
     }
     const result = await inspectCdpEndpoint({
@@ -34835,7 +35313,8 @@ async function handleBrowserCommand(parsed) {
     return;
   }
   if (parsed.options.workspace === void 0) {
-    throw new Error(
+    throw new CliError(
+      "missing_workspace",
       'Browser workspace commands require "--workspace <id>" or OPENSTEER_WORKSPACE.'
     );
   }
@@ -34858,7 +35337,11 @@ async function handleBrowserCommand(parsed) {
     case "clone": {
       const sourceUserDataDir = parsed.options.sourceUserDataDir;
       if (!sourceUserDataDir) {
-        throw new Error('browser clone requires "--source-user-data-dir <path>".');
+        throw new CliError(
+          "missing_arguments",
+          'browser clone requires "--source-user-data-dir <path>".',
+          "opensteer browser clone --source-user-data-dir <path>"
+        );
       }
       const result = await manager.clonePersistentBrowser({
         sourceUserDataDir,
@@ -34881,7 +35364,7 @@ async function handleBrowserCommand(parsed) {
       return;
     }
     default:
-      throw new Error(`Unknown browser command: ${parsed.command.join(" ")}`);
+      throw new CliError("unknown_command", `Unknown browser command: ${parsed.command.join(" ")}`);
   }
 }
 async function handleCloseCommand(parsed, engineName, providerMode, runtimeProvider) {
@@ -34914,23 +35397,27 @@ async function handleCloseCommand(parsed, engineName, providerMode, runtimeProvi
 }
 async function handleRecordCommandEntry(parsed) {
   if (parsed.options.workspace === void 0) {
-    throw new Error('record requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError("missing_workspace", 'record requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
   }
   const url = parsed.options.url ?? parsed.rest[0];
   if (url === void 0) {
-    throw new Error('record requires "--url <value>" or a positional URL.');
+    throw new CliError(
+      "missing_arguments",
+      'record requires "--url <value>" or a positional URL.',
+      "opensteer record --url <url> --workspace <id>"
+    );
   }
   const provider = resolveCliProvider(parsed);
   assertCloudCliOptionsMatchProvider(parsed, provider.mode);
   const engineName = resolveCliEngineName(parsed);
   if (engineName !== "playwright") {
-    throw new Error("record requires engine=playwright.");
+    throw new CliError("config_conflict", "record requires engine=playwright.");
   }
   const rootDir = process4__default.default.cwd();
   const recordBrowser = parsed.options.browser;
   if (provider.mode === "cloud") {
     if (typeof recordBrowser === "object") {
-      throw new Error('record does not support browser.mode="attach".');
+      throw new CliError("config_conflict", 'record does not support browser.mode="attach".');
     }
     const runtimeProvider = buildCliRuntimeProvider(parsed, provider.mode);
     const runtimeConfig = resolveOpensteerRuntimeConfig({
@@ -34950,10 +35437,10 @@ async function handleRecordCommandEntry(parsed) {
     return;
   }
   if (parsed.options.launch?.headless === true) {
-    throw new Error('record requires a headed browser. Remove "--headless true".');
+    throw new CliError("config_conflict", 'record requires a headed browser. Remove "--headless true".');
   }
   if (typeof recordBrowser === "object") {
-    throw new Error('record does not support browser.mode="attach".');
+    throw new CliError("config_conflict", 'record does not support browser.mode="attach".');
   }
   const launch = {
     ...parsed.options.launch ?? {},
@@ -35022,7 +35509,7 @@ function resolveCliBootstrapAction(argv) {
 }
 function buildCliBrowserProfile(parsed) {
   if (parsed.options.cloudProfileReuseIfActive === true && parsed.options.cloudProfileId === void 0) {
-    throw new Error('"--cloud-profile-reuse-if-active" requires "--cloud-profile-id <id>".');
+    throw new CliError("invalid_option", '"--cloud-profile-reuse-if-active" requires "--cloud-profile-id <id>".');
   }
   return parsed.options.cloudProfileId === void 0 ? void 0 : {
     profileId: parsed.options.cloudProfileId,
@@ -35083,7 +35570,8 @@ function buildCliRuntimeProvider(parsed, providerMode) {
 }
 function assertCloudCliOptionsMatchProvider(parsed, providerMode) {
   if (providerMode !== "cloud" && (parsed.options.cloudBaseUrl !== void 0 || parsed.options.cloudApiKey !== void 0 || parsed.options.cloudAppBaseUrl !== void 0 || parsed.options.cloudProfileId !== void 0 || parsed.options.cloudProfileReuseIfActive === true)) {
-    throw new Error(
+    throw new CliError(
+      "config_conflict",
       'Cloud-specific options require provider=cloud. Set "--provider cloud" or OPENSTEER_PROVIDER=cloud.'
     );
   }
@@ -35117,17 +35605,7 @@ function printVersion() {
 `);
 }
 main().catch((error) => {
-  const payload = error instanceof Error ? {
-    error: {
-      name: error.name,
-      message: error.message
-    }
-  } : {
-    error: {
-      name: "Error",
-      message: String(error)
-    }
-  };
+  const payload = formatCliErrorOutput(error);
   process4__default.default.stderr.write(`${JSON.stringify(payload)}
 `);
   process4__default.default.exitCode = 1;