carson 3.19.0 → 3.21.0

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

@@ -164,12 +164,12 @@ module Carson
 					end
 
 					begin
-						buf = verbose? ? out : StringIO.new
-						err_buf = verbose? ? err : StringIO.new
-						rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: buf, err: err_buf, verbose: verbose? )
-						status = rt.prune!
+						buffer = verbose? ? output : StringIO.new
+						error_buffer = verbose? ? error : StringIO.new
+						scoped_runtime = Runtime.new( repo_root: repo_path, tool_root: tool_root, output: buffer, error: error_buffer, verbose: verbose? )
+						status = scoped_runtime.prune!
 						unless verbose?
-							summary = buf.string.lines.last.to_s.strip
+							summary = buffer.string.lines.last.to_s.strip
 							puts_line "#{repo_name}: #{summary.empty? ? 'OK' : summary}"
 						end
 						if status == EXIT_ERROR
@@ -179,9 +179,9 @@ module Carson
 							clear_batch_success( command: "prune", repo_path: repo_path )
 							succeeded += 1
 						end
-					rescue StandardError => e
-						puts_line "#{repo_name}: FAIL (#{e.message})"
-						record_batch_skip( command: "prune", repo_path: repo_path, reason: e.message )
+					rescue StandardError => exception
+						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						record_batch_skip( command: "prune", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
 				end
@@ -294,7 +294,7 @@ module Carson
 			def onboard_run_audit!
 				audit_error = nil
 				audit_status = with_captured_output { audit! }
-			rescue StandardError => e
+			rescue StandardError => exception
 				audit_error = e
 				audit_status = EXIT_OK
 			ensure
@@ -339,17 +339,17 @@ module Carson
 			# 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 )
+					scoped_runtime = Runtime.new( repo_root: repo_path, tool_root: tool_root, output: output, error: error, verbose: true )
 				else
-					rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: StringIO.new, err: StringIO.new )
+					scoped_runtime = Runtime.new( repo_root: repo_path, tool_root: tool_root, output: StringIO.new, error: StringIO.new )
 				end
-				status = rt.refresh!
+				status = scoped_runtime.refresh!
 				label = refresh_status_label( status: status )
-				sync_suffix = refresh_sync_suffix( result: rt.template_sync_result )
+				sync_suffix = refresh_sync_suffix( result: scoped_runtime.template_sync_result )
 				puts_line "#{repo_name}: #{label}#{sync_suffix}"
 				status
-			rescue StandardError => e
-				puts_line "#{repo_name}: FAIL (#{e.message})"
+			rescue StandardError => exception
+				puts_line "#{repo_name}: FAIL (#{exception.message})"
 				EXIT_ERROR
 			end
 
@@ -376,8 +376,8 @@ module Carson
 				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})"
+			rescue StandardError => exception
+				puts_line "ERROR: unable to update core.hooksPath (#{exception.message})"
 				EXIT_ERROR
 			end
 

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

@@ -8,7 +8,7 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				unless fingerprint_status.nil?
 					if json_output
-						out.puts JSON.pretty_generate( {
+						output.puts JSON.pretty_generate( {
 							command: "prune", status: "block",
 							error: "Carson-owned artefacts detected in host repository",
 							recovery: "remove Carson-owned files (.carson.yml, bin/carson, .tools/carson) then retry",
@@ -51,7 +51,7 @@ module Carson
 				result[ :exit_code ] = exit_code
 
 				if json_output
-					out.puts JSON.pretty_generate( result )
+					output.puts JSON.pretty_generate( result )
 				else
 					print_prune_human( counters: counters )
 				end
@@ -116,7 +116,7 @@ module Carson
 			end
 
 			def prune_skip_stale_branch( type:, branch:, upstream: )
-				reason = { protected: "protected branch", current: "current branch", cwd_worktree: "checked out in CWD worktree" }.fetch( type, type.to_s )
+				reason = { protected: "protected branch", current: "current branch", cwd_worktree: "checked output in CWD worktree" }.fetch( type, type.to_s )
 				status = { protected: "skip_protected_branch", current: "skip_current_branch", cwd_worktree: "skip_cwd_worktree_branch" }.fetch( type, "skip_#{type}" )
 				puts_verbose "#{status}: #{branch} (upstream=#{upstream})"
 				{ action: :skipped, branch: branch, upstream: upstream, type: "stale", reason: reason }
@@ -135,7 +135,7 @@ module Carson
 			end
 
 			def prune_safe_delete_success( branch:, upstream:, stdout_text: )
-				out.print stdout_text if verbose? && !stdout_text.empty?
+				output.print stdout_text if verbose? && !stdout_text.empty?
 				puts_verbose "deleted_local_branch: #{branch} (upstream=#{upstream})"
 				{ action: :deleted, branch: branch, upstream: upstream, type: "stale", reason: "upstream gone" }
 			end
@@ -154,7 +154,7 @@ module Carson
 			end
 
 			def prune_force_delete_success( branch:, upstream:, merged_pr:, force_stdout: )
-				out.print force_stdout if verbose? && !force_stdout.empty?
+				output.print force_stdout if verbose? && !force_stdout.empty?
 				puts_verbose "deleted_local_branch_force: #{branch} (upstream=#{upstream}) merged_pr=#{merged_pr.fetch( :url )}"
 				{ action: :deleted, branch: branch, upstream: upstream, type: "stale", reason: "force deleted with PR evidence" }
 			end
@@ -195,9 +195,9 @@ module Carson
 				error_text.to_s.downcase.include?( "used by worktree" )
 			end
 
-			# Returns the worktree path for a branch, or nil if not checked out in any worktree.
+			# Returns the worktree path for a branch, or nil if not checked output in any worktree.
 			def worktree_path_for_branch( branch: )
-				entry = worktree_list.find { |wt| wt.fetch( :branch, nil ) == branch }
+				entry = worktree_list.find { |worktree| worktree.fetch( :branch, nil ) == branch }
 				entry&.fetch( :path, nil )
 			end
 
@@ -307,7 +307,7 @@ module Carson
 					return { action: :skipped, branch: branch, upstream: upstream, type: "absorbed", reason: error_text }
 				end
 
-				out.print force_stdout if verbose? && !force_stdout.empty?
+				output.print force_stdout if verbose? && !force_stdout.empty?
 
 				remote_branch = upstream.sub( "#{config.git_remote}/", "" )
 				git_run( "push", config.git_remote, "--delete", remote_branch )
@@ -372,7 +372,7 @@ module Carson
 
 				force_stdout, force_stderr, force_success = force_delete_local_branch( branch: branch )
 				if force_success
-					out.print force_stdout if verbose? && !force_stdout.empty?
+					output.print force_stdout if verbose? && !force_stdout.empty?
 					puts_verbose "deleted_orphan_branch: #{branch} merged_pr=#{merged_pr.fetch( :url )}"
 					return { action: :deleted, branch: branch, upstream: "", type: "orphan", reason: "merged PR evidence found" }
 				end
@@ -486,10 +486,10 @@ module Carson
 				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 ]
+			rescue JSON::ParserError => exception
+				[ nil, "invalid gh JSON response (#{exception.message})" ]
+			rescue StandardError => exception
+				[ nil, exception.message ]
 			end
 		end
 	end

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

@@ -66,8 +66,8 @@ module Carson
 					end
 
 					begin
-						rt = build_scoped_runtime( repo_path: repo_path )
-						status = rt.sync!
+						scoped_runtime = build_scoped_runtime( repo_path: repo_path )
+						status = scoped_runtime.sync!
 						if status == EXIT_OK
 							puts_line "#{repo_name}: ok" unless verbose?
 							clear_batch_success( command: "sync", repo_path: repo_path )
@@ -77,9 +77,9 @@ module Carson
 							record_batch_skip( command: "sync", repo_path: repo_path, reason: "sync failed" )
 							failed += 1
 						end
-					rescue StandardError => e
-						puts_line "#{repo_name}: FAIL (#{e.message})"
-						record_batch_skip( command: "sync", repo_path: repo_path, reason: e.message )
+					rescue StandardError => exception
+						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						record_batch_skip( command: "sync", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
 				end
@@ -106,7 +106,7 @@ module Carson
 				result[ :exit_code ] = exit_code
 
 				if json_output
-					out.puts JSON.pretty_generate( result )
+					output.puts JSON.pretty_generate( result )
 				else
 					print_sync_human( result: result )
 				end

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

@@ -1,3 +1,4 @@
+# Detects template drift, applies canonical files, and propagates changes via PR.
 module Carson
 	class Runtime
 		module Local
@@ -9,7 +10,7 @@ module Carson
 				".github/.mega-linter.yml"
 			].freeze
 
-			# Read-only template drift check; returns block when managed files are out of sync.
+			# Read-only template drift check; returns block when managed files are output of sync.
 			def template_check!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
@@ -68,8 +69,8 @@ module Carson
 					end
 
 					begin
-						rt = build_scoped_runtime( repo_path: repo_path )
-						status = rt.template_check!
+						scoped_runtime = build_scoped_runtime( repo_path: repo_path )
+						status = scoped_runtime.template_check!
 						if status == EXIT_OK
 							puts_line "#{repo_name}: in sync" unless verbose?
 							clear_batch_success( command: "template_check", repo_path: repo_path )
@@ -78,9 +79,9 @@ module Carson
 							puts_line "#{repo_name}: DRIFT" unless verbose?
 							drifted += 1
 						end
-					rescue StandardError => e
-						puts_line "#{repo_name}: FAIL (#{e.message})"
-						record_batch_skip( command: "template_check", repo_path: repo_path, reason: e.message )
+					rescue StandardError => exception
+						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						record_batch_skip( command: "template_check", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
 				end
@@ -171,9 +172,9 @@ module Carson
 					result = template_propagate_deliver!( worktree_dir: worktree_dir )
 					template_propagate_report!( result: result )
 					result
-				rescue StandardError => e
-					puts_verbose "template_propagate: error (#{e.message})"
-					{ status: :error, reason: e.message }
+				rescue StandardError => exception
+					puts_verbose "template_propagate: error (#{exception.message})"
+					{ status: :error, reason: exception.message }
 				ensure
 					template_propagate_cleanup!( worktree_dir: worktree_dir ) if worktree_dir
 				end
@@ -181,12 +182,12 @@ module Carson
 
 			def template_propagate_create_worktree!
 				worktree_dir = File.join( Dir.tmpdir, "carson-template-sync-#{Process.pid}-#{Time.now.to_i}" )
-				wt_git = Adapters::Git.new( repo_root: worktree_dir )
+				worktree_git = Adapters::Git.new( repo_root: worktree_dir )
 
 				git_system!( "fetch", config.git_remote, config.main_branch )
 				git_system!( "worktree", "add", "--detach", worktree_dir, "#{config.git_remote}/#{config.main_branch}" )
-				wt_git.run( "checkout", "-B", TEMPLATE_SYNC_BRANCH )
-				wt_git.run( "config", "core.hooksPath", "/dev/null" )
+				worktree_git.run( "checkout", "-B", TEMPLATE_SYNC_BRANCH )
+				worktree_git.run( "config", "core.hooksPath", "/dev/null" )
 				puts_verbose "template_propagate: worktree created at #{worktree_dir}"
 				worktree_dir
 			end
@@ -211,13 +212,13 @@ module Carson
 			end
 
 			def template_propagate_commit!( worktree_dir: )
-				wt_git = Adapters::Git.new( repo_root: worktree_dir )
-				wt_git.run( "add", "--all" )
+				worktree_git = Adapters::Git.new( repo_root: worktree_dir )
+				worktree_git.run( "add", "--all" )
 
-				_, _, no_diff, = wt_git.run( "diff", "--cached", "--quiet" )
+				_, _, no_diff, = worktree_git.run( "diff", "--cached", "--quiet" )
 				return false if no_diff
 
-				wt_git.run( "commit", "-m", "chore: sync Carson #{Carson::VERSION} managed templates" )
+				worktree_git.run( "commit", "-m", "chore: sync Carson #{Carson::VERSION} managed templates" )
 				puts_verbose "template_propagate: committed"
 				true
 			end
@@ -231,8 +232,8 @@ module Carson
 			end
 
 			def template_propagate_deliver_trunk!( worktree_dir: )
-				wt_git = Adapters::Git.new( repo_root: worktree_dir )
-				stdout_text, stderr_text, success, = wt_git.run( "push", config.git_remote, "HEAD:refs/heads/#{config.main_branch}" )
+				worktree_git = Adapters::Git.new( repo_root: worktree_dir )
+				stdout_text, stderr_text, success, = worktree_git.run( "push", config.git_remote, "HEAD:refs/heads/#{config.main_branch}" )
 				unless success
 					error_text = stderr_text.to_s.strip
 					error_text = "push to #{config.main_branch} failed" if error_text.empty?
@@ -243,8 +244,8 @@ module Carson
 			end
 
 			def template_propagate_deliver_branch!( worktree_dir: )
-				wt_git = Adapters::Git.new( repo_root: worktree_dir )
-				stdout_text, stderr_text, success, = wt_git.run( "push", "--force-with-lease", config.git_remote, "#{TEMPLATE_SYNC_BRANCH}:#{TEMPLATE_SYNC_BRANCH}" )
+				worktree_git = Adapters::Git.new( repo_root: worktree_dir )
+				stdout_text, stderr_text, success, = worktree_git.run( "push", "--force-with-lease", config.git_remote, "#{TEMPLATE_SYNC_BRANCH}:#{TEMPLATE_SYNC_BRANCH}" )
 				unless success
 					error_text = stderr_text.to_s.strip
 					error_text = "push #{TEMPLATE_SYNC_BRANCH} failed" if error_text.empty?
@@ -296,8 +297,8 @@ module Carson
 				git_run( "worktree", "remove", "--force", worktree_dir ) unless safe_success
 				git_run( "branch", "-D", TEMPLATE_SYNC_BRANCH )
 				puts_verbose "template_propagate: worktree and local branch cleaned up"
-			rescue StandardError => e
-				puts_verbose "template_propagate: cleanup warning (#{e.message})"
+			rescue StandardError => exception
+				puts_verbose "template_propagate: cleanup warning (#{exception.message})"
 			end
 
 			def template_propagate_report!( result: )
@@ -381,14 +382,14 @@ module Carson
 			def managed_dirty_paths
 				template_paths = config.template_managed_files + SUPERSEDED
 				linters_glob   = Dir.glob( File.join( repo_root, ".github/linters/**/*" ) )
-					.select { |p| File.file?( p ) }
-					.map { |p| p.delete_prefix( "#{repo_root}/" ) }
+					.select { |path| File.file?( path ) }
+					.map { |path| path.delete_prefix( "#{repo_root}/" ) }
 				candidates = ( template_paths + linters_glob ).uniq
 				return [] if candidates.empty?
 
 				stdout_text, = git_capture_soft( "status", "--porcelain", "--", *candidates )
 				stdout_text.to_s.lines
-					.map { |l| l[ 3.. ].strip }
+					.map { |line| line[ 3.. ].strip }
 					.reject( &:empty? )
 			end
 		end

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

@@ -1,7 +1,8 @@
 # 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 and unpushed
-# commits. Content-aware: allows removal after squash/rebase merge without --force.
+# 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.
 module Carson
 	class Runtime
@@ -14,11 +15,11 @@ module Carson
 			# Uses main_worktree_root so this works even when called from inside a worktree.
 			def worktree_create!( name:, json_output: false )
 				worktrees_dir = File.join( main_worktree_root, ".claude", "worktrees" )
-				wt_path = File.join( worktrees_dir, name )
+				worktree_path = File.join( worktrees_dir, name )
 
-				if Dir.exist?( wt_path )
+				if Dir.exist?( worktree_path )
 					return worktree_finish(
-						result: { command: "worktree create", status: "error", name: name, path: wt_path,
+						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
@@ -41,9 +42,9 @@ module Carson
 
 				# Create the worktree with a new branch based on the main branch.
 				FileUtils.mkdir_p( worktrees_dir )
-				_, wt_stderr, wt_success, = git_run( "worktree", "add", wt_path, "-b", name, base )
-				unless wt_success
-					error_text = wt_stderr.to_s.strip
+				_, 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,
@@ -53,7 +54,7 @@ module Carson
 				end
 
 				worktree_finish(
-					result: { command: "worktree create", status: "ok", name: name, path: wt_path, branch: name },
+					result: { command: "worktree create", status: "ok", name: name, path: worktree_path, branch: name },
 					exit_code: EXIT_OK, json_output: json_output
 				)
 			end
@@ -65,7 +66,7 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				unless fingerprint_status.nil?
 					if json_output
-						out.puts JSON.pretty_generate( {
+						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",
@@ -78,12 +79,12 @@ module Carson
 				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
+				# --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 )
+				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",
@@ -104,6 +105,18 @@ module Carson
 					)
 				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}"
 
@@ -189,12 +202,13 @@ module Carson
 				end
 				return if agent_prefixes.empty?
 
-				worktrees.each do |wt|
-					path = wt.fetch( :path )
-					branch = wt.fetch( :branch, nil )
+				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).
@@ -256,7 +270,7 @@ module Carson
 				result[ :exit_code ] = exit_code
 
 				if json_output
-					out.puts JSON.pretty_generate( result )
+					output.puts JSON.pretty_generate( result )
 				else
 					print_worktree_human( result: result )
 				end
@@ -296,9 +310,38 @@ module Carson
 			# 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 )
-				wt = realpath_safe( worktree_path )
-				normalised_wt = File.join( wt, "" )
-				cwd == wt || cwd.start_with?( normalised_wt )
+				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
 			end
@@ -335,7 +378,7 @@ module Carson
 				nil
 			end
 
-			# Returns the branch checked out in the worktree that contains the process CWD,
+			# Returns the branch checked output 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
@@ -344,12 +387,12 @@ module Carson
 				cwd = realpath_safe( Dir.pwd )
 				best_branch = nil
 				best_length = -1
-				worktree_list.each do |wt|
-					wt_path = wt.fetch( :path )
-					normalised = File.join( wt_path, "" )
-					if ( cwd == wt_path || cwd.start_with?( normalised ) ) && wt_path.length > best_length
-						best_branch = wt.fetch( :branch, nil )
-						best_length = wt_path.length
+				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
 					end
 				end
 				best_branch
@@ -383,7 +426,7 @@ module Carson
 				existing = File.exist?( exclude_path ) ? File.read( exclude_path ) : ""
 				return if existing.lines.any? { |line| line.strip == ".claude/" }
 
-				File.open( exclude_path, "a" ) { |f| f.puts ".claude/" }
+				File.open( exclude_path, "a" ) { |file| file.puts ".claude/" }
 			rescue StandardError
 				# Best-effort — do not block worktree creation if exclude fails.
 			end
@@ -408,14 +451,14 @@ module Carson
 			# Compares using realpath to handle symlink differences.
 			def worktree_registered?( path: )
 				canonical = realpath_safe( path )
-				worktree_list.any? { |wt| wt.fetch( :path ) == canonical }
+				worktree_list.any? { |worktree| worktree.fetch( :path ) == canonical }
 			end
 
-			# Returns the branch name checked out in a worktree, or nil.
+			# 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 { |wt| wt.fetch( :path ) == canonical }
+				entry = worktree_list.find { |worktree| worktree.fetch( :path ) == canonical }
 				entry&.fetch( :branch, nil )
 			end
 

data/lib/carson/runtime/local.rb

@@ -1,3 +1,4 @@
+# Aggregates local repository operation modules (sync, prune, hooks, worktree, template).
 require_relative "local/sync"
 require_relative "local/prune"
 require_relative "local/template"

data/lib/carson/runtime/repos.rb

@@ -9,7 +9,7 @@ module Carson
 				repos = config.govern_repos
 
 				if json_output
-					out.puts JSON.pretty_generate( { command: "repos", repos: repos } )
+					output.puts JSON.pretty_generate( { command: "repos", repos: repos } )
 				else
 					if repos.empty?
 						puts_line "No governed repositories."

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

@@ -1,3 +1,4 @@
+# GraphQL data access: PR details, pagination, and normalisation for review gate and sweep.
 module Carson
 	class Runtime
 		module Review

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

@@ -1,3 +1,4 @@
+# Review gate logic: snapshot convergence, disposition acknowledgements, and merge-readiness checks.
 module Carson
 	class Runtime
 		module Review
@@ -30,7 +31,7 @@ module Carson
 					unresolved_threads = unresolved_thread_entries( details: details )
 					actionable_top_level = actionable_top_level_items( details: details, pr_author: pr_author )
 					acknowledgements = disposition_acknowledgements( details: details, pr_author: pr_author )
-					unacknowledged_actionable = actionable_top_level.reject { |item| acknowledged_by_disposition?( item: item, acknowledgements: acknowledgements ) }
+					unacknowledged_actionable = actionable_top_level.reject { acknowledged_by_disposition?( item: it, acknowledgements: acknowledgements ) }
 					{
 						latest_activity: latest_review_activity( details: details ),
 						unresolved_threads: unresolved_threads,
@@ -44,8 +45,8 @@ module Carson
 				def review_gate_signature( snapshot: )
 					{
 						latest_activity: snapshot.fetch( :latest_activity ).to_s,
-						unresolved_urls: snapshot.fetch( :unresolved_threads ).map { |entry| entry.fetch( :url ) }.sort,
-						unacknowledged_urls: snapshot.fetch( :unacknowledged_actionable ).map { |entry| entry.fetch( :url ) }.sort
+						unresolved_urls: snapshot.fetch( :unresolved_threads ).map { it.fetch( :url ) }.sort,
+						unacknowledged_urls: snapshot.fetch( :unacknowledged_actionable ).map { it.fetch( :url ) }.sort
 					}
 				end
 
@@ -67,7 +68,7 @@ module Carson
 				end
 
 				def bot_username?( author: )
-					config.review_bot_usernames.any? { |bot| bot.downcase == author.to_s.downcase }
+					config.review_bot_usernames.any? { it.downcase == author.to_s.downcase }
 				end
 
 				def unresolved_thread_entries( details: )
@@ -78,7 +79,7 @@ module Carson
 						comments = thread.fetch( :comments )
 						first_comment = comments.first || {}
 						next if bot_username?( author: first_comment.fetch( :author, "" ) )
-						latest_time = comments.map { |entry| entry.fetch( :created_at ) }.max.to_s
+						latest_time = comments.map { it.fetch( :created_at ) }.max.to_s
 						{
 							url: blank_to( value: first_comment.fetch( :url, "" ), default: "#{details.fetch( :url )}#thread-#{index + 1}" ),
 							author: first_comment.fetch( :author, "" ),
@@ -130,7 +131,7 @@ module Carson
 					sources = []
 					sources.concat( Array( details.fetch( :comments ) ) )
 					sources.concat( Array( details.fetch( :reviews ) ) )
-					sources.concat( Array( details.fetch( :review_threads ) ).flat_map { |thread| thread.fetch( :comments ) } )
+					sources.concat( Array( details.fetch( :review_threads ) ).flat_map { it.fetch( :comments ) } )
 					sources.map do |entry|
 						next unless entry.fetch( :author, "" ) == pr_author
 						body = entry.fetch( :body, "" ).to_s
@@ -151,7 +152,7 @@ module Carson
 				# True when any disposition acknowledgement references the specific finding URL.
 				def acknowledged_by_disposition?( item:, acknowledgements: )
 					acknowledgements.any? do |ack|
-						Array( ack.fetch( :target_urls ) ).any? { |url| url == item.fetch( :url ) }
+						Array( ack.fetch( :target_urls ) ).any? { it == item.fetch( :url ) }
 					end
 				end
 
@@ -159,10 +160,10 @@ module Carson
 				def latest_review_activity( details: )
 					timestamps = []
 					timestamps << details.fetch( :updated_at )
-					timestamps.concat( Array( details.fetch( :comments ) ).map { |entry| entry.fetch( :created_at ) } )
-					timestamps.concat( Array( details.fetch( :reviews ) ).map { |entry| entry.fetch( :created_at ) } )
-					timestamps.concat( Array( details.fetch( :review_threads ) ).flat_map { |thread| thread.fetch( :comments ) }.map { |entry| entry.fetch( :created_at ) } )
-					timestamps.map { |text| parse_time_or_nil( text: text ) }.compact.max&.utc&.iso8601
+					timestamps.concat( Array( details.fetch( :comments ) ).map { it.fetch( :created_at ) } )
+					timestamps.concat( Array( details.fetch( :reviews ) ).map { it.fetch( :created_at ) } )
+					timestamps.concat( Array( details.fetch( :review_threads ) ).flat_map { it.fetch( :comments ) }.map { it.fetch( :created_at ) } )
+					timestamps.map { parse_time_or_nil( text: it ) }.compact.max&.utc&.iso8601
 				end
 
 				# Writes review gate artefacts using fixed report names in global report output.
@@ -175,8 +176,8 @@ module Carson
 					)
 					puts_verbose "review_gate_report_markdown: #{markdown_path}"
 					puts_verbose "review_gate_report_json: #{json_path}"
-				rescue StandardError => e
-					puts_verbose "review_gate_report_write: SKIP (#{e.message})"
+				rescue StandardError => exception
+					puts_verbose "review_gate_report_write: SKIP (#{exception.message})"
 				end
 
 				# Human-readable review gate report for merge-readiness evidence.
@@ -208,7 +209,7 @@ module Carson
 					if report.fetch( :block_reasons ).empty?
 						lines << "- none"
 					else
-						report.fetch( :block_reasons ).each { |reason| lines << "- #{reason}" }
+						report.fetch( :block_reasons ).each { lines << "- #{it}" }
 					end
 					lines << ""
 					lines << "## Unresolved Threads"