portage-cli 0.6.0 → 0.7.0

data/lib/portage/cli/buyer_context.rb

@@ -0,0 +1,42 @@
+module Portage
+  module Cli
+    # Builds the UCP `context` object — the buyer locale hints a real store
+    # resolves a market from — out of the same `PORTAGE_SHIP_*` environment
+    # Portage::Cli::ShippingProfile reads, plus two of its own.
+    #
+    # Separate from ShippingProfile rather than a method on it because the two
+    # have opposite completeness rules. A shipping *address* is all-or-nothing:
+    # ShippingProfile returns nil unless every required field is set, since a
+    # half-filled address can't be submitted and this CLI never guesses at the
+    # missing half. A context is explicitly partial by design ("provisional
+    # context hints ... unsupported hints may be ignored without error"), and
+    # a country alone is enough to resolve a market, so sending what's known
+    # beats sending nothing.
+    #
+    # Sending nothing is the part that actually mattered: without a context,
+    # a live Shopify store builds a cart scoped to no market, drops every line
+    # item, and reports `merchandise_out_of_stock` for products its own
+    # `search_catalog` just returned as available (confirmed live 2026-09-22,
+    # see docs/ucp-tool-gating-investigation.md). So this returns `{}` rather
+    # than nil when nothing is configured — a caller passes it through either
+    # way, and `Transports::Http#with_context` omits an empty one from the
+    # wire.
+    module BuyerContext
+      ENV_VARS = {
+        address_country: "PORTAGE_SHIP_COUNTRY",
+        address_region: "PORTAGE_SHIP_REGION",
+        postal_code: "PORTAGE_SHIP_POSTAL_CODE",
+        currency: "PORTAGE_CURRENCY",
+        language: "PORTAGE_LANGUAGE"
+      }.freeze
+
+      # @return [Hash] context hints, empty when none are configured
+      def self.from_env
+        ENV_VARS.filter_map do |key, var|
+          value = ENV.fetch(var, nil)
+          [key, value] unless value.nil? || value.empty?
+        end.to_h
+      end
+    end
+  end
+end

data/lib/portage/cli/checkout_handoff.rb

@@ -0,0 +1,70 @@
+require "uri"
+require_relative "config"
+require_relative "setting"
+
+module Portage
+  module Cli
+    # Phase 1 of docs/plans/checkout-handoff-delivery.md — auto-opens a
+    # checkout_url in the shopper's browser when a `Buy` dead-end
+    # (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,
+    # 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
+    # `system` rather than pulling in launchy for something the OS already
+    # provides. `system(cmd, url)` (array form, never an interpolated
+    # string) so a merchant-controlled checkout_url can't inject into a
+    # shell.
+    class CheckoutHandoff
+      ENV_VAR = "PORTAGE_AUTO_OPEN_CHECKOUT".freeze
+      CONFIG_KEY = "auto_open_checkout".freeze
+
+      def initialize(auto_open: nil, config: Config.load)
+        @override = auto_open
+        @config = config
+      end
+
+      def auto_open?
+        Setting.flag?(override: @override, env: ENV_VAR, config: @config, config_key: CONFIG_KEY)
+      end
+
+      # @return [Boolean] whether the browser was actually opened.
+      def call(checkout_url)
+        return false unless auto_open? && https?(checkout_url)
+
+        open_browser(checkout_url)
+      end
+
+      private
+
+      def https?(url)
+        URI.parse(url).scheme == "https"
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def open_browser(url)
+        command = platform_command
+        return false unless command
+
+        !!system(command, url)
+      rescue StandardError => e
+        warn "portage: couldn't open #{url} (#{e.message})"
+        false
+      end
+
+      def platform_command
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/i then "open"
+        when /linux|bsd/i then "xdg-open"
+        when /mswin|mingw|cygwin/i then "start"
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/confidence_check.rb

@@ -0,0 +1,127 @@
+require "json"
+require_relative "setting"
+require_relative "decisions"
+
+module Portage
+  module Cli
+    # The confidence gate (docs/plans/system-one-decision-layer.md
+    # § Responsibilities 3) as `portage buy` uses it: one yes/no question put
+    # to a Decision::ModelBackends backend right before an unattended
+    # (`--yes`) completion — "is this checkout what the shopper asked for,
+    # and safe to complete without a person looking at it?"
+    #
+    # Default off. Nothing asks a model anything unless a backend is named,
+    # via `--decision-backend NAME` or PORTAGE_DECISION_BACKEND (`jev` or
+    # `laya`, Decision::ModelBackends::REGISTRY's keys). The threshold comes
+    # from `--min-confidence N` or PORTAGE_MIN_CONFIDENCE, else
+    # DEFAULT_THRESHOLD.
+    #
+    # This answers the plan's open question about how the gate relates to
+    # `Confirmer`: it runs in front of the completion, after `--yes` and the
+    # local PolicyCheck, and never in place of either. A low score holds the
+    # purchase and hands the checkout to the shopper. It never
+    # auto-approves anything `--yes` wouldn't already have allowed.
+    #
+    # Fails closed. An unknown backend name, a backend that isn't configured
+    # (no JEV_API_KEY, no Laya bridge), or a backend call that fails all hold
+    # the purchase, the same as a low score does. So does naming a backend
+    # without portage-ucp-decision installed: the backends live in that
+    # optional gem. Once a caller has asked for a confidence check, the
+    # check never passing is not "no opinion".
+    class ConfidenceCheck
+      BACKEND_ENV = "PORTAGE_DECISION_BACKEND".freeze
+      THRESHOLD_ENV = "PORTAGE_MIN_CONFIDENCE".freeze
+      DEFAULT_THRESHOLD = 0.8
+      QUESTION = "safe_to_complete".freeze
+      # Phrased so "yes" means "proceed": a noul answer's value is the
+      # probability of yes, and that is what ConfidenceGate thresholds.
+      INSTRUCTIONS = "The state is a checkout an agent built on a shopper's behalf: the shopper's search " \
+                     "query, the merchant, the requested quantity, the checkout's line items and totals, and " \
+                     "any warnings about where the checkout differs from the request. Answer yes only if the " \
+                     "checkout clearly matches what the shopper asked for and is safe to complete without a " \
+                     "person reviewing it first.".freeze
+
+      # @param backend [String, nil] a ModelBackends::REGISTRY key; nil
+      #   defers to PORTAGE_DECISION_BACKEND.
+      # @param threshold [Float, nil] 0.0..1.0; nil defers to
+      #   PORTAGE_MIN_CONFIDENCE, then DEFAULT_THRESHOLD.
+      # @param resolver [#call, nil] builds a backend from its name —
+      #   injectable so specs never reach a real model. nil means
+      #   ModelBackends.resolve, looked up only once a backend is needed.
+      # @raise [ArgumentError] for a threshold outside 0.0..1.0. An explicit
+      #   `threshold:` is always checked, so a mistyped `--min-confidence`
+      #   fails loudly. PORTAGE_MIN_CONFIDENCE is read, and so checked,
+      #   only once a backend is enabled: a stale value in a shell that
+      #   never uses the gate mustn't stop every `portage buy`.
+      def initialize(backend: nil, threshold: nil, resolver: nil)
+        @backend_name = Setting.resolve(override: backend, env: BACKEND_ENV)&.to_s&.strip
+        raw_threshold = enabled? ? Setting.resolve(override: threshold, env: THRESHOLD_ENV) : threshold
+        @threshold = parse_threshold(raw_threshold || DEFAULT_THRESHOLD)
+        @resolver = resolver
+      end
+
+      attr_reader :threshold
+
+      def enabled? = !@backend_name.nil?
+
+      # @param state [Hash] JSON-serializable. Never pass it a payment token.
+      # @return [Hash, nil] nil when disabled. Otherwise `proceed:`,
+      #   `reason:`, `confidence:`, `threshold:`, `backend:` and `error:`.
+      #   `reason` is nil when it proceeds, else why it held:
+      #   `below_threshold`, `backend_error` (unknown, unconfigured or
+      #   failed backend) or `not_installed` (no portage-ucp-decision).
+      #   `error` is the detail behind the last two, nil otherwise.
+      def call(state)
+        return nil unless enabled?
+        return held("not_installed", not_installed_message) unless Decisions.available?
+
+        verdict = Portage::Ucp::Decision::ConfidenceGate.via_backend(
+          backend: resolve_backend, state: JSON.generate(state), question: QUESTION,
+          instructions: INSTRUCTIONS, threshold: @threshold
+        )
+        { proceed: verdict.proceed, reason: verdict.proceed ? nil : "below_threshold",
+          confidence: verdict.confidence, threshold: @threshold, backend: @backend_name, error: nil }
+      rescue StandardError => e
+        # Any failure, not only Decision::Error: this runs after a real
+        # checkout exists, so an escaped exception would drop the report,
+        # the hand-off and the history entry along with the purchase.
+        held("backend_error", e.message)
+      end
+
+      # What `portage doctor` reports: why the named backend would hold every
+      # `--yes` purchase, before one is attempted.
+      # @return [String, nil] nil when disabled or ready to answer.
+      def configuration_problem
+        return nil unless enabled?
+        return not_installed_message unless Decisions.available?
+
+        resolve_backend.configuration_problem
+      rescue Portage::Ucp::Decision::Error => e
+        e.message
+      end
+
+      private
+
+      def resolve_backend
+        (@resolver || Portage::Ucp::Decision::ModelBackends.method(:resolve)).call(@backend_name)
+      end
+
+      def held(reason, error)
+        { proceed: false, reason: reason, confidence: nil, threshold: @threshold, backend: @backend_name,
+          error: error }
+      end
+
+      def not_installed_message
+        "portage-ucp-decision is not installed — `gem install portage-ucp-decision` to use the " \
+          "#{@backend_name} confidence check."
+      end
+
+      def parse_threshold(raw)
+        value = Float(raw, exception: false)
+        return value if value&.between?(0.0, 1.0)
+
+        raise ArgumentError, "confidence threshold must be a number between 0.0 and 1.0, got #{raw.inspect}"
+      end
+    end
+  end
+end

data/lib/portage/cli/config.rb

@@ -0,0 +1,52 @@
+require "json"
+require "fileutils"
+
+module Portage
+  module Cli
+    # Durable, editable `portage-cli` config — `~/.portage/config.json` — for
+    # standing preferences that aren't payment/policy specific (the auto-open
+    # and notify-webhook toggles in docs/plans/checkout-handoff-delivery.md
+    # are the first two keys). Same shape as Portage::Ucp::Policy: absent
+    # file or absent key means "unset", a corrupt file raises rather than
+    # silently falling back.
+    class Config
+      PATH = File.join(Dir.home, ".portage", "config.json").freeze
+
+      def self.load(path: PATH) = new(path: path, data: read(path))
+
+      def initialize(path: PATH, data: {})
+        @path = path
+        @data = data
+      end
+
+      def get(key) = @data[key.to_s]
+
+      def set(key, value)
+        @data[key.to_s] = value
+        write
+        value
+      end
+
+      def to_h = @data.dup
+
+      def self.read(path)
+        return {} unless File.readable?(path)
+
+        raw = File.read(path)
+        return {} if raw.empty?
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : {}
+      end
+      private_class_method :read
+
+      private
+
+      def write
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, JSON.pretty_generate(@data))
+        File.chmod(0o600, @path)
+      end
+    end
+  end
+end

data/lib/portage/cli/decisions.rb

@@ -0,0 +1,72 @@
+require "portage/ucp"
+
+module Portage
+  module Cli
+    # portage-cli's judgment calls (docs/plans/system-one-decision-layer.md).
+    # The rules live in portage-ucp core: Support::OfferRanking,
+    # Support::Escalation and PolicyGuard. portage-ucp-decision's
+    # OfferRanking, EscalationPolicy and PolicyCheck are typed wrappers
+    # around those same modules, so `buy` and `find` answer the same way
+    # whether or not that gem is installed.
+    #
+    # Every method returns a plain Hash whose `reason` is a String or nil,
+    # so a caller sees the same values in-process as in `--json`.
+    #
+    # Only the confidence gate needs the optional gem, because the model
+    # backends live there (see ConfidenceCheck and .available?).
+    module Decisions
+      # Loaded the way Resolver.build_adapter's callers treat an optional
+      # adapter gem: `require`, then rescue LoadError. It isn't in the
+      # gemspec, so `gem install portage-cli` stays light.
+      # @return [Boolean] whether portage-ucp-decision could be loaded.
+      #   Memoized: `require` runs once per process.
+      def self.available?
+        return @available unless @available.nil?
+
+        @available = begin
+          require "portage/ucp/decision"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      # @param offers [Array<Hash>] with `:checkout` (buyable) and `:amount`.
+      def self.rank(offers)
+        Portage::Ucp::Support::OfferRanking.rank(offers) { |offer| [offer[:checkout], offer[:amount]] }
+      end
+
+      # @param warnings [Array<String>] mismatches that should escalate —
+      #   pass none when mismatches are only to be reported.
+      # @return [Hash] `escalate:`, `reason:`.
+      def self.escalation(checkout_status:, warnings: [])
+        reason = Portage::Ucp::Support::Escalation.reason(checkout_status: checkout_status, warnings: warnings)
+        { escalate: !reason.nil?, reason: reason&.to_s }
+      end
+
+      # The buyer's spend policy, checked by PolicyGuard.
+      #
+      # PolicyGuard skips both spend caps when `amount` is nil, which suits
+      # its own caller (an adapter that can't price a checkout up front).
+      # Here it would let a checkout with no `total` line past a configured
+      # cap while reporting `allowed: true`, so a missing total is denied as
+      # `total_unknown` whenever a cap exists.
+      # @param transaction_log [Portage::Ucp::Support::TransactionLog] what
+      #   the rolling cap and velocity limit count.
+      # @return [Hash] `allowed:`, `reason:`.
+      def self.policy(amount:, currency:, merchant:, token_ref:,
+                      transaction_log: Portage::Ucp::Support::TransactionLog.new)
+        policy = Portage::Ucp::Policy.load
+        if amount.nil? && (policy.per_transaction_cap || policy.rolling_cap)
+          return { allowed: false, reason: "total_unknown" }
+        end
+
+        Portage::Ucp::PolicyGuard.check!(amount: amount, currency: currency, merchant: merchant,
+                                         token_ref: token_ref, policy: policy, transaction_log: transaction_log)
+        { allowed: true, reason: nil }
+      rescue Portage::Ucp::PolicyViolationError => e
+        { allowed: false, reason: e.reason.to_s }
+      end
+    end
+  end
+end

data/lib/portage/cli/doctor.rb

@@ -1,4 +1,5 @@
 require "portage/ucp"
+require_relative "confidence_check"
 
 module Portage
   module Cli
@@ -24,6 +25,7 @@ module Portage
           rate_limiter_finding,
           signing_keys_finding,
           payment_handlers_finding,
+          decision_backend_finding,
           *capability_findings
         ].compact
       end
@@ -54,6 +56,21 @@ module Portage
         Finding.new(check: "signing_keys", message: "No signing_keys configured — the manifest ships unsigned.")
       end
 
+      # The confidence gate's backend, checked only once one is selected
+      # (PORTAGE_DECISION_BACKEND): the gate is off by default, and a
+      # missing key for a backend nobody chose is noise. Once one is
+      # selected, anything short of ready holds every `--yes` purchase, so
+      # it's flagged here rather than first surfacing mid-checkout. Covers
+      # the gem not being installed, an unknown backend name, a missing
+      # JEV_API_KEY, a missing Laya bridge, and a bad PORTAGE_MIN_CONFIDENCE.
+      def decision_backend_finding
+        problem = ConfidenceCheck.new.configuration_problem
+        problem && Finding.new(check: "decision_backend",
+                               message: "#{problem} — until then every `portage buy --yes` is held for the shopper.")
+      rescue ArgumentError => e
+        Finding.new(check: "decision_backend", message: e.message)
+      end
+
       def payment_handlers_finding
         return unless Array(config.payment_handlers).empty?
 

data/lib/portage/cli/find.rb

@@ -4,6 +4,7 @@ require "portage/ucp/client"
 
 require_relative "search_backends"
 require_relative "probe_cache"
+require_relative "decisions"
 
 module Portage
   module Cli
@@ -140,7 +141,8 @@ module Portage
 
       def offers_for(store)
         products = CatalogProducts.from(
-          store[:session].search_catalog(query: @query, limit: PER_STORE_RESULTS, meta: agent_meta)
+          store[:session].search_catalog(query: @query, limit: PER_STORE_RESULTS,
+                                         context: BuyerContext.from_env, meta: agent_meta)
         )
         products.filter_map { |product| offer(store, product) }
       rescue Portage::Ucp::Client::MissingAgentProfileError
@@ -165,14 +167,13 @@ module Portage
           amount: amount, currency: currency, url: field(product, "url") }
       end
 
-      # Buyable first, then cheapest, then unpriced. Sorting on price alone
-      # would float a browse-only store above one you can actually check out
-      # from, which is the wrong answer to "buy me this".
-      def rank(offers)
-        offers.sort_by do |offer|
-          [offer[:checkout] ? 0 : 1, offer[:amount] ? 0 : 1, offer[:amount] || 0]
-        end
-      end
+      # Buyable first, then cheapest, then unpriced (see Decisions.rank —
+      # core's Support::OfferRanking, the rule portage-ucp-decision's
+      # OfferRanking wraps), so an agent loop ranking its own candidate list
+      # gets the same order this command prints. Sorting on price alone
+      # would float a browse-only store above one you can actually check
+      # out from, which is the wrong answer to "buy me this".
+      def rank(offers) = Decisions.rank(offers)
 
       # --- Shapes ---
 

data/lib/portage/cli/generate/agent_profile.rb

@@ -27,9 +27,15 @@ module Portage
       # Same-looking key material, structurally different document — not
       # interchangeable, so this doesn't subclass or reuse Manifest.
       #
-      # `Portage::Ucp::Manifest::UCP_VERSION` is reused as-is (not
-      # redeclared) so the two documents can never drift to different spec
-      # versions by accident.
+      # The version here is deliberately *not* reused from
+      # `Portage::Ucp::Manifest::UCP_VERSION`, unlike an earlier revision of
+      # this class. Those two versions answer different questions: the
+      # manifest's says which spec revision *this gem's own server* implements
+      # for the businesses it serves, while an agent profile's says which
+      # revision the agent speaks to *whichever remote store it dials*. A
+      # store on a newer rollout than our server-side support (Shopify's
+      # `2026-08-25` endpoints, today) negotiates against the profile, so
+      # pinning the profile to the server's revision under-declared us.
       #
       # Rotation is the future-proofing this exists for: re-running with
       # `rotate: true` keeps every key already published (so a request
@@ -38,10 +44,49 @@ module Portage
       # drops a key — retiring one is a deliberate, separate edit once
       # nothing signs with it any more.
       class AgentProfile
-        UCP_VERSION = Portage::Ucp::Manifest::UCP_VERSION
+        UCP_VERSION = "2026-08-25".freeze
+
+        SHOPPING_SERVICE = "dev.ucp.shopping".freeze
 
         Key = Struct.new(:kid, :jwk, :private_pem, keyword_init: true)
 
+        # The capability identifiers a real UCP server resolves an incoming
+        # agent's tool registry from. These are NOT
+        # `Portage::Ucp::Capabilities::{CATALOG,CART,...}.name`, which an
+        # earlier revision of this class reused, and that reuse is what broke
+        # every live tool call for a month (see
+        # docs/ucp-tool-gating-investigation.md):
+        #
+        # - Catalog is registered per *action*
+        #   (`dev.ucp.shopping.catalog.search`, `.catalog.lookup`), not as one
+        #   coarse `dev.ucp.shopping.catalog`. A profile declaring only the
+        #   coarse name resolves to zero catalog tools, and the server then
+        #   answers `search_catalog` with `-32602 Tool not found:
+        #   search_catalog` — despite `tools/list` having advertised it
+        #   seconds earlier, and with no hint that the profile is the reason.
+        #   `Portage::Ucp::Capabilities::CATALOG` keeps the coarse name
+        #   because that's the right shape for *our own* server's manifest,
+        #   where one Capability object owns all three actions; the two
+        #   registries simply don't line up, so this document spells its own
+        #   ids out rather than deriving them.
+        # - Cart/Checkout/Order are registered at the root name, so those do
+        #   match — spelled out here anyway, so the whole declared set reads
+        #   from one place.
+        # - Versions are spec revisions (`2026-08-25`), not the `"1"` that
+        #   `Capability#version` carries.
+        #
+        # Live-verified 2026-09-22 against `catalog.shopify.com/api/ucp/mcp`
+        # and two per-shop endpoints: the granular ids answer `search_catalog`
+        # with real products at the anonymous tier (no token, no allowlist),
+        # the coarse id answers `Tool not found` on the same connection.
+        CAPABILITY_IDS = %w[
+          dev.ucp.shopping.catalog.search
+          dev.ucp.shopping.catalog.lookup
+          dev.ucp.shopping.cart
+          dev.ucp.shopping.checkout
+          dev.ucp.shopping.order
+        ].freeze
+
         # @param out [String] path to write the public profile JSON document
         # @param key_out [String] path to write the new private key's PEM —
         #   caller's responsibility to keep this out of version control
@@ -83,14 +128,29 @@ module Portage
           {
             "ucp" => {
               "version" => UCP_VERSION,
-              "services" => {},
-              "capabilities" => {},
+              "services" => service_hash,
+              "capabilities" => capability_hash,
               "payment_handlers" => {}
             },
             "signing_keys" => signing_keys
           }
         end
 
+        # Was `{}`. A server negotiating capabilities intersects its own
+        # service list with the profile's, so an empty `services` declares an
+        # agent that speaks no service at all — same class of under-declaration
+        # as the coarse capability ids above.
+        def service_hash
+          { SHOPPING_SERVICE => [{ "version" => UCP_VERSION,
+                                   "spec" => "https://ucp.dev/#{UCP_VERSION}/specification/overview",
+                                   "transport" => "mcp",
+                                   "schema" => "https://ucp.dev/#{UCP_VERSION}/services/shopping/mcp.openrpc.json" }] }
+        end
+
+        def capability_hash
+          CAPABILITY_IDS.to_h { |id| [id, [{ "version" => UCP_VERSION }]] }
+        end
+
         def write_profile(doc)
           FileUtils.mkdir_p(File.dirname(@out))
           File.write(@out, "#{JSON.pretty_generate(doc)}\n")

data/lib/portage/cli/history.rb

@@ -9,6 +9,13 @@ module Portage
     # history list` can answer "what did I already look for" and "what did I
     # already buy" without re-running anything, and `portage history clear`
     # can wipe either or both.
+    #
+    # A purchase entry is one checkout `portage buy` created, whatever came
+    # of it: `outcome` is the report's own (`purchased`, `dry_run`,
+    # `policy_blocked`, ...), so "what did I already buy" is the entries
+    # whose outcome is `purchased`, and every other entry still carries the
+    # `checkout_url` to finish it by hand. Entries written before `outcome`
+    # existed have only `checkout_status` and `message`.
     class History
       PATH = File.join(Dir.home, ".portage", "history.json").freeze
       MAX_ENTRIES = 200
@@ -18,14 +25,24 @@ module Portage
         @now = now.to_i
       end
 
-      def record_purchase(url:, query:, checkout:, message:, checkout_status: nil, products: [])
-        append("purchases", { "url" => url, "query" => query, "checkout" => checkout,
-                              "checkout_status" => checkout_status, "message" => message,
-                              "products" => products, "at" => @now })
+      # @param items [Array<Hash>] what the checkout holds (`id`, `title`,
+      #   `quantity`), not the search results it was picked from.
+      # @param total [Integer, nil] minor units of `currency`.
+      # rubocop:disable Metrics/ParameterLists -- all keywords; one entry's fields
+      def record_purchase(url:, query:, outcome:, message:, source: nil, checkout_id: nil, checkout_status: nil,
+                          checkout_url: nil, total: nil, currency: nil, items: [])
+        # rubocop:enable Metrics/ParameterLists
+        append("purchases", { "url" => url, "query" => query, "outcome" => outcome, "source" => source,
+                              "checkout_id" => checkout_id, "checkout_status" => checkout_status,
+                              "checkout_url" => checkout_url, "total" => total, "currency" => currency,
+                              "items" => items, "message" => message, "at" => @now })
       end
 
-      def record_search(query:, offer_count:, message:)
-        append("searches", { "query" => query, "offer_count" => offer_count, "message" => message, "at" => @now })
+      # @param url [String, nil] the store, for a `portage buy` that never
+      #   reached a checkout there; nil for a cross-store `portage find`.
+      def record_search(query:, offer_count:, message:, url: nil)
+        append("searches", { "query" => query, "url" => url, "offer_count" => offer_count, "message" => message,
+                             "at" => @now }.compact)
       end
 
       def purchases(limit: MAX_ENTRIES) = store["purchases"].last(limit)

data/lib/portage/cli/notifier.rb

@@ -0,0 +1,73 @@
+require "net/http"
+require "json"
+require "uri"
+require_relative "config"
+require_relative "setting"
+
+module Portage
+  module Cli
+    # Phase 2 of docs/plans/checkout-handoff-delivery.md — POSTs a JSON body
+    # to a configured webhook when a `Buy` dead-end (escalation, permission
+    # denied, no payment token) hands off a checkout_url, so a caller can
+    # wire that into Slack/Zapier/their own relay. Same "the actual
+    # notification transport is the caller's job" posture as
+    # Portage::Ucp::Confirmer::Webhook's own comments — this class only ever
+    # speaks HTTP.
+    #
+    # Default off. Precedence for the webhook URL (open decision #1,
+    # resolved, same Setting as CheckoutHandoff's auto-open toggle): a
+    # per-invocation `webhook_url:` override (portage buy --notify-webhook)
+    # beats PORTAGE_NOTIFY_WEBHOOK_URL, which beats ~/.portage/config.json's
+    # "notify_webhook_url" (Config).
+    class Notifier
+      ENV_VAR = "PORTAGE_NOTIFY_WEBHOOK_URL".freeze
+      CONFIG_KEY = "notify_webhook_url".freeze
+      TIMEOUT = 5
+      # Enough of an error body to name the problem, without pasting a whole
+      # HTML error page into the report.
+      BODY_EXCERPT = 200
+
+      def initialize(webhook_url: nil, config: Config.load)
+        @override = webhook_url
+        @config = config
+      end
+
+      def webhook_url
+        Setting.resolve(override: @override, env: ENV_VAR, config: @config, config_key: CONFIG_KEY)
+      end
+
+      def enabled? = !webhook_url.to_s.empty?
+
+      # Best-effort, matching CheckoutHandoff's posture: a failed POST never
+      # raises out of `Buy#call` — the checkout itself is a real, correct
+      # outcome independent of whether this delivery succeeded.
+      #
+      # Success is any 2xx, whatever the body: Slack's incoming webhooks
+      # answer `ok` as plain text, which a JSON parse would have misreported
+      # as a failed delivery. Short timeouts, since a hand-off is waiting on
+      # this and Net::HTTP's defaults would stall it for up to two minutes.
+      #
+      # @return [String, nil] the delivery failure message, or nil when
+      #   disabled or on a successful POST.
+      def call(payload)
+        return nil unless enabled?
+
+        response = post(URI(webhook_url), JSON.generate(payload))
+        return nil if response.is_a?(Net::HTTPSuccess)
+
+        "webhook answered #{response.code}: #{response.body.to_s[0, BODY_EXCERPT]}"
+      rescue StandardError => e
+        "webhook POST failed: #{e.message}"
+      end
+
+      private
+
+      def post(uri, body)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+          http.post(uri.request_uri, body, "Content-Type" => "application/json")
+        end
+      end
+    end
+  end
+end