builder.applyWorkspace

Description#

tmux gives every new session a window and every new window a pane, so the first window and first pane of each level are adopted rather than created. Creating them anyway is the classic workspace-builder bug that leaves an empty leading window behind.

What this reconciles is topology: which windows exist, in what order, under what names, with how many panes, under which layout. It is safe to apply twice and the second run does not duplicate anything. It is deliberately not a process supervisor — see CommandPolicy — and it does not unset options a previous version of the file had set, because tmux cannot say which of an option's current values this file is responsible for.

This is not the builder behind the tmux-workspace command. The two are separate implementations of one idea and they answer differently: this one converges a session that exists, while the CLI compares it against the document and refuses when they disagree. The document language differs too — the schema here is strict, so environment, before_script, window_index, suppress_history, x- keys and the CLI's other fields are rejected. A file written for the CLI is not necessarily one this accepts.