LibTmux.Watch-TmuxEvent

Description#

Emit native TmuxEvent values in stream order. A supplied Connection is borrowed and remains usable after cancellation or early pipeline exit. With Server and Target, the command owns a new control client and closes it before returning. Both forms borrow the daemon and its sessions. Output count and byte budgets reset for each input connection or server; piping N owners can emit N times MaxEvents.

There is one acknowledged handoff slot. The reader does not fetch the next event until downstream processing returns. PowerShell output runs only on the active pipeline callback; native command replies continue independently, so downstream code may send through the same connection.

Only one Watch-TmuxEvent consumer may read a connection at a time. Direct native Events readers remain the caller's responsibility: the stream is not broadcast. Event output is decoded text fragments, not rendered pane contents, lines, byte-exact output or a durable log. Loss and exit events are forwarded.

Notes

Tmux.WatchFailed preserves the native exception and supplied owner. Buffered events precede a terminal stream error. A byte-budget failure preserves earlier output and reports that the consumed oversized event was not emitted.

Byte accounting includes decoded UTF-8 text in pane IDs, output data, notification names and arguments, and exit reasons. Numeric loss counts add no text bytes. This bounds text payload, not object overhead or serialized PowerShell Job data. Set BOTH MaxEvents and MaxOutputBytes for unattended jobs. The native upstream queue separately defaults to 512 events and 4 MiB of decoded UTF-8 payload. Configure its positive ControlModeEventBufferCapacity and ControlModeEventBufferMaxBytes through ServerConnectionOptions before connecting. Queue bytes include output data, notification names and arguments, and exit reasons, excluding pane IDs and object overhead. Oldest events are discarded until both queue limits hold. An oversized event is dropped; an oversized exit reason is omitted while the exit event remains. Loss is reported by TmuxEventsDroppedEvent without blocking command replies.

Ctrl+C, pipeline early exit and module removal stop the reader and await its disposal. Module removal cancels active watches only in the importing runspace; it does not dispose supplied clients. Cancellation may consume an event that has not reached the pipeline. Resnapshot after loss when current state matters. The foreground pipeline remains occupied while watching; use a bounded ThreadJob to make the prompt available.