carson 4.1.1 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d709f0737b7411687d882b100598ae5d86bef2cf05cc39b493e567c03e687aa4
-  data.tar.gz: 968d6124cc0406f21f44ce6430e4635954f8aecb77bca53ff7d1d111cce2dbe3
+  metadata.gz: 57e828abcdfc77caa38be92fa08a41d8d13abd37a09e7a4bf726d07253a48749
+  data.tar.gz: 5a6141be7046db72d03971fc9c4f45f1b7c81a47d685b13c97810711ebe9db39
 SHA512:
-  metadata.gz: fae3226c3f11a5fb7a7269d086a8c1f1dfc2bbd5e4ca71b2823663891189fb1bc8a8da3eb67dd93a6462f20857f3ead10c4cd456efd618eb830b650b75b92f44
-  data.tar.gz: 67bf606c7221408e585145f2e37452e260ed417de8016c7f0f776b70218db821cd4c9ba7ef564cf2d689336fe989d7a2bcceb22b0be492d3f6a4a649b85a8906
+  metadata.gz: 409ab608b1bed1423f16aa257efcc53f608643112db23020ac1786bd77fcc94a1776df32991be7ff0c00eb5d9b31f6db454e1ea4ad6020b65aaeb4dd186e39aa
+  data.tar.gz: a482b66aa5220c17d9d1b4c2852cc10b9cfeaa0d8af803e0b7974c20994754b1eb2affbb4d3a5659804764a398f25f7c822ffe3feaaa61b4c6b7fea46cf4b88a

data/API.md

@@ -173,7 +173,7 @@ Environment overrides:
 - `agent.codex` / `agent.claude`: provider-specific options (reserved).
 - `check_wait`: seconds to wait for CI checks before classifying (default: `30`).
 - `merge.method`: `"squash"` only in governed mode.
-- `state_path`: JSON ledger path for active deliveries and revisions. Legacy SQLite ledgers are imported automatically on first read; explicit legacy `.sqlite3` paths keep working after import.
+- `state_path`: JSON ledger path for active deliveries and revisions.
 
 `template` schema:
 

data/RELEASE.md

@@ -7,6 +7,31 @@ Release-note scope rule:
 
 ## Unreleased
 
+## 4.2.0
+
+### New
+
+- **`carson checkin <name>`** — the agent's verb for getting a fresh workbench. Receives the latest production standard before building. Sweeps delivered workbenches automatically — the Warehouse cleans behind the agent, so explicit checkout is rarely needed.
+- **`carson checkout <name>`** — the agent's verb for releasing a workbench when done. Checks the seal (parcel in flight blocks checkout), CWD, process holds, dirty state, and unpushed work. Use at end of session; the common case is handled by the next checkin.
+
+### Changed
+
+- **CLI moved outside the story world** — `lib/carson/cli.rb` → `lib/cli.rb`. `lib/carson/` is domain objects only. checkin and checkout wire CLI directly to Warehouse with no Runtime. This is the template for Runtime dissolution.
+- **`tear_down_workbench!` renamed to `remove_workbench!`** — simpler verb, matches the domain.
+- **Remote branch deletion removed from workbench removal** — GitHub handles remote branch cleanup on PR merge. The Warehouse now only removes the directory and local branch.
+
+### UX
+
+- `carson checkin` output: `⧓ Workbench ready: <name>` with path and branch.
+- `carson checkout` output: `⧓ Workbench released: <name>`.
+- Agent lifecycle simplified: `checkin → work → deliver → checkin` (repeat). No explicit checkout between tasks.
+
+## 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.2.0

data/carson.gemspec

@@ -28,7 +28,6 @@ Gem::Specification.new do |spec|
 	spec.bindir = "exe"
 	spec.executables = [ "carson" ]
 	spec.require_paths = [ "lib" ]
-	spec.add_dependency "sqlite3", ">= 1.3", "< 3"
 	spec.files = Dir.glob( "{lib,exe,templates,config}/**/*", File::FNM_DOTMATCH ).select { |path| File.file?( path ) } + [
 		".github/workflows/carson_policy.yml",
 		"README.md",

data/lib/carson/ledger.rb

@@ -7,12 +7,10 @@ module Carson
 	class Ledger
 		UNSET = Object.new
 		ACTIVE_DELIVERY_STATES = Delivery::ACTIVE_STATES
-		SQLITE_HEADER = "SQLite format 3\0".b.freeze
 
 		def initialize( path: )
 			@path = File.expand_path( path )
 			FileUtils.mkdir_p( File.dirname( @path ) )
-			migrate_legacy_state_if_needed!
 		end
 
 		attr_reader :path
@@ -273,22 +271,6 @@ module Carson
 			)
 		end
 
-		def migrate_legacy_state_if_needed!
-			# Skip lock acquisition entirely when no legacy SQLite file exists.
-			# Read-only file checks are safe without the lock; the migration
-			# itself is idempotent so a narrow race is harmless.
-			return unless state_path_requires_migration?
-
-			with_state_lock do |lock_file|
-				lock_file.flock( File::LOCK_EX )
-				source_path = legacy_sqlite_source_path
-				next unless source_path
-
-				state = load_legacy_sqlite_state( path: source_path )
-				save_state!( state )
-			end
-		end
-
 		def with_state_lock
 			lock_path = "#{path}.lock"
 			FileUtils.mkdir_p( File.dirname( lock_path ) )
@@ -299,110 +281,6 @@ module Carson
 			end
 		end
 
-		def legacy_sqlite_source_path
-			return nil unless state_path_requires_migration?
-			return path if sqlite_database_file?( path: path )
-
-			legacy_path = legacy_state_path
-			return nil unless legacy_path
-			return legacy_path if sqlite_database_file?( path: legacy_path )
-
-			nil
-		end
-
-		def state_path_requires_migration?
-			return true if sqlite_database_file?( path: path )
-			return false if File.exist?( path )
-			!legacy_state_path.nil?
-		end
-
-		def legacy_state_path
-			return nil unless path.end_with?( ".json" )
-			path.sub( /\.json\z/, ".sqlite3" )
-		end
-
-		def sqlite_database_file?( path: )
-			return false unless File.file?( path )
-			File.binread( path, SQLITE_HEADER.bytesize ) == SQLITE_HEADER
-		rescue StandardError
-			false
-		end
-
-		def load_legacy_sqlite_state( path: )
-			begin
-				require "sqlite3"
-			rescue LoadError => exception
-				raise "legacy SQLite ledger found at #{path}, but sqlite3 support is unavailable: #{exception.message}"
-			end
-
-			database = open_legacy_sqlite_database( path: path )
-			deliveries = database.execute( "SELECT * FROM deliveries ORDER BY id ASC" )
-			revisions_by_delivery = database.execute(
-				"SELECT * FROM revisions ORDER BY delivery_id ASC, number ASC, id ASC"
-			).group_by { |row| row.fetch( "delivery_id" ) }
-
-			state = {
-				"deliveries" => {},
-				"recovery_events" => [],
-				"next_sequence" => 1
-			}
-			deliveries.each do |row|
-				key = delivery_key(
-					repo_path: row.fetch( "repo_path" ),
-					branch_name: row.fetch( "branch_name" ),
-					head: row.fetch( "head" )
-				)
-				state[ "deliveries" ][ key ] = {
-					"sequence" => row.fetch( "id" ).to_i,
-					"repo_path" => row.fetch( "repo_path" ),
-					"branch_name" => row.fetch( "branch_name" ),
-					"head" => row.fetch( "head" ),
-					"worktree_path" => row.fetch( "worktree_path" ),
-					"status" => row.fetch( "status" ),
-					"pr_number" => row.fetch( "pr_number" ),
-					"pr_url" => row.fetch( "pr_url" ),
-					"pull_request_state" => nil,
-					"pull_request_draft" => nil,
-					"pull_request_merged_at" => nil,
-					"merge_proof" => nil,
-					"cause" => row.fetch( "cause" ),
-					"summary" => row.fetch( "summary" ),
-					"created_at" => row.fetch( "created_at" ),
-					"updated_at" => row.fetch( "updated_at" ),
-					"integrated_at" => row.fetch( "integrated_at" ),
-					"superseded_at" => row.fetch( "superseded_at" ),
-					"revisions" => Array( revisions_by_delivery[ row.fetch( "id" ) ] ).map do |revision|
-						{
-							"number" => revision.fetch( "number" ).to_i,
-							"cause" => revision.fetch( "cause" ),
-							"provider" => revision.fetch( "provider" ),
-							"status" => revision.fetch( "status" ),
-							"started_at" => revision.fetch( "started_at" ),
-							"finished_at" => revision.fetch( "finished_at" ),
-							"summary" => revision.fetch( "summary" )
-						}
-					end
-				}
-			end
-			normalise_state!( state: state )
-			state
-		ensure
-			database&.close
-		end
-
-		def open_legacy_sqlite_database( path: )
-			database = SQLite3::Database.new( "file:#{path}?immutable=1", readonly: true, uri: true )
-			database.results_as_hash = true
-			database.busy_timeout = 5_000
-			database
-		rescue SQLite3::CantOpenException
-			database&.close
-			database = SQLite3::Database.new( path, readonly: true )
-			database.results_as_hash = true
-			database.busy_timeout = 5_000
-			database
-		end
-
 		def normalise_state!( state: )
 			deliveries = state[ "deliveries" ]
 			raise "state file must contain a JSON object at #{path}" unless deliveries.is_a?( Hash )

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_removal( 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.remove_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