portage-cli 0.7.0 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c2f71cd7ac7290b314bc824678fc8a9fbc31b6e43cdea4c4e78077440c555c9
-  data.tar.gz: f63510ff1b5d5d945e6e9753b0cf1a521d8da6b084d562c230c4d6b5a98ad6ad
+  metadata.gz: 996ddc0acd1ec2676257f402fbb03148e8a38c40af9d5cf4fbe50d176416a334
+  data.tar.gz: a451d4e8130b1891fb2630d9b5e9edc1efde9486afda2ca3ff863342943d4a09
 SHA512:
-  metadata.gz: 802fb90a17c93986ff7f9101e09e845af467e11607985ddd62cefcd4704f25c5f05292f871c168adeebf386d92620471d6ea6bd8273a74fabb11a3c765324f7d
-  data.tar.gz: '021008e8975eb3002986f0e9f27d5d776b1da067c3fbc6083909abbecde99a616680d3569c609fae0d87ae402e4002577c8cca6bd62ca4811d95c580d8ba8d10'
+  metadata.gz: dd25c1c868d3e70f6ef469975f0d2b24f478c1f96bf83a739d2e4a473c38d2695fbd3586e0243ac21f9d75562b080413ad173c18924024ff1135279cfe8622be
+  data.tar.gz: e8578d6935466578e44e9e4f2e2caae61e1b9a1b2b52051934989fd28ec8ea9a163d943e3f68aac3704bdae72557d600f4694c7c81b8e9fe00b16685640a10b6

data/CHANGELOG.md

@@ -4,6 +4,113 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
+## [0.7.3] - 2026-09-25
+
+- **Proxy support** (`docs/plans/proxy-support.md` Phases 2-3). Every
+  network command (`buy`, `find`, `compare`, `doctor`, `payment enroll`)
+  takes `--proxy`, `--proxy-mode`, `--proxy-header`, `--no-proxy`,
+  `--proxy-route`, `--proxy-chain`, `--proxy-passthrough`, `--proxy-ca` and
+  `--no-env-proxy`, resolved per field against `PORTAGE_PROXY*` env vars
+  and `~/.portage/config.json`'s `proxy` section into core's
+  `Support::ProxyConfig`. `proxy.password_ref` resolves through Keychain or
+  Secret Service (service `portage-cli-proxy`). The payment route stays
+  direct unless a proxy is named for it explicitly, so payment traffic no
+  longer inherits a bare `$http_proxy`/`$https_proxy`. `portage doctor`
+  probes each configured proxy through `Support::Connection` and warns on
+  plaintext credentials in `config.json`.
+- Requires `portage-ucp` `~> 0.10` (for `Support::Connection` and
+  `ProxyConfig`) and `portage-ucp-client` `>= 0.6.3` (for
+  `Client::USER_AGENT`, which the default User-Agent is built from). Both
+  floors were too low before: against `portage-ucp` 0.9.0 or
+  `portage-ucp-client` 0.6.2, `require "portage/cli"` raised `NameError`.
+- `portage --version` (also `-v` and `portage version`) prints the gem's
+  version and exits 0. Needed so a packaged install — the Homebrew
+  formula's offline `test do` block, or anyone else scripting around a
+  release — can confirm which build is on `PATH` without hitting the
+  network.
+- **`portage-console` failed to start on Ruby 4.0.** It requires `irb`,
+  which stopped being a default gem in Ruby 4.0 (it's a bundled gem now),
+  and the gemspec never declared it, so any isolated install
+  (Homebrew's, or anything under Bundler) raised `LoadError: cannot load
+  such file -- irb`. `irb` is now a runtime dependency.
+- **Did the shopper finish the checkout? `portage orders reconcile`.**
+  Every checkout `portage buy` hands to the shopper's own browser
+  (`requires_escalation`, `permission_denied`, `no_payment_token`,
+  `policy_blocked`, `low_confidence`, `checkout_mismatch`) now reserves a
+  pending record in the transaction log (best-effort — a failed write is a
+  report warning, never blocks the hand-off). `portage orders reconcile
+  [--checkout ID] [--json]` re-fetches each pending checkout from the store
+  and settles it: `complete` only on a store-reported `completed` status,
+  `failed` on `canceled` or an unanswered expiry, otherwise stays pending.
+  Never infers success from a vanished checkout or a plain timeout. Safe to
+  run from cron/launchd. See `docs/plans/handoff-reconcile.md`.
+- **`handoff_spend_mode`** (`PORTAGE_HANDOFF_SPEND_MODE`, config.json) —
+  whether a reconciled shopper purchase counts toward the buyer's own spend
+  cap/velocity limit. `block` (default): counts like any agent purchase.
+  `warn`: recorded but excluded from cap math. `precheck`: `block`, plus a
+  spend-cap check at hand-off time that suppresses auto-open (never the
+  URL) when this checkout would already exceed the cap.
+- Phase 0 of the plan above (a live signal check against a real store) was
+  not run before this shipped — see `docs/design-log.md` §44.
+- **`portage buy --wait [--wait-timeout DURATION|off]`.** After a hand-off,
+  polls `HandoffReconciler` with backoff (2s → 30s, plus jitter) until the
+  checkout settles or its deadline passes — the earlier of
+  `handoff_wait_timeout` (`PORTAGE_HANDOFF_WAIT_TIMEOUT`, config.json;
+  default 30m, `off` removes it) and the checkout's own `expires_at`.
+  Ctrl-C or the deadline leaves the record pending for a later `portage
+  orders reconcile`; it never settles from the wait itself. Under `--wait
+  --json`, stdout streams NDJSON (`handoff`, `handoff_status` on each
+  store-reported status change, `handoff_settled`) followed by the final
+  report object; plain `--json` with no `--wait` is unchanged byte-for-byte.
+- **`reconcile_notify`** (`PORTAGE_RECONCILE_NOTIFY`, config.json) — a comma
+  list of channels a settled hand-off notifies on, from `--wait` or `portage
+  orders reconcile`. Default `webhook`. Adds `macos` (a native notification,
+  merchant/amount escaped into a fixed AppleScript template) and `terminal`
+  (a printed line, forced on for a plain-text `--wait` regardless of
+  configuration). `journal` is accepted for documentation — the Phase 1
+  order-snapshot journal write was already unconditional.
+- **WebMCP outbound, opt-in (Phase 4, partial).** `Buy.new(webmcp_bridge:)`
+  takes a `portage-ucp-webmcp` outbound bridge already pointed at a
+  navigated page; when given one, `portage-cli` tries it after native-UCP
+  discovery finds nothing and before a platform-adapter fallback. Only
+  `webmcp_checkout_mode: express_stop` (the default) is implemented: it
+  builds the cart/checkout and always hands off (reason `express_stop`),
+  feeding Phases 1-3 unchanged, since a WebMCP page doesn't expose
+  `complete_checkout` by default anyway. `token` mode reports
+  `webmcp_token_unsupported` rather than attempting completion — it still
+  needs a `Confirmer`-swap seam in `Mcp::Server.build` and payment-token
+  enrollment that don't exist yet. No new hard runtime dependency:
+  `portage-ucp-webmcp` is lazily `require`d, same posture as an optional
+  platform adapter gem.
+
+## [0.7.2] - 2026-09-24
+
+- The User-Agent every store-facing request sends (`Cli::UserAgent`, née
+  `Cli::USER_AGENT`/`Cli::HTTP_HEADERS`) is now configurable: `PORTAGE_USER_AGENT`
+  beats `~/.portage/config.json`'s `user_agent` key, both of which beat the
+  `portage-cli/<ver> portage-ucp-client/<ver> (+https://github.com/...)`
+  default — same precedence `Notifier`'s webhook URL already uses. `portage
+  doctor` (and its `configure`/`setup` aliases) now flags a configured value
+  containing a stray newline, since `Net::HTTP` would otherwise raise on it
+  mid-checkout instead of at setup time.
+
+## [0.7.1] - 2026-09-24
+
+- Fix: `buy <url> --max-price` (and `--product-id` with `--max-price`) was
+  silently ignored — `add_search_options` only wired `--max-price` into the
+  `find` options, not `buy`, so a URL-driven buy could complete over the cap
+  the caller set. `Buy#select_product` now filters to products within
+  `max_price` first, using a variant's own price where available and
+  otherwise the product's lowest price (unpriced products stay eligible,
+  same rule `Find` already used). `no_match_message` now names the cap.
+- Every store-facing request (`discover()` calls and the notifier webhook
+  POST) now sends `portage-cli/<ver> portage-ucp-client/<ver>
+  (+https://github.com/tomtom87/Portage)` instead of Ruby's or Faraday's
+  default User-Agent. New `Cli::USER_AGENT`/`Cli::HTTP_HEADERS`
+  (`lib/portage/cli/user_agent.rb`) replace the ad-hoc UA strings each of
+  `portage-buy`, `portage-find` and `portage-payment-enroll` built on their
+  own. Requires `portage-ucp-client >= 0.6.3`.
+
 ## [0.7.0] - 2026-09-23
 
 - **The decision layer is wired in.** `buy`/`find` make their judgment

data/README.md

@@ -70,6 +70,7 @@ gem install portage-cli
 portage buy <url> --query "..." [--qty N] [--payment-token TOKEN] [--product-id ID]
                                 [--yes] [--dry-run] [--decision-backend jev|laya]
                                 [--min-confidence N] [--json]
+                                [--wait [--wait-timeout DURATION|off]]
 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]
@@ -88,8 +89,20 @@ 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]
+portage orders reconcile [--checkout ID] [--json]
 ```
 
+`buy`/`find`/`compare`/`doctor`/`payment enroll` (the network-touching commands —
+`orders reconcile` doesn't take these) also accept:
+
+```
+[--proxy URL] [--proxy-mode forward|gateway] [--proxy-header "Name: value"]
+[--no-proxy HOSTS] [--proxy-route ROUTE=URL|direct] [--proxy-chain URL,URL,...]
+[--proxy-passthrough HEADER] [--proxy-ca FILE] [--no-env-proxy]
+```
+
+See "Proxy" below.
+
 - `--query` — search term. Against the store's catalog when you name a store,
   against the search backends when you don't.
 - `--qty` — quantity, default `1`.
@@ -102,7 +115,10 @@ portage policy set [--per-transaction-cap N --currency CUR]
   search ranks first. If the id isn't in the results, nothing is bought.
 - `--store` — name the merchant without giving a full URL; skips the search.
 - `--max-price` — in major units (`400` means 400), compared per offer in that
-  offer's own currency. No FX conversion.
+  offer's own currency. No FX conversion. Applies per unit, to the search and
+  to the store's own catalog once one is settled (a URL, `--store`, or a
+  picked offer): nothing priced above it is checked out, even with
+  `--product-id`. A product with no price is still eligible.
 - `--limit` — how many candidate stores to probe, capped at 12.
 - `--yes` — skip the confirmation prompt before completing checkout.
 - `--dry-run` — resolve and price the order without completing checkout.
@@ -270,6 +286,135 @@ 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.
 
+### Orders reconcile
+
+Nearly every real checkout `portage buy` can't finish itself hands the
+shopper a link — `requires_escalation`, `permission_denied`,
+`no_payment_token`, `policy_blocked`, `low_confidence`, or
+`checkout_mismatch`. That's a pending purchase this process knows nothing
+more about until something asks the store. `portage orders reconcile`
+re-fetches each pending hand-off from the store and settles it once the
+store itself reports a terminal status:
+
+```bash
+portage orders reconcile              # every pending hand-off
+portage orders reconcile --checkout chk_123
+portage orders reconcile --json
+```
+
+A `completed` checkout settles `complete` — using the store's own total at
+settle time, not the hand-off-time snapshot — records the order (when one
+exists) and a journal entry, and is counted toward your spend policy's
+rolling cap/velocity per `handoff_spend_mode` below. A `canceled` checkout,
+or one that expires with no answer, settles `failed`. Anything still
+in-progress, or not currently reachable, is left pending for the next run —
+safe to put on a cron/launchd schedule; two overlapping runs never
+double-settle the same record.
+
+`handoff_spend_mode` (`PORTAGE_HANDOFF_SPEND_MODE`, config.json's
+`handoff_spend_mode`) controls whether a reconciled shopper purchase counts
+toward the caps `portage policy set` configures:
+
+- `block` (default) — counts like any agent-completed purchase.
+- `warn` — recorded, but excluded from the cap/velocity math; still notifies
+  when it would have pushed spend over the cap.
+- `precheck` — `block`, plus a spend-cap check at hand-off time
+  (`portage buy`, not reconcile): if this checkout's total would already
+  exceed your cap, the URL is still printed but auto-open is suppressed.
+
+`--wait [--wait-timeout DURATION|off]` on `portage buy` polls the same
+reconciler right after a hand-off, instead of waiting for a separate
+`orders reconcile` run. It backs off (2s → 30s, plus jitter) until the
+checkout settles or its deadline passes — the earlier of
+`handoff_wait_timeout` (`PORTAGE_HANDOFF_WAIT_TIMEOUT`, config.json; default
+`30m`, `off` removes it) and the checkout's own `expires_at`. Ctrl-C, or
+the deadline, leaves the record pending for a later `portage orders
+reconcile` — it never settles from the wait itself. Under `--wait --json`,
+stdout streams NDJSON — `handoff`, `handoff_status` on each store-reported
+status change, `handoff_settled` — followed by the final report object;
+plain `--json` without `--wait` is unchanged.
+
+`reconcile_notify` (`PORTAGE_RECONCILE_NOTIFY`, config.json's
+`reconcile_notify`) is a comma list of channels a settled hand-off notifies
+on, from `--wait` or `orders reconcile`: `webhook` (default), `macos` (a
+native notification), `terminal` (a printed line — forced on for a
+plain-text `--wait` regardless of configuration), and `journal` (the order
+snapshot journal write, already unconditional — listing it just documents
+that).
+
+### Proxy
+
+`buy`, `find`, `compare`, `doctor`, and `payment enroll` accept the flags below,
+resolved (per field, flag > env > `~/.portage/config.json`) into a
+`Portage::Ucp::Support::ProxyConfig` by `Portage::Cli::ProxySettings` — see
+[`docs/proxy.md`](../docs/proxy.md) for corporate egress, a rotating residential
+pool, an API gateway, mitmproxy for debugging, and nginx/Cloudflare in front of the
+MCP/WebMCP endpoints, worked through end to end.
+
+| Flag | Meaning |
+| --- | --- |
+| `--proxy URL` | The default proxy's URL (`http://user:pass@host:port`). Overrides only `proxy.default.url`; every other configured field (`no_proxy`, `routes`, `chains`, ...) stays as set in config.json. |
+| `--proxy-mode forward\|gateway` | The default profile's mode. `forward` (the default) is a standard HTTP proxy; `gateway` is a URL-rewriting gateway — see `docs/proxy.md`. |
+| `--proxy-header "Name: value"` | Repeatable. Sent only to the proxy (on the `CONNECT` request, or the gateway request) — never to the real target. `Authorization`/`User-Agent`/`X-Shopify-*-Access-Token`/`X-Payment-Token` are refused here, always. |
+| `--no-proxy HOSTS` | Comma-separated hostnames/suffixes/CIDRs (or a bare `*`) to always bypass the proxy for, whatever the route resolves to. |
+| `--proxy-route ROUTE=URL\|direct` | Repeatable. Points one fixed route (`store`, `search`, `notify`, `payment`, `platform`, `probe`) at its own URL, or forces it `direct` regardless of `default`. |
+| `--proxy-chain URL,URL,...` | An ad-hoc multi-hop chain for this run — each hop is `forward` unless prefixed `gateway+https://...`. Overrides the whole `default` profile (not just its `url`), since a chain has no single "url" field to merge with config.json's own. |
+| `--proxy-passthrough HEADER` | Repeatable, server commands only. Allowlists an inbound request header to ride along on outbound calls made while serving it — see `docs/proxy.md`'s passthrough section. Refuses a protected header name at parse time. |
+| `--proxy-ca FILE` | A PEM file trusted in addition to the system store — for a TLS-intercepting corporate proxy or a debugging proxy like mitmproxy. |
+| `--no-env-proxy` | Ignore `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY` (and their lowercase forms) entirely for this run — otherwise they're still the fallback for any route nothing else configured. |
+
+**Env vars** (checked when the matching flag is absent, before config.json):
+
+| Var | Matches |
+| --- | --- |
+| `PORTAGE_PROXY` | `--proxy` |
+| `PORTAGE_PROXY_MODE` | `--proxy-mode` |
+| `PORTAGE_NO_PROXY` | `--no-proxy` |
+| `PORTAGE_PROXY_CA` | `--proxy-ca` |
+| `PORTAGE_PROXY_HEADERS` | A JSON object of header name → value, merged under any `--proxy-header` flags (flags win on a name collision). |
+
+Below all of the above, the standard `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY` (and
+lowercase) variables are still the fallback for any route nothing here configures
+at all — existing environments keep working unless `--no-env-proxy` is set. The
+**`payment` route is always forced `direct`** unless a proxy is named for it
+explicitly (`--proxy-route payment=...` or config.json's `routes.payment`) — it
+never inherits a bare `default`/env proxy the way every other route does, so an
+egress proxy nobody meant to hand payment tokens to never sees them by accident.
+
+`${ENV_VAR}` inside a config.json header value (`proxy_headers`, `forward_headers.add`)
+is expanded from the process environment at resolve time, so a secret can live in
+the environment rather than the file itself. A proxy password can also live in
+`password_ref` (resolved through the same macOS Keychain/Linux Secret Service tiers
+`portage payment` uses, under its own `portage-cli-proxy` service name) instead of
+plaintext in the URL — `portage doctor` warns when it finds a plaintext one anyway.
+
+`portage doctor` reports, per route, what's effectively configured (credentials
+redacted), whether each configured proxy/gateway is actually reachable, and flags
+plaintext proxy credentials and an intercepting proxy (`ca_file` or `gateway` mode)
+sitting on the `payment` route.
+
+### WebMCP (library use, opt-in)
+
+`portage buy` from the shell has no browser of its own, so there's no CLI
+flag for this — it's for a caller embedding `Portage::Cli::Buy` directly
+alongside its own browser automation:
+
+```ruby
+Portage::Cli::Buy.new(url: "shop.example", query: "mug",
+                      webmcp_bridge: my_portage_ucp_webmcp_bridge).call
+```
+
+Given a `portage-ucp-webmcp` outbound bridge already pointed at a navigated
+page, `Buy` tries it after native-UCP discovery finds nothing at that URL
+and before falling back to a platform adapter. `webmcp_checkout_mode`
+(`PORTAGE_WEBMCP_CHECKOUT_MODE`, config.json's `webmcp_checkout_mode`)
+controls how it finishes: `express_stop` (default) builds the cart/checkout
+and always hands off — reason `express_stop`, so `--wait`/`orders
+reconcile`/`handoff_spend_mode` all apply exactly as they do to any other
+hand-off. `token` isn't implemented yet; it reports
+`webmcp_token_unsupported` rather than attempting completion. Requires
+`gem install portage-ucp-webmcp` — not a hard dependency of `portage-cli`.
+
 ### Decisions
 
 `portage buy` and `portage find` make their judgment calls

data/lib/portage/cli/buy.rb

@@ -10,6 +10,13 @@ require_relative "decisions"
 require_relative "confidence_check"
 require_relative "checkout_handoff"
 require_relative "notifier"
+require_relative "user_agent"
+require_relative "homepage_fetch"
+require_relative "permissive_authenticator"
+require_relative "handoff_reconciler"
+require_relative "handoff_spend_mode"
+require_relative "webmcp"
+require_relative "webmcp_checkout_mode"
 
 module Portage
   module Cli
@@ -49,13 +56,26 @@ module Portage
       #   rolling cap and velocity limit count. nil (the default) is the
       #   real ~/.portage/transactions.json, the file Dispatcher writes for
       #   own-store purchases.
-      # rubocop:disable Metrics/ParameterLists -- all keywords; one per flag, plus two injectable collaborators
+      # @param max_price [Integer, nil] the most one unit may cost, in minor
+      #   units (same as Find's). A product priced above it is never picked,
+      #   even with a --product-id; one with no price to go on still is, as
+      #   in Find, and the checkout's own total then meets the spend policy.
+      # @param webmcp_bridge [#list_tools, #execute_tool, nil] docs/plans/
+      #   handoff-reconcile.md Phase 4 — a `portage-ucp-webmcp` outbound
+      #   Bridge (already pointed at a navigated page) an embedding caller
+      #   already holds. nil (the default, and the only option from the
+      #   `portage buy` CLI, which has no browser of its own) skips WebMCP
+      #   entirely — zero behavior change from before this parameter
+      #   existed. Given one, attempted after native-UCP discovery finds
+      #   nothing at this URL and before a platform-adapter fallback (see
+      #   #webmcp_flow).
+      # rubocop:disable Metrics/ParameterLists -- all keywords; one per flag, plus injectable collaborators
       def initialize(url:, query:, qty: 1, payment_token: nil, yes: false, dry_run: false, product_id: nil,
-                     auto_open: nil, notify_webhook: nil, confidence_check: nil, transaction_log: nil)
+                     auto_open: nil, notify_webhook: nil, confidence_check: nil, transaction_log: nil,
+                     max_price: nil, webmcp_bridge: nil)
         # rubocop:enable Metrics/ParameterLists
         raw = url.to_s.strip
-        raw = "https://#{raw}" unless raw =~ %r{\Ahttps?://}i
-        @uri = URI.parse(raw)
+        @uri = URI.parse(raw =~ %r{\Ahttps?://}i ? raw : "https://#{raw}")
         @query = query
         @qty = qty
         @payment_token = payment_token
@@ -66,6 +86,8 @@ module Portage
         @notify_webhook = notify_webhook
         @confidence_check = confidence_check
         @transaction_log = transaction_log
+        @max_price = max_price
+        @webmcp_bridge = webmcp_bridge
         @decisions = {}
       end
 
@@ -84,6 +106,9 @@ module Portage
           return native_flow(session) if session
         end
 
+        webmcp_result = webmcp_flow
+        return webmcp_result if webmcp_result
+
         platform = Portage::Ucp::Resolver.detect_platform(body, headers)
         adapter_flow(platform) || dead_end
       end
@@ -93,7 +118,7 @@ module Portage
       # --- Step 1: native UCP manifest ---
 
       def discover(url)
-        Portage::Ucp::Client.discover(url.to_s)
+        Portage::Ucp::Client.discover(url.to_s, headers: UserAgent.headers)
       rescue Portage::Ucp::Client::ManifestShapeError => e
         # The store *is* running UCP — this client just couldn't parse its
         # manifest. Distinct from a genuine 404/unreachable host below:
@@ -200,6 +225,64 @@ module Portage
         match && URI.join(@uri, match[1])
       end
 
+      # --- Step 1b: WebMCP outbound (docs/plans/handoff-reconcile.md Phase 4) ---
+      #
+      # Opt-in only: nil unless a caller passed `webmcp_bridge:` (see
+      # #initialize), so `portage buy` from the shell — with no browser of
+      # its own — sees no behavior change here at all. Attempted after
+      # native-UCP discovery finds nothing at this URL and before falling
+      # back to a platform adapter, since a WebMCP page, like native UCP,
+      # works without this process holding the store's own credentials.
+      #
+      # `express_stop` (the only implemented mode) builds the cart and
+      # checkout, then always hands off rather than attempting
+      # #complete_checkout — which a WebMCP page doesn't expose by default
+      # in the first place (ToolCatalog leaves it out: it needs a
+      # server-side Confirmer swap this gem doesn't have a seam for yet).
+      # That hand-off feeds Phases 1-3 completely unchanged: reason
+      # `express_stop` reserves a pending record, notifies, and later
+      # reconciles exactly like any other hand-off.
+      def webmcp_flow
+        return nil unless @webmcp_bridge
+        return webmcp_not_installed_report unless Portage::Cli::Webmcp.available?
+
+        session = Portage::Ucp::WebMcp.connect(bridge: @webmcp_bridge)
+        return nil unless session.advertises?(CART_CAP) && session.advertises?(CHECKOUT_CAP)
+
+        return webmcp_token_unsupported_report if webmcp_checkout_mode == "token"
+
+        full_buy(session, source: "webmcp", force_handoff: true)
+      rescue Portage::Ucp::WebMcp::BridgeError, Portage::Ucp::WebMcp::ToolNotFoundError,
+             Portage::Ucp::Client::ServerError => e
+        build_report(source: "webmcp", outcome: "webmcp_error", browse: false, checkout: false,
+                     message: "WebMCP checkout failed: #{e.message}")
+      end
+
+      def webmcp_checkout_mode
+        Portage::Cli::WebmcpCheckoutMode.resolve
+      end
+
+      def webmcp_not_installed_report
+        build_report(source: "webmcp", outcome: "webmcp_not_installed", browse: false, checkout: false,
+                     message: "A WebMCP bridge was given but portage-ucp-webmcp isn't installed — " \
+                              "`gem install portage-ucp-webmcp`.")
+      end
+
+      # `token` mode isn't implemented: it needs `Mcp::Server.build` to swap
+      # in a payment-token Confirmer for a WebMCP session (see
+      # portage-ucp-webmcp's README, "complete_checkout"), plus PayPal/Stripe
+      # agent-token enrollment in `portage payment enroll` — neither exists
+      # yet (docs/plans/handoff-reconcile.md Phase 4 is explicitly a sketch
+      # pending that design). Fails loudly here rather than silently
+      # behaving like `express_stop`, so a caller who configured `token`
+      # notices instead of getting a hand-off they didn't ask for.
+      def webmcp_token_unsupported_report
+        build_report(source: "webmcp", outcome: "webmcp_token_unsupported", browse: false, checkout: false,
+                     message: "webmcp_checkout_mode=token isn't supported yet — see " \
+                              "docs/plans/handoff-reconcile.md Phase 4. Use express_stop (the default), or " \
+                              "complete the checkout via the page's own payment button.")
+      end
+
       # --- Step 2/3: platform detection + adapter fallback ---
 
       def adapter_flow(platform)
@@ -296,7 +379,11 @@ module Portage
       # remote store, so shipping-address/rate selection stays loopback-only
       # for now rather than guessing at a wire shape no real UCP server has
       # confirmed (see docs/design-log.md).
-      def full_buy(session, source:, fulfillment_adapter: nil)
+      # @param force_handoff [Boolean] docs/plans/handoff-reconcile.md Phase
+      #   4's `express_stop` — skips escalation/confirmation/completion
+      #   entirely and always hands the built checkout off, once past the
+      #   `--dry-run` check. Only #webmcp_flow ever sets this.
+      def full_buy(session, source:, fulfillment_adapter: nil, force_handoff: false)
         products = safe_search(session)
         product = select_product(products)
         unless product
@@ -310,7 +397,7 @@ module Portage
         checkout = select_cheapest_shipping(session, checkout) if fulfillment_adapter
 
         warnings = reconcile_checkout(product, checkout)
-        finish_checkout(session, source, products, checkout, warnings)
+        finish_checkout(session, source, products, checkout, warnings, force_handoff: force_handoff)
       end
 
       # A store can silently drop the requested line, change its quantity, or
@@ -406,9 +493,10 @@ module Portage
       end
 
       def no_match_message
-        return "No product matched \"#{@query}\"." unless @product_id
+        budget = @max_price ? " at or under #{@max_price} minor units" : ""
+        return "No product matched \"#{@query}\"#{budget}." unless @product_id
 
-        "Product #{@product_id} isn't in this store's results for \"#{@query}\"."
+        "Product #{@product_id} isn't in this store's results for \"#{@query}\"#{budget}."
       end
 
       # With a --product-id, that exact product or nothing: falling back to the
@@ -420,12 +508,28 @@ module Portage
       # when an in-stock match sits right below it (confirmed live
       # 2026-09-23 on allbirds.com and billabong.com). Falls back to the top
       # hit when nothing reports stock, so the store still gets to answer.
+      #
+      # Either way, only among products within --max-price: before it
+      # reached here, `buy <url> --max-price` checked out whatever the store
+      # ranked first (confirmed live 2026-09-24: a $679.95 board on
+      # burton.com under --max-price 600).
       def select_product(products)
+        products = products.select { |product| within_max_price?(product) }
         return products.find { |product| available?(product) } || products.first unless @product_id
 
         products.find { |product| product_id_of(product) == @product_id }
       end
 
+      # Priced the way #reconcile_checkout expects the store to charge: the
+      # variant #line_item_id_of would check out, else the product's lowest
+      # price.
+      def within_max_price?(product)
+        return true unless @max_price
+
+        price = expected_unit_price(product, line_item_id_of(product))
+        price.nil? || price <= @max_price
+      end
+
       # A product with no variant availability to go on counts as buyable —
       # only an explicit `available: false` on every variant rules it out.
       def available?(product)
@@ -462,10 +566,11 @@ module Portage
           product_id_of(product)
       end
 
-      def finish_checkout(session, source, products, checkout, warnings = [])
+      def finish_checkout(session, source, products, checkout, warnings = [], force_handoff: false)
         escalation = decide_escalation(checkout, warnings)
         return escalated_report(source, products, checkout, warnings, escalation) if escalation[:escalate]
         return dry_run_report(source, products, checkout, warnings) if @dry_run
+        return webmcp_handoff_report(source, products, checkout, warnings) if force_handoff
         return confirmation_needed_report(source, products, checkout, warnings) unless confirmed?
 
         complete(session, source, products, checkout, warnings)
@@ -670,10 +775,23 @@ module Portage
       # relay and an agent loop branch on the same value.
       def handoff_report(source, products, checkout, warnings, outcome:, message:)
         handoff = hand_off(checkout, reason: outcome, source: source, message: message, warnings: warnings)
-        checkout_report(source, products, checkout, outcome: outcome, warnings: warnings, message: message,
+        checkout_report(source, products, checkout, outcome: outcome, message: message,
+                                                    warnings: warnings + Array(@pending_handoff_warning),
                                                     checkout_url: checkout_url_of(checkout), handoff: handoff)
       end
 
+      # docs/plans/handoff-reconcile.md Phase 4 — #webmcp_flow's
+      # `express_stop` mode. Reuses #handoff_report as-is: reason
+      # `express_stop` reserves a pending shopper record and fires
+      # auto-open/notify exactly like any other hand-off (Phases 1-3 apply
+      # unchanged), even though it got here because a mode setting chose to
+      # stop, not because anything was denied or escalated.
+      def webmcp_handoff_report(source, products, checkout, warnings)
+        message = "Cart and checkout are built — finish payment with the store's own express-pay button " \
+                  "on the page."
+        handoff_report(source, products, checkout, warnings, outcome: "express_stop", message: message)
+      end
+
       # Never fires on --dry-run (a dry run creates a real checkout but never
       # attempts completion — auto-opening/notifying over a preview run would
       # be actively wrong), and never fires without a checkout_url to hand
@@ -685,15 +803,67 @@ module Portage
       # The webhook body carries the report's own `message`, plus the store
       # and the shopper's query, so a Slack/Zapier relay can post it as-is
       # without a lookup back into this process.
+      #
+      # Also where docs/plans/handoff-reconcile.md Phase 1 records a pending
+      # `settled_by: "shopper"` TransactionLog row (best-effort — a failed
+      # write surfaces as a warning, never blocks the hand-off itself), and
+      # where Phase 2's `precheck` spend mode suppresses auto-open when this
+      # checkout's total would already exceed the buyer's own spend cap.
       def hand_off(checkout, reason:, source:, message:, warnings:)
         url = checkout_url_of(checkout)
         return nil if @dry_run || url.nil?
 
-        opened = CheckoutHandoff.new(auto_open: @auto_open).call(url)
-        error = notifier.call(event: "checkout_handoff", reason: reason, message: message, store: @uri.to_s,
-                              query: @query, checkout_url: url, checkout_id: checkout["id"], source: source,
-                              totals: checkout["totals"], warnings: warnings)
-        { url: url, opened: opened, notified: notifier.enabled? && error.nil?, notify_error: error }
+        over_cap = precheck_mode? && over_spend_cap?(checkout)
+        record_pending_handoff(checkout, reason: reason)
+
+        opened = over_cap ? false : CheckoutHandoff.new(auto_open: @auto_open).call(url)
+        error = notifier.call(handoff_notify_payload(checkout, url, reason: reason, source: source, message: message,
+                                                                    warnings: warnings, over_cap: over_cap))
+        result = { url: url, opened: opened, notified: notifier.enabled? && error.nil?, notify_error: error }
+        over_cap ? result.merge(over_cap: true) : result
+      end
+
+      def handoff_notify_payload(checkout, url, reason:, source:, message:, warnings:, over_cap:)
+        payload = { event: "checkout_handoff", reason: reason, message: message, store: @uri.to_s,
+                    query: @query, checkout_url: url, checkout_id: checkout["id"], source: source,
+                    totals: checkout["totals"], warnings: warnings }
+        over_cap ? payload.merge(over_cap: true) : payload
+      end
+
+      # Never raises: a record that can't be written is a warning on the
+      # report (surfaced via @pending_handoff_warning, see #handoff_report),
+      # not a reason to fail the hand-off itself — same posture as
+      # #settle_transaction's own @unrecorded_warning.
+      def record_pending_handoff(checkout, reason:)
+        transaction_log.reserve(idempotency_key: handoff_transaction_key(checkout), checkout_id: checkout["id"],
+                                shop: @uri.host, payment_token_ref: token_ref, amount: checkout_total(checkout),
+                                currency: checkout["currency"], settled_by: "shopper", handoff_reason: reason,
+                                store_url: @uri.to_s, expires_at: checkout["expires_at"])
+      rescue StandardError => e
+        @pending_handoff_warning = "Couldn't save this hand-off for later reconcile (#{e.message}) — " \
+                                   "run `portage orders reconcile --checkout #{checkout['id']}` once fixed, " \
+                                   "or it'll never be picked up automatically."
+      end
+
+      def handoff_transaction_key(checkout)
+        "portage-buy:#{@uri.host}:#{checkout['id']}"
+      end
+
+      def precheck_mode?
+        Portage::Cli::HandoffSpendMode.resolve == "precheck"
+      end
+
+      # Same PolicyGuard the buyer's own spend cap already goes through
+      # (#decide_policy) — reused here so a hand-off that never reached
+      # #decide_policy at all (escalation, permission_denied, no_payment_token,
+      # checkout_mismatch) still gets the buyer a heads-up that finishing
+      # this checkout by hand would blow the cap, before they do.
+      def over_spend_cap?(checkout)
+        Portage::Ucp::PolicyGuard.check!(amount: checkout_total(checkout), currency: checkout["currency"],
+                                         merchant: @uri.host, token_ref: token_ref, transaction_log: transaction_log)
+        false
+      rescue Portage::Ucp::PolicyViolationError
+        true
       end
 
       def notifier
@@ -796,23 +966,7 @@ module Portage
       # catalog-only-native adapter-checkout-fallback path) ---
 
       def fetch_homepage(uri, limit = REDIRECT_LIMIT)
-        return [nil, {}] if limit.zero?
-
-        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                                                       open_timeout: 5, read_timeout: 5) do |http|
-          http.get(uri.request_uri, { "User-Agent" => "portage-buy" })
-        end
-
-        case response
-        when Net::HTTPRedirection
-          fetch_homepage(URI.join(uri, response["location"]), limit - 1)
-        when Net::HTTPSuccess
-          [response.body, response.to_hash]
-        else
-          [nil, {}]
-        end
-      rescue StandardError
-        [nil, {}]
+        HomepageFetch.call(uri, limit: limit)
       end
 
       def dead_end
@@ -823,14 +977,6 @@ module Portage
       def build_report(**fields)
         { url: @uri.to_s, checkout_url: nil, products: [], warnings: [] }.merge(fields)
       end
-
-      # Loopback buy against your own store needs *some* authenticator (§9
-      # rejects anonymous mutation by default) — since this process already
-      # has this platform's own credentials (that's the gate to even reach
-      # here), authenticating this local CLI session is reasonable.
-      class PermissiveAuthenticator < Portage::Ucp::Authenticator
-        def call(_server_context) = :local_cli
-      end
     end
   end
 end