carson 3.24.0 → 3.27.1

data/lib/carson/cli.rb

@@ -64,8 +64,10 @@ module Carson
 				parser.separator "    status       Show repository delivery state"
 				parser.separator "    setup        Initialise Carson configuration"
 				parser.separator "    audit        Run pre-commit health checks"
+				parser.separator "    abandon      Close and clean up abandoned delivery work"
 				parser.separator "    sync         Sync local main with remote"
 				parser.separator "    deliver      Start autonomous branch delivery"
+				parser.separator "    recover      Merge the repair PR for one baseline-red governance check"
 				parser.separator "    prune        Remove stale local branches"
 				parser.separator "    worktree     Manage isolated coding worktrees"
 				parser.separator "    housekeep    Sync, reap worktrees, and prune branches"
@@ -120,12 +122,16 @@ module Carson
 				parse_review_subcommand( arguments: arguments, error: error )
 			when "audit"
 				parse_audit_command( arguments: arguments, error: error )
+			when "abandon"
+				parse_abandon_command( arguments: arguments, error: error )
 			when "sync"
 				parse_sync_command( arguments: arguments, error: error )
 			when "status"
 				parse_status_command( arguments: arguments, error: error )
 			when "deliver"
 				parse_deliver_command( arguments: arguments, error: error )
+			when "recover"
+				parse_recover_command( arguments: arguments, error: error )
 			when "govern"
 				parse_govern_subcommand( arguments: arguments, error: error )
 			else
@@ -303,7 +309,7 @@ module Carson
 		def self.parse_worktree_subcommand( arguments:, error: )
 			options = { json: false, force: false }
 			worktree_parser = OptionParser.new do |parser|
-				parser.banner = "Usage: carson worktree <create|remove> <name> [options]"
+				parser.banner = "Usage: carson worktree <create|list|remove> <name> [options]"
 				parser.separator ""
 				parser.separator "Manage isolated worktrees for coding agents."
 				parser.separator "Create auto-syncs main before branching. Remove guards against"
@@ -311,6 +317,7 @@ module Carson
 				parser.separator ""
 				parser.separator "Subcommands:"
 				parser.separator "    create <name>              Create a new worktree with a fresh branch"
+				parser.separator "    list                       List registered worktrees with cleanup status"
 				parser.separator "    remove <name> [--force]    Remove a worktree (--force skips safety checks)"
 				parser.separator ""
 				parser.separator "Options:"
@@ -319,6 +326,7 @@ module Carson
 				parser.separator ""
 				parser.separator "Examples:"
 				parser.separator "    carson worktree create feature-x    Create an isolated worktree"
+				parser.separator "    carson worktree list                Show registered worktrees"
 				parser.separator "    carson worktree remove feature-x    Remove after work is pushed"
 			end
 			worktree_parser.parse!( arguments )
@@ -338,6 +346,8 @@ module Carson
 					return { command: :invalid }
 				end
 				{ command: "worktree:create", worktree_name: name, json: options[ :json ] }
+			when "list"
+				{ command: "worktree:list", json: options[ :json ] }
 			when "remove"
 				worktree_path = arguments.shift
 				if worktree_path.to_s.strip.empty?
@@ -478,6 +488,38 @@ module Carson
 			{ command: :invalid }
 		end
 
+		# --- abandon ---
+
+		def self.parse_abandon_command( arguments:, error: )
+			options = { json: false }
+			abandon_parser = OptionParser.new do |parser|
+				parser.banner = "Usage: carson abandon <pr-number|pr-url|branch> [--json]"
+				parser.separator ""
+				parser.separator "Close an abandoned delivery and clean up its worktree and branch when safe."
+				parser.separator ""
+				parser.separator "Options:"
+				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				parser.separator ""
+				parser.separator "Examples:"
+				parser.separator "    carson abandon 301"
+				parser.separator "    carson abandon https://github.com/acme/widgets/pull/301"
+				parser.separator "    carson abandon codex/feature-branch"
+			end
+			abandon_parser.parse!( arguments )
+			target = arguments.shift.to_s.strip
+			if target.empty? || !arguments.empty?
+				error.puts "#{BADGE} Use: carson abandon <pr-number|pr-url|branch>"
+				error.puts abandon_parser
+				return { command: :invalid }
+			end
+
+			{ command: "abandon", target: target, json: options.fetch( :json ) }
+		rescue OptionParser::ParseError => exception
+			error.puts "#{BADGE} #{exception.message}"
+			error.puts abandon_parser
+			{ command: :invalid }
+		end
+
 		# --- sync ---
 
 		def self.parse_sync_command( arguments:, error: )
@@ -591,6 +633,47 @@ module Carson
 			{ command: :invalid }
 		end
 
+		# --- recover ---
+
+		def self.parse_recover_command( arguments:, error: )
+			options = { json: false, check_name: nil }
+			recover_parser = OptionParser.new do |parser|
+				parser.banner = "Usage: carson recover --check NAME [--json]"
+				parser.separator ""
+				parser.separator "Merge the current repair PR when one governance-owned required check is already red on the default branch."
+				parser.separator "Recovery is narrow: Carson verifies the baseline failure, keeps every other gate intact, and records an audit event."
+				parser.separator ""
+				parser.separator "Options:"
+				parser.on( "--check NAME", "Name of the governance-owned required check to recover" ) { |value| options[ :check_name ] = value }
+				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				parser.separator ""
+				parser.separator "Examples:"
+				parser.separator "    carson recover --check \"Carson governance\""
+				parser.separator "    carson recover --check \"Carson governance\" --json"
+			end
+			recover_parser.parse!( arguments )
+			if options.fetch( :check_name, nil ).to_s.strip.empty?
+				error.puts "#{BADGE} --check requires a non-empty governance check name"
+				error.puts recover_parser
+				return { command: :invalid }
+			end
+			unless arguments.empty?
+				error.puts "#{BADGE} Unexpected arguments for recover: #{arguments.join( ' ' )}"
+				error.puts recover_parser
+				return { command: :invalid }
+			end
+
+			{
+				command: "recover",
+				json: options.fetch( :json ),
+				check_name: options.fetch( :check_name )
+			}
+		rescue OptionParser::ParseError => exception
+			error.puts "#{BADGE} #{exception.message}"
+			error.puts recover_parser
+			{ command: :invalid }
+		end
+
 		# --- repos ---
 
 		def self.parse_repos_command( arguments:, error: )
@@ -623,9 +706,9 @@ module Carson
 		# --- housekeep ---
 
 		def self.parse_housekeep_command( arguments:, error: )
-			options = { all: false, json: false, dry_run: false }
+			options = { all: false, json: false, dry_run: false, loop_seconds: nil }
 			housekeep_parser = OptionParser.new do |parser|
-				parser.banner = "Usage: carson housekeep [REPO] [--all] [--dry-run] [--json]"
+				parser.banner = "Usage: carson housekeep [REPO] [--all] [--dry-run] [--json] [--loop SECONDS]"
 				parser.separator ""
 				parser.separator "Run housekeeping: sync main, reap dead worktrees, and prune stale branches."
 				parser.separator "Defaults to the current repository."
@@ -634,21 +717,31 @@ module Carson
 				parser.on( "--all", "Housekeep all governed repositories" ) { options[ :all ] = true }
 				parser.on( "--dry-run", "Show what would be reaped/deleted without making changes" ) { options[ :dry_run ] = true }
 				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				parser.on( "--loop SECONDS", Integer, "Run continuously, sleeping SECONDS between cycles (requires --all)" ) do |seconds|
+					error.puts( "#{BADGE} --loop expects a positive integer" ) || ( return { command: :invalid } ) if seconds < 1
+					options[ :loop_seconds ] = seconds
+				end
 				parser.separator ""
 				parser.separator "Examples:"
 				parser.separator "    carson housekeep              Housekeep the current repository"
 				parser.separator "    carson housekeep --dry-run    Preview what housekeep would do"
 				parser.separator "    carson housekeep nexus        Housekeep a named governed repo"
 				parser.separator "    carson housekeep --all        Housekeep all governed repos"
+				parser.separator "    carson housekeep --all --loop 300   Housekeep every 5 minutes"
 			end
 			housekeep_parser.parse!( arguments )
 
+			if options[ :loop_seconds ] && !options[ :all ]
+				error.puts "#{BADGE} --loop requires --all"
+				return { command: :invalid }
+			end
+
 			if options[ :all ] && !arguments.empty?
 				error.puts "#{BADGE} --all and repo target are mutually exclusive. Use: carson housekeep --all OR carson housekeep [repo]"
 				return { command: :invalid }
 			end
 
-			return { command: "housekeep:all", json: options[ :json ], dry_run: options[ :dry_run ] } if options[ :all ]
+			return { command: "housekeep:all", json: options[ :json ], dry_run: options[ :dry_run ], loop_seconds: options[ :loop_seconds ] } if options[ :all ]
 
 			if arguments.length > 1
 				error.puts "#{BADGE} Too many arguments for housekeep. Use: carson housekeep [repo]"
@@ -745,6 +838,8 @@ module Carson
 				runtime.setup!( cli_choices: parsed.fetch( :cli_choices, {} ) )
 			when "audit"
 				runtime.audit!( json_output: parsed.fetch( :json, false ) )
+			when "abandon"
+				runtime.abandon!( target: parsed.fetch( :target ), json_output: parsed.fetch( :json, false ) )
 			when "sync"
 				runtime.sync!( json_output: parsed.fetch( :json, false ) )
 			when "prune"
@@ -753,6 +848,8 @@ module Carson
 				runtime.prune_all!
 			when "worktree:create"
 				runtime.worktree_create!( name: parsed.fetch( :worktree_name ), json_output: parsed.fetch( :json, false ) )
+			when "worktree:list"
+				runtime.worktree_list!( json_output: parsed.fetch( :json, false ) )
 			when "worktree:remove"
 				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ), force: parsed.fetch( :force, false ), json_output: parsed.fetch( :json, false ) )
 			when "onboard"
@@ -774,6 +871,11 @@ module Carson
 					commit_message: parsed.fetch( :commit_message, nil ),
 					json_output: parsed.fetch( :json, false )
 				)
+			when "recover"
+				runtime.recover!(
+					check_name: parsed.fetch( :check_name ),
+					json_output: parsed.fetch( :json, false )
+				)
 			when "review:gate"
 				runtime.review_gate!
 			when "review:sweep"
@@ -785,7 +887,16 @@ module Carson
 			when "housekeep:target"
 				runtime.housekeep_target!( target: parsed.fetch( :target ), json_output: parsed.fetch( :json, false ), dry_run: parsed.fetch( :dry_run, false ) )
 			when "housekeep:all"
-				runtime.housekeep_all!( json_output: parsed.fetch( :json, false ), dry_run: parsed.fetch( :dry_run, false ) )
+				loop_seconds = parsed.fetch( :loop_seconds, nil )
+				if loop_seconds
+					runtime.housekeep_loop!(
+						json_output: parsed.fetch( :json, false ),
+						dry_run: parsed.fetch( :dry_run, false ),
+						loop_seconds: loop_seconds
+					)
+				else
+					runtime.housekeep_all!( json_output: parsed.fetch( :json, false ), dry_run: parsed.fetch( :dry_run, false ) )
+				end
 			when "govern"
 				runtime.govern!(
 					dry_run: parsed.fetch( :dry_run, false ),

data/lib/carson/config.rb

@@ -30,7 +30,7 @@ module Carson
 			:review_tracking_issue_title, :review_tracking_issue_label, :review_bot_usernames,
 			:audit_advisory_check_names,
 			:workflow_style,
-			:govern_repos, :govern_authority, :govern_merge_method,
+			:govern_repos, :govern_merge_method,
 			:govern_agent_provider, :govern_state_path,
 			:govern_check_wait
 
@@ -83,7 +83,6 @@ module Carson
 				},
 				"govern" => {
 					"repos" => [],
-					"authority" => "remote",
 					"merge" => {
 						"method" => "squash"
 					},
@@ -92,7 +91,7 @@ module Carson
 						"codex" => {},
 						"claude" => {}
 					},
-					"state_path" => "~/.carson/state.sqlite3",
+					"state_path" => "~/.carson/state.json",
 					"check_wait" => 30
 				}
 			}
@@ -171,8 +170,6 @@ module Carson
 			govern = fetch_hash_section( data: copy, key: "govern" )
 			govern_repos = env_string_array( key: "CARSON_GOVERN_REPOS" )
 			govern[ "repos" ] = govern_repos unless govern_repos.empty?
-			govern_authority = ENV.fetch( "CARSON_GOVERN_AUTHORITY", "" ).to_s.strip
-			govern[ "authority" ] = govern_authority unless govern_authority.empty?
 			govern_method = ENV.fetch( "CARSON_GOVERN_MERGE_METHOD", "" ).to_s.strip
 			unless govern_method.empty?
 				govern[ "merge" ] ||= {}
@@ -243,14 +240,13 @@ module Carson
 
 			govern_hash = fetch_hash( hash: data, key: "govern" )
 			@govern_repos = fetch_optional_string_array( hash: govern_hash, key: "repos" ).map { |path| safe_expand_path( path ) }
-			@govern_authority = fetch_string( hash: govern_hash, key: "authority" ).downcase
 			govern_merge_hash = fetch_hash( hash: govern_hash, key: "merge" )
 			@govern_merge_method = fetch_string( hash: govern_merge_hash, key: "method" ).downcase
 			govern_agent_hash = fetch_hash( hash: govern_hash, key: "agent" )
 			@govern_agent_provider = fetch_string( hash: govern_agent_hash, key: "provider" ).downcase
 			@govern_state_path = resolve_runtime_path(
 				path: govern_hash.fetch( "state_path" ).to_s,
-				fallback_leaf: "state.sqlite3"
+				fallback_leaf: "state.json"
 			)
 			@govern_check_wait = fetch_non_negative_integer( hash: govern_hash, key: "check_wait" )
 
@@ -272,7 +268,6 @@ module Carson
 				raise ConfigError, "review.tracking_issue.title cannot be empty" if review_tracking_issue_title.empty?
 				raise ConfigError, "review.tracking_issue.label cannot be empty" if review_tracking_issue_label.empty?
 				raise ConfigError, "workflow.style must be one of trunk, branch" unless [ "trunk", "branch" ].include?( workflow_style )
-				raise ConfigError, "govern.authority must be one of remote, local" unless [ "remote", "local" ].include?( govern_authority )
 				raise ConfigError, "govern.merge.method must be squash" unless govern_merge_method == "squash"
 				raise ConfigError, "govern.agent.provider must be one of auto, codex, claude" unless [ "auto", "codex", "claude" ].include?( govern_agent_provider )
 			end

data/lib/carson/delivery.rb

@@ -1,4 +1,4 @@
-# Passive ledger record for one branch-to-authority delivery attempt.
+# Passive ledger record for one branch delivery attempt.
 module Carson
 	class Delivery
 		ACTIVE_STATES = %w[preparing gated queued integrating escalated].freeze
@@ -6,25 +6,25 @@ module Carson
 		READY_STATES = %w[queued].freeze
 		TERMINAL_STATES = %w[integrated failed superseded].freeze
 
-		attr_reader :id, :repository, :branch, :head, :worktree_path, :authority, :status,
-			:pull_request_number, :pull_request_url, :revision_count, :cause, :summary,
+		attr_reader :repo_path, :repository, :branch, :head, :worktree_path, :status,
+			:pull_request_number, :pull_request_url, :revisions, :cause, :summary,
 			:created_at, :updated_at, :integrated_at, :superseded_at
 
 		def initialize(
-			id:, repository:, branch:, head:, worktree_path:, authority:, status:,
-			pull_request_number:, pull_request_url:, revision_count:, cause:, summary:,
-			created_at:, updated_at:, integrated_at:, superseded_at:
+			repo_path:, branch:, head:, worktree_path:, status:,
+			pull_request_number:, pull_request_url:, cause:, summary:,
+			created_at:, updated_at:, integrated_at:, superseded_at:,
+			revisions: [], repository: nil
 		)
-			@id = id
+			@repo_path = repo_path
 			@repository = repository
 			@branch = branch
 			@head = head
 			@worktree_path = worktree_path
-			@authority = authority
 			@status = status
 			@pull_request_number = pull_request_number
 			@pull_request_url = pull_request_url
-			@revision_count = revision_count
+			@revisions = revisions
 			@cause = cause
 			@summary = summary
 			@created_at = created_at
@@ -33,6 +33,14 @@ module Carson
 			@superseded_at = superseded_at
 		end
 
+		def key
+			"#{repo_path}:#{branch}:#{head}"
+		end
+
+		def revision_count
+			revisions.length
+		end
+
 		def active?
 			ACTIVE_STATES.include?( status )
 		end