Repository navigation
Description
Motivation
session-peer list --json currently discovers saved Codex sessions in one selected home. Sessions in Orca account homes remain absent unless the caller already knows their path and passes --codex-home.
Follow-up to #75 (unified Claude/Codex listing). #55 and #61 introduced multi-home send safeguards and active-home validation, but do not provide unified multi-home listing. Reuse their bounded candidate discovery and canonicalization rather than broadening filesystem access.
Proposed behavior
- By default, list Codex sessions across the destination's default
~/.codex, itsCODEX_HOMEwhen set, known macOS Orca account homes, and explicitly configuredSESSION_PEER_CODEX_HOMES. - An explicit
--codex-home PATHselects only that home and disables automatic expansion for that invocation. - Apply the same behavior to
list --json, human-readable list, andlist --agent codex; preserve Claude discovery and agent filters. - Include canonical
codexHomeand sourcestateDbon every Codex session row. Show enough home information in human-readable output to distinguish duplicate UUIDs. - Treat host + canonical home + thread UUID as the session identity. Preserve identical UUIDs in different homes as separate rows; deduplicate symlink aliases of the same home, not distinct saved copies.
- Return per-home discovery diagnostics. Preserve successful rows when a home is unreadable or has an unsupported schema, and explicitly report incomplete discovery through the existing JSON/exit-status conventions. Distinguish absent optional candidates from discovered-but-unreadable homes; do not equate failure with an empty result.
- Enumerate and read candidate homes on the destination machine for SSH commands. Do not assume the caller's environment or filesystem describes the remote host.
- Keep saved-session discovery distinct from execution state: presence in a DB does not imply an active writer or confirmed receipt. Preserve existing send ambiguity safeguards.
- Document using a listed row's
codexHomeexplicitly when sending to its UUID.
Boundaries and MCP compatibility
No arbitrary recursive directory scans, process environment dumps, credential reads, or direct state/queue DB writes. Candidate collection remains bounded to known/configured roots and uses read-only DB access.
MCP must continue to list only homes authorized by destination policy (#46 / #77). Its existing explicitly pinned --codex-home route must remain confined to that home; the new CLI default must not silently expand MCP access. Any future MCP multi-home policy needs explicit authorization.
Acceptance criteria / tests
- Default listing includes default, environment-selected, Orca and configured additional homes, locally and over SSH.
- Explicit
--codex-homerestricts discovery to exactly one home;--agent claudedoes not inspect Codex homes. - Each Codex row includes
agent,codexHomeandstateDb; duplicate UUIDs across homes remain distinct. - Symlink aliases are deduplicated and ordering is deterministic.
- Tests cover single-home installations, missing optional roots, no Codex installation, archived filtering via
--all, corrupt/unsupported DBs and permission-denied candidate enumeration/reads. - Partial failures preserve other homes' sessions and Claude results, with documented home-level diagnostics and exit behavior.
- SSH uses remote candidate paths/environment, preserves existing single-/multi-host response cardinality, and handles different usernames.
- MCP regression test proves an explicitly pinned destination does not enumerate other available homes.
- README, CLI help, JSON contract and skill examples explain the new default and selecting the exact home for subsequent send.
Implement as a separate follow-up PR to #75, retaining the existing schema-versioned response envelope and documenting additive fields and changed default discovery scope.
Activity
Merge pull request #80 from abruption/feat/79-multi-home-list