portage-cli 0.12.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e0a17085649f21644b4e373afc590ab69b92cfdbf23c4b83fbf7ed33b1cc1c8
-  data.tar.gz: 75e4435e369e70f529af29ce9891208615d2f0d458df616dbf11a032f8276ed3
+  metadata.gz: b9dba6d24f2ebadd03022d53d85684d8cbe8e3110b609f1becadd4d5212ec47b
+  data.tar.gz: ed6cfcbb1516e7addd017c25a52343f95c71b72bde869aa7e1acd06a44eb3a48
 SHA512:
-  metadata.gz: d79a48ad6cf39bad956cafbb2e9f3317485af02a14fa3305306a4185839ce3add20326025e9eb4cfa0e0e1709ecbade149b5b2e9109627fb9b3b6112f11e91ed
-  data.tar.gz: 5bbf4e713f496fef30925cb4f59de1ad929e1a51b960c804f6bb60bbce39c8dd0856d3efcd5641f175a25bebfd7868358d63a827d0e6123a3d5b9763a7d27ead
+  metadata.gz: 54563a08ca407b2847502f2a95290598147f4e78aa47f346ce0f20d637d416afb6e5c7119ba4e19e233fe64286a83cb5b47fc1351d63a7aabac81f5065060893
+  data.tar.gz: 396ee2c09e74e5708fd5ade1555c412bf5b342979549b04932809760e0744b303050c0dc92b4a4e97d3e4c8f0090a92f7921cc29b020e277370e2566cdf8ca07

data/CHANGELOG.md

@@ -6,6 +6,34 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.13.1] - 2026-10-07
+
+- **Fix: `portage orders reconcile` can settle a hand-off on a BigCommerce, Magento, Wix or Shopify-adapter store.** Those adapters kept checkout status in the process that created the checkout, so reconcile (a new process) only ever saw `incomplete` or not-found. With their new releases, an adapter checkout that became a paid order reads as `completed` with its `order`, and reconcile settles it and snapshots the order as it does for native UCP stores. No CLI code changed; a new spec covers the adapter loopback path end to end. WooCommerce has no such signal and still stays pending (design-log §55).
+
+- **Fix: `portage orders reconcile` (and `buy --wait`) can read a native UCP checkout again.** `HandoffReconciler` called `get_checkout` and `get_order` without `meta.ucp-agent.profile`, so every real UCP store answered `MissingAgentProfileError`. Reconcile read that as "not found", so a pending hand-off never settled while the checkout lived and would have settled `failed`/`unknown` at expiry even if the shopper had paid. It now sends the same agent profile `buy` does (found in the handoff-reconcile Phase 0 live check, design-log §55). A store error's note is now the server's own message (`ServerError#summary`), not Shopify's whole several-kilobyte UCP envelope.
+
+- **Fix: a store that escalates its checkout can be approved and reconciled under `require_approval`.** On a dry run, including the dry run the default `require_approval: any` makes of an unapproved `buy --yes`, a `requires_escalation` checkout was reported as `requires_escalation`, so no quote was saved, there was nothing to `portage approve`, and the report pointed at the checkout link with no pending hand-off recorded. A dry run now reports it as `dry_run` with a new `handoff_expected: true` key and a note that a real run hands it off, so the gated run returns `needs_approval` and the approved run's hand-off is recorded for reconcile (design-log §55). A plain `--yes` run outside the gate still escalates as before.
+
+## [0.13.0] - 2026-10-05
+
+- **Fix: `payment_methods` adapter fallback no longer silently fails.** `PaymentMethods#adapter_session` referenced `Buy::PermissiveAuthenticator`, which doesn't exist (the class is `Portage::Cli::PermissiveAuthenticator`); the resulting `NameError` was swallowed by the method's `rescue StandardError`, so enrolling against your own adapter-backed store always reported no session. It now requires and uses the right constant. Patch-level bug fix.
+
+- Documentation only, no code change. Comments and changelog entries that cited `docs/plans/homebrew-distribution.md`, which is retired, now cite a permalink at commit d51200f. Patch-level.
+
+- **Removed `Portage::Cli::BrowserProfile::Cdp.close_tab`.** Nothing in the CLI called it. It is a public class method, so this is **breaking** for any caller using it directly; minor-level for a pre-1.0 gem.
+
+- Internal: the Shipping, SearchKeys and RetailerKeys setup-wizard steps now share one `SetupWizard::Steps::EnvKeysStep` base class instead of three copies of the same prompt-and-save body. No behaviour change.
+
+- **`portage browser import` no longer needs the `sqlite3` command-line tool.** It reads the copied Chromium, Firefox and Safari history databases through the `sqlite3` gem, which `portage-cli` already depends on for the local index, instead of shelling out to the system `sqlite3` CLI. The copy-to-tmpdir step (with the `-wal` file) and the UTF-8 scrub are unchanged. `error: "reader_unavailable"` now means a SQLite error reading the copy (for example a corrupt or non-SQLite file) or, for Safari bookmarks, a missing `plutil`; `docs/api/cli-json.md` and the `buy` skill's `references/outcomes.md` say so. `BrowserImport::Sqlite.new` no longer takes a `command:` keyword (it only existed for a spec), which is **breaking** for any caller passing it; minor-level for a pre-1.0 gem.
+
+- **Fix: `payment_methods` enroll now finds your own store when its homepage redirects** (for example apex to `www`). The adapter fallback's homepage fetch followed no redirects; it now follows up to five, like `buy`'s, and every hop stays on the `payment` proxy route (forced direct unless a proxy is named for it). Internally, `PaymentMethods` and `HandoffReconciler` now share one `Cli::AdapterSession` for that fallback, and `HomepageFetch.call` takes a `route:` keyword (default `:store`). Patch-level.
+
+- Internal: `HandoffAgents::Webhook` and `Notifier` now make their JSON POST through one `Notifier.post_json` class method instead of two copies. Timeouts, the agent webhook's https-only check and the error messages are unchanged, and the agent webhook still never falls back to `PORTAGE_NOTIFY_WEBHOOK_URL`. No behaviour change.
+
+- Internal: `BrowserImport::PlistXml` decodes entities with `CGI.unescapeHTML` (from the default `cgi/escape` library) instead of its own table. The same for the five named entities and decimal and hex character references; an uppercase `A` now decodes (it used to become NUL) and an out-of-range code point is left as written (it used to raise `RangeError`). No gemspec change.
+
+- Internal: the private `Cli.format_amount` wrapper is gone; its four callers in `cli.rb` call `Cli::Money.format_amount` directly. No behaviour change.
+
 ## [0.12.0] - 2026-10-01
 
 - **Release note: the confidence check wants `portage-ucp-decision` 0.1.2.** `portage-ucp-decision` stays an optional install, not a dependency, but 0.1.2 is the version that rejects a malformed backend answer (see its changelog); the README says so.
@@ -785,7 +813,7 @@ pre-1.0, so APIs may still shift between minor versions.
 ## [0.7.4] - 2026-09-25
 
 - **`portage doctor` reports how it was installed, and warns when another
-  `portage` shadows it** (`docs/plans/homebrew-distribution.md` Phase 4).
+  `portage` shadows it** ([plan](https://github.com/tomtom87/Portage/blob/d51200f/docs/plans/homebrew-distribution.md) Phase 4).
   New findings, all offline and without shelling out to `brew`:
   - `install`: `homebrew` (with the Cellar keg) when this gem or its Ruby
     lives under `HOMEBREW_PREFIX/Cellar/portage/` (`$HOMEBREW_PREFIX`,

data/README.md

@@ -512,7 +512,7 @@ probes per run), throttled, with progress output. Sources:
 | --- | --- | --- |
 | `shopify_catalog` | Merchant origins and product identities, one query per top-level taxonomy node, from `catalog.shopify.com`'s open catalog | on |
 | `stores_file` | Your own `~/.portage/stores.yml` | on |
-| `browser` | Whatever `portage browser import` (below) already saved — this source itself never reads a browser | on, but yields nothing unless you've run `browser import` |
+| `browser` | Whatever `portage browser import` (below) already saved — this source itself never reads a browser | opt-in (`--sources browser`); yields nothing unless you've run `browser import` |
 | `wikidata` | Retailers'/brands' official sites via a public SPARQL query | opt-in (`--sources wikidata`) |
 | `webmcp_sweep` | Which WebMCP preset an origin matches, when a bridge is attached | opt-in, needs a bridge |
 | `storefront_products` | Each indexed Shopify store's own `/products.json`: title, brand, handle, URL, first image, options and variant ids, mapped through the UCP `Product` shape with price and availability dropped | opt-in (`--sources storefront_products`, or `index add URL --crawl`) |

data/lib/portage/cli/adapter_session.rb

@@ -0,0 +1,34 @@
+require "portage/ucp"
+require "portage/ucp/client"
+require_relative "homepage_fetch"
+require_relative "permissive_authenticator"
+
+module Portage
+  module Cli
+    # The own-store loopback fallback HandoffReconciler and PaymentMethods
+    # share, mirroring Buy's own (#adapter_flow): sniff the platform from
+    # the store's homepage and, when that platform's env vars are set,
+    # build its adapter and wrap it in a loopback client. A later process
+    # must not assume an earlier one's session or credentials still exist,
+    # only that the env vars are still set.
+    module AdapterSession
+      # @param route [Symbol] the Support::Connection route the homepage
+      #   fetch goes over (PaymentMethods passes :payment).
+      # @return [Portage::Ucp::Client::Session, nil] nil when the platform
+      #   isn't recognised, its env is incomplete, or anything fails.
+      def self.call(uri, route: :store)
+        body, headers = HomepageFetch.call(uri, route: route)
+        platform = body && Portage::Ucp::Resolver.detect_platform(body, headers)
+        return nil unless platform
+
+        env = Portage::Ucp::Resolver.env_for(platform)
+        return nil unless Portage::Ucp::Resolver.missing_env(platform, env).empty?
+
+        adapter = Portage::Ucp::Resolver.build_adapter(platform, env)
+        Portage::Ucp::Client.for_adapter(adapter, authenticator: PermissiveAuthenticator.new)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import/importer.rb

@@ -88,7 +88,7 @@ module Portage
         # @return [Hash] the proposal: counts, `kept` (domains to save) and
         #   `products` (only with include_product_pages) — or `error:` /
         #   `message:` when the browser's files couldn't be read (Safari
-        #   without Full Disk Access, no sqlite3, no profile found).
+        #   without Full Disk Access, a SQLite error, no plutil, no profile found).
         def plan(options)
           profiles = Profiles.locate(options.browser, root: options.root)
           return no_profile(options) if profiles.empty?

data/lib/portage/cli/browser_import/plist_xml.rb

@@ -1,4 +1,5 @@
 require "strscan"
+require "cgi/escape"
 
 module Portage
   module Cli
@@ -8,7 +9,8 @@ module Portage
       # form into XML. `plutil -convert json` would be simpler but refuses
       # any plist holding a <date> (Safari's Reading List entries carry
       # them), and a real XML library (rexml) isn't a runtime dependency of
-      # this gem — this is ~50 lines instead of a new one.
+      # this gem — this is ~50 lines instead of a new one. Entities go
+      # through CGI.unescapeHTML from `cgi/escape`, a default library.
       #
       # Dates, data and numbers come back as their raw text; bookmark
       # import only ever reads strings out of the tree.
@@ -16,7 +18,6 @@ module Portage
         class ParseError < StandardError; end
 
         SCALARS = "string|key|data|date|integer|real".freeze
-        ENTITIES = { "amp" => "&", "lt" => "<", "gt" => ">", "quot" => '"', "apos" => "'" }.freeze
 
         def self.parse(xml)
           scanner = StringScanner.new(xml.to_s)
@@ -31,7 +32,7 @@ module Portage
           elsif scanner.scan(%r{<(true|false)\s*/>}) then scanner[1] == "true"
           elsif scanner.scan("<dict>") then dict(scanner)
           elsif scanner.scan("<array>") then array(scanner)
-          elsif scanner.scan(%r{<(#{SCALARS})>(.*?)</\1>}m) then unescape(scanner[2])
+          elsif scanner.scan(%r{<(#{SCALARS})>(.*?)</\1>}m) then CGI.unescapeHTML(scanner[2])
           else raise ParseError, "unexpected plist content at #{scanner.pos}"
           end
         end
@@ -57,15 +58,7 @@ module Portage
           { "dict" => {}, "array" => [] }.fetch(tag, "")
         end
 
-        def self.unescape(text)
-          text.gsub(/&(#x?)?(\w+);/) do
-            if Regexp.last_match(1) == "#x" then [Regexp.last_match(2).to_i(16)].pack("U")
-            elsif Regexp.last_match(1) == "#" then [Regexp.last_match(2).to_i].pack("U")
-            else ENTITIES.fetch(Regexp.last_match(2), Regexp.last_match(0))
-            end
-          end
-        end
-        private_class_method :value, :dict, :array, :empty, :unescape
+        private_class_method :value, :dict, :array, :empty
       end
     end
   end

data/lib/portage/cli/browser_import/sqlite.rb

@@ -1,22 +1,21 @@
-require "json"
-require "open3"
+require "sqlite3"
 require "tmpdir"
 require "fileutils"
 
 module Portage
   module Cli
     module BrowserImport
-      # Reads a browser's SQLite history database without a native gem:
-      # the database (plus its `-wal` file, when the browser left one — it
-      # holds the most recent visits until the next checkpoint) is copied
-      # into a private tmpdir first, since a running browser holds it
-      # locked, and the copy is queried with the system `sqlite3` CLI in
-      # `-readonly -json` mode. The copy is deleted before this returns,
-      # success or not. The original file is only ever read by the copy.
+      # Reads a browser's SQLite history database: the database (plus its
+      # `-wal` file, when the browser left one — it holds the most recent
+      # visits until the next checkpoint) is copied into a private tmpdir
+      # first, since a running browser holds it locked, and the copy is
+      # queried read-only through the sqlite3 gem. The `-shm` index is not
+      # copied: SQLite rebuilds it from the `-wal` in the (writable) tmpdir.
+      # The copy is deleted before this returns, success or not. The
+      # original file is only ever read by the copy.
       #
-      # `sqlite3` ships with macOS and every mainstream Linux distro; when
-      # it's missing, Unavailable says so rather than falling back to
-      # anything else.
+      # Any SQLite error (a corrupt or non-SQLite file, a schema that
+      # doesn't match the query) is Unavailable, never a fallback.
       class Sqlite
         class Unavailable < StandardError; end
 
@@ -25,12 +24,6 @@ module Portage
         # around — see Importer's own handling.
         class PermissionDenied < StandardError; end
 
-        # @param command [String] the sqlite3 executable — injectable so a
-        #   spec can prove the missing-binary path without uninstalling it.
-        def initialize(command: "sqlite3")
-          @command = command
-        end
-
         # Copies `path` once and yields a query proc, so one copy serves
         # several queries (Firefox's history and bookmarks both live in
         # places.sqlite).
@@ -54,14 +47,15 @@ module Portage
         end
 
         def run(copy, sql)
-          out, err, status = Open3.capture3(@command, "-readonly", "-json", copy, sql)
-          raise Unavailable, "sqlite3 failed: #{err.strip}" unless status.success?
-
-          text = out.dup.force_encoding("UTF-8").scrub
-          text.strip.empty? ? [] : JSON.parse(text)
-        rescue Errno::ENOENT
-          raise Unavailable, "the sqlite3 command isn't installed (it ships with macOS and most Linux distros)"
+          db = SQLite3::Database.new(copy, readonly: true, results_as_hash: true)
+          db.execute(sql).map { |row| row.transform_values { |v| v.is_a?(String) ? scrub(v) : v } }
+        rescue SQLite3::Exception => e
+          raise Unavailable, "SQLite error: #{e.message}"
+        ensure
+          db&.close
         end
+
+        def scrub(text) = text.dup.force_encoding("UTF-8").scrub
       end
     end
   end

data/lib/portage/cli/browser_profile/cdp.rb

@@ -34,15 +34,6 @@ module Portage
           get(host, port, "/json/new?#{URI.encode_www_form_component(url)}", method: :put)
         end
 
-        # `/json/close/<id>` answers plain text ("Target is closing"), not
-        # JSON — checked by success status only, never parsed as JSON.
-        def self.close_tab(port:, id:, host: HOST)
-          uri = URI("http://#{host}:#{port}/json/close/#{id}")
-          fetch(uri, :get).is_a?(Net::HTTPSuccess)
-        rescue StandardError
-          false
-        end
-
         def self.get(host, port, path, method: :get)
           uri = URI("http://#{host}:#{port}#{path}")
           response = fetch(uri, method)

data/lib/portage/cli/buy.rb

@@ -1075,8 +1075,13 @@ module Portage
         return quote_changed_report(source, products, checkout, warnings) if quote_exceeded?(checkout)
 
         escalation = decide_escalation(checkout, warnings)
+        # A dry run never hands off, so an escalating checkout is still just
+        # a priced dry run: reporting it as `requires_escalation` saved no
+        # quote, and the CLI's approval gate had nothing to approve
+        # (design-log §55). The real run after approval escalates and hands
+        # off, which is where the pending record gets written.
+        return dry_run_report(source, products, checkout, warnings, escalates: escalation[:escalate]) if @dry_run
         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_checkout_report(source, products, checkout, warnings) if force_handoff
         return confirmation_needed_report(source, products, checkout, warnings) unless confirmed?
 
@@ -1582,9 +1587,13 @@ module Portage
       # `warnings` here are #reconcile_checkout's mismatches, which a real
       # run of the same checkout stops on — so the report says so up front,
       # before anyone approves a quote for it.
-      def dry_run_report(source, products, checkout, warnings = [])
+      def dry_run_report(source, products, checkout, warnings = [], escalates: false)
         message = "Dry run — checkout created but not completed."
         extra = {}
+        if escalates
+          message += " The store needs the shopper to finish this checkout, so a real run hands it off."
+          extra[:handoff_expected] = true
+        end
         if warnings.any?
           message += " It doesn't match the request (#{warnings.join(' ')}), so a real purchase would stop " \
                      "with checkout_mismatch."

data/lib/portage/cli/compare.rb

@@ -57,12 +57,13 @@ module Portage
         return report(message: "#{uri.host} is hand-off only — #{HandoffOnly::LEGAL_NOTICE}") \
           if @handoff_only.host?(uri.host)
 
-        session = discover(origin_of(uri))
-        return report(message: "#{origin_of(uri)} doesn't speak UCP.") unless session
+        origin = OfferSources.origin_of(uri.to_s)
+        session = discover(origin)
+        return report(message: "#{origin} doesn't speak UCP.") unless session
 
         wrapped = session.get_product(product_id: @origin_product_id)
         product = wrapped.is_a?(Hash) ? wrapped["product"] : nil
-        return report(message: "Product #{@origin_product_id.inspect} not found at #{origin_of(uri)}.") unless product
+        return report(message: "Product #{@origin_product_id.inspect} not found at #{origin}.") unless product
 
         { host: uri.host, title: field(product, "title"), product: product }
       end

data/lib/portage/cli/find.rb

@@ -148,7 +148,8 @@ module Portage
         existing = seen[uri.host]
         return if existing && !upgradable?(existing, uri)
 
-        seen[uri.host] = { origin: origin_of(uri), source: existing ? existing[:source] : backend.name,
+        seen[uri.host] = { origin: OfferSources.origin_of(uri.to_s),
+                           source: existing ? existing[:source] : backend.name,
                            handoff_only: @handoff_only.host?(uri.host) }
       end
 
@@ -209,13 +210,6 @@ module Portage
         nil
       end
 
-      # Collapse every deep link a backend returns onto the origin, since
-      # that's the only thing `/.well-known/ucp` hangs off.
-      def origin_of(uri)
-        port = uri.port == uri.default_port ? "" : ":#{uri.port}"
-        "#{uri.scheme}://#{uri.host}#{port}"
-      end
-
       # --- Step 2: keep the ones that actually speak UCP ---
 
       # A cached *miss* is the only verdict that saves work here — a cached hit

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

@@ -178,7 +178,7 @@ module Portage
         end
 
         # Raw uncompressed EC point encoding: 0x04 || x (32 bytes) || y (32
-        # bytes) for P-256 — see Portage::Ucp::Security::Signature::CURVES,
+        # bytes) for P-256 — see Portage::Ucp::Security::EcJwk::CURVES,
         # which decodes the same layout in reverse when verifying.
         def coordinates(pkey)
           octets = pkey.public_key.to_bn.to_s(2)

data/lib/portage/cli/handoff_agents.rb

@@ -1,10 +1,9 @@
 require "json"
-require "net/http"
 require "open3"
 require "timeout"
 require "uri"
-require "portage/ucp/support/connection"
 require_relative "config"
+require_relative "notifier"
 require_relative "user_agent"
 
 module Portage
@@ -150,12 +149,13 @@ module Portage
         def excerpt(stderr, stdout) = (stderr.to_s.empty? ? stdout.to_s : stderr.to_s).strip[0, BODY_EXCERPT]
       end
 
-      # POSTs the payload as JSON — https only, same connection helper and
-      # short timeout as Notifier, failures swallowed into the return
-      # value rather than raised.
+      # POSTs the payload as JSON — https only, through Notifier.post_json
+      # (same connection helper as --notify-webhook, with a longer timeout),
+      # failures swallowed into the return value rather than raised. Never
+      # Notifier#call itself: that falls back to PORTAGE_NOTIFY_WEBHOOK_URL
+      # or config, so a blank agent URL would post to the global webhook.
       class Webhook
         TIMEOUT = 10
-        BODY_EXCERPT = 200
 
         def initialize(url)
           @url = url.to_s
@@ -164,21 +164,7 @@ module Portage
         def call(payload)
           return "agent webhook must be https" unless @url.start_with?("https://")
 
-          response = post(URI(@url), JSON.generate(payload))
-          return nil if response.is_a?(Net::HTTPSuccess)
-
-          "agent webhook answered #{response.code}: #{response.body.to_s[0, BODY_EXCERPT]}"
-        rescue StandardError => e
-          "agent webhook POST failed: #{e.message}"
-        end
-
-        private
-
-        def post(uri, body)
-          Portage::Ucp::Support::Connection.start(uri, route: :notify, open_timeout: TIMEOUT,
-                                                       read_timeout: TIMEOUT) do |http|
-            http.post(uri.request_uri, body, UserAgent.headers.merge("Content-Type" => "application/json"))
-          end
+          Notifier.post_json(@url, payload, timeout: TIMEOUT, label: "agent webhook")
         end
       end
     end

data/lib/portage/cli/handoff_reconciler.rb

@@ -4,10 +4,10 @@ require "portage/ucp"
 require "portage/ucp/client"
 require "portage/ucp/journal"
 require_relative "user_agent"
-require_relative "homepage_fetch"
+require_relative "agent_profile_url"
+require_relative "adapter_session"
 require_relative "handoff_spend_mode"
 require_relative "reconcile_notifier"
-require_relative "permissive_authenticator"
 require_relative "handoff_only"
 require_relative "handoff_reconciler/wire_adapters"
 
@@ -93,7 +93,7 @@ module Portage
 
       def reconcile(record)
         session = reconnect(record["store_url"])
-        checkout = session.get_checkout(checkout_id: record["checkout_id"])
+        checkout = session.get_checkout(checkout_id: record["checkout_id"], meta: agent_meta)
         settle_from_checkout(record, checkout)
       rescue StandardError => e
         # A reconnect failure (no automated path back into the store) and a
@@ -103,7 +103,9 @@ module Portage
         # buys nothing here: either way, this run learned nothing new about
         # whether the shopper paid, and the record's own `expires_at` is
         # still the only thing allowed to turn that into a settle.
-        settle_not_found(record, note: e.message)
+        # ServerError#summary: Shopify answers a gone checkout with its whole
+        # UCP envelope as the message; the note only needs its messages[].
+        settle_not_found(record, note: e.respond_to?(:summary) ? e.summary : e.message)
       end
 
       def settle_from_checkout(record, checkout)
@@ -177,7 +179,7 @@ module Portage
         return nil unless order && order["id"]
 
         session = reconnect(record["store_url"])
-        order_wire = session.get_order(order_id: order["id"])
+        order_wire = session.get_order(order_id: order["id"], meta: agent_meta)
         return order["id"] unless order_wire
 
         @order_ledger.record(idempotency_key: record["idempotency_key"], order: WireOrder.new(order_wire))
@@ -230,34 +232,20 @@ module Portage
         raise ReconnectError, "#{uri.host} is hand-off only — never reconciled automatically" \
           if @handoff_only.host?(uri.host)
 
-        native_session(uri) || adapter_session(uri) ||
+        native_session(uri) || AdapterSession.call(uri) ||
           raise(ReconnectError, "no automated path back into #{store_url}")
       end
 
+      # Same `meta.ucp-agent.profile` Buy#agent_meta sends: a real UCP
+      # server rejects any call without it, so leaving it off made every
+      # native reconcile fail as "not found" (design-log §55).
+      def agent_meta = { agent_profile: AgentProfileUrl.resolve }
+
       def native_session(uri)
         Portage::Ucp::Client.discover(uri.to_s, headers: UserAgent.headers)
       rescue Portage::Ucp::Client::DiscoveryError
         nil
       end
-
-      # Mirrors Buy's own own-store loopback fallback (#adapter_flow) — a
-      # later process re-discovers the platform from the homepage the same
-      # way, and must not assume the original process's session or
-      # credentials still exist, only that this platform's env vars are
-      # still set (see the plan's non-negotiable constraint).
-      def adapter_session(uri)
-        body, headers = HomepageFetch.call(uri)
-        platform = body && Portage::Ucp::Resolver.detect_platform(body, headers)
-        return nil unless platform
-
-        env = Portage::Ucp::Resolver.env_for(platform)
-        return nil unless Portage::Ucp::Resolver.missing_env(platform, env).empty?
-
-        adapter = Portage::Ucp::Resolver.build_adapter(platform, env)
-        Portage::Ucp::Client.for_adapter(adapter, authenticator: PermissiveAuthenticator.new)
-      rescue StandardError
-        nil
-      end
     end
   end
 end

data/lib/portage/cli/homepage_fetch.rb

@@ -13,21 +13,23 @@ module Portage
     module HomepageFetch
       REDIRECT_LIMIT = 5
 
+      # @param route [Symbol] Support::Connection route for every hop,
+      #   redirects included (:store, or :payment for PaymentMethods).
       # @return [Array(String, Hash), Array(nil, Hash)] the body and response
       #   headers, or [nil, {}] on any failure/redirect exhaustion — same
       #   "no automated path, not a crash" posture as the rest of the buy
       #   flow.
-      def self.call(uri, limit: REDIRECT_LIMIT)
+      def self.call(uri, limit: REDIRECT_LIMIT, route: :store)
         return [nil, {}] if limit.zero?
 
-        response = Portage::Ucp::Support::Connection.start(uri, route: :store, open_timeout: 5,
+        response = Portage::Ucp::Support::Connection.start(uri, route: route, open_timeout: 5,
                                                                 read_timeout: 5) do |http|
           http.get(uri.request_uri, UserAgent.headers)
         end
 
         case response
         when Net::HTTPRedirection
-          call(URI.join(uri, response["location"]), limit: limit - 1)
+          call(URI.join(uri, response["location"]), limit: limit - 1, route: route)
         when Net::HTTPSuccess
           [response.body, response.to_hash]
         else

data/lib/portage/cli/index/builder.rb

@@ -5,6 +5,7 @@ require_relative "../user_agent"
 require_relative "../classifier"
 require_relative "../probe_cache"
 require_relative "../handoff_only"
+require_relative "../offer_sources"
 require_relative "store"
 require_relative "product_store"
 require_relative "known_cache"
@@ -103,7 +104,7 @@ module Portage
         # Opt-in: a crawl is up to 21 more requests and 20s of pauses, where
         # a plain add is one probe.
         def add(url, crawl: false)
-          origin = origin_of(url)
+          origin = OfferSources.origin_of(url)
           return { added: false, message: "Not a valid http(s) URL: #{url}" } unless origin
           return store_manual_handoff_only(origin) if handoff_only_origin?(origin)
 
@@ -356,16 +357,6 @@ module Portage
         def progress(message)
           @out&.puts(message)
         end
-
-        def origin_of(url)
-          uri = URI.parse(url.to_s)
-          return nil unless uri.host && uri.scheme.to_s.start_with?("http")
-
-          port = uri.port == uri.default_port ? "" : ":#{uri.port}"
-          "#{uri.scheme}://#{uri.host}#{port}"
-        rescue URI::InvalidURIError
-          nil
-        end
       end
     end
   end

data/lib/portage/cli/index/known_cache.rb

@@ -5,7 +5,6 @@ require "fileutils"
 require "timeout"
 require "portage/ucp/support/connection"
 
-require_relative "../known_stores_url"
 require_relative "../user_agent"
 
 module Portage
@@ -32,6 +31,14 @@ module Portage
         STORES_PATH = File.join(Dir.home, ".portage", "index", "known-stores.json").freeze
         PRODUCTS_PATH = File.join(Dir.home, ".portage", "index", "known-products.json").freeze
 
+        # Published on the same jsdelivr `@main` channel AgentProfileUrl
+        # uses for the agent profile: free GitHub, no Actions, so a new
+        # entry reaches every install on its next refresh as soon as a PR
+        # merges, with no gem/brew release to wait on.
+        BASE_URL = "https://cdn.jsdelivr.net/gh/tomtom87/Portage@main/portage-cli/known-stores".freeze
+        STORES_URL = "#{BASE_URL}/stores.json".freeze
+        PRODUCTS_URL = "#{BASE_URL}/products.json".freeze
+
         STALE_AFTER = 7 * 24 * 60 * 60
         TIMEOUT = 5
 
@@ -44,7 +51,7 @@ module Portage
         FORBIDDEN_FIELDS = %w[price amount stock].freeze
 
         def initialize(stores_path: STORES_PATH, products_path: PRODUCTS_PATH,
-                       stores_url: KnownStoresUrl::STORES, products_url: KnownStoresUrl::PRODUCTS)
+                       stores_url: STORES_URL, products_url: PRODUCTS_URL)
           @stores_path = stores_path
           @products_path = products_path
           @stores_url = stores_url

data/lib/portage/cli/index/sources/stores_file.rb

@@ -1,6 +1,7 @@
 require "uri"
 
 require_relative "../../search_backends"
+require_relative "../../offer_sources"
 
 module Portage
   module Cli
@@ -36,21 +37,11 @@ module Portage
           private
 
           def sighting_for(url)
-            origin = origin_of(url)
+            origin = OfferSources.origin_of(url)
             return nil unless origin
 
             { origin: origin, url: nil, title: nil, brand: nil, gtin: nil }
           end
-
-          def origin_of(url)
-            uri = URI.parse(url.to_s)
-            return nil unless uri.host && uri.scheme.to_s.start_with?("http")
-
-            port = uri.port == uri.default_port ? "" : ":#{uri.port}"
-            "#{uri.scheme}://#{uri.host}#{port}"
-          rescue URI::InvalidURIError
-            nil
-          end
         end
       end
     end

data/lib/portage/cli/index/sources/wikidata.rb

@@ -5,6 +5,7 @@ require "timeout"
 require "portage/ucp/support/connection"
 
 require_relative "../../user_agent"
+require_relative "../../offer_sources"
 
 module Portage
   module Cli
@@ -73,21 +74,11 @@ module Portage
 
           def sighting_for(row)
             url = row.dig("website", "value")
-            origin = origin_of(url)
+            origin = OfferSources.origin_of(url)
             return nil unless origin
 
             { origin: origin, url: url, title: nil, brand: row.dig("itemLabel", "value"), gtin: nil }
           end
-
-          def origin_of(url)
-            uri = URI.parse(url.to_s)
-            return nil unless uri.host && uri.scheme.to_s.start_with?("http")
-
-            port = uri.port == uri.default_port ? "" : ":#{uri.port}"
-            "#{uri.scheme}://#{uri.host}#{port}"
-          rescue URI::InvalidURIError
-            nil
-          end
         end
       end
     end

data/lib/portage/cli/install_doctor.rb

@@ -3,7 +3,8 @@ require_relative "version"
 
 module Portage
   module Cli
-    # Phase 4 of docs/plans/homebrew-distribution.md's `doctor` checks: how
+    # Phase 4 of homebrew-distribution.md's `doctor` checks (see
+    # https://github.com/tomtom87/Portage/blob/d51200f/docs/plans/homebrew-distribution.md): how
     # this copy of portage-cli was installed (Homebrew formula or plain
     # `gem install`), which Ruby it runs on, which first-party adapter gems
     # it can load, and whether the `portage` a shell would actually run is