carson 4.0.1 → 4.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b65ac7c43c1275299430d71f23f1da3a9896b112aa1f57e334222d06282a3a62
-  data.tar.gz: ff4efcd085b8cb0deb4385bfdb40d98407d463547b6e065fbfc455f516cc4dbb
+  metadata.gz: a5678a9b3d25a0a0c6e2b37182e53607b8c41e0a199771bbae7535ec776f71c8
+  data.tar.gz: c744e380475f851bdc142dc13693f3b35a229b93a45fdbc2ecb70e33fd3ba8cc
 SHA512:
-  metadata.gz: b49a0b8760ad230996f6330b378fd7f9a202977c148683c4ae3eec066f2b820f6210e59a0e251ef275471d90db0d8154dee82cc5f97c3e46378cfad1fce074c2
-  data.tar.gz: 64cc150e7bb257ebbd6d48a603ab7eaa3e3b9794f08fcc65625bb8264628cc99e14f5603fe526d7818253ac57169de995cdc71c413c75cc6a3e2b56dbbb41f2c
+  metadata.gz: 136aeaa5ebf42de0f676875a44d8d4bf2eb758b9d70753718ba6cb27ca37756ca42af3518247e1a357c6e5a3bb8cdaa9bbdeff2d1fa9f3fd63302263b4d3c9a1
+  data.tar.gz: db5026a393f292c7dee8e1a6b3d63ec4463bcaebea179161ceb184271826d0c1a803bfc9a6a31f6cc5d7446f10be3e52739bebfbb70c548a8cb607fd1f57e4ae

data/RELEASE.md

@@ -11,6 +11,23 @@ Release-note scope rule:
 
 - CLI grammar is now two-tier: portfolio commands (`list`, `onboard`, `offboard`, `refresh`, `version`) and repo-scoped commands (`carson <repo> <command>` or `carson <command>` from CWD)
 
+## 4.0.3
+
+### Fixed
+
+- **No-checks repos can now merge** (#465) — `Waybill#cleared?` required CI to pass, but repos with no CI checks returned `:none`. These repos were permanently held. Now `:none` is treated as non-blocking.
+- **Sync failure reported explicitly** — When local main fails to sync after a merge, `carson deliver` now prints "Local main not synced — run carson sync." instead of silently omitting the line.
+- **Freshness fetch failure blocks delivery** — `Courier#deliver` ignored the return value of `fetch_latest`. If the fetch failed (network error), Carson reasoned from stale refs. Now blocks immediately with "cannot verify freshness — fetch failed" and Carson-first recovery.
+- **PR data reaches the ledger** — The Courier's `record` method hardcoded `pr_number: nil` and `pr_url: nil`. Filed deliveries had no PR reference in the ledger. Now passes waybill tracking number and URL.
+
+## 4.0.2
+
+### Fixed
+
+- **Seal marker moved outside worktree** — `.carson-delivering` marker now lives at `~/.carson/seals/` instead of inside the worktree. The in-worktree marker polluted `git status`, showed as untracked in editors, and blocked `carson deliver` via the dirty-tree guard. Seal file includes the worktree path for debugging.
+- **`receive_latest_standard!` works from worktrees** (#451) — `git fetch origin main:main` failed when `main` was checked out in the main worktree ("fatal: refusing to fetch into branch checked out"). Now uses `merge --ff-only` when main is checked out, fetch refspec otherwise.
+- **Audit seal check delegates to Warehouse** — `carson audit` no longer hardcodes the marker path; it creates a Warehouse and asks `sealed?`. Single source of truth for seal location.
+
 ## 4.0.1
 
 ### What changed
@@ -34,7 +51,7 @@ Release-note scope rule:
 
 - **`carson deliver` waits for CI and merges automatically** — `carson deliver` now polls GitHub up to 6 times (default 30s interval) instead of checking once and returning immediately. PRs that pass CI are merged without re-running `carson deliver`. Agents that relied on instant return should expect it to block for up to 3 minutes.
 - **Hold reasons renamed** — JSON output field `hold_reason` values changed: `inspector_pending` → `pending_at_registry`, `inspector_failed` → `failed_at_registry`, `inspector_error` → `error_at_registry`. Agents parsing these values must update.
-- **Hold messages include recovery commands** — Human output for held deliveries now shows actionable next steps (e.g. `→ git rebase origin/main` then `→ carson deliver`) instead of prose descriptions.
+- **Hold messages include recovery commands** — Human output for held deliveries now shows actionable next steps (e.g. `→ carson deliver`) instead of prose descriptions.
 
 ### New
 
@@ -63,7 +80,8 @@ Release-note scope rule:
 
 ### What changed
 
-- **Recovery hints re-enter through Carson, not blocked raw commands** — Delivery error recovery messages no longer suggest raw `gh pr create`, `gh pr merge`, or `git rebase` commands. All recovery paths now guide the user back through Carson. Freshness blocks say "refresh this branch onto the target, then `carson deliver`" instead of teaching raw git recipes.
+- **Recovery hints re-enter through Carson, not blocked raw commands** — Delivery error recovery messages no longer suggest raw `gh pr create` or `gh pr merge`. All recovery paths guide the user back through Carson.
+- **Auto-rebase on delivery** — `carson deliver` automatically rebases the branch when it's behind remote main. Only blocks if the rebase hits a conflict. No more manual `git rebase` before delivery.
 - **Fast PR indentation guard restored** — The Ruby indentation guard in CI now correctly handles access modifier detection, fixing false positives that blocked PRs.
 
 ### No migration required

data/VERSION

@@ -1 +1 @@
-4.0.1
+4.0.3

data/lib/carson/courier.rb

@@ -125,12 +125,21 @@ module Carson
 			parcel = Parcel.new( label: parcel.label, head: @warehouse.current_head, shelf: parcel.shelf )
 
 			# 02. Parcel behind standard — not based on client's latest standard.
-			@warehouse.fetch_latest( registry: @warehouse.main_label )
+			#     The courier rebases automatically. Only blocks on conflict.
+			unless @warehouse.fetch_latest( registry: @warehouse.main_label )
+				return blocked( result,
+					"cannot verify freshness — fetch failed",
+					recovery: "carson sync, then carson deliver" )
+			end
 			unless @warehouse.based_on_latest_standard?( parcel )
 				remote_main = "#{@warehouse.bureau_address}/#{@warehouse.main_label}"
-				return blocked( result,
-					"branch is behind #{remote_main}",
-					recovery: "git rebase #{remote_main}, then carson deliver" )
+				say "Branch is behind #{remote_main} — rebasing..."
+				unless @warehouse.rebase_on_latest_standard!
+					return blocked( result,
+						"rebase conflict onto #{remote_main}",
+						recovery: "resolve conflicts, then carson deliver" )
+				end
+				parcel = Parcel.new( label: parcel.label, head: @warehouse.current_head, shelf: parcel.shelf )
 			end
 
 			# Announce the delivery.
@@ -172,7 +181,7 @@ module Carson
 			@warehouse.unseal_shelf! if outcome == "delivered" || outcome == "held" || outcome == "rejected"
 
 			# Update the ledger with the final outcome.
-			record( parcel, status: outcome || "filed", summary: result[ :hold_reason ] )
+			record( parcel, status: outcome || "filed", summary: result[ :hold_reason ], waybill: waybill )
 
 			result[ :exit ] ||= OK
 			result
@@ -254,7 +263,7 @@ module Carson
 
 		# Record a delivery state change in the ledger.
 		# No-op when no ledger is injected (e.g. tests).
-		def record( parcel, status:, summary: nil )
+		def record( parcel, status:, summary: nil, waybill: nil )
 			return unless @ledger
 
 			# The ledger needs a repository-like object with .path pointing
@@ -265,8 +274,8 @@ module Carson
 				branch_name: parcel.label,
 				head: parcel.head,
 				worktree_path: @warehouse.path,
-				pr_number: nil,
-				pr_url: nil,
+				pr_number: waybill&.tracking_number,
+				pr_url: waybill&.url,
 				status: status,
 				summary: summary,
 				cause: nil

data/lib/carson/delivery.rb

@@ -1,7 +1,7 @@
 # Passive ledger record for one branch delivery attempt.
 module Carson
 	class Delivery
-		ACTIVE_STATES = %w[preparing gated queued integrating escalated].freeze
+		ACTIVE_STATES = %w[preparing gated queued integrating escalated filed].freeze
 		BLOCKED_STATES = %w[gated escalated].freeze
 		READY_STATES = %w[queued].freeze
 		TERMINAL_STATES = %w[integrated failed superseded].freeze
@@ -60,6 +60,10 @@ module Carson
 			READY_STATES.include?( status )
 		end
 
+		def filed?
+			status == "filed"
+		end
+
 		def integrated?
 			status == "integrated"
 		end

data/lib/carson/runtime/audit.rb

@@ -185,11 +185,12 @@ module Carson
 
 				# Check if the workbench is sealed (parcel in flight).
 				# Returns EXIT_BLOCK if sealed, nil otherwise.
+				# Delegates to Warehouse so the seal path is resolved in one place.
 				def audit_sealed_workbench( json_output: )
-					marker_path = File.join( work_dir, ".carson-delivering" )
-					return nil unless File.exist?( marker_path )
+					warehouse = Warehouse.new( path: work_dir )
+					return nil unless warehouse.sealed?
 
-					tracking_number = File.read( marker_path ).strip rescue "unknown"
+					tracking_number = warehouse.sealed_tracking_number || "unknown"
 					if json_output
 						require "json"
 						output.puts JSON.pretty_generate( {

data/lib/carson/runtime/deliver.rb

@@ -231,7 +231,7 @@ module Carson
 					when :blocked
 						result[ :outcome ] = "blocked"
 						result[ :waited_seconds ] = elapsed_settle_seconds( started_at: started_at )
-						result[ :recovery ] = "refresh this branch onto #{config.git_remote}/#{main}, then carson deliver" if evaluation[ :cause ] == "freshness"
+						result[ :recovery ] = "carson deliver" if evaluation[ :cause ] == "freshness"
 						apply_handoff!(
 							result: result,
 							reason: evaluation.fetch( :reason ),
@@ -752,7 +752,7 @@ module Carson
 
 			def freshness_recovery( freshness: )
 				remote_ref = freshness.fetch( :remote_ref )
-				return "refresh this branch onto #{remote_ref}, then carson deliver" if freshness.fetch( :status ) == :behind
+				return "carson deliver" if freshness.fetch( :status ) == :behind
 
 				"carson deliver (once #{remote_ref} is reachable)"
 			end
@@ -840,7 +840,7 @@ module Carson
 					reason: "freshness_behind",
 					cause: "freshness",
 					summary: "branch is behind #{remote_main}",
-					recovery: "refresh this branch onto #{remote_main}, then carson deliver"
+					recovery: "carson deliver"
 				} if merge_state == "BEHIND"
 
 				return {

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

@@ -2,6 +2,13 @@
 module Carson
 	class Runtime
 		module Local
+			# Refreshes hooks only — safe to run regardless of worktree or
+			# uncommitted-changes state, because hooks write to ~/.carson/hooks/
+			# and only touch .git/config, not the working tree.
+			def refresh_hooks!
+				prepare!
+			end
+
 		private
 
 			# Installs required hook files and enforces repository hook path.

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

@@ -120,8 +120,14 @@ module Carson
 
 					safety = portfolio_repo_safety( repo_path: repo_path )
 					unless safety.fetch( :safe )
+						# Hooks write to ~/.carson/hooks/, not the repo — always safe to refresh.
+						hooks_status = refresh_hooks_single_repo( repo_path: repo_path )
 						reason = safety.fetch( :reasons ).join( ", " )
-						puts_line "#{repo_name}: PENDING (#{reason})"
+						if hooks_status == EXIT_OK
+							puts_line "#{repo_name}: hooks refreshed, templates pending (#{reason})"
+						else
+							puts_line "#{repo_name}: PENDING (#{reason})"
+						end
 						record_batch_skip( command: "refresh", repo_path: repo_path, reason: reason )
 						pending += 1
 						next
@@ -304,6 +310,16 @@ module Carson
 				EXIT_ERROR
 			end
 
+			# Refreshes hooks only for a governed repo using a scoped Runtime.
+			# Used when the full refresh is blocked by active worktrees or uncommitted
+			# changes — hooks write to ~/.carson/hooks/ and do not touch the working tree.
+			def refresh_hooks_single_repo( repo_path: )
+				scoped_runtime = build_scoped_runtime( repo_path: repo_path )
+				scoped_runtime.refresh_hooks!
+			rescue StandardError
+				EXIT_ERROR
+			end
+
 			def refresh_status_label( status: )
 				case status
 				when EXIT_OK then "OK"

data/lib/carson/runtime/receive.rb

@@ -74,7 +74,23 @@ module Carson
 
 				puts_line "#{repository.name}: #{deliveries.length} active deliver#{deliveries.length == 1 ? 'y' : 'ies'}" unless silent
 
+				# Collect worktree paths of filed deliveries before reconciliation.
+				# Receive takes over lifecycle management — the courier's polling window is over.
+				filed_worktree_paths = deliveries
+					.select( &:filed? )
+					.map( &:worktree_path )
+					.compact
+					.reject { |path| path.to_s.strip.empty? }
+
 				reconciled = deliveries.map { |item| scoped_runtime.send( :reconcile_delivery!, delivery: item ) }
+
+				# Unseal worktrees that were filed — receive now owns the delivery lifecycle.
+				unless dry_run
+					filed_worktree_paths.each do |worktree_path|
+						Warehouse.new( path: worktree_path ).unseal_shelf!
+					end
+				end
+
 				next_to_integrate = reconciled.find( &:ready? )&.key
 
 				reconciled.each do |delivery|

data/lib/carson/warehouse.rb

@@ -2,6 +2,8 @@
 # parcels (committed changes) are stored on shelves (worktrees) with
 # labels (branches). Git commands are hidden inside — callers never
 # see git terms.
+require "digest"
+require "fileutils"
 require "open3"
 
 module Carson
@@ -107,8 +109,12 @@ module Carson
 
 		# Seal the shelf — no more packing until the delivery outcome is confirmed.
 		# The courier seals the shelf after shipping and filing the waybill.
+		# The marker lives outside the worktree (~/.carson/seals/) so it does
+		# not pollute git status or block delivery with a dirty-tree guard.
 		def seal_shelf!( tracking_number: )
-			File.write( delivering_marker_path, tracking_number.to_s )
+			marker = delivering_marker_path
+			FileUtils.mkdir_p( File.dirname( marker ) )
+			File.write( marker, "#{tracking_number}\n#{@path}" )
 		end
 
 		# Unseal the shelf — the courier brought back the parcel.
@@ -125,18 +131,43 @@ module Carson
 		# The tracking number of the in-flight delivery (nil if not sealed).
 		def sealed_tracking_number
 			return nil unless sealed?
-			File.read( delivering_marker_path ).strip
+			File.read( delivering_marker_path ).lines.first.strip
 		end
 
 		# Receive the latest standard from the registry after a parcel is accepted.
 		# Fast-forwards local main without switching branches.
 		# Returns true on success, false on failure.
+		#
+		# Two paths depending on the main worktree's checkout state:
+		# - Main checked out → merge --ff-only (updates ref + working tree).
+		# - Main not checked out → fetch refspec (updates ref only, safe when
+		#   no worktree has the branch).
 		def receive_latest_standard!( remote: bureau_address )
-			_, _, status = Open3.capture3(
-				"git", "-C", main_worktree_root,
-				"fetch", remote, "#{main_label}:#{main_label}"
+			root = main_worktree_root
+
+			# Fetch remote tracking refs — always safe, even when main is checked out.
+			_, _, fetch_status = Open3.capture3( "git", "-C", root, "fetch", remote )
+			return false unless fetch_status.success?
+
+			# Determine how to advance local main.
+			head_ref, _, head_status = Open3.capture3(
+				"git", "-C", root, "rev-parse", "--abbrev-ref", "HEAD"
 			)
-			status.success?
+			return false unless head_status.success?
+
+			if head_ref.strip == @main_label
+				# Main is checked out in the main worktree — fast-forward via merge.
+				_, _, merge_status = Open3.capture3(
+					"git", "-C", root, "merge", "--ff-only", "#{remote}/#{@main_label}"
+				)
+				merge_status.success?
+			else
+				# Main is not checked out — safe to update the ref via fetch refspec.
+				_, _, refspec_status = Open3.capture3(
+					"git", "-C", root, "fetch", remote, "#{@main_label}:#{@main_label}"
+				)
+				refspec_status.success?
+			end
 		end
 
 		# --- Inventory ---
@@ -173,8 +204,12 @@ module Carson
 	private
 
 		# Path to the delivery marker file — signals the shelf is sealed.
+		# Lives outside the worktree at ~/.carson/seals/<sha256-of-path>
+		# so it does not pollute git status.
 		def delivering_marker_path
-			File.join( path, ".carson-delivering" )
+			seals_dir = File.join( Dir.home, ".carson", "seals" )
+			key = Digest::SHA256.hexdigest( @path )
+			File.join( seals_dir, key )
 		end
 
 		# All git commands go through this single gateway.

data/lib/carson/waybill.rb

@@ -98,7 +98,7 @@ module Carson
 		def cleared?
 			return false unless filed?
 			return false if draft?
-			return false unless @ci == :pass
+			return false unless @ci == :pass || @ci == :none
 			return false if merge_conflicting? || merge_behind? || merge_policy_blocked?
 			merge_status = @state&.dig( "mergeStateStatus" ).to_s.upcase
 			mergeable = @state&.dig( "mergeable" ).to_s.upcase

data/lib/carson.rb

@@ -34,7 +34,11 @@ module Carson
 		case result[ :outcome ]
 		when "delivered"
 			output.puts "#{BADGE} Merged."
-			output.puts "#{BADGE} Local main synced." if result[ :synced ]
+			if result[ :synced ]
+				output.puts "#{BADGE} Local main synced."
+			elsif result.key?( :synced )
+				output.puts "#{BADGE} Local main not synced \u2014 run carson sync."
+			end
 		when "held"
 			diagnosis, *recovery_steps = translate_hold( result[ :hold_reason ], remote_main: remote_main )
 			output.puts "#{BADGE} #{diagnosis}"
@@ -64,7 +68,7 @@ module Carson
 		when "merge_conflict"
 			[ "Merge conflict with #{remote_main}.", "git rebase #{remote_main}", "carson deliver" ]
 		when "behind_registry"
-			[ "Branch is behind #{remote_main}.", "git rebase #{remote_main}", "carson deliver" ]
+			[ "Branch is behind #{remote_main}.", "carson deliver" ]
 		when "policy_block"
 			[ "Blocked by branch protection rules." ]
 		when "mergeability_pending"

metadata

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