// 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 1643 — 764 single-format cases (*.fmt) and 879 multi-command shell scenarios (*.sh) — covering formats, arithmetic, conditionals, string ops, options, buffers, windows, panes, layouts, copy mode and capture-pane. Every gated case passes byte-for-byte; 12 are quarantined (they run and are diffed, but a divergence that only appears on the Linux CI runner keeps them out of the gate), and two proven divergences live in parity/known_gaps/ with their reproductions rather than being papered over.

Behaviour ztmux does not implement yet was tracked in a mirror-image suite, parity/known_gaps/, holding cases expected to diverge from the reference — that divergence being the proof a feature was unported. That directory is now empty. The last six gaps closed in order: the OSC 9;4 progress bar, copy-mode line numbers, the prompt cursor, pane scrollbars, tree-mode preview, and switch-mode — the last of which first required porting prompt.c as a reusable struct prompt, since ztmux still carried the pre-split design with the prompt spread across struct client.

>_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. ztmux verbs counts 114 of them today, alongside the 92 ported tmux commands and their 78 aliases. Most 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 ratatui UI layer is the exception and lives in the server's draw path (see below). 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:

// DISCOVERY & CONSOLE — no server required for verbs:

// INTERACTIVE & ZELLIJ-STYLE — ratatui surfaces, modal keys, persistence:

>_THE RATATUI UI LAYER

tmux paints its interactive surfaces — menus, clock mode, display-panes — by the server writing cells into a screen or straight to the tty, not by a program that owns a terminal. src/extensions/ratatui_ui.rs bridges that: it lays a ratatui widget tree into a Buffer, then translates every Cell into a tmux grid_cell emitted through screen_write_cell (overlay and mode screens) or tty_cell (direct-to-tty overlays). That bridge is what lets ztmux add surfaces the C tmux has no equivalent for without leaving its draw model: a which-key hint bar on the prefix, a floating command palette with inline completion, ratatui clock and display-panes, edit-scrollback-in-$EDITOR, and multi-pane selective sync whose state is shown on the pane border (synced red, selected orange, trigger-armed cyan) where pane output can never overwrite it.

A separate opt-in, @ztmux-zellij-mode on, insets every pane by a one-cell ring and draws a rounded frame with the pane's name — the zellij model, where a program cannot draw on the frame. prefix C-f toggles a floating pane: a real pane on a floating layout cell above the tiled layout, so it moves and resizes like any other pane (move-pane -P centre, resize-pane -x50% -y50%) and is fully draggable with mouse on. Panes underneath are clipped around it, and a client redraw composites every visible cell — content, borders, pane status lines, floats — into a cached scene of spans before writing, so a float never costs a second pass over the terminal. Rendered screens are compared against the vendored tmux through a real VT emulator, not just model state. @ztmux-ratatui off disables the whole renderer for a classic plain-tmux server, which leaves the default draw path and the byte-for-byte parity suite untouched.

Everything here is configured with ordinary tmux user options, so it all sets from the config file. Unless noted these are global (set -g) and read live, taking effect on the next redraw:

>_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,502 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 ignore $TMUX for resolution entirely — without -L/-S it always resolves its own ztmux-<uid>/default socket — while still exporting $TMUX to its panes, pointed at that socket, so ecosystem tools that only test whether the variable is set keep working. The two multiplexers now run side by side, or nested.
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 and event-loop wrappers, Rust glue) are frozen in an allowlist, tests/data/fake_fn_allowlist.txt — 289 entries today: 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

Several layers stack:

• Parity — byte-for-byte against the vendored tmux, 1643 cases (1631 gated), blocking in CI. Two of those surfaces only became testable late: capture-pane reads a pane's backing grid, so drawn output and the command prompt were invisible to it. Attaching a second server inside a pane of the first puts the drawn scene in the outer pane's grid, and makes its keystrokes the inner client's terminal input — which is how the scrollbar, tree-mode and prompt cases reach them.
• Unit tests — in-tree, for pure logic: red-black tree invariants under randomized insert/delete, UTF-8 round-trips, layout arithmetic, and the extensions' rendering through ratatui's headless backend.
• Crash gate — tests/server_survives_bad_targets.rs drives the real binary on a private socket and asserts the server survives commands whose target resolves to nothing.
• Anti-drift gates — the three build gates above (ported_fn_names_match_c, no_c_alloc_for_rust_types, no_key_code_truncation).
• Upstream regress scripts — regress/ carries 32 of tmux's own regression scripts, run against the ztmux binary via make -C regress. Its Makefile currently ignores failures, so it is a diagnostic harness rather than a gate, and it is not wired into CI.
• Fuzzing, two kinds — an in-process cargo-fuzz (libFuzzer) target over colour_find_rgb for panics and assertion failures, and differential fuzzing (fuzz/diff/) that treats real tmux as the oracle: the same generated input drives both binaries and their output is diffed byte-for-byte. Its input mode generates random streams of printables, C0 controls, CSI/SGR/OSC/DCS sequences and wide/combining UTF-8 and compares capture-pane -p; its copy mode runs random copy-mode motion and selection commands and compares the resulting paste buffer. A divergence is minimised and saved under fuzz/diff/repros/ (gitignored) for replay with ./diff_fuzz.py repro.

>_"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 Rust toolchain and a terminfo database (ncurses) — no C libraries, since the event loop is Rust (src/extensions/event_loop, replacing tmux's libevent). Then the binary ztmux speaks the same commands as tmux — on its own socket namespace (ztmux-<uid>/ under $TMUX_TMPDIR or /tmp, never adopted from $TMUX) so it never collides with a running tmux — plus the extension subcommands: