Skip to content

chore(zmx): integrate upstream client and terminal - #32

Open
serabi wants to merge 42 commits into
mainfrom
t3/deps/zmx-upstream-8b00fef2c5
Open

serabi wants to merge 42 commits into
mainfrom
t3/deps/zmx-upstream-8b00fef2c5

Conversation

@serabi

@serabi serabi commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Why

Bring the awesoMux zmx fork up to upstream 28fba865 while retaining the session authority, status, and replay behavior used by awesoMux. This adopts upstream's client/terminal separation and public API without changing the existing AMX wire layouts.

Upstream source: neurosnap/zmx@28fba86

What's Included

  • Integrate the upstream client/terminal structure, Zig/Ghostty updates, API examples, and documentation.
  • Preserve AMX authority/watch handling, status/cwd/exit information, and receiver-aware terminal replay.
  • Queue file writes as one complete command and reject queue overflow without terminating the session or discarding accepted writes.
  • Resolve prefixed session names once, consume charset escape sequences in plain output, and flush cwd replies from idle sessions.
  • Extend the existing session and authority regression suites for the repaired behavior.

UI / UX

Not applicable.

Notes

Models: GPT-6.1 Sol. Substantial AI assistance with integration, repairs, validation, and independent review.

Validation at 67f622953a4f53d73dc0e31f53c4e949ddb040ef on Midnight Pro with Zig 0.17.1: formatting, unit tests, build, replay tests, 96/96 attach regression cases, 6/6 workflow tests, 81/81 Bats cases, leadership checks, 23/23 leadership regression scenarios, 24/24 creator scenarios, reconnect, API examples, and the client-only build all passed. Commands ran sequentially under the shared host lease and job limits. A fresh independent review of this head found no actionable defects and independently passed two raw idle-cwd queries and CLI cwd.

The original libxev failure came from a malformed cached archive. The task-local source was rehashed against the existing pinned package hash; no dependency hash was relaxed or replaced.

Merge risk: high because this integrates 37 upstream commits across the terminal and client code. Linux, mixed old/new daemon-client pairs, and downstream awesoMux application behavior were not tested. The attach harness still observes existing boundary reflow, narrower receiver, and existing-prompt gaps outside its passing regression assertions. Recovery: revert this integration on the fork and rebuild for future sessions. Reverting source does not restore sessions that have already ended.


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.


Summary

Integrates upstream's client and terminal work into the fork while preserving the AMX wire contract. The client logic moves out of main.zig into a reusable src/client.zig (exported as the zmx Zig package via src/lib.zig), and all libghostty-vt serialization moves from src/util.zig into src/terminal.zig. Alongside the move, the branch picks up Zig 0.17, upstream ghostty, a translated C header (src/c.h), a static docs site, and several functional fixes.

What changed

  • Zig package / libzmx: src/lib.zig + src/client.zig expose attach, run, list, kill, tail, send, print, write, history, labels, and printEnv. main.zig now calls these instead of owning the logic, removing a large amount of duplicated client code. -Ddaemon=false builds the package without the daemon and Ghostty VT; create() is a compile error in that configuration.
  • Terminal core extraction: src/terminal.zig holds state serialization, history formatting, mouse/keyboard detection, and all the VT round-trip tests. util.zig re-exports them for compatibility.
  • History scoping: new Capture IPC tag (34) with an 8-byte payload (format, reserved, rows) backs zmx history --screen and --scrollback N, so pollers can request only the rows they will use instead of formatting full history. Unsupported (255) is returned for unknown tags.
  • Write path: zmx write now emits one shell command with the file content base64-encoded, instead of chunking through multiple PTY writes. This fixes transfers larger than the PTY input buffer and keeps path quoting (including embedded single quotes) intact.
  • Signals: the client installs handlers for HUP/TERM/INT, restores the terminal, and re-raises the signal so exit status is preserved. drainSignalPipe now reports which signal arrived.
  • Smaller fixes: mkdirAll no longer loops on a dangling symlink; log reopen uses lseek(SEEK_END) instead of length+seek; the daemon defers HUP handling while unread input remains so zmx send/run -d payloads are not dropped; zmx run treats -d after the command as a command argument; attach now restores the snapshot even for sessions started detached or via run.
  • Build/tooling: Zig 0.17, ghostty bump, translate_c dependency, src/c.h translated for the target rather than the host, -Ddaemon option, examples/ built via zig build examples, docs generated from docs/posts with pdocs.

Security

  • Session names are still validated as filenames (no /, NUL, . or ..) before they reach socket creation or stale-socket cleanup. resolveSessionOrEnv validates the already-resolved name for ./env cases.
  • write escaping is now single-pass and correct for quotes in the destination path.
  • Status file handling still checks owner, regular-file type, and 0600 before writing.
  • Signal handling restores terminal attributes and the RIS/OSC color sequence on every exit path, including abnormal termination.

Performance

  • stripAnsi is now a small hand-rolled scanner instead of driving the Ghostty parser, removing a parser dependency from the client-only path and avoiding per-byte dispatch for plain output.
  • zmx write performs one ordered queue operation rather than N chunked operations, avoiding interleaving with shell mode changes.
  • zmx history --scrollback formats only the requested rows.
  • Daemon/media import is lazyDependency, so -Ddaemon=false builds skip Ghostty entirely.

Review findings to address before merge

  • src/loop.zig:1797 (high) — handleWrite queues with a limit of PTY_WRITE_BUF_MAX + commands.items.len, so the check can never reject its own payload and backpressure is effectively disabled.
  • src/socket.zig:51 (high) — env / . session names skip the getSeshName prefix path, so ZMX_SESSION_PREFIX is not applied and validation differs from other entry points.
  • src/ipc.zig:326 (medium) — an oversized hdr.len clears the socket buffer and returns null, discarding valid framed data and desynchronizing subsequent reads; it should be treated as a fatal framing error instead.

Notes

  • The AMX header remains 8 bytes (tag, len, zeroed reserved bytes) with tags 14–33 unchanged; Capture uses 34 and Unsupported uses 255, per LEADERSHIP.md. Daemons and clients must be the same version.
  • CHANGELOG.md and README.md are updated for the v1.0.0/v1.0.1 releases and the docs site move.

eslgastal and others added 30 commits September 30, 2026 21:12
When creating directory paths where an intermediate component is a
broken symlink, mkdir returns EEXIST (PathAlreadyExists), but resolving
child paths fails with ENOENT. Traversal ping-pongs between parent and
child infinitely at 100% CPU. Validate that existing path components
are actual directories before descending.
Every attached client's terminal answers the queries an app broadcasts
(kitty keyboard flags, DA1/DA2, DECRPM, ...). isUserInput counted any
CSI ending in `u` or `~` as a keystroke, so the reply `CSI ? 5 u` from a
passive viewer made it leader and resized the session to its window;
the actual user's client then rendered output laid out for the wrong
width until they pressed a key.

Replies carry a private marker (`?`, `>`, `=`, `<`) that keyboard
encodings never use. Skip those sequences and keep scanning, so a real
keystroke in the same read still counts.
…false

When a client connects, daemonLoop may broadcast raw PTY output into
client.write_buf between accept() and handleInit().  Clearing write_buf avoids
duplicating the initial output of forwarding already answered DA queries.  This
means we can always send terminal snapshot now.
stripAnsi fed each byte to the bare VT parser, which expects decoded
input. It dropped every non-ASCII byte, and a UTF-8 continuation byte in
the C1 range (Ý is C3 9D, 0x9D is the 8-bit OSC introducer) started a
sequence that swallowed the text after it. Pass bytes >= 0x80 through
when the parser is not inside a sequence.
zmx run dropped every argument that starts with -d, wherever it appeared,
and ran the session detached. So `zmx run dev cut -d: -f1 file` ran
`cut -f1 file` in the background. Stop looking for -d once the command
has started, like attach does for its flags.
Harden the unix domain socket IPC wire ABI in prep for libzmx embedding.

BREAKING CHANGE: existing daemons must be killed before upgrading next version of zmx

Link: neurosnap/zmx#127
Link: neurosnap/zmx#271
Link: neurosnap/zmx#122
A client that writes and exits (e.g. `zmx send`, `zmx run -d`) can be
polled with IN and HUP together while part of its message is still in
the socket. Each pass reads at most 4 KiB, so the HUP check in the same
pass closed the client and the rest of the message was discarded: no
log line, and the sender had already exited 0.

Leave such a client for the next pass instead of closing it; the reads
carry on until EOF, which closes it through the existing n == 0 path.
ERR/NVAL still close at once.
We added the ability to import zmx as a zig package.  The zmx module is really
a thin wrapper around our ipc wire protocol for communicating with the daemon.

We also made embedding the daemon (and by proxy, libghostty) optional so consumers
could import zmx as only the ipc protocol. The daemon is embedded by default,
with the build option `-Ddaemon=false` to disable it.

See `./examples/` folder for examples of how to use zmx as a package.
neurosnap and others added 12 commits November 6, 2026 11:37
Terminate `string sub` argument parsing to avoid -ENVVAR being
interpreted as a option. Without this, "set -e" fails.
The "testing" link returns an HTTP 404 response, but "community" works.

Signed-off-by: Noelle Leigh <noelle@noelle.dev>
Integrate upstream client and terminal modules and Zig 0.17 support.
Preserve the AMX wire contract, typed authority, status and replay
behavior. Adapt file writes to the ordered queue as one shell command
to prevent truncation between decoder invocations.
@github-actions github-actions Bot added the size:XXL 1,000+ effective changed lines. label Nov 11, 2026
@github-actions

Copy link
Copy Markdown

Large pull request

This PR has 7146 effective changed lines and is labeled size:XXL.
The label is informational and does not block merging. Please consider splitting the
change where practical so each part is easier to review. See CONTRIBUTING.md for
the project's small-PR guidance.

@kody-ai

kody-ai Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration
Interacting with Kody
  • Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

  • Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

  • Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

Access your configuration settings here.

​

@github-actions

Copy link
Copy Markdown

External contributor checklist

Thanks for contributing. A maintainer will handle the trusted checks and final merge.

  • A maintainer has reviewed the change.
  • The PR description follows the template.
  • Visible changes include screenshots or a clear not-applicable explanation.
  • A maintainer confirmed no untrusted fork code was run with repository secrets.

Comment thread src/ipc.zig
Comment on lines +326 to +330
if (hdr.len > MAX_PAYLOAD_LEN) {
self.buf.clearRetainingCapacity();
self.head = 0;
return null;
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Bug medium

Oversized IPC frame resets socket buffer and desynchronizes framing

The peer keeps sending the body, so resetting the buffer makes next() parse payload bytes as headers. Return a hard error that closes the connection, or drain exactly len bytes.

Prompt for LLM
File src/ipc.zig, lines 326-330:

Oversized IPC frame resets socket buffer and desynchronizes framing

When `hdr.len > MAX_PAYLOAD_LEN` the handler clears the read buffer and returns `null`, but the peer has already declared that payload length and will continue sending the body; the next `read` appends the body at offset 0 and `next()` reinterprets those bytes as a new header, desynchronizing the framing so attacker-controlled payload bytes are parsed as IPC tags. Return a hard error that closes the connection (or drain exactly `len` bytes) rather than silently discarding and resetting the buffer.

Suggested code:

if (hdr.len > MAX_PAYLOAD_LEN) {
    self.head += total;
    return null;
}

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Comment thread src/loop.zig
}
try commands.appendSlice(gpa, "'\r");

try self.queueOperationLimit(gpa, .{ .data = commands.items }, PTY_WRITE_BUF_MAX + commands.items.len);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Bug high

handleWrite passes a self-defeating limit, disabling backpressure

The limit can never trip, so a large zmx write queues without bound and stalls all PTY input. Pass PTY_WRITE_BUF_MAX so oversized writes return error.InputQueueFull.

Prompt for LLM
File src/loop.zig, line 1797:

handleWrite passes a self-defeating limit, disabling backpressure

`queueOperationLimit` is called with `PTY_WRITE_BUF_MAX + commands.items.len`, so the `queued_bytes + value.data.len > limit` guard can never be satisfied and the input-queue backpressure is effectively disabled for `zmx write`. A large file transfer therefore queues an unbounded command that stalls all further PTY input with no rejection path; pass `PTY_WRITE_BUF_MAX` (or a fixed cap) so oversized writes return `error.InputQueueFull` instead.

Suggested code:

try self.queueOperationLimit(gpa, .{ .data = commands.items }, PTY_WRITE_BUF_MAX);

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Comment thread src/socket.zig
Comment on lines +51 to +54
if (session_name == null or std.mem.eql(u8, session_name.?, ".")) {
try validateSessionName(raw);
return alloc.dupe(u8, raw);
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Security high

Env and '.' session names bypass getSeshName prefix validation

Bypassing getSeshName lets a crafted prefix put the socket outside socket_dir. Route both branches through getSeshName, or validate the fully-qualified name, instead of duplicating raw.

Prompt for LLM
File src/socket.zig, lines 51-54:

Env and '.' session names bypass getSeshName prefix validation

resolveSessionOrEnv returns the raw session name without `getSeshName`, skipping `ZMX_SESSION_PREFIX` and its path-separator/NUL validation whenever `session_name` is null or ".". An attacker-controlled (or attacker-influenced) environment such as `ZMX_SESSION_PREFIX=../..` combined with `ZMX_SESSION=x` or `zmx attach .` now yields a session name that callers pass straight into `getSocketPath(socket_dir, name)`, so socket creation, probing and `cleanupStaleSocket` operate outside the socket directory. Route both branches through `getSeshName` (or validate the fully-qualified name) instead of duplicating `raw`.

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:XXL 1,000+ effective changed lines.

Projects

None yet

Development

Successfully merging this pull request may close these issues.