[tony]

The worked example on each port's MCP page drew only what the calls returned. On the Go page, after split_window (step 3) the preview said "Panes, sizes not read yet: %0 sh, %1", and the split was drawn only at the next list_panes, whose caption read "list_panes read the panes; tmux itself is unchanged." Go's split_window answers {"paneId":"%1"}, with no layout and no size, so the preview deleted the old layout and had nothing to draw. Every port has the same shape.

This records what tmux looked like after every call and draws that. It is on main after #247 and includes the Julia recording from #248, so it supersedes #248.

Recorder

gen-mcp-transcript.mjs reads the recorder's own sandbox tmux before the first call and after each one, and stores it as tmuxBefore and as tmux on the step. readTmuxState takes the sessions, the windows with the window_layout tmux reports, and the panes with command, rectangle and active flag, in one tmux invocation on the sandbox's socket. It refuses a socket outside the sandbox and a sandbox with two servers, reads a missing server or a server with no session as an empty tmux, and fails on any other read error, so a step whose state could not be read is never written.

The state is read after the pause that stands for an agent reading the result, and again until two reads agree and every pane runs the expected shell. A pane is named tmux until its shell replaces it and a window is renamed for the program a pane runs, so a single read straight after a call is not stable. A window tmux still names itself must also carry the name of its active pane's program. A state that never settles is the existing unsettled-pane error, which records again (see Review follow-ups).

recordingStateProblems holds the checks the recorder and the page share. Each part refers to the others (window to session, pane to window), one window and one pane are active, a window's layout names exactly its panes at the rectangles they report, a call names only ids the state before it had, a result returns only ids the state after it has, and a tool that only reads leaves tmux as it was. The id checks are what catch a state read a step late or from another server. The recorder runs them, --check requires them of the stored file, and recordingHolds applies them on the page.

The state goes through the same sanitize as every other part of a step, and the finished transcript through hostLeaks (see Review follow-ups). Writing this found one real miss: Swift writes its project path with escaped slashes inside JSON text, so the committed Swift recording named a random sandbox directory (/tmp/t239-swift-…) that neither the rewrite nor the scan saw, and it changed on every run. Both handle the escaped form.

Preview

replayFrames draws frame i from the state recorded after call i and frame 0 from the state before the first call. The caption reads "tmux after <tool>", and "unchanged, the call only reads" after a tool that only reads. The provenance line says the layout and panes come from the recording's own tmux server after each call and a pane's output from the results of the calls. Each call's Result panel is unchanged, and a pane still shows what the calls typed into it and read from it. A recording that stores no state keeps drawing from its results; the tests keep that path covered.

A recording whose state is missing at the start or at any step, or does not follow from its calls, makes recordingHolds false, and the page shows requests only.

The Go frame at split_window is now two panes with the geometry tmux gave them:

Frame 3 of the Go preview

{
  "done": 3,
  "tool": "split_window",
  "recorded": true,
  "sessions": [
    {
      "id": "$0",
      "name": "checks",
      "windows": [
        {
          "id": "@0",
          "index": 0,
          "name": "sh",
          "active": true,
          "layout": "{\"V\":2,\"L\":{\"t\":\"h\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"c\":[{\"t\":\"p\",\"w\":40,\"h\":24,\"x\":0,\"y\":0,\"a\":true,\"i\":0,\"I\":\"%0\"},{\"t\":\"p\",\"w\":39,\"h\":24,\"x\":41,\"y\":0,\"i\":1,\"I\":\"%1\"}]}}",
          "panes": [
            {
              "id": "%0",
              "command": "sh",
              "left": 0,
              "top": 0,
              "width": 40,
              "height": 24,
              "active": true
            },
            {
              "id": "%1",
              "command": "sh",
              "left": 41,
              "top": 0,
              "width": 39,
              "height": 24,
              "active": false
            }
          ]
        }
      ]
    }
  ]
}

Julia and the #248 review items

• The stand-in note now says that a real call sends the generation list_panes returned and that 3f9a1c itself is refused as stale_target. The claim is measured: after the example the recorder sends the stand-in as written, requires the server to refuse it, and stores which tool listed the generation and the refusal code. A recording without them is refused.
• The recorder's stand-in mapping moved into standInCalls so it can be imported and tested: only the calls that carry the stand-in are rewritten, nothing is sent with the stand-in when no result listed a value, and a fake server shows the stand-in alone is refused as stale_target.
• The linked-pane replay test is retitled to the first link and now links one pane into two places, requiring it to be drawn in the first only.
• The four conflicts in gen-mcp-transcript.mjs are resolved as specified: both import lists, withListed inside Pin Ruby, TypeScript and Rust at their masters, re-record their MCP sessions, list the APIs Ruby's send-keys uses #247's settle-and-retry loop with listed computed after it, and julia: ['cat'] in PANE_COMMANDS.

Snapshots and recordings

Seven protocol snapshots were behind their ports' master heads, so they were refreshed first (with their mcp-tools.json rows); ts, rs and julia were already at master. Every port was then recorded at its current master head, on tmux 3.8a, under heavy.sh two at a time, from clean clones that are deleted afterwards:

Port	Recorded at
py	libtmux-mcp 800aebd26
ts	073b9d7de
rs	6942c1e60
go	f59af95c2
java	fe25ff5ed
csharp	libtmux-dotnet 486830df1
cxx	166ce2c74
swift	3fd9dfe3d
ruby	0bf78344f (re-recorded when Ruby's pin moved; see below)
julia	c19e4a164

For each, contracts equal the snapshot, the steps equal EXAMPLES, and recordingHolds passes. Each was recorded twice from the same checkout and compared except for volatile values; all ten match. The only differences are command durations, process ids and creation times, a server's generation and capture ids, and Swift's opaque refs. None is in the tmux state, which was identical in both recordings of every port. --check passes for Go, and refuses a Go recording with one step's state removed.

cxx was built with the repository's gcc preset, which this host's clang cannot link, and swift needs a libxml2.so.2 link on LD_LIBRARY_PATH; both were already the recorder's own workarounds. Free disk stayed above 240 GiB throughout.

Verification

• The whole site suite, outer files included, after the review follow-ups: 8415 tests passed, 352 skipped and 6 failed. The six failures are port-landing and core-capabilities tests that read .github/workflows files from the local libtmux-ts and libtmux-rs checkouts at their pinned revisions, which those checkouts do not hold. They fail the same way on the head of Pin Ruby, TypeScript and Rust at their masters, re-record their MCP sessions, list the APIs Ruby's send-keys uses #247.
• astro check: 0 errors and 0 warnings. oxlint reports nothing new in the touched files.
• The new tests read a real tmux on a private socket when tmux is installed, and skip otherwise.
• Not run: a site build, the publication audit, the full pnpm test outer loop, and the preview in a browser. The preview was checked through the component tests.
• mcp-exports.test.ts expected every Go markdown twin to cite the pinned revision. A tool page links its source at the pinned revision and the listings cite the extracted one, which differ once a snapshot is at master, so the test now expects each.

Review follow-ups

An independent review asked for changes. Each is fixed in its own commit after the first push, and each has a test that fails without it.

The leak guard now reads escaped and encoded paths

The recorder scanned JSON.stringify(transcript) for \/tmp\/x, but stringifying that text writes \\/tmp\\/x, so the guard could never match a path a server escapes. Its test called leaks on a bare string and proved nothing about the recorder's call. Planting an escaped sandbox root, a triple-escaped one, a percent-encoded sandbox path, a percent-encoded checkout and {"dir":"/tmp","name":"t239-…"} in a tmux-state window name and running the old call on them found none of the five.

hostLeaks is now the one call the recorder makes. It walks every parsed string of the transcript without contracts, keys included, and reads each through layers of JSON escaping and percent-encoding in any order, and reads JSON held in a string. The serialized text is scanned as a second layer with the same readings. The sandbox's unique directory name is found wherever it appears, which finds the sandbox in a split path, and two sibling strings (a directory and a name in one object, or neighbouring entries of a list) are read as one path. A path split over three values, or in another encoding such as base64, is not found; the code says so.

The tests run the recorder's own steps (the rewrite, then hostLeaks) on a full transcript and plant each form into the window name of states of every committed recording. Removing any one decoder or heuristic fails a test, and a set of clean forms (the fixed project path with escaped and encoded spellings, the generation token, \nd) passes.

Ruby's window name

tmux new-session -d -s docs /bin/cat leaves the window named tmux until tmux renames it, and it renames only after the pane prints something. In 30 starts of that command, 21 left the name tmux at the first read, and the old settle check, which read only pane commands, would have recorded it in all 21. Both sides are fixed: the borrowed session is started with -n cat, and settledState refuses a window that tmux still names itself whose name differs from its active pane's program. With the new settle check alone, all 21 are refused; with -n cat, none of 30 starts is. Ruby was re-recorded three times. The tmux state is identical in all three and in the committed recording, and the files differ only in the server's generation, process ids, start time, capture ids and read times.

A settle timeout records again

settledState throws inside recordCalls, outside the retry's try, so a timeout ended the run although the docs said it records again. The loop is now recordSettled: a timeout while the calls run, or a failed check afterwards, resets the sandbox's servers and records again, bounded by ATTEMPTS, and any other error ends the run at once. A borrowed session is started inside each attempt, so Ruby and Julia retry like the others.

The stand-in refusal must be stale_target

The recorder and recordingHolds accepted any refusal code. Both now require STALE_TARGET, defined once in mcp-examples.ts; a recording that records another code, or none, is not shown.

Smaller fixes

• runTmux kills tmux after 10 s and reports that it did not answer, and such a read fails rather than counting as an empty tmux. A test runs a fake tmux that never answers.
• The sandbox guard resolves each socket with realpath and requires the real path inside the sandbox, runs tmux on the real path, and stopSandboxServers stops only servers of the sandbox. Tests use a link to a real socket outside the sandbox and a tmux directory that is itself a link, which the old startsWith check followed.
• Two planted changes survived the tests and now fail them: dropping the "every pane runs the expected shell" condition from settledState (two equal reads of a tmux pane must be refused), and removing capture_pane from READ_ONLY_TOOLS. The unchanged-frame and caption tests no longer take their list of reading tools from the code they test, and a test pins the set.
• The provenance line no longer says the whole preview is tmux's own state: layout and panes come from the recording's tmux server, and a pane's output from the results of the calls.

Recordings and verification

In the review round, only Ruby's stored data changed, so only Ruby was re-recorded. Go and Julia were run with --check from clean clones at their recorded revisions through the new recorder and passed, including Julia's stale_target control and borrowed session. The new guard finds nothing in any of the ten committed recordings, in the parsed values or the serialized text, scanned for the home directory, the temporary directory, the sandbox prefix, every port checkout and the machine and user names.

The whole site suite ran with 8415 passed, 352 skipped and 6 failed: the same six port-landing and core-capabilities failures as before, which read workflow files the local libtmux-ts and libtmux-rs checkouts do not hold at their pinned revisions. astro check reports 0 errors and 0 warnings. A site build, the publication audit and the browser checks were not run.

Left for later

Left for later (low severity):

• --check compares the stored tmux state only with itself (scripts/gen-mcp-transcript.mjs), never with the state it just recorded.
• The preview draws only the first session (windowOf uses sessions[0]); no recording has a second one, and nothing forbids it.
• The host-name token check misses a name followed by . (tonybox.local) and uppercase variants (pre-existing).

Ruby pin and the three held programs

libtmux/libtmux-ruby#93, merged as 0bf78344f, made the three Ruby programs #247 held back publishable: examples/api/workspace_apply.rb writes the workspace file it loads, and version 2 of examples/manifest.json lets a program list the tmux capabilities it needs, with the docs export giving each API page its release in examples.tmux_releases (3.7 for control.rb and async_control.rb, 3.3a for the rest).

• ruby-examples.ts states that release in each page's intro ("tmux 3.7 or newer") and shows the three programs. An export without tmux_releases, as every earlier Ruby release produces, keeps 3.3a and keeps the three programs held, so versioned pages of v0.1.0 and v0.1.1 do not change.
• Ruby's pin moves from 20744401e to 0bf78344f with everything it regenerates: the model (55 pages carry a program, up from 44), the example cache, source guides, product copy, workspace showcase, manifest packages, tmux usage, and the MCP snapshot, tool rows and recording. 0bf78344f declares the gems at 0.1.1, so the pages install 0.1.1; the 0.1.2 release commits after it change only versions and changelogs.
• The receipt adds the eleven pages the hold removed, each program run as displayed: workspace_apply.rb on tmux 3.3a and 3.7c; control.rb and async_control.rb on 3.7 and 3.7c, and refused on 3.3a.
• The api-model suite passes (1332 tests); twelve of its new tests fail without the change, and the default-holds test fails when extractRuby holds nothing by default. ruby-api-examples.test.ts passes (60) and fails against the previous model and receipt.