Skip to content

feat: list Codex sessions across default, Orca, and configured homes #79

Closed

Description

@abruption

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, its CODEX_HOME when set, known macOS Orca account homes, and explicitly configured SESSION_PEER_CODEX_HOMES.
  • An explicit --codex-home PATH selects only that home and disables automatic expansion for that invocation.
  • Apply the same behavior to list --json, human-readable list, and list --agent codex; preserve Claude discovery and agent filters.
  • Include canonical codexHome and source stateDb on 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 codexHome explicitly 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-home restricts discovery to exactly one home; --agent claude does not inspect Codex homes.
  • Each Codex row includes agent, codexHome and stateDb; 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

  1. added a commit that references this issue on Sep 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions