portage-cli 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 805f3c78c6560bcdb4110d1bb97dcaa0700a7586578cc639fb94595cfd5c09bc
-  data.tar.gz: f2f4ca834b30fb319563ea10741385150559437bdfd87bc4657051d1f2dc0182
+  metadata.gz: c506344f3b17a2ea4199f84efaf70d658b0debec2fe03d167b847c58617e800b
+  data.tar.gz: 20c00c246e59fa9059611f7bb54380140295eada2c5deb457a11ec94309c1b04
 SHA512:
-  metadata.gz: 3b10afae4ce3260952193fd8c32b7eb8b5a97b8a4292ca78e40848a41fd94f84e3f18490115186296253edd1d8fdf65a1cd728c1eca5e96efc8a21c18563ebcb
-  data.tar.gz: 03b8c8ba8a3ee6e19116d00f6775c6825e3c70d23f7a4b1864acb44435988edf9ba400a52cdf5548ee9660e0588cd938f0c0eba6ed24afcea0010d2669abddb3
+  metadata.gz: 9a3eff64f57ab81774a2a52034232a4667227aaff13aa7279d26dd41cf52faeafeea691711755fb41fd2f3a0a67f77d144d248d48c2631779a49c10bec9f2882
+  data.tar.gz: ade0a2ba64ba928ec1272a8902858bad1f79897f5059d428528b8978e4045047ee1a0e6e2579dc2f8a468fa73b0c3491cc66c48f2bc1a18951600e05bd2a25e1

data/CHANGELOG.md

@@ -6,6 +6,75 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-29
+
+- **`portage check <url> [--json]`.** Reports whether Portage can buy from a store and
+  how: `verdict` (`automated`, `webmcp`, `handoff`, `unsupported`), `next_step`, and the
+  detail behind them (native UCP, platform, adapter install and missing env, hand-off-only,
+  WebMCP status). Wraps `Portage::Ucp::Check` and follows the precedence `buy` uses.
+  Plain GETs only, hand-off-only hosts are not contacted, and WebMCP is read only from an
+  already-open Portage profile tab. Exits `0` for `automated` and `webmcp`. The hand-off-only
+  test moved into a shared `HandoffHost` so `buy` and `check` can't disagree.
+  Follows a homepage `<link rel="ucp">` manifest pointer through `portage-ucp` 0.11.0,
+  which this release now requires (`~> 0.11`).
+
+## [0.9.0] - 2026-09-29
+
+- **Human pick and approve** (`docs/plans/human-pick-and-approve.md`, Phases 1-3).
+  Loop steps 3 and 5 now have a ready-made interface for a person at a terminal
+  and for an agent relaying their answer.
+  - **Offer refs.** Each `find` offer carries an `offer_ref` (`of_` and 6 hex
+    digits), and the report a `search_id` (`se_` and 8 hex digits). Both are saved
+    with the search in history, so `history --json` searches now hold `search_id`
+    and `offers[]`. `compare` saves its offers with refs and a `search_id` too.
+    `portage buy --offer REF` takes the store, product and query from the saved
+    offer; an unknown ref is `offer_not_found`.
+  - **Quotes.** A `buy --dry-run` that priced a checkout saves a quote in
+    `~/.portage/quotes/` and reports `quote_id`. `buy --quote QUOTE_ID --yes`
+    buys exactly that quote, capped at the quoted total: if the real checkout costs
+    more (or is in another currency) it refuses with `quote_changed`, carrying
+    `quoted_total` and `current_total`, without charging or handing off. Quotes don't
+    expire and are used once (`purchased` or any hand-off). `quote_not_found` and
+    `quote_used` cover the rest.
+  - **`portage pick`.** Loop step 3. `needs_pick` returns `choices[]` (`ref`, `label`,
+    `url`, plus the offer's fields) and a last "Compare an offer across stores"
+    choice; `--choose REF` relays an answer (`picked`, `by: "agent_relayed"`),
+    `--compare REF` runs compare and shows the pick again over its results,
+    `--search LAST|SEARCH_ID` picks the search. At a terminal it asks on `/dev/tty`
+    (`by: "person"`).
+  - **`portage approve QUOTE_ID`.** Loop step 5. `needs_approval` returns a
+    `summary` (title, store, qty, total, `total_display`, `url`); `--relayed-yes`
+    records `approved_by: "agent_relayed"`; a yes typed at a terminal records
+    `"person"`. The quote also keeps `approved`, `approved_by` and `approved_at`.
+  - **`--via auto|tty|agent`.** `tty` asks on `/dev/tty` (so it works with stdout
+    piped) and returns `no_terminal` when there's none; `agent` asks nobody;
+    `auto` is `tty` with a terminal and no `--json`, else `agent`.
+  - **`--view REF` / `approve --view` and `v N` / `v` at a prompt** open the product
+    page and never count as an answer. Only an `http(s)` URL on the offer's own
+    store host is opened; anything else is `view_refused`. `pick`'s compare
+    choice uses the proxy settings from env and config (there are no `--proxy`
+    flags on `pick`).
+  - **`policy set --require-approval person|any|off`** (default `any`, stored as
+    `require_approval` in `~/.portage/policy.json`, always shown by `policy show`).
+    Lowering it needs a yes typed at a terminal. It raises the bar against an agent
+    but isn't a hard guarantee: a process with a shell can edit the policy or quote
+    files. Docs: `docs/api/cli-json.md`, `docs/agentic-flow.md`,
+    `docs/cli-usage-tutorial.md`.
+  - **Upgrade note.** Under the default `any`, a `buy --yes` without an approved
+    `--quote` no longer buys: it dry-runs and returns `needs_approval` (exit `0`).
+    Restore the old behaviour with `portage policy set --require-approval off`
+    from a terminal. `buy --query`'s numbered pick now asks on `/dev/tty` too.
+
+- Documentation only, no code change. The README said a
+  `webmcp_mapping_unconfirmed` report returns the proposed mapping "for the
+  caller to pass back". No flag takes a mapping back, and `Buy` has no
+  `tool_names:` keyword. The README now says what each caller can do. From
+  the CLI, re-run the command in a real terminal without `--json`
+  (`--dry-run` is enough) and answer the prompt; the approved mapping is
+  saved to `~/.portage/webmcp_mappings.json`. From Ruby, inject
+  `webmcp_mapping_confirm:` or `webmcp_mappings:`, or pass `tool_names:` to
+  `WebMcp.connect` yourself.
+
 ## [0.8.0] - 2026-09-29
 
 - **Requires `portage-ucp-webmcp` 0.2.0 or newer for WebMCP paths.**

data/README.md

@@ -127,10 +127,16 @@ portage buy <url> --query "..." [--qty N] [--payment-token TOKEN] [--product-id
                                 [--handoff-target default|print|profile|agent:NAME]
                                 [--decision-backend jev|laya] [--min-confidence N] [--json]
                                 [--wait [--wait-timeout DURATION|off]]
+portage buy --offer REF [--qty N] [--yes] [--dry-run] ...
+portage buy --quote QUOTE_ID --yes [--json] ...
 portage buy --query "..." [--store URL] [--max-price N] [--limit N] ...
 portage find --query "..." [--max-price N] [--limit N] [--json]
 portage compare <url> --product-id ID [--id VALUE ...] [--results N]
                        [--max-price N] [--json]
+portage check <url> [--json]
+portage pick [--search LAST|SEARCH_ID] [--via auto|tty|agent] [--json]
+             [--choose REF | --compare REF | --view REF]
+portage approve QUOTE_ID [--via auto|tty|agent] [--relayed-yes | --view] [--json]
 portage history [list] [--purchases|--searches] [--limit N] [--json]
 portage history clear [--purchases|--searches]
 portage payment list [--json]
@@ -145,6 +151,7 @@ portage policy set [--per-transaction-cap N --currency CUR]
                     [--rolling-cap N --rolling-window-seconds N --currency CUR]
                     [--velocity-count N --velocity-window-seconds N]
                     [--allow HOST ...] [--clear-allowlist]
+                    [--require-approval person|any|off]  (lowering asks at a terminal)
 portage orders reconcile [--checkout ID] [--json]
 portage index build [--sources a,b] [--queries FILE] [--dry-run] [--export DIR] [--json]
 portage index refresh [--sources a,b] [--queries FILE] [--dry-run] [--export DIR] [--json]
@@ -212,6 +219,18 @@ used (an unreadable value, an out-of-range threshold) stops the buy before
 anything runs: on stderr normally, or as a JSON report with `outcome:
 "invalid_option"` under `--json`.
 
+### Check
+
+`portage check <url> [--json]` answers "can Portage buy from this store, and how?".
+It checks for a native `/.well-known/ucp` manifest, detects the platform, notes
+whether its adapter gem is installed and which env vars are missing, and looks for
+WebMCP tools, using the same hand-off-only rules as `buy`. `verdict` is
+`automated`, `webmcp`, `handoff` or `unsupported`, with a plain-English
+`next_step`. Exits `0` for `automated` and `webmcp`. It sends plain GETs only, and
+never contacts a hand-off-only host. WebMCP is read only from a tab your Portage
+browser profile already has open on the store; it never launches a browser.
+Takes the `--proxy*` flags.
+
 ### Compare
 
 `portage compare <url> --product-id ID` finds other stores selling the same
@@ -361,6 +380,21 @@ opt-in guardrail, not a default-deny one. Per-token scopes (merchant/amount
 limits bound to one enrolled card) are set via `portage payment enroll
 --scope-*` above, not here.
 
+`portage policy set --require-approval person|any|off` (default `any`) sets what a
+real `buy --yes` needs: `off` is `--yes` alone; `any` needs `--quote QUOTE_ID` for a
+quote approved with `portage approve` (by the person, or relayed by an agent with
+`--relayed-yes`); `person` needs the person's own yes at a terminal. Otherwise the run
+is a dry run that returns `needs_approval`. Lowering the level asks for a yes at a
+terminal. Stored as `require_approval` in `~/.portage/policy.json`. It raises the bar
+against an agent but isn't a hard guarantee: a process with a shell can edit that file
+or the quote files in `~/.portage/quotes/`. The whole flow (`find`, `pick`, `buy
+--offer --dry-run`, `approve`, `buy --quote --yes`) is in the
+[CLI JSON reference](../docs/api/cli-json.md) and the
+[tutorial](../docs/cli-usage-tutorial.md#picking-and-approving-at-the-terminal). Upgrade
+note: under the default `any`, `buy --yes` with no approved `--quote` no longer buys;
+restore the old behaviour with `portage policy set --require-approval off` from a
+terminal.
+
 ### Tiers: how a purchase actually finishes
 
 Most stores don't let a third-party agent complete payment. `portage buy`
@@ -737,9 +771,24 @@ hand-off. `token` isn't implemented yet; it reports
 Against a page whose tools aren't a known platform preset, `Buy` falls back
 to a schema-matched, shopper-confirmed mapping instead of giving up (see
 `portage-ucp-webmcp`'s README, "Stores that don't run Portage"). A mutating
-match prompts on a real TTY with `--json` off; under `--json` or with no
-TTY it stops instead (outcome `webmcp_mapping_unconfirmed`) and returns the
-proposed mapping for the caller to pass back.
+match prompts on a real TTY with `--json` off. Under `--json`, or with no
+TTY, it stops instead: outcome `webmcp_mapping_unconfirmed`, with the
+proposal in `tool_names_proposal`.
+
+No flag passes a mapping back. From the CLI, re-run the same command in
+your own terminal without `--json` and answer the prompt. `--dry-run` is
+enough, because the mapping is confirmed before the dry-run check. The
+approved mapping is saved to `~/.portage/webmcp_mappings.json`, and later
+runs reuse it with no prompt.
+
+`Buy` has no `tool_names:` keyword either. A library caller has two hooks.
+`webmcp_mapping_confirm:` takes any object whose `call(proposal, tools)`
+returns a `tool_names:` hash, or nil to stop with
+`webmcp_mapping_unconfirmed`. `Buy` saves whatever hash it returns to
+`webmcp_mappings:`, the store approved mappings are read from (default: a
+`Portage::Cli::WebmcpMappings` on `~/.portage/webmcp_mappings.json`).
+Outside `Buy`, pass `tool_names:` to `Portage::Ucp::WebMcp.connect`
+yourself.
 
 `dry_run: true` against a page whose preset hands off through its own
 checkout tool (Shopify's `proceed_to_checkout`) stops after the read-only

data/lib/portage/cli/approval_policy.rb

@@ -0,0 +1,56 @@
+require "portage/ucp"
+require_relative "human_prompt"
+
+module Portage
+  module Cli
+    # `portage policy set --require-approval person|any|off`
+    # (docs/plans/human-pick-and-approve.md Phase 2, Design § 5): how much
+    # approval a real `portage buy --yes` needs before it may charge or hand
+    # off.
+    #
+    # - `off`: `--yes` alone buys (the behaviour before this setting).
+    # - `any` (the default): `--yes` needs `--quote` with an approved quote,
+    #   approved by the person at a tty or relayed by an agent.
+    # - `person`: only a quote the person approved at the tty counts — a
+    #   model with a shell can't type on `/dev/tty`.
+    #
+    # Stored as `require_approval` in ~/.portage/policy.json (Portage::Ucp::
+    # Policy), next to the caps and allowlist it sits beside in `portage
+    # policy`. Policy#set takes any key and its file format is documented as
+    # private, and PolicyGuard reads only the keys it knows, so this needs
+    # no change to the portage-ucp gem. Deliberately no env var or
+    # config.json override: either would let an agent lower it without the
+    # tty confirmation `policy set` asks for. The gate itself is CLI-only
+    # (Cli.approval_gate); Buy's library callers aren't governed by it.
+    module ApprovalPolicy
+      KEY = "require_approval".freeze
+      LEVELS = %w[off any person].freeze
+      DEFAULT = "any".freeze
+
+      module_function
+
+      # An unrecognised stored value (a hand-edited file) fails closed, to
+      # the strictest level.
+      # @return [String] one of LEVELS.
+      def level(policy = Portage::Ucp::Policy.load)
+        stored = policy.to_h[KEY]
+        return DEFAULT if stored.nil?
+
+        LEVELS.include?(stored) ? stored : "person"
+      end
+
+      def configured?(policy) = policy.to_h.key?(KEY)
+
+      def lowering?(from, to) = LEVELS.index(to) < LEVELS.index(from)
+
+      # @param quote [Hash, nil] a saved quote (Quotes).
+      def satisfied?(quote, level)
+        case level
+        when "off" then true
+        when "any" then [HumanPrompt::BY_PERSON, HumanPrompt::BY_AGENT].include?(quote&.dig("approved_by"))
+        else quote&.dig("approved_by") == HumanPrompt::BY_PERSON
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/approve.rb

@@ -0,0 +1,135 @@
+require_relative "history"
+require_relative "quotes"
+require_relative "human_prompt"
+require_relative "product_page"
+require_relative "money"
+require_relative "approval_policy"
+
+module Portage
+  module Cli
+    # `portage approve QUOTE_ID` — loop step 5, the person says yes to the
+    # exact dry-run total (docs/plans/human-pick-and-approve.md Phase 2,
+    # Design § 5). Shows title, store, qty and total and asks yes/no.
+    #
+    # A yes typed on the `tty` surface marks the quote `approved_by:
+    # "person"`; `--relayed-yes` marks it `"agent_relayed"`. The `agent`
+    # surface asks nobody and returns `needs_approval` with the summary.
+    # `--view` only opens the product page. Whether an approval is enough
+    # for `buy --quote QUOTE_ID --yes` is ApprovalPolicy's call, at buy time
+    # — except under `person`, where a relayed yes could never be enough, so
+    # it isn't recorded and the agent is told to hand the question to the
+    # person's own terminal instead.
+    #
+    # Returns a report hash; Cli.run_approve prints it.
+    class Approve
+      def initialize(quote_id:, prompt:, relayed_yes: false, view: false, quotes: Quotes.new, history: History.new,
+                     level: ApprovalPolicy.level)
+        @quote_id = quote_id
+        @prompt = prompt
+        @relayed_yes = relayed_yes
+        @view = view
+        @quotes = quotes
+        @history = history
+        @level = level
+      end
+
+      def call
+        quote = @quotes.find(@quote_id)
+        return unusable(quote) if quote.nil? || quote["used_at"]
+
+        summary = self.class.summary(quote, history: @history)
+        return view(summary) if @view
+        return relay(summary) if @relayed_yes
+        return self.class.needs_approval(summary, level: @level) unless @prompt.tty?
+
+        ask(summary)
+      rescue HumanPrompt::NoTerminal => e
+        { outcome: "no_terminal", quote_id: @quote_id, message: e.message }
+      end
+
+      # What the person is asked to approve. Title and url were saved on
+      # the quote at dry-run time; a quote saved without them falls back to
+      # its offer's (via `offer_ref`, History#offer).
+      def self.summary(quote, history: History.new)
+        offer = fallback_offer(quote, history)
+        { quote_id: quote["quote_id"], title: quote["title"] || offer&.dig("title"), store: quote["store"],
+          product_id: quote["product_id"], qty: quote["qty"], total: quote["total"], currency: quote["currency"],
+          total_display: quote["total"] ? Money.format_amount(quote["total"], quote["currency"]) : "unknown",
+          url: quote["url"] || offer&.dig("url"), approved_by: quote["approved_by"] }
+      end
+
+      def self.fallback_offer(quote, history)
+        return nil unless quote["offer_ref"] && (quote["title"].nil? || quote["url"].nil?)
+
+        history.offer(quote["offer_ref"])
+      end
+      private_class_method :fallback_offer
+
+      # Also what a refused `buy --yes` returns (Cli.approval_gate).
+      def self.needs_approval(summary, message: nil, level: ApprovalPolicy::DEFAULT)
+        { outcome: "needs_approval", quote_id: summary[:quote_id], summary: summary,
+          message: message || relay_message(summary, level) }
+      end
+
+      def self.relay_message(summary, level)
+        id = summary[:quote_id]
+        ask = if level == "person"
+                "Ask the person to run `portage approve #{id}` in their own terminal (require_approval: person " \
+                  "doesn't accept a relayed yes)"
+              else
+                "Ask the person to approve #{describe(summary)} (show the url as a link), then relay a yes: " \
+                  "`portage approve #{id} --relayed-yes`"
+              end
+        "#{ask}, then `portage buy --quote #{id} --yes`."
+      end
+      private_class_method :relay_message
+
+      def self.describe(summary)
+        "#{summary[:qty]} × #{summary[:title] || summary[:product_id]} from #{summary[:store]} " \
+          "for #{summary[:total_display]}"
+      end
+
+      private
+
+      def ask(summary)
+        @prompt.say("#{summary[:title] || summary[:product_id]} — #{summary[:store]}")
+        @prompt.say("  qty #{summary[:qty]}, total #{summary[:total_display]}#{" — #{summary[:url]}" if summary[:url]}")
+        yes = @prompt.confirm("Buy #{self.class.describe(summary)}?", view: -> { page(summary)[:message] })
+        return approve(summary, HumanPrompt::BY_PERSON) if yes
+
+        { outcome: "cancelled", quote_id: summary[:quote_id], message: "Not approved — nothing will be bought." }
+      end
+
+      def relay(summary)
+        return self.class.needs_approval(summary, level: @level) if @level == "person"
+
+        approve(summary, HumanPrompt::BY_AGENT)
+      end
+
+      def approve(summary, by)
+        quote = @quotes.approve(summary[:quote_id], by: by)
+        return { outcome: "error", quote_id: @quote_id, message: "Couldn't save the approval." } unless quote
+
+        { outcome: "approved", quote_id: summary[:quote_id], approved_by: quote["approved_by"],
+          summary: summary.merge(approved_by: quote["approved_by"]),
+          message: "Approved #{self.class.describe(summary)} — next: " \
+                   "`portage buy --quote #{summary[:quote_id]} --yes`." }
+      end
+
+      def view(summary) = page(summary).merge(quote_id: summary[:quote_id])
+
+      def page(summary) = ProductPage.new(url: summary[:url], store: summary[:store]).open
+
+      # Same outcomes `buy --quote` reports for the same two cases.
+      def unusable(quote)
+        if quote
+          { outcome: "quote_used", quote_id: @quote_id,
+            message: "Quote #{@quote_id} has already been used — dry-run again for a new one." }
+        else
+          { outcome: "quote_not_found", quote_id: @quote_id,
+            message: "No saved quote #{@quote_id} — run `portage buy ... --dry-run --json` for a new one." }
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_opener.rb

@@ -0,0 +1,38 @@
+module Portage
+  module Cli
+    # The one shell-out that opens a URL in the shopper's browser, shared by
+    # CheckoutHandoff (a dead-end checkout's auto-open) and ProductPage
+    # (docs/plans/human-pick-and-approve.md Phase 2's "view the product
+    # page"). Mixed in rather than called as a module function so `system`
+    # stays the including object's own — specs stub it per instance.
+    #
+    # 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 URL can't inject into a shell.
+    # Whether a URL is safe to open at all is the caller's check.
+    module BrowserOpener
+      private
+
+      # @return [Boolean] whether the browser was actually opened.
+      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/buy.rb

@@ -10,8 +10,10 @@ require_relative "setting"
 require_relative "decisions"
 require_relative "confidence_check"
 require_relative "checkout_handoff"
+require_relative "money"
 require_relative "notifier"
 require_relative "handoff_only"
+require_relative "handoff_host"
 require_relative "offer_sources"
 require_relative "handoff_target"
 require_relative "handoff_agents"
@@ -115,12 +117,18 @@ module Portage
       #   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.
+      # @param quote_total [Integer, nil] minor units — set by `buy --quote`:
+      #   the total the person was quoted. Every path that would charge or
+      #   hand off the real checkout first checks its total against this
+      #   (with `quote_currency:`) and reports `quote_changed` instead if it
+      #   is higher, in another currency, or missing. See #finish_checkout.
       # 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, 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)
+                     webmcp_mapping_confirm: nil, autofill: nil, webmcp_autofill_confirm: nil, json: false,
+                     quote_total: nil, quote_currency: nil)
         # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
         raw = url.to_s.strip
         @uri = URI.parse(raw =~ %r{\Ahttps?://}i ? raw : "https://#{raw}")
@@ -141,6 +149,8 @@ module Portage
         @autofill = autofill
         @webmcp_autofill_confirm = webmcp_autofill_confirm
         @json = json
+        @quote_total = quote_total
+        @quote_currency = quote_currency
         @webmcp_bridge = webmcp_bridge
         @decisions = {}
       end
@@ -180,32 +190,10 @@ module Portage
       # "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?
+        HandoffHost.restricted?(@uri.host, handoff_only: @handoff_only)
       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
+      def etsy_buyer_host? = HandoffHost.etsy_buyer_host?(@uri.host)
 
       # No checkout was ever built — there's nothing to browse or complete,
       # just a link and why. `checkout_url` is built, never fetched: the
@@ -970,6 +958,8 @@ module Portage
       end
 
       def finish_checkout(session, source, products, checkout, warnings = [], force_handoff: false)
+        return quote_changed_report(source, products, checkout, warnings) if quote_exceeded?(checkout)
+
         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
@@ -979,6 +969,33 @@ module Portage
         complete(session, source, products, checkout, warnings)
       end
 
+      # First in #finish_checkout, ahead of the escalation gates: a
+      # `quote_changed` refusal never hands off, since that would spend the
+      # quote and open a checkout the person never approved. #complete is
+      # the only place this file charges, and it is reached only through
+      # #finish_checkout.
+      def quote_exceeded?(checkout)
+        return false unless @quote_total
+
+        total = checkout_total(checkout)
+        total.nil? || total > @quote_total || checkout["currency"] != @quote_currency
+      end
+
+      def quote_changed_report(source, products, checkout, warnings)
+        total = checkout_total(checkout)
+        checkout_report(source, products, checkout, outcome: "quote_changed", warnings: warnings,
+                                                    quoted_total: @quote_total, quoted_currency: @quote_currency,
+                                                    current_total: total, current_currency: checkout["currency"],
+                                                    message: quote_changed_message(total, checkout["currency"]))
+      end
+
+      def quote_changed_message(total, currency)
+        "The price changed since the quote (was #{quoted_amount(@quote_total, @quote_currency)}, " \
+          "now #{quoted_amount(total, currency)}) — nothing was bought."
+      end
+
+      def quoted_amount(amount, currency) = amount ? Money.format_amount(amount, currency) : "unknown"
+
       # 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