carson 3.24.0 → 3.27.1

data/lib/carson/repository.rb

@@ -1,11 +1,10 @@
 # Passive repository record reconstructed from git state and Carson's ledger.
 module Carson
 	class Repository
-		attr_reader :path, :authority
+		attr_reader :path
 
-		def initialize( path:, authority:, runtime: )
+		def initialize( path:, runtime: )
 			@path = File.expand_path( path )
-			@authority = authority
 			@runtime = runtime
 		end
 
@@ -35,7 +34,6 @@ module Carson
 			{
 				name: name,
 				path: path,
-				authority: authority,
 				branches: runtime.ledger.active_deliveries( repo_path: path ).map { |delivery| delivery.branch }
 			}
 		end

data/lib/carson/revision.rb

@@ -1,11 +1,9 @@
 # Passive ledger record for one feedback-driven revision cycle.
 module Carson
 	class Revision
-		attr_reader :id, :delivery_id, :number, :cause, :provider, :status, :started_at, :finished_at, :summary
+		attr_reader :number, :cause, :provider, :status, :started_at, :finished_at, :summary
 
-		def initialize( id:, delivery_id:, number:, cause:, provider:, status:, started_at:, finished_at:, summary: )
-			@id = id
-			@delivery_id = delivery_id
+		def initialize( number:, cause:, provider:, status:, started_at:, finished_at:, summary: )
 			@number = number
 			@cause = cause
 			@provider = provider

data/lib/carson/runtime/abandon.rb

@@ -0,0 +1,238 @@
+# Close abandoned delivery work and clean up its branch/worktree when safe.
+module Carson
+	class Runtime
+		module Abandon
+			def abandon!( target:, json_output: false )
+				result = { command: "abandon", target: target }
+
+				unless gh_available?
+					result[ :error ] = "gh CLI is required for carson abandon"
+					result[ :recovery ] = "install and authenticate gh, then retry"
+					return abandon_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+				end
+
+				resolution = resolve_abandon_target( target: target )
+				if resolution.nil?
+					result[ :error ] = "no branch or pull request found for #{target}"
+					result[ :recovery ] = "use a PR number, PR URL, or existing branch name"
+					return abandon_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+				end
+
+				branch = resolution.fetch( :branch )
+				pull_request = resolution.fetch( :pull_request )
+				worktree = resolution.fetch( :worktree )
+
+				result[ :branch ] = branch
+				result[ :pr_number ] = pull_request&.fetch( :number, nil )
+				result[ :pr_url ] = pull_request&.fetch( :url, nil )
+				result[ :worktree_path ] = worktree&.path
+
+				preflight = abandon_preflight_issue( branch: branch, worktree: worktree )
+				unless preflight.nil?
+					result[ :error ] = preflight.fetch( :error )
+					result[ :recovery ] = preflight.fetch( :recovery )
+					return abandon_finish( result: result, exit_code: preflight.fetch( :exit_code ), json_output: json_output )
+				end
+
+				if pull_request&.fetch( :state ) == "OPEN"
+					close_exit = close_pull_request!( number: pull_request.fetch( :number ), result: result )
+					return abandon_finish( result: result, exit_code: close_exit, json_output: json_output ) unless close_exit == EXIT_OK
+					result[ :pull_request_closed ] = true
+				else
+					result[ :pull_request_closed ] = false
+				end
+
+				if worktree
+					remove_exit = with_captured_output do
+						worktree_remove!( worktree_path: worktree.path, json_output: false )
+					end
+					unless remove_exit == EXIT_OK
+						result[ :error ] = "worktree cleanup failed for #{worktree.path}"
+						result[ :recovery ] = "run carson worktree remove #{File.basename( worktree.path )}"
+						return abandon_finish( result: result, exit_code: remove_exit, json_output: json_output )
+					end
+
+					result[ :worktree_removed ] = true
+					result[ :branch_deleted ] = !local_branch_exists?( branch: branch )
+					result[ :remote_deleted ] = !remote_branch_exists?( branch: branch )
+				else
+					branch_deleted, remote_deleted = delete_branch_refs!( branch: branch )
+					result[ :worktree_removed ] = false
+					result[ :branch_deleted ] = branch_deleted
+					result[ :remote_deleted ] = remote_deleted
+				end
+
+				mark_delivery_abandoned!( branch: branch )
+				result[ :summary ] = "abandoned delivery cleaned up"
+				abandon_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
+			end
+
+		private
+
+			def resolve_abandon_target( target: )
+				pull_request = pull_request_from_target( target: target )
+				branch = pull_request&.fetch( :branch ) || target.to_s.strip
+				branch = branch_from_pull_request_url( target: target ) if branch.empty?
+				return nil if branch.to_s.strip.empty?
+
+				worktree = worktree_list.find { |entry| entry.branch == branch && entry.path != main_worktree_root }
+				branch_exists = local_branch_exists?( branch: branch ) || remote_branch_exists?( branch: branch ) || !pull_request.nil?
+				return nil unless branch_exists
+
+				{
+					branch: branch,
+					pull_request: pull_request,
+					worktree: worktree
+				}
+			end
+
+			def pull_request_from_target( target: )
+				number = pull_request_number_from_target( target: target )
+				return pull_request_details_for_number( number: number ) unless number.nil?
+
+				pull_request = worktree_pull_request( branch: target )
+				return nil if pull_request.fetch( :number ).nil?
+
+				{
+					number: pull_request.fetch( :number ),
+					url: pull_request.fetch( :url ),
+					state: pull_request.fetch( :state ),
+					branch: target
+				}
+			end
+
+			def pull_request_number_from_target( target: )
+				text = target.to_s.strip
+				return Integer( text ) if text.match?( /\A\d+\z/ )
+
+				match = text.match( %r{/pull/(\d+)} )
+				return nil if match.nil?
+
+				Integer( match[ 1 ] )
+			rescue ArgumentError
+				nil
+			end
+
+			def pull_request_details_for_number( number: )
+				stdout_text, stderr_text, success, = gh_run(
+					"pr", "view", number.to_s,
+					"--json", "number,url,state,headRefName"
+				)
+				return nil unless success
+
+				data = JSON.parse( stdout_text )
+				{
+					number: data.fetch( "number" ),
+					url: data.fetch( "url" ).to_s,
+					state: data.fetch( "state" ).to_s,
+					branch: data.fetch( "headRefName" ).to_s
+				}
+			rescue JSON::ParserError
+				nil
+			end
+
+			def abandon_preflight_issue( branch:, worktree: )
+				if config.protected_branches.include?( branch )
+					return { exit_code: EXIT_BLOCK, error: "cannot abandon protected branch #{branch}", recovery: "choose a feature branch instead" }
+				end
+
+				if worktree
+					check = Worktree.remove_check( path: worktree.path, runtime: self, force: false )
+					return nil if check.fetch( :status ) == :ok
+
+					return {
+						exit_code: check.fetch( :exit_code ),
+						error: check.fetch( :error ),
+						recovery: check.fetch( :recovery )
+					}
+				end
+
+				return { exit_code: EXIT_BLOCK, error: "current branch is #{branch}", recovery: "switch to main or a different branch, then retry" } if current_branch == branch
+				return nil unless local_branch_exists?( branch: branch )
+
+				unpushed = Worktree.branch_unpushed_issue( branch: branch, worktree_path: repo_root, runtime: self )
+				return nil if unpushed.nil?
+
+				{ exit_code: EXIT_BLOCK, error: unpushed.fetch( :error ), recovery: unpushed.fetch( :recovery ) }
+			end
+
+			def close_pull_request!( number:, result: )
+				_, stderr_text, success, = gh_run( "pr", "close", number.to_s )
+				return EXIT_OK if success
+
+				result[ :error ] = gh_error_text( stdout_text: "", stderr_text: stderr_text, fallback: "unable to close pull request ##{number}" )
+				result[ :recovery ] = "gh pr close #{number}"
+				EXIT_ERROR
+			end
+
+			def delete_branch_refs!( branch: )
+				branch_deleted = false
+				remote_deleted = false
+
+				if local_branch_exists?( branch: branch ) && !config.protected_branches.include?( branch )
+					_, _, success, = git_run( "branch", "-D", branch )
+					branch_deleted = success
+				end
+
+				if remote_branch_exists?( branch: branch ) && !config.protected_branches.include?( branch )
+					_, _, success, = git_run( "push", config.git_remote, "--delete", branch )
+					remote_deleted = success
+				end
+
+				[ branch_deleted, remote_deleted ]
+			end
+
+			def local_branch_exists?( branch: )
+				_, _, success, = git_run( "show-ref", "--verify", "--quiet", "refs/heads/#{branch}" )
+				success
+			end
+
+			def remote_branch_exists?( branch: )
+				stdout_text, _, success, = git_run( "ls-remote", "--heads", config.git_remote, branch )
+				return false unless success
+
+				!stdout_text.to_s.strip.empty?
+			end
+
+			def mark_delivery_abandoned!( branch: )
+				delivery = ledger.active_delivery( repo_path: repository_record.path, branch_name: branch )
+				return if delivery.nil?
+
+				ledger.update_delivery(
+					delivery: delivery,
+					status: "failed",
+					cause: "abandoned",
+					summary: "abandoned by carson abandon"
+				)
+			end
+
+			def branch_from_pull_request_url( target: )
+				number = pull_request_number_from_target( target: target )
+				return "" if number.nil?
+
+				pull_request_details_for_number( number: number )&.fetch( :branch, "" ).to_s
+			end
+
+			def abandon_finish( result:, exit_code:, json_output: )
+				result[ :exit_code ] = exit_code
+
+				if json_output
+					output.puts JSON.pretty_generate( result )
+				else
+					if result[ :error ]
+						puts_line result.fetch( :error )
+						puts_line "  → #{result.fetch( :recovery )}" if result[ :recovery ]
+					else
+						pr_ref = result[ :pr_number ] ? "PR ##{result[ :pr_number ]}" : "no PR"
+						puts_line "Abandoned #{result.fetch( :branch )} (#{pr_ref})."
+						puts_line "  #{result.fetch( :summary )}"
+					end
+				end
+
+				exit_code
+			end
+		end
+
+		include Abandon
+	end
+end

data/lib/carson/runtime/audit.rb

@@ -38,7 +38,7 @@ module Carson
 				hooks_status = hooks_ok ? "ok" : "mismatch"
 				unless hooks_ok
 					audit_state = "block"
-					audit_concise_problems << "Hooks: mismatch — run carson refresh."
+					audit_concise_problems << "Hooks don't match — run carson refresh."
 				end
 				puts_verbose ""
 				puts_verbose "[Main Sync Status]"
@@ -158,7 +158,7 @@ module Carson
 					puts_verbose( audit_state == "block" ? "ACTION: local policy block must be resolved before commit/push." : "ACTION: no local hard block detected." )
 					unless verbose?
 						audit_concise_problems.each { |problem| puts_line problem }
-						puts_line "Audit: #{audit_state}"
+						puts_line format_audit_state( audit_state )
 					end
 				end
 				exit_code
@@ -219,6 +219,16 @@ module Carson
 			# rubocop:disable Layout/AccessModifierIndentation -- tab-width calculation produces unfixable mixed tabs+spaces
 			private
 			# rubocop:enable Layout/AccessModifierIndentation
+
+				def format_audit_state( state )
+					case state
+					when "ok" then "Audit passed."
+					when "block" then "Audit blocked."
+					when "attention" then "Audit: needs attention."
+					else "Audit: #{state}"
+					end
+				end
+
 				def audit_working_tree_report
 					dirty_reason = dirty_worktree_reason
 					return { dirty: false, context: nil, status: "ok" } if dirty_reason.nil?

data/lib/carson/runtime/deliver.rb

@@ -1,10 +1,11 @@
-# Branch delivery lifecycle — push, create/update PR, and register Carson-owned delivery state.
-# `carson deliver` is now the async handoff point. It does not wait for merge.
+# Branch delivery lifecycle — push, create/update PR, wait for merge readiness, and integrate when clear.
+# `carson deliver` owns the synchronous happy path for single-branch delivery.
 module Carson
 	class Runtime
 		module Deliver
 			# Entry point for `carson deliver`.
-			# Pushes the current branch, ensures a PR exists, records delivery state, and returns.
+			# Pushes the current branch, ensures a PR exists, records delivery state,
+			# waits for merge readiness, and integrates when the path is clear.
 			# When --commit is supplied, Carson creates one all-dirty agent-authored commit first.
 			def deliver!( title: nil, body_file: nil, commit_message: nil, json_output: false )
 				branch_name = current_branch
@@ -68,7 +69,6 @@ module Carson
 					branch_name: branch.name,
 					head: branch.head || current_head,
 					worktree_path: branch.worktree || repo_root,
-					authority: config.govern_authority,
 					pr_number: pr_number,
 					pr_url: pr_url,
 					status: "preparing",
@@ -76,13 +76,22 @@ module Carson
 					cause: nil
 				)
 				delivery = assess_delivery!( delivery: delivery, branch_name: branch.name )
+				delivery = wait_for_delivery_readiness!( delivery: delivery, branch_name: branch.name )
+				delivery = integrate_delivery_now!(
+					delivery: delivery,
+					branch_name: branch.name,
+					remote: remote_name,
+					main: main_branch,
+					result: result
+				) if delivery.ready?
 
 				result[ :pr_number ] = pr_number
 				result[ :pr_url ] = pr_url
-				result[ :ci ] = check_pr_ci( number: pr_number ).to_s
+				result[ :ci ] = delivery.integrated? ? "pass" : check_pr_ci( number: pr_number ).to_s
 				result[ :delivery ] = delivery_payload( delivery: delivery )
+				result[ :main_branch ] = main_branch
 				result[ :summary ] = delivery.summary
-				result[ :next_step ] = "carson status"
+				result[ :next_step ] = deliver_next_step( delivery: delivery, result: result )
 
 				deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
 			end
@@ -194,7 +203,8 @@ module Carson
 			def assess_delivery!( delivery:, branch_name: )
 				review = check_pr_review( number: delivery.pull_request_number, branch: branch_name, pr_url: delivery.pull_request_url )
 				ci = check_pr_ci( number: delivery.pull_request_number )
-				status, cause, summary = delivery_assessment( ci: ci, review: review )
+				pr_state = pull_request_state( number: delivery.pull_request_number )
+				status, cause, summary = delivery_assessment( ci: ci, review: review, pr_state: pr_state )
 
 				ledger.update_delivery(
 					delivery: delivery,
@@ -207,7 +217,96 @@ module Carson
 				)
 			end
 
-			def delivery_assessment( ci:, review: )
+			def wait_for_delivery_readiness!( delivery:, branch_name: )
+				return delivery unless delivery_gate_waitable?( delivery: delivery )
+				return delivery unless config.govern_check_wait.positive?
+
+				deadline = Process.clock_gettime( Process::CLOCK_MONOTONIC ) + config.govern_check_wait
+				interval = deliver_ci_poll_seconds
+				puts_verbose "waiting up to #{config.govern_check_wait}s for delivery gates to settle"
+
+				loop do
+					remaining = deadline - Process.clock_gettime( Process::CLOCK_MONOTONIC )
+					break if remaining <= 0
+
+					sleep [ interval, remaining ].min
+					delivery = assess_delivery!( delivery: delivery, branch_name: branch_name )
+					break unless delivery_gate_waitable?( delivery: delivery )
+				end
+
+				delivery
+			end
+
+			def delivery_gate_waitable?( delivery: )
+				return false unless delivery.status == "gated"
+				return true if delivery.cause == "ci"
+
+				delivery.cause == "review" && delivery.summary == "waiting for review"
+			end
+
+			def deliver_ci_poll_seconds
+				# Reuse the review poll interval for CI/review delivery polling.
+				# The config key predates the synchronous deliver loop.
+				seconds = config.review_poll_seconds.to_i
+				seconds.positive? ? seconds : 5
+			end
+
+			def integrate_delivery_now!( delivery:, branch_name:, remote:, main:, result: )
+				pr_state = pull_request_state( number: delivery.pull_request_number )
+				if pr_state && pr_state[ "state" ] == "MERGED"
+					integrated = ledger.update_delivery(
+						delivery: delivery,
+						status: "integrated",
+						integrated_at: Time.now.utc.iso8601,
+						summary: "integrated into #{main}"
+					)
+					sync_after_merge!( remote: remote, main: main, result: result )
+					return integrated
+				end
+
+				if pr_state && pr_state[ "state" ] == "CLOSED"
+					return ledger.update_delivery(
+						delivery: delivery,
+						status: "failed",
+						cause: "policy",
+						summary: "pull request closed without integration"
+					)
+				end
+
+				prepared = ledger.update_delivery(
+					delivery: delivery,
+					status: "integrating",
+					summary: "integrating into #{main}"
+				)
+				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 #{main}"
+					)
+					sync_after_merge!( remote: remote, main: main, result: result )
+					return integrated
+				end
+
+				merge_error = result.delete( :error )
+				merge_recovery = result.delete( :recovery )
+				result[ :merge ] = {
+					status: "blocked",
+					summary: merge_error || "merge failed",
+					recovery: merge_recovery,
+					method: result[ :merge_method ]
+				}
+				ledger.update_delivery(
+					delivery: prepared,
+					status: "gated",
+					cause: "policy",
+					summary: result.dig( :merge, :summary )
+				)
+			end
+
+			def delivery_assessment( ci:, review:, pr_state: )
 				return [ "gated", "ci", "waiting for CI checks" ] if ci == :pending
 				return [ "gated", "ci", "CI checks are failing" ] if ci == :fail
 				return [ "gated", "review", "review changes requested" ] if review.fetch( :review, :none ) == :changes_requested
@@ -215,12 +314,28 @@ module Carson
 				return [ "gated", "review", review.fetch( :detail ).to_s ] if review.fetch( :status, :pass ) == :fail
 				return [ "gated", "policy", "unable to assess review gate: #{review.fetch( :detail )}" ] if review.fetch( :status, :pass ) == :error
 
+				merge_result = mergeability_assessment( pr_state: pr_state )
+				return merge_result if merge_result
+
 				[ "queued", nil, "ready to integrate into #{config.main_branch}" ]
 			end
 
+			def mergeability_assessment( pr_state: )
+				return nil unless pr_state.is_a?( Hash )
+
+				mergeable = pr_state.fetch( "mergeable", "" ).to_s.upcase
+				merge_state = pr_state.fetch( "mergeStateStatus", "" ).to_s.upcase
+
+				return [ "gated", "merge", "pull request has merge conflicts" ] if mergeable == "CONFLICTING" || merge_state == "DIRTY" || merge_state == "CONFLICTING"
+				return [ "gated", "merge", "merge is blocked by repository policy" ] if merge_state == "BLOCKED"
+				return [ "queued", nil, "ready to integrate into #{config.main_branch} (branch is behind base but still mergeable)" ] if merge_state == "BEHIND"
+
+				nil
+			end
+
 			def delivery_payload( delivery: )
 				{
-					id: delivery.id,
+					key: delivery.key,
 					status: delivery.status,
 					head: delivery.head,
 					worktree_path: delivery.worktree_path,
@@ -229,6 +344,14 @@ module Carson
 				}
 			end
 
+			def deliver_next_step( delivery:, result: )
+				return "carson sync" if delivery.integrated? && result[ :synced ] == false
+				return "carson housekeep" if delivery.integrated?
+				return "carson status" if delivery.blocked?
+
+				nil
+			end
+
 			# Outputs the final result — JSON or human-readable — and returns exit code.
 			def deliver_finish( result:, exit_code:, json_output: )
 				result[ :exit_code ] = exit_code
@@ -250,15 +373,39 @@ module Carson
 					return
 				end
 
+				if result[ :delivery ]
+					branch = result[ :branch ]
+					main = result[ :main_branch ] || "main"
+					puts_line "Delivery: #{branch} → #{main}"
+				end
 				if result[ :commit ]
-					puts_line "Commit: #{result.dig( :commit, :summary )}"
+					puts_line "Committed: #{result.dig( :commit, :summary )}"
 				end
-				puts_line "PR: ##{result[ :pr_number ]} #{result[ :pr_url ]}" if result[ :pr_number ]
+				puts_line "PR ##{result[ :pr_number ]}  #{result[ :pr_url ]}" if result[ :pr_number ]
 				if result[ :delivery ]
-					puts_line "Delivery: #{result.dig( :delivery, :status )}"
+					status = result.dig( :delivery, :status )
+					summary = result[ :summary ]
+					if status == "integrated"
+						if result[ :merge_method ]
+							puts_line "Merged into #{main} with #{result[ :merge_method ]}."
+						else
+							puts_line "Merged into #{main}."
+						end
+						if result[ :synced ] == false
+							puts_line "Local #{main} sync failed — #{result[ :sync_error ]}."
+						elsif result[ :synced ]
+							puts_line "Synced local #{main}."
+						end
+					elsif status == "gated"
+						puts_line "Held at gate — #{summary}."
+						puts_line "  → #{result.dig( :merge, :recovery )}" if result.dig( :merge, :recovery )
+					elsif status == "failed"
+						puts_line "Delivery failed — #{summary}."
+					else
+						puts_line "All clear — #{summary}."
+					end
 				end
-				puts_line "Summary: #{result[ :summary ]}" if result[ :summary ]
-				puts_line "  Next: #{result[ :next_step ]}" if result[ :next_step ]
+				puts_line "Check back with #{result[ :next_step ]}" if result[ :next_step ]
 			end
 
 			# Pushes the branch to the remote with tracking.
@@ -396,7 +543,7 @@ module Carson
 			def pull_request_state( number: )
 				stdout, _, success, = gh_run(
 					"pr", "view", number.to_s,
-					"--json", "number,state,isDraft,url"
+					"--json", "number,state,isDraft,url,mergeStateStatus,mergeable"
 				)
 				return nil unless success