carson 4.0.0 → 4.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96b7009510f859ab0892bffc34678701dc74412a4f4b9f17f1be3710cb82d0c3
-  data.tar.gz: 236de5bb54d69845b4710b8ffe946a64534a1db5ea068e2a8e34d566d6c438c4
+  metadata.gz: 8bf071658d6db37302910554b54a528ac3efe7faa22a1cb88b42d13faf0b6b30
+  data.tar.gz: 0e30d7ca60c8d8f13438562b003009a64820ff7109ca1c525a127282a5c942c9
 SHA512:
-  metadata.gz: 334f80f636c8285fbb7e3bb4481b99efecf0b69700b337ad03a63cc1b9fb0fe0d1ab49765371aa57ede881958cb0d2d9f9cff9104b50d007352edd94fb1cd22e
-  data.tar.gz: b6a92f602a9d0fdd9b22ba320616c6fe2db66d51230895b88e32962edaa5c43cfcadfe828278afbeb4111585b10d04781708c2d17dcdb03df10320fa1674e6c9
+  metadata.gz: 0d50b557c6e2a29b78d4f82dfedf2f89c4d6eacc68fb561d5684eb7c40582ba43de5ff84b6929c992fd98b5069e1ee15b17fb434f4512b3ea30f94c97a387ae6
+  data.tar.gz: 4cc5c13c062c226ffcfd8627882ecb6c3093169e61dc759d03e2b77110f93323b77bc90761107a8e2a7696b211fe42c603ad0823639c3eb062ff66753410f96b

data/RELEASE.md

@@ -10,6 +10,27 @@ Release-note scope rule:
 ### Breaking
 
 - 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.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
+
+- **Workbench seal** — `carson deliver` seals the workbench after shipping. `pack!` refuses while sealed ("Shelf is sealed — parcel in flight"). `carson audit` blocks `git commit` on sealed workbenches. Delivered/held/rejected unseals; filed stays sealed.
+- **Delivery progress** — `carson deliver` announces what it's doing: "Carson is delivering committed changes on branch X to Y…" and reports each poll check with count.
+- **Seal guard in `carson audit`** — moved from bash hook template to Ruby. The pre-commit hook calls `carson audit` which checks for `.carson-delivering` marker.
+- **`error_at_registry` is transient** — CI assessment errors no longer cause immediate rejection. The courier keeps polling.
+
+### Known limitation
+
+- The workbench seal blocks `git commit` but does not block file edits (Write/Edit tools). That requires Claude Code PreToolUse hooks — a separate enforcement layer.
 - `govern` renamed to `receive` — single-repo only, no portfolio iteration
 - `repos` renamed to `list`
 - `--all` removed from all repo commands; use `carson list --json` to script batch operations
@@ -19,15 +40,14 @@ Release-note scope rule:
 
 ### Breaking
 
-- **Courier waits at the registry** — `carson deliver` now polls the bureau up to 6 times (default 30s interval) instead of checking once and leaving. PRs that pass CI are merged automatically without re-running `carson deliver`. Agents that relied on instant return from `carson deliver` should expect it to block for up to 3 minutes.
+- **`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 recovery steps (e.g. `→ git rebase origin/main` then `→ carson deliver`) instead of prose descriptions.
-- **Bureau model simplified** — No more "customs" or "inspector" in the domain model. The bureau is a registry where bureaucrats check parcels. Internal only — no user-facing impact beyond the hold_reason rename above.
+- **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.
 
 ### New
 
-- **`deliver.poll_interval_at_registry` config** — Controls how long the courier waits between registry checks (default 30 seconds). Override via config or `CARSON_POLL_INTERVAL_AT_REGISTRY` environment variable.
-- **`filed` outcome** — When the courier exhausts all checks without a definitive answer, it reports "filed" with `→ carson status` as the next step, instead of the old "deferred" with `→ carson deliver`.
+- **`deliver.poll_interval_at_registry` config** — Controls how long `carson deliver` waits between CI checks (default 30 seconds). Override via config or `CARSON_POLL_INTERVAL_AT_REGISTRY` environment variable.
+- **`filed` outcome** — When `carson deliver` exhausts all checks without a definitive answer from GitHub, it reports "filed" with `→ carson status` as the next step, instead of the old "deferred" with `→ carson deliver`.
 
 ### Migration
 

data/VERSION

@@ -1 +1 @@
-4.0.0
+4.0.2

data/lib/carson/courier.rb

@@ -15,6 +15,14 @@ module Carson
 	# parcels (CI, review, mergeability) and either accept them into the
 	# registry or hold them with a reason.
 	#
+	# == Shelf seal
+	#
+	# Once the parcel ships and the waybill is filed, the warehouse seals
+	# the shelf. No more packing until the delivery outcome is confirmed.
+	# Delivered → shelf done (housekeep removes it).
+	# Held/rejected → courier unseals (agent can fix and re-deliver).
+	# Filed (checks exhausted) → shelf stays sealed (parcel still in flight).
+	#
 	# == Situations the courier encounters
 	#
 	# Each numbered situation is handled by a specific guard or branch in the
@@ -45,7 +53,8 @@ module Carson
 	# It polls up to MAX_CHECKS_AT_REGISTRY times, pausing between each check.
 	# If the bureaucrats give a definitive answer (accepted or rejected), the
 	# courier acts immediately. If the checks are exhausted without a definitive
-	# answer, the courier reports "filed" — the parcel is still at the registry.
+	# answer, the courier reports "filed" — the parcel is still at the registry
+	# and the shelf stays sealed.
 	#
 	# == Future: destination modes
 	#
@@ -58,18 +67,21 @@ module Carson
 		ERROR = 1
 		BLOCKED = 2
 
+		BADGE = "\u29D3".freeze
+
 		# The courier checks the registry up to 6 times before leaving.
 		MAX_CHECKS_AT_REGISTRY = 6
 
-		def initialize( warehouse, ledger: nil, merge_method: "rebase", poll_interval_at_registry: 30 )
+		def initialize( warehouse, ledger: nil, merge_method: "rebase", poll_interval_at_registry: 30, output: $stdout )
 			@warehouse = warehouse
 			@ledger = ledger
 			@merge_method = merge_method
 			@poll_interval_at_registry = poll_interval_at_registry
+			@output = output
 		end
 
 		# Deliver a parcel to the registry.
-		# Ships it, files a waybill, waits at the registry for the bureaucrats.
+		# Ships it, files a waybill, seals the shelf, waits at the registry.
 		def deliver( parcel, title: nil, body_file: nil, commit_message: nil )
 			result = {
 				command: "deliver",
@@ -121,6 +133,9 @@ module Carson
 					recovery: "git rebase #{remote_main}, then carson deliver" )
 			end
 
+			# Announce the delivery.
+			say "Carson is delivering committed changes on branch #{parcel.label} to #{result[ :remote_main ]}..."
+
 			# The courier picks up the parcel — start tracking.
 			record( parcel, status: "preparing", summary: "delivery accepted" )
 
@@ -144,11 +159,20 @@ module Carson
 			result[ :tracking_number ] = waybill.tracking_number
 			result[ :url ] = waybill.url
 
+			# Seal the shelf — no more packing until the outcome is confirmed.
+			@warehouse.seal_shelf!( tracking_number: waybill.tracking_number )
+
 			# Wait at the registry while the bureaucrats check the parcel.
 			wait_and_poll_at_registry( waybill, result )
 
+			# Unseal based on outcome:
+			# delivered/held/rejected → unseal (shelf done or parcel returned)
+			# filed → stay sealed (parcel still in flight)
+			outcome = result[ :outcome ]
+			@warehouse.unseal_shelf! if outcome == "delivered" || outcome == "held" || outcome == "rejected"
+
 			# Update the ledger with the final outcome.
-			record( parcel, status: result[ :outcome ] || "filed", summary: result[ :hold_reason ] )
+			record( parcel, status: outcome || "filed", summary: result[ :hold_reason ] )
 
 			result[ :exit ] ||= OK
 			result
@@ -196,6 +220,9 @@ module Carson
 					return
 				end
 
+				# Report progress — the courier tells what the bureaucrats said.
+				say "#{waybill.hold_summary} (#{check + 1}/#{MAX_CHECKS_AT_REGISTRY})..."
+
 				# Still waiting — pause before the next check.
 				pause_between_polls unless check == MAX_CHECKS_AT_REGISTRY - 1
 			end
@@ -215,6 +242,11 @@ module Carson
 				"behind_registry", "policy_block", "draft" ].include?( reason )
 		end
 
+		# The courier speaks — reports progress to whoever is listening.
+		def say( message )
+			@output&.puts "#{BADGE} #{message}"
+		end
+
 		# Pause between poll checks. Overridable for test isolation.
 		def pause_between_polls
 			sleep @poll_interval_at_registry

data/lib/carson/runtime/audit.rb

@@ -7,6 +7,12 @@ module Carson
 	class Runtime
 		module Audit
 			def audit!( json_output: false )
+				# Sealed workbench guard — hard block before anything else.
+				# The warehouse seals the workbench when a parcel ships.
+				# No commits allowed until the delivery outcome is confirmed.
+				sealed_result = audit_sealed_workbench( json_output: json_output )
+				return sealed_result unless sealed_result.nil?
+
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 				unless head_exists?
@@ -177,6 +183,31 @@ module Carson
 					end
 				end
 
+				# 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: )
+					warehouse = Warehouse.new( path: work_dir )
+					return nil unless warehouse.sealed?
+
+					tracking_number = warehouse.sealed_tracking_number || "unknown"
+					if json_output
+						require "json"
+						output.puts JSON.pretty_generate( {
+							command: "audit",
+							status: "block",
+							reason: "workbench_sealed",
+							tracking_number: tracking_number,
+							recovery: "carson worktree create <name>",
+							exit_code: EXIT_BLOCK
+						} )
+					else
+						puts_line "Workbench is sealed — parcel in flight (PR ##{tracking_number})."
+						puts_line "  \u2192 carson worktree create <name>"
+					end
+					EXIT_BLOCK
+				end
+
 				def audit_working_tree_report
 					dirty_reason = dirty_worktree_reason
 					return { dirty: false, context: nil, status: "ok" } if dirty_reason.nil?

data/lib/carson/runtime/deliver.rb

@@ -22,7 +22,8 @@ module Carson
 				courier = Courier.new( warehouse,
 				ledger: ledger,
 				merge_method: config.govern_merge_method,
-				poll_interval_at_registry: config.poll_interval_at_registry
+				poll_interval_at_registry: config.poll_interval_at_registry,
+				output: output
 			)
 
 				result = courier.deliver( parcel,

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
@@ -91,22 +93,81 @@ module Carson
 		end
 
 		# Pack a parcel — stage all changes and commit.
+		# Refuses if the shelf is sealed (parcel already in flight).
 		# Returns true on success, false on failure.
 		def pack!( message: )
+			if sealed?
+				raise "Shelf is sealed — parcel in flight (PR ##{sealed_tracking_number}). " \
+					"Create a new worktree to continue working."
+			end
 			git( "add", "-A" )
 			_, _, status = git( "commit", "-m", message )
 			status.success?
 		end
 
+		# --- Shelf seal ---
+
+		# 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: )
+			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.
+		# Called when the delivery outcome is held or rejected.
+		def unseal_shelf!
+			File.delete( delivering_marker_path ) if File.exist?( delivering_marker_path )
+		end
+
+		# Is this shelf sealed for a delivery in flight?
+		def sealed?
+			File.exist?( delivering_marker_path )
+		end
+
+		# 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 ).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 ---
@@ -142,6 +203,15 @@ 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
+			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.
 		# Returns [stdout, stderr, status].
 		def git( *arguments )

metadata

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