portage-cli 0.7.4 → 0.8.0

data/lib/portage/cli/buy.rb

@@ -4,12 +4,17 @@ require "json"
 require "portage/ucp"
 require "portage/ucp/client"
 require "portage/ucp/journal"
+require_relative "agent_profile_url"
 require_relative "payment_methods"
 require_relative "setting"
 require_relative "decisions"
 require_relative "confidence_check"
 require_relative "checkout_handoff"
 require_relative "notifier"
+require_relative "handoff_only"
+require_relative "offer_sources"
+require_relative "handoff_target"
+require_relative "handoff_agents"
 require_relative "user_agent"
 require_relative "homepage_fetch"
 require_relative "permissive_authenticator"
@@ -17,6 +22,11 @@ require_relative "handoff_reconciler"
 require_relative "handoff_spend_mode"
 require_relative "webmcp"
 require_relative "webmcp_checkout_mode"
+require_relative "webmcp_mappings"
+require_relative "webmcp_mapping_confirm"
+require_relative "webmcp_autofill_mode"
+require_relative "webmcp_autofill_fields"
+require_relative "webmcp_autofill_confirm"
 
 module Portage
   module Cli
@@ -47,6 +57,13 @@ 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 handoff_target [HandoffTarget, nil] docs/plans/
+      #   buy-skill-and-local-browser.md Phase 5 — which of default/print/
+      #   profile/agent:<name> a hand-off dispatches to. nil (the default)
+      #   builds one from PORTAGE_HANDOFF_TARGET/config.json with no
+      #   per-invocation override — `Cli.run_buy` builds and validates one
+      #   from `--handoff-target` up front instead, the same posture as
+      #   `confidence_check:`.
       # @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
@@ -63,17 +80,48 @@ module Portage
       # @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
+      #   already holds. nil (the default) 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).
+      #   docs/plans/buy-skill-and-local-browser.md Phase 6: `portage buy`
+      #   from the shell now builds one itself — a
+      #   Portage::Cli::BrowserProfile::Bridge onto the Portage browser
+      #   profile — whenever `--handoff-target profile` resolves and that
+      #   profile is running (`Cli.profile_webmcp_bridge`); any other
+      #   target still leaves this nil, the CLI's original "no browser of
+      #   its own" posture.
+      # @param webmcp_mappings [Portage::Cli::WebmcpMappings, nil] Phase 2's
+      #   confirmed-mapping store (docs/plans/webmcp-universal-outbound.md).
+      #   nil (the default) builds the real `~/.portage/webmcp_mappings.json`
+      #   -backed one lazily, only if #webmcp_matched_session ever runs —
+      #   injectable so specs don't touch it.
+      # @param webmcp_mapping_confirm [Portage::Cli::WebmcpMappingConfirm, nil]
+      #   Phase 2's confirm-before-mutate gate. nil (the default) builds one
+      #   from whether stdin is a real TTY and `json:` is off — injectable so
+      #   a spec can simulate an interactive "y" without a real terminal.
+      # @param json [Boolean] whether this run is `--json` — Phase 2's
+      #   mapping confirmation prompt never fires under it (same posture as
+      #   "no TTY"), since a caller reading structured stdout has nowhere to
+      #   put an interactive prompt.
+      # @param autofill [Boolean, nil] docs/plans/webmcp-universal-outbound.md
+      #   Phase 3 — `--autofill`'s value: true when the flag was passed, nil
+      #   (the default) otherwise. Only ever turns WebmcpAutofillMode on;
+      #   `PORTAGE_WEBMCP_AUTOFILL=approve`/config.json still work with this
+      #   left nil. Approving the mode is still only half of Phase 3's
+      #   opt-in — see #webmcp_autofill_confirm.
+      # @param webmcp_autofill_confirm [Portage::Cli::WebmcpAutofillConfirm, nil]
+      #   Phase 3's per-run "fill exactly these fields?" prompt. nil (the
+      #   default) builds one from the same interactive? posture as Phase
+      #   2's webmcp_mapping_confirm; injectable so a spec can simulate an
+      #   interactive "y" without a real terminal.
+      # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength -- all keywords; one per flag, plus
+      # injectable collaborators, each assigned to its own ivar
       def initialize(url:, query:, qty: 1, payment_token: nil, yes: false, dry_run: false, product_id: nil,
-                     auto_open: nil, notify_webhook: nil, confidence_check: nil, transaction_log: nil,
-                     max_price: nil, webmcp_bridge: nil)
-        # rubocop:enable Metrics/ParameterLists
+                     auto_open: nil, notify_webhook: nil, handoff_target: nil, confidence_check: nil,
+                     transaction_log: nil, max_price: nil, webmcp_bridge: nil, webmcp_mappings: nil,
+                     webmcp_mapping_confirm: nil, autofill: nil, webmcp_autofill_confirm: nil, json: false)
+        # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
         raw = url.to_s.strip
         @uri = URI.parse(raw =~ %r{\Ahttps?://}i ? raw : "https://#{raw}")
         @query = query
@@ -84,9 +132,15 @@ module Portage
         @product_id = product_id
         @auto_open = auto_open
         @notify_webhook = notify_webhook
+        @handoff_target = handoff_target
         @confidence_check = confidence_check
         @transaction_log = transaction_log
         @max_price = max_price
+        @webmcp_mappings = webmcp_mappings
+        @webmcp_mapping_confirm = webmcp_mapping_confirm
+        @autofill = autofill
+        @webmcp_autofill_confirm = webmcp_autofill_confirm
+        @json = json
         @webmcp_bridge = webmcp_bridge
         @decisions = {}
       end
@@ -95,6 +149,8 @@ module Portage
       POLICY_LINK_TYPES = /policy|policies|terms|contact|privacy|legal|imprint/i
 
       def call
+        return handoff_only_report if handoff_only?
+
         session = discover(@uri)
         return native_flow(session) if session
 
@@ -115,6 +171,90 @@ module Portage
 
       private
 
+      # --- Step 0: hand-off-only hosts (Tier C) ---
+
+      # Checked before anything else in #call so a hand-off-only host never
+      # sees a single request from this process — no UCP probe, no
+      # homepage fetch, no cart (docs/plans/buy-skill-and-local-browser.md
+      # Phase 5, decision 5). Amazon by default; ~/.portage/config.json's
+      # "handoff_only_hosts" is the user's own list (see HandoffOnly).
+      def handoff_only?
+        @handoff_only ||= HandoffOnly.new
+        return true if @handoff_only.host?(@uri.host)
+        return true if OfferSources.retail_handoff_host?(@uri.host)
+
+        etsy_buyer_host?
+      end
+
+      # Phase 7 (docs/plans/buy-skill-and-local-browser.md):
+      # portage-ucp-etsy is a *seller*-side adapter — a shop owner with
+      # their own ETSY_* credentials set still reaches #adapter_flow
+      # unchanged below, the same "only your own store" rule every other
+      # adapter already gets (see the class comment at the top of this
+      # file). An ordinary buyer with no Etsy credentials of their own
+      # gets routed to hand-off here instead of a homepage fetch +
+      # platform detection that would just be scraping a stranger's
+      # listing — the buyer-side offer OfferSources::EtsyListings hands
+      # `find` has nothing this process can check out anyway.
+      def etsy_buyer_host?
+        HandoffOnly.matches_any?(@uri.host, %w[etsy.com]) && !etsy_adapter_configured?
+      end
+
+      def etsy_adapter_configured?
+        platform = Portage::Ucp::Resolver::PLATFORMS.find { |p| p.name == "Etsy" }
+        return false unless platform
+
+        Portage::Ucp::Resolver.missing_env(platform, Portage::Ucp::Resolver.env_for(platform)).empty?
+      end
+
+      # No checkout was ever built — there's nothing to browse or complete,
+      # just a link and why. `checkout_url` is built, never fetched: the
+      # product page/cart-add URL when a product id is known (Amazon's own
+      # URL shape only — that's the only pattern this phase knows), or the
+      # retailer's own search URL for the query, or (a user-added host with
+      # no known pattern) the origin's homepage.
+      def handoff_only_report
+        url = handoff_only_checkout_url
+        handoff = @dry_run ? nil : dispatch_handoff_only(url)
+        build_report(source: "handoff_only", outcome: "handoff_only", browse: false, checkout: false,
+                     checkout_url: url, legal_notice: HandoffOnly::LEGAL_NOTICE, handoff: handoff,
+                     message: "#{@uri.host} restricts automated purchasing agents — Portage opens the page " \
+                              "and you buy.")
+      end
+
+      def dispatch_handoff_only(url)
+        payload = handoff_notify_payload({}, url, reason: "handoff_only", source: "handoff_only",
+                                                  message: "Hand-off-only retailer — no automated checkout " \
+                                                           "was attempted.", warnings: [], over_cap: false)
+        finalize_handoff(url, dispatch_to_target(url, payload), notified: false, notify_error: nil)
+      end
+
+      def handoff_only_checkout_url
+        return amazon_checkout_url if HandoffOnly.amazon?(@uri.host)
+        return @uri.to_s if OfferSources.retail_handoff_host?(@uri.host) || etsy_buyer_host?
+
+        origin_homepage
+      end
+
+      def amazon_checkout_url
+        return amazon_cart_add_url if @product_id
+        return amazon_search_url unless @query.to_s.strip.empty?
+
+        origin_homepage
+      end
+
+      def amazon_search_url
+        "#{origin}/s?k=#{URI.encode_www_form_component(@query.to_s)}"
+      end
+
+      def amazon_cart_add_url
+        "#{origin}/gp/aws/cart/add.html?ASIN.1=#{URI.encode_www_form_component(@product_id.to_s)}&Quantity.1=#{@qty}"
+      end
+
+      def origin_homepage = "#{origin}/"
+
+      def origin = "#{@uri.scheme}://#{@uri.host}"
+
       # --- Step 1: native UCP manifest ---
 
       def discover(url)
@@ -242,22 +382,267 @@ module Portage
       # 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.
+      #
+      # `preset_name` is resolved once here (docs/plans/
+      # webmcp-universal-outbound.md Phase 1, decision 1) and handed to
+      # `connect` explicitly (a nil/Symbol either way skips its own
+      # detection) so the same answer also tells this method whether the
+      # page's checkout capability came from a real `create_checkout` tool
+      # or only from a preset's hand-off-only one — see
+      # #webmcp_handoff_checkout_flow.
+      #
+      # When a plain connect (no preset, no tool_names:) doesn't advertise
+      # cart+checkout, and no preset matched, #webmcp_matched_session (Phase
+      # 2) is the fallback: a confirmed mapping from a prior run, or a fresh
+      # one proposed by `Matcher` and confirmed here. A page that already
+      # speaks either a preset's names or the plain UCP action names never
+      # reaches it at all — Transport's own tool_names:/bare-action
+      # resolution already covers both, with nothing to confirm.
       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)
+        preset_name = webmcp_preset_name
+        session, unresolved = webmcp_session(preset_name)
+        return unresolved if unresolved
+        return nil unless session
 
         return webmcp_token_unsupported_report if webmcp_checkout_mode == "token"
 
-        full_buy(session, source: "webmcp", force_handoff: true)
+        run_webmcp_checkout(session, preset_name)
       rescue Portage::Ucp::WebMcp::BridgeError, Portage::Ucp::WebMcp::ToolNotFoundError,
              Portage::Ucp::Client::ServerError => e
+        # A Portage::Cli::BrowserProfile::DomainNotAllowedError (Phase 6's
+        # domain allowlist, tripped inside Bridge#evaluate) always surfaces
+        # here as a BridgeError — Bridges::ScriptEvaluator#evaluate wraps
+        # whatever its injected evaluate: callable raises, StandardError
+        # included, so there's no separate rescue clause for it.
         build_report(source: "webmcp", outcome: "webmcp_error", browse: false, checkout: false,
                      message: "WebMCP checkout failed: #{e.message}")
       end
 
+      # Split out of #webmcp_flow just to keep its own branching (bridge
+      # given?, gem installed?, cart/checkout capable?, token mode?) from
+      # also carrying the Phase 2 fallback fork (Metrics/CyclomaticComplexity)
+      # — same reasoning as #run_webmcp_checkout's own split.
+      #
+      # @return [Array(Session, nil)] a cart/checkout-capable session.
+      # @return [Array(nil, nil)] no cart/checkout capability anywhere —
+      #   #webmcp_flow falls through to adapter detection, same as before
+      #   Phase 2 existed.
+      # @return [Array(nil, Hash)] a webmcp_mapping_unconfirmed report.
+      def webmcp_session(preset_name)
+        session = Portage::Ucp::WebMcp.connect(bridge: @webmcp_bridge, preset: preset_name)
+        return [session, nil] if webmcp_cart_and_checkout?(session)
+        return [nil, nil] if preset_name
+
+        matched, unresolved = webmcp_matched_session
+        return [nil, unresolved] if unresolved
+        return [nil, nil] unless webmcp_cart_and_checkout?(matched)
+
+        [matched, nil]
+      end
+
+      def webmcp_cart_and_checkout?(session)
+        session&.advertises?(CART_CAP) && session.advertises?(CHECKOUT_CAP)
+      end
+
+      # Phase 2 fallback (docs/plans/webmcp-universal-outbound.md): a
+      # previously confirmed mapping for this exact tool fingerprint is
+      # reused with no prompt (decision 3); otherwise `Matcher.propose`
+      # builds one and #webmcp_mapping_confirm decides whether it can be
+      # used — reads unconditionally, mutating actions only once approved.
+      #
+      # @return [Array(Session, nil)] a session built with the resolved
+      #   tool_names:, when there was anything to resolve.
+      # @return [Array(nil, nil)] nothing usable — the page has no tools a
+      #   candidate scored high enough against; #webmcp_flow's own
+      #   post-connect capability check reports it same as any other
+      #   cart/checkout-incapable page.
+      # @return [Array(nil, Hash)] a webmcp_mapping_unconfirmed report, when
+      #   a mutating action was proposed but couldn't be confirmed.
+      def webmcp_matched_session
+        tools = @webmcp_bridge.list_tools
+        tool_names = webmcp_mappings.lookup(tools)
+
+        if tool_names.nil?
+          proposal = Portage::Ucp::WebMcp::Matcher.propose(tools)
+          return [nil, nil] if proposal.empty?
+
+          tool_names = webmcp_mapping_confirm.call(proposal, tools)
+          return [nil, webmcp_mapping_unconfirmed_report(proposal)] if tool_names.nil?
+
+          webmcp_mappings.confirm!(tools, tool_names: tool_names, origin: @uri.host)
+        end
+
+        [Portage::Ucp::WebMcp.connect(bridge: @webmcp_bridge, preset: nil, tool_names: tool_names), nil]
+      end
+
+      def webmcp_mappings
+        @webmcp_mappings ||= Portage::Cli::WebmcpMappings.load
+      end
+
+      def webmcp_mapping_confirm
+        @webmcp_mapping_confirm ||= Portage::Cli::WebmcpMappingConfirm.new(interactive: !@json && $stdin.tty?)
+      end
+
+      def webmcp_mapping_unconfirmed_report(proposal)
+        build_report(
+          source: "webmcp", outcome: "webmcp_mapping_unconfirmed", browse: false, checkout: false,
+          message: "This page's WebMCP tools don't match a known preset. Here's the proposed mapping — " \
+                   "confirm it and retry, passing it back as tool_names:, or run this interactively (a real " \
+                   "TTY, no --json) to confirm it now.",
+          tool_names_proposal: webmcp_serialize_proposal(proposal)
+        )
+      end
+
+      def webmcp_serialize_proposal(proposal)
+        proposal.transform_values do |match|
+          { tool_name: match.tool, confidence: match.confidence, reason: match.reason }
+        end
+      end
+
+      def webmcp_preset_name
+        Portage::Ucp::WebMcp::Presets.detect(@webmcp_bridge.list_tools)
+      end
+
+      # Split out of #webmcp_flow just to keep that method's own branching
+      # (bridge given?, gem installed?, cart/checkout capable?, token mode?)
+      # from also carrying this preset-shaped fork (Metrics/CyclomaticComplexity).
+      def run_webmcp_checkout(session, preset_name)
+        preset = preset_name && Portage::Ucp::WebMcp::Presets.fetch(preset_name)
+        return webmcp_handoff_checkout_flow(session, preset) if preset&.handoff_checkout
+
+        full_buy(session, source: "webmcp", force_handoff: true)
+      end
+
+      # A preset whose fingerprint has no `create_checkout` tool at all —
+      # Shopify's is the only one so far (see Presets::SHOPIFY) — can't run
+      # #full_buy's `session.create_checkout`; there's nothing on the page to
+      # call it against. Builds a cart, reads it back through the (already
+      # cart/checkout-capable, per the gate in #webmcp_flow) session so
+      # #reconcile_checkout has a `get_cart`-shaped document to check against
+      # (there's no checkout document either), then calls the preset's
+      # `handoff_checkout` tool directly on the bridge — after the cart
+      # read-back, not before, so any post-mutation "page not ready" gap
+      # (see Transport's own retry) has already been waited out by then.
+      #
+      # The checkout URL comes from whatever the hand-off tool itself
+      # returns, or — Shopify's `proceed_to_checkout` is a navigation, not
+      # data, and returns nothing url-shaped (README "Shopify storefronts")
+      # — from the bridge's own `#location` once the tab has navigated
+      # there, when the bridge offers one (Bridges::ScriptEvaluator does).
+      #
+      # Once the tab has navigated to that checkout page, this is also
+      # where Phase 3's autofill runs (#attempt_webmcp_autofill) — the bridge's
+      # browser is sitting on the store's own checkout, cart already built,
+      # which is exactly the moment (and the only flow) autofill needs: a
+      # real checkout DOM, not a UCP checkout wire object #full_buy never
+      # navigates a browser to at all.
+      def webmcp_handoff_checkout_flow(session, preset)
+        products = safe_search(session)
+        product = select_product(products)
+        unless product
+          return build_report(source: "webmcp", outcome: "no_match", browse: true, checkout: true,
+                              products: products, message: no_match_message)
+        end
+        return webmcp_handoff_dry_run_report(products, product, preset) if @dry_run
+
+        created = session.create_cart(line_items: [{ product_id: line_item_id_of(product), quantity: @qty }],
+                                      context: buyer_context, meta: agent_meta)
+        cart = session.get_cart(cart_id: created["id"], meta: agent_meta)
+        warnings = reconcile_checkout(product, cart)
+
+        result = @webmcp_bridge.execute_tool(preset.handoff_checkout, {})
+        autofill = attempt_webmcp_autofill(preset)
+        webmcp_handoff_report("webmcp", products, cart.merge("continue_url" => url_from_handoff(result)), warnings,
+                              autofill: autofill)
+      end
+
+      # Unlike #full_buy's dry run (which still creates a UCP checkout, since
+      # that's a document the store drops on its own), a dry run here stops
+      # before `create_cart`: every step after it changes something outside
+      # this process — a real cart on the store, the bridge's own tab
+      # navigated to checkout, and (with autofill on) typing into that page.
+      # None of that is safe to do on a preview run, so this only reports
+      # what the run would have done. No checkout_id either, so History
+      # records it as a search, not a purchase.
+      def webmcp_handoff_dry_run_report(products, product, preset)
+        build_report(
+          source: "webmcp", outcome: "dry_run", browse: true, checkout: true, products: products, handoff: nil,
+          decisions: @decisions.dup,
+          would: { line_items: [{ product_id: line_item_id_of(product), quantity: @qty }],
+                   handoff_checkout: preset.handoff_checkout, autofill: webmcp_autofill_approved? },
+          message: "Dry run — would add #{product['title'] || line_item_id_of(product)} to the store's cart and " \
+                   "hand off through #{preset.handoff_checkout}. Nothing was added, and no checkout was opened."
+        )
+      end
+
+      # Best-effort: the hand-off tool's own result shape isn't documented
+      # anywhere in this repo (see Presets::SHOPIFY's comment on
+      # `update_cart_lines`/`proceed_to_checkout`), so this only recognizes
+      # the shapes any WebMCP tool result already comes back in — a bare URL
+      # string, or a Hash carrying one under `url`/`continue_url` — before
+      # falling back to the bridge's own location.
+      def url_from_handoff(result)
+        from_result = case result
+                      when String then result if result.start_with?("http")
+                      when Hash then result["url"] || result["continue_url"]
+                      end
+        from_result || (@webmcp_bridge.location if @webmcp_bridge.respond_to?(:location))
+      end
+
+      # docs/plans/webmcp-universal-outbound.md Phase 3. Three gates, in
+      # order, any of which means nothing gets typed:
+      #   1. WebmcpAutofillMode off (the default) — no attempt at all, same
+      #      shape the report had before Phase 3 existed (no `autofill:` key).
+      #   2. Nothing to fill — no PORTAGE_SHIP_*/PORTAGE_SHIP_EMAIL
+      #      configured.
+      #   3. The shopper doesn't approve the exact fields/values in
+      #      #webmcp_autofill_confirm's prompt (decision 2) — including
+      #      "can't even ask", under --json or with no TTY.
+      # Past those, Portage::Ucp::WebMcp::Autofill (portage-ucp-webmcp) does
+      # the actual work against the checkout page the bridge's browser has
+      # already navigated to; its own gates (headless?, a CAPTCHA/challenge
+      # on the page) apply independently of these three.
+      #
+      # @return [Hash, nil] nil when gate 1 or 2 stopped this before ever
+      #   reaching the shopper — the report gets no `autofill:` key at all,
+      #   same as before Phase 3. Otherwise a Hash with a stable `outcome:`
+      #   (`autofill_declined`, `autofill_needs_headed_browser`,
+      #   `autofill_blocked`, `autofill_unsupported`, `autofill_filled`) plus
+      #   whatever `filled:`/`unmatched:`/`rate:` Autofill reported.
+      def attempt_webmcp_autofill(preset)
+        return nil unless webmcp_autofill_approved?
+
+        fields = Portage::Cli::WebmcpAutofillFields.build
+        return nil if fields.empty?
+        return { outcome: "autofill_declined" } unless webmcp_autofill_confirm.call(fields)
+
+        result = webmcp_autofill.call(bridge: @webmcp_bridge, fields: fields, selectors: preset.checkout_selectors)
+        { outcome: "autofill_#{result.outcome}", filled: result.filled, unmatched: result.unmatched,
+          rate: result.rate }
+      end
+
+      def webmcp_autofill_approved?
+        Portage::Cli::WebmcpAutofillMode.approved?(override: @autofill)
+      end
+
+      def webmcp_autofill_confirm
+        @webmcp_autofill_confirm ||= Portage::Cli::WebmcpAutofillConfirm.new(interactive: !@json && $stdin.tty?)
+      end
+
+      # Injectable so a spec can stand in for portage-ucp-webmcp's real
+      # Autofill without a real browser (same reasoning as
+      # webmcp_mappings/webmcp_mapping_confirm above) — nil by default
+      # rather than a constructor kwarg since it's only ever reached once
+      # `webmcp_bridge:` and autofill are both already in play, deep enough
+      # into #call that a kwarg here would rarely be worth threading through
+      # every other spec's Buy.new.
+      def webmcp_autofill
+        @webmcp_autofill ||= Portage::Ucp::WebMcp::Autofill
+      end
+
       def webmcp_checkout_mode
         Portage::Cli::WebmcpCheckoutMode.resolve
       end
@@ -513,11 +898,26 @@ module Portage
       # 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).
+      # A --product-id match also checks each product's own variants, not
+      # just its top-level id: OfferSources::ShopifyCatalog hands Find an
+      # offer whose product_id is the merchant's own variant gid (the
+      # catalog's own product id is a global one the merchant doesn't
+      # recognise — see that class), so the product carrying it is found by
+      # its variant, not its id.
       def select_product(products)
         products = products.select { |product| within_max_price?(product) }
         return products.find { |product| available?(product) } || products.first unless @product_id
 
-        products.find { |product| product_id_of(product) == @product_id }
+        products.find { |product| product_id_of(product) == @product_id || variant_matching(product, @product_id) }
+      end
+
+      # nil `id` matches nothing — a product's variants are never searched
+      # for a nil id, the same way #select_product's own `unless @product_id`
+      # branch never gets here without one.
+      def variant_matching(product, id)
+        return nil unless id
+
+        Array(product["variants"]).find { |variant| variant["id"] == id }
       end
 
       # Priced the way #reconcile_checkout expects the store to charge: the
@@ -561,6 +961,9 @@ module Portage
       # 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)
+        matched = variant_matching(product, @product_id)
+        return matched["id"] if matched
+
         variants = Array(product["variants"])
         (variants.find { |variant| variant_available?(variant) } || variants.first)&.dig("id") ||
           product_id_of(product)
@@ -773,11 +1176,14 @@ module Portage
       # (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:)
+      # @param extra [Hash] merged straight onto the report — Phase 3's
+      #   `autofill:` (see #webmcp_handoff_report) is the only caller today.
+      def handoff_report(source, products, checkout, warnings, outcome:, message:, extra: {})
         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)
+                                                    checkout_url: checkout_url_of(checkout), handoff: handoff,
+                                                    **extra)
       end
 
       # docs/plans/handoff-reconcile.md Phase 4 — #webmcp_flow's
@@ -786,10 +1192,18 @@ module Portage
       # 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)
+      #
+      # @param autofill [Hash, nil] docs/plans/webmcp-universal-outbound.md
+      #   Phase 3 — #webmcp_handoff_checkout_flow's own autofill attempt
+      #   (#attempt_webmcp_autofill), attached as the report's `autofill:`
+      #   key when there was one to attach. nil (the default, and always for
+      #   #finish_checkout's own force_handoff call) adds no key at all —
+      #   the report is byte-for-byte what it was before Phase 3 existed.
+      def webmcp_handoff_report(source, products, checkout, warnings, autofill: nil)
         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)
+        extra = autofill ? { autofill: autofill } : {}
+        handoff_report(source, products, checkout, warnings, outcome: "express_stop", message: message, extra: extra)
       end
 
       # Never fires on --dry-run (a dry run creates a real checkout but never
@@ -816,20 +1230,98 @@ module Portage
         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
-
+        payload = handoff_notify_payload(checkout, url, reason: reason, source: source, message: message,
+                                                        warnings: warnings, over_cap: over_cap)
+        dispatch = over_cap ? { target: handoff_target.label, opened: false } : dispatch_to_target(url, payload)
+        error = notifier.call(payload)
+        finalize_handoff(url, dispatch, notified: notifier.enabled? && error.nil?, notify_error: error,
+                                        over_cap: over_cap)
+      end
+
+      # Same payload for both `--notify-webhook` and `agent:<name>`
+      # (docs/plans/buy-skill-and-local-browser.md Phase 5, decision 3): the
+      # checkout URL plus the approved cart summary — items, qty (each
+      # item's own `quantity`), total (`totals`) and store. Reused as-is
+      # for #handoff_only_report with `checkout: {}` — no cart was ever
+      # built there, so `checkout_id`/`totals`/`items` come back nil/empty,
+      # never fabricated.
       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 }
+                    totals: checkout["totals"], items: checkout_items(checkout), warnings: warnings }
         over_cap ? payload.merge(over_cap: true) : payload
       end
 
+      # docs/plans/buy-skill-and-local-browser.md Phase 5 — routes a
+      # hand-off to whichever target `--handoff-target`/PORTAGE_HANDOFF_TARGET/
+      # config.json resolved to. `payload` is only used by the `agent`
+      # branch; building it unconditionally is cheap and keeps this method
+      # a plain dispatch with no branching on whether it's needed.
+      def dispatch_to_target(url, payload)
+        case handoff_target.kind
+        when "print" then { target: "print", opened: false }
+        when "profile" then dispatch_to_profile(url)
+        when "agent" then dispatch_to_agent(payload)
+        else { target: "default", opened: CheckoutHandoff.new(auto_open: @auto_open).call(url) }
+        end
+      end
+
+      # docs/plans/buy-skill-and-local-browser.md Phase 6: when this run
+      # already has a Portage browser profile bridge attached (`Cli.
+      # profile_webmcp_bridge`, only when `--handoff-target profile`
+      # resolved and the profile was running), navigate that same browser
+      # to the checkout URL — the cart was built there too, when the
+      # WebMCP flow ran, or is about to be paid there for the first time,
+      # for a native-UCP store. `#navigate` permits the URL's own host
+      # first (the "plus its checkout host" half of the allowlist), so
+      # this is never blocked by the allowlist itself; it's the one
+      # deliberate Portage-initiated navigation the allowlist always lets
+      # through. Any other bridge failure (the profile process died mid
+      # run, a stale WebSocket) is reported rather than raised, same
+      # posture as every other hand-off dispatch.
+      def dispatch_to_profile(url)
+        unless @webmcp_bridge.respond_to?(:navigate)
+          return { target: "profile", opened: false,
+                   message: "No Portage browser profile is attached — run `portage browser profile open` " \
+                            "first, then retry with --handoff-target profile." }
+        end
+
+        @webmcp_bridge.navigate(url)
+        { target: "profile", opened: true }
+      rescue StandardError => e
+        { target: "profile", opened: false, message: "Couldn't open the checkout in the Portage browser " \
+                                                     "profile (#{e.message}) — showing the link instead." }
+      end
+
+      def dispatch_to_agent(payload)
+        agent = handoff_agents.lookup(handoff_target.agent_name)
+        unless agent
+          return { target: handoff_target.label, opened: false, agent_delivered: false,
+                   agent_error: "#{handoff_target.agent_name.inspect} isn't approved in " \
+                                "~/.portage/config.json's handoff_agents — showing the link instead." }
+        end
+
+        error = agent.call(payload)
+        { target: handoff_target.label, opened: false, agent_delivered: error.nil?, agent_error: error }
+      end
+
+      def finalize_handoff(url, dispatch, notified:, notify_error:, over_cap: false)
+        result = { url: url, opened: dispatch[:opened], notified: notified, notify_error: notify_error,
+                   handoff_target: dispatch[:target] }
+        result[:agent_delivered] = dispatch[:agent_delivered] if dispatch.key?(:agent_delivered)
+        result[:agent_error] = dispatch[:agent_error] if dispatch.key?(:agent_error)
+        result[:target_message] = dispatch[:message] if dispatch[:message]
+        over_cap ? result.merge(over_cap: true) : result
+      end
+
+      def handoff_target
+        @handoff_target ||= HandoffTarget.new
+      end
+
+      def handoff_agents
+        @handoff_agents ||= HandoffAgents.new
+      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
@@ -918,12 +1410,12 @@ module Portage
       # 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: [])
+                          warnings: [], **extra)
         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)
+                     warnings: warnings, decisions: @decisions.dup, **extra)
       end
 
       def checkout_items(checkout)
@@ -959,7 +1451,7 @@ module Portage
       # loopback path ignores it harmlessly, so it's cheapest to always pass
       # it rather than branch on which transport `session` happens to be.
       def agent_meta
-        { agent_profile: ENV.fetch("PORTAGE_AGENT_PROFILE", nil) }
+        { agent_profile: AgentProfileUrl.resolve }
       end
 
       # --- Homepage fetch (used by both the manifest-not-found path and the