com.blockether.vis.internal.foundation.pty-bridge — com.blockether/vis 0.1.1

Passthrough bridge on top of the FFM pseudo-terminal (internal.foundation.pty).

The problem it solves: a shell_bg child runs INSIDE the vis process (the FFM PTY master fd + reader thread live in vis's heap). That's great for the agent (shell_send / shell_logs) but a HUMAN can't jump into the live terminal to finish a step the agent can't — click through a browser OAuth, answer a prompt only a person can. tmux gets that for free because its server is a separate daemon you can tmux attach to; the FFM child is not.

This namespace restores that capability WITHOUT tmux: each background PTY optionally exposes a per-shell UNIX-DOMAIN SOCKET. vis is the server (it holds the master fd); vis ext shell attach <id> is a thin client the human runs in their OWN Terminal.app. On connect the server (a) tees live master output to the socket and (b) forwards the socket's bytes to the master (stdin) — a genuine bidirectional passthrough. Multiple humans can attach at once; detaching just drops the socket and leaves the child running (exactly like tmux detach).

Everything here is stdlib: java.nio.channels AF_UNIX sockets (JDK 16+, already in vis's native-image reachability metadata) on the server side, and stty for raw mode on the client side (the human's interactive shell always has it). No JNA, no new dep, native-image clean.

attach! clj

(attach! opts)

Human-side passthrough: connect to a background shell's AF_UNIX socket, put the local terminal into raw mode, and shuffle stdin<->socket until Ctrl-] (detach) or EOF. Restores the terminal on exit. opts is {:id <shell-id>} or {:socket <path>}. Returns an exit code (0 ok, 2 = no such socket).

bridge-dir clj

(bridge-dir)

Directory the per-shell attach sockets live in: $VIS_BRIDGE_DIR or ~/.vis/bridge. Created on demand by serve!.

find-socket clj

(find-socket {:keys [socket id]})

Resolve a socket Path for the attach client. socket (explicit path) wins; otherwise scan bridge-dir for the NEWEST *__<id>.sock. Returns a Path or nil when nothing matches.

serve! clj

(serve! {:keys [pty path replay-fn]})

Start an AF_UNIX passthrough server for the PTY handle pty at path (a String or Path). Runs a daemon accept loop; per accepted client it:

• pushes (replay-fn) bytes (recent output, optional) so a late attacher sees context, then
• tees every live master chunk to the client (via pty's :add-listener), and
• forwards the client's bytes into the master (:send) on a reader thread. Detach = the client closes its socket; the child keeps running. Returns {:path <str> :stop (fn [])}; :stop closes the server + all clients and unlinks the socket file. Never blocks the caller.

socket-path clj

(socket-path session id)

Deterministic socket path for a (session, id) background shell: <bridge-dir>/<session>__<id>.sock. The __<id>.sock suffix lets the separate attach client find a shell by id alone (it scans the dir).

sweep-orphans! clj

(sweep-orphans!)

Remove stale attach sockets left by a crashed/killed prior vis: the JVM held the AF_UNIX server + PTY master fd, so a hard exit never ran serve!'s :stop and the *.sock files linger. For each socket in bridge-dir, try to CONNECT — a live server (this vis or another) accepts, so leave it; a dead one refuses, so unlink the orphan. Best-effort, never throws; safe to call once at startup.