carson 3.6.0 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d430ed51ffe8ee87c8aa2a652c63d92ef7e9f0a65713b9104dd4df57dbcba90a
-  data.tar.gz: d5bf899e7acc479cb5f673c0ba0323dce10e83a6c8d843f418d9db53adbbed38
+  metadata.gz: ec88c12e0edb3541ab43fbefd93c75ef87dfe6032217c1132f6e3cc9857428cf
+  data.tar.gz: cba06c9b0c85e0884157e6e2794a58140cbfd903da6eb61d9eb1e96f2f182860
 SHA512:
-  metadata.gz: 903da2928ca57d07422e7450670efb7686603934fc2b7aa8122789fcea6ecce2e1b841420c15c2df39dc33b2789c4d3a85a0cb56dc5816aa1b0216fa103f7cb5
-  data.tar.gz: 2c67d3aa87576d0124d3ea2fb31fdaf8457cbfb81199c539e103072636a1fcaef4e1274c3642d1a843117c1cd88a69e437cf369c5f981a06fed50d6e57e0d2f3
+  metadata.gz: 33367440b238d8ba9872aac28da62a10bd74aa6179398bde682860ea798851af3943d9f932a5a157b0913449fa82c9961800f0d832a065fe73b6f9b902a148d6
+  data.tar.gz: 4fc299aa1cc6b15f0a7498659912395691213fdfd2d778594a4c6ba52ca9ad77f87db810dc91bdb4a47d1f4aa34a2f7c375d62a5b0d9a481847189798cc36e5d

data/RELEASE.md

@@ -5,6 +5,46 @@ 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.8.0 — Session State
+
+### What changed
+
+- **`carson session`** — reads and displays the current session state for a repository. Shows active worktree, PR, task description, and last-updated timestamp.
+- **`carson session --task "description"`** — records a task description in session state so agents resuming work can discover the current objective.
+- **`carson session clear`** — removes all session state for the current repository.
+- **`carson session --json`** / **`carson session clear --json`** — machine-readable JSON output for all session commands.
+- **Side-effect integration** — `worktree_create!` automatically records the active worktree in session state; `worktree_done!` clears it; `deliver!` records the PR number and URL.
+- **Outsider-safe storage** — session files live at `~/.carson/sessions/<basename>-<hash>.json`, outside the user's repository.
+
+### UX
+
+- Human output shows a concise summary: session name, worktree, PR, task, and timestamp.
+- "No active session state" displayed when no context has been recorded.
+- Session state persists across Carson invocations — agents can `carson session --json` to discover context without re-running discovery commands.
+- `update_session` uses a `:clear` sentinel to selectively remove fields without touching others.
+
+### Migration
+
+- No breaking changes. New command — no existing behaviour affected.
+
+## 3.7.0 — Worktree JSON + Recovery
+
+### What changed
+
+- **`carson worktree --json create|done|remove`** — machine-readable JSON output for all three worktree commands. Each returns a structured envelope with `command`, `status`, `name`, `exit_code`, and context-specific fields (`path`, `branch`, `next_step`).
+- **Recovery-aware worktree errors** — every error and block path includes a `recovery` field with the exact command to run next. Dirty worktree, missing name, unregistered worktree, unpushed commits — all include actionable recovery.
+- **Unified `worktree_finish` / `print_worktree_human`** — consistent output pattern matching deliver, sync, and prune.
+
+### UX
+
+- Human output preserved unchanged when `--json` is not passed.
+- `worktree done` includes `next_step` in JSON output pointing to `carson worktree remove`.
+- `worktree remove` includes `branch_deleted` and `remote_deleted` booleans for complete lifecycle visibility.
+
+### Migration
+
+- No breaking changes. All worktree commands without `--json` behave identically to 3.6.0.
+
 ## 3.6.0 — Prune JSON + Recovery
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.6.0
+3.8.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 create|done|remove <name>|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|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|done|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]"
 			end
 		end
 
@@ -98,6 +98,8 @@ 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 }
@@ -175,6 +177,7 @@ module Carson
 		end
 
 		def self.parse_worktree_subcommand( argv:, parser:, err: )
+			json_flag = argv.delete( "--json" ) ? true : false
 			action = argv.shift
 			if action.to_s.strip.empty?
 				err.puts "#{BADGE} Missing subcommand for worktree. Use: carson worktree create|done|remove <name>"
@@ -189,10 +192,10 @@ module Carson
 					err.puts "#{BADGE} Missing name for worktree create. Use: carson worktree create <name>"
 					return { command: :invalid }
 				end
-				{ command: "worktree:create", worktree_name: name }
+				{ command: "worktree:create", worktree_name: name, json: json_flag }
 			when "done"
 				name = argv.shift
-				{ command: "worktree:done", worktree_name: name }
+				{ command: "worktree:done", worktree_name: name, json: json_flag }
 			when "remove"
 				force = argv.delete( "--force" ) ? true : false
 				worktree_path = argv.shift
@@ -200,7 +203,7 @@ module Carson
 					err.puts "#{BADGE} Missing path for worktree remove. Use: carson worktree remove <name-or-path>"
 					return { command: :invalid }
 				end
-				{ command: "worktree:remove", worktree_path: worktree_path, force: force }
+				{ command: "worktree:remove", worktree_path: worktree_path, force: force, json: json_flag }
 			else
 				err.puts "#{BADGE} Unknown worktree subcommand: #{action}. Use: carson worktree create|done|remove <name>"
 				{ command: :invalid }
@@ -334,6 +337,29 @@ 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
@@ -352,11 +378,11 @@ module Carson
 			when "prune:all"
 				runtime.prune_all!
 			when "worktree:create"
-				runtime.worktree_create!( name: parsed.fetch( :worktree_name ) )
+				runtime.worktree_create!( name: parsed.fetch( :worktree_name ), json_output: parsed.fetch( :json, false ) )
 			when "worktree:done"
-				runtime.worktree_done!( name: parsed.fetch( :worktree_name, nil ) )
+				runtime.worktree_done!( name: parsed.fetch( :worktree_name, nil ), json_output: parsed.fetch( :json, false ) )
 			when "worktree:remove"
-				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ), force: parsed.fetch( :force, false ) )
+				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ), force: parsed.fetch( :force, false ), json_output: parsed.fetch( :json, false ) )
 			when "onboard"
 				runtime.onboard!
 			when "refresh"
@@ -386,6 +412,13 @@ 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

@@ -37,6 +37,9 @@ 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 )

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

@@ -1,19 +1,23 @@
+# Safe worktree lifecycle management for coding agents.
+# Three operations: create, done (mark completed), remove (batch cleanup).
+# The deferred deletion model: worktrees persist after use, cleaned up later.
+# Supports --json for machine-readable structured output with recovery commands.
 module Carson
 	class Runtime
 		module Local
-			# Safe worktree lifecycle management for coding agents.
-			# Three operations: create, done (mark completed), remove (batch cleanup).
-			# The deferred deletion model: worktrees persist after use, cleaned up later.
 
 			# Creates a new worktree under .claude/worktrees/<name> with a fresh branch.
-			def worktree_create!( name: )
+			def worktree_create!( name:, json_output: false )
 				worktrees_dir = File.join( repo_root, ".claude", "worktrees" )
 				wt_path = File.join( worktrees_dir, name )
 
 				if Dir.exist?( wt_path )
-					puts_line "ERROR: worktree already exists: #{name}"
-					puts_line "  Path: #{wt_path}"
-					return EXIT_ERROR
+					return worktree_finish(
+						result: { command: "worktree create", status: "error", name: name, path: wt_path,
+							error: "worktree already exists: #{name}",
+							recovery: "carson worktree remove #{name}, then retry" },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				end
 
 				# Determine the base branch (main branch from config).
@@ -25,38 +29,54 @@ module Carson
 				unless wt_success
 					error_text = wt_stderr.to_s.strip
 					error_text = "unable to create worktree" if error_text.empty?
-					puts_line "ERROR: #{error_text}"
-					return EXIT_ERROR
+					return worktree_finish(
+						result: { command: "worktree create", status: "error", name: name,
+							error: error_text },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				end
 
-				puts_line "Worktree created: #{name}"
-				puts_line "  Path: #{wt_path}"
-				puts_line "  Branch: #{name}"
-				EXIT_OK
+				# 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
+				)
 			end
 
 			# Marks a worktree as completed without deleting it.
 			# Verifies all changes are committed. Deferred deletion — cleanup happens later.
-			def worktree_done!( name: nil )
+			def worktree_done!( name: nil, json_output: false )
 				if name.to_s.strip.empty?
-					# Try to detect current worktree from CWD.
-					puts_line "ERROR: missing worktree name. Use: carson worktree done <name>"
-					return EXIT_ERROR
+					return worktree_finish(
+						result: { command: "worktree done", status: "error",
+							error: "missing worktree name",
+							recovery: "carson worktree done <name>" },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				end
 
 				resolved_path = resolve_worktree_path( worktree_path: name )
 
 				unless worktree_registered?( path: resolved_path )
-					puts_line "ERROR: #{name} is not a registered worktree."
-					return EXIT_ERROR
+					return worktree_finish(
+						result: { command: "worktree done", status: "error", name: name,
+							error: "#{name} is not a registered worktree",
+							recovery: "git worktree list" },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				end
 
 				# Check for uncommitted changes in the worktree.
 				wt_status, _, status_success, = Open3.capture3( "git", "status", "--porcelain", chdir: resolved_path )
 				if status_success && !wt_status.strip.empty?
-					puts_line "Worktree has uncommitted changes: #{name}"
-					puts_line "  Commit your changes first, then run `carson worktree done #{name}` again."
-					return EXIT_BLOCK
+					return worktree_finish(
+						result: { command: "worktree done", status: "block", name: name,
+							error: "worktree has uncommitted changes",
+							recovery: "git -C #{resolved_path} add -A && git -C #{resolved_path} commit, then carson worktree done #{name}" },
+						exit_code: EXIT_BLOCK, json_output: json_output
+					)
 				end
 
 				# Check for unpushed commits.
@@ -66,39 +86,57 @@ module Carson
 					remote_ref = "#{remote}/#{branch}"
 					ahead, _, ahead_ok, = Open3.capture3( "git", "rev-list", "--count", "#{remote_ref}..#{branch}", chdir: resolved_path )
 					if ahead_ok && ahead.strip.to_i > 0
-						puts_line "Worktree has unpushed commits: #{name}"
-						puts_line "  Push with `git -C #{resolved_path} push #{remote} #{branch}` first."
-						return EXIT_BLOCK
+						return worktree_finish(
+							result: { command: "worktree done", status: "block", name: name, branch: branch,
+								error: "worktree has unpushed commits",
+								recovery: "git -C #{resolved_path} push #{remote} #{branch}" },
+							exit_code: EXIT_BLOCK, json_output: json_output
+						)
 					end
 				end
 
-				puts_line "Worktree done: #{name}"
-				puts_line "  Branch: #{branch || '(detached)'}"
-				puts_line "  Cleanup later with `carson worktree remove #{name}` or `carson housekeep`."
-				EXIT_OK
+				# Clear worktree from session state.
+				update_session( worktree: :clear )
+
+				worktree_finish(
+					result: { command: "worktree done", status: "ok", name: name, branch: branch || "(detached)",
+						next_step: "carson worktree remove #{name}" },
+					exit_code: EXIT_OK, json_output: json_output
+				)
 			end
 
 			# Removes a worktree: directory, git registration, and branch.
 			# Never forces removal — if the worktree has uncommitted changes, refuses unless
 			# the user explicitly passes force: true via CLI --force flag.
-			def worktree_remove!( worktree_path:, force: false )
+			def worktree_remove!( worktree_path:, force: false, json_output: false )
 				fingerprint_status = block_if_outsider_fingerprints!
-				return fingerprint_status unless fingerprint_status.nil?
+				unless fingerprint_status.nil?
+					if json_output
+						out.puts JSON.pretty_generate( {
+							command: "worktree remove", status: "block",
+							error: "Carson-owned artefacts detected in host repository",
+							recovery: "remove Carson-owned files (.carson.yml, bin/carson, .tools/carson) then retry",
+							exit_code: EXIT_BLOCK
+						} )
+					end
+					return fingerprint_status
+				end
 
 				resolved_path = resolve_worktree_path( worktree_path: worktree_path )
 
 				unless worktree_registered?( path: resolved_path )
-					puts_line "ERROR: #{resolved_path} is not a registered worktree."
-					puts_line "  Registered worktrees:"
-					worktree_list.each { |wt| puts_line "  - #{wt.fetch( :path )} [#{wt.fetch( :branch )}]" }
-					return EXIT_ERROR
+					return worktree_finish(
+						result: { command: "worktree remove", status: "error", name: File.basename( resolved_path ),
+							error: "#{resolved_path} is not a registered worktree",
+							recovery: "git worktree list" },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				end
 
 				branch = worktree_branch( path: resolved_path )
 				puts_verbose "worktree_remove: path=#{resolved_path} branch=#{branch} force=#{force}"
 
 				# Step 1: remove the worktree (directory + git registration).
-				# Try safe removal first. Only use --force if the user explicitly requested it.
 				rm_args = [ "worktree", "remove" ]
 				rm_args << "--force" if force
 				rm_args << resolved_path
@@ -107,40 +145,96 @@ module Carson
 					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" ) )
-						puts_line "Worktree has uncommitted changes: #{File.basename( resolved_path )}"
-						puts_line "  Commit or discard changes first, or use --force to override."
-					else
-						puts_line "ERROR: #{error_text}"
+						return worktree_finish(
+							result: { command: "worktree remove", status: "error", name: File.basename( resolved_path ),
+								error: "worktree has uncommitted changes",
+								recovery: "commit or discard changes first, or use --force to override" },
+							exit_code: EXIT_ERROR, json_output: json_output
+						)
 					end
-					return EXIT_ERROR
+					return worktree_finish(
+						result: { command: "worktree remove", status: "error", name: File.basename( resolved_path ),
+							error: error_text },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				end
 				puts_verbose "worktree_removed: #{resolved_path}"
 
 				# Step 2: delete the local branch.
+				branch_deleted = false
 				if branch && !config.protected_branches.include?( branch )
 					_, del_stderr, del_success, = git_run( "branch", "-D", branch )
 					if del_success
 						puts_verbose "branch_deleted: #{branch}"
+						branch_deleted = true
 					else
 						puts_verbose "branch_delete_skipped: #{branch} reason=#{del_stderr.to_s.strip}"
 					end
 				end
 
 				# Step 3: delete the remote branch (best-effort).
+				remote_deleted = false
 				if branch && !config.protected_branches.include?( branch )
 					remote_branch = branch
-					git_run( "push", config.git_remote, "--delete", remote_branch )
-					puts_verbose "remote_branch_deleted: #{config.git_remote}/#{remote_branch}"
+					_, _, rd_success, = git_run( "push", config.git_remote, "--delete", remote_branch )
+					if rd_success
+						puts_verbose "remote_branch_deleted: #{config.git_remote}/#{remote_branch}"
+						remote_deleted = true
+					end
 				end
 
-				unless verbose?
-					puts_line "Worktree removed: #{File.basename( resolved_path )}"
-				end
-				EXIT_OK
+				worktree_finish(
+					result: { command: "worktree remove", status: "ok", name: File.basename( resolved_path ),
+						branch: branch, branch_deleted: branch_deleted, remote_deleted: remote_deleted },
+					exit_code: EXIT_OK, json_output: json_output
+				)
 			end
 
 		private
 
+			# Unified output for worktree results — JSON or human-readable.
+			def worktree_finish( result:, exit_code:, json_output: )
+				result[ :exit_code ] = exit_code
+
+				if json_output
+					out.puts JSON.pretty_generate( result )
+				else
+					print_worktree_human( result: result )
+				end
+
+				exit_code
+			end
+
+			# Human-readable output for worktree results.
+			def print_worktree_human( 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 done"
+						puts_line "Worktree done: #{result[ :name ]}"
+						puts_line "  Branch: #{result[ :branch ]}"
+						puts_line "  Cleanup later with `#{result[ :next_step ]}` or `carson housekeep`."
+					when "worktree remove"
+						unless verbose?
+							puts_line "Worktree removed: #{result[ :name ]}"
+						end
+					end
+				when "error"
+					puts_line "ERROR: #{result[ :error ]}"
+					puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+				when "block"
+					puts_line "#{result[ :error ]&.capitalize || 'Blocked'}: #{result[ :name ]}"
+					puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+				end
+			end
+
 			# Resolves a worktree path: if it's a bare name, look under .claude/worktrees/.
 			def resolve_worktree_path( worktree_path: )
 				return File.expand_path( worktree_path ) if worktree_path.include?( "/" )

data/lib/carson/runtime/session.rb

@@ -0,0 +1,161 @@
+# Session state persistence for coding agents.
+# Maintains a lightweight JSON file per repository in ~/.carson/sessions/ so
+# agents can discover the current working context without re-running discovery commands.
+# 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 this repository.
+			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[ :updated_at ] = Time.now.utc.iso8601
+
+				write_session( state )
+			end
+
+		private
+
+			# Returns the session file path for this repository.
+			def session_file_path
+				sessions_dir = File.join( carson_home, "sessions" )
+				FileUtils.mkdir_p( sessions_dir )
+				slug = session_repo_slug
+				File.join( sessions_dir, "#{slug}.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 } unless File.exist?( path )
+
+				data = JSON.parse( File.read( path ), symbolize_names: true )
+				data[ :repo ] = repo_root
+				data
+			rescue JSON::ParserError, StandardError
+				{ repo: repo_root }
+			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
+
+			# 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

data/lib/carson/runtime.rb

@@ -222,3 +222,4 @@ 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.6.0
+  version: 3.8.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -67,6 +67,7 @@ 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