feat: v0.6 roadmap — Codex discovery, addressing, queueing, and submission status #44

Motivation

session-peer currently discovers and addresses Claude Code sessions. Users running Claude Code and Codex on the same machine, or on machines reachable over SSH, have to assemble separate commands and return addresses for each tool.

Target v0.6: add the smallest useful Codex adapter—saved-session discovery, codex:<thread> targets, native queue submission, and truthful submission status. Implemented in #51 after feasibility testing; the repository is now abruption/session-peer. Publication is tracked in #48.

Does the official path already cover it?

Codex already provides codex queue --thread <id> --message <text>. cc-peer should call that native entry point rather than write queue databases or inject terminal input. The added value is a common Claude/Codex addressing interface and reuse of cc-peer's local and SSH dispatch. Users who only need the native command can continue using it directly; Claude Remote Control remains appropriate where it already meets their needs.

Proposed behaviour

session-peer list --agent codex
session-peer list --agent codex --host worker
session-peer send --to codex:<thread-uuid> "message"
session-peer send --host worker --to codex:<thread-uuid> "message"
session-peer send --to codex:<thread-uuid> --dry-run "message"

• Keep the default list and unprefixed Claude name/PID targets compatible. Accept full Codex UUIDs for this first increment.
• Discover saved Codex sessions read-only. The tested state_5.sqlite schema is an experimental discovery source, not a stable public interface; detect unsupported layouts and report useful errors. Show archived sessions only with --all, and do not infer active/idle state from a saved record or lock-file existence.
• Add --codex-home and --codex-bin so discovery and queueing use the same installation. Interpret overrides on the destination machine for --host; otherwise use its CODEX_HOME/default home and executable PATH.
• Invoke the resolved Codex executable with a subprocess argument array. Preserve existing stdin support, message wrapping, SSH quoting, and remote no-install dispatch for cc-peer itself. Codex must be available on the destination.
• Report successful Claude socket submission as posted and successful Codex submission as queued. Neither is evidence of consumption or acknowledgement. Include agent, target ID, and submission status in Codex JSON results; coordinate broader envelope changes with --json output can't say which host it came from, and the shape differs per command #29.
• --dry-run validates and resolves without queueing or starting a turn. Missing CLI, incompatible/missing DB, unknown thread, permission failures, and timeouts must be actionable errors. A timeout has an unknown submission outcome and must not trigger automatic retry.
• Keep the single-file, standard-library design. Automatic wake/resume, response waiting, Codex sender/reply discovery, MCP, and a general plugin framework belong to later roadmap items.

Feasibility evidence (2026-09-10)

Two macOS machines were exercised using Codex CLI 0.154.0; local Python was 3.14.7 and remote Python 3.13.7.

• Read-only queries found three saved sessions on each machine with the required ID/name/title/cwd/archive fields and existing rollout paths.
• One real queue submission per machine succeeded, including the SSH path. Reading only the test items back confirmed exact preservation of Korean, emoji, newlines, quotes, and literal shell metacharacters. Both were still pending at the last check; this test does not establish response delivery.
• An unknown UUID was rejected with no rollout found and exit code 1.
• The CLI issued thread/queue/add without turn/start against a mock server. Configuring mock active/idle/notLoaded values did not test real lifecycle behaviour: the CLI did not query those values.
• Local queueing failed inside the execution sandbox with a read-only DB error and succeeded through approved execution. Readable discovery does not guarantee writable queue access.
• A mock accepted 32 KiB and 32 KiB+1 UTF-8 payloads. A proposed 32 KiB package cap would be a compatibility policy, not a measured Codex limit.
• All 57 existing cc-peer tests passed. No package implementation was added during this verification.

Acceptance criteria

• The two proposed commands work locally and over a real SSH connection; verify submitted content, not just a printed success marker.
• Discovery fixtures cover archive filtering, missing/changed schemas, configured homes, and saved-but-not-running sessions; link relevant coverage work with Test the parts the docs call fragile: discover(), the socket payload, exit codes #28.
• Queue tests cover executable/home selection, unknown UUID, subprocess failure/timeout, Unicode and shell metacharacters, and byte-based payload validation.
• --dry-run performs no submission or session activation.
• Human and JSON output distinguish posted/queued from consumption and retain remote host attribution without an incidental breaking rewrite of Claude output (--json output can't say which host it came from, and the shape differs per command #29).
• Existing Claude tests and supported CI environments remain green; document which Codex versions/platforms were actually tested.
• README/help document commands, dependencies, experimental DB coupling, and approval requirements without enabling approval bypass automatically.

Implementation follows the repository's issue → branch → PR workflow, with Conventional Commits and the PR template. This issue is a roadmap target, not a release commitment.