libtmux-mcp 0.1.0.alpha.2 → 0.1.0.alpha.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67e80d372c18bcd568c338b521a4511cd8ef7ab96e4d0cfcc7ddca3433a2cad5
-  data.tar.gz: c2a828bb53e812bf8c2de9ee3ddba7a09eb6064d31d075633bb57248a494bd9b
+  metadata.gz: af3b345cc9efd2ed4fcb1c384d8ee9a0e8f14b0da9052eedafb5e88b285a2501
+  data.tar.gz: f6c4f2647b58a02730b17ab57190f7cfc5ef2927c923961608d2a192d9f1b077
 SHA512:
-  metadata.gz: fe3c16a4ad48bb285b4081e4be8221b1f254ed7dfb77708d90c00bbdce2551ecf2ee6ce4f0e833f9ee0dac84e3042e9bc0ac472098917d8e8b42abe986deba2a
-  data.tar.gz: 3274acee7920109154be895df17286b50fc7f34fc5939f85a20891c63253e266c2a841b5239fe4b8466aa48c49cf2e2fbed0be649e5fe9066691362aa99e7ef9
+  metadata.gz: 62dddd73fc6080af123ef9b4b5aeb5dca20c72d8798232d69df61777f3e1aaa9b44db30d1853949e2e5d266d063b6827ed2b3f4feb4950072418d2283739bba2
+  data.tar.gz: 37bffa621af62f041a08dffa029d2f060874686983982e70a1906343fd2755bfc6b81daefeb1e2914f99a53a38ba7d88c1b90edb1982f3f48349396bdb1a91e9

data/README.md

@@ -12,27 +12,101 @@
 # libtmux-mcp
 
 Expose an existing tmux server over MCP stdio. Read snapshots, capture pane
-output, wait for events, or explicitly enable creation, input and shell commands.
-The official MCP SDK handles the protocol; bounded Async tasks handle transport.
+output and wait for events, or enable creation, input and shell commands one
+tool at a time.
+
+[API reference](https://libtmux.org/en/ruby/latest/mcp/reference/) ·
+[Tools](https://libtmux.org/en/ruby/latest/mcp/tools/) ·
+[Guides](https://libtmux.org/en/ruby/latest/mcp/guides/) ·
+[RubyGems](https://rubygems.org/gems/libtmux-mcp)
 
 </div>
 
-Requires tmux 3.3a or newer. The server refuses an older daemon when it
-starts, before serving any tool, and prints the reason and the remedy on
-stderr. If the daemon changes while the server runs, a tool call returns an
-`unsupported` result with `delivery: not_sent` and a fixed line that names the
-floor and says to upgrade tmux and restart the server.
+Part of [libtmux for Ruby](https://github.com/libtmux/libtmux-ruby#readme).
+Built on [libtmux](https://github.com/libtmux/libtmux-ruby/tree/master/gems/libtmux)
+and [libtmux-async](https://github.com/libtmux/libtmux-ruby/tree/master/gems/libtmux-async).
+
+An MCP client starts `libtmux-mcp` and talks to it over stdin and stdout. The
+official MCP SDK handles the protocol, and bounded Async tasks handle
+transport.
+
+**Contents** — [Quick start](#quick-start) ·
+[Connect a client](#connect-a-client) ·
+[Choose the server](#choose-which-tmux-server-it-serves) ·
+[The tools](#the-tools) · [Read](#read-the-layout-and-the-screen) ·
+[Create](#create-type-and-close) · [Run](#run-a-script-in-a-pane) ·
+[Embed](#embed-it-in-ruby) · [Leaves out](#what-it-leaves-out) ·
+[Support](#support-and-status) · [Documentation](#documentation)
 
-Install the alpha and its `libtmux-mcp` executable:
+## Quick start
+
+Install the alpha and its `libtmux-mcp` executable. It needs Ruby 3.3 or newer
+and tmux 3.3a or newer:
 
 ```console
 $ gem install libtmux-mcp --pre
 ```
 
-## Start the server
+The server borrows a tmux server that is already running. Start one on a
+socket of its own:
+
+```console
+$ tmux -L agent new-session -d -s work
+```
+
+Add the server to Claude Code. Until you enable more tools, it serves
+[`tmux_capabilities`][tool-tmux_capabilities] and
+[`tmux_snapshot`][tool-tmux_snapshot]:
+
+```console
+$ claude mcp add tmux -- libtmux-mcp --socket-name agent --endpoint dev
+```
+
+Run by hand, `libtmux-mcp` waits for input until EOF. `libtmux-mcp --help`
+lists every option.
+
+## Connect a client
+
+### `claude mcp add`: Claude Code
+
+The command in the quick start registers the server with Claude Code. Start the
+tmux server first, as above.
+
+### `codex mcp add`: Codex CLI
+
+Codex CLI takes the same command after `--`:
+
+```console
+$ codex mcp add tmux -- libtmux-mcp --socket-name agent --endpoint dev
+```
+
+### `mcpServers`: clients that read JSON
+
+A client that reads a JSON configuration, such as Claude Desktop's
+`claude_desktop_config.json`, takes the same command as an `mcpServers` entry:
+
+<!-- example: mcp_client/config -->
+```json
+{
+  "mcpServers": {
+    "tmux": {
+      "command": "libtmux-mcp",
+      "args": ["--socket-name", "agent", "--endpoint", "dev"]
+    }
+  }
+}
+```
+<!-- /example -->
+
+If the client does not start servers with your shell's `PATH`, set `command` to
+the absolute path that `command -v libtmux-mcp` prints.
+
+## Choose which tmux server it serves
+
+### `--socket` and `--socket-name`: pick the daemon
 
 Set `TMUX_SOCKET` to an existing tmux socket. This command borrows that daemon
-and serves MCP on stdin/stdout:
+and serves MCP on stdin and stdout:
 
 ```console
 $ libtmux-mcp \
@@ -40,18 +114,49 @@ $ libtmux-mcp \
     --endpoint local
 ```
 
-Use `--socket-name NAME` instead of `--socket PATH` to select a named socket.
-`--endpoint` sets the public alias used in discovery and resource URIs; it does
-not select the socket. EOF retires owned clients and preserves the daemon.
+Use `--socket-name NAME` instead of `--socket PATH` to select a named socket,
+as the quick start does:
+
+```console
+$ libtmux-mcp \
+    --socket-name agent
+```
+
+- EOF retires the clients the server owns and leaves the daemon running.
+- `--endpoint` sets the public alias in discovery and resource URIs, and
+  defaults to `local`.
+
+## The tools
+
+Each tool name links to its page on libtmux.org, with the arguments, limits and
+result schema. Repeat `--enable-tool` for each additional tool.
 
 | Tools | Default | Purpose |
 | --- | --- | --- |
-| `tmux_capabilities`, `tmux_snapshot` | Enabled | Discover capabilities and query captured metadata |
-| `tmux_capture`, `tmux_wait` | Disabled | Capture a screen or wait for text/process exit |
-| `tmux_create`, `tmux_send`, `tmux_close` | Disabled | Create entities, send text/keys and tear down exact targets |
-| `tmux_run` | Disabled | Run a script in an explicitly enrolled zsh shell |
+| [`tmux_capabilities`](https://libtmux.org/en/ruby/latest/mcp/tools/tmux_capabilities/), [`tmux_snapshot`](https://libtmux.org/en/ruby/latest/mcp/tools/tmux_snapshot/) | Enabled | Discover capabilities and query captured metadata |
+| [`tmux_capture`](https://libtmux.org/en/ruby/latest/mcp/tools/tmux_capture/), [`tmux_wait`](https://libtmux.org/en/ruby/latest/mcp/tools/tmux_wait/) | Disabled | Capture a screen or wait for text/process exit |
+| [`tmux_create`](https://libtmux.org/en/ruby/latest/mcp/tools/tmux_create/), [`tmux_send`](https://libtmux.org/en/ruby/latest/mcp/tools/tmux_send/), [`tmux_close`](https://libtmux.org/en/ruby/latest/mcp/tools/tmux_close/) | Disabled | Create entities, send text/keys and tear down exact targets |
+| [`tmux_run`](https://libtmux.org/en/ruby/latest/mcp/tools/tmux_run/) | Disabled | Run a script in an explicitly enrolled zsh shell |
+
+- Disabled tools are absent from discovery and denied on direct application
+  calls.
+- An unknown tool name is refused when the server starts.
+
+The [complete protocol recipe](../../examples/mcp_protocol.rb) exercises
+discovery, snapshots, default denial, enabled mutations, cancellation and EOF
+cleanup through actual pipes, including the installed executable.
+
+## Read the layout and the screen
+
+### [`tmux_snapshot`][tool-tmux_snapshot]: the layout, in pages
+
+- Pages come from one immutable capture, and a cursor continues that capture.
+- An expired, evicted or foreign cursor returns an error. The server never
+  substitutes a fresh listing.
 
-Repeat `--enable-tool` for each additional tool. For screen capture and waits:
+### [`tmux_capture`][tool-tmux_capture]: a pane's screen
+
+Enable the screen tools together:
 
 ```console
 $ libtmux-mcp \
@@ -60,100 +165,223 @@ $ libtmux-mcp \
     --enable-tool tmux_wait
 ```
 
-Disabled tools are absent from discovery and denied on direct application calls.
-The [complete protocol recipe](../../examples/mcp_protocol.rb) exercises
-discovery, snapshots, default denial, enabled mutations, cancellation and EOF
-cleanup through actual pipes, including the installed executable.
+- It reads a bounded screen and keeps its line endings. Bytes that are not
+  valid UTF-8 come back base64-encoded.
+- With tracking, a call returns a cursor, and later calls return a splice
+  against that exact captured state. A cursor from another server generation
+  or from a respawned pane is refused.
+- It refuses a pane whose effective `after-capture-pane` hook is not empty,
+  including inherited entries.
+- On tmux 3.3a to 3.4 the hook is checked before the capture command runs, so
+  keep hook configuration stable while observing.
+
+### [`tmux_wait`][tool-tmux_wait]: wait for text or exit
+
+- It waits for screen text, or for the pane process to exit. Screen text
+  comes from control events on tmux 3.7 and newer, and from polling the pane
+  every 50 ms on older daemons, which take no control client. Process exit
+  uses process descriptors.
+- Wrapped rows are joined, so text that the pane width split across rows
+  still matches.
+- If the pane, or the tmux server holding it, ends before the text appears,
+  the call fails with `pane_died`, `delivery: observed` and the last rows it
+  read in the error's `capture`. If only the control stream ends while the
+  pane lives, such as after the client detaches, the failure is
+  `observation_lost`.
+- A cancelled or expired wait closes its observers and never signals the pane
+  program.
+- Process tracking needs a native identity backend: Linux peer pidfds with
+  matching PID namespaces, or Darwin kqueue. Without one, the call is refused.
+
+### [Resource templates][mcp-resources]: the same data as URIs
+
+[`tmux_metadata`][resource-tmux_metadata],
+[`tmux_metadata_page`][resource-tmux_metadata_page] and
+[`tmux_screen`][resource-tmux_screen] expose metadata pages and pane screens
+under endpoint and generation URIs, with the same policy and limits as their
+tools.
+
+- The server does not advertise resource subscriptions.
+- [Snapshots, cursors and references][mcp-snapshots-topic] has the full
+  contract.
+
+## Create, type and close
+
+### [`tmux_create`][tool-tmux_create]: new sessions, windows and panes
+
+Enable the three tools together:
+
+```console
+$ libtmux-mcp \
+    --socket-name agent \
+    --enable-tool tmux_create \
+    --enable-tool tmux_send \
+    --enable-tool tmux_close
+```
+
+- It takes argument arrays as `argv`.
+- Results carry the references tmux returned.
+
+### [`tmux_send`][tool-tmux_send]: literal text or named keys
+
+- Text and keys are separate variants.
+- It reports `dispatch_only`: the input was dispatched, and the command has not
+  necessarily finished.
+- After a cancellation, the effect stays unknown and is not reported as none.
+
+### [`tmux_close`][tool-tmux_close]: an exact target
+
+- It takes an exact session, window or pane reference, and never selects by
+  name.
+
+## Run a script in a pane
+
+### [`tmux_run`][tool-tmux_run]: authored commands in an enrolled zsh
+
+[`tmux_run`][tool-tmux_run] runs a POSIX script in a pane's interactive zsh
+5.9. It needs both the tool and an enrolled pane.
+
+List the pane IDs of the server:
+
+```console
+$ tmux -L agent list-panes -a -F '#{pane_id}'
+```
+
+```text
+%0
+```
+
+Enable the tool and write a setup file for one exact pane:
+
+```console
+$ libtmux-mcp \
+    --socket-name agent \
+    --enable-tool tmux_run \
+    --enroll-pane %0=enroll.zsh
+```
+
+Then, in that pane's zsh, run `source enroll.zsh`. A relative path resolves
+from the directory where the server starts.
+
+- `--enroll-pane` requires `--enable-tool tmux_run`, and each pane and each
+  file may appear once.
+- The server writes a private file (mode `0600`) and never types into the
+  terminal. It refuses an existing file or a symlink.
+- Setup files expire. `--enrollment-timeout SECONDS` sets the lifetime, at most
+  300.
+- EOF retires pending enrollment and removes only the files the server wrote.
+- A call takes an exact pane `target`, a POSIX `script`, and optional
+  `stdout_limit` and `stderr_limit` byte counts.
+- The script runs with the shell's working directory and exported environment.
+- Stdout and stderr come back separately, as UTF-8 or base64.
+- A nonzero exit or a signal is a completion result. Output over its limit is
+  an error with completion unobserved, and never a truncated success.
+- Cancelling a run does not prove that its child processes stopped.
+
+## Embed it in Ruby
+
+Require `libtmux/mcp`. Imports start no tmux process, scheduler or MCP server.
+The [execution guide](../../docs/modes.md) covers result and ownership
+boundaries.
+
+### [`LibTmux::MCP::Application`][mcp-application]: serve from your own program
+
+[`Application`][mcp-application] borrows an application-owned
+[`LibTmux::Async::Server`][async-server]. Its
+[`sdk_server`][mcp-application-sdk_server] supplies the SDK server that
+[`StdioTransport`][mcp-stdiotransport] consumes:
+
+<!-- example: mcp_protocol/main -->
+```ruby
+application = LibTmux::MCP::Application.new(server: scope.server, endpoint_name: "example")
+sdk = application.sdk_server
+input, client_input = IO.pipe
+client_output, output = IO.pipe
+transport = LibTmux::MCP::StdioTransport.new(server: sdk, parent: parent, input: input, output: output)
+runner = parent.async { transport.run }
+```
+<!-- /example -->
+
+The [complete program](../../examples/mcp_protocol.rb) runs this excerpt inside
+an Async task with an open [`LibTmux::Async`][async] scope. It sends real
+JSON-RPC messages through the pipes, checks the replies, and prints
+`PASS mcp_protocol`.
+
+### [`Application#invite_shell`][mcp-application-invite_shell]: enroll a shell from Ruby
+
+Call `invite_shell` with a pane reference, `timeout:` and `expires_in:`, then
+pass the invitation to [`accept_shell`][mcp-application-accept_shell].
+
+- The invitation's `shell_arguments` make up the setup command to source in
+  that pane's zsh.
+- `timeout:` bounds acquisition, and `expires_in:` sets the enrollment
+  lifetime.
+- The application owns invitations and accepted connections until
+  [`close`][mcp-application-close]. Direct enrollment calls enforce tool
+  policy.
+
+## What it leaves out
+
+- **Tools you have not enabled.** Disabled tools are absent from discovery,
+  and a direct application call is denied. See [The tools](#the-tools).
+- **Resource subscriptions.** The server does not advertise them. See the
+  [resource templates][mcp-resources].
+- **Typing into your terminal.** The server writes a private setup file and
+  never types into a pane's terminal to enroll it. See
+  [`tmux_run`][tool-tmux_run].
+- **A guaranteed stop.** Cancelling a run does not prove that its child
+  processes stopped. See [`tmux_run`][tool-tmux_run].
+
+## Support and status
+
+**Alpha.** APIs may change between releases.
+
+- **Ruby 3.3 or newer.** The gem depends on `libtmux` and `libtmux-async` at
+  the same version, the `mcp` SDK 1.5, `digest` and `optparse`.
+- **tmux 3.3a or newer.** The server refuses an older daemon when it starts,
+  before it serves any tool, and prints the reason and the remedy on stderr.
+- **A daemon that changes while it runs.** A tool call returns an
+  `unsupported` result with `delivery: not_sent`. The result names the floor
+  and says to upgrade tmux and restart the server.
+- **The `screen_contains` wait.** It uses control events on tmux 3.7 and
+  newer and polls the pane screen on older daemons, which take no control
+  client.
+- **Linux, including WSL, and macOS.** The core
+  [compatibility workflow][compat] runs Ruby 3.3, 3.4 and 4.0 with tmux 3.3a
+  through 3.8 on Ubuntu 24.04. macOS is supported on a best-effort basis, and
+  CI coverage for it is highly limited.
+
+## Documentation
+
+| | |
+| --- | --- |
+| [Reference](https://libtmux.org/en/ruby/latest/mcp/reference/) | The embedding types and methods |
+| [Tools](https://libtmux.org/en/ruby/latest/mcp/tools/) | One page per tool, with arguments, limits and result schema |
+| [Guides][mcp-guides] | Connect a client to a private tmux server and select its tools |
+| [Resources][mcp-resources] | Metadata pages and pane screens as URIs |
+| [Public behavior][behavior-mcp-application] | The application, transport and command |
 
-## Snapshots, capture and waits
-
-Snapshot pages retain one immutable capture and query. Cursor expiry or eviction
-returns an error; it never substitutes a new live listing. Defaults retain up to
-16 captures and 8 MiB for 30 seconds, with a five-second acquisition deadline and
-one-MiB structured response limit. A cursor pages captured metadata; it does not
-claim that an old pane process still exists. Schema validation supplements the
-core decoder's stricter byte, depth, node and duplicate-key rules.
-
-Opt into `tmux_capture` for a bounded screen snapshot. Results retain line
-endings, encode invalid UTF-8 as base64, and distinguish truncated screen
-content from unknown history continuity. Tracking produces a retained cursor;
-subsequent calls return a splice against that exact captured state. A screen
-delta does not establish that every intervening output byte was observed.
-
-Capture refuses nonempty effective `after-capture-pane` hooks, including
-inherited sparse entries. On tmux 3.3a–3.4, callers must keep capture-hook
-configuration stable throughout observation: those versions require a separate
-hook preflight. tmux 3.5+ checks the hook in the capture command queue. Both paths
-retain an explicit session/pane context and refuse its removal instead of
-switching to another session's hooks. Process tracking retains its native
-identity checks on every version that supports it.
-
-`tmux_wait` observes screen text or process exit through events. Canceling it
-retires its observation resources without signaling the pane program. Strong
-process tracking requires tmux 3.3a or later and a native identity backend:
-Linux peer pidfds with matching process namespaces, or Darwin kqueue process
-observation. Acquisition verifies the live daemon and pane before retaining
-a cursor; unavailable evidence produces an explicit refusal. The
-[compatibility workflow](https://github.com/libtmux/libtmux-ruby/actions/workflows/compatibility.yml)
-records each exact platform/version result: positive identity cases on
-supported releases, and refusal jobs for tmux 3.0a, 3.1c, 3.2a and unpatched
-3.3.
-
-Resource templates expose metadata pages and pane screens under encoded
-endpoint/generation URIs. They enforce the same policy and response limits as
-their tools. Metadata pages preserve capture identity; screen resources
-include interval, truncation and history-continuity metadata. Resource
-subscriptions are not advertised.
-
-## Create, send and close
-
-Add `--enable-tool tmux_create`, `--enable-tool tmux_send` or
-`--enable-tool tmux_close` to authorize those tools. Creation accepts argument
-arrays; sending text and sending named keys are separate variants. Mutation
-results contain delivery evidence and positively returned references.
-`dispatch_only` input results do not claim program completion, and unknown
-effects remain unknown after cancellation.
-
-## Run authored commands
-
-`tmux_run` requires separate policy and shell enrollment. Add
-`--enable-tool tmux_run --enroll-pane %ID=FILE` for each exact pane, then
-explicitly source the generated file in that pane's interactive zsh 5.9.
-The CLI creates a private setup file and never types into the terminal.
-It refuses existing files and symlinks. Invitations expire after 60 seconds;
-`--enrollment-timeout` accepts at most 300 seconds. At most eight panes may be
-enrolled. EOF retires pending enrollment and removes only files the CLI owns.
-
-The tool accepts an exact pane target, a POSIX `script`, and separate
-`stdout_limit`/`stderr_limit` byte counts. Scripts may contain at most 65,536
-bytes. Each output defaults to 65,536 bytes and is capped at 262,144; the
-application reserves its worst-case serialized response before authorization.
-The helper inherits the enrolled shell's cwd and exported environment, uses
-closed stdin, and reports separate UTF-8 or base64 outputs. Nonzero exit and
-signal termination are completion results. Output overflow is an error with
-completion unobserved, not silently truncated success. Shell variables,
-functions, options and cwd changes do not persist in the interactive parent.
-
-An idle, empty primary ZLE editor receives the request through a private socket.
-A guarded tmux queue operation authorizes one script digest for one retained
-server, pane process and enrollment generation. Execution may follow that
-authorization; a later respawn does not redirect the prepared helper to its
-replacement. Error responses retain known authorization and native completion
-receipts. Cancellation does not prove that arbitrary descendants stopped.
-The Linux and macOS compatibility jobs exercise enrollment and the installed
-helper dependency closure; consult their results for the revision being used.
-
-## Embed in Ruby
-
-Require `libtmux/mcp`; imports start no tmux process, scheduler or MCP server.
-`Application` borrows an application-owned `LibTmux::Async::Server`. Its
-`sdk_server` supplies the SDK server consumed by `StdioTransport`. Both objects
-stay on that application's reactor thread. See the
-[execution guide](../../docs/modes.md) for result and ownership boundaries.
-
-For shell enrollment, call `Application#invite_shell(reference, timeout:,
-expires_in:)` and pass the returned invitation to `accept_shell`. The invitation
-exposes an immutable `shell_arguments` array for an explicitly sourced setup
-command and a monotonic `expires_at`. Its acquisition deadline is separate from
-its enrollment lifetime. The application owns invitations and accepted
-connections until `close`; direct enrollment calls enforce tool policy.
+[async]: https://libtmux.org/en/ruby/latest/reference/libtmux-async/
+[async-server]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-server/
+[behavior-mcp-application]: ../../docs/reference/behavior.md#mcp-application
+[compat]: https://github.com/libtmux/libtmux-ruby/actions/workflows/compatibility.yml
+[mcp-application]: https://libtmux.org/en/ruby/latest/mcp/reference/libtmux-mcp-application/
+[mcp-application-accept_shell]: https://libtmux.org/en/ruby/latest/mcp/reference/libtmux-mcp-application-accept_shell/
+[mcp-application-close]: https://libtmux.org/en/ruby/latest/mcp/reference/libtmux-mcp-application-close/
+[mcp-application-invite_shell]: https://libtmux.org/en/ruby/latest/mcp/reference/libtmux-mcp-application-invite_shell/
+[mcp-application-sdk_server]: https://libtmux.org/en/ruby/latest/mcp/reference/libtmux-mcp-application-sdk_server/
+[mcp-guides]: https://libtmux.org/en/ruby/latest/mcp/guides/
+[mcp-resources]: https://libtmux.org/en/ruby/latest/mcp/resources/
+[mcp-snapshots-topic]: https://libtmux.org/en/ruby/latest/mcp/topics/snapshots-and-references/
+[mcp-stdiotransport]: https://libtmux.org/en/ruby/latest/mcp/reference/libtmux-mcp-stdiotransport/
+[resource-tmux_metadata]: https://libtmux.org/en/ruby/latest/mcp/resources/templates/tmux_metadata/
+[resource-tmux_metadata_page]: https://libtmux.org/en/ruby/latest/mcp/resources/templates/tmux_metadata_page/
+[resource-tmux_screen]: https://libtmux.org/en/ruby/latest/mcp/resources/templates/tmux_screen/
+[tool-tmux_capabilities]: https://libtmux.org/en/ruby/latest/mcp/tools/tmux_capabilities/
+[tool-tmux_capture]: https://libtmux.org/en/ruby/latest/mcp/tools/tmux_capture/
+[tool-tmux_close]: https://libtmux.org/en/ruby/latest/mcp/tools/tmux_close/
+[tool-tmux_create]: https://libtmux.org/en/ruby/latest/mcp/tools/tmux_create/
+[tool-tmux_run]: https://libtmux.org/en/ruby/latest/mcp/tools/tmux_run/
+[tool-tmux_send]: https://libtmux.org/en/ruby/latest/mcp/tools/tmux_send/
+[tool-tmux_snapshot]: https://libtmux.org/en/ruby/latest/mcp/tools/tmux_snapshot/
+[tool-tmux_wait]: https://libtmux.org/en/ruby/latest/mcp/tools/tmux_wait/

data/lib/libtmux/mcp/application.rb

@@ -162,7 +162,7 @@ module LibTmux
           IncompleteSnapshotError => "incomplete_snapshot", Cancelled => "cancelled",
           DeadlineExceeded => "deadline", CapacityError => "capacity", TargetNotFoundError => "stale_target",
           CommandError => "command_failed", UnsupportedFeatureError => "unsupported", ClosedError => "closed",
-          Observation::LostObservation => "observation_lost"}.fetch(error.class, "transport_error")
+          Observation::LostObservation => "observation_lost", Observation::PaneDied => "pane_died"}.fetch(error.class, "transport_error")
         delivery = error.respond_to?(:delivery) ? (mutation ? mutation.delivery(error) : error.delivery) : :possibly_sent
         delivery = :observed if result
         effects = if name == "tmux_run"
@@ -177,10 +177,13 @@ module LibTmux
         end
         message = if delivery == :not_sent && LibTmux::Internal::TmuxVersion.refusal?(error)
           LibTmux::Internal::TmuxVersion.hint
+        elsif error.is_a?(Observation::PaneDied)
+          "The pane, or its tmux server, ended before the awaited text appeared."
         else
           "The operation could not establish its requested result."
         end
-        failure_response(code, message, delivery.to_s, effects: effects)
+        failure_response(code, message, delivery.to_s, effects: effects,
+          capture: (error.capture if error.is_a?(Observation::PaneDied)))
       end
 
       def inspect
@@ -509,9 +512,10 @@ module LibTmux
         value.freeze
       end
 
-      def failure_response(code, message, delivery = "not_sent", effects: nil)
+      def failure_response(code, message, delivery = "not_sent", effects: nil, capture: nil)
         details = {"code" => code, "message" => message, "delivery" => delivery}
         details["effects"] = effects if effects
+        details["capture"] = capture if capture
         ::MCP::Tool::Response.new([{type: "text", text: message}], error: true,
           structured_content: {"ok" => false, "error" => details})
       end

data/lib/libtmux/mcp/catalog.rb

@@ -186,7 +186,8 @@ module LibTmux
         {"type" => "object", "oneOf" => [object({"ok" => {"const" => true}, "data" => payload}),
           object({"ok" => {"const" => false}, "error" => object({"code" => text,
             "message" => text, "delivery" => {"enum" => %w[not_sent possibly_sent observed]},
-            "effects" => name == "tmux_run" ? run_effects : effects}, %w[code message delivery])})]}
+            "effects" => name == "tmux_run" ? run_effects : effects}.merge(name == "tmux_wait" ? {"capture" => capture_output} : {}),
+            %w[code message delivery])})]}
       end
 
       def self.authorization
@@ -239,7 +240,7 @@ module LibTmux
         elsif name == "tmux_capture"
           "Read exact-pane screen/history rows preserving LF. Defaults: 200 lines, 65536 bytes, zero history lines, track=false. Limits: 1000 lines/history, 262144 bytes. UTF-8 or base64; truncation is separate from unknown history continuity. Tracked process cursors require tmux>=3.3a and a native process identity backend: Linux peer pidfds with matching PID namespaces, or Darwin kqueue process observation. Continuation returns an exact state row splice, not a live-output journal. Refuses capture after-hooks."
         elsif name == "tmux_wait"
-          "Wait for observed literal screen text or the initial pane process exit. Deadline in seconds is capped by the application limit. Uses control events/process descriptors; no polling. Requires tmux>=3.3a and Linux peer pidfds with matching PID namespaces or Darwin kqueue process observation. Reports observed evidence, never remote termination caused by cancellation or an inferred process exit status."
+          "Wait for observed literal screen text or the initial pane process exit. Deadline in seconds is capped by the application limit. Pane exit is observed through process descriptors. The screen_contains condition joins wrapped rows, uses control events on tmux>=3.7 and polls the pane screen on older daemons, which take no control client. A pane or tmux server that ends first fails with pane_died and the last rows read in error.capture; a lost control stream fails with observation_lost. Requires tmux>=3.3a and Linux peer pidfds with matching PID namespaces or Darwin kqueue process observation. Reports observed evidence, never remote termination caused by cancellation or an inferred process exit status."
         elsif name == "tmux_send"
           "Send literal UTF-8 text or named keys to one exact pane. Opt-in mutation; 64 KiB total text bytes, at most 256 keys. Reports tmux client completion and input dispatch only; never shell completion."
         elsif name == "tmux_create"

data/lib/libtmux/mcp/observation.rb

@@ -5,8 +5,19 @@ require "libtmux/mcp/process_identity"
 module LibTmux
   module MCP
     class Observation
+      POLL_SECONDS = 0.05
       StaleCursor = Class.new(LibTmux::Error)
       LostObservation = Class.new(LibTmux::Error)
+      # The pane, or the tmux server holding it, ended before the awaited text
+      # appeared. +capture+ is the last screen state read before it ended.
+      class PaneDied < LibTmux::Error
+        attr_reader :capture
+
+        def initialize(message, capture:, **details)
+          super(message, **details)
+          @capture = capture
+        end
+      end
       module CleanupDetails
         attr_reader :mcp_cleanup_errors
       end
@@ -54,7 +65,8 @@ module LibTmux
         {"screen" => "bounded_rows", "history_continuity" => "unknown",
           "process_cursor" => conditional ? "conditional" : "unsupported",
           "requirements" => ["tmux >= #{LibTmux::Internal::TmuxVersion::MINIMUM}", *(native || ["supported 64-bit Linux or Darwin process identity backend"]),
-            "live pane process", "empty effective capture hook", "stable capture-hook configuration on tmux < 3.5"],
+            "live pane process", "empty effective capture hook", "stable capture-hook configuration on tmux < 3.5",
+            "screen_contains waits use control events from tmux #{LibTmux::Internal::TmuxVersion::CONTROL_MINIMUM} and poll the screen before it"],
           "wait_conditions" => %w[screen_contains process_exit]}
       end
 
@@ -162,7 +174,7 @@ module LibTmux
       end
 
       def wait
-        identity = control = subscription = nil
+        identity = control = subscription = latest = nil
         tasks = []
         failure = response = nil
         begin
@@ -171,8 +183,10 @@ module LibTmux
             condition = @arguments.fetch("condition")
             snapshot, pane = resolve(reference)
             require_tracking(snapshot)
+            # Daemons below 3.7 take no control client, so a screen wait polls the pane.
+            polling = condition.fetch("type") == "screen_contains" && !@server.supports_control?
             identity = acquire_identity(snapshot, pane)
-            if condition.fetch("type") == "screen_contains"
+            if condition.fetch("type") == "screen_contains" && !polling
               link = snapshot.window_links.find { |item| item.window_id == pane.window_id }
               raise TargetNotFoundError.new("pane has no observable session", phase: :admission) unless link
 
@@ -184,18 +198,38 @@ module LibTmux
               control.exchange(line, **@budget.options)
             end
             limits = defaults
-            rows, encoding, truncated = read_rows(snapshot, pane, limits, identity)
+            # A pane or server that ends mid-read ends the wait as PaneDied, with
+            # the last rows read, unless the read failed for another reason.
+            pane_died = lambda do
+              rows, encoding, truncated = latest
+              PaneDied.new("observed pane process exited", phase: :observation, delivery: :observed,
+                capture: state(reference, rows, encoding, truncated, limits, identity, SecureRandom.hex(16)))
+            end
+            read = lambda do
+              begin
+                latest = read_rows(snapshot, pane, limits, identity, true)
+              rescue TargetNotFoundError, CommandError, TransportError
+                raise if latest.nil?
+
+                raise unless ended?(identity)
+
+                raise pane_died.call
+              end
+            end
+            rows, encoding, truncated = read.call
             if condition.fetch("type") == "screen_contains" && contains?(rows, encoding, condition.fetch("text"))
               next {"target" => reference, "condition" => "screen_contains",
                 "capture" => state(reference, rows, encoding, truncated, limits, identity, SecureRandom.hex(16))}
             end
             changed = ::Async::Notification.new
             pending = nil
+            weights = {read: 0, stream_ended: 1, exited: 2, server_exited: 2}
+            weigh = ->(value) { value.is_a?(Exception) ? 3 : weights.fetch(value) }
             wake = lambda do |value|
-              pending = value if pending.nil? || (!pending.is_a?(Exception) && (value.is_a?(Exception) || value == :exited))
+              pending = value if pending.nil? || weigh.call(value) > weigh.call(pending)
               changed.signal
             end
-            [[identity.io, :exited], [identity.peer, LostObservation.new("tmux process ended", phase: :observation)]].each do |io, event|
+            [[identity.io, :exited], [identity.peer, :server_exited]].each do |io, event|
               task = ::Async::Task.new(::Async::Task.current) do
                 Fiber.scheduler.io_wait(io, IO::READABLE)
                 wake.call(event)
@@ -207,10 +241,30 @@ module LibTmux
               tasks << task
               task.run
             end
-            if subscription
+            if polling
               task = ::Async::Task.new(::Async::Task.current) do
                 loop do
-                  event = subscription.next(timeout: @budget.options.fetch(:timeout))
+                  ::Async::Task.current.sleep(POLL_SECONDS)
+                  wake.call(:read)
+                end
+              rescue ::Async::Cancel
+                nil
+              rescue StandardError => error
+                wake.call(error)
+              end
+              tasks << task
+              task.run
+            end
+            if subscription
+              task = ::Async::Task.new(::Async::Task.current) do
+                # Kernel#loop would swallow the StopIteration that ends the stream.
+                while true
+                  begin
+                    event = subscription.next(timeout: @budget.options.fetch(:timeout))
+                  rescue StopIteration
+                    wake.call(:stream_ended)
+                    break
+                  end
                   if event.kind == :gap
                     wake.call(LostObservation.new("screen observation has a gap", phase: :observation, delivery: :observed))
                     break
@@ -219,8 +273,6 @@ module LibTmux
                 end
               rescue ::Async::Cancel
                 nil
-              rescue StopIteration
-                wake.call(LostObservation.new("screen observation ended", phase: :observation, delivery: :observed))
               rescue StandardError => error
                 wake.call(error)
               end
@@ -233,15 +285,32 @@ module LibTmux
               event, pending = pending, nil
               raise event if event.is_a?(Exception)
 
-              if event == :exited
-                identity.peer_alive!
-                unless condition.fetch("type") == "process_exit"
-                  raise TargetNotFoundError.new("observed pane process exited", phase: :observation, delivery: :observed)
+              if event == :stream_ended
+                # A stopped second client keeps a killed server alive after the
+                # stream ends, so ask the daemon instead of waiting for its process.
+                raise pane_died.call if ended?(identity)
+
+                raise LostObservation.new("screen observation ended", phase: :observation, delivery: :observed)
+              end
+              if event == :exited || event == :server_exited
+                if condition.fetch("type") == "process_exit"
+                  begin
+                    identity.peer_alive!
+                  rescue TargetNotFoundError
+                    raise LostObservation.new("tmux process ended", phase: :observation, delivery: :observed), cause: nil
+                  end
+                  break {"target" => reference, "condition" => "process_exit", "process_generation" => identity.generation,
+                    "observed_at" => clock, "exit_status" => "unobserved"}
+                end
+                # The last output may have landed just before the end.
+                rows, encoding, truncated = read.call
+                if contains?(rows, encoding, condition.fetch("text"))
+                  break {"target" => reference, "condition" => "screen_contains",
+                    "capture" => state(reference, rows, encoding, truncated, limits, identity, SecureRandom.hex(16))}
                 end
-                break {"target" => reference, "condition" => "process_exit", "process_generation" => identity.generation,
-                  "observed_at" => clock, "exit_status" => "unobserved"}
+                raise pane_died.call
               end
-              rows, encoding, truncated = read_rows(snapshot, pane, limits, identity)
+              rows, encoding, truncated = read.call
               if contains?(rows, encoding, condition.fetch("text"))
                 break {"target" => reference, "condition" => "screen_contains",
                   "capture" => state(reference, rows, encoding, truncated, limits, identity, SecureRandom.hex(16))}
@@ -271,6 +340,40 @@ module LibTmux
 
       private
 
+      # What a daemon that is killed, or shutting down behind a stopped client,
+      # tells a client.
+      SERVER_GONE = /\A(?:no server running|server exited unexpectedly|error connecting to .*\((?:No such file or directory|Connection refused)\))/
+
+      # True when the pane process is gone or the daemon says it is gone.
+      # An inconclusive probe, such as a failed spawn, is not an end.
+      def ended?(identity)
+        gone?(identity) || daemon_state == :gone
+      end
+
+      # :alive when the daemon answers an ordinary command, :gone when it
+      # reports that it is gone, and :unknown when the probe itself fails. The
+      # identity read is a run-shell -C probe, which fires no hook.
+      def daemon_state
+        argv, marker = LibTmux::Internal::TmuxVersion.identity_argv(%w[pid])
+        result = @server.run(argv, **@budget.options)
+        begin
+          LibTmux::Internal::TmuxVersion.parse_identity(result, marker, 1)
+          :alive
+        rescue ProtocolError
+          SERVER_GONE.match?(result.stderr.b.force_encoding(Encoding::UTF_8)) ? :gone : :unknown
+        end
+      rescue Cancelled, DeadlineExceeded
+        raise
+      rescue LibTmux::Error, SystemCallError, IOError
+        :unknown
+      end
+
+      def gone?(identity)
+        identity.exited?
+      rescue TargetNotFoundError
+        true
+      end
+
       def acquire_identity(snapshot, pane)
         # tmux 3.8 reports no PID for a dead pane; there is no process to bind.
         raise TargetNotFoundError.new("pane process has exited", phase: :admission) if pane.pid.nil?
@@ -306,7 +409,9 @@ module LibTmux
           phase: :admission)
       end
 
-      def read_rows(snapshot, pane, limits, identity)
+      # +joined+ joins wrapped rows into the lines the program wrote, so a wait
+      # finds text that the pane width split across rows.
+      def read_rows(snapshot, pane, limits, identity, joined = false)
         identity&.ensure_live!
         names = spellings
         link = snapshot.window_links.find { |item| item.window_id == pane.window_id }
@@ -315,7 +420,7 @@ module LibTmux
         target = "#{link.session_id}:.#{pane.id}"
         guard = "\#{&&:\#{==:\#{session_id},#{link.session_id}},\#{==:\#{pane_id},#{pane.id}}}"
         guard = "\#{&&:#{guard},\#{&&:\#{==:\#{pane_pid},#{identity.pid}},\#{&&:\#{==:\#{pane_dead_status},},\#{==:\#{pane_dead_signal},}}}}" if identity
-        body = @server.__send__(:tmux_command, [names.fetch("capture-pane"), "-p", "-t", target,
+        body = @server.__send__(:tmux_command, [names.fetch("capture-pane"), "-p", *(joined ? ["-J"] : []), "-t", target,
           "-S", (-limits.fetch("history_lines")).to_s, "-E", "-"])
         # The selected false branch fails parsing, independently of screen bytes.
         failure = @server.__send__(:tmux_command, [names.fetch("capture-pane"), "-t"])

data/lib/libtmux/mcp/process_identity.rb

@@ -193,9 +193,9 @@ module LibTmux
         end
         # Registration may find a recycled PID. A fresh pinned-route reply must
         # name that same daemon while its retained process observer stays live.
-        name = server.__send__(:builtin_spellings, "display-message", budget: budget).fetch("display-message")
-        result = server.__send__(:execute_typed, [name, "-p", '#{pid}'], **budget.options)
-        unless result.stdout == "#{server_pid}\n".b && !readable?(peer)
+        argv, marker = LibTmux::Internal::TmuxVersion.identity_argv(%w[pid])
+        reported = LibTmux::Internal::TmuxVersion.parse_identity(server.run(argv, **budget.options), marker, 1).first
+        unless reported == server_pid.to_s && !readable?(peer)
           raise UnsupportedFeatureError.new("bound response does not establish the tmux process", phase: :admission)
         end
         budget.options

data/lib/libtmux/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module LibTmux
   module MCP
-    VERSION = "0.1.0.alpha.2"
+    VERSION = "0.1.0.alpha.3"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libtmux-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.2
+  version: 0.1.0.alpha.3
 platform: ruby
 authors:
 - libtmux contributors
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0.alpha.2
+        version: 0.1.0.alpha.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0.alpha.2
+        version: 0.1.0.alpha.3
 - !ruby/object:Gem::Dependency
   name: libtmux-async
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0.alpha.2
+        version: 0.1.0.alpha.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0.alpha.2
+        version: 0.1.0.alpha.3
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
@@ -118,7 +118,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/libtmux/libtmux-ruby
-  documentation_uri: https://libtmux.org/en/ruby/v0.1.0.alpha.2/mcp/
+  documentation_uri: https://libtmux.org/en/ruby/v0.1.0.alpha.3/mcp/
 rdoc_options: []
 require_paths:
 - lib