Capture and navigate

Use fwithServer to adopt an existing endpoint and fcapture to obtain a detached TSnapshot. The complete program in the README filters ordinary pane records, traverses relationships and prints its result after the handle closes. Its source and owned fixture verification are checked from the source archive, with output asserted and owned process exits observed.

Create the private demonstration server from the README, then run the Haskell executable from a provisioned checkout:

$ cabal run --verbose=0 capture-graph -- \
    "$LIBTMUX_DEMO_DIR/s" \
    "$(command -v tmux)"

To inspect your own running server, pass its actual socket and executable paths instead. The program observes that daemon; it does not create or stop it.

The library requires a trusted absolute socket path and a writable pin directory on that socket’s filesystem. The default pin directory is the socket’s parent. Installation describes the Linux host requirements.

Physical entities and appearances¶

A session links windows at numeric indices. The same physical window can appear at two indices in one session or in several sessions. A pane belongs to its physical window, while a pane occurrence retains the window-link context:

flowchart LR
    S["Session demo"] --> L0["WindowLink index 0"]
    S --> L4["WindowLink index 4"]
    L0 --> W["Window @0"]
    L4 --> W
    W --> P["Pane %0"]

windows and panes return each physical entity once. windowLinks and paneOccurrences retain both appearances in this fixture. Lists use numeric ID order; links use session ID and window index; occurrences use link and pane index. Indexed lookups avoid rescanning those lists.

References compare targeting identity within one Server generation. A lookup returns the observation from the supplied snapshot, including a later capture from that same Server. Independent Server scopes have distinct generations. Resolving a native ID with flookupPaneId deliberately selects its observation in the supplied snapshot; it does not restore an earlier targeting guarantee.

Record updates create local values. They do not update the snapshot’s indexes, validate a caller-edited graph or send a tmux command. Use dimensionValue pane.width for numeric comparisons; checked dimensions have no Num instance. Paths and current process names preserve POSIX bytes; window labels use TTmuxText with explicit, fallible text conversion.

Errors and recovery¶

Acquisition fails in IO with TTmuxException. Pure navigation returns Either LookupError; missing or foreign references never become empty results. The snapshot records a monotonic capture interval. It does not claim a transaction over tmux and operating-system state.

fwithServer preserves a callback’s original exception, including cancellation. If bounded cleanup remains incomplete, its exception context retains a TCleanupRecovery. After a successful callback, incomplete cleanup raises cCleanupFailed instead of returning success.

Use ftryTmux to catch library failures with their ExceptionWithContext, or Control.Exception.tryWithContext when handling application exceptions and cancellation too. Ordinary typed try loses this context when returning the concrete exception. Keep the context while recovering ownership.

fcleanupRecoveries and fcaptureRecoveries retrieve correlated owners from that context. Inspect them locally, resume existing cleanup, or explicitly detach logical uncertainty. Resuming never dispatches a second capture; detachment does not terminate native resources or prove daemon-side completion. The process contract defines these outcomes in detail.

Use validated offline fixtures to exercise application graph logic without tmux. Their references belong to a separate offline origin.

The capture baseline covers controlled graph sizes. The shared Runtime guide covers independent handle lifetimes. Broader performance cases remain qualification work for the public observation milestone. The status page records the broader implementation scope.

The example fixture verifies daemon exit after setup failure before session dispatch, and both daemon and pane exit after callback failure or cancellation. The runner joins interrupted session clients. When creation was dispatched but the pane receipt is unavailable, it reports that incomplete ownership explicitly.