portage-cli 0.6.4 → 0.7.0

data/lib/portage/cli/buy.rb

@@ -5,6 +5,9 @@ require "portage/ucp"
 require "portage/ucp/client"
 require "portage/ucp/journal"
 require_relative "payment_methods"
+require_relative "setting"
+require_relative "decisions"
+require_relative "confidence_check"
 require_relative "checkout_handoff"
 require_relative "notifier"
 
@@ -37,8 +40,19 @@ module Portage
       #   webhook URL a dead-end checkout_url is POSTed to — nil (the
       #   default) defers to PORTAGE_NOTIFY_WEBHOOK_URL / config.json (see
       #   Notifier).
+      # @param confidence_check [ConfidenceCheck, nil] the opt-in confidence
+      #   gate in front of an unattended completion. nil (the default) builds
+      #   one from PORTAGE_DECISION_BACKEND / PORTAGE_MIN_CONFIDENCE, which is
+      #   a no-op when no backend is named.
+      # @param transaction_log [Portage::Ucp::Support::TransactionLog, nil]
+      #   where a remote purchase is recorded, and what the spend policy's
+      #   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
       def initialize(url:, query:, qty: 1, payment_token: nil, yes: false, dry_run: false, product_id: nil,
-                     auto_open: nil, notify_webhook: nil)
+                     auto_open: nil, notify_webhook: nil, confidence_check: nil, transaction_log: nil)
+        # rubocop:enable Metrics/ParameterLists
         raw = url.to_s.strip
         raw = "https://#{raw}" unless raw =~ %r{\Ahttps?://}i
         @uri = URI.parse(raw)
@@ -50,6 +64,9 @@ module Portage
         @product_id = product_id
         @auto_open = auto_open
         @notify_webhook = notify_webhook
+        @confidence_check = confidence_check
+        @transaction_log = transaction_log
+        @decisions = {}
       end
 
       # Link `type`s that are never the checkout — see #checkout_url_of.
@@ -103,11 +120,11 @@ module Portage
       def native_flow_error_report(error)
         case error
         when Portage::Ucp::Client::MissingAgentProfileError
-          build_report(source: "native_ucp", browse: false, checkout: false,
+          build_report(source: "native_ucp", outcome: "agent_profile_missing", browse: false, checkout: false,
                        message: "Set PORTAGE_AGENT_PROFILE to a URL that describes this agent — " \
                                 "#{@uri} verifies it before answering any UCP call.")
         when Portage::Ucp::Client::UnsupportedWireShapeError
-          build_report(source: "native_ucp", browse: true, checkout: false,
+          build_report(source: "native_ucp", outcome: "unsupported_wire_shape", browse: true, checkout: false,
                        message: "Can't complete checkout on #{@uri} yet: #{error.message}")
         when Portage::Ucp::Client::ServerError
           server_error_report(error)
@@ -117,7 +134,7 @@ module Portage
           # explanation — a common cause is PORTAGE_AGENT_PROFILE not
           # pointing at a real, JSON agent-profile document the store's UCP
           # endpoint accepts.
-          build_report(source: "native_ucp", browse: false, checkout: false,
+          build_report(source: "native_ucp", outcome: "request_rejected", browse: false, checkout: false,
                        message: "#{@uri} rejected the request (#{error.message}) — if PORTAGE_AGENT_PROFILE " \
                                 "is set, check it points at a real agent-profile document the store accepts.")
         end
@@ -140,7 +157,7 @@ module Portage
       def server_error_report(error)
         url = error.continue_url
         build_report(
-          source: "native_ucp", browse: true, checkout: false, checkout_url: url,
+          source: "native_ucp", outcome: "store_refused", browse: true, checkout: false, checkout_url: url,
           message: "#{@uri} couldn't complete this: #{error.summary}#{url && " — finish it at #{url}"}"
         )
       end
@@ -148,7 +165,7 @@ module Portage
       def catalog_only(session)
         products = safe_search(session)
         report = build_report(
-          source: "native_ucp", browse: true, checkout: false, products: products,
+          source: "native_ucp", outcome: "browse_only", browse: true, checkout: false, products: products,
           message: "I can browse this store but can't check out via UCP yet."
         )
         merge_adapter_checkout_fallback(report)
@@ -164,7 +181,13 @@ module Portage
         fallback = platform && adapter_flow(platform)
         return report unless fallback && fallback[:checkout]
 
-        report.merge(source: fallback[:source], checkout: true, checkout_url: fallback[:checkout_url])
+        # The original `report[:message]` ("I can browse this store but
+        # can't check out via UCP yet.") goes stale the moment `checkout:`
+        # flips to true here — leaving it would tell the caller there's no
+        # checkout path in the same report that hands them a checkout_url.
+        report.merge(source: fallback[:source], checkout: true, checkout_url: fallback[:checkout_url],
+                     message: "#{report[:message]} Falling back to #{fallback[:source]} — " \
+                              "follow the link to buy it that way instead.")
       end
 
       # --- Step 1 fallback: alternate manifest pointer in <head> ---
@@ -189,6 +212,14 @@ module Portage
           adapter = Portage::Ucp::Resolver.build_adapter(platform, env)
         rescue LoadError
           return nil
+        rescue StandardError => e
+          # Distinct from LoadError above: the gem *is* installed and this
+          # platform *was* detected, so a raise here is a real config
+          # problem (e.g. malformed WOOCOMMERCE_BILLING_ADDRESS JSON) — same
+          # "actionable, don't hide it behind dead_end" posture as
+          # #run_adapter_flow's own rescue, just one step earlier.
+          return build_report(source: "adapter:#{platform.name}", outcome: "adapter_misconfigured", browse: false,
+                              checkout: false, message: "#{platform.name} adapter misconfigured: #{e.message}")
         end
 
         run_adapter_flow(adapter, platform)
@@ -206,8 +237,15 @@ module Portage
           catalog_only_adapter(adapter, platform)
         end
       rescue StandardError => e
-        build_report(source: "adapter:#{platform.name}", browse: false, checkout: false,
-                     message: "#{platform.name} adapter error: #{e.message}")
+        # `e.message` is the store's own text where the adapter raised an
+        # ApiError (see Support::ApiError#detail) — quoted verbatim, not
+        # replaced with a generic message, so the actual cause (a missing
+        # param, an out-of-stock line, a bad gateway id) is visible. Always
+        # paired with a next action, since "here's an error" alone leaves the
+        # caller to guess whether to retry, reconfigure, or give up.
+        build_report(source: "adapter:#{platform.name}", outcome: "adapter_error", browse: false, checkout: false,
+                     message: "#{platform.name} adapter error: #{e.message} — visit #{@uri} yourself, " \
+                              "or fix the adapter's env/config and retry.")
       end
 
       def adapter_supports_checkout?(adapter)
@@ -233,7 +271,7 @@ module Portage
         products = CatalogProducts.from(adapter.search_catalog(query: @query, limit: 10))
         checkout = redirect_checkout(adapter, products)
         build_report(
-          source: "adapter:#{platform.name}", browse: true, checkout: !!checkout,
+          source: "adapter:#{platform.name}", outcome: "browse_only", browse: true, checkout: !!checkout,
           products: products, checkout_url: checkout && checkout.links.first&.url,
           message: "Found it on #{platform.name}, but checkout there isn't a live UCP transaction — " \
                    "#{checkout ? 'follow the link to buy it yourself.' : 'no checkout path at all.'}"
@@ -262,7 +300,7 @@ module Portage
         products = safe_search(session)
         product = select_product(products)
         unless product
-          return build_report(source: source, browse: true, checkout: true, products: products,
+          return build_report(source: source, outcome: "no_match", browse: true, checkout: true, products: products,
                               message: no_match_message)
         end
 
@@ -270,7 +308,45 @@ module Portage
                                            fulfillment: requested_fulfillment(fulfillment_adapter),
                                            context: buyer_context, meta: agent_meta)
         checkout = select_cheapest_shipping(session, checkout) if fulfillment_adapter
-        finish_checkout(session, source, products, checkout)
+
+        warnings = reconcile_checkout(product, checkout)
+        finish_checkout(session, source, products, checkout, warnings)
+      end
+
+      # A store can silently drop the requested line, change its quantity, or
+      # price it differently than its own catalog just quoted a moment
+      # earlier in #safe_search — none of that raises, since it's a normal
+      # (if surprising) checkout response, not a transport error. Buying
+      # blind against a mismatch this method could have caught defeats the
+      # point of an agent shopping on the buyer's behalf, so this always
+      # checks and surfaces what it finds; PORTAGE_ABORT_ON_CHECKOUT_MISMATCH
+      # additionally refuses to proceed rather than merely warning.
+      def reconcile_checkout(product, checkout)
+        item_id = line_item_id_of(product)
+        line = Array(checkout["line_items"]).find { |li| li.dig("item", "id") == item_id }
+        return ["Store dropped the requested item (#{item_id}) from checkout."] unless line
+
+        warnings = []
+        if line["quantity"] != @qty
+          warnings << "Store checked out quantity #{line['quantity']}, not the requested #{@qty}."
+        end
+
+        expected = expected_unit_price(product, item_id)
+        actual = line.dig("item", "price")
+        if expected && actual && expected != actual
+          warnings << "Store priced the item at #{actual} #{checkout['currency']} minor units per unit, " \
+                      "not the catalog's #{expected}."
+        end
+        warnings
+      end
+
+      def expected_unit_price(product, item_id)
+        variant = Array(product["variants"]).find { |v| v["id"] == item_id }
+        variant&.dig("price", "amount") || product.dig("price_range", "min", "amount")
+      end
+
+      def abort_on_mismatch?
+        Setting.flag?(env: "PORTAGE_ABORT_ON_CHECKOUT_MISMATCH")
       end
 
       # Submits PORTAGE_SHIP_* (see Portage::Cli::ShippingProfile) as the
@@ -338,12 +414,27 @@ module Portage
       # With a --product-id, that exact product or nothing: falling back to the
       # top search hit when the requested id isn't in the results would buy
       # something the caller never chose.
+      #
+      # Without one, the top hit a shopper could actually buy: checking out a
+      # sold-out top hit dead-ends on the store's "Sold out" refusal even
+      # 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.
       def select_product(products)
-        return products.first unless @product_id
+        return products.find { |product| available?(product) } || products.first unless @product_id
 
         products.find { |product| product_id_of(product) == @product_id }
       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)
+        variants = Array(product["variants"])
+        variants.empty? || variants.any? { |variant| variant_available?(variant) }
+      end
+
+      def variant_available?(variant) = variant.dig("availability", "available") != false
+
       # #select_product only ever sees products from #safe_search, which reads
       # through a Session — native remote or the own-store loopback session
       # built via Client.for_adapter alike — so Dispatcher#wrap has already
@@ -362,37 +453,196 @@ module Portage
       # #product_id_of returns for display/--product-id matching. A
       # product with no variants (or a backend that doesn't distinguish
       # the two) falls back to the product id unchanged (see
-      # docs/design-log.md §41).
+      # docs/design-log.md §41). The first in-stock variant wins over the
+      # first variant, for the same reason #select_product skips sold-out
+      # products (a live Brooklinen sheet set lists its sold-out size first).
       def line_item_id_of(product)
-        product["variants"]&.first&.dig("id") || product_id_of(product)
+        variants = Array(product["variants"])
+        (variants.find { |variant| variant_available?(variant) } || variants.first)&.dig("id") ||
+          product_id_of(product)
+      end
+
+      def finish_checkout(session, source, products, checkout, warnings = [])
+        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 confirmation_needed_report(source, products, checkout, warnings) unless confirmed?
+
+        complete(session, source, products, checkout, warnings)
+      end
+
+      # Hand off vs. keep going is Decisions.escalation's call
+      # (docs/plans/system-one-decision-layer.md § Responsibilities 2): a
+      # literal `requires_escalation` status always escalates. A mismatch
+      # from #reconcile_checkout escalates only under
+      # PORTAGE_ABORT_ON_CHECKOUT_MISMATCH. By default the warnings are
+      # surfaced on the report, and the purchase is not stopped for them.
+      # The verdict lands on the report's `decisions:`, and the report's
+      # `outcome:` names which gate (if any) stopped the purchase.
+      def decide_escalation(checkout, warnings)
+        verdict = Decisions.escalation(checkout_status: checkout["status"],
+                                       warnings: abort_on_mismatch? ? warnings : [])
+        @decisions[:escalation] = verdict
+        verdict
       end
 
-      def finish_checkout(session, source, products, checkout)
-        status = checkout["status"]
-        return escalation_report(source, products, checkout) if status == "requires_escalation"
-        return dry_run_report(source, products, checkout) if @dry_run
-        return confirmation_needed_report(source, products, checkout) unless confirmed?
+      def escalated_report(source, products, checkout, warnings, verdict)
+        return escalation_report(source, products, checkout, warnings) unless verdict[:reason] == "mismatch"
 
-        complete(session, source, products, checkout)
+        handoff_report(source, products, checkout, warnings,
+                       outcome: "checkout_mismatch",
+                       message: "Aborted before purchase — checkout didn't match the request: #{warnings.join(' ')}")
       end
 
-      def complete(session, source, products, checkout)
+      # One guard per gate, in the order they run: a payment token, the
+      # buyer's spend policy, the opt-in confidence check, then the store's
+      # own answer to the completion.
+      def complete(session, source, products, checkout, warnings = [])
         @payment_token ||= PaymentMethods.default
-        unless @payment_token
-          url = checkout_url_of(checkout)
-          return checkout_report(
-            source, products, checkout,
-            checkout_url: url, handoff: hand_off(checkout, reason: "no_payment_token", source: source),
-            message: "No --payment-token given, and no default payment method on file — run " \
-                     "`portage payment enroll` or pass --payment-token, or visit the link to " \
-                     "finish this checkout yourself."
-          )
-        end
+        return no_payment_token_report(source, products, checkout, warnings) unless @payment_token
 
-        completed = session.complete_checkout(checkout_id: checkout["id"], payment_token: @payment_token)
-        checkout_report(source, products, completed, message: "Purchased.")
+        held = held_report(source, products, checkout, warnings)
+        return held if held
+
+        completed = recording_transaction(source, checkout) do
+          session.complete_checkout(checkout_id: checkout["id"], payment_token: @payment_token)
+        end
+        # `complete_checkout` can hand back `requires_escalation` too (e.g.
+        # Shopify's cartSubmitForCompletion result carrying `errors`) — this
+        # used to report "Purchased." unconditionally regardless of
+        # `completed["status"]`, silently misreporting an escalation as a
+        # successful purchase.
+        return escalation_report(source, products, completed, warnings) if decide_escalation(completed, [])[:escalate]
+
+        checkout_report(source, products, completed, outcome: "purchased", message: "Purchased.",
+                                                     warnings: warnings + Array(@unrecorded_warning))
       rescue Portage::Ucp::Client::PaymentPermissionError
-        permission_denied_report(source, products, checkout)
+        permission_denied_report(source, products, checkout, warnings)
+      end
+
+      # PolicyGuard's rolling cap and velocity limit count the completed
+      # records in the transaction log. On the own-store loopback path the
+      # in-process Dispatcher writes those itself, so only a remote
+      # completion is recorded here. Recording both would count a loopback
+      # purchase twice.
+      #
+      # Same shape as Dispatcher's record: reserved `pending` before the
+      # store is asked to complete, so a crash mid-charge leaves evidence,
+      # then settled. Only a completion that came back purchased settles as
+      # `complete`, the one status those limits count.
+      def recording_transaction(source, checkout)
+        return yield unless source == "native_ucp"
+
+        key = "portage-buy:#{@uri.host}:#{checkout['id']}"
+        transaction_log.reserve(idempotency_key: key, checkout_id: checkout["id"], shop: @uri.host,
+                                payment_token_ref: token_ref, amount: checkout_total(checkout),
+                                currency: checkout["currency"])
+        begin
+          completed = yield
+        rescue StandardError
+          transaction_log.complete(idempotency_key: key, status: "failed", policy_decision: @decisions[:policy])
+          raise
+        end
+        settle_transaction(key, completed)
+        completed
+      end
+
+      # Money has moved by now. TransactionLog raises on a failed write so
+      # spend-cap state never drifts silently, but an escaped exception here
+      # would drop the purchase's report and history entry too, so the
+      # failure is put on the report as a warning instead.
+      def settle_transaction(key, completed)
+        purchased = Portage::Ucp::Support::Escalation.reason(checkout_status: completed["status"]).nil?
+        transaction_log.complete(idempotency_key: key, status: purchased ? "complete" : "failed",
+                                 amount: checkout_total(completed), currency: completed["currency"],
+                                 policy_decision: @decisions[:policy])
+      rescue StandardError => e
+        @unrecorded_warning = "Purchased, but it couldn't be recorded in the transaction log (#{e.message}), " \
+                              "so your spend policy's rolling cap and velocity limit won't count it."
+      end
+
+      def transaction_log
+        @transaction_log ||= Portage::Ucp::Support::TransactionLog.new
+      end
+
+      # nil when both pre-completion gates pass; otherwise the report for
+      # the first one that held the purchase.
+      def held_report(source, products, checkout, warnings)
+        policy = decide_policy(checkout)
+        return policy_blocked_report(source, products, checkout, warnings, policy) unless policy[:allowed]
+
+        confidence = decide_confidence(checkout, warnings)
+        return nil if confidence.nil? || confidence[:proceed]
+
+        handoff_report(source, products, checkout, warnings, outcome: "low_confidence",
+                                                             message: low_confidence_message(confidence))
+      end
+
+      # The buyer's own spend policy (`portage policy set`), checked through
+      # Decisions.policy before any completion is attempted. PolicyGuard is
+      # core, so this runs with or without the optional decision gem.
+      # Dispatcher runs PolicyGuard as well, but only in-process. A remote
+      # native-UCP store's Dispatcher belongs to the merchant, not to this
+      # buyer, so without this check the buyer's caps, allowlist and token
+      # scopes never applied to a remote store at all. PolicyGuard.check!
+      # only reads, so for the own-store adapter flow this repeats a check
+      # Dispatcher also runs. It doesn't double-count anything.
+      #
+      # The rolling cap and velocity limit count the transaction log's
+      # completed records: Dispatcher writes them for own-store purchases,
+      # and #recording_transaction for remote ones.
+      def decide_policy(checkout)
+        verdict = Decisions.policy(amount: checkout_total(checkout), currency: checkout["currency"],
+                                   merchant: @uri.host, token_ref: token_ref, transaction_log: transaction_log)
+        @decisions[:policy] = verdict
+        verdict
+      end
+
+      def token_ref = Portage::Ucp::Support::TokenRef.for(@payment_token)
+
+      def checkout_total(checkout)
+        Portage::Ucp::Support::Totals.amount(checkout["totals"])
+      end
+
+      # Never includes the payment token: the state goes to a model backend,
+      # which may be a hosted API (Jev).
+      def decide_confidence(checkout, warnings)
+        verdict = confidence_check.call(
+          query: @query, merchant: @uri.host, quantity: @qty, warnings: warnings,
+          checkout: checkout.slice("id", "status", "currency", "line_items", "totals")
+        )
+        @decisions[:confidence] = verdict if verdict
+        verdict
+      end
+
+      def confidence_check
+        @confidence_check ||= ConfidenceCheck.new
+      end
+
+      def policy_blocked_report(source, products, checkout, warnings, verdict)
+        handoff_report(source, products, checkout, warnings,
+                       outcome: "policy_blocked",
+                       message: "Blocked by your spend policy (#{verdict[:reason]}) — not completed. Review it " \
+                                "with `portage policy show`, or visit the link to finish this checkout yourself.")
+      end
+
+      def low_confidence_message(verdict)
+        backend = verdict[:backend]
+        unless verdict[:reason] == "below_threshold"
+          return "Confidence check (#{backend}) couldn't answer — not completed: #{verdict[:error]} " \
+                 "Visit the link to finish this checkout yourself."
+        end
+
+        "Confidence check (#{backend}) scored this checkout #{verdict[:confidence].round(2)}, below the " \
+          "#{verdict[:threshold]} threshold — not completed. Visit the link to review and finish it yourself."
+      end
+
+      def no_payment_token_report(source, products, checkout, warnings)
+        handoff_report(source, products, checkout, warnings,
+                       outcome: "no_payment_token",
+                       message: "No --payment-token given, and no default payment method on file — run " \
+                                "`portage payment enroll` or pass --payment-token, or visit the link to " \
+                                "finish this checkout yourself.")
       end
 
       # Same posture as #escalation_report: a completion this agent isn't
@@ -400,14 +650,28 @@ module Portage
       # shopper finishes on the merchant's own continue_url/checkout link,
       # same hand-off requires_escalation already uses (see
       # Client::PaymentPermissionError).
-      def permission_denied_report(source, products, checkout)
-        url = checkout_url_of(checkout)
-        checkout_report(
-          source, products, checkout,
-          checkout_url: url, handoff: hand_off(checkout, reason: "permission_denied", source: source),
-          message: "This agent isn't yet granted permission to complete checkout on this store — " \
-                   "visit the link to finish it yourself."
-        )
+      def permission_denied_report(source, products, checkout, warnings)
+        handoff_report(source, products, checkout, warnings,
+                       outcome: "permission_denied",
+                       message: "This agent isn't yet granted permission to complete checkout on this store — " \
+                                "visit the link to finish it yourself.")
+      end
+
+      def escalation_report(source, products, checkout, warnings)
+        handoff_report(source, products, checkout, warnings,
+                       outcome: "requires_escalation",
+                       message: "Checkout requires buyer escalation — visit the link to complete it.")
+      end
+
+      # Every checkout this process can't finish itself — a gate held it, or
+      # the store escalated or refused permission — hands the shopper its URL
+      # (and fires the auto-open/webhook side effects) rather than leaving
+      # them at a dead end. `outcome` doubles as the webhook's `reason`, so a
+      # 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_url: checkout_url_of(checkout), handoff: handoff)
       end
 
       # Never fires on --dry-run (a dry run creates a real checkout but never
@@ -417,13 +681,18 @@ module Portage
       # out of #call (see CheckoutHandoff, Notifier), so the checkout itself
       # — created, or correctly escalated — stays the outcome of record
       # either way.
-      def hand_off(checkout, reason:, source:)
+      #
+      # 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.
+      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, checkout_url: url,
-                              checkout_id: checkout["id"], source: source, totals: checkout["totals"])
+        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 }
       end
 
@@ -431,10 +700,6 @@ module Portage
         @notifier ||= Notifier.new(webhook_url: @notify_webhook)
       end
 
-      # Every checkout that can't be finished by this process — no
-      # permission, no token, or an explicit requires_escalation — hands the
-      # shopper a URL rather than leaving them at a dead end.
-      #
       # `continue_url` first, because on a real store it is the only field
       # that ever holds the checkout. This used to be
       # `links.find { |l| l["url"] }` on the reasoning that not every
@@ -466,31 +731,35 @@ module Portage
         @yes
       end
 
-      def escalation_report(source, products, checkout)
-        url = checkout_url_of(checkout)
-        checkout_report(
-          source, products, checkout,
-          checkout_url: url, handoff: hand_off(checkout, reason: "requires_escalation", source: source),
-          message: "Checkout requires buyer escalation — visit the link to complete it."
-        )
-      end
-
-      def dry_run_report(source, products, checkout)
-        checkout_report(source, products, checkout, message: "Dry run — checkout created but not completed.")
+      def dry_run_report(source, products, checkout, warnings = [])
+        checkout_report(source, products, checkout, outcome: "dry_run", warnings: warnings,
+                                                    message: "Dry run — checkout created but not completed.")
       end
 
-      def confirmation_needed_report(source, products, checkout)
-        checkout_report(source, products, checkout, message: "Checkout ready — pass --yes to confirm the purchase.")
+      def confirmation_needed_report(source, products, checkout, warnings = [])
+        checkout_report(source, products, checkout, outcome: "needs_confirmation", warnings: warnings,
+                                                    message: "Checkout ready — pass --yes to confirm the purchase.")
       end
 
       # Flattens the parts of a Checkout wire hash a CLI caller actually
       # wants to see (id/status/totals) onto the report, rather than nesting
       # the raw hash under a key that'd collide with the boolean `checkout:`
-      # field the output struct already reserves (§ output shape).
-      def checkout_report(source, products, checkout, message:, checkout_url: nil, handoff: nil)
-        build_report(source: source, browse: true, checkout: true, products: products, message: message,
-                     checkout_url: checkout_url, checkout_id: checkout["id"], checkout_status: checkout["status"],
-                     totals: checkout["totals"], handoff: handoff)
+      # field the output struct already reserves (§ output shape). `items:`
+      # is what the checkout actually holds; `products:` is only what the
+      # search returned, most of which was never bought.
+      def checkout_report(source, products, checkout, outcome:, message:, checkout_url: nil, handoff: nil,
+                          warnings: [])
+        build_report(source: source, outcome: outcome, browse: true, checkout: true, products: products,
+                     message: message, checkout_url: checkout_url, checkout_id: checkout["id"],
+                     checkout_status: checkout["status"], currency: checkout["currency"],
+                     totals: checkout["totals"], items: checkout_items(checkout), handoff: handoff,
+                     warnings: warnings, decisions: @decisions.dup)
+      end
+
+      def checkout_items(checkout)
+        Array(checkout["line_items"]).map do |line|
+          { id: line.dig("item", "id"), title: line.dig("item", "title"), quantity: line["quantity"] }
+        end
       end
 
       def safe_search(session)
@@ -502,7 +771,17 @@ module Portage
       # prices — a call is scoped to from this (see
       # Portage::Cli::BuyerContext). The loopback/stdio transports drop it.
       def buyer_context
-        @buyer_context ||= BuyerContext.from_env
+        @buyer_context ||= BuyerContext.from_env.tap do |ctx|
+          next unless ctx.empty?
+
+          # See BuyerContext's own comment: a live Shopify store scoped a
+          # cart to no market and dropped every line item with no context at
+          # all, reporting `merchandise_out_of_stock` for products its own
+          # search just returned. That failure mode looks like a store bug
+          # from the report alone — this names the likely cause up front.
+          warn "portage: no buyer context set (#{BuyerContext::ENV_VARS.values.join(', ')}) — some stores " \
+               "drop line items or misprice without one. Set at least PORTAGE_SHIP_COUNTRY."
+        end
       end
 
       # Real UCP servers fetch this URL to verify the caller's identity
@@ -537,12 +816,12 @@ module Portage
       end
 
       def dead_end
-        build_report(source: "none", browse: false, checkout: false,
+        build_report(source: "none", outcome: "dead_end", browse: false, checkout: false,
                      message: "No automated path — visit #{@uri} yourself.")
       end
 
       def build_report(**fields)
-        { url: @uri.to_s, checkout_url: nil, products: [] }.merge(fields)
+        { url: @uri.to_s, checkout_url: nil, products: [], warnings: [] }.merge(fields)
       end
 
       # Loopback buy against your own store needs *some* authenticator (§9

data/lib/portage/cli/checkout_handoff.rb

@@ -1,5 +1,6 @@
 require "uri"
 require_relative "config"
+require_relative "setting"
 
 module Portage
   module Cli
@@ -8,10 +9,10 @@ module Portage
     # (escalation, permission denied, no payment token) hands off a link
     # rather than completing the purchase itself.
     #
-    # Default off. Precedence for the toggle (open decision #1, resolved):
-    # a per-invocation `auto_open:` override (portage buy --auto-open /
-    # --no-auto-open) beats PORTAGE_AUTO_OPEN_CHECKOUT, which beats
-    # ~/.portage/config.json's "auto_open_checkout" (Config).
+    # Default off. Precedence for the toggle (open decision #1, resolved,
+    # see Setting): a per-invocation `auto_open:` override (portage buy
+    # --auto-open / --no-auto-open) beats PORTAGE_AUTO_OPEN_CHECKOUT, which
+    # beats ~/.portage/config.json's "auto_open_checkout" (Config).
     #
     # No new gem for the actual open — every other shell-out in this repo
     # (PaymentMethods::KeychainBackend, SecretServiceBackend) hand-rolls
@@ -22,7 +23,6 @@ module Portage
     class CheckoutHandoff
       ENV_VAR = "PORTAGE_AUTO_OPEN_CHECKOUT".freeze
       CONFIG_KEY = "auto_open_checkout".freeze
-      TRUE_VALUES = %w[1 true yes].freeze
 
       def initialize(auto_open: nil, config: Config.load)
         @override = auto_open
@@ -30,12 +30,7 @@ module Portage
       end
 
       def auto_open?
-        return @override unless @override.nil?
-
-        env = env_override
-        return env unless env.nil?
-
-        !!@config.get(CONFIG_KEY)
+        Setting.flag?(override: @override, env: ENV_VAR, config: @config, config_key: CONFIG_KEY)
       end
 
       # @return [Boolean] whether the browser was actually opened.
@@ -47,13 +42,6 @@ module Portage
 
       private
 
-      def env_override
-        raw = ENV.fetch(ENV_VAR, nil)
-        return nil if raw.nil?
-
-        TRUE_VALUES.include?(raw.downcase)
-      end
-
       def https?(url)
         URI.parse(url).scheme == "https"
       rescue URI::InvalidURIError