browserctl 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff8250901d49ad1038c686f51d303f2139fe673c708746804cdb59e1239890fe
-  data.tar.gz: b47c1e8dbf9093ffe43001d8cacf02c490c887fb5e58336449f1b7aedebfda0b
+  metadata.gz: 2a7eb052c2bbfc4e1f5afc24ba08c5b2b0d471a85d2acf6ea61a7f160cbe201b
+  data.tar.gz: 2d4259da9b4a13a50ad80e68d404f11eda89b6249e5315c58247c8d80514d21f
 SHA512:
-  metadata.gz: e11c9a8300e7ec744e70ad5f33b645c9afc59e4e5212696045e899f4f2da017d1e4589f750db65b004d8e8208092d6a031724474a2a8feb48f249ed1daa83262
-  data.tar.gz: 1a48cb05e7d92ab6dfd2de777abd0d8904a30b27c8d03fdaee2c00d1b5b734a9f8499be90ea30db686022a5c0d9ad7532ea1c1f148f0e1047a0583a954048dd8
+  metadata.gz: ca34ca3125de0686417b06919a8cb0eaf3311eaedd7ebe6538c1f159941d737ca549f3d0c3d8a10da73146bd23602cb145ed010539a48de97c3d8552d4f317c9
+  data.tar.gz: 61c89f8a4b2e61076ddd5fa603710e226ebfe1e176914ffb37f47a79ee35a2161b3700406a35c878d6fdc6cb129f051f00943d080b636076f6d1452b6ee290b3

data/CHANGELOG.md

@@ -10,6 +10,72 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.0](https://github.com/patrick204nqh/browserctl/compare/v0.11.0...v0.12.0) (2026-05-10)
+
+
+### ⚠ BREAKING CHANGES
+
+* Scripts that hard-coded `exit 7 = AUTH_REQUIRED` must update — AUTH_REQUIRED is now exit 3, and 7 is STATE_EXPIRED. Scripts treating any non-zero status as a generic failure are unaffected. Prior to this change the CLI exited 1 for everything except AUTH_REQUIRED (which already used 7); typed errors now surface their dedicated codes.
+
+### Features
+
+* benchmark harness + bundle_codec target ([#154](https://github.com/patrick204nqh/browserctl/issues/154)) ([f4b815a](https://github.com/patrick204nqh/browserctl/commit/f4b815a617d4a7d22473e6028ce2a0f90467fa87))
+* bundle format version ([#132](https://github.com/patrick204nqh/browserctl/issues/132)) ([b52d325](https://github.com/patrick204nqh/browserctl/commit/b52d32546d1b9ec3915fac014fecd8f929161ddb))
+* crash reports ([#135](https://github.com/patrick204nqh/browserctl/issues/135)) ([b02adf4](https://github.com/patrick204nqh/browserctl/commit/b02adf4d41295dbe547d2965d838168d48efb8bf))
+* error code enum ([#128](https://github.com/patrick204nqh/browserctl/issues/128)) ([feb0522](https://github.com/patrick204nqh/browserctl/commit/feb0522887935737fd96ad8a8b47d1407a5f585e))
+* exit code map ([#140](https://github.com/patrick204nqh/browserctl/issues/140)) ([1a1d2b2](https://github.com/patrick204nqh/browserctl/commit/1a1d2b2f50693863cb508b5354e5546f340a2771))
+* format version header convention ([#129](https://github.com/patrick204nqh/browserctl/issues/129)) ([405774d](https://github.com/patrick204nqh/browserctl/commit/405774dd6c99cc96f62f0c092010b30e7e710d41))
+* migration helpers ([#143](https://github.com/patrick204nqh/browserctl/issues/143)) ([1c1762e](https://github.com/patrick204nqh/browserctl/commit/1c1762e755f83445c7cdd0df75fc5324a820fa19))
+* recording format version ([#136](https://github.com/patrick204nqh/browserctl/issues/136)) ([4f1bc46](https://github.com/patrick204nqh/browserctl/commit/4f1bc467e653ecc1f508a85b3c329adf048b783d))
+* structured error payload ([#137](https://github.com/patrick204nqh/browserctl/issues/137)) ([f028410](https://github.com/patrick204nqh/browserctl/commit/f02841069f68de749a76ba9a98a38b0c20836d76))
+* structured JSONL logs ([#131](https://github.com/patrick204nqh/browserctl/issues/131)) ([c6daff4](https://github.com/patrick204nqh/browserctl/commit/c6daff488460606659c0641dd8cee6c23561be05))
+* trace --redact ([#139](https://github.com/patrick204nqh/browserctl/issues/139)) ([19b4cec](https://github.com/patrick204nqh/browserctl/commit/19b4cec37daf95a06b0513780d991d0522069593))
+* trace command ([#133](https://github.com/patrick204nqh/browserctl/issues/133)) ([156f304](https://github.com/patrick204nqh/browserctl/commit/156f304246d24fa6c3e06f8d941ac971629ea77c))
+* workflow format version ([#138](https://github.com/patrick204nqh/browserctl/issues/138)) ([963776b](https://github.com/patrick204nqh/browserctl/commit/963776be785583fc3a3b0c04c97510e16c73ca9a))
+
+
+### Miscellaneous Chores
+
+* target next release as 0.12.0 ([#156](https://github.com/patrick204nqh/browserctl/issues/156)) ([9797fcc](https://github.com/patrick204nqh/browserctl/commit/9797fcc0bae1a47bb72eec9cec5fda105e698406))
+
+## [0.11.0](https://github.com/patrick204nqh/browserctl/compare/v0.10.0...v0.11.0) (2026-05-10)
+
+
+### Features
+
+* .bctl bundle codec ([#94](https://github.com/patrick204nqh/browserctl/issues/94)) ([75a4370](https://github.com/patrick204nqh/browserctl/commit/75a43704abf9cf766435fff35409333514fd3c73))
+* auth_required detector ([#99](https://github.com/patrick204nqh/browserctl/issues/99)) ([6d9554f](https://github.com/patrick204nqh/browserctl/commit/6d9554f7cbe9b8e93d22c42b03ff2ce59e594f28))
+* AUTH_REQUIRED structured error code ([#100](https://github.com/patrick204nqh/browserctl/issues/100)) ([9928a4e](https://github.com/patrick204nqh/browserctl/commit/9928a4e7d456d0382b2244096fb38ebeee55013d))
+* browserctl flow run/list/describe CLI ([#89](https://github.com/patrick204nqh/browserctl/issues/89)) ([5016fe5](https://github.com/patrick204nqh/browserctl/commit/5016fe54ee1414b967025f450ded79565ef9bcfb))
+* drift telemetry (WS-2.4) ([#114](https://github.com/patrick204nqh/browserctl/issues/114)) ([712da07](https://github.com/patrick204nqh/browserctl/commit/712da075e623a2aa27a779958b94c0f6e92384c8))
+* element fingerprint (WS-1.2) ([#107](https://github.com/patrick204nqh/browserctl/issues/107)) ([8a8b6b4](https://github.com/patrick204nqh/browserctl/commit/8a8b6b45121cb179919fae8c3f87a4584d4b4bc1))
+* enriched recording log (WS-3.1) ([#115](https://github.com/patrick204nqh/browserctl/issues/115)) ([c00787d](https://github.com/patrick204nqh/browserctl/commit/c00787dc5f208cf69cd4a0326d4df19ed31e3bfc))
+* fingerprint matcher (WS-2.1) ([#111](https://github.com/patrick204nqh/browserctl/issues/111)) ([1d99d20](https://github.com/patrick204nqh/browserctl/commit/1d99d208f5d3815c8ef1e59e3d549d15c3719712))
+* flow registry ([#86](https://github.com/patrick204nqh/browserctl/issues/86)) ([31579dd](https://github.com/patrick204nqh/browserctl/commit/31579dd20156a700ace15137b34b120d16c86b6f))
+* inferred waits (WS-3.3) ([#117](https://github.com/patrick204nqh/browserctl/issues/117)) ([9332754](https://github.com/patrick204nqh/browserctl/commit/93327545b1d21e00c16037c6730f019b574bc572))
+* invoke flows from workflow DSL ([#88](https://github.com/patrick204nqh/browserctl/issues/88)) ([61fdc0a](https://github.com/patrick204nqh/browserctl/commit/61fdc0a6c98fdaf29c5034b80ccc54fdfb447e3a))
+* load_state auto re-run + on_auth_required hook ([#101](https://github.com/patrick204nqh/browserctl/issues/101)) ([8328d13](https://github.com/patrick204nqh/browserctl/commit/8328d1348d2be8ec685ece9dec3cafb0eb26eb90))
+* postcondition extraction (WS-3.4) ([#118](https://github.com/patrick204nqh/browserctl/issues/118)) ([56e76d5](https://github.com/patrick204nqh/browserctl/commit/56e76d50814d9c9a539ea56b20e6936d62509fcf))
+* replay fallback in PageProxy (WS-2.2) ([#112](https://github.com/patrick204nqh/browserctl/issues/112)) ([50714fc](https://github.com/patrick204nqh/browserctl/commit/50714fcd2ff16614af0d18c8b390084e3f32511e))
+* stable ref derivation (v0.11 WS-1.1) ([#106](https://github.com/patrick204nqh/browserctl/issues/106)) ([86df66a](https://github.com/patrick204nqh/browserctl/commit/86df66aaa9fc0b6c7a3a285c572ba2941b301e55))
+* state export/import with file/s3/op transports ([#96](https://github.com/patrick204nqh/browserctl/issues/96)) ([f1dd97b](https://github.com/patrick204nqh/browserctl/commit/f1dd97b895503ee19e60f14bbb9df81dcb321bd1))
+* state rotate ([#97](https://github.com/patrick204nqh/browserctl/issues/97)) ([78bb091](https://github.com/patrick204nqh/browserctl/commit/78bb091194e12e12867d7be0f566d426bdcb3b14))
+* state save/load/list/info/delete ([#95](https://github.com/patrick204nqh/browserctl/issues/95)) ([4502cd1](https://github.com/patrick204nqh/browserctl/commit/4502cd1e8992f486b34ce2288a34a9ef78808617))
+* stdlib flow — cloudflare_solve ([#93](https://github.com/patrick204nqh/browserctl/issues/93)) ([b4411b9](https://github.com/patrick204nqh/browserctl/commit/b4411b94af669d435346006c5f9304258456ba7b))
+* stdlib flow — totp_2fa ([#90](https://github.com/patrick204nqh/browserctl/issues/90)) ([c23e574](https://github.com/patrick204nqh/browserctl/commit/c23e574887e1ef3324e41e988a8f8047079ac998))
+* stdlib flows — basic_auth, magic_link_email ([#91](https://github.com/patrick204nqh/browserctl/issues/91)) ([e401d60](https://github.com/patrick204nqh/browserctl/commit/e401d60b4cf5b4b9f2b4138c45a9b19275a089e7))
+* stdlib flows — oauth_google, oauth_github ([#92](https://github.com/patrick204nqh/browserctl/issues/92)) ([04c9586](https://github.com/patrick204nqh/browserctl/commit/04c9586ff83503b7d94a2c73fe9c3360f01dc4ca))
+* workflow generate (WS-3.2) ([#116](https://github.com/patrick204nqh/browserctl/issues/116)) ([90dca3b](https://github.com/patrick204nqh/browserctl/commit/90dca3bada9b53f91e9be39e3d94d0208dcfa181))
+* workflow promote --as-flow (WS-3.7) ([#121](https://github.com/patrick204nqh/browserctl/issues/121)) ([a5e4b30](https://github.com/patrick204nqh/browserctl/commit/a5e4b30a30559e8fa6b3f4ff3df7189dc3d6bd1e))
+* workflow promote (WS-3.6) ([#120](https://github.com/patrick204nqh/browserctl/issues/120)) ([4355353](https://github.com/patrick204nqh/browserctl/commit/4355353213586dedf9f348f0fd211d1f0d3d72c6))
+* workflow run --check + drift report (WS-2.3) ([#113](https://github.com/patrick204nqh/browserctl/issues/113)) ([7cb4bc7](https://github.com/patrick204nqh/browserctl/commit/7cb4bc7d967f4045e5709eacabb0408edf21f9f1))
+* workflow run --check snapshot-diff (WS-3.5) ([#119](https://github.com/patrick204nqh/browserctl/issues/119)) ([1d131d8](https://github.com/patrick204nqh/browserctl/commit/1d131d85ea6e7948e9e734de6531c2d8dd194388))
+
+
+### Bug Fixes
+
+* pass first open page to flow during load_state auto-rotate ([#105](https://github.com/patrick204nqh/browserctl/issues/105)) ([2c67733](https://github.com/patrick204nqh/browserctl/commit/2c67733fc4f879fc40833194e9e71e32cd3096a8))
+
 ## [0.10.0](https://github.com/patrick204nqh/browserctl/compare/v0.9.0...v0.10.0) (2026-05-09)
 
 

data/README.md

@@ -196,8 +196,9 @@ The daemon shuts itself down after 30 minutes of inactivity.
 |---|---|
 | [Getting Started](docs/getting-started.md) | Install, first session, first snapshot |
 | [Agent Integration](docs/guides/agent-integration.md) | Call browserctl from Python, shell, or Anthropic tool-use agents |
-| [Concepts](docs/concepts/) | Sessions, snapshots, human-in-the-loop |
+| [Concepts](docs/concepts/) | Sessions, snapshots, [state](docs/concepts/state.md), [flows](docs/concepts/flows.md), human-in-the-loop |
 | [Guides](docs/guides/) | Writing workflows, handling challenges, smoke testing |
+| [Debugging](docs/guides/debugging.md) | Read traces, redaction, crash reports, filing a good issue |
 | [Examples](examples/) | Runnable scripts: session reuse, Cloudflare HITL, and more |
 | [Command Reference](docs/reference/commands.md) | Every command and flag |
 | [API Stability](docs/reference/api-stability.md) | Wire protocol contract and stability zones |

data/bin/browserctl

@@ -25,17 +25,35 @@ require "browserctl/commands/page"
 require "browserctl/commands/cookie"
 require "browserctl/commands/storage"
 require "browserctl/commands/session"
+require "browserctl/commands/state"
 require "browserctl/commands/daemon"
 require "browserctl/commands/workflow"
+require "browserctl/commands/flow"
 require "browserctl/commands/dialog"
 require "browserctl/commands/ask"
+require "browserctl/commands/trace"
+require "browserctl/commands/migrate"
+
+def structured_stderr_payload(res, message)
+  code    = (res[:code] || res["code"] || Browserctl::Error::Codes::GENERIC).to_s
+  context = res[:context] || res["context"] || {}
+  action  = res[:suggested_action] || res["suggested_action"] ||
+            Browserctl::Error::SuggestedActions.for(code)
+  [code, JSON.generate(code: code, message: message, context: context, suggested_action: action)]
+end
 
 def print_result(res)
-  if res.is_a?(Hash) && res[:error]
-    warn "Error: #{res[:error]}"
-    exit 1
+  unless res.is_a?(Hash) && (res[:error] || res["error"])
+    puts res.to_json
+    return
   end
+
+  message = res[:error] || res["error"]
+  code, payload = structured_stderr_payload(res, message)
+  warn "Error: #{message}"
+  warn payload
   puts res.to_json
+  exit Browserctl::Error::ExitCodes.for(code)
 end
 
 def usage
@@ -95,15 +113,45 @@ def usage
       session export <name> <path>
       session import <path>
 
+    Auth detection:
+      auth-check <page> [--cookies] [--state NAME] [--flow NAME]
+        # Exits 7 with code: AUTH_REQUIRED when the page needs login.
+
+    State (.bctl bundles — cookies + storage + flow binding):
+      state save   <name> [--encrypt] [--origins a,b] [--flow NAME]
+      state load   <name>
+      state list
+      state info   <name>
+      state delete <name>
+      state rotate <name> [--page NAME] [--params FILE] [--key value ...]
+      state export <name> <destination>     # file path, s3://..., op://Vault/Item
+      state import <source> [--name NAME]
+
     Recording:
       record start <name>
       record stop  [--out PATH]
       record status
 
     Workflow:
-      workflow run      <name|file> [--params file] [--key value ...]
+      workflow run      <name|file> [--check] [--params file] [--key value ...]
       workflow list
       workflow describe <name>
+      workflow generate <recording> [--out PATH]
+      workflow promote  <name> [--force] [--threshold N] [--as-flow]
+
+    Flow:
+      flow run      <name|file> [--page NAME] [--params file] [--key value ...]
+      flow list
+      flow describe <name>
+
+    Trace:
+      trace [<session>]  Pretty timeline of CLI + daemon log events.
+
+    Migrate:
+      migrate <path> [--to-version N] [--dry-run]
+        # Upgrades a persisted artifact (.bctl / .jsonl recording / workflow .rb)
+        # using registered migrations. Empty registry in v0.12 — first real
+        # migration ships post-1.0 when a format actually changes.
 
     Daemon:
       daemon start  [--headed] [--name NAME]
@@ -125,6 +173,17 @@ daemon_name = if daemon_idx
                 ARGV.delete_at(daemon_idx)
               end
 
+log_level_idx = ARGV.index("--log-level") || ARGV.index("-l")
+log_level     = if log_level_idx
+                  ARGV.delete_at(log_level_idx)
+                  ARGV.delete_at(log_level_idx)
+                end || ENV["BROWSERCTL_LOG_LEVEL"] || "info"
+
+# CLI invocations write structured JSON Lines to ~/.browserctl/logs/cli.log
+# alongside the existing stderr behaviour. Stderr stays human-readable so
+# scripted callers see no change.
+Browserctl.logger = Browserctl.build_logger(log_level, component: "cli")
+
 cmd  = ARGV.shift
 args = ARGV.dup
 
@@ -132,82 +191,113 @@ usage if cmd.nil? || %w[-h --help help].include?(cmd)
 
 runner = Browserctl::Runner.new
 
-case cmd
-when "workflow" then Browserctl::Commands::Workflow.run(runner, args)
-when "record"   then Browserctl::Commands::Record.run(args)
-when "init"     then Browserctl::Commands::Init.run(args)
-when "ask"      then Browserctl::Commands::Ask.run(args)
+begin
+  case cmd
+  when "workflow" then Browserctl::Commands::Workflow.run(runner, args)
+  when "record"   then Browserctl::Commands::Record.run(args)
+  when "init"     then Browserctl::Commands::Init.run(args)
+  when "ask"      then Browserctl::Commands::Ask.run(args)
+  when "trace"    then Browserctl::Commands::Trace.run(args)
+  when "migrate"  then Browserctl::Commands::Migrate.run(args)
 
-else
-  client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
+  else
+    client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
 
-  case cmd
-  when "page"     then Browserctl::Commands::Page.run(client, args)
-  when "cookie"   then Browserctl::Commands::Cookie.run(client, args)
-  when "storage"  then Browserctl::Commands::Storage.run(client, args)
-  when "session"  then Browserctl::Commands::Session.run(client, args)
-  when "daemon"   then Browserctl::Commands::Daemon.run(client, args)
-  when "navigate" then print_result(client.navigate(args[0], args[1]))
-  when "fill"     then Browserctl::Commands::Fill.run(client, args)
-  when "click"    then Browserctl::Commands::Click.run(client, args)
-  when "snapshot" then Browserctl::Commands::Snapshot.run(client, args)
-  when "screenshot" then Browserctl::Commands::Screenshot.run(client, args)
-  when "evaluate" then print_result(client.evaluate(args[0], args[1]))
-  when "url"      then print_result(client.url(args[0]))
-  when "wait"
-    opts = Optimist.options(args) do
-      opt :timeout, "Seconds to wait (default: 30)", default: 30.0, short: "-t"
+    case cmd
+    when "flow"     then Browserctl::Commands::Flow.run(client, args)
+    when "page"     then Browserctl::Commands::Page.run(client, args)
+    when "cookie"   then Browserctl::Commands::Cookie.run(client, args)
+    when "storage"  then Browserctl::Commands::Storage.run(client, args)
+    when "session"  then Browserctl::Commands::Session.run(client, args)
+    when "state"    then Browserctl::Commands::State.run(client, args)
+    when "daemon"   then Browserctl::Commands::Daemon.run(client, args)
+    when "auth-check"
+      page_name = args.shift or abort "usage: browserctl auth-check <page> [--cookies] [--state NAME] [--flow NAME]"
+      include_cookies = args.delete("--cookies") ? true : false
+      state_idx = args.index("--state")
+      state_arg = if state_idx
+                    (args.delete_at(state_idx)
+                     args.delete_at(state_idx))
+                  end
+      flow_idx  = args.index("--flow")
+      flow_arg  = if flow_idx
+                    (args.delete_at(flow_idx)
+                     args.delete_at(flow_idx))
+                  end
+      print_result(client.auth_check(page_name, include_cookies: include_cookies,
+                                                state: state_arg, suggested_flow: flow_arg))
+    when "navigate" then print_result(client.navigate(args[0], args[1]))
+    when "fill"     then Browserctl::Commands::Fill.run(client, args)
+    when "click"    then Browserctl::Commands::Click.run(client, args)
+    when "snapshot" then Browserctl::Commands::Snapshot.run(client, args)
+    when "screenshot" then Browserctl::Commands::Screenshot.run(client, args)
+    when "evaluate" then print_result(client.evaluate(args[0], args[1]))
+    when "url"      then print_result(client.url(args[0]))
+    when "wait"
+      opts = Optimist.options(args) do
+        opt :timeout, "Seconds to wait (default: 30)", default: 30.0, short: "-t"
+      end
+      name = args.shift
+      selector = args.shift
+      abort "usage: browserctl wait <page> <selector> [--timeout N]" unless name && selector
+      print_result(client.wait(name, selector, timeout: opts[:timeout]))
+    when "pause"
+      opts = Optimist.options(args) do
+        opt :message, "Message shown to human", type: :string, short: "-m"
+      end
+      name = args.shift or abort "usage: browserctl pause <page> [--message MSG]"
+      res = client.pause(name, message: opts[:message])
+      if res[:error]
+        warn "Error: #{res[:error]}"
+        exit 1
+      end
+      puts "Page '#{name}' paused. Browser is live — interact freely."
+      puts "(#{opts[:message]})" if opts[:message]
+      puts "When done: browserctl resume #{name}"
+    when "resume" then Browserctl::Commands::Resume.run(client, args)
+    when "press"
+      name = args.shift or abort "usage: browserctl press <page> <key>"
+      key  = args.shift or abort "usage: browserctl press <page> <key>"
+      print_result(client.press(name, key))
+    when "hover"
+      name     = args.shift or abort "usage: browserctl hover <page> <selector>"
+      selector = args.shift or abort "usage: browserctl hover <page> <selector>"
+      print_result(client.hover(name, selector))
+    when "upload"
+      name     = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
+      selector = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
+      path     = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
+      print_result(client.upload(name, selector, path))
+    when "select"
+      name     = args.shift or abort "usage: browserctl select <page> <selector> <value>"
+      selector = args.shift or abort "usage: browserctl select <page> <selector> <value>"
+      value    = args.shift or abort "usage: browserctl select <page> <selector> <value>"
+      print_result(client.select(name, selector, value))
+    when "dialog" then Browserctl::Commands::Dialog.run(client, args)
+    when "devtools"
+      name = args.shift or abort "usage: browserctl devtools <page>"
+      res = client.devtools(name)
+      if res[:error]
+        warn "Error: #{res[:error]}"
+        exit 1
+      end
+      url = res[:devtools_url]
+      puts "Opening DevTools for '#{name}':"
+      puts "  #{url}"
+      opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
+      system(opener, url)
+    else
+      abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
     end
-    name = args.shift
-    selector = args.shift
-    abort "usage: browserctl wait <page> <selector> [--timeout N]" unless name && selector
-    print_result(client.wait(name, selector, timeout: opts[:timeout]))
-  when "pause"
-    opts = Optimist.options(args) do
-      opt :message, "Message shown to human", type: :string, short: "-m"
-    end
-    name = args.shift or abort "usage: browserctl pause <page> [--message MSG]"
-    res = client.pause(name, message: opts[:message])
-    if res[:error]
-      warn "Error: #{res[:error]}"
-      exit 1
-    end
-    puts "Page '#{name}' paused. Browser is live — interact freely."
-    puts "(#{opts[:message]})" if opts[:message]
-    puts "When done: browserctl resume #{name}"
-  when "resume" then Browserctl::Commands::Resume.run(client, args)
-  when "press"
-    name = args.shift or abort "usage: browserctl press <page> <key>"
-    key  = args.shift or abort "usage: browserctl press <page> <key>"
-    print_result(client.press(name, key))
-  when "hover"
-    name     = args.shift or abort "usage: browserctl hover <page> <selector>"
-    selector = args.shift or abort "usage: browserctl hover <page> <selector>"
-    print_result(client.hover(name, selector))
-  when "upload"
-    name     = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
-    selector = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
-    path     = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
-    print_result(client.upload(name, selector, path))
-  when "select"
-    name     = args.shift or abort "usage: browserctl select <page> <selector> <value>"
-    selector = args.shift or abort "usage: browserctl select <page> <selector> <value>"
-    value    = args.shift or abort "usage: browserctl select <page> <selector> <value>"
-    print_result(client.select(name, selector, value))
-  when "dialog" then Browserctl::Commands::Dialog.run(client, args)
-  when "devtools"
-    name = args.shift or abort "usage: browserctl devtools <page>"
-    res = client.devtools(name)
-    if res[:error]
-      warn "Error: #{res[:error]}"
-      exit 1
-    end
-    url = res[:devtools_url]
-    puts "Opening DevTools for '#{name}':"
-    puts "  #{url}"
-    opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
-    system(opener, url)
-  else
-    abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
   end
+rescue Browserctl::Error => e
+  payload = {
+    code: e.code,
+    message: e.message,
+    context: e.respond_to?(:context) ? (e.context || {}) : {},
+    suggested_action: Browserctl::Error::SuggestedActions.for(e.code)
+  }
+  warn "Error: #{e.message}"
+  warn JSON.generate(payload)
+  exit Browserctl::Error::ExitCodes.for(e.code)
 end

data/bin/browserd

@@ -5,6 +5,7 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
 require "optimist"
 require "nokogiri"
+require "browserctl/crash_report"
 require "browserctl/logger"
 require "browserctl/server"
 require "browserctl/version"
@@ -35,7 +36,9 @@ end
 
 log_path = Browserctl.log_path(assigned_name)
 warn "browserd starting — log: #{log_path}"
-Browserctl.logger = Browserctl.build_logger(opts[:log_level], log_path: log_path)
+warn "  if browserd crashes, attach the crash report from ~/.browserctl/logs/crash-*.json"
+Browserctl.logger = Browserctl.build_logger(opts[:log_level], log_path: log_path, component: "daemon")
+daemon_jsonl_log = File.join(Browserctl.log_dir, "daemon.log")
 begin
   Browserctl::Server.new(
     headless: !opts[:headed],
@@ -45,4 +48,8 @@ begin
   ).run
 rescue Browserctl::BrowserNotFound => e
   abort e.message
+rescue Exception => e # rubocop:disable Lint/RescueException
+  crash_path = Browserctl::CrashReport.write(error: e, log_path: daemon_jsonl_log)
+  warn "browserd crashed — crash report: #{crash_path}" if crash_path
+  raise
 end

data/lib/browserctl/client.rb

@@ -15,7 +15,7 @@ module Browserctl
 
     def call(cmd, **params)
       result = communicate(JSON.generate({ cmd: cmd }.merge(params)))
-      Recording.append(cmd, **params) if result[:ok]
+      Recording.append(cmd, response: result, **params) if result[:ok]
       result
     rescue Errno::ENOENT, Errno::ECONNREFUSED
       raise DaemonUnavailableError, "browserd is not running — start it with: browserd"
@@ -50,7 +50,8 @@ module Browserctl
     def click(name, selector = nil, ref: nil)
       raise ArgumentError, "click: provide selector or ref:" unless selector || ref
 
-      call("click", name: name, selector: selector, ref: ref)
+      call("click", name: name, selector: selector, ref: ref,
+                    capture_post_snapshot: Recording.active ? true : nil)
     end
 
     # Fills an input element with a value.
@@ -62,7 +63,8 @@ module Browserctl
     def fill(name, selector = nil, value = nil, ref: nil)
       raise ArgumentError, "fill: provide selector or ref:" unless selector || ref
 
-      call("fill", name: name, selector: selector, ref: ref, value: value)
+      call("fill", name: name, selector: selector, ref: ref, value: value,
+                   capture_post_snapshot: Recording.active ? true : nil)
     end
 
     # Takes a screenshot of a named page.
@@ -180,7 +182,7 @@ module Browserctl
     # @param path [String] file path to read cookies from
     # @return [Hash] `{ ok: true, count: }` or `{ error: }`
     def import_cookies(name, path)
-      raise "cookie file not found: #{path}" unless File.exist?(path)
+      raise Browserctl::Error, "cookie file not found: #{path}" unless File.exist?(path)
 
       cookies = JSON.parse(File.read(path), symbolize_names: true)
       call("import_cookies", name: name, cookies: cookies)
@@ -308,6 +310,48 @@ module Browserctl
       call("session_delete", session_name: session_name)
     end
 
+    # Saves browser state (cookies + storage) into a single .bctl bundle.
+    # @return [Hash] `{ ok:, path:, origins:, cookies:, encrypted: }` or `{ error: }`
+    def state_save(name, origins: nil, flow: nil, flow_version: nil, passphrase: nil)
+      call("state_save",
+           name: name, origins: origins, flow: flow,
+           flow_version: flow_version, passphrase: passphrase)
+    end
+
+    # Restores a .bctl bundle into the running daemon. The daemon runs the
+    # auth_required detector against the bundle's cookies before applying;
+    # callers that have already verified the bundle (e.g. workflow
+    # `load_state` after a successful rotate) can pass `skip_auth_check: true`
+    # to bypass it.
+    def state_load(name, passphrase: nil, skip_auth_check: false)
+      call("state_load", name: name, passphrase: passphrase, skip_auth_check: skip_auth_check)
+    end
+
+    # Lists all stored state bundles (manifest only — no payload decryption).
+    def state_list = call("state_list")
+
+    # Reads a single bundle's manifest.
+    def state_info(name) = call("state_info", name: name)
+
+    # Permanently deletes a state bundle.
+    def state_delete(name) = call("state_delete", name: name)
+
+    # Runs the auth_required detector against a named page. Returns either
+    # `{ ok: true, auth_required: false }` or an AUTH_REQUIRED error response.
+    # @param name [String] page name
+    # @param include_cookies [Boolean] also feed the page's current cookies
+    #   into the detector (catches expired-cookie auth)
+    # @param state [String, nil] bundle name the caller was working with;
+    #   passed back verbatim so callers can recover without bookkeeping
+    # @param suggested_flow [String, nil] flow name to surface when triggered
+    def auth_check(name, include_cookies: false, state: nil, suggested_flow: nil)
+      call("auth_check",
+           name: name,
+           include_cookies: include_cookies,
+           state: state,
+           suggested_flow: suggested_flow)
+    end
+
     private
 
     def auto_discover_socket
@@ -327,10 +371,10 @@ module Browserctl
     end
 
     def read_response(sock)
-      raise "browserd response timeout after 60s" unless sock.wait_readable(60)
+      raise DaemonUnavailableError, "browserd response timeout after 60s" unless sock.wait_readable(60)
 
       raw = sock.gets
-      raise "browserd closed connection" unless raw
+      raise DaemonUnavailableError, "browserd closed connection" unless raw
 
       JSON.parse(raw.chomp, symbolize_names: true)
     end

data/lib/browserctl/commands/cli_output.rb

@@ -1,15 +1,48 @@
 # frozen_string_literal: true
 
+require "json"
+require_relative "../errors"
+require_relative "../error/suggested_actions"
+
 module Browserctl
   module Commands
     module CliOutput
+      AUTH_REQUIRED_EXIT_CODE = Browserctl::AuthRequiredError::AUTH_REQUIRED_EXIT_CODE
+
       def print_result(res)
-        if res.is_a?(Hash) && res[:error]
-          warn "Error: #{res[:error]}"
-          exit 1
+        if res.is_a?(Hash) && (res[:error] || res["error"])
+          message = res[:error] || res["error"]
+          warn "Error: #{message}"
+          warn structured_error_line(res, message)
+          puts res.to_json
+          exit exit_code_for(res)
         end
         puts res.to_json
       end
+
+      # Maps a daemon error response onto a process exit code. Defaults to 1;
+      # special-cased only for codes that callers programmatically branch on.
+      def exit_code_for(res)
+        return AUTH_REQUIRED_EXIT_CODE if (res[:code] || res["code"]) == "AUTH_REQUIRED"
+
+        1
+      end
+
+      # Builds the single-line structured payload emitted to stderr after
+      # the human-readable line. Agents parse this JSON deterministically.
+      # Shape: { code, message, context, suggested_action }.
+      def structured_error_line(res, message)
+        code    = (res[:code] || res["code"] || Browserctl::Error::Codes::GENERIC).to_s
+        context = res[:context] || res["context"] || {}
+        action  = res[:suggested_action] || res["suggested_action"] ||
+                  Browserctl::Error::SuggestedActions.for(code)
+        JSON.generate(
+          code: code,
+          message: message,
+          context: context,
+          suggested_action: action
+        )
+      end
     end
   end
 end