Server

Description#

SYNOPSIS

    use v5.44;
    use LibTmux::Server;
    my $server = LibTmux::Server->new(socket_name => 'application');
    my $snapshot = $server->snapshot;
    my $pane = $snapshot->panes->first;
    say $server->capture_pane(pane => $pane) if defined $pane;

CONTRACT

Construction and planning perform no I/O. Acquisition and mutation are explicit, bounded operations. Captured LibTmux::Snapshot entities retain their observed graph; mutations do not refresh them. Acquire another snapshot to observe changes. Connection settings remain owned by the server wrapper; destroying it never kills a tmux daemon. See the orchestration guide.

Physical entity targets accept stable ID strings or generation-checked handles. Session-relative window operations require LibTmux::WindowLink. Checks across subprocesses are optimistic rather than transactional. Single-quote session IDs such as '$1' to avoid interpolating a Perl capture variable.

ERRORS

Invalid arguments throw "InvalidArgument" in LibTmux::X before dispatch. Acquisition and checked commands propagate typed LibTmux::X failures, including missing executables, absent daemons, vanished targets, stale handles, codec errors, timeouts, and output limits. Failures never become empty selections. Cancellation or a timeout after dispatch does not prove nonexecution or roll back effects.

VERIFICATION REPORT

"query_panes" supplies a fresh, detached hashref to on_verification. It contains no entity handles. Every ID array retains stable order; editing the report cannot mutate captured data or the query result.

policy, status, comparisonPolicy is auto, never, require, or native for the expert escape hatch. Status is disabled (never), local (no safe lowering), agreed, disagreed, or native. Comparison is none, exact_ids, candidate_superset, or captured_membership. Partial lowering checks inclusion of local matches; expert queries check only membership in the captured graph. Neither establishes full filter equivalence.native_checked, translation_exact, native_filter, reasonsnative_checked is Boolean. translation_exact is Boolean, or undef for never and expert queries. native_filter is the executed expression, or undef when no native check ran. reasons is a fresh arrayref of lowering limitations. Exact translation and agreement between two observations are separate facts.server_id, generation, daemon_version, capture_start, capture_endIdentity strings and the captured interval in wall-clock seconds since the epoch, from "metadata" in LibTmux::Snapshot. This is not an atomic observation.captured_ids, local_ids, native_idscaptured_ids and local_ids follow physical capture order; local_ids is undef for expert queries. native_ids holds unique IDs in native first-occurrence order, or undef when no check ran. An empty array is an observed empty set.missing_ids, unexpected_ids, uncaptured_idsmissing_ids lists local matches absent natively, in local order. For exact lowering, unexpected_ids lists native matches absent locally. uncaptured_ids lists native IDs absent from the graph. The latter two follow native order; inapplicable lists are empty. Any applicable mismatch produces disagreed. "QueryMismatch" in LibTmux::X carries this report for require or expert failures; the observer is not called for a failed query. A discrepancy has no inferred cause: concurrent changes, compiler defects and backend differences all need investigation.