Repository navigation
feat(handoff): add a bounded read-only metadata watch view #296
Description
Motivation
Priority: P2 enhancement. Users need to follow existing handoff evidence without repeatedly invoking status. This is a metadata-only presentation feature, not a new message inbox or task execution system.
Reference: published Python v1.1.0, commit 8ca77cf. Existing handoff init/prepare/status/wait/confirm and receipt handling are implemented in session_peer_core/handoff.py. Broader acceptance remains OPEN in #181 (v1.2.0).
Alternatives considered
- Reuse handoff status/wait for an individual prepared intent.
- feat(handoff): expose explicit ACK, deadline, and unknown outcome for unanswered requests #181 covers receipt/observation/bootstrap/lifecycle acceptance; investigate(delivery): extend request-ID deduplication safely to ordinary local and SSH sends #182 separately investigates receiver deduplication.
- A generic await/tasks command that scans transcripts or retains arbitrary reply bodies is outside the frozen receipt-only contract.
- No existing all-state issue or PR specifically covers a bounded, metadata-only watch presentation.
Proposed behaviour
Design an explicitly selected, local owner-ledger watch view for existing intents, reusing validated status snapshots. CLI spelling is a design choice, not an implemented command. Restrict displayed fields to an explicit metadata allowlist. Support a finite duration and bounded refresh rate/output budget; report unsupported or missing history honestly.
Acceptance criteria
- Specify CLI/options, supported routes, finite deadlines, refresh/output/resource bounds, snapshot ordering and missed-change semantics before implementation.
- Read only owner-authorized existing evidence; do not create intents/waits/receipts, submit messages, wake models, initialize/repair ledgers, delete fences or extend receipt authority.
- Never read native transcripts, message bodies, raw receipt capabilities or arbitrary agent progress APIs. No body collection, stored reply results or guaranteed lossless event stream.
- Preserve submission/injection/receipt distinctions and immutable prior wait outcomes. Queue removal, process exit and turn completion never become ACK.
- Retain missing/corrupt/restored/unsupported history and retry-forbidden semantics. Observation failure cannot change an original send outcome.
- Cover unchanged snapshots, late valid receipt, timeout/stopped waits, ledger loss/corruption, bounded output, terminal sanitization and SIGINT/cleanup; keep normal output/exit contracts unchanged.
- Document unsupported Codex observation, remote receipts, Windows and other routes rather than implicitly completing feat(handoff): expose explicit ACK, deadline, and unknown outcome for unanswered requests #181.
No implementation, live-agent experiment, operational change or release is authorized by this planning issue.
Reason-inspired UX follow-up — 2026-10-22
Keep this existing issue rather than creating another mailbox/watch proposal. Reuse the published v1.2.1 status/wait and lifecycle behavior; the frozen handoff contract is unchanged.
Implement in small reviewable slices: first an explicitly selected one-shot metadata view for existing owner-ledger intents, then a finite watch using the same validated snapshots. Display known submission evidence, observation/receipt support, the original wait outcome and any later receipt separately. Include observation time or missing-history reasons only where supported by actual data; do not synthesize a lossless event timeline.
Reason Network's directory and inbox UX is a reference, not a replacement for the receipt contract: design. Do not import transcript/todo scanning, stored reply bodies, offline auto-resend or stale-session mailbox inheritance. No watch operation may submit, wake, repair history or mint authority. Unsupported Codex/remote observation remains unsupported.
Related UX candidates: #323 (per-destination capability/readiness explanation), #324 (local destination presets). Suggested implementation order is #323, #324, then this presentation slice; that is a planning preference, not a hard dependency or a release promise. Priority P2 and v1.3.0 remain unchanged. The owner's research-first direction is retained.
Activity
abruption commentedon Oct 22, 2026
Implementation contract for the remaining watch slice
The owner authorized this slice on 2026-10-23. Extend existing PR #329 so the single-request presentation and watch share the same read-only status implementation, then run independent CLI reviews before publishing the new commits.
handoff watch --correlation-id UUID [--watch-timeout SECONDS] [--interval-ms MILLISECONDS] [--json]selects one existing local POSIX owner-ledger intent. Duration defaults to 30 seconds, accepts ASCII integers 1..60, and starts before setup. Interval defaults to 1000 ms, accepts integers 1000..5000. There are at most 61 samples. Initial and changed public metadata snapshots are emitted; unchanged samples do not produce a frame. This is polling, not a lossless event history.JSON uses NDJSON watch events with
operation: watchandevent: snapshot|end; nestedhandoffkeeps its existing frozen schema. Snapshot sequence is local sample presentation order. Optional observed UTC is diagnostic; monotonic time controls the deadline. Output is bounded to 16 KiB/frame and 256 KiB total with 2 KiB reserved for termination. Pipe backpressure is bounded using scoped nonblocking output and restored descriptor flags. Filesystem calls are not hard real-time guarantees.Normal duration completion exits 0 without proving ACK or consumption. Interruption exits 130; history/output errors exit 1. Missing/corrupt/replaced history terminates without creating a ledger, inventing an epoch or promoting replacement-history facts. An epoch change ends the watch before a new snapshot from that epoch is emitted.
No native submissions, wake, wait creation, receipt creation, repair, transcript/body reads or raw receipt capability output. Existing collector clock evidence may be queried read-only, without starting or rebinding a collector. Ledger snapshots are read-only and retention projection stays in memory. Existing restore-quarantine lifecycle limitations remain explicit. Windows and remote/device watching are unsupported.
Acceptance covers unchanged/changed snapshots, late receipt and immutable prior wait, unsupported evidence, missing/corrupt/replaced history, output size and slow/broken pipes, interruption and cleanup, descriptor flag restoration, and proof of no ledger writes/native effect.
abruption commentedon Oct 26, 2026
v1.3.0 release closeout — 2026-10-26
Closing as completed for the owner-approved release scope, following the owner's milestone cleanup instruction. The original proposal/checklist is retained as history; this is not a blanket assertion of every platform or broader research guarantee.
The approved local POSIX metadata view and finite watch of existing intents are published. Bounded sampling/output, epoch/history changes, no ledger writes or new authority, SIGINT and output-helper cleanup are covered.
Evidence: merged PR #329; published v1.3.0 scope, source
938630063b69bf6e0ae69d4b11e2095c30f289f4; successful publication and artifact/install verification. Static source/test-definition recheck today: tests/core/test_handoff_watch.py; tests/core/test_handoff_watch_cli.py; tests/core/test_handoff_status_view.py. Two read-only subagent audits independently reviewed the split issue groups; no new mandatory closure blocker was found. No new tests/live experiments or deployment were performed during this closeout.Remaining boundaries: Windows/remote/device watch, general Codex ACK, lossless event delivery and hard-real-time guarantees are excluded. Explicit restore-quarantine ACK-detail/satisfied-wait limitations remain under existing #181; this closure does not resolve them.
Retain the closed issue in v1.3.0 as the release record. Optional excluded expansions are not automatically promised for another release.