portage-cli 0.7.0 → 0.7.3

data/lib/portage/cli/doctor.rb

@@ -1,5 +1,8 @@
 require "portage/ucp"
+require "uri"
 require_relative "confidence_check"
+require_relative "user_agent"
+require_relative "proxy_settings"
 
 module Portage
   module Cli
@@ -15,8 +18,9 @@ module Portage
     class Doctor
       Finding = Struct.new(:check, :message, keyword_init: true)
 
-      def initialize(adapter_class: nil)
+      def initialize(adapter_class: nil, proxy_settings: ProxySettings.new)
         @adapter_class = adapter_class
+        @proxy_settings = proxy_settings
       end
 
       def call
@@ -26,6 +30,9 @@ module Portage
           signing_keys_finding,
           payment_handlers_finding,
           decision_backend_finding,
+          user_agent_finding,
+          proxy_finding,
+          *proxy_doctor_findings,
           *capability_findings
         ].compact
       end
@@ -71,6 +78,80 @@ 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
+
+      # 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 +187,8 @@ 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"

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

data/lib/portage/cli/handoff_reconciler.rb

@@ -0,0 +1,249 @@
+require "time"
+require "uri"
+require "portage/ucp"
+require "portage/ucp/client"
+require "portage/ucp/journal"
+require_relative "user_agent"
+require_relative "homepage_fetch"
+require_relative "handoff_spend_mode"
+require_relative "reconcile_notifier"
+require_relative "permissive_authenticator"
+require_relative "handoff_reconciler/wire_adapters"
+
+module Portage
+  module Cli
+    # docs/plans/handoff-reconcile.md Phase 1 — resolves a single pending
+    # `settled_by: "shopper"` TransactionLog record: did the shopper finish
+    # the checkout `portage buy` handed them, in the browser, on their own?
+    #
+    # Never infers success from a vanished checkout, a 404, or a plain
+    # expiry with no answer — those settle `failed` with `resolution:
+    # "unknown"`/`"expired"`, never `complete`. Only a `completed` status the
+    # store itself reports settles `complete`. Idempotent: a record that's
+    # already terminal (`complete`/`failed`) is a no-op, so `portage buy
+    # --wait` and a cron `portage orders reconcile` racing each other never
+    # double-settle.
+    class HandoffReconciler
+      # Raised when the store can't be reached again at all (no native UCP
+      # manifest, no matching/configured platform adapter) — the record
+      # stays pending; a later run (or a shorter-lived credential/env
+      # problem being fixed) may still resolve it.
+      class ReconnectError < StandardError; end
+
+      # `checkout_status` is the store's own raw status while a record stays
+      # pending (`incomplete`, `ready_for_complete`, …) — nil once settled,
+      # or when the checkout was never found at all. Phase 3's
+      # `HandoffWaiter` reads it to know when to emit a `handoff_status`
+      # NDJSON event under `portage buy --wait --json`.
+      Result = Struct.new(:idempotency_key, :settled, :status, :resolution, :order_id, :amount, :currency,
+                          :checkout_status, :note, keyword_init: true) do
+        def to_h
+          { idempotency_key: idempotency_key, settled: settled, status: status, resolution: resolution,
+            order_id: order_id, amount: amount, currency: currency, checkout_status: checkout_status,
+            note: note }.compact
+        end
+      end
+
+      # @param spend_mode [String] one of HandoffSpendMode::MODES — Phase 2.
+      def initialize(transaction_log: Portage::Ucp::Support::TransactionLog.new,
+                     order_ledger: Portage::Ucp::Support::OrderLedger.new,
+                     journal: Portage::Ucp::Journal::PurchaseJournal.new,
+                     notifier: ReconcileNotifier.new, spend_mode: HandoffSpendMode.resolve, clock: -> { Time.now })
+        @transaction_log = transaction_log
+        @order_ledger = order_ledger
+        @journal = journal
+        @notifier = notifier
+        @spend_mode = spend_mode
+        @clock = clock
+      end
+
+      # @param record [Hash] a TransactionLog record, as returned by
+      #   `#find`/`#all` — expected to have `settled_by: "shopper"`, but
+      #   this checks rather than assumes (see .each_pending_shopper_record).
+      # @return [Result]
+      def call(record)
+        if terminal?(record)
+          return Result.new(idempotency_key: record["idempotency_key"], settled: false, status: record["status"],
+                            note: "already settled")
+        end
+        unless record["settled_by"] == "shopper"
+          return Result.new(idempotency_key: record["idempotency_key"], settled: false,
+                            note: "not a shopper handoff")
+        end
+
+        reconcile(record)
+      end
+
+      # Every `pending`, `settled_by: "shopper"` record in the log — what
+      # `portage orders reconcile` (no `--checkout`) iterates.
+      def self.each_pending_shopper_record(transaction_log)
+        return enum_for(:each_pending_shopper_record, transaction_log) unless block_given?
+
+        transaction_log.each_record do |record|
+          yield record if record["settled_by"] == "shopper" && record["status"] == "pending"
+        end
+      end
+
+      private
+
+      def terminal?(record) = Portage::Ucp::Support::TransactionLog::TERMINAL_STATUSES.include?(record["status"])
+
+      def reconcile(record)
+        session = reconnect(record["store_url"])
+        checkout = session.get_checkout(checkout_id: record["checkout_id"])
+        settle_from_checkout(record, checkout)
+      rescue StandardError => e
+        # A reconnect failure (no automated path back into the store) and a
+        # transport error mid-call are both treated exactly like "not
+        # found" — see the class comment and the plan's outcome table.
+        # Distinguishing a 404 from a timeout from "can't reconnect at all"
+        # buys nothing here: either way, this run learned nothing new about
+        # whether the shopper paid, and the record's own `expires_at` is
+        # still the only thing allowed to turn that into a settle.
+        settle_not_found(record, note: e.message)
+      end
+
+      def settle_from_checkout(record, checkout)
+        case checkout && checkout["status"]
+        when "completed" then settle_complete(record, checkout)
+        when "canceled" then settle_failed(record, resolution: nil)
+        when nil then settle_not_found(record)
+        else
+          if past_expiry?(record)
+            settle_failed(record, resolution: "expired")
+          else
+            still_pending(record, checkout_status: checkout["status"])
+          end
+        end
+      end
+
+      def settle_not_found(record, note: nil)
+        return still_pending(record, note: note) unless past_expiry?(record)
+
+        settle_failed(record, resolution: "unknown", note: note)
+      end
+
+      def past_expiry?(record)
+        expires_at = record["expires_at"]
+        return false unless expires_at
+
+        Time.parse(expires_at) < @clock.call
+      rescue ArgumentError
+        false
+      end
+
+      def still_pending(record, note: nil, checkout_status: nil)
+        Result.new(idempotency_key: record["idempotency_key"], settled: false, status: "pending",
+                   checkout_status: checkout_status, note: note)
+      end
+
+      def settle_failed(record, resolution:, note: nil)
+        updated = @transaction_log.complete(idempotency_key: record["idempotency_key"], status: "failed",
+                                            resolution: resolution)
+        notify(record, updated, result: "failed")
+        Result.new(idempotency_key: record["idempotency_key"], settled: true, status: "failed",
+                   resolution: resolution, note: note)
+      end
+
+      # The store's own reported amount, at settle time — not the
+      # handoff-time snapshot on `record` (the shopper may have changed
+      # quantity/shipping in the browser; see the plan's "Non-negotiable
+      # constraints").
+      def settle_complete(record, checkout)
+        amount = Portage::Ucp::Support::Totals.amount(checkout["totals"])
+        currency = checkout["currency"]
+        counts = @spend_mode != "warn"
+
+        updated = @transaction_log.complete(idempotency_key: record["idempotency_key"], status: "complete",
+                                            amount: amount, currency: currency, counts_toward_caps: counts)
+
+        order_id = record_order(record, checkout)
+        record_journal(record, checkout)
+        notify(record, updated, result: "complete", order_id: order_id)
+
+        Result.new(idempotency_key: record["idempotency_key"], settled: true, status: "complete", order_id: order_id,
+                   amount: amount, currency: currency)
+      end
+
+      # Never blocks the settle above on this — the transaction record is
+      # already `complete` by the time this runs. A failure here just means
+      # the order snapshot/journal entry didn't get written this round; the
+      # money is still correctly recorded either way.
+      def record_order(record, checkout)
+        order = checkout["order"]
+        return nil unless order && order["id"]
+
+        session = reconnect(record["store_url"])
+        order_wire = session.get_order(order_id: order["id"])
+        return order["id"] unless order_wire
+
+        @order_ledger.record(idempotency_key: record["idempotency_key"], order: WireOrder.new(order_wire))
+        order["id"]
+      rescue StandardError
+        order["id"]
+      end
+
+      def record_journal(record, checkout)
+        return unless @journal && checkout["order"]
+
+        @journal.record_checkout(shop: record["shop"], source: "handoff_reconcile",
+                                 checkout: WireCheckout.new(checkout), idempotency_key: record["idempotency_key"])
+      rescue StandardError
+        nil
+      end
+
+      # Best-effort, same posture as Buy#hand_off's own notifier call — a
+      # failed webhook POST never raises out of #call/#reconcile.
+      def notify(record, updated, result:, order_id: nil)
+        payload = { event: "checkout_reconciled", result: result, reason: record["handoff_reason"],
+                    checkout_id: record["checkout_id"], shop: record["shop"], store_url: record["store_url"],
+                    amount: updated["amount"], currency: updated["currency"], order_id: order_id,
+                    resolution: updated["resolution"] }
+        if result == "complete" && record["handoff_reason"] == "policy_blocked" &&
+           @spend_mode != "warn"
+          payload[:cap_overridden_by_shopper] =
+            true
+        end
+        @notifier.call(payload.compact)
+      rescue StandardError
+        nil
+      end
+
+      # --- reconnecting to the store (see the plan's "Reconciling needs the
+      # store again") ---
+
+      def reconnect(store_url)
+        raise ReconnectError, "no store_url on this record" if store_url.to_s.empty?
+
+        uri = URI.parse(store_url)
+        native_session(uri) || adapter_session(uri) ||
+          raise(ReconnectError, "no automated path back into #{store_url}")
+      end
+
+      def native_session(uri)
+        Portage::Ucp::Client.discover(uri.to_s, headers: UserAgent.headers)
+      rescue Portage::Ucp::Client::DiscoveryError
+        nil
+      end
+
+      # Mirrors Buy's own own-store loopback fallback (#adapter_flow) — a
+      # later process re-discovers the platform from the homepage the same
+      # way, and must not assume the original process's session or
+      # credentials still exist, only that this platform's env vars are
+      # still set (see the plan's non-negotiable constraint).
+      def adapter_session(uri)
+        body, headers = HomepageFetch.call(uri)
+        platform = body && Portage::Ucp::Resolver.detect_platform(body, headers)
+        return nil unless platform
+
+        env = Portage::Ucp::Resolver.env_for(platform)
+        return nil unless Portage::Ucp::Resolver.missing_env(platform, env).empty?
+
+        adapter = Portage::Ucp::Resolver.build_adapter(platform, env)
+        Portage::Ucp::Client.for_adapter(adapter, authenticator: PermissiveAuthenticator.new)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/portage/cli/handoff_spend_mode.rb

@@ -0,0 +1,28 @@
+require_relative "config"
+require_relative "setting"
+
+module Portage
+  module Cli
+    # docs/plans/handoff-reconcile.md Phase 2 — how a shopper-paid,
+    # reconciled handoff counts toward the buyer's own spend cap/velocity
+    # limit (Portage::Ucp::PolicyGuard). Same Setting precedence as
+    # CheckoutHandoff/Notifier: flag > PORTAGE_HANDOFF_SPEND_MODE > config.json's
+    # "handoff_spend_mode". Unset, or set to anything not in MODES, is
+    # `block`, the safer default (a shopper's own completed purchase is real
+    # spend; hiding it from the cap would just let the next *agent* purchase
+    # blow through it unnoticed).
+    module HandoffSpendMode
+      ENV_VAR = "PORTAGE_HANDOFF_SPEND_MODE".freeze
+      CONFIG_KEY = "handoff_spend_mode".freeze
+      MODES = %w[block warn precheck].freeze
+      DEFAULT = "block".freeze
+
+      module_function
+
+      def resolve(override: nil, config: Config.load)
+        mode = Setting.resolve(override: override, env: ENV_VAR, config: config, config_key: CONFIG_KEY)
+        MODES.include?(mode) ? mode : DEFAULT
+      end
+    end
+  end
+end

data/lib/portage/cli/handoff_wait_timeout.rb

@@ -0,0 +1,49 @@
+require_relative "config"
+require_relative "setting"
+
+module Portage
+  module Cli
+    # docs/plans/handoff-reconcile.md Phase 3, decision 5 — the ceiling on
+    # `portage buy --wait`'s poll loop (see HandoffWaiter). Same Setting
+    # precedence as HandoffSpendMode/CheckoutHandoff: flag (--wait-timeout)
+    # > PORTAGE_HANDOFF_WAIT_TIMEOUT > config.json's "handoff_wait_timeout".
+    # Unset is 30 minutes; `off` (or `0`) removes the ceiling entirely, so
+    # the wait runs until the checkout's own `expires_at` instead.
+    module HandoffWaitTimeout
+      ENV_VAR = "PORTAGE_HANDOFF_WAIT_TIMEOUT".freeze
+      CONFIG_KEY = "handoff_wait_timeout".freeze
+      DEFAULT = 1800 # 30 minutes.
+      OFF_VALUES = %w[off 0].freeze
+      DURATION_UNITS = { "s" => 1, "m" => 60, "h" => 3600 }.freeze
+
+      module_function
+
+      # @return [Integer, nil] seconds to wait, or nil for "no ceiling" —
+      #   the caller then waits only on the checkout's own `expires_at`.
+      def resolve(override: nil, config: Config.load)
+        raw = Setting.resolve(override: override, env: ENV_VAR, config: config, config_key: CONFIG_KEY)
+        raw.nil? ? DEFAULT : parse(raw)
+      end
+
+      def parse(raw)
+        text = raw.to_s.strip.downcase
+        return nil if OFF_VALUES.include?(text)
+
+        seconds = parse_duration(text)
+        seconds&.positive? ? seconds : DEFAULT
+      end
+
+      # Accepts a bare integer (seconds) or a suffixed duration (`30m`,
+      # `1h`, `45s`) — `--wait-timeout` is a human-typed flag, not a raw
+      # second count like `--rolling-window-seconds`.
+      def parse_duration(text)
+        return text.to_i if text.match?(/\A\d+\z/)
+
+        match = text.match(/\A(\d+)([smh])\z/)
+        return nil unless match
+
+        match[1].to_i * DURATION_UNITS.fetch(match[2])
+      end
+    end
+  end
+end

data/lib/portage/cli/handoff_waiter.rb

@@ -0,0 +1,103 @@
+require "time"
+require_relative "handoff_reconciler"
+require_relative "handoff_wait_timeout"
+
+module Portage
+  module Cli
+    # docs/plans/handoff-reconcile.md Phase 3 — `portage buy --wait`'s poll
+    # loop. Polls a single pending shopper record through HandoffReconciler
+    # with backoff (2s -> 30s, plus jitter) until it settles or its deadline
+    # passes. Every decision about what a poll *means* stays
+    # HandoffReconciler's; this only decides when to poll again and when to
+    # stop.
+    #
+    # Ctrl-C: Ruby's default SIGINT handling raises Interrupt on the main
+    # thread, most likely while this is asleep between polls. Caught here so
+    # it never crashes the process with a backtrace — the record is already
+    # pending in the transaction log either way (see the plan's
+    # non-negotiable "the handoff itself never waits on reconcile"), so
+    # there's nothing to undo. It's left exactly as it is for a later
+    # `portage orders reconcile`; this never settles on interrupt.
+    class HandoffWaiter
+      INITIAL_BACKOFF = 2
+      MAX_BACKOFF = 30
+
+      def initialize(reconciler:, transaction_log:, wait_timeout_override: nil, clock: -> { Time.now },
+                     sleeper: ->(seconds) { Kernel.sleep(seconds) })
+        @reconciler = reconciler
+        @transaction_log = transaction_log
+        @wait_timeout_override = wait_timeout_override
+        @clock = clock
+        @sleeper = sleeper
+      end
+
+      # @param record [Hash] the pending TransactionLog record to poll —
+      #   typically fresh from the same log this was built with.
+      # @yield [Symbol, HandoffReconciler::Result] `:status` on every
+      #   store-reported checkout status change (never on the first poll's
+      #   initial status), `:settled` exactly once, when the loop ends
+      #   because the record actually settled (never on a timeout or
+      #   interrupt).
+      # @return [HandoffReconciler::Result] the last poll's result — settled
+      #   if it settled, otherwise still pending (deadline reached or
+      #   interrupted).
+      def call(record, &on_event)
+        deadline = compute_deadline(record)
+        backoff = INITIAL_BACKOFF
+        last_checkout_status = nil
+        loop do
+          current = @transaction_log.find(record["idempotency_key"]) || record
+          result = @reconciler.call(current)
+          last_checkout_status = emit_status(result, last_checkout_status, on_event)
+          return emit_settled(result, on_event) if result.settled
+          return result if @clock.call >= deadline
+
+          @sleeper.call(backoff_with_jitter(backoff))
+          backoff = [backoff * 2, MAX_BACKOFF].min
+        end
+      rescue Interrupt
+        HandoffReconciler::Result.new(idempotency_key: record["idempotency_key"], settled: false, status: "pending",
+                                      note: "wait interrupted")
+      end
+
+      private
+
+      def emit_status(result, last_checkout_status, on_event)
+        return last_checkout_status unless result.checkout_status && result.checkout_status != last_checkout_status
+
+        on_event&.call(:status, result)
+        result.checkout_status
+      end
+
+      def emit_settled(result, on_event)
+        on_event&.call(:settled, result)
+        result
+      end
+
+      # The earlier of `handoff_wait_timeout` (default 30m, `off` removes
+      # it) and the checkout's own `expires_at`. If somehow neither is set
+      # (no expires_at on the record, and the timeout resolved to nil), the
+      # default timeout still applies as a floor — this loop must not spin
+      # forever with no deadline at all.
+      def compute_deadline(record)
+        started = @clock.call
+        timeout = HandoffWaitTimeout.resolve(override: @wait_timeout_override)
+        candidates = [(started + timeout if timeout), expires_at(record)].compact
+        candidates.min || (started + HandoffWaitTimeout::DEFAULT)
+      end
+
+      def expires_at(record)
+        value = record["expires_at"]
+        return nil unless value
+
+        Time.parse(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def backoff_with_jitter(backoff)
+        backoff + Random.rand(backoff * 0.25)
+      end
+    end
+  end
+end

data/lib/portage/cli/homepage_fetch.rb

@@ -0,0 +1,41 @@
+require "net/http"
+require "uri"
+require "portage/ucp/support/connection"
+require_relative "user_agent"
+
+module Portage
+  module Cli
+    # Shared "fetch this store's homepage, for platform sniffing" logic —
+    # originally private to Buy (#fetch_homepage), extracted so
+    # HandoffReconciler's own adapter-fallback reconnect (see
+    # docs/plans/handoff-reconcile.md, "Reconciling needs the store again")
+    # doesn't duplicate it.
+    module HomepageFetch
+      REDIRECT_LIMIT = 5
+
+      # @return [Array(String, Hash), Array(nil, Hash)] the body and response
+      #   headers, or [nil, {}] on any failure/redirect exhaustion — same
+      #   "no automated path, not a crash" posture as the rest of the buy
+      #   flow.
+      def self.call(uri, limit: REDIRECT_LIMIT)
+        return [nil, {}] if limit.zero?
+
+        response = Portage::Ucp::Support::Connection.start(uri, route: :store, open_timeout: 5,
+                                                                read_timeout: 5) do |http|
+          http.get(uri.request_uri, UserAgent.headers)
+        end
+
+        case response
+        when Net::HTTPRedirection
+          call(URI.join(uri, response["location"]), limit: limit - 1)
+        when Net::HTTPSuccess
+          [response.body, response.to_hash]
+        else
+          [nil, {}]
+        end
+      rescue StandardError
+        [nil, {}]
+      end
+    end
+  end
+end