carson 3.15.0 → 3.15.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83272d790537e52d22639bbf4831f772496b9ffa5938b23da6d2865ae73d8e38
-  data.tar.gz: ff4d8db79fc54bcd12d74a4c6c74332861ea58dc3fef78f93b3188237d27c772
+  metadata.gz: 4f08f650218ee09489aea34bf1525c486827ccfd97f7c3b60ff413ac9a6e072f
+  data.tar.gz: fc443ff963e9f864b067ce2ab100988e23588c8719237ec0d980d1d0d33d56ec
 SHA512:
-  metadata.gz: 655f2cb1f8caa036e96dc17e4e360ced9256840ee5f2050d33e9f72f4187a2f0d8fefbe27d82ff2da8e3bd21f5c8bb460886bf31af922818fa74efeb3fe9d59f
-  data.tar.gz: 44490df6057142b3f58745ac24041e501207599684d9a10816ee505ed192c681661fd4e23003d637a6ccf69f4a86efbd6d754ada2d6079ee99db89b431133495
+  metadata.gz: b9a84fb14af25a2c821c17716d4cf9ca68ee0b40d294d038d013496c6861e0e9d9b83f9f0cb6135ec8ea1162b497c356b78562054e0092e16d134204e761f512
+  data.tar.gz: 8343c8fcda3a6c6aeae5d25bb7ab563c9c52730ea609a1ddc1d06c4daff898cc97dbe64cf93999a01175663b1a2a55cc5016f5f7842a4fa926504e17dfafb90b

data/MANUAL.md

@@ -142,6 +142,8 @@ carson prune
 
 After squash or rebase merge, the content matches main — removal proceeds without `--force`.
 
+**Stale worktree recovery** — if a worktree directory is destroyed externally (e.g. by running `gh pr merge --delete-branch` from inside it), `worktree remove` and `prune` handle the stale entry gracefully: they clean up the git registration and delete the branch without error. Use `carson deliver --merge` instead of raw `gh pr merge --delete-branch` to avoid this situation — `deliver` deliberately omits `--delete-branch` so the worktree directory stays intact for orderly cleanup.
+
 ### Carson vs Claude Code EnterWorktree
 
 Claude Code has a built-in `EnterWorktree` tool. Both create a git worktree under `.claude/worktrees/` with a new branch — but they solve different problems and have different trade-offs.

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`.
 
+## 3.15.2
+
+### What changed
+
+- **Stale worktree handling** — `worktree remove` and `prune` now handle missing worktree directories gracefully. When a worktree directory is destroyed externally (e.g. by `gh pr merge --delete-branch`), Carson prunes the stale git entry and cleans up the branch without error. Fixes #189, #190.
+- `resolve_worktree_path` always resolves bare names under `.claude/worktrees/`, even when the directory no longer exists.
+- `prune!` runs `git worktree prune` early to clear stale entries before listing branches — unblocks deletion for branches held by dead worktrees.
+- `reap_dead_worktrees!` detects and prunes worktrees whose directories are already gone.
+
+### UX improvement
+
+- Added safety note to MANUAL.md: use `carson deliver --merge` instead of raw `gh pr merge --delete-branch` from inside worktrees.
+
+## 3.15.1
+
+### What changed
+
+- **Dead worktree reaping** — `housekeep` now reaps dead worktrees before pruning. Unblocks prune for branches held by stale worktrees.
+- Two-layer dead check: fast content-absorbed test, then definitive merged-PR evidence via GitHub API. Covers simple merges and rebase/squash cases where main has evolved.
+- Safe removal only — refuses dirty working trees (`git worktree remove` without `--force`).
+- Deletes the local branch after removal (unless protected).
+
 ## 3.15.0
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.15.0
+3.15.2

data/lib/carson/runtime/housekeep.rb

@@ -1,8 +1,9 @@
-# Housekeeping — sync + prune for a repository.
+# Housekeeping — sync, reap dead worktrees, and prune for a repository.
 # carson housekeep <repo>  — serve one repo by name or path.
 # carson housekeep         — serve the repo you are standing in.
 # carson housekeep --all   — serve all governed repos.
 require "json"
+require "open3"
 require "stringio"
 
 module Carson
@@ -41,6 +42,59 @@ module Carson
 				housekeep_finish( result: result, exit_code: failed.zero? ? EXIT_OK : EXIT_ERROR, json_output: json_output, results: results, succeeded: succeeded, failed: failed )
 			end
 
+			# Removes dead worktrees — those whose content is on main or with merged PR evidence.
+			# Unblocks prune for the branches they hold.
+			# Two-layer dead check:
+			#   1. Content-absorbed: delegates to sweep_stale_worktrees! (shared, no gh needed).
+			#   2. Merged PR evidence: covers rebase/squash where main has since evolved
+			#      the same files (requires gh).
+			def reap_dead_worktrees!
+				# Layer 1: sweep agent-owned worktrees whose content is on main.
+				sweep_stale_worktrees!
+
+				# Layer 2: merged PR evidence for remaining worktrees.
+				return unless gh_available?
+
+				main_root = main_worktree_root
+				worktree_list.each do |wt|
+					path = wt.fetch( :path )
+					branch = wt.fetch( :branch, nil )
+					next if path == main_root
+					next unless branch
+					next if cwd_inside_worktree?( worktree_path: path )
+
+					# Missing directory: worktree was destroyed externally.
+					# Prune the stale entry and delete the branch immediately.
+					unless Dir.exist?( path )
+						git_run( "worktree", "prune" )
+						puts_verbose "reaped stale worktree entry: #{File.basename( path )} (branch: #{branch})"
+						if !config.protected_branches.include?( branch )
+							git_run( "branch", "-D", branch )
+							puts_verbose "deleted branch: #{branch}"
+						end
+						next
+					end
+
+					tip_sha = git_capture!( "rev-parse", "--verify", branch ).strip rescue nil
+					next unless tip_sha
+
+					merged_pr, = merged_pr_for_branch( branch: branch, branch_tip_sha: tip_sha )
+					next if merged_pr.nil?
+
+					# Remove the worktree (no --force: refuses if dirty working tree).
+					_, _, rm_success, = git_run( "worktree", "remove", path )
+					next unless rm_success
+
+					puts_verbose "reaped dead worktree: #{File.basename( path )} (branch: #{branch})"
+
+					# Delete the local branch now that no worktree holds it.
+					if !config.protected_branches.include?( branch )
+						git_run( "branch", "-D", branch )
+						puts_verbose "deleted branch: #{branch}"
+					end
+				end
+			end
+
 		private
 
 			# Runs sync + prune on one repo and returns the exit code directly.
@@ -64,7 +118,10 @@ module Carson
 				rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: buf, err: err_buf, verbose: verbose? )
 
 				sync_status = rt.sync!
-				prune_status = rt.prune! if sync_status == EXIT_OK
+				if sync_status == EXIT_OK
+					rt.reap_dead_worktrees!
+					prune_status = rt.prune!
+				end
 
 				ok = sync_status == EXIT_OK && prune_status == EXIT_OK
 				unless verbose? || silent

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

@@ -19,6 +19,11 @@ module Carson
 				end
 
 				prune_git!( "fetch", config.git_remote, "--prune", json_output: json_output )
+
+				# Clean stale worktree entries whose directories no longer exist.
+				# Unblocks branch deletion for branches held by dead worktrees.
+				git_run( "worktree", "prune" )
+
 				active_branch = current_branch
 				cwd_branch = cwd_worktree_branch
 				counters = { deleted: 0, skipped: 0 }

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

@@ -7,6 +7,9 @@ module Carson
 	class Runtime
 		module Local
 
+			# Agent directory names whose worktrees Carson may sweep.
+			AGENT_WORKTREE_DIRS = %w[ .claude .codex ].freeze
+
 			# Creates a new worktree under .claude/worktrees/<name> with a fresh branch.
 			# Uses main_worktree_root so this works even when called from inside a worktree.
 			def worktree_create!( name:, json_output: false )
@@ -74,7 +77,13 @@ module Carson
 
 				resolved_path = resolve_worktree_path( worktree_path: worktree_path )
 
-				unless worktree_registered?( path: resolved_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
+
+			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",
@@ -166,8 +175,82 @@ module Carson
 				)
 			end
 
+			# Removes agent-owned worktrees whose branch content is already on main.
+			# Scans AGENT_WORKTREE_DIRS (e.g. .claude/worktrees/, .codex/worktrees/)
+			# under the main repo root. Safe: skips detached HEADs, the caller's CWD,
+			# and dirty working trees (git worktree remove refuses without --force).
+			def sweep_stale_worktrees!
+				main_root = main_worktree_root
+				worktrees = worktree_list
+
+				agent_prefixes = AGENT_WORKTREE_DIRS.filter_map do |dir|
+					full = File.join( main_root, dir, "worktrees" )
+					File.join( realpath_safe( full ), "" ) if Dir.exist?( full )
+				end
+				return if agent_prefixes.empty?
+
+				worktrees.each do |wt|
+					path = wt.fetch( :path )
+					branch = wt.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 unless branch_absorbed_into_main?( branch: branch )
+
+					# Remove the worktree (no --force: refuses if dirty working tree).
+					_, _, rm_success, = git_run( "worktree", "remove", path )
+					next unless rm_success
+
+					puts_verbose "swept stale worktree: #{File.basename( path )} (branch: #{branch})"
+
+					# Delete the local branch now that no worktree holds it.
+					if !config.protected_branches.include?( branch )
+						git_run( "branch", "-D", branch )
+						puts_verbose "deleted branch: #{branch}"
+					end
+				end
+			end
+
 		private
 
+			# Handles removal when the worktree directory is already gone (destroyed
+			# externally by gh pr merge --delete-branch or manual deletion).
+			# Prunes the stale git worktree entry and cleans up the branch.
+			def worktree_remove_missing!( resolved_path:, json_output: )
+				branch = worktree_branch( path: resolved_path )
+				puts_verbose "worktree_remove_missing: path=#{resolved_path} branch=#{branch}"
+
+				# Prune the stale worktree entry from git's registry.
+				git_run( "worktree", "prune" )
+				puts_verbose "pruned stale worktree entry: #{resolved_path}"
+
+				# Delete the local branch.
+				branch_deleted = false
+				if branch && !config.protected_branches.include?( branch )
+					_, _, del_success, = git_run( "branch", "-D", branch )
+					if del_success
+						puts_verbose "branch_deleted: #{branch}"
+						branch_deleted = true
+					end
+				end
+
+				# Delete the remote branch (best-effort).
+				remote_deleted = false
+				if branch && !config.protected_branches.include?( branch )
+					_, _, rd_success, = git_run( "push", config.git_remote, "--delete", branch )
+					if rd_success
+						puts_verbose "remote_branch_deleted: #{config.git_remote}/#{branch}"
+						remote_deleted = true
+					end
+				end
+
+				worktree_finish(
+					result: { command: "worktree remove", status: "ok", name: File.basename( resolved_path ),
+						branch: branch, branch_deleted: branch_deleted, remote_deleted: remote_deleted },
+					exit_code: EXIT_OK, json_output: json_output
+				)
+			end
+
 			# Unified output for worktree results — JSON or human-readable.
 			def worktree_finish( result:, exit_code:, json_output: )
 				result[ :exit_code ] = exit_code
@@ -305,9 +388,11 @@ module Carson
 				# Best-effort — do not block worktree creation if exclude fails.
 			end
 
-			# Resolves a worktree path: if it's a bare name, look under .claude/worktrees/.
-			# Returns the canonical (realpath) form so comparisons against git worktree list succeed,
-			# even when the OS resolves symlinks differently (e.g. /tmp → /private/tmp on macOS).
+			# Resolves a worktree path: if it's a bare name, always resolve under
+			# .claude/worktrees/ — even when the directory no longer exists (e.g. after
+			# gh pr merge --delete-branch deleted it externally).
+			# Returns the canonical (realpath) form so comparisons against git worktree list
+			# succeed, even when the OS resolves symlinks differently (e.g. /tmp → /private/tmp).
 			# Uses main_worktree_root (not repo_root) so resolution works from inside worktrees.
 			def resolve_worktree_path( worktree_path: )
 				if worktree_path.include?( "/" )
@@ -316,9 +401,7 @@ module Carson
 
 				root = main_worktree_root
 				candidate = File.join( root, ".claude", "worktrees", worktree_path )
-				return realpath_safe( candidate ) if Dir.exist?( candidate )
-
-				realpath_safe( worktree_path )
+				realpath_safe( candidate )
 			end
 
 			# Returns true if the path is a registered git worktree.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.15.0
+  version: 3.15.2
 platform: ruby
 authors:
 - Hailei Wang