termio: add zmx backend for persistent terminal sessions

include/ghostty.h

@@ -460,6 +460,9 @@ typedef struct {
   ghostty_surface_io_mode_e io_mode;
   ghostty_io_write_cb io_write_cb;
   void* io_write_userdata;
+  const char* zmx_session;
+  bool zmx_create;
+  bool zmx_mode;
 } ghostty_surface_config_s;
 
 typedef struct {

src/Surface.zig

@@ -629,40 +629,46 @@ pub fn init(
     // This separate block ({}) is important because our errdefers must
     // be scoped here to be valid.
     {
-        var env = rt_surface.defaultTermioEnv() catch |err| env: {
-            // If an error occurs, we don't want to block surface startup.
-            log.warn("error getting env map for surface err={}", .{err});
-            break :env internal_os.getEnvMap(alloc) catch
-                std.process.EnvMap.init(alloc);
-        };
-        errdefer env.deinit();
-
-        // don't leak GHOSTTY_LOG to any subprocesses
-        env.remove("GHOSTTY_LOG");
+        // Determine the IO backend: zmx > manual > exec
+        // Try zmx first (if configured and binary is available)
+        var zmx_backend: ?termio.Zmx = null;
+        if (config.@"zmx-session") |session| {
+            zmx_backend = termio.Zmx.init(alloc, .{
+                .session_name = session,
+                .create_if_missing = config.@"zmx-create",
+                .working_directory = config.@"working-directory",
+            }) catch |err| switch (err) {
+                error.ZmxNotFound => blk: {
+                    log.warn("zmx binary not found, falling back to exec", .{});
+                    break :blk null;
+                },
+                else => return err,
+            };
+        }
 
-        // Initialize our IO backend
-        if (use_manual_io) {
+        var io_backend: termio.Backend = if (zmx_backend) |zmx|
+            .{ .zmx = zmx }
+        else if (use_manual_io) manual_backend: {
             var io_manual = try termio.Manual.init(alloc, .{
                 .write_cb = manual_write_cb,
                 .write_userdata = manual_write_userdata,
             });
-            errdefer io_manual.deinit();
-
-            var io_mailbox = try termio.Mailbox.initSPSC(alloc);
-            errdefer io_mailbox.deinit(alloc);
-
-            try termio.Termio.init(&self.io, alloc, .{
-                .size = size,
-                .full_config = config,
-                .config = try termio.Termio.DerivedConfig.init(alloc, config),
-                .backend = .{ .manual = io_manual },
-                .mailbox = io_mailbox,
-                .renderer_state = &self.renderer_state,
-                .renderer_wakeup = render_thread.wakeup,
-                .renderer_mailbox = render_thread.mailbox,
-                .surface_mailbox = .{ .surface = self, .app = app_mailbox },
-            });
-        } else {
+            _ = &io_manual;
+            break :manual_backend .{ .manual = io_manual };
+        } else exec_backend: {
+            var env = rt_surface.defaultTermioEnv() catch |err| env: {
+                log.warn("error getting env map for surface err={}", .{err});
+                break :env internal_os.getEnvMap(alloc) catch
+                    std.process.EnvMap.init(alloc);
+            };
+            errdefer env.deinit();
+
+            env.remove("GHOSTTY_LOG");
+
+            // Don't leak parent zmx session into child terminals.
+            // Each terminal gets its own zmx session via the zmx backend config.
+            env.remove("ZMX_SESSION");
+
             var io_exec = try termio.Exec.init(alloc, .{
                 .command = command,
                 .env = env,
@@ -676,24 +682,28 @@ pub fn init(
                 .rt_pre_exec_info = .init(config),
                 .rt_post_fork_info = .init(config),
             });
-            errdefer io_exec.deinit();
-
-            // Initialize our IO mailbox
-            var io_mailbox = try termio.Mailbox.initSPSC(alloc);
-            errdefer io_mailbox.deinit(alloc);
-
-            try termio.Termio.init(&self.io, alloc, .{
-                .size = size,
-                .full_config = config,
-                .config = try termio.Termio.DerivedConfig.init(alloc, config),
-                .backend = .{ .exec = io_exec },
-                .mailbox = io_mailbox,
-                .renderer_state = &self.renderer_state,
-                .renderer_wakeup = render_thread.wakeup,
-                .renderer_mailbox = render_thread.mailbox,
-                .surface_mailbox = .{ .surface = self, .app = app_mailbox },
-            });
-        }
+            _ = &io_exec;
+            break :exec_backend .{ .exec = io_exec };
+        };
+        errdefer io_backend.deinit();
+
+        var io_mailbox = try termio.Mailbox.initSPSC(alloc);
+        errdefer io_mailbox.deinit(alloc);
+
+        var io_config = try termio.Termio.DerivedConfig.init(alloc, config);
+        errdefer io_config.deinit();
+
+        try termio.Termio.init(&self.io, alloc, .{
+            .size = size,
+            .full_config = config,
+            .config = io_config,
+            .backend = io_backend,
+            .mailbox = io_mailbox,
+            .renderer_state = &self.renderer_state,
+            .renderer_wakeup = render_thread.wakeup,
+            .renderer_mailbox = render_thread.mailbox,
+            .surface_mailbox = .{ .surface = self, .app = app_mailbox },
+        });
     }
     // Outside the block, IO has now taken ownership of our temporary state
     // so we can just defer this and not the subcomponents.
@@ -1092,6 +1102,7 @@ pub fn handleMessage(self: *Surface, msg: Message) !void {
         .close => self.close(),
 
         .child_exited => |v| self.childExited(v),
+        .child_disconnected => |v| self.childDisconnected(v),
 
         .desktop_notification => |notification| {
             if (!self.config.desktop_notifications) {
@@ -1311,6 +1322,35 @@ fn childExited(self: *Surface, info: apprt.surface.Message.ChildExited) void {
     self.close();
 }
 
+fn childDisconnected(self: *Surface, info: apprt.surface.Message.ChildExited) void {
+    self.child_exited = true;
+
+    log.warn("persistent backend disconnected unexpectedly", .{});
+
+    if (self.rt_app.performAction(
+        .{ .surface = self },
+        .show_child_exited,
+        info,
+    ) catch |err| gui: {
+        log.err("error trying to show native child disconnected GUI err={}", .{err});
+        break :gui false;
+    }) return;
+
+    switch (self.io.backend) {
+        .zmx => |*zmx| {
+            self.renderer_state.mutex.lock();
+            defer self.renderer_state.mutex.unlock();
+            const t: *terminal.Terminal = self.renderer_state.terminal;
+            zmx.childExitedAbnormally(self.alloc, t, info.exit_code, info.runtime_ms) catch |err| {
+                log.err("error handling zmx backend disconnect err={}", .{err});
+            };
+        },
+        else => self.childExitedAbnormally(info) catch |err| {
+            log.err("error handling backend disconnect err={}", .{err});
+        },
+    }
+}
+
 /// Called when the child process exited abnormally.
 fn childExitedAbnormally(
     self: *Surface,
@@ -1324,6 +1364,7 @@ fn childExitedAbnormally(
     const command = switch (self.io.backend) {
         .exec => |*exec| try std.mem.join(alloc, " ", exec.subprocess.args),
         .manual => "manual backend",
+        .zmx => |*zmx| try std.fmt.allocPrint(alloc, "zmx session: {s}", .{zmx.session_name}),
     };
     const runtime_str = try std.fmt.allocPrint(alloc, "{d} ms", .{info.runtime_ms});
 

src/apprt/embedded.zig

@@ -478,6 +478,18 @@ pub const Surface = struct {
 
         /// Userdata passed to io_write_cb.
         io_write_userdata: ?*anyopaque = null,
+
+        /// zmx session name. When non-null, the surface connects to a zmx
+        /// daemon session instead of spawning a new shell process.
+        zmx_session: ?[*:0]const u8 = null,
+
+        /// Whether to create the zmx session if it doesn't exist.
+        zmx_create: bool = true,
+
+        /// Whether this surface should use zmx mode. When true and
+        /// zmx_session is null, a session name is auto-generated.
+        /// This is how zmx mode propagates across splits/tabs.
+        zmx_mode: bool = false,
     };
 
     pub fn init(self: *Surface, app: *App, opts: Options) !void {
@@ -586,6 +598,29 @@ pub const Surface = struct {
             config.@"wait-after-command" = true;
         }
 
+        // zmx mode: explicit session name takes priority, then zmx_mode flag.
+        // An explicit empty string clears any inherited session before deciding
+        // whether to auto-generate one from zmx_mode.
+        const zmx_session = if (opts.zmx_session) |c_session| blk: {
+            const session = std.mem.sliceTo(c_session, 0);
+            break :blk if (session.len > 0) session else null;
+        } else null;
+        if (opts.zmx_session != null and zmx_session == null) {
+            config.@"zmx-session" = null;
+        }
+
+        if (zmx_session) |session| {
+            config.@"zmx-session" = session;
+            config.@"zmx-create" = opts.zmx_create;
+        } else if (opts.zmx_mode) {
+            // Inherited zmx mode — auto-generate a unique session name
+            const zmx_alloc = config.arenaAlloc();
+            const uuid = std.crypto.random.int(u128);
+            const session = try std.fmt.allocPrint(zmx_alloc, "cmux-{x}", .{uuid});
+            config.@"zmx-session" = session;
+            config.@"zmx-create" = true;
+        }
+
         // Initialize our surface right away. We're given a view that is
         // ready to use.
         try self.core_surface.init(
@@ -969,13 +1004,19 @@ pub const Surface = struct {
             break :wd self.app.core_app.alloc.dupeZ(u8, cwd) catch null;
         };
 
+        // Inherit zmx mode: if this surface uses zmx, new surfaces should too.
+        // Each new surface gets its own fresh zmx session (name auto-generated
+        // in Surface.init when zmx_mode=true and zmx_session=null).
+        const zmx_mode: bool = self.core_surface.io.backend == .zmx;
+
         return .{
             .font_size = font_size,
             .working_directory = working_directory,
             .context = context,
             .io_mode = self.io_mode,
             .io_write_cb = self.io_write_cb,
             .io_write_userdata = self.io_write_userdata,
+            .zmx_mode = zmx_mode,
         };
     }
 

src/apprt/surface.zig

@@ -51,6 +51,10 @@ pub const Message = union(enum) {
     /// command are given in the `ChildExited` struct.
     child_exited: ChildExited,
 
+    /// A persistent backend disconnected unexpectedly. This is always treated
+    /// as an abnormal failure regardless of runtime.
+    child_disconnected: ChildExited,
+
     /// Show a desktop notification.
     desktop_notification: struct {
         /// Desktop notification title.

src/config/Config.zig

@@ -1534,6 +1534,16 @@ class: ?[:0]const u8 = null,
 ///   * `inherit` - The working directory of the launching process.
 @"working-directory": ?[]const u8 = null,
 
+/// Connect to a zmx daemon session instead of spawning a new shell process.
+/// When set, the surface connects to the named zmx session over a Unix
+/// domain socket. The zmx daemon owns the PTY and persists independently
+/// of the surface, enabling session persistence across restarts.
+@"zmx-session": ?[]const u8 = null,
+
+/// Whether to create the zmx session if it doesn't already exist.
+/// Only applies when `zmx-session` is set. Default: true.
+@"zmx-create": bool = true,
+
 /// Key bindings. The format is `trigger=action`. Duplicate triggers will
 /// overwrite previously set values. The list of actions is available in
 /// the documentation or using the `ghostty +list-actions` command.
@@ -10597,6 +10607,40 @@ test "compatibility: gtk-single-instance desktop" {
     }
 }
 
+test "parse zmx config defaults and override" {
+    const testing = std.testing;
+    const alloc = testing.allocator;
+
+    {
+        var cfg = try Config.default(alloc);
+        defer cfg.deinit();
+
+        var it: TestIterator = .{ .data = &.{
+            "--zmx-session=session-1",
+        } };
+        try cfg.loadIter(alloc, &it);
+        try cfg.finalize();
+
+        try testing.expectEqualStrings("session-1", cfg.@"zmx-session".?);
+        try testing.expect(cfg.@"zmx-create");
+    }
+
+    {
+        var cfg = try Config.default(alloc);
+        defer cfg.deinit();
+
+        var it: TestIterator = .{ .data = &.{
+            "--zmx-session=session-1",
+            "--zmx-create=false",
+        } };
+        try cfg.loadIter(alloc, &it);
+        try cfg.finalize();
+
+        try testing.expectEqualStrings("session-1", cfg.@"zmx-session".?);
+        try testing.expect(!cfg.@"zmx-create");
+    }
+}
+
 test "compatibility: removed cursor-invert-fg-bg" {
     const testing = std.testing;
     const alloc = testing.allocator;

src/termio.zig

@@ -27,6 +27,7 @@ pub const Exec = @import("termio/Exec.zig");
 pub const Manual = manual.Manual;
 pub const ManualConfig = manual.Config;
 pub const ManualThreadData = manual.ThreadData;
+pub const Zmx = @import("termio/Zmx.zig");
 pub const Options = @import("termio/Options.zig");
 pub const Termio = @import("termio/Termio.zig");
 pub const Thread = @import("termio/Thread.zig");