oss/exe-scroll: attach-or-create terminal sessions with ghostty scrollback

Prompt: In the exe-dtach-ghostty branch there's a zdtach binary that's like
dtach but written in zig and uses ghostty for scrollback. I want you to make a
clean commit that adds it to the oss/ dir. call it exe-scroll. The default
should take one argument, a path to place the socket in. And either attach or
create depending on whether the file exists. We should securely create any
intervening dirs if applicable. If the file is deleted while we're alive we
should securely recreate it (borrowing an idea from abduco). No need for dtach
protocol compatibility; do whatever is natural and good and easy to evolve and
test. Follow-ups: Why periodic watchdog? Can we set up a file watcher? / Let's
do just inotify and whenever bytes come across. I don't want a timer. / The
race I'm worried about is another session using the same path and them
competing for the file. Suggestions? / Undo that. Let's make recreation tied
to a signal sent to the process like done by abduco. Get rid of inotify and so
on. / I don't want the pid files. Just be simple -- just let the server
understand SIGUSR1 to recreate as necessary. / Simplify and fix: mention zmx
alongside dtach/abduco; drop the -D dump, the -e/-E detach character, and the
-s scrollback flag (default to 10,000 lines); detach by sending SIGUSR2 to the
process instead; drop master/slave terminology; replace the Python test
harness with Zig's native test harness; and use mise to fetch the toolchain
consistently instead of a hand-rolled installer. / Doc/cleanup pass: drop the
"no wire-protocol compatibility" paragraph and the "intervening directories
are created securely" line and the dtach-compatibility sentence above the
framing (the code should read sensibly from first principles); confirm whether
Zig really doesn't expose the libc bindings we hand-roll and lean on std.c
where it does; collapse the two scrollback concepts (lines + bytes) into a
single byte budget and remove the scrollbackBytes() helper; and drop the
abduco reference from the socket-recreation comment. / Portability: stop
hardcoding the Linux ABI in the libc binding block -- source the termios
layout, signal numbers, ioctl encodings, errno values, and flags from
std.c/std.posix so they follow the target platform, letting the source build
natively on Linux, macOS, and the BSDs (verified the binding block compiles
for aarch64/x86_64-macos, both linux-musl arches, and freebsd; filled the one
std gap, Darwin's missing T.IOCSWINSZ). / Make `make` work out of the box: a
bare `make` now fetches Ghostty at the pinned revision into ./.ghostty and
symlinks it, instead of defaulting GHOSTTY_SRC to a hardcoded absolute path;
pass GHOSTTY_SRC=... to use an existing checkout. / Set a per-role process
title so `ps` distinguishes the backgrounded "exe-scroll: session <sock>" from
each "exe-scroll: attach <sock>" (rewrites the argv string region in place,
the portable Linux/macOS/BSD mechanism); dup progname and sockname out of argv
first so the rewrite doesn't corrupt them.

Co-authored-by: Shelley <shelley@exe.dev>

Author: philz

exe-scroll/.gitignore

@@ -0,0 +1,4 @@
+/zig-out
+/.zig-cache
+/ghostty-src
+/.ghostty

exe-scroll/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 exe.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

exe-scroll/Makefile

@@ -0,0 +1,57 @@
+# Developer Makefile for exe-scroll.
+#
+# exe-scroll imports Ghostty's `ghostty-vt` Zig module directly, so it needs a
+# Ghostty checkout to build against. A bare `make` fetches Ghostty at the pinned
+# revision into ./.ghostty automatically, so it works out of the box. To build
+# against a checkout you already have, point GHOSTTY_SRC at it:
+#
+#   make                                     # -> zig-out/bin/exe-scroll
+#   make test                                # build + run the e2e tests
+#   make GHOSTTY_SRC=/path/to/ghostty        # use an existing checkout instead
+
+ZIG ?= zig
+OPTIMIZE ?= ReleaseFast
+BIN := zig-out/bin/exe-scroll
+
+# Pinned Ghostty revision (kept in sync with build-static.sh).
+GHOSTTY_REV ?= 48d3e972d839999745368b156df396d9512fd17b
+GHOSTTY_REPO_URL ?= https://github.com/ghostty-org/ghostty.git
+# Where `make` clones Ghostty when GHOSTTY_SRC isn't supplied.
+GHOSTTY_CACHE := .ghostty
+# Use the caller's checkout if given, otherwise our managed clone.
+GHOSTTY_SRC ?=
+
+$(BIN): exe-scroll.zig build.zig build.zig.zon ghostty-src
+	$(ZIG) build -Doptimize=$(OPTIMIZE)
+
+.PHONY: build test clean
+build: $(BIN)
+
+# `zig build test` builds the binary and runs test_e2e.zig against it.
+test: ghostty-src
+	$(ZIG) build test
+
+# Create the ./ghostty-src symlink the build.zig.zon dependency resolves
+# through. If GHOSTTY_SRC is set, point at it; otherwise fetch a pinned clone.
+.PHONY: ghostty-src
+ghostty-src:
+ifeq ($(strip $(GHOSTTY_SRC)),)
+	@if [ ! -d "$(GHOSTTY_CACHE)/.git" ]; then \
+		echo "Cloning Ghostty into $(GHOSTTY_CACHE)..."; \
+		git clone --filter=tree:0 "$(GHOSTTY_REPO_URL)" "$(GHOSTTY_CACHE)"; \
+	fi
+	@git -C "$(GHOSTTY_CACHE)" cat-file -e "$(GHOSTTY_REV)^{commit}" 2>/dev/null \
+		|| git -C "$(GHOSTTY_CACHE)" fetch --filter=tree:0 origin "$(GHOSTTY_REV)"
+	@git -C "$(GHOSTTY_CACHE)" checkout --quiet --detach "$(GHOSTTY_REV)"
+	@ln -sfn "$(GHOSTTY_CACHE)" ghostty-src
+else
+	@ln -sfn "$(GHOSTTY_SRC)" ghostty-src
+endif
+
+clean:
+	rm -rf .zig-cache zig-out ghostty-src
+
+# `make distclean` also removes the managed Ghostty clone.
+.PHONY: distclean
+distclean: clean
+	rm -rf $(GHOSTTY_CACHE)

exe-scroll/README.md

@@ -0,0 +1,135 @@
+# exe-scroll
+
+`exe-scroll` is a small terminal session multiplexer in the spirit of
+[dtach](https://github.com/crigler/dtach),
+[abduco](https://github.com/martanne/abduco), and
+[zmx](https://github.com/qbit/zmx), written in Zig. It hosts a PTY-backed
+command behind a Unix socket so you can attach and detach without disturbing the
+program — and it uses Ghostty's `ghostty-vt` terminal emulator to keep
+scrollback, so reattaching repaints the screen (and optional history) exactly:
+colors, styles, cursor and all.
+
+## Usage
+
+The default invocation takes a single argument — a path for the session socket
+— and **attaches** to it if a live session is there, otherwise **creates** it:
+
+```sh
+# Create (no session yet): runs $SHELL behind /tmp/work/session.sock.
+exe-scroll /tmp/work/session.sock
+
+# ...later, from anywhere: attach to the same session.
+exe-scroll /tmp/work/session.sock
+
+# Create with an explicit command (everything after `--` is the command).
+exe-scroll /tmp/work/session.sock -- bash -l
+```
+
+**Detach** (leaving the session running) by sending the attach client
+`SIGUSR2`:
+
+```sh
+kill -USR2 <pid-of-exe-scroll>
+```
+
+The session keeps running; reattach later with the same command.
+
+### Telling the processes apart
+
+Each session involves a backgrounded *session server* (owns the pty and
+scrollback) and one *attach client* per attachment. They rewrite their command
+line so `ps` shows which is which:
+
+```
+$ ps -o pid,command
+  4258 exe-scroll: attach /tmp/work/session.sock
+  2976 exe-scroll: session /tmp/work/session.sock
+```
+
+So the `session` line is the one to send `SIGUSR1` (recreate socket), and an
+`attach` line is the one to send `SIGUSR2` (detach).
+
+### Options
+
+| flag | meaning |
+|------|---------|
+| `-R none\|screen\|scrollback` | what to replay on attach (default `scrollback`) |
+| `--version` | print version and exit |
+| `-h`, `--help` | help |
+
+Options may appear before or after the socket path.
+
+## Design notes
+
+- **Attach-or-create by default.** A single path argument is all you need; the
+  tool connects if a session is live, otherwise spawns one. Intervening
+  directories are created securely (mode `0700`).
+- **A session server and attach clients.** Creating a session forks a
+  backgrounded *session server* that owns the pty and the scrollback. Each
+  `exe-scroll <socket>` you run is an *attach client* that connects to it over
+  the socket and relays your terminal.
+- **Signal-driven socket recreation (an abduco idea).** There's no polling
+  timer and no file watcher. The session server understands `SIGUSR1`: on
+  receipt, if its socket file is missing (or has been replaced), it binds a
+  fresh one. So if a socket gets deleted out from under a live session,
+  `kill -USR1 <server-pid>` brings it back and you can reattach. On exit the
+  server only unlinks the socket if its on-disk inode still matches the one it
+  created.
+- **Ghostty for scrollback.** Every byte of program output is fed into an
+  in-process `ghostty-vt` terminal. On attach the server serializes that
+  emulator back to VT sequences (optionally including scrollback) so the client
+  repaints exactly. `ghostty-vt` is imported as a Zig module directly — no
+  C ABI / FFI. The session retains a fixed 1 MiB scrollback budget.
+- **Simple, evolvable framing.** The server/client protocol is a trivial
+  length-prefixed message format (`[type:u8][len:u32-le][payload]`), chosen to
+  be easy to read, test and extend. There is intentionally no wire-protocol
+  compatibility with dtach; unknown message types are ignored, so the protocol
+  can grow.
+
+## Building
+
+exe-scroll imports Ghostty's `ghostty-vt` Zig module, so it builds against a
+[Ghostty](https://github.com/ghostty-org/ghostty) checkout. You need Zig 0.15.2
+(macOS also needs the Xcode command-line tools for Ghostty's bundled C++).
+
+```sh
+# Just build. Fetches Ghostty at the pinned revision into ./.ghostty for you:
+make                                        # -> zig-out/bin/exe-scroll
+make test                                   # build + run the test suite
+
+# Already have a Ghostty checkout? Point at it to skip the fetch:
+make GHOSTTY_SRC=/path/to/ghostty
+
+# Reproducible static musl build for Linux (fetches the pinned toolchain via
+# mise, and a pinned ghostty revision):
+./build-static.sh amd64                     # or arm64
+```
+
+The Zig toolchain version is pinned in `mise.toml` (with per-platform checksums
+in `mise.lock`); `build-static.sh` uses [mise](https://mise.jdx.dev) to fetch it
+consistently.
+
+## Platforms
+
+The source is POSIX and uses Zig's standard library for all the platform ABI
+(termios, signals, ioctls, errno, ...), so it builds and runs natively on
+Linux, macOS, and the BSDs. `build-static.sh` is Linux-specific: it produces a
+fully static musl binary. (Cross-compiling the macOS binary *from* Linux is not
+set up here because Ghostty's bundled C++ SIMD sources need the macOS SDK; build
+on the target OS, or wire up an SDK, for a native macOS binary.)
+
+## Testing
+
+`test_e2e.zig` drives the real binary over PTYs — attach-or-create, secure
+directory creation, detach (SIGUSR2) / reattach survival, replay modes, color
+preservation, and the abduco-style socket recreation. Run it with Zig's test
+harness:
+
+```sh
+zig build test     # builds the binary and runs the e2e tests against it
+```
+
+## License
+
+MIT (see [LICENSE](LICENSE)). This is an independent implementation; it does not
+reuse dtach's (GPL) source.

exe-scroll/build-static.sh

@@ -0,0 +1,89 @@
+#!/bin/sh
+# Reproducible static build of exe-scroll: uses mise to fetch the pinned Zig
+# toolchain (versioned + checksummed in mise.toml / mise.lock; the tarball is
+# verified against the Zig Software Foundation's signing key), clones Ghostty at
+# a pinned revision, and `zig build`s exe-scroll.zig + ghostty-vt into one fully
+# static musl binary (no dynamic interpreter at all).
+#
+# Usage: build-static.sh <target_arch>   (arm64 or amd64)
+set -e
+
+ARCH="$1"
+if [ -z "$ARCH" ]; then
+    echo "Usage: $0 <target_arch>  (arm64 or amd64)" >&2
+    exit 1
+fi
+
+GHOSTTY_REV="${GHOSTTY_REV:-48d3e972d839999745368b156df396d9512fd17b}"
+GHOSTTY_REPO_URL="${GHOSTTY_REPO_URL:-https://github.com/ghostty-org/ghostty.git}"
+
+# Directory containing build.zig (this script's directory by default).
+SRC_DIR="${SRC_DIR:-$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)}"
+
+case "$ARCH" in
+amd64 | x86_64)
+    ZIG_TARGET="x86_64-linux-musl"
+    EXPECT_UNAME="x86_64"
+    ;;
+arm64 | aarch64)
+    ZIG_TARGET="aarch64-linux-musl"
+    EXPECT_UNAME="aarch64"
+    ;;
+*)
+    echo "build-static.sh: unsupported target arch '$ARCH'" >&2
+    exit 1
+    ;;
+esac
+
+if [ "$(uname -m)" != "$EXPECT_UNAME" ]; then
+    echo "build-static.sh: target $ARCH expects uname -m=$EXPECT_UNAME but got" \
+        "$(uname -m); run under the target platform (buildx/qemu)." >&2
+    exit 1
+fi
+
+echo "Building exe-scroll for $ARCH (zig target $ZIG_TARGET)..."
+
+# --- Toolchain (zig) via mise -------------------------------------------
+# mise.toml pins the Zig version; mise.lock pins per-platform checksums, so the
+# toolchain itself is reproducible. We install mise on demand if it isn't
+# already present, then let it fetch the exact toolchain. `mise exec` runs the
+# build with that zig on PATH.
+#
+# Note: the on-demand bootstrap below pulls the latest mise (not version-pinned).
+# For a fully pinned chain, preinstall a known mise version yourself.
+if ! command -v mise >/dev/null 2>&1; then
+    echo "Installing mise..."
+    curl -fsSL https://mise.run | sh
+    export PATH="$HOME/.local/bin:$PATH"
+fi
+mise trust "$SRC_DIR/mise.toml"
+mise install --cd "$SRC_DIR"
+
+# --- Fetch ghostty at the pinned commit ---------------------------------
+GHOSTTY_SRC="${GHOSTTY_SRC:-/src/ghostty}"
+if [ ! -d "$GHOSTTY_SRC/.git" ]; then
+    echo "Cloning ghostty..."
+    git clone --filter=tree:0 "$GHOSTTY_REPO_URL" "$GHOSTTY_SRC"
+fi
+if ! git -C "$GHOSTTY_SRC" cat-file -e "${GHOSTTY_REV}^{commit}" 2>/dev/null; then
+    git -C "$GHOSTTY_SRC" fetch --filter=tree:0 origin "$GHOSTTY_REV"
+fi
+git -C "$GHOSTTY_SRC" checkout --detach "$GHOSTTY_REV"
+
+ln -sfn "$GHOSTTY_SRC" "$SRC_DIR/ghostty-src"
+
+# --- Build --------------------------------------------------------------
+(
+    cd "$SRC_DIR"
+    rm -rf .zig-cache zig-out
+    mise exec -- zig build -Dtarget="$ZIG_TARGET" -Doptimize=ReleaseFast
+)
+
+OUT="$SRC_DIR/zig-out/bin/exe-scroll"
+if [ ! -f "$OUT" ]; then
+    echo "build-static.sh: exe-scroll binary not produced" >&2
+    exit 1
+fi
+strip --strip-all --remove-section=.comment --remove-section=.note "$OUT" 2>/dev/null || true
+
+echo "exe-scroll (static musl) built successfully for $ARCH: $OUT"

exe-scroll/build.zig

@@ -0,0 +1,44 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const ghostty = b.dependency("ghostty", .{
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const exe = b.addExecutable(.{
+        .name = "exe-scroll",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("exe-scroll.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        }),
+    });
+    exe.root_module.addImport("ghostty-vt", ghostty.module("ghostty-vt"));
+    b.installArtifact(exe);
+
+    // End-to-end tests (`zig build test`). They drive the real binary over a
+    // pty, so we hand them its path via build options. The test step depends
+    // on the executable, so `zig build test` (re)builds it first.
+    const exe_opts = b.addOptions();
+    exe_opts.addOptionPath("exe_path", exe.getEmittedBin());
+
+    const tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("test_e2e.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        }),
+    });
+    tests.root_module.addImport("build_options", exe_opts.createModule());
+
+    const run_tests = b.addRunArtifact(tests);
+    run_tests.has_side_effects = true; // always re-run, even if inputs unchanged
+    const test_step = b.step("test", "Run end-to-end tests against the built binary");
+    test_step.dependOn(&run_tests.step);
+}

exe-scroll/build.zig.zon

@@ -0,0 +1,15 @@
+.{
+    .name = .exe_scroll,
+    .version = "0.1.0",
+    .fingerprint = 0x8e7c6e2e100742c9,
+    .minimum_zig_version = "0.15.2",
+    .dependencies = .{
+        .ghostty = .{ .path = "ghostty-src" },
+    },
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "exe-scroll.zig",
+        "test_e2e.zig",
+    },
+}