carson 3.22.0 → 3.22.1

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

@@ -1,384 +1,36 @@
-# Safe worktree lifecycle management for coding agents.
-# Two operations: create and remove. Create auto-syncs main before branching.
-# Remove is safe by default — guards against CWD-inside-worktree, cross-process
-# CWD holds, and unpushed commits. Content-aware: allows removal after
-# squash/rebase merge without --force.
-# Supports --json for machine-readable structured output with recovery commands.
+# Thin worktree delegate layer on Runtime.
+# Lifecycle operations live on Carson::Worktree; this module delegates
+# and keeps only methods that genuinely belong on Runtime (path resolution,
+# CWD branch detection).
 module Carson
 	class Runtime
 		module Local
 
-			# Agent directory names whose worktrees Carson may sweep.
-			AGENT_WORKTREE_DIRS = %w[ .claude .codex ].freeze
+			# --- Delegates to Carson::Worktree ---
 
-			# Creates a new worktree under .claude/worktrees/<name> with a fresh branch.
-			# Uses main_worktree_root so this works even when called from inside a worktree.
+			# Creates a new worktree under .claude/worktrees/<name>.
 			def worktree_create!( name:, json_output: false )
-				worktrees_dir = File.join( main_worktree_root, ".claude", "worktrees" )
-				worktree_path = File.join( worktrees_dir, name )
-
-				if Dir.exist?( worktree_path )
-					return worktree_finish(
-						result: { command: "worktree create", status: "error", name: name, path: worktree_path,
-							error: "worktree already exists: #{name}",
-							recovery: "carson worktree remove #{name}, then retry" },
-						exit_code: EXIT_ERROR, json_output: json_output
-					)
-				end
-
-				# Determine the base branch (main branch from config).
-				base = config.main_branch
-
-				# Sync main from remote before branching so the worktree starts
-				# from the latest code. Prevents stale-base merge conflicts later.
-				# Best-effort — if pull fails (non-ff, offline), continue anyway.
-				main_root = main_worktree_root
-				_, _, pull_ok, = Open3.capture3( "git", "-C", main_root, "pull", "--ff-only", config.git_remote, base )
-				puts_verbose pull_ok.success? ? "synced #{base} before branching" : "sync skipped — continuing from local #{base}"
-
-				# Ensure .claude/ is excluded from git status in the host repository.
-				# Uses .git/info/exclude (local-only, never committed) to respect the outsider boundary.
-				ensure_claude_dir_excluded!
-
-				# Create the worktree with a new branch based on the main branch.
-				FileUtils.mkdir_p( worktrees_dir )
-				_, worktree_stderr, worktree_success, = git_run( "worktree", "add", worktree_path, "-b", name, base )
-				unless worktree_success
-					error_text = worktree_stderr.to_s.strip
-					error_text = "unable to create worktree" if error_text.empty?
-					return worktree_finish(
-						result: { command: "worktree create", status: "error", name: name,
-							error: error_text },
-						exit_code: EXIT_ERROR, json_output: json_output
-					)
-				end
-
-				worktree_finish(
-					result: { command: "worktree create", status: "ok", name: name, path: worktree_path, branch: name },
-					exit_code: EXIT_OK, json_output: json_output
-				)
+				Worktree.create!( name: name, runtime: self, json_output: json_output )
 			end
 
 			# Removes a worktree: directory, git registration, and branch.
-			# Never forces removal — if the worktree has uncommitted changes, refuses unless
-			# the user explicitly passes force: true via CLI --force flag.
 			def worktree_remove!( worktree_path:, force: false, json_output: false )
-				fingerprint_status = block_if_outsider_fingerprints!
-				unless fingerprint_status.nil?
-					if json_output
-						output.puts JSON.pretty_generate( {
-							command: "worktree remove", status: "block",
-							error: "Carson-owned artefacts detected in host repository",
-							recovery: "remove Carson-owned files (.carson.yml, bin/carson, .tools/carson) then retry",
-							exit_code: EXIT_BLOCK
-						} )
-					end
-					return fingerprint_status
-				end
-
-				resolved_path = resolve_worktree_path( worktree_path: worktree_path )
-
-				# Missing directory: worktree was destroyed externally (e.g. gh pr merge
-				# --delete-branch). Clean up the stale git registration and delete the branch.
-				if !Dir.exist?( resolved_path ) && worktree_registered?( path: resolved_path )
-					return worktree_remove_missing!( resolved_path: resolved_path, json_output: json_output )
-				end
-
-				unless worktree_registered?( path: resolved_path )
-					return worktree_finish(
-						result: { command: "worktree remove", status: "error", name: File.basename( resolved_path ),
-							error: "#{resolved_path} is not a registered worktree",
-							recovery: "git worktree list" },
-						exit_code: EXIT_ERROR, json_output: json_output
-					)
-				end
-
-				# Safety: refuse if the caller's shell CWD is inside the worktree.
-				# Removing a directory while a shell is inside it kills the shell permanently.
-				if cwd_inside_worktree?( worktree_path: resolved_path )
-					safe_root = main_worktree_root
-					return worktree_finish(
-						result: { command: "worktree remove", status: "block", name: File.basename( resolved_path ),
-							error: "current working directory is inside this worktree",
-							recovery: "cd #{safe_root} && carson worktree remove #{File.basename( resolved_path )}" },
-						exit_code: EXIT_BLOCK, json_output: json_output
-					)
-				end
-
-				# Safety: refuse if another process has its CWD inside the worktree.
-				# Protects against cross-process CWD crashes (e.g. an agent session
-				# removed by a separate cleanup process while the agent's shell is inside).
-				if worktree_held_by_other_process?( worktree_path: resolved_path )
-					return worktree_finish(
-						result: { command: "worktree remove", status: "block", name: File.basename( resolved_path ),
-							error: "another process has its working directory inside this worktree",
-							recovery: "wait for the other session to finish, then retry" },
-						exit_code: EXIT_BLOCK, json_output: json_output
-					)
-				end
-
-				branch = worktree_branch( path: resolved_path )
-				puts_verbose "worktree_remove: path=#{resolved_path} branch=#{branch} force=#{force}"
-
-				# Safety: refuse if the branch has unpushed commits (unless --force).
-				# Prevents accidental destruction of work that exists only locally.
-				unless force
-					unpushed = check_unpushed_commits( branch: branch, worktree_path: resolved_path )
-					if unpushed
-						return worktree_finish(
-							result: { command: "worktree remove", status: "block", name: File.basename( resolved_path ),
-								branch: branch,
-								error: unpushed[ :error ],
-								recovery: unpushed[ :recovery ] },
-							exit_code: EXIT_BLOCK, json_output: json_output
-						)
-					end
-				end
-
-				# Step 1: remove the worktree (directory + git registration).
-				rm_args = [ "worktree", "remove" ]
-				rm_args << "--force" if force
-				rm_args << resolved_path
-				rm_stdout, rm_stderr, rm_success, = git_run( *rm_args )
-				unless rm_success
-					error_text = rm_stderr.to_s.strip
-					error_text = "unable to remove worktree" if error_text.empty?
-					if !force && ( error_text.downcase.include?( "untracked" ) || error_text.downcase.include?( "modified" ) )
-						return worktree_finish(
-							result: { command: "worktree remove", status: "error", name: File.basename( resolved_path ),
-								error: "worktree has uncommitted changes",
-								recovery: "commit or discard changes first, or use --force to override" },
-							exit_code: EXIT_ERROR, json_output: json_output
-						)
-					end
-					return worktree_finish(
-						result: { command: "worktree remove", status: "error", name: File.basename( resolved_path ),
-							error: error_text },
-						exit_code: EXIT_ERROR, json_output: json_output
-					)
-				end
-				puts_verbose "worktree_removed: #{resolved_path}"
-
-				# Step 2: delete the local branch.
-				branch_deleted = false
-				if branch && !config.protected_branches.include?( branch )
-					_, del_stderr, del_success, = git_run( "branch", "-D", branch )
-					if del_success
-						puts_verbose "branch_deleted: #{branch}"
-						branch_deleted = true
-					else
-						puts_verbose "branch_delete_skipped: #{branch} reason=#{del_stderr.to_s.strip}"
-					end
-				end
-
-				# Step 3: delete the remote branch (best-effort).
-				remote_deleted = false
-				if branch && !config.protected_branches.include?( branch )
-					remote_branch = branch
-					_, _, rd_success, = git_run( "push", config.git_remote, "--delete", remote_branch )
-					if rd_success
-						puts_verbose "remote_branch_deleted: #{config.git_remote}/#{remote_branch}"
-						remote_deleted = true
-					end
-				end
-				worktree_finish(
-					result: { command: "worktree remove", status: "ok", name: File.basename( resolved_path ),
-						branch: branch, branch_deleted: branch_deleted, remote_deleted: remote_deleted },
-					exit_code: EXIT_OK, json_output: json_output
-				)
+				Worktree.remove!( path: worktree_path, runtime: self, force: force, json_output: json_output )
 			end
 
 			# Removes agent-owned worktrees whose branch content is already on main.
-			# Scans AGENT_WORKTREE_DIRS (e.g. .claude/worktrees/, .codex/worktrees/)
-			# under the main repo root. Safe: skips detached HEADs, the caller's CWD,
-			# and dirty working trees (git worktree remove refuses without --force).
 			def sweep_stale_worktrees!
-				main_root = main_worktree_root
-				worktrees = worktree_list
-
-				agent_prefixes = AGENT_WORKTREE_DIRS.filter_map do |dir|
-					full = File.join( main_root, dir, "worktrees" )
-					File.join( realpath_safe( full ), "" ) if Dir.exist?( full )
-				end
-				return if agent_prefixes.empty?
-
-				worktrees.each do |worktree|
-					path = worktree.fetch( :path )
-					branch = worktree.fetch( :branch, nil )
-					next unless branch
-					next unless agent_prefixes.any? { |prefix| path.start_with?( prefix ) }
-					next if cwd_inside_worktree?( worktree_path: path )
-					next if worktree_held_by_other_process?( worktree_path: path )
-					next unless branch_absorbed_into_main?( branch: branch )
-
-					# Remove the worktree (no --force: refuses if dirty working tree).
-					_, _, rm_success, = git_run( "worktree", "remove", path )
-					next unless rm_success
-
-					puts_verbose "swept stale worktree: #{File.basename( path )} (branch: #{branch})"
-
-					# Delete the local branch now that no worktree holds it.
-					if !config.protected_branches.include?( branch )
-						git_run( "branch", "-D", branch )
-						puts_verbose "deleted branch: #{branch}"
-					end
-				end
-			end
-
-		private
-
-			# Handles removal when the worktree directory is already gone (destroyed
-			# externally by gh pr merge --delete-branch or manual deletion).
-			# Prunes the stale git worktree entry and cleans up the branch.
-			def worktree_remove_missing!( resolved_path:, json_output: )
-				branch = worktree_branch( path: resolved_path )
-				puts_verbose "worktree_remove_missing: path=#{resolved_path} branch=#{branch}"
-
-				# Prune the stale worktree entry from git's registry.
-				git_run( "worktree", "prune" )
-				puts_verbose "pruned stale worktree entry: #{resolved_path}"
-
-				# Delete the local branch.
-				branch_deleted = false
-				if branch && !config.protected_branches.include?( branch )
-					_, _, del_success, = git_run( "branch", "-D", branch )
-					if del_success
-						puts_verbose "branch_deleted: #{branch}"
-						branch_deleted = true
-					end
-				end
-
-				# Delete the remote branch (best-effort).
-				remote_deleted = false
-				if branch && !config.protected_branches.include?( branch )
-					_, _, rd_success, = git_run( "push", config.git_remote, "--delete", branch )
-					if rd_success
-						puts_verbose "remote_branch_deleted: #{config.git_remote}/#{branch}"
-						remote_deleted = true
-					end
-				end
-
-				worktree_finish(
-					result: { command: "worktree remove", status: "ok", name: File.basename( resolved_path ),
-						branch: branch, branch_deleted: branch_deleted, remote_deleted: remote_deleted },
-					exit_code: EXIT_OK, json_output: json_output
-				)
-			end
-
-			# Unified output for worktree results — JSON or human-readable.
-			def worktree_finish( result:, exit_code:, json_output: )
-				result[ :exit_code ] = exit_code
-
-				if json_output
-					output.puts JSON.pretty_generate( result )
-				else
-					print_worktree_human( result: result )
-				end
-
-				exit_code
+				Worktree.sweep_stale!( runtime: self )
 			end
 
-			# Human-readable output for worktree results.
-			def print_worktree_human( result: )
-				command = result[ :command ]
-				status = result[ :status ]
-
-				case status
-				when "ok"
-					case command
-					when "worktree create"
-						puts_line "Worktree created: #{result[ :name ]}"
-						puts_line "  Path: #{result[ :path ]}"
-						puts_line "  Branch: #{result[ :branch ]}"
-					when "worktree remove"
-						unless verbose?
-							puts_line "Worktree removed: #{result[ :name ]}"
-						end
-					end
-				when "error"
-					puts_line "ERROR: #{result[ :error ]}"
-					puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
-				when "block"
-					puts_line "#{result[ :error ]&.capitalize || 'Blocked'}: #{result[ :name ]}"
-					puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
-				end
-			end
-
-			# Returns true when the process CWD is inside the given worktree path.
-			# This detects the most common session-crash scenario: removing a worktree
-			# while the caller's shell is inside it.
-			# Uses realpath on both sides to handle symlink differences (e.g. /tmp vs /private/tmp).
-			def cwd_inside_worktree?( worktree_path: )
-				cwd = realpath_safe( Dir.pwd )
-				worktree = realpath_safe( worktree_path )
-				normalised_wt = File.join( worktree, "" )
-				cwd == worktree || cwd.start_with?( normalised_wt )
-			rescue StandardError
-				false
-			end
-
-			# Checks whether any other process has its working directory inside the worktree.
-			# Uses lsof to query CWD file descriptors system-wide, then matches against
-			# the worktree path. Catches the cross-process CWD crash scenario: a cleanup
-			# process removing a worktree while another session's shell is still inside it.
-			# Fails safe: returns false if lsof is unavailable or any error occurs.
-			def worktree_held_by_other_process?( worktree_path: )
-				canonical = realpath_safe( worktree_path )
-				return false if canonical.nil? || canonical.empty?
-				return false unless Dir.exist?( canonical )
-
-				stdout, _, status = Open3.capture3( "lsof", "-d", "cwd" )
-				return false unless status.success?
-
-				normalised = File.join( canonical, "" )
-				my_pid = Process.pid
-				stdout.lines.drop( 1 ).any? do |line|
-					fields = line.strip.split( /\s+/ )
-					next false unless fields.length >= 9
-					next false if fields[ 1 ].to_i == my_pid
-					name = fields[ 8.. ].join( " " )
-					name == canonical || name.start_with?( normalised )
-				end
-			rescue Errno::ENOENT
-				# lsof not installed.
-				false
-			rescue StandardError
-				false
+			# Returns all registered worktrees as Carson::Worktree instances.
+			def worktree_list
+				Worktree.list( runtime: self )
 			end
 
-			# Checks whether a branch has unpushed commits that would be lost on removal.
-			# Content-aware: after squash/rebase merge, SHAs differ but tree content may match main. Compares content, not SHAs.
-			# Returns nil if safe, or { error:, recovery: } hash if unpushed work exists.
-			def check_unpushed_commits( branch:, worktree_path: )
-				return nil unless branch
-
-				remote = config.git_remote
-				remote_ref = "#{remote}/#{branch}"
-				ahead, _, ahead_status, = Open3.capture3( "git", "rev-list", "--count", "#{remote_ref}..#{branch}", chdir: worktree_path )
-				if !ahead_status.success?
-					# Remote ref does not exist. Only block if the branch has unique commits vs main.
-					unique, _, unique_status, = Open3.capture3( "git", "rev-list", "--count", "#{config.main_branch}..#{branch}", chdir: worktree_path )
-					if unique_status.success? && unique.strip.to_i > 0
-						# Content-aware check: after squash/rebase merge, commit SHAs differ
-						# but the tree content may be identical to main. Compare content,
-						# not SHAs — if the diff is empty, the work is already on main.
-						_, _, diff_ok, = Open3.capture3( "git", "diff", "--quiet", config.main_branch, branch, chdir: worktree_path )
-						unless diff_ok.success?
-							return { error: "branch has not been pushed to #{remote}",
-								recovery: "git -C #{worktree_path} push -u #{remote} #{branch}, or use --force to override" }
-						end
-						# Diff is empty — content is on main (squash/rebase merged). Safe.
-						puts_verbose "branch #{branch} content matches main — squash/rebase merged, safe to remove"
-					end
-				elsif ahead.strip.to_i > 0
-					return { error: "worktree has unpushed commits",
-						recovery: "git -C #{worktree_path} push #{remote} #{branch}, or use --force to override" }
-				end
-
-				nil
-			end
+			# --- Methods that stay on Runtime ---
 
-			# Returns the branch checked output in the worktree that contains the process CWD,
+			# Returns the branch checked out in the worktree that contains the process CWD,
 			# or nil if CWD is not inside any worktree. Used by prune to proactively
 			# protect the CWD worktree's branch from deletion.
 			# Matches the longest (most specific) path because worktree directories
@@ -388,11 +40,10 @@ module Carson
 				best_branch = nil
 				best_length = -1
 				worktree_list.each do |worktree|
-					worktree_path = worktree.fetch( :path )
-					normalised = File.join( worktree_path, "" )
-					if ( cwd == worktree_path || cwd.start_with?( normalised ) ) && worktree_path.length > best_length
-						best_branch = worktree.fetch( :branch, nil )
-						best_length = worktree_path.length
+					normalised = File.join( worktree.path, "" )
+					if ( cwd == worktree.path || cwd.start_with?( normalised ) ) && worktree.path.length > best_length
+						best_branch = worktree.branch
+						best_length = worktree.path.length
 					end
 				end
 				best_branch
@@ -410,87 +61,31 @@ module Carson
 				repo_root
 			end
 
-			# Adds .claude/ to .git/info/exclude if not already present.
-			# This prevents worktree directories from appearing as untracked files
-			# in the host repository. Uses the local exclude file (never committed)
-			# so the host repo's .gitignore is never touched.
-			# Uses main_worktree_root — worktrees have .git as a file, not a directory.
-			def ensure_claude_dir_excluded!
-				git_dir = File.join( main_worktree_root, ".git" )
-				return unless File.directory?( git_dir )
-
-				info_dir = File.join( git_dir, "info" )
-				exclude_path = File.join( info_dir, "exclude" )
-
-				FileUtils.mkdir_p( info_dir )
-				existing = File.exist?( exclude_path ) ? File.read( exclude_path ) : ""
-				return if existing.lines.any? { |line| line.strip == ".claude/" }
+			# Resolves a path to its canonical form, tolerating non-existent paths.
+			# Preserves canonical parents for missing paths so deleted worktrees still
+			# compare equal to git's recorded path (for example /tmp vs /private/tmp).
+			def realpath_safe( path )
+				File.realpath( path )
+			rescue Errno::ENOENT
+				expanded = File.expand_path( path )
+				missing_segments = []
+				candidate = expanded
 
-				File.open( exclude_path, "a" ) { |file| file.puts ".claude/" }
-			rescue StandardError
-				# Best-effort — do not block worktree creation if exclude fails.
-			end
+				until File.exist?( candidate ) || Dir.exist?( candidate )
+					parent = File.dirname( candidate )
+					break if parent == candidate
 
-			# Resolves a worktree path: if it's a bare name, always resolve under
-			# .claude/worktrees/ — even when the directory no longer exists (e.g. after
-			# gh pr merge --delete-branch deleted it externally).
-			# Returns the canonical (realpath) form so comparisons against git worktree list
-			# succeed, even when the OS resolves symlinks differently (e.g. /tmp → /private/tmp).
-			# Uses main_worktree_root (not repo_root) so resolution works from inside worktrees.
-			def resolve_worktree_path( worktree_path: )
-				if worktree_path.include?( "/" )
-					return realpath_safe( worktree_path )
+					missing_segments.unshift( File.basename( candidate ) )
+					candidate = parent
 				end
 
-				root = main_worktree_root
-				candidate = File.join( root, ".claude", "worktrees", worktree_path )
-				realpath_safe( candidate )
-			end
-
-			# Returns true if the path is a registered git worktree.
-			# Compares using realpath to handle symlink differences.
-			def worktree_registered?( path: )
-				canonical = realpath_safe( path )
-				worktree_list.any? { |worktree| worktree.fetch( :path ) == canonical }
-			end
-
-			# Returns the branch name checked output in a worktree, or nil.
-			# Compares using realpath to handle symlink differences.
-			def worktree_branch( path: )
-				canonical = realpath_safe( path )
-				entry = worktree_list.find { |worktree| worktree.fetch( :path ) == canonical }
-				entry&.fetch( :branch, nil )
-			end
-
-			# Parses `git worktree list --porcelain` into structured entries.
-			# Normalises paths with realpath so comparisons work across symlink differences.
-			def worktree_list
-				output = git_capture!( "worktree", "list", "--porcelain" )
-				entries = []
-				current = {}
-				output.lines.each do |line|
-					line = line.strip
-					if line.empty?
-						entries << current unless current.empty?
-						current = {}
-					elsif line.start_with?( "worktree " )
-						current[ :path ] = realpath_safe( line.sub( "worktree ", "" ) )
-					elsif line.start_with?( "branch " )
-						current[ :branch ] = line.sub( "branch refs/heads/", "" )
-					elsif line == "detached"
-						current[ :branch ] = nil
-					end
+				base = if File.exist?( candidate ) || Dir.exist?( candidate )
+					File.realpath( candidate )
+				else
+					candidate
 				end
-				entries << current unless current.empty?
-				entries
-			end
 
-			# Resolves a path to its canonical form, tolerating non-existent paths.
-			# Falls back to File.expand_path when the path does not exist yet.
-			def realpath_safe( path )
-				File.realpath( path )
-			rescue Errno::ENOENT
-				File.expand_path( path )
+				missing_segments.empty? ? base : File.join( base, *missing_segments )
 			end
 		end
 

data/lib/carson/runtime/review/gate_support.rb

@@ -5,6 +5,73 @@ module Carson
 			module GateSupport
 			private
 
+				def review_gate_report_for_missing_pr( branch_name: )
+					{
+						generated_at: Time.now.utc.iso8601,
+						branch: branch_name,
+						status: "block",
+						converged: false,
+						wait_seconds: config.review_wait_seconds,
+						poll_seconds: config.review_poll_seconds,
+						max_polls: config.review_max_polls,
+						block_reasons: [ "no pull request found for current branch" ],
+						pr: nil,
+						unresolved_threads: [],
+						actionable_top_level: [],
+						unacknowledged_actionable: []
+					}
+				end
+
+				def review_gate_report_for_pr( owner:, repo:, pr_number:, branch_name:, pr_summary: nil )
+					resolved_pr_summary = resolved_review_gate_pr_summary(
+						owner: owner,
+						repo: repo,
+						pr_number: pr_number,
+						pr_summary: pr_summary
+					)
+					pre_snapshot = wait_for_review_warmup( owner: owner, repo: repo, pr_number: pr_number )
+					converged = false
+					last_snapshot = pre_snapshot
+					last_signature = pre_snapshot.nil? ? nil : review_gate_signature( snapshot: pre_snapshot )
+					poll_attempts = 0
+
+					config.review_max_polls.times do |index|
+						poll_attempts = index + 1
+						snapshot = review_gate_snapshot( owner: owner, repo: repo, pr_number: pr_number )
+						last_snapshot = snapshot
+						signature = review_gate_signature( snapshot: snapshot )
+						puts_verbose "poll_attempt: #{poll_attempts}/#{config.review_max_polls}"
+						puts_verbose "latest_activity: #{snapshot.fetch( :latest_activity ) || 'unknown'}"
+						puts_verbose "unresolved_threads: #{snapshot.fetch( :unresolved_threads ).count}"
+						puts_verbose "unacknowledged_actionable: #{snapshot.fetch( :unacknowledged_actionable ).count}"
+						if !last_signature.nil? && signature == last_signature
+							converged = true
+							puts_verbose "convergence: stable"
+							break
+						end
+						last_signature = signature
+						wait_for_review_poll if index < config.review_max_polls - 1
+					end
+
+					build_review_gate_report(
+						branch_name: branch_name,
+						pr_summary: resolved_pr_summary,
+						snapshot: last_snapshot,
+						converged: converged,
+						poll_attempts: poll_attempts
+					)
+				end
+
+				def review_gate_result( report: )
+					return { status: :pass, review: :approved, detail: "review gate passed" } if report.fetch( :status ) == "ok"
+
+					{
+						status: :fail,
+						review: review_gate_changes_requested?( report: report ) ? :changes_requested : :blocked,
+						detail: report.fetch( :block_reasons ).join( "; " )
+					}
+				end
+
 				def wait_for_review_warmup( owner:, repo:, pr_number: )
 					return unless config.review_wait_seconds.positive?
 					quick = review_gate_snapshot( owner: owner, repo: repo, pr_number: pr_number )
@@ -67,8 +134,11 @@ module Carson
 					}
 				end
 
+				# GraphQL returns "gemini-code-assist"; REST returns "gemini-code-assist[bot]".
+				# Normalise both sides by stripping the [bot] suffix for a consistent match.
 				def bot_username?( author: )
-					config.review_bot_usernames.any? { it.downcase == author.to_s.downcase }
+					normalised = author.to_s.downcase.delete_suffix( "[bot]" )
+					config.review_bot_usernames.any? { it.downcase.delete_suffix( "[bot]" ) == normalised }
 				end
 
 				def unresolved_thread_entries( details: )
@@ -166,6 +236,66 @@ module Carson
 					timestamps.map { parse_time_or_nil( text: it ) }.compact.max&.utc&.iso8601
 				end
 
+				def resolved_review_gate_pr_summary( owner:, repo:, pr_number:, pr_summary: )
+					required_keys = %i[number title url state]
+					if !pr_summary.nil? && required_keys.all? { |key| pr_summary.key?( key ) && !pr_summary.fetch( key ).to_s.empty? }
+						return pr_summary
+					end
+
+					pull_request_summary( owner: owner, repo: repo, pr_number: pr_number )
+				end
+
+				def pull_request_summary( owner:, repo:, pr_number: )
+					details = pull_request_details( owner: owner, repo: repo, pr_number: pr_number )
+					{
+						number: details.fetch( :number ),
+						title: details.fetch( :title ),
+						url: details.fetch( :url ),
+						state: details.fetch( :state )
+					}
+				end
+
+				def build_review_gate_report( branch_name:, pr_summary:, snapshot:, converged:, poll_attempts: )
+					{
+						generated_at: Time.now.utc.iso8601,
+						branch: branch_name,
+						status: review_gate_block_reasons( snapshot: snapshot, converged: converged ).empty? ? "ok" : "block",
+						converged: converged,
+						wait_seconds: config.review_wait_seconds,
+						poll_seconds: config.review_poll_seconds,
+						max_polls: config.review_max_polls,
+						poll_attempts: poll_attempts,
+						block_reasons: review_gate_block_reasons( snapshot: snapshot, converged: converged ),
+						pr: {
+							number: pr_summary.fetch( :number ),
+							title: pr_summary.fetch( :title ),
+							url: pr_summary.fetch( :url ),
+							state: pr_summary.fetch( :state )
+						},
+						unresolved_threads: snapshot.fetch( :unresolved_threads ),
+						actionable_top_level: snapshot.fetch( :actionable_top_level ),
+						unacknowledged_actionable: snapshot.fetch( :unacknowledged_actionable )
+					}
+				end
+
+				def review_gate_block_reasons( snapshot:, converged: )
+					reasons = []
+					reasons << "review snapshot did not converge within #{config.review_max_polls} polls" unless converged
+					if snapshot.fetch( :unresolved_threads ).any?
+						reasons << "unresolved review threads remain (#{snapshot.fetch( :unresolved_threads ).count})"
+					end
+					if snapshot.fetch( :unacknowledged_actionable ).any?
+						reasons << "actionable top-level comments/reviews without required disposition (#{snapshot.fetch( :unacknowledged_actionable ).count})"
+					end
+					reasons
+				end
+
+				def review_gate_changes_requested?( report: )
+					Array( report.fetch( :unacknowledged_actionable ) ).any? do |entry|
+						entry.fetch( :reason ) == "changes_requested_review"
+					end
+				end
+
 				# Writes review gate artefacts using fixed report names in global report output.
 				def write_review_gate_report( report: )
 					markdown_path, json_path = report(