feat(discovery): add bounded opt-in discovery across paired devices #367

Problem

The default session-peer list discovers local sessions. list --device <fingerprint> queries one explicitly selected paired receiver; --all includes stale/local discovery records and does not mean all paired devices. There is no explicit aggregate discovery workflow for already paired receivers.

In a user-reported KR workflow, an agent inspected only the standalone CLI and initially missed an existing package-managed Relay environment and existing paired-device state. After selecting that environment, the agent discovered an allowed remote Codex target and submitted one request. The reported queued/receiverAccepted result did not establish consumption. This is a usability case, not a reproduced pairing or transport defect.

Proposal

Design an explicit opt-in paired-device discovery mode, provisionally list --paired (name and contract to be reviewed). Preserve default local listing and the existing meaning of --all. Do not silently turn ordinary discovery into network fan-out.

Acceptance criteria

• Select one explicit, existing device-state context. Missing, ambiguous or unsafe state must be reported without initializing an identity, creating state, repairing permissions or scanning arbitrary private directories.
• Take a bounded snapshot of eligible paired peers; exclude pending/revoked entries. A paired record alone grants no list permission: each receiver's current policy remains authoritative and exposes only permitted target aliases.
• Define finite peer-count, concurrency, per-peer/total-time and output budgets. Specify whether local results are included; do not infer inclusion silently.
• Preserve existing explicit route/admission controls. No automatic login, installation, re-pairing, endpoint rewrite, transport fallback after uncertainty, or native send/wake.
• Retain provenance per result: peer identity, selected route and receiver target alias. Do not merge targets solely because native IDs or labels match across devices/homes. Labels and returned text remain untrusted data.
• Preserve partial successes and separately classify unavailable/denied/timeout/unsupported/truncated peers. An incomplete discovery must not become an empty successful result or prove that sessions are absent.
• Define aggregate text/JSON and exit behavior while preserving existing local/single-device output contracts. Discovery/readiness must not be described as submission, consumption or ACK.
• Add offline tests for mixed peer states, policy refusal, duplicate labels/IDs across peers, unreachable peers, partial failures, budget/cancellation boundaries, missing Relay dependencies and unsafe/missing state. Keep native/real-network acceptance claims separate from fixtures.

Related scope

A companion skill issue will document how to locate an already installed Relay-capable runtime and perform existing single-device discovery now. That guidance must not wait for or advertise the proposed flag.

This issue records design/development work only. It does not authorize deployment, pairing/state changes, publication or broaden ordinary list/send permissions. No release date or milestone is promised here.

Companion documentation issue: abruption/session-peer-skill#44