Parent: #116
Outcome
run-once observes one explicitly owned parent Pi session with deterministic ordering, callback backpressure, immediate cancellation on observation failure, and complete terminal error reporting.
Scope
- Atomically pre-create an exact parent session file and pass it through Pi's
--session option.
- Follow only that exact file; never discover the newest recursive JSONL file.
- Deliver observations serially and await consumer callbacks.
- Surface observation failure immediately, abort the Pi command, await process close and cleanup, and retain every independent failure cause.
- Preserve final JSON on stdout and progress on stderr.
- Add reusable command-runner cancellation only as required by this contract.
Out of scope
- Subagent-specific metadata parsing or rendering.
- Changing
pi-subagents.
- Migrating triage to the exact-session API; triage behavior should remain unchanged and receive regression coverage only.
Acceptance criteria
- Concurrent or nested sessions cannot redirect
run-once observation.
- Slow callbacks are backpressured without reordering.
- Malformed JSON, I/O failures, callback failures, runner failures, and cleanup failures remain observable without masking one another.
- Observation failure cancels Pi promptly rather than waiting for normal completion.
- Tests use deterministic synchronization rather than timing races.
Planning constraints
This issue owns one focused session-reliability PR. Its spec and plan supersede only the exact-session, streaming, cancellation, and terminal-error portions of the deprecated monolithic plan referenced by #116.
Parent: #116
Outcome
run-onceobserves one explicitly owned parent Pi session with deterministic ordering, callback backpressure, immediate cancellation on observation failure, and complete terminal error reporting.Scope
--sessionoption.Out of scope
pi-subagents.Acceptance criteria
run-onceobservation.Planning constraints
This issue owns one focused session-reliability PR. Its spec and plan supersede only the exact-session, streaming, cancellation, and terminal-error portions of the deprecated monolithic plan referenced by #116.