carson 3.7.0 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43f5ee17800cad35a51d2aaaf6ce306197bf2823cc6b0de4858912213d06e01b
-  data.tar.gz: 51b3a3e91d84a98266b2bccee868e583c25609c5466e34c938b2fa2bcd6564fc
+  metadata.gz: ffbada076dd17e9f8ae9a85e9abce9abbc84e23b71324c8cde1ffec1db537071
+  data.tar.gz: 4654c5d248f856818ffa83600b4db21838c0f665bb6a16f2d45d566643312ec6
 SHA512:
-  metadata.gz: c7bca3554a185fc1951292d62e0bfcfd6b63d77488d22013f14b93885e6b8d043d2d30e20e8e9725796d26bc3aaa031bcce8f0b28474ab3198bf77733c56f0c5
-  data.tar.gz: ce3240db72d7fb1c6a5aa9f590628d23e3533778cc492def9c73951a8f5b6772a347cb8d64c79e0063fb79f67f16fb663c9a8ecdc33db7f9af15e0204678adfd
+  metadata.gz: b4e517ccc14a75a2389bf5743fdd095b2796605c5c7fbeb4d12af4b0f237f370a275e2ff244436da4439b10e44b38a7aceae44c26b858d2224a8b0a25b1d193f
+  data.tar.gz: a1de0764868ee6fda99d4f74f5ec10dfc2071a84e65102ab77749e83a8307aee37aa661d98b3670e1d62aeda28f1be1a05093283ac697de3a39ad542256e6da9

data/RELEASE.md

@@ -5,6 +5,48 @@ 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.9.0 — Agent Coordination Signals
+
+### What changed
+
+- **Per-session state files** — each Runtime instance gets a unique session ID (`<pid>-<timestamp>`) and its own session file at `~/.carson/sessions/<repo_slug>/<session_id>.json`. Multiple agents on the same repo each have independent state that does not collide.
+- **Session ownership on worktrees** — `carson status` cross-references active session files to annotate each worktree with its owning session's PID, task, and staleness. Other agents can see which worktrees are in use and by whom.
+- **Staleness detection** — sessions whose PID is no longer running and whose last update is older than 1 hour are marked as `stale`. This signals to other agents that the worktree may be abandoned and available for cleanup.
+- **`session_list`** — new method that scans all session files for the current repo and returns structured data with staleness annotations.
+- **Migration from 3.8 format** — old single-file session state (`<slug>.json`) is automatically migrated to the per-session directory format on first access.
+
+### UX
+
+- `carson status` worktree listing now shows owner context: task description if set, PID if no task, or "stale session" if the owner is no longer running.
+- `carson session --json` now includes `session_id` and `pid` fields for correlation by other agents.
+- Human output unchanged when no session ownership data exists.
+
+### Migration
+
+- Automatic. The old `<slug>.json` file is moved into the new `<slug>/` directory as `migrated.json` on first access. No user action required.
+
+## 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

data/VERSION

@@ -1 +1 @@
-3.7.0
+3.9.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|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 }
@@ -335,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
@@ -387,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

@@ -36,6 +36,9 @@ 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
@@ -92,6 +95,9 @@ module Carson
 					end
 				end
 
+				# 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}" },

data/lib/carson/runtime/session.rb

@@ -0,0 +1,228 @@
+# 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

data/lib/carson/runtime/status.rb

@@ -81,17 +81,47 @@ module Carson
 				end
 			end
 
-			# Lists all worktrees with branch and lifecycle state.
+			# Lists all worktrees with branch, lifecycle state, and session ownership.
 			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).
 				entries.reject { |wt| wt.fetch( :path ) == repo_root }.map do |wt|
-					{
+					name = File.basename( wt.fetch( :path ) )
+					info = {
 						path: wt.fetch( :path ),
-						name: File.basename( wt.fetch( :path ) ),
+						name: name,
 						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.
@@ -177,7 +207,8 @@ module Carson
 					puts_line "Worktrees:"
 					worktrees.each do |wt|
 						branch_label = wt.fetch( :branch ) || "(detached)"
-						puts_line "  #{wt.fetch( :name )}  #{branch_label}"
+						owner_label = format_worktree_owner( worktree: wt )
+						puts_line "  #{wt.fetch( :name )}  #{branch_label}#{owner_label}"
 					end
 				end
 
@@ -211,6 +242,24 @@ 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,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.7.0
+  version: 3.9.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