Make tmux operations literal, bounded, and identity-safe

.github/CONTRIBUTING.md

@@ -16,7 +16,6 @@ Nothing about this is a convention you have to remember:
 | --- | --- | --- |
 | `libtmux*/` | yes | one artifact each, named for its directory |
 | `integration-tests/` | no | the real-tmux suite, which spans artifacts |
-| `benchmarks/` | no | the carrier measurements |
 | `examples/` | no | whole runnable programs, run by its own suite |
 | [`docs-tests/`](../docs-tests/) | no | compiles and runs every snippet in the docs |
 | `scripts/` | no | what the build does not do |
@@ -88,19 +87,6 @@ A unix socket path cannot exceed about 104 bytes, and tmux reports a longer one
 as `error connecting to … (File name too long)`. That rules out sockets under a
 build directory or a deep scratch path, and it is why the roots above are short.
 
-`ExecutionMode` chooses how a command travels, and the suite can be run under
-any of them:
-
-```console
-$ LIBTMUX_MODE=control ./gradlew check
-```
-
-A failure that appears only under one carrier is a real finding — the library
-claims the answer does not depend on the carrier, and
-`ExecutionModeConformanceTest` is where that claim is gated. Confirm it against
-a clean `/tmp` first: the failure modes of cross-port debris and of a genuine
-carrier defect look alike.
-
 Against every supported tmux release:
 
 ```console
@@ -215,7 +201,7 @@ toolchain and `options.release` in
 matrix in the CI workflow, which builds on 21 and 25, and the claim `README.md`
 makes under `Requirements`.
 
-**tmux 3.2a through 3.7b is the supported range**, and it is not a claim: the
+**tmux 3.2a through 3.7c is the supported range**, and it is not a claim: the
 whole real-tmux suite runs against every one of those releases, and each lane
 checks it really ran the tmux it is named after. Moving the range means moving
 `workflows/tmux-matrix.yml` and the README together.

.github/WRITING.md

@@ -28,7 +28,7 @@ Four things near the top are compatibility claims, and they move together:
   exported identifiers without a deprecation period, pin an exact version, not
   recommended for production. `CHANGELOG.md` and the `Status` section say the
   same thing in the same words.
-- **The requirements are JDK 21 or newer, and tmux 3.2a through 3.7b.** The tmux
+- **The requirements are JDK 21 or newer, and tmux 3.2a through 3.7c.** The tmux
   range is not a claim — the matrix runs every lane of it — so it may not drift
   from `workflows/tmux-matrix.yml`.
 - **Coordinates are group `io.github.libtmux`, imported through
@@ -79,7 +79,7 @@ makes it decidable:
   points at `tmux_list_servers`.
 ```
 
-Name identifiers literally: `Pane.capture`, `LIBTMUX_MODE`, `--rerun-tasks`,
+Name identifiers literally: `Pane.capture`, `LIBTMUX_WATCH`, `--rerun-tasks`,
 `tmux://panes/{pane}`. Lead with a concrete verb — add, fix, remove, reject,
 `now`, `no longer`.
 
@@ -104,7 +104,7 @@ Order it capability, then consequence, then compatibility:
 
 > 0.0.1-alpha.7 adds streaming capture, and rejects `windowId` at pane scope
 > rather than ignoring it. Pass `scope: window` to read at window scope. JDK 21
-> and tmux 3.2a through 3.7b are unchanged.
+> and tmux 3.2a through 3.7c are unchanged.
 
 The title is plain — the version, optionally preceded by `libtmux for Java`.
 Never "we are excited to announce"; state what shipped.
@@ -354,8 +354,8 @@ has nothing but the string:
   "JDK 21" both appear upstream — this project writes **JDK 21**.
 - A **pane**, **window**, **session**, and **server** are what tmux calls them.
   Do not introduce a synonym for one.
-- Write the identifier, not a description of it: `LIBTMUX_MODE=control`, not
-  "the mode environment variable"; `--rerun-tasks`, not "the rerun flag";
+- Write the identifier, not a description of it: `LIBTMUX_WATCH=true`, not
+  "the watch environment variable"; `--rerun-tasks`, not "the rerun flag";
   `/tmp/libtmux-java-test/`, not "the test socket directory".
 
 Treat AI slop as review-hostile noise. The goal is information density:

.github/workflows/tmux-matrix.yml

@@ -1,6 +1,6 @@
 name: tmux matrix
 
-# The README claims tmux 3.2a through 3.7b, and says that range is not a claim because the suite runs
+# The README claims tmux 3.2a through 3.7c, and says that range is not a claim because the suite runs
 # against every one of them. This is where that stops depending on someone running it locally.
 
 on:
@@ -32,7 +32,7 @@ jobs:
       matrix:
         # Must match the lanes in build-logic/src/main/kotlin/libtmux.tmux-matrix.gradle.kts, which
         # is the source of truth. The agree step below fails if they drift apart.
-        tmux: ['3.2a', '3.3a', '3.4', '3.5', '3.6', '3.7', '3.7a', '3.7b']
+        tmux: ['3.2a', '3.3a', '3.4', '3.5', '3.6', '3.7', '3.7a', '3.7b', '3.7c']
     steps:
       - uses: actions/checkout@v7
 

CHANGELOG.md

@@ -12,6 +12,127 @@ production.
 
 ## Unreleased
 
+### Added
+
+- **`Pane.findWindow` searches by name, title, or content, with
+  case-insensitive and regular-expression matching.** Build a `FindSpec` or
+  configure one inline. (#6)
+- **`Batch.length()` reports the exact UTF-8 byte length of the encoded
+  command.** Use it to dispatch before tmux's command-size limit is reached.
+  (#6)
+- **`Pane.paste(String)` sends literal text without leaving a server buffer.**
+  Text no longer shares tmux's command-size limit; this API requires tmux 3.4.
+  (#6)
+
+### Changed
+
+- **`Pane.findWindowByName` and `Pane.findWindowByContent` are removed.** Use
+  `findWindow` with `inName()` or `inContent()`. (#6)
+- **`Server.waitFor`, `waitForWithSignalCapacity`, `signal`, and `drain` move
+  to `Server.channel(name)`.** Use `await`, `awaitReservingCapacity`,
+  `signal`, and `drain` on the returned `Channel`. (#6)
+- **`Pane.mode()` returns `PaneMode` rather than text.** Compare against enum
+  values such as `PaneMode.TREE`; `modeOrNull()` changes with it. (#6)
+- **The supported tmux range now includes 3.7c.** The compatibility matrix runs
+  that lane. (#6)
+- **`Server.snapshot()` captures the hierarchy in one fenced command group.**
+  Watchers start fewer tmux processes, and a replacement server is rejected
+  before its rows are read. (#6)
+- **`CommandRequest` carries command groups and optional input rather than one
+  flat argv.** Use `CommandRequest.of` for one command and `commands()` where
+  `argv()` was read; `ControlClient.isCommandGroup` is removed. (#6)
+- **`Pane.paste(String bufferName)` is now `Pane.pasteBuffer(String name)`.**
+  `Pane.paste(String)` now means literal text. (#6)
+- **`ControlClient.onOutput` and `onEvent` are replaced by bounded pull
+  subscriptions.** Use `subscribeOutput` or `subscribeEvents`, close the
+  returned `EventSubscription`, and inspect `droppedCount()`. (#6)
+- **Filter expressions are immutable, model-bound wire values.** Build fields
+  and relations through `Fields` or generated handles, and pass the matching
+  `FilterModel` to `FilterJson.write*`; `EntityMetamodel`, `FieldProvenance`,
+  and `FieldRef.name()` are removed. (#6)
+- **`ProcessTransport` now bounds concurrency, input writes, output, deadlines,
+  and cleanup.** Configure its limits through the constructors; timeouts
+  surface as `TmuxTimeoutException` with dispatch certainty. A deadline or
+  cancellation during input terminates the child instead of blocking. (#6)
+- **`Buffers.delete` now requires tmux 3.4 and reports a missing name.** tmux
+  3.2a and 3.3a can delete the top buffer when the named buffer is absent, so
+  the library refuses that unsafe operation. (#6)
+
+### Fixed
+
+- **Destructive MCP tools fail closed when caller-pane identity cannot be
+  proven.** Uncertain socket, server, or pane identity now requires explicit
+  self-confirmation instead of bypassing the guard. (#6)
+- **MCP pane cursors are authenticated and bound to daemon and pane identity.**
+  Reads preserve continuity across bounded history compaction when it can be
+  proven, and pane capture uses identity-fenced batches with strict outcome
+  checks. (#6)
+- **`RowFormat` uses an explicit record terminator.** Multiline final fields
+  and single-field rows no longer depend on physical line boundaries. (#6)
+- **`tmux_run` requires a POSIX shell and uses a 128-bit completion marker.**
+  It refuses another foreground program instead of sending shell framing that
+  program cannot interpret. (#6)
+- **Hierarchy listings preserve values containing newlines.** A pane working
+  directory containing a newline no longer empties session, window, and pane
+  listings. (#6)
+- **`Options.all`, `Options.effective`, and `Options.get` return complete
+  stored values.** Escape-sensitive and multiline strings are no longer
+  altered or truncated. (#6)
+- **`Server.expand`, `Session.expand`, `Window.expand`, and `Pane.expand`
+  preserve multiline results.** They no longer return only the first line.
+  (#6)
+- **Names, options, sent keys, shell commands, and batch operations preserve a
+  trailing semicolon.** The semicolon remains data rather than ending the tmux
+  command. (#6)
+- **`Pane.sendLine`, command-chain input, and `tmux_run` deliver text plus
+  Enter as one literal operation.** Option-shaped input remains data, and
+  concurrent calls cannot interleave their input. (#6)
+- **`tmux_paste_text` no longer leaves pasted text on the server when a client
+  disconnects during the call.** (#6)
+- **`tmux_run` keeps caller shell syntax isolated from completion framing, uses
+  the server's resolved tmux binary, and keeps completion state off pane
+  options.** A command accepted before an indeterminate send failure still
+  executes. (#6)
+- **Serialized MCP sends obey their queue and byte bounds across cancellation
+  and shutdown.** A send cancelled after promotion is skipped before delegate
+  delivery, later sends keep order, and close settles every admitted caller.
+  (#6)
+- **`libtmux-mcp` publishes the dependencies its API exposes.** Consumers now
+  receive `mcp-core`; the artifact no longer selects an SLF4J provider or
+  exports `libtmux-jackson`. (#6)
+- **Handles refuse a replacement tmux server that reused an identifier.**
+  Linked-window operations also retain the exact session and index they came
+  from. (#6)
+- **Workspace input is validated before session creation.** Unsupported
+  layouts, unsafe names, malformed topology, and uncertain creation replies
+  leave tmux untouched or roll back the exact staging session. (#6)
+- **MCP watching stays consistent across concurrent output, new sessions,
+  dropped events, outages, and server restarts.** Notifications are serialized
+  and bounded, and watcher clients remain hidden from listings. (#6)
+- **The MCP launcher exits when its protocol session ends.** Oversized or
+  malformed input and output failures no longer leave the process waiting on
+  stdin. (#6)
+- **MCP tools now advertise non-additive effects as destructive.** Clients can
+  request confirmation for commands, input, and settings even when the safety
+  ceiling permits those tools. (#6)
+- **MCP rename and kill tools resolve destructive targets unambiguously.**
+  Session operations use stable identifiers; only arguments explicitly naming
+  a session by name use names. (#6)
+- **Snapshot-backed accessors reject a closed `Server`.** They no longer turn
+  use after close into an empty hierarchy. (#6)
+- **A live server with no sessions captures as an empty snapshot.** Child
+  listings are not attempted when tmux has no current target. (#6)
+- **`TmuxExtension` proves abandoned servers exited before deleting their
+  directories.** Successful recovery also removes the abandoned directory.
+  (#6)
+
+### Removed
+
+- **`ExecutionMode`, `ControlTransport`, `VirtualThreadTransport`,
+  `LIBTMUX_MODE`, and their benchmark surface are removed.** `Server` uses
+  process execution; use `ControlClient` for event streams and batches or
+  command chains to reduce round trips. (#6)
+
 ## 0.0.1-alpha.7 — 2026-08-22
 
 ### Documented

README.md

@@ -159,32 +159,11 @@ In a real pane those two variables are already set, so `TmuxEnvironment.current(
 takes nothing and returns empty when there is no pane to describe. This README is
 not running inside one, so the example supplies them.
 
-## Three switches
+## Avoid unnecessary round trips
 
-| to stop                                     | write                          | which costs                    |
-| ------------------------------------------- | ------------------------------ | ------------------------------ |
-| paying for a process per command            | `.mode(ExecutionMode.CONTROL)` | one tmux client, then reused   |
-| waiting on the thread you were handed       | `.mode(ExecutionMode.VIRTUAL)` | a virtual thread per command   |
-| round-tripping to learn what you just made  | `server.chain()`               | one request, however many steps |
-
-```java
-ServerConfig config = ServerConfig.builder()
-        .endpoint(ServerEndpoint.socketPath(socket))
-        .mode(ExecutionMode.CONTROL)
-        .build();
-```
-
-A carrier can also be chosen from outside the program that uses one, so trying
-another costs nothing:
-
-```console
-$ LIBTMUX_MODE=control java -jar app.jar
-```
-
-A carrier and a grouping are separate choices that compose, and neither changes
-what a call returns: the same filter answers identically under each. What that
-costs is measured in [the benchmark](docs/benchmarks/modes.md), which shows the
-identical answers next to the different prices.
+`server.batch()` sends independent commands in one invocation. `server.chain()`
+does the same for dependent commands, letting tmux carry the current target from
+one step to the next. Both retain an outcome for every operation.
 
 ## What it is like to use
 
@@ -238,7 +217,7 @@ README, and each is [on Maven Central](https://central.sonatype.com/namespace/io
 
 Not published, and part of how the library is built:
 [`examples/`](examples/) · [`integration-tests/`](integration-tests/) ·
-[`docs-tests/`](docs-tests/) · [`benchmarks/`](benchmarks/) ·
+[`docs-tests/`](docs-tests/) ·
 [`scripts/`](scripts/) · `build-logic/`
 
 A directory is a published artifact exactly when it appears above, and
@@ -306,7 +285,7 @@ bug. See [the Scala guide](docs/guide/scala.md).
 
 JDK 21 or newer.
 
-tmux 3.2a through 3.7b. That range is not a claim: the whole real-tmux suite runs
+tmux 3.2a through 3.7c. That range is not a claim: the whole real-tmux suite runs
 against every one of those releases, and each lane checks it really ran the tmux
 it is named after.
 
@@ -317,7 +296,6 @@ $ ./gradlew testTmuxMatrix -PlibtmuxMatrix=/path/to/tmux/builds
 ## Documentation
 
 - [Getting started](docs/guide/getting-started.md)
-- [Execution modes](docs/guide/execution-modes.md) — and the [measured comparison](docs/benchmarks/modes.md)
 - [Filtering](docs/guide/filtering.md)
 - [Options and hooks](docs/guide/options-and-hooks.md)
 - [Batching and chaining](docs/guide/batching-and-chaining.md)

benchmarks/README.md

@@ -1,22 +1,30 @@
 # benchmarks
 
-**Measures what each carrier costs. Not published.**
+**Measures what an operation costs. Not published.**
 
-`ExecutionMode` changes how a command travels, never what it answers. This
-measures the difference in price, and regenerates
-[`docs/benchmarks/modes.md`](../docs/benchmarks/modes.md) from a real run.
+Every command this library sends starts a tmux process, so what a caller pays is
+decided by how many commands an operation takes rather than by how fast any one
+of them runs. This measures that, and regenerates
+[`docs/benchmarks/operations.md`](../docs/benchmarks/operations.md) from a real
+run.
 
 ```console
-$ ./gradlew modeBenchmark -PlibtmuxTmux=/path/to/tmux
+$ ./gradlew operationBenchmark -PlibtmuxTmux=/path/to/tmux
 ```
 
-The table is **never hand-edited**. It shows identical answers next to different
-prices, which is the only honest way to present a performance switch.
+The table is **never hand-edited**, and it stamps which tmux answered, because a
+table without its conditions is a claim rather than a measurement. Read the
+dispatch counts; the milliseconds are one machine at one moment.
+
+Four things are measured, and each exists because the library made a choice that
+costs something: collapsing round trips with `batch()` and `chain()`, capturing
+the hierarchy, fencing a handle's command against a replaced server, and reading
+a scope's options.
 
 Its own module, and excluded from `check`: a benchmark starts a tmux server per
 case and takes seconds. Keeping it inside a published artifact's tests made that
 a matter of remembering a tag rather than a matter of where the code lives.
 
 ## Next
 
-- [Execution modes](../docs/guide/execution-modes.md) · [the measured table](../docs/benchmarks/modes.md)
+- [Batching and chaining](../docs/guide/batching-and-chaining.md) · [the measured table](../docs/benchmarks/operations.md)

benchmarks/build.gradle.kts

@@ -1,30 +1,27 @@
-// Measures what each carrier costs, and rewrites docs/benchmarks/modes.md from a real run.
+// Measures what an operation costs, and rewrites docs/benchmarks/operations.md from a real run.
 //
 // Its own module, and never published. A benchmark takes seconds per case and starts a server per
 // case, so it must not run in any ordinary suite; keeping it in a published artifact's tests made
 // that a matter of remembering a tag rather than a matter of where the code lives.
 plugins { id("libtmux.java-library") }
 
-dependencies {
-    testImplementation(project(":libtmux"))
-    testImplementation(project(":libtmux-junit5"))
-}
+dependencies { testImplementation(project(":libtmux")) }
 
 // Nothing here belongs to `check`: it writes a file and takes seconds. Run it when the table needs
 // regenerating.
 tasks.named<Test>("test") { enabled = false }
 
-tasks.register<Test>("modeBenchmark") {
+tasks.register<Test>("operationBenchmark") {
     group = "verification"
-    description = "Measures each execution mode and rewrites docs/benchmarks/modes.md."
+    description = "Measures what each operation costs and rewrites docs/benchmarks/operations.md."
     val tests = sourceSets.test.get()
     testClassesDirs = tests.output.classesDirs
     classpath = tests.runtimeClasspath
     useJUnitPlatform { includeTags("benchmark") }
     systemProperty("libtmux.tmux", providers.gradleProperty("libtmuxTmux").getOrElse("tmux"))
     systemProperty(
         "libtmux.benchmark.out",
-        rootProject.layout.projectDirectory.file("docs/benchmarks/modes.md").asFile.path,
+        rootProject.layout.projectDirectory.file("docs/benchmarks/operations.md").asFile.path,
     )
     outputs.upToDateWhen { false }
 }