carson 3.27.1 → 3.29.0

data/lib/carson/runtime/govern.rb

@@ -18,12 +18,12 @@ module Carson
 			def govern_cycle!( dry_run:, json_output: )
 				repositories = governed_repo_paths
 				repositories = [ repository_record.path ] if repositories.empty?
-				print_header "Governing #{repositories.length} repo#{plural_suffix( count: repositories.length )}"
+				print_header "Governing #{repositories.length} repo#{plural_suffix( count: repositories.length )}" unless json_output
 
 				report = {
 					cycle_at: Time.now.utc.iso8601,
 					dry_run: dry_run,
-					repositories: repositories.map { |path| govern_repo!( repo_path: path, dry_run: dry_run ) }
+					repositories: repositories.map { |path| govern_repo!( repo_path: path, dry_run: dry_run, silent: json_output ) }
 				}
 
 				if json_output
@@ -39,17 +39,17 @@ module Carson
 			end
 
 			def govern_loop!( dry_run:, json_output:, loop_seconds: )
-				cycle_count = 0
-				loop do
-					cycle_count += 1
-					puts_line ""
-					puts_line "cycle #{cycle_count} at #{Time.now.utc.strftime( '%Y-%m-%d %H:%M:%S UTC' )}"
+				run_signal_aware_loop!(
+					loop_name: "govern",
+					loop_seconds: loop_seconds,
+					cycle_line: ->( cycle_count ) { "cycle #{cycle_count} at #{Time.now.utc.strftime( '%Y-%m-%d %H:%M:%S UTC' )}" },
+					sleep_line: ->( seconds ) do
+						next_at = Time.now + seconds
+						"sleeping #{seconds}s — next cycle at #{next_at.strftime( '%Y-%m-%d %H:%M:%S %z' )}"
+					end
+				) do
 					govern_cycle!( dry_run: dry_run, json_output: json_output )
-					sleep loop_seconds
 				end
-			rescue Interrupt
-				puts_line "govern loop stopped after #{cycle_count} cycle#{plural_suffix( count: cycle_count )}"
-				EXIT_OK
 			end
 
 		private
@@ -62,7 +62,7 @@ module Carson
 				end.compact
 			end
 
-			def govern_repo!( repo_path:, dry_run: )
+			def govern_repo!( repo_path:, dry_run:, silent: false )
 				scoped_runtime = repo_runtime_for( repo_path: repo_path )
 				repository = Repository.new( path: repo_path, runtime: scoped_runtime )
 				deliveries = scoped_runtime.ledger.active_deliveries( repo_path: repo_path )
@@ -75,16 +75,18 @@ module Carson
 				}
 
 				if deliveries.empty?
-					puts_line "#{repository.name}: no active deliveries"
+					puts_line "#{repository.name}: no active deliveries" unless silent
 					return repo_report
 				end
 
-				puts_line "#{repository.name}: #{deliveries.length} active deliver#{deliveries.length == 1 ? 'y' : 'ies'}"
+				puts_line "#{repository.name}: #{deliveries.length} active deliver#{deliveries.length == 1 ? 'y' : 'ies'}" unless silent
 
 				reconciled = deliveries.map { |item| scoped_runtime.send( :reconcile_delivery!, delivery: item ) }
 				next_to_integrate = reconciled.find( &:ready? )&.key
 
 				reconciled.each do |delivery|
+					hint = delivery_action_hint( delivery: delivery, next_to_integrate: next_to_integrate, dry_run: dry_run )
+					puts_line "  #{delivery.branch} — #{hint}" if hint && !silent
 					delivery_report = scoped_runtime.send(
 						:decide_delivery_action,
 						delivery: delivery,
@@ -122,7 +124,10 @@ module Carson
 						delivery: delivery,
 						status: "integrated",
 						integrated_at: Time.now.utc.iso8601,
-						summary: "integrated into #{config.main_branch}"
+						summary: "integrated into #{config.main_branch}",
+						pull_request_state: "MERGED",
+						pull_request_draft: false,
+						pull_request_merged_at: pr_state[ "mergedAt" ]
 					)
 				end
 
@@ -131,47 +136,67 @@ module Carson
 						delivery: delivery,
 						status: "failed",
 						cause: "policy",
-						summary: "pull request closed without integration"
+						summary: "pull request closed without integration",
+						pull_request_state: "CLOSED",
+						pull_request_draft: pr_state[ "isDraft" ],
+						pull_request_merged_at: pr_state[ "mergedAt" ]
 					)
 				end
 
 				assess_delivery!( delivery: delivery, branch_name: delivery.branch )
 			end
 
-			def decide_delivery_action( delivery:, repo_path:, dry_run:, next_to_integrate: )
-				report = {
-					key: delivery.key,
-					branch: delivery.branch,
-					status: delivery.status,
-					summary: delivery.summary,
-					revision_count: delivery.revision_count,
-					action: "none"
-				}
+				def decide_delivery_action( delivery:, repo_path:, dry_run:, next_to_integrate: )
+					report = {
+						key: delivery.key,
+						branch: delivery.branch,
+						status: delivery.status,
+						cause: delivery.cause,
+						summary: delivery.summary,
+						revision_count: delivery.revision_count,
+						action: "none"
+					}
 
 				if delivery.superseded? || delivery.integrated? || delivery.failed?
 					return report
 				end
 
-				if delivery.ready? && delivery.key == next_to_integrate
-					report[ :action ] = dry_run ? "would_integrate" : "integrate"
-					report[ :status ] = execute_delivery_action!( action: report[ :action ], delivery: delivery, repo_path: repo_path, dry_run: dry_run ).status unless dry_run
-					return report
-				end
-
-				if delivery.blocked?
-					if merge_blocked_delivery?( delivery: delivery )
-						report[ :action ] = dry_run ? "would_hold" : "hold"
+					if delivery.ready? && delivery.key == next_to_integrate
+						report[ :action ] = dry_run ? "would_integrate" : "integrate"
+						unless dry_run
+							updated = execute_delivery_action!( action: report[ :action ], delivery: delivery, repo_path: repo_path, dry_run: dry_run )
+							report[ :status ] = updated.status
+							report[ :cause ] = updated.cause
+							report[ :summary ] = updated.summary
+							report[ :merge_proof ] = merge_proof_payload( proof: updated.merge_proof ) if updated.integrated? && updated.merge_proof
+						end
 						return report
 					end
 
-					if delivery.revision_count >= 3
-						report[ :action ] = dry_run ? "would_escalate" : "escalate"
-						report[ :status ] = execute_delivery_action!( action: report[ :action ], delivery: delivery, repo_path: repo_path, dry_run: dry_run ).status unless dry_run
-					else
-						report[ :action ] = dry_run ? "would_revise" : "revise"
-						report[ :status ] = execute_delivery_action!( action: report[ :action ], delivery: delivery, repo_path: repo_path, dry_run: dry_run ).status unless dry_run
+					if delivery.blocked?
+						if held_delivery?( delivery: delivery )
+							report[ :action ] = dry_run ? "would_hold" : "hold"
+							return report
+						end
+
+						if delivery.revision_count >= 3
+							report[ :action ] = dry_run ? "would_escalate" : "escalate"
+							unless dry_run
+								updated = execute_delivery_action!( action: report[ :action ], delivery: delivery, repo_path: repo_path, dry_run: dry_run )
+								report[ :status ] = updated.status
+								report[ :cause ] = updated.cause
+								report[ :summary ] = updated.summary
+							end
+						else
+							report[ :action ] = dry_run ? "would_revise" : "revise"
+							unless dry_run
+								updated = execute_delivery_action!( action: report[ :action ], delivery: delivery, repo_path: repo_path, dry_run: dry_run )
+								report[ :status ] = updated.status
+								report[ :cause ] = updated.cause
+								report[ :summary ] = updated.summary
+							end
+						end
 					end
-				end
 
 				report
 			end
@@ -191,23 +216,46 @@ module Carson
 				end
 			end
 
-			def integrate_delivery!( delivery:, repo_path: )
-				result = {}
-				prepared = ledger.update_delivery(
-					delivery: delivery,
-					status: "integrating",
-					summary: "integrating into #{config.main_branch}"
-				)
+				def integrate_delivery!( delivery:, repo_path: )
+					result = {}
+					freshness = assess_branch_freshness(
+						head_ref: delivery.head || delivery.branch,
+						remote: config.git_remote,
+						main: config.main_branch
+					)
+					unless freshness.fetch( :ready )
+						return ledger.update_delivery(
+							delivery: delivery,
+							status: "gated",
+							cause: "freshness",
+							summary: freshness.fetch( :summary )
+						)
+					end
+
+					prepared = ledger.update_delivery(
+						delivery: delivery,
+						status: "integrating",
+						summary: "integrating into #{config.main_branch}"
+					)
 				merge_exit = merge_pr!( number: prepared.pull_request_number, result: result )
 				if merge_exit == EXIT_OK
 					integrated = ledger.update_delivery(
 						delivery: prepared,
 						status: "integrated",
 						integrated_at: Time.now.utc.iso8601,
-						summary: "integrated into #{config.main_branch}"
+						summary: "integrated into #{config.main_branch}",
+						pull_request_state: "MERGED",
+						pull_request_draft: false,
+						pull_request_merged_at: Time.now.utc.iso8601
+					)
+					# Fetch-only: update the remote tracking ref without mutating the
+					# main worktree. Reap and prune are deferred to explicit housekeep.
+					fetch_for_merge_proof!( repo_path: repo_path )
+					proof = merge_proof_for_remote_ref( branch: integrated.branch )
+					ledger.update_delivery(
+						delivery: integrated,
+						merge_proof: proof
 					)
-					housekeep_repo!( repo_path: repo_path )
-					integrated
 				else
 					ledger.update_delivery(
 						delivery: prepared,
@@ -223,6 +271,27 @@ module Carson
 				return escalate_delivery!( delivery: delivery, reason: "no agent provider available" ) if provider.nil?
 				return escalate_delivery!( delivery: delivery, reason: "worktree missing for revision" ) unless File.directory?( delivery.worktree_path.to_s )
 
+				# Defer if the target worktree is occupied — temporary hold, not failure.
+				worktree = Carson::Worktree.find( path: delivery.worktree_path.to_s, runtime: self )
+				if worktree
+					if worktree.held_by_other_process?
+						return ledger.update_delivery(
+							delivery: delivery,
+							status: "gated",
+							cause: "busy",
+							summary: "worktree held by another process — deferring revision"
+						)
+					end
+					if worktree.dirty?
+						return ledger.update_delivery(
+							delivery: delivery,
+							status: "gated",
+							cause: "busy",
+							summary: "worktree has uncommitted changes — deferring revision"
+						)
+					end
+				end
+
 				objective = revision_objective( cause: delivery.cause )
 				context = evidence( delivery: delivery, repo_path: repo_path, objective: objective )
 				work_order = Adapters::Agent::WorkOrder.new(
@@ -288,15 +357,33 @@ module Carson
 				end
 			end
 
-			def merge_blocked_delivery?( delivery: )
-				delivery.cause == "merge"
-			end
+				def held_delivery?( delivery: )
+					[ "merge", "freshness", "busy" ].include?( delivery.cause )
+				end
+
+				def delivery_action_hint( delivery:, next_to_integrate:, dry_run: )
+					return nil if dry_run
+					return nil if delivery.superseded? || delivery.integrated? || delivery.failed?
+					return "integrating…" if delivery.ready? && delivery.key == next_to_integrate
+					return nil unless delivery.blocked?
+					return nil if held_delivery?( delivery: delivery )
+					delivery.revision_count >= 3 ? "escalating…" : "revising…"
+				end
 
 			def housekeep_repo!( repo_path: )
 				scoped_runtime = repo_runtime_for( repo_path: repo_path )
 				scoped_runtime.send( :housekeep_one_entry, repo_path: repo_path, silent: true )
 			end
 
+			# Fetch-only helper for post-merge proof generation.
+			# Updates the remote tracking ref without mutating the main worktree.
+			def fetch_for_merge_proof!( repo_path: )
+				scoped = repo_runtime_for( repo_path: repo_path )
+				scoped.send( :git_run, "fetch", scoped.config.git_remote, "--prune" )
+			rescue StandardError
+				# Best-effort — merge proof falls back to unavailable if fetch fails.
+			end
+
 			def select_agent_provider
 				provider = config.govern_agent_provider
 				case provider
@@ -435,36 +522,37 @@ module Carson
 
 					next if repo_report[ :deliveries ].empty?
 
-					repo_report[ :deliveries ].each do |delivery|
-						action_text = format_govern_action( status: delivery[ :status ], action: delivery[ :action ] )
-						puts_line "#{repo_report[ :repository ]}/#{delivery[ :branch ]} — #{action_text}"
-						puts_line "  #{delivery[ :summary ]}" unless delivery[ :summary ].to_s.empty?
+						repo_report[ :deliveries ].each do |delivery|
+							action_text = format_govern_action( status: delivery[ :status ], action: delivery[ :action ], cause: delivery[ :cause ] )
+							puts_line "#{repo_report[ :repository ]}/#{delivery[ :branch ]} — #{action_text}"
+							puts_line "  #{delivery[ :summary ]}" unless delivery[ :summary ].to_s.empty?
+							puts_line "  Merge proof: #{delivery.dig( :merge_proof, :summary )}" if delivery[ :merge_proof ]
+						end
 					end
 				end
-			end
 
-			def format_govern_action( status:, action: )
-				case action
-				when "integrate"
-					format_govern_integration_outcome( status: status )
-				when "would_integrate" then "ready to integrate (dry run)"
-				when "hold" then "held at gate"
-				when "would_hold" then "would hold at gate (dry run)"
-				when "revise" then "revision dispatched"
-				when "would_revise" then "would revise (dry run)"
+				def format_govern_action( status:, action:, cause: )
+					case action
+					when "integrate"
+						format_govern_integration_outcome( status: status, cause: cause )
+					when "would_integrate" then "ready to integrate (dry run)"
+					when "hold" then cause == "freshness" ? "refresh required" : "held at gate"
+					when "would_hold" then cause == "freshness" ? "would require refresh (dry run)" : "would hold at gate (dry run)"
+					when "revise" then "revision dispatched"
+					when "would_revise" then "would revise (dry run)"
 				when "escalate" then "escalated"
 				when "would_escalate" then "would escalate (dry run)"
 				else status
 				end
 			end
 
-			def format_govern_integration_outcome( status: )
-				case status
-				when "integrated" then "integrated"
-				when "gated" then "held at gate"
-				when "failed" then "integration failed"
-				when "escalated" then "integration escalated"
-				else status
+				def format_govern_integration_outcome( status:, cause: )
+					case status
+					when "integrated" then "integrated"
+					when "gated" then cause == "freshness" ? "refresh required" : "held at gate"
+					when "failed" then "integration failed"
+					when "escalated" then "integration escalated"
+					else status
 				end
 			end
 		end

data/lib/carson/runtime/housekeep.rb

@@ -81,17 +81,13 @@ module Carson
 			end
 
 			def housekeep_loop!( json_output:, dry_run:, loop_seconds: )
-				cycle_count = 0
-				loop do
-					cycle_count += 1
-					puts_line ""
-					puts_line "housekeep cycle #{cycle_count} at #{Time.now.utc.strftime( '%Y-%m-%d %H:%M:%S UTC' )}"
+				run_signal_aware_loop!(
+					loop_name: "housekeep",
+					loop_seconds: loop_seconds,
+					cycle_line: ->( cycle_count ) { "housekeep cycle #{cycle_count} at #{Time.now.utc.strftime( '%Y-%m-%d %H:%M:%S UTC' )}" }
+				) do
 					housekeep_all!( json_output: json_output, dry_run: dry_run )
-					sleep loop_seconds
 				end
-			rescue Interrupt
-				puts_line "housekeep loop stopped after #{cycle_count} cycle#{plural_suffix( count: cycle_count )}"
-				EXIT_OK
 			end
 
 			# Prints a dry-run plan for this repo without making any changes.

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

@@ -0,0 +1,217 @@
+# Shared local merge-proof detection for commands that need content-aware "already on main" evidence.
+module Carson
+	class Runtime
+		module Local
+			# Generates merge proof against the remote tracking ref directly.
+			# Skips the local-main trust check — the caller is responsible for
+			# fetching before calling. Used by govern's post-merge path to avoid
+			# mutating the main worktree.
+			def merge_proof_for_remote_ref( branch:, remote: config.git_remote, main_ref: config.main_branch )
+				remote_ref = "#{remote}/#{main_ref}"
+				return merge_proof_not_applicable( main_ref: main_ref ) if branch.to_s == main_ref.to_s
+
+				candidate = merge_proof_candidate( branch: branch, main_ref: remote_ref )
+				return candidate if candidate.fetch( :basis ) == "unavailable"
+
+				# Normalise display: show the local branch name, not the remote tracking ref.
+				candidate.merge(
+					main_branch: main_ref,
+					summary: candidate.fetch( :summary ).gsub( remote_ref, main_ref )
+				)
+			end
+
+			def merge_proof_for_branch( branch:, main_ref: config.main_branch )
+				return merge_proof_not_applicable( main_ref: main_ref ) if branch.to_s == main_ref.to_s
+
+				candidate = merge_proof_candidate( branch: branch, main_ref: main_ref )
+				return candidate if candidate.fetch( :basis ) == "unavailable"
+
+				trust = merge_proof_main_trust( main_ref: main_ref )
+				return candidate if trust.fetch( :trusted )
+
+				merge_proof_hash(
+					applicable: true,
+					proven: false,
+					basis: "unavailable",
+					summary: trust.fetch( :summary ),
+					main_branch: main_ref,
+					changed_files_count: candidate.fetch( :changed_files_count, 0 )
+				)
+			end
+
+			def branch_absorbed_into_main?( branch: )
+				merge_proof_for_branch( branch: branch ).fetch( :proven )
+			end
+
+		private
+
+			def merge_proof_candidate( branch:, main_ref: )
+				_, _, ancestor_success, ancestor_exit = git_run( "merge-base", "--is-ancestor", branch, main_ref )
+				merge_base_text, merge_base_error, merge_base_success, = git_run( "merge-base", main_ref, branch )
+				unless merge_base_success
+					return merge_proof_unavailable(
+						main_ref: main_ref,
+						summary: merge_proof_command_failure_summary(
+							remote_ref: merge_proof_remote_ref( main_ref: main_ref ),
+							fallback: "proof unavailable — could not determine merge-base with #{main_ref}.",
+							error_text: merge_base_error
+						)
+					)
+				end
+
+				merge_base = merge_base_text.to_s.strip
+				return merge_proof_unavailable( main_ref: main_ref, summary: "proof unavailable — merge-base with #{main_ref} is empty." ) if merge_base.empty?
+
+				changed_text, changed_error, changed_success, = git_run( "diff", "--name-only", merge_base, branch )
+				unless changed_success
+					return merge_proof_unavailable(
+						main_ref: main_ref,
+						summary: merge_proof_command_failure_summary(
+							remote_ref: merge_proof_remote_ref( main_ref: main_ref ),
+							fallback: "proof unavailable — could not list branch changes against #{main_ref}.",
+							error_text: changed_error
+						)
+					)
+				end
+
+				changed_files = changed_text.to_s.lines.map( &:strip ).reject( &:empty? )
+				changed_files_count = changed_files.length
+
+				if ancestor_success
+					return merge_proof_hash(
+						applicable: true,
+						proven: true,
+						basis: "ancestor",
+						summary: "proven on main — branch tip is already on #{main_ref}.",
+						main_branch: main_ref,
+						changed_files_count: changed_files_count
+					)
+				end
+
+				if ancestor_exit != 1
+					return merge_proof_unavailable(
+						main_ref: main_ref,
+						summary: "proof unavailable — could not verify whether #{branch} is already on #{main_ref}.",
+						changed_files_count: changed_files_count
+					)
+				end
+
+				if changed_files.empty?
+					return merge_proof_hash(
+						applicable: true,
+						proven: true,
+						basis: "no_changes",
+						summary: "proven on main — branch has no unique changes.",
+						main_branch: main_ref,
+						changed_files_count: 0
+					)
+				end
+
+				_, _, identical, identical_exit = git_run( "diff", "--quiet", branch, main_ref, "--", *changed_files )
+				if identical
+					return merge_proof_hash(
+						applicable: true,
+						proven: true,
+						basis: "content_identical",
+						summary: "proven on main — #{changed_files_count} changed file#{plural_suffix( count: changed_files_count )} already #{merge_proof_files_verb( count: changed_files_count, singular: 'matches', plural: 'match' )} #{main_ref}.",
+						main_branch: main_ref,
+						changed_files_count: changed_files_count
+					)
+				end
+
+				if identical_exit == 1
+					return merge_proof_hash(
+						applicable: true,
+						proven: false,
+						basis: "content_differs",
+						summary: "not proven on main — #{changed_files_count} changed file#{plural_suffix( count: changed_files_count )} still #{merge_proof_files_verb( count: changed_files_count, singular: 'differs', plural: 'differ' )} from #{main_ref}.",
+						main_branch: main_ref,
+						changed_files_count: changed_files_count
+					)
+				end
+
+				merge_proof_unavailable(
+					main_ref: main_ref,
+					summary: "proof unavailable — could not compare branch content against #{main_ref}.",
+					changed_files_count: changed_files_count
+				)
+			end
+
+			def merge_proof_main_trust( main_ref: )
+				remote_ref = merge_proof_remote_ref( main_ref: main_ref )
+				_, _, remote_exists, = git_run( "rev-parse", "--verify", remote_ref )
+				unless remote_exists
+					return {
+						trusted: false,
+						summary: "proof unavailable — no local #{remote_ref} reference."
+					}
+				end
+
+				ahead_behind, _, sync_success, = git_run( "rev-list", "--left-right", "--count", "#{main_ref}...#{remote_ref}" )
+				unless sync_success
+					return {
+						trusted: false,
+						summary: "proof unavailable — could not compare local #{main_ref} with #{remote_ref}."
+					}
+				end
+
+				ahead, behind = ahead_behind.to_s.strip.split.map( &:to_i )
+				return { trusted: true, summary: "local #{main_ref} is in sync with #{remote_ref}." } if ahead.zero? && behind.zero?
+
+				{
+					trusted: false,
+					summary: "proof unavailable — local #{main_ref} is not in sync with #{remote_ref}."
+				}
+			end
+
+			def merge_proof_remote_ref( main_ref: )
+				"#{config.git_remote}/#{main_ref}"
+			end
+
+			def merge_proof_not_applicable( main_ref: )
+				merge_proof_hash(
+					applicable: false,
+					proven: false,
+					basis: "not_applicable",
+					summary: "not applicable — current branch is #{main_ref}.",
+					main_branch: main_ref,
+					changed_files_count: 0
+				)
+			end
+
+			def merge_proof_unavailable( main_ref:, summary:, changed_files_count: 0 )
+				merge_proof_hash(
+					applicable: true,
+					proven: false,
+					basis: "unavailable",
+					summary: summary,
+					main_branch: main_ref,
+					changed_files_count: changed_files_count
+				)
+			end
+
+			def merge_proof_hash( applicable:, proven:, basis:, summary:, main_branch:, changed_files_count: )
+				{
+					applicable: applicable,
+					proven: proven,
+					basis: basis,
+					summary: summary,
+					main_branch: main_branch,
+					changed_files_count: changed_files_count.to_i
+				}
+			end
+
+			def merge_proof_files_verb( count:, singular:, plural: )
+				count.to_i == 1 ? singular : plural
+			end
+
+			def merge_proof_command_failure_summary( remote_ref:, fallback:, error_text: )
+				text = error_text.to_s.strip
+				return fallback if text.empty?
+				return "proof unavailable — local main is not in sync with #{remote_ref}." if text.include?( remote_ref ) && text.include?( "not a valid object name" )
+
+				fallback
+			end
+		end
+	end
+end