opensteer 0.9.5 → 0.9.7

package/dist/cli/bin.cjs

@@ -1662,31 +1662,131 @@ function isAlreadyExistsError(error) {
 }
 async function withFilesystemLock(lockPath, task) {
   await ensureDirectory(path10__default.default.dirname(lockPath));
+  const ownerToken = crypto.randomUUID();
   let attempt = 0;
   while (true) {
     try {
       await promises.mkdir(lockPath);
+      const acquiredAt = Date.now();
+      await writeLockMetadata(lockPath, {
+        version: LOCK_METADATA_VERSION,
+        ownerToken,
+        pid: process.pid,
+        acquiredAt,
+        heartbeatAt: acquiredAt
+      });
       break;
     } catch (error) {
       if (!isAlreadyExistsError(error)) {
         throw error;
       }
+      if (await tryRecoverFilesystemLock(lockPath)) {
+        attempt = 0;
+        continue;
+      }
       const delayMs = LOCK_RETRY_DELAYS_MS[Math.min(attempt, LOCK_RETRY_DELAYS_MS.length - 1)];
       attempt += 1;
       await new Promise((resolve4) => setTimeout(resolve4, delayMs));
     }
   }
+  const heartbeatTimer = setInterval(() => {
+    void touchLockMetadata(lockPath, ownerToken);
+  }, LOCK_HEARTBEAT_INTERVAL_MS);
+  heartbeatTimer.unref?.();
   try {
     return await task();
   } finally {
-    await promises.rm(lockPath, { recursive: true, force: true });
+    clearInterval(heartbeatTimer);
+    const metadata = await readLockMetadata(lockPath);
+    if (metadata?.ownerToken === ownerToken) {
+      await promises.rm(lockPath, { recursive: true, force: true });
+    }
   }
 }
-var LOCK_RETRY_DELAYS_MS;
+async function tryRecoverFilesystemLock(lockPath) {
+  if (!await shouldRecoverFilesystemLock(lockPath)) {
+    return false;
+  }
+  await promises.rm(lockPath, { recursive: true, force: true });
+  return true;
+}
+async function shouldRecoverFilesystemLock(lockPath) {
+  const metadata = await readLockMetadata(lockPath);
+  if (metadata !== void 0) {
+    if (isProcessRunning2(metadata.pid)) {
+      return false;
+    }
+    return Date.now() - metadata.heartbeatAt >= LOCK_ORPHAN_GRACE_MS;
+  }
+  const lockStat = await promises.stat(lockPath).catch(() => void 0);
+  if (lockStat === void 0) {
+    return false;
+  }
+  return Date.now() - lockStat.mtimeMs >= LOCK_METADATALESS_STALE_MS;
+}
+async function readLockMetadata(lockPath) {
+  const metadataPath = path10__default.default.join(lockPath, LOCK_METADATA_FILENAME);
+  if (!await pathExists(metadataPath)) {
+    return void 0;
+  }
+  try {
+    const parsed = await readJsonFile(metadataPath);
+    const pid = parsed.pid;
+    const acquiredAt = parsed.acquiredAt;
+    const heartbeatAt = parsed.heartbeatAt;
+    if (parsed.version !== LOCK_METADATA_VERSION || typeof parsed.ownerToken !== "string" || parsed.ownerToken.length === 0 || typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0 || typeof acquiredAt !== "number" || !Number.isFinite(acquiredAt) || typeof heartbeatAt !== "number" || !Number.isFinite(heartbeatAt)) {
+      return void 0;
+    }
+    return {
+      version: LOCK_METADATA_VERSION,
+      ownerToken: parsed.ownerToken,
+      pid,
+      acquiredAt,
+      heartbeatAt
+    };
+  } catch {
+    return void 0;
+  }
+}
+async function writeLockMetadata(lockPath, metadata) {
+  try {
+    await writeJsonFileAtomic(path10__default.default.join(lockPath, LOCK_METADATA_FILENAME), metadata);
+  } catch (error) {
+    await promises.rm(lockPath, { recursive: true, force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+async function touchLockMetadata(lockPath, ownerToken) {
+  const metadata = await readLockMetadata(lockPath);
+  if (metadata === void 0 || metadata.ownerToken !== ownerToken) {
+    return;
+  }
+  await writeJsonFileAtomic(path10__default.default.join(lockPath, LOCK_METADATA_FILENAME), {
+    ...metadata,
+    heartbeatAt: Date.now()
+  }).catch(() => void 0);
+}
+function isProcessRunning2(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+var LOCK_RETRY_DELAYS_MS, LOCK_METADATA_FILENAME, LOCK_METADATA_VERSION, LOCK_HEARTBEAT_INTERVAL_MS, LOCK_ORPHAN_GRACE_MS, LOCK_METADATALESS_STALE_MS;
 var init_filesystem = __esm({
   "../runtime-core/src/internal/filesystem.ts"() {
     init_json();
     LOCK_RETRY_DELAYS_MS = [1, 2, 5, 10, 20, 50];
+    LOCK_METADATA_FILENAME = "owner.json";
+    LOCK_METADATA_VERSION = 1;
+    LOCK_HEARTBEAT_INTERVAL_MS = 1e3;
+    LOCK_ORPHAN_GRACE_MS = 2e3;
+    LOCK_METADATALESS_STALE_MS = 3e4;
   }
 });
 function normalizeScope(scope) {
@@ -2294,7 +2394,7 @@ var init_version = __esm({
   "../protocol/src/version.ts"() {
     init_json2();
     OPENSTEER_PROTOCOL_NAME = "opensteer";
-    OPENSTEER_PROTOCOL_COMPATIBILITY_REVISION = 2;
+    OPENSTEER_PROTOCOL_COMPATIBILITY_REVISION = 3;
     OPENSTEER_PROTOCOL_VERSION = `0.${OPENSTEER_PROTOCOL_COMPATIBILITY_REVISION}.0`;
     OPENSTEER_PROTOCOL_MEDIA_TYPE = `application/vnd.${OPENSTEER_PROTOCOL_NAME}+json;version=${OPENSTEER_PROTOCOL_VERSION}`;
     OPENSTEER_PROTOCOL_REST_BASE_PATH = `/api/v${OPENSTEER_PROTOCOL_COMPATIBILITY_REVISION}`;
@@ -2598,10 +2698,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;
   }
 });
 
@@ -6679,15 +6777,15 @@ function assertValidSemanticOperationInput(name, input) {
     }
   );
 }
-var opensteerComputerAnnotationNames, opensteerExposedSemanticOperationNames, opensteerPackageRunnableSemanticOperationNames, snapshotModeSchema, viewportSchema, opensteerBrowserLaunchOptionsSchema, attachBrowserOptionsSchema, opensteerBrowserOptionsSchema, opensteerBrowserContextOptionsSchema, targetByElementSchema2, targetByPersistSchema2, targetBySelectorSchema2, opensteerTargetInputSchema, opensteerResolvedTargetSchema, opensteerActionResultSchema, opensteerSnapshotCounterSchema, opensteerSessionStateSchema, opensteerOpenInputSchema, opensteerPageListInputSchema, opensteerPageListOutputSchema, opensteerPageNewInputSchema, opensteerPageActivateInputSchema, opensteerPageCloseInputSchema, opensteerPageCloseOutputSchema, opensteerPageGotoInputSchema, opensteerPageEvaluateInputSchema, opensteerPageEvaluateOutputSchema, opensteerAddInitScriptInputSchema, opensteerAddInitScriptOutputSchema, opensteerCapturedScriptSchema, opensteerCaptureScriptsInputSchema, opensteerCaptureScriptsOutputSchema, opensteerPageSnapshotInputSchema, opensteerPageSnapshotOutputSchema, opensteerComputerMouseButtonSchema, opensteerComputerKeyModifierSchema, opensteerDomClickInputSchema, opensteerDomHoverInputSchema, opensteerDomInputInputSchema, opensteerDomScrollInputSchema, opensteerExtractTemplateSchema, opensteerDomExtractInputSchema, jsonValueSchema2, opensteerDomExtractOutputSchema, opensteerSessionCloseInputSchema, opensteerSessionCloseOutputSchema, opensteerComputerAnnotationSchema, opensteerComputerClickActionSchema, opensteerComputerMoveActionSchema, opensteerComputerScrollActionSchema, opensteerComputerTypeActionSchema, opensteerComputerKeyActionSchema, opensteerComputerDragActionSchema, opensteerComputerScreenshotActionSchema, opensteerComputerWaitActionSchema, opensteerComputerActionSchema, opensteerComputerScreenshotOptionsSchema, opensteerComputerExecuteInputSchema, opensteerComputerTracePointSchema, opensteerComputerTraceEnrichmentSchema, opensteerComputerExecuteTimingSchema, opensteerComputerDisplayScaleSchema, opensteerComputerExecuteOutputSchema, opensteerSemanticOperationSpecificationsBase, exposedSemanticOperationNameSet, opensteerSemanticOperationSpecificationsInternal, opensteerSemanticOperationSpecifications, opensteerSemanticOperationSpecificationMap, semanticRestBasePath, opensteerSemanticRestEndpoints;
+var opensteerComputerAnnotationNames, opensteerExposedSemanticOperationNames, opensteerPackageRunnableSemanticOperationNames, snapshotModeSchema, viewportSchema, opensteerBrowserLaunchOptionsSchema, attachBrowserOptionsSchema, opensteerBrowserOptionsSchema, opensteerBrowserContextOptionsSchema, targetByElementSchema2, targetByPersistSchema2, targetBySelectorSchema2, opensteerTargetInputSchema, opensteerActionResultSchema, opensteerSnapshotCounterSchema, opensteerNavigationSummarySchema, opensteerOpenInputSchema, opensteerPageListInputSchema, opensteerPageListOutputSchema, opensteerPageNewInputSchema, opensteerPageActivateInputSchema, opensteerPageCloseInputSchema, opensteerPageCloseOutputSchema, opensteerPageNewOutputSchema, opensteerPageGotoInputSchema, opensteerPageEvaluateInputSchema, opensteerPageEvaluateOutputSchema, opensteerAddInitScriptInputSchema, opensteerAddInitScriptOutputSchema, opensteerCapturedScriptSchema, opensteerCaptureScriptsInputSchema, opensteerCaptureScriptsOutputSchema, opensteerPageSnapshotInputSchema, opensteerPageSnapshotOutputSchema, opensteerComputerMouseButtonSchema, opensteerComputerKeyModifierSchema, opensteerDomClickInputSchema, opensteerDomHoverInputSchema, opensteerDomInputInputSchema, opensteerDomScrollInputSchema, opensteerExtractTemplateSchema, opensteerDomExtractInputSchema, jsonValueSchema2, opensteerDomExtractOutputSchema, opensteerSessionCloseInputSchema, opensteerSessionCloseOutputSchema, opensteerComputerAnnotationSchema, opensteerComputerClickActionSchema, opensteerComputerMoveActionSchema, opensteerComputerScrollActionSchema, opensteerComputerTypeActionSchema, opensteerComputerKeyActionSchema, opensteerComputerDragActionSchema, opensteerComputerScreenshotActionSchema, opensteerComputerWaitActionSchema, opensteerComputerActionSchema, opensteerComputerScreenshotOptionsSchema, opensteerComputerExecuteInputSchema, opensteerScreenshotSummarySchema, opensteerComputerExecuteOutputSchema, opensteerSemanticOperationSpecificationsBase, exposedSemanticOperationNameSet, opensteerSemanticOperationSpecificationsInternal, opensteerSemanticOperationSpecifications, opensteerSemanticOperationSpecificationMap, semanticRestBasePath, opensteerSemanticRestEndpoints;
 var init_semantic = __esm({
   "../protocol/src/semantic.ts"() {
     init_json2();
     init_errors2();
+    init_binary_location();
     init_identity2();
     init_geometry2();
     init_metadata2();
-    init_events2();
     init_envelopes();
     init_snapshots2();
     init_artifacts2();
@@ -6911,39 +7009,14 @@ var init_semantic = __esm({
         title: "OpensteerTargetInput"
       }
     );
-    opensteerResolvedTargetSchema = objectSchema(
-      {
-        pageRef: pageRefSchema,
-        frameRef: frameRefSchema,
-        documentRef: documentRefSchema,
-        documentEpoch: documentEpochSchema,
-        nodeRef: nodeRefSchema,
-        tagName: stringSchema(),
-        pathHint: stringSchema(),
-        persist: stringSchema(),
-        selectorUsed: stringSchema()
-      },
-      {
-        title: "OpensteerResolvedTarget",
-        required: [
-          "pageRef",
-          "frameRef",
-          "documentRef",
-          "documentEpoch",
-          "nodeRef",
-          "tagName",
-          "pathHint"
-        ]
-      }
-    );
     opensteerActionResultSchema = objectSchema(
       {
-        target: opensteerResolvedTargetSchema,
-        point: pointSchema
+        tagName: stringSchema({ minLength: 1 }),
+        persist: stringSchema({ minLength: 1 })
       },
       {
         title: "OpensteerActionResult",
-        required: ["target"]
+        required: ["tagName"]
       }
     );
     opensteerSnapshotCounterSchema = objectSchema(
@@ -6989,16 +7062,14 @@ var init_semantic = __esm({
         ]
       }
     );
-    opensteerSessionStateSchema = objectSchema(
+    opensteerNavigationSummarySchema = objectSchema(
       {
-        sessionRef: sessionRefSchema,
-        pageRef: pageRefSchema,
         url: stringSchema(),
         title: stringSchema()
       },
       {
-        title: "OpensteerSessionState",
-        required: ["sessionRef", "pageRef", "url", "title"]
+        title: "OpensteerNavigationSummary",
+        required: ["url", "title"]
       }
     );
     opensteerOpenInputSchema = objectSchema(
@@ -7066,6 +7137,17 @@ var init_semantic = __esm({
         required: ["closedPageRef", "pages"]
       }
     );
+    opensteerPageNewOutputSchema = objectSchema(
+      {
+        pageRef: pageRefSchema,
+        url: stringSchema(),
+        title: stringSchema()
+      },
+      {
+        title: "OpensteerPageNewOutput",
+        required: ["pageRef", "url", "title"]
+      }
+    );
     opensteerPageGotoInputSchema = objectSchema(
       {
         url: stringSchema(),
@@ -7452,72 +7534,28 @@ var init_semantic = __esm({
         required: ["action"]
       }
     );
-    opensteerComputerTracePointSchema = objectSchema(
-      {
-        role: enumSchema(["point", "start", "end"]),
-        point: pointSchema,
-        hitTest: hitTestResultSchema,
-        target: opensteerResolvedTargetSchema
-      },
-      {
-        title: "OpensteerComputerTracePoint",
-        required: ["role", "point"]
-      }
-    );
-    opensteerComputerTraceEnrichmentSchema = objectSchema(
+    opensteerScreenshotSummarySchema = objectSchema(
       {
-        points: arraySchema(opensteerComputerTracePointSchema)
-      },
-      {
-        title: "OpensteerComputerTraceEnrichment",
-        required: ["points"]
-      }
-    );
-    opensteerComputerExecuteTimingSchema = objectSchema(
-      {
-        actionMs: integerSchema({ minimum: 0 }),
-        waitMs: integerSchema({ minimum: 0 }),
-        totalMs: integerSchema({ minimum: 0 })
-      },
-      {
-        title: "OpensteerComputerExecuteTiming",
-        required: ["actionMs", "waitMs", "totalMs"]
-      }
-    );
-    opensteerComputerDisplayScaleSchema = objectSchema(
-      {
-        x: numberSchema({ exclusiveMinimum: 0 }),
-        y: numberSchema({ exclusiveMinimum: 0 })
+        payload: externalBinaryLocationSchema,
+        format: screenshotFormatSchema,
+        size: sizeSchema,
+        coordinateSpace: coordinateSpaceSchema,
+        clip: rectSchema
       },
       {
-        title: "OpensteerComputerDisplayScale",
-        required: ["x", "y"]
+        title: "OpensteerScreenshotSummary",
+        required: ["payload", "format", "size", "coordinateSpace"]
       }
     );
     opensteerComputerExecuteOutputSchema = objectSchema(
       {
-        action: opensteerComputerActionSchema,
-        pageRef: pageRefSchema,
-        screenshot: screenshotArtifactSchema,
-        displayViewport: viewportMetricsSchema,
-        nativeViewport: viewportMetricsSchema,
-        displayScale: opensteerComputerDisplayScaleSchema,
-        events: arraySchema(opensteerEventSchema),
-        timing: opensteerComputerExecuteTimingSchema,
-        trace: opensteerComputerTraceEnrichmentSchema
+        url: stringSchema(),
+        title: stringSchema(),
+        screenshot: opensteerScreenshotSummarySchema
       },
       {
         title: "OpensteerComputerExecuteOutput",
-        required: [
-          "action",
-          "pageRef",
-          "screenshot",
-          "displayViewport",
-          "nativeViewport",
-          "displayScale",
-          "events",
-          "timing"
-        ]
+        required: ["url", "title", "screenshot"]
       }
     );
     opensteerSemanticOperationSpecificationsBase = [
@@ -7525,7 +7563,7 @@ var init_semantic = __esm({
         name: "session.open",
         description: "Open or resume the current Opensteer session and primary page.",
         inputSchema: opensteerOpenInputSchema,
-        outputSchema: opensteerSessionStateSchema,
+        outputSchema: opensteerNavigationSummarySchema,
         requiredCapabilities: ["sessions.manage", "pages.manage"],
         resolveRequiredCapabilities: (input) => input.url === void 0 ? ["sessions.manage", "pages.manage"] : ["sessions.manage", "pages.manage", "pages.navigate"]
       }),
@@ -7540,7 +7578,7 @@ var init_semantic = __esm({
         name: "page.new",
         description: "Create and optionally navigate a new top-level page in the current session.",
         inputSchema: opensteerPageNewInputSchema,
-        outputSchema: opensteerSessionStateSchema,
+        outputSchema: opensteerPageNewOutputSchema,
         requiredCapabilities: ["pages.manage"],
         resolveRequiredCapabilities: (input) => input.url === void 0 ? ["pages.manage"] : ["pages.manage", "pages.navigate"]
       }),
@@ -7548,7 +7586,7 @@ var init_semantic = __esm({
         name: "page.activate",
         description: "Activate an existing top-level page in the current session.",
         inputSchema: opensteerPageActivateInputSchema,
-        outputSchema: opensteerSessionStateSchema,
+        outputSchema: opensteerNavigationSummarySchema,
         requiredCapabilities: ["pages.manage", "inspect.pages"]
       }),
       defineSemanticOperationSpec({
@@ -7562,7 +7600,7 @@ var init_semantic = __esm({
         name: "page.goto",
         description: "Navigate the current Opensteer page to a new URL.",
         inputSchema: opensteerPageGotoInputSchema,
-        outputSchema: opensteerSessionStateSchema,
+        outputSchema: opensteerNavigationSummarySchema,
         requiredCapabilities: ["pages.navigate"]
       }),
       defineSemanticOperationSpec({
@@ -9804,16 +9842,37 @@ async function writePersistedSessionRecord(rootPath, record) {
 async function clearPersistedSessionRecord(rootPath, provider) {
   await promises.rm(resolveLiveSessionRecordPath(rootPath, provider), { force: true });
 }
+function getPersistedLocalBrowserSessionOwnership(record) {
+  return record.ownership === "attached" ? "attached" : "owned";
+}
+async function isAttachedLocalBrowserSessionReachable(record) {
+  if (getPersistedLocalBrowserSessionOwnership(record) !== "attached") {
+    return false;
+  }
+  if (record.engine !== "playwright" || record.endpoint === void 0) {
+    return false;
+  }
+  try {
+    await inspectCdpEndpoint({
+      endpoint: record.endpoint,
+      timeoutMs: 1500
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
 function isPersistedCloudSessionRecord(value) {
   return value.layout === OPENSTEER_LIVE_SESSION_LAYOUT && value.version === OPENSTEER_LIVE_SESSION_VERSION && value.provider === "cloud" && typeof value.sessionId === "string" && value.sessionId.length > 0 && typeof value.startedAt === "number" && Number.isFinite(value.startedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt);
 }
 function isPersistedLocalBrowserSessionRecord(value) {
-  return value.layout === OPENSTEER_LIVE_SESSION_LAYOUT && value.version === OPENSTEER_LIVE_SESSION_VERSION && value.provider === "local" && (value.engine === "playwright" || value.engine === "abp") && typeof value.pid === "number" && Number.isFinite(value.pid) && typeof value.startedAt === "number" && Number.isFinite(value.startedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt) && typeof value.userDataDir === "string" && value.userDataDir.length > 0;
+  return value.layout === OPENSTEER_LIVE_SESSION_LAYOUT && value.version === OPENSTEER_LIVE_SESSION_VERSION && value.provider === "local" && (value.engine === "playwright" || value.engine === "abp") && (value.ownership === void 0 || value.ownership === "owned" || value.ownership === "attached") && typeof value.pid === "number" && Number.isFinite(value.pid) && typeof value.startedAt === "number" && Number.isFinite(value.startedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt) && typeof value.userDataDir === "string" && value.userDataDir.length > 0;
 }
 var OPENSTEER_LIVE_SESSION_LAYOUT, OPENSTEER_LIVE_SESSION_VERSION;
 var init_live_session = __esm({
   "src/live-session.ts"() {
     init_filesystem2();
+    init_cdp_discovery();
     OPENSTEER_LIVE_SESSION_LAYOUT = "opensteer-session";
     OPENSTEER_LIVE_SESSION_VERSION = 1;
   }
@@ -10302,19 +10361,40 @@ var init_service = __esm({
   }
 });
 function buildLocalViewSessionId(input) {
+  const ownership = input.ownership ?? "owned";
+  const identity = ownership === "attached" ? input.endpoint ?? input.remoteDebuggingUrl ?? input.baseUrl ?? "attached" : `pid:${String(input.pid ?? 0)}`;
   const hash = crypto.createHash("sha256").update(`${input.rootPath}
-${String(input.pid)}
+${ownership}
+${identity}
 ${String(input.startedAt)}`).digest("hex");
   return `local_${hash.slice(0, 24)}`;
 }
+function buildLocalViewSessionIdForRecord(input) {
+  const ownership = getPersistedLocalBrowserSessionOwnership(input.live);
+  if (ownership === "attached") {
+    return buildLocalViewSessionId({
+      rootPath: input.rootPath,
+      ownership,
+      startedAt: input.live.startedAt,
+      ...input.live.endpoint === void 0 ? {} : { endpoint: input.live.endpoint },
+      ...input.live.baseUrl === void 0 ? {} : { baseUrl: input.live.baseUrl },
+      ...input.live.remoteDebuggingUrl === void 0 ? {} : { remoteDebuggingUrl: input.live.remoteDebuggingUrl }
+    });
+  }
+  return buildLocalViewSessionId({
+    rootPath: input.rootPath,
+    ownership,
+    startedAt: input.live.startedAt,
+    pid: input.live.pid
+  });
+}
 function createLocalViewSessionManifest(input) {
   return {
     layout: OPENSTEER_LOCAL_VIEW_SESSION_LAYOUT,
     version: OPENSTEER_LOCAL_VIEW_SESSION_VERSION,
-    sessionId: buildLocalViewSessionId({
+    sessionId: buildLocalViewSessionIdForRecord({
       rootPath: input.rootPath,
-      pid: input.live.pid,
-      startedAt: input.live.startedAt
+      live: input.live
     }),
     rootPath: input.rootPath,
     ...input.workspace === void 0 ? {} : { workspace: input.workspace },
@@ -10365,6 +10445,7 @@ var OPENSTEER_LOCAL_VIEW_SESSION_LAYOUT, OPENSTEER_LOCAL_VIEW_SESSION_VERSION;
 var init_session_manifest = __esm({
   "src/local-view/session-manifest.ts"() {
     init_filesystem2();
+    init_live_session();
     init_runtime_dir();
     OPENSTEER_LOCAL_VIEW_SESSION_LAYOUT = "opensteer-local-view-session";
     OPENSTEER_LOCAL_VIEW_SESSION_VERSION = 1;
@@ -10413,7 +10494,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 +10504,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 +10513,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 +10572,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";
   }
@@ -10529,6 +10614,7 @@ function toPersistedLocalBrowserSessionRecord(workspace, live) {
     version: 1,
     provider: "local",
     ...workspace === void 0 ? {} : { workspace },
+    ownership: live.ownership,
     engine: live.engine,
     ...live.endpoint === void 0 ? {} : { endpoint: live.endpoint },
     ...live.baseUrl === void 0 ? {} : { baseUrl: live.baseUrl },
@@ -10544,6 +10630,7 @@ function toPersistedLocalBrowserSessionRecord(workspace, live) {
 function toWorkspaceLiveBrowserRecord(record) {
   return {
     mode: "persistent",
+    ownership: getPersistedLocalBrowserSessionOwnership(record),
     engine: record.engine,
     ...record.endpoint === void 0 ? {} : { endpoint: record.endpoint },
     ...record.baseUrl === void 0 ? {} : { baseUrl: record.baseUrl },
@@ -10570,7 +10657,12 @@ function isAttachBrowserOptions(browser) {
 async function resolveAttachEndpoint(browser) {
   const endpoint = browser?.endpoint?.trim();
   if (endpoint && endpoint.length > 0) {
-    return endpoint;
+    const inspected = await inspectCdpEndpoint({
+      endpoint,
+      ...browser?.headers === void 0 ? {} : { headers: browser.headers },
+      timeoutMs: DEFAULT_TIMEOUT_MS
+    });
+    return inspected.endpoint;
   }
   const selection = await selectAttachBrowserCandidate({
     timeoutMs: DEFAULT_TIMEOUT_MS
@@ -10996,7 +11088,7 @@ var init_browser_manager = __esm({
         }
         const liveRecord = await this.readLivePersistentBrowser(await this.ensureWorkspaceStore());
         return {
-          mode: this.mode,
+          mode: liveRecord?.ownership === "attached" ? "attach" : this.mode,
           engine: liveRecord?.engine ?? this.engineName,
           ...this.workspace === void 0 ? {} : { workspace: this.workspace },
           live: liveRecord !== void 0
@@ -11124,6 +11216,7 @@ var init_browser_manager = __esm({
           });
           const liveRecord = {
             mode: "persistent",
+            ownership: "owned",
             engine: "abp",
             baseUrl: launched.baseUrl,
             remoteDebuggingUrl: launched.remoteDebuggingUrl,
@@ -11210,11 +11303,78 @@ var init_browser_manager = __esm({
       }
       async createAttachEngine() {
         const endpoint = await resolveAttachEndpoint(this.browserOptions);
-        return this.createAttachedEngine({
-          endpoint,
-          ...this.browserOptions?.headers === void 0 ? {} : { headers: this.browserOptions.headers },
-          freshTab: this.browserOptions?.freshTab ?? true,
-          onDispose: async () => void 0
+        if (this.workspace === void 0) {
+          return this.createAttachedEngine({
+            endpoint,
+            ...this.browserOptions?.headers === void 0 ? {} : { headers: this.browserOptions.headers },
+            freshTab: this.browserOptions?.freshTab ?? true,
+            onDispose: async () => void 0
+          });
+        }
+        const workspace = await this.ensureWorkspaceStore();
+        return workspace.lock(async () => {
+          const live = await this.readLivePersistentBrowser(workspace);
+          if (live) {
+            if (live.engine !== "playwright") {
+              throw new Error(
+                `workspace "${this.workspace}" already has a live ${live.engine} browser. Close it before attaching a Playwright browser.`
+              );
+            }
+            if (live.ownership !== "attached") {
+              throw new Error(
+                `workspace "${this.workspace}" already has a live Opensteer-owned browser. Close it before attaching another browser.`
+              );
+            }
+            if (live.endpoint === void 0) {
+              throw new Error("workspace live browser record is missing a DevTools endpoint.");
+            }
+            if (live.endpoint !== endpoint) {
+              throw new Error(
+                `workspace "${this.workspace}" is already attached to a different browser endpoint. Close it before reattaching.`
+              );
+            }
+            await bestEffortRegisterLocalViewSession({
+              rootPath: workspace.rootPath,
+              ...this.workspace === void 0 ? {} : { workspace: this.workspace },
+              live: toPersistedLocalBrowserSessionRecord(this.workspace, live),
+              ownership: "attached"
+            });
+            return this.createAttachedEngine({
+              endpoint: live.endpoint,
+              ...this.browserOptions?.headers === void 0 ? {} : { headers: this.browserOptions.headers },
+              freshTab: this.browserOptions?.freshTab ?? true,
+              onDispose: async () => void 0
+            });
+          }
+          const liveRecord = {
+            mode: "persistent",
+            ownership: "attached",
+            engine: "playwright",
+            endpoint,
+            pid: 0,
+            startedAt: Date.now(),
+            userDataDir: workspace.browserUserDataDir
+          };
+          await this.writeLivePersistentBrowser(workspace, liveRecord);
+          const persistedLiveRecord = toPersistedLocalBrowserSessionRecord(this.workspace, liveRecord);
+          await bestEffortRegisterLocalViewSession({
+            rootPath: workspace.rootPath,
+            ...this.workspace === void 0 ? {} : { workspace: this.workspace },
+            live: persistedLiveRecord,
+            ownership: "attached"
+          });
+          try {
+            return await this.createAttachedEngine({
+              endpoint,
+              ...this.browserOptions?.headers === void 0 ? {} : { headers: this.browserOptions.headers },
+              freshTab: this.browserOptions?.freshTab ?? true,
+              onDispose: async () => void 0
+            });
+          } catch (error) {
+            await this.unregisterLocalViewSessionForRecord(workspace.rootPath, persistedLiveRecord);
+            await clearPersistedSessionRecord(workspace.rootPath, "local").catch(() => void 0);
+            throw error;
+          }
         });
       }
       async createPersistentEngine() {
@@ -11234,7 +11394,7 @@ var init_browser_manager = __esm({
               rootPath: workspace.rootPath,
               ...this.workspace === void 0 ? {} : { workspace: this.workspace },
               live: toPersistedLocalBrowserSessionRecord(this.workspace, live),
-              ownership: "owned"
+              ownership: live.ownership
             });
             return this.createAttachedEngine({
               endpoint: live.endpoint,
@@ -11250,6 +11410,7 @@ var init_browser_manager = __esm({
           });
           const liveRecord = {
             mode: "persistent",
+            ownership: "owned",
             engine: "playwright",
             endpoint: launched.endpoint,
             pid: launched.pid,
@@ -11379,7 +11540,20 @@ var init_browser_manager = __esm({
         if (live === void 0) {
           return void 0;
         }
+        if (live.ownership === "attached") {
+          const attachedRecord = toPersistedLocalBrowserSessionRecord(this.workspace, live);
+          if (!await isAttachedLocalBrowserSessionReachable(attachedRecord)) {
+            await this.unregisterLocalViewSessionForRecord(workspace.rootPath, attachedRecord);
+            await clearPersistedSessionRecord(workspace.rootPath, "local").catch(() => void 0);
+            return void 0;
+          }
+          return live;
+        }
         if (!isProcessRunning(live.pid)) {
+          await this.unregisterLocalViewSessionForRecord(
+            workspace.rootPath,
+            toPersistedLocalBrowserSessionRecord(this.workspace, live)
+          );
           await clearPersistedSessionRecord(workspace.rootPath, "local").catch(() => void 0);
           return void 0;
         }
@@ -11427,6 +11601,10 @@ var init_browser_manager = __esm({
           workspace.rootPath,
           toPersistedLocalBrowserSessionRecord(this.workspace, live)
         );
+        if (live.ownership === "attached") {
+          await clearPersistedSessionRecord(workspace.rootPath, "local").catch(() => void 0);
+          return;
+        }
         if (live.engine === "playwright") {
           if (live.endpoint !== void 0) {
             await requestBrowserClose(live.endpoint).catch(() => void 0);
@@ -11455,10 +11633,18 @@ var init_browser_manager = __esm({
       }
       async unregisterLocalViewSessionForRecord(rootPath, record) {
         await bestEffortUnregisterLocalViewSession(
-          buildLocalViewSessionId({
+          getPersistedLocalBrowserSessionOwnership(record) === "attached" ? buildLocalViewSessionId({
             rootPath,
-            pid: record.pid,
-            startedAt: record.startedAt
+            startedAt: record.startedAt,
+            ownership: "attached",
+            ...record.endpoint === void 0 ? {} : { endpoint: record.endpoint },
+            ...record.baseUrl === void 0 ? {} : { baseUrl: record.baseUrl },
+            ...record.remoteDebuggingUrl === void 0 ? {} : { remoteDebuggingUrl: record.remoteDebuggingUrl }
+          }) : buildLocalViewSessionId({
+            rootPath,
+            startedAt: record.startedAt,
+            ownership: "owned",
+            pid: record.pid
           })
         );
       }
@@ -11472,7 +11658,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 +11669,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 +11695,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 +12157,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 +12386,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 +12461,7 @@ var init_package = __esm({
   "../runtime-core/package.json"() {
     package_default2 = {
       name: "@opensteer/runtime-core",
-      version: "0.2.4",
+      version: "0.2.6",
       description: "Shared semantic runtime for Opensteer local and cloud execution.",
       license: "MIT",
       type: "module",
@@ -12372,7 +12613,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,30 +12642,15 @@ 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 },
-      "dom.scroll": { settleMs: 600, scope: "visible-frames", timeoutMs: 7e3 },
+      "dom.click": { settleMs: 750, scope: "main-frame", timeoutMs: 7e3 },
+      "dom.input": { settleMs: 750, scope: "main-frame", timeoutMs: 7e3 },
+      "dom.scroll": { settleMs: 600, scope: "main-frame", timeoutMs: 7e3 },
       "dom.hover": { settleMs: 200, scope: "main-frame", timeoutMs: 2500 }
     };
     DEFAULT_DOM_ACTION_VISUAL_STABILITY_PROFILE = {
       settleMs: 750,
-      scope: "visible-frames",
+      scope: "main-frame",
       timeoutMs: 7e3
     };
     NAVIGATION_VISUAL_STABILITY_PROFILE = {
@@ -12448,6 +12674,7 @@ var init_defaults = __esm({
             pageRef: input.pageRef,
             timeoutMs: effectiveTimeout,
             settleMs: profile.settleMs,
+            ...input.observedMutationQuietMs === void 0 ? {} : { initialQuietMs: input.observedMutationQuietMs },
             scope: profile.scope
           });
           return true;
@@ -12468,15 +12695,20 @@ var init_defaults = __esm({
           return false;
         }
         try {
-          const startedAt = Date.now();
-          await input.engine.waitForPostLoadQuiet({
-            pageRef: input.pageRef,
-            timeoutMs: effectiveTimeout,
-            quietMs: DEFAULT_POST_LOAD_TRACKER_QUIET_WINDOW_MS,
-            captureWindowMs: Math.min(NAVIGATION_POST_LOAD_CAPTURE_WINDOW_MS, effectiveTimeout),
-            signal: input.signal
-          });
-          const visualTimeout = Math.max(0, effectiveTimeout - (Date.now() - startedAt));
+          let visualTimeout = effectiveTimeout;
+          let initialQuietMs = input.observedMutationQuietMs ?? 0;
+          if (!input.postLoadHandled) {
+            const startedAt = Date.now();
+            await input.engine.waitForPostLoadQuiet({
+              pageRef: input.pageRef,
+              timeoutMs: effectiveTimeout,
+              quietMs: DEFAULT_POST_LOAD_TRACKER_QUIET_WINDOW_MS,
+              captureWindowMs: Math.min(NAVIGATION_POST_LOAD_CAPTURE_WINDOW_MS, effectiveTimeout),
+              signal: input.signal
+            });
+            visualTimeout = Math.max(0, effectiveTimeout - (Date.now() - startedAt));
+            initialQuietMs = Math.max(initialQuietMs, DEFAULT_POST_LOAD_TRACKER_QUIET_WINDOW_MS);
+          }
           if (visualTimeout <= 0) {
             return true;
           }
@@ -12484,6 +12716,7 @@ var init_defaults = __esm({
             pageRef: input.pageRef,
             timeoutMs: visualTimeout,
             settleMs: profile.settleMs,
+            ...initialQuietMs <= 0 ? {} : { initialQuietMs },
             scope: profile.scope
           });
           return true;
@@ -12494,7 +12727,6 @@ var init_defaults = __esm({
     };
     Object.freeze(defaultNavigationSettleObserver);
     DEFAULT_SETTLE_OBSERVERS = Object.freeze([
-      defaultSnapshotSettleObserver,
       defaultDomActionSettleObserver,
       defaultNavigationSettleObserver
     ]);
@@ -12982,6 +13214,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 +13332,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 +13920,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 +13950,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 +14112,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 +14173,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 +14594,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"
@@ -14624,7 +14884,7 @@ var init_executor = __esm({
             ...snapshot === void 0 ? {} : { snapshot },
             signal: timeout.signal,
             remainingMs: () => timeout.remainingMs(),
-            policySettle: async (targetPageRef, trigger) => {
+            policySettle: async (targetPageRef, trigger, boundary2) => {
               try {
                 await settleWithPolicy(this.options.policy.settle, {
                   operation,
@@ -14632,7 +14892,9 @@ var init_executor = __esm({
                   engine: this.options.engine,
                   pageRef: targetPageRef,
                   signal: timeout.signal,
-                  remainingMs: timeout.remainingMs()
+                  remainingMs: timeout.remainingMs(),
+                  ...boundary2?.observedMutationQuietMs === void 0 ? {} : { observedMutationQuietMs: boundary2.observedMutationQuietMs },
+                  ...boundary2?.postLoadHandled === true ? { postLoadHandled: true } : {}
                 });
               } catch (error) {
                 if (snapshot !== void 0 && isSoftSettleTimeoutError(error, timeout.signal)) {
@@ -14821,11 +15083,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 +15102,7 @@ var init_executor = __esm({
             hitMissingFromSnapshot: !resolved.snapshot.nodes.some(
               (node) => node.nodeRef === hit.nodeRef
             )
-          },
-          true
+          }
         );
       }
       async resolveActionablePointerTarget(session, operation, resolved) {
@@ -15031,7 +15293,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 +15518,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 +15536,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 +15641,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 +15812,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;
         }
@@ -15883,12 +16152,16 @@ function toOpensteerResolvedTarget(target) {
     documentRef: target.documentRef,
     documentEpoch: target.documentEpoch,
     nodeRef: target.nodeRef,
-    tagName: target.node.nodeName.toUpperCase(),
+    tagName: toOpensteerTagName(target.node.nodeName),
     pathHint: buildPathSelectorHint(target.replayPath ?? target.anchor),
     ...target.persist === void 0 ? {} : { persist: target.persist },
     ...target.selectorUsed === void 0 ? {} : { selectorUsed: target.selectorUsed }
   };
 }
+function toOpensteerTagName(nodeName) {
+  const tagName = String(nodeName).trim().toLowerCase();
+  return tagName.length === 0 ? "element" : tagName;
+}
 var init_trace_enrichment = __esm({
   "../runtime-core/src/runtimes/computer-use/trace-enrichment.ts"() {
     init_src();
@@ -15944,7 +16217,7 @@ var init_runtime2 = __esm({
             screenshot,
             signal: input.timeout.signal,
             remainingMs: () => input.timeout.remainingMs(),
-            policySettle: async (pageRef, trigger) => {
+            policySettle: async (pageRef, trigger, boundary) => {
               try {
                 await settleWithPolicy(this.options.policy.settle, {
                   operation: "computer.execute",
@@ -15952,7 +16225,9 @@ var init_runtime2 = __esm({
                   engine: this.options.engine,
                   pageRef,
                   signal: input.timeout.signal,
-                  remainingMs: input.timeout.remainingMs()
+                  remainingMs: input.timeout.remainingMs(),
+                  ...boundary?.observedMutationQuietMs === void 0 ? {} : { observedMutationQuietMs: boundary.observedMutationQuietMs },
+                  ...boundary?.postLoadHandled === true ? { postLoadHandled: true } : {}
                 });
               } catch (error) {
                 if (pageRef === input.pageRef && isSoftSettleTimeoutError(error, input.timeout.signal)) {
@@ -16948,29 +17223,29 @@ function buildVariantDescriptorFromCluster(descriptors) {
   const keyStats = /* @__PURE__ */ new Map();
   for (const descriptor of descriptors) {
     for (const field of descriptor.fields) {
-      const stat2 = keyStats.get(field.path) ?? {
+      const stat3 = keyStats.get(field.path) ?? {
         indices: /* @__PURE__ */ new Set(),
         pathNodes: [],
         attributes: [],
         sources: []
       };
-      stat2.indices.add(descriptor.index);
+      stat3.indices.add(descriptor.index);
       if (isPersistedOpensteerExtractionValueNode(field.node)) {
-        stat2.pathNodes.push(field.node.$path);
-        stat2.attributes.push(field.node.attribute);
+        stat3.pathNodes.push(field.node.$path);
+        stat3.attributes.push(field.node.attribute);
       } else if (isPersistedOpensteerExtractionSourceNode(field.node)) {
-        stat2.sources.push("current_url");
+        stat3.sources.push("current_url");
       }
-      keyStats.set(field.path, stat2);
+      keyStats.set(field.path, stat3);
     }
   }
   const mergedFields = [];
-  for (const [fieldPath, stat2] of keyStats) {
-    if (stat2.indices.size < threshold) {
+  for (const [fieldPath, stat3] of keyStats) {
+    if (stat3.indices.size < threshold) {
       continue;
     }
-    if (stat2.pathNodes.length >= threshold) {
-      let mergedFieldPath = stat2.pathNodes.length === 1 ? sanitizeElementPath(stat2.pathNodes[0]) : mergeElementPathsByMajority(stat2.pathNodes);
+    if (stat3.pathNodes.length >= threshold) {
+      let mergedFieldPath = stat3.pathNodes.length === 1 ? sanitizeElementPath(stat3.pathNodes[0]) : mergeElementPathsByMajority(stat3.pathNodes);
       if (!mergedFieldPath) {
         continue;
       }
@@ -16978,8 +17253,8 @@ function buildVariantDescriptorFromCluster(descriptors) {
         mergedFieldPath = relaxPathForSingleSample(mergedFieldPath, "field");
       }
       mergedFieldPath = minimizePathMatchClauses(mergedFieldPath, "field");
-      const attrThreshold = stat2.pathNodes.length === 1 ? 1 : majorityThreshold(stat2.pathNodes.length);
-      const attribute = pickModeString(stat2.attributes, attrThreshold);
+      const attrThreshold = stat3.pathNodes.length === 1 ? 1 : majorityThreshold(stat3.pathNodes.length);
+      const attribute = pickModeString(stat3.attributes, attrThreshold);
       mergedFields.push({
         path: fieldPath,
         node: createValueNode({
@@ -16989,7 +17264,7 @@ function buildVariantDescriptorFromCluster(descriptors) {
       });
       continue;
     }
-    const dominantSource = pickModeString(stat2.sources, threshold);
+    const dominantSource = pickModeString(stat3.sources, threshold);
     if (dominantSource === "current_url") {
       mergedFields.push({
         path: fieldPath,
@@ -17126,6 +17401,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 +17506,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 +17916,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" });
@@ -19089,28 +19372,24 @@ function restoreBoundedAttr(el, attr, value) {
   }
   setBoundedAttr(el, attr, value);
 }
-function deduplicateImages(html) {
+function deduplicateImagesInDom($) {
   const seen = /* @__PURE__ */ new Set();
-  return html.replace(/<img\b([^>]*)>/gi, (full, attrContent) => {
-    if (/\bc\s*=/.test(attrContent)) {
-      return full;
-    }
-    const srcMatch = attrContent.match(/\bsrc\s*=\s*(["']?)(.*?)\1/);
-    const srcsetMatch = attrContent.match(/\bsrcset\s*=\s*(["'])(.*?)\1/);
-    let src = null;
-    if (srcMatch && srcMatch[2]) {
-      src = srcMatch[2].trim();
-    } else if (srcsetMatch && srcsetMatch[2]) {
-      src = srcsetMatch[2].split(",")[0]?.trim().split(" ")[0] ?? null;
+  $("img").each(function deduplicateDomImage() {
+    const el = $(this);
+    if (el.attr("c") !== void 0) {
+      return;
     }
+    const srcValue = el.attr("src")?.trim();
+    const srcsetValue = el.attr("srcset");
+    const src = srcValue && srcValue.length > 0 ? srcValue : srcsetValue?.split(",")[0]?.trim().split(/\s+/u)[0];
     if (!src) {
-      return full;
+      return;
     }
     if (seen.has(src)) {
-      return "";
+      el.remove();
+      return;
     }
     seen.add(src);
-    return full;
   });
 }
 function hasAttribute2(node, attr) {
@@ -19168,23 +19447,6 @@ function isPreservedImageElement(node) {
 function getElementsInReverseDocumentOrder($) {
   return $.root().find("*").toArray().reverse().filter((node) => node.type === "tag");
 }
-function getNodeDepth(node) {
-  let depth = 0;
-  let current = node.parent;
-  while (current) {
-    depth++;
-    current = current.parent;
-  }
-  return depth;
-}
-function getElementsByDepthDescending($) {
-  const elements = $.root().find("*").toArray().filter((node) => node.type === "tag");
-  const depths = /* @__PURE__ */ new Map();
-  for (const el of elements) {
-    depths.set(el, getNodeDepth(el));
-  }
-  return elements.sort((a, b) => (depths.get(b) ?? 0) - (depths.get(a) ?? 0));
-}
 function flattenExtractionTree($) {
   for (const node of getElementsInReverseDocumentOrder($)) {
     const el = $(node);
@@ -19202,19 +19464,6 @@ function flattenExtractionTree($) {
     el.replaceWith(el.contents());
   }
 }
-function hasMarkedAncestor(el, attr) {
-  let current = el[0]?.parent;
-  while (current) {
-    if (!isElementLikeNode(current)) {
-      return false;
-    }
-    if (current.attribs?.[attr] !== void 0) {
-      return true;
-    }
-    current = current.parent;
-  }
-  return false;
-}
 function isIndicatorImage(node) {
   return (node?.tagName || "").toLowerCase() === "img" && (hasAttribute2(node, "alt") || hasAttribute2(node, "src") || hasAttribute2(node, "srcset"));
 }
@@ -19332,7 +19581,7 @@ function serializeForExtraction($, root) {
   traverse(root, 0);
   return lines.map((l) => l.trim()).filter((l) => l.length > 0).join("");
 }
-function isClickable($, el, context) {
+function isClickable(el, context) {
   if (context.hasPreMarked) {
     return el.attr(OPENSTEER_INTERACTIVE_ATTR) !== void 0;
   }
@@ -19366,21 +19615,17 @@ function isClickable($, el, context) {
   }
   return false;
 }
-function cleanForExtraction(html) {
+function prepareExtractionSnapshotDom(html) {
   if (!html.trim()) {
-    return "";
+    return void 0;
   }
   const $ = cheerio__namespace.load(html, { xmlMode: false });
   removeNoise($);
   removeComments($);
   markInlineSelfHiddenFallback($);
   pruneSelfHiddenNodes($);
-  const $clean = cheerio__namespace.load(
-    $.html().replace(/\n{2,}/g, "\n").trim(),
-    { xmlMode: false }
-  );
-  $clean("*").each(function stripAndRestoreExtractionAttrs() {
-    const el = $clean(this);
+  $("*").each(function stripAndRestoreExtractionAttrs() {
+    const el = $(this);
     const node = el[0];
     if (!node) {
       return;
@@ -19421,16 +19666,20 @@ function cleanForExtraction(html) {
       restoreBoundedAttr(el, "href", hrefValue);
     }
   });
-  flattenExtractionTree($clean);
-  const root = $clean.root()[0];
+  flattenExtractionTree($);
+  deduplicateImagesInDom($);
+  return $;
+}
+function serializePreparedExtractionSnapshot($) {
+  const root = $.root()[0];
   if (root === void 0) {
     return "";
   }
-  return deduplicateImages(serializeForExtraction($clean, root));
+  return serializeForExtraction($, root);
 }
-function cleanForAction(html) {
+function prepareActionSnapshotDom(html) {
   if (!html.trim()) {
-    return "";
+    return void 0;
   }
   const $ = cheerio__namespace.load(html, { xmlMode: false });
   removeNoise($);
@@ -19439,13 +19688,12 @@ function cleanForAction(html) {
   pruneSelfHiddenNodes($);
   const clickableMark = "data-clickable-marker";
   const indicatorMark = "data-keep-indicator";
-  const branchMark = "data-keep-branch";
   const context = {
     hasPreMarked: $(`[${OPENSTEER_INTERACTIVE_ATTR}]`).length > 0
   };
   $("*").each(function markClickables() {
     const el = $(this);
-    if (isClickable($, el, context)) {
+    if (isClickable(el, context)) {
       el.attr(clickableMark, "1");
     }
   });
@@ -19475,25 +19723,7 @@ function cleanForAction(html) {
       el.remove();
     }
   });
-  $(`[${clickableMark}], [${indicatorMark}]`).each(function markBranches() {
-    let current = $(this).parent();
-    while (current.length > 0) {
-      const node = current[0];
-      if (!node || node.type !== "tag") {
-        break;
-      }
-      const ancestor = current;
-      const tag = (node.tagName || "").toLowerCase();
-      if (ROOT_TAGS.has(tag) || ancestor.attr(clickableMark) !== void 0) {
-        break;
-      }
-      if (!isBoundaryTag(tag)) {
-        ancestor.attr(branchMark, "1");
-      }
-      current = ancestor.parent();
-    }
-  });
-  for (const node of getElementsByDepthDescending($)) {
+  for (const node of getElementsInReverseDocumentOrder($)) {
     const el = $(node);
     const tag = (node.tagName || "").toLowerCase();
     if (ROOT_TAGS.has(tag) || isBoundaryTag(tag)) {
@@ -19502,17 +19732,7 @@ function cleanForAction(html) {
     if (el.attr(clickableMark) !== void 0 || el.attr(indicatorMark) !== void 0) {
       continue;
     }
-    const insideClickable = hasMarkedAncestor(el, clickableMark);
-    const preserveBranch = el.attr(branchMark) !== void 0;
     const hasContent = hasElementChildren(node) || hasDirectText(node);
-    if (insideClickable || preserveBranch) {
-      if (!hasContent) {
-        el.remove();
-      } else {
-        unwrapActionNode($, el);
-      }
-      continue;
-    }
     if (!hasContent) {
       el.remove();
       continue;
@@ -19613,13 +19833,20 @@ function cleanForAction(html) {
     }
     el.removeAttr(clickableMark);
     el.removeAttr(indicatorMark);
-    el.removeAttr(branchMark);
     el.removeAttr(OPENSTEER_INTERACTIVE_ATTR);
     el.removeAttr(OPENSTEER_HIDDEN_ATTR);
     el.removeAttr(OPENSTEER_SCROLLABLE_ATTR);
     el.removeAttr(OPENSTEER_SELF_HIDDEN_ATTR);
   });
-  return compactHtml(deduplicateImages($.html()));
+  deduplicateImagesInDom($);
+  return $;
+}
+function serializePreparedActionSnapshot($) {
+  const normalized = compactHtml($.html());
+  if (normalized.length === 0) {
+    return "";
+  }
+  return cheerio__namespace.load(normalized, { xmlMode: false }).html();
 }
 var STRIP_TAGS, TEXT_ATTR_MAX, SRCSET_ATTR_MAX, MIDDLE_TRUNCATED_URL_ATTRS, TEXT_ATTRS, TRUNCATION_SUFFIX, MIDDLE_TRUNCATION_MARKER, MIDDLE_TRUNCATION_HEAD_MAX, MIDDLE_TRUNCATION_TAIL_MAX, SRCSET_CANDIDATE_HEAD_MAX, SRCSET_CANDIDATE_TAIL_MAX, SRCSET_COMPACT_CANDIDATE_HEAD_MAX, SRCSET_COMPACT_CANDIDATE_TAIL_MAX, SRCSET_FALLBACK_HEAD_MAX, SRCSET_FALLBACK_TAIL_MAX, NOISE_SELECTORS, VOID_TAGS2;
 var init_cleaner = __esm({
@@ -19680,23 +19907,27 @@ async function markLiveSnapshotSemantics(options) {
   const frames = await options.engine.listFrames({
     pageRef: options.pageRef
   });
-  for (const frame of frames) {
-    await evaluateFrameBestEffort(
-      options.engine,
-      frame.frameRef,
-      MARK_SNAPSHOT_SEMANTICS_SCRIPT,
-      SNAPSHOT_SEMANTIC_ARGS
-    );
-  }
-  return async () => {
-    for (const frame of frames) {
-      await evaluateFrameBestEffort(
+  await Promise.all(
+    frames.map(
+      (frame) => evaluateFrameBestEffort(
         options.engine,
         frame.frameRef,
-        CLEAR_SNAPSHOT_SEMANTICS_SCRIPT,
-        CLEAR_SNAPSHOT_SEMANTIC_ARGS
-      );
-    }
+        MARK_SNAPSHOT_SEMANTICS_SCRIPT,
+        SNAPSHOT_SEMANTIC_ARGS
+      )
+    )
+  );
+  return async () => {
+    await Promise.all(
+      frames.map(
+        (frame) => evaluateFrameBestEffort(
+          options.engine,
+          frame.frameRef,
+          CLEAR_SNAPSHOT_SEMANTICS_SCRIPT,
+          CLEAR_SNAPSHOT_SEMANTIC_ARGS
+        )
+      )
+    );
   };
 }
 var MARK_SNAPSHOT_SEMANTICS_SCRIPT, CLEAR_SNAPSHOT_SEMANTICS_SCRIPT, SNAPSHOT_SEMANTIC_ARGS, CLEAR_SNAPSHOT_SEMANTIC_ARGS;
@@ -19894,6 +20125,8 @@ var init_marking = __esm({
     ];
   }
 });
+
+// ../runtime-core/src/sdk/snapshot/compiler.ts
 function isLiveCounterSyncError(error) {
   return error instanceof LiveCounterSyncError;
 }
@@ -19931,20 +20164,22 @@ function ensureSparseCountersForAllRecords(counterRecords) {
 async function clearOpensteerLiveCounters(engine, pageRef) {
   const frames = await engine.listFrames({ pageRef });
   const failures = [];
-  for (const frame of frames) {
-    try {
-      await engine.evaluateFrame({
-        frameRef: frame.frameRef,
-        script: CLEAR_LIVE_COUNTERS_SCRIPT,
-        args: [{ sparseCounterAttr: OPENSTEER_SPARSE_COUNTER_ATTR }]
-      });
-    } catch (error) {
-      if (isDetachedFrameSyncError(error)) {
-        continue;
+  await Promise.all(
+    frames.map(async (frame) => {
+      try {
+        await engine.evaluateFrame({
+          frameRef: frame.frameRef,
+          script: CLEAR_LIVE_COUNTERS_SCRIPT,
+          args: [{ sparseCounterAttr: OPENSTEER_SPARSE_COUNTER_ATTR }]
+        });
+      } catch (error) {
+        if (isDetachedFrameSyncError(error)) {
+          return;
+        }
+        failures.push(`frame ${frame.frameRef} could not be cleared (${describeError(error)}).`);
       }
-      failures.push(`frame ${frame.frameRef} could not be cleared (${describeError(error)}).`);
-    }
-  }
+    })
+  );
   if (failures.length > 0) {
     throw buildLiveCounterSyncError("clear live counters", failures);
   }
@@ -19993,25 +20228,29 @@ async function syncDenseCountersToLiveDom(engine, pageRef, sparseToDirectMapping
       denseCounter
     ])
   );
-  for (const frame of frames) {
-    try {
-      await engine.evaluateFrame({
-        frameRef: frame.frameRef,
-        script: APPLY_DENSE_COUNTERS_SCRIPT,
-        args: [
-          {
-            sparseCounterAttr: OPENSTEER_SPARSE_COUNTER_ATTR,
-            mapping: mappingObj
-          }
-        ]
-      });
-    } catch (error) {
-      if (isDetachedFrameSyncError(error)) {
-        continue;
+  await Promise.all(
+    frames.map(async (frame) => {
+      try {
+        await engine.evaluateFrame({
+          frameRef: frame.frameRef,
+          script: APPLY_DENSE_COUNTERS_SCRIPT,
+          args: [
+            {
+              sparseCounterAttr: OPENSTEER_SPARSE_COUNTER_ATTR,
+              mapping: mappingObj
+            }
+          ]
+        });
+      } catch (error) {
+        if (isDetachedFrameSyncError(error)) {
+          return;
+        }
+        failures.push(
+          `frame ${frame.frameRef} could not be synchronized (${describeError(error)}).`
+        );
       }
-      failures.push(`frame ${frame.frameRef} could not be synchronized (${describeError(error)}).`);
-    }
-  }
+    })
+  );
   if (failures.length > 0) {
     throw buildLiveCounterSyncError("synchronize dense counters", failures);
   }
@@ -20029,26 +20268,26 @@ async function compileOpensteerSnapshot(options) {
       await clearOpensteerLiveCounters(options.engine, options.pageRef);
       await assignSparseCountersToLiveDom(options.engine, options.pageRef);
       const pageInfo = await options.engine.getPageInfo({ pageRef: options.pageRef });
-      const mainSnapshot = await getMainDocumentSnapshot(options.engine, options.pageRef);
-      const snapshotsByDocumentRef = await collectDocumentSnapshots(options.engine, mainSnapshot);
+      const { mainSnapshot, snapshotsByDocumentRef } = await getPageDocumentSnapshots(
+        options.engine,
+        options.pageRef
+      );
       await cleanupLiveSemantics();
       cleanupLiveSemantics = async () => {
       };
-      const snapshotIndices = /* @__PURE__ */ new Map();
       const renderedNodes = /* @__PURE__ */ new Map();
       const rawHtml = renderDocumentSnapshot(
         mainSnapshot.documentRef,
         snapshotsByDocumentRef,
-        snapshotIndices,
         renderedNodes,
         {
           iframeDepth: 0,
           shadowDepth: 0
         }
       );
-      const cleanedHtml = options.mode === "extraction" ? cleanForExtraction(rawHtml) : cleanForAction(rawHtml);
-      const compiledHtml = assignCounters(cleanedHtml, renderedNodes);
-      const finalHtml = options.mode === "extraction" ? unwrapExtractionHtml(compiledHtml.html) : compiledHtml.html;
+      const preparedSnapshotDom = options.mode === "extraction" ? prepareExtractionSnapshotDom(rawHtml) : prepareActionSnapshotDom(rawHtml);
+      const compiledHtml = assignCountersInDom(preparedSnapshotDom, renderedNodes, options.mode);
+      const finalHtml = preparedSnapshotDom === void 0 ? "" : options.mode === "extraction" ? serializePreparedExtractionSnapshot(preparedSnapshotDom) : serializePreparedActionSnapshot(preparedSnapshotDom);
       ensureSparseCountersForAllRecords(compiledHtml.counterRecords);
       await syncDenseCountersToLiveDom(
         options.engine,
@@ -20083,6 +20322,25 @@ async function getMainDocumentSnapshot(engine, pageRef) {
   }
   return engine.getDomSnapshot({ frameRef: mainFrame.frameRef });
 }
+async function getPageDocumentSnapshots(engine, pageRef) {
+  const bundleEngine = engine;
+  const bundledSnapshots = await bundleEngine.getPageDomSnapshots?.({ pageRef });
+  if (bundledSnapshots && bundledSnapshots.length > 0) {
+    const mainSnapshot2 = bundledSnapshots.find((snapshot) => snapshot.parentDocumentRef === void 0) ?? bundledSnapshots[0];
+    return {
+      mainSnapshot: mainSnapshot2,
+      snapshotsByDocumentRef: new Map(
+        bundledSnapshots.map((snapshot) => [snapshot.documentRef, snapshot])
+      )
+    };
+  }
+  const mainSnapshot = await getMainDocumentSnapshot(engine, pageRef);
+  const snapshotsByDocumentRef = await collectDocumentSnapshots(engine, mainSnapshot);
+  return {
+    mainSnapshot,
+    snapshotsByDocumentRef
+  };
+}
 async function collectDocumentSnapshots(engine, mainSnapshot) {
   const snapshotsByDocumentRef = /* @__PURE__ */ new Map([
     [mainSnapshot.documentRef, mainSnapshot]
@@ -20101,7 +20359,7 @@ async function collectDocumentSnapshots(engine, mainSnapshot) {
   }
   return snapshotsByDocumentRef;
 }
-function renderDocumentSnapshot(documentRef, snapshotsByDocumentRef, snapshotIndices, renderedNodes, depth) {
+function renderDocumentSnapshot(documentRef, snapshotsByDocumentRef, renderedNodes, depth) {
   const snapshot = snapshotsByDocumentRef.get(documentRef);
   if (!snapshot) {
     return "";
@@ -20113,17 +20371,9 @@ function renderDocumentSnapshot(documentRef, snapshotsByDocumentRef, snapshotInd
       `snapshot ${snapshot.documentRef} is missing root node ${String(snapshot.rootSnapshotNodeId)}`
     );
   }
-  return renderNode(
-    snapshot,
-    rootNode,
-    nodesById,
-    snapshotsByDocumentRef,
-    snapshotIndices,
-    renderedNodes,
-    depth
-  );
+  return renderNode(snapshot, rootNode, nodesById, snapshotsByDocumentRef, renderedNodes, depth);
 }
-function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotIndices, renderedNodes, depth) {
+function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth) {
   if (node.nodeType === 3) {
     return escapeHtml(node.nodeValue || node.textContent || "");
   }
@@ -20131,56 +20381,26 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
     return "";
   }
   if (node.nodeType === 9 || node.nodeType === 11) {
-    return renderChildren(
-      snapshot,
-      node,
-      nodesById,
-      snapshotsByDocumentRef,
-      snapshotIndices,
-      renderedNodes,
-      depth
-    );
+    return renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth);
   }
   if (node.nodeType !== 1) {
-    return renderChildren(
-      snapshot,
-      node,
-      nodesById,
-      snapshotsByDocumentRef,
-      snapshotIndices,
-      renderedNodes,
-      depth
-    );
+    return renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth);
   }
   const tagName = normalizeTagName(node.nodeName);
   if (isPseudoElementTagName(tagName)) {
-    return renderChildren(
-      snapshot,
-      node,
-      nodesById,
-      snapshotsByDocumentRef,
-      snapshotIndices,
-      renderedNodes,
-      depth
-    );
+    return renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth);
   }
   if ((depth.iframeDepth > 0 || depth.shadowDepth > 0) && (tagName === "html" || tagName === "head" || tagName === "body")) {
-    return renderChildren(
-      snapshot,
-      node,
-      nodesById,
-      snapshotsByDocumentRef,
-      snapshotIndices,
-      renderedNodes,
-      depth
-    );
+    return renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth);
   }
   const snapshotAttributes = normalizeNodeAttributes(node.attributes);
+  const snapshotAttributeIndex = indexNodeAttributes(snapshotAttributes);
   const authoredAttributes = stripInternalSnapshotAttributes(snapshotAttributes);
+  const authoredAttributeIndex = indexNodeAttributes(authoredAttributes);
   const attributes = [...authoredAttributes];
-  const subtreeHidden = hasAttribute3(snapshotAttributes, OPENSTEER_HIDDEN_ATTR) || isLikelySubtreeHidden(node);
-  const selfHidden = !subtreeHidden && (hasAttribute3(snapshotAttributes, OPENSTEER_SELF_HIDDEN_ATTR) || isLikelySelfHidden(node, nodesById));
-  const interactive = !subtreeHidden && !selfHidden && (hasAttribute3(snapshotAttributes, OPENSTEER_INTERACTIVE_ATTR) || isLikelyInteractive(tagName, node, authoredAttributes));
+  const subtreeHidden = snapshotAttributeIndex.has(OPENSTEER_HIDDEN_ATTR) || isLikelySubtreeHidden(node);
+  const selfHidden = !subtreeHidden && (snapshotAttributeIndex.has(OPENSTEER_SELF_HIDDEN_ATTR) || isLikelySelfHidden(node, nodesById));
+  const interactive = !subtreeHidden && !selfHidden && (snapshotAttributeIndex.has(OPENSTEER_INTERACTIVE_ATTR) || isLikelyInteractive(tagName, node, authoredAttributes, authoredAttributeIndex));
   if (interactive) {
     attributes.push({ name: OPENSTEER_INTERACTIVE_ATTR, value: "1" });
   }
@@ -20189,7 +20409,7 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
   } else if (selfHidden) {
     attributes.push({ name: OPENSTEER_SELF_HIDDEN_ATTR, value: "1" });
   }
-  const sparseCounter = findAttributeValue(snapshotAttributes, OPENSTEER_SPARSE_COUNTER_ATTR);
+  const sparseCounter = snapshotAttributeIndex.get(OPENSTEER_SPARSE_COUNTER_ATTR);
   if (sparseCounter !== void 0) {
     attributes.push({ name: OPENSTEER_SPARSE_COUNTER_ATTR, value: sparseCounter });
   }
@@ -20200,21 +20420,18 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
     const syntheticNodeId = buildSyntheticNodeId(snapshot, node);
     attributes.push({ name: OPENSTEER_NODE_ID_ATTR, value: syntheticNodeId });
     renderedNodes.set(syntheticNodeId, {
-      locator: createNodeLocator(snapshot.documentRef, snapshot.documentEpoch, node.nodeRef),
-      anchor: buildSnapshotElementAnchor(snapshot, node, snapshotsByDocumentRef, snapshotIndices),
       pageRef: snapshot.pageRef,
       frameRef: snapshot.frameRef,
       documentRef: snapshot.documentRef,
       documentEpoch: snapshot.documentEpoch,
       nodeRef: node.nodeRef,
       tagName: tagName.toUpperCase(),
-      pathHint: buildPathHint(tagName, authoredAttributes),
-      ...buildTextSnippet(node.textContent) === void 0 ? {} : { text: buildTextSnippet(node.textContent) },
       ...authoredAttributes.length === 0 ? {} : { attributes: authoredAttributes },
       iframeDepth: depth.iframeDepth,
       shadowDepth: depth.shadowDepth,
       interactive,
-      liveCounterSyncEligible: isLiveCounterSyncEligible(node, nodesById)
+      liveCounterSyncEligible: isLiveCounterSyncEligible(node, nodesById),
+      ...node.textContent === void 0 ? {} : { textContent: node.textContent }
     });
   }
   const attributeText = attributesToHtml(attributes);
@@ -20223,7 +20440,6 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
     node,
     nodesById,
     snapshotsByDocumentRef,
-    snapshotIndices,
     renderedNodes,
     depth
   );
@@ -20234,7 +20450,6 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
   const iframeHtml = renderDocumentSnapshot(
     node.contentDocumentRef,
     snapshotsByDocumentRef,
-    snapshotIndices,
     renderedNodes,
     {
       iframeDepth: depth.iframeDepth + 1,
@@ -20246,7 +20461,7 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
   }
   return `${elementHtml}<${OPENSTEER_IFRAME_BOUNDARY_TAG} ${OPENSTEER_BOUNDARY_ATTR}="iframe">${iframeHtml}</${OPENSTEER_IFRAME_BOUNDARY_TAG}>`;
 }
-function renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotIndices, renderedNodes, depth) {
+function renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth) {
   const regularChildren = [];
   const shadowChildren = [];
   for (const childSnapshotNodeId of node.childSnapshotNodeIds) {
@@ -20263,18 +20478,10 @@ function renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, snaps
   const chunks = [];
   if (shadowChildren.length > 0) {
     const shadowHtml = shadowChildren.map(
-      (child) => renderNode(
-        snapshot,
-        child,
-        nodesById,
-        snapshotsByDocumentRef,
-        snapshotIndices,
-        renderedNodes,
-        {
-          iframeDepth: depth.iframeDepth,
-          shadowDepth: depth.shadowDepth + 1
-        }
-      )
+      (child) => renderNode(snapshot, child, nodesById, snapshotsByDocumentRef, renderedNodes, {
+        iframeDepth: depth.iframeDepth,
+        shadowDepth: depth.shadowDepth + 1
+      })
     ).join("");
     chunks.push(
       `<${OPENSTEER_SHADOW_BOUNDARY_TAG} ${OPENSTEER_BOUNDARY_ATTR}="shadow">${shadowHtml}</${OPENSTEER_SHADOW_BOUNDARY_TAG}>`
@@ -20282,24 +20489,21 @@ function renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, snaps
   }
   for (const child of regularChildren) {
     chunks.push(
-      renderNode(
-        snapshot,
-        child,
-        nodesById,
-        snapshotsByDocumentRef,
-        snapshotIndices,
-        renderedNodes,
-        depth
-      )
+      renderNode(snapshot, child, nodesById, snapshotsByDocumentRef, renderedNodes, depth)
     );
   }
   return chunks.join("");
 }
-function assignCounters(cleanedHtml, renderedNodes) {
-  const $ = cheerio__namespace.load(cleanedHtml, { xmlMode: false });
+function assignCountersInDom($, renderedNodes, mode) {
   const counterRecords = /* @__PURE__ */ new Map();
   const sparseToDirectMapping = /* @__PURE__ */ new Map();
   let nextCounter = 1;
+  if (!$) {
+    return {
+      counterRecords,
+      sparseToDirectMapping
+    };
+  }
   $("*").each(function assignElementCounter() {
     const el = $(this);
     const syntheticNodeId = el.attr(OPENSTEER_NODE_ID_ATTR);
@@ -20311,14 +20515,24 @@ function assignCounters(cleanedHtml, renderedNodes) {
     if (!rendered) {
       return;
     }
+    if (mode === "extraction" && EXTRACTION_SKIPPED_COUNTER_TAGS.has(rendered.tagName.toLowerCase())) {
+      el.removeAttr(OPENSTEER_SPARSE_COUNTER_ATTR);
+      return;
+    }
     const rawSparseCounter = el.attr(OPENSTEER_SPARSE_COUNTER_ATTR);
     el.removeAttr(OPENSTEER_SPARSE_COUNTER_ATTR);
     const sparseCounter = rawSparseCounter ? Number.parseInt(rawSparseCounter, 10) : void 0;
+    const replayableSparseCounter = typeof sparseCounter === "number" && Number.isFinite(sparseCounter) ? sparseCounter : void 0;
+    if (rendered.liveCounterSyncEligible && replayableSparseCounter === void 0) {
+      return;
+    }
     const counter = nextCounter++;
     el.attr("c", String(counter));
-    if (sparseCounter !== void 0 && Number.isFinite(sparseCounter)) {
-      sparseToDirectMapping.set(sparseCounter, counter);
+    if (replayableSparseCounter !== void 0) {
+      sparseToDirectMapping.set(replayableSparseCounter, counter);
     }
+    const pathHint = buildPathHint(rendered.tagName.toLowerCase(), rendered.attributes ?? []);
+    const text = buildTextSnippet(rendered.textContent);
     counterRecords.set(counter, {
       element: counter,
       pageRef: rendered.pageRef,
@@ -20327,20 +20541,17 @@ function assignCounters(cleanedHtml, renderedNodes) {
       documentEpoch: rendered.documentEpoch,
       nodeRef: rendered.nodeRef,
       tagName: rendered.tagName,
-      pathHint: rendered.pathHint,
-      ...rendered.text === void 0 ? {} : { text: rendered.text },
+      pathHint,
+      ...text === void 0 ? {} : { text },
       ...rendered.attributes === void 0 ? {} : { attributes: rendered.attributes },
       iframeDepth: rendered.iframeDepth,
       shadowDepth: rendered.shadowDepth,
       interactive: rendered.interactive,
       liveCounterSyncEligible: rendered.liveCounterSyncEligible,
-      locator: rendered.locator,
-      anchor: rendered.anchor,
-      ...sparseCounter !== void 0 && Number.isFinite(sparseCounter) ? { sparseCounter } : {}
+      ...replayableSparseCounter === void 0 ? {} : { sparseCounter: replayableSparseCounter }
     });
   });
   return {
-    html: $.html(),
     counterRecords,
     sparseToDirectMapping
   };
@@ -20414,28 +20625,28 @@ function isLikelySelfHidden(node, nodesById) {
   }
   return !hasVisibleOutOfFlowChild(node, nodesById);
 }
-function isLikelyInteractive(tagName, node, attributes) {
+function isLikelyInteractive(tagName, node, attributes, attributeIndex) {
   if (NATIVE_INTERACTIVE_TAGS.has(tagName)) {
-    if (tagName === "input" && findAttributeValue(attributes, "type")?.toLowerCase() === "hidden") {
+    if (tagName === "input" && attributeIndex.get("type")?.toLowerCase() === "hidden") {
       return false;
     }
     if (tagName !== "a") {
       return true;
     }
   }
-  if (tagName === "a" && findAttributeValue(attributes, "href") !== void 0) {
+  if (tagName === "a" && attributeIndex.has("href")) {
     return true;
   }
-  if (findAttributeValue(attributes, "onclick") !== void 0 || findAttributeValue(attributes, "onmousedown") !== void 0 || findAttributeValue(attributes, "onmouseup") !== void 0 || findAttributeValue(attributes, "data-action") !== void 0 || findAttributeValue(attributes, "data-click") !== void 0 || findAttributeValue(attributes, "data-toggle") !== void 0) {
+  if (attributeIndex.has("onclick") || attributeIndex.has("onmousedown") || attributeIndex.has("onmouseup") || attributeIndex.has("data-action") || attributeIndex.has("data-click") || attributeIndex.has("data-toggle")) {
     return true;
   }
-  if (hasNonNegativeTabIndex(findAttributeValue(attributes, "tabindex"))) {
+  if (hasNonNegativeTabIndex(attributeIndex.get("tabindex"))) {
     return true;
   }
-  if (findAttributeValue(attributes, "contenteditable")?.toLowerCase() === "true") {
+  if (attributeIndex.get("contenteditable")?.toLowerCase() === "true") {
     return true;
   }
-  const role = findAttributeValue(attributes, "role")?.toLowerCase();
+  const role = attributeIndex.get("role")?.toLowerCase();
   return role !== void 0 && INTERACTIVE_ROLE_SET.has(role);
 }
 function hasVisibleOutOfFlowChild(node, nodesById) {
@@ -20498,14 +20709,6 @@ function parseOpacity(value) {
   const parsed = Number.parseFloat(value);
   return Number.isFinite(parsed) ? parsed : Number.NaN;
 }
-function hasAttribute3(attributes, name) {
-  const normalizedName = name.toLowerCase();
-  return attributes.some((attribute) => attribute.name.toLowerCase() === normalizedName);
-}
-function unwrapExtractionHtml(html) {
-  const $ = cheerio__namespace.load(html, { xmlMode: false });
-  return $("body").html()?.trim() || html;
-}
 function buildSyntheticNodeId(snapshot, node) {
   return `${snapshot.documentRef}:${String(snapshot.documentEpoch)}:${String(node.snapshotNodeId)}`;
 }
@@ -20552,6 +20755,13 @@ function findAttributeValue(attributes, name) {
   const normalizedName = name.toLowerCase();
   return attributes.find((attribute) => attribute.name.toLowerCase() === normalizedName)?.value;
 }
+function indexNodeAttributes(attributes) {
+  const indexed = /* @__PURE__ */ new Map();
+  for (const attribute of attributes) {
+    indexed.set(attribute.name.toLowerCase(), attribute.value);
+  }
+  return indexed;
+}
 function attributesToHtml(attributes) {
   if (attributes.length === 0) {
     return "";
@@ -20561,68 +20771,16 @@ function attributesToHtml(attributes) {
 function escapeAttribute(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function buildSnapshotElementAnchor(snapshot, node, snapshotsByDocumentRef, snapshotIndices) {
-  const index = getSnapshotIndex(snapshot.documentRef, snapshotsByDocumentRef, snapshotIndices);
-  const localAnchor = buildLocalStructuralElementAnchor(index, node);
-  return prefixIframeContext(snapshot, localAnchor, snapshotsByDocumentRef, snapshotIndices);
-}
-function prefixIframeContext(snapshot, localPath, snapshotsByDocumentRef, snapshotIndices) {
-  if (snapshot.parentDocumentRef === void 0) {
-    return sanitizeStructuralElementAnchor(localPath);
-  }
-  const parentSnapshot = snapshotsByDocumentRef.get(snapshot.parentDocumentRef);
-  if (!parentSnapshot) {
-    throw new Error(
-      `document ${snapshot.documentRef} has parent ${snapshot.parentDocumentRef} but no parent snapshot`
-    );
-  }
-  const parentIndex = getSnapshotIndex(
-    parentSnapshot.documentRef,
-    snapshotsByDocumentRef,
-    snapshotIndices
-  );
-  const iframeHost = findIframeHostNode(parentIndex, snapshot.documentRef);
-  if (!iframeHost) {
-    throw new Error(
-      `document ${snapshot.documentRef} has parent ${snapshot.parentDocumentRef} but no iframe host`
-    );
-  }
-  const hostPath = buildSnapshotElementAnchor(
-    parentSnapshot,
-    iframeHost,
-    snapshotsByDocumentRef,
-    snapshotIndices
-  );
-  return sanitizeStructuralElementAnchor({
-    context: [...hostPath.context, { kind: "iframe", host: hostPath.nodes }, ...localPath.context],
-    nodes: localPath.nodes
-  });
-}
-function getSnapshotIndex(documentRef, snapshotsByDocumentRef, snapshotIndices) {
-  const existing = snapshotIndices.get(documentRef);
-  if (existing) {
-    return existing;
-  }
-  const snapshot = snapshotsByDocumentRef.get(documentRef);
-  if (!snapshot) {
-    throw new Error(`missing DOM snapshot for ${documentRef}`);
-  }
-  const index = createSnapshotIndex(snapshot);
-  snapshotIndices.set(documentRef, index);
-  return index;
-}
 function escapeHtml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-var INTERNAL_SNAPSHOT_ATTRIBUTE_NAMES, MAX_LIVE_COUNTER_SYNC_ATTEMPTS, CLEAR_LIVE_COUNTERS_SCRIPT, ASSIGN_SPARSE_COUNTERS_SCRIPT, APPLY_DENSE_COUNTERS_SCRIPT, LiveCounterSyncError;
+var EXTRACTION_SKIPPED_COUNTER_TAGS, INTERNAL_SNAPSHOT_ATTRIBUTE_NAMES, MAX_LIVE_COUNTER_SYNC_ATTEMPTS, CLEAR_LIVE_COUNTERS_SCRIPT, ASSIGN_SPARSE_COUNTERS_SCRIPT, APPLY_DENSE_COUNTERS_SCRIPT, LiveCounterSyncError;
 var init_compiler = __esm({
   "../runtime-core/src/sdk/snapshot/compiler.ts"() {
-    init_src();
-    init_path();
-    init_selectors();
     init_cleaner();
     init_constants();
     init_marking();
+    EXTRACTION_SKIPPED_COUNTER_TAGS = /* @__PURE__ */ new Set(["html", "head", "body"]);
     INTERNAL_SNAPSHOT_ATTRIBUTE_NAMES = /* @__PURE__ */ new Set([
       "c",
       OPENSTEER_BOUNDARY_ATTR,
@@ -20637,7 +20795,7 @@ var init_compiler = __esm({
     MAX_LIVE_COUNTER_SYNC_ATTEMPTS = 4;
     CLEAR_LIVE_COUNTERS_SCRIPT = `(({ sparseCounterAttr }) => {
   const walk = (root) => {
-    for (const child of root.children) {
+    for (const child of Array.from(root?.children || [])) {
       child.removeAttribute("c");
       child.removeAttribute(sparseCounterAttr);
       walk(child);
@@ -20653,7 +20811,7 @@ var init_compiler = __esm({
     ASSIGN_SPARSE_COUNTERS_SCRIPT = `(({ sparseCounterAttr, startCounter }) => {
   let counter = startCounter;
   const walk = (root) => {
-    for (const child of root.children) {
+    for (const child of Array.from(root?.children || [])) {
       child.setAttribute(sparseCounterAttr, String(counter++));
       walk(child);
       if (child.shadowRoot) {
@@ -20667,7 +20825,7 @@ var init_compiler = __esm({
 })`;
     APPLY_DENSE_COUNTERS_SCRIPT = `(({ sparseCounterAttr, mapping }) => {
   const walk = (root) => {
-    for (const child of root.children) {
+    for (const child of Array.from(root?.children || [])) {
       child.removeAttribute("c");
       const sparse = child.getAttribute(sparseCounterAttr);
       if (sparse !== null) {
@@ -22851,15 +23009,10 @@ function normalizeNamespace2(value) {
   const normalized = String(value ?? "default").trim();
   return normalized.length === 0 ? "default" : normalized;
 }
-function toOpensteerActionResult(result) {
+function toOpensteerActionResult(target) {
   return {
-    target: toOpensteerResolvedTarget2(result.resolved),
-    ...result.point === void 0 ? {} : {
-      point: {
-        x: result.point.x,
-        y: result.point.y
-      }
-    }
+    tagName: toOpensteerTagName2(target.node.nodeName),
+    ...target.persist === void 0 ? {} : { persist: target.persist }
   };
 }
 function toOpensteerResolvedTarget2(target) {
@@ -22869,12 +23022,16 @@ function toOpensteerResolvedTarget2(target) {
     documentRef: target.documentRef,
     documentEpoch: target.documentEpoch,
     nodeRef: target.nodeRef,
-    tagName: target.node.nodeName.toUpperCase(),
+    tagName: toOpensteerTagName2(target.node.nodeName),
     pathHint: buildPathSelectorHint(target.replayPath ?? target.anchor),
     ...target.persist === void 0 ? {} : { persist: target.persist },
     ...target.selectorUsed === void 0 ? {} : { selectorUsed: target.selectorUsed }
   };
 }
+function toOpensteerTagName2(nodeName) {
+  const tagName = String(nodeName).trim().toLowerCase();
+  return tagName.length === 0 ? "element" : tagName;
+}
 function normalizeOpensteerError(error) {
   return normalizeThrownOpensteerError(error, "Unknown Opensteer runtime failure");
 }
@@ -23192,7 +23349,7 @@ var init_runtime3 = __esm({
               options
             );
           }
-          return this.readSessionState();
+          return this.readNavigationSummary();
         }
         const startedAt = Date.now();
         const root = await this.ensureRoot();
@@ -23213,7 +23370,8 @@ var init_runtime3 = __esm({
               openedSessionRef = sessionRef;
               const createdPage = await timeout.runStep(
                 () => engine.createPage({
-                  sessionRef
+                  sessionRef,
+                  ...input.url === void 0 ? {} : { url: input.url }
                 })
               );
               openedPageRef = createdPage.data.pageRef;
@@ -23223,18 +23381,19 @@ var init_runtime3 = __esm({
               await timeout.runStep(() => this.ensureSemantics());
               let frameRef2 = createdPage.frameRef;
               if (input.url !== void 0) {
-                const navigation = await this.navigatePage(
-                  {
+                await timeout.runStep(
+                  () => settleWithPolicy(this.policy.settle, {
                     operation: "session.open",
+                    trigger: "navigation",
+                    engine: this.requireEngine(),
                     pageRef: createdPage.data.pageRef,
-                    url: input.url
-                  },
-                  timeout
+                    signal: timeout.signal,
+                    remainingMs: timeout.remainingMs()
+                  })
                 );
-                frameRef2 = navigation.data.mainFrame.frameRef;
               }
               return {
-                state: await timeout.runStep(() => this.readSessionState()),
+                state: await timeout.runStep(() => this.readNavigationSummary()),
                 frameRef: frameRef2
               };
             },
@@ -23327,7 +23486,11 @@ var init_runtime3 = __esm({
               "page.new cannot use openerPageRef before a session exists"
             );
           }
-          return this.open(input.url === void 0 ? {} : { url: input.url }, options);
+          const summary = await this.open(input.url === void 0 ? {} : { url: input.url }, options);
+          return {
+            pageRef: await this.ensurePageRef(),
+            ...summary
+          };
         }
         const startedAt = Date.now();
         try {
@@ -23342,7 +23505,7 @@ var init_runtime3 = __esm({
                 })
               );
               this.pageRef = created.data.pageRef;
-              return this.readSessionState();
+              return this.readCreatedPageOutput(created.data.pageRef);
             },
             options
           );
@@ -23384,7 +23547,7 @@ var init_runtime3 = __esm({
                 () => this.requireEngine().activatePage({ pageRef: input.pageRef })
               );
               this.pageRef = input.pageRef;
-              return this.readSessionState();
+              return this.readNavigationSummary(input.pageRef);
             },
             options
           );
@@ -23510,7 +23673,7 @@ var init_runtime3 = __esm({
               timeout.throwIfAborted();
               return {
                 navigation: navigation2,
-                state: await timeout.runStep(() => this.readSessionState())
+                state: await timeout.runStep(() => this.readNavigationSummary(pageRef))
               };
             },
             (diagnostics) => {
@@ -24744,7 +24907,7 @@ var init_runtime3 = __esm({
         let mutationCaptureDiagnostics;
         let boundaryDiagnostics;
         try {
-          const { artifacts, output } = await this.runMutationCapturedOperation(
+          const { artifacts, output, result } = await this.runMutationCapturedOperation(
             "computer.execute",
             {
               ...input.captureNetwork === void 0 ? {} : { captureNetwork: input.captureNetwork },
@@ -24762,9 +24925,14 @@ var init_runtime3 = __esm({
                 await this.invalidateLiveSnapshotCounters([pageRef, output2.pageRef], timeout);
                 this.pageRef = output2.pageRef;
                 const artifacts2 = await this.persistComputerArtifacts(output2, timeout);
+                const result2 = {
+                  ...await timeout.runStep(() => this.readNavigationSummary(output2.pageRef)),
+                  screenshot: artifacts2.screenshot
+                };
                 return {
                   artifacts: { manifests: artifacts2.manifests },
-                  output: artifacts2.output
+                  output: output2,
+                  result: result2
                 };
               } catch (error) {
                 boundaryDiagnostics ??= takeActionBoundaryDiagnostics(timeout.signal);
@@ -24801,7 +24969,7 @@ var init_runtime3 = __esm({
               documentEpoch: output.screenshot.documentEpoch
             })
           });
-          return output;
+          return result;
         } catch (error) {
           await this.appendTrace({
             operation: "computer.execute",
@@ -24949,8 +25117,9 @@ var init_runtime3 = __esm({
               mutationCaptureDiagnostics = diagnostics;
             }
           );
-          const output = toOpensteerActionResult(executed.result);
+          const output = toOpensteerActionResult(executed.result.resolved);
           const actionEvents = "events" in executed.result ? executed.result.events : void 0;
+          const resolvedTarget = toOpensteerResolvedTarget2(executed.result.resolved);
           await this.appendTrace({
             operation,
             startedAt,
@@ -24958,8 +25127,13 @@ var init_runtime3 = __esm({
             outcome: "ok",
             ...actionEvents === void 0 ? {} : { events: actionEvents },
             data: {
-              target: output.target,
-              ...output.point === void 0 ? {} : { point: output.point },
+              target: resolvedTarget,
+              ..."point" in executed.result && executed.result.point !== void 0 ? {
+                point: {
+                  x: executed.result.point.x,
+                  y: executed.result.point.y
+                }
+              } : {},
               ...boundaryDiagnostics === void 0 ? {} : { settle: boundaryDiagnostics },
               ...buildMutationCaptureTraceData(mutationCaptureDiagnostics)
             },
@@ -26424,20 +26598,20 @@ var init_runtime3 = __esm({
           throw error;
         }
       }
-      async readSessionState() {
-        const pageRef = await this.ensurePageRef();
+      async readNavigationSummary(targetPageRef) {
+        const pageRef = targetPageRef ?? await this.ensurePageRef();
         const pageInfo = await this.requireEngine().getPageInfo({ pageRef });
-        const sessionRef = this.sessionRef;
-        if (!sessionRef) {
-          throw new Error("Opensteer session is not initialized");
-        }
         return {
-          sessionRef,
-          pageRef,
           url: pageInfo.url,
           title: pageInfo.title
         };
       }
+      async readCreatedPageOutput(pageRef) {
+        return {
+          pageRef,
+          ...await this.readNavigationSummary(pageRef)
+        };
+      }
       async captureSnapshotArtifacts(pageRef, options, timeout) {
         const root = this.requireRoot();
         const mainFrame = await timeout.runStep(() => getMainFrame(this.requireEngine(), pageRef));
@@ -26509,12 +26683,12 @@ var init_runtime3 = __esm({
         const screenshotPayload = manifestToExternalBinaryLocation(root.rootPath, screenshotManifest);
         return {
           manifests,
-          output: {
-            ...output,
-            screenshot: {
-              ...output.screenshot,
-              payload: screenshotPayload
-            }
+          screenshot: {
+            payload: screenshotPayload,
+            format: output.screenshot.format,
+            size: output.screenshot.size,
+            coordinateSpace: output.screenshot.coordinateSpace,
+            ...output.screenshot.clip === void 0 ? {} : { clip: output.screenshot.clip }
           }
         };
       }
@@ -28599,7 +28773,11 @@ function generateReplayScript(options) {
     ``,
     ...renderOpensteerBootstrap(replayTarget),
     ``,
-    `const ${initialPageId} = (await opensteer.open(${JSON.stringify(initialPages[0]?.initialUrl ?? "")})).pageRef;`,
+    `await opensteer.open(${JSON.stringify(initialPages[0]?.initialUrl ?? "")});`,
+    `const ${initialPageId} = (await opensteer.listPages()).activePageRef;`,
+    `if (!${initialPageId}) {`,
+    `  throw new Error("Opensteer did not report an active page after open().");`,
+    `}`,
     `let activePageRef: string | undefined = ${initialPageId};`,
     ``,
     `async function ensureActive(pageRef: string): Promise<void> {`,
@@ -29528,8 +29706,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 +29738,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 +29748,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 +29765,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 +29796,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 +29913,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 +29980,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 +30009,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 +30058,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 +30070,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 +30078,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 +30113,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 +30177,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 +30564,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 +30655,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 +30681,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 +30746,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 +30780,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 +31038,7 @@ var init_opensteer = __esm({
 
 // package.json
 var package_default = {
-  version: "0.9.5"};
+  version: "0.9.7"};
 
 // src/cli/bin.ts
 init_browser_manager();
@@ -30624,6 +31053,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 +31418,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 +31447,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 +31494,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 +31557,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 +31588,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 +31597,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 +31618,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 +31628,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 +31648,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 +31681,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 +31693,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 +31716,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 +31747,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 +31783,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 +31794,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 +31802,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 +31833,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 +31863,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 +31873,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 +31922,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 +31937,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 +31945,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 +31993,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 +32004,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 +32020,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 +32075,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 +32126,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 +32161,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 +32169,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;
 }
@@ -31644,6 +32196,7 @@ function joinRest(rest, startIndex) {
 function renderOperationOutput(operation, result, input) {
   switch (operation) {
     case "session.open":
+    case "page.activate":
     case "page.goto":
       return renderJson(formatNavigationOutput(result));
     case "page.snapshot":
@@ -31652,14 +32205,14 @@ function renderOperationOutput(operation, result, input) {
     case "dom.hover":
     case "dom.input":
     case "dom.scroll":
-      return renderJson(formatActionOutput(result, input));
+      return renderJson(formatActionOutput(result));
     case "dom.extract":
       return renderJson(formatExtractOutput(result));
     case "page.list":
-    case "page.new":
-    case "page.activate":
     case "page.close":
       return formatTabOutput(result);
+    case "page.new":
+      return renderJson(formatCreatedPageOutput(result));
     case "network.query":
       return formatNetworkQueryOutput(result, input);
     case "network.detail":
@@ -31697,6 +32250,12 @@ function formatNavigationOutput(result) {
     ...readStringField(result, "title") === void 0 ? {} : { title: readStringField(result, "title") }
   };
 }
+function formatCreatedPageOutput(result) {
+  return {
+    ...readStringField(result, "pageRef") === void 0 ? {} : { pageRef: readStringField(result, "pageRef") },
+    ...formatNavigationOutput(result)
+  };
+}
 function formatSnapshotOutput(result) {
   if (result !== null && typeof result === "object" && typeof result.html === "string") {
     return `${result.html}
@@ -31704,36 +32263,11 @@ function formatSnapshotOutput(result) {
   }
   return renderJson(result);
 }
-function formatActionOutput(result, input) {
-  const target = readObjectField(result, "target");
-  const output = {
-    ...readStringField(target, "tagName") === void 0 ? {} : { tagName: readStringField(target, "tagName") },
-    ...readStringField(target, "pathHint") === void 0 ? {} : { pathHint: readStringField(target, "pathHint") }
+function formatActionOutput(result) {
+  return {
+    ...readStringField(result, "tagName") === void 0 ? {} : { tagName: readStringField(result, "tagName") },
+    ...readStringField(result, "persist") === void 0 ? {} : { persist: readStringField(result, "persist") }
   };
-  const point = readObjectField(result, "point");
-  if (point !== void 0) {
-    output.point = {
-      ...readNumberField(point, "x") === void 0 ? {} : { x: readNumberField(point, "x") },
-      ...readNumberField(point, "y") === void 0 ? {} : { y: readNumberField(point, "y") }
-    };
-  }
-  const persist = readStringField(target, "persist");
-  if (persist !== void 0) {
-    output.persist = persist;
-  }
-  const text = readStringField(input, "text");
-  if (text !== void 0) {
-    output.text = text;
-  }
-  const direction = readStringField(input, "direction");
-  if (direction !== void 0) {
-    output.direction = direction;
-  }
-  const amount = readNumberField(input, "amount");
-  if (amount !== void 0) {
-    output.amount = amount;
-  }
-  return output;
 }
 function formatExtractOutput(result) {
   const data = readUnknownField(result, "data");
@@ -31965,20 +32499,18 @@ function formatStateOutput(result) {
 `;
 }
 function formatComputerOutput(result) {
-  const action = readObjectField(result, "action");
   const screenshot = readObjectField(result, "screenshot");
   const payload = readObjectField(screenshot, "payload");
-  const timing = readObjectField(result, "timing");
   return {
-    ...action === void 0 ? {} : { action },
+    ...readStringField(result, "url") === void 0 ? {} : { url: readStringField(result, "url") },
+    ...readStringField(result, "title") === void 0 ? {} : { title: readStringField(result, "title") },
     ...payload === void 0 ? {} : {
       screenshot: {
         ...readStringField(payload, "uri") === void 0 ? {} : { uri: readStringField(payload, "uri") },
         ...readStringField(screenshot, "format") === void 0 ? {} : { format: readStringField(screenshot, "format") },
         ...readObjectField(screenshot, "size") === void 0 ? {} : { size: readObjectField(screenshot, "size") }
       }
-    },
-    ...timing === void 0 ? {} : { timingMs: timing }
+    }
   };
 }
 function formatScriptsCaptureOutput(result) {
@@ -32640,7 +33172,7 @@ async function collectOpensteerStatus(input) {
     ...output,
     rootPath,
     lanes: {
-      local: describeLocalLane(localRecord, input.provider.mode === "local"),
+      local: await describeLocalLane(localRecord, input.provider.mode === "local"),
       cloud: await describeCloudLane({
         record: cloudRecord,
         current: input.provider.mode === "cloud",
@@ -32692,8 +33224,38 @@ async function readWorkspaceCloudRecord(rootPath) {
   }
   return readPersistedCloudSessionRecord(rootPath);
 }
-function describeLocalLane(record, current) {
-  if (record === void 0 || !isProcessRunning(record.pid)) {
+async function describeLocalLane(record, current) {
+  if (record === void 0) {
+    return {
+      provider: "local",
+      status: "idle",
+      current,
+      summary: "none"
+    };
+  }
+  if (getPersistedLocalBrowserSessionOwnership(record) === "attached") {
+    if (!await isAttachedLocalBrowserSessionReachable(record)) {
+      return {
+        provider: "local",
+        status: "stale",
+        current,
+        summary: "attached browser unavailable",
+        detail: record.engine,
+        engine: record.engine
+      };
+    }
+    const browser2 = record.executablePath ? path10__default.default.basename(record.executablePath).replace(/\.[A-Za-z0-9]+$/u, "") : void 0;
+    return {
+      provider: "local",
+      status: "active",
+      current,
+      summary: "attached browser",
+      detail: browser2 ?? record.engine,
+      engine: record.engine,
+      ...browser2 === void 0 ? {} : { browser: browser2 }
+    };
+  }
+  if (!isProcessRunning(record.pid)) {
     return {
       provider: "local",
       status: "idle",
@@ -32844,13 +33406,13 @@ async function resolveSessionSummary(manifest) {
   return {
     sessionId: manifest.sessionId,
     label: manifest.workspace ?? (path10__default.default.basename(manifest.rootPath) || manifest.sessionId),
-    status: isProcessRunning(record.pid) ? "live" : "stale",
+    status: getPersistedLocalBrowserSessionOwnership(record) === "attached" || isProcessRunning(record.pid) ? "live" : "stale",
     ...manifest.workspace === void 0 ? {} : { workspace: manifest.workspace },
     rootPath: manifest.rootPath,
     engine: record.engine,
     ownership: manifest.ownership,
-    pid: record.pid,
     startedAt: record.startedAt,
+    ...record.pid > 0 ? { pid: record.pid } : {},
     ...browserName === void 0 ? {} : { browserName }
   };
 }
@@ -32878,7 +33440,16 @@ async function readLiveRecord(manifest) {
   if (!record) {
     return void 0;
   }
-  if (record.pid !== manifest.pid || record.startedAt !== manifest.startedAt || !isProcessRunning(record.pid)) {
+  if (buildLocalViewSessionIdForRecord({
+    rootPath: manifest.rootPath,
+    live: record
+  }) !== manifest.sessionId || record.startedAt !== manifest.startedAt || record.engine !== manifest.engine || getPersistedLocalBrowserSessionOwnership(record) !== manifest.ownership) {
+    return void 0;
+  }
+  if (getPersistedLocalBrowserSessionOwnership(record) === "attached") {
+    return await isAttachedLocalBrowserSessionReachable(record) ? record : void 0;
+  }
+  if (record.pid !== manifest.pid || !isProcessRunning(record.pid)) {
     return void 0;
   }
   return record;
@@ -34610,7 +35181,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);
@@ -34647,18 +35218,27 @@ async function resolveWorkspaceSessionId(input) {
     workspace: input.workspace
   });
   const live = await readPersistedLocalBrowserSessionRecord(rootPath);
-  if (!live || !isProcessRunning(live.pid)) {
+  if (!live) {
     return void 0;
   }
-  return buildLocalViewSessionId({
+  if (getPersistedLocalBrowserSessionOwnership(live) === "attached") {
+    if (!await isAttachedLocalBrowserSessionReachable(live)) {
+      return void 0;
+    }
+  } else if (!isProcessRunning(live.pid)) {
+    return void 0;
+  }
+  return buildLocalViewSessionIdForRecord({
     rootPath,
-    pid: live.pid,
-    startedAt: live.startedAt
+    live
   });
 }
 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 +35323,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 +35348,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 +35416,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 +35432,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 +35456,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 +35483,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 +35516,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 +35556,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 +35628,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 +35689,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 +35724,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;