Struct DataPaths 

pub struct DataPaths {
    pub home_dir: PathBuf,
    pub instance_dir: PathBuf,
    pub channel: String,
    pub data_dir: PathBuf,
    pub config_dir: PathBuf,
    pub logs_dir: PathBuf,
    pub cef_cache_dir: PathBuf,
    pub agents_dir: PathBuf,
    pub instance_runtime_dir: PathBuf,
    pub shared_dir: PathBuf,
    pub mode: RuntimeMode,
}

All paths a launcher / host / srv needs. Computed once by the launcher; downstream binaries read paths from env vars set by the launcher rather than recomputing (avoids the legacy desync risk where each binary made its own portable / dev-mode determination).

Fields

home_dir: PathBuf

~/.agentmux/ itself — the resolved root. Account-wide config that predates the unified layout (e.g. the launcher’s config.toml) lives directly here. Honors AGENTMUX_HOME_OVERRIDE for tests.

instance_dir: PathBuf

Top-level dir for this channel+mode. All per-channel paths below are children. Either ~/.agentmux/channels/<channel>/ (installed / portable / AGENTMUX_CHANNEL override) or ~/.agentmux/dev/<branch>/ (dev mode without env override).

Note: the field name is instance_dir for backward compat with downstream call sites; semantically it’s now the channel root, not the version root.

channel: String

Channel identifier this resolution used (e.g. "stable", "dev-portable", "dev-main", or a user-specified custom channel from AGENTMUX_CHANNEL). Surfaced for diagnostics, logging, and the launcher splash; downstream binaries usually don’t need it (paths are passed via env vars).

data_dir: PathBuf

instance_dir/data/ — srv DB (objects.db, sagas.db, …).

config_dir: PathBuf

instance_dir/config/ — settings.json, repos.json, etc.

logs_dir: PathBuf

instance_dir/logs/ — host + srv + launcher logs (rotated).

cef_cache_dir: PathBuf

instance_dir/cef-cache/ — Chromium runtime cache (regenerable).

agents_dir: PathBuf

instance_dir/agents/ — agent workspace state.

instance_runtime_dir: PathBuf

instance_dir/runtime/ — single-instance lock + IPC (pid, lockfile, ipc-port, named-pipe). One set per version+mode.

shared_dir: PathBuf

~/.agentmux/shared/ — version-independent, account-wide state (cookies, OAuth tokens, API keys, dictionary downloads).

mode: RuntimeMode

Snapshot of the RuntimeMode this resolution used. Helpful for logging and feature gates.

Implementations

impl DataPaths

pub fn resolve(version: &str, mode: &RuntimeMode) -> Result<Self, String>

Resolve all paths for the given version + mode. Honors AGENTMUX_HOME_OVERRIDE for tests (replaces ~/.agentmux root).

Returns Err if the input contains values that cannot be represented as a safe single-segment subpath — e.g. .. in the version string, or a Dev branch that sanitizes to empty. This is belt-and-braces safety: parse-time sanitization in crate::RuntimeMode should already have caught these, but a RuntimeMode::Dev { branch } constructed directly (e.g. by a test or future caller) is also rejected here.

pub fn resolve_path_only( version: &str, mode: &RuntimeMode, ) -> Result<Self, String>

Like Self::resolve, but ignores the AGENTMUX_CHANNEL env override and uses only the mode-based default channel. Mirror of RuntimeMode::current_path_only for path resolution.

Used by dev-build self-detection paths in agentmux-cef’s main.rs and sidecar.rs. Those paths run when a dev host has been launched from inside a parent AgentMux instance (e.g. task dev invoked from inside an agent pane in a portable build), where the child would otherwise inherit the parent’s AGENTMUX_* env — including AGENTMUX_CHANNEL — and write into the parent’s channel instead of dev/<branch>/. That cross-contamination would also trip the channel’s single- instance lock and route every “open” back to the parent window. Path-based mode detection is authoritative for dev builds; channel resolution here mirrors that discipline. Codex P1 follow-up on PR #1027.

pub fn ensure_dirs(&self) -> Result<(), String>

Create every directory that may be written to. Idempotent. Safe to call on every launch.

pub fn to_env_vars(&self) -> Vec<(&'static str, OsString)>

Env vars to pass to host + srv subprocesses. The launcher computes DataPaths once and exports these; downstream binaries read them via Self::from_env instead of recomputing.

Returns OsString (not String) so paths with non-UTF-8 bytes — possible on Linux/macOS for users with exotic home dirs — round-trip losslessly. Command::env(k, v) accepts any AsRef<OsStr>, so the OsString flows through to children unchanged. The mode value is the only String-typed entry (it’s a fixed ASCII vocabulary).

pub fn from_env() -> Option<Self>

Reconstruct from env vars set by the launcher. Returns None if any required var is missing — fail-fast vs. silently falling back to legacy paths the way the old sidecar.rs did.

Uses var_os (not var) so non-UTF-8 path bytes survive.

pub fn identities_dir(&self) -> PathBuf

~/.agentmux/shared/identities/ — root for per-bundle OAuth credential directories. Lives under shared_dir so it’s account-wide and version-independent: upgrading agentmux does not move a user’s bundle credentials. Per SPEC_OAUTH_IDENTITY_BUNDLES_2026_05_22.md §4.1.

pub fn identity_dir(&self, bundle_id: &str) -> Option<PathBuf>

~/.agentmux/shared/identities/<bundle_id>/ — a specific bundle’s credential root, when bundle_id is a safe path segment. Returns None for empty / . / .. / any segment containing /, \, drive-letter colons, or Windows-reserved characters (same rules as the version/branch sanitizer in resolve).

Defensive return type: bundle_id flows from auth.start request bodies (PR C) into create_dir_all, so an unvalidated PathBuf::join would let a crafted id escape the identities root and write outside the bundle area. codex P1 follow-up on #981.

Per-provider subdirectories (e.g. claude/, codex/) hang off this when the bundle gains an OAuth binding (PR C). The directory is created lazily by the bundle / OAuth flow that needs it — ensure_dirs() does not pre-create it.

Trait Implementations

impl Clone for DataPaths

fn clone(&self) -> DataPaths

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DataPaths

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.