Waiting, following and recovering

An observer reads existing work. Ending its wait does not cancel a job, stop a recording or detach a browser view.

Choose the observation boundary

olenji jobs wait JOB_ID --wait-timeout 30 --json
olenji events SESSION_ID --after CURSOR --follow --seconds 30 --committed-only --jsonl
olenji ui configure VIEW_ID --config '{"layout":"bilingual","target_language":"tr"}' --wait-applied 5 --json
olenji tui SESSION_ID --seconds 30

Job waits and event follow establish the service once before starting their observation timer. This initial connection/startup has its existing lifecycle and is separate from --wait-timeout or --seconds. View waits start after the view mutation. An interactive terminal timer starts after its initial snapshot; machine tui --json returns one snapshot.

Later observer polls check the current service's workspace identity and version without starting a replacement daemon. Each read uses the same address that passed its health probe, even if service discovery changes during a concurrent restart.

Interpret completion and failure

Outcome	Meaning and next action
Job result	The observed job completed within the observation budget. Inspect its result.
`WAIT_TIMEOUT` with `job_id`	The wait ended; work was not cancelled. Resume waiting on that same ID or inspect `jobs get`.
Event follow reaches `--seconds`	The stream ends cleanly without a final document. Save the last event/reset checkpoint.
View has `applied:false` and `wait_timed_out:true`	The requested presentation has not been confirmed within this wait. Keep its last known revision and query again before claiming it is visible.
`SERVICE_UNAVAILABLE`	The observed owner disappeared or did not pass its health probe. Inspect service status; restart deliberately if appropriate, then inspect recovery before resuming.
`SERVICE_VERSION_MISMATCH`	The service belongs to this workspace but runs another application version. Finish active work and explicitly stop/restart with the intended installation.
`RESPONSE_TOO_LARGE`	Reduce the event page/window or export the content. Repeating the same oversized observation is not a repair.

A follow error includes details.cursor and details.session_id. This cursor covers the pages already consumed, including empty filtered pages. Resume with --after only after checking the service's recovered state. A stream.reset frame means the saved cursor is ahead of the restored database: read a new atomic snapshot and resume from its cursor. A segments.replacement_started event also requires a snapshot before applying its constituent edits.

Ctrl-C returns exit code 130 and leaves already admitted work alone. A closed downstream pipe exits quietly. Event following does not read or close the caller's stdin. Explicit jobs cancel and live stop remain separate operations.

Time and size bounds

Observation uses monotonic time. Sleep durations and network phase timeouts shrink to the remaining budget; expiry is checked before/after blocking phases and between yielded response chunks. A response that finishes after expiry is not accepted as timely completion or acknowledgement.

These synchronous checks do not promise hard real-time interruption of an OS call. Scheduling, an in-progress read and JSON decoding can finish after the nominal deadline. Initial bootstrap is also outside the observation timer, as described above.

Observer bodies accept at most 8 MiB, and health probes accept at most 16 KiB. Requests ask for identity encoding, check declared and streamed byte sizes and close the response on completion, error or cancellation. Normal one-shot API data reads and streamed exports retain their existing behavior. The terminal uses the same observer transport for refresh/reconnect; see TERMINAL.md.