carson 4.1.1 → 4.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d709f0737b7411687d882b100598ae5d86bef2cf05cc39b493e567c03e687aa4
-  data.tar.gz: 968d6124cc0406f21f44ce6430e4635954f8aecb77bca53ff7d1d111cce2dbe3
+  metadata.gz: c882d441c7ea190db45ec65d5aad771de7a601c19375204dfabaa6ec285a6ebf
+  data.tar.gz: 6b7cc35fa68c90a5d493409f8bbc7799dd1cc2adacb2af0ff15cf42393d66c9c
 SHA512:
-  metadata.gz: fae3226c3f11a5fb7a7269d086a8c1f1dfc2bbd5e4ca71b2823663891189fb1bc8a8da3eb67dd93a6462f20857f3ead10c4cd456efd618eb830b650b75b92f44
-  data.tar.gz: 67bf606c7221408e585145f2e37452e260ed417de8016c7f0f776b70218db821cd4c9ba7ef564cf2d689336fe989d7a2bcceb22b0be492d3f6a4a649b85a8906
+  metadata.gz: c28c1b696376b7949f505481c22908dabc8c4c813ae71b9d461e11d1298143e89fa4490a0f6a00a7a4730880aa0b5b3d9916559dfa3181d595bf181c3e62eca8
+  data.tar.gz: c202d344de6b324aae1e9dc9d8ad31a7378c6404c248daca3084d919caa5e21068cc64a6bf38d0e50deccd41e88ee5c0680dac51702410469f6906b5f35903f9

data/RELEASE.md

@@ -7,6 +7,12 @@ Release-note scope rule:
 
 ## Unreleased
 
+## 4.1.2
+
+### Fixed
+
+- **Hook templates misplaced under `.github/`** — `config/.github/hooks/` moved to `config/hooks/`. Git hooks are local mechanisms installed to `~/.carson/hooks/`, not GitHub configuration. The previous path falsely implied a relationship with GitHub's `.github/` convention.
+
 ## 4.1.1
 
 ### Fixed

data/VERSION

@@ -1 +1 @@
-4.1.1
+4.1.2

data/lib/carson/cli.rb

@@ -898,7 +898,7 @@ module Carson
 		# referenced by Claude Code's PreToolUse hook. It must exist regardless of
 		# whether `carson refresh` has been run in any governed repo.
 		def self.ensure_global_artefacts!( tool_root: )
-			source = File.join( tool_root, "config", ".github", "hooks", "command-guard" )
+			source = File.join( tool_root, "config", "hooks", "command-guard" )
 			return unless File.file?( source )
 
 			hooks_base = File.expand_path( "~/.carson/hooks" )

data/lib/carson/runtime/abandon.rb

@@ -140,17 +140,18 @@ module Carson
 				end
 
 				if worktree
-					check = Worktree.remove_check( path: worktree.path, runtime: self, force: false, skip_unpushed: true )
+					check = worktree_warehouse.assess_teardown( worktree, force: false, skip_unpushed: true )
 					return nil if check.fetch( :status ) == :ok
 
-					recovery = check.fetch( :recovery )
-					if check.fetch( :error ) == "worktree has uncommitted changes"
+					recovery = check[ :recovery ]
+					if check[ :error ] == "worktree has uncommitted changes"
 						recovery = "commit or discard the changes, then retry carson abandon #{branch}"
 					end
 
+					exit_code = check[ :status ] == :block ? EXIT_BLOCK : EXIT_ERROR
 					return {
-						exit_code: check.fetch( :exit_code ),
-						error: check.fetch( :error ),
+						exit_code: exit_code,
+						error: check[ :error ],
 						recovery: recovery
 					}
 				end

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

@@ -64,7 +64,7 @@ module Carson
 
 			# Canonical hook template location inside Carson repository.
 			def hook_template_path( hook_name: )
-				File.join( tool_root, "config", ".github", "hooks", hook_name )
+				File.join( tool_root, "config", "hooks", hook_name )
 			end
 
 			# Reports full hook health and can enforce stricter action messaging in `check`.

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

@@ -1,31 +1,46 @@
 # Thin worktree delegate layer on Runtime.
-# Lifecycle operations live on Carson::Worktree; this module delegates
-# and keeps only methods that genuinely belong on Runtime (path resolution,
-# CWD branch detection).
+# Lifecycle operations delegate to Warehouse::Workbench.
+# Keeps only methods that genuinely belong on Runtime (path resolution,
+# CWD branch detection, output rendering).
 module Carson
 	class Runtime
 		module Local
 
-			# --- Delegates to Carson::Worktree ---
+			# --- Delegates to Warehouse::Workbench ---
 
 			# Creates a new worktree under .claude/worktrees/<name>.
 			def worktree_create!( name:, json_output: false )
-				Worktree.create!( name: name, runtime: self, json_output: json_output )
+				result = worktree_warehouse.build_workbench!( name: name )
+				finish_worktree( result: result, json_output: json_output )
 			end
 
 			# Removes a worktree: directory, git registration, and branch.
 			def worktree_remove!( worktree_path:, force: false, skip_unpushed: false, json_output: false )
-				Worktree.remove!( path: worktree_path, runtime: self, force: force, skip_unpushed: skip_unpushed, json_output: json_output )
+				wh = worktree_warehouse
+				workbench = wh.workbench_named( worktree_path )
+				unless workbench
+					return finish_worktree(
+						result: { command: "worktree remove", status: "error",
+							name: File.basename( worktree_path ),
+							error: "#{worktree_path} is not a registered worktree",
+							recovery: "git worktree list" },
+						json_output: json_output )
+				end
+				result = wh.tear_down_workbench!( workbench, force: force, skip_unpushed: skip_unpushed )
+				finish_worktree( result: result, json_output: json_output )
 			end
 
 			# Removes agent-owned worktrees whose branch content is already on main.
+			# Still uses Worktree.sweep_stale! which needs classify_worktree_cleanup
+			# on Runtime. Migrates to warehouse.sweep_workbenches! when housekeep
+			# is absorbed (Phase 4 item 40).
 			def sweep_stale_worktrees!
 				Worktree.sweep_stale!( runtime: self )
 			end
 
 			# Returns all registered worktrees as Carson::Worktree instances.
 			def worktree_list
-				Worktree.list( runtime: self )
+				worktree_warehouse.workbenches
 			end
 
 			# Human and JSON status surface for all registered worktrees.
@@ -109,6 +124,65 @@ module Carson
 
 		private
 
+			# Build a Warehouse for workbench operations.
+			# Always rooted at the main worktree so workbench management
+			# works correctly even when called from inside a worktree.
+			def worktree_warehouse
+				Warehouse.new(
+					path: main_worktree_root,
+					main_label: config.main_branch,
+					bureau_address: config.git_remote
+				)
+			end
+
+			# Render a workbench operation result as JSON or human text.
+			# Returns the exit code for CLI dispatch.
+			def finish_worktree( result:, json_output: false )
+				exit_code = result.fetch( :exit_code, nil )
+				status = result[ :status ]
+
+				# Derive exit code from status if not explicitly set.
+				exit_code ||= case status
+					when "ok" then EXIT_OK
+					when "block" then EXIT_BLOCK
+					else EXIT_ERROR
+				end
+
+				result[ :exit_code ] = exit_code
+
+				if json_output
+					output.puts JSON.pretty_generate( result )
+				else
+					print_worktree_result( result: result )
+				end
+
+				exit_code
+			end
+
+			# Human-readable output for worktree operation results.
+			def print_worktree_result( result: )
+				command = result[ :command ]
+				status = result[ :status ]
+
+				case status
+				when "ok"
+					case command
+					when "worktree create"
+						puts_line "Worktree created: #{result[ :name ]}"
+						puts_line "  Path: #{result[ :path ]}"
+						puts_line "  Branch: #{result[ :branch ]}"
+					when "worktree remove"
+						puts_line "Worktree removed: #{result[ :name ]}" unless verbose?
+					end
+				when "error"
+					puts_line result[ :error ]
+					puts_line "  → #{result[ :recovery ]}" if result[ :recovery ]
+				when "block"
+					puts_line "#{result[ :error ]&.capitalize || 'Held'}: #{result[ :name ]}"
+					puts_line "  → #{result[ :recovery ]}" if result[ :recovery ]
+				end
+			end
+
 			def worktree_inventory
 				worktree_list.map { |worktree| worktree_inventory_entry( worktree: worktree ) }
 			end

data/lib/carson/runtime/recover.rb

@@ -2,7 +2,7 @@
 module Carson
 	class Runtime
 		module Recover
-			GOVERNANCE_SURFACE_PREFIXES = %w[ .github/ config/.github/ ].freeze
+			GOVERNANCE_SURFACE_PREFIXES = %w[ .github/ config/hooks/ ].freeze
 
 			def recover!( check_name:, json_output: false )
 				result = {
@@ -71,7 +71,7 @@ module Carson
 
 				unless relation.fetch( :related )
 					result[ :error ] = "branch does not touch the governance surface for #{check_name}"
-					result[ :recovery ] = "update the branch to repair .github/ or config/.github/, then rerun carson recover --check #{check_name.inspect}"
+					result[ :recovery ] = "update the branch to repair .github/ or config/hooks/, then rerun carson recover --check #{check_name.inspect}"
 					return recover_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
 				end
 

data/lib/carson/warehouse/bureau.rb

@@ -0,0 +1,117 @@
+# The warehouse's bureau-facing concern.
+# The warehouse owns the connection to the bureau (GitHub).
+# It queries, files, and registers on behalf of the courier.
+require "json"
+
+module Carson
+	class Warehouse
+		module Bureau
+
+			# 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
+
+		private
+
+			# 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
+end

data/lib/carson/warehouse/seal.rb

@@ -0,0 +1,55 @@
+# The warehouse's workbench seal concern.
+# Once a parcel ships and the waybill is filed, the warehouse seals the
+# workbench. No more packing until the delivery outcome is confirmed.
+# The seal marker lives outside the worktree (~/.carson/seals/) so it
+# does not pollute git status.
+require "digest"
+require "fileutils"
+
+module Carson
+	class Warehouse
+		module Seal
+
+			# Seal the workbench — no more packing until delivery outcome is confirmed.
+			# The courier seals the workbench after shipping and filing the waybill.
+			def seal_workbench!( tracking_number: )
+				marker = delivering_marker_path
+				FileUtils.mkdir_p( File.dirname( marker ) )
+				File.write( marker, "#{tracking_number}\n#{@path}" )
+			end
+
+			# Unseal the workbench — the courier brought back the parcel.
+			# Called when the delivery outcome is held or rejected.
+			def unseal_workbench!
+				File.delete( delivering_marker_path ) if File.exist?( delivering_marker_path )
+			end
+
+			# Is this workbench 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
+
+			# --- Transitional aliases ---
+			# Keep old names working until all callers are updated.
+			alias seal_shelf! seal_workbench!
+			alias unseal_shelf! unseal_workbench!
+
+		private
+
+			# Path to the delivery marker file.
+			# 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
+		end
+	end
+end

data/lib/carson/warehouse/workbench.rb

@@ -0,0 +1,469 @@
+# The warehouse's workbench concern.
+# Builds, tears down, sweeps, and inventories workbenches.
+# Workbenches are passive objects — the warehouse acts on them.
+require "fileutils"
+require "open3"
+require "pathname"
+
+module Carson
+	class Warehouse
+		module Workbench
+
+			# Agent directory names whose workbenches the warehouse may sweep.
+			AGENT_DIRS = %w[ .claude .codex ].freeze
+
+			# --- Inventory ---
+
+			# All workbenches in this warehouse.
+			# Parses the git worktree registry into Worktree instances.
+			# Normalises paths with realpath so comparisons work across symlinks.
+			def workbenches
+				raw, = git( "worktree", "list", "--porcelain" )
+				entries = []
+				current_path = nil
+				current_branch = :unset
+				current_prunable_reason = nil
+
+				raw.lines.each do |line|
+					line = line.strip
+					if line.empty?
+						entries << Carson::Worktree.new(
+							path: current_path,
+							branch: current_branch == :unset ? nil : current_branch,
+							prunable_reason: current_prunable_reason
+						) if current_path
+						current_path = nil
+						current_branch = :unset
+						current_prunable_reason = nil
+					elsif line.start_with?( "worktree " )
+						current_path = realpath_safe( line.sub( "worktree ", "" ) )
+					elsif line.start_with?( "branch " )
+						current_branch = line.sub( "branch refs/heads/", "" )
+					elsif line == "detached"
+						current_branch = nil
+					elsif line.start_with?( "prunable" )
+						reason = line.sub( "prunable", "" ).strip
+						current_prunable_reason = reason.empty? ? "prunable" : reason
+					end
+				end
+
+				# Handle the last entry (porcelain output may not end with a blank line).
+				entries << Carson::Worktree.new(
+					path: current_path,
+					branch: current_branch == :unset ? nil : current_branch,
+					prunable_reason: current_prunable_reason
+				) if current_path
+
+				entries
+			end
+
+			# Find a workbench by canonical path.
+			def workbench_at( path: )
+				canonical = realpath_safe( path )
+				workbenches.find { |wb| wb.path == canonical }
+			end
+
+			# Resolve a bare name and find the workbench.
+			# Tries .claude/worktrees/<name> first, then searches all registered
+			# workbenches by directory name.
+			def workbench_named( name )
+				if Pathname.new( name ).absolute?
+					return workbench_at( path: name )
+				end
+
+				# Try as a relative path from CWD.
+				relative_candidate = realpath_safe( File.expand_path( name, Dir.pwd ) )
+				found = workbench_at( path: relative_candidate )
+				return found if found
+
+				# Try scoped path (e.g. "claude/foo" → .claude/worktrees/claude/foo).
+				if name.include?( "/" )
+					scoped_candidate = realpath_safe( File.join( main_worktree_root, ".claude", "worktrees", name ) )
+					found = workbench_at( path: scoped_candidate )
+					return found if found
+				end
+
+				# Try flat layout: .claude/worktrees/<name>.
+				root = main_worktree_root
+				candidate = realpath_safe( File.join( root, ".claude", "worktrees", name ) )
+				found = workbench_at( path: candidate )
+				return found if found
+
+				# Search all registered workbenches by dirname.
+				matches = workbenches.select { |wb| File.basename( wb.path ) == name }
+				return matches.first if matches.size == 1
+
+				nil
+			end
+
+			# Is this path a registered workbench?
+			def workbench_registered?( path: )
+				canonical = realpath_safe( path )
+				workbenches.any? { |wb| wb.path == canonical }
+			end
+
+			# --- Lifecycle ---
+
+			# Build a new workbench from the latest production standard.
+			# Creates the directory, branches from the latest standard,
+			# ensures .claude/ is excluded from git status.
+			def build_workbench!( name: )
+				root = main_worktree_root
+				worktrees_dir = File.join( root, ".claude", "worktrees" )
+				workbench_path = File.join( worktrees_dir, name )
+
+				if Dir.exist?( workbench_path )
+					return { command: "worktree create", status: "error", name: name,
+						path: workbench_path,
+						error: "worktree already exists: #{name}",
+						recovery: "carson worktree remove #{name}, then retry" }
+				end
+
+				# Determine the base branch.
+				base = @main_label
+
+				# Fetch to update remote tracking ref without mutating the main worktree.
+				_, _, fetch_ok = git( "fetch", @bureau_address, base )
+				if fetch_ok.success?
+					remote_ref = "#{@bureau_address}/#{base}"
+					_, _, ref_ok = git( "rev-parse", "--verify", remote_ref )
+					base = remote_ref if ref_ok.success?
+				end
+
+				# Ensure .claude/ is excluded from git status.
+				ensure_claude_dir_excluded!
+
+				# Create the worktree with a new branch.
+				FileUtils.mkdir_p( File.dirname( workbench_path ) )
+				wt_stdout, wt_stderr, wt_status = git( "worktree", "add", workbench_path, "-b", name, base )
+				unless wt_status.success?
+					error_text = wt_stderr.to_s.strip
+					error_text = "unable to create worktree" if error_text.empty?
+					return { command: "worktree create", status: "error", name: name,
+						error: error_text }
+				end
+
+				# Verify the build succeeded.
+				unless workbench_creation_verified?( path: workbench_path, branch: name )
+					diagnostics = gather_build_diagnostics(
+						git_stdout: wt_stdout, git_stderr: wt_stderr, name: name )
+					cleanup_partial_build!( path: workbench_path, branch: name )
+					return { command: "worktree create", status: "error", name: name,
+						path: workbench_path, branch: name,
+						error: "git reported success but Carson could not verify the worktree and branch",
+						recovery: "git worktree list --porcelain && git branch --list '#{name}'",
+						diagnostics: diagnostics }
+				end
+
+				{ command: "worktree create", status: "ok", name: name,
+					path: workbench_path, branch: name }
+			end
+
+			# Tear down a workbench — directory, registration, label.
+			# The warehouse checks safety before acting.
+			def tear_down_workbench!( workbench, force: false, skip_unpushed: false )
+				# If the directory is already gone, repair the stale registration.
+				unless workbench.exists?
+					return repair_missing_workbench!( workbench )
+				end
+
+				# Safety assessment.
+				assessment = assess_teardown( workbench, force: force, skip_unpushed: skip_unpushed )
+				unless assessment[ :status ] == :ok
+					return { command: "worktree remove", status: assessment[ :result_status ] || "error",
+						name: File.basename( workbench.path ), branch: workbench.branch,
+						error: assessment[ :error ], recovery: assessment[ :recovery ] }
+				end
+
+				# Step 1: remove the worktree (directory + git registration).
+				rm_args = [ "worktree", "remove" ]
+				rm_args << "--force" if force
+				rm_args << workbench.path
+				_, rm_stderr, rm_status = git( *rm_args )
+				unless rm_status.success?
+					error_text = rm_stderr.to_s.strip
+					error_text = "unable to remove worktree" if error_text.empty?
+					if !force && ( error_text.downcase.include?( "untracked" ) || error_text.downcase.include?( "modified" ) )
+						return { command: "worktree remove", status: "error",
+							name: File.basename( workbench.path ),
+							error: "worktree has uncommitted changes",
+							recovery: "commit or discard changes first, or use --force to override" }
+					end
+					return { command: "worktree remove", status: "error",
+						name: File.basename( workbench.path ), error: error_text }
+				end
+
+				# Step 2: delete the local branch.
+				branch = workbench.branch
+				branch_deleted = false
+				if branch
+					_, _, del_ok = git( "branch", "-D", branch )
+					branch_deleted = del_ok.success?
+				end
+
+				# Step 3: delete the remote branch (best-effort).
+				remote_deleted = false
+				if branch
+					_, _, rd_ok = git( "push", @bureau_address, "--delete", branch )
+					remote_deleted = rd_ok.success?
+				end
+
+				{ command: "worktree remove", status: "ok",
+					name: File.basename( workbench.path ),
+					branch: branch, branch_deleted: branch_deleted,
+					remote_deleted: remote_deleted }
+			end
+
+			# Full safety assessment before tear-down.
+			# Returns { status: :ok } or { status: :block/:error, error:, recovery: }.
+			def assess_teardown( workbench, force: false, skip_unpushed: false )
+				unless workbench.exists?
+					return { status: :ok, missing: true }
+				end
+
+				if agent_at_workbench?( workbench )
+					return { status: :block, result_status: "block",
+						error: "current working directory is inside this worktree",
+						recovery: "cd #{main_worktree_root} && carson worktree remove #{File.basename( workbench.path )}" }
+				end
+
+				if workbench_held_by_process?( workbench )
+					return { status: :block, result_status: "block",
+						error: "another process has its working directory inside this worktree",
+						recovery: "wait for the other session to finish, then retry" }
+				end
+
+				if !force && !workbench.clean?
+					return { status: :error, result_status: "error",
+						error: "worktree has uncommitted changes",
+						recovery: "commit or discard changes first, or use --force to override" }
+				end
+
+				unless force || skip_unpushed
+					unpushed = workbench_has_unpushed_work?( workbench )
+					return unpushed if unpushed
+				end
+
+				{ status: :ok, missing: false }
+			end
+
+			# Sweep stale workbenches. Walk all agent-owned workbenches,
+			# check state, tear down those safe to reap. Repair missing ones.
+			def sweep_workbenches!
+				root = main_worktree_root
+
+				agent_prefixes = AGENT_DIRS.map do |dir|
+					full = File.join( root, dir, "worktrees" )
+					File.join( realpath_safe( full ), "" ) if Dir.exist?( full )
+				end.compact
+				return if agent_prefixes.empty?
+
+				workbenches.each do |workbench|
+					next unless workbench.branch
+					next unless agent_prefixes.any? { |prefix| workbench.path.start_with?( prefix ) }
+
+					# Use the existing classifier if available (transitional).
+					if respond_to?( :classify_worktree_cleanup, true )
+						classification = classify_worktree_cleanup( worktree: workbench )
+						next unless classification.fetch( :action ) == :reap
+					end
+
+					unless workbench.exists?
+						repair_missing_workbench!( workbench )
+						next
+					end
+
+					_, _, rm_ok = git( "worktree", "remove", workbench.path )
+					next unless rm_ok.success?
+
+					if workbench.branch
+						git( "branch", "-D", workbench.branch )
+					end
+				end
+			end
+
+		private
+
+			# --- Safety checks ---
+
+			# Is the agent's working directory inside this workbench?
+			def agent_at_workbench?( workbench )
+				cwd = realpath_safe( Dir.pwd )
+				workbench_path = realpath_safe( workbench.path )
+				normalised = File.join( workbench_path, "" )
+				cwd == workbench_path || cwd.start_with?( normalised )
+			rescue StandardError
+				false
+			end
+
+			# Is another process occupying this workbench?
+			def workbench_held_by_process?( workbench )
+				canonical = realpath_safe( workbench.path )
+				return false if canonical.nil? || canonical.empty?
+				return false unless Dir.exist?( canonical )
+
+				stdout, = Open3.capture3( "lsof", "-d", "cwd" )
+				return false if stdout.nil? || stdout.empty?
+
+				normalised = File.join( canonical, "" )
+				my_pid = Process.pid
+				stdout.lines.drop( 1 ).any? do |line|
+					fields = line.strip.split( /\s+/ )
+					next false unless fields.length >= 9
+					next false if fields[ 1 ].to_i == my_pid
+					name = fields[ 8.. ].join( " " )
+					name == canonical || name.start_with?( normalised )
+				end
+			rescue Errno::ENOENT
+				false
+			rescue StandardError
+				false
+			end
+
+			# Would tearing down lose unpushed work?
+			# Content-aware: compares tree content vs main, not SHAs.
+			# Returns nil if safe, or { status:, error:, recovery: } if blocked.
+			def workbench_has_unpushed_work?( workbench )
+				branch = workbench.branch
+				return nil unless branch
+
+				remote_ref = "#{@bureau_address}/#{branch}"
+				ahead, _, ahead_status = Open3.capture3(
+					"git", "rev-list", "--count", "#{remote_ref}..#{branch}",
+					chdir: workbench.path )
+
+				if !ahead_status.success?
+					# Remote ref missing. Only block if branch has unique commits vs main.
+					unique, _, unique_status = Open3.capture3(
+						"git", "rev-list", "--count", "#{@main_label}..#{branch}",
+						chdir: workbench.path )
+					if unique_status.success? && unique.strip.to_i > 0
+						# Content-aware: if diff is empty, work is on main (squash/rebase merged).
+						_, _, diff_ok = Open3.capture3(
+							"git", "diff", "--quiet", @main_label, branch,
+							chdir: workbench.path )
+						unless diff_ok.success?
+							return { status: :block, result_status: "block",
+								error: "branch has not been pushed to #{@bureau_address}",
+								recovery: "git -C #{workbench.path} push -u #{@bureau_address} #{branch}, or use --force to override" }
+						end
+					end
+				elsif ahead.strip.to_i > 0
+					return { status: :block, result_status: "block",
+						error: "worktree has unpushed commits",
+						recovery: "git -C #{workbench.path} push #{@bureau_address} #{branch}, or use --force to override" }
+				end
+
+				nil
+			end
+
+			# --- Repair ---
+
+			# Handle a missing workbench — prune stale registration, clean up label.
+			def repair_missing_workbench!( workbench )
+				branch = workbench.branch
+				git( "worktree", "prune" )
+
+				branch_deleted = false
+				if branch
+					_, _, del_ok = git( "branch", "-D", branch )
+					branch_deleted = del_ok.success?
+				end
+
+				remote_deleted = false
+				if branch
+					_, _, rd_ok = git( "push", @bureau_address, "--delete", branch )
+					remote_deleted = rd_ok.success?
+				end
+
+				{ command: "worktree remove", status: "ok",
+					name: File.basename( workbench.path ),
+					branch: branch, branch_deleted: branch_deleted,
+					remote_deleted: remote_deleted }
+			end
+
+			# --- Build helpers ---
+
+			# Verify the workbench was created correctly.
+			def workbench_creation_verified?( path:, branch: )
+				entry = workbench_at( path: path )
+				return false if entry.nil?
+				return false if entry.prunable?
+				return false unless Dir.exist?( path )
+
+				_, _, success = git( "show-ref", "--verify", "--quiet", "refs/heads/#{branch}" )
+				success.success?
+			end
+
+			# Clean up partial state from a failed build.
+			def cleanup_partial_build!( path:, branch: )
+				FileUtils.rm_rf( path ) if Dir.exist?( path )
+				git( "worktree", "prune" )
+				_, _, ref_ok = git( "show-ref", "--verify", "--quiet", "refs/heads/#{branch}" )
+				git( "branch", "-D", branch ) if ref_ok.success?
+			end
+
+			# Capture diagnostic state for a build verification failure.
+			def gather_build_diagnostics( git_stdout:, git_stderr:, name: )
+				root = main_worktree_root
+				wt_list, = git( "worktree", "list", "--porcelain" )
+				branch_list, = git( "branch", "--list", name )
+				git_version, = Open3.capture3( "git", "--version" )
+				workbench_path = File.join( root, ".claude", "worktrees", name )
+				entry = workbench_at( path: workbench_path )
+				{
+					git_stdout: git_stdout.to_s.strip,
+					git_stderr: git_stderr.to_s.strip,
+					main_worktree_root: root,
+					worktree_list: wt_list.to_s.strip,
+					branch_list: branch_list.to_s.strip,
+					git_version: git_version.to_s.strip,
+					worktree_directory_exists: Dir.exist?( workbench_path ),
+					registered_worktree: !entry.nil?,
+					prunable_reason: entry&.prunable_reason
+				}
+			end
+
+			# Ensure .claude/ is in .git/info/exclude.
+			def ensure_claude_dir_excluded!
+				git_dir = File.join( main_worktree_root, ".git" )
+				return unless File.directory?( git_dir )
+
+				info_dir = File.join( git_dir, "info" )
+				exclude_path = File.join( info_dir, "exclude" )
+
+				FileUtils.mkdir_p( info_dir )
+				existing = File.exist?( exclude_path ) ? File.read( exclude_path ) : ""
+				return if existing.lines.any? { |line| line.strip == ".claude/" }
+
+				File.open( exclude_path, "a" ) { |file| file.puts ".claude/" }
+			rescue StandardError
+				# Best-effort — do not block workbench creation.
+			end
+
+			# Resolve a path to its canonical form, tolerating non-existent paths.
+			def realpath_safe( a_path )
+				File.realpath( a_path )
+			rescue Errno::ENOENT
+				expanded = File.expand_path( a_path )
+				missing_segments = []
+				candidate = expanded
+
+				until File.exist?( candidate ) || Dir.exist?( candidate )
+					parent = File.dirname( candidate )
+					break if parent == candidate
+					missing_segments.unshift( File.basename( candidate ) )
+					candidate = parent
+				end
+
+				base = if File.exist?( candidate ) || Dir.exist?( candidate )
+					File.realpath( candidate )
+				else
+					candidate
+				end
+
+				missing_segments.empty? ? base : File.join( base, *missing_segments )
+			end
+		end
+	end
+end

data/lib/carson/warehouse.rb

@@ -1,18 +1,24 @@
 # A governed repository. In the FedEx metaphor, the warehouse is where
-# parcels (committed changes) are stored on shelves (worktrees) with
-# labels (branches). Git and gh commands are hidden inside — callers
-# never see git or GitHub terms.
-require "digest"
+# parcels are built on workbenches (worktrees) with labels (branches).
+# Git and gh commands are hidden inside — callers never see git or
+# GitHub terms.
 require "fileutils"
-require "json"
 require "open3"
 
+require_relative "warehouse/workbench"
+require_relative "warehouse/seal"
+require_relative "warehouse/bureau"
+
 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.
+	# A governed repository — the warehouse where parcels are built on
+	# workbenches (worktrees) with labels (branches). An intelligent
+	# warehouse that manages itself: packing parcels, checking compliance,
+	# managing workbenches, and sweeping up.
 	class Warehouse
+		include Workbench
+		include Seal
+		include Bureau
+
 		attr_reader :path
 
 		def initialize( path:, main_label: "main", bureau_address: "github", compliance_checker: nil )
@@ -24,12 +30,12 @@ module Carson
 
 		# --- What the warehouse knows ---
 
-		# The label on the current shelf (branch name).
+		# The label on the current workbench (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).
+		# The tip of the parcel on the current workbench (commit SHA).
 		def current_head
 			git( "rev-parse", "HEAD" ).first.strip
 		end
@@ -44,7 +50,7 @@ module Carson
 			@bureau_address
 		end
 
-		# Is the warehouse floor clean? No uncommitted changes on the current shelf.
+		# Is the warehouse floor clean? No uncommitted changes on the current workbench.
 		def clean?
 			output, _, status = git( "status", "--porcelain" )
 			status.success? && output.strip.empty?
@@ -78,7 +84,6 @@ module Carson
 		# 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
 
@@ -87,15 +92,13 @@ module Carson
 
 		# 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.
-		# Refuses if the shelf is sealed (parcel already in flight).
-		# Returns true on success, false on failure.
+		# Refuses if the workbench is sealed (parcel already in flight).
 		def pack!( message: )
 			if sealed?
 				raise "Branch is locked — PR ##{sealed_tracking_number} in flight. " \
@@ -106,38 +109,8 @@ module Carson
 			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).
@@ -146,24 +119,20 @@ module Carson
 		def receive_latest_standard!( remote: bureau_address )
 			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"
 			)
 			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}"
 				)
@@ -171,72 +140,8 @@ 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).
-		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)" )
@@ -249,88 +154,31 @@ module Carson
 			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.
+		# All worktree paths (transitional — use workbenches for Worktree instances).
+		def shelves
+			output, = git( "worktree", "list", "--porcelain" )
+			output.lines
+				.select { it.start_with?( "worktree " ) }
+				.map { it.sub( "worktree ", "" ).strip }
+		end
+
+		# The main warehouse location — resolves correctly even from a workbench.
 		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
 
-		# 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 )
 			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/worktree.rb

@@ -420,6 +420,16 @@ module Carson
 			false
 		end
 
+		# Is the workbench surface clean? (no uncommitted changes)
+		def clean?
+			return false unless exists?
+
+			stdout, = Open3.capture3( "git", "status", "--porcelain", chdir: path )
+			stdout.to_s.strip.empty?
+		rescue StandardError
+			false
+		end
+
 	# rubocop:disable Layout/AccessModifierIndentation -- tab-width calculation produces unfixable mixed tabs+spaces
 	private
 	# rubocop:enable Layout/AccessModifierIndentation

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 4.1.1
+  version: 4.1.2
 platform: ruby
 authors:
 - Hailei Wang
@@ -53,11 +53,11 @@ files:
 - RELEASE.md
 - VERSION
 - carson.gemspec
-- config/.github/hooks/command-guard
-- config/.github/hooks/pre-commit
-- config/.github/hooks/pre-merge-commit
-- config/.github/hooks/pre-push
-- config/.github/hooks/prepare-commit-msg
+- config/hooks/command-guard
+- config/hooks/pre-commit
+- config/hooks/pre-merge-commit
+- config/hooks/pre-push
+- config/hooks/prepare-commit-msg
 - exe/carson
 - icon.svg
 - lib/carson.rb
@@ -103,6 +103,9 @@ files:
 - lib/carson/runtime/status.rb
 - lib/carson/version.rb
 - lib/carson/warehouse.rb
+- lib/carson/warehouse/bureau.rb
+- lib/carson/warehouse/seal.rb
+- lib/carson/warehouse/workbench.rb
 - lib/carson/waybill.rb
 - lib/carson/worktree.rb
 homepage: https://github.com/wanghailei/carson