Module data_paths 

Unified data-path resolution for AgentMux.

Single source of truth for where state lives on disk. Replaces the launcher / host / sidecar trio of independent path computations (see docs/specs/archive/SPEC_DATA_DIR_UNIFICATION_2026-05-05.md §3) and the per-version isolation pattern it set up (data was keyed on the build version so My Agents reset on every patch bump). The current model keys data on a channel — a stable identifier that spans versions within the same compat band, so agents survive rebuilds. See docs/specs/SPEC_DATA_CHANNELS_2026_05_24.md and discussion #1026 for the channel design and rationale.

Layout:

~/.agentmux/
├── shared/                       (cookies, credentials, account-wide)
├── channels/<channel>/           (installed + portable + custom)
│   ├── data/, config/, logs/, cef-cache/, agents/
│   └── runtime/                  (lock + IPC, single instance per channel)
└── dev/<branch>/                 (per-branch dev isolation)
    └── (same children as channels/<channel>/)

Channel resolution (via DataPaths::resolve):

• AGENTMUX_CHANNEL=<name> env override wins for Installed / Portable modes — lets the operator point a released binary at any channel for parallel-channel testing.
• RuntimeMode::Installed / Portable w/o override → build-time default from AGENTMUX_BUILD_CHANNEL_DEFAULT (set by the packaging script; defaults to "stable" if unset, e.g. for cargo run).
• RuntimeMode::Dev { branch } → channel name is dev-<branch> for diagnostics; on-disk path stays at ~/.agentmux/dev/<branch>/ (NOT under channels/). Both the host (agentmux-cef) and launcher (agentmux-launcher) use DataPaths::resolve_path_only for dev builds to ignore AGENTMUX_CHANNEL — a dev session launched from inside a parent agentmux pane mustn’t inherit the parent’s channel and break per-branch isolation. Channel override is intentionally NOT supported in dev mode; if you want a different channel, use a portable build.

Structs

DataPaths

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).

Enums

IsolatedAuthReason

Which rule decided isolated_auth_enabled’s result — for boot-time diagnostics (see bootstrap/stores.rs’s “shared store: attached” log line) so a developer staring at an empty Connectors → Accounts can tell at a glance whether that is an explicit choice, rather than re-deriving it from the env by hand. Callers that only need the boolean should use isolated_auth_enabled directly — this exists purely so the two never drift (one resolution, two views).

IsolatedMuxbusReconnectReason

Which rule decided isolated_muxbus_reconnect_enabled’s result — mirrors IsolatedAuthReason/IsolatedSettingsReason exactly, same rationale (one resolution, two views).

IsolatedSettingsReason

Which rule decided isolated_settings_enabled’s result — for boot-time diagnostics, mirroring IsolatedAuthReason exactly (see that type’s doc comment for the rationale: one resolution, two views, so the boolean and the log line can never drift apart).

OwnerOnlyOutcome

What ensure_owner_only_dir did.

Functions

agentmux_root

The AgentMux root (~/.agentmux) — the single resolver for it.

ensure_history_link

Best-effort: ensure link_path (a projects/ subdirectory inside an isolated_auth_enabled-isolated provider credential dir) is a directory junction (Windows) / symlink (Unix) pointing at target_dir (the always-global DataPaths::identity_history_dir), so a provider’s session transcripts stay reachable across a channel/build change even though the credential directory around them is per-channel isolated. See docs/specs/SPEC_AGENT_IDENTITY_HISTORY_PERSISTENCE_PROTOCOL_2026_08_16.md §4.1.

ensure_owner_only_dir

Make dir owner-only on Unix: create it 0700 if missing (its parents with the normal umask — they are the user’s, not AgentMux’s), or strip group/other bits from an existing directory, keeping the owner bits as they were. See DataPaths::ensure_dirs for why (#3682).

isolated_auth_enabled

Isolated per-channel auth (identity accounts + OAuth credential dirs). Read directly at every call site rather than cached on DataPaths so identities_dir() behaves consistently regardless of whether the caller built its DataPaths via resolve() (launcher) or from_env() (downstream host/srv).

isolated_auth_reason

isolated_muxbus_reconnect_enabled

Skip the automatic, EAGER MuxBus cloud-session reconnect (CloudSubscriber::init_global, called at boot) on a randomized per-build local-package channel. See docs/retro/retro-macos-0560-stale-cef-cache-launch-crash-2026-09-16.md for the incident this closes.

isolated_muxbus_reconnect_reason

isolated_settings_enabled

Isolated per-channel settings.json. Same shape and same reasoning as isolated_auth_enabled — see docs/specs/SPEC_SETTINGS_ISOLATED_BY_CHANNEL_2026_08_19.md.

isolated_settings_reason