wait_for

Consume raw pane output until predicate(result::OutputWaitResult) returns true. The predicate runs outside the reader lock and must return promptly. One total deadline includes baseline capture, predicate calls and every read; a synchronous predicate cannot be forcibly interrupted. Cancellation and an expired deadline are checked again before accepting its result.

wait_for(predicate, stream::ObservationStream; baseline=false, timeout=5.0,
         cancel=nothing, max_bytes=65536, invalid=:error, mode=:raw)

By default only output consumed by this call is considered. baseline=true first tests an independently captured screen, bounded by max_bytes, with soft-wrapped rows joined so text wider than the pane still matches; an oversized capture raises OutputLimitExceeded . A rejected baseline is never concatenated with subsequent raw bytes. Already queued output remains eligible; register a new stream before sending input when fresh-output evidence matters.

Predicates see a tail of at most max_bytes bytes, not unlimited history. UTF-8 spans chunks through TextDecoder ; malformed input follows invalid. Terminal escapes remain literal data. mode=:rendered refuses streaming screen reconstruction before I/O; explicit captures remain available.

The stream retains incomplete UTF-8 across successive waits, including after cancellation or a predicate exception. Only one helper may consume it at a time, on its consumer task. A UTF-8 policy change requires no pending bytes. Direct raw reads during a helper are refused; raw reads between helpers make later text waits refuse lost decoder continuity. Register a new stream after a strict UTF-8 error or to change consumption modes.

The caller retains ownership of the stream and connection. Stream overflow, topology loss, cancellation, EOF and transport errors propagate without replay.