feat(v0.3): H1 — tmux keepalive (sessions survive a server restart)

- src/session/tmux.ts: sync tmux CLI wrappers (available/has/kill), best-effort
- config: useTmux from USE_TMUX env (1/0/auto→detect tmux on PATH)
- session: when useTmux, spawn 'tmux new-session -A -s web_<id> <shell>' (the
  node-pty proc is a tmux CLIENT); createSession takes an optional id for
  re-attach; Session.tmuxName; kill() runs tmux kill-session
- manager: handleAttach re-attaches to a surviving 'web_<id>' tmux session after
  a restart (Case 3.5); shutdown kills only the client pty for tmux sessions so
  the shell keeps running
- tests: USE_TMUX:0 in shared integration cfg (no tmux leakage); unit CFGs
  useTmux:false; integration 'H1' (real tmux): set var → restart server →
  re-attach → var survived. 208 tests green.

src/config.ts

@@ -8,6 +8,15 @@
 
 import os from 'node:os'
 import type { Config, EnvLike } from './types.js'
+import { tmuxAvailable } from './session/tmux.js'
+
+/** USE_TMUX: '1'/'true'/'on' → on, '0'/'false'/'off' → off, else auto-detect tmux. */
+function resolveUseTmux(raw: string | undefined): boolean {
+  const v = raw?.trim().toLowerCase()
+  if (v === '1' || v === 'true' || v === 'on') return true
+  if (v === '0' || v === 'false' || v === 'off') return false
+  return tmuxAvailable() // unset / 'auto'
+}
 
 // ── constants ─────────────────────────────────────────────────────────────────
 
@@ -141,6 +150,8 @@ export function loadConfig(env: EnvLike): Config {
 
   const wsPath = env['WS_PATH'] ?? DEFAULT_WS_PATH
 
+  const useTmux = resolveUseTmux(env['USE_TMUX'])
+
   const allowedOrigins = deriveAllowedOrigins(port, env['ALLOWED_ORIGINS'])
 
   return Object.freeze({
@@ -152,6 +163,7 @@ export function loadConfig(env: EnvLike): Config {
     scrollbackBytes,
     maxPayloadBytes,
     wsPath,
+    useTmux,
     allowedOrigins,
   } satisfies Config)
 }

src/session/manager.ts

@@ -33,6 +33,7 @@ import type {
 import { WS_OPEN } from '../types.js';
 import { serialize } from '../protocol.js';
 import { createSession, attachWs, kill } from './session.js';
+import { hasSession, tmuxName } from './tmux.js';
 
 /**
  * Send a serialised ServerMessage to `ws` only when it is OPEN (M5).
@@ -113,6 +114,17 @@ export function createSessionManager(cfg: Config): SessionManager {
       return existing;
     }
 
+    // ── Case 3.5 (H1): not in our table, but a tmux session survived a restart ─
+    // Re-attach with the SAME id so `tmux new-session -A -s web_<id>` reconnects
+    // to the still-running shell instead of spawning a fresh one.
+    if (cfg.useTmux && hasSession(tmuxName(sessionId))) {
+      const revived = createSession(cfg, dims, now, onSessionExit, sessionId);
+      const kickedRevived = attachWs(revived, ws);
+      if (kickedRevived !== null) kickedRevived.close();
+      sessions = new Map(sessions).set(revived.meta.id, revived);
+      return revived;
+    }
+
     // ── Case 4: session not found → create a new one ─────────────────────────
     // M4: createSession may throw. Do NOT catch here.
     const session = createSession(cfg, dims, now, onSessionExit);
@@ -180,10 +192,18 @@ export function createSessionManager(cfg: Config): SessionManager {
     return count;
   }
 
-  /** Kill every live session and clear the table (called on SIGINT/SIGTERM). */
+  /**
+   * Called on SIGINT/SIGTERM/close. For non-tmux sessions, kill the PTY. For
+   * tmux sessions (H1), kill only the client pty — the tmux server keeps the
+   * shell alive so it survives the restart and can be re-attached.
+   */
   function shutdown(): void {
     for (const session of sessions.values()) {
-      kill(session);
+      if (session.tmuxName !== null) {
+        session.pty.kill(); // detach client; tmux keeps the shell
+      } else {
+        kill(session);
+      }
     }
     sessions = new Map();
   }

src/session/session.ts

@@ -37,6 +37,7 @@ import type {
 import { WS_OPEN } from '../types.js';
 import { serialize } from '../protocol.js';
 import { createRingBuffer } from './ring-buffer.js';
+import { tmuxName, killSession } from './tmux.js';
 
 /** Send a server message to `ws` only if it is OPEN (M5). Never throws on a
  *  closed socket; forwarding to a dead ws is simply a no-op. */
@@ -57,14 +58,21 @@ export function createSession(
   dims: Dims,
   now: number,
   onExit: (session: Session) => void,
+  // H1: pass an existing id to RE-ATTACH to a surviving tmux session (e.g. after
+  // a server restart). Default = a fresh id for a brand-new session.
+  id: string = randomUUID(),
 ): Session {
-  // Generate the id first so it can be injected into the shell env: Claude Code
-  // hooks running inside this shell read $WEBTERM_SESSION to tell us which tab
-  // an event belongs to, and POST to $WEBTERM_HOOK_URL (H2).
-  const id = randomUUID();
+  // The id is injected into the shell env so Claude Code hooks know which tab an
+  // event belongs to ($WEBTERM_SESSION) and where to POST ($WEBTERM_HOOK_URL, H2).
+  const tName = cfg.useTmux ? tmuxName(id) : null;
 
-  // M4: let a spawn failure (e.g. missing shell) propagate synchronously.
-  const pty: IPty = spawn(cfg.shellPath, [], {
+  // H1: under tmux, the node-pty process is a tmux CLIENT; `new-session -A`
+  // attaches to web_<id> if it exists (restart survival) or creates it.
+  const file = tName !== null ? 'tmux' : cfg.shellPath;
+  const args = tName !== null ? ['new-session', '-A', '-s', tName, cfg.shellPath] : [];
+
+  // M4: let a spawn failure (e.g. missing shell / tmux) propagate synchronously.
+  const pty: IPty = spawn(file, args, {
     name: 'xterm-256color',
     cols: dims.cols,
     rows: dims.rows,
@@ -91,6 +99,7 @@ export function createSession(
     exitedAt: null,
     exitCode: null,
     claudeStatus: 'unknown',
+    tmuxName: tName,
     pty,
   };
 
@@ -149,7 +158,12 @@ export function resize(session: Session, cols: number, rows: number): void {
   session.pty.resize(cols, rows);
 }
 
-/** Kill the underlying PTY (process exit / idle reclaim). */
+/**
+ * Kill the session (idle reclaim). Under tmux this ends the actual shell via
+ * `tmux kill-session` (H1); killing only the client pty would leave the tmux
+ * session running. Always also kills the client pty.
+ */
 export function kill(session: Session): void {
+  if (session.tmuxName !== null) killSession(session.tmuxName);
   session.pty.kill();
 }

src/session/tmux.ts

@@ -0,0 +1,46 @@
+/**
+ * src/session/tmux.ts (H1) — thin synchronous wrappers around the tmux CLI.
+ *
+ * Used only when cfg.useTmux is on. Running the shell inside a tmux session
+ * lets it survive a server/host restart: the node-pty process is just a tmux
+ * *client*; killing it detaches, and the tmux server keeps the shell alive.
+ *
+ * Every call is best-effort and never throws (tmux missing / session gone are
+ * treated as "false"/no-op).
+ */
+
+import { execFileSync } from 'node:child_process'
+
+/** Is the tmux binary available on PATH? */
+export function tmuxAvailable(): boolean {
+  try {
+    execFileSync('tmux', ['-V'], { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** tmux session name for a web-terminal session id (UUIDs are tmux-safe). */
+export function tmuxName(sessionId: string): string {
+  return `web_${sessionId}`
+}
+
+/** Does a tmux session with this name already exist (e.g. after a restart)? */
+export function hasSession(name: string): boolean {
+  try {
+    execFileSync('tmux', ['has-session', '-t', name], { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Kill a tmux session (ends the shell). No-op if it's already gone. */
+export function killSession(name: string): void {
+  try {
+    execFileSync('tmux', ['kill-session', '-t', name], { stdio: 'ignore' })
+  } catch {
+    // already gone — fine
+  }
+}

src/types.ts

@@ -27,6 +27,7 @@ export interface Config {
   readonly scrollbackBytes: number; // ring buffer capacity, default 2MB
   readonly maxPayloadBytes: number; // max WS frame bytes, default 1MB (L5)
   readonly wsPath: string; // WS upgrade path, default '/term' (L3; invariant 8)
+  readonly useTmux: boolean; // H1: spawn the shell inside tmux so it survives a server restart
   readonly allowedOrigins: readonly string[]; // derived from NIC IPs, NOT bindHost (M1)
 }
 
@@ -149,6 +150,8 @@ export interface Session {
   exitCode: number | null;
   /** Claude Code activity from hooks (H2); updated by manager.handleHookEvent. */
   claudeStatus: ClaudeStatus;
+  /** tmux session name (H1) when running under tmux, else null. */
+  readonly tmuxName: string | null;
   readonly pty: IPty;
 }