feat: v0.7 roadmap — doctor, reply waiting, reply URIs, and SSH return-route diagnostics #45

Prerequisite: #44 (v0.6 Codex adapter). Existing related work: #31 (reply waiting), #29 (JSON contract), #28 (test coverage).

Motivation

Once Claude and Codex can be addressed through one CLI, users still need to diagnose why a message is pending, describe a working return address, and wait for an actual reply without fragile marker searches.

Target v0.7: diagnostics, a correlated waiting interface, structured reply addresses, and clear SSH return-route status. This is a release-level tracker: #31 remains the existing work item for reply waiting, rather than opening a second competing implementation issue.

Does the official path already cover it?

Native Claude inbox and Codex queue mechanisms submit messages, but a transport write alone does not confirm an application reply or that the remote machine can connect back. Prefer supported native events/status interfaces wherever available; investigate those before coupling session-peer to transcript or private DB layouts. If reliable reply detection is not available, explicitly document the limitation instead of claiming delivery.

Proposed behaviour

session-peer doctor
session-peer doctor --host worker
session-peer send --to codex:<thread-uuid> --wait --wait-timeout 60 "message"

• doctor checks the selected machine's installed tools, discovery sources, selected Codex home, Claude inbox availability, and known access restrictions. Socket existence is not proof that the caller can connect. Diagnostics must not send messages, start turns, or change configuration by default; report checks as unverified when a conclusive probe would be side-effectful.
• Extend the waiting design in No way to wait for a reply #31 with the send --wait convenience form. Correlate message IDs and acknowledgements, distinguish posted/queued/consumed/acknowledged only when evidence exists, and never count the request's own marker or an error echo as a reply.
• Record the supported observation mechanism and timeout/exit-code contract in No way to wait for a reply #31 before implementing wait. Unsupported observation must be explicit; timeout must not resend or automatically activate a session.
• Introduce a versioned, structured reply address identifying agent, destination host/transport, and session. A resolver should reconstruct destination-specific execution context without treating received addresses as arbitrary shell commands. Keep credentials out of addresses and avoid breaking current reply flags without a documented migration.
• Display a useful warning when an advertised SSH return route is unverified or has a verified failure. A forward SSH connection does not establish reverse SSH access. Any actual reverse-route test is opt-in and must not edit SSH keys or authentication configuration.
• Coordinate diagnostic and wait JSON results with --json output can't say which host it came from, and the shape differs per command #29, including host attribution and explicit unknown/unsupported outcomes.

Evidence and limits

Local/remote tests found that using the wrong CODEX_HOME can make an otherwise valid thread unavailable, a Codex execution sandbox can deny UDS access or queue DB writes, and successful forward SSH can coexist with reverse SSH authentication failure. Approval-based execution worked in the observed configuration; session-peer should explain that condition, not apply an approval policy itself.

These observations justify diagnosis and route status. They do not yet validate a general acknowledgement observer or reply URI protocol.

Acceptance criteria

• doctor differentiates missing tools, wrong/missing home, unavailable inbox, permission failure, and unknown/unsupported checks using local fixtures and a real SSH host.
• No way to wait for a reply #31 records the wait observation decision and implements the agreed send --wait behaviour, or records a reproducible reason to defer it; no false-positive success on quoted request markers or stale replies.
• Correlation, timeout, cancellation, delayed replies, and unsupported observation are tested; timeout leaves the submitted message intact and does not duplicate it.
• Reply addresses round-trip through the parser, distinguish local and SSH destinations and both agents, and reject malformed/unsafe addresses without executing content.
• A return route is not shown as working solely because forward SSH succeeded; reverse checks are opt-in.
• Human/JSON semantics and compatibility are documented alongside --json output can't say which host it came from, and the shape differs per command #29; existing send/reply behaviour has regression coverage.

Deliver through linked issue → branch → PR changes. Waiting implementation remains coordinated with #31.