// 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 1080 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 parity suite and unit tests root-caused to a single line — each now locked by a regression test (the full log is in BUGS.md):

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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 GATE

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.

>_TESTING

Three 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); and the anti-drift gate that fails the build on invented functions.

>_"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: