feat: improve detached session retention and session UX

Author: masterkain

README.md

@@ -119,9 +119,10 @@ Session controls:
 - click the `Session` badge in the status bar to open the session menu.
 - `New session`: start a fresh session in the current tab.
 - `Resume last`: reattach the last session id seen in this browser.
-- session list merges live server sessions (`/api/sessions`) and local history entries.
+- session menu separates `Live sessions` (running on server) from `Recent session ids` (browser memory only).
 - sessions already controlled in another tab/operator are shown as `Watch` (read-only attach).
 - resumable sessions are shown as `Resume` (full control attach).
+- recent ids that are not running are shown as unavailable.
 - tabs do not implicitly steal active sessions from each other.
 - terminal font starts at minimum (`11px`) by default and can be changed from controls/shortcuts.
 
@@ -131,14 +132,40 @@ Session controls:
 | --- | --- | --- |
 | `WOOTTY_HOST` | `0.0.0.0` | Bind address |
 | `WOOTTY_PORT` | `8080` | HTTP/WebSocket port |
-| `WOOTTY_RECONNECT_GRACE_MS` | `30000` | Session retention window while reconnecting |
+| `WOOTTY_RECONNECT_GRACE_MS` | `0` | Legacy detached-session cleanup timeout in ms (used only when `WOOTTY_DETACHED_TTL_MS=0`) |
+| `WOOTTY_DETACHED_TTL_MS` | `86400000` | Hard TTL for running detached sessions (24h). `0` disables this TTL |
 | `WOOTTY_HISTORY_BYTES` | `5242880` | Buffered output bytes for replay |
 | `WOOTTY_COMMAND` | `$SHELL` or `bash` | Executed command |
 | `WOOTTY_COMMAND_ARGS` | _empty_ | Space-separated command args |
 | `WOOTTY_CWD` | current directory | Process working directory |
 | `WOOTTY_STATIC_DIR` | auto-detected | Directory with built web assets |
 | `WOOTTY_FAKE_PTY` | `0` | Set to `1` for deterministic fake PTY mode |
 
+CLI equivalents are available for key timing controls: `--reconnect-grace-ms` and `--detached-ttl-ms`.
+
+### Session Retention Model
+
+- Session metadata and PTY state are in-memory only.
+- If a terminal process exits, the session is removed immediately.
+- If a terminal process is still running but no client is attached, the session is retained for `WOOTTY_DETACHED_TTL_MS`.
+- If `WOOTTY_DETACHED_TTL_MS=0`, cleanup falls back to `WOOTTY_RECONNECT_GRACE_MS` behavior.
+- Server restart clears all sessions because there is no persistent session store.
+
+Recommended for long-running jobs with occasional reconnects:
+
+```bash
+WOOTTY_RECONNECT_GRACE_MS=0
+WOOTTY_DETACHED_TTL_MS=259200000  # 72h
+```
+
+Example in Compose:
+
+```yaml
+environment:
+  WOOTTY_RECONNECT_GRACE_MS: "0"
+  WOOTTY_DETACHED_TTL_MS: "259200000"
+```
+
 ## Architecture
 
 ```mermaid

apps/server/internal/config/config.go

@@ -12,13 +12,15 @@ import (
 const (
 	DefaultPort             = 8080
 	DefaultHistoryBytes     = 5 * 1024 * 1024
-	DefaultReconnectGraceMS = 30_000
+	DefaultReconnectGraceMS = 0
+	DefaultDetachedTTLMS    = 86_400_000
 )
 
 type RuntimeConfig struct {
 	Host             string
 	Port             int
 	ReconnectGraceMS int
+	DetachedTTLMS    int
 	HistoryBytes     int
 	FakePTY          bool
 	Command          string
@@ -36,7 +38,8 @@ func ParseRunConfig(argv []string, env map[string]string, cwd string) (RuntimeCo
 
 	host := getOrDefault(env["WOOTTY_HOST"], "0.0.0.0")
 	port := parsePositiveInt(env["WOOTTY_PORT"], DefaultPort)
-	reconnectGraceMS := parsePositiveInt(env["WOOTTY_RECONNECT_GRACE_MS"], DefaultReconnectGraceMS)
+	reconnectGraceMS := parseNonNegativeInt(env["WOOTTY_RECONNECT_GRACE_MS"], DefaultReconnectGraceMS)
+	detachedTTLMS := parseNonNegativeInt(env["WOOTTY_DETACHED_TTL_MS"], DefaultDetachedTTLMS)
 	historyBytes := parsePositiveInt(env["WOOTTY_HISTORY_BYTES"], DefaultHistoryBytes)
 
 	commandParts := make([]string, 0)
@@ -62,7 +65,13 @@ func ParseRunConfig(argv []string, env map[string]string, cwd string) (RuntimeCo
 		case "--reconnect-grace-ms":
 			i++
 			if i < len(args) {
-				reconnectGraceMS = parsePositiveInt(args[i], reconnectGraceMS)
+				reconnectGraceMS = parseNonNegativeInt(args[i], reconnectGraceMS)
+			}
+			continue
+		case "--detached-ttl-ms":
+			i++
+			if i < len(args) {
+				detachedTTLMS = parseNonNegativeInt(args[i], detachedTTLMS)
 			}
 			continue
 		case "--history-bytes":
@@ -111,6 +120,7 @@ func ParseRunConfig(argv []string, env map[string]string, cwd string) (RuntimeCo
 		Host:             host,
 		Port:             port,
 		ReconnectGraceMS: reconnectGraceMS,
+		DetachedTTLMS:    detachedTTLMS,
 		HistoryBytes:     historyBytes,
 		FakePTY:          env["WOOTTY_FAKE_PTY"] == "1",
 		Command:          commandParts[0],
@@ -143,6 +153,19 @@ func parsePositiveInt(value string, fallback int) int {
 	return parsed
 }
 
+func parseNonNegativeInt(value string, fallback int) int {
+	if strings.TrimSpace(value) == "" {
+		return fallback
+	}
+
+	parsed, err := strconv.Atoi(value)
+	if err != nil || parsed < 0 {
+		return fallback
+	}
+
+	return parsed
+}
+
 func splitArgs(value string) []string {
 	parts := strings.Fields(value)
 	if len(parts) == 0 {

apps/server/internal/config/config_test.go

@@ -16,6 +16,9 @@ func TestParseRunConfigDefaults(t *testing.T) {
 	if cfg.Port != DefaultPort {
 		t.Fatalf("expected default port %d, got %d", DefaultPort, cfg.Port)
 	}
+	if cfg.DetachedTTLMS != DefaultDetachedTTLMS {
+		t.Fatalf("expected default detached ttl %d, got %d", DefaultDetachedTTLMS, cfg.DetachedTTLMS)
+	}
 	if cfg.Command != "bash" {
 		t.Fatalf("expected default shell command bash, got %q", cfg.Command)
 	}
@@ -27,7 +30,7 @@ func TestParseRunConfigWithFlagsAndCommand(t *testing.T) {
 		"SHELL":       "/bin/zsh",
 	}
 	cfg, err := ParseRunConfig(
-		[]string{"run", "-p", "4444", "--host", "127.0.0.1", "sh", "-lc", "echo ok"},
+		[]string{"run", "-p", "4444", "--host", "127.0.0.1", "--detached-ttl-ms", "0", "sh", "-lc", "echo ok"},
 		env,
 		"/tmp/wootty/apps/server",
 	)
@@ -44,6 +47,9 @@ func TestParseRunConfigWithFlagsAndCommand(t *testing.T) {
 	if cfg.Command != "sh" {
 		t.Fatalf("expected command sh, got %q", cfg.Command)
 	}
+	if cfg.DetachedTTLMS != 0 {
+		t.Fatalf("expected detached ttl override 0, got %d", cfg.DetachedTTLMS)
+	}
 	if len(cfg.Args) != 2 {
 		t.Fatalf("expected 2 args, got %d", len(cfg.Args))
 	}
@@ -60,9 +66,10 @@ func TestParseRunConfigUsesEnvCommandArgsAndFakePTY(t *testing.T) {
 	cfg, err := ParseRunConfig(
 		[]string{"run"},
 		map[string]string{
-			"WOOTTY_COMMAND":      "/bin/bash",
-			"WOOTTY_COMMAND_ARGS": "-lc echo-ok",
-			"WOOTTY_FAKE_PTY":     "1",
+			"WOOTTY_COMMAND":         "/bin/bash",
+			"WOOTTY_COMMAND_ARGS":    "-lc echo-ok",
+			"WOOTTY_FAKE_PTY":        "1",
+			"WOOTTY_DETACHED_TTL_MS": "0",
 		},
 		"/tmp/wootty/apps/server",
 	)
@@ -82,4 +89,7 @@ func TestParseRunConfigUsesEnvCommandArgsAndFakePTY(t *testing.T) {
 	if !cfg.FakePTY {
 		t.Fatal("expected fake PTY to be enabled from env")
 	}
+	if cfg.DetachedTTLMS != 0 {
+		t.Fatalf("expected detached ttl from env 0, got %d", cfg.DetachedTTLMS)
+	}
 }

apps/server/internal/server/server.go

@@ -2,6 +2,7 @@ package server
 
 import (
 	"encoding/json"
+	"errors"
 	"io/fs"
 	"log/slog"
 	"mime"
@@ -33,6 +34,7 @@ func New(cfg config.RuntimeConfig) *Server {
 
 	manager := session.NewManager(session.ManagerOptions{
 		ReconnectGrace: time.Duration(cfg.ReconnectGraceMS) * time.Millisecond,
+		DetachedTTL:    time.Duration(cfg.DetachedTTLMS) * time.Millisecond,
 		HistoryBytes:   cfg.HistoryBytes,
 		FakePTY:        cfg.FakePTY,
 		ProcessOptions: session.ProcessOptions{
@@ -138,8 +140,16 @@ func (s *Server) handleTerminal(w http.ResponseWriter, r *http.Request) {
 				message.Watch,
 			)
 			if attachErr != nil {
+				errorCode := "attach_failed"
+				switch {
+				case errors.Is(attachErr, session.ErrSessionNotFound):
+					errorCode = "session_not_found"
+				case errors.Is(attachErr, session.ErrSessionAlreadyAttached):
+					errorCode = "session_busy"
+				}
 				s.log.Error("failed to attach terminal session", "err", attachErr)
 				send(map[string]string{
+					"code":    errorCode,
 					"type":    "error",
 					"message": "Terminal attach failed: " + attachErr.Error(),
 				})

apps/server/internal/server/server_test.go

@@ -262,6 +262,44 @@ func TestWatchModeIsReadOnly(t *testing.T) {
 	}
 }
 
+func TestAttachMissingSessionReturnsSessionNotFoundCode(t *testing.T) {
+	cfg := testRuntimeConfig(t, true, "sh", filepath.Join(t.TempDir(), "missing-static"))
+	server := New(cfg)
+	defer server.Shutdown()
+
+	httpServer := httptest.NewServer(server.http.Handler)
+	defer httpServer.Close()
+
+	wsConnA := dialTerminalWebsocket(t, httpServer.URL)
+	if err := wsConnA.WriteJSON(map[string]any{"type": "attach", "cols": 80, "rows": 24}); err != nil {
+		t.Fatalf("failed writing initial attach payload: %v", err)
+	}
+	readyMessage := waitForWSMessageType(t, wsConnA, "ready", 2*time.Second)
+	sessionID := stringField(readyMessage, "sessionId")
+	if sessionID == "" {
+		t.Fatalf("expected session id in ready payload, got %#v", readyMessage)
+	}
+	wsConnA.Close()
+
+	time.Sleep(150 * time.Millisecond)
+
+	wsConnB := dialTerminalWebsocket(t, httpServer.URL)
+	defer wsConnB.Close()
+	if err := wsConnB.WriteJSON(map[string]any{
+		"type":      "attach",
+		"sessionId": sessionID,
+		"cols":      80,
+		"rows":      24,
+	}); err != nil {
+		t.Fatalf("failed writing stale attach payload: %v", err)
+	}
+
+	errorMessage := waitForWSMessageType(t, wsConnB, "error", 2*time.Second)
+	if stringField(errorMessage, "code") != "session_not_found" {
+		t.Fatalf("expected session_not_found code, got %#v", errorMessage)
+	}
+}
+
 func TestWebsocketAttachFailureSurfacesError(t *testing.T) {
 	cfg := testRuntimeConfig(t, false, "/definitely/missing-command", filepath.Join(t.TempDir(), "missing-static"))
 	server := New(cfg)
@@ -299,6 +337,7 @@ func testRuntimeConfig(t *testing.T, fakePTY bool, command string, staticDir str
 		Host:             "127.0.0.1",
 		Port:             0,
 		ReconnectGraceMS: 100,
+		DetachedTTLMS:    0,
 		HistoryBytes:     4096,
 		FakePTY:          fakePTY,
 		Command:          command,

apps/server/internal/session/manager.go

@@ -19,6 +19,7 @@ var (
 
 type ManagerOptions struct {
 	ReconnectGrace time.Duration
+	DetachedTTL    time.Duration
 	HistoryBytes   int
 	FakePTY        bool
 	ProcessOptions ProcessOptions
@@ -119,6 +120,9 @@ func (m *Manager) Attach(sessionID string, conn *websocket.Conn, cols, rows int,
 			m.mu.Unlock()
 			return AttachResult{}, ErrSessionNotFound
 		}
+
+		m.mu.Unlock()
+		return AttachResult{}, ErrSessionNotFound
 	}
 
 	id := uuid.NewString()
@@ -228,11 +232,26 @@ func (m *Manager) Detach(sessionID string, conn *websocket.Conn) {
 	}
 	delete(session.watchers, conn)
 
-	delay := m.options.ReconnectGrace
+	if session.reconnectTimer != nil {
+		session.reconnectTimer.Stop()
+		session.reconnectTimer = nil
+	}
+
 	if session.exitInfo != nil {
-		delay = time.Millisecond
+		m.scheduleCleanupLocked(sessionID, time.Millisecond)
+		m.mu.Unlock()
+		return
+	}
+
+	// Running detached sessions are retained for DetachedTTL.
+	// ReconnectGrace acts as a legacy fallback when DetachedTTL is disabled.
+	delay := m.options.DetachedTTL
+	if delay <= 0 {
+		delay = m.options.ReconnectGrace
+	}
+	if delay > 0 {
+		m.scheduleCleanupLocked(sessionID, delay)
 	}
-	m.scheduleCleanupLocked(sessionID, delay)
 	m.mu.Unlock()
 }