carson 3.8.0 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec88c12e0edb3541ab43fbefd93c75ef87dfe6032217c1132f6e3cc9857428cf
-  data.tar.gz: cba06c9b0c85e0884157e6e2794a58140cbfd903da6eb61d9eb1e96f2f182860
+  metadata.gz: ffbada076dd17e9f8ae9a85e9abce9abbc84e23b71324c8cde1ffec1db537071
+  data.tar.gz: 4654c5d248f856818ffa83600b4db21838c0f665bb6a16f2d45d566643312ec6
 SHA512:
-  metadata.gz: 33367440b238d8ba9872aac28da62a10bd74aa6179398bde682860ea798851af3943d9f932a5a157b0913449fa82c9961800f0d832a065fe73b6f9b902a148d6
-  data.tar.gz: 4fc299aa1cc6b15f0a7498659912395691213fdfd2d778594a4c6ba52ca9ad77f87db810dc91bdb4a47d1f4aa34a2f7c375d62a5b0d9a481847189798cc36e5d
+  metadata.gz: b4e517ccc14a75a2389bf5743fdd095b2796605c5c7fbeb4d12af4b0f237f370a275e2ff244436da4439b10e44b38a7aceae44c26b858d2224a8b0a25b1d193f
+  data.tar.gz: a1de0764868ee6fda99d4f74f5ec10dfc2071a84e65102ab77749e83a8307aee37aa661d98b3670e1d62aeda28f1be1a05093283ac697de3a39ad542256e6da9

data/RELEASE.md

@@ -5,6 +5,26 @@ 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

data/VERSION

@@ -1 +1 @@
-3.8.0
+3.9.0

data/lib/carson/runtime/session.rb

@@ -1,6 +1,7 @@
 # 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.
+# 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"
 
@@ -25,7 +26,7 @@ module Carson
 				)
 			end
 
-			# Clears session state for this repository.
+			# Clears session state for the current session.
 			def session_clear!( json_output: false )
 				path = session_file_path
 				File.delete( path ) if File.exist?( path )
@@ -54,19 +55,55 @@ module Carson
 
 				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 the session file path for this repository.
-			def session_file_path
-				sessions_dir = File.join( carson_home, "sessions" )
-				FileUtils.mkdir_p( sessions_dir )
+			# 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
-				File.join( sessions_dir, "#{slug}.json" )
+				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.
@@ -87,13 +124,14 @@ module Carson
 			# 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 )
+				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 }
+				{ repo: repo_root, session_id: session_id }
 			end
 
 			# Writes session state to disk as formatted JSON.
@@ -112,6 +150,35 @@ module Carson
 				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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.8.0
+  version: 3.9.0
 platform: ruby
 authors:
 - Hailei Wang