carson 3.30.3 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 414294f12e0a6e1560b7c60df2ee77676734a63f279e40675bd4d10b55660851
-  data.tar.gz: 2dafbe3def3939e75263fb47de9e474d073f083adbb8fb22ec997ff839727768
+  metadata.gz: 96b7009510f859ab0892bffc34678701dc74412a4f4b9f17f1be3710cb82d0c3
+  data.tar.gz: 236de5bb54d69845b4710b8ffe946a64534a1db5ea068e2a8e34d566d6c438c4
 SHA512:
-  metadata.gz: fbc81621f5aa779bf26ef20316083c1e207266f99bbefaba4fa78eea4c475745c67f30410b66e4a29257ed88b54400068a8cfb6d40e1aabeda16615b9baad3bf
-  data.tar.gz: 973068e6d3e716f44e7a86fed848eeab6c5f26b95839e414061ed9f745ef5ed79a000ec60d753294cd27844bd6878beb14c3739ac24e4cdac04f2510592212d5
+  metadata.gz: 334f80f636c8285fbb7e3bb4481b99efecf0b69700b337ad03a63cc1b9fb0fe0d1ab49765371aa57ede881958cb0d2d9f9cff9104b50d007352edd94fb1cd22e
+  data.tar.gz: b6a92f602a9d0fdd9b22ba320616c6fe2db66d51230895b88e32962edaa5c43cfcadfe828278afbeb4111585b10d04781708c2d17dcdb03df10320fa1674e6c9

data/RELEASE.md

@@ -15,6 +15,25 @@ Release-note scope rule:
 - `--all` removed from all repo commands; use `carson list --json` to script batch operations
 - `refresh` is now portfolio-only (always refreshes all governed repos)
 
+## 4.0.0
+
+### 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.
+- **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.
+
+### 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`.
+
+### Migration
+
+- If you parse `hold_reason` from JSON output, update: `inspector_pending` → `pending_at_registry`, `inspector_failed` → `failed_at_registry`, `inspector_error` → `error_at_registry`.
+- `carson deliver` now takes up to ~3 minutes (6 checks × 30s). Adjust timeouts in CI or automation scripts if needed.
+
 ## 3.30.3
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.30.3
+4.0.0

data/lib/carson/config.rb

@@ -32,7 +32,8 @@ module Carson
 			:workflow_style,
 			:govern_repos, :govern_merge_method,
 			:govern_agent_provider, :govern_state_path,
-			:govern_check_wait
+			:govern_check_wait,
+			:poll_interval_at_registry
 
 		def self.load( repo_root: )
 			base_data = default_data
@@ -81,7 +82,10 @@ module Carson
 				"audit" => {
 					"advisory_check_names" => [ "Scheduled review sweep", "Carson governance", "Tag, release, publish" ]
 				},
-				"govern" => {
+				"deliver" => {
+				"poll_interval_at_registry" => 30
+			},
+			"govern" => {
 					"repos" => [],
 					"merge" => {
 						"method" => "squash"
@@ -167,6 +171,8 @@ module Carson
 			audit = fetch_hash_section( data: copy, key: "audit" )
 			advisory_names = env_string_array( key: "CARSON_AUDIT_ADVISORY_CHECK_NAMES" )
 			audit[ "advisory_check_names" ] = advisory_names unless advisory_names.empty?
+			deliver = fetch_hash_section( data: copy, key: "deliver" )
+			deliver[ "poll_interval_at_registry" ] = env_integer( key: "CARSON_POLL_INTERVAL_AT_REGISTRY", fallback: deliver.fetch( "poll_interval_at_registry" ) )
 			govern = fetch_hash_section( data: copy, key: "govern" )
 			govern_repos = env_string_array( key: "CARSON_GOVERN_REPOS" )
 			govern[ "repos" ] = govern_repos unless govern_repos.empty?
@@ -238,6 +244,9 @@ module Carson
 			audit_hash = fetch_hash( hash: data, key: "audit" )
 			@audit_advisory_check_names = fetch_optional_string_array( hash: audit_hash, key: "advisory_check_names" )
 
+			deliver_hash = fetch_hash( hash: data, key: "deliver" )
+			@poll_interval_at_registry = fetch_non_negative_integer( hash: deliver_hash, key: "poll_interval_at_registry" )
+
 			govern_hash = fetch_hash( hash: data, key: "govern" )
 			@govern_repos = fetch_optional_string_array( hash: govern_hash, key: "repos" ).map { |path| safe_expand_path( path ) }
 			govern_merge_hash = fetch_hash( hash: govern_hash, key: "merge" )

data/lib/carson/courier.rb

@@ -0,0 +1,259 @@
+# Carson Co.
+module Carson
+	# The delivery person — picks up parcels and delivers them to the registry.
+	#
+	# The courier is a Carson employee assigned to a warehouse. They pick up
+	# a parcel, ship it to the bureau, file a waybill, and wait at the
+	# registry while the bureaucrats check it.
+	#
+	# The courier is a thin orchestrator: it creates a Waybill and sends it
+	# messages. The domain logic lives in the objects, not the courier.
+	#
+	# == The bureau
+	#
+	# The bureau is a registry (GitHub) where bureaucrats work. They check
+	# parcels (CI, review, mergeability) and either accept them into the
+	# registry or hold them with a reason.
+	#
+	# == Situations the courier encounters
+	#
+	# Each numbered situation is handled by a specific guard or branch in the
+	# delivery flow. The number appears in the code comment where it's handled.
+	#
+	#   01. Parcel on main — cannot deliver from the destination.
+	#   02. Parcel behind standard — not based on client's latest standard.
+	#   03. Shipping fails — warehouse couldn't push to the bureau.
+	#   04. Waybill filing fails — bureau rejected the paperwork.
+	#   05. Pending at registry — bureaucrats still checking (CI running).
+	#   06. Failed at registry — bureaucrats rejected (CI failed).
+	#   07. Review pending — review still in progress.
+	#   08. Review changes requested — reviewer wants corrections.
+	#   09. Merge conflict — parcel conflicts with registry contents.
+	#   10. Behind standard (post-filing) — standard changed since shipping.
+	#   11. Policy block — bureau regulation prevents acceptance.
+	#   12. Draft waybill — form not finalised.
+	#   13. Mergeability pending — bureau still processing eligibility.
+	#   14. Acceptance succeeds — parcel enters the registry. Delivered.
+	#   15. Acceptance fails — classify why, report.
+	#   16. Bureau unreachable — cannot contact the bureau.
+	#   17. Parcel already delivered — already in registry.
+	#   18. Waybill closed — cancelled by someone externally.
+	#
+	# == Design: wait and poll at the registry
+	#
+	# The courier waits at the registry while the bureaucrats check the parcel.
+	# 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.
+	#
+	# == Future: destination modes
+	#
+	# Currently remote-centred (ship → waybill → registry → acceptance).
+	# A future local-centred mode merges locally; remote is a synced backup.
+	# The destination mode should be injectable, not baked in.
+	class Courier
+		# Exit codes — shared contract between Carson employees and the CLI.
+		OK = 0
+		ERROR = 1
+		BLOCKED = 2
+
+		# 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 )
+			@warehouse = warehouse
+			@ledger = ledger
+			@merge_method = merge_method
+			@poll_interval_at_registry = poll_interval_at_registry
+		end
+
+		# Deliver a parcel to the registry.
+		# Ships it, files a waybill, waits at the registry for the bureaucrats.
+		def deliver( parcel, title: nil, body_file: nil, commit_message: nil )
+			result = {
+				command: "deliver",
+				label: parcel.label,
+				remote_main: "#{@warehouse.bureau_address}/#{@warehouse.main_label}"
+			}
+
+			# 01. Parcel on main — cannot deliver from the destination.
+			if parcel.on_main?( @warehouse.main_label )
+				return blocked( result,
+					"cannot deliver from #{@warehouse.main_label}",
+					recovery: "carson worktree create <name>" )
+			end
+
+			# Dirty tree guard — the warehouse knows if its floor is clean.
+			if commit_message && @warehouse.clean?
+				return blocked( result,
+					"working tree is already clean",
+					recovery: "carson deliver" )
+			end
+			if !commit_message && !@warehouse.clean?
+				return blocked( result,
+					"working tree is dirty",
+					recovery: "carson deliver --commit \"describe this delivery\"" )
+			end
+
+			# Submit compliance — ensure templates are in sync before delivery.
+			compliance = @warehouse.submit_compliance!
+			unless compliance[ :compliant ]
+				return error( result, compliance[ :error ] || "compliance check failed" )
+			end
+
+			# Pack the parcel if the sender provided a commit message.
+			# Skip if compliance already committed everything (tree is now clean).
+			if commit_message && !@warehouse.clean?
+				unless @warehouse.pack!( message: commit_message )
+					return error( result, "packing failed — nothing to commit?" )
+				end
+			end
+			# Refresh parcel head — compliance or pack may have created commits.
+			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 )
+			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" )
+			end
+
+			# The courier picks up the parcel — start tracking.
+			record( parcel, status: "preparing", summary: "delivery accepted" )
+
+			# 03. Shipping fails — warehouse couldn't push to the bureau.
+			unless @warehouse.ship( parcel )
+				return error( result, "push failed" )
+			end
+
+			# File a waybill with the bureau.
+			waybill = Waybill.new(
+				label: parcel.label,
+				warehouse_path: @warehouse.path
+			)
+			waybill.file!( title: title, body_file: body_file )
+
+			# 04. Waybill filing fails — bureau rejected the paperwork.
+			unless waybill.filed?
+				return error( result, "PR creation failed", recovery: "carson deliver" )
+			end
+
+			result[ :tracking_number ] = waybill.tracking_number
+			result[ :url ] = waybill.url
+
+			# Wait at the registry while the bureaucrats check the parcel.
+			wait_and_poll_at_registry( waybill, result )
+
+			# Update the ledger with the final outcome.
+			record( parcel, status: result[ :outcome ] || "filed", summary: result[ :hold_reason ] )
+
+			result[ :exit ] ||= OK
+			result
+		end
+
+	private
+
+		# Wait at the registry, polling the bureaucrats up to MAX_CHECKS_AT_REGISTRY
+		# times. The courier stays until a definitive answer comes back or the
+		# checks are exhausted.
+		def wait_and_poll_at_registry( waybill, result )
+			MAX_CHECKS_AT_REGISTRY.times do |check|
+				waybill.refresh!
+
+				# 14/17. Already accepted — parcel is in the registry.
+				if waybill.accepted?
+					result[ :outcome ] = "delivered"
+					result[ :synced ] = @warehouse.receive_latest_standard!
+					return
+				end
+
+				# 18. Waybill closed — cancelled externally.
+				if waybill.rejected?
+					result[ :outcome ] = "rejected"
+					result[ :exit ] = BLOCKED
+					return
+				end
+
+				# Cleared or mergeability pending — try to accept.
+				if waybill.cleared? || waybill.mergeability_pending?
+					waybill.accept!( method: @merge_method )
+
+					if waybill.accepted?
+						result[ :outcome ] = "delivered"
+						result[ :synced ] = @warehouse.receive_latest_standard!
+						return
+					end
+				end
+
+				# 05-12. Definitively blocked — courier takes parcel back.
+				if definitively_blocked?( waybill )
+					result[ :outcome ] = "held"
+					result[ :exit ] = BLOCKED
+					result[ :hold_reason ] = waybill.hold_reason
+					return
+				end
+
+				# Still waiting — pause before the next check.
+				pause_between_polls unless check == MAX_CHECKS_AT_REGISTRY - 1
+			end
+
+			# Exhausted all checks — bureau hasn't given a definitive answer.
+			result[ :outcome ] = "filed"
+			result[ :hold_reason ] = waybill.hold_reason
+		end
+
+		# Is the waybill blocked by something that won't resolve by waiting?
+		# CI failure, merge conflict, policy block — the courier should take
+		# the parcel back immediately.
+		def definitively_blocked?( waybill )
+			return false unless waybill.held?
+			reason = waybill.hold_reason
+			[ "failed_at_registry", "merge_conflict",
+				"behind_registry", "policy_block", "draft" ].include?( reason )
+		end
+
+		# Pause between poll checks. Overridable for test isolation.
+		def pause_between_polls
+			sleep @poll_interval_at_registry
+		end
+
+		# Record a delivery state change in the ledger.
+		# No-op when no ledger is injected (e.g. tests).
+		def record( parcel, status:, summary: nil )
+			return unless @ledger
+
+			# The ledger needs a repository-like object with .path pointing
+			# to the main warehouse root (not a side shelf).
+			repo = Struct.new( :path ).new( @warehouse.main_worktree_root )
+			@ledger.upsert_delivery(
+				repository: repo,
+				branch_name: parcel.label,
+				head: parcel.head,
+				worktree_path: @warehouse.path,
+				pr_number: nil,
+				pr_url: nil,
+				status: status,
+				summary: summary,
+				cause: nil
+			)
+		end
+
+		# Build a blocked result — the courier cannot proceed.
+		def blocked( result, message, recovery: nil )
+			result[ :exit ] = BLOCKED
+			result[ :error ] = message
+			result[ :recovery ] = recovery
+			result
+		end
+
+		def error( result, message, recovery: nil )
+			result[ :exit ] = ERROR
+			result[ :error ] = message
+			result[ :recovery ] = recovery
+			result
+		end
+	end
+end

data/lib/carson/parcel.rb

@@ -0,0 +1,28 @@
+# The committed changes on a branch — the thing being delivered.
+#
+# In the FedEx metaphor, a parcel sits on a shelf (worktree) identified
+# by a label (branch name). Agents put committed changes — the parcel —
+# on a branch, then call Carson to deliver it.
+#
+# The parcel does not deliver itself. The courier does that.
+# The parcel does not pack itself. The warehouse does that.
+module Carson
+	# The committed changes being delivered. Knows its label (branch),
+	# head (commit SHA), and shelf (worktree). The protagonist of every
+	# delivery — without a parcel, there is nothing to deliver.
+	class Parcel
+		attr_reader :label, :head, :shelf
+
+		def initialize( label:, head:, shelf: nil )
+			@label = label
+			@head = head
+			@shelf = shelf
+		end
+
+		# Is this parcel sitting on the main shelf?
+		# The main shelf is the destination — you cannot deliver FROM the destination.
+		def on_main?( main_label )
+			label == main_label
+		end
+	end
+end

data/lib/carson/runtime/deliver.rb

@@ -6,119 +6,61 @@ module Carson
 			DELIVER_MERGE_ATTEMPT_CAP = 3
 
 			# Entry point for `carson deliver`.
-			# Pushes the current branch, ensures a PR exists, records delivery state,
-			# waits for merge readiness, and integrates when the path is clear.
-			# When --commit is supplied, Carson creates one all-dirty agent-authored commit first.
+			# Delegates to the OO domain model: Warehouse → Courier → Waybill.
+			# The Courier orchestrates the delivery; Carson renders the result.
 			def deliver!( title: nil, body_file: nil, commit_message: nil, json_output: false )
-				branch_name = current_branch
-				main_branch = config.main_branch
-				remote_name = config.git_remote
-				result = {
-					command: "deliver",
-					branch: branch_name,
-					git_remote: remote_name,
-					watch_window_seconds: config.govern_check_wait.to_i,
-					waited_seconds: 0,
-					merge_attempted: false
-				}
-
-				if branch_name == main_branch
-					result[ :error ] = "cannot deliver from #{main_branch}"
-					result[ :recovery ] = "carson worktree create <name>"
-					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
-				end
-
-				initial_dirty = working_tree_dirty?
-				if initial_dirty && commit_message.to_s.strip.empty?
-					result[ :error ] = "working tree is dirty"
-					result[ :recovery ] = "carson deliver --commit \"describe this delivery\""
-					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
-				end
-
-				if !initial_dirty && !commit_message.to_s.strip.empty?
-					result[ :commit ] = blocked_commit_payload(
-						message: commit_message,
-						summary: "blocked — working tree is already clean"
-					)
-					result[ :error ] = "working tree is already clean"
-					result[ :recovery ] = "carson deliver"
-					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
-				end
-
-				sync_exit, sync_diagnostics = deliver_template_sync
-				if sync_exit == EXIT_ERROR
-					result[ :error ] = sync_diagnostics.to_s.strip.empty? ? "template sync failed" : sync_diagnostics.strip
-					return deliver_finish( result: result, exit_code: sync_exit, json_output: json_output )
-				end
-				template_sync_committed = sync_exit == EXIT_BLOCK
-
-				unless commit_message.to_s.strip.empty?
-					commit_exit = prepare_delivery_commit!(
-						commit_message: commit_message,
-						template_sync_committed: template_sync_committed,
-						result: result
-					)
-					return deliver_finish( result: result, exit_code: commit_exit, json_output: json_output ) unless commit_exit == EXIT_OK
-				end
-
-				freshness = assess_branch_freshness(
-					head_ref: current_head,
-					remote: remote_name,
-					main: main_branch
+				warehouse = Warehouse.new(
+					path: work_dir,
+					main_label: config.main_branch,
+					bureau_address: config.git_remote,
+					compliance_checker: method( :deliver_compliance_checker )
 				)
-				result[ :freshness ] = freshness_payload( freshness: freshness )
-				unless freshness.fetch( :ready )
-					result[ :summary ] = freshness.fetch( :summary )
-					result[ :error ] = freshness.fetch( :summary )
-					result[ :recovery ] = freshness_recovery( freshness: freshness )
-					result[ :main_branch ] = main_branch
-					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
-				end
-
-				push_exit = push_branch!( branch: branch_name, remote: remote_name, result: result )
-				return deliver_finish( result: result, exit_code: push_exit, json_output: json_output ) unless push_exit == EXIT_OK
+				parcel = Parcel.new(
+					label: current_branch,
+					head: current_head
+				)
+				courier = Courier.new( warehouse,
+				ledger: ledger,
+				merge_method: config.govern_merge_method,
+				poll_interval_at_registry: config.poll_interval_at_registry
+			)
 
-				pr_number, pr_url = find_or_create_pr!(
-					branch: branch_name,
+				result = courier.deliver( parcel,
 					title: title,
 					body_file: body_file,
-					result: result
-				)
-				return deliver_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output ) if pr_number.nil?
-
-				branch = branch_record( name: branch_name )
-				delivery = ledger.upsert_delivery(
-					repository: repository_record,
-					branch_name: branch.name,
-					head: branch.head || current_head,
-					worktree_path: branch.worktree || repo_root,
-					pr_number: pr_number,
-					pr_url: pr_url,
-					status: "preparing",
-					summary: "delivery accepted",
-					cause: nil
-				)
-				delivery = settle_delivery!(
-					delivery: delivery,
-					branch_name: branch.name,
-					remote: remote_name,
-					main: main_branch,
-					result: result
+					commit_message: commit_message
 				)
 
-				result[ :pr_number ] = pr_number
-				result[ :pr_url ] = pr_url
-				result[ :ci ] = "pass" if delivery.integrated?
-				result[ :delivery ] = delivery_payload( delivery: delivery )
-				result[ :main_branch ] = main_branch
-				result[ :summary ] = delivery.summary
-				result[ :next_step ] = deliver_next_step( delivery: delivery, result: result )
-
-				deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
+				deliver_oo_finish( result: result, json_output: json_output )
 			end
 
 		private
 
+			# --- OO bridge methods ---
+
+			# Compliance checker for the Warehouse. Wraps the existing template_apply!
+			# machinery and returns the hash contract submit_compliance! expects.
+			def deliver_compliance_checker( _warehouse )
+				sync_exit, sync_diagnostics = deliver_template_sync
+				case sync_exit
+				when EXIT_OK
+					{ compliant: true, committed: false }
+				when EXIT_BLOCK
+					{ compliant: true, committed: true }
+				else
+					{ compliant: false, committed: false, error: sync_diagnostics.to_s.strip.empty? ? "template sync failed" : sync_diagnostics.strip }
+				end
+			end
+
+			# Render the OO result — JSON or human via Carson.report.
+			def deliver_oo_finish( result:, json_output: )
+				format = json_output ? :json : :human
+				Carson.report( result, format: format, output: output )
+				result[ :exit ] || Courier::OK
+			end
+
+			# --- Legacy deliver methods (used by receive!, status!, etc.) ---
+
 			def prepare_delivery_commit!( commit_message:, template_sync_committed:, result: )
 				if working_tree_dirty?
 					return create_delivery_commit!( commit_message: commit_message, result: result )

data/lib/carson/warehouse.rb

@@ -0,0 +1,151 @@
+# A governed repository. In the FedEx metaphor, the warehouse is where
+# parcels (committed changes) are stored on shelves (worktrees) with
+# labels (branches). Git commands are hidden inside — callers never
+# see git terms.
+require "open3"
+
+module Carson
+	# A governed repository — the warehouse where parcels are stored on
+	# shelves (worktrees) with labels (branches). Wraps git operations
+	# with story-language methods. An intelligent warehouse that manages
+	# itself: packing parcels, checking compliance, and sweeping up.
+	class Warehouse
+		attr_reader :path
+
+		def initialize( path:, main_label: "main", bureau_address: "github", compliance_checker: nil )
+			@path = path
+			@main_label = main_label
+			@bureau_address = bureau_address
+			@compliance_checker = compliance_checker
+		end
+
+		# --- What the warehouse knows ---
+
+		# The label on the current shelf (branch name).
+		def current_label
+			git( "rev-parse", "--abbrev-ref", "HEAD" ).first.strip
+		end
+
+		# The tip of the parcel on the current shelf (commit SHA).
+		def current_head
+			git( "rev-parse", "HEAD" ).first.strip
+		end
+
+		# The destination label (from config).
+		def main_label
+			@main_label
+		end
+
+		# The bureau's address (remote name).
+		def bureau_address
+			@bureau_address
+		end
+
+		# Is the warehouse floor clean? No uncommitted changes on the current shelf.
+		def clean?
+			output, _, status = git( "status", "--porcelain" )
+			status.success? && output.strip.empty?
+		end
+
+		# --- Warehouse operations ---
+
+		# Ship a parcel to the bureau.
+		# The warehouse sends the parcel's label to the remote.
+		def ship( parcel, remote: bureau_address )
+			_, _, status = git( "push", "-u", remote, parcel.label )
+			status.success?
+		end
+
+		# Get latest registry state from the bureau (git fetch).
+		# Returns true on success, false on failure.
+		def fetch_latest( remote: bureau_address, registry: nil )
+			arguments = [ "fetch", remote ]
+			arguments << registry if registry
+			_, _, status = git( *arguments )
+			status.success?
+		end
+
+		# Is the parcel based on the client's latest production standard?
+		# Checks whether the registry tip is an ancestor of the parcel's head.
+		def based_on_latest_standard?( parcel, registry: "#{bureau_address}/#{main_label}" )
+			_, _, status = git( "merge-base", "--is-ancestor", registry, parcel.head )
+			status.success?
+		end
+
+		# Ensure the warehouse complies with company standards (template sync).
+		# Delegates to the injected compliance checker. If no checker is set,
+		# the warehouse assumes compliance — no templates to enforce.
+		# Returns a hash: { compliant: true/false, committed: true/false, error: nil/string }
+		def submit_compliance!
+			return { compliant: true, committed: false } unless @compliance_checker
+
+			@compliance_checker.call( self )
+		end
+
+		# Update the warehouse's production standard — rebase onto latest registry state.
+		# Called after the bureau refuses a parcel for being behind standard.
+		# Returns true on success, false on failure.
+		def rebase_on_latest_standard!( registry: "#{bureau_address}/#{main_label}" )
+			_, _, status = git( "rebase", registry )
+			status.success?
+		end
+
+		# Pack a parcel — stage all changes and commit.
+		# Returns true on success, false on failure.
+		def pack!( message: )
+			git( "add", "-A" )
+			_, _, status = git( "commit", "-m", message )
+			status.success?
+		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.
+		def receive_latest_standard!( remote: bureau_address )
+			_, _, status = Open3.capture3(
+				"git", "-C", main_worktree_root,
+				"fetch", remote, "#{main_label}:#{main_label}"
+			)
+			status.success?
+		end
+
+		# --- Inventory ---
+
+		# All shelves (worktree paths).
+		def shelves
+			output, = git( "worktree", "list", "--porcelain" )
+			output.lines
+				.select { it.start_with?( "worktree " ) }
+				.map { it.sub( "worktree ", "" ).strip }
+		end
+
+		# All labels (branch names).
+		def labels
+			output, = git( "branch", "--format", "%(refname:short)" )
+			output.lines.map { it.strip }.reject { it.empty? }
+		end
+
+		# Has this label been merged into main?
+		def label_absorbed?( name )
+			merged_output, = git( "branch", "--merged", main_label, "--format", "%(refname:short)" )
+			merged_output.lines.map { it.strip }.include?( name )
+		end
+
+		# The main warehouse location — resolves correctly even from a side shelf.
+		# Used by sync! and ledger recording to always reference the canonical path.
+		def main_worktree_root
+			git_common_dir, = git( "rev-parse", "--path-format=absolute", "--git-common-dir" )
+			common = git_common_dir.strip
+			# If it ends with /.git, the parent is the main worktree root.
+			common.end_with?( "/.git" ) ? File.dirname( common ) : common
+		end
+
+	private
+
+		# All git commands go through this single gateway.
+		# Returns [stdout, stderr, status].
+		def git( *arguments )
+			Open3.capture3( "git", "-C", path, *arguments )
+		end
+	end
+end

data/lib/carson/waybill.rb

@@ -0,0 +1,243 @@
+# The shipping document filed with the bureau (GitHub PR).
+#
+# The courier files a waybill with the bureau when delivering a parcel.
+# The waybill has a tracking number (PR number), knows the bureau's
+# response (cleared/held/accepted/rejected), and can ask the bureau
+# to accept the parcel into the registry.
+#
+# The bureau is a registry where bureaucrats work. They check parcels
+# (CI, review, mergeability) and either accept them into the registry
+# or hold them with a reason.
+#
+# The waybill uses gh CLI internally — that's a tool, not the domain.
+require "json"
+require "open3"
+
+module Carson
+	# The shipping document filed with the bureau (GitHub PR). Has a
+	# tracking number, knows the bureaucrats' response (cleared/held/
+	# accepted/rejected), and can ask the bureau to accept the parcel
+	# into the registry. Uses gh CLI internally — that's a tool, not
+	# the domain.
+	class Waybill
+		attr_reader :tracking_number, :url, :label
+
+		def initialize( label:, warehouse_path:, tracking_number: nil, url: nil, review_gate: nil )
+			@label = label
+			@warehouse_path = warehouse_path
+			@tracking_number = tracking_number
+			@url = url
+			@review_gate = review_gate
+			@state = nil
+			@ci = nil
+		end
+
+		# --- Filing ---
+
+		# Has the waybill been filed with the bureau?
+		def filed?
+			!tracking_number.nil?
+		end
+
+		# File the waybill with the bureau. Creates a PR on GitHub.
+		def file!( title: nil, body_file: nil )
+			filing_title = title || default_title
+			arguments = [ "pr", "create", "--title", filing_title, "--head", label ]
+
+			if body_file && File.exist?( body_file )
+				arguments.push( "--body-file", body_file )
+			else
+				arguments.push( "--body", "" )
+			end
+
+			stdout, stderr, success, = gh( *arguments )
+			if success
+				@url = stdout.to_s.strip
+				@tracking_number = @url.split( "/" ).last.to_i
+				@tracking_number = nil if @tracking_number == 0
+			end
+
+			# If create failed or returned no number, try to find existing.
+			find_existing! unless filed?
+			self
+		end
+
+		# Generate a human-readable title from the label.
+		def default_title
+			label.tr( "-", " " ).gsub( "/", ": " ).sub( /\A\w/ ) do |character|
+				character.upcase
+			end
+		end
+
+		# --- Bureau's response ---
+
+		# Check with the bureau for the latest on this waybill.
+		def refresh!
+			@state = fetch_state
+			@ci = fetch_ci
+			self
+		end
+
+		# Has the bureau accepted the parcel into the registry?
+		def accepted?
+			@state&.dig( "state" ) == "MERGED"
+		end
+
+		# Has the bureau rejected the waybill (closed without merge)?
+		def rejected?
+			@state&.dig( "state" ) == "CLOSED"
+		end
+
+		# Is the waybill still a draft?
+		def draft?
+			@state&.dig( "isDraft" ) || false
+		end
+
+		# Has the bureau cleared the parcel for delivery?
+		# All bureaucrats pass, no merge blocks, merge state is clean.
+		def cleared?
+			return false unless filed?
+			return false if draft?
+			return false unless @ci == :pass
+			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
+			merge_status == "CLEAN" || mergeable == "MERGEABLE"
+		end
+
+		# Is something blocking this waybill?
+		def held?
+			return false if cleared? || accepted? || rejected?
+			filed?
+		end
+
+		# Why is the waybill being held?
+		def hold_reason
+			return "draft" if draft?
+			return "pending_at_registry" if @ci == :pending
+			return "failed_at_registry" if @ci == :fail
+			return "error_at_registry" if @ci == :error
+			return "merge_conflict" if merge_conflicting?
+			return "behind_registry" if merge_behind?
+			return "policy_block" if merge_policy_blocked?
+			"mergeability_pending"
+		end
+
+		# Human-readable explanation of why the waybill is held.
+		def hold_summary
+			case hold_reason
+			when "draft" then "waybill is still a draft"
+			when "pending_at_registry" then "waiting for bureaucrats to check"
+			when "failed_at_registry" then "bureaucrats rejected the parcel"
+			when "error_at_registry" then "unable to reach the bureaucrats"
+			when "merge_conflict" then "parcel has conflicts with registry"
+			when "behind_registry" then "parcel is behind the registry"
+			when "policy_block" then "blocked by bureau policy"
+			else "waiting for bureau assessment"
+			end
+		end
+
+		# Is the hold specifically because mergeability is still pending?
+		def mergeability_pending?
+			hold_reason == "mergeability_pending"
+		end
+
+		# --- Acceptance ---
+
+		# Ask the bureau to accept the parcel into the registry.
+		# Updates own state after the attempt.
+		def accept!( method: )
+			gh( "pr", "merge", tracking_number.to_s, "--#{method}" )
+			refresh!
+			self
+		end
+
+		# --- Observation data for delivery records ---
+
+		# Returns a hash of the bureau's current state for tracking records.
+		def to_observation
+			return {} unless @state.is_a?( Hash )
+
+			{
+				pull_request_state: @state[ "state" ],
+				pull_request_draft: @state[ "isDraft" ],
+				pull_request_merged_at: @state[ "mergedAt" ]
+			}
+		end
+
+		# --- Test support ---
+
+		# Stub the bureau's response for testing without gh CLI.
+		def stub_bureau_response( state: nil, ci: nil )
+			@state = state if state
+			@ci = ci if ci
+		end
+
+	private
+
+		def merge_conflicting?
+			status = @state&.dig( "mergeStateStatus" ).to_s.upcase
+			mergeable = @state&.dig( "mergeable" ).to_s.upcase
+			mergeable == "CONFLICTING" || status == "DIRTY" || status == "CONFLICTING"
+		end
+
+		def merge_behind?
+			@state&.dig( "mergeStateStatus" ).to_s.upcase == "BEHIND"
+		end
+
+		def merge_policy_blocked?
+			@state&.dig( "mergeStateStatus" ).to_s.upcase == "BLOCKED"
+		end
+
+		def fetch_state
+			stdout, _, success, = gh(
+				"pr", "view", tracking_number.to_s,
+				"--json", "number,state,isDraft,url,mergeStateStatus,mergeable,mergedAt"
+			)
+			return nil unless success
+
+			JSON.parse( stdout )
+		rescue JSON::ParserError
+			nil
+		end
+
+		def fetch_ci
+			stdout, _, success, = gh(
+				"pr", "checks", tracking_number.to_s,
+				"--json", "name,bucket"
+			)
+			return :error unless success
+
+			checks = JSON.parse( stdout ) rescue []
+			return :none if checks.empty?
+
+			buckets = checks.map do |entry|
+				entry[ "bucket" ].to_s.downcase
+			end
+			return :fail if buckets.include?( "fail" )
+			return :pending if buckets.include?( "pending" )
+
+			:pass
+		end
+
+		def find_existing!
+			stdout, _, success, = gh(
+				"pr", "view", label,
+				"--json", "number,url,state"
+			)
+			if success
+				data = JSON.parse( stdout ) rescue nil
+				if data && data[ "number" ] && data[ "state" ] == "OPEN"
+					@tracking_number = data[ "number" ]
+					@url = data[ "url" ].to_s
+				end
+			end
+		end
+
+		# All gh commands go through this single gateway.
+		def gh( *arguments )
+			stdout, stderr, status = Open3.capture3( "gh", *arguments, chdir: @warehouse_path )
+			[ stdout, stderr, status.success?, status.exitstatus ]
+		end
+	end
+end

data/lib/carson.rb

@@ -3,6 +3,78 @@ require_relative "carson/version"
 
 module Carson
 	BADGE = "\u29D3".freeze # ⧓ BLACK BOWTIE (U+29D3)
+
+	# The company renders results for whoever is listening.
+	# JSON is the primary format (agents consume it). Human-readable is secondary.
+	# Domain objects return result hashes — Carson decides how to present them.
+	def self.report( result, format: :json, output: $stdout )
+		case format
+		when :json
+			require "json"
+			output.puts JSON.pretty_generate( result )
+		when :human
+			report_human( result, output: output )
+		end
+	end
+
+	# Human-readable delivery report — technical language for agents and humans.
+	# Story language is internal (source code). Output speaks the client's language.
+	def self.report_human( result, output: $stdout )
+		if result[ :error ]
+			output.puts "#{BADGE} #{result[ :error ]}"
+			output.puts "  \u2192 #{result[ :recovery ]}" if result[ :recovery ]
+			return
+		end
+
+		output.puts "#{BADGE} Delivery: #{result[ :label ]}" if result[ :label ]
+		output.puts "#{BADGE} PR ##{result[ :tracking_number ]}  #{result[ :url ]}" if result[ :tracking_number ]
+
+		remote_main = result[ :remote_main ] || "origin/main"
+
+		case result[ :outcome ]
+		when "delivered"
+			output.puts "#{BADGE} Merged."
+			output.puts "#{BADGE} Local main synced." if result[ :synced ]
+		when "held"
+			diagnosis, *recovery_steps = translate_hold( result[ :hold_reason ], remote_main: remote_main )
+			output.puts "#{BADGE} #{diagnosis}"
+			recovery_steps.each do |step|
+				output.puts "  \u2192 #{step}"
+			end
+		when "rejected"
+			output.puts "#{BADGE} PR closed externally."
+		when "filed"
+			output.puts "#{BADGE} Bureau hasn't responded yet. Run carson status to check back."
+		end
+	end
+
+	# Translate internal hold reasons to agent-actionable output.
+	# Returns [ diagnosis, *recovery_steps ]. The diagnosis says what
+	# happened. Each recovery step is a command the agent can execute.
+	def self.translate_hold( reason, remote_main: "origin/main" )
+		case reason
+		when "draft"
+			[ "PR is still a draft." ]
+		when "pending_at_registry"
+			[ "Waiting for CI checks.", "carson status" ]
+		when "failed_at_registry"
+			[ "CI checks failed.", "carson deliver" ]
+		when "error_at_registry"
+			[ "Unable to assess CI checks.", "carson status" ]
+		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" ]
+		when "policy_block"
+			[ "Blocked by branch protection rules." ]
+		when "mergeability_pending"
+			[ "GitHub is calculating mergeability.", "carson status" ]
+		else
+			[ "Waiting for merge readiness.", "carson status" ]
+		end
+	end
+
+	private_class_method :report_human
 end
 
 require_relative "carson/repository"
@@ -10,6 +82,10 @@ require_relative "carson/branch"
 require_relative "carson/delivery"
 require_relative "carson/revision"
 require_relative "carson/ledger"
+require_relative "carson/parcel"
+require_relative "carson/warehouse"
+require_relative "carson/waybill"
+require_relative "carson/courier"
 require_relative "carson/worktree"
 require_relative "carson/config"
 require_relative "carson/adapters/git"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.30.3
+  version: 4.0.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -70,8 +70,10 @@ files:
 - lib/carson/branch.rb
 - lib/carson/cli.rb
 - lib/carson/config.rb
+- lib/carson/courier.rb
 - lib/carson/delivery.rb
 - lib/carson/ledger.rb
+- lib/carson/parcel.rb
 - lib/carson/repository.rb
 - lib/carson/revision.rb
 - lib/carson/runtime.rb
@@ -100,6 +102,8 @@ files:
 - lib/carson/runtime/setup.rb
 - lib/carson/runtime/status.rb
 - lib/carson/version.rb
+- lib/carson/warehouse.rb
+- lib/carson/waybill.rb
 - lib/carson/worktree.rb
 homepage: https://github.com/wanghailei/carson
 licenses: