Read tmux objects

The cmdlets return native objects from libtmux for .NET. Inspect them with Get-Member, select their properties and pass them directly to other cmdlets.

Create an endpoint with New-TmuxServer -SocketPath or -SocketName, then pipe it to a read command. Constructing the endpoint performs no I/O. fConnect-TmuxServer discovers an unmaterialized endpoint and returns its connected replacement. An already connected handle is returned unchanged.

The acquisition commands above read tmux explicitly. -Id selects a literal tmux identifier, such as $0, @1, or %2; use single quotes for a session ID. Session and window commands also accept -Name. Selectors compare ordinally and distinguish case. They do not expand wildcards. Combining selectors requires both to match. An unmatched selector emits no objects; it is not an error. Wrap a pipeline in @(...) when its count matters.

For -Name and -Id, Tab offers values from an explicitly supplied captured server, session or window. Capture first with fGet-TmuxSnapshot. Completion does not contact tmux, refresh a handle or guess an endpoint. An uncaptured owner offers no tmux values. The suggestion comes from the earlier observation; the read command still checks current tmux state when you run it.

Owners bind by their native type. Property names on an arbitrary object do not provide pipeline binding. Use Where-Object after acquisition for further local filtering. For reusable criteria, use fNew-TmuxQuery and the local fSelect-TmuxPane, fSelect-TmuxWindow or fSelect-TmuxSession commands. fGet-TmuxQueryField discovers the shared query catalog locally.

For a fresh query, pass an explicit endpoint and a query document to fInvoke-TmuxQuery. It emits matching native objects; -AsResult retains the result and its complete captured graph, including an empty selection. Use fGet-TmuxQueryPlan with a known daemon version to inspect source evaluation, local residuals and fallback reasons before execution. Planning performs no I/O. The query guide walks through native filtering, reusable criteria, relationships and source plans.

fGet-TmuxSnapshot defaults to -Depth Panes. Shallower depths are kServer, kSessions, and kWindows. It returns a replacement graph and leaves the input handle and earlier snapshots unchanged. CSnapshotMetadata records the depth, daemon generation, UTC start/end readings and monotonic pElapsed time. UTC can move backwards if the clock is adjusted; use pElapsed for duration. Even -Depth Server performs a fresh generation-guarded read.

Snapshot acquisition spans several tmux commands; it does not promise an atomic view. Contradictory parent, child-count or active-child observations fail with CInconsistentSnapshotException and emit no graph. Equal-count changes can escape detection. The command never retries automatically. Uncaptured relations report IsCaptured = false and throw when enumerated. Property access never reads tmux. Captured panes expose pCurrentCommand and pCurrentPath, which remain readable after the daemon exits. A field that was not captured raises CIncompleteSnapshotException; a captured empty string or null retains that value.

Captured children retain their root through CServer. Parent properties return the captured instances when that depth is available. pSession.ActiveWindow, pSession.ActivePane and pWindow.ActivePane return CapturedValue<T>: inspect pIsCaptured, then read pValue for the captured object. Reading an unavailable pValue raises CIncompleteSnapshotException; mOrNull() explicitly opts into null instead. A pane’s CWindow retains its session/index placement, including repeated links to the same window. pWindow.LinkedSessions contains each related session once. Filtering a collection changes only selected membership; traversing its parents still reaches their complete captured children. Active properties use the IDs from their own parent’s row, so separate reads can record different selection states.

fUpdate-TmuxPane refreshes one pane’s fields. Its parent navigation does not borrow captured data from an older graph, even when its CServer names an older captured root. Acquire another snapshot for a new graph.

Default tables show native identifiers, captured names or titles, and owner context. Handles resolved only by identifier show blank columns for fields they have not captured. The views distinguish that specific missing-field condition from other failures. Formatting and Get-Member use local data and remain usable after the daemon exits. They do not refresh objects.

Read failures write an error for the affected owner, including an endpoint with no running server, then allow later pipeline owners to continue. Use -ErrorAction Stop to terminate instead. Error IDs are Tmux.ConnectFailed, Tmux.SnapshotFailed, Tmux.SessionReadFailed, Tmux.WindowReadFailed, and Tmux.PaneReadFailed. The error record retains the core exception and its dispatch metadata when the exception supplies it. Pipeline cancellation cancels the pending core operation; borrowed server handles do not own daemon lifetime.

The installed-module integration test executes typed pipelines, exact selection, shallow and replacement snapshots, and strict errors against its own tmux server. The fixture owns teardown. The snapshot integration test checks provenance, repeated placements, parent navigation after teardown and contradictory reads. The formatting integration test checks captured objects and identity-only handles after daemon shutdown, including that formatting and member discovery start no tmux processes. The completion integration test checks Tab suggestions after teardown and verifies that completion starts no tmux client.