portage-cli 0.6.4 → 0.7.3

data/lib/portage/cli/buy.rb

@@ -5,8 +5,18 @@ 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"
+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
@@ -37,11 +47,35 @@ 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.
+      # @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)
+                     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
@@ -50,6 +84,11 @@ module Portage
         @product_id = product_id
         @auto_open = auto_open
         @notify_webhook = notify_webhook
+        @confidence_check = confidence_check
+        @transaction_log = transaction_log
+        @max_price = max_price
+        @webmcp_bridge = webmcp_bridge
+        @decisions = {}
       end
 
       # Link `type`s that are never the checkout — see #checkout_url_of.
@@ -67,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
@@ -76,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:
@@ -103,11 +145,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 +159,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 +182,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 +190,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 +206,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> ---
@@ -177,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)
@@ -189,6 +295,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 +320,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 +354,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.'}"
@@ -258,11 +379,15 @@ 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
-          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 +395,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, force_handoff: force_handoff)
+      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
@@ -330,20 +493,52 @@ 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
       # 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.
+      #
+      # 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)
-        return products.first unless @product_id
+        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)
+        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 +557,197 @@ 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 = [], 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)
+      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
+
+        held = held_report(source, products, checkout, warnings)
+        return held if held
 
-        completed = session.complete_checkout(checkout_id: checkout["id"], payment_token: @payment_token)
-        checkout_report(source, products, completed, message: "Purchased.")
+        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 +755,41 @@ 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, 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
@@ -417,24 +799,77 @@ 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.
+      #
+      # 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, checkout_url: url,
-                              checkout_id: checkout["id"], source: source, totals: checkout["totals"])
-        { 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
         @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 +901,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."
-        )
+      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 dry_run_report(source, products, checkout)
-        checkout_report(source, products, checkout, 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 +941,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
@@ -517,40 +966,16 @@ 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
-        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)
-      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
+        { url: @uri.to_s, checkout_url: nil, products: [], warnings: [] }.merge(fields)
       end
     end
   end