portage-cli 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 805f3c78c6560bcdb4110d1bb97dcaa0700a7586578cc639fb94595cfd5c09bc
-  data.tar.gz: f2f4ca834b30fb319563ea10741385150559437bdfd87bc4657051d1f2dc0182
+  metadata.gz: 3d34c9ba25977baefa9f1f802e38ae6b2175e455d246f7a0dd3a2833136c46e8
+  data.tar.gz: 2c1d701bafd9c914115bdb02ab661906eaddba139e0627a56bfa0cf094e71d06
 SHA512:
-  metadata.gz: 3b10afae4ce3260952193fd8c32b7eb8b5a97b8a4292ca78e40848a41fd94f84e3f18490115186296253edd1d8fdf65a1cd728c1eca5e96efc8a21c18563ebcb
-  data.tar.gz: 03b8c8ba8a3ee6e19116d00f6775c6825e3c70d23f7a4b1864acb44435988edf9ba400a52cdf5548ee9660e0588cd938f0c0eba6ed24afcea0010d2669abddb3
+  metadata.gz: ec3b6bf08d832abbe197591050b229f38a3650603feb6e94b47a6e84fbb9d3b9ddf531c51e84d71c8b708131b655e6b501e6a55662908eb6edb60981da4f14a2
+  data.tar.gz: 137b718fd1283383aa70879a6f2290a35dc1bc3f3a898ceff6965019b110329caf943dcf3ef39c04c29d1661beee3da6edd3a056877b7a6c3a932debce90c99f

data/CHANGELOG.md

@@ -6,6 +6,63 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [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,15 @@ 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 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 +150,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]
@@ -361,6 +367,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 +758,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,6 +10,7 @@ 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 "offer_sources"
@@ -115,12 +116,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 +148,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
@@ -970,6 +979,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 +990,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

data/lib/portage/cli/checkout_handoff.rb

@@ -1,6 +1,7 @@
 require "uri"
 require_relative "config"
 require_relative "setting"
+require_relative "browser_opener"
 
 module Portage
   module Cli
@@ -14,13 +15,11 @@ module Portage
     # --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.
+    # The open itself is BrowserOpener's array-form `system` shell-out, so
+    # a merchant-controlled checkout_url can't inject into a shell.
     class CheckoutHandoff
+      include BrowserOpener
+
       ENV_VAR = "PORTAGE_AUTO_OPEN_CHECKOUT".freeze
       CONFIG_KEY = "auto_open_checkout".freeze
 
@@ -47,24 +46,6 @@ module Portage
       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/find.rb

@@ -1,4 +1,5 @@
 require "uri"
+require "securerandom"
 require "portage/ucp"
 require "portage/ucp/client"
 
@@ -62,7 +63,7 @@ module Portage
         sourced = source_offers
         return report(candidates: candidates, message: no_candidates_message) if nothing_to_go_on?(candidates, sourced)
 
-        offers = rank(sourced + probed.flat_map { |store| offers_for(store) })
+        offers = rank(sourced + probed.flat_map { |store| offers_for(store) }).map { |o| with_offer_ref(o) }
         report(candidates: candidates, stores: store_summaries(stores), offers: offers,
                message: summary(candidates, stores, offers))
       rescue Portage::Ucp::Client::MissingAgentProfileError
@@ -78,6 +79,12 @@ module Portage
       # the complexity budget.
       def nothing_to_go_on?(candidates, sourced) = candidates.empty? && sourced.empty?
 
+      # A short opaque id `portage buy --offer` resolves from history, so a
+      # later step can point at one offer without re-sending its store,
+      # product id and query. Added last, after ranking, so it never
+      # influences the order.
+      def with_offer_ref(offer) = { offer_ref: "of_#{SecureRandom.hex(3)}" }.merge(offer)
+
       # --- Step 1: ask the backends who might sell this ---
 
       def candidate_origins

data/lib/portage/cli/history.rb

@@ -1,5 +1,6 @@
 require "json"
 require "fileutils"
+require "securerandom"
 
 module Portage
   module Cli
@@ -40,11 +41,43 @@ module Portage
 
       # @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,
+      # @param offers [Array<Hash>] a `find`'s (or `compare`'s) offers, kept
+      #   so `portage buy --offer REF` can resolve an `offer_ref` later (see
+      #   #offer). A search that keeps offers also gets a `search_id`, which
+      #   `portage pick --search` names it by (docs/plans/
+      #   human-pick-and-approve.md Phase 2).
+      # @return [Hash] the saved entry.
+      def record_search(query:, offer_count:, message:, url: nil, offers: [])
+        kept = offers.empty? ? nil : saved_offers(offers)
+        append("searches", { "search_id" => kept && "se_#{SecureRandom.hex(4)}", "query" => query, "url" => url,
+                             "offer_count" => offer_count, "message" => message, "offers" => kept,
                              "at" => @now }.compact)
       end
 
+      # @param id [String, nil] a `search_id`, or nil/"LAST" for the most
+      #   recent search that kept offers.
+      # @return [Hash, nil]
+      def search(id = nil)
+        with_offers = store["searches"].select { |search| Array(search["offers"]).any? }
+        return with_offers.last if id.nil? || id.casecmp?("last")
+
+        with_offers.reverse.find { |search| search["search_id"] == id }
+      end
+
+      # @return [Hash, nil] the saved offer for `ref` (store, product_id,
+      #   title, amount, currency, url, checkout, found_at) plus the catalog
+      #   `query` to buy it with — the offer's own when it was saved with
+      #   one (a compare result, searched by the compared product's title),
+      #   else that of the search that found it — from the most recent
+      #   search that holds it.
+      def offer(ref)
+        store["searches"].reverse_each do |search|
+          found = Array(search["offers"]).find { |saved| saved["offer_ref"] == ref }
+          return { "query" => search["query"] }.merge(found) if found
+        end
+        nil
+      end
+
       def purchases(limit: MAX_ENTRIES) = store["purchases"].last(limit)
 
       def searches(limit: MAX_ENTRIES) = store["searches"].last(limit)
@@ -58,6 +91,18 @@ module Portage
 
       private
 
+      # Takes a report's symbol-keyed offers or already-saved string-keyed
+      # ones (`pick` re-saves the offer it compared alongside the results).
+      def saved_offers(offers)
+        offers.map do |offer|
+          offer = offer.transform_keys(&:to_s)
+          saved = { "offer_ref" => offer["offer_ref"], "store" => offer["store"], "product_id" => offer["product_id"],
+                    "title" => offer["title"], "amount" => offer["amount"], "currency" => offer["currency"],
+                    "url" => offer["url"], "checkout" => offer["checkout"], "found_at" => offer["found_at"] || @now }
+          offer["query"] ? saved.merge("query" => offer["query"]) : saved
+        end
+      end
+
       def append(kind, entry)
         store[kind] = (store[kind] + [entry]).last(MAX_ENTRIES)
         write