Skip to content

feat(cli): explain delivery capabilities and readiness per destination #323

Open

Description

@abruption

Problem

The CLI already exposes discovery, doctor capabilities and dry-run evidence, but users must combine several outputs to understand whether a particular destination can accept input and what evidence they can expect afterward. A reachable endpoint, successful submission, wake support and an explicit receipt are different facts.

Reference baseline: published Python v1.2.1, source f19f2b5e9ac17d392375507bc753548cdfc0e751. Existing doctor/dry-run behavior is implemented; this issue adds a clearer presentation, not a new transport or ACK capability.

Proposed scope

Provide an opt-in, per-destination explanation assembled from existing validated discovery/doctor/dry-run facts: selected agent and route, target availability, submission support, explicit wake support where proven, receipt/observation support, limitations and last observation time where meaningful. Begin with human-readable output; specify any additive machine-readable fields and CLI spelling before implementation.

Reason Network's delivery tiers are useful UX inspiration, but do not copy a blanket push classification or promise immediate consumption for Codex. Reference design.

Acceptance criteria

  • Reuse existing capability and target-resolution logic; clearly distinguish observed facts, declared capability and unknown/unsupported conditions.
  • Keep standalone list metadata-only. Do not introduce native-version probes, SSH connections or model/session activation beyond the explicitly selected command's existing contract.
  • Show the actual selected host/device/home context without exposing credentials, message contents or receipt capabilities; sanitize human output.
  • Separate submission, wake, injection observation, explicit receipt and task completion. A queue write, idle indication or native exit zero never becomes consumption/ACK evidence.
  • Preserve ordinary output/exit compatibility, partial discovery errors and per-host failures. A readiness snapshot does not guarantee later delivery; actual send retains existing revalidation.
  • Preserve unknown/no-automatic-resend behavior. Unsupported versions/routes must not silently fall back or gain capabilities.
  • Cover unavailable/ambiguous targets, partial inventory, inactive Codex, unregistered Antigravity, supported versus unsupported handoff receipts and stale observations with bounded offline fixtures.
  • Document the initial supported scope and examples in the existing four-language documentation.

Relationship and planning

Reuses completed doctor/addressing work (#45/#44) and complements #181 (handoff acceptance), #268 (storage contract) and #296 (existing-intent status view). It does not complete their remaining acceptance gates.

Priority P2; v1.3.0 planning candidate, first among the Reason-inspired UX slices. The owner's current research-first direction remains in effect; this issue does not schedule a release or authorize implementation, live experiments, operations or publication.

Activity

  1. added this to the v1.3.0 milestone on Oct 22, 2026
  2. added
    enhancementNew feature or request
    priority:P2Planned reliability, acceptance or feature work; priority does not authorize implementation.
    on Oct 22, 2026
  3. abruption commented on Oct 23, 2026

    @abruption
    OwnerAuthor

    The owner-approved expansion is available in PR #325 at 5507298a699cc9462500b830e28120e121de7cbb; all 28 checks on that exact head passed.

    In addition to local/SSH send previews, the candidate explains paired readiness using negotiated optional context, existing doctor diagnostics, and stored read-only handoff-status evidence. Explanation rendering adds no native submissions, extra probes, receipt collection or waiting. Older peers retain their original result and unknown-context behavior. Submission, injection observations, stored ACKs, wait outcomes and task completion are not conflated.

    Independent Claude Opus 5.5 and Codex CLI reviews were completed before the push. Confirmed path/wire/privacy findings were corrected with regressions. Gemini 3.8 Flash Medium reviewed the four-language text; the PR records the precise input hashes, versions and limits. Local Python 3.13 dev-mode suite: 1373 tests pass, 19 skipped; focused Python 3.9 and documentation/generator checks pass.

    The frozen handoff contract and fixture remain unchanged. The issue is not closed before normal human review/merge, and this does not authorize release or operations changes. Sibling v1.3 feature integration is being checked in a separate local worktree.

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

    enhancementNew feature or requestpriority:P2Planned reliability, acceptance or feature work; priority does not authorize implementation.

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions