Struct AgentRegistry 

pub struct AgentRegistry { /* private fields */ }

Manages agent registry entries stored in .heddle/agents/.

Implementations

impl AgentRegistry

pub fn new(heddle_dir: &Path) -> Self

Create a new registry backed by <heddle_dir>/agents/.

pub fn liveness_for(entry: &AgentEntry) -> Liveness

Liveness verdict for an active entry. Terminal entries (anything other than Active) are reported as Dead so reaping logic can skip them in one pass alongside crashed actives.

pub fn reap_dead_for_thread(&self, thread: &str) -> Result<usize>

Reap any active reservation on thread whose owning process is no longer alive. Returns the number of entries abandoned.

This is the read-side complement of [try_reserve_thread]: callers that only need a fresh view of which sessions are alive (e.g. heddle agent list --alive-only) can run it without reserving.

pub fn reap_dead(&self) -> Result<usize>

Reap dead reservations across every thread.

pub fn create_generated_entry<F>(&self, build_entry: F) -> Result<AgentEntry>

where F: FnMut(&str) -> Result<AgentEntry>,

Create and persist a new agent entry with a unique generated session ID.

pub fn save(&self, entry: &AgentEntry) -> Result<()>

Persist an agent entry.

Atomic write: uses write-to-temp-then-rename so a crash mid-write never leaves the TOML file truncated or partially written.

pub fn load(&self, session_id: &str) -> Result<Option<AgentEntry>>

Load a single agent entry by session ID.

pub fn list(&self) -> Result<Vec<AgentEntry>>

List all agent entries, most-recently-started first.

pub fn update_status(&self, session_id: &str, status: AgentStatus) -> Result<()>

Update the status of an agent entry in place.

pub fn update_entry<F>( &self, session_id: &str, update: F, ) -> Result<Option<AgentEntry>>

where F: FnMut(&mut AgentEntry),

Mutate an existing agent entry under the registry write lock.

pub fn find_or_create_active_entry<FMatch, FUpdate, FBuild>( &self, matches: FMatch, update_existing: FUpdate, build_entry: FBuild, ) -> Result<(AgentEntry, bool)>

where FMatch: FnMut(&AgentEntry) -> bool, FUpdate: FnMut(&mut AgentEntry), FBuild: FnMut(&str) -> Result<AgentEntry>,

Under one registry write lock, reuse a matching active entry if one exists; otherwise create a new generated entry.

pub fn try_reserve_thread<F>( &self, thread: &str, build_entry: F, ) -> Result<ReserveOutcome>

where F: FnMut(&str) -> Result<AgentEntry>,

Atomic “reap dead, then reserve” for a single thread.

Under one registry write lock this:

1. Prunes terminal-status entries past their TTL.
2. Transitions any active entry whose recorded owner has died (per liveness_for) to Abandoned.
3. If a still-living active entry on thread remains, returns ReserveOutcome::LiveOwner with that entry.
4. Otherwise builds and persists a new entry, returning ReserveOutcome::Reserved.

Both cmd_agent_reserve (the JSON API) and start_thread route through here, so reaping and conflict detection share exactly one code path.

pub fn create_generated_entry_for_thread<F>( &self, thread: &str, build_entry: F, ) -> Result<AgentEntry>

where F: FnMut(&str) -> Result<AgentEntry>,

Backwards-compatible thin wrapper around [try_reserve_thread] that returns the same flat Result<AgentEntry> shape callers historically expected. Live-owner conflicts surface as a HeddleError::Config(..) with the same human-readable message as before.

pub fn find_active_by_path( &self, worktree_root: &Path, ) -> Result<Option<AgentEntry>>

Find the active session whose visible or private execution root matches the given worktree root.

pub fn find_active_by_heddle_session_id( &self, heddle_session_id: &str, ) -> Result<Option<AgentEntry>>

Find the active registry entry associated with the given Heddle session ID.

pub fn find_active_by_client_instance_id( &self, client_instance_id: &str, ) -> Result<Option<AgentEntry>>

Find the active registry entry associated with a stable harness-side client instance identifier.

pub fn find_active_by_native_actor_key( &self, native_actor_key: &str, ) -> Result<Option<AgentEntry>>

Find the active registry entry associated with a harness-native actor key.

pub fn actor_chain_for_session( &self, session_id: &str, ) -> Result<Vec<ActorChainNode>>

Return this actor’s native parent chain, ordered root to leaf.

The lookup intentionally follows harness-native actor keys rather than thread names: subagents may work in lightweight directories or forked threads, but the native parent key is the stable “who spawned whom” edge that preserves Human -> agent -> agent attribution.

pub fn find_active_by_native_instance_key_at_path( &self, native_instance_key: &str, worktree_root: &Path, ) -> Result<Option<AgentEntry>>

Find the active registry entry associated with a harness-native instance key inside the given worktree root.

pub fn log_context_query( &self, session_id: &str, query: ContextQueryEntry, ) -> Result<()>

Append a context query to an active session’s log.

Best-effort: silently ignored if the session no longer exists or has completed.

pub fn delete(&self, session_id: &str) -> Result<()>

Delete an agent entry.