# Dispatch, completion, and failure

Source: https://libtmux.org/en/powershell/latest/topics/execution/

> Distinguish accepted input, tmux replies, shell completion, and application readiness.

Choose the completion signal that answers your actual question. A successful
key-send operation means tmux accepted input. It does not establish that a shell
command or service has finished.

## What a result proves

| Task | Evidence to use |
| --- | --- |
| Send key tokens to a pane | [`Send-TmuxKey`](<https://libtmux.org/en/powershell/latest/reference/libtmux-send-tmuxkey/>) reports the input operation's result. |
| Run a shell command and inspect its exit status | [`Invoke-TmuxPaneCommand`](<https://libtmux.org/en/powershell/latest/reference/libtmux-invoke-tmuxpanecommand/>) waits for authenticated completion. |
| Wait for a service to announce readiness | [`Wait-TmuxPaneText`](<https://libtmux.org/en/powershell/latest/reference/libtmux-wait-tmuxpanetext/>) observes the stated text condition; check service behavior separately. |
| Send a control command | [`Invoke-TmuxControlCommand`](<https://libtmux.org/en/powershell/latest/reference/libtmux-invoke-tmuxcontrolcommand/>) returns the command reply; deferred work may continue. |
| Submit a known sequence of tmux commands | [`Invoke-TmuxChain`](<https://libtmux.org/en/powershell/latest/reference/libtmux-invoke-tmuxchain/>) dispatches the chain in order. |

The [command-completion example](https://libtmux.org/en/powershell/latest/examples/command-completion/) checks
exit status 7. A nonzero shell exit is a result, not automatically a tmux error.
The [service example](https://libtmux.org/en/powershell/latest/examples/wait-for-service/) checks a readiness line
and then makes an HTTP request. Seeing echoed input alone proves neither result.

## Commands and chains

[`New-TmuxCommand`](<https://libtmux.org/en/powershell/latest/reference/libtmux-new-tmuxcommand/>) creates an inert command value with literal argument boundaries.
Arguments can still invoke tmux features that run shell programs; literal argv
handling does not change the semantics of those features.

A chain retains guards carried by its typed commands. It returns combined output,
not an individual receipt for every step. A failure can skip later commands while
leaving earlier changes in place. A chain is not a transaction.

Use individual typed operations when later steps need newly acquired object
handles. Use bounded concurrent work only for operations whose independence you
have established. Result ordering does not imply dispatch ordering.

## Stopping the caller does not undo dispatch

Ctrl+C cancels a current wait. A dispatched command may continue, and a timeout
may leave its effect uncertain. The library does not make cancellation a rollback
or a reason to retry a mutation automatically.

PowerShell's error policy also matters: the default continuing behavior can allow
later input owners to be processed, whereas `-ErrorAction Stop` terminates the
pipeline on the reported failure. Keep the original native exception and its
available dispatch evidence when reporting the failure.

The [command guide](https://libtmux.org/en/powershell/latest/guides/commands/) covers transport and batch limits.
The [input guide](https://libtmux.org/en/powershell/latest/guides/input/) specifies completion, timeout, and key-send
behavior for each operation.