carson 2.30.0 → 2.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 374e4a7af2ec608b1c3c9d07ca4a5ad8b028715434c1f02fb4b4034a71b153d2
-  data.tar.gz: a795fabcecbe2b43d03f155b0d4b730f804d0879ef4a1fe280cc4e082350c76f
+  metadata.gz: 99666417783ceb949cdef39bbf1595465bf0a5f674607229b4b937a4ae8b6197
+  data.tar.gz: a8e55f943e2ab34a26d50b0468e10cecbdbf5879eaeef1a7323e99e80715dac3
 SHA512:
-  metadata.gz: 83b920da278fa2e457c424babaf3b06955a2317f920b5ad3681ae4da8a90fc5d5c3969d7160796b0febc49669a7cf7995c8f83ba674ce7f0865ca72eb6a48cbf
-  data.tar.gz: 8506fe647fe4538a27dd0ef25e0ecbeb1d9c0b78c8251d45b6023e562091cd6c861ef660707684b4e3d202a69728b0779a8a623ceb79313efc7e86eb0b482b17
+  metadata.gz: 2342dcf7bde01d3632741e76adaefe6c499a03a36d11bda476870419e43f87caa51ae9837fc5f1cdbbc9b5c083b4b2058824fc5c0f346788ca7f2658aecbe2ab
+  data.tar.gz: f0f8fe556fa65044b3789a45cd25d1fc354e2865a5b923843bf3249a30259bac989eb74f0cb5bb1ff2072c4dc548911ca5f5d26d13da933baceb70161a527993

data/RELEASE.md

@@ -5,6 +5,28 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 2.32.0 — Worktree-Aware Pruning
+
+### What changed
+
+- **Prune now clears worktrees that block branch deletion.** When a branch is checked out in a worktree, `carson prune` safely removes the worktree first (refuses if uncommitted changes exist), then deletes the branch. Previously, these branches were silently skipped.
+- **Honest skip reporting.** Non-verbose output no longer says "No stale branches" when branches were detected but couldn't be pruned. Shows "Skipped N branch(es)" or "Pruned N, skipped M" as appropriate, with a `--verbose` hint.
+
+### Migration
+
+- No action required. Existing prune behaviour is strictly improved.
+
+## 2.31.0 — Worktree Lifecycle + Prune --all
+
+### What changed
+
+- **`carson worktree remove <name-or-path>`** — Safe worktree teardown in the correct order: removes the worktree directory and git registration, deletes the local branch, and cleans up the remote branch. Accepts either a full path or a short name (resolves under `.claude/worktrees/`). Prevents agents from being stranded in deleted directories.
+- **`carson prune --all`** — Prunes stale branches across all governed repositories. Same discipline as single-repo prune, applied to the full estate.
+
+### Migration
+
+- No action required. Both commands are additive.
+
 ## 2.30.0 — Prune Rebase Merge Support + Audit Noise Reduction
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.30.0
+2.32.0

data/lib/carson/cli.rb

@@ -12,7 +12,7 @@ module Carson
 				return Runtime::EXIT_OK
 			end
 
-			if command == "refresh:all"
+			if %w[refresh:all prune:all].include?( command )
 				verbose = parsed.fetch( :verbose, false )
 				runtime = Runtime.new( repo_root: repo_root, tool_root: tool_root, out: out, err: err, verbose: verbose )
 				return dispatch( parsed: parsed, runtime: runtime )
@@ -53,7 +53,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--merge METHOD] [--canonical PATH]|audit|sync|prune|onboard [repo_path]|refresh [--all|repo_path]|offboard [repo_path]|template check|template apply|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
+				opts.banner = "Usage: carson [setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--merge METHOD] [--canonical PATH]|audit|sync|prune [--all]|worktree remove <name-or-path>|onboard [repo_path]|refresh [--all|repo_path]|offboard [repo_path]|template check|template apply|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -82,6 +82,10 @@ module Carson
 				parse_refresh_command( argv: argv, parser: parser, err: err )
 			when "template"
 				parse_template_subcommand( argv: argv, parser: parser, err: err )
+			when "prune"
+				parse_prune_command( argv: argv, parser: parser, err: err )
+			when "worktree"
+				parse_worktree_subcommand( argv: argv, parser: parser, err: err )
 			when "review"
 				parse_named_subcommand( command: command, usage: "gate|sweep", argv: argv, parser: parser, err: err )
 			when "govern"
@@ -154,6 +158,35 @@ module Carson
 			}
 		end
 
+		def self.parse_prune_command( argv:, parser:, err: )
+			all_flag = argv.delete( "--all" ) ? true : false
+			parser.parse!( argv )
+			return { command: "prune:all" } if all_flag
+			{ command: "prune" }
+		end
+
+		def self.parse_worktree_subcommand( argv:, parser:, err: )
+			action = argv.shift
+			if action.to_s.strip.empty?
+				err.puts "#{BADGE} Missing subcommand for worktree. Use: carson worktree remove <name-or-path>"
+				err.puts parser
+				return { command: :invalid }
+			end
+
+			case action
+			when "remove"
+				worktree_path = argv.shift
+				if worktree_path.to_s.strip.empty?
+					err.puts "#{BADGE} Missing path for worktree remove. Use: carson worktree remove <name-or-path>"
+					return { command: :invalid }
+				end
+				{ command: "worktree:remove", worktree_path: worktree_path }
+			else
+				err.puts "#{BADGE} Unknown worktree subcommand: #{action}. Use: carson worktree remove <name-or-path>"
+				{ command: :invalid }
+			end
+		end
+
 		def self.parse_named_subcommand( command:, usage:, argv:, parser:, err: )
 			action = argv.shift
 			parser.parse!( argv )
@@ -240,6 +273,10 @@ module Carson
 				runtime.sync!
 			when "prune"
 				runtime.prune!
+			when "prune:all"
+				runtime.prune_all!
+			when "worktree:remove"
+				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ) )
 			when "onboard"
 				runtime.onboard!
 			when "refresh"

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

@@ -115,6 +115,48 @@ module Carson
 				failed.zero? ? EXIT_OK : EXIT_ERROR
 			end
 
+			def prune_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Prune all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				succeeded = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						failed += 1
+						next
+					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!
+						unless verbose?
+							summary = buf.string.lines.last.to_s.strip
+							puts_line "#{repo_name}: #{summary.empty? ? 'OK' : summary}"
+						end
+						status == EXIT_ERROR ? ( failed += 1 ) : ( succeeded += 1 )
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Prune all complete: #{succeeded} pruned, #{failed} failed."
+				failed.zero? ? EXIT_OK : EXIT_ERROR
+			end
+
 			# Removes Carson-managed repository integration so a host repository can retire Carson cleanly.
 			def offboard!
 				puts_verbose ""

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

@@ -25,11 +25,15 @@ module Carson
 				puts_verbose "prune_summary: deleted=#{counters.fetch( :deleted )} skipped=#{counters.fetch( :skipped )}"
 				unless verbose?
 					deleted_count = counters.fetch( :deleted )
-					if deleted_count.zero?
-						puts_line "No stale branches."
+					skipped_count = counters.fetch( :skipped )
+					message = if deleted_count > 0 && skipped_count > 0
+						"Pruned #{deleted_count}, skipped #{skipped_count} (--verbose for details)."
+					elsif deleted_count > 0
+						"Pruned #{deleted_count} stale branch#{plural_suffix( count: deleted_count )}."
 					else
-						puts_line "Pruned #{deleted_count} stale branch#{plural_suffix( count: deleted_count )}."
+						"Skipped #{skipped_count} branch#{plural_suffix( count: skipped_count )} (--verbose for details)."
 					end
+					puts_line message
 				end
 				EXIT_OK
 			end
@@ -93,7 +97,7 @@ module Carson
 				)
 				return prune_force_delete_skipped( branch: branch, upstream: upstream, delete_error_text: delete_error_text, force_error: force_error ) if merged_pr.nil?
 
-				force_stdout, force_stderr, force_success, = git_run( "branch", "-D", branch )
+				force_stdout, force_stderr, force_success = force_delete_local_branch( branch: branch )
 				return prune_force_delete_success( branch: branch, upstream: upstream, merged_pr: merged_pr, force_stdout: force_stdout ) if force_success
 
 				prune_force_delete_failed( branch: branch, upstream: upstream, force_stderr: force_stderr )
@@ -122,6 +126,37 @@ module Carson
 				text.empty? ? "unknown error" : text
 			end
 
+			# Attempts git branch -D. If blocked by a worktree, safely removes the worktree
+			# first (no --force — refuses if worktree has uncommitted changes) and retries.
+			def force_delete_local_branch( branch: )
+				stdout, stderr, success, = git_run( "branch", "-D", branch )
+				return [ stdout, stderr, success ] if success
+				return [ stdout, stderr, false ] unless worktree_blocked_error?( error_text: stderr )
+
+				wt_path = worktree_path_for_branch( branch: branch )
+				return [ stdout, stderr, false ] if wt_path.nil?
+
+				rm_stdout, rm_stderr, rm_success, = git_run( "worktree", "remove", wt_path )
+				unless rm_success
+					error_text = rm_stderr.to_s.strip
+					puts_verbose "skip_worktree_remove: #{wt_path} (branch=#{branch}) reason=#{error_text}"
+					return [ stdout, stderr, false ]
+				end
+				puts_verbose "worktree_removed_for_prune: #{wt_path} (branch=#{branch})"
+
+				git_run( "branch", "-D", branch )
+			end
+
+			def worktree_blocked_error?( error_text: )
+				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.
+			def worktree_path_for_branch( branch: )
+				entry = worktree_list.find { |wt| wt.fetch( :branch, nil ) == branch }
+				entry&.fetch( :path, nil )
+			end
+
 			# Detects local branches whose upstream tracking is marked [gone] after fetch --prune.
 			def stale_local_branches
 				git_capture!( "for-each-ref", "--format=%(refname:short)\t%(upstream:short)\t%(upstream:track)", "refs/heads" ).lines.map do |line|
@@ -218,7 +253,7 @@ module Carson
 					return :skipped
 				end
 
-				force_stdout, force_stderr, force_success, = git_run( "branch", "-D", branch )
+				force_stdout, force_stderr, force_success = force_delete_local_branch( branch: branch )
 				unless force_success
 					error_text = normalise_branch_delete_error( error_text: force_stderr )
 					puts_verbose "fail_delete_absorbed_branch: #{branch} reason=#{error_text}"
@@ -287,7 +322,7 @@ module Carson
 					return :skipped
 				end
 
-				force_stdout, force_stderr, force_success, = git_run( "branch", "-D", branch )
+				force_stdout, force_stderr, force_success = force_delete_local_branch( branch: branch )
 				if force_success
 					out.print force_stdout if verbose? && !force_stdout.empty?
 					puts_verbose "deleted_orphan_branch: #{branch} merged_pr=#{merged_pr.fetch( :url )}"

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

@@ -0,0 +1,103 @@
+module Carson
+	class Runtime
+		module Local
+			# Safe worktree lifecycle management for coding agents.
+			# Enforces the teardown order: exit worktree → git worktree remove → branch cleanup.
+			def worktree_remove!( worktree_path: )
+				fingerprint_status = block_if_outsider_fingerprints!
+				return fingerprint_status unless fingerprint_status.nil?
+
+				resolved_path = resolve_worktree_path( worktree_path: worktree_path )
+
+				unless worktree_registered?( path: resolved_path )
+					puts_line "ERROR: #{resolved_path} is not a registered worktree."
+					puts_line "  Registered worktrees:"
+					worktree_list.each { |wt| puts_line "  - #{wt.fetch( :path )} [#{wt.fetch( :branch )}]" }
+					return EXIT_ERROR
+				end
+
+				branch = worktree_branch( path: resolved_path )
+				puts_verbose "worktree_remove: path=#{resolved_path} branch=#{branch}"
+
+				# Step 1: remove the worktree (directory + git registration).
+				rm_stdout, rm_stderr, rm_success, = git_run( "worktree", "remove", "--force", resolved_path )
+				unless rm_success
+					error_text = rm_stderr.to_s.strip
+					error_text = "unable to remove worktree" if error_text.empty?
+					puts_line "ERROR: #{error_text}"
+					return EXIT_ERROR
+				end
+				puts_verbose "worktree_removed: #{resolved_path}"
+
+				# Step 2: delete the local branch.
+				if branch && !config.protected_branches.include?( branch )
+					_, del_stderr, del_success, = git_run( "branch", "-D", branch )
+					if del_success
+						puts_verbose "branch_deleted: #{branch}"
+					else
+						puts_verbose "branch_delete_skipped: #{branch} reason=#{del_stderr.to_s.strip}"
+					end
+				end
+
+				# Step 3: delete the remote branch (best-effort).
+				if branch && !config.protected_branches.include?( branch )
+					remote_branch = branch
+					git_run( "push", config.git_remote, "--delete", remote_branch )
+					puts_verbose "remote_branch_deleted: #{config.git_remote}/#{remote_branch}"
+				end
+
+				unless verbose?
+					puts_line "Worktree removed: #{File.basename( resolved_path )}"
+				end
+				EXIT_OK
+			end
+
+		private
+
+			# Resolves a worktree path: if it's a bare name, look under .claude/worktrees/.
+			def resolve_worktree_path( worktree_path: )
+				return File.expand_path( worktree_path ) if worktree_path.include?( "/" )
+
+				candidate = File.join( repo_root, ".claude", "worktrees", worktree_path )
+				return candidate if Dir.exist?( candidate )
+
+				File.expand_path( worktree_path )
+			end
+
+			# Returns true if the path is a registered git worktree.
+			def worktree_registered?( path: )
+				worktree_list.any? { |wt| wt.fetch( :path ) == path }
+			end
+
+			# Returns the branch name checked out in a worktree, or nil.
+			def worktree_branch( path: )
+				entry = worktree_list.find { |wt| wt.fetch( :path ) == path }
+				entry&.fetch( :branch, nil )
+			end
+
+			# Parses `git worktree list --porcelain` into structured entries.
+			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 ] = line.sub( "worktree ", "" )
+					elsif line.start_with?( "branch " )
+						current[ :branch ] = line.sub( "branch refs/heads/", "" )
+					elsif line == "detached"
+						current[ :branch ] = nil
+					end
+				end
+				entries << current unless current.empty?
+				entries
+			end
+		end
+
+		include Local
+	end
+end

data/lib/carson/runtime/local.rb

@@ -3,6 +3,7 @@ require_relative "local/prune"
 require_relative "local/template"
 require_relative "local/hooks"
 require_relative "local/onboard"
+require_relative "local/worktree"
 
 module Carson
 	class Runtime

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.30.0
+  version: 2.32.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -59,6 +59,7 @@ files:
 - lib/carson/runtime/local/prune.rb
 - lib/carson/runtime/local/sync.rb
 - lib/carson/runtime/local/template.rb
+- lib/carson/runtime/local/worktree.rb
 - lib/carson/runtime/review.rb
 - lib/carson/runtime/review/data_access.rb
 - lib/carson/runtime/review/gate_support.rb