opendevbrowser 0.0.17 → 0.0.18

package/dist/cli/index.js

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
 import {
+  CLI_COMMANDS,
+  CLI_COMMAND_HELP_DETAILS,
   DaemonClient,
   EXIT_DISCONNECTED,
   EXIT_EXECUTION,
   EXIT_USAGE,
+  PUBLIC_CLI_COMMAND_GROUPS,
+  TOOL_SURFACE_ENTRIES,
+  VALID_EQUALS_FLAGS,
+  VALID_FLAGS,
   buildAnnotateResult,
   callDaemon,
   createOpenDevBrowserCore,
@@ -14,82 +20,35 @@ import {
   fetchWithTimeout,
   formatErrorPayload,
   generateSecureToken,
+  getChromeUserDataRoots,
   getExtensionPath,
+  getProfileDirs,
   loadGlobalConfig,
+  onboarding_metadata_default,
   readDaemonMetadata,
+  readProfilePreferences,
   resolveExitCode,
   startDaemon,
   toCliError
-} from "../chunk-5J3IFL3X.js";
+} from "../chunk-L57D35TB.js";
+import {
+  getBundledSkillsDir,
+  listBundledSkillDirectories
+} from "../chunk-YBQECXZX.js";
 import "../chunk-Y2KL55OG.js";
 import {
   writeFileAtomic
 } from "../chunk-TBUCZX4A.js";
-import "../chunk-V7KUDHDG.js";
 import {
-  cleanupExpiredArtifacts
-} from "../chunk-D633UO34.js";
+  cleanupExpiredArtifacts,
+  isChallengeAutomationMode,
+  setDefaultLogSink,
+  stderrSink,
+  summarizePrimaryProviderIssue
+} from "../chunk-5FZQJRBQ.js";
 import "../chunk-FUSXMW3G.js";
 
 // src/cli/args.ts
-var CLI_COMMANDS = [
-  "install",
-  "update",
-  "uninstall",
-  "help",
-  "version",
-  "serve",
-  "daemon",
-  "native",
-  "run",
-  "launch",
-  "connect",
-  "disconnect",
-  "status",
-  "research",
-  "shopping",
-  "product-video",
-  "artifacts",
-  "goto",
-  "wait",
-  "snapshot",
-  "click",
-  "hover",
-  "press",
-  "check",
-  "uncheck",
-  "type",
-  "select",
-  "scroll",
-  "scroll-into-view",
-  "targets-list",
-  "target-use",
-  "target-new",
-  "target-close",
-  "page",
-  "pages",
-  "page-close",
-  "dom-html",
-  "dom-text",
-  "dom-attr",
-  "dom-value",
-  "dom-visible",
-  "dom-enabled",
-  "dom-checked",
-  "clone-page",
-  "clone-component",
-  "perf",
-  "screenshot",
-  "console-poll",
-  "network-poll",
-  "debug-trace-snapshot",
-  "cookie-import",
-  "cookie-list",
-  "macro-resolve",
-  "annotate",
-  "canvas",
-  "rpc"
-];
 var CLI_COMMAND_SET = new Set(CLI_COMMANDS);
 var SHORT_FLAGS = {
   "-g": "--global",
@@ -153,158 +112,7 @@ function parseTransport(args) {
   }
   throw createUsageError(`Invalid --transport: ${value ?? "missing"}`);
 }
-var VALID_FLAGS = [
-  "--global",
-  "--local",
-  "--update",
-  "--uninstall",
-  "--help",
-  "--version",
-  "--with-config",
-  "--no-prompt",
-  "--no-interactive",
-  "--quiet",
-  "--output-format",
-  "--full",
-  "--port",
-  "--token",
-  "--stop",
-  "--script",
-  "--headless",
-  "--profile",
-  "--persist-profile",
-  "--chrome-path",
-  "--start-url",
-  "--flag",
-  "--session-id",
-  "--close-browser",
-  "--ws-endpoint",
-  "--host",
-  "--cdp-port",
-  "--url",
-  "--wait-until",
-  "--timeout-ms",
-  "--ref",
-  "--state",
-  "--until",
-  "--mode",
-  "--max-chars",
-  "--cursor",
-  "--text",
-  "--clear",
-  "--submit",
-  "--values",
-  "--dy",
-  "--key",
-  "--attr",
-  "--name",
-  "--target-id",
-  "--tab-id",
-  "--include-urls",
-  "--path",
-  "--since-seq",
-  "--max",
-  "--since-console-seq",
-  "--since-network-seq",
-  "--since-exception-seq",
-  "--request-id",
-  "--cookies",
-  "--cookies-file",
-  "--strict",
-  "--expression",
-  "--default-provider",
-  "--include-catalog",
-  "--command",
-  "--execute",
-  "--params",
-  "--params-file",
-  "--unsafe-internal",
-  "--daemon",
-  "--transport",
-  "--no-extension",
-  "--extension-only",
-  "--extension-legacy",
-  "--wait-for-extension",
-  "--wait-timeout-ms",
-  "--skills-global",
-  "--skills-local",
-  "--no-skills",
-  "--screenshot-mode",
-  "--debug",
-  "--context",
-  "--stored",
-  "--topic",
-  "--days",
-  "--from",
-  "--to",
-  "--source-selection",
-  "--sources",
-  "--include-engagement",
-  "--limit-per-source",
-  "--query",
-  "--providers",
-  "--budget",
-  "--region",
-  "--sort",
-  "--product-url",
-  "--product-name",
-  "--provider-hint",
-  "--include-screenshots",
-  "--include-all-images",
-  "--include-copy",
-  "--output-dir",
-  "--ttl-hours",
-  "--expired-only"
-];
 var VALID_FLAG_SET = new Set(VALID_FLAGS);
-var VALID_EQUALS_FLAGS = [
-  "--output-format",
-  "--transport",
-  "--session-id",
-  "--url",
-  "--screenshot-mode",
-  "--context",
-  "--timeout-ms",
-  "--since-seq",
-  "--since-console-seq",
-  "--since-network-seq",
-  "--since-exception-seq",
-  "--max",
-  "--target-id",
-  "--tab-id",
-  "--name",
-  "--cookies",
-  "--cookies-file",
-  "--persist-profile",
-  "--expression",
-  "--default-provider",
-  "--command",
-  "--request-id",
-  "--strict",
-  "--params",
-  "--params-file",
-  "--topic",
-  "--days",
-  "--from",
-  "--to",
-  "--source-selection",
-  "--sources",
-  "--mode",
-  "--limit-per-source",
-  "--query",
-  "--providers",
-  "--budget",
-  "--region",
-  "--sort",
-  "--product-url",
-  "--product-name",
-  "--provider-hint",
-  "--include-screenshots",
-  "--include-all-images",
-  "--include-copy",
-  "--output-dir",
-  "--ttl-hours"
-];
 var VALID_EQUALS_FLAG_SET = new Set(VALID_EQUALS_FLAGS);
 function parseArgs(argv) {
   let args = expandShortFlags(argv.slice(2));
@@ -451,77 +259,28 @@ function listCommands() {
 
 // src/cli/help.ts
 var LABEL_WIDTH = 42;
-var EXPECTED_TOOL_COUNT = 49;
+var DETAIL_LABEL_WIDTH = 9;
 var COMMAND_SET = new Set(CLI_COMMANDS);
 var FLAG_SET = new Set(VALID_FLAGS);
-var HELP_COMMAND_GROUPS = [
-  {
-    title: "Install & Lifecycle",
-    summary: "Install, remove, and inspect CLI basics.",
-    commands: ["install", "update", "uninstall", "help", "version"]
-  },
-  {
-    title: "Daemon & Runtime",
-    summary: "Run daemon services and single-process scripts.",
-    commands: ["serve", "daemon", "native", "run"]
-  },
-  {
-    title: "Session Lifecycle",
-    summary: "Launch/connect sessions and manage browser state.",
-    commands: ["launch", "connect", "disconnect", "status", "cookie-import", "cookie-list"]
-  },
-  {
-    title: "Provider Workflows",
-    summary: "Run research/shopping/media workflows and macro plans.",
-    commands: ["research", "shopping", "product-video", "artifacts", "macro-resolve"]
-  },
-  {
-    title: "Design Canvas",
-    summary: "Execute design-canvas session, document, overlay, and preview commands.",
-    commands: ["canvas"]
-  },
-  {
-    title: "Navigation",
-    summary: "Move through pages and capture fresh refs.",
-    commands: ["goto", "wait", "snapshot"]
-  },
-  {
-    title: "Interaction",
-    summary: "Perform ref-based interactions in the active page.",
-    commands: ["click", "hover", "press", "check", "uncheck", "type", "select", "scroll", "scroll-into-view"]
-  },
-  {
-    title: "Targets & Pages",
-    summary: "Manage tabs/targets and named pages.",
-    commands: ["targets-list", "target-use", "target-new", "target-close", "page", "pages", "page-close"]
-  },
-  {
-    title: "DOM & Export",
-    summary: "Read DOM state and export page/component code.",
-    commands: ["dom-html", "dom-text", "dom-attr", "dom-value", "dom-visible", "dom-enabled", "dom-checked", "clone-page", "clone-component"]
-  },
-  {
-    title: "Diagnostics & Annotation",
-    summary: "Collect runtime diagnostics and annotation payloads.",
-    commands: ["perf", "screenshot", "console-poll", "network-poll", "debug-trace-snapshot", "annotate"]
-  },
-  {
-    title: "Power",
-    summary: "Unsafe internal command passthrough.",
-    commands: ["rpc"]
-  }
-];
+var TOOL_COUNT = TOOL_SURFACE_ENTRIES.length;
+var formatFlags = (flags) => flags.length > 0 ? flags.join(", ") : "none";
+var HELP_COMMAND_GROUPS = PUBLIC_CLI_COMMAND_GROUPS.map((group) => ({
+  title: group.title,
+  summary: group.summary,
+  commands: group.commands.map((command) => command.name)
+}));
+var COMMAND_HELP_DETAILS = CLI_COMMAND_HELP_DETAILS;
 var HELP_FLAG_GROUPS = [
   {
-    title: "Install/Global Flags",
-    summary: "Control installation scope and setup behavior.",
+    title: "Install / Global Flags",
+    summary: "Control install scope, prompting, and bundled skill setup.",
     flags: [
-      { flag: "--global", alias: "-g", description: "Install into ~/.config/opencode/opencode.json." },
-      { flag: "--local", alias: "-l", description: "Install into ./opencode.json for this project." },
+      { flag: "--global", alias: "-g", description: "Install into ~/.config/opencode/opencode.json.", example: "npx opendevbrowser --global --with-config" },
+      { flag: "--local", alias: "-l", description: "Install into ./opencode.json for this project.", example: "npx opendevbrowser --local --skills-local" },
       { flag: "--update", alias: "-u", description: "Alias for the update command." },
       { flag: "--uninstall", description: "Alias for the uninstall command." },
-      { flag: "--with-config", description: "Also create opendevbrowser.jsonc defaults." },
-      { flag: "--full", alias: "-f", description: "Install config and pre-extract extension assets." },
+      { flag: "--with-config", description: "Also create opendevbrowser.jsonc defaults.", example: "npx opendevbrowser --global --with-config" },
+      { flag: "--full", alias: "-f", description: "Install config and pre-extract extension assets.", example: "npx opendevbrowser --full" },
       { flag: "--no-prompt", description: "Run non-interactively using defaults." },
       { flag: "--no-interactive", description: "Alias of --no-prompt." },
       { flag: "--quiet", description: "Suppress non-error text output." },
@@ -531,179 +290,241 @@ var HELP_FLAG_GROUPS = [
     ]
   },
   {
-    title: "Help/Output Flags",
-    summary: "Inspect help/version and control output transport.",
+    title: "Help / Output Flags",
+    summary: "Inspect help or version and control output transport.",
     flags: [
-      { flag: "--help", alias: "-h", description: "Show CLI help output." },
-      { flag: "--version", alias: "-v", description: "Show CLI version." },
-      { flag: "--output-format", description: "Output mode: text, json, stream-json." },
-      { flag: "--transport", description: "Transport selector for transport-aware commands. `status` uses relay/native; `annotate` uses auto/direct/relay." }
+      { flag: "--help", alias: "-h", description: "Show CLI help output.", example: "npx opendevbrowser --help" },
+      { flag: "--version", alias: "-v", description: "Show CLI version.", example: "npx opendevbrowser --version" },
+      { flag: "--output-format", description: "Output mode: text, json, or stream-json.", example: "opendevbrowser status --daemon --output-format json" },
+      { flag: "--transport", description: "Transport selector for transport-aware commands. `status` uses relay/native; `annotate` uses auto/direct/relay.", example: "opendevbrowser status --session-id s1 --transport native" }
     ]
   },
   {
-    title: "Daemon/Session/Launch Flags",
-    summary: "Control daemon binding, connect, and launch behavior.",
+    title: "Daemon / Session / Launch Flags",
+    summary: "Control daemon binding, browser connect, and launch behavior. If ext=on but handshake=off, reopen the extension popup and click Connect again to re-establish a clean daemon-extension handshake.",
     flags: [
-      { flag: "--port", description: "Daemon or relay port override." },
-      { flag: "--token", description: "Relay/daemon auth token override." },
-      { flag: "--stop", description: "Stop a running daemon." },
-      { flag: "--daemon", description: "Target daemon status mode where supported." },
-      { flag: "--script", description: "Path to a run-script JSON file." },
-      { flag: "--session-id", description: "Target an existing daemon session." },
-      { flag: "--close-browser", description: "Close managed browser on disconnect." },
-      { flag: "--ws-endpoint", description: "Connect using explicit CDP WebSocket endpoint." },
-      { flag: "--host", description: "CDP host for host/port connect mode." },
+      { flag: "--port", description: "Daemon or relay port override.", example: "opendevbrowser serve --port 8788" },
+      { flag: "--token", description: "Relay or daemon auth token override.", example: "opendevbrowser serve --token local-dev-token" },
+      { flag: "--stop", description: "Stop a running daemon.", example: "opendevbrowser serve --stop" },
+      { flag: "--daemon", description: "Target daemon status mode where supported.", example: "opendevbrowser status --daemon --output-format json" },
+      { flag: "--script", description: "Path to a run-script JSON file.", example: "opendevbrowser run --script ./workflow.json" },
+      { flag: "--session-id", description: "Target an existing browser or daemon session.", example: "opendevbrowser snapshot --session-id s1" },
+      { flag: "--close-browser", description: "Close the managed browser on disconnect." },
+      { flag: "--ws-endpoint", description: "Connect using an explicit CDP WebSocket endpoint.", example: "opendevbrowser connect --ws-endpoint ws://127.0.0.1:9222/devtools/browser/..." },
+      { flag: "--host", description: "CDP host for host/port connect mode.", example: "opendevbrowser connect --host 127.0.0.1 --cdp-port 9222" },
       { flag: "--cdp-port", description: "CDP port for host/port connect mode." },
-      { flag: "--headless", description: "Launch managed browser in headless mode." },
+      { flag: "--headless", description: "Launch a managed browser in headless mode.", example: "opendevbrowser launch --no-extension --headless" },
       { flag: "--profile", description: "Use a named browser profile directory." },
-      { flag: "--persist-profile", description: "Keep generated profile directory after exit." },
-      { flag: "--chrome-path", description: "Use a specific Chrome/Chromium binary." },
+      { flag: "--persist-profile", description: "Keep the generated profile directory after exit. `run` uses a temporary profile by default unless this flag is enabled." },
+      { flag: "--chrome-path", description: "Use a specific Chrome, Chromium, or CfT binary." },
       { flag: "--start-url", description: "Open this URL immediately after launch or connect." },
       { flag: "--flag", description: "Pass one or more extra Chrome CLI flags." },
       { flag: "--no-extension", description: "Force managed mode without extension relay." },
-      { flag: "--extension-only", description: "Fail unless extension relay is connected." },
-      { flag: "--extension-legacy", description: "Use legacy /cdp relay mode instead of /ops." },
-      { flag: "--wait-for-extension", description: "Wait for extension handshake before returning." },
+      { flag: "--extension-only", description: "Fail unless the extension relay websocket is connected and the daemon-extension handshake is complete." },
+      { flag: "--extension-legacy", description: "Use the legacy /cdp relay mode instead of /ops." },
+      { flag: "--wait-for-extension", description: "Wait for a clean daemon-extension handshake before returning." },
       { flag: "--wait-timeout-ms", description: "Handshake wait timeout in milliseconds." }
     ]
   },
   {
-    title: "Navigation/Interaction/Diagnostics Flags",
-    summary: "Command-specific flags for page actions and diagnostics.",
+    title: "Navigation / Interaction / Diagnostics Flags",
+    summary: "Command-specific flags for page actions, reads, and diagnostics.",
     flags: [
-      { flag: "--url", description: "Target URL for navigation, connect, or workflow commands." },
-      { flag: "--wait-until", description: "Navigation wait strategy (load, domcontentloaded, etc.)." },
-      { flag: "--timeout-ms", description: "Operation timeout in milliseconds (for example goto, wait, screenshot, annotate, canvas, rpc, and macro-resolve)." },
-      { flag: "--ref", description: "Snapshot ref id for element-targeted commands." },
+      { flag: "--url", description: "Target URL for navigation, connect, or workflow commands.", example: "opendevbrowser goto --session-id s1 --url https://example.com" },
+      { flag: "--wait-until", description: "Navigation wait strategy such as load or domcontentloaded." },
+      { flag: "--timeout-ms", description: "Operation timeout in milliseconds.", example: "opendevbrowser canvas --timeout-ms 120000 --command canvas.session.open ..." },
+      { flag: "--ref", description: "Snapshot ref id for element-targeted commands.", example: "opendevbrowser click --session-id s1 --ref r12" },
       { flag: "--state", description: "Wait state selector for wait-style commands." },
       { flag: "--until", description: "Wait condition selector for wait-style commands." },
       { flag: "--mode", description: "Mode selector for commands that accept variants." },
       { flag: "--max-chars", description: "Maximum text characters to return for DOM reads." },
       { flag: "--cursor", description: "Cursor token for paginated list commands." },
       { flag: "--text", description: "Text payload for type and related commands." },
-      { flag: "--clear", description: "Clear existing input value before typing." },
-      { flag: "--submit", description: "Submit form/input after typing." },
+      { flag: "--clear", description: "Clear the existing input value before typing." },
+      { flag: "--submit", description: "Submit the form or input after typing." },
       { flag: "--values", description: "CSV values for select commands." },
+      { flag: "--files", description: "CSV file paths for upload commands." },
       { flag: "--dy", description: "Vertical scroll delta for scroll commands." },
-      { flag: "--key", description: "Keyboard key for press command." },
-      { flag: "--attr", description: "DOM attribute name for dom-attr command." },
+      { flag: "--key", description: "Keyboard key for the press command." },
+      { flag: "--attr", description: "DOM attribute name for dom-attr." },
+      { flag: "--x", description: "Viewport x coordinate for pointer commands." },
+      { flag: "--y", description: "Viewport y coordinate for pointer commands." },
+      { flag: "--from-x", description: "Pointer drag start x coordinate." },
+      { flag: "--from-y", description: "Pointer drag start y coordinate." },
+      { flag: "--to-x", description: "Pointer drag end x coordinate." },
+      { flag: "--to-y", description: "Pointer drag end y coordinate." },
+      { flag: "--steps", description: "Interpolation step count for pointer move or drag commands." },
+      { flag: "--button", description: "Pointer button selector for pointer down or up." },
+      { flag: "--click-count", description: "Associated click count for pointer down or up." },
       { flag: "--name", description: "Named page identifier for page commands." },
-      { flag: "--target-id", description: "Browser target id for target commands." },
-      { flag: "--tab-id", description: "Browser tab id override for extension/annotation commands." },
+      { flag: "--target-id", description: "Browser target id for target commands.", example: "opendevbrowser target-use --session-id s1 --target-id page-2" },
+      { flag: "--window-id", description: "Desktop window id for direct window capture commands." },
+      { flag: "--tab-id", description: "Browser tab id override for extension and annotation commands." },
       { flag: "--include-urls", description: "Include page URLs in list output where supported." },
-      { flag: "--path", description: "Filesystem path for command output/artifacts." },
-      { flag: "--since-seq", description: "Poll from sequence id across diagnostics streams." },
-      { flag: "--max", description: "Maximum number of records/items to return." },
-      { flag: "--since-console-seq", description: "Console sequence cursor for debug trace snapshots." },
-      { flag: "--since-network-seq", description: "Network sequence cursor for debug trace snapshots." },
-      { flag: "--since-exception-seq", description: "Exception sequence cursor for debug trace snapshots." },
-      { flag: "--request-id", description: "Attach/lookup request id for correlateable output." },
-      { flag: "--cookies", description: "Inline cookie payload for cookie-import command." },
+      { flag: "--path", description: "Filesystem path for command output or artifacts.", example: "opendevbrowser screenshot --session-id s1 --path ./shot.png" },
+      { flag: "--screencast-id", description: "Recorded screencast id returned by screencast-start for the same session." },
+      { flag: "--reason", description: "Audit reason for desktop observation commands." },
+      { flag: "--full-page", description: "Capture the full scrollable page instead of the current viewport." },
+      { flag: "--action", description: "Dialog action: status, accept, or dismiss." },
+      { flag: "--prompt-text", description: "Prompt text to submit when accepting a prompt dialog." },
+      { flag: "--since-seq", description: "Poll from a sequence id across diagnostics streams." },
+      { flag: "--max", description: "Maximum number of records or items to return." },
+      { flag: "--interval-ms", description: "Frame capture interval for screencast recording." },
+      { flag: "--max-frames", description: "Maximum screencast frame count before auto-stop." },
+      { flag: "--since-console-seq", description: "Console sequence cursor for debug-trace snapshots." },
+      { flag: "--since-network-seq", description: "Network sequence cursor for debug-trace snapshots." },
+      { flag: "--since-exception-seq", description: "Exception sequence cursor for debug-trace snapshots." },
+      { flag: "--request-id", description: "Attach or lookup a request id for correlated output." },
+      { flag: "--cookies", description: "Inline cookie payload for cookie-import." },
       { flag: "--cookies-file", description: "File path containing cookies for cookie-import." },
       { flag: "--strict", description: "Fail cookie import on invalid entries." },
       { flag: "--screenshot-mode", description: "Annotation screenshot mode: visible, full, or none." },
       { flag: "--debug", description: "Enable debug-level annotation capture extras." },
-      { flag: "--context", description: "Free-form annotation context for reviewers/agents." },
+      { flag: "--context", description: "Free-form annotation context for reviewers or agents." },
       { flag: "--stored", description: "Return the last stored annotation payload instead of starting a new capture." }
     ]
   },
   {
-    title: "Macro/Provider/Power Flags",
-    summary: "Workflow filters, provider selectors, and unsafe RPC options.",
+    title: "Macro / Provider / Power Flags",
+    summary: "Workflow filters, provider selectors, and unsafe RPC or /canvas options.",
     flags: [
-      { flag: "--expression", description: "Macro expression to resolve/execute." },
+      { flag: "--expression", description: "Macro expression to resolve or execute.", example: `opendevbrowser macro-resolve --expression '@web.search("openai")'` },
       { flag: "--default-provider", description: "Provider fallback for shorthand macro expressions." },
-      { flag: "--include-catalog", description: "Include macro catalog metadata in response." },
-      { flag: "--execute", description: "Execute resolved macro action after planning (pair with --timeout-ms on slow runs)." },
-      { flag: "--command", description: "Canvas command name for the canvas CLI command." },
+      { flag: "--include-catalog", description: "Include macro catalog metadata in the response." },
+      { flag: "--command", description: "Canvas command name for the canvas CLI command.", example: "opendevbrowser canvas --command canvas.session.open --params '{...}'" },
+      { flag: "--execute", description: "Execute a resolved macro action after planning." },
       { flag: "--params", description: "Inline JSON params for canvas or rpc commands." },
-      { flag: "--params-file", description: "Path to JSON params file for canvas or rpc commands." },
-      { flag: "--unsafe-internal", description: "Required safety gate for rpc command." },
+      { flag: "--params-file", description: "Path to a JSON params file for canvas or rpc commands.", example: "opendevbrowser canvas --command canvas.plan.set --params-file ./plan.json" },
+      { flag: "--unsafe-internal", description: "Required safety gate for the rpc command." },
       { flag: "--topic", description: "Research topic input." },
       { flag: "--days", description: "Lookback window in days for research commands." },
       { flag: "--from", description: "Start date boundary for research commands." },
       { flag: "--to", description: "End date boundary for research commands." },
-      { flag: "--source-selection", description: "Research source-family selector." },
-      { flag: "--sources", description: "Explicit source selectors within a source family." },
+      { flag: "--source-selection", description: "Research source-family selector. Use auto for generic topical research; add shopping only for deliberate commercial comparison." },
+      { flag: "--sources", description: "Explicit source selectors within a source family. Use shopping only when commercial intent is explicit." },
       { flag: "--include-engagement", description: "Include engagement metrics in research output." },
       { flag: "--limit-per-source", description: "Per-source result cap for research runs." },
       { flag: "--query", description: "Shopping query input." },
-      { flag: "--providers", description: "Comma-separated provider ids for shopping/artifacts." },
+      { flag: "--providers", description: "Comma-separated provider ids for shopping or artifact commands." },
       { flag: "--budget", description: "Budget filter for shopping workflows." },
-      { flag: "--region", description: "Region/country hint for provider selection." },
+      { flag: "--region", description: "Region or country hint for provider selection. Treat it as advisory unless output metadata reports `region_authoritative=true`." },
       { flag: "--sort", description: "Sort mode for shopping results." },
-      { flag: "--product-url", description: "Target product URL for product-video/artifacts workflows." },
-      { flag: "--product-name", description: "Product name override for media workflows." },
+      { flag: "--product-url", description: "Target product URL for product-video workflows." },
+      { flag: "--product-name", description: "Product name override for product-video workflows." },
       { flag: "--provider-hint", description: "Provider hint override for product workflows." },
       { flag: "--include-screenshots", description: "Include screenshots in product presentation output, or prefer screenshots when fetching stored annotations." },
       { flag: "--include-all-images", description: "Include all discovered product images." },
       { flag: "--include-copy", description: "Include product marketing copy metadata." },
-      { flag: "--output-dir", description: "Directory where generated artifacts are written." },
+      { flag: "--use-cookies", description: "Enable or disable provider cookie injection for workflow runs; a bare flag means true.", example: "opendevbrowser shopping run --query 'usb hub' --use-cookies" },
+      { flag: "--browser-mode", description: "Shopping browser-recovery preference: auto, extension, or managed. Use managed for deterministic reruns and extension only when relay-backed auth/session state is required.", example: "opendevbrowser shopping run --query 'wireless ergonomic mouse' --providers shopping/bestbuy,shopping/ebay --browser-mode managed" },
+      { flag: "--challenge-automation-mode", description: "Per-run challenge automation mode for workflow runs and macro-resolve execute: off, browser, or browser_with_helper. Precedence is run > session > config, and the helper remains browser-scoped only.", example: `opendevbrowser macro-resolve --expression '@community.search("openai")' --execute --challenge-automation-mode browser_with_helper` },
+      { flag: "--cookie-policy-override", description: "Per-run workflow cookie policy override: off, auto, or required.", example: "opendevbrowser research run --topic 'agent workflows' --cookie-policy-override required" },
+      { flag: "--cookie-policy", description: "Alias of --cookie-policy-override." },
+      { flag: "--output-dir", description: "Directory where generated artifacts are written, including screencast replay output." },
       { flag: "--ttl-hours", description: "Artifact cache time-to-live in hours." },
       { flag: "--expired-only", description: "List only expired artifacts in artifacts commands." }
     ]
   }
 ];
-var HELP_TOOL_ENTRIES = [
-  { name: "opendevbrowser_launch", description: "Launch a managed browser session." },
-  { name: "opendevbrowser_connect", description: "Connect to an existing browser session." },
-  { name: "opendevbrowser_disconnect", description: "Disconnect a managed or connected session." },
-  { name: "opendevbrowser_status", description: "Inspect session and relay status." },
-  { name: "opendevbrowser_targets_list", description: "List available page targets/tabs." },
-  { name: "opendevbrowser_target_use", description: "Switch active target by id." },
-  { name: "opendevbrowser_target_new", description: "Create a new target/tab." },
-  { name: "opendevbrowser_target_close", description: "Close target/tab by id." },
-  { name: "opendevbrowser_page", description: "Open or focus a named page." },
-  { name: "opendevbrowser_list", description: "List named pages in the session." },
-  { name: "opendevbrowser_close", description: "Close a named page." },
-  { name: "opendevbrowser_goto", description: "Navigate to a URL." },
-  { name: "opendevbrowser_wait", description: "Wait for load/ref/state conditions." },
-  { name: "opendevbrowser_snapshot", description: "Capture AX-tree refs for actions." },
-  { name: "opendevbrowser_click", description: "Click an element by ref." },
-  { name: "opendevbrowser_hover", description: "Hover an element by ref." },
-  { name: "opendevbrowser_press", description: "Send a keyboard key." },
-  { name: "opendevbrowser_check", description: "Check checkbox/radio by ref." },
-  { name: "opendevbrowser_uncheck", description: "Uncheck checkbox/radio by ref." },
-  { name: "opendevbrowser_type", description: "Type text into an input by ref." },
-  { name: "opendevbrowser_select", description: "Set select values by ref." },
-  { name: "opendevbrowser_scroll", description: "Scroll page or element." },
-  { name: "opendevbrowser_scroll_into_view", description: "Scroll target element into view." },
-  { name: "opendevbrowser_dom_get_html", description: "Get HTML for page or ref." },
-  { name: "opendevbrowser_dom_get_text", description: "Get text for page or ref." },
-  { name: "opendevbrowser_get_attr", description: "Read a DOM attribute by ref." },
-  { name: "opendevbrowser_get_value", description: "Read form/control value by ref." },
-  { name: "opendevbrowser_is_visible", description: "Check ref visibility." },
-  { name: "opendevbrowser_is_enabled", description: "Check ref enabled state." },
-  { name: "opendevbrowser_is_checked", description: "Check ref checked state." },
-  { name: "opendevbrowser_run", description: "Execute multi-action automation scripts." },
-  { name: "opendevbrowser_prompting_guide", description: "Return best-practice prompting guidance." },
-  { name: "opendevbrowser_console_poll", description: "Poll redacted console events." },
-  { name: "opendevbrowser_network_poll", description: "Poll redacted network events." },
-  { name: "opendevbrowser_debug_trace_snapshot", description: "Capture page + console + network diagnostics." },
-  { name: "opendevbrowser_cookie_import", description: "Import validated cookies into session." },
-  { name: "opendevbrowser_cookie_list", description: "List cookies in session with optional URL filters." },
-  { name: "opendevbrowser_macro_resolve", description: "Resolve/execute provider macro expressions." },
-  { name: "opendevbrowser_research_run", description: "Run research workflow directly." },
-  { name: "opendevbrowser_shopping_run", description: "Run shopping workflow directly." },
-  { name: "opendevbrowser_product_video_run", description: "Run product-video asset workflow directly." },
-  { name: "opendevbrowser_canvas", description: "Execute a design-canvas command surface call." },
-  { name: "opendevbrowser_clone_page", description: "Export active page into React code." },
-  { name: "opendevbrowser_clone_component", description: "Export component by ref into React code." },
-  { name: "opendevbrowser_perf", description: "Collect browser performance metrics." },
-  { name: "opendevbrowser_screenshot", description: "Capture page screenshot." },
-  { name: "opendevbrowser_annotate", description: "Capture interactive annotations." },
-  { name: "opendevbrowser_skill_list", description: "List available skill packs." },
-  { name: "opendevbrowser_skill_load", description: "Load a specific skill pack." }
+var HELP_TOOL_ENTRIES = TOOL_SURFACE_ENTRIES;
+var HELP_CAPABILITY_ENTRIES = [
+  {
+    label: "screencast / browser replay",
+    description: "Use the public browser replay lane when you need temporal browser evidence before or after a fragile flow.",
+    details: [
+      { label: "cli:", value: "screencast-start, screencast-stop" },
+      { label: "example:", value: "npx opendevbrowser screencast-start --session-id <id> --output-dir ./artifacts/replay" }
+    ]
+  },
+  {
+    label: "desktop observation",
+    description: "Use the public read-only desktop observation plane for sibling desktop evidence on macOS; window inventory and accessibility probes use the local swift command, while screenshots use screencapture outside extension relay.",
+    details: [
+      {
+        label: "cli:",
+        value: "desktop-status, desktop-windows, desktop-active-window, desktop-capture-desktop, desktop-capture-window, desktop-accessibility-snapshot"
+      },
+      { label: "example:", value: "npx opendevbrowser desktop-status --output-format json" }
+    ]
+  },
+  {
+    label: "computer use / browser-scoped computer use",
+    description: "Control the bounded browser-scoped computer-use challenge lane with --challenge-automation-mode; the optional helper is not a desktop agent.",
+    details: [
+      { label: "flag:", value: "--challenge-automation-mode off|browser|browser_with_helper" },
+      { label: "works:", value: "research run, shopping run, product-video run, macro-resolve --execute" },
+      { label: "proof:", value: "review, session-inspector, workflow fallback metadata" }
+    ]
+  }
+];
+var HELP_ONBOARDING_ENTRIES = [
+  {
+    label: "prompting_guide",
+    description: "Load local best-practice guidance before low-level browser commands.",
+    details: [{ label: "tool:", value: onboarding_metadata_default.quickStartCommands.promptingGuide }]
+  },
+  {
+    label: "skill_load",
+    description: `Load ${onboarding_metadata_default.skillName} ${onboarding_metadata_default.skillTopic} directly when you want the canonical quick-start section.`,
+    details: [{ label: "tool:", value: onboarding_metadata_default.quickStartCommands.skillLoad }]
+  },
+  {
+    label: "validated_lanes",
+    description: `Load ${onboarding_metadata_default.skillName} ${onboarding_metadata_default.validatedSkillTopic} when you need the current proven transcript, research, and shopping runbook.`,
+    details: [{ label: "tool:", value: onboarding_metadata_default.quickStartCommands.validatedLanes }]
+  },
+  {
+    label: "skill_list",
+    description: "Inspect bundled and discovered skill packs when you need a different local lane.",
+    details: [{ label: "tool:", value: onboarding_metadata_default.quickStartCommands.skillList }]
+  },
+  {
+    label: "research_reliable",
+    description: "Generic topical research is currently safest with `--source-selection auto`; add shopping only when the task is explicitly commercial.",
+    details: [{ label: "cli:", value: onboarding_metadata_default.quickStartCommands.validatedResearch }]
+  },
+  {
+    label: "shopping_reliable",
+    description: "Start deal hunting with explicit providers in managed mode and only trust regional comparisons when the result reports `region_authoritative=true`.",
+    details: [{ label: "cli:", value: onboarding_metadata_default.quickStartCommands.validatedShopping }]
+  },
+  {
+    label: "happy_path",
+    description: "After guidance, verify a minimal managed happy path before widening into multi-step automation.",
+    details: [{ label: "cli:", value: onboarding_metadata_default.quickStartCommands.happyPath }]
+  },
+  {
+    label: "docs",
+    description: "Use the first-run checklist and canonical skill runbook for proof and deeper operating details.",
+    details: [{
+      label: "paths:",
+      value: `${onboarding_metadata_default.referencePaths.onboardingDoc}, ${onboarding_metadata_default.referencePaths.skillDoc}`
+    }]
+  }
 ];
 var HELP_REFERENCE_ENTRIES = [
-  { label: "docs/CLI.md", description: "Full command docs, flag matrix, and examples." },
-  { label: "docs/SURFACE_REFERENCE.md", description: "Canonical CLI/tool/channel inventory matrix." },
-  { label: "src/tools/index.ts", description: "Code-level tool registry (source of truth)." },
+  { label: "src/cli/onboarding-metadata.json", description: "Canonical first-contact onboarding metadata shared by help, nudges, and proof lanes." },
+  { label: "src/public-surface/source.ts", description: "Authoritative command, usage, flag, and tool surface metadata." },
+  { label: "src/public-surface/generated-manifest.ts", description: "Checked-in generated public-surface snapshot consumed by help and parity tests." },
+  { label: "src/public-surface/generated-manifest.json", description: "Checked-in generated public-surface snapshot consumed by inventory scripts." },
+  { label: "src/cli/args.ts", description: "CLI argument parsing backed by the public-surface source." },
+  { label: "src/cli/help.ts", description: "Human-facing CLI formatting layered on the public-surface source, including the first-contact Find It Fast lookup block." },
+  { label: "src/tools/index.ts", description: "Code-level tool registry." },
+  { label: "docs/CLI.md", description: "Detailed CLI guide and release-gate runbooks." },
+  { label: onboarding_metadata_default.referencePaths.onboardingDoc, description: "First-run checklist for help-led onboarding and happy-path proof." },
+  { label: onboarding_metadata_default.referencePaths.skillDoc, description: "Canonical bundled best-practices runbook and quick-start guidance." },
+  { label: "docs/SURFACE_REFERENCE.md", description: "Canonical CLI, tool, and relay channel inventory." },
   { label: "opendevbrowser --help", description: "Primary full help invocation for quick discovery." },
   { label: "opendevbrowser help", description: "Alias that prints the same full help inventory." }
 ];
 function formatRows(rows) {
-  return rows.map((row) => `  ${row.label.padEnd(LABEL_WIDTH)} ${row.description}`).join("\n");
+  return rows.map((row) => {
+    const lines = [`  ${row.label.padEnd(LABEL_WIDTH)} ${row.description}`];
+    for (const detail of row.details ?? []) {
+      lines.push(`    ${detail.label.padEnd(DETAIL_LABEL_WIDTH)} ${detail.value}`);
+    }
+    return lines.join("\n");
+  }).join("\n");
 }
 function getCommandDescriptions() {
   const descriptions = /* @__PURE__ */ new Map();
@@ -716,6 +537,7 @@ function assertCommandCoverage(commandDescriptions) {
   const seen = /* @__PURE__ */ new Set();
   for (const group of HELP_COMMAND_GROUPS) {
     for (const command of group.commands) {
+      const detail = COMMAND_HELP_DETAILS[command];
       if (!COMMAND_SET.has(command)) {
         throw new Error(`Help references unknown CLI command: ${command}`);
       }
@@ -725,6 +547,14 @@ function assertCommandCoverage(commandDescriptions) {
       if (seen.has(command)) {
         throw new Error(`Help command appears multiple times: ${command}`);
       }
+      if (!detail || !detail.usage.trim()) {
+        throw new Error(`Missing command help metadata: ${command}`);
+      }
+      for (const flag of detail.flags) {
+        if (!FLAG_SET.has(flag)) {
+          throw new Error(`Command help metadata references unknown flag ${flag} for ${command}`);
+        }
+      }
       seen.add(command);
     }
   }
@@ -752,26 +582,39 @@ function assertFlagCoverage() {
   }
 }
 function assertToolCoverage() {
-  if (HELP_TOOL_ENTRIES.length !== EXPECTED_TOOL_COUNT) {
-    throw new Error(`Help tool inventory must list ${EXPECTED_TOOL_COUNT} tools; got ${HELP_TOOL_ENTRIES.length}`);
-  }
   const seen = /* @__PURE__ */ new Set();
   for (const entry of HELP_TOOL_ENTRIES) {
+    if (!entry.name.startsWith("opendevbrowser_")) {
+      throw new Error(`Invalid tool name in help inventory: ${entry.name}`);
+    }
+    if (!entry.description.trim()) {
+      throw new Error(`Help tool is missing a description: ${entry.name}`);
+    }
     if (seen.has(entry.name)) {
       throw new Error(`Help tool appears multiple times: ${entry.name}`);
     }
-    if (!entry.name.startsWith("opendevbrowser_")) {
-      throw new Error(`Invalid tool name in help inventory: ${entry.name}`);
+    if (entry.cliEquivalent && !COMMAND_SET.has(entry.cliEquivalent)) {
+      throw new Error(`Tool metadata references unknown CLI command: ${entry.cliEquivalent}`);
     }
     seen.add(entry.name);
   }
+  if (HELP_TOOL_ENTRIES.length !== TOOL_COUNT) {
+    throw new Error(`Help tool inventory must list ${TOOL_COUNT} tools; got ${HELP_TOOL_ENTRIES.length}`);
+  }
 }
 function formatCommandGroups(commandDescriptions) {
   return HELP_COMMAND_GROUPS.map((group) => {
-    const rows = group.commands.map((command) => ({
-      label: command,
-      description: commandDescriptions.get(command) ?? "Missing command description."
-    }));
+    const rows = group.commands.map((command) => {
+      const detail = COMMAND_HELP_DETAILS[command];
+      return {
+        label: command,
+        description: commandDescriptions.get(command) ?? "Missing command description.",
+        details: [
+          { label: "usage:", value: detail.usage },
+          { label: "flags:", value: formatFlags(detail.flags) }
+        ]
+      };
+    });
     return `${group.title}: ${group.summary}
 ${formatRows(rows)}`;
   }).join("\n\n");
@@ -780,7 +623,8 @@ function formatFlagGroups() {
   return HELP_FLAG_GROUPS.map((group) => {
     const rows = group.flags.map((entry) => ({
       label: entry.alias ? `${entry.flag} (${entry.alias})` : entry.flag,
-      description: entry.description
+      description: entry.description,
+      details: entry.example ? [{ label: "example:", value: entry.example }] : []
     }));
     return `${group.title}: ${group.summary}
 ${formatRows(rows)}`;
@@ -789,9 +633,16 @@ ${formatRows(rows)}`;
 function formatToolEntries() {
   return formatRows(HELP_TOOL_ENTRIES.map((entry) => ({
     label: entry.name,
-    description: entry.description
+    description: entry.description,
+    details: entry.cliEquivalent ? [{ label: "cli:", value: entry.cliEquivalent }] : [{ label: "scope:", value: "tool-only" }]
   })));
 }
+function formatOnboardingEntries() {
+  return formatRows(HELP_ONBOARDING_ENTRIES);
+}
+function formatCapabilityEntries() {
+  return formatRows(HELP_CAPABILITY_ENTRIES);
+}
 function formatReferenceEntries() {
   return formatRows(HELP_REFERENCE_ENTRIES.map((entry) => ({
     label: entry.label,
@@ -809,13 +660,21 @@ function getHelpText() {
     "Usage:",
     "  npx opendevbrowser <command> [options]",
     "",
+    "Find It Fast:",
+    "  Use these exact lookup terms when you need replay, desktop evidence, or browser-scoped computer use.",
+    formatCapabilityEntries(),
+    "",
+    `${onboarding_metadata_default.sectionTitle}:`,
+    `  ${onboarding_metadata_default.sectionSummary}`,
+    formatOnboardingEntries(),
+    "",
     `Command Inventory (all ${CLI_COMMANDS.length} commands):`,
     formatCommandGroups(commandDescriptions),
     "",
     "Flag Inventory (all supported flags):",
     formatFlagGroups(),
     "",
-    `Tool Inventory (all ${EXPECTED_TOOL_COUNT} opendevbrowser_* tools):`,
+    `Tool Inventory (all ${TOOL_COUNT} opendevbrowser_* tools):`,
     formatToolEntries(),
     "",
     "Reference Pointers:",
@@ -1079,52 +938,15 @@ function installLocal(withConfig = false) {
 }
 
 // src/cli/installers/skills.ts
-import * as fs6 from "fs";
+import * as crypto from "crypto";
+import * as fs5 from "fs";
 import * as path4 from "path";
 
 // src/cli/utils/skills.ts
-import * as fs5 from "fs";
 import * as path3 from "path";
 import * as os3 from "os";
-import { fileURLToPath } from "url";
-var PACKAGE_NAME = "opendevbrowser";
 var SKILL_DIR_NAME = "skill";
 var SKILLS_DIR_NAME = "skills";
-var cachedPackageRoot = null;
-function findPackageRoot(startDir) {
-  let current = startDir;
-  while (true) {
-    const pkgPath = path3.join(current, "package.json");
-    if (fs5.existsSync(pkgPath)) {
-      try {
-        const parsed = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
-        if (parsed.name === PACKAGE_NAME) {
-          return current;
-        }
-      } catch {
-      }
-    }
-    const parent = path3.dirname(current);
-    if (parent === current) {
-      break;
-    }
-    current = parent;
-  }
-  throw new Error("Unable to locate opendevbrowser package root for skill installation.");
-}
-function getPackageRoot() {
-  if (cachedPackageRoot) return cachedPackageRoot;
-  const moduleDir = path3.dirname(fileURLToPath(import.meta.url));
-  cachedPackageRoot = findPackageRoot(moduleDir);
-  return cachedPackageRoot;
-}
-function getBundledSkillsDir() {
-  const skillsDir = path3.join(getPackageRoot(), "skills");
-  if (!fs5.existsSync(skillsDir)) {
-    throw new Error(`Bundled skills directory not found at ${skillsDir}`);
-  }
-  return skillsDir;
-}
 function getGlobalSkillDir() {
   const configDir = process.env.OPENCODE_CONFIG_DIR || path3.join(os3.homedir(), ".config", "opencode");
   return path3.join(configDir, SKILL_DIR_NAME);
@@ -1182,34 +1004,207 @@ function getLocalSkillTargets() {
 }
 
 // src/cli/installers/skills.ts
-function installSkills(mode) {
-  const targets = mode === "global" ? getGlobalSkillTargets() : getLocalSkillTargets();
+var LEGACY_ALIAS_DIRS = [
+  { name: "research", canonical: "opendevbrowser-research" },
+  { name: "shopping", canonical: "opendevbrowser-shopping" }
+];
+function getTargets(mode) {
+  return mode === "global" ? getGlobalSkillTargets() : getLocalSkillTargets();
+}
+function getCanonicalBundledSkillNames() {
+  return listBundledSkillDirectories().map((entry) => entry.name);
+}
+function hasCanonicalBundledSkillInTarget(targetDir, packNames) {
+  return packNames.some((packName) => fs5.existsSync(path4.join(targetDir, packName)));
+}
+function formatSummary(parts, totalTargets, failures) {
+  const summary = parts.length > 0 ? parts.join(", ") : "no lifecycle changes";
+  const failureSummary = failures > 0 ? `, ${failures} failed` : "";
+  return `${summary} across ${totalTargets} targets${failureSummary}`;
+}
+function hashDirectoryTree(dirPath) {
+  const hash = crypto.createHash("sha256");
+  const visit = (currentPath, relativePath) => {
+    const entries = fs5.readdirSync(currentPath, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const absolutePath = path4.join(currentPath, entry.name);
+      const entryRelativePath = relativePath ? path4.posix.join(relativePath, entry.name) : entry.name;
+      if (entry.isDirectory()) {
+        hash.update(`D:${entryRelativePath}\0`);
+        visit(absolutePath, entryRelativePath);
+        continue;
+      }
+      if (entry.isFile()) {
+        hash.update(`F:${entryRelativePath}\0`);
+        hash.update(fs5.readFileSync(absolutePath));
+        hash.update("\0");
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        hash.update(`L:${entryRelativePath}\0${fs5.readlinkSync(absolutePath)}\0`);
+      }
+    }
+  };
+  visit(dirPath, "");
+  return hash.digest("hex");
+}
+function syncSkillDirectory(sourcePath, targetPath, sourceFingerprint) {
+  if (!fs5.existsSync(targetPath)) {
+    fs5.cpSync(sourcePath, targetPath, { recursive: true });
+    return "installed";
+  }
+  const targetFingerprint = hashDirectoryTree(targetPath);
+  if (targetFingerprint === sourceFingerprint) {
+    return "unchanged";
+  }
+  const parentDir = path4.dirname(targetPath);
+  const targetName = path4.basename(targetPath);
+  const stagingRoot = fs5.mkdtempSync(path4.join(parentDir, `.${targetName}-sync-`));
+  const stagedPath = path4.join(stagingRoot, targetName);
+  const backupPath = path4.join(stagingRoot, `${targetName}-backup`);
+  try {
+    fs5.cpSync(sourcePath, stagedPath, { recursive: true });
+    fs5.renameSync(targetPath, backupPath);
+    try {
+      fs5.renameSync(stagedPath, targetPath);
+    } catch (error) {
+      if (fs5.existsSync(backupPath) && !fs5.existsSync(targetPath)) {
+        fs5.renameSync(backupPath, targetPath);
+      }
+      throw error;
+    }
+    fs5.rmSync(backupPath, { recursive: true, force: true });
+    return "refreshed";
+  } finally {
+    if (fs5.existsSync(stagedPath)) {
+      fs5.rmSync(stagedPath, { recursive: true, force: true });
+    }
+    if (fs5.existsSync(backupPath)) {
+      fs5.rmSync(backupPath, { recursive: true, force: true });
+    }
+    fs5.rmSync(stagingRoot, { recursive: true, force: true });
+  }
+}
+function cleanupLegacyAlias(targetDir, aliasName) {
+  const aliasPath = path4.join(targetDir, aliasName);
+  if (!fs5.existsSync(aliasPath)) {
+    return { removed: [], preserved: [] };
+  }
+  let stats;
+  try {
+    stats = fs5.statSync(aliasPath);
+  } catch {
+    return {
+      removed: [],
+      preserved: [{ targetDir, name: aliasName, reason: "unknown_layout" }]
+    };
+  }
+  if (!stats.isDirectory()) {
+    return {
+      removed: [],
+      preserved: [{ targetDir, name: aliasName, reason: "unknown_layout" }]
+    };
+  }
+  if (fs5.existsSync(path4.join(aliasPath, "SKILL.md"))) {
+    return {
+      removed: [],
+      preserved: [{ targetDir, name: aliasName, reason: "contains_skill_md" }]
+    };
+  }
+  const entries = fs5.readdirSync(aliasPath);
+  if (entries.length === 0) {
+    fs5.rmSync(aliasPath, { recursive: true, force: true });
+    return { removed: [aliasName], preserved: [] };
+  }
+  return {
+    removed: [],
+    preserved: [{ targetDir, name: aliasName, reason: "non_empty" }]
+  };
+}
+function cleanupLegacyAliases(targetDir) {
+  const removed = [];
+  const preserved = [];
+  for (const alias of LEGACY_ALIAS_DIRS) {
+    const result = cleanupLegacyAlias(targetDir, alias.name);
+    removed.push(...result.removed);
+    preserved.push(...result.preserved);
+  }
+  return { removed, preserved };
+}
+function buildSyncMessage(mode, result) {
+  return `Skills ${mode} sync: ${formatSummary(
+    [
+      result.installed.length > 0 ? `${result.installed.length} installed` : "",
+      result.refreshed.length > 0 ? `${result.refreshed.length} refreshed` : "",
+      result.unchanged.length > 0 ? `${result.unchanged.length} unchanged` : "",
+      result.removedLegacyAliases.length > 0 ? `${result.removedLegacyAliases.length} legacy aliases removed` : "",
+      result.preservedLegacyAliases.length > 0 ? `${result.preservedLegacyAliases.length} legacy aliases preserved` : ""
+    ].filter(Boolean),
+    result.targets.length,
+    result.targets.filter((entry) => !entry.success).length
+  )}`;
+}
+function buildRemovalMessage(mode, result) {
+  return `Skills ${mode} removal: ${formatSummary(
+    [
+      result.removed.length > 0 ? `${result.removed.length} removed` : "",
+      result.missing.length > 0 ? `${result.missing.length} already absent` : "",
+      result.removedLegacyAliases.length > 0 ? `${result.removedLegacyAliases.length} legacy aliases removed` : "",
+      result.preservedLegacyAliases.length > 0 ? `${result.preservedLegacyAliases.length} legacy aliases preserved` : ""
+    ].filter(Boolean),
+    result.targets.length,
+    result.targets.filter((entry) => !entry.success).length
+  )}`;
+}
+function syncBundledSkills(mode) {
+  const targets = getTargets(mode);
   const targetResults = [];
   try {
     const sourceDir = getBundledSkillsDir();
-    const entries = fs6.readdirSync(sourceDir, { withFileTypes: true });
+    const packNames = getCanonicalBundledSkillNames();
+    const bundledFingerprints = /* @__PURE__ */ new Map();
+    for (const packName of packNames) {
+      const sourcePath = path4.join(sourceDir, packName);
+      if (!fs5.existsSync(sourcePath)) {
+        throw new Error(`Bundled skill directory missing: ${packName}`);
+      }
+      bundledFingerprints.set(packName, hashDirectoryTree(sourcePath));
+    }
     for (const target of targets) {
-      const installed2 = [];
-      const skipped2 = [];
+      const installed = [];
+      const refreshed = [];
+      const unchanged = [];
+      const removedLegacyAliases = [];
+      const preservedLegacyAliases = [];
       try {
         ensureDir(target.dir);
-        for (const entry of entries) {
-          if (!entry.isDirectory()) continue;
-          const skillName = entry.name;
-          const sourcePath = path4.join(sourceDir, skillName);
-          const targetPath = path4.join(target.dir, skillName);
-          if (fs6.existsSync(targetPath)) {
-            skipped2.push(skillName);
-            continue;
+        for (const packName of packNames) {
+          const sourcePath = path4.join(sourceDir, packName);
+          const targetPath = path4.join(target.dir, packName);
+          const sourceFingerprint = bundledFingerprints.get(packName);
+          if (!sourceFingerprint) {
+            throw new Error(`Bundled fingerprint missing: ${packName}`);
+          }
+          const outcome = syncSkillDirectory(sourcePath, targetPath, sourceFingerprint);
+          if (outcome === "installed") {
+            installed.push(packName);
+          } else if (outcome === "refreshed") {
+            refreshed.push(packName);
+          } else {
+            unchanged.push(packName);
           }
-          fs6.cpSync(sourcePath, targetPath, { recursive: true });
-          installed2.push(skillName);
         }
+        const legacyCleanup = cleanupLegacyAliases(target.dir);
+        removedLegacyAliases.push(...legacyCleanup.removed);
+        preservedLegacyAliases.push(...legacyCleanup.preserved);
         targetResults.push({
           agents: target.agents,
           targetDir: target.dir,
-          installed: installed2,
-          skipped: skipped2,
+          installed,
+          refreshed,
+          unchanged,
+          removedLegacyAliases,
+          preservedLegacyAliases,
           success: true
         });
       } catch (error) {
@@ -1217,41 +1212,112 @@ function installSkills(mode) {
         targetResults.push({
           agents: target.agents,
           targetDir: target.dir,
-          installed: installed2,
-          skipped: skipped2,
+          installed,
+          refreshed,
+          unchanged,
+          removedLegacyAliases,
+          preservedLegacyAliases,
           success: false,
           error: message
         });
       }
     }
-    const installed = targetResults.flatMap((result) => result.installed);
-    const skipped = targetResults.flatMap((result) => result.skipped);
-    const failures = targetResults.filter((result) => !result.success);
-    const failedSummary = failures.length > 0 ? `, ${failures.length} failed` : "";
-    const summary = `Skills ${mode} install: ${installed.length} installed${skipped.length ? `, ${skipped.length} skipped` : ""}${failedSummary} across ${targetResults.length} targets`;
-    return {
-      success: failures.length === 0,
-      message: summary,
+    const result = {
+      success: targetResults.every((entry) => entry.success),
+      message: "",
       mode,
       targets: targetResults,
-      installed,
-      skipped
+      installed: targetResults.flatMap((entry) => entry.installed),
+      refreshed: targetResults.flatMap((entry) => entry.refreshed),
+      unchanged: targetResults.flatMap((entry) => entry.unchanged),
+      removedLegacyAliases: targetResults.flatMap((entry) => entry.removedLegacyAliases),
+      preservedLegacyAliases: targetResults.flatMap((entry) => entry.preservedLegacyAliases)
     };
+    result.message = buildSyncMessage(mode, result);
+    return result;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    return {
+    const result = {
       success: false,
-      message: `Failed to install skills (${mode}): ${message}`,
+      message: "",
       mode,
       targets: targetResults,
-      installed: targetResults.flatMap((result) => result.installed),
-      skipped: targetResults.flatMap((result) => result.skipped)
+      installed: targetResults.flatMap((entry) => entry.installed),
+      refreshed: targetResults.flatMap((entry) => entry.refreshed),
+      unchanged: targetResults.flatMap((entry) => entry.unchanged),
+      removedLegacyAliases: targetResults.flatMap((entry) => entry.removedLegacyAliases),
+      preservedLegacyAliases: targetResults.flatMap((entry) => entry.preservedLegacyAliases)
     };
+    result.message = `Failed to sync skills (${mode}): ${message}`;
+    return result;
+  }
+}
+function removeBundledSkills(mode) {
+  const targets = getTargets(mode);
+  const packNames = getCanonicalBundledSkillNames();
+  const targetResults = [];
+  for (const target of targets) {
+    const removed = [];
+    const missing = [];
+    const removedLegacyAliases = [];
+    const preservedLegacyAliases = [];
+    try {
+      for (const packName of packNames) {
+        const targetPath = path4.join(target.dir, packName);
+        if (fs5.existsSync(targetPath)) {
+          fs5.rmSync(targetPath, { recursive: true, force: true });
+          removed.push(packName);
+        } else {
+          missing.push(packName);
+        }
+      }
+      const legacyCleanup = cleanupLegacyAliases(target.dir);
+      removedLegacyAliases.push(...legacyCleanup.removed);
+      preservedLegacyAliases.push(...legacyCleanup.preserved);
+      targetResults.push({
+        agents: target.agents,
+        targetDir: target.dir,
+        removed,
+        missing,
+        removedLegacyAliases,
+        preservedLegacyAliases,
+        success: true
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      targetResults.push({
+        agents: target.agents,
+        targetDir: target.dir,
+        removed,
+        missing,
+        removedLegacyAliases,
+        preservedLegacyAliases,
+        success: false,
+        error: message
+      });
+    }
   }
+  const result = {
+    success: targetResults.every((entry) => entry.success),
+    message: "",
+    mode,
+    targets: targetResults,
+    removed: targetResults.flatMap((entry) => entry.removed),
+    missing: targetResults.flatMap((entry) => entry.missing),
+    removedLegacyAliases: targetResults.flatMap((entry) => entry.removedLegacyAliases),
+    preservedLegacyAliases: targetResults.flatMap((entry) => entry.preservedLegacyAliases)
+  };
+  result.message = buildRemovalMessage(mode, result);
+  return result;
+}
+function hasBundledSkillArtifacts(mode) {
+  const packNames = getCanonicalBundledSkillNames();
+  const targets = getTargets(mode);
+  return targets.some((target) => hasCanonicalBundledSkillInTarget(target.dir, packNames));
 }
 
 // src/cli/commands/update.ts
-import * as fs7 from "fs";
+import * as fs6 from "fs";
 import * as path5 from "path";
 import * as os4 from "os";
 var PLUGIN_NAME2 = "opendevbrowser";
@@ -1265,8 +1331,8 @@ function rmdir(dirPath) {
   if (!resolvedPath.startsWith(resolvedCache + path5.sep) || resolvedPath === resolvedCache) {
     throw new Error(`Security: refusing to delete path outside cache directory: ${dirPath}`);
   }
-  if (fs7.existsSync(dirPath)) {
-    fs7.rmSync(dirPath, { recursive: true, force: true });
+  if (fs6.existsSync(dirPath)) {
+    fs6.rmSync(dirPath, { recursive: true, force: true });
   }
 }
 function runUpdate() {
@@ -1274,8 +1340,8 @@ function runUpdate() {
   const nodeModulesDir = path5.join(cacheDir, "node_modules");
   const pluginCacheDir = path5.join(nodeModulesDir, PLUGIN_NAME2);
   try {
-    if (!fs7.existsSync(pluginCacheDir)) {
-      if (fs7.existsSync(nodeModulesDir)) {
+    if (!fs6.existsSync(pluginCacheDir)) {
+      if (fs6.existsSync(nodeModulesDir)) {
         rmdir(nodeModulesDir);
         return {
           success: true,
@@ -1306,7 +1372,7 @@ function runUpdate() {
 }
 
 // src/cli/commands/uninstall.ts
-import * as fs8 from "fs";
+import * as fs7 from "fs";
 import * as path6 from "path";
 import * as os5 from "os";
 function getPluginConfigPath2(mode) {
@@ -1318,8 +1384,8 @@ function getPluginConfigPath2(mode) {
 }
 function removePluginConfigFile(mode) {
   const configPath = getPluginConfigPath2(mode);
-  if (fs8.existsSync(configPath)) {
-    fs8.unlinkSync(configPath);
+  if (fs7.existsSync(configPath)) {
+    fs7.unlinkSync(configPath);
     return true;
   }
   return false;
@@ -1338,7 +1404,7 @@ function runUninstall(mode, deleteConfigFile = false) {
       };
     }
     const newContent = removePluginFromContent(content, "opendevbrowser");
-    fs8.writeFileSync(configPath, newContent, "utf-8");
+    fs7.writeFileSync(configPath, newContent, "utf-8");
     let configFileDeleted = false;
     if (deleteConfigFile) {
       configFileDeleted = removePluginConfigFile(mode);
@@ -1398,6 +1464,16 @@ function parseNumberFlag(value, flag, options = {}) {
   }
   return parsed;
 }
+function parseBooleanFlag(value, flag) {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true" || normalized === "1") {
+    return true;
+  }
+  if (normalized === "false" || normalized === "0") {
+    return false;
+  }
+  throw createUsageError(`Invalid ${flag}: ${value}`);
+}
 function parseOptionalStringFlag(rawArgs, flag) {
   for (let i = 0; i < rawArgs.length; i += 1) {
     const arg = rawArgs[i];
@@ -1418,13 +1494,23 @@ function parseOptionalStringFlag(rawArgs, flag) {
   }
   return void 0;
 }
+function parseStringArrayFlag(rawArgs, flag) {
+  const value = parseOptionalStringFlag(rawArgs, flag);
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const items = value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+  if (items.length === 0) {
+    throw createUsageError(`Missing value for ${flag}`);
+  }
+  return items;
+}
 
 // src/cli/commands/native.ts
-import * as fs9 from "fs";
+import * as fs8 from "fs";
 import * as path7 from "path";
-import { homedir as homedir6 } from "os";
 import { execFileSync } from "child_process";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { fileURLToPath } from "url";
 var EXTENSION_ID_RE = /^[a-p]{32}$/;
 var EXTENSION_NAME = "OpenDevBrowser Relay";
 var ANNOTATION_COMMAND_NAME = "toggle-annotation";
@@ -1472,7 +1558,7 @@ var getManifestDir = () => {
   throw createUsageError(`Native messaging is not supported on ${process.platform}.`);
 };
 var getScriptsDir = () => {
-  const __filename = fileURLToPath2(import.meta.url);
+  const __filename = fileURLToPath(import.meta.url);
   const startDir = path7.dirname(__filename);
   const rootsToScan = [startDir, process.cwd()];
   for (const root of rootsToScan) {
@@ -1480,7 +1566,7 @@ var getScriptsDir = () => {
     while (true) {
       const scriptsDir = path7.join(current, "scripts", "native");
       const packageJsonPath = path7.join(current, "package.json");
-      if (fs9.existsSync(scriptsDir) && fs9.existsSync(packageJsonPath)) {
+      if (fs8.existsSync(scriptsDir) && fs8.existsSync(packageJsonPath)) {
         return scriptsDir;
       }
       const parent = path7.dirname(current);
@@ -1504,7 +1590,7 @@ var getWrapperPath = () => {
 };
 var readManifest = (manifestPath) => {
   try {
-    const raw = fs9.readFileSync(manifestPath, "utf8");
+    const raw = fs8.readFileSync(manifestPath, "utf8");
     const data = JSON.parse(raw);
     const origins = Array.isArray(data.allowed_origins) ? data.allowed_origins : [];
     const match = origins.find((origin) => origin.startsWith("chrome-extension://"));
@@ -1541,57 +1627,11 @@ var readRegistryPath = () => {
 };
 var normalizePath = (value) => {
   try {
-    return fs9.realpathSync(value);
+    return fs8.realpathSync(value);
   } catch {
     return path7.resolve(value);
   }
 };
-var getChromeUserDataRoots = () => {
-  if (process.platform === "darwin") {
-    return [
-      path7.join(homedir6(), "Library", "Application Support", "Google", "Chrome"),
-      path7.join(homedir6(), "Library", "Application Support", "Chromium"),
-      path7.join(homedir6(), "Library", "Application Support", "BraveSoftware", "Brave-Browser")
-    ];
-  }
-  if (process.platform === "linux") {
-    return [
-      path7.join(homedir6(), ".config", "google-chrome"),
-      path7.join(homedir6(), ".config", "chromium"),
-      path7.join(homedir6(), ".config", "BraveSoftware", "Brave-Browser")
-    ];
-  }
-  if (process.platform === "win32") {
-    const base = process.env.LOCALAPPDATA || (process.env.USERPROFILE ? path7.join(process.env.USERPROFILE, "AppData", "Local") : "");
-    if (!base) return [];
-    return [
-      path7.join(base, "Google", "Chrome", "User Data"),
-      path7.join(base, "Chromium", "User Data"),
-      path7.join(base, "BraveSoftware", "Brave-Browser", "User Data")
-    ];
-  }
-  return [];
-};
-var PROFILE_PREFERENCES_FILES = ["Preferences", "Secure Preferences"];
-var getProfileDirs = (root) => {
-  try {
-    const entries = fs9.readdirSync(root, { withFileTypes: true });
-    return entries.filter((entry) => entry.isDirectory() && (entry.name === "Default" || entry.name.startsWith("Profile "))).map((entry) => path7.join(root, entry.name)).filter((dir) => PROFILE_PREFERENCES_FILES.some((filename) => fs9.existsSync(path7.join(dir, filename))));
-  } catch {
-    return [];
-  }
-};
-var readProfilePreferences = (profileDir) => {
-  const records = [];
-  for (const filename of PROFILE_PREFERENCES_FILES) {
-    try {
-      const raw = fs9.readFileSync(path7.join(profileDir, filename), "utf8");
-      records.push(JSON.parse(raw));
-    } catch {
-    }
-  }
-  return records;
-};
 var findExtensionIdInCommands = (preferences) => {
   const extensionCommands = preferences.extensions;
   const commandMaps = [
@@ -1651,7 +1691,7 @@ var getExtensionPathCandidates = () => {
     candidates.add(normalizePath(primary));
   }
   const cwdExtension = path7.join(process.cwd(), "extension");
-  if (fs9.existsSync(path7.join(cwdExtension, "manifest.json"))) {
+  if (fs8.existsSync(path7.join(cwdExtension, "manifest.json"))) {
     candidates.add(normalizePath(cwdExtension));
   }
   if (candidates.size === 0) {
@@ -1736,13 +1776,13 @@ var getNativeStatusSnapshot = () => {
   let manifestExists = false;
   let wrapperExists = false;
   let extensionIdValue = null;
-  if (fs9.existsSync(manifestPath)) {
+  if (fs8.existsSync(manifestPath)) {
     manifestExists = true;
     installed = true;
     const manifest = readManifest(manifestPath);
     extensionIdValue = manifest.extensionId;
   }
-  if (fs9.existsSync(wrapperPath)) {
+  if (fs8.existsSync(wrapperPath)) {
     wrapperExists = true;
   }
   if (!manifestExists || !wrapperExists) {
@@ -1768,6 +1808,30 @@ var getNativeStatusSnapshot = () => {
     mismatch
   };
 };
+function assessNativeStatus(data) {
+  if (!data.installed) {
+    return {
+      success: false,
+      message: "Native host not installed.",
+      summary: "not installed",
+      exitCode: EXIT_DISCONNECTED
+    };
+  }
+  if (data.mismatch && data.extensionId && data.expectedExtensionId) {
+    return {
+      success: false,
+      message: `Native host targets ${data.extensionId}, but the current extension is ${data.expectedExtensionId}. Reinstall with \`opendevbrowser native install ${data.expectedExtensionId}\` or rerun \`opendevbrowser serve\`.`,
+      summary: `mismatch (${data.extensionId} != ${data.expectedExtensionId})`,
+      exitCode: EXIT_DISCONNECTED
+    };
+  }
+  return {
+    success: true,
+    message: data.extensionId ? `Native host installed for extension ${data.extensionId}.` : "Native host installed (extension id missing).",
+    summary: `installed${data.extensionId ? ` (${data.extensionId})` : ""}`,
+    exitCode: null
+  };
+}
 function installNativeHost(extensionId) {
   const normalized = normalizeExtensionId(extensionId);
   if (!normalized) {
@@ -1778,7 +1842,7 @@ function installNativeHost(extensionId) {
     };
   }
   const hostScript = getHostScriptPath();
-  if (!fs9.existsSync(hostScript)) {
+  if (!fs8.existsSync(hostScript)) {
     return {
       success: false,
       message: `Native host not found at ${hostScript}.`,
@@ -1816,34 +1880,27 @@ async function runNativeCommand(args) {
       runScript(uninstallScript, []);
       return { success: true, message: "Native host uninstalled." };
     } catch (error) {
-      const message2 = error instanceof Error ? error.message : String(error);
-      return { success: false, message: `Native uninstall failed: ${message2}`, exitCode: EXIT_EXECUTION };
+      const message = error instanceof Error ? error.message : String(error);
+      return { success: false, message: `Native uninstall failed: ${message}`, exitCode: EXIT_EXECUTION };
     }
   }
   const data = getNativeStatusSnapshot();
-  if (!data.installed) {
-    return {
-      success: false,
-      message: "Native host not installed.",
-      data,
-      exitCode: EXIT_DISCONNECTED
-    };
-  }
-  if (data.mismatch && data.extensionId && data.expectedExtensionId) {
-    return {
-      success: false,
-      message: `Native host targets ${data.extensionId}, but the current extension is ${data.expectedExtensionId}. Reinstall with \`opendevbrowser native install ${data.expectedExtensionId}\` or rerun \`opendevbrowser serve\`.`,
-      data,
-      exitCode: EXIT_DISCONNECTED
-    };
-  }
-  const message = data.extensionId ? `Native host installed for extension ${data.extensionId}.` : "Native host installed (extension id missing).";
-  return { success: true, message, data };
+  const assessment = assessNativeStatus(data);
+  return {
+    success: assessment.success,
+    message: assessment.message,
+    data,
+    exitCode: assessment.exitCode
+  };
 }
 
 // src/cli/commands/serve.ts
 var daemonHandle = null;
 var PS_MAX_BUFFER = 8 * 1024 * 1024;
+var SERVE_COMMAND_PATTERN = /(?:^|\s)(?:\S*[\\/])?(?:opendevbrowser|dist[\\/]+cli[\\/]+index\.js)(?=\s|$).*?\bserve\b/;
+var SERVE_STOP_PATTERN = /(?:^|\s)--stop(?:\s|$)/;
+var CURRENT_UID = typeof process.getuid === "function" ? process.getuid() : null;
+var CURRENT_EXECUTABLE = process.execPath;
 function resolveTokenCandidates(requestedToken, metadataToken, configToken) {
   return Array.from(new Set([requestedToken, metadataToken, configToken].filter((token) => typeof token === "string" && token.trim().length > 0)));
 }
@@ -1901,32 +1958,52 @@ function parseServeArgs(rawArgs) {
   }
   return parsed;
 }
-function listServeProcessPids() {
-  const result = spawnSync("ps", ["-ax", "-o", "pid=,command="], {
+function parseServeProcessSnapshot(line) {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+  const match = trimmed.match(/^(\d+)(?:\s+(\d+))?\s+(.*)$/);
+  if (!match) {
+    return null;
+  }
+  const pid = Number.parseInt(match[1] ?? "", 10);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return null;
+  }
+  const rawUid = match[2];
+  const parsedUid = typeof rawUid === "string" && rawUid.length > 0 ? Number.parseInt(rawUid, 10) : null;
+  const command = (match[3] ?? "").trim();
+  if (command.length === 0) {
+    return null;
+  }
+  return {
+    pid,
+    uid: typeof parsedUid === "number" && Number.isInteger(parsedUid) && parsedUid >= 0 ? parsedUid : null,
+    command
+  };
+}
+function listServeProcessSnapshots() {
+  const result = spawnSync("ps", ["-axww", "-o", "pid=,uid=,command="], {
     encoding: "utf-8",
     maxBuffer: PS_MAX_BUFFER
   });
   if ((result.status ?? 1) !== 0) {
     return [];
   }
-  const servePattern = /\b(opendevbrowser|dist\/cli\/index\.js)\b.*\bserve\b/;
-  const lines = String(result.stdout ?? "").split(/\r?\n/);
-  const pids = /* @__PURE__ */ new Set();
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    const match = trimmed.match(/^(\d+)\s+(.+)$/);
-    if (!match) continue;
-    const pidText = match[1];
-    if (!pidText) continue;
-    const pid = Number.parseInt(pidText, 10);
-    const command = match[2] ?? "";
-    if (!Number.isInteger(pid) || pid <= 0) continue;
-    if (pid === process.pid || pid === process.ppid) continue;
-    if (!servePattern.test(command)) continue;
-    pids.add(pid);
-  }
-  return [...pids];
+  return String(result.stdout ?? "").split("\n").map((line) => parseServeProcessSnapshot(line)).filter((snapshot) => snapshot !== null);
+}
+function isCurrentExecutableServeProcess(snapshot) {
+  if (CURRENT_UID === null || snapshot.uid === null || snapshot.uid !== CURRENT_UID) {
+    return false;
+  }
+  if (!snapshot.command.includes(CURRENT_EXECUTABLE)) {
+    return false;
+  }
+  if (!SERVE_COMMAND_PATTERN.test(snapshot.command)) {
+    return false;
+  }
+  return !SERVE_STOP_PATTERN.test(snapshot.command);
 }
 function terminateProcess(pid) {
   if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid || pid === process.ppid) {
@@ -1943,16 +2020,29 @@ function terminateProcess(pid) {
   }
   return true;
 }
-function cleanupStaleServeProcesses(keepPid) {
-  const candidates = listServeProcessPids();
-  let cleaned = 0;
-  for (const pid of candidates) {
-    if (Number.isInteger(keepPid) && pid === keepPid) continue;
-    if (terminateProcess(pid)) {
-      cleaned += 1;
+function cleanupCompetingServeProcesses(keepPid) {
+  const candidates = listServeProcessSnapshots().filter((snapshot) => {
+    if (!isCurrentExecutableServeProcess(snapshot)) {
+      return false;
+    }
+    if (snapshot.pid === process.pid || snapshot.pid === process.ppid) {
+      return false;
     }
+    if (Number.isInteger(keepPid) && snapshot.pid === keepPid) {
+      return false;
+    }
+    return true;
+  });
+  if (candidates.length === 0) {
+    return [];
   }
-  return cleaned;
+  const clearedPids = [];
+  for (const snapshot of candidates) {
+    if (terminateProcess(snapshot.pid)) {
+      clearedPids.push(snapshot.pid);
+    }
+  }
+  return clearedPids;
 }
 async function runServe(args) {
   const serveArgs = parseServeArgs(args.rawArgs);
@@ -1986,10 +2076,13 @@ async function runServe(args) {
   const metadataToken = metadata?.port === requestedPort ? metadata.token : void 0;
   const tokenCandidates = resolveTokenCandidates(serveArgs.token, metadataToken, config.daemonToken);
   const existingDaemon = await resolveExistingDaemon(requestedPort, tokenCandidates);
-  const staleCleared = cleanupStaleServeProcesses(existingDaemon?.status.pid);
+  const staleDaemonPids = new Set(cleanupCompetingServeProcesses(existingDaemon?.status.pid));
+  const staleCleared = () => staleDaemonPids.size;
   if (existingDaemon) {
     const relayPort = existingDaemon.status.relay.port ?? config.relayPort;
-    const staleNote2 = staleCleared > 0 ? ` Cleared ${staleCleared} stale daemon process${staleCleared === 1 ? "" : "es"}.` : "";
+    const clearedCount2 = staleCleared();
+    const staleNote2 = clearedCount2 > 0 ? `
+Cleared ${clearedCount2} stale daemon process${clearedCount2 === 1 ? "" : "es"}.` : "";
     return {
       success: true,
       message: `Daemon already running on 127.0.0.1:${requestedPort} (pid=${existingDaemon.status.pid}, relay ${relayPort}).${staleNote2}`,
@@ -1998,7 +2091,7 @@ async function runServe(args) {
         pid: existingDaemon.status.pid,
         relayPort,
         alreadyRunning: true,
-        staleDaemonsCleared: staleCleared,
+        staleDaemonsCleared: clearedCount2,
         relay: existingDaemon.status.relay
       },
       exitCode: null
@@ -2026,32 +2119,62 @@ async function runServe(args) {
       nativeMessage = "Native host not installed. Set nativeExtensionId in opendevbrowser.jsonc to auto-install.";
     }
   }
-  let handle;
-  try {
-    handle = await startDaemon({
-      port: serveArgs.port,
-      token: serveArgs.token,
-      config
-    });
-  } catch (error) {
-    const message2 = error instanceof Error ? error.message : String(error);
-    if (message2.includes("EADDRINUSE") || message2.includes("in use")) {
+  let handle = null;
+  let startError = null;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      handle = await startDaemon({
+        port: serveArgs.port,
+        token: serveArgs.token,
+        config
+      });
+      startError = null;
+      break;
+    } catch (error) {
+      startError = error;
+      const message2 = error instanceof Error ? error.message : String(error);
+      if (!message2.includes("EADDRINUSE") && !message2.includes("in use")) {
+        break;
+      }
       const runningDaemon = await resolveExistingDaemon(requestedPort, tokenCandidates);
       if (runningDaemon) {
         const relayPort = runningDaemon.status.relay.port ?? config.relayPort;
+        const clearedCount2 = staleCleared();
+        const staleNote2 = clearedCount2 > 0 ? `
+Cleared ${clearedCount2} stale daemon process${clearedCount2 === 1 ? "" : "es"}.` : "";
         return {
           success: true,
-          message: `Daemon already running on 127.0.0.1:${requestedPort} (pid=${runningDaemon.status.pid}, relay ${relayPort}).`,
+          message: `Daemon already running on 127.0.0.1:${requestedPort} (pid=${runningDaemon.status.pid}, relay ${relayPort}).${staleNote2}`,
           data: {
             port: requestedPort,
             pid: runningDaemon.status.pid,
             relayPort,
             alreadyRunning: true,
+            staleDaemonsCleared: clearedCount2,
             relay: runningDaemon.status.relay
           },
           exitCode: null
         };
       }
+      if (attempt === 0) {
+        let clearedNewPid = false;
+        for (const pid of cleanupCompetingServeProcesses()) {
+          const previousSize = staleDaemonPids.size;
+          staleDaemonPids.add(pid);
+          if (staleDaemonPids.size > previousSize) {
+            clearedNewPid = true;
+          }
+        }
+        if (clearedNewPid) {
+          continue;
+        }
+      }
+      break;
+    }
+  }
+  if (!handle) {
+    const message2 = startError instanceof Error ? startError.message : String(startError);
+    if (message2.includes("EADDRINUSE") || message2.includes("in use")) {
       return {
         success: false,
         message: `Daemon port ${requestedPort} is already in use by another process. If this is an existing daemon, run \`opendevbrowser status --daemon\` or \`opendevbrowser serve --stop\`.`,
@@ -2067,54 +2190,93 @@ async function runServe(args) {
   daemonHandle = handle;
   const { state } = handle;
   const baseMessage = `Daemon running on 127.0.0.1:${state.port} (relay ${state.relayPort})`;
-  const staleNote = staleCleared > 0 ? `
-Cleared ${staleCleared} stale daemon process${staleCleared === 1 ? "" : "es"}.` : "";
+  const clearedCount = staleCleared();
+  const staleNote = clearedCount > 0 ? `
+Cleared ${clearedCount} stale daemon process${clearedCount === 1 ? "" : "es"}.` : "";
   const message = nativeMessage ? `${baseMessage}
 ${nativeMessage}${staleNote}` : `${baseMessage}${staleNote}`;
   return {
     success: true,
     message,
-    data: { port: state.port, pid: state.pid, relayPort: state.relayPort, native: nativeStatus, staleDaemonsCleared: staleCleared },
+    data: { port: state.port, pid: state.pid, relayPort: state.relayPort, native: nativeStatus, staleDaemonsCleared: clearedCount },
     exitCode: null
   };
 }
 
 // src/cli/daemon-autostart.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { existsSync as existsSync8, mkdirSync as mkdirSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync4 } from "fs";
-import { homedir as homedir7 } from "os";
-import { dirname as dirname5, join as join8, resolve as resolve4 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
+import { existsSync as existsSync7, mkdirSync as mkdirSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync4 } from "fs";
+import { homedir as homedir6, tmpdir } from "os";
+import { dirname as dirname5, isAbsolute, join as join8, relative, resolve as resolve4 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 var MAC_LABEL = "com.opendevbrowser.daemon";
 var WIN_TASK_NAME = "OpenDevBrowser Daemon";
+var STABLE_DAEMON_INSTALL_GUIDANCE = "Run opendevbrowser daemon install from a stable install location (for example, a global npm install or a persistent local package install).";
 var defaultDeps = () => ({
   platform: process.platform,
   argv1: process.argv[1] ?? "",
   moduleUrl: import.meta.url,
   uid: typeof process.getuid === "function" ? process.getuid() : 0,
-  homedir: homedir7,
-  existsSync: existsSync8,
+  homedir: homedir6,
+  existsSync: existsSync7,
   mkdirSync: mkdirSync3,
   writeFileSync: writeFileSync4,
   unlinkSync: unlinkSync2,
-  execFileSync: execFileSync2
+  execFileSync: execFileSync2,
+  transientEntrypointRoots: void 0
 });
+var NPX_CACHE_SEGMENT_PATTERN = /[\\/]_npx(?:[\\/]|$)/;
+var formatCommand = (programArguments) => {
+  return programArguments.map((value) => `"${value}"`).join(" ");
+};
 var resolveCliPathFromModule = (moduleUrl, exists) => {
-  const modulePath = fileURLToPath3(moduleUrl);
+  const modulePath = fileURLToPath2(moduleUrl);
   const candidate = resolve4(dirname5(modulePath), "..", "index.js");
   if (!exists(candidate)) {
     throw new Error(`CLI entrypoint not found at ${candidate}`);
   }
   return candidate;
 };
+var normalizeComparisonPath = (value, platform) => {
+  const resolvedPath = resolve4(value);
+  return platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
+};
+var isPathInsideRoot = (candidate, root, platform) => {
+  const normalizedCandidate = normalizeComparisonPath(candidate, platform);
+  const normalizedRoot = normalizeComparisonPath(root, platform);
+  const relation = relative(normalizedRoot, normalizedCandidate);
+  return relation === "" || !relation.startsWith("..") && !isAbsolute(relation);
+};
+var getTransientEntrypointRoots = (deps) => {
+  const configuredRoots = deps.transientEntrypointRoots;
+  if (configuredRoots && configuredRoots.length > 0) {
+    return [...new Set(configuredRoots.map((root) => normalizeComparisonPath(root, deps.platform)))];
+  }
+  const roots = [tmpdir()];
+  if (deps.platform === "darwin") {
+    roots.push("/tmp", "/private/tmp");
+  }
+  return [...new Set(roots.map((root) => normalizeComparisonPath(root, deps.platform)))];
+};
+var isTransientCliPath = (cliPath, deps) => {
+  const normalizedCliPath = normalizeComparisonPath(cliPath, deps.platform);
+  return getTransientEntrypointRoots(deps).some((root) => isPathInsideRoot(cliPath, root, deps.platform)) || NPX_CACHE_SEGMENT_PATTERN.test(normalizedCliPath);
+};
+var TRANSIENT_AUTOSTART_INSTALL_ERROR_PREFIX = "Cannot install daemon autostart from transient CLI path";
+var isTransientAutostartInstallError = (error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.startsWith(TRANSIENT_AUTOSTART_INSTALL_ERROR_PREFIX);
+};
 var resolveCliEntrypoint = (deps = {}) => {
   const resolved = { ...defaultDeps(), ...deps };
   const exists = resolved.existsSync;
   let cliPath = null;
+  let source = "module";
   if (resolved.argv1) {
     const candidate = resolve4(resolved.argv1);
     if (exists(candidate)) {
       cliPath = candidate;
+      source = "argv1";
     }
   }
   if (!cliPath) {
@@ -2122,16 +2284,17 @@ var resolveCliEntrypoint = (deps = {}) => {
   }
   const nodePath = process.execPath;
   const args = [cliPath, "serve"];
-  const command = `"${nodePath}" "${cliPath}" serve`;
-  return { nodePath, cliPath, args, command };
+  const command = formatCommand([nodePath, ...args]);
+  const isTransient = isTransientCliPath(cliPath, resolved);
+  return { nodePath, cliPath, args, command, source, isTransient };
 };
-var getLaunchAgentPath = (home = homedir7()) => {
+var getLaunchAgentPath = (home = homedir6()) => {
   return join8(home, "Library", "LaunchAgents", `${MAC_LABEL}.plist`);
 };
 var buildLaunchAgentPlist = (entrypoint, options = {}) => {
   const label = options.label ?? MAC_LABEL;
-  const stdoutPath = options.stdoutPath ?? join8(homedir7(), "Library", "Logs", "opendevbrowser-daemon.log");
-  const stderrPath = options.stderrPath ?? join8(homedir7(), "Library", "Logs", "opendevbrowser-daemon.err.log");
+  const stdoutPath = options.stdoutPath ?? join8(homedir6(), "Library", "Logs", "opendevbrowser-daemon.log");
+  const stderrPath = options.stderrPath ?? join8(homedir6(), "Library", "Logs", "opendevbrowser-daemon.err.log");
   const programArgs = [entrypoint.nodePath, ...entrypoint.args].map((value) => `      <string>${value}</string>`).join("\n");
   return [
     '<?xml version="1.0" encoding="UTF-8"?>',
@@ -2158,7 +2321,7 @@ var buildLaunchAgentPlist = (entrypoint, options = {}) => {
   ].join("\n");
 };
 var buildWindowsTaskArgs = (entrypoint, taskName = WIN_TASK_NAME) => {
-  const command = `"${entrypoint.nodePath}" "${entrypoint.cliPath}" serve`;
+  const command = formatCommand([entrypoint.nodePath, entrypoint.cliPath, "serve"]);
   const args = [
     "/Create",
     "/TN",
@@ -2173,6 +2336,146 @@ var buildWindowsTaskArgs = (entrypoint, taskName = WIN_TASK_NAME) => {
   ];
   return { taskName, command, args };
 };
+var createAutostartStatus = (status) => status;
+var createMacAutostartStatus = (entrypoint, location, overrides) => {
+  return createAutostartStatus({
+    platform: "darwin",
+    supported: true,
+    installed: false,
+    health: "missing",
+    needsRepair: false,
+    location,
+    label: MAC_LABEL,
+    expectedCommand: entrypoint.isTransient ? void 0 : entrypoint.command,
+    ...overrides
+  });
+};
+var createWindowsAutostartStatus = (entrypoint, overrides) => {
+  return createAutostartStatus({
+    platform: "win32",
+    supported: true,
+    installed: false,
+    health: "missing",
+    needsRepair: false,
+    taskName: WIN_TASK_NAME,
+    expectedCommand: entrypoint.isTransient ? void 0 : entrypoint.command,
+    ...overrides
+  });
+};
+var classifyPersistedProgramArguments = (programArguments, deps) => {
+  const actualNodePath = programArguments[0];
+  const actualCliPath = programArguments[1];
+  if (!actualNodePath || !deps.existsSync(actualNodePath)) {
+    return { health: "needs_repair", reason: "missing_node_path" };
+  }
+  if (!actualCliPath || !deps.existsSync(actualCliPath)) {
+    return { health: "needs_repair", reason: "missing_cli_path" };
+  }
+  if (isTransientCliPath(actualCliPath, deps)) {
+    return { health: "needs_repair", reason: "transient_cli_path" };
+  }
+  if (programArguments.length !== 3 || programArguments[2] !== "serve") {
+    return { health: "needs_repair", reason: "entrypoint_mismatch" };
+  }
+  return { health: "healthy" };
+};
+var hasMatchingProgramArgument = (programArguments, expectedValue, deps, isPath = false) => {
+  const normalizedExpected = isPath ? normalizeComparisonPath(expectedValue, deps.platform) : expectedValue;
+  return programArguments.some((value) => {
+    const normalizedValue = isPath ? normalizeComparisonPath(value, deps.platform) : value;
+    return normalizedValue === normalizedExpected;
+  });
+};
+var classifyExpectedProgramArguments = (expectedArgs, actualArgs, deps) => {
+  if (!hasMatchingProgramArgument([actualArgs[0] ?? ""], expectedArgs[0] ?? "", deps, true)) {
+    return hasMatchingProgramArgument(actualArgs, expectedArgs[0] ?? "", deps, true) ? "entrypoint_mismatch" : "missing_node_path";
+  }
+  if (!hasMatchingProgramArgument([actualArgs[1] ?? ""], expectedArgs[1] ?? "", deps, true)) {
+    return hasMatchingProgramArgument(actualArgs, expectedArgs[1] ?? "", deps, true) ? "entrypoint_mismatch" : "missing_cli_path";
+  }
+  if (actualArgs.length !== expectedArgs.length || !actualArgs.every((value, index) => {
+    const expectedValue = expectedArgs[index] ?? "";
+    return index < 2 ? normalizeComparisonPath(value, deps.platform) === normalizeComparisonPath(expectedValue, deps.platform) : value === expectedValue;
+  })) {
+    return "entrypoint_mismatch";
+  }
+  return void 0;
+};
+var readMacLaunchAgentProgramArguments = (plistPath, deps) => {
+  try {
+    const text = deps.execFileSync("plutil", ["-convert", "json", "-o", "-", plistPath], { encoding: "utf-8" });
+    const parsed = JSON.parse(text);
+    const programArguments = parsed?.ProgramArguments;
+    if (!Array.isArray(programArguments) || programArguments.length < 2 || programArguments.some((value) => typeof value !== "string")) {
+      return { ok: false, reason: "missing_program_arguments" };
+    }
+    const commandArgs = programArguments;
+    return {
+      ok: true,
+      command: formatCommand(commandArgs),
+      programArguments: commandArgs
+    };
+  } catch {
+    return { ok: false, reason: "malformed_plist" };
+  }
+};
+var classifyMacAutostartStatus = (entrypoint, location, deps) => {
+  if (!deps.existsSync(location)) {
+    return createMacAutostartStatus(entrypoint, location, {
+      installed: false,
+      health: "missing",
+      needsRepair: false,
+      reason: "missing_plist"
+    });
+  }
+  const parsed = readMacLaunchAgentProgramArguments(location, deps);
+  if (!parsed.ok) {
+    return createMacAutostartStatus(entrypoint, location, {
+      installed: true,
+      health: "malformed",
+      needsRepair: true,
+      reason: parsed.reason
+    });
+  }
+  const expectedNodePath = entrypoint.nodePath;
+  const expectedCliPath = entrypoint.cliPath;
+  const expectedArgs = [expectedNodePath, ...entrypoint.args];
+  const actualArgs = parsed.programArguments;
+  const actualStatus = classifyPersistedProgramArguments(actualArgs, deps);
+  if (actualStatus.health !== "healthy") {
+    return createMacAutostartStatus(entrypoint, location, {
+      installed: true,
+      health: "needs_repair",
+      needsRepair: true,
+      command: parsed.command,
+      reason: actualStatus.reason
+    });
+  }
+  if (entrypoint.isTransient) {
+    return createMacAutostartStatus(entrypoint, location, {
+      installed: true,
+      health: "healthy",
+      needsRepair: false,
+      command: parsed.command
+    });
+  }
+  const mismatchReason = classifyExpectedProgramArguments(expectedArgs, actualArgs, deps);
+  if (mismatchReason) {
+    return createMacAutostartStatus(entrypoint, location, {
+      installed: true,
+      health: "needs_repair",
+      needsRepair: true,
+      command: parsed.command,
+      reason: mismatchReason
+    });
+  }
+  return createMacAutostartStatus(entrypoint, location, {
+    installed: true,
+    health: "healthy",
+    needsRepair: false,
+    command: parsed.command
+  });
+};
 var runCommand = (exec, command, args, ignoreFailure = false) => {
   try {
     exec(command, args, { stdio: "ignore" });
@@ -2182,41 +2485,57 @@ var runCommand = (exec, command, args, ignoreFailure = false) => {
     throw new Error(`${command} ${args.join(" ")} failed: ${message}`);
   }
 };
+var assertPersistentEntrypoint = (entrypoint) => {
+  if (!entrypoint.isTransient) {
+    return;
+  }
+  throw new Error(
+    `${TRANSIENT_AUTOSTART_INSTALL_ERROR_PREFIX} "${entrypoint.cliPath}". ${STABLE_DAEMON_INSTALL_GUIDANCE} Do not use a temporary npx cache or onboarding workspace.`
+  );
+};
 var installMacAutostart = (deps = {}) => {
   const resolved = { ...defaultDeps(), ...deps };
   const entrypoint = resolveCliEntrypoint(resolved);
-  const plistPath = getLaunchAgentPath(resolved.homedir());
+  assertPersistentEntrypoint(entrypoint);
+  const home = resolved.homedir();
+  const plistPath = getLaunchAgentPath(home);
+  const stdoutPath = join8(home, "Library", "Logs", "opendevbrowser-daemon.log");
+  const stderrPath = join8(home, "Library", "Logs", "opendevbrowser-daemon.err.log");
+  const logsDir = dirname5(stdoutPath);
   resolved.mkdirSync(dirname5(plistPath), { recursive: true });
-  resolved.writeFileSync(plistPath, buildLaunchAgentPlist(entrypoint), { encoding: "utf-8" });
+  resolved.mkdirSync(logsDir, { recursive: true });
+  resolved.writeFileSync(
+    plistPath,
+    buildLaunchAgentPlist(entrypoint, { stdoutPath, stderrPath }),
+    { encoding: "utf-8" }
+  );
   const uid = resolved.uid;
   runCommand(resolved.execFileSync, "launchctl", ["bootout", `gui/${uid}`, plistPath], true);
   runCommand(resolved.execFileSync, "launchctl", ["bootstrap", `gui/${uid}`, plistPath]);
   runCommand(resolved.execFileSync, "launchctl", ["enable", `gui/${uid}/${MAC_LABEL}`], true);
   runCommand(resolved.execFileSync, "launchctl", ["kickstart", "-k", `gui/${uid}/${MAC_LABEL}`], true);
-  return {
-    platform: "darwin",
-    supported: true,
+  return createMacAutostartStatus(entrypoint, plistPath, {
     installed: true,
-    location: plistPath,
-    label: MAC_LABEL,
+    health: "healthy",
+    needsRepair: false,
     command: entrypoint.command
-  };
+  });
 };
 var uninstallMacAutostart = (deps = {}) => {
   const resolved = { ...defaultDeps(), ...deps };
+  const entrypoint = resolveCliEntrypoint(resolved);
   const plistPath = getLaunchAgentPath(resolved.homedir());
   const uid = resolved.uid;
   runCommand(resolved.execFileSync, "launchctl", ["bootout", `gui/${uid}`, plistPath], true);
   if (resolved.existsSync(plistPath)) {
     resolved.unlinkSync(plistPath);
   }
-  return {
-    platform: "darwin",
-    supported: true,
+  return createMacAutostartStatus(entrypoint, plistPath, {
     installed: false,
-    location: plistPath,
-    label: MAC_LABEL
-  };
+    health: "missing",
+    needsRepair: false,
+    reason: "missing_plist"
+  });
 };
 var isWindowsTaskInstalled = (deps = {}) => {
   const resolved = { ...defaultDeps(), ...deps };
@@ -2227,55 +2546,175 @@ var isWindowsTaskInstalled = (deps = {}) => {
     return false;
   }
 };
+var decodeXmlText = (value) => {
+  return value.replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+};
+var readXmlTag = (xml, tagName) => {
+  const match = xml.match(new RegExp(`<${tagName}>([\\s\\S]*?)</${tagName}>`, "i"));
+  return match?.[1] ? decodeXmlText(match[1]) : void 0;
+};
+var splitCommandLine = (value) => {
+  const args = [];
+  let current = "";
+  let inQuotes = false;
+  let backslashes = 0;
+  for (const char of value) {
+    if (char === "\\") {
+      backslashes += 1;
+      continue;
+    }
+    if (char === '"') {
+      if (backslashes > 0) {
+        current += "\\".repeat(Math.floor(backslashes / 2));
+        if (backslashes % 2 === 1) {
+          current += '"';
+          backslashes = 0;
+          continue;
+        }
+      }
+      backslashes = 0;
+      inQuotes = !inQuotes;
+      continue;
+    }
+    if (backslashes > 0) {
+      current += "\\".repeat(backslashes);
+      backslashes = 0;
+    }
+    if (!inQuotes && /\s/.test(char)) {
+      if (current.length > 0) {
+        args.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+  if (backslashes > 0) {
+    current += "\\".repeat(backslashes);
+  }
+  if (current.length > 0) {
+    args.push(current);
+  }
+  return args;
+};
+var readWindowsTaskAction = (taskName, deps) => {
+  try {
+    const xml = deps.execFileSync("schtasks", ["/Query", "/TN", taskName, "/XML"], { encoding: "utf-8" });
+    const command = readXmlTag(xml, "Command");
+    const argumentsValue = readXmlTag(xml, "Arguments");
+    if (!command) {
+      return { ok: false };
+    }
+    const programArguments = argumentsValue !== void 0 ? [command, ...splitCommandLine(argumentsValue)] : splitCommandLine(command);
+    if (programArguments.length === 0) {
+      return { ok: false };
+    }
+    return {
+      ok: true,
+      command: formatCommand(programArguments),
+      programArguments
+    };
+  } catch {
+    return { ok: false };
+  }
+};
+var classifyWindowsAutostartStatus = (entrypoint, deps) => {
+  const installed = isWindowsTaskInstalled(deps);
+  if (!installed) {
+    return createWindowsAutostartStatus(entrypoint, {
+      installed: false,
+      health: "missing",
+      needsRepair: false
+    });
+  }
+  const parsed = readWindowsTaskAction(WIN_TASK_NAME, deps);
+  if (!parsed.ok) {
+    return createWindowsAutostartStatus(entrypoint, {
+      installed: true,
+      health: "needs_repair",
+      needsRepair: true,
+      reason: "entrypoint_mismatch"
+    });
+  }
+  const expectedArgs = [entrypoint.nodePath, ...entrypoint.args];
+  const actualStatus = classifyPersistedProgramArguments(parsed.programArguments, deps);
+  if (actualStatus.health !== "healthy") {
+    return createWindowsAutostartStatus(entrypoint, {
+      installed: true,
+      health: "needs_repair",
+      needsRepair: true,
+      command: parsed.command,
+      reason: actualStatus.reason
+    });
+  }
+  if (entrypoint.isTransient) {
+    return createWindowsAutostartStatus(entrypoint, {
+      installed: true,
+      health: "healthy",
+      needsRepair: false,
+      command: parsed.command
+    });
+  }
+  const mismatchReason = classifyExpectedProgramArguments(expectedArgs, parsed.programArguments, deps);
+  if (mismatchReason) {
+    return createWindowsAutostartStatus(entrypoint, {
+      installed: true,
+      health: "needs_repair",
+      needsRepair: true,
+      command: parsed.command,
+      reason: mismatchReason
+    });
+  }
+  return createWindowsAutostartStatus(entrypoint, {
+    installed: true,
+    health: "healthy",
+    needsRepair: false,
+    command: parsed.command
+  });
+};
 var installWindowsAutostart = (deps = {}) => {
   const resolved = { ...defaultDeps(), ...deps };
   const entrypoint = resolveCliEntrypoint(resolved);
+  assertPersistentEntrypoint(entrypoint);
   const { args } = buildWindowsTaskArgs(entrypoint, WIN_TASK_NAME);
   runCommand(resolved.execFileSync, "schtasks", args);
-  return {
-    platform: "win32",
-    supported: true,
+  return createWindowsAutostartStatus(entrypoint, {
     installed: true,
-    taskName: WIN_TASK_NAME,
+    health: "healthy",
+    needsRepair: false,
     command: entrypoint.command
-  };
+  });
 };
 var uninstallWindowsAutostart = (deps = {}) => {
   const resolved = { ...defaultDeps(), ...deps };
+  const entrypoint = resolveCliEntrypoint(resolved);
   runCommand(resolved.execFileSync, "schtasks", ["/Delete", "/TN", WIN_TASK_NAME, "/F"], true);
-  return {
-    platform: "win32",
-    supported: true,
+  return createWindowsAutostartStatus(entrypoint, {
     installed: false,
-    taskName: WIN_TASK_NAME
-  };
+    health: "missing",
+    needsRepair: false
+  });
 };
 var getAutostartStatus = (deps = {}) => {
   const resolved = { ...defaultDeps(), ...deps };
   const platform = resolved.platform;
   if (platform === "darwin") {
+    const entrypoint = resolveCliEntrypoint(resolved);
     const location = getLaunchAgentPath(resolved.homedir());
-    return {
-      platform,
-      supported: true,
-      installed: resolved.existsSync(location),
-      location,
-      label: MAC_LABEL
-    };
+    return classifyMacAutostartStatus(entrypoint, location, resolved);
   }
   if (platform === "win32") {
-    return {
-      platform,
-      supported: true,
-      installed: isWindowsTaskInstalled(resolved),
-      taskName: WIN_TASK_NAME
-    };
+    const entrypoint = resolveCliEntrypoint(resolved);
+    return classifyWindowsAutostartStatus(entrypoint, resolved);
   }
-  return {
+  return createAutostartStatus({
     platform,
     supported: false,
-    installed: false
-  };
+    installed: false,
+    health: "unsupported",
+    needsRepair: false,
+    reason: "unsupported_platform"
+  });
 };
 var installAutostart = (deps = {}) => {
   const platform = deps.platform ?? process.platform;
@@ -2285,11 +2724,14 @@ var installAutostart = (deps = {}) => {
   if (platform === "win32") {
     return installWindowsAutostart(deps);
   }
-  return {
+  return createAutostartStatus({
     platform,
     supported: false,
-    installed: false
-  };
+    installed: false,
+    health: "unsupported",
+    needsRepair: false,
+    reason: "unsupported_platform"
+  });
 };
 var uninstallAutostart = (deps = {}) => {
   const platform = deps.platform ?? process.platform;
@@ -2299,11 +2741,14 @@ var uninstallAutostart = (deps = {}) => {
   if (platform === "win32") {
     return uninstallWindowsAutostart(deps);
   }
-  return {
+  return createAutostartStatus({
     platform,
     supported: false,
-    installed: false
-  };
+    installed: false,
+    health: "unsupported",
+    needsRepair: false,
+    reason: "unsupported_platform"
+  });
 };
 
 // src/cli/commands/daemon.ts
@@ -2329,20 +2774,55 @@ var stopDaemonIfRunning = async () => {
     return false;
   }
 };
+var formatReason = (reason) => {
+  return reason ? reason.replace(/_/g, " ") : "unknown reason";
+};
+var buildStableAutostartGuidance = (action) => {
+  return `${STABLE_DAEMON_INSTALL_GUIDANCE.replace(/\.$/, "")} to ${action} it.`;
+};
+var describeAutostartLocation = (autostart) => {
+  if (autostart.location) {
+    return ` at ${autostart.location}`;
+  }
+  if (autostart.taskName) {
+    return ` (${autostart.taskName})`;
+  }
+  return "";
+};
 var buildStatusMessage = (autostart, running) => {
+  const runningText = running ? "running" : "not running";
   if (!autostart.supported) {
-    return `Daemon autostart is not supported on ${autostart.platform}.`;
+    return `Daemon autostart is not supported on ${autostart.platform}. Daemon is ${runningText}.`;
   }
-  const installed = autostart.installed ? "installed" : "not installed";
-  const runningText = running ? "running" : "not running";
-  const location = autostart.location ? ` at ${autostart.location}` : "";
-  const task = autostart.taskName ? ` (${autostart.taskName})` : "";
-  return `Autostart ${installed}${location}${task}. Daemon is ${runningText}.`;
+  const location = describeAutostartLocation(autostart);
+  if (autostart.health === "healthy") {
+    return `Autostart is installed and healthy${location}. Daemon is ${runningText}.`;
+  }
+  if (autostart.health === "missing") {
+    return `Autostart is not installed${location}. ${buildStableAutostartGuidance("install")} Daemon is ${runningText}.`;
+  }
+  if (autostart.health === "needs_repair") {
+    return `Autostart is installed${location} but needs repair (${formatReason(autostart.reason)}). ${buildStableAutostartGuidance("repair")} Daemon is ${runningText}.`;
+  }
+  if (autostart.health === "malformed") {
+    return `Autostart exists${location} but is malformed (${formatReason(autostart.reason)}). ${buildStableAutostartGuidance("repair")} Daemon is ${runningText}.`;
+  }
+  return `Daemon autostart is not supported on ${autostart.platform}. Daemon is ${runningText}.`;
 };
 async function runDaemonCommand(args) {
   const { subcommand } = parseDaemonArgs(args.rawArgs);
   if (subcommand === "install") {
-    const result = installAutostart();
+    let result;
+    try {
+      result = installAutostart();
+    } catch (error) {
+      const message2 = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        message: isTransientAutostartInstallError(error) ? message2 : `Daemon autostart install failed: ${message2}`,
+        exitCode: EXIT_EXECUTION
+      };
+    }
     if (!result.supported) {
       return {
         success: false,
@@ -2400,7 +2880,21 @@ async function runDaemonCommand(args) {
 
 // src/cli/commands/artifacts.ts
 import { join as join9, resolve as resolve5 } from "path";
-import { tmpdir } from "os";
+import { tmpdir as tmpdir2 } from "os";
+var PASSTHROUGH_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+  "--with-config",
+  "--no-prompt",
+  "--no-interactive",
+  "--quiet",
+  "--skills-global",
+  "--skills-local",
+  "--no-skills",
+  "--full"
+]);
+var PASSTHROUGH_VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--output-format",
+  "--transport"
+]);
 var usageError = () => {
   throw createUsageError("Usage: opendevbrowser artifacts cleanup --expired-only [--output-dir <path>]");
 };
@@ -2411,6 +2905,24 @@ var requireValue = (rawArgs, index, flag) => {
   }
   return value;
 };
+var consumePassthroughFlag = (rawArgs, index) => {
+  const arg = rawArgs[index];
+  if (!arg) {
+    return null;
+  }
+  if (PASSTHROUGH_BOOLEAN_FLAGS.has(arg)) {
+    return index;
+  }
+  if (PASSTHROUGH_VALUE_FLAGS.has(arg)) {
+    requireValue(rawArgs, index, arg);
+    return index + 1;
+  }
+  const equalsFlag = arg.split("=", 2)[0];
+  if (equalsFlag && PASSTHROUGH_VALUE_FLAGS.has(equalsFlag)) {
+    return index;
+  }
+  return null;
+};
 var parseArtifactsArgs = (rawArgs) => {
   const [candidate, ...rest] = rawArgs;
   if (candidate !== "cleanup") {
@@ -2438,6 +2950,11 @@ var parseArtifactsArgs = (rawArgs) => {
       outputDir = value;
       continue;
     }
+    const passthroughIndex = consumePassthroughFlag(rest, index);
+    if (passthroughIndex !== null) {
+      index = passthroughIndex;
+      continue;
+    }
     throw createUsageError(`Unknown artifacts flag: ${arg}`);
   }
   if (!expiredOnly) {
@@ -2451,7 +2968,7 @@ var parseArtifactsArgs = (rawArgs) => {
 };
 async function runArtifactsCommand(args) {
   const parsed = parseArtifactsArgs(args.rawArgs);
-  const rootDir = parsed.outputDir ? resolve5(parsed.outputDir) : join9(tmpdir(), "opendevbrowser");
+  const rootDir = parsed.outputDir ? resolve5(parsed.outputDir) : join9(tmpdir2(), "opendevbrowser");
   const cleaned = await cleanupExpiredArtifacts(rootDir);
   return {
     success: true,
@@ -2467,10 +2984,139 @@ async function runArtifactsCommand(args) {
   };
 }
 
+// src/cli/install-autostart-reconciliation.ts
+var INSTALL_AUTOSTART_SKIP_ENV_VAR = "OPDEVBROWSER_SKIP_INSTALL_AUTOSTART_RECONCILIATION";
+var defaultDeps2 = () => ({
+  getAutostartStatus,
+  installAutostart
+});
+function shouldSkipInstallAutostartReconciliation(env = process.env) {
+  const raw = env[INSTALL_AUTOSTART_SKIP_ENV_VAR];
+  if (raw === void 0) {
+    return false;
+  }
+  const normalized = raw.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+function reconcileInstallAutostart(installResult, deps = {}, options = {}) {
+  if (!installResult.success || shouldSkipInstallAutostartReconciliation(options.env)) {
+    return { attempted: false };
+  }
+  const resolved = { ...defaultDeps2(), ...deps };
+  const status = resolved.getAutostartStatus();
+  if (!status.supported) {
+    return {
+      attempted: false,
+      autostart: status,
+      autostartAction: "unsupported"
+    };
+  }
+  if (status.health === "healthy") {
+    return {
+      attempted: false,
+      autostart: status,
+      autostartAction: "already_healthy"
+    };
+  }
+  if (status.health !== "missing" && status.health !== "needs_repair" && status.health !== "malformed") {
+    return {
+      attempted: false,
+      autostart: status
+    };
+  }
+  try {
+    const autostart = resolved.installAutostart();
+    return {
+      attempted: true,
+      autostart,
+      autostartAction: status.health === "missing" ? "installed" : "repaired"
+    };
+  } catch (error) {
+    let autostart = status;
+    try {
+      autostart = resolved.getAutostartStatus();
+    } catch {
+      autostart = status;
+    }
+    return {
+      attempted: true,
+      autostart,
+      autostartAction: "repair_failed",
+      autostartError: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// src/cli/install-autostart-output.ts
+function createInstallAutostartOutputPayload(result) {
+  if (!result) {
+    return {};
+  }
+  return {
+    autostart: result.autostart,
+    autostartAction: result.autostartAction,
+    ...result.autostartAction === "repair_failed" && result.autostartError ? { autostartError: result.autostartError } : {}
+  };
+}
+function formatAutostartReconciliationMessage(result) {
+  switch (result.autostartAction) {
+    case "unsupported":
+      return result.autostart ? `Autostart not supported on ${result.autostart.platform}.` : "Autostart not supported on this platform.";
+    case "already_healthy":
+      return "Autostart already healthy.";
+    case "installed":
+      return result.autostart ? `Autostart installed (${result.autostart.platform}).` : "Autostart installed.";
+    case "repaired":
+      return result.autostart ? `Autostart repaired (${result.autostart.platform}).` : "Autostart repaired.";
+    case "repair_failed":
+      if (result.autostartError && isTransientAutostartInstallError(result.autostartError)) {
+        return `Plugin install succeeded but autostart repair was skipped because the current CLI path is transient: ${result.autostartError}`;
+      }
+      return `Plugin install succeeded but autostart repair failed: ${result.autostartError ?? "unknown error"}. Run opendevbrowser daemon install to repair it.`;
+    default:
+      return null;
+  }
+}
+
 // src/cli/commands/run.ts
 import { readFileSync as readFileSync4 } from "fs";
 
 // src/cli/output.ts
+var normalizeExitCode = (code) => {
+  return Number.isInteger(code) ? Number(code) : 0;
+};
+var flushStream = (stream) => {
+  return new Promise((resolve6) => {
+    if (!stream || typeof stream.write !== "function") {
+      resolve6();
+      return;
+    }
+    try {
+      stream.write("", () => resolve6());
+    } catch {
+      resolve6();
+    }
+  });
+};
+async function flushOutputAndExit(code, proc = process, timeoutMs = 250) {
+  const finalCode = normalizeExitCode(code);
+  proc.exitCode = finalCode;
+  await new Promise((resolve6) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve6();
+    };
+    const timer = setTimeout(finish, Math.max(0, timeoutMs));
+    timer.unref?.();
+    void Promise.allSettled([flushStream(proc.stdout), flushStream(proc.stderr)]).finally(() => {
+      clearTimeout(timer);
+      finish();
+    });
+  });
+  proc.exit(finalCode);
+}
 function writeOutput(payload, options) {
   if (options.quiet) {
     return;
@@ -2526,7 +3172,19 @@ function parseRunArgs(rawArgs) {
       continue;
     }
     if (arg === "--persist-profile") {
-      parsed.persistProfile = true;
+      const value = rawArgs[i + 1];
+      if (value && !value.startsWith("--")) {
+        parsed.persistProfile = parseBooleanFlag(value, "--persist-profile");
+        i += 1;
+      } else {
+        parsed.persistProfile = true;
+      }
+      continue;
+    }
+    if (arg?.startsWith("--persist-profile=")) {
+      const value = arg.split("=", 2)[1];
+      if (!value) throw createUsageError("Missing value for --persist-profile");
+      parsed.persistProfile = parseBooleanFlag(value, "--persist-profile");
       continue;
     }
     if (arg === "--chrome-path") {
@@ -2613,7 +3271,7 @@ async function runScriptCommand(args) {
     startUrl: runArgs.startUrl,
     chromePath: runArgs.chromePath,
     flags: runArgs.flags.length ? runArgs.flags : void 0,
-    persistProfile: runArgs.persistProfile
+    persistProfile: runArgs.persistProfile ?? false
   });
   try {
     const result = await core.runner.run(launchResult.sessionId, steps, true);
@@ -2632,13 +3290,8 @@ async function runScriptCommand(args) {
 
 // src/cli/commands/session/launch.ts
 var MIN_LAUNCH_CALL_TIMEOUT_MS = 3e4;
+var MANAGED_HEADED_LAUNCH_CALL_TIMEOUT_MS = 6e4;
 var LAUNCH_CALL_TIMEOUT_BUFFER_MS = 5e3;
-var parseBooleanFlag = (value, flag) => {
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "true" || normalized === "1") return true;
-  if (normalized === "false" || normalized === "0") return false;
-  throw createUsageError(`Invalid ${flag}: ${value}`);
-};
 function parseLaunchArgs(rawArgs) {
   const parsed = { flags: [] };
   for (let i = 0; i < rawArgs.length; i += 1) {
@@ -2743,7 +3396,8 @@ function parseLaunchArgs(rawArgs) {
 }
 function deriveLaunchCallTimeoutMs(launchArgs) {
   const waitHintMs = typeof launchArgs.waitTimeoutMs === "number" ? launchArgs.waitTimeoutMs + LAUNCH_CALL_TIMEOUT_BUFFER_MS : 0;
-  return Math.max(MIN_LAUNCH_CALL_TIMEOUT_MS, waitHintMs);
+  const managedHeadedHintMs = launchArgs.noExtension && launchArgs.headless !== true ? MANAGED_HEADED_LAUNCH_CALL_TIMEOUT_MS : 0;
+  return Math.max(MIN_LAUNCH_CALL_TIMEOUT_MS, waitHintMs, managedHeadedHintMs);
 }
 async function runSessionLaunch(args) {
   const launchArgs = parseLaunchArgs(args.rawArgs);
@@ -2829,6 +3483,7 @@ function promptYesNo(question, defaultYes) {
 }
 
 // src/cli/commands/session/connect.ts
+var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
 function parseConnectArgs(rawArgs) {
   const parsed = {};
   for (let i = 0; i < rawArgs.length; i += 1) {
@@ -2896,7 +3551,9 @@ function parseConnectArgs(rawArgs) {
 }
 async function runSessionConnect(args) {
   const connectArgs = parseConnectArgs(args.rawArgs);
-  const result = await callDaemon("session.connect", connectArgs);
+  const result = await callDaemon("session.connect", connectArgs, {
+    timeoutMs: DEFAULT_CONNECT_TIMEOUT_MS
+  });
   return {
     success: true,
     message: `Session connected: ${result.sessionId}`,
@@ -2932,10 +3589,120 @@ async function runSessionDisconnect(args) {
   if (!sessionId) {
     throw createUsageError("Missing --session-id");
   }
-  await callDaemon("session.disconnect", { sessionId, closeBrowser }, { timeoutMs: 2e4 });
+  const timeoutMs = closeBrowser ? 12e4 : 2e4;
+  await callDaemon("session.disconnect", { sessionId, closeBrowser }, { timeoutMs });
   return { success: true, message: `Session disconnected: ${sessionId}` };
 }
 
+// src/cli/commands/session/inspector.ts
+function parseSessionInspectorArgs(rawArgs) {
+  const parsed = {};
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === "--session-id") {
+      const value = rawArgs[index + 1];
+      if (!value) throw createUsageError("Missing value for --session-id");
+      parsed.sessionId = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--session-id=")) {
+      parsed.sessionId = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--include-urls") {
+      parsed.includeUrls = true;
+      continue;
+    }
+    if (arg === "--since-console-seq") {
+      const value = rawArgs[index + 1];
+      if (!value) throw createUsageError("Missing value for --since-console-seq");
+      parsed.sinceConsoleSeq = parseNumberFlag(value, "--since-console-seq", { min: 0 });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--since-console-seq=")) {
+      const value = arg.split("=", 2)[1];
+      if (!value) throw createUsageError("Missing value for --since-console-seq");
+      parsed.sinceConsoleSeq = parseNumberFlag(value, "--since-console-seq", { min: 0 });
+      continue;
+    }
+    if (arg === "--since-network-seq") {
+      const value = rawArgs[index + 1];
+      if (!value) throw createUsageError("Missing value for --since-network-seq");
+      parsed.sinceNetworkSeq = parseNumberFlag(value, "--since-network-seq", { min: 0 });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--since-network-seq=")) {
+      const value = arg.split("=", 2)[1];
+      if (!value) throw createUsageError("Missing value for --since-network-seq");
+      parsed.sinceNetworkSeq = parseNumberFlag(value, "--since-network-seq", { min: 0 });
+      continue;
+    }
+    if (arg === "--since-exception-seq") {
+      const value = rawArgs[index + 1];
+      if (!value) throw createUsageError("Missing value for --since-exception-seq");
+      parsed.sinceExceptionSeq = parseNumberFlag(value, "--since-exception-seq", { min: 0 });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--since-exception-seq=")) {
+      const value = arg.split("=", 2)[1];
+      if (!value) throw createUsageError("Missing value for --since-exception-seq");
+      parsed.sinceExceptionSeq = parseNumberFlag(value, "--since-exception-seq", { min: 0 });
+      continue;
+    }
+    if (arg === "--max") {
+      const value = rawArgs[index + 1];
+      if (!value) throw createUsageError("Missing value for --max");
+      parsed.max = parseNumberFlag(value, "--max", { min: 1 });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--max=")) {
+      const value = arg.split("=", 2)[1];
+      if (!value) throw createUsageError("Missing value for --max");
+      parsed.max = parseNumberFlag(value, "--max", { min: 1 });
+      continue;
+    }
+    if (arg === "--request-id") {
+      const value = rawArgs[index + 1];
+      if (!value) throw createUsageError("Missing value for --request-id");
+      parsed.requestId = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--request-id=")) {
+      const value = arg.split("=", 2)[1];
+      if (!value) throw createUsageError("Missing value for --request-id");
+      parsed.requestId = value;
+      continue;
+    }
+  }
+  return parsed;
+}
+async function runSessionInspector(args) {
+  const parsed = parseSessionInspectorArgs(args.rawArgs);
+  if (!parsed.sessionId) {
+    throw createUsageError("Missing --session-id");
+  }
+  const result = await callDaemon("session.inspect", {
+    sessionId: parsed.sessionId,
+    ...typeof parsed.includeUrls === "boolean" ? { includeUrls: parsed.includeUrls } : {},
+    sinceConsoleSeq: parsed.sinceConsoleSeq,
+    sinceNetworkSeq: parsed.sinceNetworkSeq,
+    sinceExceptionSeq: parsed.sinceExceptionSeq,
+    max: parsed.max,
+    requestId: parsed.requestId
+  });
+  return {
+    success: true,
+    message: "Session inspector snapshot captured.",
+    data: result
+  };
+}
+
 // src/cli/commands/session/status.ts
 function parseStatusArgs(rawArgs) {
   const parsed = {};
@@ -2965,6 +3732,11 @@ async function runSessionStatus(args) {
 }
 
 // src/cli/commands/status.ts
+var DAEMON_STATUS_READ_OPTIONS = {
+  timeoutMs: 5e3,
+  retryAttempts: 5,
+  retryDelayMs: 250
+};
 var parseStatusArgs2 = (rawArgs) => {
   const parsed = { daemon: false };
   for (let i = 0; i < rawArgs.length; i += 1) {
@@ -2997,41 +3769,31 @@ async function runStatus(args) {
   }
   if (!daemon && args.transport === "native") {
     const nativeStatus2 = getNativeStatusSnapshot();
-    if (!nativeStatus2.installed) {
-      return {
-        success: false,
-        message: "Native host not installed.",
-        data: nativeStatus2,
-        exitCode: EXIT_DISCONNECTED
-      };
-    }
-    if (nativeStatus2.mismatch && nativeStatus2.extensionId && nativeStatus2.expectedExtensionId) {
-      return {
-        success: false,
-        message: `Native host targets ${nativeStatus2.extensionId}, but the current extension is ${nativeStatus2.expectedExtensionId}.`,
-        data: nativeStatus2,
-        exitCode: EXIT_DISCONNECTED
-      };
-    }
+    const assessment = assessNativeStatus(nativeStatus2);
     return {
-      success: true,
-      message: nativeStatus2.extensionId ? `Native host installed for extension ${nativeStatus2.extensionId}.` : "Native host installed.",
-      data: nativeStatus2
+      success: assessment.success,
+      message: assessment.message,
+      data: nativeStatus2,
+      exitCode: assessment.exitCode ?? void 0
     };
   }
-  const daemonStatus = await fetchDaemonStatusFromMetadata();
+  const daemonStatus = await fetchDaemonStatusFromMetadata(void 0, DAEMON_STATUS_READ_OPTIONS);
   if (!daemonStatus) {
     throw createUsageError("Daemon not running. Start with `opendevbrowser serve`.");
   }
   const nativeStatus = getNativeStatusSnapshot();
-  const nativeSummary = !nativeStatus.installed ? "not installed" : nativeStatus.mismatch && nativeStatus.extensionId && nativeStatus.expectedExtensionId ? `mismatch (${nativeStatus.extensionId} != ${nativeStatus.expectedExtensionId})` : `installed${nativeStatus.extensionId ? ` (${nativeStatus.extensionId})` : ""}`;
-  const baseMessage = [
+  const nativeAssessment = assessNativeStatus(nativeStatus);
+  const baseLines = [
     `Daemon OK (pid=${daemonStatus.pid})`,
     `Relay: port=${daemonStatus.relay.port ?? "n/a"} ext=${daemonStatus.relay.extensionConnected ? "on" : "off"} handshake=${daemonStatus.relay.extensionHandshakeComplete ? "on" : "off"} cdp=${daemonStatus.relay.cdpConnected ? "on" : "off"} annotate=${daemonStatus.relay.annotationConnected ? "on" : "off"} ops=${daemonStatus.relay.opsConnected ? "on" : "off"} canvas=${daemonStatus.relay.canvasConnected ? "on" : "off"} pairing=${daemonStatus.relay.pairingRequired ? "on" : "off"} health=${daemonStatus.relay.health?.reason ?? "n/a"}`,
-    `Native: ${nativeSummary}`,
+    `Native: ${nativeAssessment.summary}`,
     daemonStatus.relay.lastHandshakeError ? `Relay last handshake error: ${daemonStatus.relay.lastHandshakeError.code} (${daemonStatus.relay.lastHandshakeError.message})` : "Relay last handshake error: none",
     "Legend: ext=extension websocket, handshake=extension handshake, cdp=active /cdp client, annotate=annotation channel, ops=ops clients, canvas=canvas clients, pairing=token required, health=relay status"
-  ].join("\n");
+  ];
+  if (!nativeAssessment.success) {
+    baseLines.splice(3, 0, `Native detail: ${nativeAssessment.message}`);
+  }
+  const baseMessage = baseLines.join("\n");
   const message = daemon || args.outputFormat !== "text" ? baseMessage : [
     "Warning: `status` defaults to daemon status. Use --daemon explicitly or --session-id for session status.",
     baseMessage
@@ -3135,30 +3897,119 @@ function parseWaitArgs(rawArgs) {
       i += 1;
       continue;
     }
-    if (arg?.startsWith("--ref=")) {
-      parsed.ref = arg.split("=", 2)[1];
+    if (arg?.startsWith("--ref=")) {
+      parsed.ref = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--state") {
+      const value = rawArgs[i + 1];
+      if (!value) throw createUsageError("Missing value for --state");
+      parsed.state = value;
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--state=")) {
+      parsed.state = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--until") {
+      const value = rawArgs[i + 1];
+      if (!value) throw createUsageError("Missing value for --until");
+      parsed.until = value;
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--until=")) {
+      parsed.until = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--timeout-ms") {
+      const value = rawArgs[i + 1];
+      if (!value) throw createUsageError("Missing value for --timeout-ms");
+      parsed.timeoutMs = parseNumberFlag(value, "--timeout-ms", { min: 1 });
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--timeout-ms=")) {
+      const value = arg.split("=", 2)[1];
+      if (!value) throw createUsageError("Missing value for --timeout-ms");
+      parsed.timeoutMs = parseNumberFlag(value, "--timeout-ms", { min: 1 });
+      continue;
+    }
+  }
+  return parsed;
+}
+async function runWait(args) {
+  const { sessionId, ref, state, until, timeoutMs } = parseWaitArgs(args.rawArgs);
+  const targetId = parseOptionalStringFlag(args.rawArgs, "--target-id");
+  if (!sessionId) throw createUsageError("Missing --session-id");
+  const result = await callDaemon("nav.wait", {
+    sessionId,
+    ref,
+    state,
+    until,
+    timeoutMs,
+    ...typeof targetId === "string" ? { targetId } : {}
+  });
+  return { success: true, message: "Wait complete.", data: result };
+}
+
+// src/cli/transport-timeouts.ts
+var DEFAULT_CLICK_TRANSPORT_TIMEOUT_MS = 6e4;
+var DEFAULT_DIALOG_TRANSPORT_TIMEOUT_MS = 3e4;
+var DEFAULT_TARGET_CREATION_TRANSPORT_TIMEOUT_MS = 3e4;
+var DEFAULT_SNAPSHOT_TRANSPORT_TIMEOUT_MS = 3e4;
+var DEFAULT_REVIEW_TRANSPORT_TIMEOUT_MS = 3e4;
+var DEFAULT_SCREENSHOT_TRANSPORT_TIMEOUT_MS = 3e4;
+var DEFAULT_WORKFLOW_TRANSPORT_TIMEOUT_MS = 12e4;
+
+// src/cli/commands/nav/snapshot.ts
+function parseSnapshotArgs(rawArgs) {
+  const parsed = {};
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const arg = rawArgs[i];
+    if (arg === "--session-id") {
+      const value = rawArgs[i + 1];
+      if (!value) throw createUsageError("Missing value for --session-id");
+      parsed.sessionId = value;
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--session-id=")) {
+      parsed.sessionId = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--mode") {
+      const value = rawArgs[i + 1];
+      if (!value) throw createUsageError("Missing value for --mode");
+      parsed.mode = value;
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--mode=")) {
+      parsed.mode = arg.split("=", 2)[1];
       continue;
     }
-    if (arg === "--state") {
+    if (arg === "--max-chars") {
       const value = rawArgs[i + 1];
-      if (!value) throw createUsageError("Missing value for --state");
-      parsed.state = value;
+      if (!value) throw createUsageError("Missing value for --max-chars");
+      parsed.maxChars = Number(value);
       i += 1;
       continue;
     }
-    if (arg?.startsWith("--state=")) {
-      parsed.state = arg.split("=", 2)[1];
+    if (arg?.startsWith("--max-chars=")) {
+      parsed.maxChars = Number(arg.split("=", 2)[1]);
       continue;
     }
-    if (arg === "--until") {
+    if (arg === "--cursor") {
       const value = rawArgs[i + 1];
-      if (!value) throw createUsageError("Missing value for --until");
-      parsed.until = value;
+      if (!value) throw createUsageError("Missing value for --cursor");
+      parsed.cursor = value;
       i += 1;
       continue;
     }
-    if (arg?.startsWith("--until=")) {
-      parsed.until = arg.split("=", 2)[1];
+    if (arg?.startsWith("--cursor=")) {
+      parsed.cursor = arg.split("=", 2)[1];
       continue;
     }
     if (arg === "--timeout-ms") {
@@ -3172,28 +4023,29 @@ function parseWaitArgs(rawArgs) {
       const value = arg.split("=", 2)[1];
       if (!value) throw createUsageError("Missing value for --timeout-ms");
       parsed.timeoutMs = parseNumberFlag(value, "--timeout-ms", { min: 1 });
-      continue;
     }
   }
   return parsed;
 }
-async function runWait(args) {
-  const { sessionId, ref, state, until, timeoutMs } = parseWaitArgs(args.rawArgs);
+async function runSnapshot(args) {
+  const { sessionId, mode, maxChars, cursor, timeoutMs } = parseSnapshotArgs(args.rawArgs);
   const targetId = parseOptionalStringFlag(args.rawArgs, "--target-id");
   if (!sessionId) throw createUsageError("Missing --session-id");
-  const result = await callDaemon("nav.wait", {
+  const payload = {
     sessionId,
-    ref,
-    state,
-    until,
-    timeoutMs,
+    mode,
+    maxChars,
+    cursor,
     ...typeof targetId === "string" ? { targetId } : {}
+  };
+  const result = await callDaemon("nav.snapshot", payload, {
+    timeoutMs: timeoutMs ?? DEFAULT_SNAPSHOT_TRANSPORT_TIMEOUT_MS
   });
-  return { success: true, message: "Wait complete.", data: result };
+  return { success: true, message: "Snapshot captured.", data: result };
 }
 
-// src/cli/commands/nav/snapshot.ts
-function parseSnapshotArgs(rawArgs) {
+// src/cli/commands/nav/review.ts
+function parseReviewArgs(rawArgs) {
   const parsed = {};
   for (let i = 0; i < rawArgs.length; i += 1) {
     const arg = rawArgs[i];
@@ -3208,17 +4060,6 @@ function parseSnapshotArgs(rawArgs) {
       parsed.sessionId = arg.split("=", 2)[1];
       continue;
     }
-    if (arg === "--mode") {
-      const value = rawArgs[i + 1];
-      if (!value) throw createUsageError("Missing value for --mode");
-      parsed.mode = value;
-      i += 1;
-      continue;
-    }
-    if (arg?.startsWith("--mode=")) {
-      parsed.mode = arg.split("=", 2)[1];
-      continue;
-    }
     if (arg === "--max-chars") {
       const value = rawArgs[i + 1];
       if (!value) throw createUsageError("Missing value for --max-chars");
@@ -3241,21 +4082,35 @@ function parseSnapshotArgs(rawArgs) {
       parsed.cursor = arg.split("=", 2)[1];
       continue;
     }
+    if (arg === "--timeout-ms") {
+      const value = rawArgs[i + 1];
+      if (!value) throw createUsageError("Missing value for --timeout-ms");
+      parsed.timeoutMs = parseNumberFlag(value, "--timeout-ms", { min: 1 });
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--timeout-ms=")) {
+      const value = arg.split("=", 2)[1];
+      if (!value) throw createUsageError("Missing value for --timeout-ms");
+      parsed.timeoutMs = parseNumberFlag(value, "--timeout-ms", { min: 1 });
+    }
   }
   return parsed;
 }
-async function runSnapshot(args) {
-  const { sessionId, mode, maxChars, cursor } = parseSnapshotArgs(args.rawArgs);
+async function runReview(args) {
+  const { sessionId, maxChars, cursor, timeoutMs } = parseReviewArgs(args.rawArgs);
   const targetId = parseOptionalStringFlag(args.rawArgs, "--target-id");
   if (!sessionId) throw createUsageError("Missing --session-id");
-  const result = await callDaemon("nav.snapshot", {
+  const payload = {
     sessionId,
-    mode,
     maxChars,
     cursor,
     ...typeof targetId === "string" ? { targetId } : {}
+  };
+  const result = await callDaemon("nav.review", payload, {
+    timeoutMs: timeoutMs ?? DEFAULT_REVIEW_TRANSPORT_TIMEOUT_MS
   });
-  return { success: true, message: "Snapshot captured.", data: result };
+  return { success: true, message: "Review captured.", data: result };
 }
 
 // src/cli/commands/annotate.ts
@@ -3435,8 +4290,6 @@ async function runAnnotate(args) {
 // src/cli/commands/canvas.ts
 import { readFileSync as readFileSync5 } from "fs";
 var DEFAULT_FEEDBACK_STREAM_TIMEOUT_MS = 3e4;
-var MIN_FEEDBACK_STREAM_POLL_MS = 250;
-var MAX_FEEDBACK_STREAM_POLL_MS = 1e3;
 var isRecord = (value) => {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 };
@@ -3449,23 +4302,23 @@ var asNumber = (value) => {
 var asRecordArray = (value) => {
   return Array.isArray(value) ? value.filter(isRecord) : [];
 };
-var sleep = async (ms) => {
-  await new Promise((resolve6) => setTimeout(resolve6, ms));
-};
-var toFeedbackPollResult = (value) => {
+var toFeedbackSubscribeResult = (value) => {
   if (!isRecord(value)) {
-    return { items: [], nextCursor: null };
+    return {
+      subscriptionId: null,
+      initialItems: [],
+      cursor: null,
+      heartbeatMs: 15e3
+    };
   }
-  const retention = isRecord(value.retention) ? {
-    activeTargetIds: Array.isArray(value.retention.activeTargetIds) ? value.retention.activeTargetIds.filter((entry) => typeof entry === "string") : void 0
-  } : void 0;
   return {
-    items: asRecordArray(value.items),
-    nextCursor: asString(value.nextCursor),
-    retention
+    subscriptionId: asString(value.subscriptionId),
+    initialItems: asRecordArray(value.initialItems),
+    cursor: asString(value.cursor),
+    heartbeatMs: Math.max(asNumber(value.heartbeatMs) ?? 15e3, 1e3)
   };
 };
-async function streamFeedbackViaPolling(client, args, canvasArgs, params, initial) {
+async function streamFeedbackViaSubscription(client, args, canvasArgs, params, initial) {
   const outputOptions = { format: args.outputFormat, quiet: args.quiet };
   writeOutput({
     success: true,
@@ -3475,86 +4328,95 @@ async function streamFeedbackViaPolling(client, args, canvasArgs, params, initia
       result: initial
     }
   }, outputOptions);
-  const heartbeatMs = Math.max(asNumber(initial.heartbeatMs) ?? 15e3, 1e3);
-  const pollIntervalMs = Math.min(
-    MAX_FEEDBACK_STREAM_POLL_MS,
-    Math.max(MIN_FEEDBACK_STREAM_POLL_MS, Math.floor(heartbeatMs / 3))
-  );
+  const initialResult = toFeedbackSubscribeResult(initial);
+  const subscriptionId = initialResult.subscriptionId;
+  const heartbeatMs = initialResult.heartbeatMs;
   const streamTimeoutMs = canvasArgs.timeoutMs ?? DEFAULT_FEEDBACK_STREAM_TIMEOUT_MS;
   const deadline = Date.now() + streamTimeoutMs;
-  let cursor = asString(initial.cursor);
-  let lastHeartbeatAt = Date.now();
-  while (Date.now() < deadline) {
-    await sleep(pollIntervalMs);
+  let cursor = initialResult.cursor;
+  for (const item of initialResult.initialItems) {
+    const itemCursor = asString(item.cursor);
+    if (itemCursor) {
+      cursor = itemCursor;
+    }
+    writeOutput({
+      success: true,
+      message: `Canvas feedback: ${canvasArgs.command}`,
+      data: {
+        command: canvasArgs.command,
+        streamEvent: {
+          eventType: "feedback.item",
+          item
+        }
+      }
+    }, outputOptions);
+  }
+  while (subscriptionId && Date.now() < deadline) {
     const remainingMs = deadline - Date.now();
     if (remainingMs <= 0) {
       break;
     }
-    const polled = toFeedbackPollResult(await client.call(
+    const nextEvent = await client.call(
       "canvas.execute",
       {
-        command: "canvas.feedback.poll",
+        command: "canvas.feedback.next",
         params: {
           ...params,
-          afterCursor: cursor
+          subscriptionId,
+          timeoutMs: Math.min(heartbeatMs, remainingMs)
         }
       },
       { timeoutMs: remainingMs }
-    ));
-    if (polled.items.length > 0) {
-      for (const item of polled.items) {
-        const itemCursor = asString(item.cursor);
+    );
+    if (isRecord(nextEvent)) {
+      if (nextEvent.eventType === "feedback.item" && isRecord(nextEvent.item)) {
+        const itemCursor = asString(nextEvent.item.cursor);
         if (itemCursor) {
           cursor = itemCursor;
         }
-        writeOutput({
-          success: true,
-          message: `Canvas feedback: ${canvasArgs.command}`,
-          data: {
-            command: canvasArgs.command,
-            streamEvent: {
-              eventType: "feedback.item",
-              item,
-              cursor: cursor ?? null
-            }
-          }
-        }, outputOptions);
+      } else if (typeof nextEvent.cursor === "string") {
+        cursor = nextEvent.cursor;
       }
-      lastHeartbeatAt = Date.now();
-      continue;
     }
-    if (polled.nextCursor) {
-      cursor = polled.nextCursor;
+    writeOutput({
+      success: true,
+      message: `Canvas feedback: ${canvasArgs.command}`,
+      data: {
+        command: canvasArgs.command,
+        streamEvent: nextEvent
+      }
+    }, outputOptions);
+    if (isRecord(nextEvent) && nextEvent.eventType === "feedback.complete") {
+      break;
     }
-    if (Date.now() - lastHeartbeatAt >= heartbeatMs) {
-      writeOutput({
-        success: true,
-        message: `Canvas feedback: ${canvasArgs.command}`,
-        data: {
-          command: canvasArgs.command,
-          streamEvent: {
-            eventType: "feedback.heartbeat",
-            cursor: cursor ?? null,
-            ts: (/* @__PURE__ */ new Date()).toISOString(),
-            activeTargetIds: polled.retention?.activeTargetIds ?? []
-          }
+  }
+  if (Date.now() >= deadline) {
+    writeOutput({
+      success: true,
+      message: `Canvas feedback: ${canvasArgs.command}`,
+      data: {
+        command: canvasArgs.command,
+        streamEvent: {
+          eventType: "feedback.complete",
+          cursor: cursor ?? null,
+          reason: "timeout"
         }
-      }, outputOptions);
-      lastHeartbeatAt = Date.now();
-    }
+      }
+    }, outputOptions);
   }
-  writeOutput({
-    success: true,
-    message: `Canvas feedback: ${canvasArgs.command}`,
-    data: {
-      command: canvasArgs.command,
-      streamEvent: {
-        eventType: "feedback.complete",
-        cursor: cursor ?? null,
-        completeReason: "timeout"
+  if (subscriptionId) {
+    await client.call(
+      "canvas.execute",
+      {
+        command: "canvas.feedback.unsubscribe",
+        params: {
+          ...params,
+          subscriptionId
+        }
       }
-    }
-  }, outputOptions);
+    ).catch(() => {
+    });
+  }
 }
 var requireValue3 = (value, flag) => {
   if (!value) throw createUsageError(`Missing value for ${flag}`);
@@ -3639,6 +4501,15 @@ var resolveCanvasParams = (canvasArgs) => {
   }
   return {};
 };
+var attachRepoRoot = (params) => {
+  if (typeof params.repoRoot === "string" && params.repoRoot.trim().length > 0) {
+    return params;
+  }
+  return {
+    ...params,
+    repoRoot: process.cwd()
+  };
+};
 async function runCanvas(args) {
   const canvasArgs = parseCanvasArgs(args.rawArgs);
   if (!canvasArgs.command) {
@@ -3649,7 +4520,7 @@ async function runCanvas(args) {
   }
   const client = new DaemonClient({ autoRenew: true });
   try {
-    const params = resolveCanvasParams(canvasArgs);
+    const params = attachRepoRoot(resolveCanvasParams(canvasArgs));
     const result = await client.call(
       "canvas.execute",
       {
@@ -3659,7 +4530,7 @@ async function runCanvas(args) {
       { timeoutMs: canvasArgs.timeoutMs }
     );
     if (canvasArgs.command === "canvas.feedback.subscribe" && args.outputFormat === "stream-json" && isRecord(result)) {
-      await streamFeedbackViaPolling(client, args, canvasArgs, params, result);
+      await streamFeedbackViaSubscription(client, args, canvasArgs, params, result);
       return {
         success: true,
         message: `Canvas executed: ${canvasArgs.command}`,
@@ -3813,7 +4684,10 @@ async function runRpc(args) {
 
 // src/cli/commands/interact/click.ts
 function parseClickArgs(rawArgs) {
-  const parsed = {};
+  const timeoutValue = parseOptionalStringFlag(rawArgs, "--timeout-ms");
+  const parsed = {
+    timeoutMs: typeof timeoutValue === "string" ? parseNumberFlag(timeoutValue, "--timeout-ms", { min: 1 }) : void 0
+  };
   for (let i = 0; i < rawArgs.length; i += 1) {
     const arg = rawArgs[i];
     if (arg === "--session-id") {
@@ -3842,14 +4716,17 @@ function parseClickArgs(rawArgs) {
   return parsed;
 }
 async function runClick(args) {
-  const { sessionId, ref } = parseClickArgs(args.rawArgs);
+  const { sessionId, ref, timeoutMs } = parseClickArgs(args.rawArgs);
   const targetId = parseOptionalStringFlag(args.rawArgs, "--target-id");
   if (!sessionId) throw createUsageError("Missing --session-id");
   if (!ref) throw createUsageError("Missing --ref");
-  const result = await callDaemon("interact.click", {
+  const params = {
     sessionId,
     ref,
     ...typeof targetId === "string" ? { targetId } : {}
+  };
+  const result = await callDaemon("interact.click", params, {
+    timeoutMs: timeoutMs ?? DEFAULT_CLICK_TRANSPORT_TIMEOUT_MS
   });
   return { success: true, message: "Click complete.", data: result };
 }
@@ -4260,6 +5137,146 @@ async function runScrollIntoView(args) {
   return { success: true, message: "Scroll into view complete.", data: result };
 }
 
+// src/cli/commands/interact/upload.ts
+function parseUploadArgs(rawArgs) {
+  return {
+    sessionId: parseOptionalStringFlag(rawArgs, "--session-id"),
+    targetId: parseOptionalStringFlag(rawArgs, "--target-id"),
+    ref: parseOptionalStringFlag(rawArgs, "--ref"),
+    files: parseStringArrayFlag(rawArgs, "--files")
+  };
+}
+async function runUpload(args) {
+  const { sessionId, targetId, ref, files } = parseUploadArgs(args.rawArgs);
+  if (!sessionId) throw createUsageError("Missing --session-id");
+  if (!ref) throw createUsageError("Missing --ref");
+  if (!files) throw createUsageError("Missing --files");
+  const result = await callDaemon("interact.upload", {
+    sessionId,
+    ref,
+    files,
+    ...typeof targetId === "string" ? { targetId } : {}
+  });
+  return { success: true, message: "Upload complete.", data: result };
+}
+
+// src/cli/commands/interact/pointer-shared.ts
+var POINTER_BUTTONS = /* @__PURE__ */ new Set(["left", "middle", "right"]);
+function requireFlagValue(rawArgs, flag) {
+  const value = parseOptionalStringFlag(rawArgs, flag);
+  if (!value) {
+    throw createUsageError(`Missing ${flag}`);
+  }
+  return value;
+}
+function requirePointerCoordinate(rawArgs, flag) {
+  return parseNumberFlag(requireFlagValue(rawArgs, flag), flag, { integer: false });
+}
+function parsePointerSteps(rawArgs) {
+  const value = parseOptionalStringFlag(rawArgs, "--steps");
+  return value ? parseNumberFlag(value, "--steps", { min: 1 }) : void 0;
+}
+function parsePointerClickCount(rawArgs) {
+  const value = parseOptionalStringFlag(rawArgs, "--click-count");
+  return value ? parseNumberFlag(value, "--click-count", { min: 1 }) : void 0;
+}
+function parsePointerButton(rawArgs) {
+  const value = parseOptionalStringFlag(rawArgs, "--button");
+  if (!value) {
+    return void 0;
+  }
+  if (!POINTER_BUTTONS.has(value)) {
+    throw createUsageError(`Invalid --button: ${value}`);
+  }
+  return value;
+}
+
+// src/cli/commands/interact/pointer-move.ts
+async function runPointerMove(args) {
+  const sessionId = parseOptionalStringFlag(args.rawArgs, "--session-id");
+  const targetId = parseOptionalStringFlag(args.rawArgs, "--target-id");
+  const x = requirePointerCoordinate(args.rawArgs, "--x");
+  const y = requirePointerCoordinate(args.rawArgs, "--y");
+  const steps = parsePointerSteps(args.rawArgs);
+  if (!sessionId) {
+    throw createUsageError("Missing --session-id");
+  }
+  const result = await callDaemon("pointer.move", {
+    sessionId,
+    x,
+    y,
+    ...typeof steps === "number" ? { steps } : {},
+    ...typeof targetId === "string" ? { targetId } : {}
+  });
+  return { success: true, message: "Pointer move complete.", data: result };
+}
+
+// src/cli/commands/interact/pointer-down.ts
+async function runPointerDown(args) {
+  const sessionId = parseOptionalStringFlag(args.rawArgs, "--session-id");
+  const targetId = parseOptionalStringFlag(args.rawArgs, "--target-id");
+  const x = requirePointerCoordinate(args.rawArgs, "--x");
+  const y = requirePointerCoordinate(args.rawArgs, "--y");
+  const button = parsePointerButton(args.rawArgs);
+  const clickCount = parsePointerClickCount(args.rawArgs);
+  if (!sessionId) {
+    throw createUsageError("Missing --session-id");
+  }
+  const result = await callDaemon("pointer.down", {
+    sessionId,
+    x,
+    y,
+    ...typeof button === "string" ? { button } : {},
+    ...typeof clickCount === "number" ? { clickCount } : {},
+    ...typeof targetId === "string" ? { targetId } : {}
+  });
+  return { success: true, message: "Pointer down complete.", data: result };
+}
+
+// src/cli/commands/interact/pointer-up.ts
+async function runPointerUp(args) {
+  const sessionId = parseOptionalStringFlag(args.rawArgs, "--session-id");
+  const targetId = parseOptionalStringFlag(args.rawArgs, "--target-id");
+  const x = requirePointerCoordinate(args.rawArgs, "--x");
+  const y = requirePointerCoordinate(args.rawArgs, "--y");
+  const button = parsePointerButton(args.rawArgs);
+  const clickCount = parsePointerClickCount(args.rawArgs);
+  if (!sessionId) {
+    throw createUsageError("Missing --session-id");
+  }
+  const result = await callDaemon("pointer.up", {
+    sessionId,
+    x,
+    y,
+    ...typeof button === "string" ? { button } : {},
+    ...typeof clickCount === "number" ? { clickCount } : {},
+    ...typeof targetId === "string" ? { targetId } : {}
+  });
+  return { success: true, message: "Pointer up complete.", data: result };
+}
+
+// src/cli/commands/interact/pointer-drag.ts
+async function runPointerDrag(args) {
+  const sessionId = parseOptionalStringFlag(args.rawArgs, "--session-id");
+  const targetId = parseOptionalStringFlag(args.rawArgs, "--target-id");
+  const fromX = requirePointerCoordinate(args.rawArgs, "--from-x");
+  const fromY = requirePointerCoordinate(args.rawArgs, "--from-y");
+  const toX = requirePointerCoordinate(args.rawArgs, "--to-x");
+  const toY = requirePointerCoordinate(args.rawArgs, "--to-y");
+  const steps = parsePointerSteps(args.rawArgs);
+  if (!sessionId) {
+    throw createUsageError("Missing --session-id");
+  }
+  const result = await callDaemon("pointer.drag", {
+    sessionId,
+    from: { x: fromX, y: fromY },
+    to: { x: toX, y: toY },
+    ...typeof steps === "number" ? { steps } : {},
+    ...typeof targetId === "string" ? { targetId } : {}
+  });
+  return { success: true, message: "Pointer drag complete.", data: result };
+}
+
 // src/cli/commands/targets/list.ts
 function parseTargetsListArgs(rawArgs) {
   const parsed = {};
@@ -4360,7 +5377,11 @@ function parseTargetNewArgs(rawArgs) {
 async function runTargetNew(args) {
   const { sessionId, url } = parseTargetNewArgs(args.rawArgs);
   if (!sessionId) throw createUsageError("Missing --session-id");
-  const result = await callDaemon("targets.new", { sessionId, url });
+  const result = await callDaemon(
+    "targets.new",
+    { sessionId, url },
+    { timeoutMs: DEFAULT_TARGET_CREATION_TRANSPORT_TIMEOUT_MS }
+  );
   return { success: true, message: "Target created.", data: result };
 }
 
@@ -4447,7 +5468,11 @@ async function runPageOpen(args) {
   const { sessionId, name, url } = parsePageOpenArgs(args.rawArgs);
   if (!sessionId) throw createUsageError("Missing --session-id");
   if (!name) throw createUsageError("Missing --name");
-  const result = await callDaemon("page.open", { sessionId, name, url });
+  const result = await callDaemon(
+    "page.open",
+    { sessionId, name, url },
+    { timeoutMs: DEFAULT_TARGET_CREATION_TRANSPORT_TIMEOUT_MS }
+  );
   return { success: true, message: `Page ready: ${name}`, data: result };
 }
 
@@ -4945,97 +5970,162 @@ async function runCloneComponent(args) {
   });
   return { success: true, message: "Component cloned.", data: result };
 }
-
-// src/cli/commands/devtools/perf.ts
-function parsePerfArgs(rawArgs) {
-  const parsed = {};
-  for (let i = 0; i < rawArgs.length; i += 1) {
-    const arg = rawArgs[i];
-    if (arg === "--session-id") {
-      const value = rawArgs[i + 1];
-      if (!value) throw createUsageError("Missing value for --session-id");
-      parsed.sessionId = value;
-      i += 1;
-      continue;
-    }
-    if (arg?.startsWith("--session-id=")) {
-      parsed.sessionId = arg.split("=", 2)[1];
-      continue;
-    }
-  }
-  return parsed;
-}
-async function runPerf(args) {
-  const { sessionId } = parsePerfArgs(args.rawArgs);
-  const targetId = parseOptionalStringFlag(args.rawArgs, "--target-id");
-  if (!sessionId) throw createUsageError("Missing --session-id");
-  const result = await callDaemon("devtools.perf", {
-    sessionId,
-    ...typeof targetId === "string" ? { targetId } : {}
-  });
-  return { success: true, message: "Performance metrics captured.", data: result };
-}
-
-// src/cli/commands/devtools/screenshot.ts
-var requireValue5 = (value, flag) => {
-  if (!value) throw createUsageError(`Missing value for ${flag}`);
-  return value;
-};
-function parseScreenshotArgs(rawArgs) {
-  const parsed = {};
-  for (let i = 0; i < rawArgs.length; i += 1) {
-    const arg = rawArgs[i];
-    if (arg === "--session-id") {
-      parsed.sessionId = requireValue5(rawArgs[i + 1], "--session-id");
-      i += 1;
-      continue;
-    }
-    if (arg?.startsWith("--session-id=")) {
-      parsed.sessionId = requireValue5(arg.split("=", 2)[1], "--session-id");
-      continue;
-    }
-    if (arg === "--target-id") {
-      parsed.targetId = requireValue5(rawArgs[i + 1], "--target-id");
-      i += 1;
-      continue;
-    }
-    if (arg?.startsWith("--target-id=")) {
-      parsed.targetId = requireValue5(arg.split("=", 2)[1], "--target-id");
-      continue;
-    }
-    if (arg === "--path") {
-      parsed.path = requireValue5(rawArgs[i + 1], "--path");
-      i += 1;
-      continue;
-    }
-    if (arg?.startsWith("--path=")) {
-      parsed.path = requireValue5(arg.split("=", 2)[1], "--path");
-      continue;
-    }
-    if (arg === "--timeout-ms") {
-      parsed.timeoutMs = parseNumberFlag(requireValue5(rawArgs[i + 1], "--timeout-ms"), "--timeout-ms", { min: 1 });
+
+// src/cli/commands/devtools/perf.ts
+function parsePerfArgs(rawArgs) {
+  const parsed = {};
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const arg = rawArgs[i];
+    if (arg === "--session-id") {
+      const value = rawArgs[i + 1];
+      if (!value) throw createUsageError("Missing value for --session-id");
+      parsed.sessionId = value;
       i += 1;
       continue;
     }
-    if (arg?.startsWith("--timeout-ms=")) {
-      parsed.timeoutMs = parseNumberFlag(requireValue5(arg.split("=", 2)[1], "--timeout-ms"), "--timeout-ms", { min: 1 });
+    if (arg?.startsWith("--session-id=")) {
+      parsed.sessionId = arg.split("=", 2)[1];
       continue;
     }
   }
   return parsed;
 }
+async function runPerf(args) {
+  const { sessionId } = parsePerfArgs(args.rawArgs);
+  const targetId = parseOptionalStringFlag(args.rawArgs, "--target-id");
+  if (!sessionId) throw createUsageError("Missing --session-id");
+  const result = await callDaemon("devtools.perf", {
+    sessionId,
+    ...typeof targetId === "string" ? { targetId } : {}
+  });
+  return { success: true, message: "Performance metrics captured.", data: result };
+}
+
+// src/cli/commands/devtools/screenshot.ts
+function parseScreenshotArgs(rawArgs) {
+  const timeoutValue = parseOptionalStringFlag(rawArgs, "--timeout-ms");
+  const parsed = {
+    sessionId: parseOptionalStringFlag(rawArgs, "--session-id"),
+    targetId: parseOptionalStringFlag(rawArgs, "--target-id"),
+    path: parseOptionalStringFlag(rawArgs, "--path"),
+    ref: parseOptionalStringFlag(rawArgs, "--ref"),
+    fullPage: rawArgs.includes("--full-page"),
+    timeoutMs: typeof timeoutValue === "string" ? parseNumberFlag(timeoutValue, "--timeout-ms", { min: 1 }) : void 0
+  };
+  if (parsed.ref && parsed.fullPage) {
+    throw createUsageError("Choose either --ref or --full-page.");
+  }
+  return parsed;
+}
 async function runScreenshot(args) {
-  const { sessionId, targetId, path: path8, timeoutMs } = parseScreenshotArgs(args.rawArgs);
+  const { sessionId, targetId, path: path8, ref, fullPage, timeoutMs } = parseScreenshotArgs(args.rawArgs);
   if (!sessionId) throw createUsageError("Missing --session-id");
   const params = {
     sessionId,
-    path: path8,
-    ...typeof targetId === "string" ? { targetId } : {}
+    ...typeof path8 === "string" ? { path: path8 } : {},
+    ...typeof targetId === "string" ? { targetId } : {},
+    ...typeof ref === "string" ? { ref } : {},
+    ...fullPage === true ? { fullPage: true } : {}
   };
-  const result = typeof timeoutMs === "number" ? await callDaemon("page.screenshot", params, { timeoutMs }) : await callDaemon("page.screenshot", params);
+  const result = await callDaemon("page.screenshot", params, {
+    timeoutMs: timeoutMs ?? DEFAULT_SCREENSHOT_TRANSPORT_TIMEOUT_MS
+  });
   return { success: true, message: "Screenshot captured.", data: result };
 }
 
+// src/cli/commands/devtools/screencast-start.ts
+function parseScreencastStartArgs(rawArgs) {
+  const intervalValue = parseOptionalStringFlag(rawArgs, "--interval-ms");
+  const maxFramesValue = parseOptionalStringFlag(rawArgs, "--max-frames");
+  const timeoutValue = parseOptionalStringFlag(rawArgs, "--timeout-ms");
+  return {
+    sessionId: parseOptionalStringFlag(rawArgs, "--session-id"),
+    targetId: parseOptionalStringFlag(rawArgs, "--target-id"),
+    outputDir: parseOptionalStringFlag(rawArgs, "--output-dir"),
+    intervalMs: typeof intervalValue === "string" ? parseNumberFlag(intervalValue, "--interval-ms", { min: 250 }) : void 0,
+    maxFrames: typeof maxFramesValue === "string" ? parseNumberFlag(maxFramesValue, "--max-frames", { min: 1 }) : void 0,
+    timeoutMs: typeof timeoutValue === "string" ? parseNumberFlag(timeoutValue, "--timeout-ms", { min: 1 }) : void 0
+  };
+}
+async function runScreencastStart(args) {
+  const { sessionId, targetId, outputDir, intervalMs, maxFrames, timeoutMs } = parseScreencastStartArgs(args.rawArgs);
+  if (!sessionId) {
+    throw createUsageError("Missing --session-id");
+  }
+  const result = await callDaemon("page.screencast.start", {
+    sessionId,
+    ...typeof targetId === "string" ? { targetId } : {},
+    ...typeof outputDir === "string" ? { outputDir } : {},
+    ...typeof intervalMs === "number" ? { intervalMs } : {},
+    ...typeof maxFrames === "number" ? { maxFrames } : {}
+  }, {
+    timeoutMs: timeoutMs ?? DEFAULT_SCREENSHOT_TRANSPORT_TIMEOUT_MS
+  });
+  return { success: true, message: "Screencast started.", data: result };
+}
+
+// src/cli/commands/devtools/screencast-stop.ts
+function parseScreencastStopArgs(rawArgs) {
+  const timeoutValue = parseOptionalStringFlag(rawArgs, "--timeout-ms");
+  return {
+    sessionId: parseOptionalStringFlag(rawArgs, "--session-id"),
+    screencastId: parseOptionalStringFlag(rawArgs, "--screencast-id"),
+    timeoutMs: typeof timeoutValue === "string" ? parseNumberFlag(timeoutValue, "--timeout-ms", { min: 1 }) : void 0
+  };
+}
+async function runScreencastStop(args) {
+  const { sessionId, screencastId, timeoutMs } = parseScreencastStopArgs(args.rawArgs);
+  if (!sessionId) {
+    throw createUsageError("Missing --session-id");
+  }
+  if (!screencastId) {
+    throw createUsageError("Missing --screencast-id");
+  }
+  const result = await callDaemon("page.screencast.stop", { sessionId, screencastId }, {
+    timeoutMs: timeoutMs ?? DEFAULT_SCREENSHOT_TRANSPORT_TIMEOUT_MS
+  });
+  return { success: true, message: "Screencast stopped.", data: result };
+}
+
+// src/cli/commands/devtools/dialog.ts
+function parseDialogAction(value) {
+  if (!value) {
+    return "status";
+  }
+  if (value === "status" || value === "accept" || value === "dismiss") {
+    return value;
+  }
+  throw createUsageError(`Invalid --action: ${value}`);
+}
+function parseDialogArgs(rawArgs) {
+  const timeoutValue = parseOptionalStringFlag(rawArgs, "--timeout-ms");
+  const parsed = {
+    sessionId: parseOptionalStringFlag(rawArgs, "--session-id"),
+    targetId: parseOptionalStringFlag(rawArgs, "--target-id"),
+    action: parseDialogAction(parseOptionalStringFlag(rawArgs, "--action")),
+    promptText: parseOptionalStringFlag(rawArgs, "--prompt-text"),
+    timeoutMs: typeof timeoutValue === "string" ? parseNumberFlag(timeoutValue, "--timeout-ms", { min: 1 }) : void 0
+  };
+  if (parsed.promptText && parsed.action !== "accept") {
+    throw createUsageError("--prompt-text is only valid with --action accept");
+  }
+  return parsed;
+}
+async function runDialog(args) {
+  const { sessionId, targetId, action, promptText, timeoutMs } = parseDialogArgs(args.rawArgs);
+  if (!sessionId) throw createUsageError("Missing --session-id");
+  const params = {
+    sessionId,
+    action,
+    ...typeof targetId === "string" ? { targetId } : {},
+    ...typeof promptText === "string" ? { promptText } : {}
+  };
+  const result = await callDaemon("page.dialog", params, {
+    timeoutMs: timeoutMs ?? DEFAULT_DIALOG_TRANSPORT_TIMEOUT_MS
+  });
+  return { success: true, message: "Dialog request complete.", data: result };
+}
+
 // src/cli/commands/devtools/console-poll.ts
 function parseConsolePollArgs(rawArgs) {
   const parsed = {};
@@ -5236,9 +6326,103 @@ async function runDebugTraceSnapshot(args) {
   };
 }
 
+// src/cli/commands/desktop/shared.ts
+function parseDesktopTimeoutArgs(rawArgs) {
+  const timeoutValue = parseOptionalStringFlag(rawArgs, "--timeout-ms");
+  return {
+    timeoutMs: typeof timeoutValue === "string" ? parseNumberFlag(timeoutValue, "--timeout-ms", { min: 1 }) : void 0
+  };
+}
+function parseDesktopReasonArgs(rawArgs) {
+  return {
+    ...parseDesktopTimeoutArgs(rawArgs),
+    reason: parseOptionalStringFlag(rawArgs, "--reason")
+  };
+}
+function parseDesktopWindowReasonArgs(rawArgs) {
+  return {
+    ...parseDesktopReasonArgs(rawArgs),
+    windowId: parseOptionalStringFlag(rawArgs, "--window-id")
+  };
+}
+function requireDesktopReason(reason) {
+  if (!reason) {
+    throw createUsageError("Missing --reason");
+  }
+  return reason;
+}
+function requireDesktopWindowId(windowId) {
+  if (!windowId) {
+    throw createUsageError("Missing --window-id");
+  }
+  return windowId;
+}
+async function callDesktopCommand(name, params, timeoutMs) {
+  return callDaemon(name, params, {
+    timeoutMs: timeoutMs ?? DEFAULT_SCREENSHOT_TRANSPORT_TIMEOUT_MS
+  });
+}
+function desktopCommandResult(message, data) {
+  return { success: true, message, data };
+}
+
+// src/cli/commands/desktop/status.ts
+async function runDesktopStatus(args) {
+  const { timeoutMs } = parseDesktopTimeoutArgs(args.rawArgs);
+  const result = await callDesktopCommand("desktop.status", {}, timeoutMs);
+  return desktopCommandResult("Desktop status captured.", result);
+}
+
+// src/cli/commands/desktop/windows.ts
+async function runDesktopWindows(args) {
+  const { reason, timeoutMs } = parseDesktopReasonArgs(args.rawArgs);
+  const result = await callDesktopCommand("desktop.windows.list", {
+    ...typeof reason === "string" ? { reason } : {}
+  }, timeoutMs);
+  return desktopCommandResult("Desktop windows listed.", result);
+}
+
+// src/cli/commands/desktop/active-window.ts
+async function runDesktopActiveWindow(args) {
+  const { reason, timeoutMs } = parseDesktopReasonArgs(args.rawArgs);
+  const result = await callDesktopCommand("desktop.window.active", {
+    ...typeof reason === "string" ? { reason } : {}
+  }, timeoutMs);
+  return desktopCommandResult("Active desktop window captured.", result);
+}
+
+// src/cli/commands/desktop/capture-desktop.ts
+async function runDesktopCaptureDesktop(args) {
+  const { reason, timeoutMs } = parseDesktopReasonArgs(args.rawArgs);
+  const result = await callDesktopCommand("desktop.capture.desktop", {
+    reason: requireDesktopReason(reason)
+  }, timeoutMs);
+  return desktopCommandResult("Desktop captured.", result);
+}
+
+// src/cli/commands/desktop/capture-window.ts
+async function runDesktopCaptureWindow(args) {
+  const { windowId, reason, timeoutMs } = parseDesktopWindowReasonArgs(args.rawArgs);
+  const result = await callDesktopCommand("desktop.capture.window", {
+    windowId: requireDesktopWindowId(windowId),
+    reason: requireDesktopReason(reason)
+  }, timeoutMs);
+  return desktopCommandResult("Desktop window captured.", result);
+}
+
+// src/cli/commands/desktop/accessibility-snapshot.ts
+async function runDesktopAccessibilitySnapshot(args) {
+  const { windowId, reason, timeoutMs } = parseDesktopWindowReasonArgs(args.rawArgs);
+  const result = await callDesktopCommand("desktop.accessibility.snapshot", {
+    reason: requireDesktopReason(reason),
+    ...typeof windowId === "string" ? { windowId } : {}
+  }, timeoutMs);
+  return desktopCommandResult("Desktop accessibility snapshot captured.", result);
+}
+
 // src/cli/commands/session/cookie-import.ts
 import { readFileSync as readFileSync7 } from "fs";
-var requireValue6 = (value, flag) => {
+var requireValue5 = (value, flag) => {
   if (!value) {
     throw createUsageError(`Missing value for ${flag}`);
   }
@@ -5255,30 +6439,30 @@ var parseCookieImportArgs = (rawArgs) => {
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
     if (arg === "--session-id") {
-      parsed.sessionId = requireValue6(rawArgs[index + 1], "--session-id");
+      parsed.sessionId = requireValue5(rawArgs[index + 1], "--session-id");
       index += 1;
       continue;
     }
     if (arg?.startsWith("--session-id=")) {
-      parsed.sessionId = requireValue6(arg.split("=", 2)[1], "--session-id");
+      parsed.sessionId = requireValue5(arg.split("=", 2)[1], "--session-id");
       continue;
     }
     if (arg === "--cookies") {
-      parsed.cookies = requireValue6(rawArgs[index + 1], "--cookies");
+      parsed.cookies = requireValue5(rawArgs[index + 1], "--cookies");
       index += 1;
       continue;
     }
     if (arg?.startsWith("--cookies=")) {
-      parsed.cookies = requireValue6(arg.split("=", 2)[1], "--cookies");
+      parsed.cookies = requireValue5(arg.split("=", 2)[1], "--cookies");
       continue;
     }
     if (arg === "--cookies-file") {
-      parsed.cookiesFile = requireValue6(rawArgs[index + 1], "--cookies-file");
+      parsed.cookiesFile = requireValue5(rawArgs[index + 1], "--cookies-file");
       index += 1;
       continue;
     }
     if (arg?.startsWith("--cookies-file=")) {
-      parsed.cookiesFile = requireValue6(arg.split("=", 2)[1], "--cookies-file");
+      parsed.cookiesFile = requireValue5(arg.split("=", 2)[1], "--cookies-file");
       continue;
     }
     if (arg === "--strict") {
@@ -5286,16 +6470,16 @@ var parseCookieImportArgs = (rawArgs) => {
       continue;
     }
     if (arg?.startsWith("--strict=")) {
-      parsed.strict = parseStrictValue(requireValue6(arg.split("=", 2)[1], "--strict"), "--strict");
+      parsed.strict = parseStrictValue(requireValue5(arg.split("=", 2)[1], "--strict"), "--strict");
       continue;
     }
     if (arg === "--request-id") {
-      parsed.requestId = requireValue6(rawArgs[index + 1], "--request-id");
+      parsed.requestId = requireValue5(rawArgs[index + 1], "--request-id");
       index += 1;
       continue;
     }
     if (arg?.startsWith("--request-id=")) {
-      parsed.requestId = requireValue6(arg.split("=", 2)[1], "--request-id");
+      parsed.requestId = requireValue5(arg.split("=", 2)[1], "--request-id");
       continue;
     }
   }
@@ -5383,7 +6567,7 @@ async function runCookieImport(args) {
 }
 
 // src/cli/commands/session/cookie-list.ts
-var requireValue7 = (value, flag) => {
+var requireValue6 = (value, flag) => {
   if (!value) {
     throw createUsageError(`Missing value for ${flag}`);
   }
@@ -5420,31 +6604,31 @@ var parseCookieListArgs = (rawArgs) => {
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
     if (arg === "--session-id") {
-      parsed.sessionId = requireValue7(rawArgs[index + 1], "--session-id");
+      parsed.sessionId = requireValue6(rawArgs[index + 1], "--session-id");
       index += 1;
       continue;
     }
     if (arg?.startsWith("--session-id=")) {
-      parsed.sessionId = requireValue7(arg.split("=", 2)[1], "--session-id");
+      parsed.sessionId = requireValue6(arg.split("=", 2)[1], "--session-id");
       continue;
     }
     if (arg === "--url") {
-      const rawValue = requireValue7(rawArgs[index + 1], "--url");
+      const rawValue = requireValue6(rawArgs[index + 1], "--url");
       parsed.urls.push(...rawValue.split(","));
       index += 1;
       continue;
     }
     if (arg?.startsWith("--url=")) {
-      parsed.urls.push(...requireValue7(arg.split("=", 2)[1], "--url").split(","));
+      parsed.urls.push(...requireValue6(arg.split("=", 2)[1], "--url").split(","));
       continue;
     }
     if (arg === "--request-id") {
-      parsed.requestId = requireValue7(rawArgs[index + 1], "--request-id");
+      parsed.requestId = requireValue6(rawArgs[index + 1], "--request-id");
       index += 1;
       continue;
     }
     if (arg?.startsWith("--request-id=")) {
-      parsed.requestId = requireValue7(arg.split("=", 2)[1], "--request-id");
+      parsed.requestId = requireValue6(arg.split("=", 2)[1], "--request-id");
       continue;
     }
   }
@@ -5470,7 +6654,7 @@ async function runCookieList(args) {
 }
 
 // src/cli/commands/macro-resolve.ts
-var requireValue8 = (value, flag) => {
+var requireValue7 = (value, flag) => {
   if (!value) {
     throw createUsageError(`Missing value for ${flag}`);
   }
@@ -5481,21 +6665,21 @@ var parseMacroResolveArgs = (rawArgs) => {
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
     if (arg === "--expression") {
-      parsed.expression = requireValue8(rawArgs[index + 1], "--expression");
+      parsed.expression = requireValue7(rawArgs[index + 1], "--expression");
       index += 1;
       continue;
     }
     if (arg?.startsWith("--expression=")) {
-      parsed.expression = requireValue8(arg.split("=", 2)[1], "--expression");
+      parsed.expression = requireValue7(arg.split("=", 2)[1], "--expression");
       continue;
     }
     if (arg === "--default-provider") {
-      parsed.defaultProvider = requireValue8(rawArgs[index + 1], "--default-provider");
+      parsed.defaultProvider = requireValue7(rawArgs[index + 1], "--default-provider");
       index += 1;
       continue;
     }
     if (arg?.startsWith("--default-provider=")) {
-      parsed.defaultProvider = requireValue8(arg.split("=", 2)[1], "--default-provider");
+      parsed.defaultProvider = requireValue7(arg.split("=", 2)[1], "--default-provider");
       continue;
     }
     if (arg === "--include-catalog") {
@@ -5507,13 +6691,30 @@ var parseMacroResolveArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--timeout-ms") {
-      const value = requireValue8(rawArgs[index + 1], "--timeout-ms");
+      const value = requireValue7(rawArgs[index + 1], "--timeout-ms");
       parsed.timeoutMs = parseNumberFlag(value, "--timeout-ms", { min: 1 });
       index += 1;
       continue;
     }
     if (arg?.startsWith("--timeout-ms=")) {
-      parsed.timeoutMs = parseNumberFlag(requireValue8(arg.split("=", 2)[1], "--timeout-ms"), "--timeout-ms", { min: 1 });
+      parsed.timeoutMs = parseNumberFlag(requireValue7(arg.split("=", 2)[1], "--timeout-ms"), "--timeout-ms", { min: 1 });
+      continue;
+    }
+    if (arg === "--challenge-automation-mode") {
+      const value = requireValue7(rawArgs[index + 1], "--challenge-automation-mode");
+      if (!isChallengeAutomationMode(value)) {
+        throw createUsageError(`Invalid --challenge-automation-mode: ${value}`);
+      }
+      parsed.challengeAutomationMode = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--challenge-automation-mode=")) {
+      const value = requireValue7(arg.split("=", 2)[1], "--challenge-automation-mode");
+      if (!isChallengeAutomationMode(value)) {
+        throw createUsageError(`Invalid --challenge-automation-mode: ${value}`);
+      }
+      parsed.challengeAutomationMode = value;
       continue;
     }
   }
@@ -5528,7 +6729,9 @@ async function runMacroResolve(args) {
     expression: parsed.expression,
     defaultProvider: parsed.defaultProvider,
     includeCatalog: parsed.includeCatalog ?? false,
-    execute: parsed.execute ?? false
+    execute: parsed.execute ?? false,
+    ...typeof parsed.timeoutMs === "number" ? { timeoutMs: parsed.timeoutMs } : {},
+    ...parsed.challengeAutomationMode ? { challengeAutomationMode: parsed.challengeAutomationMode } : {}
   };
   const result = typeof parsed.timeoutMs === "number" ? await callDaemon("macro.resolve", params, { timeoutMs: parsed.timeoutMs }) : await callDaemon("macro.resolve", params);
   return {
@@ -5538,12 +6741,42 @@ async function runMacroResolve(args) {
   };
 }
 
+// src/cli/utils/workflow-message.ts
+var readMeta = (data) => {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+  const meta = data.meta;
+  return meta && typeof meta === "object" && !Array.isArray(meta) ? meta : null;
+};
+var readPrimarySummary = (data) => {
+  const meta = readMeta(data);
+  if (!meta) return null;
+  const summary = meta.primaryConstraintSummary;
+  return typeof summary === "string" && summary.trim().length > 0 ? summary.trim() : null;
+};
+var readFailures = (data) => {
+  const meta = readMeta(data);
+  if (!meta) return [];
+  const failures = meta.failures;
+  return Array.isArray(failures) ? failures.filter((entry) => Boolean(entry) && typeof entry === "object") : [];
+};
+var buildWorkflowCompletionMessage = (workflowLabel, data) => {
+  const explicitSummary = readPrimarySummary(data);
+  if (explicitSummary) {
+    return `${workflowLabel} completed with provider follow-up required: ${explicitSummary}`;
+  }
+  const inferred = summarizePrimaryProviderIssue(readFailures(data));
+  if (inferred) {
+    return `${workflowLabel} completed with provider follow-up required: ${inferred.summary}`;
+  }
+  return `${workflowLabel} completed.`;
+};
+
 // src/cli/commands/research.ts
 var SOURCE_VALUES = /* @__PURE__ */ new Set(["web", "community", "social", "shopping"]);
 var SOURCE_SELECTION_VALUES = /* @__PURE__ */ new Set(["auto", "web", "community", "social", "shopping", "all"]);
 var MODE_VALUES = /* @__PURE__ */ new Set(["compact", "json", "md", "context", "path"]);
 var COOKIE_POLICY_VALUES = /* @__PURE__ */ new Set(["off", "auto", "required"]);
-var requireValue9 = (rawArgs, index, flag) => {
+var requireValue8 = (rawArgs, index, flag) => {
   const value = rawArgs[index + 1];
   if (!value) {
     throw createUsageError(`Missing value for ${flag}`);
@@ -5573,7 +6806,7 @@ var parseResearchRunArgs = (rawArgs) => {
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
     if (arg === "--topic") {
-      parsed.topic = requireValue9(rawArgs, index, "--topic");
+      parsed.topic = requireValue8(rawArgs, index, "--topic");
       index += 1;
       continue;
     }
@@ -5582,7 +6815,7 @@ var parseResearchRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--days") {
-      parsed.days = parseNumberFlag(requireValue9(rawArgs, index, "--days"), "--days", { min: 1, max: 365 });
+      parsed.days = parseNumberFlag(requireValue8(rawArgs, index, "--days"), "--days", { min: 1, max: 365 });
       index += 1;
       continue;
     }
@@ -5591,7 +6824,7 @@ var parseResearchRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--from") {
-      parsed.from = requireValue9(rawArgs, index, "--from");
+      parsed.from = requireValue8(rawArgs, index, "--from");
       index += 1;
       continue;
     }
@@ -5600,7 +6833,7 @@ var parseResearchRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--to") {
-      parsed.to = requireValue9(rawArgs, index, "--to");
+      parsed.to = requireValue8(rawArgs, index, "--to");
       index += 1;
       continue;
     }
@@ -5609,7 +6842,7 @@ var parseResearchRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--source-selection") {
-      const value = requireValue9(rawArgs, index, "--source-selection").toLowerCase();
+      const value = requireValue8(rawArgs, index, "--source-selection").toLowerCase();
       if (!SOURCE_SELECTION_VALUES.has(value)) {
         throw createUsageError(`Invalid --source-selection: ${value}`);
       }
@@ -5626,7 +6859,7 @@ var parseResearchRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--sources") {
-      parsed.sources = parseSources(requireValue9(rawArgs, index, "--sources"));
+      parsed.sources = parseSources(requireValue8(rawArgs, index, "--sources"));
       index += 1;
       continue;
     }
@@ -5635,7 +6868,7 @@ var parseResearchRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--mode") {
-      const value = requireValue9(rawArgs, index, "--mode").toLowerCase();
+      const value = requireValue8(rawArgs, index, "--mode").toLowerCase();
       if (!MODE_VALUES.has(value)) {
         throw createUsageError(`Invalid --mode: ${value}`);
       }
@@ -5656,7 +6889,7 @@ var parseResearchRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--limit-per-source") {
-      parsed.limitPerSource = parseNumberFlag(requireValue9(rawArgs, index, "--limit-per-source"), "--limit-per-source", { min: 1, max: 100 });
+      parsed.limitPerSource = parseNumberFlag(requireValue8(rawArgs, index, "--limit-per-source"), "--limit-per-source", { min: 1, max: 100 });
       index += 1;
       continue;
     }
@@ -5664,8 +6897,17 @@ var parseResearchRunArgs = (rawArgs) => {
       parsed.limitPerSource = parseNumberFlag(arg.split("=", 2)[1] ?? "", "--limit-per-source", { min: 1, max: 100 });
       continue;
     }
+    if (arg === "--timeout-ms") {
+      parsed.timeoutMs = parseNumberFlag(requireValue8(rawArgs, index, "--timeout-ms"), "--timeout-ms", { min: 1 });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--timeout-ms=")) {
+      parsed.timeoutMs = parseNumberFlag(arg.split("=", 2)[1] ?? "", "--timeout-ms", { min: 1 });
+      continue;
+    }
     if (arg === "--output-dir") {
-      parsed.outputDir = requireValue9(rawArgs, index, "--output-dir");
+      parsed.outputDir = requireValue8(rawArgs, index, "--output-dir");
       index += 1;
       continue;
     }
@@ -5674,7 +6916,7 @@ var parseResearchRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--ttl-hours") {
-      parsed.ttlHours = parseNumberFlag(requireValue9(rawArgs, index, "--ttl-hours"), "--ttl-hours", { min: 1, max: 168 });
+      parsed.ttlHours = parseNumberFlag(requireValue8(rawArgs, index, "--ttl-hours"), "--ttl-hours", { min: 1, max: 168 });
       index += 1;
       continue;
     }
@@ -5690,8 +6932,25 @@ var parseResearchRunArgs = (rawArgs) => {
       parsed.useCookies = parseBoolean(arg.split("=", 2)[1] ?? "", "--use-cookies");
       continue;
     }
+    if (arg === "--challenge-automation-mode") {
+      const value = requireValue8(rawArgs, index, "--challenge-automation-mode");
+      if (!isChallengeAutomationMode(value)) {
+        throw createUsageError(`Invalid --challenge-automation-mode: ${value}`);
+      }
+      parsed.challengeAutomationMode = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--challenge-automation-mode=")) {
+      const value = arg.split("=", 2)[1] ?? "";
+      if (!isChallengeAutomationMode(value)) {
+        throw createUsageError(`Invalid --challenge-automation-mode: ${value}`);
+      }
+      parsed.challengeAutomationMode = value;
+      continue;
+    }
     if (arg === "--cookie-policy-override" || arg === "--cookie-policy") {
-      const value = requireValue9(rawArgs, index, arg).toLowerCase();
+      const value = requireValue8(rawArgs, index, arg).toLowerCase();
       if (!COOKIE_POLICY_VALUES.has(value)) {
         throw createUsageError(`Invalid ${arg}: ${value}`);
       }
@@ -5719,7 +6978,7 @@ async function runResearchCommand(args) {
   if (!parsed.topic?.trim()) {
     throw createUsageError("Missing --topic");
   }
-  const data = await callDaemon("research.run", {
+  const payload = {
     topic: parsed.topic,
     days: parsed.days,
     from: parsed.from,
@@ -5729,14 +6988,17 @@ async function runResearchCommand(args) {
     mode: parsed.mode ?? "compact",
     includeEngagement: parsed.includeEngagement ?? false,
     limitPerSource: parsed.limitPerSource,
+    timeoutMs: parsed.timeoutMs ?? DEFAULT_WORKFLOW_TRANSPORT_TIMEOUT_MS,
     outputDir: parsed.outputDir,
     ttlHours: parsed.ttlHours,
     useCookies: parsed.useCookies,
+    challengeAutomationMode: parsed.challengeAutomationMode,
     cookiePolicyOverride: parsed.cookiePolicyOverride
-  });
+  };
+  const data = await callDaemon("research.run", payload);
   return {
     success: true,
-    message: "Research workflow completed.",
+    message: buildWorkflowCompletionMessage("Research workflow", data),
     data
   };
 }
@@ -5745,7 +7007,15 @@ async function runResearchCommand(args) {
 var SORT_VALUES = /* @__PURE__ */ new Set(["best_deal", "lowest_price", "highest_rating", "fastest_shipping"]);
 var MODE_VALUES2 = /* @__PURE__ */ new Set(["compact", "json", "md", "context", "path"]);
 var COOKIE_POLICY_VALUES2 = /* @__PURE__ */ new Set(["off", "auto", "required"]);
-var requireValue10 = (rawArgs, index, flag) => {
+var BROWSER_MODE_VALUES = /* @__PURE__ */ new Set(["auto", "extension", "managed"]);
+var SHOPPING_TRANSPORT_TIMEOUT_BUFFER_MS = 6e4;
+var deriveShoppingTransportTimeoutMs = (timeoutMs) => {
+  return Math.max(
+    DEFAULT_WORKFLOW_TRANSPORT_TIMEOUT_MS,
+    timeoutMs + SHOPPING_TRANSPORT_TIMEOUT_BUFFER_MS
+  );
+};
+var requireValue9 = (rawArgs, index, flag) => {
   const value = rawArgs[index + 1];
   if (!value) {
     throw createUsageError(`Missing value for ${flag}`);
@@ -5769,7 +7039,7 @@ var parseShoppingRunArgs = (rawArgs) => {
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
     if (arg === "--query") {
-      parsed.query = requireValue10(rawArgs, index, "--query");
+      parsed.query = requireValue9(rawArgs, index, "--query");
       index += 1;
       continue;
     }
@@ -5778,7 +7048,7 @@ var parseShoppingRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--providers") {
-      parsed.providers = parseProviders(requireValue10(rawArgs, index, "--providers"));
+      parsed.providers = parseProviders(requireValue9(rawArgs, index, "--providers"));
       index += 1;
       continue;
     }
@@ -5787,7 +7057,7 @@ var parseShoppingRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--budget") {
-      parsed.budget = parseNumberFlag(requireValue10(rawArgs, index, "--budget"), "--budget", { min: 1, integer: false });
+      parsed.budget = parseNumberFlag(requireValue9(rawArgs, index, "--budget"), "--budget", { min: 1, integer: false });
       index += 1;
       continue;
     }
@@ -5796,7 +7066,7 @@ var parseShoppingRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--region") {
-      parsed.region = requireValue10(rawArgs, index, "--region");
+      parsed.region = requireValue9(rawArgs, index, "--region");
       index += 1;
       continue;
     }
@@ -5804,8 +7074,25 @@ var parseShoppingRunArgs = (rawArgs) => {
       parsed.region = arg.split("=", 2)[1];
       continue;
     }
+    if (arg === "--browser-mode") {
+      const value = requireValue9(rawArgs, index, "--browser-mode").toLowerCase();
+      if (!BROWSER_MODE_VALUES.has(value)) {
+        throw createUsageError(`Invalid --browser-mode: ${value}`);
+      }
+      parsed.browserMode = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--browser-mode=")) {
+      const value = (arg.split("=", 2)[1] ?? "").toLowerCase();
+      if (!BROWSER_MODE_VALUES.has(value)) {
+        throw createUsageError(`Invalid --browser-mode: ${value}`);
+      }
+      parsed.browserMode = value;
+      continue;
+    }
     if (arg === "--sort") {
-      const value = requireValue10(rawArgs, index, "--sort").toLowerCase();
+      const value = requireValue9(rawArgs, index, "--sort").toLowerCase();
       if (!SORT_VALUES.has(value)) {
         throw createUsageError(`Invalid --sort: ${value}`);
       }
@@ -5822,7 +7109,7 @@ var parseShoppingRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--mode") {
-      const value = requireValue10(rawArgs, index, "--mode").toLowerCase();
+      const value = requireValue9(rawArgs, index, "--mode").toLowerCase();
       if (!MODE_VALUES2.has(value)) {
         throw createUsageError(`Invalid --mode: ${value}`);
       }
@@ -5839,7 +7126,7 @@ var parseShoppingRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--timeout-ms") {
-      parsed.timeoutMs = parseNumberFlag(requireValue10(rawArgs, index, "--timeout-ms"), "--timeout-ms", { min: 1 });
+      parsed.timeoutMs = parseNumberFlag(requireValue9(rawArgs, index, "--timeout-ms"), "--timeout-ms", { min: 1 });
       index += 1;
       continue;
     }
@@ -5848,7 +7135,7 @@ var parseShoppingRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--output-dir") {
-      parsed.outputDir = requireValue10(rawArgs, index, "--output-dir");
+      parsed.outputDir = requireValue9(rawArgs, index, "--output-dir");
       index += 1;
       continue;
     }
@@ -5857,7 +7144,7 @@ var parseShoppingRunArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--ttl-hours") {
-      parsed.ttlHours = parseNumberFlag(requireValue10(rawArgs, index, "--ttl-hours"), "--ttl-hours", { min: 1, max: 168 });
+      parsed.ttlHours = parseNumberFlag(requireValue9(rawArgs, index, "--ttl-hours"), "--ttl-hours", { min: 1, max: 168 });
       index += 1;
       continue;
     }
@@ -5873,8 +7160,25 @@ var parseShoppingRunArgs = (rawArgs) => {
       parsed.useCookies = parseBoolean2(arg.split("=", 2)[1] ?? "", "--use-cookies");
       continue;
     }
+    if (arg === "--challenge-automation-mode") {
+      const value = requireValue9(rawArgs, index, "--challenge-automation-mode");
+      if (!isChallengeAutomationMode(value)) {
+        throw createUsageError(`Invalid --challenge-automation-mode: ${value}`);
+      }
+      parsed.challengeAutomationMode = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--challenge-automation-mode=")) {
+      const value = arg.split("=", 2)[1] ?? "";
+      if (!isChallengeAutomationMode(value)) {
+        throw createUsageError(`Invalid --challenge-automation-mode: ${value}`);
+      }
+      parsed.challengeAutomationMode = value;
+      continue;
+    }
     if (arg === "--cookie-policy-override" || arg === "--cookie-policy") {
-      const value = requireValue10(rawArgs, index, arg).toLowerCase();
+      const value = requireValue9(rawArgs, index, arg).toLowerCase();
       if (!COOKIE_POLICY_VALUES2.has(value)) {
         throw createUsageError(`Invalid ${arg}: ${value}`);
       }
@@ -5907,24 +7211,28 @@ async function runShoppingCommand(args) {
     providers: parsed.providers,
     budget: parsed.budget,
     region: parsed.region,
+    browserMode: parsed.browserMode,
     sort: parsed.sort,
     mode: parsed.mode ?? "compact",
-    ...typeof parsed.timeoutMs === "number" ? { timeoutMs: parsed.timeoutMs } : {},
+    timeoutMs: parsed.timeoutMs ?? DEFAULT_WORKFLOW_TRANSPORT_TIMEOUT_MS,
     outputDir: parsed.outputDir,
     ttlHours: parsed.ttlHours,
     useCookies: parsed.useCookies,
+    challengeAutomationMode: parsed.challengeAutomationMode,
     cookiePolicyOverride: parsed.cookiePolicyOverride
   };
-  const data = typeof parsed.timeoutMs === "number" ? await callDaemon("shopping.run", payload, { timeoutMs: parsed.timeoutMs }) : await callDaemon("shopping.run", payload);
+  const data = await callDaemon("shopping.run", payload, {
+    timeoutMs: deriveShoppingTransportTimeoutMs(payload.timeoutMs)
+  });
   return {
     success: true,
-    message: "Shopping workflow completed.",
+    message: buildWorkflowCompletionMessage("Shopping workflow", data),
     data
   };
 }
 
 // src/cli/commands/product-video.ts
-var requireValue11 = (rawArgs, index, flag) => {
+var requireValue10 = (rawArgs, index, flag) => {
   const value = rawArgs[index + 1];
   if (!value) {
     throw createUsageError(`Missing value for ${flag}`);
@@ -5942,7 +7250,7 @@ var parseProductVideoArgs = (rawArgs) => {
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
     if (arg === "--product-url") {
-      parsed.productUrl = requireValue11(rawArgs, index, "--product-url");
+      parsed.productUrl = requireValue10(rawArgs, index, "--product-url");
       index += 1;
       continue;
     }
@@ -5951,7 +7259,7 @@ var parseProductVideoArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--product-name") {
-      parsed.productName = requireValue11(rawArgs, index, "--product-name");
+      parsed.productName = requireValue10(rawArgs, index, "--product-name");
       index += 1;
       continue;
     }
@@ -5960,7 +7268,7 @@ var parseProductVideoArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--provider-hint") {
-      parsed.providerHint = requireValue11(rawArgs, index, "--provider-hint");
+      parsed.providerHint = requireValue10(rawArgs, index, "--provider-hint");
       index += 1;
       continue;
     }
@@ -5993,7 +7301,7 @@ var parseProductVideoArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--output-dir") {
-      parsed.outputDir = requireValue11(rawArgs, index, "--output-dir");
+      parsed.outputDir = requireValue10(rawArgs, index, "--output-dir");
       index += 1;
       continue;
     }
@@ -6002,7 +7310,7 @@ var parseProductVideoArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--ttl-hours") {
-      parsed.ttlHours = parseNumberFlag(requireValue11(rawArgs, index, "--ttl-hours"), "--ttl-hours", { min: 1, max: 168 });
+      parsed.ttlHours = parseNumberFlag(requireValue10(rawArgs, index, "--ttl-hours"), "--ttl-hours", { min: 1, max: 168 });
       index += 1;
       continue;
     }
@@ -6011,7 +7319,7 @@ var parseProductVideoArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--timeout-ms") {
-      parsed.timeoutMs = parseNumberFlag(requireValue11(rawArgs, index, "--timeout-ms"), "--timeout-ms", { min: 1 });
+      parsed.timeoutMs = parseNumberFlag(requireValue10(rawArgs, index, "--timeout-ms"), "--timeout-ms", { min: 1 });
       index += 1;
       continue;
     }
@@ -6027,8 +7335,25 @@ var parseProductVideoArgs = (rawArgs) => {
       parsed.useCookies = parseBoolean3(arg.split("=", 2)[1] ?? "", "--use-cookies");
       continue;
     }
+    if (arg === "--challenge-automation-mode") {
+      const value = requireValue10(rawArgs, index, "--challenge-automation-mode");
+      if (!isChallengeAutomationMode(value)) {
+        throw createUsageError(`Invalid --challenge-automation-mode: ${value}`);
+      }
+      parsed.challengeAutomationMode = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--challenge-automation-mode=")) {
+      const value = arg.split("=", 2)[1] ?? "";
+      if (!isChallengeAutomationMode(value)) {
+        throw createUsageError(`Invalid --challenge-automation-mode: ${value}`);
+      }
+      parsed.challengeAutomationMode = value;
+      continue;
+    }
     if (arg === "--cookie-policy-override" || arg === "--cookie-policy") {
-      const value = requireValue11(rawArgs, index, arg).toLowerCase();
+      const value = requireValue10(rawArgs, index, arg).toLowerCase();
       if (!COOKIE_POLICY_VALUES3.has(value)) {
         throw createUsageError(`Invalid ${arg}: ${value}`);
       }
@@ -6056,7 +7381,7 @@ async function runProductVideoCommand(args) {
   if (!parsed.productUrl && !parsed.productName) {
     throw createUsageError("Missing --product-url or --product-name");
   }
-  const timeoutMs = parsed.timeoutMs ?? 12e4;
+  const timeoutMs = parsed.timeoutMs ?? DEFAULT_WORKFLOW_TRANSPORT_TIMEOUT_MS;
   const data = await callDaemon("product.video.run", {
     product_url: parsed.productUrl,
     product_name: parsed.productName,
@@ -6066,12 +7391,14 @@ async function runProductVideoCommand(args) {
     include_copy: parsed.includeCopy,
     output_dir: parsed.outputDir,
     ttl_hours: parsed.ttlHours,
+    timeoutMs,
     useCookies: parsed.useCookies,
+    challengeAutomationMode: parsed.challengeAutomationMode,
     cookiePolicyOverride: parsed.cookiePolicyOverride
-  }, { timeoutMs });
+  });
   return {
     success: true,
-    message: "Product video asset workflow completed.",
+    message: buildWorkflowCompletionMessage("Product video asset workflow", data),
     data
   };
 }
@@ -6079,8 +7406,8 @@ async function runProductVideoCommand(args) {
 // package.json
 var package_default = {
   name: "opendevbrowser",
-  version: "0.0.17",
-  description: "OpenCode plugin for browser automation via CDP with snapshot-refs-actions workflow",
+  version: "0.0.18",
+  description: "Browser automation runtime with snapshot-refs-actions, browser replay screencasts, public read-only desktop observation, and browser-scoped computer-use orchestration",
   type: "module",
   main: "dist/index.js",
   types: "dist/index.d.ts",
@@ -6106,7 +7433,14 @@ var package_default = {
     "playwright",
     "testing",
     "web-scraping",
-    "chrome"
+    "chrome",
+    "annotation",
+    "design-canvas",
+    "screencast",
+    "desktop-observation",
+    "browser-replay",
+    "computer-use",
+    "challenge-automation"
   ],
   license: "MIT",
   repository: {
@@ -6117,24 +7451,11 @@ var package_default = {
     node: ">=18"
   },
   scripts: {
-    build: `tsup src/index.ts src/cli/index.ts --format esm --clean --sourcemap && tsc --emitDeclarationOnly --declaration --declarationMap -p tsconfig.json && node --input-type=module -e "import { copyFileSync, existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-const dist = resolve('dist');
-const pairs = [
-  ['index.js', 'opendevbrowser.js'],
-  ['index.js.map', 'opendevbrowser.js.map'],
-  ['index.d.ts', 'opendevbrowser.d.ts'],
-  ['index.d.ts.map', 'opendevbrowser.d.ts.map'],
-];
-for (const [src, dst] of pairs) {
-  const from = resolve(dist, src);
-  const to = resolve(dist, dst);
-  if (existsSync(from)) copyFileSync(from, to);
-}"`,
-    dev: "tsup src/index.ts src/cli/index.ts --format esm --dts --watch",
+    build: "tsup src/index.ts src/cli/index.ts src/skills/skill-loader.ts --format esm --clean --sourcemap && tsc --emitDeclarationOnly --declaration --declarationMap -p tsconfig.json && node scripts/postbuild-dist.mjs",
+    dev: "tsup src/index.ts src/cli/index.ts src/skills/skill-loader.ts --format esm --dts --watch",
     lint: 'eslint "src/**/*.ts" "tests/**/*.ts"',
     typecheck: "tsc --noEmit -p tsconfig.json",
-    test: `node --input-type=module -e "import { mkdirSync } from 'node:fs'; mkdirSync('coverage/.tmp', { recursive: true });" && vitest run --coverage`,
+    test: "node scripts/run-vitest-coverage.mjs",
     "test:release-gate": "node scripts/release-gate-test-groups.mjs",
     "test:release-gate:g1": "node scripts/release-gate-test-groups.mjs --group 1",
     "test:release-gate:g2": "node scripts/release-gate-test-groups.mjs --group 2",
@@ -6149,10 +7470,11 @@ for (const [src, dst] of pairs) {
     prepack: "npm run version:check && npm run build && npm run extension:build"
   },
   dependencies: {
-    "@opencode-ai/plugin": "^1.2.11",
+    "@opencode-ai/plugin": "^1.2.25",
     "@puppeteer/browsers": "^2.13.0",
     "async-mutex": "^0.5.0",
     "jsonc-parser": "^3.2.0",
+    parse5: "^8.0.0",
     "playwright-core": "^1.58.2",
     typescript: "^5.9.3",
     ws: "^8.19.0",
@@ -6175,6 +7497,29 @@ for (const [src, dst] of pairs) {
 
 // src/cli/index.ts
 var VERSION = typeof package_default.version === "string" ? package_default.version : "0.0.0";
+function resolveUpdateSkillModes(args) {
+  if (args.rawArgs.includes("--no-skills")) {
+    return [];
+  }
+  if (args.rawArgs.includes("--skills-global")) {
+    return ["global"];
+  }
+  if (args.rawArgs.includes("--skills-local")) {
+    return ["local"];
+  }
+  if (args.mode) {
+    return [args.mode];
+  }
+  const installed = findInstalledConfigs();
+  const modes = [];
+  if (installed.global || hasBundledSkillArtifacts("global")) {
+    modes.push("global");
+  }
+  if (installed.local || hasBundledSkillArtifacts("local")) {
+    modes.push("local");
+  }
+  return modes;
+}
 async function promptInstallMode() {
   if (!process.stdin.isTTY) {
     console.log("Non-interactive mode detected. Using global install.");
@@ -6275,6 +7620,7 @@ async function main() {
     const args = parseArgs(process.argv);
     parseSucceeded = true;
     outputFormat = args.outputFormat;
+    setDefaultLogSink(stderrSink);
     const outputOptions = { format: args.outputFormat, quiet: args.quiet };
     const emitResult = (result2, payload) => {
       const suppressOutput = Boolean(
@@ -6310,15 +7656,27 @@ async function main() {
     });
     registerCommand({
       name: "update",
-      description: "Clear cached plugin to trigger reinstall",
+      description: "Clear cached plugin and refresh managed skill packs",
       run: () => {
         const result2 = runUpdate();
-        return { success: result2.success, message: result2.message };
+        const skillModes = result2.success ? resolveUpdateSkillModes(args) : [];
+        const skillResults = result2.success ? skillModes.map((mode) => syncBundledSkills(mode)) : [];
+        const skillMessage = args.rawArgs.includes("--no-skills") ? "Managed skill refresh skipped (--no-skills)." : skillResults.length > 0 ? skillResults.map((entry) => entry.message).join("\n") : result2.success ? "No managed skill packs required refresh." : "";
+        const message = [result2.message, skillMessage].filter(Boolean).join("\n");
+        return {
+          success: result2.success && skillResults.every((entry) => entry.success),
+          message,
+          data: {
+            cacheCleared: result2.cleared,
+            skillModes,
+            skills: skillResults
+          }
+        };
       }
     });
     registerCommand({
       name: "uninstall",
-      description: "Remove plugin from config",
+      description: "Remove plugin from config and clean managed skill packs",
       run: async () => {
         let mode = args.mode;
         if (!mode && !args.noPrompt) {
@@ -6331,12 +7689,22 @@ async function main() {
           return { success: false, message: "Error: Please specify --global or --local for uninstall.", exitCode: EXIT_USAGE };
         }
         const result2 = runUninstall(mode);
-        return { success: result2.success, message: result2.message };
+        const skipSkills = args.rawArgs.includes("--no-skills");
+        const skillsResult = result2.success && !skipSkills ? removeBundledSkills(mode) : void 0;
+        const skillMessage = skipSkills ? "Managed skill cleanup skipped (--no-skills)." : skillsResult?.message ?? "";
+        return {
+          success: result2.success && (skillsResult?.success ?? true),
+          message: [result2.message, skillMessage].filter(Boolean).join("\n"),
+          data: {
+            config: result2,
+            skills: skillsResult
+          }
+        };
       }
     });
     registerCommand({
       name: "install",
-      description: "Install the plugin",
+      description: "Install the plugin and sync bundled skill packs",
       run: async () => {
         const log = (...values) => {
           if (args.quiet) return;
@@ -6351,28 +7719,14 @@ async function main() {
           mode = await promptInstallMode();
         }
         const result2 = mode === "global" ? installGlobal(args.withConfig) : installLocal(args.withConfig);
-        const maybeInstallAutostart = () => {
-          const status = getAutostartStatus();
-          if (!status.supported) {
-            return { status, installed: false, message: `Autostart not supported on ${status.platform}.` };
-          }
-          if (status.installed) {
-            return { status, installed: true, message: "Autostart already installed." };
-          }
-          try {
-            const result3 = installAutostart();
-            return { status: result3, installed: result3.installed, message: `Autostart installed (${result3.platform}).` };
-          } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return { status, installed: false, message };
-          }
-        };
+        const autostart = result2.success ? reconcileInstallAutostart(result2) : void 0;
+        const skillsResult = result2.success && args.skillsMode !== "none" ? syncBundledSkills(args.skillsMode) : void 0;
+        const installSuccess = result2.success && (skillsResult?.success ?? true);
         if (args.outputFormat !== "text") {
           const payload = {
             alreadyInstalled: result2.alreadyInstalled
           };
-          if (result2.success && args.skillsMode !== "none") {
-            const skillsResult = installSkills(args.skillsMode);
+          if (skillsResult) {
             payload.skills = skillsResult;
           }
           if (args.fullInstall && result2.success) {
@@ -6383,20 +7737,15 @@ async function main() {
               payload.extensionError = error instanceof Error ? error.message : String(error);
             }
           }
-          if (result2.success && !result2.alreadyInstalled) {
-            const autostart = maybeInstallAutostart();
-            payload.autostart = autostart.status;
-            if (!autostart.installed) {
-              payload.autostartError = autostart.message;
-            }
+          if (autostart) {
+            Object.assign(payload, createInstallAutostartOutputPayload(autostart));
           }
-          return { success: result2.success, message: result2.message, data: payload };
+          return { success: installSuccess, message: result2.message, data: payload };
         }
         log(result2.message);
         if (args.skillsMode === "none") {
           log("Skill installation skipped (--no-skills).");
-        } else if (result2.success) {
-          const skillsResult = installSkills(args.skillsMode);
+        } else if (skillsResult) {
           if (skillsResult.success) {
             log(skillsResult.message);
           } else {
@@ -6418,21 +7767,24 @@ async function main() {
             warn(`Extension pre-extraction failed: ${message}`);
           }
         }
-        if (result2.success && !result2.alreadyInstalled) {
-          const autostart = maybeInstallAutostart();
-          if (autostart.installed) {
-            log(autostart.message);
-          } else {
-            warn(`Autostart install skipped: ${autostart.message}`);
+        if (autostart) {
+          const autostartMessage = formatAutostartReconciliationMessage(autostart);
+          if (autostartMessage) {
+            if (autostart.autostartAction === "repair_failed") {
+              warn(autostartMessage);
+            } else {
+              log(autostartMessage);
+            }
           }
         }
-        if (result2.success && !result2.alreadyInstalled) {
+        if (installSuccess && !result2.alreadyInstalled) {
           log("\nNext steps:");
           log("  1. Start or restart OpenCode");
-          log("  2. Use opendevbrowser_status to verify the plugin is loaded");
-          log("\nFor help: npx opendevbrowser --help");
+          log(`  2. Read npx opendevbrowser --help and start with ${onboarding_metadata_default.quickStartCommands.promptingGuide}`);
+          log(`  3. Or load ${onboarding_metadata_default.skillName} ${onboarding_metadata_default.skillTopic} directly via ${onboarding_metadata_default.quickStartCommands.skillLoad}`);
+          log("  4. Use opendevbrowser_status to verify the plugin is loaded");
         }
-        return { success: result2.success, message: result2.message };
+        return { success: installSuccess, message: result2.message };
       }
     });
     registerCommand({
@@ -6475,6 +7827,11 @@ async function main() {
       description: "Get daemon or session status",
       run: async () => runStatus(args)
     });
+    registerCommand({
+      name: "session-inspector",
+      description: "Capture a session-first diagnostic summary with relay health and trace proof",
+      run: async () => runSessionInspector(args)
+    });
     registerCommand({
       name: "goto",
       description: "Navigate current session to a URL",
@@ -6490,6 +7847,11 @@ async function main() {
       description: "Capture a snapshot of the active page",
       run: async () => runSnapshot(args)
     });
+    registerCommand({
+      name: "review",
+      description: "Capture a first-class review payload for the active page",
+      run: async () => runReview(args)
+    });
     registerCommand({
       name: "annotate",
       description: "Request interactive annotations via direct or relay transport",
@@ -6550,6 +7912,31 @@ async function main() {
       description: "Scroll an element into view by ref",
       run: async () => runScrollIntoView(args)
     });
+    registerCommand({
+      name: "upload",
+      description: "Upload files to a file input or chooser by ref",
+      run: async () => runUpload(args)
+    });
+    registerCommand({
+      name: "pointer-move",
+      description: "Move the pointer to viewport coordinates",
+      run: async () => runPointerMove(args)
+    });
+    registerCommand({
+      name: "pointer-down",
+      description: "Press a mouse button at viewport coordinates",
+      run: async () => runPointerDown(args)
+    });
+    registerCommand({
+      name: "pointer-up",
+      description: "Release a mouse button at viewport coordinates",
+      run: async () => runPointerUp(args)
+    });
+    registerCommand({
+      name: "pointer-drag",
+      description: "Drag the pointer between two viewport coordinates",
+      run: async () => runPointerDrag(args)
+    });
     registerCommand({
       name: "targets-list",
       description: "List page targets",
@@ -6640,6 +8027,21 @@ async function main() {
       description: "Capture a screenshot",
       run: async () => runScreenshot(args)
     });
+    registerCommand({
+      name: "screencast-start",
+      description: "Start a browser replay screencast capture",
+      run: async () => runScreencastStart(args)
+    });
+    registerCommand({
+      name: "screencast-stop",
+      description: "Stop a browser replay screencast capture",
+      run: async () => runScreencastStop(args)
+    });
+    registerCommand({
+      name: "dialog",
+      description: "Inspect or handle a JavaScript dialog",
+      run: async () => runDialog(args)
+    });
     registerCommand({
       name: "console-poll",
       description: "Poll console events",
@@ -6655,6 +8057,36 @@ async function main() {
       description: "Capture page + console + network + exception diagnostics",
       run: async () => runDebugTraceSnapshot(args)
     });
+    registerCommand({
+      name: "desktop-status",
+      description: "Inspect public read-only desktop observation availability",
+      run: async () => runDesktopStatus(args)
+    });
+    registerCommand({
+      name: "desktop-windows",
+      description: "List windows exposed by the public read-only desktop observation plane",
+      run: async () => runDesktopWindows(args)
+    });
+    registerCommand({
+      name: "desktop-active-window",
+      description: "Inspect the active window through the public read-only desktop observation plane",
+      run: async () => runDesktopActiveWindow(args)
+    });
+    registerCommand({
+      name: "desktop-capture-desktop",
+      description: "Capture the current desktop surface through the public read-only desktop observation plane",
+      run: async () => runDesktopCaptureDesktop(args)
+    });
+    registerCommand({
+      name: "desktop-capture-window",
+      description: "Capture a specific window through the public read-only desktop observation plane",
+      run: async () => runDesktopCaptureWindow(args)
+    });
+    registerCommand({
+      name: "desktop-accessibility-snapshot",
+      description: "Capture desktop accessibility state through the public read-only desktop observation plane",
+      run: async () => runDesktopAccessibilitySnapshot(args)
+    });
     registerCommand({
       name: "cookie-import",
       description: "Import validated cookies into a session",
@@ -6700,17 +8132,19 @@ async function main() {
     if (exitCode === null) {
       return;
     }
-    process.exit(exitCode);
+    await flushOutputAndExit(exitCode);
+    return;
   } catch (error) {
     const format = outputFormat ?? detectOutputFormat(process.argv);
     const cliError = toCliError(error, parseSucceeded ? EXIT_EXECUTION : EXIT_USAGE);
     emitFatalError(cliError, format);
-    process.exit(cliError.exitCode);
+    await flushOutputAndExit(cliError.exitCode);
+    return;
   }
 }
-main().catch((error) => {
+main().catch(async (error) => {
   const cliError = toCliError(error, EXIT_EXECUTION);
   emitFatalError(cliError, detectOutputFormat(process.argv));
-  process.exit(cliError.exitCode);
+  await flushOutputAndExit(cliError.exitCode);
 });
 //# sourceMappingURL=index.js.map