carson 4.0.3 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5678a9b3d25a0a0c6e2b37182e53607b8c41e0a199771bbae7535ec776f71c8
-  data.tar.gz: c744e380475f851bdc142dc13693f3b35a229b93a45fdbc2ecb70e33fd3ba8cc
+  metadata.gz: 4f0dff052fa48cda5c1c0819ff109a9e93c70579c3e450d8af3e82bb55140b54
+  data.tar.gz: b2543300a607dccd88aaa3286e3c37b34cb4e847a30b3fb202ee76cc223125fb
 SHA512:
-  metadata.gz: 136aeaa5ebf42de0f676875a44d8d4bf2eb758b9d70753718ba6cb27ca37756ca42af3518247e1a357c6e5a3bb8cdaa9bbdeff2d1fa9f3fd63302263b4d3c9a1
-  data.tar.gz: db5026a393f292c7dee8e1a6b3d63ec4463bcaebea179161ceb184271826d0c1a803bfc9a6a31f6cc5d7446f10be3e52739bebfbb70c548a8cb607fd1f57e4ae
+  metadata.gz: c0b1853fe814ad941a983d4d0676eb1912ec818b3387b3d74ab61241cb413bea296a797b6bb2f7fbbca8b30f978fc6df203a27a1879727bd753c3a615efdf8ec
+  data.tar.gz: 3a51ccae965f6f0008123396c0347a3758c8ad28fac60ceabf8a058bb44538afd2988155b9ec895fe0419f0ddf82279c5f86517f2626dec5dfe96b2375877153

data/RELEASE.md

@@ -7,9 +7,28 @@ Release-note scope rule:
 
 ## Unreleased
 
+## 4.1.0
+
 ### 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)
+- Config key `poll_interval_at_registry` renamed to `poll_interval_at_bureau`. Env var `CARSON_POLL_INTERVAL_AT_REGISTRY` renamed to `CARSON_POLL_INTERVAL_AT_BUREAU`.
+- Hold reason codes renamed: `*_at_registry` → `*_at_bureau`, `behind_registry` → `behind_bureau`. Affects JSON output consumers matching on these strings.
+- `Carson.translate_hold` removed. Recovery steps now come from `Carson.recovery_steps_for_hold` (private).
+- `Carson.report` format `:human` renamed to `:text`.
+
+### What changed
+
+- **Waybill is a data object** — `Waybill` no longer calls `gh`. It records findings written onto it by the Warehouse and answers questions about its state. `fetch_ci`, `refresh!`, `accept!`, `file!` removed. Added `record()`, `stamp()`, `ci_diagnostic`.
+- **Warehouse owns bureau interaction** — `check_parcel_at_bureau_with()`, `file_waybill_for!()`, `register_parcel_at_bureau_with!()` added. The Warehouse queries GitHub and writes findings onto the Waybill. Diagnostic context (stderr from `gh pr checks`) is captured and surfaced.
+- **CI diagnostic surfaces in output** (#468) — When CI checks cannot be assessed, the first line of `gh` stderr appears in polling messages and the delivery report. Agents can see WHY checks failed, not just that they failed.
+- **No story language in CLI output** (#458) — `hold_summary` returns client language directly. Polling messages, delivery reports, seal messages, and housekeep output all use technical terms (CI checks, PR, branch, merge). Story language (bureau, bureaucrat, parcel, waybill) is confined to source code.
+- **Consistent naming: bureau, not registry** — GitHub interactions use "bureau" consistently. "Registry" was a subset concept that leaked into method and constant names, creating confusion with "bureau."
+
+### Fixed
+
+- **Repeated opaque CI error polling** (#468) — `fetch_ci` discarded `gh pr checks` stderr. Six retries showed "unable to reach the bureaucrats" with no cause. Now captures the first line of stderr and shows it: "Unable to assess CI checks. — HTTP 404: Not Found (1/6)..."
+- **Story language in polling output** (#458) — Courier polling used `waybill.hold_summary` (story language) instead of client language. Now uses client-language summaries directly.
 
 ## 4.0.3
 

data/VERSION

@@ -1 +1 @@
-4.0.3
+4.1.0

data/config/.github/hooks/command-guard

@@ -96,6 +96,9 @@ on_main_branch=false
 delivery_pattern='(^|&&|\|\||;|\|)\s*gh\s+pr\s+(create|merge)\b'
 worktree_pattern='(^|&&|\|\||;|\|)\s*git\s+worktree\s+(add|remove)\b'
 pull_rebase_pattern='(^|&&|\|\||;|\|)\s*git\s+pull([^;&|]|\\\|)*--rebase\b'
+fetch_pattern='(^|&&|\|\||;|\|)\s*git\s+fetch\b'
+rebase_pattern='(^|&&|\|\||;|\|)\s*git\s+rebase\b'
+rebase_continue_pattern='(^|&&|\|\||;|\|)\s*git\s+rebase\s+--(continue|abort|skip)\b'
 main_mutation_pattern='(^|&&|\|\||;|\|)\s*git\s+(add|commit)\b'
 
 if grep -qE "$delivery_pattern" <<<"$command_text"; then
@@ -116,6 +119,21 @@ if grep -qE "$pull_rebase_pattern" <<<"$command_text"; then
 		"Use \`carson sync\` instead — it owns main-branch alignment in governed repos."
 fi
 
+if grep -qE "$fetch_pattern" <<<"$command_text"; then
+	block_command \
+		"This repo is Carson-governed — do not use raw \`git fetch\`." \
+		"Carson commands handle fetching internally. Use \`carson deliver\` or \`carson sync\`."
+fi
+
+if grep -qE "$rebase_pattern" <<<"$command_text"; then
+	# Allow conflict resolution: --continue, --abort, --skip.
+	if ! grep -qE "$rebase_continue_pattern" <<<"$command_text"; then
+		block_command \
+			"This repo is Carson-governed — do not use raw \`git rebase\`." \
+			"\`carson deliver\` rebases automatically when the branch is behind."
+	fi
+fi
+
 if [ "$on_main_worktree" = true ] && [ "$on_main_branch" = true ] && grep -qE "$main_mutation_pattern" <<<"$command_text"; then
 	block_command \
 		"Main working tree is read-only in this Carson-governed repo." \

data/lib/carson/adapters/prompt.rb

@@ -9,7 +9,7 @@ module Carson
 
 			def build_prompt( work_order: )
 				parts = []
-				parts << "You are an automated coding agent dispatched by Carson to fix an issue on a pull request."
+				parts << "You are an automated coding agent working on a pull request."
 				parts << "Repository: #{sanitize( File.basename( work_order.repo ) )}"
 				parts << "<pr_branch>#{sanitize( work_order.branch )}</pr_branch>"
 				parts << "PR: ##{work_order.pr_number}"

data/lib/carson/cli.rb

@@ -142,18 +142,10 @@ module Carson
 				parser.separator ""
 				parser.separator "Repository commands (from CWD or with explicit repo):"
 				parser.separator "    status       Show repository delivery state"
-				parser.separator "    setup        Initialise Carson configuration"
 				parser.separator "    audit        Run pre-commit health checks"
-				parser.separator "    abandon      Close and clean up abandoned delivery work"
-				parser.separator "    sync         Sync local main with remote"
 				parser.separator "    deliver      Start autonomous branch delivery"
 				parser.separator "    recover      Merge the repair PR for one baseline-red governance check"
-				parser.separator "    prune        Remove stale local branches"
 				parser.separator "    worktree     Manage isolated coding worktrees"
-				parser.separator "    housekeep    Sync, reap worktrees, and prune branches"
-				parser.separator "    review       Manage PR review workflow"
-				parser.separator "    template     Manage canonical template files"
-				parser.separator "    receive      Triage and advance deliveries for one repo"
 				parser.separator ""
 				parser.separator "Run `carson <command> --help` for details on a specific command."
 			end
@@ -478,16 +470,14 @@ module Carson
 		def self.parse_worktree_subcommand( arguments:, error: )
 			options = { json: false, force: false }
 			worktree_parser = OptionParser.new do |parser|
-				parser.banner = "Usage: carson worktree <create|list|remove> <name> [options]"
+				parser.banner = "Usage: carson worktree <create|list> <name> [options]"
 				parser.separator ""
 				parser.separator "Manage isolated worktrees for coding agents."
-				parser.separator "Create auto-syncs main before branching. Remove guards against"
-				parser.separator "unpushed commits and CWD-inside-worktree by default."
+				parser.separator "Create auto-syncs main before branching."
 				parser.separator ""
 				parser.separator "Subcommands:"
-				parser.separator "    create <name>              Create a new worktree with a fresh branch"
-				parser.separator "    list                       List registered worktrees with cleanup status"
-				parser.separator "    remove <name> [--force]    Remove a worktree (--force skips safety checks)"
+				parser.separator "    create <name>    Create a new worktree with a fresh branch"
+				parser.separator "    list             List registered worktrees with cleanup status"
 				parser.separator ""
 				parser.separator "Options:"
 				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
@@ -496,7 +486,6 @@ module Carson
 				parser.separator "Examples:"
 				parser.separator "    carson worktree create feature-x    Create an isolated worktree"
 				parser.separator "    carson worktree list                Show registered worktrees"
-				parser.separator "    carson worktree remove feature-x    Remove after work is pushed"
 			end
 			worktree_parser.parse!( arguments )
 

data/lib/carson/config.rb

@@ -33,7 +33,7 @@ module Carson
 			:govern_repos, :govern_merge_method,
 			:govern_agent_provider, :govern_state_path,
 			:govern_check_wait,
-			:poll_interval_at_registry
+			:poll_interval_at_bureau
 
 		def self.load( repo_root: )
 			base_data = default_data
@@ -83,7 +83,7 @@ module Carson
 					"advisory_check_names" => [ "Scheduled review sweep", "Carson governance", "Tag, release, publish" ]
 				},
 				"deliver" => {
-				"poll_interval_at_registry" => 30
+				"poll_interval_at_bureau" => 30
 			},
 			"govern" => {
 					"repos" => [],
@@ -172,7 +172,7 @@ module Carson
 			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" ) )
+			deliver[ "poll_interval_at_bureau" ] = env_integer( key: "CARSON_POLL_INTERVAL_AT_BUREAU", fallback: deliver.fetch( "poll_interval_at_bureau" ) )
 			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?
@@ -245,7 +245,7 @@ module Carson
 			@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" )
+			@poll_interval_at_bureau = fetch_non_negative_integer( hash: deliver_hash, key: "poll_interval_at_bureau" )
 
 			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 ) }

data/lib/carson/courier.rb

@@ -1,19 +1,22 @@
 # Carson Co.
 module Carson
-	# The delivery person — picks up parcels and delivers them to the registry.
+	# The delivery person — picks up parcels and delivers them to the bureau.
 	#
 	# 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.
+	# a parcel, ask the warehouse to ship it, file a waybill, and wait at
+	# the bureau 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 courier is a thin orchestrator: it asks the warehouse to interact
+	# with the bureau, reads the waybill for status, and reports results.
+	# 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.
+	# The bureau (GitHub) is where bureaucrats work. They check parcels
+	# (CI, review, mergeability) and either accept them into the registry
+	# or hold them with a reason. The warehouse owns the connection to
+	# the bureau — the courier asks the warehouse to check, file, and
+	# register.
 	#
 	# == Shelf seal
 	#
@@ -32,8 +35,8 @@ module Carson
 	#   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).
+	#   05. Pending at bureau — bureaucrats still checking (CI running).
+	#   06. Failed at bureau — 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.
@@ -47,18 +50,18 @@ module Carson
 	#   17. Parcel already delivered — already in registry.
 	#   18. Waybill closed — cancelled by someone externally.
 	#
-	# == Design: wait and poll at the registry
+	# == Design: wait and poll at the bureau
 	#
-	# 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.
+	# The courier waits at the bureau while the bureaucrats check the parcel.
+	# It polls up to MAX_CHECKS_AT_BUREAU 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 bureau
 	# and the shelf stays sealed.
 	#
 	# == Future: destination modes
 	#
-	# Currently remote-centred (ship → waybill → registry → acceptance).
+	# Currently remote-centred (ship → waybill → bureau → acceptance).
 	# A future local-centred mode merges locally; remote is a synced backup.
 	# The destination mode should be injectable, not baked in.
 	class Courier
@@ -69,19 +72,19 @@ module Carson
 
 		BADGE = "\u29D3".freeze
 
-		# The courier checks the registry up to 6 times before leaving.
-		MAX_CHECKS_AT_REGISTRY = 6
+		# The courier checks the bureau up to 6 times before leaving.
+		MAX_CHECKS_AT_BUREAU = 6
 
-		def initialize( warehouse, ledger: nil, merge_method: "rebase", poll_interval_at_registry: 30, output: $stdout )
+		def initialize( warehouse, ledger: nil, merge_method: "rebase", poll_interval_at_bureau: 30, output: $stdout )
 			@warehouse = warehouse
 			@ledger = ledger
 			@merge_method = merge_method
-			@poll_interval_at_registry = poll_interval_at_registry
+			@poll_interval_at_bureau = poll_interval_at_bureau
 			@output = output
 		end
 
 		# Deliver a parcel to the registry.
-		# Ships it, files a waybill, seals the shelf, waits at the registry.
+		# Ships it, files a waybill, seals the shelf, waits at the bureau.
 		def deliver( parcel, title: nil, body_file: nil, commit_message: nil )
 			result = {
 				command: "deliver",
@@ -153,15 +156,11 @@ module Carson
 				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 )
+			# File a waybill with the bureau — the warehouse handles the gh call.
+			waybill = @warehouse.file_waybill_for!( parcel, title: title, body_file: body_file )
 
 			# 04. Waybill filing fails — bureau rejected the paperwork.
-			unless waybill.filed?
+			unless waybill
 				return error( result, "PR creation failed", recovery: "carson deliver" )
 			end
 
@@ -171,8 +170,8 @@ module Carson
 			# 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 )
+			# Wait at the bureau while the bureaucrats check the parcel.
+			wait_and_poll_at_bureau( waybill, result )
 
 			# Unseal based on outcome:
 			# delivered/held/rejected → unseal (shelf done or parcel returned)
@@ -180,7 +179,7 @@ module Carson
 			outcome = result[ :outcome ]
 			@warehouse.unseal_shelf! if outcome == "delivered" || outcome == "held" || outcome == "rejected"
 
-			# Update the ledger with the final outcome.
+			# Update the ledger with the final outcome and PR identity.
 			record( parcel, status: outcome || "filed", summary: result[ :hold_reason ], waybill: waybill )
 
 			result[ :exit ] ||= OK
@@ -189,12 +188,12 @@ module Carson
 
 	private
 
-		# Wait at the registry, polling the bureaucrats up to MAX_CHECKS_AT_REGISTRY
+		# Wait at the bureau, polling the bureaucrats up to MAX_CHECKS_AT_BUREAU
 		# 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!
+		def wait_and_poll_at_bureau( waybill, result )
+			MAX_CHECKS_AT_BUREAU.times do |check|
+				@warehouse.check_parcel_at_bureau_with( waybill )
 
 				# 14/17. Already accepted — parcel is in the registry.
 				if waybill.accepted?
@@ -210,9 +209,9 @@ module Carson
 					return
 				end
 
-				# Cleared or mergeability pending — try to accept.
+				# Cleared or mergeability pending — ask the warehouse to register.
 				if waybill.cleared? || waybill.mergeability_pending?
-					waybill.accept!( method: @merge_method )
+					@warehouse.register_parcel_at_bureau_with!( waybill, method: @merge_method )
 
 					if waybill.accepted?
 						result[ :outcome ] = "delivered"
@@ -226,19 +225,25 @@ module Carson
 					result[ :outcome ] = "held"
 					result[ :exit ] = BLOCKED
 					result[ :hold_reason ] = waybill.hold_reason
+					result[ :hold_summary ] = waybill.hold_summary( remote_main: result[ :remote_main ] )
+					result[ :diagnostic ] = waybill.ci_diagnostic
 					return
 				end
 
-				# Report progress — the courier tells what the bureaucrats said.
-				say "#{waybill.hold_summary} (#{check + 1}/#{MAX_CHECKS_AT_REGISTRY})..."
+				# Report progress — client-language summary from the waybill.
+				summary = waybill.hold_summary( remote_main: result[ :remote_main ] )
+				detail = waybill.ci_diagnostic ? " \u2014 #{waybill.ci_diagnostic}" : ""
+				say "#{summary}#{detail} (#{check + 1}/#{MAX_CHECKS_AT_BUREAU})..."
 
 				# Still waiting — pause before the next check.
-				pause_between_polls unless check == MAX_CHECKS_AT_REGISTRY - 1
+				pause_between_polls unless check == MAX_CHECKS_AT_BUREAU - 1
 			end
 
 			# Exhausted all checks — bureau hasn't given a definitive answer.
 			result[ :outcome ] = "filed"
 			result[ :hold_reason ] = waybill.hold_reason
+			result[ :hold_summary ] = waybill.hold_summary( remote_main: result[ :remote_main ] )
+			result[ :diagnostic ] = waybill.ci_diagnostic
 		end
 
 		# Is the waybill blocked by something that won't resolve by waiting?
@@ -247,8 +252,8 @@ module Carson
 		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 )
+			[ "failed_at_bureau", "merge_conflict",
+				"behind_bureau", "policy_block", "draft" ].include?( reason )
 		end
 
 		# The courier speaks — reports progress to whoever is listening.
@@ -258,11 +263,11 @@ module Carson
 
 		# Pause between poll checks. Overridable for test isolation.
 		def pause_between_polls
-			sleep @poll_interval_at_registry
+			sleep @poll_interval_at_bureau
 		end
 
 		# Record a delivery state change in the ledger.
-		# No-op when no ledger is injected (e.g. tests).
+		# When a waybill is provided, its PR identity is persisted.
 		def record( parcel, status:, summary: nil, waybill: nil )
 			return unless @ledger
 

data/lib/carson/runtime/audit.rb

@@ -202,7 +202,7 @@ module Carson
 							exit_code: EXIT_BLOCK
 						} )
 					else
-						puts_line "Workbench is sealed — parcel in flight (PR ##{tracking_number})."
+						puts_line "Branch is locked — PR ##{tracking_number} in flight."
 						puts_line "  \u2192 carson worktree create <name>"
 					end
 					EXIT_BLOCK

data/lib/carson/runtime/deliver.rb

@@ -22,7 +22,7 @@ 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_bureau: config.poll_interval_at_bureau,
 				output: output
 			)
 
@@ -55,7 +55,7 @@ module Carson
 
 			# Render the OO result — JSON or human via Carson.report.
 			def deliver_oo_finish( result:, json_output: )
-				format = json_output ? :json : :human
+				format = json_output ? :json : :text
 				Carson.report( result, format: format, output: output )
 				result[ :exit ] || Courier::OK
 			end

data/lib/carson/runtime/housekeep.rb

@@ -262,7 +262,7 @@ module Carson
 
 					next unless current_head == delivery.head
 
-					reason = "integrated delivery recorded in ledger"
+					reason = "merged — delivery recorded"
 					reaped = reap_one_worktree!( worktree: worktree, reason: reason )
 					next unless reaped
 

data/lib/carson/runtime/receive.rb

@@ -127,6 +127,16 @@ module Carson
 					)
 				end
 
+				# No PR number — courier failed to record it. Cannot reconcile against GitHub.
+				unless delivery.pull_request_number
+					return ledger.update_delivery(
+						delivery: delivery,
+						status: "failed",
+						cause: "policy",
+						summary: "PR number missing from delivery record — run carson deliver to refile"
+					)
+				end
+
 				pr_state = pull_request_state( number: delivery.pull_request_number )
 				if pr_state && pr_state[ "state" ] == "MERGED"
 					return ledger.update_delivery(

data/lib/carson/warehouse.rb

@@ -1,9 +1,10 @@
 # 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.
+# labels (branches). Git and gh commands are hidden inside — callers
+# never see git or GitHub terms.
 require "digest"
 require "fileutils"
+require "json"
 require "open3"
 
 module Carson
@@ -97,7 +98,7 @@ module Carson
 		# Returns true on success, false on failure.
 		def pack!( message: )
 			if sealed?
-				raise "Shelf is sealed — parcel in flight (PR ##{sealed_tracking_number}). " \
+				raise "Branch is locked — PR ##{sealed_tracking_number} in flight. " \
 					"Create a new worktree to continue working."
 			end
 			git( "add", "-A" )
@@ -170,6 +171,62 @@ module Carson
 			end
 		end
 
+		# --- Bureau interaction ---
+		# The warehouse owns the connection to the bureau (GitHub).
+		# It queries, files, and registers on behalf of the courier.
+
+		# Check the parcel's status at the bureau using the waybill.
+		# Calls gh pr view + gh pr checks. Records findings onto the waybill.
+		def check_parcel_at_bureau_with( waybill )
+			state = fetch_pr_state_for( waybill.tracking_number )
+			ci, ci_diagnostic = fetch_ci_state_for( waybill.tracking_number )
+			waybill.record( state: state, ci: ci, ci_diagnostic: ci_diagnostic )
+		end
+
+		# File a waybill at the bureau for this parcel.
+		# Calls gh pr create. Returns a Waybill with tracking number, or nil on failure.
+		def file_waybill_for!( parcel, title: nil, body_file: nil )
+			filing_title = title || Waybill.default_title_for( parcel.label )
+			arguments = [ "pr", "create", "--title", filing_title, "--head", parcel.label ]
+
+			if body_file && File.exist?( body_file )
+				arguments.push( "--body-file", body_file )
+			else
+				arguments.push( "--body", "" )
+			end
+
+			stdout, _, status = gh( *arguments )
+			tracking_number = nil
+			url = nil
+
+			if status.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 an existing PR.
+			unless tracking_number
+				tracking_number, url = find_existing_waybill_for( parcel.label )
+			end
+
+			return nil unless tracking_number
+
+			Waybill.new( label: parcel.label, tracking_number: tracking_number, url: url )
+		end
+
+		# Register the parcel at the bureau using the waybill.
+		# Calls gh pr merge. Stamps the waybill on success.
+		def register_parcel_at_bureau_with!( waybill, method: )
+			_, _, status = gh( "pr", "merge", waybill.tracking_number.to_s, "--#{method}" )
+			if status.success?
+				waybill.stamp( :accepted )
+			else
+				# Re-check the state — the merge may have revealed a new blocker.
+				check_parcel_at_bureau_with( waybill )
+			end
+		end
+
 		# --- Inventory ---
 
 		# All shelves (worktree paths).
@@ -217,5 +274,63 @@ module Carson
 		def git( *arguments )
 			Open3.capture3( "git", "-C", path, *arguments )
 		end
+
+		# All gh commands go through this single gateway.
+		# Returns [stdout, stderr, status].
+		def gh( *arguments )
+			Open3.capture3( "gh", *arguments, chdir: path )
+		end
+
+		# Fetch PR state from the bureau for a tracking number.
+		# Returns the parsed state hash, or nil on failure.
+		def fetch_pr_state_for( tracking_number )
+			stdout, _, status = gh(
+				"pr", "view", tracking_number.to_s,
+				"--json", "number,state,isDraft,url,mergeStateStatus,mergeable,mergedAt"
+			)
+			return nil unless status.success?
+
+			JSON.parse( stdout )
+		rescue JSON::ParserError
+			nil
+		end
+
+		# Fetch CI state from the bureau for a tracking number.
+		# Returns [ci_symbol, diagnostic_or_nil].
+		# Captures the first line of stderr as diagnostic when the command fails.
+		def fetch_ci_state_for( tracking_number )
+			stdout, stderr, status = gh(
+				"pr", "checks", tracking_number.to_s,
+				"--json", "name,bucket"
+			)
+			unless status.success?
+				return [ :error, stderr.to_s.strip.lines.first&.strip ]
+			end
+
+			checks = JSON.parse( stdout ) rescue []
+			return [ :none, nil ] if checks.empty?
+
+			buckets = checks.map { it[ "bucket" ].to_s.downcase }
+			return [ :fail, nil ] if buckets.include?( "fail" )
+			return [ :pending, nil ] if buckets.include?( "pending" )
+
+			[ :pass, nil ]
+		end
+
+		# Try to find an existing PR for this label at the bureau.
+		# Returns [tracking_number, url] or [nil, nil].
+		def find_existing_waybill_for( label )
+			stdout, _, status = gh(
+				"pr", "view", label,
+				"--json", "number,url,state"
+			)
+			if status.success?
+				data = JSON.parse( stdout ) rescue nil
+				if data && data[ "number" ] && data[ "state" ] == "OPEN"
+					return [ data[ "number" ], data[ "url" ].to_s ]
+				end
+			end
+			[ nil, nil ]
+		end
 	end
 end

data/lib/carson/waybill.rb

@@ -1,35 +1,29 @@
 # 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.
+# A waybill is a data object — it records findings and answers questions.
+# It does not fetch, file, or accept anything. The warehouse handles all
+# bureau interaction and writes findings onto the waybill.
 #
-# 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"
+# The waybill has a tracking number (PR number), a label (branch name),
+# and records the bureau's response (cleared/held/accepted/rejected).
+# ci_diagnostic preserves the first line of stderr when CI checks fail.
 
 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.
+	# tracking number, records the bureaucrats' response (cleared/held/
+	# accepted/rejected). A data object — state is written onto it by
+	# the warehouse, never fetched by the waybill itself.
 	class Waybill
-		attr_reader :tracking_number, :url, :label
+		attr_reader :tracking_number, :url, :label, :ci_diagnostic
 
-		def initialize( label:, warehouse_path:, tracking_number: nil, url: nil, review_gate: nil )
+		def initialize( label:, tracking_number: nil, url: nil )
 			@label = label
-			@warehouse_path = warehouse_path
 			@tracking_number = tracking_number
 			@url = url
-			@review_gate = review_gate
 			@state = nil
 			@ci = nil
+			@ci_diagnostic = nil
+			@verdict = nil
 		end
 
 		# --- Filing ---
@@ -39,53 +33,46 @@ module Carson
 			!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
+		# Generate a title from the label. Class method so the warehouse
+		# can compute the title before creating the waybill.
+		def self.default_title_for( label )
+			label.tr( "-", " " ).gsub( "/", ": " ).sub( /\A\w/ ) do |character|
+				character.upcase
 			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.
+		# Instance convenience — delegates to the class method.
 		def default_title
-			label.tr( "-", " " ).gsub( "/", ": " ).sub( /\A\w/ ) do |character|
-				character.upcase
-			end
+			self.class.default_title_for( label )
 		end
 
-		# --- Bureau's response ---
+		# --- Recorded state ---
+
+		# Record findings from a bureau check onto the waybill.
+		# Called by the warehouse after querying the bureau.
+		def record( state:, ci:, ci_diagnostic: nil )
+			@state = state
+			@ci = ci
+			@ci_diagnostic = ci_diagnostic
+		end
 
-		# Check with the bureau for the latest on this waybill.
-		def refresh!
-			@state = fetch_state
-			@ci = fetch_ci
-			self
+		# Stamp the waybill with a verdict.
+		# Called by the warehouse after registering the parcel at the bureau.
+		def stamp( verdict )
+			@verdict = verdict
 		end
 
+		# --- Bureau's response queries ---
+
 		# Has the bureau accepted the parcel into the registry?
+		# True when stamped :accepted OR when the recorded state shows MERGED.
 		def accepted?
-			@state&.dig( "state" ) == "MERGED"
+			@verdict == :accepted || @state&.dig( "state" ) == "MERGED"
 		end
 
 		# Has the bureau rejected the waybill (closed without merge)?
 		def rejected?
-			@state&.dig( "state" ) == "CLOSED"
+			@verdict == :rejected || @state&.dig( "state" ) == "CLOSED"
 		end
 
 		# Is the waybill still a draft?
@@ -111,29 +98,31 @@ module Carson
 			filed?
 		end
 
-		# Why is the waybill being held?
+		# Why is the waybill being held? Code string for recovery step lookup.
 		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 "pending_at_bureau" if @ci == :pending
+			return "failed_at_bureau" if @ci == :fail
+			return "error_at_bureau" if @ci == :error
 			return "merge_conflict" if merge_conflicting?
-			return "behind_registry" if merge_behind?
+			return "behind_bureau" 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
+		# Client-language summary of why the waybill is held.
+		# Agents read this directly — no translation layer needed.
+		def hold_summary( remote_main: "github/main" )
 			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"
+			when "draft" then "PR is still a draft."
+			when "pending_at_bureau" then "Waiting for CI checks."
+			when "failed_at_bureau" then "CI checks failed."
+			when "error_at_bureau" then "Unable to assess CI checks."
+			when "merge_conflict" then "Merge conflict with #{remote_main}."
+			when "behind_bureau" then "Branch is behind #{remote_main}."
+			when "policy_block" then "Blocked by branch protection rules."
+			when "mergeability_pending" then "GitHub is calculating mergeability."
+			else "Waiting for merge readiness."
 			end
 		end
 
@@ -142,16 +131,6 @@ module Carson
 			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.
@@ -165,14 +144,6 @@ module Carson
 			}
 		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?
@@ -188,56 +159,5 @@ module Carson
 		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

@@ -5,21 +5,21 @@ 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.
+	# JSON is the primary format (agents consume it). Text 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 )
+		when :text
+			report_text( result, output: output )
 		end
 	end
 
-	# Human-readable delivery report — technical language for agents and humans.
+	# Text delivery report — client language for agents.
 	# Story language is internal (source code). Output speaks the client's language.
-	def self.report_human( result, output: $stdout )
+	def self.report_text( result, output: $stdout )
 		if result[ :error ]
 			output.puts "#{BADGE} #{result[ :error ]}"
 			output.puts "  \u2192 #{result[ :recovery ]}" if result[ :recovery ]
@@ -40,45 +40,39 @@ module Carson
 				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}"
-			recovery_steps.each do |step|
+			summary = result[ :hold_summary ] || "Waiting for merge readiness."
+			output.puts "#{BADGE} #{summary}"
+			recovery_steps_for_hold( result[ :hold_reason ], remote_main: remote_main ).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."
+			summary = result[ :hold_summary ] || "Waiting for merge readiness."
+			diagnostic = result[ :diagnostic ] ? " (#{result[ :diagnostic ]})" : ""
+			output.puts "#{BADGE} #{summary}#{diagnostic}"
+			output.puts "  \u2192 carson status"
 		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" )
+	# Recovery commands for a held delivery.
+	# The report knows what commands to suggest for each situation.
+	def self.recovery_steps_for_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 "pending_at_bureau", "mergeability_pending", "error_at_bureau"
+			[ "carson status" ]
+		when "failed_at_bureau"
+			[ "carson deliver" ]
 		when "merge_conflict"
-			[ "Merge conflict with #{remote_main}.", "git rebase #{remote_main}", "carson deliver" ]
-		when "behind_registry"
-			[ "Branch is behind #{remote_main}.", "carson deliver" ]
-		when "policy_block"
-			[ "Blocked by branch protection rules." ]
-		when "mergeability_pending"
-			[ "GitHub is calculating mergeability.", "carson status" ]
+			[ "git rebase #{remote_main}", "carson deliver" ]
+		when "behind_bureau"
+			[ "carson deliver" ]
 		else
-			[ "Waiting for merge readiness.", "carson status" ]
+			[]
 		end
 	end
 
-	private_class_method :report_human
+	private_class_method :report_text, :recovery_steps_for_hold
 end
 
 require_relative "carson/repository"
@@ -87,8 +81,8 @@ 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/warehouse"
 require_relative "carson/courier"
 require_relative "carson/worktree"
 require_relative "carson/config"

metadata

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