ace-git-worktree 0.22.1 → 0.24.0

data/lib/ace/git/worktree/molecules/cleanup_pr_resolver.rb

@@ -2,116 +2,173 @@
 
 require "json"
 require "open3"
-require "ace/git/molecules/pr_metadata_fetcher"
+require "ace/git"
 
 module Ace
   module Git
     module Worktree
       module Molecules
-        # Resolves PR evidence for candidate branches to prove safe squash-merge cleanup.
+        # Resolves PR evidence for candidate branches through the registered
+        # forge provider to prove safe merge cleanup.
+        #
+        # Only confirmed remote merge evidence (:merged) can prove removal;
+        # object states (:no_pr, :open, :closed_unmerged) and transport
+        # failures (:offline, :authentication_error, :malformed) always
+        # retain the candidate. Local ancestry proof is handled by the
+        # reporter before this resolver is consulted.
         class CleanupPrResolver
-          def initialize(target:, target_sha:, offline: false)
+          # @param target [String] base ref the PR must have targeted
+          # @param target_sha [String] commit SHA of the target
+          # @param offline [Boolean] skip provider evidence entirely
+          # @param server_name [String, nil] explicit server selection
+          # @param use_default [Boolean] resolve the configured default server
+          # @param remote_name [String, nil] remote used for fallback resolution
+          # @param timeout [Integer, nil] provider timeout
+          # @param runner [Proc, nil] injectable provider runner (tests)
+          def initialize(target:, target_sha:, offline: false, server_name: nil, use_default: false,
+            remote_name: nil, timeout: nil, runner: nil)
             @target = target
             @target_sha = target_sha
             @offline = offline
-            
-            # Cache gh availability to avoid repeated checks
-            @gh_available = Ace::Git::Molecules::PrMetadataFetcher.gh_installed? && 
-                            Ace::Git::Molecules::PrMetadataFetcher.gh_authenticated?
+            @selection = {server_name: server_name, use_default: use_default, remote_name: remote_name}
+            @timeout = timeout
+            @runner = runner
           end
 
-          # Classify a candidate branch with GitHub PR evidence.
+          # @return [Ace::Git::ResolvedServer, nil] the server resolved for
+          #   provider evidence; nil when unresolvable (local proof only)
+          def resolved_server
+            resolve_provider
+            @resolved_server
+          end
+
+          # Classify a candidate branch with provider PR evidence.
           #
-          # @param branch [String] The branch name (e.g. "feature")
-          # @param candidate_sha [String] The commit SHA of the candidate
-          # @return [Hash] Proof classification result
+          # @param branch [String] the branch name (e.g. "feature")
+          # @param candidate_sha [String] the commit SHA of the candidate
+          # @return [Hash] proof classification; :status is one of
+          #   Ace::Git::CLEANUP_PROOF_STATUSES
           def classify(branch, candidate_sha)
-            return offline_result unless @gh_available && !@offline
-
-            prs = fetch_merged_prs_for_branch(branch)
-            return unproven_result if prs.nil? || prs.empty?
-
-            # Find a PR that targets the configured base and is actually reachable
-            valid_pr = prs.find do |pr|
-              pr["baseRefName"] == @target && 
-              pr["state"] == "MERGED" && 
-              pr["mergeCommit"] && 
-              pr["mergeCommit"]["oid"] &&
-              ancestor?(pr["mergeCommit"]["oid"], @target_sha)
-            end
+            return unproven_result(:no_pr, "provider_disabled") if @offline
 
-            return ambiguous_result(prs) if prs.length > 1 && !valid_pr
-            return unproven_result unless valid_pr
+            evidence = fetch_merged_evidence(branch)
+            return failure_result(evidence) if evidence.is_a?(Hash) # transport failure marker
 
-            merge_commit_sha = valid_pr["mergeCommit"]["oid"]
-            pr_head_sha = valid_pr["headRefOid"]
+            return unproven_result(:no_pr) unless evidence
+            return unproven_result(:open) if evidence.state == :open
+            return unproven_result(:closed_unmerged) if evidence.state == :closed
+            return unproven_result(:no_pr, "state_unavailable") unless evidence.state == :merged
+            return unproven_result(:merged, "merge_commit_unavailable") unless evidence.merge_commit_sha
+            return unproven_result(:merged, "merge_commit_unreachable") unless ancestor?(evidence.merge_commit_sha, @target_sha)
+
+            merge_commit_sha = evidence.merge_commit_sha
+            pr_head_sha = evidence.head_sha
 
             if candidate_sha == pr_head_sha
-              {
-                proof: "exact_merged_pr_head",
-                pr: valid_pr["number"],
-                candidate_head: candidate_sha,
-                merged_head: pr_head_sha,
-                merge_commit: merge_commit_sha,
-                target_reachable: true,
-                path_type_mode_match: true,
-                provider_status: "available",
-                action: "remove"
-              }
+              proof_result(evidence, "exact_merged_pr_head", candidate_sha, pr_head_sha, merge_commit_sha)
             elsif patch_equivalent?(candidate_sha, merge_commit_sha)
-              {
-                proof: "stable_patch_equivalence",
-                pr: valid_pr["number"],
-                candidate_head: candidate_sha,
-                merged_head: pr_head_sha,
-                merge_commit: merge_commit_sha,
-                target_reachable: true,
-                path_type_mode_match: true,
-                provider_status: "available",
-                action: "remove"
-              }
+              proof_result(evidence, "stable_patch_equivalence", candidate_sha, pr_head_sha, merge_commit_sha)
             else
               {
-                proof: "none",
-                pr: valid_pr["number"],
+                status: :merged,
+                proof: nil,
+                pr: evidence.number,
+                pr_url: evidence.url,
                 candidate_head: candidate_sha,
                 merged_head: pr_head_sha,
                 merge_commit: merge_commit_sha,
                 target_reachable: true,
-                path_type_mode_match: false,
                 provider_status: "available",
                 action: "retain",
                 retention_reason: "patch_mismatch"
               }
             end
-          rescue Ace::Git::GhNotInstalledError, Ace::Git::GhAuthenticationError, Ace::Git::TimeoutError
-            # Provider failure degradation
-            offline_result("unavailable")
           end
 
           private
 
-          def fetch_merged_prs_for_branch(branch)
-            # Use `gh pr list --head <branch> --state merged` to find the exact PR
-            cmd = [
-              "gh", "pr", "list", "--state", "merged", "--head", branch,
-              "--json", "number,state,headRefOid,mergeCommit,baseRefName"
-            ]
-            
-            # Using Open3 directly to avoid circular dependencies if we don't want to augment ace-git too heavily for just this
-            # but we can rely on LC_ALL=C for safety.
-            env = {"LC_ALL" => "C"}
-            out, err, status = Open3.capture3(env, *cmd)
-            
-            return nil unless status.success?
-            
-            JSON.parse(out)
-          rescue JSON::ParserError, Errno::ENOENT
-            nil
+          # Fetch the merged PR evidence for a branch, or a failure marker
+          # hash {:failure_status => ...} on classified transport failures.
+          def fetch_merged_evidence(branch)
+            provider = resolve_provider
+            return {failure_status: :offline} unless provider
+
+            provider.pull_request_for_branch(branch: branch)
+          rescue Ace::Git::ProviderAuthenticationError
+            {failure_status: :authentication_error}
+          rescue Ace::Git::ProviderMalformedOutputError
+            {failure_status: :malformed}
+          rescue Ace::Git::Error
+            {failure_status: :offline}
+          end
+
+          # Resolve the provider lazily, once per resolver. Unresolvable
+          # server selection (no config, ambiguous remote, missing provider)
+          # means no provider evidence is available.
+          def resolve_provider
+            return @provider if defined?(@provider)
+
+            @provider = begin
+              server = Ace::Git::ServerRegistry.resolve_for(**@selection)
+              @resolved_server = server
+              Ace::Git::Providers.for(server, timeout: @timeout, runner: @runner)
+            rescue Ace::Git::Error
+              @resolved_server = nil
+              nil
+            end
+          end
+
+          def proof_result(evidence, proof, candidate_sha, pr_head_sha, merge_commit_sha)
+            {
+              status: :merged,
+              proof: proof,
+              pr: evidence.number,
+              pr_url: evidence.url,
+              candidate_head: candidate_sha,
+              merged_head: pr_head_sha,
+              merge_commit: merge_commit_sha,
+              target_reachable: true,
+              provider_status: "available",
+              action: "remove",
+              retention_reason: nil
+            }
+          end
+
+          def unproven_result(status, reason = "ancestry_unproven")
+            {
+              status: status,
+              proof: nil,
+              pr: nil,
+              pr_url: nil,
+              candidate_head: nil,
+              merged_head: nil,
+              merge_commit: nil,
+              target_reachable: "unknown",
+              provider_status: "available",
+              action: "retain",
+              retention_reason: reason
+            }
+          end
+
+          def failure_result(marker)
+            status = marker[:failure_status]
+            {
+              status: status,
+              proof: nil,
+              pr: nil,
+              pr_url: nil,
+              candidate_head: nil,
+              merged_head: nil,
+              merge_commit: nil,
+              target_reachable: "unknown",
+              provider_status: status.to_s,
+              action: "retain",
+              retention_reason: "provider_evidence_unavailable"
+            }
           end
 
           def ancestor?(candidate, target)
-            out, status = Open3.capture2("git", "merge-base", "--is-ancestor", candidate, target)
+            _out, status = Open3.capture2("git", "merge-base", "--is-ancestor", candidate, target)
             status.success?
           end
 
@@ -121,7 +178,7 @@ module Ace
             base, status = Open3.capture2("git", "merge-base", candidate_sha, @target_sha)
             return false unless status.success?
             base = base.strip
-            
+
             # Candidate inventory: path, type, mode changes
             cand_inv = tree_diff_inventory(base, candidate_sha)
             return false unless cand_inv
@@ -135,9 +192,8 @@ module Ace
           end
 
           def tree_diff_inventory(tree_a, tree_b)
-            # git diff-tree -r --name-status or raw mode
-            # using raw mode to get exact mode and type
-            # :100644 100644 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0000000000000000000000000000000000000000 M  file
+            # git diff-tree -r raw mode carries exact mode and type information
+            # :100644 100644 e69de29... 000000... M  file
             out, status = Open3.capture2("git", "diff-tree", "-r", "--no-commit-id", tree_a, tree_b)
             return nil unless status.success?
 
@@ -145,66 +201,19 @@ module Ace
             out.each_line do |line|
               # Format: :src_mode dst_mode src_sha dst_sha status\tpath
               parts = line.strip.split("\t", 2)
+              next if parts.length < 2
+
               meta = parts[0].split(" ")
               path = parts[1]
-              
-              dst_mode = meta[1]
-              dst_sha = meta[3]
-              status_char = meta[4]
-              
+
               inventory[path] = {
-                mode: dst_mode,
-                sha: dst_sha,
-                status: status_char[0] # handle R100 etc by taking first char
+                mode: meta[1],
+                sha: meta[3],
+                status: meta[4][0] # handle R100 etc by taking first char
               }
             end
-            
-            inventory
-          end
-
-          def offline_result(status = "offline")
-            {
-              proof: "none",
-              pr: nil,
-              candidate_head: nil,
-              merged_head: nil,
-              merge_commit: nil,
-              target_reachable: "unknown",
-              path_type_mode_match: "unknown",
-              provider_status: status,
-              action: "retain",
-              retention_reason: "ancestry_unproven"
-            }
-          end
 
-          def unproven_result
-            {
-              proof: "none",
-              pr: nil,
-              candidate_head: nil,
-              merged_head: nil,
-              merge_commit: nil,
-              target_reachable: "unknown",
-              path_type_mode_match: "unknown",
-              provider_status: "available",
-              action: "retain",
-              retention_reason: "ancestry_unproven"
-            }
-          end
-
-          def ambiguous_result(prs)
-            {
-              proof: "none",
-              pr: nil,
-              candidate_head: nil,
-              merged_head: nil,
-              merge_commit: nil,
-              target_reachable: "unknown",
-              path_type_mode_match: "unknown",
-              provider_status: "ambiguous",
-              action: "retain",
-              retention_reason: "ambiguous_prs"
-            }
+            inventory
           end
         end
       end

data/lib/ace/git/worktree/molecules/cleanup_reporter.rb

@@ -19,12 +19,22 @@ module Ace
           SCHEMA_VERSION = "1.0"
 
           # @param target [String] Target ref (e.g. "main", "origin/main")
-          # @param remote [String] Remote name (e.g. "origin")
+          # @param remote [String] Remote name (e.g. "origin"); identifies the
+          #   local Git remote, never the forge
           # @param offline [Boolean] Skip remote refresh
-          def initialize(target:, remote: "origin", offline: false)
+          # @param server_name [String, nil] explicit forge server selection
+          # @param use_default [Boolean] resolve the configured default server
+          # @param remote_name [String, nil] remote used for fallback resolution
+          # @param timeout [Integer, nil] provider timeout
+          # @param runner [Proc, nil] injectable provider runner (tests)
+          def initialize(target:, remote: "origin", offline: false, server_name: nil, use_default: false,
+            remote_name: nil, timeout: nil, runner: nil)
             @target = target
             @remote = remote
             @offline = offline
+            @selection = {server_name: server_name, use_default: use_default, remote_name: remote_name}
+            @timeout = timeout
+            @runner = runner
           end
 
           # Build complete cleanup report.
@@ -46,7 +56,11 @@ module Ace
             local_refs = inventory_local_refs
             remote_refs = inventory_remote_refs
 
-            pr_resolver = CleanupPrResolver.new(target: @target, target_sha: target_sha, offline: @offline)
+            pr_resolver = CleanupPrResolver.new(
+              target: @target, target_sha: target_sha, offline: @offline,
+              server_name: @selection[:server_name], use_default: @selection[:use_default],
+              remote_name: @selection[:remote_name], timeout: @timeout, runner: @runner
+            )
 
             # Classify each item
             classify_worktrees(worktrees, target_sha, pr_resolver)
@@ -56,8 +70,12 @@ module Ace
             # Build ordered action plan
             actions = build_action_plan(worktrees, local_refs, remote_refs)
 
-            # Compute canonical digest
-            plan_digest = compute_plan_digest(worktrees, local_refs, remote_refs, actions, target_sha)
+            # The resolved server identity binds provider proof to the plan;
+            # changed server configuration invalidates approval.
+            server = server_identity_hash(pr_resolver)
+
+            # Compute canonical digest (server/PR/head evidence included)
+            plan_digest = compute_plan_digest(worktrees, local_refs, remote_refs, actions, target_sha, server)
 
             {
               success: true,
@@ -65,6 +83,7 @@ module Ace
               repository: common_dir,
               target: {ref: @target, sha: target_sha},
               remote: {name: @remote, sha: remote_sha},
+              server: server,
               refresh: @offline ? {status: "offline"} : (refresh_result || {status: "skipped"}),
               worktrees: worktrees,
               local_refs: local_refs,
@@ -286,7 +305,7 @@ module Ace
                 wt[:ancestry] = "ancestor"
                 wt[:action] = "remove"
               else
-                # Try GitHub PR evidence
+                # Try provider PR evidence
                 proof_result = pr_resolver.classify(wt[:branch], wt[:sha])
                 if proof_result[:action] == "remove"
                   wt[:ancestry] = proof_result[:proof]
@@ -311,7 +330,7 @@ module Ace
                 ref[:ancestry] = "ancestor"
                 ref[:action] = "remove"
               else
-                # Try GitHub PR evidence
+                # Try provider PR evidence
                 # Only local refs and remote-tracking refs have meaningful branch names for PR lookup
                 branch_name = kind == "remote" ? ref[:short_name] : ref[:name]
                 proof_result = pr_resolver.classify(branch_name, ref[:sha])
@@ -378,17 +397,36 @@ module Ace
 
           # --- Canonical digest ---
 
-          def compute_plan_digest(worktrees, local_refs, remote_refs, actions, target_sha)
+          # Resolved server identity for the report/digest; nil when no
+          # provider was resolvable (local ancestry proof only).
+          def server_identity_hash(pr_resolver)
+            server = pr_resolver.resolved_server
+            return nil unless server
+
+            {name: server.name, provider: server.provider.to_s, url: server.url}
+          end
+
+          def compute_plan_digest(worktrees, local_refs, remote_refs, actions, target_sha, server)
             canonical = {
+              schema_version: SCHEMA_VERSION,
               target_sha: target_sha,
-              worktrees: worktrees.sort_by { |wt| wt[:path] }.map { |wt| [wt[:path], wt[:sha], wt[:action]] },
-              local_refs: local_refs.sort_by { |r| r[:name] }.map { |r| [r[:name], r[:sha], r[:action]] },
-              remote_refs: remote_refs.sort_by { |r| r[:name] }.map { |r| [r[:name], r[:sha], r[:action]] },
+              server: server,
+              worktrees: worktrees.sort_by { |wt| wt[:path] }.map { |wt| proof_tuple(wt[:path], wt) },
+              local_refs: local_refs.sort_by { |r| r[:name] }.map { |r| proof_tuple(r[:name], r) },
+              remote_refs: remote_refs.sort_by { |r| r[:name] }.map { |r| proof_tuple(r[:name], r) },
               actions: actions.map { |a| [a[:type], a[:target], a[:sha]] }
             }
 
             Digest::SHA256.hexdigest(JSON.generate(canonical))
           end
+
+          # One canonical entry per item: identity, decision, and the full
+          # provider proof that justified it.
+          def proof_tuple(identity, item)
+            proof = item[:pr_proof]
+            [identity, item[:sha], item[:action], item[:ancestry],
+             proof ? [proof[:status], proof[:pr], proof[:merged_head], proof[:merge_commit]] : nil]
+          end
         end
       end
     end

data/lib/ace/git/worktree/molecules/pull_request_checkout_preparer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "ace/git"
+
+module Ace
+  module Git
+    module Worktree
+      module Molecules
+        # Fetches the exact source repository/ref declared by PR evidence and
+        # proves the fetched commit before any worktree is created.
+        #
+        # Canonical-repository and fork source URLs are equally valid: the
+        # fetch goes through a matching local remote when one exists, and by
+        # explicit URL otherwise (no remote ref is created for URL fetches).
+        class PullRequestCheckoutPreparer
+          DEFAULT_TIMEOUT = 60
+
+          # @param timeout [Integer] git command timeout in seconds
+          def initialize(timeout: DEFAULT_TIMEOUT)
+            @timeout = timeout
+          end
+
+          # Fetch the declared source ref and verify its SHA against the
+          # evidence head.
+          #
+          # @param evidence [Ace::Git::ProviderPullRequest] normalized PR evidence
+          # @return [Hash] {success:, local_ref:, sha:, remote_tracking:, error:}
+          #   `local_ref` is the exact verified commit SHA (immutable), safe
+          #   for `git worktree add` even if later fetches move FETCH_HEAD.
+          def prepare(evidence)
+            head_url = evidence.head_repository_url
+            head_ref = evidence.head_ref
+            return error_result("PR evidence is missing the source repository URL") if head_url.nil? || head_url.empty?
+            return error_result("PR evidence is missing the source branch") if head_ref.nil? || head_ref.empty?
+            return error_result("PR evidence is missing the exact head SHA") unless evidence.head_sha
+
+            local_remote = matching_local_remote(head_url)
+            fetch_source = local_remote || head_url
+            fetch_desc = "#{head_url}@#{head_ref}"
+
+            fetch_result = Ace::Git::Worktree::Atoms::GitCommand.execute(
+              "fetch", fetch_source, head_ref, timeout: @timeout
+            )
+            return error_result("Failed to fetch #{fetch_desc}: #{fetch_result[:error]}") unless fetch_result[:success]
+
+            sha = resolve_fetch_head
+            return error_result("Cannot resolve fetched commit for #{fetch_desc}") unless sha
+
+            if sha != evidence.head_sha
+              return error_result(
+                "Fetched head #{sha} does not match PR evidence head #{evidence.head_sha} " \
+                "(#{head_url}@#{head_ref}); the PR head moved since the evidence was captured"
+              )
+            end
+
+            {
+              success: true,
+              # The immutable verified SHA, not FETCH_HEAD: a later fetch must
+              # never be able to change what the worktree is created from.
+              local_ref: sha,
+              sha: sha,
+              remote_tracking: local_remote ? "#{local_remote}/#{head_ref}" : nil,
+              error: nil
+            }
+          end
+
+          private
+
+          # Find a configured local git remote whose URL matches the evidence
+          # source repository; nil means fetch by explicit URL instead.
+          def matching_local_remote(head_url)
+            result = Ace::Git::Worktree::Atoms::GitCommand.execute("remote", "-v", timeout: 5)
+            return nil unless result[:success]
+
+            remotes = {}
+            result[:output].to_s.each_line do |line|
+              name, url, = line.strip.split(/\s+/)
+              remotes[name] = url if url
+            end
+
+            remotes.find do |_name, url|
+              Ace::Git::Atoms::ServerUrl.match?(url, head_url)
+            end&.first
+          end
+
+          def resolve_fetch_head
+            result = Ace::Git::Worktree::Atoms::GitCommand.execute(
+              "rev-parse", "--verify", "FETCH_HEAD^{commit}", timeout: 10
+            )
+            result[:success] ? result[:output].to_s.strip : nil
+          end
+
+          def error_result(message)
+            {success: false, local_ref: nil, sha: nil, remote_tracking: nil, error: message}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/molecules/pull_request_creator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "ace/git"
+
+module Ace
+  module Git
+    module Worktree
+      module Molecules
+        # Creates draft pull requests for task worktrees through the
+        # forge-neutral provider contract.
+        #
+        # The caller must supply the exact pushed head SHA (`expected_head`);
+        # creation or reuse is proven against that SHA by the provider, never
+        # inferred from branch names. Server selection resolves lazily inside
+        # the lifecycle organism, so local-only task runs never touch a forge.
+        class PullRequestCreator
+          # @param server_name [String, nil] explicit server selection
+          # @param use_default [Boolean] resolve the configured default server
+          # @param remote_name [String, nil] remote used for fallback resolution
+          # @param timeout [Integer, nil] provider timeout
+          # @param runner [Proc, nil] injectable provider runner (tests)
+          def initialize(server_name: nil, use_default: false, remote_name: nil, timeout: nil, runner: nil)
+            @selection = {
+              server_name: server_name, use_default: use_default, remote_name: remote_name
+            }
+            @timeout = timeout
+            @runner = runner
+          end
+
+          # Create (or reconcile to) a draft PR for a pushed branch.
+          #
+          # @param branch [String] pushed head branch
+          # @param base [String] base branch/ref
+          # @param title [String] PR title
+          # @param expected_head [String] exact SHA the pushed branch resolves to
+          # @param head_repository_url [String, nil] source repository URL
+          #   (defaults to the selected server's repository)
+          # @param body [String, nil] PR body text
+          # @return [Hash] {success:, pr_number:, pr_url:, existing:, head_sha:, error:}
+          def create_draft(branch:, base:, title:, expected_head:, head_repository_url: nil, body: nil)
+            lifecycle = Ace::Git::Organisms::PullRequestLifecycle.new(**@selection.merge(timeout: @timeout, runner: @runner))
+            receipt = lifecycle.create(
+              head_ref: branch,
+              head_repository_url: head_repository_url,
+              base_ref: base,
+              expected_head: expected_head,
+              title: title,
+              body: body,
+              draft: true
+            )
+            pr = receipt.pull_request
+            {
+              success: true,
+              pr_number: pr.number,
+              pr_url: pr.url,
+              existing: receipt.idempotency == :existing,
+              head_sha: pr.head_sha,
+              error: nil
+            }
+          rescue Ace::Git::Error => e
+            {success: false, pr_number: nil, pr_url: nil, existing: false, head_sha: nil, error: e.message}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/molecules/pull_request_evidence_resolver.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "ace/git"
+
+module Ace
+  module Git
+    module Worktree
+      module Molecules
+        # Resolves normalized pull request evidence for worktree consumers.
+        #
+        # The server is selected once (explicit `--server`, `--default-server`,
+        # or remote resolution) and the PR is fetched through the registered
+        # provider contract. Local-only callers never construct this molecule,
+        # so no forge resolution happens without a PR-aware request.
+        class PullRequestEvidenceResolver
+          # @param server_name [String, nil] explicit server selection
+          # @param use_default [Boolean] resolve the configured default server
+          # @param remote_name [String, nil] git remote for fallback resolution
+          # @param timeout [Integer, nil] provider timeout
+          # @param runner [Proc, nil] injectable provider runner (tests)
+          def initialize(server_name: nil, use_default: false, remote_name: nil, timeout: nil, runner: nil)
+            @selection = {server_name: server_name, use_default: use_default, remote_name: remote_name}
+            @timeout = timeout
+            @runner = runner
+          end
+
+          # Fetch exact PR evidence with source/base provenance.
+          #
+          # @param number [Integer, String] pull request number
+          # @return [Hash] {server: ResolvedServer, evidence: ProviderPullRequest}
+          def resolve(number)
+            server = Ace::Git::ServerRegistry.resolve_for(**@selection)
+            provider = Ace::Git::Providers.for(server, timeout: @timeout, runner: @runner)
+            {server: server, evidence: provider.pull_request(number: number)}
+          end
+        end
+      end
+    end
+  end
+end