LibTmux.Server

Description#

Server ownership

new captures a borrowed endpoint without I/O. snapshot and capabilities acquire daemon state explicitly. new-session requires an existing daemon, creates a detached session, and returns a SessionRef from tmux's returned ID. Names are literal Unicode text; controls, backslash, dot and colon are refused before creation because supported tmux releases normalize them differently. A shell-command explicitly requests tmux's shell-command interpretation.

start creates a clean foreground daemon on an exclusive temporary socket, verifies its executable profile before launch, binds its actual process identity, and creates the initial session. The startup timeout covers all stages. Linux inotify socket attributes signal listener readiness; pidfds bind termination to the original process, independently of socket reuse.

Close is idempotent and joins owned work. Borrowed daemons remain running. Owned daemons receive TERM followed by bounded KILL escalation and are reaped. Cleanup removes only the original socket and empty original directory; unknown files and replacement sockets are preserved. References retain values only and are not clients owned by the Server. A stopped owned daemon invalidates them.

Configuration factories perform one explicit identity observation. The returned facades retain endpoint and incarnation values, and each subsequent configuration operation owns its temporary command client. open-control and attach return separate lifecycle owners: callers must close them. Closing a borrowed Server does not close those owners; closing an owned daemon causes its attached clients to disconnect. attach proves process creation, not terminal readiness.

command is an explicit tmux-syntax escape hatch with a daemon fence. It does not insert an entity target or interpret shell syntax on the caller's behalf. run-batch reports partial outcomes and never promises rollback.

Explicit environment and health

from-env is the only factory that interprets TMUX. It parses its final PID and session components from the right, so commas in the socket path remain literal. It requires an absolute socket path, validates TMUX_PANE when present, observes the actual daemon and rejects a different PID. The returned borrowed facade is bound to that incarnation. Child processes still receive neither ambient variable. Imported object IDs are observations from the supplied environment, not evidence that those objects still exist:

use LibTmux; my $server = LibTmux::Server.from-env(:environment(%*ENV)); LEAVE $server.close; my $snapshot = $server.snapshot; my $pane = $snapshot.panes.where(%(id => $server.environment-pane-id)).single; my $window = $pane.window; my $session = $snapshot.sessions .where(%(id => $server.environment-session-id)).single;

The selection throws for a vanished object or absent imported ID. A window can belong to several sessions; the imported session ID supplies that context. capabilities is the explicit native health observation: success returns verified daemon evidence, while connection, identity and permission failures retain their original typed exceptions. has-session(:name) and has-session(:id) return false only after a successful exact listing finds no match. kill-server deliberately terminates the observed daemon, including a borrowed one; close continues to preserve borrowed daemons. An owner must still close after kill-server to join its process and filesystem cleanup.

Jobs and channels

run-shell receives literal shell source; tmux FORMAT-looking text is escaped before dispatch. if-shell follows the same rule for its shell condition and accepts bounded Invocation values for both branches. Its explicit :format option instead evaluates a native tmux FORMAT condition. source-file reads one literal pathname, escaping native glob metacharacters; it does not expand FORMAT, tilde or a caller shell. Relative paths use the captured command cwd. :parse-only parses configuration without executing it.

Each request shares one admission, observation and dispatch deadline. A background job acknowledges scheduling. Foreground completion follows tmux's job/command queue contract, not an application-specific postcondition; command output availability also depends on the declared daemon profile. Timing out or cancelling a client does not undo a job, configuration effect or channel lock already accepted by the daemon. wait-for offers only wait, signal, lock and unlock; it does not claim that a signal proves another process's application work completed.

Administrative commands

Diagnostics and administrative commands intentionally use the explicit bounded Invocation surface rather than separate wrappers. These complete calls retain raw stdout/stderr in Result, enforce the server deadline and throw typed command errors. list-commands, show-messages, lock-server and server-access are deliberate replacements for named Python helpers, not claims of identical typed parameters. switch-mode is also available through Invocation.

use LibTmux; my $server = LibTmux::Server.start(:name<inspection>); LEAVE $server.close; my $commands = $server.command(Invocation.new(:argv(['list-commands']))); my $access = $server.command(Invocation.new(:argv(['server-access', '-l']))); my $messages = $server.command(Invocation.new(:argv(['show-messages', '-T']))); $server.command(Invocation.new(:argv(['lock-server'])));

Administrative flags keep tmux's native semantics and errors; arbitrary Invocation values do not acquire a typed catalogue guarantee. Locking may run configured lock commands on attached clients. Access changes affect other users. Use only an endpoint whose administration the caller owns or has authorized. To detach captured clients, iterate $snapshot.clients and call each .ref.detach. Each target is identity guarded; a changing client set is not an atomic detach-all operation, and acknowledgement does not prove terminal rendering or child-process exit.