Send caller text literally, surface every failure

.github/CONTRIBUTING.md

@@ -334,11 +334,12 @@ not in its generated output, and survive rerecording. A `missing` row is a
 field a listing could carry and does not; adding one is ordinary work, leaving
 it unrecorded is not.
 
-**Parsers that read from outside are fuzzed.** The control-mode line parser,
-the filter-expression wire format, and the workspace YAML loader each have a
-target under `fuzz/`. Add one when adding a parser that reads bytes this crate
-did not write, and seed it — an unseeded target proves only that arbitrary
-input is not valid input.
+**Parsers that read from outside are fuzzed.** `just fuzz-list` names a target
+for each; `design.md` says what each checks. Add one when adding a parser that
+reads bytes this workspace did not write, seed it from real output, and give it
+an oracle where one exists — an unseeded target proves only that arbitrary
+input is not valid input, and one without an oracle proves only that it does
+not panic.
 
 **Packaging is a gate.** `just package` builds the published crates and
 verifies what the tarballs contain. A packaged crate ships its README, so a
@@ -371,6 +372,11 @@ The floor is stated in several places, and they have to agree:
 then the `tmux-mcp` tests on 1.88.0. `rust-toolchain.toml` pins a much newer
 toolchain for day-to-day work; it is not the floor and does not prove one.
 
+The derive's compile-fail cases pin rustc's diagnostics, which change between
+releases, so they run on the pinned toolchain only; the MSRV run checks the
+passing cases. After a toolchain bump, `just macros-ui-bless` rewrites their
+`.stderr` files; review the diff before committing it.
+
 ## Dependencies
 
 - A declared version is the **minimum supported**, not the newest published,
@@ -400,11 +406,12 @@ follows is the rule.
   invalid UTF-8, so they cross the API as `TmuxText`. Reading a tmux stream
   with anything that requires UTF-8 fails the whole operation the first time a
   pane prints a high byte.
-- **Listings come in pairs, and the short name is the loud one.** `sessions()`
-  returns `Result`; `sessions_or_empty()` collapses failure into no rows. Both
-  halves are load-bearing, and which one gets the short name is the point: a
-  caller who writes the obvious thing gets the error, and a caller who wants
-  an empty list on failure has to say so. Add both when adding a listing.
+- **A listing propagates; nothing collapses a failure into empty rows for
+  it.** `sessions()` returns `Result`, and a caller who wants an empty list on
+  failure writes `sessions().await.unwrap_or_default()` at the call site. An
+  `_or_empty` twin of each listing existed once; nothing called one, and a
+  method whose whole purpose is to discard a reason is a way to discard one by
+  accident, so they are gone.
 - **A failure says what to do about it.** `Error::kind` reduces the variants
   to a decision, and `is_object_gone` is the branch most callers write. tmux
   reports a missing target and a bad argument with the same exit status, so

.github/WRITING.md

@@ -122,6 +122,15 @@ channel inside a type is not documentation.
   restating that it can fail.
 - `# Panics` where a caller could trip one. Where nothing can, "Never panics"
   is worth writing: it is a promise, and inference is not.
+- `# Cancel safety` on an `async fn` whose future, dropped partway, leaves
+  something a caller has to know about. Say which of three it is: nothing
+  happened; the effect may or may not have happened, so a retry can repeat it;
+  or something is left held -- a lock, a queue position, a half-sent input.
+  The crate-wide model is in the README's "Cancellation and shutdown": dropping
+  a dispatch signals its process group and reaps it. A method that adds nothing
+  to that model needs no section; one that does needs one, because a caller
+  racing it against a timeout or a `select!` cannot read the answer off the
+  signature.
 - No `# Safety`. `unsafe_code` is `forbid` at the workspace level, so there is
   no unsafe code here to document. If that ever changes, the section states
   the proof obligation the caller must uphold, and the reason it holds.

.github/workflows/ci.yml

@@ -54,7 +54,7 @@ jobs:
         with:
           tool: just,cargo-hack,cargo-deny,uv
 
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
 
       - run: just check
 
@@ -81,7 +81,7 @@ jobs:
       - uses: dtolnay/rust-toolchain@v1
         with:
           toolchain: stable
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
 
       # `--no-fail-fast` because this lane runs only on master and bills at ten
       # times a Linux runner. Stopping at the first failing test binary hides
@@ -107,7 +107,7 @@ jobs:
       - uses: taiki-e/install-action@v2
         with:
           tool: just
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
       - run: just api-check
       # Same toolchain and the same rustdoc JSON, so it rides along here
       # rather than paying for a second nightly build.
@@ -127,7 +127,15 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        target: [control_line, filter_expr_json, workspace_yaml]
+        target:
+          - control_block
+          - control_line
+          - environment_listing
+          - filter_expr_json
+          - format_rows
+          - text_filter
+          - list_keys
+          - workspace_yaml
     steps:
       - uses: actions/checkout@v7
       - uses: dtolnay/rust-toolchain@v1
@@ -136,7 +144,16 @@ jobs:
       - uses: taiki-e/install-action@v2
         with:
           tool: cargo-fuzz
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      # The corpus is what this job grows. Cache entries are immutable, so each
+      # run saves under its own key and the next restores the newest by prefix.
+      # An entry unused for seven days is evicted: a late run restarts from seeds.
+      - name: Restore the ${{ matrix.target }} corpus
+        uses: actions/cache/restore@v6
+        with:
+          path: fuzz/corpus/${{ matrix.target }}
+          key: fuzz-corpus-${{ matrix.target }}-${{ github.run_id }}
+          restore-keys: fuzz-corpus-${{ matrix.target }}-
       - name: Fuzz ${{ matrix.target }}
         env:
           TARGET: ${{ matrix.target }}
@@ -146,8 +163,17 @@ jobs:
           # statically, which a sanitizer cannot instrument, so the target
           # has to be named here rather than left to how cargo-fuzz arrived.
           host=$(rustc +nightly -vV | sed -n 's/^host: //p')
-          cargo +nightly fuzz run --target "$host" "$TARGET" "fuzz/seeds/$TARGET" \
+          # libFuzzer writes new inputs to the first directory only.
+          mkdir -p "fuzz/corpus/$TARGET"
+          cargo +nightly fuzz run --target "$host" "$TARGET" \
+            "fuzz/corpus/$TARGET" "fuzz/seeds/$TARGET" \
             -- -max_total_time=300 -rss_limit_mb=4096
+      - name: Save the ${{ matrix.target }} corpus
+        if: always()
+        uses: actions/cache/save@v6
+        with:
+          path: fuzz/corpus/${{ matrix.target }}
+          key: fuzz-corpus-${{ matrix.target }}-${{ github.run_id }}
       - name: Keep any crash that was found
         if: failure()
         uses: actions/upload-artifact@v7
@@ -180,6 +206,6 @@ jobs:
       - uses: taiki-e/install-action@v2
         with:
           tool: just
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
 
       - run: just compat

.github/workflows/release.yml

@@ -57,7 +57,7 @@ jobs:
         with:
           tool: just,cargo-hack,cargo-deny,uv
 
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
 
       - run: just check
 
@@ -90,7 +90,7 @@ jobs:
       - uses: dtolnay/rust-toolchain@v1
         with:
           toolchain: stable
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
 
       # The tag is an assertion about the tree, and an assertion is worth
       # checking: a tag naming a version the manifest does not carry would

CHANGELOG.md

@@ -16,6 +16,180 @@ full.
 
 ## Unreleased
 
+### Fixed
+
+- Creation commands and plans, shell commands, messages, key bindings and
+  access rules treat caller text beginning with `-` as a value instead of a
+  tmux flag. (#28)
+
+- `PaneOutput` ends when its pane or window closes. (#28)
+
+- `Pane::stream_output` preserves frame-limit errors while opening its
+  output stream. (#28)
+
+- `ControlSender::resume_pane` and `unmute_pane` restore output after
+  muting. (#28)
+
+- `ControlSender::watch_only` leaves panes in other sessions unchanged. (#28)
+
+- `Server::lock_channel` and `wait_for_channel` preserve locks and signals
+  when a waiting call is cancelled or times out. (#28)
+
+- `Pane::capture_with` trims unwritten padding from joined lines on tmux
+  3.2a, so equality checks see the text the pane printed. (#28)
+
+- `Server::environment_all` and `Session::environment_all` accept variable
+  names and values containing shell punctuation or newlines. (#28)
+
+- Replacing `set_hooks` no longer leaves a hook cleared but unwritten when
+  the call is cancelled. (#28)
+
+- Object listings decode the additional format escapes emitted by newer
+  tmux builds. (#28)
+
+- `tmux-mcp`'s `wait_for_text` ignores echoed input from `send_keys`,
+  `paste_text` and `run_shell_command` when matching command output. (#28)
+
+- `tmux-mcp`'s streamed captures and waits keep reading output after an
+  unterminated terminal escape string. (#28)
+
+- `tmux-mcp` reports tool refusals as tool errors, with structured reasons
+  for clients deciding whether to retry. (#28)
+
+- `tmux-mcp` accepts session IDs returned by its own listings. (#28)
+
+- `tmux-mcp` treats empty `TMUX` and `TMUX_PANE` as detached operation. (#28)
+
+- `tmux-mcp` accepts interrupt keys while `run_shell_command` owns a pane,
+  so callers can stop a running command. (#28)
+
+- `tmux-mcp` keeps its shared daemon alive while another instance uses it.
+  (#28)
+
+- `tmux-workspace` executes tmuxp's command shorthand and creates empty
+  panes from its blank-pane forms. (#28)
+
+- `tmux-workspace` resolves inherited and relative start directories and
+  expands environment variables as tmuxp does. (#28)
+
+- `tmux_workspace::freeze` records an idle shell as an empty pane, so
+  rebuilding it does not start a nested shell. (#28)
+
+### Added
+
+- `Server::over_control_mode` routes typed operations through an existing
+  control connection; blocking operations require the original server. (#28)
+
+- `Server::owns_control_client` and `Client::is_own` identify this process's
+  control clients. MCP attachment reports exclude those clients. (#28)
+
+- `plan::Pause` delays later operations in a plan. Control-mode plans
+  refuse pauses before running any operations. (#28)
+
+- `Server::typed_key_bindings` reads key bindings as structured values on
+  tmux 3.7 and newer. (#28)
+
+- `Pane::get`, `Window::get`, `Session::get` and `Client::get` read fields
+  already fetched by a listing, including fields without named getters. (#28)
+
+- `set_typed_option` validates option values before writing them. (#28)
+
+- `Server::load_buffer` and `save_buffer` transfer buffer contents through
+  files, including buffers too large for command arguments. (#28)
+
+- `Server::with_channel_lock` releases its lock when the operation ends,
+  including failure or cancellation. (#28)
+
+- `NewSessionOptions::environment` sets environment variables for a
+  session's first process. (#28)
+
+- `Pane::wait_until` waits for a predicate over captured lines and reports
+  arrival, pane death or timeout. (#28)
+
+- `TmuxVersion::has_behavior` checks capabilities on development builds
+  using the same rules as `Server::require`. (#28)
+
+- `Pane::stream_output_with_limits` lets callers bound streamed output.
+  (#28)
+
+### Changed
+
+- **Breaking.** `Session`, `Window`, `Client` and `ServerGeneration`
+  timestamp accessors return `SystemTime`; convert through `UNIX_EPOCH`
+  when Unix seconds are needed. (#28)
+
+- **Breaking.** Buffer names use `TmuxText` to preserve arbitrary bytes;
+  pass listed names directly to buffer reads and deletion. (#28)
+
+- **Breaking.** Pane and window respawning use `Respawn::Replacing` or
+  `Respawn::OnlyIfDead` in place of a boolean. (#28)
+
+- **Breaking.** `Server::display_menu` accepts `MenuItem` values in place
+  of tuples. (#28)
+
+- **Breaking.** ID field handles carry their ID type; update explicit
+  `TextField` annotations as shown in the migration guide. (#28)
+
+- **Breaking.** `ControlEvents` reports stream failures during iteration.
+  Handle each event's error before reading the event. (#28)
+
+- **Breaking.** `with_session`, `with_window` and `with_pane` report
+  `ScopeError`, preserving both operation and cleanup failures. (#28)
+
+- **Breaking.** Query iterators support owned values through
+  `matching_owned`; update explicit trait bounds using the migration guide.
+  (#28)
+
+- **Breaking.** `AccessRule::name` replaces `user`, and `principal`
+  distinguishes users from groups. (#28)
+
+- **Breaking.** `Pane::pid` can be absent for a dead pane; use `is_dead`
+  to check liveness. (#28)
+
+- `Window::select_layout` and layout operations in plans, workspaces and
+  MCP refuse invalid layouts before dispatch. Unique preset prefixes remain
+  accepted. (#28)
+
+- **Breaking.** `tmux-mcp` tool methods return `ToolError` for refusals.
+  (#28)
+
+- **Breaking.** `tmux-mcp`'s `wait_for_text` distinguishes output present
+  at entry, pending input and output received during the wait. (#28)
+
+- **Breaking.** MCP tool metadata omits repeated descriptions and schemas;
+  read them from the tool or `tmux://capabilities`. (#28)
+
+- `tmux-mcp` requires the `teardown` toolset for `set_history_limit`. (#28)
+
+- **Breaking.** `tmux-workspace` configuration errors include line and
+  column fields; update matches on `ConfigError`. (#28)
+
+- **Breaking.** `tmux-workspace` suppresses shell history by default; set
+  `suppress_history: false` to record commands. (#28)
+
+- **Breaking.** `PaneConfig::shell_commands` uses `ShellCommand` values to
+  support tmuxp's per-command Enter and delay settings. (#28)
+
+### Removed
+
+- **Breaking.** The `*_or_empty` listing helpers are removed. Handle
+  listing errors or apply `unwrap_or_default` at the call site. (#28)
+
+- **Breaking.** `get_option` and its global variants are removed; use
+  `typed_option` and the corresponding typed global readers. (#28)
+
+### Security
+
+- Names, titles and start directories are literal text by default. Drop
+  manual format escaping; use `TmuxArg::format` for intentional templates.
+  (#28)
+
+- `test::TestServer` limits inherited environment variables so tests do not
+  expose unrelated exported values through tmux. (#28)
+
+- **Breaking.** MCP environment tools withhold values unless their names
+  appear in `LIBTMUX_ENVIRONMENT_VALUES`. (#28)
+
 ## 0.1.0-alpha.11 - 2026-09-12
 
 `libtmux`, `libtmux-macros`, and `tmux-workspace` are 0.1.0-alpha.11;

README.md

@@ -29,8 +29,8 @@ You may be looking for:
   transport switches, testing
 - [`tmux-mcp`](crates/tmux-mcp/README.md) — the MCP server, a **separate
   package**, if you want an agent to drive tmux
-- [Examples](crates/libtmux/examples) — six programs that run and clean up
-  after themselves, from reading a server to watching one over control mode
+- [Examples](crates/libtmux/examples) — programs that run and clean up after
+  themselves, from reading a server to watching one over control mode
 - [Design notes](crates/libtmux/docs/design.md) — why it is shaped this way
 - [Parity ledger](crates/libtmux/docs/parity.md) — capability-by-capability
   against Python libtmux
@@ -190,7 +190,9 @@ a CLI, a config file, or an MCP tool call can carry one.
 Three switches, each a Cargo feature, none of them the default. The same
 workload under each, printed by `cargo run --example matrix --all-features`.
 Every column but `wall` is exact and checked against this block by
-`just example-tables`; the timings are one run on one developer machine:
+`just example-tables`; the timings are one run on one developer machine.
+`processes` is counted: the example runs tmux through a wrapper that logs
+each start. `routed` is `Plan::run` on a `Server::over_control_mode` handle:
 
 <!-- example-output: matrix --all-features -->
 
@@ -201,7 +203,8 @@ blocking/sequential      plan                        6         6     16ms  per-c
 async/sequential         plan                        6         6     16ms  per-command  2 panes, 2 windows, 2 active
 async/folded             plan                        3         3      9ms  merged       2 panes, 2 windows, 2 active
 async/marked-fold        plan                        3         3     10ms  merged       2 panes, 2 windows, 2 active
-control-mode/streaming   plan,control-mode           6         1      6ms  per-command  2 panes, 2 windows, 2 active
+control-mode/streaming   plan,control-mode           6         1     10ms  per-command  2 panes, 2 windows, 2 active
+control-mode/routed      plan,control-mode           6         1      6ms  per-command  2 panes, 2 windows, 2 active
 
 every mode built the same thing: true
 dispatches ranged 3..6, processes ranged 1..6