carson 2.24.0 → 2.26.0

data/lib/carson/runtime/local/onboard.rb

@@ -0,0 +1,356 @@
+module Carson
+	class Runtime
+		module Local
+			# One-command onboarding for new repositories: detect remote, install hooks,
+			# apply templates, and run initial audit.
+			def onboard!
+				fingerprint_status = block_if_outsider_fingerprints!
+				return fingerprint_status unless fingerprint_status.nil?
+
+				unless inside_git_work_tree?
+					puts_line "ERROR: #{repo_root} is not a git repository."
+					return EXIT_ERROR
+				end
+
+				repo_name = File.basename( repo_root )
+				puts_line ""
+				puts_line "Onboarding #{repo_name}..."
+
+				if !global_config_exists? || !git_remote_exists?( remote_name: config.git_remote )
+					if self.in.respond_to?( :tty? ) && self.in.tty?
+						setup_status = setup!
+						return setup_status unless setup_status == EXIT_OK
+					else
+						silent_setup!
+					end
+				end
+
+				onboard_apply!
+			end
+
+			# Re-applies hooks, templates, and audit after upgrading Carson.
+			def refresh!
+				fingerprint_status = block_if_outsider_fingerprints!
+				return fingerprint_status unless fingerprint_status.nil?
+
+				unless inside_git_work_tree?
+					puts_line "ERROR: #{repo_root} is not a git repository."
+					return EXIT_ERROR
+				end
+
+				if verbose?
+					puts_verbose ""
+					puts_verbose "[Refresh]"
+					hook_status = prepare!
+					return hook_status unless hook_status == EXIT_OK
+
+					drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+					template_status = template_apply!
+					return template_status unless template_status == EXIT_OK
+
+					@template_sync_result = template_propagate!( drift_count: drift_count )
+
+					audit_status = audit!
+					if audit_status == EXIT_OK
+						puts_line "OK: Carson refresh completed for #{repo_root}."
+					elsif audit_status == EXIT_BLOCK
+						puts_line "BLOCK: Carson refresh completed with policy blocks; resolve and rerun carson audit."
+					end
+					return audit_status
+				end
+
+				puts_line "Refresh"
+				hook_status = with_captured_output { prepare! }
+				return hook_status unless hook_status == EXIT_OK
+				puts_line "Hooks installed (#{config.managed_hooks.count} hooks)."
+
+				template_drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+				template_status = with_captured_output { template_apply! }
+				return template_status unless template_status == EXIT_OK
+				if template_drift_count.positive?
+					puts_line "Templates applied (#{template_drift_count} updated)."
+				else
+					puts_line "Templates in sync."
+				end
+
+				@template_sync_result = template_propagate!( drift_count: template_drift_count )
+
+				audit_status = audit!
+				puts_line "Refresh complete."
+				audit_status
+			end
+
+			# Re-applies hooks, templates, and audit across all governed repositories.
+			def refresh_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Refresh all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				refreshed = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						failed += 1
+						next
+					end
+
+					status = refresh_single_repo( repo_path: repo_path, repo_name: repo_name )
+					if status == EXIT_ERROR
+						failed += 1
+					else
+						refreshed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Refresh all complete: #{refreshed} refreshed, #{failed} failed."
+				failed.zero? ? EXIT_OK : EXIT_ERROR
+			end
+
+			# Removes Carson-managed repository integration so a host repository can retire Carson cleanly.
+			def offboard!
+				puts_verbose ""
+				puts_verbose "[Offboard]"
+				unless inside_git_work_tree?
+					puts_line "ERROR: #{repo_root} is not a git repository."
+					return EXIT_ERROR
+				end
+				if self.in.respond_to?( :tty? ) && self.in.tty?
+					puts_line ""
+					puts_line "This will remove Carson hooks, managed .github/ files,"
+					puts_line "and deregister this repository from portfolio governance."
+					puts_line "Continue?"
+					unless prompt_yes_no( default: false )
+						puts_line "Offboard cancelled."
+						return EXIT_OK
+					end
+				end
+
+				hooks_status = disable_carson_hooks_path!
+				return hooks_status unless hooks_status == EXIT_OK
+
+				removed_count = 0
+				missing_count = 0
+				offboard_cleanup_targets.each do |relative|
+					absolute = resolve_repo_path!( relative_path: relative, label: "offboard target #{relative}" )
+					if File.exist?( absolute )
+						FileUtils.rm_rf( absolute )
+						puts_verbose "removed_path: #{relative}"
+						removed_count += 1
+					else
+						puts_verbose "skip_missing_path: #{relative}"
+						missing_count += 1
+					end
+				end
+				remove_empty_offboard_directories!
+				remove_govern_repo!( repo_path: File.expand_path( repo_root ) )
+				puts_verbose "govern_deregistered: #{File.expand_path( repo_root )}"
+				puts_verbose "offboard_summary: removed=#{removed_count} missing=#{missing_count}"
+				if verbose?
+					puts_line "OK: Carson offboard completed for #{repo_root}."
+				else
+					puts_line "Removed #{removed_count} file#{plural_suffix( count: removed_count )}. Offboard complete."
+				end
+				puts_line ""
+				puts_line "Next: commit the removals and push to finalise offboarding."
+				EXIT_OK
+			end
+
+		private
+
+			# Concise onboard orchestration: hooks, templates, remote, audit, guidance.
+			def onboard_apply!
+				hook_status = with_captured_output { prepare! }
+				return hook_status unless hook_status == EXIT_OK
+				puts_line "Hooks installed (#{config.managed_hooks.count} hooks)."
+
+				template_drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+				template_status = with_captured_output { template_apply! }
+				return template_status unless template_status == EXIT_OK
+				if template_drift_count.positive?
+					puts_line "Templates synced (#{template_drift_count} file#{plural_suffix( count: template_drift_count )} updated)."
+				else
+					puts_line "Templates in sync."
+				end
+
+				onboard_report_remote!
+				audit_status = onboard_run_audit!
+
+				puts_line ""
+				puts_line "Carson at your service."
+
+				if self.in.respond_to?( :tty? ) && self.in.tty?
+					prompt_govern_registration!
+				else
+					puts_line "To register for portfolio governance: carson onboard (in a TTY)"
+				end
+
+				puts_line ""
+				puts_line "Your repository is set up. Carson has placed files in your"
+				puts_line "project's .github/ directory — pull request templates,"
+				puts_line "guidelines for AI coding assistants, and any canonical"
+				puts_line "rules you've configured. Once pushed to GitHub, they'll"
+				puts_line "ensure every pull request follows a consistent standard"
+				puts_line "and all checks run automatically."
+				puts_line ""
+				puts_line "Before your first push, have a look through .github/ to"
+				puts_line "make sure everything is to your liking."
+				puts_line ""
+				puts_line "To adjust any setting: carson setup"
+
+				audit_status
+			end
+
+			# Friendly remote status for onboard output.
+			def onboard_report_remote!
+				if git_remote_exists?( remote_name: config.git_remote )
+					puts_line "Remote: #{config.git_remote} (connected)."
+				else
+					puts_line "Remote not configured yet — carson setup will walk you through it."
+				end
+			end
+
+			# Runs audit with captured output; reports summary instead of full detail.
+			def onboard_run_audit!
+				audit_error = nil
+				audit_status = with_captured_output { audit! }
+			rescue StandardError => e
+				audit_error = e
+				audit_status = EXIT_OK
+			ensure
+				return onboard_print_audit_result( status: audit_status, error: audit_error )
+			end
+
+			def onboard_print_audit_result( status:, error: )
+				if error
+					if error.message.to_s.match?( /HEAD|rev-parse/ )
+						puts_line "No commits yet — run carson audit after your first commit."
+					else
+						puts_line "Audit skipped — run carson audit for details."
+					end
+					return EXIT_OK
+				end
+
+				if status == EXIT_BLOCK
+					puts_line "Some checks need attention — run carson audit for details."
+				end
+				status
+			end
+
+			# Verifies configured remote exists and logs status without mutating remotes.
+			def report_detected_remote!
+				if git_remote_exists?( remote_name: config.git_remote )
+					puts_verbose "remote_ok: #{config.git_remote}"
+				else
+					puts_line "WARN: remote '#{config.git_remote}' not found; run carson setup to configure."
+				end
+			end
+
+			def refresh_sync_suffix( result: )
+				return "" if result.nil?
+
+				case result.fetch( :status )
+				when :pushed then " (templates pushed to #{result.fetch( :ref )})"
+				when :pr then " (PR: #{result.fetch( :pr_url )})"
+				else ""
+				end
+			end
+
+			# Refreshes a single governed repository using a scoped Runtime.
+			def refresh_single_repo( repo_path:, repo_name: )
+				if verbose?
+					rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: out, err: err, verbose: true )
+				else
+					rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: StringIO.new, err: StringIO.new )
+				end
+				status = rt.refresh!
+				label = refresh_status_label( status: status )
+				sync_suffix = refresh_sync_suffix( result: rt.template_sync_result )
+				puts_line "#{repo_name}: #{label}#{sync_suffix}"
+				status
+			rescue StandardError => e
+				puts_line "#{repo_name}: FAIL (#{e.message})"
+				EXIT_ERROR
+			end
+
+			def refresh_status_label( status: )
+				case status
+				when EXIT_OK then "OK"
+				when EXIT_BLOCK then "BLOCK"
+				else "FAIL"
+				end
+			end
+
+			def disable_carson_hooks_path!
+				configured = configured_hooks_path
+				if configured.nil?
+					puts_verbose "hooks_path: (unset)"
+					return EXIT_OK
+				end
+				puts_verbose "hooks_path: #{configured}"
+				configured_abs = File.expand_path( configured, repo_root )
+				unless carson_managed_hooks_path?( configured_abs: configured_abs )
+					puts_verbose "hooks_path_kept: #{configured} (not Carson-managed)"
+					return EXIT_OK
+				end
+				git_system!( "config", "--unset", "core.hooksPath" )
+				puts_verbose "hooks_path_unset: core.hooksPath"
+				EXIT_OK
+			rescue StandardError => e
+				puts_line "ERROR: unable to update core.hooksPath (#{e.message})"
+				EXIT_ERROR
+			end
+
+			def carson_managed_hooks_path?( configured_abs: )
+				hooks_root = File.join( File.expand_path( config.hooks_path ), "" )
+				return true if configured_abs.start_with?( hooks_root )
+
+				carson_hook_files_match_templates?( hooks_path: configured_abs )
+			end
+
+			def carson_hook_files_match_templates?( hooks_path: )
+				return false unless Dir.exist?( hooks_path )
+				config.managed_hooks.all? do |hook_name|
+					installed_path = File.join( hooks_path, hook_name )
+					template_path = hook_template_path( hook_name: hook_name )
+					next false unless File.file?( installed_path ) && File.file?( template_path )
+
+					installed_content = normalize_text( text: File.read( installed_path ) )
+					template_content = normalize_text( text: File.read( template_path ) )
+					installed_content == template_content
+				end
+			rescue StandardError
+				false
+			end
+
+			def offboard_cleanup_targets
+				( config.template_managed_files + SUPERSEDED + [
+					".github/workflows/carson-governance.yml",
+					".github/workflows/carson_policy.yml",
+					".carson.yml",
+					"bin/carson",
+					".tools/carson"
+				] ).uniq
+			end
+
+			def remove_empty_offboard_directories!
+				[ ".github/workflows", ".github", ".tools", "bin" ].each do |relative|
+					absolute = resolve_repo_path!( relative_path: relative, label: "offboard cleanup directory #{relative}" )
+					next unless Dir.exist?( absolute )
+					next unless Dir.empty?( absolute )
+
+					Dir.rmdir( absolute )
+					puts_verbose "removed_empty_dir: #{relative}"
+				end
+			end
+		end
+	end
+end

data/lib/carson/runtime/local/prune.rb

@@ -0,0 +1,292 @@
+module Carson
+	class Runtime
+		module Local
+			# Removes stale local branches (gone upstream) and orphan branches (no tracking) with merged PR evidence.
+			def prune!
+				fingerprint_status = block_if_outsider_fingerprints!
+				return fingerprint_status unless fingerprint_status.nil?
+
+				git_system!( "fetch", config.git_remote, "--prune" )
+				active_branch = current_branch
+				counters = { deleted: 0, skipped: 0 }
+
+				stale_branches = stale_local_branches
+				prune_stale_branch_entries( stale_branches: stale_branches, active_branch: active_branch, counters: counters )
+
+				orphan_branches = orphan_local_branches( active_branch: active_branch )
+				prune_orphan_branch_entries( orphan_branches: orphan_branches, counters: counters )
+
+				return prune_no_stale_branches if counters.fetch( :deleted ).zero? && counters.fetch( :skipped ).zero?
+
+				puts_verbose "prune_summary: deleted=#{counters.fetch( :deleted )} skipped=#{counters.fetch( :skipped )}"
+				unless verbose?
+					deleted_count = counters.fetch( :deleted )
+					if deleted_count.zero?
+						puts_line "No stale branches."
+					else
+						puts_line "Pruned #{deleted_count} stale branch#{plural_suffix( count: deleted_count )}."
+					end
+				end
+				EXIT_OK
+			end
+
+		private
+
+			def prune_no_stale_branches
+				if verbose?
+					puts_line "OK: no stale or orphan branches to prune."
+				else
+					puts_line "No stale branches."
+				end
+				EXIT_OK
+			end
+
+			def prune_stale_branch_entries( stale_branches:, active_branch:, counters: { deleted: 0, skipped: 0 } )
+				stale_branches.each do |entry|
+					outcome = prune_stale_branch_entry( entry: entry, active_branch: active_branch )
+					counters[ outcome ] += 1
+				end
+				counters
+			end
+
+			def prune_stale_branch_entry( entry:, active_branch: )
+				branch = entry.fetch( :branch )
+				upstream = entry.fetch( :upstream )
+				return prune_skip_stale_branch( type: :protected, branch: branch, upstream: upstream ) if config.protected_branches.include?( branch )
+				return prune_skip_stale_branch( type: :current, branch: branch, upstream: upstream ) if branch == active_branch
+
+				prune_delete_stale_branch( branch: branch, upstream: upstream )
+			end
+
+			def prune_skip_stale_branch( type:, branch:, upstream: )
+				status = type == :protected ? "skip_protected_branch" : "skip_current_branch"
+				puts_verbose "#{status}: #{branch} (upstream=#{upstream})"
+				:skipped
+			end
+
+			def prune_delete_stale_branch( branch:, upstream: )
+				stdout_text, stderr_text, success, = git_run( "branch", "-d", branch )
+				return prune_safe_delete_success( branch: branch, upstream: upstream, stdout_text: stdout_text ) if success
+
+				delete_error_text = normalise_branch_delete_error( error_text: stderr_text )
+				prune_force_delete_stale_branch(
+					branch: branch,
+					upstream: upstream,
+					delete_error_text: delete_error_text
+				)
+			end
+
+			def prune_safe_delete_success( branch:, upstream:, stdout_text: )
+				out.print stdout_text if verbose? && !stdout_text.empty?
+				puts_verbose "deleted_local_branch: #{branch} (upstream=#{upstream})"
+				:deleted
+			end
+
+			def prune_force_delete_stale_branch( branch:, upstream:, delete_error_text: )
+				merged_pr, force_error = force_delete_evidence_for_stale_branch(
+					branch: branch,
+					delete_error_text: delete_error_text
+				)
+				return prune_force_delete_skipped( branch: branch, upstream: upstream, delete_error_text: delete_error_text, force_error: force_error ) if merged_pr.nil?
+
+				force_stdout, force_stderr, force_success, = git_run( "branch", "-D", branch )
+				return prune_force_delete_success( branch: branch, upstream: upstream, merged_pr: merged_pr, force_stdout: force_stdout ) if force_success
+
+				prune_force_delete_failed( branch: branch, upstream: upstream, force_stderr: force_stderr )
+			end
+
+			def prune_force_delete_success( branch:, upstream:, merged_pr:, force_stdout: )
+				out.print force_stdout if verbose? && !force_stdout.empty?
+				puts_verbose "deleted_local_branch_force: #{branch} (upstream=#{upstream}) merged_pr=#{merged_pr.fetch( :url )}"
+				:deleted
+			end
+
+			def prune_force_delete_failed( branch:, upstream:, force_stderr: )
+				force_error_text = normalise_branch_delete_error( error_text: force_stderr )
+				puts_verbose "fail_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error_text}"
+				:skipped
+			end
+
+			def prune_force_delete_skipped( branch:, upstream:, delete_error_text:, force_error: )
+				puts_verbose "skip_delete_branch: #{branch} (upstream=#{upstream}) reason=#{delete_error_text}"
+				puts_verbose "skip_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error}" unless force_error.to_s.strip.empty?
+				:skipped
+			end
+
+			def normalise_branch_delete_error( error_text: )
+				text = error_text.to_s.strip
+				text.empty? ? "unknown error" : text
+			end
+
+			# Detects local branches whose upstream tracking is marked [gone] after fetch --prune.
+			def stale_local_branches
+				git_capture!( "for-each-ref", "--format=%(refname:short)\t%(upstream:short)\t%(upstream:track)", "refs/heads" ).lines.map do |line|
+					branch, upstream, track = line.strip.split( "\t", 3 )
+					upstream = upstream.to_s
+					track = track.to_s
+					next if branch.to_s.empty? || upstream.empty?
+					next unless upstream.start_with?( "#{config.git_remote}/" ) && track.include?( "gone" )
+
+					{ branch: branch, upstream: upstream, track: track }
+				end.compact
+			end
+
+			# Detects local branches with no upstream tracking ref — candidates for orphan pruning.
+			def orphan_local_branches( active_branch: )
+				git_capture!( "for-each-ref", "--format=%(refname:short)\t%(upstream:short)", "refs/heads" ).lines.filter_map do |line|
+					branch, upstream = line.strip.split( "\t", 2 )
+					branch = branch.to_s.strip
+					upstream = upstream.to_s.strip
+					next if branch.empty?
+					next unless upstream.empty?
+					next if config.protected_branches.include?( branch )
+					next if branch == active_branch
+					next if branch == TEMPLATE_SYNC_BRANCH
+
+					branch
+				end
+			end
+
+			# Processes orphan branches: verifies merged PR evidence via GitHub API before deleting.
+			def prune_orphan_branch_entries( orphan_branches:, counters: )
+				return counters if orphan_branches.empty?
+				return counters unless gh_available?
+
+				orphan_branches.each do |branch|
+					outcome = prune_orphan_branch_entry( branch: branch )
+					counters[ outcome ] += 1
+				end
+				counters
+			end
+
+			# Checks a single orphan branch for merged PR evidence and force-deletes if confirmed.
+			def prune_orphan_branch_entry( branch: )
+				tip_sha_text, tip_sha_error, tip_sha_success, = git_run( "rev-parse", "--verify", branch.to_s )
+				unless tip_sha_success
+					error_text = tip_sha_error.to_s.strip
+					error_text = "unable to read local branch tip sha" if error_text.empty?
+					puts_verbose "skip_orphan_branch: #{branch} reason=#{error_text}"
+					return :skipped
+				end
+				branch_tip_sha = tip_sha_text.to_s.strip
+				if branch_tip_sha.empty?
+					puts_verbose "skip_orphan_branch: #{branch} reason=unable to read local branch tip sha"
+					return :skipped
+				end
+
+				merged_pr, error = merged_pr_for_branch( branch: branch, branch_tip_sha: branch_tip_sha )
+				if merged_pr.nil?
+					reason = error.to_s.strip
+					reason = "no merged PR evidence for branch tip into #{config.main_branch}" if reason.empty?
+					puts_verbose "skip_orphan_branch: #{branch} reason=#{reason}"
+					return :skipped
+				end
+
+				force_stdout, force_stderr, force_success, = git_run( "branch", "-D", branch )
+				if force_success
+					out.print force_stdout if verbose? && !force_stdout.empty?
+					puts_verbose "deleted_orphan_branch: #{branch} merged_pr=#{merged_pr.fetch( :url )}"
+					return :deleted
+				end
+
+				force_error_text = normalise_branch_delete_error( error_text: force_stderr )
+				puts_verbose "fail_delete_orphan_branch: #{branch} reason=#{force_error_text}"
+				:skipped
+			end
+
+			# Safe delete can fail after squash merges because branch tip is no longer an ancestor.
+			def non_merged_delete_error?( error_text: )
+				error_text.to_s.downcase.include?( "not fully merged" )
+			end
+
+			# Guarded force-delete policy for stale branches.
+			def force_delete_evidence_for_stale_branch( branch:, delete_error_text: )
+				return [ nil, "safe delete failure is not merge-related" ] unless non_merged_delete_error?( error_text: delete_error_text )
+				return [ nil, "gh CLI not available; cannot verify merged PR evidence" ] unless gh_available?
+
+				tip_sha_text, tip_sha_error, tip_sha_success, = git_run( "rev-parse", "--verify", branch.to_s )
+				unless tip_sha_success
+					error_text = tip_sha_error.to_s.strip
+					error_text = "unable to read local branch tip sha" if error_text.empty?
+					return [ nil, error_text ]
+				end
+				branch_tip_sha = tip_sha_text.to_s.strip
+				return [ nil, "unable to read local branch tip sha" ] if branch_tip_sha.empty?
+
+				merged_pr_for_branch( branch: branch, branch_tip_sha: branch_tip_sha )
+			end
+
+			# Finds merged PR evidence for the exact local branch tip.
+			def merged_pr_for_branch( branch:, branch_tip_sha: )
+				owner, repo = repository_coordinates
+				results = []
+				page = 1
+				max_pages = 50
+				loop do
+					stdout_text, stderr_text, success, = gh_run(
+						"api", "repos/#{owner}/#{repo}/pulls",
+						"--method", "GET",
+						"-f", "state=closed",
+						"-f", "base=#{config.main_branch}",
+						"-f", "head=#{owner}:#{branch}",
+						"-f", "sort=updated",
+						"-f", "direction=desc",
+						"-f", "per_page=100",
+						"-f", "page=#{page}"
+					)
+					unless success
+						error_text = gh_error_text( stdout_text: stdout_text, stderr_text: stderr_text, fallback: "unable to query merged PR evidence for branch #{branch}" )
+						return [ nil, error_text ]
+					end
+					page_nodes = Array( JSON.parse( stdout_text ) )
+					break if page_nodes.empty?
+
+					page_nodes.each do |entry|
+						next unless entry.dig( "head", "ref" ).to_s == branch.to_s
+						next unless entry.dig( "base", "ref" ).to_s == config.main_branch
+						next unless entry.dig( "head", "sha" ).to_s == branch_tip_sha
+
+						merged_at = parse_time_or_nil( text: entry[ "merged_at" ] )
+						next if merged_at.nil?
+
+						results << {
+							number: entry[ "number" ],
+							url: entry[ "html_url" ].to_s,
+							merged_at: merged_at.utc.iso8601,
+							head_sha: entry.dig( "head", "sha" ).to_s
+						}
+						end
+						if page >= max_pages
+							probe_stdout_text, probe_stderr_text, probe_success, = gh_run(
+								"api", "repos/#{owner}/#{repo}/pulls",
+								"--method", "GET",
+								"-f", "state=closed",
+								"-f", "base=#{config.main_branch}",
+								"-f", "head=#{owner}:#{branch}",
+								"-f", "sort=updated",
+								"-f", "direction=desc",
+								"-f", "per_page=100",
+								"-f", "page=#{page + 1}"
+							)
+							unless probe_success
+								error_text = gh_error_text( stdout_text: probe_stdout_text, stderr_text: probe_stderr_text, fallback: "unable to verify merged PR pagination limit for branch #{branch}" )
+								return [ nil, error_text ]
+							end
+							probe_nodes = Array( JSON.parse( probe_stdout_text ) )
+							return [ nil, "merged PR lookup exceeded pagination safety limit (#{max_pages} pages) for branch #{branch}" ] unless probe_nodes.empty?
+							break
+						end
+						page += 1
+					end
+				latest = results.max_by { |item| item.fetch( :merged_at ) }
+				return [ nil, "no merged PR evidence for branch tip #{branch_tip_sha} into #{config.main_branch}" ] if latest.nil?
+
+				[ latest, nil ]
+			rescue JSON::ParserError => e
+				[ nil, "invalid gh JSON response (#{e.message})" ]
+			rescue StandardError => e
+				[ nil, e.message ]
+			end
+		end
+	end
+end