portage-cli 0.7.0 → 0.7.3

data/lib/portage/cli/reconcile_notifier.rb

@@ -0,0 +1,65 @@
+require_relative "notifier"
+require_relative "macos_notifier"
+require_relative "reconcile_notify"
+
+module Portage
+  module Cli
+    # docs/plans/handoff-reconcile.md Phase 3 — fans a settle event
+    # (`checkout_reconciled`, from HandoffReconciler#notify) out to whichever
+    # channels `ReconcileNotify` names. The default `HandoffReconciler`
+    # notifier for both `portage buy --wait` and `portage orders reconcile`,
+    # replacing the plain webhook-only `Notifier` those used through Phase 1.
+    #
+    # Every channel is best-effort, same posture as `Notifier#call` itself —
+    # one channel failing (a bad webhook URL, no `osascript` on this host)
+    # never stops another from firing, and this never raises out of
+    # `HandoffReconciler#notify`, which already wraps the whole call in its
+    # own rescue.
+    class ReconcileNotifier
+      def initialize(channels: ReconcileNotify.resolve, webhook: Notifier.new, macos: MacosNotifier.new)
+        @channels = channels
+        @webhook = webhook
+        @macos = macos
+      end
+
+      def enabled?(channel) = @channels.include?(channel)
+
+      # @return [String, nil] the webhook channel's own failure message, same
+      #   shape `Notifier#call` always returned — the other channels have no
+      #   return-value contract to preserve, since nothing read theirs before
+      #   this class existed.
+      def call(payload)
+        error = @webhook.call(payload) if enabled?("webhook")
+        notify_macos(payload) if enabled?("macos")
+        puts terminal_line(payload) if enabled?("terminal")
+        error
+      end
+
+      private
+
+      def notify_macos(payload)
+        @macos.call(title: "Portage checkout #{payload[:result]}", message: macos_message(payload))
+      end
+
+      def macos_message(payload)
+        parts = [payload[:shop], format_amount(payload[:amount], payload[:currency])].compact
+        parts.empty? ? "checkout #{payload[:checkout_id]}" : parts.join(" — ")
+      end
+
+      def terminal_line(payload)
+        parts = ["[reconcile] #{payload[:checkout_id]}: #{payload[:result]}"]
+        parts << "resolution: #{payload[:resolution]}" if payload[:resolution]
+        parts << "order: #{payload[:order_id]}" if payload[:order_id]
+        amount = format_amount(payload[:amount], payload[:currency])
+        parts << amount if amount
+        parts.join(" — ")
+      end
+
+      def format_amount(amount, currency)
+        return nil unless amount
+
+        "#{format('%.2f', amount / 100.0)}#{" #{currency}" if currency}"
+      end
+    end
+  end
+end

data/lib/portage/cli/reconcile_notify.rb

@@ -0,0 +1,38 @@
+require_relative "config"
+require_relative "setting"
+
+module Portage
+  module Cli
+    # docs/plans/handoff-reconcile.md Phase 3 — which channels fire when a
+    # handoff settles, from `portage buy --wait` or `portage orders
+    # reconcile` (see ReconcileNotifier). A comma list, same Setting
+    # precedence as every other standing preference here: an explicit
+    # `override:` beats PORTAGE_RECONCILE_NOTIFY, which beats config.json's
+    # "reconcile_notify". Unset is `webhook` only.
+    #
+    # "journal" is accepted but drives nothing here: the Phase 1 order
+    # snapshot journal write already happens unconditionally in
+    # HandoffReconciler#record_journal whenever a completed checkout carries
+    # an order. Naming it in `reconcile_notify` documents that as always-on
+    # rather than gating a second write path.
+    module ReconcileNotify
+      ENV_VAR = "PORTAGE_RECONCILE_NOTIFY".freeze
+      CONFIG_KEY = "reconcile_notify".freeze
+      CHANNELS = %w[webhook journal macos terminal].freeze
+      DEFAULT = %w[webhook].freeze
+
+      module_function
+
+      # @param extra [Array<String>] channels to force on regardless of
+      #   configuration — `portage buy --wait` forces `terminal` in plain
+      #   (non-`--json`) mode, so the shopper sees a line when it settles
+      #   even with nothing configured.
+      # @return [Array<String>]
+      def resolve(override: nil, config: Config.load, extra: [])
+        raw = Setting.resolve(override: override, env: ENV_VAR, config: config, config_key: CONFIG_KEY)
+        configured = raw.nil? ? DEFAULT : raw.to_s.split(",").map(&:strip)
+        ((configured & CHANNELS) + extra).uniq
+      end
+    end
+  end
+end

data/lib/portage/cli/search_backends.rb

@@ -2,6 +2,9 @@ require "net/http"
 require "uri"
 require "json"
 require "yaml"
+require "portage/ucp"
+require "portage/ucp/support/connection"
+require_relative "user_agent"
 
 module Portage
   module Cli
@@ -18,7 +21,6 @@ module Portage
     module SearchBackends
       OPEN_TIMEOUT = 5
       READ_TIMEOUT = 5
-      USER_AGENT = "portage-find".freeze
 
       # Reference works and marketplaces-of-links that a search backend will
       # happily return for a product query but that are never themselves a UCP
@@ -45,9 +47,9 @@ module Portage
       end
 
       def self.request(uri, headers)
-        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                                            open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT) do |http|
-          http.get(uri.request_uri, { "User-Agent" => USER_AGENT }.merge(headers))
+        Portage::Ucp::Support::Connection.start(uri, route: :search, open_timeout: OPEN_TIMEOUT,
+                                                     read_timeout: READ_TIMEOUT) do |http|
+          http.get(uri.request_uri, UserAgent.headers.merge(headers))
         end
       end
       private_class_method :request

data/lib/portage/cli/user_agent.rb

@@ -0,0 +1,39 @@
+require "portage/ucp/client"
+require_relative "version"
+require_relative "config"
+require_relative "setting"
+
+module Portage
+  module Cli
+    # Every request this CLI makes — to a store, a search backend, a
+    # payment handler, or a notify webhook — names itself, then the client
+    # gem it speaks UCP through, so a merchant reading its logs sees
+    # "portage-cli/... portage-ucp-client/... (+https://github.com/...)"
+    # rather than Ruby's default and knows where to look.
+    #
+    # A caller running many agents behind one IP (or one that just wants
+    # its own contact info in the string a merchant might grep for) can
+    # override it — same Setting precedence as Notifier's webhook URL:
+    # PORTAGE_USER_AGENT beats ~/.portage/config.json's "user_agent" key,
+    # both of which beat this default. Resolved fresh on every call rather
+    # than frozen at load time, so a config.json edit or an ENV change
+    # takes effect without restarting whatever's driving this CLI.
+    module UserAgent
+      DEFAULT = "portage-cli/#{VERSION} #{Portage::Ucp::Client::USER_AGENT}".freeze
+      ENV_VAR = "PORTAGE_USER_AGENT".freeze
+      CONFIG_KEY = "user_agent".freeze
+
+      module_function
+
+      # @param config [Config]
+      # @return [String] never blank — falls back to DEFAULT.
+      def value(config: Config.load)
+        Setting.resolve(env: ENV_VAR, config: config, config_key: CONFIG_KEY) || DEFAULT
+      end
+
+      # @param config [Config]
+      # @return [Hash] a fresh header hash, safe for a caller to #merge into.
+      def headers(config: Config.load) = { "User-Agent" => value(config: config) }
+    end
+  end
+end

data/lib/portage/cli/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Cli
-    VERSION = "0.7.0".freeze
+    VERSION = "0.7.3".freeze
   end
 end

data/lib/portage/cli/webmcp.rb

@@ -0,0 +1,25 @@
+module Portage
+  module Cli
+    # docs/plans/handoff-reconcile.md Phase 4 — `portage-ucp-webmcp` is
+    # optional at runtime, not in portage-cli's gemspec, same posture as
+    # `Decisions.available?` for `portage-ucp-decision` and
+    # `Resolver.build_adapter` for a platform adapter gem: `require`, then
+    # rescue LoadError, so `gem install portage-cli` stays light and only a
+    # caller who actually passes `Buy.new(webmcp_bridge:)` ever needs it
+    # installed.
+    module Webmcp
+      # @return [Boolean] whether portage-ucp-webmcp could be loaded.
+      #   Memoized: `require` runs once per process.
+      def self.available?
+        return @available unless @available.nil?
+
+        @available = begin
+          require "portage/ucp/webmcp"
+          true
+        rescue LoadError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/webmcp_checkout_mode.rb

@@ -0,0 +1,28 @@
+require_relative "config"
+require_relative "setting"
+
+module Portage
+  module Cli
+    # docs/plans/handoff-reconcile.md Phase 4 — how `Buy`'s optional WebMCP
+    # path (see Webmcp, Buy#webmcp_flow) finishes a checkout it built in the
+    # browser. Same Setting precedence as HandoffSpendMode: no CLI flag (a
+    # WebMCP bridge is an injected collaborator, not something a shell
+    # invocation can name), so just PORTAGE_WEBMCP_CHECKOUT_MODE >
+    # config.json's "webmcp_checkout_mode". Unset, or anything not in
+    # MODES, is `express_stop`, the only mode actually implemented — see
+    # Buy#webmcp_token_unsupported_report for why `token` isn't yet.
+    module WebmcpCheckoutMode
+      ENV_VAR = "PORTAGE_WEBMCP_CHECKOUT_MODE".freeze
+      CONFIG_KEY = "webmcp_checkout_mode".freeze
+      MODES = %w[express_stop token].freeze
+      DEFAULT = "express_stop".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.rb

@@ -2,6 +2,7 @@ require "optparse"
 require "json"
 
 require_relative "cli/version"
+require_relative "cli/user_agent"
 require_relative "cli/shipping_profile"
 require_relative "cli/buyer_context"
 require_relative "cli/catalog_products"
@@ -10,7 +11,12 @@ require_relative "cli/find"
 require_relative "cli/compare"
 require_relative "cli/history"
 require_relative "cli/payment_methods"
+require_relative "cli/proxy_settings"
 require_relative "cli/doctor"
+require_relative "cli/handoff_reconciler"
+require_relative "cli/handoff_waiter"
+require_relative "cli/reconcile_notifier"
+require_relative "cli/reconcile_notify"
 require_relative "cli/generate/adapter"
 require_relative "cli/generate/agent_profile"
 
@@ -25,6 +31,7 @@ module Portage
                                 [--product-id ID] [--yes] [--dry-run]
                                 [--auto-open|--no-auto-open] [--notify-webhook URL]
                                 [--decision-backend jev|laya] [--min-confidence N] [--json]
+                                [--wait [--wait-timeout DURATION|off]]
              portage buy --query "..." [--store URL] [--max-price N] [--limit N] ...
              portage find --query "..." [--max-price N] [--limit N] [--json]
              portage compare <url> --product-id ID [--id VALUE ...] [--results N]
@@ -43,28 +50,66 @@ module Portage
                                  [--rolling-cap N --rolling-window-seconds N --currency CUR]
                                  [--velocity-count N --velocity-window-seconds N]
                                  [--allow HOST ...] [--clear-allowlist]
+             portage orders reconcile [--checkout ID] [--json]
              portage doctor [--require FILE] [--adapter CLASS_NAME] [--json]
              portage configure [--require FILE] [--adapter CLASS_NAME] [--json]  (alias for doctor)
              portage setup [--require FILE] [--adapter CLASS_NAME] [--json]      (alias for doctor)
              portage generate adapter NAME [--dir DIR]
              portage generate agent-profile [--out FILE] [--key-out FILE] [--rotate]
+             portage --version
+
+           proxy flags (buy/find/compare/doctor/payment enroll):
+             [--proxy URL] [--proxy-mode forward|gateway] [--proxy-header "Name: value"]
+             [--no-proxy HOSTS] [--proxy-route ROUTE=URL|direct] [--proxy-chain URL,URL,...]
+             [--proxy-passthrough HEADER] [--proxy-ca FILE] [--no-env-proxy]
     USAGE
 
     COMMANDS = { "buy" => :run_buy, "find" => :run_find, "compare" => :run_compare,
                  "history" => :run_history, "payment" => :run_payment, "policy" => :run_policy,
-                 "doctor" => :run_doctor, "configure" => :run_doctor, "setup" => :run_doctor,
-                 "generate" => :run_generate }.freeze
+                 "orders" => :run_orders, "doctor" => :run_doctor, "configure" => :run_doctor,
+                 "setup" => :run_doctor, "generate" => :run_generate }.freeze
+
+    VERSION_FLAGS = %w[--version -v version].freeze
 
     # @param argv [Array<String>]
     # @return [Integer] process exit code
     def self.run(argv)
       command, *rest = argv
+      return run_version if VERSION_FLAGS.include?(command)
       return send(COMMANDS[command], rest) if COMMANDS.key?(command)
 
       warn USAGE
       1
     end
 
+    # So a packaged install (Homebrew's `test do` block, `portage doctor`)
+    # can confirm which release it's running without hitting the network.
+    def self.run_version
+      puts VERSION
+      0
+    end
+    private_class_method :run_version
+
+    # --- proxy (docs/plans/proxy-support.md Phase 2) ---
+
+    # Resolves this command's `--proxy*` flags/env/config.json into a
+    # ProxyConfig and installs it as the process-wide default every
+    # Support::Connection.start call (buy/find/compare/payment/doctor alike)
+    # already reads unless it's handed its own `proxy:` — see ProxySettings'
+    # own comment for why. A bad flag or a malformed/protected-header
+    # config.json surfaces here as a clean message, never a raw core
+    # exception.
+    # @return [ProxySettings, nil] nil on a config error (already reported).
+    def self.apply_proxy_settings(proxy_flags)
+      settings = ProxySettings.new(flags: proxy_flags || {})
+      Portage::Ucp::Support::ProxyConfig.current = settings.resolve
+      settings
+    rescue ProxySettings::ConfigError => e
+      warn "portage: #{e.message}"
+      nil
+    end
+    private_class_method :apply_proxy_settings
+
     # --- find ---
 
     def self.run_find(argv)
@@ -72,6 +117,8 @@ module Portage
       return 1 unless options
 
       json = options.delete(:json)
+      return 1 unless apply_proxy_settings(options.delete(:proxy))
+
       report = Find.new(**options).call
       record_find(report)
       puts json ? JSON.pretty_generate(report) : format_find(report)
@@ -98,11 +145,13 @@ module Portage
     private_class_method :parse_find_options
 
     def self.find_option_parser(opts)
+      opts[:proxy] = {}
       OptionParser.new do |parser|
         parser.on("--query QUERY") { |v| opts[:query] = v }
         parser.on("--limit N", Integer) { |v| opts[:limit] = v }
         parser.on("--max-price N", Float) { |v| opts[:max_price] = to_minor_units(v) }
         parser.on("--json") { opts[:json] = true }
+        ProxySettings.add_options(parser, opts[:proxy])
       end
     end
     private_class_method :find_option_parser
@@ -121,6 +170,8 @@ module Portage
 
       json = options.delete(:json)
       url = options.delete(:url)
+      return 1 unless apply_proxy_settings(options.delete(:proxy))
+
       report = Compare.new(origin_url: url, **options).call
       # Recorded as a search, not a purchase — compare never checks out. The
       # query string names the compare so `portage history list` doesn't
@@ -147,12 +198,14 @@ module Portage
     private_class_method :parse_compare_options
 
     def self.compare_option_parser(opts)
+      opts[:proxy] = {}
       OptionParser.new do |parser|
         parser.on("--product-id ID") { |v| opts[:origin_product_id] = v }
         parser.on("--id VALUE") { |v| opts[:identity] << v }
         parser.on("--results N", Integer) { |v| opts[:results] = v }
         parser.on("--max-price N", Float) { |v| opts[:max_price] = to_minor_units(v) }
         parser.on("--json") { opts[:json] = true }
+        ProxySettings.add_options(parser, opts[:proxy])
       end
     end
     private_class_method :compare_option_parser
@@ -162,6 +215,7 @@ module Portage
     def self.run_buy(argv)
       parsed = parse_buy_options(argv)
       return 1 unless parsed
+      return 1 unless apply_proxy_settings(parsed[:proxy])
 
       url = parsed[:buy][:url] || parsed[:store]
       parsed[:confidence_check] = confidence_check(parsed, url)
@@ -210,11 +264,88 @@ module Portage
       options[:product_id] ||= product_id
       report = Buy.new(**options).call
       record_buy(report, options[:query])
-      puts parsed[:json] ? JSON.pretty_generate(report) : format_report(report)
+      result = parsed[:wait] ? wait_for_handoff(report, parsed) : nil
+      print_buy_report(report, result, parsed[:json])
       report[:checkout] || report[:browse] ? 0 : 1
     end
     private_class_method :execute_buy
 
+    # docs/plans/handoff-reconcile.md Phase 3 — `portage buy --wait`. A
+    # no-op (returns nil) whenever there's nothing to wait on: --dry-run
+    # never hands off at all, and a completed/browse-only/dead-end report
+    # has no pending shopper record either. Otherwise polls
+    # `HandoffReconciler` through `HandoffWaiter` until it settles or its
+    # deadline passes.
+    #
+    # Under --json, every event streams to stdout as it happens (NDJSON) —
+    # the initial hand-off, then a line per checkout-status change, then the
+    # settle, so a calling agent reading stdout live never has to guess
+    # whether it's still waiting. Under plain output, nothing streams here:
+    # the forced "terminal" notify channel (see #wait_notifier) prints its
+    # own line when it settles, and the final report follows exactly as it
+    # does without --wait.
+    def self.wait_for_handoff(report, parsed)
+      return nil unless report[:handoff] && report[:checkout_id]
+
+      transaction_log = Portage::Ucp::Support::TransactionLog.new
+      record = pending_shopper_record(report[:checkout_id], transaction_log)
+      return nil unless record
+
+      json = parsed[:json]
+      emit_ndjson(handoff_event(report)) if json
+      reconciler = HandoffReconciler.new(transaction_log: transaction_log, notifier: wait_notifier(json))
+      waiter = HandoffWaiter.new(reconciler: reconciler, transaction_log: transaction_log,
+                                 wait_timeout_override: parsed[:wait_timeout])
+      waiter.call(record) { |event, result| emit_wait_event(event, result, json) }
+    end
+    private_class_method :wait_for_handoff
+
+    def self.pending_shopper_record(checkout_id, transaction_log)
+      transaction_log.each_record.find { |r| r["checkout_id"] == checkout_id && r["settled_by"] == "shopper" }
+    end
+    private_class_method :pending_shopper_record
+
+    # `terminal` is forced on for a plain-text wait (see ReconcileNotify) so
+    # the shopper sees a line the moment it settles even with nothing
+    # configured. Never forced under --json: that channel prints plain text,
+    # which would corrupt the NDJSON stream this method's caller is also
+    # writing to the same stdout.
+    def self.wait_notifier(json)
+      ReconcileNotifier.new(channels: ReconcileNotify.resolve(extra: json ? [] : ["terminal"]))
+    end
+    private_class_method :wait_notifier
+
+    def self.handoff_event(report)
+      { event: "handoff", checkout_id: report[:checkout_id], checkout_url: report[:checkout_url],
+        reason: report[:outcome] }
+    end
+    private_class_method :handoff_event
+
+    # Only `:settled` ever reaches stdout as `handoff_settled` — a timeout or
+    # an interrupted wait leaves `result.settled` false, and that's already
+    # visible in the final report object this event stream ends with, so a
+    # second, redundant "gave up" event isn't needed.
+    def self.emit_wait_event(event, result, json)
+      return unless json
+
+      case event
+      when :status then emit_ndjson({ event: "handoff_status", status: result.checkout_status })
+      when :settled
+        emit_ndjson({ event: "handoff_settled", result: result.status, resolution: result.resolution,
+                      order_id: result.order_id, amount: result.amount, currency: result.currency }.compact)
+      end
+    end
+    private_class_method :emit_wait_event
+
+    def self.emit_ndjson(payload) = puts JSON.generate(payload)
+    private_class_method :emit_ndjson
+
+    def self.print_buy_report(report, result, json)
+      report = report.merge(reconcile: result.to_h) if result
+      puts json ? JSON.pretty_generate(report) : format_report(report)
+    end
+    private_class_method :print_buy_report
+
     # Built before the buy starts (and before the search, when there's no
     # URL), so a bad --min-confidence, or a bad PORTAGE_MIN_CONFIDENCE with
     # a backend enabled, stops the run up front rather than after a
@@ -276,7 +407,10 @@ module Portage
       buy = { url: url, qty: 1, yes: false, dry_run: false }
       parsed = { buy: buy, find: {}, confidence: {} }
       json = argv.include?("--json")
-      buy_option_parser(buy, parsed).parse!(argv)
+      parsed[:proxy] = {}
+      parser = buy_option_parser(buy, parsed)
+      ProxySettings.add_options(parser, parsed[:proxy])
+      parser.parse!(argv)
       buy[:query] ||= ""
       return parsed if url || !buy[:query].strip.empty?
 
@@ -294,9 +428,9 @@ module Portage
         parser.on("--product-id ID") { |v| buy[:product_id] = v }
         parser.on("--yes") { buy[:yes] = true }
         parser.on("--dry-run") { buy[:dry_run] = true }
-        parser.on("--[no-]auto-open") { |v| buy[:auto_open] = v }
-        parser.on("--notify-webhook URL") { |v| buy[:notify_webhook] = v }
         parser.on("--json") { parsed[:json] = true }
+        add_handoff_options(parser, buy)
+        add_wait_options(parser, parsed)
         add_search_options(parser, buy, parsed)
         add_confidence_options(parser, parsed[:confidence])
       end
@@ -311,6 +445,22 @@ module Portage
     end
     private_class_method :add_confidence_options
 
+    def self.add_handoff_options(parser, buy)
+      parser.on("--[no-]auto-open") { |v| buy[:auto_open] = v }
+      parser.on("--notify-webhook URL") { |v| buy[:notify_webhook] = v }
+    end
+    private_class_method :add_handoff_options
+
+    # docs/plans/handoff-reconcile.md Phase 3 — `--wait`/`--wait-timeout`
+    # land on `parsed`, never on `buy`: they're consumed by
+    # `#wait_for_handoff` after `Buy#call` returns, and `Buy.new` has no
+    # `wait:`/`wait_timeout:` keyword to accidentally receive them.
+    def self.add_wait_options(parser, parsed)
+      parser.on("--wait") { parsed[:wait] = true }
+      parser.on("--wait-timeout DURATION") { |v| parsed[:wait_timeout] = v }
+    end
+    private_class_method :add_wait_options
+
     # `--query` feeds both halves: it's the store search when there's no URL
     # and the catalog search once a store is settled, so it's registered once
     # here rather than twice on the same parser.
@@ -318,7 +468,7 @@ module Portage
       parser.on("--query QUERY") { |v| parsed[:find][:query] = buy[:query] = v }
       parser.on("--store URL") { |v| parsed[:store] = v }
       parser.on("--limit N", Integer) { |v| parsed[:find][:limit] = v }
-      parser.on("--max-price N", Float) { |v| parsed[:find][:max_price] = to_minor_units(v) }
+      parser.on("--max-price N", Float) { |v| parsed[:find][:max_price] = buy[:max_price] = to_minor_units(v) }
     end
     private_class_method :add_search_options
 
@@ -455,13 +605,14 @@ module Portage
     private_class_method :run_payment_mutate
 
     def self.parse_payment_enroll_options(argv)
-      opts = { scope_merchants: [] }
+      opts = { scope_merchants: [], proxy: {} }
       OptionParser.new do |parser|
         parser.on("--label NAME") { |v| opts[:label] = v }
         parser.on("--json") { opts[:json] = true }
         parser.on("--scope-merchant HOST") { |v| opts[:scope_merchants] << v }
         parser.on("--scope-max-amount N", Integer) { |v| opts[:scope_max_amount] = v }
         parser.on("--scope-currency CUR") { |v| opts[:scope_currency] = v }
+        ProxySettings.add_options(parser, opts[:proxy])
       end.parse!(argv)
       opts[:url] = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
       opts
@@ -486,6 +637,7 @@ module Portage
         warn USAGE
         return 1
       end
+      return 1 unless apply_proxy_settings(opts[:proxy])
 
       result = PaymentMethods.new.enroll(opts[:url], label: opts[:label],
                                                      scope: payment_enroll_scope(opts)) do |setup_url|
@@ -610,14 +762,86 @@ module Portage
     end
     private_class_method :format_payment_enroll
 
+    # --- orders ---
+
+    # docs/plans/handoff-reconcile.md Phase 1 — resolves every pending
+    # `settled_by: "shopper"` TransactionLog record (or just the one named
+    # by `--checkout`) by re-fetching that checkout from the store. Safe to
+    # run from cron/launchd: a record that's already terminal, or that
+    # doesn't belong to this run (a `--checkout` for a different id, or
+    # `settled_by: nil` dispatcher crash-evidence), is a no-op result, not
+    # an error, so a scheduled run never needs its own filtering logic.
+    def self.run_orders(argv)
+      sub = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      return run_orders_reconcile(argv) if sub == "reconcile"
+
+      warn USAGE
+      1
+    end
+    private_class_method :run_orders
+
+    def self.run_orders_reconcile(argv)
+      opts = {}
+      OptionParser.new do |parser|
+        parser.on("--checkout ID") { |v| opts[:checkout] = v }
+        parser.on("--json") { opts[:json] = true }
+      end.parse!(argv)
+
+      transaction_log = Portage::Ucp::Support::TransactionLog.new
+      reconciler = HandoffReconciler.new(transaction_log: transaction_log)
+      results = reconcile_records(opts[:checkout], transaction_log, reconciler)
+
+      puts opts[:json] ? JSON.pretty_generate(results.map(&:to_h)) : format_reconcile(results)
+      0
+    end
+    private_class_method :run_orders_reconcile
+
+    def self.reconcile_records(checkout_id, transaction_log, reconciler)
+      return reconcile_one_checkout(checkout_id, transaction_log, reconciler) if checkout_id
+
+      HandoffReconciler.each_pending_shopper_record(transaction_log).map { |record| reconciler.call(record) }
+    end
+    private_class_method :reconcile_records
+
+    # `--checkout ID` reconciles the one named record whatever its
+    # `settled_by`/status — #call itself still refuses to settle anything
+    # that isn't a pending shopper record, this just skips the "iterate
+    # every pending record" step when the caller already knows which one.
+    def self.reconcile_one_checkout(checkout_id, transaction_log, reconciler)
+      key = transaction_log.each_record.find { |r| r["checkout_id"] == checkout_id }&.fetch("idempotency_key", nil)
+      return [] unless key
+
+      [reconciler.call(transaction_log.find(key))]
+    end
+    private_class_method :reconcile_one_checkout
+
+    def self.format_reconcile(results)
+      return "(nothing to reconcile)" if results.empty?
+
+      results.map { |r| format_reconcile_result(r) }.join("\n")
+    end
+    private_class_method :format_reconcile
+
+    def self.format_reconcile_result(result)
+      return "#{result.idempotency_key}: #{result.note}" unless result.settled
+
+      parts = ["#{result.idempotency_key}: #{result.status}"]
+      parts << "resolution: #{result.resolution}" if result.resolution
+      parts << "order: #{result.order_id}" if result.order_id
+      parts << format_amount(result.amount, result.currency) if result.amount
+      parts.join(" — ")
+    end
+    private_class_method :format_reconcile_result
+
     # --- doctor ---
 
     def self.parse_doctor_options(argv)
-      opts = {}
+      opts = { proxy: {} }
       OptionParser.new do |parser|
         parser.on("--require FILE") { |v| opts[:require] = v }
         parser.on("--adapter CLASS_NAME") { |v| opts[:adapter] = v }
         parser.on("--json") { opts[:json] = true }
+        ProxySettings.add_options(parser, opts[:proxy])
       end.parse!(argv)
       opts
     end
@@ -627,8 +851,10 @@ module Portage
       opts = parse_doctor_options(argv)
       require File.expand_path(opts[:require]) if opts[:require]
       adapter_class = opts[:adapter] && Object.const_get(opts[:adapter])
+      proxy_settings = apply_proxy_settings(opts[:proxy])
+      return 1 unless proxy_settings
 
-      findings = Doctor.new(adapter_class: adapter_class).call
+      findings = Doctor.new(adapter_class: adapter_class, proxy_settings: proxy_settings).call
       puts opts[:json] ? JSON.pretty_generate(findings.map(&:to_h)) : format_doctor(findings)
       findings.empty? ? 0 : 1
     end