carson 3.11.0 → 3.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d6a7526cb4973b9f911b8fd28d151ca719cbb53be7d42beb29e676d0d9354f4
-  data.tar.gz: 4b116460df0e2e9397edf0f60432abb907d7b81f1e28a4d7e8bceda47e030db7
+  metadata.gz: 1d653b3c6ec67aa729186db46215c6e51c85a42ac82ca782f5004f9d84e32a31
+  data.tar.gz: 5caa70de1a5c9538c3ef3027ba0862445c9ff2d985ec6f4659231bb40d8e5cb7
 SHA512:
-  metadata.gz: 807185f0bbeb5c2762b89c8a59aed681006a1589a66024f2cf546972416bde79ad858be69cceb685a6b762a8594d95efa41607323f1d5469f3d70709b64a57f1
-  data.tar.gz: 7d7c6a06a7bf4b75428a57afa891f04dadf1ca402ac35cfee2d968658963e180b8b2ed27a1aa2a8c78c057456d319977ddfce6d022f945281081c9d7b936a7ff
+  metadata.gz: 91bd6ee521d91f31c3593558e1b544fcba99eefd1d084fb8c618fad428c470d308ed774e7655b31be9d0fc35969bd9d5354832d5002042396e3d48b8ffde77b2
+  data.tar.gz: 10758df9aeb5d246211592671eb19c59156cbd9fd7cb5d6e31e32186ee36d1caef8fe3dc7c785bdbfbac4e1339ee8d56bf445556a6722395f8eb42a2bfdabe12

data/RELEASE.md

@@ -5,11 +5,36 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 3.13.0
+
+### What changed
+
+- **Worktree create auto-syncs main** — `carson worktree create` now pulls the main branch from remote (`--ff-only`) before branching. Prevents stale-base merge conflicts that waste agent context resolving later. Best-effort: if pull fails (offline, non-fast-forward), creation continues from the local main.
+- **Deliver prints next steps after merge** — `carson deliver --merge` now tells the agent exactly what to do after a successful merge. If running inside a worktree, prints `cd <main_root> && carson worktree remove <name>`. If not, suggests `carson prune`. Available in both human and JSON output (`next_step` field).
+
+### UX improvement
+
+- Agents no longer need to remember post-merge cleanup steps — Carson tells them.
+- Agents no longer hit merge conflicts from stale main — Carson syncs before branching.
+
+## 3.12.0
+
+### What changed
+
+- **Drop session state** — removed the `session` and `session clear` CLI commands, session file persistence (`~/.carson/sessions/`), and all session side effects from `worktree create`, `worktree remove`, and `deliver`. Session state duplicated information already available from better sources (`git worktree list`, `gh pr list`, memory files). No agent ever read another agent's session file. Convention ("don't touch other sessions' worktrees") beat engineered tracking.
+- **Simplify status** — `carson status` no longer shows session ownership annotations on worktrees. Worktree display now shows name and branch only — the same information `git worktree list` provides.
+
+### Breaking changes
+
+- `carson session` and `carson session clear` no longer exist.
+- Session files in `~/.carson/sessions/` are no longer written or read. Existing files are inert.
+- `carson status` worktree entries no longer include `owner`, `owner_pid`, `owner_task`, or `stale` fields in JSON output.
+
 ## 3.11.0
 
 ### What changed
 
-- **Drop `worktree done`** — removed the `worktree done` subcommand entirely. `worktree remove` now handles everything: CWD safety guard, unpushed-commits guard, session state cleanup, branch and remote deletion. Two operations (create, remove) instead of three. Simpler, safer, less to remember.
+- **Drop `worktree done`** — removed the `worktree done` subcommand entirely. `worktree remove` now handles everything: CWD safety guard, unpushed-commits guard, branch and remote deletion. Two operations (create, remove) instead of three. Simpler, safer, less to remember.
 
 ### Breaking changes
 

data/VERSION

@@ -1 +1 @@
-3.11.0
+3.13.0

data/lib/carson/cli.rb

@@ -53,7 +53,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [status [--json]|setup|audit [--json]|sync [--json]|deliver [--merge] [--json] [--title T] [--body-file F]|prune [--all] [--json]|worktree [--json] create|remove <name>|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|session [--json] [--task T]|session clear [--json]|version]"
+				opts.banner = "Usage: carson [status [--json]|setup|audit [--json]|sync [--json]|deliver [--merge] [--json] [--title T] [--body-file F]|prune [--all] [--json]|worktree [--json] create|remove <name>|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -98,8 +98,6 @@ module Carson
 				parse_deliver_command( argv: argv, err: err )
 			when "govern"
 				parse_govern_subcommand( argv: argv, err: err )
-			when "session"
-				parse_session_command( argv: argv, err: err )
 			else
 				parser.parse!( argv )
 				{ command: command }
@@ -334,29 +332,6 @@ module Carson
 			{ command: :invalid }
 		end
 
-		def self.parse_session_command( argv:, err: )
-			json_flag = argv.delete( "--json" ) ? true : false
-			task_value = nil
-			# Check for --task "description"
-			task_index = argv.index( "--task" )
-			if task_index
-				argv.delete_at( task_index )
-				task_value = argv.delete_at( task_index )
-				if task_value.to_s.strip.empty?
-					err.puts "#{BADGE} Missing value for --task. Use: carson session --task \"description\""
-					return { command: :invalid }
-				end
-			end
-
-			action = argv.first
-			if action == "clear"
-				argv.shift
-				return { command: "session:clear", json: json_flag }
-			end
-
-			{ command: "session", json: json_flag, task: task_value }
-		end
-
 		def self.dispatch( parsed:, runtime: )
 			command = parsed.fetch( :command )
 			return Runtime::EXIT_ERROR if command == :invalid
@@ -407,13 +382,6 @@ module Carson
 					json_output: parsed.fetch( :json, false ),
 					loop_seconds: parsed.fetch( :loop_seconds, nil )
 				)
-			when "session"
-				runtime.session!(
-					task: parsed.fetch( :task, nil ),
-					json_output: parsed.fetch( :json, false )
-				)
-			when "session:clear"
-				runtime.session_clear!( json_output: parsed.fetch( :json, false ) )
 			else
 				runtime.send( :puts_line, "Unknown command: #{command}" )
 				Runtime::EXIT_ERROR

data/lib/carson/runtime/deliver.rb

@@ -36,10 +36,6 @@ module Carson
 
 				result[ :pr_number ] = pr_number
 				result[ :pr_url ] = pr_url
-
-				# Record PR in session state.
-				update_session( pr: { number: pr_number, url: pr_url } )
-
 				# Without --merge, we are done.
 				unless merge
 					return deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
@@ -78,12 +74,12 @@ module Carson
 
 				result[ :merged ] = true
 
-				# Step 6: clear worktree from session state.
-				update_session( worktree: :clear )
-
-				# Step 7: sync main in the main worktree.
+				# Step 6: sync main in the main worktree.
 				sync_after_merge!( remote: remote, main: main, result: result )
 
+				# Step 7: compute next-step guidance for the agent.
+				compute_post_merge_next_step!( result: result )
+
 				deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
 			end
 
@@ -135,6 +131,7 @@ module Carson
 
 				if result[ :merged ]
 					puts_line "Merged PR ##{result[ :pr_number ]} via #{result[ :merge_method ]}."
+					puts_line "  Next: #{result[ :next_step ]}" if result[ :next_step ]
 				end
 			end
 
@@ -297,6 +294,24 @@ module Carson
 					puts_verbose "sync failed: #{pull_stderr.to_s.strip}"
 				end
 			end
+
+			# Builds next-step guidance after a successful merge.
+			# Detects whether the agent is inside a worktree and suggests cleanup.
+			def compute_post_merge_next_step!( result: )
+				main_root = main_worktree_root
+				cwd = realpath_safe( Dir.pwd )
+				current_wt = worktree_list.select { |wt| wt.fetch( :path ) != realpath_safe( main_root ) }
+					.find { |wt| cwd == wt.fetch( :path ) || cwd.start_with?( File.join( wt.fetch( :path ), "" ) ) }
+
+				if current_wt
+					wt_name = File.basename( current_wt.fetch( :path ) )
+					result[ :next_step ] = "cd #{main_root} && carson worktree remove #{wt_name}"
+				else
+					result[ :next_step ] = "carson prune"
+				end
+			rescue StandardError
+				# Best-effort — do not fail deliver because of next-step detection.
+			end
 		end
 
 		include Deliver

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

@@ -24,6 +24,13 @@ module Carson
 				# Determine the base branch (main branch from config).
 				base = config.main_branch
 
+				# Sync main from remote before branching so the worktree starts
+				# from the latest code. Prevents stale-base merge conflicts later.
+				# Best-effort — if pull fails (non-ff, offline), continue anyway.
+				main_root = main_worktree_root
+				_, _, pull_ok, = Open3.capture3( "git", "-C", main_root, "pull", "--ff-only", config.git_remote, base )
+				puts_verbose pull_ok.success? ? "synced #{base} before branching" : "sync skipped — continuing from local #{base}"
+
 				# Ensure .claude/ is excluded from git status in the host repository.
 				# Uses .git/info/exclude (local-only, never committed) to respect the outsider boundary.
 				ensure_claude_dir_excluded!
@@ -41,9 +48,6 @@ module Carson
 					)
 				end
 
-				# Record active worktree in session state.
-				update_session( worktree: { name: name, path: wt_path, branch: name } )
-
 				worktree_finish(
 					result: { command: "worktree create", status: "ok", name: name, path: wt_path, branch: name },
 					exit_code: EXIT_OK, json_output: json_output
@@ -154,10 +158,6 @@ module Carson
 						remote_deleted = true
 					end
 				end
-
-				# Clear worktree from session state.
-				update_session( worktree: :clear )
-
 				worktree_finish(
 					result: { command: "worktree remove", status: "ok", name: File.basename( resolved_path ),
 						branch: branch, branch_deleted: branch_deleted, remote_deleted: remote_deleted },

data/lib/carson/runtime/status.rb

@@ -1,5 +1,5 @@
-# Agent session briefing — one command to know the full state of the estate.
-# Gathers branch, working tree, worktrees, open PRs, stale branches,
+# Agent briefing — one command to know the full state of the estate.
+# Gathers branch, worktrees, open PRs, stale branches,
 # governance health, and version. Supports human-readable and JSON output.
 module Carson
 	class Runtime
@@ -81,49 +81,20 @@ module Carson
 				end
 			end
 
-			# Lists all worktrees with branch, lifecycle state, and session ownership.
+			# Lists all worktrees with branch name.
 			def gather_worktree_info
 				entries = worktree_list
-				sessions = session_list
-				ownership = build_worktree_ownership( sessions: sessions )
 
 				# Filter out the main worktree (the repository root itself).
 				# Use realpath for comparison — git returns canonical paths that may differ from repo_root.
 				canonical_root = realpath_safe( repo_root )
 				entries.reject { |wt| wt.fetch( :path ) == canonical_root }.map do |wt|
-					name = File.basename( wt.fetch( :path ) )
-					info = {
+					{
 						path: wt.fetch( :path ),
-						name: name,
+						name: File.basename( wt.fetch( :path ) ),
 						branch: wt.fetch( :branch, nil )
 					}
-					owner = ownership[ name ]
-					if owner
-						info[ :owner ] = owner[ :session_id ]
-						info[ :owner_pid ] = owner[ :pid ]
-						info[ :owner_task ] = owner[ :task ]
-						info[ :stale ] = owner[ :stale ]
-					end
-					info
-				end
-			end
-
-			# Builds a name-to-session mapping for worktree ownership.
-			def build_worktree_ownership( sessions: )
-				result = {}
-				sessions.each do |session|
-					wt = session[ :worktree ]
-					next unless wt
-					name = wt[ :name ] || wt[ "name" ]
-					next unless name
-					result[ name ] = {
-						session_id: session[ :session_id ] || session[ "session_id" ],
-						pid: session[ :pid ] || session[ "pid" ],
-						task: session[ :task ] || session[ "task" ],
-						stale: session[ :stale ]
-					}
 				end
-				result
 			end
 
 			# Queries open PRs via gh.
@@ -209,8 +180,7 @@ module Carson
 					puts_line "Worktrees:"
 					worktrees.each do |wt|
 						branch_label = wt.fetch( :branch ) || "(detached)"
-						owner_label = format_worktree_owner( worktree: wt )
-						puts_line "  #{wt.fetch( :name )}  #{branch_label}#{owner_label}"
+						puts_line "  #{wt.fetch( :name )}  #{branch_label}"
 					end
 				end
 
@@ -244,24 +214,6 @@ module Carson
 				end
 			end
 
-			# Formats owner annotation for a worktree entry.
-			def format_worktree_owner( worktree: )
-				owner = worktree[ :owner ]
-				return "" unless owner
-
-				stale = worktree[ :stale ]
-				task = worktree[ :owner_task ]
-				pid = worktree[ :owner_pid ]
-
-				if stale
-					"  (stale session #{pid})"
-				elsif task
-					"  (#{task})"
-				else
-					"  (session #{pid})"
-				end
-			end
-
 			# Formats sync status for display.
 			def format_sync( sync: )
 				case sync

data/lib/carson/runtime.rb

@@ -222,4 +222,3 @@ require_relative "runtime/govern"
 require_relative "runtime/setup"
 require_relative "runtime/status"
 require_relative "runtime/deliver"
-require_relative "runtime/session"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.11.0
+  version: 3.13.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -67,7 +67,6 @@ files:
 - lib/carson/runtime/review/query_text.rb
 - lib/carson/runtime/review/sweep_support.rb
 - lib/carson/runtime/review/utility.rb
-- lib/carson/runtime/session.rb
 - lib/carson/runtime/setup.rb
 - lib/carson/runtime/status.rb
 - lib/carson/version.rb

data/lib/carson/runtime/session.rb

@@ -1,228 +0,0 @@
-# Session state persistence for coding agents.
-# Maintains a lightweight JSON file per session in ~/.carson/sessions/<repo_slug>/
-# so agents can discover the current working context without re-running discovery commands.
-# Multiple agents on the same repo each get their own session file.
-# Respects the outsider boundary: state lives in Carson's own space, not the repository.
-require "digest"
-
-module Carson
-	class Runtime
-		module Session
-			# Reads and displays current session state for this repository.
-			def session!( task: nil, json_output: false )
-				if task
-					update_session( worktree: nil, pr: nil, task: task )
-					state = read_session
-					return session_finish(
-						result: state.merge( command: "session", status: "ok" ),
-						exit_code: EXIT_OK, json_output: json_output
-					)
-				end
-
-				state = read_session
-				session_finish(
-					result: state.merge( command: "session", status: "ok" ),
-					exit_code: EXIT_OK, json_output: json_output
-				)
-			end
-
-			# Clears session state for the current session.
-			def session_clear!( json_output: false )
-				path = session_file_path
-				File.delete( path ) if File.exist?( path )
-				session_finish(
-					result: { command: "session clear", status: "ok", repo: repo_root },
-					exit_code: EXIT_OK, json_output: json_output
-				)
-			end
-
-			# Records session state — called as a side effect from other commands.
-			# Only non-nil values are updated; nil values preserve existing state.
-			def update_session( worktree: nil, pr: nil, task: nil )
-				state = read_session
-
-				if worktree == :clear
-					state.delete( :worktree )
-				elsif worktree
-					state[ :worktree ] = worktree
-				end
-
-				if pr == :clear
-					state.delete( :pr )
-				elsif pr
-					state[ :pr ] = pr
-				end
-
-				state[ :task ] = task if task
-				state[ :repo ] = repo_root
-				state[ :session_id ] = session_id
-				state[ :pid ] = Process.pid
-				state[ :updated_at ] = Time.now.utc.iso8601
-
-				write_session( state )
-			end
-
-			# Returns all active sessions for this repository.
-			# Each entry is a parsed session state hash with staleness annotation.
-			def session_list
-				dir = session_repo_dir
-				return [] unless Dir.exist?( dir )
-
-				Dir.glob( File.join( dir, "*.json" ) ).filter_map do |path|
-					data = JSON.parse( File.read( path ), symbolize_names: true ) rescue next
-					data[ :stale ] = session_stale?( data )
-					data
-				end
-			end
-
-		private
-
-			# Returns a stable session identifier for this Runtime instance.
-			# PID + start timestamp — unique per process, stable across calls.
-			def session_id
-				@session_id ||= "#{Process.pid}-#{Time.now.utc.strftime( '%Y%m%d%H%M%S' )}"
-			end
-
-			# Returns the per-repo session directory: ~/.carson/sessions/<slug>/
-			# Migrates from the pre-3.9 single-file format if found.
-			def session_repo_dir
-				slug = session_repo_slug
-				dir = File.join( carson_home, "sessions", slug )
-
-				# Migrate from pre-3.9 single-file format: <slug>.json → <slug>/<session_id>.json
-				old_file = File.join( carson_home, "sessions", "#{slug}.json" )
-				if File.file?( old_file ) && !Dir.exist?( dir )
-					FileUtils.mkdir_p( dir )
-					migrated = File.join( dir, "migrated.json" )
-					FileUtils.mv( old_file, migrated )
-				end
-
-				FileUtils.mkdir_p( dir )
-				dir
-			end
-
-			# Returns the session file path for the current session.
-			def session_file_path
-				File.join( session_repo_dir, "#{session_id}.json" )
-			end
-
-			# Generates a readable, unique slug for the repository: basename-shortsha.
-			def session_repo_slug
-				basename = File.basename( repo_root )
-				short_hash = Digest::SHA256.hexdigest( repo_root )[ 0, 8 ]
-				"#{basename}-#{short_hash}"
-			end
-
-			# Returns Carson's home directory (~/.carson).
-			def carson_home
-				home = ENV.fetch( "HOME", "" ).to_s
-				return File.join( home, ".carson" ) if !home.empty? && home.start_with?( "/" )
-
-				File.join( "/tmp", ".carson" )
-			end
-
-			# Reads session state from disk. Returns an empty hash if no state exists.
-			def read_session
-				path = session_file_path
-				return { repo: repo_root, session_id: session_id } unless File.exist?( path )
-
-				data = JSON.parse( File.read( path ), symbolize_names: true )
-				data[ :repo ] = repo_root
-				data[ :session_id ] = session_id
-				data
-			rescue JSON::ParserError, StandardError
-				{ repo: repo_root, session_id: session_id }
-			end
-
-			# Writes session state to disk as formatted JSON.
-			def write_session( state )
-				path = session_file_path
-				# Convert symbol keys to strings for clean JSON output.
-				string_state = deep_stringify_keys( state )
-				File.write( path, JSON.pretty_generate( string_state ) + "\n" )
-			end
-
-			# Recursively converts symbol keys to strings for JSON serialisation.
-			def deep_stringify_keys( hash )
-				hash.each_with_object( {} ) do |( key, value ), result|
-					string_key = key.to_s
-					result[ string_key ] = value.is_a?( Hash ) ? deep_stringify_keys( value ) : value
-				end
-			end
-
-			# Detects whether a session is stale — PID no longer running and updated
-			# more than 1 hour ago.
-			def session_stale?( data )
-				pid = data[ :pid ]
-				updated = data[ :updated_at ]
-
-				# If PID is still running, not stale.
-				if pid
-					begin
-						Process.kill( 0, pid.to_i )
-						return false
-					rescue Errno::ESRCH
-						# Process not running — check age.
-					rescue Errno::EPERM
-						# Process exists but we lack permission — assume active.
-						return false
-					end
-				end
-
-				# If no timestamp, assume stale.
-				return true unless updated
-
-				# Stale if last updated more than 1 hour ago.
-				age = Time.now.utc - Time.parse( updated )
-				age > 3600
-			rescue StandardError
-				true
-			end
-
-			# Unified output for session results — JSON or human-readable.
-			def session_finish( result:, exit_code:, json_output: )
-				result[ :exit_code ] = exit_code
-
-				if json_output
-					out.puts JSON.pretty_generate( result )
-				else
-					print_session_human( result: result )
-				end
-
-				exit_code
-			end
-
-			# Human-readable output for session state.
-			def print_session_human( result: )
-				if result[ :command ] == "session clear"
-					puts_line "Session state cleared."
-					return
-				end
-
-				puts_line "Session: #{File.basename( result[ :repo ].to_s )}"
-
-				if result[ :worktree ]
-					wt = result[ :worktree ]
-					puts_line "  Worktree: #{wt[ :name ] || wt[ "name" ]} (#{wt[ :branch ] || wt[ "branch" ]})"
-				end
-
-				if result[ :pr ]
-					pr = result[ :pr ]
-					puts_line "  PR: ##{pr[ :number ] || pr[ "number" ]} #{pr[ :url ] || pr[ "url" ]}"
-				end
-
-				if result[ :task ]
-					puts_line "  Task: #{result[ :task ]}"
-				end
-
-				if result[ :updated_at ]
-					puts_line "  Updated: #{result[ :updated_at ]}"
-				end
-
-				puts_line "  No active session state." unless result[ :worktree ] || result[ :pr ] || result[ :task ]
-			end
-		end
-
-		include Session
-	end
-end