LibTmux.Workspace\Invoke-TmuxWorkspace

Description#

Apply the supplied native WorkspacePlan using its own endpoint, observed identities and frozen actions. No declaration, file, endpoint or policy can be substituted at invocation. Stale preconditions fail; invocation never replans or retries mutations automatically.

One PowerShell ShouldProcess decision covers the whole plan. Its target names the executable, socket and literal session name. Its action describes conflict, startup, readiness and compensation policy, global option effects, then lists every action and conditional cleanup step in order by kind and symbolic target. Option actions disclose scope and whether they change global defaults; request values are omitted. Inspect the original plan for full request and host-command values. WhatIf and declined confirmation perform no application I/O or cleanup and emit no WorkspaceResult.

Successful invocation returns one native WorkspaceResult containing the session, created windows, unsupported layouts and action journals. WorkspaceBuildException remains ErrorRecord.Exception under Tmux.WorkspaceApplyFailed, with the original plan as TargetObject. Inspect its Dispatch, InnerException, PartialResult, Journal and CompensationJournal; partial results are never emitted as success.

Stopping the pipeline cancels owned work. Cleanup follows the plan's frozen budget. A stopped pipeline can suppress subsequent error output, so receiving a cancellation journal after pipeline shutdown is not guaranteed. Application is detached; it does not attach a terminal or transfer ownership of the daemon. To enter the applied session, pass the successful WorkspaceResult.Session to Enter-TmuxSession in a foreground terminal outside tmux. Attachment has its own confirmation and cancellation behavior; it does not repeat application.

Notes

Replace is an explicit planning policy. Compensation can remove only creations whose ownership is established by the native journal; shell and host-script effects cannot be undone. Reuse returns the existing session without running workspace mutation or host actions. A window name with a colon or a period on exactly tmux 3.7 reports LibTmux.TmuxUnsupportedOnReleaseException before the first action creates anything.