// ZTMUX — ENGINEERING REPORT

>_PARITY VS tmux

ztmux is a port of tmux, so "correct" means tmux itself. The parity suite runs the same inputs through the vendored tmux (reference) and ztmux (port) and compares byte-for-byte — the same shape as the sibling ports (zshrs vs zsh, strykelang vs perl). The suite has grown from a handful of format cases to 1107 covering formats, arithmetic, conditionals, string ops, options, buffers, windows, panes, and layouts — and every one now passes byte-for-byte, with zero known divergences.

>_REPOSITORY LAYOUT

Original code is kept apart from the port so the fidelity gate only judges what is meant to mirror C:

>_EXTENSIONS — BEYOND tmux

Because ztmux owns the whole stack, it adds capabilities upstream tmux does not have. They are plain clients — they re-invoke the ztmux binary and read its own machine-readable output, so they need no linkage to the server internals. The foundation is structured output plus the two interactive TUIs:

On top of that sits a family of one-shot client subcommands, each resolving the running server over the list-* -o json query layer. The inspection verbs are pipeable tables that also emit -o json / --json; the action verbs are dry-run by default and only mutate when passed -f / --force.

// INSPECTION — read-only, pipeable:

// ACTIONS — dry-run by default, apply with -f:

>_HOW THE PORT IS BUILT

Two references, both vendored under vendor/ as plain, read-only, SHA-pinned copies so the clone is self-contained:

Every ported function carries a back-link to its C origin as a doc comment, e.g. /// C vendor/tmux/grid.c:320: grid_create(). The port report tracks per-function C→Rust coverage: 2,127 of tmux's 2,696 functions ported so far.

>_BUGS THE HARNESS CAUGHT

Verifying against C at every step turns "looks right" into "is right." A sample of faults the harnesses root-caused to a single line — the parity suite and unit tests, plus a sweep that drives every command against a private socket and, for the paths that only run with a client attached (modes, redraw, status), against a real client on a pty. Aborts are keyed on crash reports rather than on "is the server still up," since a dying client can legitimately take the server with it. Each fault below is now locked by a regression test or a build gate (the full log, including what is still open, is in BUGS.md):

1. A mouse event could kill a window — tmux dispatches keys with switch (key) over the full 64-bit key_code. Five ported handlers matched key as u8 against byte literals, discarding the top bits. KEYC_* codes run sequentially from KEYC_BASE (0x10e000), so 18 real keys alias an ASCII command letter: KEYC_MOUSEUP11_STATUS_DEFAULT (0x10e078) truncates to 'x' — the Kill prompt — and KEYC_DOUBLECLICK11_PANE to 'X', Kill Tagged. Each dispatch now gates on key < 0x80, so only a bare ASCII byte reaches those arms; a build gate fails on any match key as u<N>.
2. "Not found" returned an arbitrary element — C's TAILQ_FOREACH leaves the loop variable NULL when it runs to completion, and callers branch on that NULL; a Rust for loop that assigns each element retains the last one visited. Five ports had it. cmd_find_client returned a session-less client, so lock-client -t nosuch dereferenced c->session and killed the server — and every CMD_CLIENT_TFLAG command shared it, so detach-client -t <typo> silently acted on the wrong client instead of erroring. window_pane_set_mode reused a wrong-mode entry (type confusion on its data); session_group_synchronize_to synced a lone session from itself and wiped its own window list.
3. Zeroing a struct that holds a Rust type — Vec, String, CString and Box all need a non-null data pointer, but xcalloc hands back all-zero bytes. window_client_modedata holds item_list: Vec, so the first drain(..) in window_client_build dereferenced null and choose-client killed the server. Nothing complains at the allocation; it detonates later, far from the cause. Now built with Box::new and reclaimed with Box::from_raw so Drop frees them — and a build gate fails when any struct with such a field is xcalloc'd, because converting a char * field to an owned CString turns every C-style allocation of its struct into UB.
4. Destroying a pane rebuilt its mode against the dead window — window_pane_destroy called window_pane_reset_mode_all, the interactive teardown that resizes the next mode, redraws and notifies. C calls window_pane_free_modes, which the port was missing entirely, so tearing down a pane rebuilt the customize-mode tree against a window that was already gone.
5. Freeing a pointer Rust never allocated — session_group_find mirrored C's throwaway stack struct used as the RB_FIND key. In Rust (*sg).name = … is a place assignment, so it drops the previous value — uninitialized stack garbage that happened to look like an owned string. ztmux new-session -t ggg called free() on a junk pointer and aborted the server. Fixed by searching with rb_find_by: same descent, no fabricated key node.
6. Mouse-driven TUIs froze mid-pane — a stale - 1 in the SGR-mouse encoder (input_keys.rs) dropped the sequence's M/m terminator after xsnprintf was corrected to exclude the NUL. ztmux wrote \033[<35;69;44 with no terminator; crossterm blocked in read() waiting for an end byte that never came, so rich ratatui/crossterm panes locked up on any click or focus change while keyboard input still worked.
7. ztmux hijacked real tmux's socket — it resolved its default socket from $TMUX, so launched inside a tmux pane it connected to tmux's server and spoke protocol 8 at it (server exited unexpectedly). Fixed to resolve only from $ZTMUX and advertise both $TMUX and $ZTMUX to panes, so the two multiplexers run side by side.
8. Server crash on bind-key h then l — the red-black tree's delete rebalance (rb_remove_color, compat/tree.rs) rotated around the wrong node. Rebinding a key that already had a default removed the old node first, corrupting the key-bindings tree and segfaulting the server on startup.
9. Powerline glyphs rendered as \202\202\202 — utf8_strvis's inner loop never advanced the source pointer (the C is while (++src < end …)), so each multibyte UTF-8 character was re-read and mangled into raw bytes plus octal escapes.
10. even-* layouts off by one — layout_spread_cell dumped the leftover column on the last pane instead of handing it to the leading cells; an 80-col two-pane split came out 39|40 instead of tmux's 40|39.
11. Pane spawn hung on macOS — the ported closefrom looped close() up to the server-raised RLIMIT_NOFILE; replaced with the libproc PROC_PIDLISTFDS path tmux actually compiles on macOS, so the forked child reaches execvp.

>_ANTI-DRIFT GATES

A port can be faked by inventing Rust-only "helper" functions that don't exist in tmux, inflating apparent completeness. tests/ported_fn_names_match_c.rs fails the build when a free fn is added under src/ported/ whose name has no counterpart in vendor/tmux. src/extensions/ is exempt by design — it is original code, not a mirror of C — exactly as #[cfg(test)] blocks are skipped. Pre-existing exceptions (libc/libevent wrappers, Rust glue) are frozen in an allowlist: an audit trail to burn down, not a free pass.

Two more gates grew out of the bugs above, because each was a class rather than a one-off — the kind that the C→Rust ownership migration keeps re-creating:

• tests/no_c_alloc_for_rust_types.rs — fails the build when a struct holding a Vec/String/CString/Box is allocated with xcalloc/zeroed/MaybeUninit. Zeroed bytes give those types a null data pointer, which they are not allowed to hold. This matters most during the migration: the moment a char * field becomes an owned CString, every C-style allocation of its struct silently becomes UB.
• tests/no_key_code_truncation.rs — fails the build on any match key as u<N>, which is what let a mouse event alias the Kill prompt.

Both were verified by mutation: reintroducing the defect makes the gate fail with the offending file:line and the fix.

>_TESTING

Four layers stack: byte-for-byte parity against the vendored tmux; in-tree unit tests for pure logic (red-black tree invariants under randomized insert/delete, UTF-8 round-trips, layout arithmetic, and the extensions' rendering via ratatui's headless backend); a crash gate (tests/server_survives_bad_targets.rs) that drives the real binary on a private socket and asserts the server survives commands whose target resolves to nothing; and the anti-drift gates above.

>_"DONE RIGHT"

1. Start from a working skeleton — a running program to refactor, not a blank page.
2. Shrink the unsafe surface — replace raw-pointer intrusive lists and C-isms with safe Rust where behavior allows.
3. Verify against C at every step — a module isn't "ported" until it matches the C reference (parity suite).
4. Keep it green — cargo build and cargo clippy stay clean as code comes over.

>_BUILD & RUN

Requires a C libevent and a terminfo database (ncurses), matching tmux itself. On macOS the build links Homebrew's libevent automatically (TMUX_RS_DISABLE_HOMEBREW_LIBS=1 to opt out). Then the binary ztmux speaks the same commands as tmux — on its own socket namespace (ztmux-<uid>, from $ZTMUX, never $TMUX) so it never collides with a running tmux — plus the extension subcommands: