opendevbrowser 0.0.15 → 0.0.16

package/dist/cli/index.js

@@ -6,9 +6,11 @@ import {
   EXIT_USAGE,
   buildAnnotateResult,
   callDaemon,
+  cleanupExpiredArtifacts,
   createOpenDevBrowserCore,
   createUsageError,
   extractExtension,
+  fetchDaemonStatus,
   fetchDaemonStatusFromMetadata,
   fetchWithTimeout,
   formatErrorPayload,
@@ -20,9 +22,68 @@ import {
   startDaemon,
   toCliError,
   writeFileAtomic
-} from "../chunk-JVBMT2O5.js";
+} from "../chunk-ST7CO5FA.js";
+import "../chunk-7W3SPXIB.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",
+  "rpc"
+];
+var CLI_COMMAND_SET = new Set(CLI_COMMANDS);
 var SHORT_FLAGS = {
   "-g": "--global",
   "-l": "--local",
@@ -85,12 +146,162 @@ 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",
+  "--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",
+  "--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",
+  "--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));
   let commandOverride = null;
   if (args[0] && !args[0].startsWith("-")) {
     const candidate = args[0];
-    if (candidate === "install" || candidate === "update" || candidate === "uninstall" || candidate === "help" || candidate === "version" || candidate === "serve" || candidate === "daemon" || candidate === "native" || candidate === "run" || candidate === "launch" || candidate === "connect" || candidate === "disconnect" || candidate === "status" || candidate === "goto" || candidate === "wait" || candidate === "snapshot" || candidate === "click" || candidate === "hover" || candidate === "press" || candidate === "check" || candidate === "uncheck" || candidate === "type" || candidate === "select" || candidate === "scroll" || candidate === "scroll-into-view" || candidate === "targets-list" || candidate === "target-use" || candidate === "target-new" || candidate === "target-close" || candidate === "page" || candidate === "pages" || candidate === "page-close" || candidate === "dom-html" || candidate === "dom-text" || candidate === "dom-attr" || candidate === "dom-value" || candidate === "dom-visible" || candidate === "dom-enabled" || candidate === "dom-checked" || candidate === "clone-page" || candidate === "clone-component" || candidate === "perf" || candidate === "screenshot" || candidate === "console-poll" || candidate === "network-poll" || candidate === "annotate") {
+    if (CLI_COMMAND_SET.has(candidate)) {
       commandOverride = candidate;
       args = args.slice(1);
     } else {
@@ -179,87 +390,11 @@ function parseArgs(argv) {
   } else if (noPrompt) {
     mode = "global";
   }
-  const validFlags = /* @__PURE__ */ new Set([
-    "--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",
-    "--daemon",
-    "--transport",
-    "--no-extension",
-    "--extension-only",
-    "--extension-legacy",
-    "--wait-for-extension",
-    "--wait-timeout-ms",
-    "--skills-global",
-    "--skills-local",
-    "--no-skills",
-    "--screenshot-mode",
-    "--debug",
-    "--context"
-  ]);
-  const validEqualsFlags = /* @__PURE__ */ new Set([
-    "--output-format",
-    "--transport",
-    "--session-id",
-    "--url",
-    "--screenshot-mode",
-    "--context",
-    "--timeout-ms",
-    "--target-id",
-    "--tab-id"
-  ]);
   for (const arg of args) {
-    if (arg.startsWith("--") && !validFlags.has(arg)) {
+    if (arg.startsWith("--") && !VALID_FLAG_SET.has(arg)) {
       if (arg.includes("=")) {
         const baseFlag = arg.split("=", 2)[0] ?? "";
-        if (validEqualsFlags.has(baseFlag)) {
+        if (VALID_EQUALS_FLAG_SET.has(baseFlag)) {
           continue;
         }
       }
@@ -283,94 +418,6 @@ function parseArgs(argv) {
     rawArgs: args
   };
 }
-function getHelpText() {
-  return `
-OpenDevBrowser CLI - Install and manage the OpenDevBrowser plugin
-
-USAGE:
-  npx opendevbrowser [command] [options]
-
-COMMANDS:
-  install          Install the plugin (default if no command specified)
-  update           Clear cached plugin to trigger reinstall
-  uninstall        Remove plugin from config
-  serve            Start or stop the local daemon
-  daemon           Install/uninstall/status daemon auto-start
-  native           Install/uninstall/status native messaging host
-  run              Execute a JSON script in a single process
-  launch           Launch a managed browser session via daemon
-  connect          Connect to an existing browser via daemon
-  disconnect       Disconnect a daemon session
-  status           Get daemon status (or session status with --session-id)
-  goto             Navigate current session to a URL
-  wait             Wait for load or a ref to appear
-  snapshot         Capture a snapshot of the active page
-  click            Click an element by ref
-  hover            Hover an element by ref
-  press            Press a keyboard key
-  check            Check a checkbox by ref
-  uncheck          Uncheck a checkbox by ref
-  type             Type into an element by ref
-  select           Select values in a select by ref
-  scroll           Scroll the page or element by ref
-  scroll-into-view Scroll an element into view by ref
-  targets-list     List page targets
-  target-use       Focus a target by id
-  target-new       Open a new target
-  target-close     Close a target by id
-  page             Open or focus a named page
-  pages            List named pages
-  page-close       Close a named page
-  dom-html         Capture HTML for a ref
-  dom-text         Capture text for a ref
-  dom-attr         Capture attribute value for a ref
-  dom-value        Capture input value for a ref
-  dom-visible      Check visibility for a ref
-  dom-enabled      Check enabled state for a ref
-  dom-checked      Check checked state for a ref
-  clone-page       Clone the active page to React
-  clone-component  Clone a component by ref
-  perf             Capture performance metrics
-  screenshot       Capture a screenshot
-  console-poll     Poll console events
-  network-poll     Poll network events
-  annotate         Request interactive annotations (direct or relay)
-  help             Show this help message
-  version          Show version
-
-ALIASES:
-  --update, -u     Same as update
-  --uninstall      Same as uninstall
-  --help, -h       Same as help
-  --version, -v    Same as version
-
-INSTALL OPTIONS:
-  --global, -g     Install to ~/.config/opencode/opencode.json
-  --local, -l      Install to ./opencode.json (project-local)
-  --with-config    Also create opendevbrowser.jsonc with defaults
-  --full, -f       Create config and pre-extract extension assets
-  --no-prompt      Skip prompts, use defaults (global install)
-  --no-interactive Alias of --no-prompt
-  --quiet          Suppress non-error output
-  --output-format  Output format: text (default), json, stream-json
-  --transport      Transport: relay (default) or native
-  --skills-global  Install bundled skills to ~/.config/opencode/skill (default)
-  --skills-local   Install bundled skills to ./.opencode/skill
-  --no-skills      Skip installing bundled skills
-
-EXAMPLES:
-  npx opendevbrowser              # Interactive install
-  npx opendevbrowser --global     # Global install
-  npx opendevbrowser --local      # Project install
-  npx opendevbrowser --full       # Install + config + extension assets
-  npx opendevbrowser -g --with-config  # Global + config file
-  npx opendevbrowser --skills-local   # Install skills locally
-  npx opendevbrowser --no-skills      # Skip skill installation
-  npx opendevbrowser --update     # Update plugin
-  npx opendevbrowser --uninstall --global  # Remove from global config
-  npx opendevbrowser native install <extension-id>  # Install native host
-`.trim();
-}
 function detectOutputFormat(argv) {
   const args = expandShortFlags(argv.slice(2));
   try {
@@ -388,6 +435,374 @@ function registerCommand(definition) {
 function getCommand(name) {
   return registry.get(name);
 }
+function listCommands() {
+  return Array.from(registry.values());
+}
+
+// src/cli/help.ts
+var LABEL_WIDTH = 42;
+var EXPECTED_TOOL_COUNT = 48;
+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: "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 HELP_FLAG_GROUPS = [
+  {
+    title: "Install/Global Flags",
+    summary: "Control installation scope and setup behavior.",
+    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: "--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: "--no-prompt", description: "Run non-interactively using defaults." },
+      { flag: "--no-interactive", description: "Alias of --no-prompt." },
+      { flag: "--quiet", description: "Suppress non-error text output." },
+      { flag: "--skills-global", description: "Install bundled skills into global agent directories." },
+      { flag: "--skills-local", description: "Install bundled skills into local project agent directories." },
+      { flag: "--no-skills", description: "Skip bundled skill installation." }
+    ]
+  },
+  {
+    title: "Help/Output Flags",
+    summary: "Inspect help/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: "Annotation transport: relay (default) or native." }
+    ]
+  },
+  {
+    title: "Daemon/Session/Launch Flags",
+    summary: "Control daemon binding, connect, and launch behavior.",
+    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: "--cdp-port", description: "CDP port for host/port connect mode." },
+      { flag: "--headless", description: "Launch managed browser in headless mode." },
+      { 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: "--start-url", description: "Open this URL immediately after launch." },
+      { 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: "--wait-timeout-ms", description: "Handshake wait timeout in milliseconds." }
+    ]
+  },
+  {
+    title: "Navigation/Interaction/Diagnostics Flags",
+    summary: "Command-specific flags for page actions 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, rpc, and macro-resolve)." },
+      { flag: "--ref", description: "Snapshot ref id for element-targeted commands." },
+      { 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: "--values", description: "CSV values for select 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: "--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: "--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: "--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: crop, full, or none." },
+      { flag: "--debug", description: "Enable debug-level annotation capture extras." },
+      { flag: "--context", description: "Free-form annotation context for reviewers/agents." }
+    ]
+  },
+  {
+    title: "Macro/Provider/Power Flags",
+    summary: "Workflow filters, provider selectors, and unsafe RPC options.",
+    flags: [
+      { flag: "--expression", description: "Macro expression to resolve/execute." },
+      { 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: "--params", description: "Inline JSON params for rpc command." },
+      { flag: "--params-file", description: "Path to JSON params file for rpc command." },
+      { flag: "--unsafe-internal", description: "Required safety gate for 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: "--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: "--budget", description: "Budget filter for shopping workflows." },
+      { flag: "--region", description: "Region/country hint for provider selection." },
+      { 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: "--provider-hint", description: "Provider hint override for product workflows." },
+      { flag: "--include-screenshots", description: "Include screenshots in product presentation output." },
+      { 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: "--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_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_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: "opendevbrowser --help", description: "Always safe first command for quick discovery." }
+];
+function formatRows(rows) {
+  return rows.map((row) => `  ${row.label.padEnd(LABEL_WIDTH)} ${row.description}`).join("\n");
+}
+function getCommandDescriptions() {
+  const descriptions = /* @__PURE__ */ new Map();
+  for (const definition of listCommands()) {
+    descriptions.set(definition.name, definition.description);
+  }
+  return descriptions;
+}
+function assertCommandCoverage(commandDescriptions) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const group of HELP_COMMAND_GROUPS) {
+    for (const command of group.commands) {
+      if (!COMMAND_SET.has(command)) {
+        throw new Error(`Help references unknown CLI command: ${command}`);
+      }
+      if (!commandDescriptions.has(command)) {
+        throw new Error(`Help references unregistered CLI command: ${command}`);
+      }
+      if (seen.has(command)) {
+        throw new Error(`Help command appears multiple times: ${command}`);
+      }
+      seen.add(command);
+    }
+  }
+  if (seen.size !== CLI_COMMANDS.length) {
+    const missing = CLI_COMMANDS.filter((command) => !seen.has(command));
+    throw new Error(`Help command coverage mismatch; missing: ${missing.join(", ")}`);
+  }
+}
+function assertFlagCoverage() {
+  const seen = /* @__PURE__ */ new Set();
+  for (const group of HELP_FLAG_GROUPS) {
+    for (const entry of group.flags) {
+      if (!FLAG_SET.has(entry.flag)) {
+        throw new Error(`Help references unknown CLI flag: ${entry.flag}`);
+      }
+      if (seen.has(entry.flag)) {
+        throw new Error(`Help flag appears multiple times: ${entry.flag}`);
+      }
+      seen.add(entry.flag);
+    }
+  }
+  if (seen.size !== VALID_FLAGS.length) {
+    const missing = VALID_FLAGS.filter((flag) => !seen.has(flag));
+    throw new Error(`Help flag coverage mismatch; missing: ${missing.join(", ")}`);
+  }
+}
+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 (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}`);
+    }
+    seen.add(entry.name);
+  }
+}
+function formatCommandGroups(commandDescriptions) {
+  return HELP_COMMAND_GROUPS.map((group) => {
+    const rows = group.commands.map((command) => ({
+      label: command,
+      description: commandDescriptions.get(command) ?? "Missing command description."
+    }));
+    return `${group.title}: ${group.summary}
+${formatRows(rows)}`;
+  }).join("\n\n");
+}
+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
+    }));
+    return `${group.title}: ${group.summary}
+${formatRows(rows)}`;
+  }).join("\n\n");
+}
+function formatToolEntries() {
+  return formatRows(HELP_TOOL_ENTRIES.map((entry) => ({
+    label: entry.name,
+    description: entry.description
+  })));
+}
+function formatReferenceEntries() {
+  return formatRows(HELP_REFERENCE_ENTRIES.map((entry) => ({
+    label: entry.label,
+    description: entry.description
+  })));
+}
+function getHelpText() {
+  const commandDescriptions = getCommandDescriptions();
+  assertCommandCoverage(commandDescriptions);
+  assertFlagCoverage();
+  assertToolCoverage();
+  return [
+    "OpenDevBrowser CLI",
+    "",
+    "Usage:",
+    "  npx opendevbrowser <command> [options]",
+    "",
+    `Command Inventory (all ${CLI_COMMANDS.length} commands):`,
+    formatCommandGroups(commandDescriptions),
+    "",
+    "Flag Inventory (all supported flags):",
+    formatFlagGroups(),
+    "",
+    `Tool Inventory (all ${EXPECTED_TOOL_COUNT} opendevbrowser_* tools):`,
+    formatToolEntries(),
+    "",
+    "Reference Pointers:",
+    formatReferenceEntries()
+  ].join("\n");
+}
 
 // src/cli/installers/global.ts
 import * as fs3 from "fs";
@@ -504,7 +919,7 @@ function buildConfigTemplate(relayToken, daemonToken) {
   "skills": {
     "nudge": {
       "enabled": true,
-      "keywords": ["login", "form", "extract"],
+      "keywords": ["quick start", "getting started", "launch", "connect", "setup"],
       "maxAgeMs": 60000
     }
   },
@@ -655,6 +1070,7 @@ 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;
@@ -697,33 +1113,108 @@ function getGlobalSkillDir() {
 function getLocalSkillDir() {
   return path3.join(process.cwd(), ".opencode", SKILL_DIR_NAME);
 }
+function getCodexHomeDir() {
+  return process.env.CODEX_HOME || path3.join(os3.homedir(), ".codex");
+}
+function getClaudeCodeHomeDir() {
+  return process.env.CLAUDECODE_HOME || process.env.CLAUDE_HOME || path3.join(os3.homedir(), ".claude");
+}
+function getAmpHomeDir() {
+  return process.env.AMPCLI_HOME || process.env.AMP_CLI_HOME || process.env.AMP_HOME || path3.join(os3.homedir(), ".amp");
+}
+function dedupeTargets(targets) {
+  const deduped = /* @__PURE__ */ new Map();
+  for (const target of targets) {
+    const key = path3.resolve(target.dir);
+    const existing = deduped.get(key);
+    if (existing) {
+      if (!existing.agents.includes(target.agent)) {
+        existing.agents.push(target.agent);
+      }
+      continue;
+    }
+    deduped.set(key, { agents: [target.agent], dir: target.dir });
+  }
+  return Array.from(deduped.values());
+}
+function getGlobalSkillTargets() {
+  const claudeSkillsDir = path3.join(getClaudeCodeHomeDir(), SKILLS_DIR_NAME);
+  const ampSkillsDir = path3.join(getAmpHomeDir(), SKILLS_DIR_NAME);
+  return dedupeTargets([
+    { agent: "opencode", dir: getGlobalSkillDir() },
+    { agent: "codex", dir: path3.join(getCodexHomeDir(), SKILLS_DIR_NAME) },
+    { agent: "claudecode", dir: claudeSkillsDir },
+    { agent: "claude", dir: claudeSkillsDir },
+    { agent: "ampcli", dir: ampSkillsDir },
+    { agent: "amp", dir: ampSkillsDir }
+  ]);
+}
+function getLocalSkillTargets() {
+  const localClaudeSkillsDir = path3.join(process.cwd(), ".claude", SKILLS_DIR_NAME);
+  const localAmpSkillsDir = path3.join(process.cwd(), ".amp", SKILLS_DIR_NAME);
+  return dedupeTargets([
+    { agent: "opencode", dir: getLocalSkillDir() },
+    { agent: "codex", dir: path3.join(process.cwd(), ".codex", SKILLS_DIR_NAME) },
+    { agent: "claudecode", dir: localClaudeSkillsDir },
+    { agent: "claude", dir: localClaudeSkillsDir },
+    { agent: "ampcli", dir: localAmpSkillsDir },
+    { agent: "amp", dir: localAmpSkillsDir }
+  ]);
+}
 
 // src/cli/installers/skills.ts
 function installSkills(mode) {
-  const targetDir = mode === "global" ? getGlobalSkillDir() : getLocalSkillDir();
-  const installed = [];
-  const skipped = [];
+  const targets = mode === "global" ? getGlobalSkillTargets() : getLocalSkillTargets();
+  const targetResults = [];
   try {
     const sourceDir = getBundledSkillsDir();
     const entries = fs6.readdirSync(sourceDir, { withFileTypes: true });
-    ensureDir(targetDir);
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const skillName = entry.name;
-      const sourcePath = path4.join(sourceDir, skillName);
-      const targetPath = path4.join(targetDir, skillName);
-      if (fs6.existsSync(targetPath)) {
-        skipped.push(skillName);
-        continue;
+    for (const target of targets) {
+      const installed2 = [];
+      const skipped2 = [];
+      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;
+          }
+          fs6.cpSync(sourcePath, targetPath, { recursive: true });
+          installed2.push(skillName);
+        }
+        targetResults.push({
+          agents: target.agents,
+          targetDir: target.dir,
+          installed: installed2,
+          skipped: skipped2,
+          success: true
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        targetResults.push({
+          agents: target.agents,
+          targetDir: target.dir,
+          installed: installed2,
+          skipped: skipped2,
+          success: false,
+          error: message
+        });
       }
-      fs6.cpSync(sourcePath, targetPath, { recursive: true });
-      installed.push(skillName);
     }
-    const summary = `Skills ${mode} install: ${installed.length} installed${skipped.length ? `, ${skipped.length} skipped` : ""} (${targetDir})`;
+    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: true,
+      success: failures.length === 0,
       message: summary,
-      targetDir,
+      mode,
+      targets: targetResults,
       installed,
       skipped
     };
@@ -732,9 +1223,10 @@ function installSkills(mode) {
     return {
       success: false,
       message: `Failed to install skills (${mode}): ${message}`,
-      targetDir,
-      installed,
-      skipped
+      mode,
+      targets: targetResults,
+      installed: targetResults.flatMap((result) => result.installed),
+      skipped: targetResults.flatMap((result) => result.skipped)
     };
   }
 }
@@ -866,6 +1358,9 @@ function findInstalledConfigs() {
   return { global, local };
 }
 
+// src/cli/commands/serve.ts
+import { spawnSync } from "child_process";
+
 // src/cli/utils/parse.ts
 function parseNumberFlag(value, flag, options = {}) {
   const parsed = Number(value);
@@ -1175,7 +1670,7 @@ function discoverExtensionId() {
             return { extensionId: match.id, matchedBy: match.matchedBy };
           }
           if (!nameFallback) {
-            nameFallback = match;
+            nameFallback = { id: match.id, matchedBy: "name" };
           }
         }
         if (!commandFallback) {
@@ -1259,6 +1754,19 @@ async function runNativeCommand(args) {
 
 // src/cli/commands/serve.ts
 var daemonHandle = null;
+var PS_MAX_BUFFER = 8 * 1024 * 1024;
+function resolveTokenCandidates(requestedToken, metadataToken, configToken) {
+  return Array.from(new Set([requestedToken, metadataToken, configToken].filter((token) => typeof token === "string" && token.trim().length > 0)));
+}
+async function resolveExistingDaemon(port, tokens) {
+  for (const token of tokens) {
+    const status = await fetchDaemonStatus(port, token);
+    if (status?.ok) {
+      return { token, status };
+    }
+  }
+  return null;
+}
 function parseServeArgs(rawArgs) {
   const parsed = { stop: false };
   for (let i = 0; i < rawArgs.length; i += 1) {
@@ -1304,11 +1812,64 @@ function parseServeArgs(rawArgs) {
   }
   return parsed;
 }
+function listServeProcessPids() {
+  const result = spawnSync("ps", ["-ax", "-o", "pid=,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];
+}
+function terminateProcess(pid) {
+  if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid || pid === process.ppid) {
+    return false;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    return false;
+  }
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {
+  }
+  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;
+    }
+  }
+  return cleaned;
+}
 async function runServe(args) {
   const serveArgs = parseServeArgs(args.rawArgs);
   if (serveArgs.stop) {
-    const metadata = readDaemonMetadata();
-    if (!metadata) {
+    const metadata2 = readDaemonMetadata();
+    if (!metadata2) {
       if (daemonHandle) {
         await daemonHandle.stop();
         daemonHandle = null;
@@ -1317,9 +1878,9 @@ async function runServe(args) {
       return { success: false, message: "Daemon not running.", exitCode: EXIT_DISCONNECTED };
     }
     try {
-      const response = await fetchWithTimeout(`http://127.0.0.1:${metadata.port}/stop`, {
+      const response = await fetchWithTimeout(`http://127.0.0.1:${metadata2.port}/stop`, {
         method: "POST",
-        headers: { Authorization: `Bearer ${metadata.token}` }
+        headers: { Authorization: `Bearer ${metadata2.token}` }
       });
       if (!response.ok) {
         throw new Error(`Stop failed (${response.status})`);
@@ -1331,6 +1892,29 @@ async function runServe(args) {
     }
   }
   const config = loadGlobalConfig();
+  const requestedPort = serveArgs.port ?? config.daemonPort;
+  const metadata = readDaemonMetadata();
+  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);
+  if (existingDaemon) {
+    const relayPort = existingDaemon.status.relay.port ?? config.relayPort;
+    const staleNote2 = staleCleared > 0 ? ` Cleared ${staleCleared} stale daemon process${staleCleared === 1 ? "" : "es"}.` : "";
+    return {
+      success: true,
+      message: `Daemon already running on 127.0.0.1:${requestedPort} (pid=${existingDaemon.status.pid}, relay ${relayPort}).${staleNote2}`,
+      data: {
+        port: requestedPort,
+        pid: existingDaemon.status.pid,
+        relayPort,
+        alreadyRunning: true,
+        staleDaemonsCleared: staleCleared,
+        relay: existingDaemon.status.relay
+      },
+      exitCode: null
+    };
+  }
   let nativeStatus = getNativeStatusSnapshot();
   let nativeMessage = null;
   if (!nativeStatus.installed) {
@@ -1350,20 +1934,55 @@ async function runServe(args) {
       nativeMessage = "Native host not installed. Set nativeExtensionId in opendevbrowser.jsonc to auto-install.";
     }
   }
-  const handle = await startDaemon({
-    port: serveArgs.port,
-    token: serveArgs.token,
-    config
-  });
+  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")) {
+      const runningDaemon = await resolveExistingDaemon(requestedPort, tokenCandidates);
+      if (runningDaemon) {
+        const relayPort = runningDaemon.status.relay.port ?? config.relayPort;
+        return {
+          success: true,
+          message: `Daemon already running on 127.0.0.1:${requestedPort} (pid=${runningDaemon.status.pid}, relay ${relayPort}).`,
+          data: {
+            port: requestedPort,
+            pid: runningDaemon.status.pid,
+            relayPort,
+            alreadyRunning: true,
+            relay: runningDaemon.status.relay
+          },
+          exitCode: null
+        };
+      }
+      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\`.`,
+        exitCode: EXIT_EXECUTION
+      };
+    }
+    return {
+      success: false,
+      message: `Failed to start daemon: ${message2}`,
+      exitCode: EXIT_EXECUTION
+    };
+  }
   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 message = nativeMessage ? `${baseMessage}
-${nativeMessage}` : baseMessage;
+${nativeMessage}${staleNote}` : `${baseMessage}${staleNote}`;
   return {
     success: true,
     message,
-    data: { port: state.port, pid: state.pid, relayPort: state.relayPort, native: nativeStatus },
+    data: { port: state.port, pid: state.pid, relayPort: state.relayPort, native: nativeStatus, staleDaemonsCleared: staleCleared },
     exitCode: null
   };
 }
@@ -1372,7 +1991,7 @@ ${nativeMessage}` : baseMessage;
 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 resolve3 } from "path";
+import { dirname as dirname5, join as join8, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var MAC_LABEL = "com.opendevbrowser.daemon";
 var WIN_TASK_NAME = "OpenDevBrowser Daemon";
@@ -1390,7 +2009,7 @@ var defaultDeps = () => ({
 });
 var resolveCliPathFromModule = (moduleUrl, exists) => {
   const modulePath = fileURLToPath3(moduleUrl);
-  const candidate = resolve3(dirname5(modulePath), "..", "index.js");
+  const candidate = resolve4(dirname5(modulePath), "..", "index.js");
   if (!exists(candidate)) {
     throw new Error(`CLI entrypoint not found at ${candidate}`);
   }
@@ -1401,7 +2020,7 @@ var resolveCliEntrypoint = (deps = {}) => {
   const exists = resolved.existsSync;
   let cliPath = null;
   if (resolved.argv1) {
-    const candidate = resolve3(resolved.argv1);
+    const candidate = resolve4(resolved.argv1);
     if (exists(candidate)) {
       cliPath = candidate;
     }
@@ -1687,6 +2306,75 @@ async function runDaemonCommand(args) {
   };
 }
 
+// src/cli/commands/artifacts.ts
+import { join as join9, resolve as resolve5 } from "path";
+import { tmpdir } from "os";
+var usageError = () => {
+  throw createUsageError("Usage: opendevbrowser artifacts cleanup --expired-only [--output-dir <path>]");
+};
+var requireValue = (rawArgs, index, flag) => {
+  const value = rawArgs[index + 1];
+  if (!value) {
+    throw createUsageError(`Missing value for ${flag}`);
+  }
+  return value;
+};
+var parseArtifactsArgs = (rawArgs) => {
+  const [candidate, ...rest] = rawArgs;
+  if (candidate !== "cleanup") {
+    usageError();
+  }
+  const subcommand = "cleanup";
+  let expiredOnly = false;
+  let outputDir;
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (arg === "--expired-only") {
+      expiredOnly = true;
+      continue;
+    }
+    if (arg === "--output-dir") {
+      outputDir = requireValue(rest, index, "--output-dir");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--output-dir=")) {
+      const value = arg.split("=", 2)[1];
+      if (!value) {
+        throw createUsageError("Missing value for --output-dir");
+      }
+      outputDir = value;
+      continue;
+    }
+    throw createUsageError(`Unknown artifacts flag: ${arg}`);
+  }
+  if (!expiredOnly) {
+    usageError();
+  }
+  return {
+    subcommand,
+    expiredOnly,
+    outputDir
+  };
+};
+async function runArtifactsCommand(args) {
+  const parsed = parseArtifactsArgs(args.rawArgs);
+  const rootDir = parsed.outputDir ? resolve5(parsed.outputDir) : join9(tmpdir(), "opendevbrowser");
+  const cleaned = await cleanupExpiredArtifacts(rootDir);
+  return {
+    success: true,
+    message: `Artifact cleanup completed. Removed ${cleaned.removed.length} expired run(s).`,
+    data: {
+      rootDir,
+      expiredOnly: parsed.expiredOnly,
+      removed: cleaned.removed,
+      skipped: cleaned.skipped,
+      removedCount: cleaned.removed.length,
+      skippedCount: cleaned.skipped.length
+    }
+  };
+}
+
 // src/cli/commands/run.ts
 import { readFileSync as readFileSync4 } from "fs";
 
@@ -1790,13 +2478,13 @@ function parseRunArgs(rawArgs) {
   return parsed;
 }
 function readScriptFromStdin() {
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve6, reject) => {
     let data = "";
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
-    process.stdin.on("end", () => resolve4(data));
+    process.stdin.on("end", () => resolve6(data));
     process.stdin.on("error", reject);
   });
 }
@@ -1851,6 +2539,14 @@ async function runScriptCommand(args) {
 }
 
 // src/cli/commands/session/launch.ts
+var MIN_LAUNCH_CALL_TIMEOUT_MS = 3e4;
+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) {
@@ -1893,7 +2589,19 @@ function parseLaunchArgs(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 === "--no-extension") {
@@ -1941,10 +2649,15 @@ function parseLaunchArgs(rawArgs) {
   }
   return parsed;
 }
+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);
+}
 async function runSessionLaunch(args) {
   const launchArgs = parseLaunchArgs(args.rawArgs);
+  const launchCallTimeoutMs = deriveLaunchCallTimeoutMs(launchArgs);
   try {
-    const result = await callDaemon("session.launch", launchArgs);
+    const result = await callDaemon("session.launch", launchArgs, { timeoutMs: launchCallTimeoutMs });
     return {
       success: true,
       message: `Session launched: ${result.sessionId}`,
@@ -1966,7 +2679,8 @@ async function runSessionLaunch(args) {
     );
     if (retry) {
       try {
-        const result = await callDaemon("session.launch", { ...launchArgs, waitForExtension: true });
+        const retryArgs = { ...launchArgs, waitForExtension: true };
+        const result = await callDaemon("session.launch", retryArgs, { timeoutMs: deriveLaunchCallTimeoutMs(retryArgs) });
         return {
           success: true,
           message: `Session launched: ${result.sessionId}`,
@@ -1979,11 +2693,12 @@ async function runSessionLaunch(args) {
     const proceedManaged = await promptYesNo("Proceed with a managed session (headed)?", false);
     if (proceedManaged) {
       const useHeadless = await promptYesNo("Run headless instead?", false);
-      const result = await callDaemon("session.launch", {
+      const managedArgs = {
         ...launchArgs,
         noExtension: true,
         headless: useHeadless ? true : false
-      });
+      };
+      const result = await callDaemon("session.launch", managedArgs, { timeoutMs: deriveLaunchCallTimeoutMs(managedArgs) });
       return {
         success: true,
         message: `Session launched: ${result.sessionId}`,
@@ -2007,16 +2722,16 @@ function promptYesNo(question, defaultYes) {
     return Promise.resolve(false);
   }
   const suffix = defaultYes ? " [Y/n] " : " [y/N] ";
-  return new Promise((resolve4) => {
+  return new Promise((resolve6) => {
     process.stdout.write(`${question}${suffix}`);
     process.stdin.setEncoding("utf8");
     process.stdin.once("data", (data) => {
       const input = data.toString().trim().toLowerCase();
       if (!input) {
-        resolve4(defaultYes);
+        resolve6(defaultYes);
         return;
       }
-      resolve4(input === "y" || input === "yes");
+      resolve6(input === "y" || input === "yes");
     });
   });
 }
@@ -2067,6 +2782,10 @@ function parseConnectArgs(rawArgs) {
       parsed.extensionLegacy = true;
       continue;
     }
+    if (arg === "--headless") {
+      parsed.headless = true;
+      continue;
+    }
   }
   return parsed;
 }
@@ -2404,7 +3123,7 @@ async function runSnapshot(args) {
 }
 
 // src/cli/commands/annotate.ts
-var requireValue = (value, flag) => {
+var requireValue2 = (value, flag) => {
   if (!value) throw createUsageError(`Missing value for ${flag}`);
   return value;
 };
@@ -2425,68 +3144,68 @@ var parseAnnotateArgs = (rawArgs) => {
   for (let i = 0; i < rawArgs.length; i += 1) {
     const arg = rawArgs[i];
     if (arg === "--session-id") {
-      const value = requireValue(rawArgs[i + 1], "--session-id");
+      const value = requireValue2(rawArgs[i + 1], "--session-id");
       parsed.sessionId = value;
       i += 1;
       continue;
     }
     if (arg?.startsWith("--session-id=")) {
-      const value = requireValue(arg.split("=", 2)[1], "--session-id");
+      const value = requireValue2(arg.split("=", 2)[1], "--session-id");
       parsed.sessionId = value;
       continue;
     }
     if (arg === "--url") {
-      const value = requireValue(rawArgs[i + 1], "--url");
+      const value = requireValue2(rawArgs[i + 1], "--url");
       parsed.url = value;
       i += 1;
       continue;
     }
     if (arg?.startsWith("--url=")) {
-      const value = requireValue(arg.split("=", 2)[1], "--url");
+      const value = requireValue2(arg.split("=", 2)[1], "--url");
       parsed.url = value;
       continue;
     }
     if (arg === "--screenshot-mode") {
-      const value = requireValue(rawArgs[i + 1], "--screenshot-mode");
+      const value = requireValue2(rawArgs[i + 1], "--screenshot-mode");
       parsed.screenshotMode = requireScreenshotMode(value);
       i += 1;
       continue;
     }
     if (arg?.startsWith("--screenshot-mode=")) {
-      const value = requireValue(arg.split("=", 2)[1], "--screenshot-mode");
+      const value = requireValue2(arg.split("=", 2)[1], "--screenshot-mode");
       parsed.screenshotMode = requireScreenshotMode(value);
       continue;
     }
     if (arg === "--transport") {
-      const value = requireValue(rawArgs[i + 1], "--transport");
+      const value = requireValue2(rawArgs[i + 1], "--transport");
       parsed.transport = requireTransport(value);
       i += 1;
       continue;
     }
     if (arg?.startsWith("--transport=")) {
-      const value = requireValue(arg.split("=", 2)[1], "--transport");
+      const value = requireValue2(arg.split("=", 2)[1], "--transport");
       parsed.transport = requireTransport(value);
       continue;
     }
     if (arg === "--target-id") {
-      const value = requireValue(rawArgs[i + 1], "--target-id");
+      const value = requireValue2(rawArgs[i + 1], "--target-id");
       parsed.targetId = value;
       i += 1;
       continue;
     }
     if (arg?.startsWith("--target-id=")) {
-      const value = requireValue(arg.split("=", 2)[1], "--target-id");
+      const value = requireValue2(arg.split("=", 2)[1], "--target-id");
       parsed.targetId = value;
       continue;
     }
     if (arg === "--tab-id") {
-      const value = requireValue(rawArgs[i + 1], "--tab-id");
+      const value = requireValue2(rawArgs[i + 1], "--tab-id");
       parsed.tabId = parseNumberFlag(value, "--tab-id", { min: 1 });
       i += 1;
       continue;
     }
     if (arg?.startsWith("--tab-id=")) {
-      const value = requireValue(arg.split("=", 2)[1], "--tab-id");
+      const value = requireValue2(arg.split("=", 2)[1], "--tab-id");
       parsed.tabId = parseNumberFlag(value, "--tab-id", { min: 1 });
       continue;
     }
@@ -2495,24 +3214,24 @@ var parseAnnotateArgs = (rawArgs) => {
       continue;
     }
     if (arg === "--context") {
-      const value = requireValue(rawArgs[i + 1], "--context");
+      const value = requireValue2(rawArgs[i + 1], "--context");
       parsed.context = value;
       i += 1;
       continue;
     }
     if (arg?.startsWith("--context=")) {
-      const value = requireValue(arg.split("=", 2)[1], "--context");
+      const value = requireValue2(arg.split("=", 2)[1], "--context");
       parsed.context = value;
       continue;
     }
     if (arg === "--timeout-ms") {
-      const value = requireValue(rawArgs[i + 1], "--timeout-ms");
+      const value = requireValue2(rawArgs[i + 1], "--timeout-ms");
       parsed.timeoutMs = parseNumberFlag(value, "--timeout-ms", { min: 1 });
       i += 1;
       continue;
     }
     if (arg?.startsWith("--timeout-ms=")) {
-      const value = requireValue(arg.split("=", 2)[1], "--timeout-ms");
+      const value = requireValue2(arg.split("=", 2)[1], "--timeout-ms");
       parsed.timeoutMs = parseNumberFlag(value, "--timeout-ms", { min: 1 });
       continue;
     }
@@ -2548,6 +3267,131 @@ async function runAnnotate(args) {
   }
 }
 
+// src/cli/commands/rpc.ts
+import { readFileSync as readFileSync5 } from "fs";
+var requireValue3 = (value, flag) => {
+  if (!value) throw createUsageError(`Missing value for ${flag}`);
+  return value;
+};
+var parseJsonObject = (raw, source) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid JSON";
+    throw createUsageError(`Invalid JSON from ${source}: ${message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw createUsageError(`Invalid JSON from ${source}: expected object`);
+  }
+  return parsed;
+};
+var parseRpcArgs = (rawArgs) => {
+  const parsed = {};
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const arg = rawArgs[i];
+    if (arg === "--unsafe-internal") {
+      parsed.unsafeInternal = true;
+      continue;
+    }
+    if (arg === "--name") {
+      parsed.name = requireValue3(rawArgs[i + 1], "--name");
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--name=")) {
+      parsed.name = requireValue3(arg.split("=", 2)[1], "--name");
+      continue;
+    }
+    if (arg === "--params") {
+      parsed.params = requireValue3(rawArgs[i + 1], "--params");
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--params=")) {
+      parsed.params = requireValue3(arg.split("=", 2)[1], "--params");
+      continue;
+    }
+    if (arg === "--params-file") {
+      parsed.paramsFile = requireValue3(rawArgs[i + 1], "--params-file");
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--params-file=")) {
+      parsed.paramsFile = requireValue3(arg.split("=", 2)[1], "--params-file");
+      continue;
+    }
+    if (arg === "--timeout-ms") {
+      const value = requireValue3(rawArgs[i + 1], "--timeout-ms");
+      parsed.timeoutMs = parseNumberFlag(value, "--timeout-ms", { min: 1 });
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--timeout-ms=")) {
+      const value = requireValue3(arg.split("=", 2)[1], "--timeout-ms");
+      parsed.timeoutMs = parseNumberFlag(value, "--timeout-ms", { min: 1 });
+      continue;
+    }
+  }
+  return parsed;
+};
+var resolveRpcParams = (rpcArgs) => {
+  const hasParamsArg = typeof rpcArgs.params === "string";
+  const hasParamsFile = typeof rpcArgs.paramsFile === "string";
+  const inputCount = Number(hasParamsArg) + Number(hasParamsFile);
+  if (inputCount > 1) {
+    throw createUsageError("Provide only one params source: --params or --params-file.");
+  }
+  if (hasParamsArg) {
+    return parseJsonObject(rpcArgs.params ?? "", "--params");
+  }
+  if (hasParamsFile) {
+    let raw = "";
+    try {
+      raw = readFileSync5(rpcArgs.paramsFile ?? "", "utf8");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unable to read file";
+      throw createUsageError(`Invalid --params-file: ${message}`);
+    }
+    if (!raw.trim()) {
+      throw createUsageError("Invalid JSON from --params-file: empty input");
+    }
+    return parseJsonObject(raw, "--params-file");
+  }
+  return {};
+};
+async function runRpc(args) {
+  const rpcArgs = parseRpcArgs(args.rawArgs);
+  if (!rpcArgs.unsafeInternal) {
+    throw createUsageError(
+      "Missing --unsafe-internal. rpc is a power-user command that executes internal daemon commands and can mutate session state."
+    );
+  }
+  if (!rpcArgs.name) {
+    throw createUsageError("Missing --name");
+  }
+  const params = resolveRpcParams(rpcArgs);
+  const client = new DaemonClient({ autoRenew: true });
+  try {
+    const result = await client.call(rpcArgs.name, params, { timeoutMs: rpcArgs.timeoutMs });
+    if (args.outputFormat === "text") {
+      const output = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+      return { success: true, message: output };
+    }
+    return {
+      success: true,
+      message: `RPC executed: ${rpcArgs.name}`,
+      data: {
+        name: rpcArgs.name,
+        result
+      }
+    };
+  } finally {
+    await client.releaseBinding().catch(() => {
+    });
+  }
+}
+
 // src/cli/commands/interact/click.ts
 function parseClickArgs(rawArgs) {
   const parsed = {};
@@ -3592,39 +4436,49 @@ async function runPerf(args) {
 }
 
 // src/cli/commands/devtools/screenshot.ts
+var requireValue4 = (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") {
-      const value = rawArgs[i + 1];
-      if (!value) throw createUsageError("Missing value for --session-id");
-      parsed.sessionId = value;
+      parsed.sessionId = requireValue4(rawArgs[i + 1], "--session-id");
       i += 1;
       continue;
     }
     if (arg?.startsWith("--session-id=")) {
-      parsed.sessionId = arg.split("=", 2)[1];
+      parsed.sessionId = requireValue4(arg.split("=", 2)[1], "--session-id");
       continue;
     }
     if (arg === "--path") {
-      const value = rawArgs[i + 1];
-      if (!value) throw createUsageError("Missing value for --path");
-      parsed.path = value;
+      parsed.path = requireValue4(rawArgs[i + 1], "--path");
       i += 1;
       continue;
     }
     if (arg?.startsWith("--path=")) {
-      parsed.path = arg.split("=", 2)[1];
+      parsed.path = requireValue4(arg.split("=", 2)[1], "--path");
+      continue;
+    }
+    if (arg === "--timeout-ms") {
+      parsed.timeoutMs = parseNumberFlag(requireValue4(rawArgs[i + 1], "--timeout-ms"), "--timeout-ms", { min: 1 });
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--timeout-ms=")) {
+      parsed.timeoutMs = parseNumberFlag(requireValue4(arg.split("=", 2)[1], "--timeout-ms"), "--timeout-ms", { min: 1 });
       continue;
     }
   }
   return parsed;
 }
 async function runScreenshot(args) {
-  const { sessionId, path: path8 } = parseScreenshotArgs(args.rawArgs);
+  const { sessionId, path: path8, timeoutMs } = parseScreenshotArgs(args.rawArgs);
   if (!sessionId) throw createUsageError("Missing --session-id");
-  const result = await callDaemon("page.screenshot", { sessionId, path: path8 });
+  const params = { sessionId, path: path8 };
+  const result = typeof timeoutMs === "number" ? await callDaemon("page.screenshot", params, { timeoutMs }) : await callDaemon("page.screenshot", params);
   return { success: true, message: "Screenshot captured.", data: result };
 }
 
@@ -3724,23 +4578,1062 @@ async function runNetworkPoll(args) {
   return { success: true, message: "Network events polled.", data: result };
 }
 
-// src/cli/index.ts
-var VERSION = "0.1.0";
-async function promptInstallMode() {
-  if (!process.stdin.isTTY) {
-    console.log("Non-interactive mode detected. Using global install.");
-    return "global";
-  }
-  return new Promise((resolve4) => {
-    console.log("\nWhere would you like to install opendevbrowser?\n");
-    console.log("  1. Global (~/.config/opencode/opencode.json)");
-    console.log("  2. Local (./opencode.json in this project)\n");
-    process.stdout.write("Enter choice [1]: ");
-    process.stdin.setEncoding("utf8");
-    let resolved = false;
-    let timeoutId = null;
-    const cleanup = () => {
-      if (timeoutId !== null) {
+// src/cli/commands/devtools/debug-trace-snapshot.ts
+function parseDebugTraceSnapshotArgs(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 === "--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 runDebugTraceSnapshot(args) {
+  const parsed = parseDebugTraceSnapshotArgs(args.rawArgs);
+  if (!parsed.sessionId) {
+    throw createUsageError("Missing --session-id");
+  }
+  const result = await callDaemon("devtools.debugTraceSnapshot", {
+    sessionId: parsed.sessionId,
+    sinceConsoleSeq: parsed.sinceConsoleSeq,
+    sinceNetworkSeq: parsed.sinceNetworkSeq,
+    sinceExceptionSeq: parsed.sinceExceptionSeq,
+    max: parsed.max,
+    requestId: parsed.requestId
+  });
+  return {
+    success: true,
+    message: "Debug trace snapshot captured.",
+    data: result
+  };
+}
+
+// src/cli/commands/session/cookie-import.ts
+import { readFileSync as readFileSync6 } from "fs";
+var requireValue5 = (value, flag) => {
+  if (!value) {
+    throw createUsageError(`Missing value for ${flag}`);
+  }
+  return value;
+};
+var parseStrictValue = (value, flag) => {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true") return true;
+  if (normalized === "false") return false;
+  throw createUsageError(`Invalid ${flag}: ${value}`);
+};
+var parseCookieImportArgs = (rawArgs) => {
+  const parsed = {};
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === "--session-id") {
+      parsed.sessionId = requireValue5(rawArgs[index + 1], "--session-id");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--session-id=")) {
+      parsed.sessionId = requireValue5(arg.split("=", 2)[1], "--session-id");
+      continue;
+    }
+    if (arg === "--cookies") {
+      parsed.cookies = requireValue5(rawArgs[index + 1], "--cookies");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--cookies=")) {
+      parsed.cookies = requireValue5(arg.split("=", 2)[1], "--cookies");
+      continue;
+    }
+    if (arg === "--cookies-file") {
+      parsed.cookiesFile = requireValue5(rawArgs[index + 1], "--cookies-file");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--cookies-file=")) {
+      parsed.cookiesFile = requireValue5(arg.split("=", 2)[1], "--cookies-file");
+      continue;
+    }
+    if (arg === "--strict") {
+      parsed.strict = true;
+      continue;
+    }
+    if (arg?.startsWith("--strict=")) {
+      parsed.strict = parseStrictValue(requireValue5(arg.split("=", 2)[1], "--strict"), "--strict");
+      continue;
+    }
+    if (arg === "--request-id") {
+      parsed.requestId = requireValue5(rawArgs[index + 1], "--request-id");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--request-id=")) {
+      parsed.requestId = requireValue5(arg.split("=", 2)[1], "--request-id");
+      continue;
+    }
+  }
+  return parsed;
+};
+var parseCookiesJson = (raw, source) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid JSON";
+    throw createUsageError(`Invalid JSON from ${source}: ${message}`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw createUsageError(`Invalid JSON from ${source}: expected array`);
+  }
+  const cookies = [];
+  for (const entry of parsed) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw createUsageError(`Invalid JSON from ${source}: expected cookie object entries`);
+    }
+    const cookie = entry;
+    if (typeof cookie.name !== "string" || typeof cookie.value !== "string") {
+      throw createUsageError(`Invalid JSON from ${source}: each cookie requires string name and value`);
+    }
+    if (typeof cookie.sameSite !== "undefined" && cookie.sameSite !== "Strict" && cookie.sameSite !== "Lax" && cookie.sameSite !== "None") {
+      throw createUsageError(`Invalid JSON from ${source}: sameSite must be Strict, Lax, or None`);
+    }
+    cookies.push({
+      name: cookie.name,
+      value: cookie.value,
+      ...typeof cookie.url === "string" ? { url: cookie.url } : {},
+      ...typeof cookie.domain === "string" ? { domain: cookie.domain } : {},
+      ...typeof cookie.path === "string" ? { path: cookie.path } : {},
+      ...typeof cookie.expires === "number" ? { expires: cookie.expires } : {},
+      ...typeof cookie.httpOnly === "boolean" ? { httpOnly: cookie.httpOnly } : {},
+      ...typeof cookie.secure === "boolean" ? { secure: cookie.secure } : {},
+      ...cookie.sameSite ? { sameSite: cookie.sameSite } : {}
+    });
+  }
+  return cookies;
+};
+var resolveCookies = (parsed) => {
+  const hasInline = typeof parsed.cookies === "string";
+  const hasFile = typeof parsed.cookiesFile === "string";
+  if (!hasInline && !hasFile) {
+    throw createUsageError("Missing --cookies or --cookies-file");
+  }
+  if (hasInline && hasFile) {
+    throw createUsageError("Provide only one cookies source: --cookies or --cookies-file.");
+  }
+  if (hasInline) {
+    return parseCookiesJson(parsed.cookies ?? "", "--cookies");
+  }
+  let raw = "";
+  try {
+    raw = readFileSync6(parsed.cookiesFile ?? "", "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unable to read file";
+    throw createUsageError(`Invalid --cookies-file: ${message}`);
+  }
+  if (!raw.trim()) {
+    throw createUsageError("Invalid JSON from --cookies-file: empty input");
+  }
+  return parseCookiesJson(raw, "--cookies-file");
+};
+async function runCookieImport(args) {
+  const parsed = parseCookieImportArgs(args.rawArgs);
+  if (!parsed.sessionId) {
+    throw createUsageError("Missing --session-id");
+  }
+  const cookies = resolveCookies(parsed);
+  const result = await callDaemon("session.cookieImport", {
+    sessionId: parsed.sessionId,
+    cookies,
+    strict: parsed.strict ?? true,
+    requestId: parsed.requestId
+  });
+  const imported = typeof result.imported === "number" ? result.imported : cookies.length;
+  return {
+    success: true,
+    message: `Cookies imported: ${imported}`,
+    data: result
+  };
+}
+
+// src/cli/commands/session/cookie-list.ts
+var requireValue6 = (value, flag) => {
+  if (!value) {
+    throw createUsageError(`Missing value for ${flag}`);
+  }
+  return value;
+};
+var normalizeCookieUrls = (values) => {
+  const normalized = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      continue;
+    }
+    let parsedUrl;
+    try {
+      parsedUrl = new URL(trimmed);
+    } catch {
+      throw createUsageError(`Invalid --url value: ${trimmed}`);
+    }
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+      throw createUsageError(`Invalid --url protocol: ${trimmed}`);
+    }
+    const normalizedUrl = parsedUrl.toString();
+    if (seen.has(normalizedUrl)) {
+      continue;
+    }
+    seen.add(normalizedUrl);
+    normalized.push(normalizedUrl);
+  }
+  return normalized;
+};
+var parseCookieListArgs = (rawArgs) => {
+  const parsed = { urls: [] };
+  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");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--session-id=")) {
+      parsed.sessionId = requireValue6(arg.split("=", 2)[1], "--session-id");
+      continue;
+    }
+    if (arg === "--url") {
+      const rawValue = requireValue6(rawArgs[index + 1], "--url");
+      parsed.urls.push(...rawValue.split(","));
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--url=")) {
+      parsed.urls.push(...requireValue6(arg.split("=", 2)[1], "--url").split(","));
+      continue;
+    }
+    if (arg === "--request-id") {
+      parsed.requestId = requireValue6(rawArgs[index + 1], "--request-id");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--request-id=")) {
+      parsed.requestId = requireValue6(arg.split("=", 2)[1], "--request-id");
+      continue;
+    }
+  }
+  parsed.urls = normalizeCookieUrls(parsed.urls);
+  return parsed;
+};
+async function runCookieList(args) {
+  const parsed = parseCookieListArgs(args.rawArgs);
+  if (!parsed.sessionId) {
+    throw createUsageError("Missing --session-id");
+  }
+  const result = await callDaemon("session.cookieList", {
+    sessionId: parsed.sessionId,
+    ...parsed.urls.length > 0 ? { urls: parsed.urls } : {},
+    requestId: parsed.requestId
+  });
+  const count = typeof result.count === "number" ? result.count : Array.isArray(result.cookies) ? result.cookies.length : 0;
+  return {
+    success: true,
+    message: `Cookies listed: ${count}`,
+    data: result
+  };
+}
+
+// src/cli/commands/macro-resolve.ts
+var requireValue7 = (value, flag) => {
+  if (!value) {
+    throw createUsageError(`Missing value for ${flag}`);
+  }
+  return value;
+};
+var parseMacroResolveArgs = (rawArgs) => {
+  const parsed = {};
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === "--expression") {
+      parsed.expression = requireValue7(rawArgs[index + 1], "--expression");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--expression=")) {
+      parsed.expression = requireValue7(arg.split("=", 2)[1], "--expression");
+      continue;
+    }
+    if (arg === "--default-provider") {
+      parsed.defaultProvider = requireValue7(rawArgs[index + 1], "--default-provider");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--default-provider=")) {
+      parsed.defaultProvider = requireValue7(arg.split("=", 2)[1], "--default-provider");
+      continue;
+    }
+    if (arg === "--include-catalog") {
+      parsed.includeCatalog = true;
+      continue;
+    }
+    if (arg === "--execute") {
+      parsed.execute = true;
+      continue;
+    }
+    if (arg === "--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(requireValue7(arg.split("=", 2)[1], "--timeout-ms"), "--timeout-ms", { min: 1 });
+      continue;
+    }
+  }
+  return parsed;
+};
+async function runMacroResolve(args) {
+  const parsed = parseMacroResolveArgs(args.rawArgs);
+  if (!parsed.expression) {
+    throw createUsageError("Missing --expression");
+  }
+  const params = {
+    expression: parsed.expression,
+    defaultProvider: parsed.defaultProvider,
+    includeCatalog: parsed.includeCatalog ?? false,
+    execute: parsed.execute ?? false
+  };
+  const result = typeof parsed.timeoutMs === "number" ? await callDaemon("macro.resolve", params, { timeoutMs: parsed.timeoutMs }) : await callDaemon("macro.resolve", params);
+  return {
+    success: true,
+    message: parsed.execute ? "Macro resolved and executed." : "Macro resolved.",
+    data: result
+  };
+}
+
+// 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 requireValue8 = (rawArgs, index, flag) => {
+  const value = rawArgs[index + 1];
+  if (!value) {
+    throw createUsageError(`Missing value for ${flag}`);
+  }
+  return value;
+};
+var parseBoolean = (value, flag) => {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw createUsageError(`Invalid ${flag}: ${value}`);
+};
+var parseSources = (raw) => {
+  const parsed = raw.split(",").map((entry) => entry.trim().toLowerCase()).filter(Boolean);
+  if (parsed.length === 0) {
+    throw createUsageError("--sources requires at least one source");
+  }
+  const deduped = [...new Set(parsed)];
+  for (const source of deduped) {
+    if (!SOURCE_VALUES.has(source)) {
+      throw createUsageError(`Invalid --sources value: ${source}`);
+    }
+  }
+  return deduped;
+};
+var parseResearchRunArgs = (rawArgs) => {
+  const parsed = {};
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === "--topic") {
+      parsed.topic = requireValue8(rawArgs, index, "--topic");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--topic=")) {
+      parsed.topic = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--days") {
+      parsed.days = parseNumberFlag(requireValue8(rawArgs, index, "--days"), "--days", { min: 1, max: 365 });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--days=")) {
+      parsed.days = parseNumberFlag(arg.split("=", 2)[1] ?? "", "--days", { min: 1, max: 365 });
+      continue;
+    }
+    if (arg === "--from") {
+      parsed.from = requireValue8(rawArgs, index, "--from");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--from=")) {
+      parsed.from = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--to") {
+      parsed.to = requireValue8(rawArgs, index, "--to");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--to=")) {
+      parsed.to = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--source-selection") {
+      const value = requireValue8(rawArgs, index, "--source-selection").toLowerCase();
+      if (!SOURCE_SELECTION_VALUES.has(value)) {
+        throw createUsageError(`Invalid --source-selection: ${value}`);
+      }
+      parsed.sourceSelection = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--source-selection=")) {
+      const value = (arg.split("=", 2)[1] ?? "").toLowerCase();
+      if (!SOURCE_SELECTION_VALUES.has(value)) {
+        throw createUsageError(`Invalid --source-selection: ${value}`);
+      }
+      parsed.sourceSelection = value;
+      continue;
+    }
+    if (arg === "--sources") {
+      parsed.sources = parseSources(requireValue8(rawArgs, index, "--sources"));
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--sources=")) {
+      parsed.sources = parseSources(arg.split("=", 2)[1] ?? "");
+      continue;
+    }
+    if (arg === "--mode") {
+      const value = requireValue8(rawArgs, index, "--mode").toLowerCase();
+      if (!MODE_VALUES.has(value)) {
+        throw createUsageError(`Invalid --mode: ${value}`);
+      }
+      parsed.mode = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--mode=")) {
+      const value = (arg.split("=", 2)[1] ?? "").toLowerCase();
+      if (!MODE_VALUES.has(value)) {
+        throw createUsageError(`Invalid --mode: ${value}`);
+      }
+      parsed.mode = value;
+      continue;
+    }
+    if (arg === "--include-engagement") {
+      parsed.includeEngagement = true;
+      continue;
+    }
+    if (arg === "--limit-per-source") {
+      parsed.limitPerSource = parseNumberFlag(requireValue8(rawArgs, index, "--limit-per-source"), "--limit-per-source", { min: 1, max: 100 });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--limit-per-source=")) {
+      parsed.limitPerSource = parseNumberFlag(arg.split("=", 2)[1] ?? "", "--limit-per-source", { min: 1, max: 100 });
+      continue;
+    }
+    if (arg === "--output-dir") {
+      parsed.outputDir = requireValue8(rawArgs, index, "--output-dir");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--output-dir=")) {
+      parsed.outputDir = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--ttl-hours") {
+      parsed.ttlHours = parseNumberFlag(requireValue8(rawArgs, index, "--ttl-hours"), "--ttl-hours", { min: 1, max: 168 });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--ttl-hours=")) {
+      parsed.ttlHours = parseNumberFlag(arg.split("=", 2)[1] ?? "", "--ttl-hours", { min: 1, max: 168 });
+      continue;
+    }
+    if (arg === "--use-cookies") {
+      parsed.useCookies = true;
+      continue;
+    }
+    if (arg?.startsWith("--use-cookies=")) {
+      parsed.useCookies = parseBoolean(arg.split("=", 2)[1] ?? "", "--use-cookies");
+      continue;
+    }
+    if (arg === "--cookie-policy-override" || arg === "--cookie-policy") {
+      const value = requireValue8(rawArgs, index, arg).toLowerCase();
+      if (!COOKIE_POLICY_VALUES.has(value)) {
+        throw createUsageError(`Invalid ${arg}: ${value}`);
+      }
+      parsed.cookiePolicyOverride = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--cookie-policy-override=") || arg?.startsWith("--cookie-policy=")) {
+      const value = (arg.split("=", 2)[1] ?? "").toLowerCase();
+      if (!COOKIE_POLICY_VALUES.has(value)) {
+        throw createUsageError(`Invalid --cookie-policy-override: ${value}`);
+      }
+      parsed.cookiePolicyOverride = value;
+      continue;
+    }
+  }
+  return parsed;
+};
+async function runResearchCommand(args) {
+  const [subcommand, ...rest] = args.rawArgs;
+  if (subcommand !== "run") {
+    throw createUsageError("Usage: opendevbrowser research run --topic <value> [options]");
+  }
+  const parsed = parseResearchRunArgs(rest);
+  if (!parsed.topic?.trim()) {
+    throw createUsageError("Missing --topic");
+  }
+  const data = await callDaemon("research.run", {
+    topic: parsed.topic,
+    days: parsed.days,
+    from: parsed.from,
+    to: parsed.to,
+    sourceSelection: parsed.sourceSelection,
+    sources: parsed.sources,
+    mode: parsed.mode ?? "compact",
+    includeEngagement: parsed.includeEngagement ?? false,
+    limitPerSource: parsed.limitPerSource,
+    outputDir: parsed.outputDir,
+    ttlHours: parsed.ttlHours,
+    useCookies: parsed.useCookies,
+    cookiePolicyOverride: parsed.cookiePolicyOverride
+  });
+  return {
+    success: true,
+    message: "Research workflow completed.",
+    data
+  };
+}
+
+// src/cli/commands/shopping.ts
+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 requireValue9 = (rawArgs, index, flag) => {
+  const value = rawArgs[index + 1];
+  if (!value) {
+    throw createUsageError(`Missing value for ${flag}`);
+  }
+  return value;
+};
+var parseBoolean2 = (value, flag) => {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw createUsageError(`Invalid ${flag}: ${value}`);
+};
+var parseProviders = (raw) => {
+  const providers = raw.split(",").map((entry) => entry.trim()).filter(Boolean);
+  if (providers.length === 0) {
+    throw createUsageError("--providers requires at least one provider");
+  }
+  return [...new Set(providers)];
+};
+var parseShoppingRunArgs = (rawArgs) => {
+  const parsed = {};
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === "--query") {
+      parsed.query = requireValue9(rawArgs, index, "--query");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--query=")) {
+      parsed.query = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--providers") {
+      parsed.providers = parseProviders(requireValue9(rawArgs, index, "--providers"));
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--providers=")) {
+      parsed.providers = parseProviders(arg.split("=", 2)[1] ?? "");
+      continue;
+    }
+    if (arg === "--budget") {
+      parsed.budget = parseNumberFlag(requireValue9(rawArgs, index, "--budget"), "--budget", { min: 1, integer: false });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--budget=")) {
+      parsed.budget = parseNumberFlag(arg.split("=", 2)[1] ?? "", "--budget", { min: 1, integer: false });
+      continue;
+    }
+    if (arg === "--region") {
+      parsed.region = requireValue9(rawArgs, index, "--region");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--region=")) {
+      parsed.region = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--sort") {
+      const value = requireValue9(rawArgs, index, "--sort").toLowerCase();
+      if (!SORT_VALUES.has(value)) {
+        throw createUsageError(`Invalid --sort: ${value}`);
+      }
+      parsed.sort = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--sort=")) {
+      const value = (arg.split("=", 2)[1] ?? "").toLowerCase();
+      if (!SORT_VALUES.has(value)) {
+        throw createUsageError(`Invalid --sort: ${value}`);
+      }
+      parsed.sort = value;
+      continue;
+    }
+    if (arg === "--mode") {
+      const value = requireValue9(rawArgs, index, "--mode").toLowerCase();
+      if (!MODE_VALUES2.has(value)) {
+        throw createUsageError(`Invalid --mode: ${value}`);
+      }
+      parsed.mode = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--mode=")) {
+      const value = (arg.split("=", 2)[1] ?? "").toLowerCase();
+      if (!MODE_VALUES2.has(value)) {
+        throw createUsageError(`Invalid --mode: ${value}`);
+      }
+      parsed.mode = value;
+      continue;
+    }
+    if (arg === "--timeout-ms") {
+      parsed.timeoutMs = parseNumberFlag(requireValue9(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");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--output-dir=")) {
+      parsed.outputDir = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--ttl-hours") {
+      parsed.ttlHours = parseNumberFlag(requireValue9(rawArgs, index, "--ttl-hours"), "--ttl-hours", { min: 1, max: 168 });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--ttl-hours=")) {
+      parsed.ttlHours = parseNumberFlag(arg.split("=", 2)[1] ?? "", "--ttl-hours", { min: 1, max: 168 });
+      continue;
+    }
+    if (arg === "--use-cookies") {
+      parsed.useCookies = true;
+      continue;
+    }
+    if (arg?.startsWith("--use-cookies=")) {
+      parsed.useCookies = parseBoolean2(arg.split("=", 2)[1] ?? "", "--use-cookies");
+      continue;
+    }
+    if (arg === "--cookie-policy-override" || arg === "--cookie-policy") {
+      const value = requireValue9(rawArgs, index, arg).toLowerCase();
+      if (!COOKIE_POLICY_VALUES2.has(value)) {
+        throw createUsageError(`Invalid ${arg}: ${value}`);
+      }
+      parsed.cookiePolicyOverride = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--cookie-policy-override=") || arg?.startsWith("--cookie-policy=")) {
+      const value = (arg.split("=", 2)[1] ?? "").toLowerCase();
+      if (!COOKIE_POLICY_VALUES2.has(value)) {
+        throw createUsageError(`Invalid --cookie-policy-override: ${value}`);
+      }
+      parsed.cookiePolicyOverride = value;
+      continue;
+    }
+  }
+  return parsed;
+};
+async function runShoppingCommand(args) {
+  const [subcommand, ...rest] = args.rawArgs;
+  if (subcommand !== "run") {
+    throw createUsageError("Usage: opendevbrowser shopping run --query <value> [options]");
+  }
+  const parsed = parseShoppingRunArgs(rest);
+  if (!parsed.query?.trim()) {
+    throw createUsageError("Missing --query");
+  }
+  const payload = {
+    query: parsed.query,
+    providers: parsed.providers,
+    budget: parsed.budget,
+    region: parsed.region,
+    sort: parsed.sort,
+    mode: parsed.mode ?? "compact",
+    ...typeof parsed.timeoutMs === "number" ? { timeoutMs: parsed.timeoutMs } : {},
+    outputDir: parsed.outputDir,
+    ttlHours: parsed.ttlHours,
+    useCookies: parsed.useCookies,
+    cookiePolicyOverride: parsed.cookiePolicyOverride
+  };
+  const data = typeof parsed.timeoutMs === "number" ? await callDaemon("shopping.run", payload, { timeoutMs: parsed.timeoutMs }) : await callDaemon("shopping.run", payload);
+  return {
+    success: true,
+    message: "Shopping workflow completed.",
+    data
+  };
+}
+
+// src/cli/commands/product-video.ts
+var requireValue10 = (rawArgs, index, flag) => {
+  const value = rawArgs[index + 1];
+  if (!value) {
+    throw createUsageError(`Missing value for ${flag}`);
+  }
+  return value;
+};
+var parseBoolean3 = (value, flag) => {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw createUsageError(`Invalid ${flag}: ${value}`);
+};
+var COOKIE_POLICY_VALUES3 = /* @__PURE__ */ new Set(["off", "auto", "required"]);
+var parseProductVideoArgs = (rawArgs) => {
+  const parsed = {};
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === "--product-url") {
+      parsed.productUrl = requireValue10(rawArgs, index, "--product-url");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--product-url=")) {
+      parsed.productUrl = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--product-name") {
+      parsed.productName = requireValue10(rawArgs, index, "--product-name");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--product-name=")) {
+      parsed.productName = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--provider-hint") {
+      parsed.providerHint = requireValue10(rawArgs, index, "--provider-hint");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--provider-hint=")) {
+      parsed.providerHint = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--include-screenshots") {
+      parsed.includeScreenshots = true;
+      continue;
+    }
+    if (arg?.startsWith("--include-screenshots=")) {
+      parsed.includeScreenshots = parseBoolean3(arg.split("=", 2)[1] ?? "", "--include-screenshots");
+      continue;
+    }
+    if (arg === "--include-all-images") {
+      parsed.includeAllImages = true;
+      continue;
+    }
+    if (arg?.startsWith("--include-all-images=")) {
+      parsed.includeAllImages = parseBoolean3(arg.split("=", 2)[1] ?? "", "--include-all-images");
+      continue;
+    }
+    if (arg === "--include-copy") {
+      parsed.includeCopy = true;
+      continue;
+    }
+    if (arg?.startsWith("--include-copy=")) {
+      parsed.includeCopy = parseBoolean3(arg.split("=", 2)[1] ?? "", "--include-copy");
+      continue;
+    }
+    if (arg === "--output-dir") {
+      parsed.outputDir = requireValue10(rawArgs, index, "--output-dir");
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--output-dir=")) {
+      parsed.outputDir = arg.split("=", 2)[1];
+      continue;
+    }
+    if (arg === "--ttl-hours") {
+      parsed.ttlHours = parseNumberFlag(requireValue10(rawArgs, index, "--ttl-hours"), "--ttl-hours", { min: 1, max: 168 });
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--ttl-hours=")) {
+      parsed.ttlHours = parseNumberFlag(arg.split("=", 2)[1] ?? "", "--ttl-hours", { min: 1, max: 168 });
+      continue;
+    }
+    if (arg === "--timeout-ms") {
+      parsed.timeoutMs = parseNumberFlag(requireValue10(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 === "--use-cookies") {
+      parsed.useCookies = true;
+      continue;
+    }
+    if (arg?.startsWith("--use-cookies=")) {
+      parsed.useCookies = parseBoolean3(arg.split("=", 2)[1] ?? "", "--use-cookies");
+      continue;
+    }
+    if (arg === "--cookie-policy-override" || arg === "--cookie-policy") {
+      const value = requireValue10(rawArgs, index, arg).toLowerCase();
+      if (!COOKIE_POLICY_VALUES3.has(value)) {
+        throw createUsageError(`Invalid ${arg}: ${value}`);
+      }
+      parsed.cookiePolicyOverride = value;
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--cookie-policy-override=") || arg?.startsWith("--cookie-policy=")) {
+      const value = (arg.split("=", 2)[1] ?? "").toLowerCase();
+      if (!COOKIE_POLICY_VALUES3.has(value)) {
+        throw createUsageError(`Invalid --cookie-policy-override: ${value}`);
+      }
+      parsed.cookiePolicyOverride = value;
+      continue;
+    }
+  }
+  return parsed;
+};
+async function runProductVideoCommand(args) {
+  const [subcommand, ...rest] = args.rawArgs;
+  if (subcommand !== "run") {
+    throw createUsageError("Usage: opendevbrowser product-video run --product-url <url> | --product-name <name>");
+  }
+  const parsed = parseProductVideoArgs(rest);
+  if (!parsed.productUrl && !parsed.productName) {
+    throw createUsageError("Missing --product-url or --product-name");
+  }
+  const timeoutMs = parsed.timeoutMs ?? 12e4;
+  const data = await callDaemon("product.video.run", {
+    product_url: parsed.productUrl,
+    product_name: parsed.productName,
+    provider_hint: parsed.providerHint,
+    include_screenshots: parsed.includeScreenshots,
+    include_all_images: parsed.includeAllImages,
+    include_copy: parsed.includeCopy,
+    output_dir: parsed.outputDir,
+    ttl_hours: parsed.ttlHours,
+    useCookies: parsed.useCookies,
+    cookiePolicyOverride: parsed.cookiePolicyOverride
+  }, { timeoutMs });
+  return {
+    success: true,
+    message: "Product video asset workflow completed.",
+    data
+  };
+}
+
+// package.json
+var package_default = {
+  name: "opendevbrowser",
+  version: "0.0.16",
+  description: "OpenCode plugin for browser automation via CDP with snapshot-refs-actions workflow",
+  type: "module",
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  bin: {
+    opendevbrowser: "dist/cli/index.js"
+  },
+  files: [
+    "dist",
+    "skills",
+    "scripts/native",
+    "extension/manifest.json",
+    "extension/popup.html",
+    "extension/dist",
+    "extension/icons"
+  ],
+  keywords: [
+    "opencode",
+    "plugin",
+    "browser",
+    "automation",
+    "cdp",
+    "playwright",
+    "testing",
+    "web-scraping",
+    "chrome"
+  ],
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/freshtechbro/opendevbrowser.git"
+  },
+  engines: {
+    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",
+    lint: 'eslint "src/**/*.ts" "tests/**/*.ts"',
+    typecheck: "tsc --noEmit -p tsconfig.json",
+    test: "vitest run --coverage",
+    "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",
+    "test:release-gate:g3": "node scripts/release-gate-test-groups.mjs --group 3",
+    "test:release-gate:g4": "node scripts/release-gate-test-groups.mjs --group 4",
+    "test:release-gate:g5": "node scripts/release-gate-test-groups.mjs --group 5",
+    "extension:sync": "node scripts/sync-extension-version.mjs",
+    "extension:build": "npm run extension:sync && tsc -p extension/tsconfig.json && node scripts/copy-extension-assets.mjs",
+    "extension:pack": "cd extension && zip -r ../opendevbrowser-extension.zip manifest.json popup.html dist/ icons/",
+    "extension:store": "node scripts/chrome-store-publish.mjs",
+    "version:check": "node scripts/verify-versions.mjs",
+    prepack: "npm run version:check && npm run build && npm run extension:build"
+  },
+  dependencies: {
+    "@opencode-ai/plugin": "^1.2.11",
+    "@puppeteer/browsers": "^2.13.0",
+    "async-mutex": "^0.5.0",
+    "jsonc-parser": "^3.2.0",
+    "playwright-core": "^1.58.2",
+    ws: "^8.19.0",
+    zod: "^3.25.76"
+  },
+  devDependencies: {
+    "@types/chrome": "^0.1.37",
+    "@types/node": "^20.19.35",
+    "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    eslint: "^9.39.3",
+    "happy-dom": "^20.7.0",
+    tsup: "^8.5.1",
+    typescript: "^5.9.3",
+    vitest: "^4.0.18"
+  }
+};
+
+// src/cli/index.ts
+var VERSION = typeof package_default.version === "string" ? package_default.version : "0.0.0";
+async function promptInstallMode() {
+  if (!process.stdin.isTTY) {
+    console.log("Non-interactive mode detected. Using global install.");
+    return "global";
+  }
+  return new Promise((resolve6) => {
+    console.log("\nWhere would you like to install opendevbrowser?\n");
+    console.log("  1. Global (~/.config/opencode/opencode.json)");
+    console.log("  2. Local (./opencode.json in this project)\n");
+    process.stdout.write("Enter choice [1]: ");
+    process.stdin.setEncoding("utf8");
+    let resolved = false;
+    let timeoutId = null;
+    const cleanup = () => {
+      if (timeoutId !== null) {
         clearTimeout(timeoutId);
         timeoutId = null;
       }
@@ -3751,23 +5644,23 @@ async function promptInstallMode() {
       resolved = true;
       const input = data.toString().trim();
       if (input === "2") {
-        resolve4("local");
+        resolve6("local");
       } else {
-        resolve4("global");
+        resolve6("global");
       }
     });
     process.stdin.once("close", () => {
       cleanup();
       if (resolved) return;
       resolved = true;
-      resolve4("global");
+      resolve6("global");
     });
     timeoutId = setTimeout(() => {
       timeoutId = null;
       if (resolved) return;
       resolved = true;
       console.log("\nTimeout - using global install.");
-      resolve4("global");
+      resolve6("global");
     }, 3e4);
   });
 }
@@ -3787,7 +5680,7 @@ async function promptUninstallMode() {
     console.log("Plugin found in both global and local configs. Use --global or --local flag.");
     return null;
   }
-  return new Promise((resolve4) => {
+  return new Promise((resolve6) => {
     console.log("\nopendevbrowser is installed in multiple locations:\n");
     console.log("  1. Global (~/.config/opencode/opencode.json)");
     console.log("  2. Local (./opencode.json)");
@@ -3797,15 +5690,15 @@ async function promptUninstallMode() {
     process.stdin.once("data", (data) => {
       const input = data.toString().trim();
       if (input === "1") {
-        resolve4("global");
+        resolve6("global");
       } else if (input === "2") {
-        resolve4("local");
+        resolve6("local");
       } else {
-        resolve4(null);
+        resolve6(null);
       }
     });
     process.stdin.once("close", () => {
-      resolve4(null);
+      resolve6(null);
     });
   });
 }
@@ -4046,6 +5939,11 @@ async function main() {
       description: "Request interactive annotations (extension relay)",
       run: async () => runAnnotate(args)
     });
+    registerCommand({
+      name: "rpc",
+      description: "Execute an internal daemon RPC command (power-user)",
+      run: async () => runRpc(args)
+    });
     registerCommand({
       name: "click",
       description: "Click an element by ref",
@@ -4191,6 +6089,46 @@ async function main() {
       description: "Poll network events",
       run: async () => runNetworkPoll(args)
     });
+    registerCommand({
+      name: "debug-trace-snapshot",
+      description: "Capture page + console + network + exception diagnostics",
+      run: async () => runDebugTraceSnapshot(args)
+    });
+    registerCommand({
+      name: "cookie-import",
+      description: "Import validated cookies into a session",
+      run: async () => runCookieImport(args)
+    });
+    registerCommand({
+      name: "cookie-list",
+      description: "List cookies for a session (optionally filtered by URL)",
+      run: async () => runCookieList(args)
+    });
+    registerCommand({
+      name: "macro-resolve",
+      description: "Resolve or execute a macro expression via provider actions",
+      run: async () => runMacroResolve(args)
+    });
+    registerCommand({
+      name: "research",
+      description: "Run research workflows",
+      run: async () => runResearchCommand(args)
+    });
+    registerCommand({
+      name: "shopping",
+      description: "Run shopping workflows",
+      run: async () => runShoppingCommand(args)
+    });
+    registerCommand({
+      name: "product-video",
+      description: "Run product presentation asset workflows",
+      run: async () => runProductVideoCommand(args)
+    });
+    registerCommand({
+      name: "artifacts",
+      description: "Manage workflow artifact lifecycle",
+      run: async () => runArtifactsCommand(args)
+    });
     const command = getCommand(args.command);
     if (!command) {
       throw new Error(`Unknown command: ${args.command}`);