carson 3.27.1 → 3.29.0

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

@@ -22,6 +22,15 @@ module Carson
 						exit_code: EXIT_BLOCK, json_output: json_output
 					)
 				end
+
+				attachment = ensure_main_attached!
+				unless attachment.fetch( :ok )
+					return sync_finish(
+						result: { command: "sync", status: "block", error: attachment.fetch( :error ), recovery: attachment[ :recovery ] },
+						exit_code: EXIT_BLOCK, json_output: json_output
+					)
+				end
+
 				start_branch = current_branch
 				switched = false
 				sync_git!( "fetch", config.git_remote, "--prune", json_output: json_output )
@@ -186,6 +195,86 @@ module Carson
 				success
 			end
 
+			# Ensures the main worktree is attached to the main branch, not detached HEAD
+			# or on a wrong branch.
+			#
+			# Returns { ok: true } when already attached or successfully reattached.
+			# Returns { ok: false, error: "...", recovery: "..." } when blocked.
+			#
+			# Why this exists: git pull --ff-only on a detached HEAD succeeds (exit 0)
+			# but fast-forwards the detached HEAD instead of updating the local main
+			# branch ref. This means sync_after_merge! can report synced: true while
+			# local main is still stale.
+			def ensure_main_attached!( main_root: nil )
+				main_root ||= repo_root
+				main = config.main_branch
+
+				head_ref, _, head_success, = Open3.capture3( "git", "-C", main_root, "rev-parse", "--abbrev-ref", "HEAD" )
+				return { ok: true } unless head_success
+
+				head_ref = head_ref.strip
+				return { ok: true } if head_ref == main
+
+				if head_ref != "HEAD"
+					# On a wrong branch — switch to main if the tree is clean.
+					status_out, = Open3.capture3( "git", "-C", main_root, "status", "--porcelain" )
+					unless status_out.to_s.strip.empty?
+						return {
+							ok: false,
+							error: "main worktree is on branch #{head_ref} with uncommitted changes, expected #{main}",
+							recovery: "cd #{main_root} && git stash && git switch #{main}"
+						}
+					end
+
+					_, switch_err, switch_status, = Open3.capture3( "git", "-C", main_root, "switch", main )
+					unless switch_status.success?
+						return {
+							ok: false,
+							error: "main worktree is on branch #{head_ref}, could not switch to #{main}: #{switch_err.strip}",
+							recovery: "cd #{main_root} && git switch #{main}"
+						}
+					end
+
+					puts_verbose "switched main worktree from #{head_ref} to #{main}"
+					return { ok: true, reattached: true }
+				end
+
+				# Detached HEAD — check if safe to reattach.
+				detached_sha, = Open3.capture3( "git", "-C", main_root, "rev-parse", "HEAD" )
+				detached_sha = detached_sha.strip
+
+				main_sha, _, main_exists, = Open3.capture3( "git", "-C", main_root, "rev-parse", "--verify", "refs/heads/#{main}" )
+				main_sha = main_sha.strip if main_exists&.success?
+
+				remote = config.git_remote
+				remote_sha, _, remote_exists, = Open3.capture3( "git", "-C", main_root, "rev-parse", "--verify", "refs/remotes/#{remote}/#{main}" )
+				remote_sha = remote_sha.strip if remote_exists&.success?
+
+				safe = ( main_exists&.success? && detached_sha == main_sha ) ||
+					( remote_exists&.success? && detached_sha == remote_sha )
+
+				unless safe
+					short_sha = detached_sha[ 0, 8 ]
+					return {
+						ok: false,
+						error: "main worktree is detached at #{short_sha} which differs from #{main}",
+						recovery: "cd #{main_root} && git switch #{main}"
+					}
+				end
+
+				_, switch_err, switch_status, = Open3.capture3( "git", "-C", main_root, "switch", main )
+				unless switch_status.success?
+					return {
+						ok: false,
+						error: "could not reattach main worktree to #{main}: #{switch_err.strip}",
+						recovery: "cd #{main_root} && git switch #{main}"
+					}
+				end
+
+				puts_verbose "reattached main worktree to #{main}"
+				{ ok: true, reattached: true }
+			end
+
 			# In outsider mode, Carson must not leave Carson-owned fingerprints in host repositories.
 			def block_if_outsider_fingerprints!
 				return nil unless outsider_mode?

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

@@ -14,8 +14,8 @@ module Carson
 			end
 
 			# Removes a worktree: directory, git registration, and branch.
-			def worktree_remove!( worktree_path:, force: false, json_output: false )
-				Worktree.remove!( path: worktree_path, runtime: self, force: force, json_output: json_output )
+			def worktree_remove!( worktree_path:, force: false, skip_unpushed: false, json_output: false )
+				Worktree.remove!( path: worktree_path, runtime: self, force: force, skip_unpushed: skip_unpushed, json_output: json_output )
 			end
 
 			# Removes agent-owned worktrees whose branch content is already on main.
@@ -143,35 +143,21 @@ module Carson
 				return { action: :skip, reason: "held by another process", absorbed: false } if worktree.held_by_other_process?
 				return { action: :reap, reason: "directory missing (destroyed externally)", absorbed: false } unless worktree.exists?
 
-				if worktree.dirty?
-					absorbed = branch_absorbed_into_main?( branch: worktree.branch )
-					return { action: :reap, reason: "dirty worktree with content absorbed into main", absorbed: true, force: true } if absorbed
-					return { action: :skip, reason: "gh CLI not available for PR check", absorbed: false } unless gh_available?
-
-					tip_sha = worktree_branch_tip_sha( branch: worktree.branch )
-					return { action: :skip, reason: "cannot read branch tip SHA", absorbed: false } if tip_sha.nil?
-
-					merged_pr, = merged_pr_for_branch( branch: worktree.branch, branch_tip_sha: tip_sha )
-					return { action: :reap, reason: "dirty worktree with merged #{pr_short_ref( merged_pr.fetch( :url ) )}", absorbed: false, force: true } unless merged_pr.nil?
-
-					return { action: :skip, reason: "dirty worktree", absorbed: false }
-				end
-
 				absorbed = branch_absorbed_into_main?( branch: worktree.branch )
-				return { action: :reap, reason: "content absorbed into main", absorbed: true } if absorbed
-				return { action: :skip, reason: "gh CLI not available for PR check", absorbed: false } unless gh_available?
+				return { action: :skip, reason: "dirty worktree", absorbed: absorbed } if worktree.dirty?
+				return { action: :skip, reason: "gh CLI not available for PR check", absorbed: absorbed } unless gh_available?
 
 				tip_sha = worktree_branch_tip_sha( branch: worktree.branch )
-				return { action: :skip, reason: "cannot read branch tip SHA", absorbed: false } if tip_sha.nil?
+				return { action: :skip, reason: "cannot read branch tip SHA", absorbed: absorbed } if tip_sha.nil?
 
 				merged_pr, = merged_pr_for_branch( branch: worktree.branch, branch_tip_sha: tip_sha )
-				return { action: :reap, reason: "merged #{pr_short_ref( merged_pr.fetch( :url ) )}", absorbed: false } unless merged_pr.nil?
-				return { action: :skip, reason: "open PR exists", absorbed: false } if branch_has_open_pr?( branch: worktree.branch )
+				return { action: :reap, reason: "merged #{pr_short_ref( merged_pr.fetch( :url ) )}", absorbed: absorbed } unless merged_pr.nil?
+				return { action: :skip, reason: "open PR exists", absorbed: absorbed } if branch_has_open_pr?( branch: worktree.branch )
 
 				abandoned_pr, = abandoned_pr_for_branch( branch: worktree.branch, branch_tip_sha: tip_sha )
-				return { action: :reap, reason: "closed abandoned #{pr_short_ref( abandoned_pr.fetch( :url ) )}", absorbed: false } unless abandoned_pr.nil?
+				return { action: :reap, reason: "closed abandoned #{pr_short_ref( abandoned_pr.fetch( :url ) )}", absorbed: absorbed } unless abandoned_pr.nil?
 
-				{ action: :skip, reason: "no evidence to reap", absorbed: false }
+				{ action: :skip, reason: "no evidence to reap", absorbed: absorbed }
 			end
 
 			def worktree_branch_tip_sha( branch: )

data/lib/carson/runtime/local.rb

@@ -1,5 +1,6 @@
 # Aggregates local repository operation modules (sync, prune, hooks, worktree, template).
 require_relative "local/sync"
+require_relative "local/merge_proof"
 require_relative "local/prune"
 require_relative "local/template"
 require_relative "local/hooks"

data/lib/carson/runtime/loop_runner.rb

@@ -0,0 +1,90 @@
+# Shared loop runner for commands that poll on a schedule.
+module Carson
+	class Runtime
+		module LoopRunner
+			LOOP_STOP_SIGNALS = %w[INT TERM].freeze
+			LOOP_SLEEP_SLICE_SECONDS = 0.25
+
+		private
+
+			def run_signal_aware_loop!( loop_name:, loop_seconds:, cycle_line:, sleep_line: nil )
+				cycle_count = 0
+				stop_requested = false
+				previous_handlers = install_loop_stop_handlers! do
+					stop_requested = true
+				end
+
+				loop do
+					break if stop_requested
+
+					cycle_count += 1
+					puts_line ""
+					puts_line cycle_line.call( cycle_count )
+					yield cycle_count
+					break if stop_requested
+
+					puts_line sleep_line.call( loop_seconds ) if sleep_line
+					loop_runner_wait( seconds: loop_seconds ) { stop_requested }
+				end
+
+				puts_line "#{loop_name} loop stopped after #{cycle_count} cycle#{plural_suffix( count: cycle_count )}"
+				EXIT_OK
+			rescue Interrupt
+				puts_line "#{loop_name} loop stopped after #{cycle_count} cycle#{plural_suffix( count: cycle_count )}"
+				EXIT_OK
+			rescue SignalException => exception
+				raise unless graceful_loop_signal?( exception )
+
+				puts_line "#{loop_name} loop stopped after #{cycle_count} cycle#{plural_suffix( count: cycle_count )}"
+				EXIT_OK
+			ensure
+				restore_loop_stop_handlers!( previous_handlers ) if previous_handlers
+			end
+
+			def install_loop_stop_handlers!
+				LOOP_STOP_SIGNALS.each_with_object( {} ) do |signal_name, handlers|
+					handlers[ signal_name ] = loop_runner_trap( signal_name ) { yield signal_name }
+				end
+			end
+
+			def restore_loop_stop_handlers!( previous_handlers )
+				previous_handlers.each do |signal_name, previous_handler|
+					loop_runner_trap( signal_name, previous_handler )
+				end
+			end
+
+			def graceful_loop_signal?( exception )
+				signo = exception.respond_to?( :signo ) ? exception.signo : nil
+				LOOP_STOP_SIGNALS.any? do |signal_name|
+					Signal.list.fetch( signal_name, nil ) == signo
+				end
+			end
+
+			def loop_runner_wait( seconds: )
+				deadline = loop_runner_monotonic_now + seconds.to_f
+				while ( remaining = deadline - loop_runner_monotonic_now ) > 0
+					break if block_given? && yield
+					loop_runner_sleep( [ remaining, LOOP_SLEEP_SLICE_SECONDS ].min )
+				end
+			end
+
+			def loop_runner_trap( signal_name, handler = nil, &block )
+				if handler
+					Signal.trap( signal_name, handler )
+				else
+					Signal.trap( signal_name, &block )
+				end
+			end
+
+			def loop_runner_monotonic_now
+				Process.clock_gettime( Process::CLOCK_MONOTONIC )
+			end
+
+			def loop_runner_sleep( seconds )
+				sleep seconds
+			end
+		end
+
+		include LoopRunner
+	end
+end

data/lib/carson/runtime/status.rb

@@ -54,6 +54,7 @@ module Carson
 			def gather_status
 				repository = repository_record
 				branch = branch_record
+				tracked_delivery = status_branch_delivery( branch_name: branch.name )
 				deliveries = ledger.active_deliveries( repo_path: repository.path )
 				next_delivery_key = deliveries.find( &:ready? )&.key
 
@@ -69,7 +70,9 @@ module Carson
 						worktree: branch.worktree,
 						dirty: working_tree_dirty?,
 						dirty_reason: dirty_worktree_reason,
-						sync: remote_sync_status( branch: branch.name )
+						sync: remote_sync_status( branch: branch.name ),
+						pull_request: status_branch_pull_request( delivery: tracked_delivery ),
+						merge_proof: status_branch_merge_proof( branch_name: branch.name, delivery: tracked_delivery )
 					},
 					worktrees: gather_worktree_summary,
 					branches: deliveries.map { |delivery| status_branch_entry( delivery: delivery, next_to_integrate: delivery.key == next_delivery_key ) },
@@ -150,6 +153,12 @@ module Carson
 				puts_line branch_line
 				worktree_summary = data.fetch( :worktrees )
 				puts_line "Worktrees: #{worktree_summary.fetch( :non_main_count )} tracked outside main — run carson worktree list." if worktree_summary.fetch( :non_main_count ).positive?
+				if (pull_request = branch[ :pull_request ])
+					puts_line pull_request.fetch( :summary )
+				end
+				if branch.fetch( :name ) != config.main_branch && (merge_proof = branch[ :merge_proof ])
+					puts_line "Merge proof: #{merge_proof.fetch( :summary )}"
+				end
 
 				deliveries = data.fetch( :branches )
 				if deliveries.empty?
@@ -194,6 +203,30 @@ module Carson
 				else "sync unknown"
 				end
 			end
+
+			def status_branch_delivery( branch_name: )
+				return nil if branch_name == config.main_branch
+
+				ledger.latest_delivery(
+					repo_path: repository_record.path,
+					branch_name: branch_name
+				)
+			end
+
+			def status_branch_pull_request( delivery: )
+				return nil unless delivery
+
+				pull_request_payload( delivery: delivery )
+			end
+
+			def status_branch_merge_proof( branch_name:, delivery: )
+				return merge_proof_payload( proof: merge_proof_for_branch( branch: branch_name ) ) if branch_name == config.main_branch
+				return nil unless delivery
+
+				return merge_proof_payload( proof: delivery.merge_proof ) if delivery.merge_proof
+
+				merge_proof_payload( proof: merge_proof_for_branch( branch: branch_name ) )
+			end
 		end
 
 		include Status

data/lib/carson/runtime.rb

@@ -33,11 +33,17 @@ module Carson
 			@config = Config.load( repo_root: repo_root )
 			@git_adapter = Adapters::Git.new( repo_root: repo_root )
 			@github_adapter = Adapters::GitHub.new( repo_root: repo_root )
-			@ledger = Ledger.new( path: @config.govern_state_path )
 			@template_sync_result = nil
 		end
 
-		attr_reader :template_sync_result, :ledger
+		attr_reader :template_sync_result
+
+		# Lazy ledger: only constructed when a command actually needs delivery state.
+		# Read-only commands (worktree list, audit, prune, sync) never touch the
+		# govern state lock file.
+		def ledger
+			@ledger ||= Ledger.new( path: @config.govern_state_path )
+		end
 
 	private
 
@@ -364,6 +370,7 @@ end
 
 require_relative "runtime/local"
 require_relative "runtime/audit"
+require_relative "runtime/loop_runner"
 require_relative "runtime/housekeep"
 require_relative "runtime/repos"
 require_relative "runtime/review"

data/lib/carson/worktree.rb

@@ -7,18 +7,20 @@
 require "fileutils"
 require "json"
 require "open3"
+require "pathname"
 
 module Carson
 	class Worktree
 		# Agent directory names whose worktrees Carson may sweep.
 		AGENT_DIRS = %w[ .claude .codex ].freeze
 
-		attr_reader :path, :branch
+		attr_reader :path, :branch, :prunable_reason
 
-		def initialize( path:, branch:, runtime: nil )
+		def initialize( path:, branch:, runtime: nil, prunable_reason: nil )
 			@path = path
 			@branch = branch
 			@runtime = runtime
+			@prunable_reason = prunable_reason
 		end
 
 		# --- Class lifecycle methods ---
@@ -30,21 +32,36 @@ module Carson
 			entries = []
 			current_path = nil
 			current_branch = :unset
+			current_prunable_reason = nil
 			raw.lines.each do |line|
 				line = line.strip
 				if line.empty?
-					entries << new( path: current_path, branch: current_branch == :unset ? nil : current_branch, runtime: runtime ) if current_path
+					entries << new(
+						path: current_path,
+						branch: current_branch == :unset ? nil : current_branch,
+						runtime: runtime,
+						prunable_reason: current_prunable_reason
+					) if current_path
 					current_path = nil
 					current_branch = :unset
+					current_prunable_reason = nil
 				elsif line.start_with?( "worktree " )
 					current_path = runtime.realpath_safe( line.sub( "worktree ", "" ) )
 				elsif line.start_with?( "branch " )
 					current_branch = line.sub( "branch refs/heads/", "" )
 				elsif line == "detached"
 					current_branch = nil
+				elsif line.start_with?( "prunable" )
+					reason = line.sub( "prunable", "" ).strip
+					current_prunable_reason = reason.empty? ? "prunable" : reason
 				end
 			end
-			entries << new( path: current_path, branch: current_branch == :unset ? nil : current_branch, runtime: runtime ) if current_path
+			entries << new(
+				path: current_path,
+				branch: current_branch == :unset ? nil : current_branch,
+				runtime: runtime,
+				prunable_reason: current_prunable_reason
+			) if current_path
 			entries
 		end
 
@@ -79,20 +96,31 @@ module Carson
 			# Determine the base branch (main branch from config).
 			base = runtime.config.main_branch
 
-			# Sync main from remote before branching so the worktree starts
-			# from the latest code. Prevents stale-base merge conflicts later.
-			# Best-effort — if pull fails (non-ff, offline), continue anyway.
+			# Fetch to update the remote tracking ref without mutating the main worktree.
+			# Best-effort — if fetch fails (no remote, offline), branch from local main.
 			main_root = runtime.main_worktree_root
-			_, _, pull_ok, = Open3.capture3( "git", "-C", main_root, "pull", "--ff-only", runtime.config.git_remote, base )
-			runtime.puts_verbose pull_ok.success? ? "synced #{base} before branching" : "sync skipped — continuing from local #{base}"
+			remote = runtime.config.git_remote
+			_, _, fetch_ok, = Open3.capture3( "git", "-C", main_root, "fetch", remote, base )
+			if fetch_ok.success?
+				remote_ref = "#{remote}/#{base}"
+				_, _, ref_ok, = Open3.capture3( "git", "-C", main_root, "rev-parse", "--verify", remote_ref )
+				if ref_ok.success?
+					base = remote_ref
+					runtime.puts_verbose( "branching from #{remote_ref}" ) unless json_output
+				else
+					runtime.puts_verbose( "fetch succeeded but #{remote_ref} not found — branching from local #{runtime.config.main_branch}" ) unless json_output
+				end
+			else
+				runtime.puts_verbose( "fetch skipped — branching from local #{runtime.config.main_branch}" ) unless json_output
+			end
 
 			# Ensure .claude/ is excluded from git status in the host repository.
 			# Uses .git/info/exclude (local-only, never committed) to respect the outsider boundary.
 			ensure_claude_dir_excluded!( runtime: runtime )
 
 			# Create the worktree with a new branch based on the main branch.
-			FileUtils.mkdir_p( worktrees_dir )
-			_, worktree_stderr, worktree_success, = runtime.git_run( "worktree", "add", worktree_path, "-b", name, base )
+			FileUtils.mkdir_p( File.dirname( worktree_path ) )
+			worktree_stdout, worktree_stderr, worktree_success, = runtime.git_run( "worktree", "add", worktree_path, "-b", name, base )
 			unless worktree_success
 				error_text = worktree_stderr.to_s.strip
 				error_text = "unable to create worktree" if error_text.empty?
@@ -104,10 +132,16 @@ module Carson
 			end
 
 			unless creation_verified?( path: worktree_path, branch: name, runtime: runtime )
+				diagnostics = gather_create_diagnostics(
+					git_stdout: worktree_stdout, git_stderr: worktree_stderr,
+					name: name, runtime: runtime
+				)
+				cleanup_partial_create!( path: worktree_path, branch: name, runtime: runtime )
 				return finish(
 					result: { command: "worktree create", status: "error", name: name, path: worktree_path, branch: name,
 						error: "git reported success but Carson could not verify the worktree and branch",
-						recovery: "git worktree list && git branch --list '#{name}'" },
+						recovery: "git worktree list --porcelain && git branch --list '#{name}'",
+						diagnostics: diagnostics },
 					exit_code: Runtime::EXIT_ERROR, runtime: runtime, json_output: json_output
 				)
 			end
@@ -121,7 +155,7 @@ module Carson
 		# Removes a worktree: directory, git registration, and branch.
 		# Never forces removal — if the worktree has uncommitted changes, refuses unless
 		# the caller explicitly passes force: true via CLI --force flag.
-		def self.remove!( path:, runtime:, force: false, json_output: false )
+		def self.remove!( path:, runtime:, force: false, skip_unpushed: false, json_output: false )
 			fingerprint_status = runtime.block_if_outsider_fingerprints!
 			unless fingerprint_status.nil?
 				if json_output
@@ -135,7 +169,7 @@ module Carson
 				return fingerprint_status
 			end
 
-			check = remove_check( path: path, runtime: runtime, force: force )
+			check = remove_check( path: path, runtime: runtime, force: force, skip_unpushed: skip_unpushed )
 			unless check.fetch( :status ) == :ok
 				return finish(
 					result: { command: "worktree remove", status: check.fetch( :result_status ), name: File.basename( check.fetch( :resolved_path ) ),
@@ -213,7 +247,7 @@ module Carson
 		# Preflight guard for worktree removal. Shared by `worktree remove` and
 		# other runtime flows that need to know whether cleanup is safe before
 		# mutating GitHub or branch state.
-		def self.remove_check( path:, runtime:, force: false )
+		def self.remove_check( path:, runtime:, force: false, skip_unpushed: false )
 			resolved_path = resolve_path( path: path, runtime: runtime )
 
 			if !Dir.exist?( resolved_path ) && registered?( path: resolved_path, runtime: runtime )
@@ -273,7 +307,7 @@ module Carson
 				}
 			end
 
-			unless force
+			unless force || skip_unpushed
 				unpushed = branch_unpushed_issue( branch: branch, worktree_path: resolved_path, runtime: runtime )
 				if unpushed
 					return {
@@ -291,10 +325,9 @@ module Carson
 			{ status: :ok, resolved_path: resolved_path, branch: branch, missing: false }
 		end
 
-		# Removes agent-owned worktrees whose branch content is already on main.
-		# Scans AGENT_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).
+		# Removes agent-owned worktrees that the shared cleanup classifier judges
+		# safe to reap. Scans AGENT_DIRS (e.g. .claude/worktrees/, .codex/worktrees/)
+		# under the main repo root.
 		def self.sweep_stale!( runtime: )
 			main_root = runtime.main_worktree_root
 			worktrees = list( runtime: runtime )
@@ -308,11 +341,16 @@ module Carson
 			worktrees.each do |worktree|
 				next unless worktree.branch
 				next unless agent_prefixes.any? { |prefix| worktree.path.start_with?( prefix ) }
-				next if worktree.holds_cwd?
-				next if worktree.held_by_other_process?
-				next unless runtime.branch_absorbed_into_main?( branch: worktree.branch )
 
-				# Remove the worktree (no --force: refuses if dirty working tree).
+				classification = runtime.send( :classify_worktree_cleanup, worktree: worktree )
+				next unless classification.fetch( :action ) == :reap
+
+				unless worktree.exists?
+					remove_missing!( resolved_path: worktree.path, runtime: runtime, json_output: false )
+					next
+				end
+
+				# Remove the worktree (no --force: automatic sweep never force-removes dirty worktrees).
 				_, _, rm_success, = runtime.git_run( "worktree", "remove", worktree.path )
 				next unless rm_success
 
@@ -369,6 +407,10 @@ module Carson
 			Dir.exist?( path )
 		end
 
+		def prunable?
+			!prunable_reason.to_s.strip.empty?
+		end
+
 		def dirty?
 			return false unless exists?
 
@@ -440,7 +482,12 @@ module Carson
 		private_class_method :finish
 
 		def self.creation_verified?( path:, branch:, runtime: )
-			registered?( path: path, runtime: runtime ) && branch_exists?( branch: branch, runtime: runtime )
+			entry = find( path: path, runtime: runtime )
+			return false if entry.nil?
+			return false if entry.prunable?
+			return false unless Dir.exist?( path )
+
+			branch_exists?( branch: branch, runtime: runtime )
 		end
 		private_class_method :creation_verified?
 
@@ -450,6 +497,39 @@ module Carson
 		end
 		private_class_method :branch_exists?
 
+		# Removes partial state left behind when git worktree add reports success
+		# but verification reveals the worktree or branch is incomplete.
+		def self.cleanup_partial_create!( path:, branch:, runtime: )
+			FileUtils.rm_rf( path ) if Dir.exist?( path )
+			runtime.git_run( "worktree", "prune" )
+			runtime.git_run( "branch", "-D", branch ) if branch_exists?( branch: branch, runtime: runtime )
+		end
+		private_class_method :cleanup_partial_create!
+
+		# Captures diagnostic state for a verification failure so the next
+		# incident is self-diagnosing without manual investigation.
+		def self.gather_create_diagnostics( git_stdout:, git_stderr:, name:, runtime: )
+			wt_list, = runtime.git_run( "worktree", "list", "--porcelain" )
+			branch_list, = runtime.git_run( "branch", "--list", name )
+			git_version, = Open3.capture3( "git", "--version" )
+			worktree_path = File.join( runtime.main_worktree_root, ".claude", "worktrees", name )
+			entry = find( path: worktree_path, runtime: runtime )
+			{
+				git_stdout: git_stdout.to_s.strip,
+				git_stderr: git_stderr.to_s.strip,
+				repo_root: runtime.send( :repo_root ),
+				main_worktree_root: runtime.main_worktree_root,
+				worktree_list: wt_list.to_s.strip,
+				branch_list: branch_list.to_s.strip,
+				git_version: git_version.to_s.strip,
+				worktree_directory_exists: Dir.exist?( worktree_path ),
+				registered_worktree: !entry.nil?,
+				prunable_reason: entry&.prunable_reason
+			}
+		end
+		private_class_method :gather_create_diagnostics
+
+
 		# Human-readable output for worktree results.
 		def self.print_human( result:, runtime: )
 			command = result[ :command ]
@@ -519,10 +599,18 @@ module Carson
 		# succeed, even when the OS resolves symlinks differently.
 		# Uses main_worktree_root (not repo_root) so resolution works from inside worktrees.
 		def self.resolve_path( path:, runtime: )
-			if path.include?( "/" )
+			if Pathname.new( path ).absolute?
 				return runtime.realpath_safe( path )
 			end
 
+			relative_candidate = runtime.realpath_safe( File.expand_path( path, Dir.pwd ) )
+			return relative_candidate if registered?( path: relative_candidate, runtime: runtime )
+
+			if path.include?( "/" )
+				scoped_candidate = runtime.realpath_safe( File.join( runtime.main_worktree_root, ".claude", "worktrees", path ) )
+				return scoped_candidate if registered?( path: scoped_candidate, runtime: runtime )
+			end
+
 			root = runtime.main_worktree_root
 			candidate = File.join( root, ".claude", "worktrees", path )
 			canonical = runtime.realpath_safe( candidate )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.27.1
+  version: 3.29.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -83,11 +83,13 @@ files:
 - lib/carson/runtime/housekeep.rb
 - lib/carson/runtime/local.rb
 - lib/carson/runtime/local/hooks.rb
+- lib/carson/runtime/local/merge_proof.rb
 - lib/carson/runtime/local/onboard.rb
 - 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/loop_runner.rb
 - lib/carson/runtime/recover.rb
 - lib/carson/runtime/repos.rb
 - lib/carson/runtime/review.rb
@@ -126,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Autonomous git strategist and repositories governor — you write the code,
   Carson manages everything else.