From 5baf231e076ed96bb2aaba245eb53ad0e4501d76 Mon Sep 17 00:00:00 2001 From: Franz Bettag Date: Tue, 28 Apr 2026 19:11:11 +0200 Subject: Add named persistent sessions (#57) * feat: add named persistent sessions * feat: add session management commands * fix: tighten named session stop and override precedence * fix: handle session help and stop test race * test: isolate default session env test --------- Co-authored-by: Ogulcan Celik --- SOCKET_API.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) (limited to 'SOCKET_API.md') diff --git a/SOCKET_API.md b/SOCKET_API.md index b9da2efb..ea834e14 100644 --- a/SOCKET_API.md +++ b/SOCKET_API.md @@ -23,13 +23,21 @@ important difference: `pane.run` and `wait agent-status` are **cli conveniences* - request/response: send one json request per line, read one json response per line - subscriptions: send `events.subscribe`, receive an ack, then keep the same connection open and continue reading pushed events +named sessions are runtime/socket namespaces, not replacements for herdr workspaces. each named session has its own server sockets and persistent runtime state while config remains global. + socket path resolution order: -1. `HERDR_SOCKET_PATH` -2. `$XDG_RUNTIME_DIR/herdr.sock` -3. `$XDG_CONFIG_HOME/herdr/herdr.sock` -4. `$HOME/.config/herdr/herdr.sock` -5. `/tmp/herdr.sock` +1. explicit `herdr --session `: + `$XDG_CONFIG_HOME/herdr/sessions//herdr.sock` or `$HOME/.config/herdr/sessions//herdr.sock` +2. `HERDR_SOCKET_PATH` +3. `HERDR_SESSION=`: + `$XDG_CONFIG_HOME/herdr/sessions//herdr.sock` or `$HOME/.config/herdr/sessions//herdr.sock` +4. default session path: + `$XDG_CONFIG_HOME/herdr/herdr.sock` or `$HOME/.config/herdr/herdr.sock` + +this means `HERDR_SOCKET_PATH` remains an exact low-level socket override, but an explicit cli `--session ` still wins when a command runs inside a pane that inherited `HERDR_SOCKET_PATH`. + +session names may contain ASCII letters, numbers, `.`, `_`, and `-`. `default` is reserved for the default session. use `herdr session list`, `herdr session stop `, and `herdr session delete ` to inspect and manage session namespaces. `session delete` refuses running sessions and does not delete the default session. ## request and response envelopes -- cgit v1.2.3