Struct Registry 

pub struct Registry {
    root: PathBuf,
    write_lock: Mutex<()>,
}

Fields

root: PathBuf

write_lock: Mutex<()>

Implementations

impl Registry

pub fn open(root: PathBuf) -> Result<Self, RegistryError>

Open or create the registry rooted at root. Ensures the active dir and retired/ subdir both exist.

pub fn root(&self) -> &Path

pub fn agents_root(&self) -> Option<&Path>

Resolved <shared_home>/agents/ — one level above root. Used by callers that need to express working-directory paths as relative subpaths under the shared agents tree. Returns None if the registry root has no parent (only happens in pathological filesystem-root setups; production always nests under ~/.agentmux/agents/registry).

fn active_path(&self, instance_id: &str) -> PathBuf

fn retired_path(&self, instance_id: &str) -> PathBuf

pub fn upsert(&self, rec: &NamedAgentRecord) -> Result<(), RegistryError>

Insert or update a record. If the file already exists, unknown top-level + data fields are preserved (forward-compat with future schemas that add columns this binary doesn’t know).

Forward-compat invariant (spec §6): never write a higher-schema row into a lower schema, never overwrite a corrupt/unparseable file. Both cases skip the mirror with a warning — the on-disk file stays intact for the binary that authored it (or for ops triage). Skipping is Ok(()): SQLite remains authoritative.

pub fn retire(&self, instance_id: &str) -> Result<(), RegistryError>

Move record into retired/ (soft delete — keeps the working dir intact, drops it from the launch-modal dropdown). Idempotent.

pub fn unretire(&self, instance_id: &str) -> Result<(), RegistryError>

Move record back from retired/ to active. Idempotent.

pub fn hard_delete(&self, instance_id: &str) -> Result<(), RegistryError>

Hard-delete (drops both active and retired files). Mirrors SQLite instance_delete.

pub fn exists(&self, instance_id: &str) -> bool

Whether an active record exists for instance_id. Doesn’t validate — useful for migration idempotency checks. Use Self::exists_anywhere when retired records should also count (e.g. so migration doesn’t resurrect a hidden agent).

pub fn exists_anywhere(&self, instance_id: &str) -> bool

Whether a record exists in either active or retired. Used by migration to skip already-tombstoned records (avoid resurrecting a user’s deliberate “Forget agent” via a per-version SQLite row that still has display_hidden = 0).

pub fn list_active(&self) -> Result<Vec<NamedAgentRecord>, RegistryError>

Read every valid active record. Invalid files are skipped + logged. PR A doesn’t wire this into the RPC path; included so PR B can swap reads over without further restructuring.