portage-cli 0.7.0 → 0.7.4

data/lib/portage/cli/buy.rb

@@ -10,6 +10,13 @@ require_relative "decisions"
 require_relative "confidence_check"
 require_relative "checkout_handoff"
 require_relative "notifier"
+require_relative "user_agent"
+require_relative "homepage_fetch"
+require_relative "permissive_authenticator"
+require_relative "handoff_reconciler"
+require_relative "handoff_spend_mode"
+require_relative "webmcp"
+require_relative "webmcp_checkout_mode"
 
 module Portage
   module Cli
@@ -49,13 +56,26 @@ module Portage
       #   rolling cap and velocity limit count. nil (the default) is the
       #   real ~/.portage/transactions.json, the file Dispatcher writes for
       #   own-store purchases.
-      # rubocop:disable Metrics/ParameterLists -- all keywords; one per flag, plus two injectable collaborators
+      # @param max_price [Integer, nil] the most one unit may cost, in minor
+      #   units (same as Find's). A product priced above it is never picked,
+      #   even with a --product-id; one with no price to go on still is, as
+      #   in Find, and the checkout's own total then meets the spend policy.
+      # @param webmcp_bridge [#list_tools, #execute_tool, nil] docs/plans/
+      #   handoff-reconcile.md Phase 4 — a `portage-ucp-webmcp` outbound
+      #   Bridge (already pointed at a navigated page) an embedding caller
+      #   already holds. nil (the default, and the only option from the
+      #   `portage buy` CLI, which has no browser of its own) skips WebMCP
+      #   entirely — zero behavior change from before this parameter
+      #   existed. Given one, attempted after native-UCP discovery finds
+      #   nothing at this URL and before a platform-adapter fallback (see
+      #   #webmcp_flow).
+      # rubocop:disable Metrics/ParameterLists -- all keywords; one per flag, plus injectable collaborators
       def initialize(url:, query:, qty: 1, payment_token: nil, yes: false, dry_run: false, product_id: nil,
-                     auto_open: nil, notify_webhook: nil, confidence_check: nil, transaction_log: nil)
+                     auto_open: nil, notify_webhook: nil, confidence_check: nil, transaction_log: nil,
+                     max_price: nil, webmcp_bridge: nil)
         # rubocop:enable Metrics/ParameterLists
         raw = url.to_s.strip
-        raw = "https://#{raw}" unless raw =~ %r{\Ahttps?://}i
-        @uri = URI.parse(raw)
+        @uri = URI.parse(raw =~ %r{\Ahttps?://}i ? raw : "https://#{raw}")
         @query = query
         @qty = qty
         @payment_token = payment_token
@@ -66,6 +86,8 @@ module Portage
         @notify_webhook = notify_webhook
         @confidence_check = confidence_check
         @transaction_log = transaction_log
+        @max_price = max_price
+        @webmcp_bridge = webmcp_bridge
         @decisions = {}
       end
 
@@ -84,6 +106,9 @@ module Portage
           return native_flow(session) if session
         end
 
+        webmcp_result = webmcp_flow
+        return webmcp_result if webmcp_result
+
         platform = Portage::Ucp::Resolver.detect_platform(body, headers)
         adapter_flow(platform) || dead_end
       end
@@ -93,7 +118,7 @@ module Portage
       # --- Step 1: native UCP manifest ---
 
       def discover(url)
-        Portage::Ucp::Client.discover(url.to_s)
+        Portage::Ucp::Client.discover(url.to_s, headers: UserAgent.headers)
       rescue Portage::Ucp::Client::ManifestShapeError => e
         # The store *is* running UCP — this client just couldn't parse its
         # manifest. Distinct from a genuine 404/unreachable host below:
@@ -200,6 +225,64 @@ module Portage
         match && URI.join(@uri, match[1])
       end
 
+      # --- Step 1b: WebMCP outbound (docs/plans/handoff-reconcile.md Phase 4) ---
+      #
+      # Opt-in only: nil unless a caller passed `webmcp_bridge:` (see
+      # #initialize), so `portage buy` from the shell — with no browser of
+      # its own — sees no behavior change here at all. Attempted after
+      # native-UCP discovery finds nothing at this URL and before falling
+      # back to a platform adapter, since a WebMCP page, like native UCP,
+      # works without this process holding the store's own credentials.
+      #
+      # `express_stop` (the only implemented mode) builds the cart and
+      # checkout, then always hands off rather than attempting
+      # #complete_checkout — which a WebMCP page doesn't expose by default
+      # in the first place (ToolCatalog leaves it out: it needs a
+      # server-side Confirmer swap this gem doesn't have a seam for yet).
+      # That hand-off feeds Phases 1-3 completely unchanged: reason
+      # `express_stop` reserves a pending record, notifies, and later
+      # reconciles exactly like any other hand-off.
+      def webmcp_flow
+        return nil unless @webmcp_bridge
+        return webmcp_not_installed_report unless Portage::Cli::Webmcp.available?
+
+        session = Portage::Ucp::WebMcp.connect(bridge: @webmcp_bridge)
+        return nil unless session.advertises?(CART_CAP) && session.advertises?(CHECKOUT_CAP)
+
+        return webmcp_token_unsupported_report if webmcp_checkout_mode == "token"
+
+        full_buy(session, source: "webmcp", force_handoff: true)
+      rescue Portage::Ucp::WebMcp::BridgeError, Portage::Ucp::WebMcp::ToolNotFoundError,
+             Portage::Ucp::Client::ServerError => e
+        build_report(source: "webmcp", outcome: "webmcp_error", browse: false, checkout: false,
+                     message: "WebMCP checkout failed: #{e.message}")
+      end
+
+      def webmcp_checkout_mode
+        Portage::Cli::WebmcpCheckoutMode.resolve
+      end
+
+      def webmcp_not_installed_report
+        build_report(source: "webmcp", outcome: "webmcp_not_installed", browse: false, checkout: false,
+                     message: "A WebMCP bridge was given but portage-ucp-webmcp isn't installed — " \
+                              "`gem install portage-ucp-webmcp`.")
+      end
+
+      # `token` mode isn't implemented: it needs `Mcp::Server.build` to swap
+      # in a payment-token Confirmer for a WebMCP session (see
+      # portage-ucp-webmcp's README, "complete_checkout"), plus PayPal/Stripe
+      # agent-token enrollment in `portage payment enroll` — neither exists
+      # yet (docs/plans/handoff-reconcile.md Phase 4 is explicitly a sketch
+      # pending that design). Fails loudly here rather than silently
+      # behaving like `express_stop`, so a caller who configured `token`
+      # notices instead of getting a hand-off they didn't ask for.
+      def webmcp_token_unsupported_report
+        build_report(source: "webmcp", outcome: "webmcp_token_unsupported", browse: false, checkout: false,
+                     message: "webmcp_checkout_mode=token isn't supported yet — see " \
+                              "docs/plans/handoff-reconcile.md Phase 4. Use express_stop (the default), or " \
+                              "complete the checkout via the page's own payment button.")
+      end
+
       # --- Step 2/3: platform detection + adapter fallback ---
 
       def adapter_flow(platform)
@@ -296,7 +379,11 @@ module Portage
       # remote store, so shipping-address/rate selection stays loopback-only
       # for now rather than guessing at a wire shape no real UCP server has
       # confirmed (see docs/design-log.md).
-      def full_buy(session, source:, fulfillment_adapter: nil)
+      # @param force_handoff [Boolean] docs/plans/handoff-reconcile.md Phase
+      #   4's `express_stop` — skips escalation/confirmation/completion
+      #   entirely and always hands the built checkout off, once past the
+      #   `--dry-run` check. Only #webmcp_flow ever sets this.
+      def full_buy(session, source:, fulfillment_adapter: nil, force_handoff: false)
         products = safe_search(session)
         product = select_product(products)
         unless product
@@ -310,7 +397,7 @@ module Portage
         checkout = select_cheapest_shipping(session, checkout) if fulfillment_adapter
 
         warnings = reconcile_checkout(product, checkout)
-        finish_checkout(session, source, products, checkout, warnings)
+        finish_checkout(session, source, products, checkout, warnings, force_handoff: force_handoff)
       end
 
       # A store can silently drop the requested line, change its quantity, or
@@ -406,9 +493,10 @@ module Portage
       end
 
       def no_match_message
-        return "No product matched \"#{@query}\"." unless @product_id
+        budget = @max_price ? " at or under #{@max_price} minor units" : ""
+        return "No product matched \"#{@query}\"#{budget}." unless @product_id
 
-        "Product #{@product_id} isn't in this store's results for \"#{@query}\"."
+        "Product #{@product_id} isn't in this store's results for \"#{@query}\"#{budget}."
       end
 
       # With a --product-id, that exact product or nothing: falling back to the
@@ -420,12 +508,28 @@ module Portage
       # when an in-stock match sits right below it (confirmed live
       # 2026-09-23 on allbirds.com and billabong.com). Falls back to the top
       # hit when nothing reports stock, so the store still gets to answer.
+      #
+      # Either way, only among products within --max-price: before it
+      # reached here, `buy <url> --max-price` checked out whatever the store
+      # ranked first (confirmed live 2026-09-24: a $679.95 board on
+      # burton.com under --max-price 600).
       def select_product(products)
+        products = products.select { |product| within_max_price?(product) }
         return products.find { |product| available?(product) } || products.first unless @product_id
 
         products.find { |product| product_id_of(product) == @product_id }
       end
 
+      # Priced the way #reconcile_checkout expects the store to charge: the
+      # variant #line_item_id_of would check out, else the product's lowest
+      # price.
+      def within_max_price?(product)
+        return true unless @max_price
+
+        price = expected_unit_price(product, line_item_id_of(product))
+        price.nil? || price <= @max_price
+      end
+
       # A product with no variant availability to go on counts as buyable —
       # only an explicit `available: false` on every variant rules it out.
       def available?(product)
@@ -462,10 +566,11 @@ module Portage
           product_id_of(product)
       end
 
-      def finish_checkout(session, source, products, checkout, warnings = [])
+      def finish_checkout(session, source, products, checkout, warnings = [], force_handoff: false)
         escalation = decide_escalation(checkout, warnings)
         return escalated_report(source, products, checkout, warnings, escalation) if escalation[:escalate]
         return dry_run_report(source, products, checkout, warnings) if @dry_run
+        return webmcp_handoff_report(source, products, checkout, warnings) if force_handoff
         return confirmation_needed_report(source, products, checkout, warnings) unless confirmed?
 
         complete(session, source, products, checkout, warnings)
@@ -670,10 +775,23 @@ module Portage
       # relay and an agent loop branch on the same value.
       def handoff_report(source, products, checkout, warnings, outcome:, message:)
         handoff = hand_off(checkout, reason: outcome, source: source, message: message, warnings: warnings)
-        checkout_report(source, products, checkout, outcome: outcome, warnings: warnings, message: message,
+        checkout_report(source, products, checkout, outcome: outcome, message: message,
+                                                    warnings: warnings + Array(@pending_handoff_warning),
                                                     checkout_url: checkout_url_of(checkout), handoff: handoff)
       end
 
+      # docs/plans/handoff-reconcile.md Phase 4 — #webmcp_flow's
+      # `express_stop` mode. Reuses #handoff_report as-is: reason
+      # `express_stop` reserves a pending shopper record and fires
+      # auto-open/notify exactly like any other hand-off (Phases 1-3 apply
+      # unchanged), even though it got here because a mode setting chose to
+      # stop, not because anything was denied or escalated.
+      def webmcp_handoff_report(source, products, checkout, warnings)
+        message = "Cart and checkout are built — finish payment with the store's own express-pay button " \
+                  "on the page."
+        handoff_report(source, products, checkout, warnings, outcome: "express_stop", message: message)
+      end
+
       # Never fires on --dry-run (a dry run creates a real checkout but never
       # attempts completion — auto-opening/notifying over a preview run would
       # be actively wrong), and never fires without a checkout_url to hand
@@ -685,15 +803,67 @@ module Portage
       # The webhook body carries the report's own `message`, plus the store
       # and the shopper's query, so a Slack/Zapier relay can post it as-is
       # without a lookup back into this process.
+      #
+      # Also where docs/plans/handoff-reconcile.md Phase 1 records a pending
+      # `settled_by: "shopper"` TransactionLog row (best-effort — a failed
+      # write surfaces as a warning, never blocks the hand-off itself), and
+      # where Phase 2's `precheck` spend mode suppresses auto-open when this
+      # checkout's total would already exceed the buyer's own spend cap.
       def hand_off(checkout, reason:, source:, message:, warnings:)
         url = checkout_url_of(checkout)
         return nil if @dry_run || url.nil?
 
-        opened = CheckoutHandoff.new(auto_open: @auto_open).call(url)
-        error = notifier.call(event: "checkout_handoff", reason: reason, message: message, store: @uri.to_s,
-                              query: @query, checkout_url: url, checkout_id: checkout["id"], source: source,
-                              totals: checkout["totals"], warnings: warnings)
-        { url: url, opened: opened, notified: notifier.enabled? && error.nil?, notify_error: error }
+        over_cap = precheck_mode? && over_spend_cap?(checkout)
+        record_pending_handoff(checkout, reason: reason)
+
+        opened = over_cap ? false : CheckoutHandoff.new(auto_open: @auto_open).call(url)
+        error = notifier.call(handoff_notify_payload(checkout, url, reason: reason, source: source, message: message,
+                                                                    warnings: warnings, over_cap: over_cap))
+        result = { url: url, opened: opened, notified: notifier.enabled? && error.nil?, notify_error: error }
+        over_cap ? result.merge(over_cap: true) : result
+      end
+
+      def handoff_notify_payload(checkout, url, reason:, source:, message:, warnings:, over_cap:)
+        payload = { event: "checkout_handoff", reason: reason, message: message, store: @uri.to_s,
+                    query: @query, checkout_url: url, checkout_id: checkout["id"], source: source,
+                    totals: checkout["totals"], warnings: warnings }
+        over_cap ? payload.merge(over_cap: true) : payload
+      end
+
+      # Never raises: a record that can't be written is a warning on the
+      # report (surfaced via @pending_handoff_warning, see #handoff_report),
+      # not a reason to fail the hand-off itself — same posture as
+      # #settle_transaction's own @unrecorded_warning.
+      def record_pending_handoff(checkout, reason:)
+        transaction_log.reserve(idempotency_key: handoff_transaction_key(checkout), checkout_id: checkout["id"],
+                                shop: @uri.host, payment_token_ref: token_ref, amount: checkout_total(checkout),
+                                currency: checkout["currency"], settled_by: "shopper", handoff_reason: reason,
+                                store_url: @uri.to_s, expires_at: checkout["expires_at"])
+      rescue StandardError => e
+        @pending_handoff_warning = "Couldn't save this hand-off for later reconcile (#{e.message}) — " \
+                                   "run `portage orders reconcile --checkout #{checkout['id']}` once fixed, " \
+                                   "or it'll never be picked up automatically."
+      end
+
+      def handoff_transaction_key(checkout)
+        "portage-buy:#{@uri.host}:#{checkout['id']}"
+      end
+
+      def precheck_mode?
+        Portage::Cli::HandoffSpendMode.resolve == "precheck"
+      end
+
+      # Same PolicyGuard the buyer's own spend cap already goes through
+      # (#decide_policy) — reused here so a hand-off that never reached
+      # #decide_policy at all (escalation, permission_denied, no_payment_token,
+      # checkout_mismatch) still gets the buyer a heads-up that finishing
+      # this checkout by hand would blow the cap, before they do.
+      def over_spend_cap?(checkout)
+        Portage::Ucp::PolicyGuard.check!(amount: checkout_total(checkout), currency: checkout["currency"],
+                                         merchant: @uri.host, token_ref: token_ref, transaction_log: transaction_log)
+        false
+      rescue Portage::Ucp::PolicyViolationError
+        true
       end
 
       def notifier
@@ -796,23 +966,7 @@ module Portage
       # catalog-only-native adapter-checkout-fallback path) ---
 
       def fetch_homepage(uri, limit = REDIRECT_LIMIT)
-        return [nil, {}] if limit.zero?
-
-        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                                                       open_timeout: 5, read_timeout: 5) do |http|
-          http.get(uri.request_uri, { "User-Agent" => "portage-buy" })
-        end
-
-        case response
-        when Net::HTTPRedirection
-          fetch_homepage(URI.join(uri, response["location"]), limit - 1)
-        when Net::HTTPSuccess
-          [response.body, response.to_hash]
-        else
-          [nil, {}]
-        end
-      rescue StandardError
-        [nil, {}]
+        HomepageFetch.call(uri, limit: limit)
       end
 
       def dead_end
@@ -823,14 +977,6 @@ module Portage
       def build_report(**fields)
         { url: @uri.to_s, checkout_url: nil, products: [], warnings: [] }.merge(fields)
       end
-
-      # Loopback buy against your own store needs *some* authenticator (§9
-      # rejects anonymous mutation by default) — since this process already
-      # has this platform's own credentials (that's the gate to even reach
-      # here), authenticating this local CLI session is reasonable.
-      class PermissiveAuthenticator < Portage::Ucp::Authenticator
-        def call(_server_context) = :local_cli
-      end
     end
   end
 end

data/lib/portage/cli/doctor.rb

@@ -1,5 +1,9 @@
 require "portage/ucp"
+require "uri"
 require_relative "confidence_check"
+require_relative "user_agent"
+require_relative "proxy_settings"
+require_relative "shipping_profile"
 
 module Portage
   module Cli
@@ -13,19 +17,33 @@ module Portage
     # process, so a host app passes `--require` to load its own initializer
     # first (Rails: `--require ./config/environment`).
     class Doctor
-      Finding = Struct.new(:check, :message, keyword_init: true)
+      # `level` is "warning" (something to fix; any one makes doctor exit 1)
+      # or "info" (a report, e.g. how portage was installed). `details` is
+      # structured data for `--json`; `to_h` drops it when there is none.
+      Finding = Struct.new(:check, :message, :level, :details, keyword_init: true) do
+        def initialize(level: "warning", **) = super
+        def warning? = level == "warning"
+        def to_h = super.compact
+      end
 
-      def initialize(adapter_class: nil)
+      def initialize(adapter_class: nil, proxy_settings: ProxySettings.new, install_doctor: InstallDoctor.new)
         @adapter_class = adapter_class
+        @proxy_settings = proxy_settings
+        @install_doctor = install_doctor
       end
 
       def call
         [
+          *@install_doctor.findings,
           authenticator_finding,
           rate_limiter_finding,
           signing_keys_finding,
           payment_handlers_finding,
           decision_backend_finding,
+          user_agent_finding,
+          shipping_finding,
+          proxy_finding,
+          *proxy_doctor_findings,
           *capability_findings
         ].compact
       end
@@ -71,6 +89,110 @@ module Portage
         Finding.new(check: "decision_backend", message: e.message)
       end
 
+      # PORTAGE_USER_AGENT / config.json's "user_agent" (UserAgent) is sent
+      # as-is on every outbound request. Net::HTTP raises ArgumentError on a
+      # header value containing CR/LF rather than send it, so a bad override
+      # would otherwise surface for the first time mid-checkout instead of
+      # here.
+      def user_agent_finding
+        value = Portage::Cli::UserAgent.value
+        return unless value =~ /[\r\n]/
+
+        Finding.new(check: "user_agent",
+                    message: "Configured User-Agent (PORTAGE_USER_AGENT or user_agent in " \
+                             "~/.portage/config.json) contains a newline — every outbound request will " \
+                             "raise instead of sending.")
+      end
+
+      # PORTAGE_SHIP_* (ShippingProfile, BuyerContext) has two jobs, and both
+      # fail quietly: with no complete address an own-store checkout goes
+      # out with no shipping destination, and with no PORTAGE_SHIP_COUNTRY a
+      # native UCP store gets no buyer context, so a live Shopify store
+      # builds a cart in no market and reports in-stock items as
+      # `merchandise_out_of_stock` (docs/ucp-tool-gating-investigation.md).
+      def shipping_finding
+        missing = ShippingProfile::REQUIRED.map { |key| ShippingProfile::ENV_VARS.fetch(key) }
+                                           .select { |var| ENV[var].to_s.empty? }
+        return if missing.empty?
+
+        Finding.new(check: "shipping", message: "#{shipping_gap(missing)} Export them in your shell; " \
+                                                ".env.example lists every PORTAGE_SHIP_* variable.")
+      end
+
+      def shipping_gap(missing)
+        country = ShippingProfile::ENV_VARS.fetch(:address_country)
+        gap = if missing.length == ShippingProfile::REQUIRED.length
+                "No shipping address set (#{missing.join(', ')})."
+              else
+                "Shipping address incomplete: missing #{missing.join(', ')}, and a partial address is " \
+                  "treated as none."
+              end
+        gap += " `portage buy` sends no shipping destination to your own store's checkout"
+        return "#{gap}." unless missing.include?(country)
+
+        "#{gap}, and without #{country} a native UCP store (e.g. Shopify) gets no market to price in " \
+          "and can report in-stock items as out of stock."
+      end
+
+      # Phase 0 of docs/plans/proxy-support.md: every raw Net::HTTP.start call
+      # site in portage-cli/portage-ucp/the adapter gems resolves its proxy
+      # from Ruby stdlib's own `:ENV` default, which — confirmed against a
+      # real local proxy — only ever reads `http_proxy`/`HTTP_PROXY`, for
+      # *both* http and https targets, and never `https_proxy`/`HTTPS_PROXY`.
+      # That's surprising enough (and the failure silent enough — requests
+      # just go direct) that it's worth a doctor check on both sides: report
+      # the effective proxy when one is actually active, and flag the classic
+      # footgun of setting only HTTPS_PROXY and expecting it to do anything
+      # here.
+      def proxy_finding
+        http_proxy = ENV["http_proxy"] || ENV.fetch("HTTP_PROXY", nil)
+        return https_only_proxy_finding if !http_proxy && https_env_proxy_set?
+
+        return unless http_proxy
+
+        Finding.new(check: "proxy",
+                    message: "Outbound requests proxy through #{redact_proxy_url(http_proxy)} " \
+                             "(from #{ENV['http_proxy'] ? 'http_proxy' : 'HTTP_PROXY'}, used for both http:// " \
+                             "and https:// targets)#{no_proxy_suffix}.")
+      end
+
+      def https_only_proxy_finding
+        Finding.new(check: "proxy",
+                    message: "HTTPS_PROXY/https_proxy is set but http_proxy/HTTP_PROXY is not — Ruby's " \
+                             "Net::HTTP only ever reads http_proxy for its :ENV proxy mode (for both http:// " \
+                             "and https:// targets), so every portage-cli/portage-ucp/adapter call site is " \
+                             "proxying nothing right now. Set http_proxy (it covers https:// targets too) if " \
+                             "that traffic should go through a proxy. (portage-ucp-client's own UCP/MCP tool " \
+                             "calls are the one exception — they're Faraday-based and do read https_proxy.)")
+      end
+
+      def https_env_proxy_set?
+        !(ENV["https_proxy"].to_s.empty? && ENV["HTTPS_PROXY"].to_s.empty?)
+      end
+
+      def no_proxy_suffix
+        no_proxy = ENV["no_proxy"] || ENV.fetch("NO_PROXY", nil)
+        no_proxy ? "; no_proxy=#{no_proxy}" : ""
+      end
+
+      # `http://***@host:port` — never the real credentials (see the plan's
+      # "Credentials stay safe" constraint).
+      def redact_proxy_url(url)
+        uri = URI.parse(url.include?("://") ? url : "http://#{url}")
+        userinfo = uri.userinfo ? "***@" : ""
+        port = uri.port ? ":#{uri.port}" : ""
+        "#{uri.scheme}://#{userinfo}#{uri.host}#{port}"
+      rescue URI::InvalidURIError
+        "(unparseable proxy URL)"
+      end
+
+      # Phase 2's own checks against whatever ProxySettings resolved
+      # (flags/env/config.json), kept separate from proxy_finding above —
+      # see ProxyDoctor's own comment for why the two don't merge.
+      def proxy_doctor_findings
+        ProxyDoctor.new(proxy_settings: @proxy_settings).findings
+      end
+
       def payment_handlers_finding
         return unless Array(config.payment_handlers).empty?
 
@@ -106,3 +228,9 @@ module Portage
     end
   end
 end
+
+# Loaded after Doctor closes — ProxyDoctor calls Doctor::Finding.new, so
+# Doctor has to exist first (this file requires proxy_settings, not
+# proxy_doctor, at the top for exactly this reason).
+require_relative "proxy_doctor"
+require_relative "install_doctor"

data/lib/portage/cli/find.rb

@@ -5,6 +5,7 @@ require "portage/ucp/client"
 require_relative "search_backends"
 require_relative "probe_cache"
 require_relative "decisions"
+require_relative "user_agent"
 
 module Portage
   module Cli
@@ -128,7 +129,7 @@ module Portage
       end
 
       def discover(origin)
-        Portage::Ucp::Client.discover(origin)
+        Portage::Ucp::Client.discover(origin, headers: UserAgent.headers)
       rescue StandardError
         nil
       end

data/lib/portage/cli/handoff_reconciler/wire_adapters.rb

@@ -0,0 +1,50 @@
+module Portage
+  module Cli
+    class HandoffReconciler
+      # Adapts a wire hash (from #get_checkout/#get_order) to what
+      # OrderLedger#record/PurchaseJournal#record_checkout duck-type against
+      # (Portage::Ucp::Order/Checkout value objects) — see
+      # docs/plans/handoff-reconcile.md, "The journal needs a
+      # hash-to-value-object step". Deliberately not a second, parallel
+      # entry shape: both still go through PurchaseJournal#record_checkout /
+      # OrderLedger#record's own logic (`to_wire_h`) — these just wrap the
+      # already-wire-shaped hash to answer the handful of methods each one
+      # calls.
+      WireOrder = Struct.new(:wire) do
+        def id = wire["id"]
+        def to_wire_h = wire
+      end
+
+      WireCheckout = Struct.new(:wire) do
+        def currency = wire["currency"]
+        def order = wire["order"] && WireOrderRef.new(wire["order"])
+
+        def line_items
+          Array(wire["line_items"]).map { |li| WireLineItem.new(li) }
+        end
+      end
+
+      WireOrderRef = Struct.new(:wire) do
+        def id = wire["id"]
+      end
+
+      WireLineItem = Struct.new(:wire) do
+        def item = WireItem.new(wire["item"] || {})
+        def quantity = wire["quantity"]
+
+        def totals
+          Array(wire["totals"]).map { |t| WireTotal.new(t) }
+        end
+      end
+
+      WireItem = Struct.new(:wire) do
+        def id = wire["id"]
+      end
+
+      WireTotal = Struct.new(:wire) do
+        def type = wire["type"]
+        def amount = wire["amount"]
+      end
+    end
+  end
+end