carson 3.10.0 → 3.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0a28061ca9078e4ba0cf70626b209da67a9b85b6af31414d2a98e7f7e7abd36
-  data.tar.gz: de84e7e100d34a35ca9d844e34235eaf2e5b9dcf5071d2b651f28ee4bf83d3e6
+  metadata.gz: d2734c0dc1bc4bdea4f81fe024fce1f92aa303d47eec26c7c9ef5370260a83ef
+  data.tar.gz: 7f16d9206694d8f448817dc7b9b5e034354ac222f082774b281b8f8a2ac9a482
 SHA512:
-  metadata.gz: 42ac93cfe9c110636f1327e2cf0a1cbd1fc4ad1cb258d745e3c487984153f95e3ec5ebe70016214d8f8a63de3ee13c8a248afedd6a6710277019011f5cf995d2
-  data.tar.gz: a64696f982dbe5947a333cf0fd2c94744a739b26dde0a60593f322a368ea9a6b371e6901007c762c012a810fbcb2702fcfc23d8b9543c51ffa966d4a83b97b6f
+  metadata.gz: 3a498a739c2b113e41fa9980a89e5de218520bb3f53b4521d1bc7a706f7a5890a193b6650b724b0671f8b1ec66d4865a94ea2f64ac24328034ffb9b07cefd7df
+  data.tar.gz: f7db7bc6d8e00580aecd53f7d0e3e35d511a2d39df5a84cff90a98d60ccfed2efa731f5902ee9f362d3afe4b4b4e78e8ae44b6c6b31f2ff545903611e9836e85

data/RELEASE.md

@@ -5,6 +5,31 @@ 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.10.2
+
+### What changed
+
+- **Path normalisation** — all worktree path comparisons now use `File.realpath` to handle symlink differences (e.g. `/tmp` → `/private/tmp` on macOS). Fixes worktree recognition failures in `worktree done`, `worktree remove`, and `status` where Git returns canonical paths that differ from Carson's internal paths.
+- **deliver --merge post-merge sync** — `sync_after_merge!` now pulls into the main worktree via `git -C` instead of attempting `git checkout main` (which always fails inside a feature worktree). Also adds a review gate check before merge (blocks on `CHANGES_REQUESTED`), marks the worktree done in session state after merge, and records sync result in structured output.
+- **Worktree repo pollution** — `worktree create` now auto-adds `.claude/` to `.git/info/exclude` (local-only, never committed) so worktree directories do not appear as untracked files in the host repository. Idempotent and outsider-safe.
+- **Worktree done push guard** — `worktree done` now blocks when a branch has unique unpushed commits and no remote ref exists. Previously the guard silently passed due to a `Process::Status` truthiness bug (`Open3.capture3` returns a Status object that is always truthy; now uses `.success?`). Branches with no unique commits (just created, no work done) are allowed through.
+
+### UX
+
+- `deliver --merge --json` output now includes `review`, `synced`, and optionally `sync_error` fields.
+- `worktree done` error messages distinguish "branch has not been pushed" from "worktree has unpushed commits", with specific recovery commands for each.
+- Host repositories stay clean after worktree creation — no more `?? .claude/` in `git status`.
+
+### Migration
+
+- No breaking changes. All fixes are backwards-compatible improvements to existing behaviour.
+
+## 3.10.1
+
+### What changed
+
+- **CWD guard recovery points to main worktree** — the recovery command in the CWD safety block now uses `git rev-parse --git-common-dir` to find the main repository root, not the current worktree's root. Previously, when invoked from inside a worktree, the recovery command would `cd` back to the worktree itself instead of the main repo.
+
 ## 3.10.0 — CWD Safety Guard
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.10.0
+3.10.2

data/lib/carson/runtime/deliver.rb

@@ -51,7 +51,7 @@ module Carson
 
 				case ci_status
 				when :pass
-					# Continue to merge.
+					# Continue to review gate.
 				when :pending
 					result[ :recovery ] = "gh pr checks #{pr_number} --watch && carson deliver --merge"
 					return deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
@@ -63,14 +63,26 @@ module Carson
 					return deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
 				end
 
-				# Step 4: merge.
+				# Step 4: check review gate — block if changes are requested.
+				review = check_pr_review( number: pr_number )
+				result[ :review ] = review.to_s
+				if review == :changes_requested
+					result[ :error ] = "review changes requested on PR ##{pr_number}"
+					result[ :recovery ] = "address review comments, push, then `carson deliver --merge`"
+					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
+				end
+
+				# Step 5: merge.
 				merge_exit = merge_pr!( number: pr_number, result: result )
 				return deliver_finish( result: result, exit_code: merge_exit, json_output: json_output ) unless merge_exit == EXIT_OK
 
 				result[ :merged ] = true
 
-				# Step 5: sync main.
-				sync_after_merge!( remote: remote, main: main )
+				# Step 6: mark worktree done in session state.
+				update_session( worktree: :clear )
+
+				# Step 7: sync main in the main worktree.
+				sync_after_merge!( remote: remote, main: main, result: result )
 
 				deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
 			end
@@ -225,6 +237,24 @@ module Carson
 				:pass
 			end
 
+			# Checks review decision on a PR. Returns :approved, :changes_requested, :review_required, or :none.
+			def check_pr_review( number: )
+				stdout, _, success, = gh_run(
+					"pr", "view", number.to_s,
+					"--json", "reviewDecision"
+				)
+				return :none unless success
+
+				data = JSON.parse( stdout ) rescue {}
+				decision = data[ "reviewDecision" ].to_s.strip.upcase
+				case decision
+				when "APPROVED" then :approved
+				when "CHANGES_REQUESTED" then :changes_requested
+				when "REVIEW_REQUIRED" then :review_required
+				else :none
+				end
+			end
+
 			# Merges the PR using the configured merge method.
 			def merge_pr!( number:, result: )
 				method = config.govern_merge_method
@@ -248,10 +278,22 @@ module Carson
 			end
 
 			# Syncs main after a successful merge.
-			def sync_after_merge!( remote:, main: )
-				git_run( "checkout", main )
-				git_run( "pull", remote, main )
-				puts_verbose "synced #{main} from #{remote}"
+			# Pulls into the main worktree directly — does not attempt checkout,
+			# because checkout would fail when running inside a feature worktree
+			# (main is already checked out in the main tree).
+			def sync_after_merge!( remote:, main:, result: )
+				main_root = main_worktree_root
+				_, pull_stderr, pull_success, = Open3.capture3(
+					"git", "-C", main_root, "pull", "--ff-only", remote, main
+				)
+				if pull_success
+					result[ :synced ] = true
+					puts_verbose "synced #{main} in #{main_root} from #{remote}"
+				else
+					result[ :synced ] = false
+					result[ :sync_error ] = pull_stderr.to_s.strip
+					puts_verbose "sync failed: #{pull_stderr.to_s.strip}"
+				end
 			end
 		end
 

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

@@ -23,6 +23,10 @@ module Carson
 				# Determine the base branch (main branch from config).
 				base = config.main_branch
 
+				# 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!
+
 				# Create the worktree with a new branch based on the main branch.
 				FileUtils.mkdir_p( worktrees_dir )
 				_, wt_stderr, wt_success, = git_run( "worktree", "add", wt_path, "-b", name, base )
@@ -69,8 +73,8 @@ module Carson
 				end
 
 				# Check for uncommitted changes in the worktree.
-				wt_status, _, status_success, = Open3.capture3( "git", "status", "--porcelain", chdir: resolved_path )
-				if status_success && !wt_status.strip.empty?
+				wt_status, _, status_result, = Open3.capture3( "git", "status", "--porcelain", chdir: resolved_path )
+				if status_result.success? && !wt_status.strip.empty?
 					return worktree_finish(
 						result: { command: "worktree done", status: "block", name: name,
 							error: "worktree has uncommitted changes",
@@ -80,12 +84,27 @@ module Carson
 				end
 
 				# Check for unpushed commits.
+				# If the remote branch does not exist, check whether the branch has unique commits
+				# versus the main branch. If it does, block — the work exists only locally.
+				# If the branch has no unique commits (just created, no work done), allow.
+				# Note: Open3.capture3 returns Process::Status (always truthy), so .success? is required.
 				branch = worktree_branch( path: resolved_path )
 				if branch
 					remote = config.git_remote
 					remote_ref = "#{remote}/#{branch}"
-					ahead, _, ahead_ok, = Open3.capture3( "git", "rev-list", "--count", "#{remote_ref}..#{branch}", chdir: resolved_path )
-					if ahead_ok && ahead.strip.to_i > 0
+					ahead, _, ahead_status, = Open3.capture3( "git", "rev-list", "--count", "#{remote_ref}..#{branch}", chdir: resolved_path )
+					if !ahead_status.success?
+						# Remote ref does not exist. Only block if the branch has unique commits vs main.
+						unique, _, unique_status, = Open3.capture3( "git", "rev-list", "--count", "#{config.main_branch}..#{branch}", chdir: resolved_path )
+						if unique_status.success? && unique.strip.to_i > 0
+							return worktree_finish(
+								result: { command: "worktree done", status: "block", name: name, branch: branch,
+									error: "branch has not been pushed to #{remote}",
+									recovery: "git -C #{resolved_path} push -u #{remote} #{branch}" },
+								exit_code: EXIT_BLOCK, json_output: json_output
+							)
+						end
+					elsif ahead.strip.to_i > 0
 						return worktree_finish(
 							result: { command: "worktree done", status: "block", name: name, branch: branch,
 								error: "worktree has unpushed commits",
@@ -136,10 +155,11 @@ module Carson
 				# Safety: refuse if the caller's shell CWD is inside the worktree.
 				# Removing a directory while a shell is inside it kills the shell permanently.
 				if cwd_inside_worktree?( worktree_path: resolved_path )
+					safe_root = main_worktree_root
 					return worktree_finish(
 						result: { command: "worktree remove", status: "block", name: File.basename( resolved_path ),
 							error: "current working directory is inside this worktree",
-							recovery: "cd #{repo_root} && carson worktree remove #{File.basename( resolved_path )}" },
+							recovery: "cd #{safe_root} && carson worktree remove #{File.basename( resolved_path )}" },
 						exit_code: EXIT_BLOCK, json_output: json_output
 					)
 				end
@@ -249,36 +269,77 @@ module Carson
 			# Returns true when the process CWD is inside the given worktree path.
 			# This detects the most common session-crash scenario: removing a worktree
 			# while the caller's shell is inside it.
+			# Uses realpath on both sides to handle symlink differences (e.g. /tmp vs /private/tmp).
 			def cwd_inside_worktree?( worktree_path: )
-				cwd = Dir.pwd
-				normalised_wt = File.join( worktree_path, "" )
-				cwd == worktree_path || cwd.start_with?( normalised_wt )
+				cwd = realpath_safe( Dir.pwd )
+				wt = realpath_safe( worktree_path )
+				normalised_wt = File.join( wt, "" )
+				cwd == wt || cwd.start_with?( normalised_wt )
 			rescue StandardError
 				false
 			end
 
+			# Returns the main (non-worktree) repository root.
+			# Uses git-common-dir to find the shared .git directory, then takes its parent.
+			# Falls back to repo_root if detection fails.
+			def main_worktree_root
+				common_dir, _, success, = git_run( "rev-parse", "--path-format=absolute", "--git-common-dir" )
+				return File.dirname( common_dir.strip ) if success && !common_dir.strip.empty?
+
+				repo_root
+			end
+
+			# Adds .claude/ to .git/info/exclude if not already present.
+			# This prevents worktree directories from appearing as untracked files
+			# in the host repository. Uses the local exclude file (never committed)
+			# so the host repo's .gitignore is never touched.
+			def ensure_claude_dir_excluded!
+				git_dir = File.join( repo_root, ".git" )
+				return unless File.directory?( git_dir )
+
+				info_dir = File.join( git_dir, "info" )
+				exclude_path = File.join( info_dir, "exclude" )
+
+				FileUtils.mkdir_p( info_dir )
+				existing = File.exist?( exclude_path ) ? File.read( exclude_path ) : ""
+				return if existing.lines.any? { |line| line.strip == ".claude/" }
+
+				File.open( exclude_path, "a" ) { |f| f.puts ".claude/" }
+			rescue StandardError
+				# 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).
 			def resolve_worktree_path( worktree_path: )
-				return File.expand_path( worktree_path ) if worktree_path.include?( "/" )
+				if worktree_path.include?( "/" )
+					return realpath_safe( worktree_path )
+				end
 
 				candidate = File.join( repo_root, ".claude", "worktrees", worktree_path )
-				return candidate if Dir.exist?( candidate )
+				return realpath_safe( candidate ) if Dir.exist?( candidate )
 
-				File.expand_path( worktree_path )
+				realpath_safe( worktree_path )
 			end
 
 			# Returns true if the path is a registered git worktree.
+			# Compares using realpath to handle symlink differences.
 			def worktree_registered?( path: )
-				worktree_list.any? { |wt| wt.fetch( :path ) == path }
+				canonical = realpath_safe( path )
+				worktree_list.any? { |wt| wt.fetch( :path ) == canonical }
 			end
 
 			# Returns the branch name checked out in a worktree, or nil.
+			# Compares using realpath to handle symlink differences.
 			def worktree_branch( path: )
-				entry = worktree_list.find { |wt| wt.fetch( :path ) == path }
+				canonical = realpath_safe( path )
+				entry = worktree_list.find { |wt| wt.fetch( :path ) == canonical }
 				entry&.fetch( :branch, nil )
 			end
 
 			# Parses `git worktree list --porcelain` into structured entries.
+			# Normalises paths with realpath so comparisons work across symlink differences.
 			def worktree_list
 				output = git_capture!( "worktree", "list", "--porcelain" )
 				entries = []
@@ -289,7 +350,7 @@ module Carson
 						entries << current unless current.empty?
 						current = {}
 					elsif line.start_with?( "worktree " )
-						current[ :path ] = line.sub( "worktree ", "" )
+						current[ :path ] = realpath_safe( line.sub( "worktree ", "" ) )
 					elsif line.start_with?( "branch " )
 						current[ :branch ] = line.sub( "branch refs/heads/", "" )
 					elsif line == "detached"
@@ -299,6 +360,14 @@ module Carson
 				entries << current unless current.empty?
 				entries
 			end
+
+			# Resolves a path to its canonical form, tolerating non-existent paths.
+			# Falls back to File.expand_path when the path does not exist yet.
+			def realpath_safe( path )
+				File.realpath( path )
+			rescue Errno::ENOENT
+				File.expand_path( path )
+			end
 		end
 
 		include Local

data/lib/carson/runtime/status.rb

@@ -88,7 +88,9 @@ module Carson
 				ownership = build_worktree_ownership( sessions: sessions )
 
 				# Filter out the main worktree (the repository root itself).
-				entries.reject { |wt| wt.fetch( :path ) == repo_root }.map do |wt|
+				# Use realpath for comparison — git returns canonical paths that may differ from repo_root.
+				canonical_root = realpath_safe( repo_root )
+				entries.reject { |wt| wt.fetch( :path ) == canonical_root }.map do |wt|
 					name = File.basename( wt.fetch( :path ) )
 					info = {
 						path: wt.fetch( :path ),

metadata

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