hqsh 0.1.0: the daemon, the client and resume, for real

[ralyodio]

Turns the 0.0.1 stub into a working hqsh: hqsh dev2 gives a persistent shell that survives disconnects and passes the raw byte stream (Kitty / iTerm2 image escapes included).

What's in it

• Daemon (hqsh server daemon): $SHELL -l in a PTY, 4 MiB resume ring, one attached client (a newer one takes over), HELLO → WELCOME + replay with the gap flag (and a resize nudge so the screen redraws), INPUT / RESIZE / ACK / PING, EXIT with the shell's status. A lock file allows one daemon per session, and the socket is recreated if its dir is removed.
• Attach (hqsh server attach): bridges ssh stdio to the socket. If no daemon is running it starts one (setsid, /dev/null stdio) and waits up to 3 s for the socket.
• hqsh server list [--json]: prints [{"name":"main","attached":true}] and removes stale sockets. This uses a new local-only STATUS frame.
• Protocol: HELLO now carries the client's TERM after a 0 byte. HELLOs from 0.0.x still decode. The docs are updated to match.
• Client: raw mode starts after the first WELCOME, so ssh can still prompt before it. Ctrl-^ . detaches and Ctrl-^ Ctrl-^ sends a literal Ctrl-^. Resizes come from SIGWINCH (polled on Windows). A ping and a 15 s watchdog trigger reconnects with backoff, and the reconnect status goes only in the window title. A gap clears the screen. The client exits with the shell's status. If the host has no hqsh on its PATH, the client tries ~/.local/bin/hqsh, and if that also fails it prints the curl -fsSL https://hqterm.sh/install | sh hint.
• Release workflow: on a v* tag it builds raw hqsh-<os>-<arch> binaries for linux/darwin amd64 and arm64, plus windows/amd64 .exe, and a SHA256SUMS file.

Tests

• Unit tests for the HELLO TERM field (encode/decode and backward compatibility), WELCOME/ACK/EXIT, list output (JSON and text), session-name validation, escape keys, and the missing-remote path (fake ssh that exits 127).
• Integration tests with a real /bin/sh and a real daemon process, over pipes and without ssh. They cover: echo hi, disconnect, output produced while detached, reconnect with lastSeq (replay is contiguous and has no duplicates), takeover, and exit 3 → EXIT 3 with the socket removed. The real client is also tested reconnecting after its transport dies.
• A manual end-to-end run on dev2 over ssh localhost, inside a real PTY:
  • command output came through;
  • Kitty APC and iTerm2 OSC 1337 bytes arrived unmodified;
  • after SIGKILLing ssh in the middle of a command, the client reconnected in 1.5 s and printed the missed output exactly once;
  • Ctrl-^ . detached, and list showed the session detached;
  • re-attaching got the same shell;
  • exit 5 made the client exit 5, and list then showed [].

🤖 Generated with Claude Code

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	github.com/​creack/​pty@​v1.1.24
	golang.org/​x/​term@​v0.46.0

View full report